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 `<ul>` 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'
 
 /** `<html>` lang/dir attributes for an exported document. */
 function htmlLangDir(config: PdfConfig): string {
@@ -55,8 +55,10 @@ ${author ? `<meta name="author" content="${escapeHtml(author)}" />` : ''}
 ${keywords ? `<meta name="keywords" content="${escapeHtml(keywords)}" />` : ''}
 <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
 <link href="${FONTS_HREF}" rel="stylesheet" />
-<link href="${KATEX_HREF}" rel="stylesheet" />
 <style>
+/* Inlined, not linked: an unreachable CDN would stop hiding .katex-mathml and
+   every equation would render twice — once typeset, once as raw MathML text. */
+${katexCss}
 ${documentCss}
 body { margin: 0; background: #f1f3f7; color: #1f2532; font-family: ${FONT_STACKS[config.font]}; }
 .page { max-width: 820px; margin: 0 auto; padding: 48px 24px; }
@@ -92,6 +94,7 @@ export function exportWord(docElement: HTMLElement, config: PdfConfig, name: str
 <meta charset="utf-8" />
 <title>${escapeHtml(config.meta.title || 'Document')}</title>
 <style>
+${katexCss}
 ${documentCss}
 body { font-family: ${FONT_STACKS[config.font]}; }
 ${config.customCss}
diff --git a/src/markdown/MarkdownRenderer.tsx b/src/markdown/MarkdownRenderer.tsx
index bb79673..54869d1 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'
@@ -13,6 +13,7 @@ import rehypePrismPlus from 'rehype-prism-plus'
 import { rehypeSourceLine } from './plugins/rehypeSourceLine'
 import { rehypeFenceMeta } from './plugins/rehypeFenceMeta'
 import { remarkCallouts } from './plugins/remarkCallouts'
+import { remarkPageDirectives } from './plugins/remarkPageDirectives'
 import { remarkMarks } from './plugins/remarkMarks'
 import { CodeBlock } from './components/CodeBlock'
 import { Mermaid } from './components/Mermaid'
@@ -63,6 +64,7 @@ const remarkPlugins = [
   remarkMath,
   remarkDirective,
   remarkCallouts,
+  remarkPageDirectives,
   remarkDefinitionList,
   remarkMarks,
   remarkGemoji,
@@ -131,18 +133,22 @@ function MarkdownRendererImpl({ content, resolvedTheme }: MarkdownRendererProps)
       a({ href, children }) {
         const isExternal = typeof href === 'string' && /^https?:\/\//.test(href)
         return (
-          <a
-            href={href}
-            {...(isExternal ? { target: '_blank', rel: 'noreferrer noopener' } : {})}
-          >
+          <a href={href} {...(isExternal ? { target: '_blank', rel: 'noreferrer noopener' } : {})}>
             {children as ReactNode}
           </a>
         )
       },
       img({ src, alt }) {
-        return <img src={typeof src === 'string' ? src : ''} alt={alt ?? ''} loading="lazy" decoding="async" />
+        return (
+          <img
+            src={typeof src === 'string' ? src : ''}
+            alt={alt ?? ''}
+            loading="lazy"
+            decoding="async"
+          />
+        )
       },
-      input({ type, checked, onChange: _onChange, ...rest }: ComponentPropsWithoutRef<'input'>) {
+      input({ node: _node, type, checked, onChange: _onChange, ...rest }) {
         if (type === 'checkbox') {
           return <input {...rest} type="checkbox" checked={Boolean(checked)} readOnly disabled />
         }
@@ -150,16 +156,32 @@ function MarkdownRendererImpl({ content, resolvedTheme }: MarkdownRendererProps)
       },
       // Headings that already carry a manual number opt out of auto-numbering.
       h1({ node, children, ...props }) {
-        return <h1 {...props} {...selfNumberedAttr(node as HastNode)}>{children as ReactNode}</h1>
+        return (
+          <h1 {...props} {...selfNumberedAttr(node as HastNode)}>
+            {children as ReactNode}
+          </h1>
+        )
       },
       h2({ node, children, ...props }) {
-        return <h2 {...props} {...selfNumberedAttr(node as HastNode)}>{children as ReactNode}</h2>
+        return (
+          <h2 {...props} {...selfNumberedAttr(node as HastNode)}>
+            {children as ReactNode}
+          </h2>
+        )
       },
       h3({ node, children, ...props }) {
-        return <h3 {...props} {...selfNumberedAttr(node as HastNode)}>{children as ReactNode}</h3>
+        return (
+          <h3 {...props} {...selfNumberedAttr(node as HastNode)}>
+            {children as ReactNode}
+          </h3>
+        )
       },
       h4({ node, children, ...props }) {
-        return <h4 {...props} {...selfNumberedAttr(node as HastNode)}>{children as ReactNode}</h4>
+        return (
+          <h4 {...props} {...selfNumberedAttr(node as HastNode)}>
+            {children as ReactNode}
+          </h4>
+        )
       },
     }
   }, [resolvedTheme])
diff --git a/src/markdown/plugins/remarkPageDirectives.ts b/src/markdown/plugins/remarkPageDirectives.ts
new file mode 100644
index 0000000..fa49d47
--- /dev/null
+++ b/src/markdown/plugins/remarkPageDirectives.ts
@@ -0,0 +1,44 @@
+import { visit } from 'unist-util-visit'
+
+// Layout control the author can reach for when the automatic rules aren't
+// enough:
+//
+//   ::page-break            start the next block on a fresh page
+//   :::keep-together … :::  never split this run across a page boundary
+//   :::landscape … :::      put this run on its own rotated page
+//
+// The CSS lives in document.css (`.page-break`, `.keep-together`) and
+// pageStyles.ts (the named `landscape` page).
+
+interface DirectiveNode {
+  type: 'containerDirective' | 'leafDirective' | 'textDirective'
+  name: string
+  children: unknown[]
+  data?: Record<string, unknown>
+}
+
+const CONTAINERS: Record<string, string> = {
+  'keep-together': 'keep-together',
+  landscape: 'page-landscape',
+}
+
+export function remarkPageDirectives() {
+  return (tree: unknown): void => {
+    visit(tree as never, (node: DirectiveNode) => {
+      if (node.type === 'leafDirective' && node.name === 'page-break') {
+        node.data = {
+          hName: 'div',
+          hProperties: { className: ['page-break'], 'aria-hidden': 'true' },
+          hChildren: [],
+        }
+        return
+      }
+
+      if (node.type !== 'containerDirective') return
+      const className = CONTAINERS[node.name]
+      if (!className) return
+
+      node.data = { hName: 'section', hProperties: { className: [className] } }
+    })
+  }
+}
diff --git a/src/pdf/buildExportContent.ts b/src/pdf/buildExportContent.ts
index 37aee68..01c53fc 100644
--- a/src/pdf/buildExportContent.ts
+++ b/src/pdf/buildExportContent.ts
@@ -1,4 +1,5 @@
 import { buildCoverHtml, resolveDocDirection } from './pageStyles'
+import { prepareForPaging } from './prepareForPaging'
 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)
+  prepareForPaging(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<HTMLElement>('.code-block').forEach((block) => {
+    splitBlock(block, perRow)
+  })
+}
diff --git a/src/pdf/fitToPage.ts b/src/pdf/fitToPage.ts
new file mode 100644
index 0000000..02cc37a
--- /dev/null
+++ b/src/pdf/fitToPage.ts
@@ -0,0 +1,54 @@
+/**
+ * Some content cannot reflow to fit a page: display math is typeset at a fixed
+ * width, and a diagram or table can be intrinsically wider than the page box.
+ * On screen `overflow-x: auto` hides that behind a scrollbar; on paper the
+ * excess is simply cut off, with no way to recover it.
+ *
+ * So after pagination, anything still wider than its page is scaled down to
+ * fit. 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 ever frees vertical space, so the pages
+ * already laid out stay valid and no re-pagination is needed.
+ */
+
+/** Things that can be intrinsically too wide and cannot wrap their way out. */
+const UNSHRINKABLE = '.katex-display, .mermaid-figure, .ascii-diagram, .table-wrap, pre'
+
+/** Leave a hair of slack so rounding can't re-trigger the overflow. */
+const SAFETY = 0.985
+/** Below this the content is unreadable; clamp and report instead. */
+const MIN_SCALE = 0.55
+
+export interface FitResult {
+  /** Elements that were scaled down to fit. */
+  scaled: number
+  /** Elements still wider than the page even at the minimum scale. */
+  clipped: number
+}
+
+export function fitToPage(container: HTMLElement): FitResult {
+  let scaled = 0
+  let clipped = 0
+
+  container.querySelectorAll<HTMLElement>('.pagedjs_page_content').forEach((content) => {
+    const available = content.getBoundingClientRect().width
+    if (available <= 0) return
+
+    content.querySelectorAll<HTMLElement>(UNSHRINKABLE).forEach((el) => {
+      // A chunked code block reports its `pre` and its wrapper; measure the
+      // widest thing actually painted inside.
+      const width = Math.max(el.scrollWidth, el.getBoundingClientRect().width)
+      if (width <= available + 1) return
+
+      const wanted = (available / width) * SAFETY
+      const scale = Math.max(MIN_SCALE, wanted)
+      const current = parseFloat(getComputedStyle(el).fontSize) || 16
+      el.style.fontSize = `${current * scale}px`
+      el.style.maxWidth = '100%'
+      scaled += 1
+      if (wanted < MIN_SCALE) clipped += 1
+    })
+  })
+
+  return { scaled, clipped }
+}
diff --git a/src/pdf/pageStyles.ts b/src/pdf/pageStyles.ts
index 7052b8f..7f0a3f6 100644
--- a/src/pdf/pageStyles.ts
+++ b/src/pdf/pageStyles.ts
@@ -77,6 +77,23 @@ export function buildPageCss(config: PdfConfig): string {
       ${marginBoxes.join('\n      ')}
     }
 
+    /* Rotated page for content that is simply wider than portrait allows.
+       Opt-in via the :::landscape directive, since it costs a break either
+       side. */
+    @page landscape {
+      size: ${round(height)}mm ${round(width)}mm;
+      ${marginBoxes.join('\n      ')}
+    }
+    .scripto-doc .page-landscape {
+      page: landscape;
+      break-before: page;
+      break-after: page;
+    }
+
+    /* Author-controlled breaks (remarkPageDirectives.ts) */
+    .scripto-doc .page-break { break-after: page; }
+    .scripto-doc .keep-together { break-inside: avoid; page-break-inside: avoid; }
+
     /* Cover page: full-bleed, no margin boxes */
     @page cover {
       margin: 0;
@@ -102,12 +119,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/pdf/prepareForPaging.ts b/src/pdf/prepareForPaging.ts
new file mode 100644
index 0000000..3c90a3f
--- /dev/null
+++ b/src/pdf/prepareForPaging.ts
@@ -0,0 +1,13 @@
+import { chunkCodeBlocks } from './chunkCodeBlocks'
+import { stackWideTables } from './stackWideTables'
+import type { PdfConfig } from '@/types'
+
+/**
+ * Every DOM transform the export applies before handing a document to the
+ * paginator. Kept in one place so the visual regression suite can run exactly
+ * what the export runs, rather than a re-implementation that can drift.
+ */
+export function prepareForPaging(root: HTMLElement, config: PdfConfig): void {
+  chunkCodeBlocks(root, config)
+  stackWideTables(root)
+}
diff --git a/src/pdf/renderPaged.ts b/src/pdf/renderPaged.ts
index 946afff..f831217 100644
--- a/src/pdf/renderPaged.ts
+++ b/src/pdf/renderPaged.ts
@@ -1,6 +1,7 @@
 import { Previewer } from 'pagedjs'
 import { buildExportContent, type ExportStrings } from './buildExportContent'
 import { buildPageCss } from './pageStyles'
+import { fitToPage } from './fitToPage'
 import { getErrorMessage, logger } from '@/lib/logger'
 import type { ExportProgress, PdfConfig, TocEntry } from '@/types'
 
@@ -16,6 +17,8 @@ interface RenderOptions {
 export interface RenderResult {
   pageCount: number
   toc: TocEntry[]
+  /** Content too wide for the page: scaled down to fit, or still clipped. */
+  fit: { scaled: number; clipped: number }
 }
 
 // A dead/slow image host must never hang the export.
@@ -128,9 +131,13 @@ export async function renderPagedPreview({
       ),
     )
 
+    // Anything that could not reflow into the page box is scaled to fit now
+    // that real widths exist. Shrinking only frees space, so the layout holds.
+    const fit = fitToPage(container)
+
     const pageCount = flow?.total ?? container.querySelectorAll('.pagedjs_page').length
     onProgress?.({ stage: 'done', message: `${pageCount} page${pageCount === 1 ? '' : 's'} ready`, percent: 100 })
-    return { pageCount, toc }
+    return { pageCount, toc, fit }
   } catch (error) {
     logger.error('Paged.js rendering failed', error)
     onProgress?.({ stage: 'error', message: getErrorMessage(error), percent: 0 })
diff --git a/src/pdf/stackWideTables.ts b/src/pdf/stackWideTables.ts
new file mode 100644
index 0000000..bcc198a
--- /dev/null
+++ b/src/pdf/stackWideTables.ts
@@ -0,0 +1,28 @@
+/**
+ * Past a certain width, shrinking type stops helping: a 10+ column table gets
+ * columns a couple of characters wide and becomes unreadable. Those tables are
+ * turned into one labelled block per row instead, which is longer but legible.
+ *
+ * The labels have to be baked in as attributes here — CSS alone cannot copy a
+ * header cell down into the body rows.
+ */
+
+/** Column count at which compaction gives up and rows are stacked. */
+const STACK_AT_COLUMNS = 10
+
+export function stackWideTables(root: HTMLElement): void {
+  root.querySelectorAll<HTMLTableElement>('table').forEach((table) => {
+    const headers = Array.from(table.querySelectorAll('thead th')).map(
+      (th) => th.textContent?.trim() ?? '',
+    )
+    if (headers.length < STACK_AT_COLUMNS) return
+
+    table.classList.add('table--stacked')
+    table.querySelectorAll('tbody tr').forEach((row) => {
+      Array.from(row.children).forEach((cell, index) => {
+        const label = headers[index]
+        if (label) (cell as HTMLElement).dataset.label = label
+      })
+    })
+  })
+}
diff --git a/src/styles/document.css b/src/styles/document.css
index 3f594b0..e3602eb 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,49 @@
 .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 — <strong>, <code>, <a>, 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
+   <li>, loose items put it inside the item's first <p>. */
+.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;
+}
+
+/* ---------- Page layout directives ---------- */
+/* `::page-break`, `:::keep-together`, `:::landscape` — see
+   remarkPageDirectives.ts. Inert on screen; the break behaviour is in
+   pageStyles.ts, which only runs under the paginator. */
+.scripto-doc .page-break {
+  height: 0;
+  margin: 0;
+}
+.scripto-doc .keep-together > :first-child,
+.scripto-doc .page-landscape > :first-child {
+  margin-top: 0;
+}
+.scripto-doc .keep-together > :last-child,
+.scripto-doc .page-landscape > :last-child {
+  margin-bottom: 0;
 }
 
 /* ---------- Horizontal rule ---------- */
@@ -514,6 +593,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 +612,69 @@
   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;
+}
+
+/* Past ~10 columns compaction stops being readable, so each row becomes a
+   labelled block instead. The labels are copied from the header cells at export
+   time (stackWideTables.ts) — CSS cannot reach across rows to fetch them. */
+.scripto-doc table.table--stacked {
+  font-size: 0.9em;
+  border-collapse: separate;
+  border-spacing: 0;
+}
+.scripto-doc table.table--stacked thead {
+  display: none;
+}
+.scripto-doc table.table--stacked tbody,
+.scripto-doc table.table--stacked tr,
+.scripto-doc table.table--stacked td {
+  display: block;
+  width: auto;
+}
+.scripto-doc table.table--stacked tr {
+  border: 1px solid var(--doc-rule);
+  border-radius: 8px;
+  padding: 0.5em 0.8em;
+  margin-bottom: 0.6em;
+  break-inside: avoid;
+  page-break-inside: avoid;
+}
+.scripto-doc table.table--stacked td {
+  display: grid;
+  grid-template-columns: minmax(5em, 28%) 1fr;
+  gap: 0 0.9em;
+  border: none;
+  padding: 0.16em 0;
+}
+.scripto-doc table.table--stacked td::before {
+  content: attr(data-label);
+  font-family: Inter, sans-serif;
+  font-weight: 600;
+  font-size: 0.85em;
+  color: var(--doc-muted);
+}
+
 .scripto-doc[data-table-style='striped'] tbody tr:nth-child(even) {
   background: color-mix(in srgb, var(--doc-fg) 3.5%, transparent);
 }
@@ -1456,6 +1608,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
 }
 
diff --git a/tests/visual/fixtures/checklists.md b/tests/visual/fixtures/checklists.md
new file mode 100644
index 0000000..337708f
--- /dev/null
+++ b/tests/visual/fixtures/checklists.md
@@ -0,0 +1,86 @@
+# Rendering torture test
+
+## 1 · Tight task list with inline formatting (the reported bug)
+
+- [ ] Create/confirm a **Meta Business Portfolio** (Meta Business Suite) that will own the app.
+- [ ] Make sure the business's **legal name, address, and phone match public records** and your official documents (in KSA: exactly as on your Commercial Registration, Arabic + English).
+- [x] Create the app at developers.facebook.com → **App type = Business** (⚠️ this choice is permanent — do not pick Consumer).
+- [ ] **Start Business Verification** (App Dashboard → Settings → Basic → Start Verification). **This is the longest fixed wait (several days to ~2 weeks) — start it day one.**
+
+## 2 · Tight task list with inline code (the second reported bug)
+
+- [ ] Choose the **Instagram route = "Instagram API with Facebook Login"** (permissions `instagram_basic`, `instagram_content_publish`, `instagram_manage_comments`, `instagram_manage_insights`). ⚠️ Do **not** also request the `instagram_business_*` set — that's a different route and requesting both confuses reviewers.
+- [ ] Submit **App Review** for the permissions: `pages_show_list`, `pages_read_engagement`, `pages_manage_posts`, `pages_manage_engagement`, `pages_manage_metadata`, `publish_video`, `business_management`.
+- [ ] A single enormous unbreakable token: `AbCdEfGhIjKlMnOpQrStUvWxYz0123456789AbCdEfGhIjKlMnOpQrStUvWxYz0123456789`
+
+## 3 · Loose task list (blank lines between items)
+
+- [ ] Loose item with **bold** and `code` and a [link](https://example.com/some/deep/path).
+
+- [x] Second loose item — should align identically to the tight ones above.
+
+## 4 · Nested task lists
+
+- [ ] Parent task with **bold**
+  - [ ] Child task with `inline_code`
+    - [x] Grandchild task
+  - [ ] Second child
+- [x] Sibling parent
+
+## 5 · Mixed list — task items next to plain bullets
+
+- [ ] A task item
+- A plain bullet that must keep its disc marker
+- [x] Another task item
+- Another plain bullet
+
+## 6 · Ordered list containing task items
+
+1. [ ] Ordered task one
+2. [x] Ordered task two
+3. A plain ordered item
+
+## 7 · Task item with block children
+
+- [ ] Task with a fenced block underneath:
+
+  ```ts
+  const x: number = 1
+  ```
+
+- [ ] Task followed by a blockquote
+
+  > quoted line inside a task item
+
+## 8 · Task item wrapping a long link and image
+
+- [ ] Long bare URL: https://developers.facebook.com/docs/permissions/reference/instagram_content_publish?locale=en_US&extra=aaaaaaaaaaaaaaa
+- [ ] ![tiny](data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7) inline image in a task item
+
+## 9 · Table with long tokens
+
+| Permission | Description | Docs |
+| --- | --- | --- |
+| `instagram_content_publish` | Lets the app publish media to a connected Instagram professional account on behalf of the user. | https://developers.facebook.com/docs/permissions/reference/instagram_content_publish |
+| `pages_manage_metadata` | Subscribe/unsubscribe webhooks. | https://developers.facebook.com/docs/permissions/reference/pages_manage_metadata |
+
+## 10 · Callout with long inline code
+
+:::warning{title="Do not mix routes"}
+Requesting `instagram_business_basic` alongside `instagram_basic` triggers an automatic rejection: https://developers.facebook.com/docs/instagram-platform/instagram-api-with-facebook-login
+:::
+
+## 11 · Definition list
+
+Term with `code`
+: Definition body with a very long token AbCdEfGhIjKlMnOpQrStUvWxYz0123456789AbCdEfGhIjKlMnOpQrStUvWxYz
+
+## 12 · Footnote
+
+Some claim that needs a source.[^1]
+
+[^1]: The footnote body with `inline_code` and a long URL https://example.com/aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
+
+## 13 · Heading with a `code_token_that_is_extremely_long_and_unbreakable_abcdefghijklmnop`
+
+Body text after.
diff --git a/tests/visual/fixtures/code-blocks.md b/tests/visual/fixtures/code-blocks.md
new file mode 100644
index 0000000..4e852b6
--- /dev/null
+++ b/tests/visual/fixtures/code-blocks.md
@@ -0,0 +1,94 @@
+# Code block pagination test
+
+Some intro text so the first code block does not start at the very top of the page,
+which is what makes the "jumps to the next page" behaviour visible in the first place.
+
+## A · Wide lines (must wrap, not clip)
+
+```nginx
+# SSE / token-streaming AI endpoints — must NOT buffer.
+location /api/ai/ {
+    proxy_pass http://127.0.0.1:3003;
+    proxy_http_version 1.1;              # chunked + keepalive (default is 1.0 pre-nginx-1.29.7)
+    proxy_set_header Connection "";       # required for upstream keepalive on HTTP/1.1
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+
+    proxy_buffering off;                  # pass response to client as-received (default: on = buffered)
+    proxy_cache off;
+    proxy_read_timeout 300s;              # between two successive reads — heartbeats reset it
+    proxy_send_timeout 300s;
+    gzip off;                             # belt-and-braces; text/event-stream isn't in gzip_types anyway
+    chunked_transfer_encoding on;         # default on — do not disable
+}
+```
+
+Text between the two blocks.
+
+## B · Tall block (must split across pages, not jump)
+
+```ts
+export async function streamCompletion(req: StreamRequest): Promise<StreamHandle> {
+  const controller = new AbortController()
+  const signal = controller.signal
+  const started = performance.now()
+  const decoder = new TextDecoder()
+  let buffered = ''
+  let tokens = 0
+
+  const response = await fetch(req.endpoint, {
+    method: 'POST',
+    signal,
+    headers: {
+      'content-type': 'application/json',
+      accept: 'text/event-stream',
+      authorization: `Bearer ${req.token}`,
+    },
+    body: JSON.stringify({ model: req.model, messages: req.messages, stream: true }),
+  })
+
+  if (!response.ok) {
+    const detail = await response.text().catch(() => '')
+    throw new StreamError(`upstream ${response.status}`, { status: response.status, detail })
+  }
+  if (!response.body) {
+    throw new StreamError('upstream returned no body', { status: response.status })
+  }
+
+  const reader = response.body.getReader()
+
+  async function pump(): Promise<void> {
+    for (;;) {
+      const { done, value } = await reader.read()
+      if (done) break
+      buffered += decoder.decode(value, { stream: true })
+
+      let index = buffered.indexOf('\n\n')
+      while (index !== -1) {
+        const frame = buffered.slice(0, index)
+        buffered = buffered.slice(index + 2)
+        index = buffered.indexOf('\n\n')
+
+        if (!frame.startsWith('data:')) continue
+        const payload = frame.slice(5).trim()
+        if (payload === '[DONE]') return
+
+        try {
+          const parsed = JSON.parse(payload) as StreamFrame
+          tokens += 1
+          req.onToken(parsed.choices[0]?.delta?.content ?? '')
+        } catch (error) {
+          req.onError(new StreamError('malformed frame', { cause: error }))
+        }
+      }
+    }
+  }
+
+  await pump()
+  return { tokens, elapsed: performance.now() - started, abort: () => controller.abort() }
+}
+```
+
+Trailing paragraph after the tall block.
diff --git a/tests/visual/fixtures/page-directives.md b/tests/visual/fixtures/page-directives.md
new file mode 100644
index 0000000..6a2cc14
--- /dev/null
+++ b/tests/visual/fixtures/page-directives.md
@@ -0,0 +1,38 @@
+# Page layout directives
+
+Text on the first page, before any forced break.
+
+::page-break
+
+## After a forced break
+
+This heading must start a new page because of the `::page-break` above it.
+
+:::keep-together
+### A run that must not split
+
+- [ ] first item
+- [ ] second item
+- [ ] third item
+
+| Step | Owner |
+| --- | --- |
+| Draft | Platform |
+| Review | Legal |
+:::
+
+::page-break
+
+## Landscape
+
+:::landscape
+### A table that needs the extra width
+
+| ID | Platform | Gate | Owner | Started | Status | Approved | Retries | Escalated | Notes |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| 1 | Instagram | Business Verification | Aashir Haris | 2026-07-02 | Approved | 2026-07-19 | 0 | No | Clean first pass, no follow-up needed |
+| 2 | Facebook Pages | App Review | Platform Team | 2026-07-04 | In review | — | 1 | No | Screencast re-recorded at 1080p |
+| 3 | Threads | App Review | Platform Team | 2026-07-21 | Rejected | — | 2 | Yes | Needs a separate app registration |
+:::
+
+Back to portrait after the landscape section.
diff --git a/tests/visual/fixtures/rtl-arabic.md b/tests/visual/fixtures/rtl-arabic.md
new file mode 100644
index 0000000..38301a7
--- /dev/null
+++ b/tests/visual/fixtures/rtl-arabic.md
@@ -0,0 +1,39 @@
+# خطة مراجعة تطبيق ميتا
+
+فقرة تمهيدية بالعربية تحتوي على مصطلح إنجليزي مثل **Business Verification** وكذلك رمز `instagram_basic` داخل النص.
+
+## أ · قائمة المهام
+
+- [ ] إنشاء **حافظة أعمال ميتا** (Meta Business Suite) التي ستملك التطبيق.
+- [ ] التأكد من تطابق **الاسم القانوني والعنوان والهاتف** مع السجل التجاري (بالعربية والإنجليزية).
+- [x] إنشاء التطبيق واختيار **App type = Business** — هذا الاختيار نهائي ولا يمكن تغييره.
+- [ ] طلب الأذونات `instagram_basic` و `instagram_content_publish` و `instagram_manage_comments`.
+  - [ ] مهمة فرعية مع رابط طويل https://developers.facebook.com/docs/permissions/reference/instagram_content_publish
+  - [x] مهمة فرعية منتهية
+
+## ب · جدول
+
+| المنصة | البوابة | المسؤول | الحالة | الملاحظات |
+| --- | --- | --- | --- | --- |
+| إنستغرام | توثيق الأعمال | عاشر | ✅ معتمد | استغرق ١٧ يوماً |
+| فيسبوك | مراجعة التطبيق | الفريق | ⏳ قيد المراجعة | إعادة تسجيل الفيديو |
+| ثريدز | مراجعة التطبيق | الفريق | 🚫 مرفوض | يحتاج تطبيقاً منفصلاً |
+
+## ج · كتلة برمجية
+
+```nginx
+# نقاط النهاية التي تبث الرموز — يجب ألا تُخزَّن مؤقتاً
+location /api/ai/ {
+    proxy_pass http://127.0.0.1:3003;
+    proxy_buffering off;                  # تمرير الاستجابة كما تصل
+    proxy_read_timeout 300s;
+}
+```
+
+## د · تنبيه
+
+:::warning{title="لا تخلط المسارات"}
+طلب `instagram_business_basic` مع `instagram_basic` يؤدي إلى رفض تلقائي.
+:::
+
+> اقتباس بالعربية مع **نص عريض** ورمز `code_token`.
diff --git a/tests/visual/fixtures/structure.md b/tests/visual/fixtures/structure.md
new file mode 100644
index 0000000..993472b
--- /dev/null
+++ b/tests/visual/fixtures/structure.md
@@ -0,0 +1,97 @@
+# Lists, notes & math
+
+## 1 · Deeply nested mixed lists
+
+1. Ordered level one with **bold**
+   - Unordered level two with `code_token`
+     1. Ordered level three
+        - [ ] Task at level four with **bold** and `inline_code`
+          - [x] Task at level five
+            - Plain bullet at level six with a long URL https://example.com/very/deep/path/that/keeps/going/and/going
+   - Second level two
+2. Back to level one
+
+- [ ] Task containing a table
+
+  | A | B |
+  | --- | --- |
+  | 1 | 2 |
+
+- [ ] Task containing an image and a nested ordered list
+  1. First
+  2. Second
+
+## 2 · Loose vs tight in one document
+
+- tight one
+- tight two
+
+* loose one
+
+* loose two
+
+## 3 · Definition lists
+
+`instagram_basic`
+: Baseline read permission. Required for **every** Instagram Graph call, including the ones that only touch metadata.
+
+Business Verification
+: A one-time review of the legal entity. Takes several days to ~2 weeks.
+: Can be reused across apps in the same portfolio.
+
+## 4 · Math
+
+Inline math $E = mc^2$ inside a sentence, and a display block:
+
+$$
+\frac{\partial L}{\partial \theta} = \sum_{i=1}^{n} \left( \hat{y}_i - y_i \right) x_i + \lambda \lVert \theta \rVert_2^2
+$$
+
+A very wide display equation that must not run off the page:
+
+$$
+f(x) = a_0 + a_1 x + a_2 x^2 + a_3 x^3 + a_4 x^4 + a_5 x^5 + a_6 x^6 + a_7 x^7 + a_8 x^8 + a_9 x^9 + a_{10} x^{10}
+$$
+
+## 5 · Callouts
+
+:::warning{title="One route only"}
+Requesting `instagram_business_basic` alongside `instagram_basic` triggers an automatic rejection. See https://developers.facebook.com/docs/instagram-platform/instagram-api-with-facebook-login for the full matrix.
+:::
+
+:::tip
+A callout containing a list:
+
+- [ ] item with `code`
+- [x] done item
+:::
+
+## 6 · Blockquotes
+
+> A quote with **bold**, `code`, and a [link](https://example.com).
+>
+> > A nested quote inside it.
+>
+> - a list inside a quote
+> - second item
+
+## 7 · Footnotes
+
+Meta's review now warns ~20 days per submission.[^meta] A second reference.[^two]
+
+[^meta]: Measured across five submissions between June and August 2026. Source: https://developers.facebook.com/docs/app-review
+[^two]: A footnote with `inline_code` and **bold**.
+
+## 8 · Horizontal rules and headings
+
+### H3 with `code` in it
+
+#### H4 level
+
+##### H5 level
+
+###### H6 level
+
+---
+
+Trailing paragraph.
diff --git a/tests/visual/fixtures/tables.md b/tests/visual/fixtures/tables.md
new file mode 100644
index 0000000..73ba33c
--- /dev/null
+++ b/tests/visual/fixtures/tables.md
@@ -0,0 +1,56 @@
+# Wide tables & raw HTML
+
+## 1 · Seven columns (the reported shape)
+
+| Platform | Gate | Owner | Started | Status | Approved on | Notes |
+| --- | --- | --- | --- | --- | --- | --- |
+| Instagram | Business Verification | Aashir Haris | 2026-07-02 | ✅ Approved | 2026-07-19 | Took 17 days; CR in Arabic + English matched exactly. |
+| Facebook Pages | App Review | Platform Team | 2026-07-04 | ⏳ In review | — | Screencast re-recorded at 1080p after first rejection. |
+| Threads | App Review | Platform Team | 2026-07-21 | 🚫 Rejected | — | `threads_manage_insights` needs a separate app; resubmitting. |
+| WhatsApp | Business Verification | Finance | 2026-06-28 | ✅ Approved | 2026-07-05 | Reused the portfolio verification from Instagram. |
+| TikTok | Content Posting API | Growth | 2026-08-01 | ⏳ In review | — | Sandbox tenant provisioned, awaiting production scope. |
+
+## 2 · Nine columns
+
+| ID | Platform | Gate | Owner | Started | Status | Approved | Retries | Notes |
+| --- | --- | --- | --- | --- | --- | --- | --- | --- |
+| 1 | Instagram | Business Verification | Aashir | 2026-07-02 | Approved | 2026-07-19 | 0 | Clean first pass |
+| 2 | Facebook | App Review | Platform | 2026-07-04 | In review | — | 1 | Screencast redone |
+| 3 | Threads | App Review | Platform | 2026-07-21 | Rejected | — | 2 | Separate app needed |
+
+## 3 · Five columns (must stay at the current density)
+
+| Permission | Scope | Route | Required | Notes |
+| --- | --- | --- | --- | --- |
+| `instagram_basic` | Read | IG w/ FB Login | Yes | Baseline for every call |
+| `instagram_content_publish` | Write | IG w/ FB Login | Yes | Publishing only |
+
+## 4 · Long unbreakable content inside cells
+
+| Endpoint | Docs |
+| --- | --- |
+| `POST /v26.0/{ig-user-id}/media_publish` | https://developers.facebook.com/docs/instagram-platform/instagram-api-with-facebook-login/content-publishing |
+
+## 5 · Raw HTML passthrough
+
+<div style="border:1px solid #ccc;padding:8px;border-radius:6px">
+  A raw <strong>HTML block</strong> with an inline <code>code_token</code> and a
+  <a href="https://example.com">link</a>.
+</div>
+
+<table>
+  <thead><tr><th>Raw</th><th>HTML</th><th>Table</th></tr></thead>
+  <tbody><tr><td>one</td><td>two</td><td>three</td></tr></tbody>
+</table>
+
+## 6 · Malformed Markdown
+
+| Broken | Table |
+| --- |
+| missing a cell |
+| too | many | cells |
+
+Unclosed emphasis **like this and a stray pipe | in text.
+
+```ts
+const unclosed = "this fence never closes"
diff --git a/tests/visual/harness.ts b/tests/visual/harness.ts
new file mode 100644
index 0000000..5f96725
--- /dev/null
+++ b/tests/visual/harness.ts
@@ -0,0 +1,247 @@
+import { createElement } from 'react'
+import { renderToStaticMarkup } from 'react-dom/server'
+import { execFile } from 'node:child_process'
+import { existsSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { promisify } from 'node:util'
+import { build } from 'esbuild'
+import { DEFAULT_CONFIG } from '@/lib/constants'
+import { buildPageCss } from '@/pdf/pageStyles'
+import type { PdfConfig } from '@/types'
+
+const execFileAsync = promisify(execFile)
+
+export const ROOT = new URL('../..', import.meta.url).pathname.replace(/\/$/, '')
+const FIXTURES = `${ROOT}/tests/visual/fixtures`
+
+/** Chrome locations to try, in order, when CHROME_PATH is not set. */
+const CHROME_CANDIDATES = [
+  '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+  '/Applications/Chromium.app/Contents/MacOS/Chromium',
+  '/usr/bin/google-chrome',
+  '/usr/bin/google-chrome-stable',
+  '/usr/bin/chromium',
+  '/usr/bin/chromium-browser',
+]
+
+/** Resolve a headless Chrome binary, or null when none is installed. */
+export function findChrome(): string | null {
+  const fromEnv = process.env.CHROME_PATH
+  if (fromEnv && existsSync(fromEnv)) return fromEnv
+  return CHROME_CANDIDATES.find((path) => existsSync(path)) ?? null
+}
+
+/** Every code line in a fenced block, in source order, for the whole document. */
+export function sourceCodeLines(markdown: string): string[] {
+  const lines: string[] = []
+  const fence = /^([ \t]*)(?:```|~~~)([^\n]*)\n([\s\S]*?)^[ \t]*(?:```|~~~)[ \t]*$/gm
+  for (const match of markdown.matchAll(fence)) {
+    const language = match[2].trim().split(/\s+/)[0] ?? ''
+    // Mermaid and ASCII fences render as figures, not `.code-line` runs.
+    if (language === 'mermaid') continue
+    lines.push(...match[3].replace(/\n$/, '').split('\n'))
+  }
+  return lines
+}
+
+/** What the in-page probe reports back after pagination settles. */
+export interface PageReport {
+  pages: number
+  /** Elements sticking out past the page content box, per page. */
+  overflowing: { page: number; tag: string; cls: string; by: number }[]
+  /** Rendered code lines, in page then document order. */
+  codeLines: { line: number; text: string }[]
+  /** Any element whose text was dropped by the paginator. */
+  emptiedElements: string[]
+}
+
+/**
+ * Paged.js preloads every @font-face before it lays out, and stalls silently —
+ * zero pages, no error — when a face cannot load. KaTeX ships relative font
+ * URLs that resolve nowhere from a temp page, and Chrome blocks file:// fetches
+ * across directories anyway, so the faces are embedded instead. Data URIs also
+ * keep the real glyph metrics, without which the math-overflow assertions would
+ * be measuring a fallback font.
+ */
+function inlineKatexFonts(): string {
+  const dist = `${ROOT}/node_modules/katex/dist`
+  const css = readFileSync(`${dist}/katex.min.css`, 'utf8')
+  return css.replace(/@font-face\{[^}]*\}/g, (face) => {
+    const woff2 = face.match(/url\(fonts\/([\w-]+\.woff2)\)/)
+    if (!woff2) return ''
+    const data = readFileSync(`${dist}/fonts/${woff2[1]}`).toString('base64')
+    return face.replace(
+      /src:[^;}]+/,
+      `src:url(data:font/woff2;base64,${data}) format("woff2")`,
+    )
+  })
+}
+
+/**
+ * Bundle the export-time DOM transforms for the browser. The harness runs the
+ * real `buildExportContent` pipeline rather than a copy of it, so a regression
+ * in chunking or table labelling fails here too.
+ */
+async function bundleTransforms(): Promise<string> {
+  const dir = mkdtempSync(join(tmpdir(), 'scripto-visual-'))
+  const entry = join(dir, 'entry.ts')
+  const out = join(dir, 'out.js')
+  writeFileSync(
+    entry,
+    `import { prepareForPaging } from '${ROOT}/src/pdf/prepareForPaging'
+     window.__prepare = (config) => {
+       document.querySelectorAll('.scripto-doc').forEach((doc) => prepareForPaging(doc, config))
+     }`,
+  )
+  await build({
+    entryPoints: [entry],
+    outfile: out,
+    bundle: true,
+    format: 'iife',
+    alias: { '@': `${ROOT}/src` },
+    logLevel: 'silent',
+  })
+  return readFileSync(out, 'utf8')
+}
+
+/**
+ * Assemble a self-contained page that renders `markdown` exactly the way the
+ * export does — same stylesheet, same page CSS, same DOM transforms, same
+ * paginator — then probes the laid-out result.
+ */
+async function buildHarnessPage(markdown: string, config: PdfConfig, rtl: boolean): Promise<string> {
+  const body = renderToStaticMarkup(
+    createElement(
+      (await import('@/markdown/MarkdownRenderer')).MarkdownRenderer,
+      { content: markdown, resolvedTheme: 'light' },
+    ),
+  )
+  const documentCss = readFileSync(`${ROOT}/src/styles/document.css`, 'utf8')
+  const katexCss = inlineKatexFonts()
+  const printCss = readFileSync(`${ROOT}/src/styles/print.css`, 'utf8')
+  const polyfill = readFileSync(`${ROOT}/node_modules/pagedjs/dist/paged.polyfill.js`, 'utf8')
+  const transforms = await bundleTransforms()
+
+  return `<!doctype html><meta charset="utf-8">
+<style>
+body { margin: 0; background: #eef1f6; }
+${katexCss}
+${documentCss.replace(/@import[^;]+;/g, '')}
+${printCss}
+${buildPageCss(config)}
+</style>
+<div class="scripto-print-surface">
+  <div class="scripto-doc"${rtl ? ' dir="rtl" style="direction:rtl"' : ''}>${body}</div>
+</div>
+<script>${transforms}</script>
+<script>
+  const fail = (message) => {
+    const out = document.createElement('pre')
+    out.id = 'probe'
+    out.textContent = JSON.stringify({ error: String(message) })
+    document.body.appendChild(out)
+  }
+  window.addEventListener('error', (event) => fail(event.message))
+  window.addEventListener('unhandledrejection', (event) => fail(event.reason && event.reason.stack || event.reason))
+  // PagedConfig.before runs while the source DOM is still intact, so the
+  // export's own transforms are applied exactly as in production; .after fires
+  // once pagination has finished, which avoids racing a timer.
+  window.PagedConfig = {
+    before: () => window.__prepare(${JSON.stringify(config)}),
+    after: () => probe(),
+  }
+
+  const probe = () => {
+    const pages = [...document.querySelectorAll('.pagedjs_page')]
+    const report = { pages: pages.length, overflowing: [], codeLines: [], emptiedElements: [] }
+
+    pages.forEach((page, index) => {
+      const content = page.querySelector('.pagedjs_page_content')
+      if (!content) return
+      const box = content.getBoundingClientRect()
+
+      page.querySelectorAll('.scripto-doc *').forEach((el) => {
+        const r = el.getBoundingClientRect()
+        if (r.width <= 0 || r.height <= 0) return
+        const by = Math.round(Math.max(r.right - box.right, box.left - r.left))
+        // Ignore sub-pixel rounding; anything more is real clipping.
+        if (by > 2) {
+          report.overflowing.push({
+            page: index + 1,
+            tag: el.tagName.toLowerCase(),
+            cls: el.className.toString().slice(0, 60),
+            by,
+          })
+        }
+      })
+
+      page.querySelectorAll('.code-line[line]').forEach((el) => {
+        const r = el.getBoundingClientRect()
+        if (r.height <= 0 || r.top < box.top - 1 || r.bottom > box.bottom + 1) return
+        report.codeLines.push({ line: Number(el.getAttribute('line')), text: el.textContent ?? '' })
+      })
+    })
+
+    // Paged.js replaces the body with its own pages, so the probe element can
+    // only be created once it is done.
+    const out = document.createElement('pre')
+    out.id = 'probe'
+    out.textContent = JSON.stringify(report)
+    document.body.appendChild(out)
+  }
+</script>
+<script>${polyfill}</script>`
+}
+
+/** Render a fixture through the full export pipeline and report the layout. */
+export async function paginate(
+  fixture: string,
+  overrides: Partial<PdfConfig> = {},
+): Promise<PageReport> {
+  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(/<pre id="probe">([\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(/&quot;/g, '"')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&#39;/g, "'")
+    .replace(/&amp;/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<ReturnType<typeof paginate>>
+
+/**
+ * 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<string, Promise<PageReport>>()
+const report = (fixture: string): Promise<PageReport> => {
+  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,
   },
 })