From b517364caaf9bf011ea50b077146e3c9993f97bf Mon Sep 17 00:00:00 2001 From: aashir-tech Date: Sun, 16 Aug 2026 15:12:18 +0530 Subject: [PATCH 1/2] fix: correct task list, code block and wide table rendering MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit `.task-list-item { display: flex }` promoted every inline child of a checklist item to a flex item, so bold runs and inline code each became their own column; `word-break: break-word` on inline code then let those items shrink to min-content — one character wide. Replaced with normal inline flow and a hanging checkbox (negative margin-inline-start), which also fixes nested checklists rendering as sibling columns, plain bullets losing their markers beside task items, ordered checklists losing their numbering (a flex item is not a list-item, so the counter never advanced), block children sitting beside the checkbox, and long URLs running off the page. Code blocks: - `pre { overflow-x: auto }` made every block a scroll container, which is monolithic under CSS fragmentation — so `break-inside` was ignored and a tall block could never split, it was pushed whole to the next page and then clipped. Removed, and lines now wrap (`pre-wrap`) with continuations hanging past the line-number gutter, so nothing is cut off at the right margin. - Splitting exposed a Paged.js defect that blanks the line straddling a page edge, so the export instead cuts long listings into page-sized atomic pieces (chunkCodeBlocks) that join seamlessly; Paged.js only ever places whole blocks. Tables: type and padding step down at 6+ and 8+ columns, and only long tokens and URLs may break, so headers stay whole rather than reading "Platfor / m". Also gives callout bodies `min-width: 0` and lets links break anywhere, so neither overflows the page box. Stops two leaks into exported files: the Copy button was printed into every PDF, and every checkbox carried `node="[object Object]"` into the preview DOM, the standalone HTML export and the PDF. Verified by rendering checklist, wide-table, deep-nesting and RTL Arabic fixtures through the real pipeline and Paged.js in headless Chrome: no element extends past the page content box and the code-line sequence matches the source exactly. --- src/markdown/MarkdownRenderer.tsx | 42 +++++++--- src/pdf/buildExportContent.ts | 2 + src/pdf/chunkCodeBlocks.ts | 112 +++++++++++++++++++++++++++ src/pdf/pageStyles.ts | 8 +- src/styles/document.css | 124 +++++++++++++++++++++++++++--- src/types/pagedjs.d.ts | 4 +- 6 files changed, 267 insertions(+), 25 deletions(-) create mode 100644 src/pdf/chunkCodeBlocks.ts diff --git a/src/markdown/MarkdownRenderer.tsx b/src/markdown/MarkdownRenderer.tsx index bb79673..befd150 100644 --- a/src/markdown/MarkdownRenderer.tsx +++ b/src/markdown/MarkdownRenderer.tsx @@ -1,4 +1,4 @@ -import { memo, useMemo, type ComponentPropsWithoutRef, type ReactNode } from 'react' +import { memo, useMemo, type ReactNode } from 'react' import ReactMarkdown, { defaultUrlTransform, type Components } from 'react-markdown' import { startsWithManualNumber } from '@/lib/headingNumbers' import remarkGfm from 'remark-gfm' @@ -131,18 +131,22 @@ function MarkdownRendererImpl({ content, resolvedTheme }: MarkdownRendererProps) a({ href, children }) { const isExternal = typeof href === 'string' && /^https?:\/\//.test(href) return ( - + {children as ReactNode} ) }, img({ src, alt }) { - return {alt + return ( + {alt + ) }, - input({ type, checked, onChange: _onChange, ...rest }: ComponentPropsWithoutRef<'input'>) { + input({ node: _node, type, checked, onChange: _onChange, ...rest }) { if (type === 'checkbox') { return } @@ -150,16 +154,32 @@ function MarkdownRendererImpl({ content, resolvedTheme }: MarkdownRendererProps) }, // Headings that already carry a manual number opt out of auto-numbering. h1({ node, children, ...props }) { - return

{children as ReactNode}

+ return ( +

+ {children as ReactNode} +

+ ) }, h2({ node, children, ...props }) { - return

{children as ReactNode}

+ return ( +

+ {children as ReactNode} +

+ ) }, h3({ node, children, ...props }) { - return

{children as ReactNode}

+ return ( +

+ {children as ReactNode} +

+ ) }, h4({ node, children, ...props }) { - return

{children as ReactNode}

+ return ( +

+ {children as ReactNode} +

+ ) }, } }, [resolvedTheme]) diff --git a/src/pdf/buildExportContent.ts b/src/pdf/buildExportContent.ts index 37aee68..876040f 100644 --- a/src/pdf/buildExportContent.ts +++ b/src/pdf/buildExportContent.ts @@ -1,4 +1,5 @@ import { buildCoverHtml, resolveDocDirection } from './pageStyles' +import { chunkCodeBlocks } from './chunkCodeBlocks' import { startsWithManualNumber } from '@/lib/headingNumbers' import { escapeHtml } from '@/lib/utils' import type { PdfConfig, TocEntry } from '@/types' @@ -103,6 +104,7 @@ export function buildExportContent( const clone = liveDoc.cloneNode(true) as HTMLElement namespaceIds(clone) + chunkCodeBlocks(clone, config) // Number headings as literal text and turn off the CSS counters (data-numbered) // so they don't double up — Paged.js can't reset baked-in text across pages. if (config.numberedHeadings) { diff --git a/src/pdf/chunkCodeBlocks.ts b/src/pdf/chunkCodeBlocks.ts new file mode 100644 index 0000000..7350291 --- /dev/null +++ b/src/pdf/chunkCodeBlocks.ts @@ -0,0 +1,112 @@ +import { resolvePageDimensions } from '@/lib/constants' +import type { PdfConfig } from '@/types' + +/** + * Paged.js cannot reliably fragment a code block: breaking inside `pre > code` + * blanks the line that straddles the page edge. So the export never asks it to. + * A long block is cut into consecutive atomic blocks here instead, and Paged.js + * only ever has to place whole ones — the case it handles correctly. + * + * The pieces are styled to butt together seamlessly (see the `data-code-chunk` + * rules in document.css), so a chunked block still reads as one listing. + */ + +/** Blocks shorter than this stay whole — they fit a page on their own. */ +const MIN_ROWS_TO_CHUNK = 20 +/** Target rows per piece. Sets the worst-case slack left at a page bottom. */ +const ROWS_PER_CHUNK = 10 + +/** Monospace advance as a fraction of the font size, matching the ASCII diagram + * sizing in pageStyles.ts. */ +const CHAR_ADVANCE = 0.6 +/** `pre` renders at 0.82em (document.css). */ +const CODE_SCALE = 0.82 +/** Line-number gutter plus the trailing padding, in code-font ems. */ +const GUTTER_EMS = 4.7 + +const PT_TO_MM = 25.4 / 72 + +/** How many characters of code fit on one row of the configured page. */ +function charsPerRow(config: PdfConfig): number { + const { width } = resolvePageDimensions(config) + const contentMm = width - config.margins.left - config.margins.right + const codePt = config.fontSize * CODE_SCALE + const charMm = codePt * CHAR_ADVANCE * PT_TO_MM + const usableMm = contentMm - codePt * GUTTER_EMS * PT_TO_MM + return Math.max(20, Math.floor(usableMm / charMm)) +} + +function rowsFor(line: Element, perRow: number): number { + return Math.max(1, Math.ceil((line.textContent ?? '').replace(/\n$/, '').length / perRow)) +} + +/** Partition lines into groups of roughly ROWS_PER_CHUNK rendered rows. */ +function groupLines(lines: readonly Element[], perRow: number): Element[][] { + const groups: Element[][] = [] + let current: Element[] = [] + let rows = 0 + + for (const line of lines) { + const lineRows = rowsFor(line, perRow) + if (current.length > 0 && rows + lineRows > ROWS_PER_CHUNK) { + groups.push(current) + current = [] + rows = 0 + } + current.push(line) + rows += lineRows + } + if (current.length > 0) groups.push(current) + return groups +} + +function buildChunk(block: HTMLElement, pre: HTMLElement, code: HTMLElement): HTMLElement { + const chunk = block.cloneNode(false) as HTMLElement + const newPre = pre.cloneNode(false) as HTMLElement + const newCode = code.cloneNode(false) as HTMLElement + newPre.appendChild(newCode) + chunk.appendChild(newPre) + return chunk +} + +function splitBlock(block: HTMLElement, perRow: number): void { + const pre = block.querySelector('pre') + const code = pre?.querySelector('code') + if (!pre || !code) return + + const lines = Array.from(code.children).filter((el) => el.classList.contains('code-line')) + if (lines.length === 0) return + + const totalRows = lines.reduce((sum, line) => sum + rowsFor(line, perRow), 0) + if (totalRows <= MIN_ROWS_TO_CHUNK) return + + const groups = groupLines(lines, perRow) + if (groups.length < 2) return + + const parent = block.parentNode + if (!parent) return + + const header = block.querySelector('.code-block__header') + const fragment = block.ownerDocument.createDocumentFragment() + + groups.forEach((group, index) => { + const chunk = buildChunk(block, pre, code) + const isFirst = index === 0 + const isLast = index === groups.length - 1 + chunk.dataset.codeChunk = isFirst ? 'first' : isLast ? 'last' : 'middle' + // The language label belongs to the listing, not to each piece of it. + if (isFirst && header) chunk.insertBefore(header, chunk.firstChild) + group.forEach((line) => chunk.querySelector('code')?.appendChild(line)) + fragment.appendChild(chunk) + }) + + parent.replaceChild(fragment, block) +} + +/** Cut every over-long code block in `root` into page-friendly pieces. */ +export function chunkCodeBlocks(root: HTMLElement, config: PdfConfig): void { + const perRow = charsPerRow(config) + root.querySelectorAll('.code-block').forEach((block) => { + splitBlock(block, perRow) + }) +} diff --git a/src/pdf/pageStyles.ts b/src/pdf/pageStyles.ts index 7052b8f..f0cc2b2 100644 --- a/src/pdf/pageStyles.ts +++ b/src/pdf/pageStyles.ts @@ -102,12 +102,18 @@ export function buildPageCss(config: PdfConfig): string { /* Break controls layered on top of document.css */ .scripto-doc h1, .scripto-doc h2, .scripto-doc h3 { break-after: avoid; } /* Small, atomic blocks stay whole; large tables are allowed to flow. */ - .scripto-doc pre, .scripto-doc .code-block, .scripto-doc figure, .scripto-doc blockquote, .scripto-doc .callout, .scripto-doc .katex-display, .scripto-doc .mermaid-figure { break-inside: avoid; } + /* Code blocks stay atomic — a long listing was already cut into page-sized + pieces by chunkCodeBlocks, so Paged.js only ever places whole ones. */ + .scripto-doc .code-block, .scripto-doc pre { break-inside: avoid; } + .scripto-doc .code-block__header { break-after: avoid; } + /* Interactive-only chrome has no place on paper. */ + .scripto-doc .code-block__copy { display: none; } + /* Tall diagrams / images are scaled to fit within one page's content box, WITH the heading that precedes them (headings set break-after: avoid). An unbreakable heading+figure taller than the page makes Paged.js split the diff --git a/src/styles/document.css b/src/styles/document.css index 3f594b0..8657690 100644 --- a/src/styles/document.css +++ b/src/styles/document.css @@ -225,6 +225,10 @@ text-decoration: none; border-bottom: 1px solid color-mix(in srgb, var(--doc-accent) 35%, transparent); transition: border-color 0.15s ease; + /* Bare URLs have no break opportunities of their own; without this a long one + runs straight off the page box and is clipped in the PDF. `anywhere` (not + `break-word`) so the link can also shrink inside a narrow table cell. */ + overflow-wrap: anywhere; } .scripto-doc a:hover { border-bottom-color: var(--doc-accent); @@ -259,7 +263,13 @@ padding: 0.12em 0.4em; border-radius: 5px; border: 1px solid var(--doc-rule); - word-break: break-word; + /* `overflow-wrap`, NOT `word-break: break-word` — the latter is an alias for + `overflow-wrap: anywhere`, which lets the break opportunities count towards + the element's min-content size. Inside any shrink-to-fit box (flex item, + grid track, narrow table cell) that collapses a token to a one-character + column. `break-word` still wraps long tokens, it just doesn't lie about + how narrow the element can get. */ + overflow-wrap: break-word; } /* ---------- Code blocks ---------- */ @@ -309,12 +319,17 @@ .scripto-doc pre { margin: 0; padding: 0.9em 0; - overflow-x: auto; background: var(--c-bg); color: var(--c-fg); font-size: 0.82em; line-height: 1.65; tab-size: 2; + /* Long lines wrap instead of scrolling: a scrollbar means nothing on paper, + where the overflow is simply clipped. `pre-wrap` keeps the indentation. + No `overflow-x` — a scroll container is monolithic, so it could never be + split across pages (see the code-block rules in pageStyles.ts). */ + white-space: pre-wrap; + overflow-wrap: break-word; } .scripto-doc pre code { font-family: 'JetBrains Mono', ui-monospace, monospace; @@ -323,11 +338,50 @@ padding: 0; display: block; } +/* A long listing is cut into consecutive atomic blocks for export + (chunkCodeBlocks.ts). Suppress every interior edge so the pieces read as one + block, and let only the outer two carry the border, radius and margins. */ +.scripto-doc .code-block[data-code-chunk] { + margin: 0; + border-radius: 0; + border-top: none; + border-bottom: none; + box-shadow: none; +} +.scripto-doc .code-block[data-code-chunk] pre { + padding-block: 0; +} +.scripto-doc .code-block[data-code-chunk='first'] { + margin-top: 1.2em; + border-top: 1px solid color-mix(in srgb, var(--c-fg) 14%, transparent); + border-start-start-radius: 10px; + border-start-end-radius: 10px; +} +.scripto-doc .code-block[data-code-chunk='first'] pre { + padding-block-start: 0.9em; +} +.scripto-doc .code-block[data-code-chunk='last'] { + margin-bottom: 1.2em; + border-bottom: 1px solid color-mix(in srgb, var(--c-fg) 14%, transparent); + border-end-start-radius: 10px; + border-end-end-radius: 10px; +} +.scripto-doc .code-block[data-code-chunk='last'] pre { + padding-block-end: 0.9em; +} + .scripto-doc .code-line { display: block; padding: 0 1.1em; border-left: 3px solid transparent; } +/* When a wrapped line continues onto the next visual row, hang it past the + line-number gutter (1.4em number + 1.1em margin) so it reads as a + continuation of the statement above rather than as a new line of code. */ +.scripto-doc .code-line.line-number { + padding-inline-start: 3.6em; + text-indent: -2.5em; +} .scripto-doc .code-line.highlight-line { background: color-mix(in srgb, var(--doc-accent) 16%, transparent); border-left-color: var(--doc-accent); @@ -460,24 +514,32 @@ .scripto-doc li > p:last-child { margin-bottom: 0; } -.scripto-doc ul.contains-task-list { +/* Task lists (GFM). The item MUST stay in normal inline flow: as a flex (or + grid) container every inline child — , , , a text run — + becomes its own column, and a nested list becomes a sibling column. The + checkbox instead hangs into the list's existing indent with a negative + inline-start margin, so wrapped lines align under the text, in LTR and RTL + alike. `list-style` is cleared on the item, not the list, so plain bullets + sitting alongside task items keep their markers. + Both GFM shapes are covered: tight items put the checkbox directly in the +
  • , loose items put it inside the item's first

    . */ +.scripto-doc li.task-list-item { list-style: none; - padding-inline-start: 0.2em; -} -.scripto-doc .task-list-item { - display: flex; - align-items: flex-start; - gap: 0.55em; } -.scripto-doc .task-list-item::marker { +.scripto-doc li.task-list-item::marker { content: ''; } .scripto-doc .task-list-item input[type='checkbox'] { - margin-top: 0.34em; + /* Explicit, because the standalone HTML export ships document.css without + Tailwind's preflight — without it the UA font-size applies and every `em` + below resolves against the wrong value. */ + font: inherit; width: 1.05em; height: 1.05em; + margin-block: 0; + margin-inline: -1.55em 0.5em; + vertical-align: -0.14em; accent-color: var(--doc-accent); - flex: none; } /* ---------- Horizontal rule ---------- */ @@ -514,6 +576,16 @@ text-align: start; vertical-align: top; border-bottom: 1px solid var(--doc-rule); + /* A table is sized from its cells' min-content widths, so what may break + decides the column widths. Ordinary words only break when they can't fit — + otherwise a long free-text column starves the rest and headers come out as + "Platfor / m". */ + overflow-wrap: break-word; +} +/* Long tokens and URLs are the ones that must be allowed to shrink, so the + table can still fit the page box without a scrollbar to fall back on. */ +.scripto-doc :is(th, td) :is(code, a) { + overflow-wrap: anywhere; } .scripto-doc th { font-family: Inter, sans-serif; @@ -523,6 +595,29 @@ color: var(--doc-fg); border-bottom: 2px solid color-mix(in srgb, var(--doc-accent) 30%, var(--doc-rule)); } +/* Wide tables: step type and padding down as the column count grows, so a 7- + or 9-column table still fits the page box instead of overflowing it. Gated on + an nth-child column existing, so it needs no markup from the author. */ +.scripto-doc table:has(> thead > tr > th:nth-child(6)), +.scripto-doc table:has(> tbody > tr > td:nth-child(6)) { + font-size: 0.82em; +} +.scripto-doc table:has(> thead > tr > th:nth-child(6)) :is(th, td), +.scripto-doc table:has(> tbody > tr > td:nth-child(6)) :is(th, td) { + padding: 0.4em 0.5em; +} +.scripto-doc table:has(> thead > tr > th:nth-child(8)), +.scripto-doc table:has(> tbody > tr > td:nth-child(8)) { + font-size: 0.74em; +} +.scripto-doc table:has(> thead > tr > th:nth-child(8)) :is(th, td), +.scripto-doc table:has(> tbody > tr > td:nth-child(8)) :is(th, td) { + padding: 0.3em 0.35em; +} +.scripto-doc table:has(> thead > tr > th:nth-child(8)) th { + letter-spacing: -0.01em; +} + .scripto-doc[data-table-style='striped'] tbody tr:nth-child(even) { background: color-mix(in srgb, var(--doc-fg) 3.5%, transparent); } @@ -1456,6 +1551,11 @@ text-transform: uppercase; align-self: center; } +/* Grid items default to `min-width: auto`, so a long token in the body would + push the 1fr track wider than the callout and spill past its border. */ +.scripto-doc .callout__body { + min-width: 0; +} .scripto-doc .callout__body > :first-child { margin-top: 0; } diff --git a/src/types/pagedjs.d.ts b/src/types/pagedjs.d.ts index 29afde7..25f51f7 100644 --- a/src/types/pagedjs.d.ts +++ b/src/types/pagedjs.d.ts @@ -15,7 +15,9 @@ declare module 'pagedjs' { on(event: string, handler: (...args: unknown[]) => void): void } - export class Handler {} + export class Handler { + constructor(chunker?: unknown, polisher?: unknown, caller?: unknown) + } export function registerHandlers(...handlers: unknown[]): void } From 7c170d73aed4e2cc7681c385a4ec64bcc533c079 Mon Sep 17 00:00:00 2001 From: aashir-tech Date: Sun, 16 Aug 2026 15:49:51 +0530 Subject: [PATCH 2/2] feat: page layout directives, fit-to-page, and a visual regression harness MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds author control over pagination and closes the remaining ways content could be silently clipped in a PDF. Directives (remarkPageDirectives): - ::page-break starts the next block on a fresh page - :::keep-together never splits a run across a page boundary - :::landscape puts a run on its own rotated page, via a named @page sized from the configured paper Content that cannot reflow: - fitToPage runs after pagination and scales down anything still wider than its page — display math, diagrams, ASCII figures, code. Reduces type size rather than applying a transform, so the element's box shrinks too; a transform would leave the original height as a gap. Shrinking only frees vertical space, so the laid-out pages stay valid. This closes the KaTeX clipping bug: .katex-display had the same overflow-x scroll-container trap that hid the code-block bug. - Tables past 10 columns stack into one labelled block per row (stackWideTables); the header text has to be copied onto the body cells as an attribute because CSS cannot reach across rows. - renderPagedPreview returns fit: { scaled, clipped } so the UI can warn when something was still too wide at the minimum scale. Export transforms now live behind prepareForPaging, so the regression suite runs exactly what the export runs rather than a copy that can drift. The standalone HTML export inlined KaTeX CSS instead of linking a CDN: if that CDN was unreachable, .katex-mathml stopped being hidden and every equation rendered twice, once typeset and once as raw MathML. The Word export gains the same stylesheet, so math survives there too. tests/visual renders fixtures through the real pipeline and paginator and asserts no element leaves the page content box, the rendered code-line sequence matches the source, and no line is blank where the source has content. Opt-in for now (SCRIPTO_VISUAL=1) — headless Chrome's --dump-dom races Paged.js's async layout under a virtual time budget. Two findings are captured in docs/RENDERING_AUDIT.md: Paged.js preloads every @font-face and stalls silently when one cannot load, and PagedConfig before/after are the supported hooks. --- docs/RENDERING_AUDIT.md | 192 ++++++++++++++ src/io/exporters.ts | 7 +- src/markdown/MarkdownRenderer.tsx | 2 + src/markdown/plugins/remarkPageDirectives.ts | 44 ++++ src/pdf/buildExportContent.ts | 4 +- src/pdf/fitToPage.ts | 54 ++++ src/pdf/pageStyles.ts | 17 ++ src/pdf/prepareForPaging.ts | 13 + src/pdf/renderPaged.ts | 9 +- src/pdf/stackWideTables.ts | 28 +++ src/styles/document.css | 57 +++++ tests/visual/fixtures/checklists.md | 86 +++++++ tests/visual/fixtures/code-blocks.md | 94 +++++++ tests/visual/fixtures/page-directives.md | 38 +++ tests/visual/fixtures/rtl-arabic.md | 39 +++ tests/visual/fixtures/structure.md | 97 ++++++++ tests/visual/fixtures/tables.md | 56 +++++ tests/visual/harness.ts | 247 +++++++++++++++++++ tests/visual/layout.test.ts | 86 +++++++ vitest.config.ts | 5 + 20 files changed, 1170 insertions(+), 5 deletions(-) create mode 100644 docs/RENDERING_AUDIT.md create mode 100644 src/markdown/plugins/remarkPageDirectives.ts create mode 100644 src/pdf/fitToPage.ts create mode 100644 src/pdf/prepareForPaging.ts create mode 100644 src/pdf/stackWideTables.ts create mode 100644 tests/visual/fixtures/checklists.md create mode 100644 tests/visual/fixtures/code-blocks.md create mode 100644 tests/visual/fixtures/page-directives.md create mode 100644 tests/visual/fixtures/rtl-arabic.md create mode 100644 tests/visual/fixtures/structure.md create mode 100644 tests/visual/fixtures/tables.md create mode 100644 tests/visual/harness.ts create mode 100644 tests/visual/layout.test.ts diff --git a/docs/RENDERING_AUDIT.md b/docs/RENDERING_AUDIT.md new file mode 100644 index 0000000..5b17386 --- /dev/null +++ b/docs/RENDERING_AUDIT.md @@ -0,0 +1,192 @@ +# Rendering audit & page-layout features + +Written 2026-08-16. Covers the checklist/code/table rendering bugs found from two +editor screenshots, the fixes, the new author-facing layout controls, and what is +still open. + +--- + +## 1 · The bug that started it + +Every checklist in the editor was rendering as columns — bold runs in one column, +inline code broken to one character per line in another. + +One declaration caused it: + +```css +.scripto-doc .task-list-item { display: flex } +``` + +A flex container promotes **every inline child to a flex item**. So `**bold**`, +`` `code` ``, and each text run became its own column. `word-break: break-word` +on inline code then let those items shrink to their min-content width, which for +a code token is a single character. + +Replaced with normal inline flow and a hanging checkbox: + +```css +.scripto-doc li.task-list-item { list-style: none } +.scripto-doc .task-list-item input[type='checkbox'] { + font: inherit; /* the HTML export ships no Tailwind preflight */ + margin-inline: -1.55em 0.5em; /* hangs into the list's own indent */ +} +``` + +Five further defects fell out of the same rule and were fixed with it: + +| Symptom | Why | +| --- | --- | +| Nested checklists rendered sideways | A nested `

      ` became a sibling flex column | +| Plain bullets lost their markers next to task items | `list-style: none` was on the list, not the item | +| Ordered checklists lost their numbering | A flex item is not a `list-item`, so the counter never advanced | +| Code blocks and quotes sat beside the checkbox | Block children became flex columns | +| Long URLs ran off the page | A flex item will not shrink below min-content | + +--- + +## 2 · Code blocks + +### Long lines were clipped + +`pre` had `overflow-x: auto`. A scrollbar means nothing on paper — the excess is +simply cut off. Lines now wrap with `white-space: pre-wrap`, and a wrapped +continuation hangs past the line-number gutter so it reads as a continuation +rather than a new statement. + +### Tall blocks jumped pages instead of splitting + +The cause was not obvious. `overflow-x: auto` made every block a **scroll +container**, and a scroll container is *monolithic* under CSS fragmentation — it +can never be split, so `break-inside` was being ignored regardless of its value. + +Removing it let blocks split, but Paged.js then blanks the line straddling the +page edge. Rather than fight the paginator, the export now cuts long listings +into page-sized atomic pieces before pagination: + +- `src/pdf/chunkCodeBlocks.ts` — splits at ~10 rendered rows, estimated from the + page width and the `pre` metrics. +- `document.css` `[data-code-chunk]` rules — suppress every interior edge so the + pieces read as one block. + +Paged.js therefore only ever places whole blocks, which is the case it handles +correctly. Verified: a 59-line block ends page 2 at line 28 and resumes page 3 at +line 29, with nothing lost. + +--- + +## 3 · Wide tables + +Type and padding step down automatically as the column count grows, gated with +`:has()` so it needs no markup from the author: + +| Columns | Font | Cell padding | +| --- | --- | --- | +| ≤ 5 | 0.92em | 0.55em 0.85em | +| 6–7 | 0.82em | 0.4em 0.5em | +| 8–9 | 0.74em | 0.3em 0.35em | +| 10+ | stacked — one labelled block per row | + +Only long tokens and URLs may break (`overflow-wrap: anywhere` on `code` and `a` +inside cells); ordinary words use `break-word`. Without that split, a long +free-text column starves the rest and headers come out as `Platfor / m`. + +Past 10 columns `stackWideTables.ts` copies each header into a `data-label` on the +body cells and CSS renders one labelled block per row — CSS alone cannot reach +across rows to fetch a header. + +--- + +## 4 · New author controls + +Three directives, handled by `remarkPageDirectives.ts`: + +```markdown +::page-break start the next block on a fresh page + +:::keep-together never split this run across a page boundary +| Step | Owner | +| --- | --- | +| Draft | Platform | +::: + +:::landscape put this run on its own rotated page +…a table too wide for portrait… +::: +``` + +`landscape` uses a named `@page` sized from the configured paper, rotated, and +breaks either side of the section. + +--- + +## 5 · Content that still cannot fit + +`src/pdf/fitToPage.ts` runs after pagination and scales down anything still wider +than its page — display math, diagrams, ASCII figures, code. Type size is reduced +rather than a transform applied, because that also shrinks the element's box; a +transform would leave the original height behind as a gap. Shrinking only frees +vertical space, so the pages already laid out stay valid. + +`renderPagedPreview` now returns `fit: { scaled, clipped }` so the UI can warn +when something was still too wide at the minimum scale. + +--- + +## 6 · Export leaks fixed + +- The **Copy** button was being printed into every PDF. +- Every checkbox carried `node="[object Object]"` into the preview DOM, the + standalone HTML export, and the PDF (react-markdown's hast node, spread onto + the element). +- The standalone HTML export linked KaTeX CSS from a CDN. If unreachable, + `.katex-mathml` stops being hidden and every equation renders twice — once + typeset, once as raw MathML. Now inlined, so the export is genuinely + self-contained. The Word export gained the same stylesheet, so math survives + there too. + +--- + +## 7 · Visual regression harness + +`tests/visual/` renders fixtures through the **real** pipeline — same stylesheet, +same `buildPageCss`, same export DOM transforms, same paginator — then asserts on +the laid-out result: + +- no element extends past the page content box +- the rendered code-line sequence matches the source exactly +- no line renders blank where the source has content + +Fixtures: `checklists`, `code-blocks`, `tables`, `structure`, `rtl-arabic`, +`page-directives`. Every bug in this document would have been caught by the first +assertion alone. + +### Status: opt-in, not yet gating + +```bash +SCRIPTO_VISUAL=1 npm test +``` + +Headless Chrome's `--dump-dom` races Paged.js's async layout under a virtual time +budget — the run is not yet reliable enough to gate commits on. Two things were +found and fixed along the way and are worth knowing: + +- Paged.js **preloads every `@font-face`** before laying out, and stalls silently + — zero pages, no error — if one cannot load. KaTeX's relative font URLs resolve + nowhere from a temp page, so the harness embeds the faces as data URIs. +- `PagedConfig.before` / `.after` are the supported hooks for running transforms + and probing results; `window.PagedPolyfill` does not exist. + +**Remaining fix:** drive Chrome over the DevTools Protocol and wait on the +`after` hook, instead of `--dump-dom` plus a virtual time budget. + +--- + +## 8 · Still open + +| Item | Note | +| --- | --- | +| Harness reliability | See above — the blocker to making it gate CI | +| Chunk slack | Code chunks are ~10 rows, so a page can end that far short | +| Stacked table rendering | Transform and CSS are in, but not yet visually confirmed end to end | +| Templates | 5 proposed (Arabic/bilingual invoice, incident postmortem, ADR, statement of work, investor update) — not built. With 55 templates and 19 skins already shipped this was judged the lowest-value track | +| Export presets | Named bundles of paper size, margins, skin and font — not started | diff --git a/src/io/exporters.ts b/src/io/exporters.ts index b34fd33..c33e1a4 100644 --- a/src/io/exporters.ts +++ b/src/io/exporters.ts @@ -1,4 +1,5 @@ import documentCss from '@/styles/document.css?inline' +import katexCss from 'katex/dist/katex.min.css?inline' import { downloadTextFile, escapeHtml } from '@/lib/utils' import { documentDataAttrs, documentStyleVars } from '@/pdf/documentStyle' import { FONT_STACKS } from '@/lib/constants' @@ -6,7 +7,6 @@ import type { PdfConfig } from '@/types' const FONTS_HREF = 'https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;500;700&family=Source+Serif+4:opsz,wght@8..60,400;8..60,600;8..60,700&family=Lora:wght@400;500;600;700&family=Noto+Naskh+Arabic:wght@400;500;600;700&family=Cairo:wght@400;500;600;700&family=Amiri:wght@400;700&display=swap' -const KATEX_HREF = 'https://cdn.jsdelivr.net/npm/katex@0.16.11/dist/katex.min.css' /** `` lang/dir attributes for an exported document. */ function htmlLangDir(config: PdfConfig): string { @@ -55,8 +55,10 @@ ${author ? `` : ''} ${keywords ? `` : ''} - +
      +
      ${body}
      +
      + + +` +} + +/** Render a fixture through the full export pipeline and report the layout. */ +export async function paginate( + fixture: string, + overrides: Partial = {}, +): Promise { + const chrome = findChrome() + if (!chrome) throw new Error('no Chrome binary found') + + const config = { ...DEFAULT_CONFIG, ...overrides } as PdfConfig + const markdown = readFileSync(`${FIXTURES}/${fixture}.md`, 'utf8') + const html = await buildHarnessPage(markdown, config, fixture.startsWith('rtl')) + + const dir = mkdtempSync(join(tmpdir(), 'scripto-page-')) + const page = join(dir, `${fixture}.html`) + writeFileSync(page, html) + + const { stdout } = await execFileAsync( + chrome, + [ + '--headless', + '--disable-gpu', + '--no-sandbox', + '--virtual-time-budget=120000', + '--dump-dom', + `file://${page}`, + ], + { maxBuffer: 64 * 1024 * 1024 }, + ) + + const match = stdout.match(/
      ([\s\S]*?)<\/pre>/)
+  if (!match || !match[1].trim()) {
+    if (process.env.SCRIPTO_VISUAL_DEBUG) {
+      // eslint-disable-next-line no-console
+      console.error(`[visual] page kept at ${page}`)
+    }
+    throw new Error('probe produced no output')
+  }
+
+  const decoded = match[1]
+    .replace(/"/g, '"')
+    .replace(/</g, '<')
+    .replace(/>/g, '>')
+    .replace(/'/g, "'")
+    .replace(/&/g, '&')
+  const report = JSON.parse(decoded) as PageReport & { error?: string }
+  if (report.error) throw new Error(`pagination failed: ${report.error}`)
+  return report
+}
+
+export const fixtureSource = (fixture: string): string =>
+  readFileSync(`${FIXTURES}/${fixture}.md`, 'utf8')
diff --git a/tests/visual/layout.test.ts b/tests/visual/layout.test.ts
new file mode 100644
index 0000000..0fd0173
--- /dev/null
+++ b/tests/visual/layout.test.ts
@@ -0,0 +1,86 @@
+import { describe, expect, it, vi } from 'vitest'
+
+// The renderer's code-block header pulls a label from the i18n context, which
+// needs a React provider we have no use for here — the label is hidden in the
+// PDF anyway and never affects layout.
+vi.mock('@/i18n', () => ({
+  useLanguage: () => ({ t: (key: string) => key, lang: 'en', dir: 'ltr', setLang: () => {} }),
+}))
+
+const { findChrome, fixtureSource, paginate, sourceCodeLines } = await import('./harness')
+type PageReport = Awaited>
+
+/**
+ * Layout regressions are invisible to unit tests: every bug fixed in this
+ * suite's history was a single CSS declaration that broke rendering while every
+ * other test stayed green. These render fixtures through the real export
+ * pipeline and Paged.js, then assert on the laid-out result.
+ *
+ * Needs a Chrome/Chromium binary (CHROME_PATH overrides discovery). Skipped
+ * rather than failed where none exists, so `npm test` still works on a bare box.
+ */
+
+const FIXTURES = [
+  'checklists',
+  'code-blocks',
+  'tables',
+  'structure',
+  'rtl-arabic',
+  'page-directives',
+] as const
+
+// Opt-in: `SCRIPTO_VISUAL=1 npm test`. Headless Chrome's --dump-dom races
+// Paged.js's async layout under a virtual time budget, so the run is not yet
+// reliable enough to gate every commit on. Everything else about the harness
+// works — see docs/VISUAL_REGRESSION.md for the remaining fix.
+const enabled = process.env.SCRIPTO_VISUAL === '1' && findChrome() !== null
+const suite = enabled ? describe : describe.skip
+
+// One pagination run per fixture, shared by every assertion about it.
+const reports = new Map>()
+const report = (fixture: string): Promise => {
+  if (!reports.has(fixture)) reports.set(fixture, paginate(fixture))
+  return reports.get(fixture)!
+}
+
+suite('paginated layout', () => {
+  describe.each(FIXTURES)('%s', (fixture) => {
+    it('lays out at least one page', async () => {
+      expect((await report(fixture)).pages).toBeGreaterThan(0)
+    })
+
+    it('keeps every element inside the page box', async () => {
+      // Anything sticking out horizontally is silently clipped in the PDF —
+      // there is no scrollbar on paper. This is what caught the flex task-list,
+      // the unwrapped code lines, and the overflowing wide tables.
+      const { overflowing } = await report(fixture)
+      expect(overflowing).toEqual([])
+    })
+
+    it('renders every source code line exactly once, in order', async () => {
+      // Paged.js can drop the line straddling a page edge when it fragments a
+      // code block, leaving an empty shell behind. Comparing the rendered run
+      // against the source is the only way to see it.
+      const { codeLines } = await report(fixture)
+      const source = sourceCodeLines(fixtureSource(fixture))
+      expect(codeLines.map((l) => l.text.replace(/\n$/, ''))).toEqual(source)
+    })
+
+    it('never renders a blank line where the source has content', async () => {
+      const { codeLines } = await report(fixture)
+      const source = sourceCodeLines(fixtureSource(fixture))
+      const blanked = codeLines.filter(
+        (rendered, index) => !rendered.text.trim() && (source[index] ?? '').trim(),
+      )
+      expect(blanked).toEqual([])
+    })
+  })
+
+  it('honours ::page-break and :::landscape', async () => {
+    const { pages } = await report('page-directives')
+    // Two forced breaks plus a landscape section that breaks either side.
+    expect(pages).toBeGreaterThanOrEqual(4)
+  })
+}, 240_000)
+
+
diff --git a/vitest.config.ts b/vitest.config.ts
index 9eef0e8..f0d115d 100644
--- a/vitest.config.ts
+++ b/vitest.config.ts
@@ -1,8 +1,13 @@
 import { defineConfig } from 'vitest/config'
+import path from 'node:path'
 
 export default defineConfig({
+  resolve: { alias: { '@': path.resolve(__dirname, './src') } },
   test: {
     environment: 'node',
     include: ['tests/**/*.test.ts'],
+    // Layout tests spawn headless Chrome and paginate real documents.
+    testTimeout: 240_000,
+    hookTimeout: 240_000,
   },
 })