@amg555/frameforge-mcp 2.7.6 → 2.7.8

package/.agent/skills/gstack-make-pdf/src/setup.ts

@@ -1,113 +0,0 @@
-/**
- * `$P setup` — guided smoke test.
- *
- * Flow:
- *   1. Find a browser: Aside (primary) or gstack's own headless browser (fallback)
- *   2. Render a tiny HTML page through it
- *   3. Verify pdftotext is installed (warn, don't fail)
- *   4. Generate a smoke-test PDF from an inline 2-paragraph fixture
- *   5. Print a 3-command cheatsheet
- */
-
-import * as path from "node:path";
-import * as fs from "node:fs";
-
-import { NO_BROWSER_HELP, pickEngine, render, renderTmpDir } from "../../lib/aside-render";
-import { ExitCode } from "./types";
-import { resolvePdftotext, PdftotextUnavailableError } from "./pdftotext";
-import { OUTPUT_TMP_DIR, generate } from "./orchestrator";
-
-export async function runSetup(): Promise<void> {
-  process.stderr.write("make-pdf setup — verifying install\n\n");
-
-  // 1. A browser: Aside when it answers, else gstack's own
-  process.stderr.write("  [1/5] Checking for a browser...");
-  const engine = pickEngine();
-  if (!engine.engine) {
-    process.stderr.write(" FAIL\n");
-    process.stderr.write(`\n${engine.error}\n`);
-    process.exit(ExitCode.BrowserUnavailable);
-  }
-  const via = engine.engine === "aside" ? `Aside ${engine.version}` : "gstack browser";
-  process.stderr.write(engine.engine === "aside"
-    ? ` Aside OK (${engine.version})\n`
-    : ` gstack browser OK (fallback: ${engine.bin}; Aside is not running)\n`);
-
-  // 2. Render smoke: open a tiny page and read it back
-  process.stderr.write(`  [2/5] Rendering through ${via}...`);
-  const smokeDir = fs.mkdtempSync(path.join(renderTmpDir(), "make-pdf-setup-"));
-  try {
-    const file = path.join(smokeDir, "smoke.html");
-    fs.writeFileSync(file, "<!doctype html><title>make-pdf smoke</title><p id=t>browser-ok</p>", "utf8");
-    const r = await render({ file, steps: [{ kind: "eval", expression: "document.getElementById('t').textContent" }] });
-    if (!r.ok || r.evals[0] !== "browser-ok") {
-      throw new Error(r.error ?? `unexpected page text: ${r.evals[0]}`);
-    }
-    process.stderr.write(" OK\n");
-  } catch (err: any) {
-    process.stderr.write(" FAIL\n");
-    process.stderr.write(`\n${via} could not render a page: ${err.message}\n`);
-    process.stderr.write(`To fix: ${NO_BROWSER_HELP}\n`);
-    process.exit(ExitCode.BrowserUnavailable);
-  } finally {
-    fs.rmSync(smokeDir, { recursive: true, force: true });
-  }
-
-  // 3. pdftotext (optional — CI gate only)
-  process.stderr.write("  [3/5] Checking pdftotext (optional)...");
-  try {
-    const info = resolvePdftotext();
-    process.stderr.write(` OK (${info.flavor}, ${info.version.split(" ").slice(-1)[0] || "version unknown"})\n`);
-  } catch (err) {
-    process.stderr.write(" SKIP\n");
-    if (err instanceof PdftotextUnavailableError) {
-      process.stderr.write(
-        "    pdftotext not installed. This is optional — only the CI\n" +
-        "    copy-paste gate needs it. To enable:\n" +
-        "      macOS:  brew install poppler\n" +
-        "      Ubuntu: sudo apt-get install poppler-utils\n",
-      );
-    }
-  }
-
-  // 4. Render smoke-test PDF
-  process.stderr.write("  [4/5] Generating smoke-test PDF...\n");
-  const fixture = [
-    "# Hello from make-pdf",
-    "",
-    "This is a two-paragraph smoke test. If you can read this sentence in the PDF that just opened, the pipeline works end-to-end.",
-    "",
-    "The second paragraph contains curly quotes (\"hello\"), an em dash -- like this, and an ellipsis... all of which should render correctly.",
-    "",
-  ].join("\n");
-  const fixturePath = path.join(OUTPUT_TMP_DIR, `make-pdf-smoke-${process.pid}.md`);
-  const outPath = path.join(OUTPUT_TMP_DIR, `make-pdf-smoke-${process.pid}.pdf`);
-  fs.writeFileSync(fixturePath, fixture, "utf8");
-
-  try {
-    await generate({
-      input: fixturePath,
-      output: outPath,
-      quiet: true,
-      pageNumbers: true,
-    });
-    process.stderr.write(`        PASSED. Smoke test saved to ${outPath}\n`);
-  } catch (err: any) {
-    process.stderr.write(`        FAILED: ${err.message}\n`);
-    process.exit(2);
-  } finally {
-    try { fs.unlinkSync(fixturePath); } catch { /* ignore */ }
-  }
-
-  // 5. Cheatsheet
-  process.stderr.write("  [5/5] All checks passed.\n\n");
-  process.stderr.write([
-    "make-pdf is ready. Try:",
-    "  $P generate letter.md                  # default memo mode",
-    "  $P generate --cover --toc essay.md     # full publication",
-    "  $P generate --watermark DRAFT memo.md  # diagonal watermark",
-    "",
-    `Smoke-test PDF: ${outPath}`,
-    "",
-  ].join("\n"));
-}

package/.agent/skills/gstack-make-pdf/src/smartypants.ts

@@ -1,105 +0,0 @@
-/**
- * Inline typographic transform (smartypants).
- *
- * Converts ASCII typography to real Unicode:
- *   "quoted"     → "quoted"    (U+201C/U+201D)
- *   'quoted'     → 'quoted'    (U+2018/U+2019)
- *   don't        → don't       (apostrophe: U+2019)
- *   --           → —           (em dash U+2014)
- *   ...          → …           (ellipsis U+2026)
- *
- * Critical: must NOT touch code, URLs, or HTML attributes. The Codex round
- * 2 review flagged this specifically — smartypants run over a fenced code
- * block corrupts the code and tokens inside tag attributes can break
- * parsing.
- *
- * This operates on HTML (marked already produced it) and walks text nodes
- * only via a lightweight regex that recognizes code/pre/URL zones and
- * skips them entirely.
- */
-
-const CODE_ZONE_RE = /<(pre|code|script|style)\b[^>]*>[\s\S]*?<\/\1>/gi;
-const TAG_RE = /<[^>]+>/g;
-// \u0000 is the placeholder sentinel (see PLACEHOLDER below). It must be
-// excluded here: URLs are carved AFTER tags, so a URL sitting flush against
-// a tag (`<a href="...">https://ex.com</a>`) would otherwise let \S+ swallow
-// the placeholder standing in for `</a>` — that placeholder then never
-// restores (restore is a single pass) and the tag is lost.
-const URL_RE = /\bhttps?:\/\/[^\s\u0000]+/g;
-
-/**
- * Apply smartypants to an HTML string. Zones that should not be touched:
- *   - <pre>, <code>, <script>, <style> blocks (content unchanged)
- *   - HTML tags themselves (attributes unchanged)
- *   - URLs (http:// and https:// spans unchanged)
- */
-export function smartypants(html: string): string {
-  // Step 1: split into preserved + transformed zones.
-  // Preserved zones: code/pre/script/style, tags, URLs.
-  // We carve them out with placeholder tokens, transform the rest, and
-  // splice them back.
-  const preserved: string[] = [];
-  const PLACEHOLDER = (i: number) => `\u0000SMARTPANTS_PRESERVED_${i}\u0000`;
-
-  const carve = (source: string, pattern: RegExp): string => {
-    return source.replace(pattern, (match) => {
-      const idx = preserved.length;
-      preserved.push(match);
-      return PLACEHOLDER(idx);
-    });
-  };
-
-  let s = html.replace(/\u0000/g, "");  // drop stray input NUL (can't forge a placeholder)
-  s = carve(s, CODE_ZONE_RE);
-  s = carve(s, TAG_RE);
-  s = carve(s, URL_RE);
-
-  s = transformText(s);
-
-  // Step 2: restore preserved zones.
-  // Use a function to avoid $-substitution gotchas.
-  s = s.replace(/\u0000SMARTPANTS_PRESERVED_(\d+)\u0000/g, (_, idx) => {
-    return preserved[parseInt(idx, 10)] ?? "";
-  });
-
-  return s;
-}
-
-/**
- * Transform plain text (no HTML, no code, no URLs).
- *
- * Order matters:
- *   1. Triple dots first (so they don't collide with later apostrophes)
- *   2. Em dashes (two hyphens → em dash)
- *   3. Apostrophes (contractions + possessives)
- *   4. Double quotes (open/close pairing)
- *   5. Single quotes (open/close pairing — after apostrophes)
- */
-function transformText(text: string): string {
-  let s = text;
-
-  // Ellipsis: three literal dots (with optional spaces) → …
-  s = s.replace(/\.\s?\.\s?\./g, "\u2026");
-
-  // Em dash: -- → —. Require space or word-char boundary on both sides so
-  // we don't mangle ARGV-style flags in prose like `--verbose`.
-  s = s.replace(/(\w|\s)--(\w|\s)/g, "$1\u2014$2");
-  // Standalone --  at start/end
-  s = s.replace(/^--\s/gm, "\u2014 ");
-  s = s.replace(/\s--$/gm, " \u2014");
-
-  // Apostrophes in contractions and possessives.
-  // "don't", "it's", "they're", "Garry's"
-  s = s.replace(/(\w)'(\w)/g, "$1\u2019$2");
-
-  // Double quotes: open if preceded by whitespace/bol, close if preceded
-  // by word char or punctuation.
-  s = s.replace(/(^|[\s\(\[\{\-\uff1a\uff08\u3010\u300c\u300e\u3008\u300a])"/g, "$1\u201c");     // opening "
-  s = s.replace(/"/g, "\u201d");                         // remaining " are closing
-
-  // Single quotes (after apostrophe pass):
-  s = s.replace(/(^|[\s\(\[\{\-\uff1a\uff08\u3010\u300c\u300e\u3008\u300a])'/g, "$1\u2018");      // opening '
-  s = s.replace(/'/g, "\u2019");                         // remaining ' are closing
-
-  return s;
-}

package/.agent/skills/gstack-make-pdf/src/toc-pages.ts

@@ -1,197 +0,0 @@
-/**
- * TOC page numbers, offline: print, read where each heading landed from the
- * printed PDF itself, write those numbers into the TOC, and print again until
- * the numbers the PDF shows are the numbers its own layout produced.
- *
- * Why this strategy (#2903): Chromium's print engine has no CSS
- * `target-counter()`, and a pagination polyfill (Paged.js) would mean running
- * a third-party script inside the user's browser profile on untrusted
- * markdown and re-implementing the layout Chromium already does. Instead the
- * oracle is the PDF: the TOC links make Chromium (Skia) write one named
- * destination per target heading — `/Dests << /toc-0 [<page ref> /XYZ …] >>`
- * in the catalog — and the page tree gives each page ref its 1-based number,
- * the same physical number the `counter(page)` footer prints.
- *
- * No script is injected and nothing is fetched, so the offline/sanitization
- * boundary is unchanged. Every failure is explicit (TocPaginationError →
- * exit 3): a PDF this parser cannot read, a TOC target with no destination,
- * or numbers that have not settled after MAX_PRINTS. A TOC with empty
- * page-number cells is never written.
- */
-
-import * as fs from "node:fs";
-import * as path from "node:path";
-
-/** Prints needed is normally 2 (measure, then confirm); the third absorbs one reflow. */
-export const MAX_PRINTS = 3;
-
-export class TocPaginationError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = "TocPaginationError";
-  }
-}
-
-const TOC_SECTION = /<section class="toc">[\s\S]*?<\/section>/;
-const TOC_PAGE_SPAN = /(<span class="toc-page" data-toc-target=")([^"]*)(">)[^<]*(<\/span>)/g;
-
-function decodeAttr(s: string): string {
-  return s
-    .replace(/&lt;/g, "<")
-    .replace(/&gt;/g, ">")
-    .replace(/&quot;/g, '"')
-    .replace(/&#39;/g, "'")
-    .replace(/&amp;/g, "&");
-}
-
-/**
- * The key a TOC target and its PDF destination share. Chromium names a
- * destination after the link's URL fragment, percent-encoded (`#café` →
- * `/caf#25C3#25A9`), so both sides compare percent-decoded.
- */
-function destKey(id: string): string {
-  try {
-    return decodeURIComponent(id);
-  } catch {
-    return id;
-  }
-}
-
-/** TOC target keys, in TOC order. Empty when the document has no TOC. */
-export function tocTargets(html: string): string[] {
-  const toc = html.match(TOC_SECTION)?.[0] ?? "";
-  return [...toc.matchAll(TOC_PAGE_SPAN)].map((m) => destKey(decodeAttr(m[2])));
-}
-
-/** Write each target's page from `pages` (keyed by tocTargets keys; 0 when unknown) into its TOC cell. */
-export function fillTocPages(html: string, pages: ReadonlyMap<string, number>): string {
-  return html.replace(TOC_SECTION, (toc) =>
-    toc.replace(TOC_PAGE_SPAN, (_m, open: string, target: string, close: string, end: string) =>
-      `${open}${target}${close}${pages.get(destKey(decodeAttr(target))) ?? 0}${end}`));
-}
-
-// ─── PDF reading (classic xref, as Chromium/Skia writes it) ───────────────
-
-/** PDF name token (after the slash) → string: `#xx` escapes are UTF-8 bytes. */
-function decodePdfName(raw: string): string {
-  const bytes: number[] = [];
-  for (let i = 0; i < raw.length; i++) {
-    if (raw[i] === "#" && /^[0-9a-fA-F]{2}$/.test(raw.slice(i + 1, i + 3))) {
-      bytes.push(parseInt(raw.slice(i + 1, i + 3), 16));
-      i += 2;
-    } else {
-      bytes.push(raw.charCodeAt(i) & 0xff);
-    }
-  }
-  return Buffer.from(bytes).toString("utf8");
-}
-
-/**
- * Named destination (as a tocTargets key) → 1-based page number, read from a PDF's catalog /Dests
- * dictionary and page tree. Throws TocPaginationError when the file is not a
- * PDF this reader understands (cross-reference streams, a /Dests name tree).
- */
-export function pdfDestinationPages(pdf: Uint8Array): Map<string, number> {
-  const fail = (why: string): never => {
-    throw new TocPaginationError(`could not read TOC page numbers from the printed PDF: ${why}`);
-  };
-  const s = Buffer.from(pdf).toString("latin1");
-  const startxref = s.match(/startxref\s+(\d+)\s+%%EOF\s*$/);
-  if (!startxref) return fail("no startxref trailer");
-  const xrefAt = Number(startxref[1]);
-  if (!s.startsWith("xref", xrefAt)) return fail("cross-reference streams are not supported");
-
-  const offsets = new Map<number, number>();
-  const trailerAt = s.indexOf("trailer", xrefAt);
-  if (trailerAt < 0) return fail("no trailer dictionary");
-  const table = s.slice(xrefAt + 4, trailerAt).trim().split(/\r?\n|\r/);
-  for (let i = 0; i < table.length;) {
-    const [first, count] = table[i].trim().split(/\s+/).map(Number);
-    for (let k = 0; k < count; k++) {
-      const [off, , kind] = (table[i + 1 + k] ?? "").trim().split(/\s+/);
-      if (kind === "n") offsets.set(first + k, Number(off));
-    }
-    i += 1 + count;
-  }
-
-  const object = (num: number): string => {
-    const at = offsets.get(num);
-    if (at === undefined) return fail(`object ${num} is not in the cross-reference table`);
-    const end = s.indexOf("endobj", at);
-    return s.slice(at, end < 0 ? undefined : end);
-  };
-  const ref = (body: string, key: string): number | null => {
-    const m = body.match(new RegExp(`/${key}\\s+(\\d+)\\s+\\d+\\s+R`));
-    return m ? Number(m[1]) : null;
-  };
-
-  const root = ref(s.slice(trailerAt), "Root") ?? fail("trailer has no /Root");
-  const catalog = object(root);
-  const pagesRoot = ref(catalog, "Pages") ?? fail("catalog has no /Pages");
-
-  const pageNumber = new Map<number, number>();
-  const walk = (num: number, depth: number): void => {
-    if (depth > 32) fail("page tree is too deep");
-    const node = object(num);
-    const kids = node.match(/\/Kids\s*\[([^\]]*)\]/);
-    if (/\/Type\s*\/Pages\b/.test(node) && kids) {
-      for (const k of kids[1].matchAll(/(\d+)\s+\d+\s+R/g)) walk(Number(k[1]), depth + 1);
-    } else {
-      pageNumber.set(num, pageNumber.size + 1);
-    }
-  };
-  walk(pagesRoot, 0);
-
-  const pages = new Map<string, number>();
-  const destsRef = ref(catalog, "Dests");
-  if (destsRef === null) {
-    if (/\/Names\s*<<[^>]*\/Dests/.test(catalog)) fail("named destinations in a /Names tree are not supported");
-    return pages;
-  }
-  for (const m of object(destsRef).matchAll(/\/([^\s()<>[\]{}/%]+)\s*\[\s*(\d+)\s+\d+\s+R/g)) {
-    const page = pageNumber.get(Number(m[2]));
-    if (page !== undefined) pages.set(destKey(decodePdfName(m[1])), page);
-  }
-  return pages;
-}
-
-// ─── Print loop ───────────────────────────────────────────────────────────
-
-/**
- * Print `html` to `output` with every TOC page cell holding the page its
- * heading prints on. `print(html, out)` prints one PDF (one browser render).
- * Returns print's result from the accepted pass.
- */
-export async function printWithTocPages<R>(
-  html: string,
-  output: string,
-  print: (html: string, out: string) => Promise<R>,
-): Promise<R> {
-  const targets = tocTargets(html);
-  if (targets.length === 0) return print(html, output);
-
-  const tmp = path.join(path.dirname(output), `.${path.basename(output)}.toc-pass.pdf`);
-  let pages: ReadonlyMap<string, number> = new Map();
-  try {
-    for (let pass = 1; pass <= MAX_PRINTS; pass++) {
-      const result = await print(fillTocPages(html, pages), tmp);
-      const printed = pdfDestinationPages(fs.readFileSync(tmp));
-      const missing = targets.filter((t) => !printed.has(t));
-      if (missing.length > 0) {
-        throw new TocPaginationError(
-          `the printed PDF has no destination for TOC target(s) ${missing.map((t) => `#${t}`).join(", ")}; ` +
-          `their links and page numbers would be wrong`);
-      }
-      if (targets.every((t) => pages.get(t) === printed.get(t))) {
-        fs.renameSync(tmp, output);
-        return result;
-      }
-      pages = printed;
-    }
-    throw new TocPaginationError(
-      `TOC page numbers did not settle after ${MAX_PRINTS} prints (adding them reflowed the document); ` +
-      `drop --toc or shorten the longest TOC entries`);
-  } finally {
-    fs.rmSync(tmp, { force: true });
-  }
-}

package/.agent/skills/gstack-make-pdf/src/types.ts

@@ -1,109 +0,0 @@
-/**
- * make-pdf — shared types.
- *
- * No runtime code. Imports are safe from any module.
- */
-
-export type PageSize = "letter" | "a4" | "legal" | "tabloid";
-export type FontMode = "sans"; // v1: Helvetica only. Future: "serif" | "custom".
-
-/**
- * Options for `$P generate` — the public CLI contract.
- * Matches the flag set documented in the CEO plan.
- */
-export type OutputFormat = "pdf" | "html" | "docx";
-
-export interface GenerateOptions {
-  input: string;                  // markdown input path
-  output?: string;                // output path (default: /tmp/<slug>.<ext>)
-
-  // Output format (NOT --format, which is a --page-size alias):
-  //   pdf  — print-quality PDF through the browser: Aside, else gstack's own (default)
-  //   html — single self-contained file, zero network references
-  //   docx — content-fidelity Word document (diagrams embedded as PNG)
-  to?: OutputFormat;
-
-  // Page layout
-  margins?: string;               // "1in" | "72pt" | "25mm" | "2.54cm"
-  marginTop?: string;
-  marginRight?: string;
-  marginBottom?: string;
-  marginLeft?: string;
-  pageSize?: PageSize;            // default "letter"
-
-  // Document structure
-  cover?: boolean;
-  toc?: boolean;
-  noChapterBreaks?: boolean;      // default: chapter breaks ON
-
-  // Branding
-  watermark?: string;             // e.g. "DRAFT"
-  headerTemplate?: string;        // raw HTML
-  footerTemplate?: string;        // raw HTML, mutex with pageNumbers
-  confidential?: boolean;         // default: true
-
-  // Output control
-  pageNumbers?: boolean;          // default: true
-  tagged?: boolean;               // default: true (accessible PDF)
-  outline?: boolean;              // default: true (PDF bookmarks)
-  quiet?: boolean;                // suppress progress on stderr
-  verbose?: boolean;              // per-stage timings on stderr
-
-  // Network
-  allowNetwork?: boolean;         // default: false
-
-  // Strict mode (eng-review D6.1): missing/remote images hard-fail instead of
-  // warn + placeholder. For CI docs pipelines that need determinism.
-  strict?: boolean;               // default: false
-
-  // Metadata
-  title?: string;
-  author?: string;
-  date?: string;                  // ISO-ish; default: today
-}
-
-/**
- * Options for `$P preview`.
- */
-export interface PreviewOptions {
-  input: string;
-  quiet?: boolean;
-  verbose?: boolean;
-  // Same render flags as generate so preview matches output
-  cover?: boolean;
-  toc?: boolean;
-  watermark?: string;
-  noChapterBreaks?: boolean;
-  confidential?: boolean;
-  pageNumbers?: boolean;
-  allowNetwork?: boolean;
-  title?: string;
-  author?: string;
-  date?: string;
-}
-
-/**
- * Exit codes for $P generate.
- * Mirror these in orchestrator error paths.
- */
-export const ExitCode = {
-  Success: 0,
-  BadArgs: 1,
-  RenderError: 2,
-  TocPagination: 3,
-  BrowserUnavailable: 4,
-} as const;
-export type ExitCode = typeof ExitCode[keyof typeof ExitCode];
-
-/**
- * No browser at all: Aside is not installed or not open AND gstack's own
- * headless browser is not built (exit 4). The message (lib/aside-render's
- * NO_BROWSER text) names both remedies. A render that fails while a browser
- * IS available is a plain Error (exit 2).
- */
-export class BrowserUnavailableError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = "BrowserUnavailableError";
-  }
-}

package/.agent/skills/gstack-make-pdf/test/asideClient.test.ts

@@ -1,153 +0,0 @@
-/**
- * asideClient unit tests — PdfOptions → CDP Page.printToPDF mapping, the
- * staging/failure shape of renderPdf (render function injected), and the
- * no-browser classification (BrowserUnavailableError, exit 4). No live
- * browser needed.
- */
-
-import { describe, expect, test } from "bun:test";
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-
-import { pdfStepOptions, renderFailure, renderPdf } from "../src/asideClient";
-import { BrowserUnavailableError, ExitCode } from "../src/types";
-import { NO_BROWSER, NO_BROWSER_HELP, type RenderResult, type RenderSpec } from "../../lib/aside-render";
-
-describe("pdfStepOptions", () => {
-  test("defaults: Letter paper, zero margins, no header/footer, nothing else set", () => {
-    const o = pdfStepOptions({ output: "/tmp/x.pdf" });
-    expect(o.paperWidth).toBe(8.5);
-    expect(o.paperHeight).toBe(11);
-    expect([o.marginTop, o.marginRight, o.marginBottom, o.marginLeft]).toEqual([0, 0, 0, 0]);
-    expect(o.displayHeaderFooter).toBeUndefined();
-    expect(o.generateTaggedPDF).toBeUndefined();
-    expect(o.generateDocumentOutline).toBeUndefined();
-    expect(o.printBackground).toBeUndefined();
-    expect(o.preferCSSPageSize).toBeUndefined();
-    expect(o.waitForPagedJs).toBeUndefined();
-  });
-
-  test("named formats map to paper inches, case-insensitively", () => {
-    expect(pdfStepOptions({ output: "o", format: "a4" }).paperWidth).toBeCloseTo(8.27);
-    expect(pdfStepOptions({ output: "o", format: "A4" }).paperHeight).toBeCloseTo(11.7);
-    expect(pdfStepOptions({ output: "o", format: "legal" }).paperHeight).toBe(14);
-    expect(() => pdfStepOptions({ output: "o", format: "napkin" })).toThrow(/unknown page size/);
-  });
-
-  test("explicit width/height lengths win only when no format is given", () => {
-    const o = pdfStepOptions({ output: "o", width: "10in", height: "254mm" });
-    expect(o.paperWidth).toBe(10);
-    expect(o.paperHeight).toBeCloseTo(10);
-    const withFormat = pdfStepOptions({ output: "o", format: "letter", width: "10in", height: "10in" });
-    expect(withFormat.paperWidth).toBe(8.5);
-  });
-
-  test("margins convert per side (in/pt/cm/mm/px)", () => {
-    const o = pdfStepOptions({ output: "o", marginTop: "1in", marginRight: "72pt", marginBottom: "2.54cm", marginLeft: "96px" });
-    expect(o.marginTop).toBe(1);
-    expect(o.marginRight).toBeCloseTo(1);
-    expect(o.marginBottom).toBeCloseTo(1);
-    expect(o.marginLeft).toBeCloseTo(1);
-  });
-
-  test("header only: footer gets the empty <div></div> so Chromium prints no default URL/date", () => {
-    const o = pdfStepOptions({ output: "o", headerTemplate: "<b>H</b>" });
-    expect(o.displayHeaderFooter).toBe(true);
-    expect(o.headerTemplate).toBe("<b>H</b>");
-    expect(o.footerTemplate).toBe("<div></div>");
-  });
-
-  test("footer only: header gets the empty <div></div>", () => {
-    const o = pdfStepOptions({ output: "o", footerTemplate: "<i>F</i>" });
-    expect(o.headerTemplate).toBe("<div></div>");
-    expect(o.footerTemplate).toBe("<i>F</i>");
-  });
-
-  test("pageNumbers builds the 'N of M' footer and overrides a custom footer", () => {
-    const o = pdfStepOptions({ output: "o", pageNumbers: true, footerTemplate: "<i>ignored</i>" });
-    expect(o.displayHeaderFooter).toBe(true);
-    expect(o.headerTemplate).toBe("<div></div>");
-    expect(o.footerTemplate).toContain('class="pageNumber"');
-    expect(o.footerTemplate).toContain('class="totalPages"');
-    expect(o.footerTemplate).not.toContain("ignored");
-  });
-
-  test("pageNumbers:false alone does not turn on header/footer", () => {
-    expect(pdfStepOptions({ output: "o", pageNumbers: false }).displayHeaderFooter).toBeUndefined();
-  });
-
-  test("tagged/outline/printBackground/preferCSSPageSize map to their CDP names", () => {
-    const o = pdfStepOptions({ output: "o", tagged: true, outline: true, printBackground: true, preferCSSPageSize: true });
-    expect(o.generateTaggedPDF).toBe(true);
-    expect(o.generateDocumentOutline).toBe(true);
-    expect(o.printBackground).toBe(true);
-    expect(o.preferCSSPageSize).toBe(true);
-    // #2903: TOC page numbers come from toc-pages.ts's print loop, never from
-    // the browser-side 3s Paged.js wait (no pagination script ships).
-    expect(o.waitForPagedJs).toBeUndefined();
-    // false never emits the key (CDP defaults apply)
-    expect(pdfStepOptions({ output: "o", tagged: false, outline: false }).generateTaggedPDF).toBeUndefined();
-  });
-});
-
-describe("renderPdf", () => {
-  test("stages the HTML into a private dir, asks for one pdf step, and cleans up", async () => {
-    const seen: RenderSpec[] = [];
-    const fakeRender = async (spec: RenderSpec): Promise<RenderResult> => {
-      seen.push(spec);
-      expect(fs.readFileSync(spec.file, "utf8")).toBe("<p>hi</p>");
-      return { ok: true, outputs: [], evals: {}, stdout: "" };
-    };
-    const out = path.join(os.tmpdir(), `aside-client-${process.pid}.pdf`);
-    await renderPdf("<p>hi</p>", { output: out, format: "a4", tagged: true }, fakeRender);
-    expect(seen).toHaveLength(1);
-    expect(seen[0].steps).toHaveLength(1);
-    const step = seen[0].steps[0];
-    expect(step.kind).toBe("pdf");
-    if (step.kind === "pdf") {
-      expect(step.out).toBe(out);
-      expect(step.options?.generateTaggedPDF).toBe(true);
-      expect(step.options?.paperWidth).toBeCloseTo(8.27);
-    }
-    // Staging dir is gone after the render.
-    expect(fs.existsSync(path.dirname(seen[0].file))).toBe(false);
-  });
-
-  test("a failed render with a browser up is a plain render error (exit 2 class), never silent", async () => {
-    const failing = async (): Promise<RenderResult> => ({ ok: false, engine: "aside", outputs: [], evals: {}, stdout: "", error: "render script did not finish" });
-    const err = await renderPdf("<p></p>", { output: "/tmp/never.pdf" }, failing).catch((e: Error) => e);
-    expect(err).toBeInstanceOf(Error);
-    expect(err).not.toBeInstanceOf(BrowserUnavailableError);
-    expect((err as Error).message).toMatch(/PDF render failed: render script did not finish/);
-  });
-
-  test("no browser at all (render() found neither Aside nor the browse binary) is BrowserUnavailableError", async () => {
-    const none = async (): Promise<RenderResult> => ({ ok: false, outputs: [], evals: {}, stdout: "", error: `${NO_BROWSER}: ${NO_BROWSER_HELP} (NEEDS_ASIDE: aside not on PATH)` });
-    const err = await renderPdf("<p></p>", { output: "/tmp/never.pdf" }, none).catch((e: Error) => e);
-    expect(err).toBeInstanceOf(BrowserUnavailableError);
-    expect((err as Error).message).toContain("aside.com");
-    expect((err as Error).message).toContain("./setup");
-    expect((err as Error).message).toContain("GSTACK_BROWSE_BIN");
-  });
-
-  test("the fallback engine's failures are render errors too (engine picked ≠ engine missing)", async () => {
-    const browseFail = async (): Promise<RenderResult> => ({ ok: false, engine: "browse", outputs: [], evals: {}, stdout: "", error: "browse pdf failed: boom" });
-    await expect(renderPdf("<p></p>", { output: "/tmp/never.pdf" }, browseFail)).rejects.toThrow(/PDF render failed: browse pdf failed: boom/);
-  });
-});
-
-describe("BrowserUnavailableError", () => {
-  test("renderFailure classifies on the NO_BROWSER prefix only", () => {
-    expect(renderFailure(`${NO_BROWSER}: x`)).toBeInstanceOf(BrowserUnavailableError);
-    expect(renderFailure("no browser available")).toBeInstanceOf(BrowserUnavailableError);
-    expect(renderFailure("Aside closed mid-run")).not.toBeInstanceOf(BrowserUnavailableError);
-    expect(new BrowserUnavailableError("m").name).toBe("BrowserUnavailableError");
-  });
-
-  test("exit code 4 is no-browser (the old Aside/browse slot, same value)", () => {
-    expect(ExitCode.BrowserUnavailable).toBe(4);
-    expect((ExitCode as Record<string, number>).AsideUnavailable).toBeUndefined();
-    expect((ExitCode as Record<string, number>).BrowseUnavailable).toBeUndefined();
-  });
-});