test(make-pdf): width-policy unit suite + landscape e2e gate with negative fixtures

24 unit tests weighted toward the false-positive guards: wide screenshot
without an alt hint stays portrait, sub-threshold and tall images stay
portrait, deterministic 1560/1561px boundary, whole-word alt matching
('photographic' must not match 'graph'), page=portrait veto beats every
heuristic, diagnostic blocks never promote. E2E gate asserts pdfinfo
per-page boxes through the compiled binary: exactly 3 of 5 fixture blocks
get landscape pages (alt-hinted image, directive-forced image, wide sequence
diagram) while the unhinted screenshot and the veto'd diagram stay portrait —
plus the --toc combo proving TOC and named-page landscape coexist.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

make-pdf/test/e2e/landscape-gate.test.ts

@@ -0,0 +1,134 @@
+/**
+ * Landscape promotion gate — proves the conservative auto-landscape policy
+ * end-to-end through the compiled binary, asserted on pdfinfo per-page boxes
+ * (the only oracle that can't lie about orientation).
+ *
+ * The fixture encodes one of each decision:
+ *   - wide screenshot, no alt hint    → MUST stay portrait (false-positive guard)
+ *   - wide image, alt "architecture diagram" → promotes
+ *   - small image with {page=landscape}      → promotes (directive force)
+ *   - wide mermaid sequence diagram          → promotes (provenance automatic)
+ *   - wide mermaid with page=portrait fence  → MUST stay portrait (veto)
+ *
+ * Also runs the --toc combo: Paged.js isn't shipped in v1 (TOC renders
+ * without page numbers, browse falls through after 3s), so named-page
+ * landscape must survive a --toc run unchanged. If Paged.js ever lands and
+ * re-paginates, this is the test that catches the interaction.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { execFileSync } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import { resolvePopplerTool } from "../../src/pdftotext";
+
+const FIXTURE = path.resolve(__dirname, "../fixtures/landscape-gate.md");
+const ROOT = path.resolve(__dirname, "../../..");
+const PDF_BIN = path.join(ROOT, "make-pdf/dist/pdf");
+const BROWSE_BIN = path.join(ROOT, "browse/dist/browse");
+const BUNDLE = path.join(ROOT, "lib/diagram-render/dist/diagram-render.html");
+
+const CHILD_TIMEOUT_MS = 60_000;
+
+function prerequisitesAvailable(): { ok: true } | { ok: false; reason: string } {
+  if (!fs.existsSync(PDF_BIN)) return { ok: false, reason: `make-pdf binary missing (${PDF_BIN}). Run bun run build.` };
+  if (!fs.existsSync(BROWSE_BIN)) return { ok: false, reason: `browse binary missing (${BROWSE_BIN}).` };
+  if (!fs.existsSync(BUNDLE)) return { ok: false, reason: `diagram-render bundle missing (${BUNDLE}).` };
+  if (!fs.existsSync(FIXTURE)) return { ok: false, reason: `fixture missing (${FIXTURE}).` };
+  if (!resolvePopplerTool("pdfinfo")) return { ok: false, reason: "pdfinfo not found (install poppler-utils)." };
+  if (!resolvePopplerTool("pdftotext")) return { ok: false, reason: "pdftotext not found (install poppler-utils)." };
+  return { ok: true };
+}
+
+interface PageBox {
+  page: number;
+  width: number;
+  height: number;
+}
+
+function pageBoxes(pdfPath: string): PageBox[] {
+  const pdfinfo = resolvePopplerTool("pdfinfo")!;
+  const out = execFileSync(pdfinfo, ["-f", "1", "-l", "99", pdfPath], {
+    encoding: "utf8",
+    timeout: CHILD_TIMEOUT_MS,
+  });
+  const boxes: PageBox[] = [];
+  for (const m of out.matchAll(/Page\s+(\d+)\s+size:\s+([0-9.]+)\s+x\s+([0-9.]+)\s+pts/g)) {
+    boxes.push({ page: Number(m[1]), width: parseFloat(m[2]), height: parseFloat(m[3]) });
+  }
+  if (boxes.length === 0) throw new Error(`pdfinfo reported no page sizes:\n${out}`);
+  return boxes;
+}
+
+const isLandscape = (b: PageBox) => b.width > b.height;
+
+function generate(args: string[], outputPdf: string): void {
+  execFileSync(PDF_BIN, ["generate", FIXTURE, outputPdf, "--quiet", ...args], {
+    encoding: "utf8",
+    env: { ...process.env, BROWSE_BIN },
+    stdio: ["ignore", "pipe", "pipe"],
+    timeout: CHILD_TIMEOUT_MS,
+  });
+}
+
+describe("landscape promotion gate", () => {
+  const avail = prerequisitesAvailable();
+
+  test.skipIf(!avail.ok)("exactly the promoted blocks get landscape pages", () => {
+    if (!avail.ok) return;
+    const workDir = fs.mkdtempSync("/tmp/make-pdf-landscape-gate-");
+    const outputPdf = path.join(workDir, "out.pdf");
+    try {
+      generate([], outputPdf);
+      const boxes = pageBoxes(outputPdf);
+      const landscape = boxes.filter(isLandscape);
+      const portrait = boxes.filter((b) => !isLandscape(b));
+
+      // Three promotions: alt-hinted image, directive-forced image, wide diagram.
+      expect(landscape.length).toBe(3);
+      // First page (intro + screenshot) and the veto'd diagram stay portrait.
+      expect(portrait.length).toBeGreaterThanOrEqual(2);
+      expect(isLandscape(boxes[0])).toBe(false);
+
+      // The veto'd diagram rendered (its labels exist) on a PORTRAIT page.
+      const pdftotext = resolvePopplerTool("pdftotext")!;
+      const lastPortrait = portrait[portrait.length - 1];
+      const vetoText = execFileSync(
+        pdftotext,
+        ["-f", String(lastPortrait.page), "-l", String(lastPortrait.page), outputPdf, "-"],
+        { encoding: "utf8", timeout: CHILD_TIMEOUT_MS },
+      );
+      expect(vetoText).toContain("vetoalpha");
+    } finally {
+      try { fs.rmSync(workDir, { recursive: true, force: true }); } catch { /* ignore */ }
+    }
+  }, 120000);
+
+  test.skipIf(!avail.ok)("--toc combo: TOC renders and landscape promotion survives", () => {
+    if (!avail.ok) return;
+    const workDir = fs.mkdtempSync("/tmp/make-pdf-landscape-toc-");
+    const outputPdf = path.join(workDir, "out.pdf");
+    try {
+      generate(["--toc"], outputPdf);
+      const boxes = pageBoxes(outputPdf);
+      expect(boxes.filter(isLandscape).length).toBe(3);
+
+      const pdftotext = resolvePopplerTool("pdftotext")!;
+      const text = execFileSync(pdftotext, [outputPdf, "-"], { encoding: "utf8", timeout: CHILD_TIMEOUT_MS });
+      // TOC heading extracts uppercase (small-caps styling).
+      expect(text.toUpperCase()).toContain("CONTENTS");
+    } finally {
+      try { fs.rmSync(workDir, { recursive: true, force: true }); } catch { /* ignore */ }
+    }
+  }, 120000);
+
+  if (!avail.ok) {
+    test("landscape gate prerequisites are present (hard-required in CI)", () => {
+      if (process.env.CI) {
+        throw new Error(`landscape gate prerequisites missing in CI: ${avail.reason}`);
+      }
+      console.warn(`[skip] ${avail.reason}`);
+    });
+  }
+});

make-pdf/test/fixtures/landscape-gate.md

@@ -0,0 +1,52 @@
+# Landscape Gate
+
+Intro text under the first heading.
+
+## Negative: screenshot stays portrait
+
+![just a screenshot of the app](./diagram-assets/wide-screenshot.png)
+
+## Positive: alt-hinted wide image promotes
+
+![architecture diagram of the system](./diagram-assets/wide-arch.png)
+
+## Positive: directive forces a small image
+
+![small forced](./diagram-assets/red-box.png){page=landscape}
+
+## Positive: wide diagram auto-promotes
+
+```mermaid title="Wide sequence"
+sequenceDiagram
+  participant A as seqalpha
+  participant B as seqbeta
+  participant C as seqgamma
+  participant D as seqdelta
+  participant E as seqepsilon
+  participant F as seqzeta
+  participant G as seqeta
+  participant H as seqtheta
+  participant I as seqiota
+  participant J as seqkappa
+  A->>J: long hop
+  B->>I: cross
+```
+
+## Negative: directive vetoes a wide diagram
+
+```mermaid page=portrait
+sequenceDiagram
+  participant A as vetoalpha
+  participant B as vetobeta
+  participant C as vetogamma
+  participant D as vetodelta
+  participant E as vetoepsilon
+  participant F as vetozeta
+  participant G as vetoeta
+  participant H as vetotheta
+  participant I as vetoiota
+  participant J as vetokappa
+  A->>J: long hop
+```
+
+Closing text.

make-pdf/test/image-policy.test.ts

@@ -0,0 +1,190 @@
+/**
+ * Unit tests for the image width policy + conservative auto-landscape
+ * (image-policy.ts). Pure HTML-in/HTML-out — no browse daemon.
+ *
+ * The promotion heuristic is deliberately conservative (eng-review P4):
+ * false negatives are cheap (add {page=landscape}), false positives feel
+ * broken. The negative cases here are the load-bearing ones.
+ */
+import { describe, expect, test } from "bun:test";
+
+import {
+  applyImageDirectives,
+  applyImagePolicy,
+  parseDirectives,
+} from "../src/image-policy";
+
+const silent = { warn: () => {} };
+
+// 6.5in content box → threshold = 6.5 × 96 × 2.5 = 1560 CSS px.
+const OPTS = { contentWidthIn: 6.5, ...silent };
+
+function img(attrs: string): string {
+  return `<p><img ${attrs}></p>`;
+}
+
+// ─── directive parsing ────────────────────────────────────────────────
+
+describe("parseDirectives", () => {
+  test("width grammar", () => {
+    expect(parseDirectives("width=full")).toEqual({ width: "full", page: undefined });
+    expect(parseDirectives("width=50%")).toEqual({ width: "50%", page: undefined });
+    expect(parseDirectives("width=3in")).toEqual({ width: "3in", page: undefined });
+    expect(parseDirectives("width=2.5cm")).toEqual({ width: "2.5cm", page: undefined });
+  });
+  test("page grammar + combination", () => {
+    expect(parseDirectives("page=landscape")).toEqual({ width: undefined, page: "landscape" });
+    expect(parseDirectives("width=full page=portrait")).toEqual({ width: "full", page: "portrait" });
+  });
+  test("unknown tokens reject the whole group (stays visible text)", () => {
+    expect(parseDirectives("widht=full")).toBeNull();
+    expect(parseDirectives("width=full caption=x")).toBeNull();
+  });
+  test("malformed values reject", () => {
+    expect(parseDirectives("width=banana")).toBeNull();
+    expect(parseDirectives("page=sideways")).toBeNull();
+  });
+});
+
+describe("applyImageDirectives", () => {
+  test("brace suffix becomes data attrs and is consumed", () => {
+    const out = applyImageDirectives(`<p><img src="x.png" alt="a">{width=50%}</p>`);
+    expect(out).toContain('data-gstack-width="50%"');
+    expect(out).not.toContain("{width=50%}");
+  });
+  test("unrecognized brace group is left as literal text", () => {
+    const html = `<p><img src="x.png">{not a directive}</p>`;
+    expect(applyImageDirectives(html)).toBe(html);
+  });
+  test("non-adjacent braces untouched", () => {
+    const html = `<p>set {width=full} in config</p>`;
+    expect(applyImageDirectives(html)).toBe(html);
+  });
+});
+
+// ─── width policy ─────────────────────────────────────────────────────
+
+describe("width styles", () => {
+  test("width=full → inline 100% style", () => {
+    const { html } = applyImagePolicy(img(`src="x" data-gstack-width="full"`), OPTS);
+    expect(html).toContain("width: 100%");
+  });
+  test("explicit dimension passes through", () => {
+    const { html } = applyImagePolicy(img(`src="x" data-gstack-width="3in"`), OPTS);
+    expect(html).toContain("width: 3in");
+  });
+  test("no directive → no inline style (CSS max-width owns the default)", () => {
+    const { html } = applyImagePolicy(img(`src="x" data-gstack-px-width="40" data-gstack-px-height="20"`), OPTS);
+    expect(html).not.toContain("style=");
+  });
+});
+
+// ─── landscape promotion ──────────────────────────────────────────────
+
+describe("auto-landscape: negative cases (the load-bearing ones)", () => {
+  test("wide screenshot with no alt hint stays portrait", () => {
+    const r = applyImagePolicy(
+      img(`src="x" alt="screenshot of the app" data-gstack-px-width="3000" data-gstack-px-height="900"`),
+      OPTS,
+    );
+    expect(r.hasLandscape).toBe(false);
+    expect(r.html).not.toContain("page-wide");
+  });
+  test("wide banner with hint but below width threshold stays portrait", () => {
+    const r = applyImagePolicy(
+      img(`src="x" alt="chart" data-gstack-px-width="1200" data-gstack-px-height="400"`),
+      OPTS,
+    );
+    expect(r.hasLandscape).toBe(false);
+  });
+  test("tall diagram (aspect below 1.8) stays portrait", () => {
+    const r = applyImagePolicy(
+      img(`src="x" alt="architecture diagram" data-gstack-px-width="2000" data-gstack-px-height="1500"`),
+      OPTS,
+    );
+    expect(r.hasLandscape).toBe(false);
+  });
+  test("no intrinsic dimensions stays portrait", () => {
+    const r = applyImagePolicy(img(`src="x" alt="diagram"`), OPTS);
+    expect(r.hasLandscape).toBe(false);
+  });
+  test("page=portrait vetoes everything", () => {
+    const r = applyImagePolicy(
+      img(`src="x" alt="diagram" data-gstack-page="portrait" data-gstack-px-width="4000" data-gstack-px-height="1000"`),
+      OPTS,
+    );
+    expect(r.hasLandscape).toBe(false);
+  });
+  test("threshold boundary is deterministic: exactly at threshold stays portrait", () => {
+    // threshold = 6.5 × 96 × 2.5 = 1560
+    const r = applyImagePolicy(
+      img(`src="x" alt="diagram" data-gstack-px-width="1560" data-gstack-px-height="600"`),
+      OPTS,
+    );
+    expect(r.hasLandscape).toBe(false);
+    const r2 = applyImagePolicy(
+      img(`src="x" alt="diagram" data-gstack-px-width="1561" data-gstack-px-height="600"`),
+      OPTS,
+    );
+    expect(r2.hasLandscape).toBe(true);
+  });
+});
+
+describe("auto-landscape: positive cases", () => {
+  test("wide + alt hint + over threshold promotes and wraps", () => {
+    const warnings: string[] = [];
+    const r = applyImagePolicy(
+      img(`src="x" alt="architecture diagram" data-gstack-px-width="2400" data-gstack-px-height="1000"`),
+      { contentWidthIn: 6.5, warn: (m) => warnings.push(m) },
+    );
+    expect(r.hasLandscape).toBe(true);
+    expect(r.html).toContain('<div class="page-wide"><img');
+    expect(r.html).not.toContain("<p><img");
+    expect(warnings[0]).toContain("landscape");
+  });
+  test("page=landscape forces promotion regardless of size", () => {
+    const r = applyImagePolicy(img(`src="x" data-gstack-page="landscape"`), OPTS);
+    expect(r.hasLandscape).toBe(true);
+  });
+  test("alt hint matches whole words only", () => {
+    const r = applyImagePolicy(
+      img(`src="x" alt="photographic" data-gstack-px-width="2400" data-gstack-px-height="1000"`),
+      OPTS,
+    );
+    expect(r.hasLandscape).toBe(false); // "graph" inside "photographic" must not match
+  });
+});
+
+describe("auto-landscape: diagram figures", () => {
+  const fig = (svgAttrs: string, figAttrs = "") =>
+    `<figure class="diagram" role="img" aria-label="d"${figAttrs}>\n<svg ${svgAttrs}><g/></svg>\n</figure>`;
+
+  test("wide diagram via viewBox promotes (provenance automatic, no alt needed)", () => {
+    const r = applyImagePolicy(fig(`width="100%" viewBox="0 0 2050 600"`), OPTS);
+    expect(r.hasLandscape).toBe(true);
+    expect(r.html).toContain('<div class="page-wide"><figure');
+  });
+  test("normal flowchart stays portrait", () => {
+    const r = applyImagePolicy(fig(`width="100%" viewBox="0 0 800 400"`), OPTS);
+    expect(r.hasLandscape).toBe(false);
+  });
+  test("fence page=portrait vetoes a wide diagram", () => {
+    const r = applyImagePolicy(
+      fig(`width="100%" viewBox="0 0 3000 600"`, ` data-gstack-page="portrait"`),
+      OPTS,
+    );
+    expect(r.hasLandscape).toBe(false);
+  });
+  test("fence page=landscape forces a small diagram", () => {
+    const r = applyImagePolicy(
+      fig(`width="100%" viewBox="0 0 400 300"`, ` data-gstack-page="landscape"`),
+      OPTS,
+    );
+    expect(r.hasLandscape).toBe(true);
+  });
+  test("diagnostic blocks are never promoted", () => {
+    const html = `<figure class="diagram diagram-error" role="img" aria-label="x"><svg viewBox="0 0 4000 600"></svg></figure>`;
+    const r = applyImagePolicy(html, OPTS);
+    expect(r.hasLandscape).toBe(false);
+  });
+});