v1.81.0.0 feat: Aside is the browser gstack drives first; every browsing skill, the PDF/diagram renderer, and web research; the bundled browser stays the automatic fallback (#2810)

* feat(aside): browser-driver contract, cookbook, research and fallback resolvers {{ASIDE_SETUP}} (readiness probe + ten rules for driving the user's real browser), {{ASIDE_COOKBOOK}} (script shapes verified live against Aside CLI 1.26: one flow per aside repl script, CDP console hook before navigation, evidence lines, session-directory artifact handoff, GSTACK_STEP_OK sentinel), {{ASIDE_RESEARCH}} (research through aside exec, WebSearch when Aside is absent, knowledge otherwise) and {{BROWSE_FALLBACK}} (the fifteen-row Aside-step to $B-command table plus the rules that differ, so every browsing skill keeps working on gstack's own headless browser). test/aside-driver.test.ts pins the sentences and asserts every browsing skill carries the Aside block followed by the fallback; test/helpers/aside-available.ts is the shared live-Aside probe. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * feat(render): Aside-first local-HTML renderer with the bundled browser as fallback lib/aside-render.ts serves the HTML's directory on loopback (Aside refuses file:// URLs), opens it with waitUntil load, prints through CDP Page.printToPDF so tagged output, outlines, header/footer templates and page numbers survive, emulates device metrics for sized screenshots, and writes in-page evaluations to files; when Aside is absent it runs the same spec through the browse daemon (newtab, load, js, pdf, screenshot, closetab) and reports ENGINE=aside|browse. bin/gstack-render.ts is the CLI skill templates call. lib/claude-bin.ts and lib/error-handling.ts become the canonical copies (browse/src re-exports them). Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * refactor(browse): /browse drives Aside first, with the $B reference behind the fallback Contract, cookbook, mode choice (aside repl by default, aside exec for reading), report format, the fallback section, and the full command reference carved on demand. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * refactor(qa): /qa and /qa-only drive Aside, fall back to $B QA_METHODOLOGY runs every phase as Aside scripts (orient, explore, document, re-test, mobile viewport via CDP emulation, links via HEAD fetch); the authenticate phase is 'you are already signed in'; a 13th rule requires consent before mutating actions on non-local targets; the fallback section translates each step onto $B. The qa E2E tests run on whichever engine is present. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * refactor(design): design-review, design-consultation, design-shotgun, plan-design-review, design-html drive Aside Design-system extraction is one script printing FONTS/COLORS/HEADINGS/TOUCH_TARGETS/NAV; competitor research confirms the exact URLs before opening them in the real browser and runs on the bundled browser when Aside is absent; design-html's viewport screenshots, sketches and comparison boards render through gstack-render. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * refactor(deploy): benchmark, canary, land-and-deploy Step 7, devex-review drive Aside One aside repl script per page prints NAV/PAINT/LCP/RESOURCES/SCRIPTS/CSS/SUMMARY (benchmark), CONSOLE_ERRORS/NAV/TEXT + screenshot (canary, re-run every 60s), and the post-deploy check reads responseStatus from the navigation entry; each carries the $B fallback. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * feat(third-party-actions): Aside is the recommended driver; gstack's visible browser stays the fallback The readiness probe is lifted from {{ASIDE_SETUP}} at gen time (byte-identity pinned) and rule 3 points at browse/SKILL.md for how to drive; the consent question offers Aside first and gstack's own visible browser (handoff/resume for sign-in) as the fallback, as v1.72 framed it. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * refactor(scrape): /scrape reads pages through Aside; the browser-skills runtime rides the fallback Look-then-extract scripts build the JSON inside the page and print it between JSON_START/JSON_END; aside exec for fuzzy intents; on the $B fallback the browser-skills match/prototype flow and /skillify apply as before. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * refactor(make-pdf): print through Aside first, the bundled browser otherwise asideClient.ts replaces the direct $B client with one render() call per PDF (the exact option mapping the browse pdf command had: paper, margins, header/footer/page numbers, tagged, outline, printBackground, preferCSSPageSize, Paged.js wait); the diagram pre-pass, oversized-image downscale and DOCX rasters each run as one render script with per-fence try/catch; exit 4 now means no browser is available and names both remedies; $P setup reports which engine it found. The e2e gates run on whichever engine is present, so the Linux lane exercises the fallback. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * refactor(diagram): the triplet is one gstack-render call SVG, PNG and excalidraw from one invocation over the content-addressed bundle staged under /tmp/gstack-render; every diagram type gets an excalidraw export; gstack-render picks the engine and prints ENGINE=; the diagram E2E gates on either engine. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * feat(research): web research runs in Aside first, WebSearch second The planning, review, design, security and investigate skills research through {{ASIDE_RESEARCH}}; WebSearch stays in allowed-tools as the fallback; testing.ts's bootstrap step follows; skeleton ceilings ratcheted for the research block. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * feat(setup,gen-skill-docs): prune renders of skills that no longer exist setup gains _prune_stale_generated for every host tree and the doc generator removes gstack-* output dirs it did not write, so a skill removed from the source tree can never linger in an install. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * test: registries, budgets and suite reconciled for Aside-first with the $B fallback Touchfiles + E2E tiers gain the Aside keys, coverage matrix and eval baselines updated, size budget re-baselined to parity-baseline-v1.80.0.0.json (the contract plus fallback ride in every browsing skill), parity ceilings ratcheted with measured values, LLM-judge prompts and the E2E fixtures speak Aside-first, browse-fallback. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs: Aside first, gstack browser fallback README, BROWSER.md, docs/, CONTRIBUTING, CLAUDE.md, ARCHITECTURE, AGENTS.md, TODOS and the root router describe the one product story: Aside is the browser gstack drives first; the bundled headless browser is the automatic fallback (Linux, Windows, app closed) where cookie import, GStack Browser, pair-agent and browser-skills still apply. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * chore: regenerate SKILL.md docs, llms.txt, agents digest, ship goldens, context-budget fixture bun run gen:skill-docs over the templates; goldens re-rendered; context-budget ceilings recaptured. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * v1.80.0.0: Aside is the browser gstack drives first; the bundled browser is the fallback MINOR: new capability across ten skills, the renderer and research; nothing removed. CHANGELOG release summary + itemized changes; VERSION 1.80.0.0; package.json 1.80.0. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs(todos): file non-Claude host ownership-gate and version-heading pin follow-ups Two follow-ups from the /plan-ceo-review + /plan-eng-review pass on merging PR #2804 with main's v1.80.0.0 ownership gate: bring the Codex/Factory/ OpenCode/Cursor/Kiro copy loops and the stale-render prune under the .gstack-owned marker rule, and a free test pinning that the CHANGELOG top heading equals VERSION (the collision that git cannot see). Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * fix: pre-landing review fixes for the Aside-first branch Review army + adversarial passes (Claude and Codex) on the merged branch: setup - _prune_stale_generated scans the host dirs too (the generator already removed the render before setup ran, so the host branch was dead), skips symlinks in the render tree (rm -rf on a slash-terminated link empties its target), removes a host symlink only when it resolves into gstack, cleans a bannered real dir through _cleanup_weak_dir, recognizes frontmatter-renamed skills, and logs through log. The always-run codex render passes every host dir that may link to it. - NEEDS_BUILD checks all three binaries (with $_EXE) and lib/ sources; the browser hint and the bootstrap summary honor GSTACK_SKIP_ASIDE, treat a requested skip as a request, and derive one skill list. lib/aside-render.ts + bin/gstack-render.ts - The loopback server carries a per-render secret path, checks containment on the real path (symlink escapes are 403), and rejects malformed encoding. - Inline eval results are one base64 line, so page text cannot forge ASIDE_DIR= or the sentinel; the last ASIDE_DIR wins. - runProc escalates SIGTERM to SIGKILL, bounds every wait, and clears every timer (an uncleared one kept gstack-render alive after printing OK). - renderTmpDir refuses a shared /tmp name owned by someone else; the work dir and server are created inside try; goto's budget follows the render budget. - probeAside classifies a present-but-failing CLI as ASIDE_NOT_RUNNING like the skills' bash probe; render() retries on gstack's own browser when Aside could not start or its private CDP bridge is gone (never on a page error or a timeout of a running script); the CLI reports the engine that actually rendered, exits 0 on --help, rejects non-numeric flags, documents --wait-timeout, fences EVAL/PAGE_ERRORS as untrusted content, and names the daemon's cookie-import JS lock remedy. - The browse path passes --scale only when asked (a scale change rebuilds the daemon context) and restores the viewport after a sized screenshot. resolvers / templates - The bash probe honors GSTACK_SKIP_ASIDE and has a perl deadline on stock macOS; .local is no longer LOCAL (mDNS); same-origin filters compare parsed origins; link status is HEAD-checked only on LOCAL targets; every aside exec goes through the receipted _aside_exec prelude ({{ASIDE_EXEC_PRELUDE}}), including nine template blocks that called it bare; the design sketch and diagram staging use private directories. - The generator prunes only bannered renders and never a host whose generation failed. Docs, stale comments and dead code cleaned; goldens re-rendered; tests updated and added for every behavior above. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * test: coverage for the render CLI, setup rebuild check, make-pdf exit codes, and prose $B spans New free tests from the ship coverage audit: test/gstack-render-cli.test.ts (argv guards, --help, output contract with a fake daemon, failure and serve-root paths, no-browser case, prompt exit), test/setup-needs-build.test.ts (every binary and source set flips NEEDS_BUILD, Windows suffixes), make-pdf/test/cli-exit-codes.test.ts and setup-smoke.test.ts (error to exit code mapping, runSetup stages, renderPdf's engine), and prose-span cases for extractBrowseCommands in test/skill-parser.test.ts. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs: CHANGELOG and TODOS cover the review fixes (v1.81.0.0) Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs: sync project docs with the v1.81.0.0 review fixes BROWSER.md, ARCHITECTURE.md, CONTRIBUTING.md, README.md, CLAUDE.md, docs/TESTING_INTERNALS.md and docs/PROJECT_STRUCTURE.md now describe the shipped renderer and setup: the loopback render server's per-render secret path and real-path containment, ENGINE= naming the engine that actually rendered (mid-run retry on gstack's own browser), EVAL/PAGE_ERRORS fenced as untrusted content, --wait-timeout and the CLI's argv guards, the receipted _aside_exec prelude ({{ASIDE_EXEC_PRELUDE}} in the placeholder table), the LOCAL host rule without .local, LOCAL-only HEAD checks in the links script, GSTACK_SKIP_ASIDE across probe/renderer/setup, the ownership-gated retired-skill prune, the widened NEEDS_BUILD check, and the new free tests (gstack-render-cli, setup-prune-stale-generated, setup-browser-hint, setup-needs-build, make-pdf cli-exit-codes and setup-smoke). Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs: CHANGELOG states the precise mid-run retry rule Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * fix(test): skill-e2e-bws slices the $B setup block from the Browser fallback section browse/SKILL.md no longer has '## SETUP' / '## Core QA Patterns' (Aside is the primary driver; the $B block moved under 'Browser fallback'), so the gate test sliced an empty block and handed the agent nothing to run. Anchor on '### Find the `$B` binary' up to the next heading. 7/7 pass. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * fix(test): gate POSIX-only fixtures off Windows windows-free-tests: the gstack-render CLI tests drive a shebang fake browse that CreateProcess cannot exec, and two NEEDS_BUILD cases assert an execute bit and a bare-name miss that MSYS bash does not have (test -x ignores mode bits and resolves design -> design.exe). Those describes and cases now self-skip on win32; argument guards, --help, the no-browser case, and every other rebuild-check case still run there. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * fix(render): runProc waits for the exit code until the kill deadline; newtab retries once on a cold daemon A process whose pipes have reached EOF is exiting, but runProc gave the exit code only five seconds to arrive and then returned null, which run() reports as a failed command. Under CI's six-shard load one such render failed with the artifact already written. The SIGTERM/SIGKILL timers already bound the wait, so the exit race now runs to the kill deadline. The first CLI call auto-starts the browse daemon; on a cold start it can answer 'Unable to connect' once while the server is still coming up. That single case is retried after 1.5s; every other newtab failure is not. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * test(aside-render): warm the daemon before live fallback cases; failures name the render error - Live fallback cases run 'goto about:blank' up to twice before asserting and skip (never fail) when the daemon cannot come up. - expectOk() puts r.error and the browse transcript into the assertion so a failed render is diagnosable from the CI log. - The argv-contract cases dump the fake's log on a miss. - File default timeout is 30s: the subject is the CLI contract, not latency. - Two cases pin the cold-daemon newtab retry and that other errors are not retried. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> * docs: CHANGELOG notes the cold-start tolerance of the bundled-browser renderer Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> --------- Co-authored-by: Sina <sdroid674+github@gmail.com> Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>
2026-09-14 00:49:00 +02:00 · 2026-09-06 08:54:25 -07:00
parent c241216637
commit 0530392821
172 changed files with 12044 additions and 4676 deletions
@@ -83,13 +83,15 @@ Core commands:
 - `$P generate --cover --toc essay.md out.pdf` — full publication layout
 - `$P generate --watermark DRAFT memo.md draft.pdf` — diagonal DRAFT watermark
 - `$P preview <input.md>` — render HTML and open in browser (fast iteration)
- `$P setup` — verify browse + Chromium + pdftotext and run a smoke test
+- `$P setup` — verify the browser (Aside, or gstack's own headless fallback) + pdftotext and run a smoke test
 - `$P --help` — full flag reference

 Output contract:
 - `stdout`: ONLY the output path on success. One line.
 - `stderr`: progress (`Rendering HTML... Generating PDF...`) unless `--quiet`.
- Exit 0 success / 1 bad args / 2 render error / 3 Paged.js timeout / 4 browse unavailable.
+- Exit 0 success / 1 bad args / 2 render error / 3 Paged.js timeout / 4 no browser available (open the Aside app, or run `./setup` to build gstack's own browser).
+
+PDFs print through Aside when it is running and through gstack's own headless browser otherwise; the stderr progress line says which (`Rendering PDF through Aside` / `through gstack's browser`).

 ## Plan Mode Safe Operations

@@ -207,7 +209,15 @@ Emoji) ship one; most Linux distros and containers ship none, so emoji render as
 empty boxes (▯). `./setup` auto-installs `fonts-noto-color-emoji` on Linux
 (apt/dnf/pacman/apk, best-effort) and the print CSS falls back through Apple /
 Segoe / Noto emoji families. Set `GSTACK_SKIP_FONTS=1` to skip the install (CI
-without sudo, managed or offline machines).
+without sudo, managed or offline machines). These matter on the gstack-browser
+fallback; Aside renders with the fonts already on the Mac.
+
+PDF output prints through the Aside browser (macOS 15+, aside.com) when it is
+running, and falls back to gstack's own headless browser (built by `./setup`;
+`GSTACK_BROWSE_BIN` / `BROWSE_BIN` point at a different build) everywhere
+else — Linux, Windows, or a closed Aside app. Exit 4 means neither browser is
+available. `--to html` and `--to docx` need no browser at all (diagrams in
+DOCX need one to rasterize; without it they embed as source text).

 ## Core patterns

@@ -383,7 +393,13 @@ If the user has a `.md` file open and says "make it look nice", propose

 ## Debugging

- Output looks empty / blank → check browse daemon is running: `$B status`.
+- Exit 4 / "no browser available" → neither the Aside browser (macOS 15+,
+  aside.com) nor gstack's own headless browser is usable. Open Aside, or run
+  `./setup` in the gstack repo to build the fallback, re-run. `$P setup` checks
+  the whole chain and says which browser it found.
+- Diagram shows a red "failed to render" block → the parse error is printed in
+  the block. If EVERY diagram fails with "diagram renderer:", the browser went
+  away mid-run (Aside closed, or the fallback daemon died).
 - Fragmented text on copy-paste → highlight.js output (Phase 4). Retry with
  `--no-syntax` once that flag exists. For now, remove fenced code blocks
  and regenerate.
@@ -398,11 +414,11 @@ If the user has a `.md` file open and says "make it look nice", propose
 ```
 stdout: /tmp/letter.pdf          ← just the path, one line
 stderr: Rendering HTML...        ← progress spinner (unless --quiet)
-        Generating PDF...
-        Done in 1.5s. 43 words · 22KB · /tmp/letter.pdf
+        Rendering PDF through Aside...   ← or "through gstack's browser"
+        Done in 11.2s. 43 words · 22KB · /tmp/letter.pdf

 exit code: 0 success / 1 bad args / 2 render error / 3 Paged.js timeout
-           / 4 browse unavailable
+           / 4 no browser available (Aside not open, fallback not built)
 ```

 Capture the path: `PDF=$($P generate letter.md)` — then use `$PDF`.
@@ -46,7 +46,15 @@ Emoji) ship one; most Linux distros and containers ship none, so emoji render as
 empty boxes (▯). `./setup` auto-installs `fonts-noto-color-emoji` on Linux
 (apt/dnf/pacman/apk, best-effort) and the print CSS falls back through Apple /
 Segoe / Noto emoji families. Set `GSTACK_SKIP_FONTS=1` to skip the install (CI
-without sudo, managed or offline machines).
+without sudo, managed or offline machines). These matter on the gstack-browser
+fallback; Aside renders with the fonts already on the Mac.
+
+PDF output prints through the Aside browser (macOS 15+, aside.com) when it is
+running, and falls back to gstack's own headless browser (built by `./setup`;
+`GSTACK_BROWSE_BIN` / `BROWSE_BIN` point at a different build) everywhere
+else — Linux, Windows, or a closed Aside app. Exit 4 means neither browser is
+available. `--to html` and `--to docx` need no browser at all (diagrams in
+DOCX need one to rasterize; without it they embed as source text).

 ## Core patterns

@@ -222,7 +230,13 @@ If the user has a `.md` file open and says "make it look nice", propose

 ## Debugging

- Output looks empty / blank → check browse daemon is running: `$B status`.
+- Exit 4 / "no browser available" → neither the Aside browser (macOS 15+,
+  aside.com) nor gstack's own headless browser is usable. Open Aside, or run
+  `./setup` in the gstack repo to build the fallback, re-run. `$P setup` checks
+  the whole chain and says which browser it found.
+- Diagram shows a red "failed to render" block → the parse error is printed in
+  the block. If EVERY diagram fails with "diagram renderer:", the browser went
+  away mid-run (Aside closed, or the fallback daemon died).
 - Fragmented text on copy-paste → highlight.js output (Phase 4). Retry with
  `--no-syntax` once that flag exists. For now, remove fenced code blocks
  and regenerate.
@@ -237,11 +251,11 @@ If the user has a `.md` file open and says "make it look nice", propose
 ```
 stdout: /tmp/letter.pdf          ← just the path, one line
 stderr: Rendering HTML...        ← progress spinner (unless --quiet)
-        Generating PDF...
-        Done in 1.5s. 43 words · 22KB · /tmp/letter.pdf
+        Rendering PDF through Aside...   ← or "through gstack's browser"
+        Done in 11.2s. 43 words · 22KB · /tmp/letter.pdf

 exit code: 0 success / 1 bad args / 2 render error / 3 Paged.js timeout
-           / 4 browse unavailable
+           / 4 no browser available (Aside not open, fallback not built)
 ```

 Capture the path: `PDF=$($P generate letter.md)` — then use `$PDF`.
@@ -0,0 +1,117 @@
+/**
+ * make-pdf's render client: final HTML → PDF through lib/aside-render's
+ * `render()` — the Aside browser (macOS 15+, aside.com) when it is running,
+ * otherwise gstack's own headless browser (the browse daemon; GSTACK_BROWSE_BIN
+ * / BROWSE_BIN override where it lives). The HTML is staged into a private
+ * dir, served over loopback for the duration of the render, printed, and the
+ * PDF copied to `output`. No browser at all is exit 4 (BrowserUnavailableError).
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import {
+  NO_BROWSER,
+  PAGE_NUMBER_FOOTER,
+  lengthToInches,
+  paperInches,
+  render,
+  renderTmpDir,
+  type PdfStepOptions,
+  type RenderEngine,
+} from "../../lib/aside-render";
+import { BrowserUnavailableError } from "./types";
+
+export interface PdfOptions {
+  output: string;
+  format?: string;
+  width?: string;
+  height?: string;
+  marginTop?: string;
+  marginRight?: string;
+  marginBottom?: string;
+  marginLeft?: string;
+  headerTemplate?: string;
+  footerTemplate?: string;
+  pageNumbers?: boolean;
+  tagged?: boolean;
+  outline?: boolean;
+  printBackground?: boolean;
+  preferCSSPageSize?: boolean;
+  /** Wait (≤3s, non-fatal) for Paged.js before printing. */
+  toc?: boolean;
+}
+
+/**
+ * make-pdf's option shape → CDP Page.printToPDF options (inches). Same
+ * mapping the browse `pdf` command applies: Letter when no size is
+ * given, empty `<div></div>` for whichever header/footer slot is unset so
+ * Chromium never prints its default URL/date, margins default to none.
+ */
+export function pdfStepOptions(opts: PdfOptions): PdfStepOptions {
+  const o: PdfStepOptions = {};
+
+  if (opts.format) {
+    const paper = paperInches(opts.format);
+    if (!paper) throw new Error(`unknown page size: ${opts.format}`);
+    [o.paperWidth, o.paperHeight] = paper;
+  } else if (opts.width && opts.height) {
+    o.paperWidth = lengthToInches(opts.width);
+    o.paperHeight = lengthToInches(opts.height);
+  } else {
+    [o.paperWidth, o.paperHeight] = paperInches("letter")!;
+  }
+
+  o.marginTop = lengthToInches(opts.marginTop) ?? 0;
+  o.marginRight = lengthToInches(opts.marginRight) ?? 0;
+  o.marginBottom = lengthToInches(opts.marginBottom) ?? 0;
+  o.marginLeft = lengthToInches(opts.marginLeft) ?? 0;
+
+  if (opts.headerTemplate !== undefined || opts.footerTemplate !== undefined || opts.pageNumbers === true) {
+    o.displayHeaderFooter = true;
+    o.headerTemplate = opts.headerTemplate ?? "<div></div>";
+    o.footerTemplate = opts.pageNumbers ? PAGE_NUMBER_FOOTER : (opts.footerTemplate ?? "<div></div>");
+  }
+
+  if (opts.tagged === true) o.generateTaggedPDF = true;
+  if (opts.outline === true) o.generateDocumentOutline = true;
+  if (opts.printBackground === true) o.printBackground = true;
+  if (opts.preferCSSPageSize === true) o.preferCSSPageSize = true;
+  if (opts.toc === true) o.waitForPagedJs = true;
+  return o;
+}
+
+/**
+ * Render a self-contained HTML document to `opts.output`. Everything the page
+ * needs must be inline (the orchestrator inlines images as data URIs): only
+ * the staging dir is served.
+ */
+export async function renderPdf(
+  html: string,
+  opts: PdfOptions,
+  renderFn: typeof render = render,
+): Promise<RenderEngine | undefined> {
+  const dir = fs.mkdtempSync(path.join(renderTmpDir(), "make-pdf-"));
+  try {
+    const file = path.join(dir, "document.html");
+    fs.writeFileSync(file, html, "utf8");
+    const result = await renderFn({
+      file,
+      steps: [{ kind: "pdf", out: path.resolve(opts.output), options: pdfStepOptions(opts) }],
+    });
+    if (!result.ok) throw renderFailure(result.error ?? "unknown error");
+    return result.engine;
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Classify a failed render: a BrowserUnavailableError (exit 4) when neither
+ * browser could run at all, otherwise a plain render error (exit 2).
+ */
+export function renderFailure(detail: string): Error {
+  return detail.startsWith(NO_BROWSER)
+    ? new BrowserUnavailableError(detail)
+    : new Error(`PDF render failed: ${detail}`);
+}
@@ -1,428 +0,0 @@
-/**
- * Typed shell-out wrapper for the browse CLI.
- *
- * Every browse call goes through this file. Reasons:
- *   - One place to do binary resolution.
- *   - One place to enforce the --from-file convention for large payloads
- *     (Windows argv cap is 8191 chars; 200KB HTML dies without this).
- *   - One place that maps non-zero exit codes to typed errors.
- *
- * Binary resolution order (Codex round 2 #4, v1.24-aligned):
- *   1. $GSTACK_BROWSE_BIN env override (preferred, matches v1.24 GSTACK_*_BIN pattern)
- *   2. $BROWSE_BIN env override (back-compat alias)
- *   3. sibling dir: dirname(execPath)/../browse/dist/browse[.exe]
- *      (execPath, NOT argv[0]: in a bun-compiled binary argv[0] is the raw
- *      invocation string — often relative, so dirname() yields "." and the
- *      sibling candidates resolve against the CWD instead of the install
- *      dir; #2156. execPath is always the absolute binary path.)
- *   4. ~/.claude/skills/gstack/browse/dist/browse[.exe]
- *   5. PATH lookup via Bun.which('browse') — handles Windows PATHEXT natively
- *   6. error with setup hint
- *
- * Windows quirks:
- *   - bun build --compile --outfile X emits X.exe on win32, so candidate paths
- *     need a .exe probe pass (fs.accessSync(X_OK) degrades to existence-checking
- *     on Windows per Node docs, so the bare path silently misses the .exe file).
- *   - `which` only exists in Git Bash; Bun.which() handles cmd.exe / PowerShell
- *     natively via PATHEXT semantics.
- */
-
-import { execFileSync } from "node:child_process";
-import * as fs from "node:fs";
-import * as os from "node:os";
-import * as path from "node:path";
-import * as crypto from "node:crypto";
-
-import { BrowseClientError } from "./types";
-
-export interface LoadHtmlOptions {
-  html: string;                   // raw HTML string
-  waitUntil?: "load" | "domcontentloaded" | "networkidle";
-  tabId: number;
-}
-
-export interface PdfOptions {
-  output: string;
-  tabId: number;
-  format?: string;
-  width?: string;
-  height?: string;
-  marginTop?: string;
-  marginRight?: string;
-  marginBottom?: string;
-  marginLeft?: string;
-  headerTemplate?: string;
-  footerTemplate?: string;
-  pageNumbers?: boolean;
-  tagged?: boolean;
-  outline?: boolean;
-  printBackground?: boolean;
-  preferCSSPageSize?: boolean;
-  toc?: boolean;
-}
-
-export interface JsOptions {
-  tabId: number;
-  expression: string;             // JS expression to evaluate
-}
-
-/**
- * Resolve an absolute or PATH-resolvable command via Bun.which-style semantics,
- * with a Windows .exe/.cmd/.bat extension probe for absolute paths. Mirrors
- * the v1.24 claude-bin.ts override-resolution shape.
- *
- * Returns null if nothing resolves; callers degrade with a typed error rather
- * than throwing here.
- */
-function resolveOverride(value: string | undefined, env: NodeJS.ProcessEnv): string | null {
-  if (!value?.trim()) return null;
-  const trimmed = value.trim().replace(/^"(.*)"$/, '$1');
-  if (path.isAbsolute(trimmed)) return findExecutable(trimmed);
-  const PATH = env.PATH ?? env.Path ?? '';
-  return Bun.which(trimmed, { PATH }) ?? null;
-}
-
-/**
- * Probe a base path for executability, honoring Windows extension suffixes.
- *
- * On POSIX, isExecutable(base) is the only check that matters. On Windows,
- * fs.accessSync(p, X_OK) degrades to an existence check — so a bare-path probe
- * misses bun-compiled binaries (which land at base.exe). After the bare probe
- * fails on win32, try .exe / .cmd / .bat. Linux/macOS behavior is unchanged.
- */
-export function findExecutable(base: string): string | null {
-  if (isExecutable(base)) return base;
-  if (process.platform === "win32") {
-    for (const ext of [".exe", ".cmd", ".bat"]) {
-      const withExt = base + ext;
-      if (isExecutable(withExt)) return withExt;
-    }
-  }
-  return null;
-}
-
-/**
- * Locate the browse binary. Throws a BrowseClientError with a
- * canonical setup message if not found. See header for resolution order.
- */
-export function resolveBrowseBin(
-  env: NodeJS.ProcessEnv = process.env,
-  // Injectable for tests: under `bun test` the process path is the bun
-  // runtime, so the compiled-binary shapes are unreachable without a seam.
-  selfPath: string = process.execPath || process.argv[0],
-): string {
-  // 1 + 2: env overrides (GSTACK_BROWSE_BIN preferred, BROWSE_BIN back-compat).
-  const overrideRaw = env.GSTACK_BROWSE_BIN ?? env.BROWSE_BIN;
-  const override = resolveOverride(overrideRaw, env);
-  if (override) return override;
-
-  // 3: sibling — make-pdf and browse co-located in dist/. execPath, not
-  // argv[0] (#2156): see the header — argv[0] in a compiled binary is the
-  // invocation string, and a relative one resolved candidates against CWD.
-  const selfDir = path.dirname(selfPath);
-  const siblingCandidates = [
-    path.resolve(selfDir, "../browse/dist/browse"),
-    path.resolve(selfDir, "../../browse/dist/browse"),
-    path.resolve(selfDir, "../browse"),
-  ];
-  for (const candidate of siblingCandidates) {
-    const found = findExecutable(candidate);
-    if (found) return found;
-  }
-
-  // 4: global install.
-  const home = os.homedir();
-  const globalPath = path.join(home, ".claude/skills/gstack/browse/dist/browse");
-  const globalFound = findExecutable(globalPath);
-  if (globalFound) return globalFound;
-
-  // 5: PATH lookup via Bun.which — handles Windows PATHEXT natively (no `which`
-  // dependency on cmd.exe / PowerShell, no `where`-vs-`which` branch).
-  const PATH = env.PATH ?? env.Path ?? '';
-  const onPath = Bun.which('browse', { PATH });
-  if (onPath) return onPath;
-
-  throw new BrowseClientError(
-    /* exitCode */ 127,
-    "resolve",
-    [
-      "browse binary not found.",
-      "",
-      "make-pdf needs browse (the gstack Chromium daemon) to render PDFs.",
-      "Tried:",
-      `  - $GSTACK_BROWSE_BIN (${env.GSTACK_BROWSE_BIN || "unset"})`,
-      `  - $BROWSE_BIN (${env.BROWSE_BIN || "unset"})`,
-      `  - sibling: ${siblingCandidates.join(", ")}`,
-      `  - global: ${globalPath}`,
-      "  - PATH: `browse`",
-      "",
-      "To fix: run gstack setup from the gstack repo:",
-      "  cd ~/.claude/skills/gstack && ./setup",
-      "",
-      "Or set GSTACK_BROWSE_BIN explicitly:",
-      process.platform === "win32"
-        ? '  setx GSTACK_BROWSE_BIN "C:\\path\\to\\browse.exe"'
-        : "  export GSTACK_BROWSE_BIN=/path/to/browse",
-    ].join("\n"),
-  );
-}
-
-function isExecutable(p: string): boolean {
-  try {
-    // Must be a regular FILE. access(X_OK) alone is true for directories — they carry the
-    // execute/traverse bit on POSIX and pass the Windows check too — so discovery happily
-    // "found" ~/.claude/skills/browse, which is the skill's docs folder containing nothing
-    // but SKILL.md, and returned a directory as the browse binary.
-    if (!fs.statSync(p).isFile()) return false;
-    fs.accessSync(p, fs.constants.X_OK);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-/**
- * Run a browse command. Returns stdout on success.
- * Throws BrowseClientError on non-zero exit.
- */
-function runBrowse(args: string[]): string {
-  const bin = resolveBrowseBin();
-  try {
-    return execFileSync(bin, args, {
-      encoding: "utf8",
-      maxBuffer: 16 * 1024 * 1024,    // 16MB; tab content can be large
-      stdio: ["ignore", "pipe", "pipe"],
-      // A wedged daemon (or a hostile mermaid source spinning the renderer)
-      // must fail the run, not hang it forever.
-      timeout: 120_000,
-    });
-  } catch (err: any) {
-    const exitCode = typeof err.status === "number" ? err.status : 1;
-    const stderr = typeof err.stderr === "string"
-      ? err.stderr
-      : (err.stderr?.toString() ?? "");
-    throw new BrowseClientError(exitCode, args[0] || "unknown", stderr);
-  }
-}
-
-/**
- * Temp dir for any file handed to browse (payloads, rendered HTML, PDF output).
- *
- * Path must be under the browse safe-dirs allowlist (/tmp or cwd on
- * non-Windows; os.tmpdir on Windows).  v1.6.0.0 tightened --from-file
- * validation to close a CLI/API parity gap (PR #1103), so os.tmpdir()
- * on macOS (/var/folders/...) now fails validateReadPath.  Use the same
- * TEMP_DIR convention as browse/src/platform.ts.
- *
- * Exported because orchestrator.ts and setup.ts write files that browse must
- * read back; os.tmpdir() there trips the same validateReadPath rejection.
- */
-export const PAYLOAD_TMP_DIR = process.platform === "win32" ? os.tmpdir() : "/tmp";
-
-function writePayloadFile(payload: Record<string, unknown>): string {
-  const hash = crypto.createHash("sha256")
-    .update(JSON.stringify(payload))
-    .digest("hex")
-    .slice(0, 12);
-  const tmpPath = path.join(PAYLOAD_TMP_DIR, `make-pdf-browse-${process.pid}-${hash}.json`);
-  fs.writeFileSync(tmpPath, JSON.stringify(payload), "utf8");
-  return tmpPath;
-}
-
-function cleanupPayloadFile(p: string): void {
-  try { fs.unlinkSync(p); } catch { /* best-effort */ }
-}
-
-// ─── Public API ─────────────────────────────────────────────────
-
-/**
- * Open a new tab. Returns the tabId.
- * Requires `$B newtab --json` to be available (added in the browse flag
- * extension for this feature). If --json isn't supported yet, the fallback
- * parses "Opened tab N" from stdout.
- */
-export function newtab(url?: string): number {
-  const args = ["newtab"];
-  if (url) args.push(url);
-  // Try --json first (preferred path for programmatic use)
-  try {
-    const out = runBrowse([...args, "--json"]);
-    const parsed = JSON.parse(out);
-    if (typeof parsed.tabId === "number") return parsed.tabId;
-  } catch {
-    // Fall back to stdout-string parsing. Brittle, but works on older browse builds.
-  }
-  const out = runBrowse(args);
-  const m = out.match(/tab\s+(\d+)/i);
-  if (!m) throw new BrowseClientError(1, "newtab", `could not parse tab id from: ${out}`);
-  return parseInt(m[1], 10);
-}
-
-/**
- * Close a tab (by id or the active tab).
- */
-export function closetab(tabId?: number): void {
-  const args = ["closetab"];
-  if (tabId !== undefined) args.push(String(tabId));
-  runBrowse(args);
-}
-
-/**
- * Load raw HTML into a specific tab.
- * Uses --from-file for any payload >4KB (Codex round 2 #3).
- */
-export function loadHtml(opts: LoadHtmlOptions): void {
-  // Always use --from-file to dodge argv limits. The HTML is almost always >4KB.
-  const payload = {
-    html: opts.html,
-    waitUntil: opts.waitUntil ?? "domcontentloaded",
-  };
-  const payloadFile = writePayloadFile(payload);
-  try {
-    runBrowse([
-      "load-html",
-      "--from-file", payloadFile,
-      "--tab-id", String(opts.tabId),
-    ]);
-  } finally {
-    cleanupPayloadFile(payloadFile);
-  }
-}
-
-/**
- * Load an HTML file (already under browse's safe dirs, e.g. /tmp) into a tab
- * by path. Cheaper than loadHtml for large pages — no JSON payload round-trip;
- * browse reads the file directly (diagram-render bundle is ~9MB).
- */
-export function loadHtmlFile(opts: { file: string; tabId: number; waitUntil?: "load" | "domcontentloaded" | "networkidle" }): void {
-  const args = ["load-html", opts.file, "--tab-id", String(opts.tabId)];
-  if (opts.waitUntil) args.push("--wait-until", opts.waitUntil);
-  runBrowse(args);
-}
-
-/**
- * Evaluate a JS expression in a tab. Returns the serialized result as string.
- */
-export function js(opts: JsOptions): string {
-  return runBrowse([
-    "js",
-    opts.expression,
-    "--tab-id", String(opts.tabId),
-  ]).trim();
-}
-
-/**
- * Evaluate a JS file in a tab (`browse eval <file>`): the argv-safe transport
- * for expressions too large for a command-line element. The file must live
- * under browse's safe dirs (/tmp or cwd).
- */
-export function evalFile(opts: { file: string; tabId: number }): string {
-  return runBrowse([
-    "eval",
-    opts.file,
-    "--tab-id", String(opts.tabId),
-  ]).trim();
-}
-
-/**
- * Poll a boolean JS expression until it evaluates to true, or timeout.
- * Returns true if it succeeded, false if timed out.
- */
-export function waitForExpression(opts: {
-  expression: string;
-  tabId: number;
-  timeoutMs: number;
-  pollIntervalMs?: number;
-}): boolean {
-  const poll = opts.pollIntervalMs ?? 200;
-  const deadline = Date.now() + opts.timeoutMs;
-  while (Date.now() < deadline) {
-    try {
-      const result = js({ expression: opts.expression, tabId: opts.tabId });
-      if (result === "true") return true;
-    } catch {
-      // Tab may still be loading; keep polling
-    }
-    const wait = Math.min(poll, Math.max(0, deadline - Date.now()));
-    if (wait <= 0) break;
-    // Real sleep, not a busy-wait: this poll now runs on every diagram-render
-    // bundle load (and after every fence render error), exactly while Chromium
-    // is parsing a 9MB page on the same machine — spinning a core competes
-    // with the work being awaited.
-    Bun.sleepSync(wait);
-  }
-  return false;
-}
-
-/**
- * Generate a PDF from the given tab. Uses --from-file when header/footer
- * templates are present (they can be HTML strings of arbitrary size).
- */
-export function pdf(opts: PdfOptions): void {
-  // If any large payload is present, send via --from-file
-  const hasLargePayload =
-    (opts.headerTemplate && opts.headerTemplate.length > 1024) ||
-    (opts.footerTemplate && opts.footerTemplate.length > 1024);
-
-  if (hasLargePayload) {
-    const payloadFile = writePayloadFile({
-      output: opts.output,
-      tabId: opts.tabId,
-      ...optionsToPdfFlags(opts),
-    });
-    try {
-      runBrowse(["pdf", "--from-file", payloadFile]);
-    } finally {
-      cleanupPayloadFile(payloadFile);
-    }
-    return;
-  }
-
-  // Small payload: pass flags via argv
-  const args = ["pdf", opts.output, "--tab-id", String(opts.tabId)];
-  pushFlagsFromOptions(args, opts);
-  runBrowse(args);
-}
-
-function optionsToPdfFlags(opts: PdfOptions): Record<string, unknown> {
-  // Shape mirrors what the browse `pdf` case expects when reading --from-file
-  const out: Record<string, unknown> = {};
-  if (opts.format) out.format = opts.format;
-  if (opts.width) out.width = opts.width;
-  if (opts.height) out.height = opts.height;
-  if (opts.marginTop) out.marginTop = opts.marginTop;
-  if (opts.marginRight) out.marginRight = opts.marginRight;
-  if (opts.marginBottom) out.marginBottom = opts.marginBottom;
-  if (opts.marginLeft) out.marginLeft = opts.marginLeft;
-  if (opts.headerTemplate !== undefined) out.headerTemplate = opts.headerTemplate;
-  if (opts.footerTemplate !== undefined) out.footerTemplate = opts.footerTemplate;
-  if (opts.pageNumbers !== undefined) out.pageNumbers = opts.pageNumbers;
-  if (opts.tagged !== undefined) out.tagged = opts.tagged;
-  if (opts.outline !== undefined) out.outline = opts.outline;
-  if (opts.printBackground !== undefined) out.printBackground = opts.printBackground;
-  if (opts.preferCSSPageSize !== undefined) out.preferCSSPageSize = opts.preferCSSPageSize;
-  if (opts.toc !== undefined) out.toc = opts.toc;
-  return out;
-}
-
-function pushFlagsFromOptions(args: string[], opts: PdfOptions): void {
-  if (opts.format) { args.push("--format", opts.format); }
-  if (opts.width) { args.push("--width", opts.width); }
-  if (opts.height) { args.push("--height", opts.height); }
-  if (opts.marginTop) { args.push("--margin-top", opts.marginTop); }
-  if (opts.marginRight) { args.push("--margin-right", opts.marginRight); }
-  if (opts.marginBottom) { args.push("--margin-bottom", opts.marginBottom); }
-  if (opts.marginLeft) { args.push("--margin-left", opts.marginLeft); }
-  if (opts.headerTemplate !== undefined) {
-    args.push("--header-template", opts.headerTemplate);
-  }
-  if (opts.footerTemplate !== undefined) {
-    args.push("--footer-template", opts.footerTemplate);
-  }
-  if (opts.pageNumbers === true) args.push("--page-numbers");
-  if (opts.tagged === true) args.push("--tagged");
-  if (opts.outline === true) args.push("--outline");
-  if (opts.printBackground === true) args.push("--print-background");
-  if (opts.preferCSSPageSize === true) args.push("--prefer-css-page-size");
-  if (opts.toc === true) args.push("--toc");
-}
@@ -7,11 +7,12 @@
 *   stderr: progress spinner per stage, final "Done in Xs. N pages."
 *   --quiet: suppress progress. Errors still print.
 *   --verbose: per-stage timings.
- *   exit 0 success / 1 bad args / 2 render error / 3 Paged.js timeout / 4 browse unavailable.
+ *   exit 0 success / 1 bad args / 2 render error / 3 Paged.js timeout / 4 no browser
+ *   (Aside not running AND gstack's own browser not built).
 */

 import { COMMANDS } from "./commands";
-import { ExitCode, BrowseClientError } from "./types";
+import { ExitCode, BrowserUnavailableError } from "./types";
 import type { GenerateOptions, PreviewOptions } from "./types";

 interface ParsedArgs {
@@ -119,7 +120,7 @@ function printUsage(): void {
  lines.push("  $P generate --watermark DRAFT memo.md draft.pdf");
  lines.push("  $P preview letter.md");
  lines.push("");
-  lines.push("Run `$P setup` to verify browse + Chromium + pdftotext install.");
+  lines.push("Run `$P setup` to verify the browser (Aside, or gstack's own fallback) + pdftotext install.");
  console.error(lines.join("\n"));
 }

@@ -265,9 +266,9 @@ async function main(): Promise<void> {
        process.exit(ExitCode.BadArgs);
    }
  } catch (err: any) {
-    if (err instanceof BrowseClientError) {
+    if (err instanceof BrowserUnavailableError) {
      console.error(`$P: ${err.message}`);
-      process.exit(ExitCode.BrowseUnavailable);
+      process.exit(ExitCode.BrowserUnavailable);
    }
    if (err?.code === "ENOENT") {
      console.error(`$P: file not found: ${err.path ?? err.message}`);
@@ -48,7 +48,7 @@ export const COMMANDS = new Map<string, {
    ],
  }],
  ["setup", {
-    description: "Verify browse + Chromium + pdftotext, then run a smoke test",
+    description: "Verify the browser (Aside, or gstack's own fallback) + pdftotext, then run a smoke test",
    usage: "setup",
    category: "Setup",
    flags: [],
@@ -6,8 +6,8 @@
 *        │        fences → placeholder tokens        │
 *        │                                           ▼
 *        └─▶ renderFenceSlots() ───────────▶ substituteSlots(html, slots)
- *             one browse render tab/run              │
- *             error ⇒ diagnostic block + page reload ▼
+ *             one browser render per batch           │
+ *             error ⇒ diagnostic block               ▼
 *                                          inlineLocalImages(html)
 *                                            data URIs, probe dims from bytes,
 *                                            downscale >2x content box @300dpi,
@@ -19,9 +19,11 @@
 * through the same sanitizer as user content before substitution (the bundle
 * renders with securityLevel strict — the sanitizer is the second layer).
 *
- * Reset contract (eng-review D6.2): each fence renders with a fresh
- * mermaid.render id; after ANY render error the bundle page is reloaded before
- * the next fence so a poisoned global can't corrupt diagram N+1.
+ * Bundle calls are batched: one render per batch (Aside runs one script per `aside repl` process) and
+ * nothing survives it, so every consumer collects its calls, runs them in one
+ * script (`BundleRun`), and substitutes the results. A failed call is data
+ * (diagnostic block / warning), never an abort. Each PDF run gets a fresh
+ * bundle page and each fence a fresh mermaid.render id (eng-review D6.2).
 */

 import * as fs from "node:fs";
@@ -30,7 +32,7 @@ import * as path from "node:path";
 import * as crypto from "node:crypto";
 import { fileURLToPath } from "node:url";

-import * as browseClient from "./browseClient";
+import { render as renderHtml, renderTmpDir } from "../../lib/aside-render";
 import { escapeHtml, sanitizeUntrustedHtml } from "./render";
 import { imageDims } from "./image-size";

@@ -72,8 +74,8 @@ export interface PrepassImageOptions {
  /** Physical content-box width in inches (page width minus margins). */
  contentWidthIn: number;
  warn: (msg: string) => void;
-  /** Lazily provides a ready bundle tab (only opened when needed). */
-  getTab: () => RenderTab | null;
+  /** Bundle runner for print-resolution downscaling; null = inline at full size. */
+  run: BundleRun | null;
 }

 /** Print-resolution policy (eng-review D4): downscale rasters wider than
@@ -289,145 +291,89 @@ function diagramLabel(fence: DiagramFence): string {
  return fence.title ?? `diagram ${fence.ordinal}`;
 }

-// ─── Render tab (bundle page lifecycle) ───────────────────────────────
+// ─── Bundle runner (diagram-render page, driven through Aside or gstack's browser) ────────
+
+export type BundleCall = { fn: string; args: unknown[] };
+export type BundleResult =
+  | { ok: true; value: string }
+  | { ok: false; error: string };
+/** Run bundle calls in order. Every call gets a result; failures are data. */
+export type BundleRun = (calls: BundleCall[]) => Promise<BundleResult[]>;

-const PAYLOAD_TMP_DIR = process.platform === "win32" ? os.tmpdir() : "/tmp";
 const READY_TIMEOUT_MS = 20_000;
-// Expressions bigger than this ship via `browse eval <file>` instead of argv.
-// 8KB is safe on every platform (Windows CreateProcess caps the WHOLE command
-// line at 32,767 chars; Linux MAX_ARG_STRLEN is ~128KiB) and the tmp-file
-// round-trip costs microseconds — one spawn regardless of payload size.
-const MAX_ARGV_EXPR_BYTES = 8_000;
+/** Aside caps a script at 120s (the browse path shares the budget); ~40 mermaid renders fit with room to spare. */
+const CALLS_PER_SCRIPT = 40;

-export class RenderTab {
-  private constructor(
-    public readonly tabId: number,
-    private readonly stagedBundlePath: string,
-  ) {}
-
-  /**
-   * Open a tab and load the diagram-render bundle. The bundle HTML is staged
-   * under /tmp (content-addressed, reused across runs — load-html only reads
-   * inside its safe dirs) and loaded by PATH, not --from-file: a 9MB JSON
-   * round-trip per run would be pure waste.
-   */
-  static open(): RenderTab {
-    const bundleSrc = resolveBundlePath();
-    const html = fs.readFileSync(bundleSrc);
-    const sha = crypto.createHash("sha256").update(html).digest("hex").slice(0, 16);
-    const staged = path.join(PAYLOAD_TMP_DIR, `gstack-diagram-render-${sha}.html`);
-    // Never trust an existing file at the predictable shared-/tmp name: verify
-    // its content hash and re-stage on mismatch (a pre-planted file would
-    // otherwise be loaded into the render tab as the bundle).
-    let needsWrite = true;
-    if (fs.existsSync(staged)) {
-      try {
-        const existing = crypto.createHash("sha256").update(fs.readFileSync(staged)).digest("hex").slice(0, 16);
-        needsWrite = existing !== sha;
-      } catch {
-        needsWrite = true;
-      }
-    }
-    if (needsWrite) {
-      // Concurrent-safe: write to a unique temp name, then atomic rename.
-      const tmp = `${staged}.${process.pid}.${crypto.randomBytes(4).toString("hex")}`;
-      fs.writeFileSync(tmp, html);
-      try {
-        fs.renameSync(tmp, staged);
-      } catch (renameErr) {
-        try { fs.unlinkSync(tmp); } catch { /* best-effort tmp cleanup */ }
-        // Only swallow the rename failure when the surviving file HASHES to
-        // the expected bundle (a concurrent writer won an OS-level race).
-        // Sticky-bit /tmp makes rename-over-foreign-file fail EPERM — if the
-        // survivor were trusted on existence alone, a pre-planted file would
-        // ride through the exact check added to stop it.
-        let survivorOk = false;
-        try {
-          const survivor = crypto.createHash("sha256").update(fs.readFileSync(staged)).digest("hex").slice(0, 16);
-          survivorOk = survivor === sha;
-        } catch { /* unreadable survivor = not ok */ }
-        if (!survivorOk) throw renameErr;
-      }
-    }
-    const tabId = browseClient.newtab();
-    const tab = new RenderTab(tabId, staged);
-    tab.loadBundle();
-    return tab;
-  }
-
-  /** (Re)load the bundle page — also the reset path after a render error. */
-  loadBundle(): void {
-    browseClient.loadHtmlFile({ file: this.stagedBundlePath, tabId: this.tabId });
-    const ready = browseClient.waitForExpression({
-      expression: "document.getElementById('status') !== null && document.getElementById('status').textContent === 'ready'",
-      tabId: this.tabId,
-      timeoutMs: READY_TIMEOUT_MS,
-    });
-    if (!ready) {
-      throw new Error(
-        "diagram-render bundle did not become ready in the browse tab " +
-        `(${READY_TIMEOUT_MS}ms). Check \`browse js "window.__errors"\` on tab ${this.tabId}.`,
-      );
-    }
-  }
-
-  /**
-   * Call one of the bundle's async window functions with JSON-safe string
-   * args. Errors come back as a recognizable ERR: prefix so a render failure
-   * is data, not a thrown browse exit.
-   */
-  call(fn: string, ...args: Array<string | number>): string {
-    const argList = args.map((a) => JSON.stringify(a)).join(",");
-    const expression =
-      `window.${fn}(${argList})` +
-      `.then(r => "OK:" + r)` +
-      `.catch(e => "ERR:" + String((e && e.message) || e))`;
-    const result = this.js(expression);
-    if (result.startsWith("OK:")) return result.slice(3);
-    if (result.startsWith("ERR:")) throw new RenderCallError(result.slice(4));
-    throw new RenderCallError(`unexpected bundle result: ${result.slice(0, 200)}`);
-  }
-
-  private js(expression: string): string {
-    // Large payloads (scene JSON, SVG text, data URIs) blow past argv limits —
-    // browseClient.js shells out with the expression as an argv element. The
-    // limit is BYTES, not chars (CJK content is 3x its char count in UTF-8),
-    // and Windows caps the whole command line at 32,767 chars — so anything
-    // big ships via `browse eval <file>` instead: one spawn, any size.
-    if (Buffer.byteLength(expression, "utf8") <= MAX_ARGV_EXPR_BYTES) {
-      return browseClient.js({ expression, tabId: this.tabId });
-    }
-    return this.jsViaFile(expression);
-  }
-
-  /** argv-safe path for big expressions: stage to a tmp file under browse's
-   *  safe dirs and run `browse eval <file>` (one spawn regardless of size). */
-  private jsViaFile(expression: string): string {
-    const file = path.join(
-      PAYLOAD_TMP_DIR,
-      `gstack-diagram-expr-${process.pid}-${crypto.randomBytes(4).toString("hex")}.js`,
-    );
-    fs.writeFileSync(file, expression, "utf8");
+/**
+ * Build the runner. The bundle path resolves lazily on the first call so an
+ * image-only document never touches it; a missing bundle fails every call
+ * with the resolver's message instead of throwing.
+ */
+export function bundleRunner(opts: { bundlePath?: string; render?: typeof renderHtml } = {}): BundleRun {
+  const render = opts.render ?? renderHtml;
+  let bundlePath = opts.bundlePath;
+  return async (calls) => {
+    const results: BundleResult[] = [];
    try {
-      return browseClient.evalFile({ file, tabId: this.tabId });
-    } finally {
-      try { fs.unlinkSync(file); } catch { /* best-effort tmp cleanup */ }
+      if (calls.length > 0) bundlePath ??= resolveBundlePath();
+      for (let i = 0; i < calls.length; i += CALLS_PER_SCRIPT) {
+        results.push(...await runScript(bundlePath!, calls.slice(i, i + CALLS_PER_SCRIPT), render));
+      }
+    } catch (err: any) {
+      // Unresolvable/unreadable bundle, staging failure: fail what's left as data.
+      const error = firstLine(err?.message ?? String(err));
+      while (results.length < calls.length) results.push({ ok: false, error });
    }
-  }
-
-  close(): void {
-    try {
-      browseClient.closetab(this.tabId);
-    } catch {
-      // best-effort: orchestrator finally path
-    }
-  }
+    return results;
+  };
 }

-export class RenderCallError extends Error {
-  constructor(msg: string) {
-    super(msg);
-    this.name = "RenderCallError";
+/**
+ * One render (an Aside script, or a browse tab): open the bundle, wait for #done, evaluate one expression
+ * per call, write each result to a file and read them back. The bundle copy
+ * and one JSON args file per call sit in a private dir served over loopback,
+ * so multi-MB payloads (data URIs, scene JSON) never ride argv; results are
+ * files too (never inline stdout) so SVG/PNG text survives intact.
+ */
+async function runScript(
+  bundlePath: string,
+  calls: BundleCall[],
+  render: typeof renderHtml,
+): Promise<BundleResult[]> {
+  const dir = fs.mkdtempSync(path.join(renderTmpDir(), "make-pdf-diagrams-"));
+  try {
+    const bundle = path.join(dir, "diagram-render.html");
+    fs.copyFileSync(bundlePath, bundle, fs.constants.COPYFILE_FICLONE);
+    const steps = calls.map((call, i) => {
+      fs.writeFileSync(path.join(dir, `call-${i}.json`), JSON.stringify(call.args));
+      // try/catch INSIDE the expression: a throwing fence returns an ERR
+      // marker and the script keeps going for the other fences. The URL is
+      // resolved against location.href, not the document base: the bundle
+      // sets <base href="https://gstack-render.localhost/"> for excalidraw.
+      const expression =
+        `(async () => { try { const a = await (await fetch(new URL("call-${i}.json", location.href).href)).json(); ` +
+        `return "OK:" + await window[${JSON.stringify(call.fn)}](...a); } ` +
+        `catch (e) { return "ERR:" + String((e && e.message) || e); } })()`;
+      return { kind: "eval" as const, expression, out: path.join(dir, `result-${i}.txt`) };
+    });
+    const r = await render({
+      file: bundle,
+      serveRoot: dir,
+      waitFor: { selector: "#done", timeoutMs: READY_TIMEOUT_MS },
+      steps,
+    });
+    if (!r.ok) {
+      const error = `diagram renderer: ${firstLine(r.error ?? "unknown error")}`;
+      return calls.map(() => ({ ok: false, error }));
+    }
+    return calls.map((_, i) => {
+      const text = fs.readFileSync(path.join(dir, `result-${i}.txt`), "utf8");
+      if (text.startsWith("OK:")) return { ok: true, value: text.slice(3) };
+      if (text.startsWith("ERR:")) return { ok: false, error: text.slice(4) };
+      return { ok: false, error: `unexpected bundle result: ${text.slice(0, 200)}` };
+    });
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
  }
 }

@@ -457,38 +403,39 @@ export function resolveBundlePath(env: NodeJS.ProcessEnv = process.env): string
 // ─── Fence rendering ──────────────────────────────────────────────────

 /**
- * Render every extracted fence to its slot HTML. One bundle tab serves all
- * fences; a failed fence yields a diagnostic block and a bundle reload
- * (reset contract) before the next fence renders.
+ * Render every extracted fence to its slot HTML in one batch. A failed fence
+ * yields a visible diagnostic block; the others still render.
 */
-export function renderFenceSlots(
+export async function renderFenceSlots(
  fences: DiagramFence[],
-  tab: RenderTab,
+  run: BundleRun,
  warn: (msg: string) => void,
-): Map<string, string> {
+): Promise<Map<string, string>> {
  const slots = new Map<string, string>();
+  const fail = (fence: DiagramFence, msg: string) => {
+    warn(`diagram ${fence.ordinal} (${fence.lang}) failed to render: ${firstLine(msg)}`);
+    slots.set(fence.token, buildDiagnosticBlock(fence, msg));
+  };
+  const todo: DiagramFence[] = [];
  for (const fence of fences) {
-    try {
-      let svg: string;
-      if (fence.lang === "mermaid") {
-        svg = tab.call("__renderMermaid", `mermaid-fence-${fence.ordinal}`, fence.source);
-      } else {
-        JSON.parse(fence.source); // fail fast with a JSON diagnostic, not a bundle stack
-        svg = tab.call("__excalidrawToSvg", fence.source);
-      }
-      slots.set(fence.token, buildDiagramFigure(fence, svg));
-    } catch (err: any) {
-      const msg = err?.message ?? String(err);
-      warn(`diagram ${fence.ordinal} (${fence.lang}) failed to render: ${firstLine(msg)}`);
-      slots.set(fence.token, buildDiagnosticBlock(fence, msg));
-      // Reset contract: a poisoned page must not corrupt the next fence.
+    if (fence.lang !== "mermaid") {
      try {
-        tab.loadBundle();
-      } catch (reloadErr: any) {
-        warn(`bundle reload after render error failed: ${firstLine(reloadErr?.message ?? String(reloadErr))}`);
+        JSON.parse(fence.source); // fail fast with a JSON diagnostic, not a bundle stack
+      } catch (err: any) {
+        fail(fence, err?.message ?? String(err));
+        continue;
      }
    }
+    todo.push(fence);
  }
+  const results = await run(todo.map((f) => f.lang === "mermaid"
+    ? { fn: "__renderMermaid", args: [`mermaid-fence-${f.ordinal}`, f.source] }
+    : { fn: "__excalidrawToSvg", args: [f.source] }));
+  todo.forEach((fence, i) => {
+    const r = results[i];
+    if (r.ok) slots.set(fence.token, buildDiagramFigure(fence, r.value));
+    else fail(fence, r.error);
+  });
  return slots;
 }

@@ -498,15 +445,26 @@ export function renderFenceSlots(
 * Replace inline diagram SVGs (and svg data-URI images) with PNG <img> tags
 * for the DOCX export — Word's SVG support is unreliable, so the content-
 * fidelity contract embeds rasters at 300dpi of the placed width (the
- * content box). Diagnostic blocks keep their text form.
+ * content box). Diagnostic blocks keep their text form. Two passes: swap
+ * each target for a token while collecting its bundle call, run the batch,
+ * substitute results.
 */
-export function rasterizeDiagramFigures(
+export async function rasterizeDiagramFigures(
  html: string,
-  tab: RenderTab,
+  run: BundleRun,
  contentWidthIn: number,
  warn: (msg: string) => void,
-): string {
+): Promise<string> {
  const targetPx = Math.round(contentWidthIn * PRINT_DPI);
+  const runId = crypto.randomBytes(4).toString("hex");
+  const calls: BundleCall[] = [];
+  const pending: Array<{ token: string; onOk: (png: string) => string; onErr: (reason: string) => string }> = [];
+  const enqueue = (svgText: string, onOk: (png: string) => string, onErr: (reason: string) => string): string => {
+    const token = `gstack-raster-slot-${runId}-${calls.length}`;
+    calls.push({ fn: "__rasterize", args: [svgText, targetPx] });
+    pending.push({ token, onOk, onErr });
+    return token;
+  };

  // 1. Rendered diagram figures → <img> with the figure's aria-label as alt.
  let out = html.replace(
@@ -515,21 +473,21 @@ export function rasterizeDiagramFigures(
      const svgMatch = figure.match(/<svg\b[\s\S]*<\/svg>/i);
      if (!svgMatch) return figure;
      const label = figure.match(/\baria-label\s*=\s*"([^"]*)"/i)?.[1] ?? "diagram";
-      try {
-        const png = tab.call("__rasterize", svgMatch[0], targetPx);
-        return `<p><img src="${png}" alt="${label}"></p>`;
-      } catch (err: any) {
-        const reason = firstLine(err?.message ?? String(err));
-        warn(`docx: diagram rasterization failed (${reason}); embedding source text instead`);
-        // The converter drops <figure>/<svg> entirely, so returning the figure
-        // would make the diagram vanish without a trace — the exact invisible
-        // failure the diagnostic contract forbids. Surface the source.
-        const source = decodeFigureSource(figure) ?? "(source unavailable)";
-        return [
-          `<p><strong>Diagram could not be rasterized for DOCX (${escapeHtml(reason)}) — source:</strong></p>`,
-          `<pre>${escapeHtml(source)}</pre>`,
-        ].join("\n");
-      }
+      return enqueue(
+        svgMatch[0],
+        (png) => `<p><img src="${png}" alt="${label}"></p>`,
+        (reason) => {
+          warn(`docx: diagram rasterization failed (${reason}); embedding source text instead`);
+          // The converter drops <figure>/<svg> entirely, so returning the figure
+          // would make the diagram vanish without a trace — the exact invisible
+          // failure the diagnostic contract forbids. Surface the source.
+          const source = decodeFigureSource(figure) ?? "(source unavailable)";
+          return [
+            `<p><strong>Diagram could not be rasterized for DOCX (${escapeHtml(reason)}) — source:</strong></p>`,
+            `<pre>${escapeHtml(source)}</pre>`,
+          ].join("\n");
+        },
+      );
    },
  );

@@ -538,18 +496,25 @@ export function rasterizeDiagramFigures(
    const m = tag.match(SRC_RE);
    const src = m?.[2] ?? m?.[3] ?? "";
    if (!src.startsWith("data:image/svg+xml")) return tag;
-    try {
-      const b64 = src.slice(src.indexOf(",") + 1);
-      const svgText = Buffer.from(b64, "base64").toString("utf8");
-      const png = tab.call("__rasterize", svgText, targetPx);
+    const svgText = Buffer.from(src.slice(src.indexOf(",") + 1), "base64").toString("utf8");
+    return enqueue(
+      svgText,
      // Function replacement: data URIs can contain $-patterns.
-      return tag.replace(SRC_RE, () => `src="${png}"`);
-    } catch (err: any) {
-      warn(`docx: svg image rasterization failed (${firstLine(err?.message ?? String(err))})`);
-      return tag;
-    }
+      (png) => tag.replace(SRC_RE, () => `src="${png}"`),
+      (reason) => {
+        warn(`docx: svg image rasterization failed (${reason})`);
+        return tag;
+      },
+    );
  });

+  if (calls.length === 0) return out;
+  const results = await run(calls);
+  pending.forEach((p, i) => {
+    const r = results[i];
+    // split/join, not replace(): the replacement carries user content.
+    out = out.split(p.token).join(r.ok ? p.onOk(r.value) : p.onErr(firstLine(r.error)));
+  });
  return out;
 }

@@ -581,14 +546,21 @@ const SRC_RE = /\bsrc\s*=\s*("([^"]*)"|'([^']*)')/i;
 * tab. Missing files become visible placeholders (or throw under --strict);
 * remote URLs warn (offline posture) unless --allow-network.
 */
-export function inlineLocalImages(html: string, opts: PrepassImageOptions): string {
+export async function inlineLocalImages(html: string, opts: PrepassImageOptions): Promise<string> {
  const maxPx = Math.round(opts.contentWidthIn * PRINT_DPI * DOWNSCALE_FACTOR);
  const targetPx = Math.round(opts.contentWidthIn * PRINT_DPI);
  // An image referenced N times is read/probed/downscaled once; the same data
  // URI string is reused (also dedupes memory until the final join).
  const memo = new Map<string, { dataUri: string; attrs: string }>();
+  // Oversized rasters get a token src in this pass and their downscaled bytes
+  // in the second — one bundle batch for the whole document.
+  const runId = crypto.randomBytes(4).toString("hex");
+  const downscales: Array<{
+    token: string; src: string; name: string; buf: Buffer; mime: string;
+    dims: { width: number; height: number };
+  }> = [];

-  return html.replace(IMG_TAG_RE, (tag) => {
+  const out = html.replace(IMG_TAG_RE, (tag) => {
    const srcMatch = tag.match(SRC_RE);
    if (!srcMatch) return tag;
    const src = srcMatch[2] ?? srcMatch[3] ?? "";
@@ -675,38 +647,54 @@ export function inlineLocalImages(html: string, opts: PrepassImageOptions): stri
      return buildMissingImagePlaceholder(src);
    }

-    let buf = fs.readFileSync(filePath);
-    let dims = imageDims(buf);
-    let mime = dims?.mime ?? mimeFromExtension(filePath);
+    const buf = fs.readFileSync(filePath);
+    const dims = imageDims(buf);
+    const mime = dims?.mime ?? mimeFromExtension(filePath);

    // Print-resolution normalization (D4): rasters only — SVG scales free.
-    if (dims && mime !== "image/svg+xml" && dims.width > maxPx) {
-      const tab = opts.getTab();
-      if (tab) {
-        try {
-          const dataUri = `data:${mime};base64,${buf.toString("base64")}`;
-          const scaled = tab.call("__downscaleRaster", dataUri, targetPx, mime);
-          const scaledB64 = scaled.replace(/^data:[^,]*,/, "");
-          opts.warn(
-            `downscaled ${path.basename(filePath)} ${dims.width}px → ${targetPx}px ` +
-            `(print is ${PRINT_DPI}dpi; original exceeds ${maxPx}px content-box ceiling)`,
-          );
-          buf = Buffer.from(scaledB64, "base64");
-          mime = scaled.slice(5, scaled.indexOf(";"));
-          dims = { ...dims, height: Math.round((dims.height * targetPx) / dims.width), width: targetPx };
-        } catch (err: any) {
-          opts.warn(`downscale failed for ${src}, inlining at full size: ${firstLine(err?.message ?? String(err))}`);
-        }
-      }
+    if (dims && mime !== "image/svg+xml" && dims.width > maxPx && opts.run) {
+      const token = `gstack-downscale-slot-${runId}-${downscales.length}`;
+      downscales.push({ token, src, name: path.basename(filePath), buf, mime, dims });
+      memo.set(filePath, { dataUri: token, attrs: "" });
+      return rewriteImgTag(tag, memo.get(filePath)!);
    }

-    const dataUri = `data:${mime};base64,${buf.toString("base64")}`;
-    const attrs = dims
-      ? ` data-gstack-px-width="${Math.round(dims.width)}" data-gstack-px-height="${Math.round(dims.height)}"`
-      : "";
-    memo.set(filePath, { dataUri, attrs });
+    memo.set(filePath, inlineEntry(buf, mime, dims));
    return rewriteImgTag(tag, memo.get(filePath)!);
  });
+
+  if (downscales.length === 0) return out;
+  const results = await opts.run!(downscales.map((d) => ({
+    fn: "__downscaleRaster",
+    args: [`data:${d.mime};base64,${d.buf.toString("base64")}`, targetPx, d.mime],
+  })));
+  const byToken = new Map<string, { dataUri: string; attrs: string }>();
+  downscales.forEach((d, i) => {
+    const r = results[i];
+    if (r.ok) {
+      opts.warn(
+        `downscaled ${d.name} ${d.dims.width}px → ${targetPx}px ` +
+        `(print is ${PRINT_DPI}dpi; original exceeds ${maxPx}px content-box ceiling)`,
+      );
+      const height = Math.round((d.dims.height * targetPx) / d.dims.width);
+      byToken.set(d.token, { dataUri: r.value, attrs: dimAttrs({ width: targetPx, height }) });
+    } else {
+      opts.warn(`downscale failed for ${d.src}, inlining at full size: ${firstLine(r.error)}`);
+      byToken.set(d.token, inlineEntry(d.buf, d.mime, d.dims));
+    }
+  });
+  return out.replace(IMG_TAG_RE, (tag) => {
+    const entry = byToken.get(tag.match(SRC_RE)?.[2] ?? "");
+    return entry ? rewriteImgTag(tag, entry) : tag;
+  });
+}
+
+function inlineEntry(buf: Buffer, mime: string, dims: { width: number; height: number } | null): { dataUri: string; attrs: string } {
+  return { dataUri: `data:${mime};base64,${buf.toString("base64")}`, attrs: dims ? dimAttrs(dims) : "" };
+}
+
+function dimAttrs(dims: { width: number; height: number }): string {
+  return ` data-gstack-px-width="${Math.round(dims.width)}" data-gstack-px-height="${Math.round(dims.height)}"`;
 }

 /** Apply a memoized inline result to an img tag. */
@@ -1,5 +1,6 @@
 /**
- * Orchestrator — ties render, browseClient, and filesystem together.
+ * Orchestrator — ties render, the diagram pre-pass, asideClient, and the
+ * filesystem together.
 *
 *   generate(opts): markdown → PDF on disk. Returns output path.
 *   preview(opts):  markdown → HTML, opens it in a browser.
@@ -9,23 +10,26 @@
 *   - stderr: spinner + per-stage status lines, unless opts.quiet.
 *   - --verbose: stage timings.
 *
- * Tab lifecycle: every generate opens a dedicated tab via $B newtab --json,
- * runs load-html/js/pdf against --tab-id <N>, and closes the tab in a
- * try/finally. Parallel $P generate calls never race on the active tab.
+ * Every browser step is its own lib/aside-render `render()` call (an Aside
+ * script when Aside is running, otherwise a tab in gstack's own headless
+ * browser; nothing persists between them): one batch for diagram fences, one
+ * for oversized-image downscales, one for DOCX rasters, one print. Parallel
+ * $P generate calls never share state.
 */

 import * as fs from "node:fs";
+import * as os from "node:os";
 import * as path from "node:path";
-import * as crypto from "node:crypto";
 import { spawn } from "node:child_process";

 import { render } from "./render";
 import { screenCss } from "./print-css";
 import type { GenerateOptions, PreviewOptions } from "./types";
 import { ExitCode } from "./types";
-import * as browseClient from "./browseClient";
+import { pickEngine } from "../../lib/aside-render";
+import { renderPdf } from "./asideClient";
 import {
-  RenderTab,
+  bundleRunner,
  contentWidthInches,
  convertDiagnosticsForDocx,
  extractDiagramFences,
@@ -37,6 +41,9 @@ import {
 } from "./diagram-prepass";
 import { applyImagePolicy } from "./image-policy";

+/** Default output location (`$P generate letter.md` → /tmp/letter.pdf). */
+export const OUTPUT_TMP_DIR = process.platform === "win32" ? os.tmpdir() : "/tmp";
+
 class ProgressReporter {
  private readonly quiet: boolean;
  private readonly verbose: boolean;
@@ -85,7 +92,7 @@ export async function generate(opts: GenerateOptions): Promise<string> {

  const to = opts.to ?? "pdf";
  const outputPath = path.resolve(
-    opts.output ?? path.join(browseClient.PAYLOAD_TMP_DIR, `${deriveSlug(input)}.${to}`),
+    opts.output ?? path.join(OUTPUT_TMP_DIR, `${deriveSlug(input)}.${to}`),
  );

  // Stage 1: read markdown
@@ -94,7 +101,7 @@ export async function generate(opts: GenerateOptions): Promise<string> {
  progress.end("Reading markdown");

  // Stage 1.5: diagram pre-pass — extract ```mermaid/```excalidraw fences and
-  // swap in placeholder tokens. Rendering happens after the tab opens below.
+  // swap in placeholder tokens. Rendering happens in Stage 2.5 below.
  const extraction = extractDiagramFences(markdown);

  // Stage 2: render HTML
@@ -120,87 +127,52 @@ export async function generate(opts: GenerateOptions): Promise<string> {
  });
  progress.end("Rendering HTML", `${rendered.meta.wordCount} words`);

-  // Stage 2.5: render diagram fences in a dedicated bundle tab, substitute
-  // slots, then inline + probe + (if oversized) downscale local images.
-  // The bundle tab is lazy: image-only documents open it only when a raster
-  // actually needs print-resolution downscaling (eng-review D4).
+  // Stage 2.5: render diagram fences through the bundle, substitute slots,
+  // then inline + probe + (if oversized) downscale local images. The runner
+  // resolves the bundle lazily, so image-only documents never touch it; a
+  // missing bundle or missing browser surfaces per fence as a diagnostic block.
  const warn = (msg: string) => {
    if (!opts.quiet) process.stderr.write(`\r\x1b[K[make-pdf] warning: ${msg}\n`);
  };
-  let renderTab: RenderTab | null = null;
+  const run = bundleRunner();
  let hasLandscape = false;
-  const getRenderTab = (): RenderTab | null => {
-    if (renderTab) return renderTab;
-    try {
-      renderTab = RenderTab.open();
-    } catch (err: any) {
-      warn(`diagram-render tab unavailable: ${String(err?.message ?? err).split("\n")[0]}`);
-      return null;
-    }
-    return renderTab;
-  };

  let finalHtml = rendered.html;
-  try {
-    if (extraction.fences.length > 0) {
-      progress.begin(`Rendering ${extraction.fences.length} diagram(s)`);
-      const tab = getRenderTab();
-      if (tab) {
-        const slots = renderFenceSlots(extraction.fences, tab, warn);
-        finalHtml = substituteSlots(finalHtml, slots);
-      } else {
-        // No bundle/tab: visible diagnostic beats silent raw tokens.
-        const slots = new Map(
-          extraction.fences.map((f) => [
-            f.token,
-            `<figure class="diagram diagram-error" role="img" aria-label="diagram ${f.ordinal} (not rendered)">` +
-            `<figcaption class="diagram-error-title">Diagram not rendered (${f.lang}) — diagram-render bundle unavailable</figcaption></figure>`,
-          ]),
-        );
-        finalHtml = substituteSlots(finalHtml, slots);
-      }
-      progress.end(`Rendering ${extraction.fences.length} diagram(s)`);
+  if (extraction.fences.length > 0) {
+    progress.begin(`Rendering ${extraction.fences.length} diagram(s)`);
+    finalHtml = substituteSlots(finalHtml, await renderFenceSlots(extraction.fences, run, warn));
+    progress.end(`Rendering ${extraction.fences.length} diagram(s)`);
+  }
+
+  progress.begin("Inlining images");
+  const contentWidthIn = contentWidthInches(opts);
+  finalHtml = await inlineLocalImages(finalHtml, {
+    inputDir: path.dirname(input),
+    strict: opts.strict === true,
+    allowNetwork: opts.allowNetwork === true,
+    contentWidthIn,
+    warn,
+    run,
+  });
+  progress.end("Inlining images");
+
+  // Width directives + conservative auto-landscape (image-policy).
+  const policy = applyImagePolicy(finalHtml, {
+    contentWidthIn,
+    landscape: landscapeContentBox(opts),
+    warn,
+  });
+  finalHtml = policy.html;
+  hasLandscape = policy.hasLandscape;
+
+  // DOCX needs rasters, not inline SVG (Word's SVG support is unreliable).
+  if (to === "docx") {
+    if (/<figure class="diagram"|data:image\/svg\+xml/.test(finalHtml)) {
+      progress.begin("Rasterizing diagrams for DOCX");
+      finalHtml = await rasterizeDiagramFigures(finalHtml, run, contentWidthIn, warn);
+      progress.end("Rasterizing diagrams for DOCX");
    }
-
-    progress.begin("Inlining images");
-    const contentWidthIn = contentWidthInches(opts);
-    finalHtml = inlineLocalImages(finalHtml, {
-      inputDir: path.dirname(input),
-      strict: opts.strict === true,
-      allowNetwork: opts.allowNetwork === true,
-      contentWidthIn,
-      warn,
-      getTab: getRenderTab,
-    });
-    progress.end("Inlining images");
-
-    // Width directives + conservative auto-landscape (image-policy).
-    const policy = applyImagePolicy(finalHtml, {
-      contentWidthIn,
-      landscape: landscapeContentBox(opts),
-      warn,
-    });
-    finalHtml = policy.html;
-    hasLandscape = policy.hasLandscape;
-
-    // DOCX needs rasters, not inline SVG (Word's SVG support is unreliable) —
-    // do it while the render tab is still open.
-    if (to === "docx") {
-      const needsRaster = /<figure class="diagram"|data:image\/svg\+xml/.test(finalHtml);
-      if (needsRaster) {
-        progress.begin("Rasterizing diagrams for DOCX");
-        const tab = getRenderTab();
-        if (tab) {
-          finalHtml = rasterizeDiagramFigures(finalHtml, tab, contentWidthIn, warn);
-        } else {
-          warn("docx: no render tab — diagrams keep their source text form");
-        }
-        progress.end("Rasterizing diagrams for DOCX");
-      }
-      finalHtml = convertDiagnosticsForDocx(finalHtml);
-    }
-  } finally {
-    renderTab?.close();
+    finalHtml = convertDiagnosticsForDocx(finalHtml);
  }

  // ─── --to html: write the self-contained document, no print round-trip ──
@@ -244,74 +216,44 @@ export async function generate(opts: GenerateOptions): Promise<string> {
    return outputPath;
  }

-  // Stage 3: write HTML to a tmp file browse can read
-  // (We don't actually write it; we pass inline via --from-file JSON.)
-  // But for preview mode and debugging, we still write to tmp.
-  const htmlTmp = tmpFile("html");
-  fs.writeFileSync(htmlTmp, finalHtml, "utf8");
-
-  // Stage 4: spin up a dedicated tab, load HTML, (wait for Paged.js if TOC),
-  // then emit PDF. Always close the tab.
-  progress.begin("Opening tab");
-  const tabId = browseClient.newtab();
-  progress.end("Opening tab", `tabId=${tabId}`);
-
-  try {
-    progress.begin("Loading HTML into Chromium");
-    browseClient.loadHtml({
-      html: finalHtml,
-      waitUntil: "domcontentloaded",
-      tabId,
-    });
-    progress.end("Loading HTML into Chromium");
-
-    if (opts.toc) {
-      progress.begin("Paginating with Paged.js");
-      // Browse's $B pdf already waits internally when --toc is passed.
-      // We pass toc=true to browseClient.pdf() below.
-      progress.end("Paginating with Paged.js", "Paged.js after");
-    }
-
-    progress.begin("Generating PDF");
-    browseClient.pdf({
-      output: outputPath,
-      tabId,
-      format: opts.pageSize ?? "letter",
-      marginTop: opts.marginTop ?? opts.margins ?? "1in",
-      marginRight: opts.marginRight ?? opts.margins ?? "1in",
-      marginBottom: opts.marginBottom ?? opts.margins ?? "1in",
-      marginLeft: opts.marginLeft ?? opts.margins ?? "1in",
-      headerTemplate: opts.headerTemplate,
-      footerTemplate: opts.footerTemplate,
-      // CSS is the single source of truth for page numbers (see print-css.ts
-      // @bottom-center). Chromium's native numbering always off to avoid double
-      // footers. The CSS layer honors pageNumbers + footerTemplate via render().
-      pageNumbers: false,
-      tagged: opts.tagged !== false,
-      outline: opts.outline !== false,
-      printBackground: !!opts.watermark,
-      // Named landscape pages only take effect when Chromium honors CSS page
-      // sizes. Flip it ONLY when a promotion exists — minimal behavior change
-      // for every other document.
-      preferCSSPageSize: hasLandscape ? true : undefined,
-      toc: opts.toc,
-    });
-    progress.end("Generating PDF");
-
-    const stat = fs.statSync(outputPath);
-    const kb = Math.round(stat.size / 1024);
-    progress.done(`${rendered.meta.wordCount} words · ${kb}KB · ${outputPath}`);
-  } finally {
-    // Always clean up the tab — even on crash, timeout, or Chromium hang.
-    try {
-      browseClient.closetab(tabId);
-    } catch {
-      // best-effort; we already exited the main path
-    }
-    // Cleanup tmp HTML
-    try { fs.unlinkSync(htmlTmp); } catch { /* best-effort */ }
+  // Stage 3: print — one render: serve the staged HTML over loopback, (wait
+  // ≤3s for Paged.js if --toc), print through whichever browser is up.
+  const engine = pickEngine().engine;
+  const via = engine === "aside" ? "Aside" : engine === "browse" ? "gstack's browser" : "a browser";
+  progress.begin(`Rendering PDF through ${via}`);
+  const used = await renderPdf(finalHtml, {
+    output: outputPath,
+    format: opts.pageSize ?? "letter",
+    marginTop: opts.marginTop ?? opts.margins ?? "1in",
+    marginRight: opts.marginRight ?? opts.margins ?? "1in",
+    marginBottom: opts.marginBottom ?? opts.margins ?? "1in",
+    marginLeft: opts.marginLeft ?? opts.margins ?? "1in",
+    headerTemplate: opts.headerTemplate,
+    footerTemplate: opts.footerTemplate,
+    // CSS is the single source of truth for page numbers (see print-css.ts
+    // @bottom-center). Chromium's native numbering always off to avoid double
+    // footers. The CSS layer honors pageNumbers + footerTemplate via render().
+    pageNumbers: false,
+    tagged: opts.tagged !== false,
+    outline: opts.outline !== false,
+    printBackground: !!opts.watermark,
+    // Named landscape pages only take effect when Chromium honors CSS page
+    // sizes. Flip it ONLY when a promotion exists — minimal behavior change
+    // for every other document.
+    preferCSSPageSize: hasLandscape ? true : undefined,
+    toc: opts.toc,
+  });
+  progress.end(`Rendering PDF through ${via}`);
+  if (used && used !== engine) {
+    // render() fell back mid-run (Aside quit or its CLI could not start): say
+    // which browser actually produced the file, since the label above was
+    // decided before the render.
+    process.stderr.write("  Aside was unavailable mid-run; the PDF was rendered through gstack's own browser.\n");
  }

+  const kb = Math.round(fs.statSync(outputPath).size / 1024);
+  progress.done(`${rendered.meta.wordCount} words · ${kb}KB · ${outputPath}`);
+
  return outputPath;
 }

@@ -327,7 +269,7 @@ export async function preview(opts: PreviewOptions): Promise<string> {

  progress.begin("Rendering HTML");
  const markdown = fs.readFileSync(input, "utf8");
-  // Preview deliberately skips the diagram/image pre-pass (no browse daemon
+  // Preview deliberately skips the diagram/image pre-pass (no browser
  // round-trip — preview is the fast loop). Be loud about the divergence so
  // nobody signs off on a preview that lacks what the PDF will have.
  if (!opts.quiet) {
@@ -357,7 +299,7 @@ export async function preview(opts: PreviewOptions): Promise<string> {
  progress.end("Rendering HTML", `${rendered.meta.wordCount} words`);

  // Write to a stable path under /tmp so the user can reload in the same tab.
-  const previewPath = path.join(browseClient.PAYLOAD_TMP_DIR, `make-pdf-preview-${deriveSlug(input)}.html`);
+  const previewPath = path.join(OUTPUT_TMP_DIR, `make-pdf-preview-${deriveSlug(input)}.html`);
  fs.writeFileSync(previewPath, rendered.html, "utf8");

  progress.begin("Opening preview");
@@ -375,11 +317,6 @@ function deriveSlug(p: string): string {
  return base.replace(/[^a-zA-Z0-9-_]+/g, "-").slice(0, 64) || "document";
 }

-function tmpFile(ext: string): string {
-  const hash = crypto.randomBytes(6).toString("hex");
-  return path.join(browseClient.PAYLOAD_TMP_DIR, `make-pdf-${process.pid}-${hash}.${ext}`);
-}
-
 function tryOpen(pathOrUrl: string): void {
  const platform = process.platform;
  const cmd = platform === "darwin" ? "open" :
@@ -46,8 +46,6 @@ export interface PdftotextInfo {

 /**
 * Probe a base path for executability, honoring Windows extension suffixes.
- * Matches browseClient.ts:findExecutable — duplicated rather than shared
- * because the two modules already duplicate isExecutable for compile-isolation.
 */
 export function findExecutable(base: string): string | null {
  if (isExecutable(base)) return base;
@@ -144,6 +142,8 @@ export function resolvePopplerTool(

 function isExecutable(p: string): boolean {
  try {
+    // access(X_OK) is true for directories (the traverse bit); only regular files count.
+    if (!fs.statSync(p).isFile()) return false;
    fs.accessSync(p, fs.constants.X_OK);
    return true;
  } catch {
@@ -7,8 +7,8 @@
 *
 *   - Helvetica first, with Liberation Sans as a metric-compatible Linux
 *     fallback (Helvetica and Arial aren't installed on most Linux distros;
- *     Liberation Sans ships via the fonts-liberation package and Playwright's
- *     install-deps). No bundled webfonts — dodges the per-glyph Tj bug that
+ *     Liberation Sans ships via the fonts-liberation package). No bundled
+ *     webfonts — dodges the per-glyph Tj bug that
 *     breaks copy-paste extraction.
 *   - All paragraphs flush-left. No first-line indent, no justify, no
 *     p+p indent. text-align: left everywhere. 12pt margin-bottom.
@@ -1,5 +1,5 @@
 /**
- * Markdown → HTML renderer. Pure function, no I/O, no Playwright.
+ * Markdown → HTML renderer. Pure function, no I/O, no browser.
 *
 * Pipeline:
 *   1. marked parses markdown → HTML
@@ -51,7 +51,7 @@ export interface RenderOptions {
 }

 export interface RenderResult {
-  html: string;                   // full HTML document, ready for $B load-html
+  html: string;                   // full HTML document, staged and printed through the browser
  printCss: string;               // for debugging / preview
  bodyHtml: string;               // just the rendered body (tests, snapshots)
  meta: {
@@ -1,52 +1,56 @@
 /**
 * `$P setup` — guided smoke test.
 *
- * Flow (per the CEO plan CLI UX spec):
- *   1. Verify browse binary exists and responds
- *   2. Verify Chromium launches via $B goto about:blank
+ * 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. Open it
- *   6. Print a 3-command cheatsheet
+ *   5. Print a 3-command cheatsheet
 */

 import * as path from "node:path";
 import * as fs from "node:fs";

-import * as browseClient from "./browseClient";
+import { NO_BROWSER_HELP, pickEngine, render, renderTmpDir } from "../../lib/aside-render";
+import { ExitCode } from "./types";
 import { resolvePdftotext, PdftotextUnavailableError } from "./pdftotext";
-import { generate } from "./orchestrator";
+import { OUTPUT_TMP_DIR, generate } from "./orchestrator";

 export async function runSetup(): Promise<void> {
  process.stderr.write("make-pdf setup — verifying install\n\n");

-  // 1. Resolve browse binary
-  process.stderr.write("  [1/5] Checking browse binary...");
-  try {
-    const bin = browseClient.resolveBrowseBin();
-    process.stderr.write(` OK (${bin})\n`);
-  } catch (err: any) {
+  // 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${err.message}\n`);
-    process.exit(4);
+    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. Chromium smoke (navigate a dedicated tab to about:blank)
-  process.stderr.write("  [2/5] Launching Chromium...");
-  let chromiumTab: number | null = null;
+  // 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 {
-    chromiumTab = browseClient.newtab("about:blank");
-    process.stderr.write(` OK (tab ${chromiumTab})\n`);
+    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(`\nChromium failed to launch: ${err.message}\n`);
-    process.stderr.write("\nTo fix: run gstack setup from the gstack repo:\n");
-    process.stderr.write("  cd ~/.claude/skills/gstack && ./setup\n");
-    process.exit(4);
+    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 {
-    if (chromiumTab !== null) {
-      try { browseClient.closetab(chromiumTab); } catch { /* ignore */ }
-    }
+    fs.rmSync(smokeDir, { recursive: true, force: true });
  }

  // 3. pdftotext (optional — CI gate only)
@@ -76,8 +80,8 @@ export async function runSetup(): Promise<void> {
    "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(browseClient.PAYLOAD_TMP_DIR, `make-pdf-smoke-${process.pid}.md`);
-  const outPath = path.join(browseClient.PAYLOAD_TMP_DIR, `make-pdf-smoke-${process.pid}.pdf`);
+  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 {
@@ -18,7 +18,7 @@ export interface GenerateOptions {
  output?: string;                // output path (default: /tmp/<slug>.<ext>)

  // Output format (NOT --format, which is a --page-size alias):
-  //   pdf  — print-quality PDF via Chromium (default)
+  //   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;
@@ -82,32 +82,6 @@ export interface PreviewOptions {
  date?: string;
 }

-/**
- * Parsed page.pdf() options passed to browse.
- */
-export interface BrowsePdfOptions {
-  output: string;
-  tabId: number;
-  format?: PageSize;
-  width?: string;
-  height?: string;
-  margins?: {
-    top: string;
-    right: string;
-    bottom: string;
-    left: string;
-  };
-  headerTemplate?: string;
-  footerTemplate?: string;
-  pageNumbers?: boolean;
-  displayHeaderFooter?: boolean;
-  tagged?: boolean;
-  outline?: boolean;
-  printBackground?: boolean;
-  preferCSSPageSize?: boolean;
-  toc?: boolean;                  // signals browse to wait for Paged.js
-}
-
 /**
 * Exit codes for $P generate.
 * Mirror these in orchestrator error paths.
@@ -117,20 +91,19 @@ export const ExitCode = {
  BadArgs: 1,
  RenderError: 2,
  PagedJsTimeout: 3,
-  BrowseUnavailable: 4,
+  BrowserUnavailable: 4,
 } as const;
 export type ExitCode = typeof ExitCode[keyof typeof ExitCode];

 /**
- * Structured error for browse CLI shell-out failures.
+ * 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 BrowseClientError extends Error {
-  constructor(
-    public readonly exitCode: number,
-    public readonly command: string,
-    public readonly stderr: string,
-  ) {
-    super(`browse ${command} exited ${exitCode}: ${stderr.trim()}`);
-    this.name = "BrowseClientError";
+export class BrowserUnavailableError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "BrowserUnavailableError";
  }
 }
@@ -0,0 +1,151 @@
+/**
+ * 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/toc map to their CDP names", () => {
+    const o = pdfStepOptions({ output: "o", tagged: true, outline: true, printBackground: true, preferCSSPageSize: true, toc: true });
+    expect(o.generateTaggedPDF).toBe(true);
+    expect(o.generateDocumentOutline).toBe(true);
+    expect(o.printBackground).toBe(true);
+    expect(o.preferCSSPageSize).toBe(true);
+    expect(o.waitForPagedJs).toBe(true);
+    // 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();
+  });
+});
@@ -1,218 +0,0 @@
-/**
- * browseClient unit tests — binary resolution and error mapping.
- *
- * These are pure unit tests; they do NOT require a running browse daemon.
- * Cross-platform: assertions that pin POSIX behavior early-return on win32
- * and vice versa, so both lanes only exercise their own branch.
- */
-
-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 { BrowseClientError } from "../src/types";
-import { resolveBrowseBin, findExecutable } from "../src/browseClient";
-
-// A real, always-present executable for the test platform — `cmd.exe` on
-// Windows (System32 is on every install) and `/bin/sh` on POSIX. Lets the
-// "honors override when it points at a real executable" test work in both
-// lanes without writing a temp script.
-const REAL_EXE: string =
-  process.platform === "win32"
-    ? path.join(process.env.SystemRoot ?? "C:\\Windows", "System32", "cmd.exe")
-    : "/bin/sh";
-
-function withEnv<T>(overrides: Record<string, string | undefined>, fn: () => T): T {
-  const saved: Record<string, string | undefined> = {};
-  for (const k of Object.keys(overrides)) saved[k] = process.env[k];
-  for (const [k, v] of Object.entries(overrides)) {
-    if (v === undefined) delete process.env[k];
-    else process.env[k] = v;
-  }
-  try {
-    return fn();
-  } finally {
-    for (const [k, v] of Object.entries(saved)) {
-      if (v === undefined) delete process.env[k];
-      else process.env[k] = v;
-    }
-  }
-}
-
-describe("findExecutable", () => {
-  test("returns the bare path on POSIX when it's executable", () => {
-    if (process.platform === "win32") return;
-    const found = findExecutable("/bin/sh");
-    expect(found).toBe("/bin/sh");
-  });
-
-  test("on win32, probes .exe / .cmd / .bat after the bare-path miss", () => {
-    if (process.platform !== "win32") return;
-    // cmd.exe lives at System32\cmd.exe — probe with the bare base.
-    const base = path.join(process.env.SystemRoot ?? "C:\\Windows", "System32", "cmd");
-    const found = findExecutable(base);
-    expect(found).toBe(base + ".exe");
-  });
-
-  test("returns null when no extension matches", () => {
-    const found = findExecutable("/nonexistent/path/to/nothing");
-    expect(found).toBeNull();
-  });
-
-  // access(X_OK) is TRUE for directories — they carry the execute/traverse bit — so a
-  // bare X_OK test returned ~/.claude/skills/browse, the skill's docs folder, as "the
-  // browse binary". Every browse call then failed with an empty error, which surfaced
-  // as make-pdf reporting "Chromium failed to launch".
-  test("rejects a DIRECTORY even though it passes access(X_OK)", () => {
-    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "mkpdf-dir-"));
-    try {
-      // Prove the precondition: the directory really does pass the old test.
-      let passesXok = true;
-      try {
-        fs.accessSync(dir, fs.constants.X_OK);
-      } catch {
-        passesXok = false;
-      }
-      expect(passesXok).toBe(true);
-
-      expect(findExecutable(dir)).toBeNull();
-    } finally {
-      fs.rmSync(dir, { recursive: true, force: true });
-    }
-  });
-
-  test("rejects a directory that shadows a real binary name", () => {
-    // The exact shape of the bug: a directory named like the thing being looked for.
-    const base = fs.mkdtempSync(path.join(os.tmpdir(), "mkpdf-shadow-"));
-    const shadow = path.join(base, "browse");
-    fs.mkdirSync(shadow);
-    fs.writeFileSync(path.join(shadow, "SKILL.md"), "# not a binary\n");
-    try {
-      expect(findExecutable(shadow)).toBeNull();
-    } finally {
-      fs.rmSync(base, { recursive: true, force: true });
-    }
-  });
-});
-
-describe("resolveBrowseBin", () => {
-  test("throws BrowseClientError with setup hint when nothing is found", () => {
-    // Point overrides at non-existent paths and clear PATH so Bun.which finds
-    // nothing. Sibling/global probes go through findExecutable on real paths,
-    // but the test asserts on the error shape rather than depending on whether
-    // a real browse install exists on the box.
-    let thrown: unknown = null;
-    try {
-      withEnv(
-        {
-          GSTACK_BROWSE_BIN: "/nonexistent/gstack-browse-bin",
-          BROWSE_BIN: "/nonexistent/browse-bin",
-          PATH: "",
-          Path: "",
-        },
-        () => resolveBrowseBin(),
-      );
-    } catch (err) {
-      thrown = err;
-    }
-
-    if (thrown) {
-      expect(thrown).toBeInstanceOf(BrowseClientError);
-      expect((thrown as BrowseClientError).message).toContain("browse binary not found");
-      expect((thrown as BrowseClientError).message).toContain("./setup");
-      expect((thrown as BrowseClientError).message).toContain("GSTACK_BROWSE_BIN");
-      // Back-compat alias still surfaces in the diagnostic.
-      expect((thrown as BrowseClientError).message).toContain("BROWSE_BIN");
-    }
-    // If the test box has a real browse install on disk, sibling/global may
-    // resolve and the helper won't throw — that's fine; the assertion is
-    // gated on whether it threw at all.
-  });
-
-  test("honors GSTACK_BROWSE_BIN when it points at a real executable", () => {
-    const resolved = withEnv({ GSTACK_BROWSE_BIN: REAL_EXE }, () => resolveBrowseBin());
-    expect(resolved).toBe(REAL_EXE);
-  });
-
-  test("honors BROWSE_BIN as a back-compat alias", () => {
-    const resolved = withEnv(
-      { GSTACK_BROWSE_BIN: undefined, BROWSE_BIN: REAL_EXE },
-      () => resolveBrowseBin(),
-    );
-    expect(resolved).toBe(REAL_EXE);
-  });
-
-  test("GSTACK_BROWSE_BIN takes precedence over BROWSE_BIN", () => {
-    const resolved = withEnv(
-      { GSTACK_BROWSE_BIN: REAL_EXE, BROWSE_BIN: "/nonexistent/legacy" },
-      () => resolveBrowseBin(),
-    );
-    expect(resolved).toBe(REAL_EXE);
-  });
-
-  test("strips wrapping double quotes from override values", () => {
-    const resolved = withEnv({ GSTACK_BROWSE_BIN: `"${REAL_EXE}"` }, () => resolveBrowseBin());
-    expect(resolved).toBe(REAL_EXE);
-  });
-});
-
-describe("BrowseClientError", () => {
-  test("captures exit code, command, and stderr", () => {
-    const err = new BrowseClientError(127, "pdf", "Chromium not found");
-    expect(err.exitCode).toBe(127);
-    expect(err.command).toBe("pdf");
-    expect(err.stderr).toBe("Chromium not found");
-    expect(err.message).toContain("browse pdf exited 127");
-    expect(err.message).toContain("Chromium not found");
-    expect(err.name).toBe("BrowseClientError");
-  });
-});
-
-describe("resolveBrowseBin — sibling resolution from execPath (#2156)", () => {
-  // In a bun-compiled binary argv[0] is the raw invocation string (often
-  // relative), so the old dirname(argv[0]) built sibling candidates against
-  // the CWD. Under `bun test` the process path is the bun runtime, so these
-  // shapes are only reachable through the selfPath seam.
-
-  test("sibling browse next to the install dir is found via selfPath", () => {
-    const base = fs.mkdtempSync(path.join(os.tmpdir(), "mkpdf-sib-"));
-    try {
-      const distDir = path.join(base, "browse", "dist");
-      fs.mkdirSync(distDir, { recursive: true });
-      const sibling = path.join(distDir, "browse");
-      fs.writeFileSync(sibling, "#!/bin/sh\nexit 0\n", { mode: 0o755 });
-      const selfPath = path.join(base, "make-pdf", "dist", "pdf");
-      // Receipts: pre-fix code ignores the selfPath seam entirely, so it can
-      // never produce this sibling — it either finds a global install (wrong
-      // value) or throws (PATH is empty). Red on v1.68.3.0 either way.
-      const resolved = resolveBrowseBin({ PATH: "" }, selfPath);
-      expect(resolved).toBe(path.resolve(path.join(base, "make-pdf"), "../browse/dist/browse"));
-    } finally {
-      fs.rmSync(base, { recursive: true, force: true });
-    }
-  });
-
-  test("a decoy browse DIRECTORY near selfPath never shadows a real PATH binary", () => {
-    const base = fs.mkdtempSync(path.join(os.tmpdir(), "mkpdf-decoy-"));
-    try {
-      // The ~/.claude/skills/browse alias-directory shape from #2156: a
-      // directory named exactly like the third sibling candidate.
-      fs.mkdirSync(path.join(base, "browse"), { recursive: true });
-      const pathDir = path.join(base, "pathbin");
-      fs.mkdirSync(pathDir, { recursive: true });
-      const onPath = path.join(pathDir, "browse");
-      fs.writeFileSync(onPath, "#!/bin/sh\nexit 0\n", { mode: 0o755 });
-      const selfPath = path.join(base, "tools", "pdf");
-      // os.homedir() ignores a $HOME override under bun, so the global-install
-      // probe may legitimately win on boxes with a real ~/.claude install. The
-      // invariant under test is narrower: the decoy DIRECTORY never wins, and
-      // whatever wins is a regular file.
-      const resolved = resolveBrowseBin({ PATH: pathDir }, selfPath);
-      expect(resolved).not.toBe(path.join(base, "browse"));
-      expect(fs.statSync(resolved).isFile()).toBe(true);
-    } finally {
-      fs.rmSync(base, { recursive: true, force: true });
-    }
-  });
-});
@@ -0,0 +1,329 @@
+/**
+ * cli.ts error → exit code mapping, pinned through the REAL CLI process.
+ *
+ *   exit 0 success / 1 bad args / 2 render error / 3 Paged.js timeout / 4 no browser
+ *
+ * `main()` is not exported and runs only under `import.meta.main`, so the
+ * catch block cannot be driven in-process. Each case spawns `bun cli.ts`
+ * instead, two ways:
+ *
+ *   1. Stubbed orchestrator. A `--preload` file registers a Bun runtime plugin
+ *      whose onLoad swaps make-pdf/src/orchestrator.ts for a module whose
+ *      generate()/preview() throw a chosen error class. The stub imports
+ *      BrowserUnavailableError from the same types.ts cli.ts uses, so the
+ *      `instanceof` check in the catch block is exercised for real.
+ *   2. No stubs. Filesystem errors that need no browser (missing input, output
+ *      dir that does not exist), bad args, and fake `aside` / `browse` shell
+ *      scripts reached via GSTACK_BROWSE_BIN and a scrubbed PATH. The children
+ *      never see the real PATH, so no real browser is ever probed or launched.
+ *
+ * Exit 4 through an UNSTUBBED process is not forceable from inside this
+ * checkout: resolveBrowseBin() always finds <repo>/browse/dist/browse (a
+ * BROWSE_ROOTS entry computed from import.meta.dir), so the stubbed case (1)
+ * is the exit-4 pin here; make-pdf/test/asideClient.test.ts covers the
+ * renderFailure() classification that produces the error in the first place.
+ */
+
+import { afterAll, beforeAll, 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 { ExitCode } from "../src/types";
+import { NO_BROWSER, NO_BROWSER_HELP } from "../../lib/aside-render";
+
+const ROOT = path.resolve(import.meta.dir, "..", "..");
+const CLI = path.join(ROOT, "make-pdf", "src", "cli.ts");
+const TYPES = path.join(ROOT, "make-pdf", "src", "types.ts");
+const isWin = process.platform === "win32";
+
+let tmp: string;
+/** PATH for children: nothing on it (no `aside`, no `browse`, no `pdftotext`). */
+let emptyBin: string;
+/** PATH for children: only a fake `aside` that answers the probe but cannot run a script. */
+let fakeAsideBin: string;
+/** Fake browse daemon CLIs (reached via GSTACK_BROWSE_BIN, never PATH). */
+let browseOk: string;
+let browseRefusesNewtab: string;
+let inputMd: string;
+
+beforeAll(() => {
+  tmp = fs.mkdtempSync(path.join(os.tmpdir(), "make-pdf-cli-exit-"));
+  emptyBin = path.join(tmp, "empty-bin");
+  fs.mkdirSync(emptyBin);
+  fakeAsideBin = path.join(tmp, "fake-aside-bin");
+  fs.mkdirSync(fakeAsideBin);
+  inputMd = path.join(tmp, "in.md");
+  fs.writeFileSync(inputMd, "# Smoke\n\nOne paragraph is enough.\n", "utf8");
+
+  if (!isWin) {
+    // Answers `aside --version` and the ASIDE_READY probe like a live app, then
+    // fails every render script the way an Aside release that renamed its
+    // private CDP bridge would — the exact shape render() retries on browse.
+    writeScript(path.join(fakeAsideBin, "aside"), [
+      'case "$1" in',
+      '  --version) echo "aside 1.26.0-fake" ;;',
+      "  repl)",
+      '    case "$2" in',
+      '      *ASIDE_READY*) echo "ASIDE_READY /fake/aside/session" ;;',
+      '      *) echo "ReferenceError: openTab is not defined" ;;',
+      "    esac ;;",
+      "esac",
+      "exit 0",
+    ]);
+    browseOk = writeFakeBrowse("browse-ok", { pdf: true });
+    browseRefusesNewtab = writeFakeBrowse("browse-refuses-newtab", { newtabFails: true });
+  }
+});
+
+afterAll(() => {
+  fs.rmSync(tmp, { recursive: true, force: true });
+});
+
+// ─── helpers ──────────────────────────────────────────────────────────────────
+
+function writeScript(file: string, body: string[]): string {
+  // Builtins only (case/echo/read/printf): the children run with PATH scrubbed.
+  fs.writeFileSync(file, ["#!/bin/sh", ...body, ""].join("\n"), { mode: 0o755 });
+  return file;
+}
+
+/**
+ * A stand-in for gstack's browse daemon CLI: `newtab --json` hands out a tab,
+ * `js` answers with `pageText`, and `pdf --from-file <payload>` writes a fake
+ * PDF at the payload's `output` path (JSON parsed with parameter expansion).
+ */
+function writeFakeBrowse(name: string, opts: { pageText?: string; pdf?: boolean; newtabFails?: boolean }): string {
+  const body = ['case "$1" in'];
+  body.push(opts.newtabFails
+    ? '  newtab) echo "daemon refused: boom" >&2; exit 1 ;;'
+    : `  newtab) echo '{"tabId":7}' ;;`);
+  body.push(`  js) echo '${opts.pageText ?? "browser-ok"}' ;;`);
+  if (opts.pdf) {
+    body.push(
+      "  pdf)",
+      '    read -r payload < "$3"',
+      '    out="${payload#*\\"output\\":\\"}"',
+      '    out="${out%%\\"*}"',
+      "    printf '%%PDF-1.4 fake\\n' > \"$out\"",
+      "    ;;",
+    );
+  }
+  body.push("esac", "exit 0");
+  return writeScript(path.join(tmp, name), body);
+}
+
+/** Hermetic child env: no real PATH, Aside skipped unless a test opts back in. */
+function childEnv(extra: Record<string, string | undefined> = {}): Record<string, string> {
+  const env: Record<string, string> = {
+    PATH: emptyBin,
+    HOME: process.env.HOME ?? tmp,
+    TMPDIR: os.tmpdir(),
+    GSTACK_SKIP_ASIDE: "1",
+    NO_COLOR: "1",
+  };
+  for (const [k, v] of Object.entries(extra)) {
+    if (v === undefined) delete env[k];
+    else env[k] = v;
+  }
+  return env;
+}
+
+function runCli(args: string[], opts: { preload?: string; env?: Record<string, string> } = {}) {
+  const argv = [process.execPath, ...(opts.preload ? ["--preload", opts.preload] : []), CLI, ...args];
+  const r = Bun.spawnSync(argv, { cwd: ROOT, env: opts.env ?? childEnv(), stdout: "pipe", stderr: "pipe", stdin: "ignore", timeout: 120_000 });
+  return { code: r.exitCode, stdout: r.stdout.toString(), stderr: r.stderr.toString() };
+}
+
+const ORCHESTRATOR_FILTER = String.raw`make-pdf[/\\]src[/\\]orchestrator\.ts$`;
+
+/**
+ * Write a --preload file whose Bun plugin replaces the orchestrator module with
+ * one whose generate()/preview() `throw <throwExpr>`. `throwExpr` may reference
+ * BrowserUnavailableError (imported from the real types.ts, so instanceof holds).
+ */
+function stubOrchestrator(name: string, throwExpr: string): string {
+  const module = [
+    `import { BrowserUnavailableError } from ${JSON.stringify(TYPES)};`,
+    `export const OUTPUT_TMP_DIR = ${JSON.stringify(os.tmpdir())};`,
+    `export async function generate() { throw ${throwExpr}; }`,
+    `export async function preview() { throw ${throwExpr}; }`,
+    "",
+  ].join("\n");
+  const preload = [
+    "// Generated by make-pdf/test/cli-exit-codes.test.ts",
+    "Bun.plugin({",
+    '  name: "make-pdf-test-stub-orchestrator",',
+    "  setup(build) {",
+    `    build.onLoad({ filter: new RegExp(${JSON.stringify(ORCHESTRATOR_FILTER)}) }, () => ({ loader: "ts", contents: ${JSON.stringify(module)} }));`,
+    "  },",
+    "});",
+    "",
+  ].join("\n");
+  const file = path.join(tmp, `stub-${name}.preload.ts`);
+  fs.writeFileSync(file, preload, "utf8");
+  return file;
+}
+
+// ─── 1. error class → exit code (orchestrator stubbed) ────────────────────────
+
+describe("cli.ts maps the thrown error class to the exit code (orchestrator stubbed)", () => {
+  test("BrowserUnavailableError → exit 4, stderr is `$P: <message>`, stdout stays empty", () => {
+    const msg = `${NO_BROWSER}: ${NO_BROWSER_HELP} (NEEDS_ASIDE: stubbed)`;
+    const r = runCli(["generate", inputMd], {
+      preload: stubOrchestrator("no-browser", `new BrowserUnavailableError(${JSON.stringify(msg)})`),
+    });
+    expect(r.code).toBe(ExitCode.BrowserUnavailable);
+    expect(r.code).toBe(4);
+    expect(r.stderr.trim()).toBe(`$P: ${msg}`);
+    expect(r.stdout).toBe("");
+  });
+
+  test("a plain Error → exit 2 (render error): message only, the stack only with --verbose", () => {
+    const preload = stubOrchestrator("render-error", `new Error("PDF render failed: render script did not finish")`);
+    const quiet = runCli(["generate", inputMd], { preload });
+    expect(quiet.code).toBe(ExitCode.RenderError);
+    expect(quiet.code).toBe(2);
+    expect(quiet.stderr.trim()).toBe("$P: PDF render failed: render script did not finish");
+    expect(quiet.stdout).toBe("");
+
+    const verbose = runCli(["generate", inputMd, "--verbose"], { preload });
+    expect(verbose.code).toBe(ExitCode.RenderError);
+    const lines = verbose.stderr.trim().split("\n");
+    expect(lines[0]).toBe("$P: PDF render failed: render script did not finish");
+    expect(lines.length).toBeGreaterThan(1); // err.stack follows
+    expect(verbose.stderr).toMatch(/\bat\b/);
+    expect(verbose.stdout).toBe("");
+  });
+
+  test("an ENOENT-coded error → exit 1 (bad args) with `file not found: <path>`", () => {
+    const withPath = runCli(["generate", inputMd], {
+      preload: stubOrchestrator("enoent-path",
+        `Object.assign(new Error("ENOENT: no such file or directory, open '/x/in.md'"), { code: "ENOENT", errno: -2, syscall: "open", path: "/x/in.md" })`),
+    });
+    expect(withPath.code).toBe(ExitCode.BadArgs);
+    expect(withPath.code).toBe(1);
+    expect(withPath.stderr.trim()).toBe("$P: file not found: /x/in.md");
+    expect(withPath.stdout).toBe("");
+
+    // No `path` on the error: the message stands in.
+    const noPath = runCli(["generate", inputMd], {
+      preload: stubOrchestrator("enoent-nopath", `Object.assign(new Error("ENOENT: no such file or directory"), { code: "ENOENT" })`),
+    });
+    expect(noPath.code).toBe(ExitCode.BadArgs);
+    expect(noPath.stderr.trim()).toBe("$P: file not found: ENOENT: no such file or directory");
+  });
+
+  test("an error named PagedJsTimeout → exit 3", () => {
+    const r = runCli(["generate", inputMd], {
+      preload: stubOrchestrator("pagedjs", `Object.assign(new Error("Paged.js did not finish within 3000ms"), { name: "PagedJsTimeout" })`),
+    });
+    expect(r.code).toBe(ExitCode.PagedJsTimeout);
+    expect(r.code).toBe(3);
+    expect(r.stderr.trim()).toBe("$P: Paged.js did not finish within 3000ms");
+    expect(r.stdout).toBe("");
+  });
+
+  test("a non-Error throw is still reported (String(err)) and exits 2", () => {
+    const r = runCli(["generate", inputMd], { preload: stubOrchestrator("string-throw", `"boom"`) });
+    expect(r.code).toBe(ExitCode.RenderError);
+    expect(r.stderr.trim()).toBe("$P: boom");
+    expect(r.stdout).toBe("");
+  });
+
+  test("preview shares the same catch block: BrowserUnavailableError → exit 4", () => {
+    const r = runCli(["preview", inputMd], {
+      preload: stubOrchestrator("preview-no-browser", `new BrowserUnavailableError("${NO_BROWSER}: stubbed")`),
+    });
+    expect(r.code).toBe(ExitCode.BrowserUnavailable);
+    expect(r.stderr.trim()).toBe(`$P: ${NO_BROWSER}: stubbed`);
+    expect(r.stdout).toBe("");
+  });
+});
+
+// ─── 2. real error paths that need no browser (no stubs) ──────────────────────
+
+describe("cli.ts exit codes end to end (no stubs, no browser touched)", () => {
+  test("a missing input is the orchestrator's own guard: exit 2 `input file not found` — NOT the ENOENT branch", () => {
+    // generate() checks existsSync before any fs call can throw ENOENT, so a
+    // typo'd input reads as a render error (2), not bad args (1). Pinned as-is.
+    const missing = path.join(tmp, "does-not-exist.md");
+    const r = runCli(["generate", missing, "--quiet"]);
+    expect(r.code).toBe(ExitCode.RenderError);
+    expect(r.stderr.trim()).toBe(`$P: input file not found: ${missing}`);
+    expect(r.stdout).toBe("");
+  });
+
+  test("a real ENOENT (output directory does not exist; --to html needs no browser) → exit 1 `file not found`", () => {
+    const out = path.join(tmp, "no-such-dir", "out.html");
+    const r = runCli(["generate", inputMd, out, "--to", "html", "--quiet"]);
+    expect(r.code).toBe(ExitCode.BadArgs);
+    expect(r.stderr.trim()).toBe(`$P: file not found: ${out}`);
+    expect(r.stdout).toBe("");
+    expect(fs.existsSync(out)).toBe(false);
+  });
+
+  test("bad args → exit 1: no input, unknown command (with usage), invalid --to", () => {
+    const noInput = runCli(["generate"]);
+    expect(noInput.code).toBe(ExitCode.BadArgs);
+    expect(noInput.stderr).toContain("$P generate: missing <input.md>");
+    expect(noInput.stdout).toBe("");
+
+    const unknown = runCli(["frobnicate"]);
+    expect(unknown.code).toBe(ExitCode.BadArgs);
+    expect(unknown.stderr).toContain("$P: unknown command: frobnicate");
+    expect(unknown.stderr).toContain("Usage:");
+    expect(unknown.stdout).toBe("");
+
+    const badTo = runCli(["generate", inputMd, "--to", "xml"]);
+    expect(badTo.code).toBe(ExitCode.BadArgs);
+    expect(badTo.stderr).toContain("invalid --to 'xml'");
+    expect(badTo.stdout).toBe("");
+  });
+
+  test("exit 0 paths: no arguments prints usage (stderr); version prints VERSION on stdout only", () => {
+    const usage = runCli([]);
+    expect(usage.code).toBe(ExitCode.Success);
+    expect(usage.stderr).toContain("Usage:");
+    expect(usage.stdout).toBe("");
+
+    const version = runCli(["version"]);
+    expect(version.code).toBe(ExitCode.Success);
+    expect(version.stdout.trim()).toBe(fs.readFileSync(path.join(ROOT, "VERSION"), "utf8").trim());
+    expect(version.stderr).toBe("");
+  });
+});
+
+// ─── 3. fake browsers: success contract, render error vs no browser, mid-run note ─
+
+describe.skipIf(isWin)("cli.ts through fake browsers (GSTACK_BROWSE_BIN + a scrubbed PATH)", () => {
+  test("gstack's own browser renders: exit 0, stdout is the output path and nothing else, --quiet keeps stderr empty", () => {
+    const out = path.join(tmp, "steady", "out.pdf");
+    const r = runCli(["generate", inputMd, out, "--quiet"], { env: childEnv({ GSTACK_BROWSE_BIN: browseOk }) });
+    expect(r.code).toBe(ExitCode.Success);
+    expect(r.stdout).toBe(`${out}\n`);
+    expect(r.stderr).toBe("");
+    expect(fs.readFileSync(out, "utf8")).toBe("%PDF-1.4 fake\n");
+  });
+
+  test("a browser that is up but cannot render is a render error (exit 2), never `no browser` (exit 4)", () => {
+    const out = path.join(tmp, "refused", "out.pdf");
+    const r = runCli(["generate", inputMd, out, "--quiet"], { env: childEnv({ GSTACK_BROWSE_BIN: browseRefusesNewtab }) });
+    expect(r.code).toBe(ExitCode.RenderError);
+    expect(r.stderr.trim()).toBe("$P: PDF render failed: browse newtab failed: daemon refused: boom");
+    expect(r.stderr).not.toContain(NO_BROWSER);
+    expect(r.stdout).toBe("");
+    expect(fs.existsSync(out)).toBe(false);
+  });
+
+  test("Aside answers the probe but cannot run the script: the PDF comes from gstack's browser, stderr says so, exit 0", () => {
+    const out = path.join(tmp, "mid-run", "out.pdf");
+    const r = runCli(["generate", inputMd, out, "--quiet"], {
+      env: childEnv({ PATH: fakeAsideBin, GSTACK_SKIP_ASIDE: undefined, GSTACK_BROWSE_BIN: browseOk }),
+    });
+    expect(r.code).toBe(ExitCode.Success);
+    expect(r.stdout).toBe(`${out}\n`);
+    expect(r.stderr).toContain("Aside was unavailable mid-run; the PDF was rendered through gstack's own browser.");
+    expect(fs.readFileSync(out, "utf8")).toBe("%PDF-1.4 fake\n");
+  });
+});
@@ -1,6 +1,6 @@
 /**
 * Coverage-gap fills from the v1.58.0.0 ship audit — the branches the main
- * suites couldn't reach without a live browse tab (mock-tab here), plus the
+ * suites couldn't reach without a live bundle page (mock runner here), plus the
 * pure-function stragglers (WebP probing, landscape geometry, bundle path
 * resolution, screen CSS).
 */
@@ -10,8 +10,8 @@ import * as os from "node:os";
 import * as path from "node:path";

 import {
-  RenderCallError,
-  type RenderTab,
+  type BundleCall,
+  type BundleResult,
  landscapeContentBox,
  rasterizeDiagramFigures,
  renderFenceSlots,
@@ -21,19 +21,22 @@ import {
 import { imageDims } from "../src/image-size";
 import { screenCss } from "../src/print-css";

-/** Duck-typed RenderTab: scripted call results + a loadBundle counter. */
-function mockTab(script: (fn: string, ...args: Array<string | number>) => string) {
+/** Scripted BundleRun: a throwing script call becomes an ERR result, plus counters. */
+function mockRun(script: (fn: string, ...args: unknown[]) => string) {
  const calls: string[] = [];
-  let reloads = 0;
-  const tab = {
-    call: (fn: string, ...args: Array<string | number>) => {
-      calls.push(fn);
-      return script(fn, ...args);
-    },
-    loadBundle: () => { reloads++; },
-    close: () => {},
-  } as unknown as RenderTab;
-  return { tab, calls, reloadCount: () => reloads };
+  let batches = 0;
+  const run = async (batch: BundleCall[]): Promise<BundleResult[]> => {
+    batches++;
+    return batch.map((c) => {
+      calls.push(c.fn);
+      try {
+        return { ok: true, value: script(c.fn, ...c.args) };
+      } catch (e: any) {
+        return { ok: false, error: e.message };
+      }
+    });
+  };
+  return { run, calls, batchCount: () => batches };
 }

 const fence = (over: Partial<{ lang: string; source: string; ordinal: number }>) => ({
@@ -49,88 +52,99 @@ const fence = (over: Partial<{ lang: string; source: string; ordinal: number }>)

 // ─── renderFenceSlots: reset contract + excalidraw branches ───────────

-describe("renderFenceSlots (mock tab)", () => {
-  test("reset contract: a failure reloads the bundle and the NEXT fence still renders", () => {
-    const { tab, reloadCount } = mockTab((fn, ...args) => {
-      if (String(args[1] ?? "").includes("BROKEN")) throw new RenderCallError("Parse error on line 1");
+describe("renderFenceSlots (mock runner)", () => {
+  test("one batch for all fences: a failure is a diagnostic block and the NEXT fence still renders", async () => {
+    const { run, batchCount } = mockRun((fn, ...args) => {
+      if (String(args[1] ?? "").includes("BROKEN")) throw new Error("Parse error on line 1");
      return "<svg><g/></svg>";
    });
    const warnings: string[] = [];
-    const slots = renderFenceSlots(
+    const slots = await renderFenceSlots(
      [
        fence({ ordinal: 1 }),
        fence({ ordinal: 2, source: "BROKEN" }),
        fence({ ordinal: 3 }),
      ],
-      tab,
+      run,
      (m) => warnings.push(m),
    );
    expect(slots.get("tok-1")).toContain("<svg>");
    expect(slots.get("tok-2")).toContain("diagram-error");
+    expect(slots.get("tok-2")).toContain("Parse error on line 1");
    expect(slots.get("tok-3")).toContain("<svg>"); // post-failure fence rendered
-    expect(reloadCount()).toBe(1);                 // exactly one reset reload
+    expect(batchCount()).toBe(1);                  // one script for the whole document
    expect(warnings[0]).toContain("failed to render");
  });

-  test("excalidraw fence renders via __excalidrawToSvg", () => {
-    const { tab, calls } = mockTab(() => "<svg data-x><g/></svg>");
-    const slots = renderFenceSlots(
+  test("excalidraw fence renders via __excalidrawToSvg", async () => {
+    const { run, calls } = mockRun(() => "<svg data-x><g/></svg>");
+    const slots = await renderFenceSlots(
      [fence({ lang: "excalidraw", source: '{"type":"excalidraw","elements":[]}' })],
-      tab,
+      run,
      () => {},
    );
    expect(calls).toEqual(["__excalidrawToSvg"]);
    expect(slots.get("tok-1")).toContain("<svg");
  });

-  test("invalid excalidraw JSON fails fast into a diagnostic WITHOUT calling the tab", () => {
-    const { tab, calls, reloadCount } = mockTab(() => "<svg/>");
+  test("invalid excalidraw JSON fails fast into a diagnostic WITHOUT a bundle call", async () => {
+    const { run, calls } = mockRun(() => "<svg/>");
    const warnings: string[] = [];
-    const slots = renderFenceSlots(
+    const slots = await renderFenceSlots(
      [fence({ lang: "excalidraw", source: "{not json" })],
-      tab,
+      run,
      (m) => warnings.push(m),
    );
    expect(calls).toEqual([]); // JSON.parse threw before any bundle call
    expect(slots.get("tok-1")).toContain("diagram-error");
-    expect(reloadCount()).toBe(1);
    expect(warnings).toHaveLength(1);
  });
 });

 // ─── rasterizeDiagramFigures: svg-data-URI + error fallbacks ──────────

-describe("rasterizeDiagramFigures (mock tab)", () => {
+describe("rasterizeDiagramFigures (mock runner)", () => {
  const figure = `<figure class="diagram" role="img" aria-label="flow"><svg viewBox="0 0 10 10"><g/></svg></figure>`;

-  test("svg data-URI images rasterize to PNG", () => {
+  test("figures and svg data-URI images rasterize to PNG in ONE batch", async () => {
    const svgUri = `data:image/svg+xml;base64,${Buffer.from("<svg/>").toString("base64")}`;
-    const { tab } = mockTab(() => "data:image/png;base64,AAAA");
-    const out = rasterizeDiagramFigures(`<img src="${svgUri}" alt="v">`, tab, 6.5, () => {});
-    expect(out).toContain('src="data:image/png;base64,AAAA"');
+    const { run, calls, batchCount } = mockRun((_fn, svg) => `data:image/png;base64,${String(svg).includes("viewBox") ? "FIG" : "IMG"}`);
+    const out = await rasterizeDiagramFigures(`${figure}<img src="${svgUri}" alt="v">`, run, 6.5, () => {});
+    expect(calls).toEqual(["__rasterize", "__rasterize"]);
+    expect(batchCount()).toBe(1);
+    expect(out).toContain('<p><img src="data:image/png;base64,FIG" alt="flow"></p>');
+    expect(out).toContain('src="data:image/png;base64,IMG" alt="v"');
+    expect(out).not.toContain("gstack-raster-slot");
  });

-  test("figure rasterization failure surfaces the SOURCE as text (never silent loss)", () => {
+  test("no rasterizable content → no bundle call at all", async () => {
+    const { run, batchCount } = mockRun(() => "x");
+    const html = `<p>plain</p><img src="data:image/png;base64,AAAA">`;
+    expect(await rasterizeDiagramFigures(html, run, 6.5, () => {})).toBe(html);
+    expect(batchCount()).toBe(0);
+  });
+
+  test("figure rasterization failure surfaces the SOURCE as text (never silent loss)", async () => {
    // Returning the figure unchanged would make the diagram vanish in DOCX
    // (the converter drops <figure>/<svg>) — the failure must be visible.
-    const { tab } = mockTab(() => { throw new RenderCallError("tainted"); });
+    const { run } = mockRun(() => { throw new Error("tainted"); });
    const warnings: string[] = [];
    const srcFigure = figure.replace(
      '<figure class="diagram"',
      `<figure class="diagram" data-gstack-source="${Buffer.from("graph LR\n  A --> B").toString("base64")}"`,
    );
-    const out = rasterizeDiagramFigures(srcFigure, tab, 6.5, (m) => warnings.push(m));
+    const out = await rasterizeDiagramFigures(srcFigure, run, 6.5, (m) => warnings.push(m));
    expect(out).toContain("could not be rasterized");
    expect(out).toContain("A --&gt; B"); // source visible (escaped), not dropped
    expect(out).not.toContain("<figure");
    expect(warnings[0]).toContain("rasterization failed");
  });

-  test("svg data-URI rasterization failure keeps the original tag", () => {
+  test("svg data-URI rasterization failure keeps the original tag", async () => {
    const svgUri = `data:image/svg+xml;base64,${Buffer.from("<svg/>").toString("base64")}`;
-    const { tab } = mockTab(() => { throw new RenderCallError("decode failed"); });
+    const { run } = mockRun(() => { throw new Error("decode failed"); });
    const tagIn = `<img src="${svgUri}">`;
-    const out = rasterizeDiagramFigures(tagIn, tab, 6.5, () => {});
+    const out = await rasterizeDiagramFigures(tagIn, run, 6.5, () => {});
    expect(out).toBe(tagIn);
  });
 });
@@ -1,8 +1,9 @@
 /**
 * Unit tests for the diagram pre-pass: fence extraction, info-string parsing,
 * slot substitution, diagnostic blocks, image inlining policy, and the
- * byte-level image dimension prober. No browse daemon required — the tab
- * factory returns null so downscale paths are exercised as no-ops.
+ * byte-level image dimension prober, and the bundle runner's script shape
+ * (render function injected). No live Aside required — `run: null` makes
+ * downscale paths no-ops.
 */
 import { afterAll, describe, expect, test } from "bun:test";
 import * as fs from "node:fs";
@@ -13,6 +14,7 @@ import zlib from "node:zlib";
 import {
  StrictModeError,
  buildDiagnosticBlock,
+  bundleRunner,
  buildDiagramFigure,
  contentWidthInches,
  dimToInches,
@@ -23,6 +25,7 @@ import {
  decodeFigureSource,
 } from "../src/diagram-prepass";
 import { imageDims } from "../src/image-size";
+import type { RenderResult, RenderSpec } from "../../lib/aside-render";

 // ─── fence extraction ─────────────────────────────────────────────────

@@ -251,51 +254,51 @@ describe("inlineLocalImages", () => {
    strict: false,
    allowNetwork: false,
    contentWidthIn: 6.5,
-    getTab: () => null,
+    run: null,
  };

-  test("local image becomes a data URI with probed dimensions", () => {
+  test("local image becomes a data URI with probed dimensions", async () => {
    const warnings: string[] = [];
-    const out = inlineLocalImages(`<img src="ok.png" alt="x">`, { ...base, warn: (m) => warnings.push(m) });
+    const out = await inlineLocalImages(`<img src="ok.png" alt="x">`, { ...base, warn: (m) => warnings.push(m) });
    expect(out).toContain("data:image/png;base64,");
    expect(out).toContain('data-gstack-px-width="40"');
    expect(out).toContain('data-gstack-px-height="20"');
    expect(warnings).toHaveLength(0);
  });

-  test("missing image → visible placeholder + warning", () => {
+  test("missing image → visible placeholder + warning", async () => {
    const warnings: string[] = [];
-    const out = inlineLocalImages(`<img src="nope.png">`, { ...base, warn: (m) => warnings.push(m) });
+    const out = await inlineLocalImages(`<img src="nope.png">`, { ...base, warn: (m) => warnings.push(m) });
    expect(out).toContain("image-missing");
    expect(out).toContain("nope.png");
    expect(warnings.length).toBe(1);
  });

-  test("missing image + --strict → StrictModeError", () => {
-    expect(() =>
+  test("missing image + --strict → StrictModeError", async () => {
+    await expect(
      inlineLocalImages(`<img src="nope.png">`, { ...base, strict: true, warn: () => {} }),
-    ).toThrow(StrictModeError);
+    ).rejects.toThrow(StrictModeError);
  });

-  test("remote image is BLOCKED with a visible placeholder (offline posture)", () => {
+  test("remote image is BLOCKED with a visible placeholder (offline posture)", async () => {
    // Leaving the tag would make Chromium fetch it at print time anyway —
    // the offline posture must remove the src, not just warn about it.
    const warnings: string[] = [];
    const tag = `<img src="https://example.com/x.png">`;
-    const out = inlineLocalImages(tag, { ...base, warn: (m) => warnings.push(m) });
+    const out = await inlineLocalImages(tag, { ...base, warn: (m) => warnings.push(m) });
    expect(out).not.toContain("https://example.com/x.png\"");
    expect(out).toContain("remote image blocked");
    expect(warnings[0]).toContain("offline");
  });

-  test("symlink escaping the input dir is caught by the realpath check", () => {
+  test("symlink escaping the input dir is caught by the realpath check", async () => {
    const outside = fs.mkdtempSync(path.join(os.tmpdir(), "prepass-symlink-"));
    fs.writeFileSync(path.join(outside, "secret.png"), tinyPng(5, 5));
    const link = path.join(dir, "innocent.png");
    try {
      fs.symlinkSync(path.join(outside, "secret.png"), link);
      const warnings: string[] = [];
-      inlineLocalImages(`<img src="innocent.png">`, { ...base, warn: (m) => warnings.push(m) });
+      await inlineLocalImages(`<img src="innocent.png">`, { ...base, warn: (m) => warnings.push(m) });
      expect(warnings.some((w) => w.includes("OUTSIDE the input directory"))).toBe(true);
    } finally {
      try { fs.unlinkSync(link); } catch { /* ignore */ }
@@ -303,48 +306,48 @@ describe("inlineLocalImages", () => {
    }
  });

-  test("special files and oversized images degrade to placeholders, never hang", () => {
+  test("special files and oversized images degrade to placeholders, never hang", async () => {
    // Directory masquerading as an image — not a regular file.
    fs.mkdirSync(path.join(dir, "dir.png"), { recursive: true });
    const warnings: string[] = [];
-    const out = inlineLocalImages(`<img src="dir.png">`, { ...base, warn: (m) => warnings.push(m) });
+    const out = await inlineLocalImages(`<img src="dir.png">`, { ...base, warn: (m) => warnings.push(m) });
    expect(out).toContain("image-missing");
    expect(warnings.some((w) => w.includes("not a regular file"))).toBe(true);
  });

-  test("malformed percent-encoding degrades to missing-image, never throws", () => {
+  test("malformed percent-encoding degrades to missing-image, never throws", async () => {
    const warnings: string[] = [];
-    const out = inlineLocalImages(`<img src="foo%zz.png">`, { ...base, warn: (m) => warnings.push(m) });
+    const out = await inlineLocalImages(`<img src="foo%zz.png">`, { ...base, warn: (m) => warnings.push(m) });
    expect(out).toContain("image-missing");
  });

-  test("remote image + --allow-network passes silently", () => {
+  test("remote image + --allow-network passes silently", async () => {
    const warnings: string[] = [];
    const tag = `<img src="https://example.com/x.png">`;
-    const out = inlineLocalImages(tag, { ...base, allowNetwork: true, warn: (m) => warnings.push(m) });
+    const out = await inlineLocalImages(tag, { ...base, allowNetwork: true, warn: (m) => warnings.push(m) });
    expect(out).toBe(tag);
    expect(warnings).toHaveLength(0);
  });

-  test("remote image + --strict → StrictModeError", () => {
-    expect(() =>
+  test("remote image + --strict → StrictModeError", async () => {
+    await expect(
      inlineLocalImages(`<img src="https://example.com/x.png">`, { ...base, strict: true, warn: () => {} }),
-    ).toThrow(StrictModeError);
+    ).rejects.toThrow(StrictModeError);
  });

-  test("existing data URI gets dimension annotations only", () => {
+  test("existing data URI gets dimension annotations only", async () => {
    const uri = `data:image/png;base64,${tinyPng(33, 44).toString("base64")}`;
-    const out = inlineLocalImages(`<img src="${uri}">`, { ...base, warn: () => {} });
+    const out = await inlineLocalImages(`<img src="${uri}">`, { ...base, warn: () => {} });
    expect(out).toContain('data-gstack-px-width="33"');
    expect(out).toContain('data-gstack-px-height="44"');
  });

-  test("out-of-tree image reads warn (never silent) and still inline", () => {
+  test("out-of-tree image reads warn (never silent) and still inline", async () => {
    const outside = fs.mkdtempSync(path.join(os.tmpdir(), "prepass-outside-"));
    fs.writeFileSync(path.join(outside, "ext.png"), tinyPng(10, 10));
    try {
      const warnings: string[] = [];
-      const out = inlineLocalImages(`<img src="${path.join(outside, "ext.png")}">`, {
+      const out = await inlineLocalImages(`<img src="${path.join(outside, "ext.png")}">`, {
        ...base, warn: (m) => warnings.push(m),
      });
      expect(out).toContain("data:image/png;base64,");
@@ -354,26 +357,26 @@ describe("inlineLocalImages", () => {
    }
  });

-  test("out-of-tree image + --strict → StrictModeError", () => {
+  test("out-of-tree image + --strict → StrictModeError", async () => {
    const outside = fs.mkdtempSync(path.join(os.tmpdir(), "prepass-outside-"));
    fs.writeFileSync(path.join(outside, "ext.png"), tinyPng(10, 10));
    try {
-      expect(() =>
+      await expect(
        inlineLocalImages(`<img src="${path.join(outside, "ext.png")}">`, {
          ...base, strict: true, warn: () => {},
        }),
-      ).toThrow(StrictModeError);
+      ).rejects.toThrow(StrictModeError);
    } finally {
      fs.rmSync(outside, { recursive: true, force: true });
    }
  });

-  test("Windows drive-letter src is treated as a local path, not a URL scheme", () => {
+  test("Windows drive-letter src is treated as a local path, not a URL scheme", async () => {
    // C:/x.png matches the single-letter-scheme regex — it must reach the
    // local-path branch (and the missing-file placeholder), never silently
    // pass through as an unknown URL.
    const warnings: string[] = [];
-    const out = inlineLocalImages(`<img src="C:/missing/x.png">`, { ...base, warn: (m) => warnings.push(m) });
+    const out = await inlineLocalImages(`<img src="C:/missing/x.png">`, { ...base, warn: (m) => warnings.push(m) });
    expect(out).toContain("image-missing");
    // Two warnings: it's out-of-tree (resolved outside inputDir) AND missing.
    expect(warnings.some((w) => w.includes("image not found"))).toBe(true);
@@ -393,11 +396,137 @@ describe("inlineLocalImages", () => {
    expect(markdown).toBe(md);
  });

-  test("oversized raster without a tab inlines at full size with no downscale", () => {
+  test("oversized raster without a tab inlines at full size with no downscale", async () => {
    // 6000px-wide PNG header (body irrelevant for probing; file must exist)
    fs.writeFileSync(path.join(dir, "wide.png"), tinyPng(6000, 100));
    const warnings: string[] = [];
-    const out = inlineLocalImages(`<img src="wide.png">`, { ...base, warn: (m) => warnings.push(m) });
+    const out = await inlineLocalImages(`<img src="wide.png">`, { ...base, warn: (m) => warnings.push(m) });
    expect(out).toContain('data-gstack-px-width="6000"');
  });
+
+  test("oversized raster WITH a runner: one __downscaleRaster batch, token swapped for the scaled bytes", async () => {
+    fs.writeFileSync(path.join(dir, "wide2.png"), tinyPng(6000, 100));
+    const calls: Array<{ fn: string; args: unknown[] }> = [];
+    const run = async (batch: Array<{ fn: string; args: unknown[] }>) => {
+      calls.push(...batch);
+      return batch.map(() => ({ ok: true as const, value: "data:image/png;base64,U0NBTEVE" }));
+    };
+    const warnings: string[] = [];
+    // Same image twice: read/downscaled once, both tags rewritten.
+    const out = await inlineLocalImages(`<img src="wide2.png"> <img src="wide2.png" alt="b">`, { ...base, run, warn: (m) => warnings.push(m) });
+    expect(calls).toHaveLength(1);
+    expect(calls[0].fn).toBe("__downscaleRaster");
+    expect(String(calls[0].args[0])).toStartWith("data:image/png;base64,");
+    expect(calls[0].args[1]).toBe(1950); // 6.5in × 300dpi
+    expect(out.match(/data:image\/png;base64,U0NBTEVE/g)).toHaveLength(2);
+    expect(out).toContain('data-gstack-px-width="1950"');
+    expect(out).not.toContain("gstack-downscale-slot");
+    expect(warnings.some((w) => w.includes("downscaled wide2.png 6000px"))).toBe(true);
+  });
+
+  test("a failed downscale falls back to the full-size bytes with a warning", async () => {
+    fs.writeFileSync(path.join(dir, "wide3.png"), tinyPng(6000, 100));
+    const run = async (batch: unknown[]) => batch.map(() => ({ ok: false as const, error: "image decode failed" }));
+    const warnings: string[] = [];
+    const out = await inlineLocalImages(`<img src="wide3.png">`, { ...base, run, warn: (m) => warnings.push(m) });
+    expect(out).toContain('data-gstack-px-width="6000"');
+    expect(out).toContain("data:image/png;base64,");
+    expect(out).not.toContain("gstack-downscale-slot");
+    expect(warnings.some((w) => w.includes("downscale failed"))).toBe(true);
+  });
+});
+
+// ─── bundle runner (script shape, injected render) ────────────────────
+
+describe("bundleRunner", () => {
+  const bundle = path.join(os.tmpdir(), `fake-bundle-${process.pid}.html`);
+  fs.writeFileSync(bundle, "<!doctype html><div id=done>ready</div>");
+  afterAll(() => { try { fs.unlinkSync(bundle); } catch { /* best-effort */ } });
+
+  /** Fake Aside: asserts the spec shape and writes OK:/ERR: result files. */
+  function fakeRender(script: (fn: string, args: unknown[]) => string) {
+    const specs: RenderSpec[] = [];
+    const render = async (spec: RenderSpec): Promise<RenderResult> => {
+      specs.push(spec);
+      for (const step of spec.steps) {
+        if (step.kind !== "eval" || !step.out) throw new Error("expected eval steps with out files");
+        const i = Number(step.expression.match(/call-(\d+)\.json/)![1]);
+        const fn = step.expression.match(/window\["(__\w+)"\]/)![1];
+        const args = JSON.parse(fs.readFileSync(path.join(spec.serveRoot!, `call-${i}.json`), "utf8"));
+        let text: string;
+        try { text = "OK:" + script(fn, args); } catch (e: any) { text = "ERR:" + e.message; }
+        fs.writeFileSync(step.out, text);
+      }
+      return { ok: true, outputs: [], evals: {}, stdout: "" };
+    };
+    return { render, specs };
+  }
+
+  test("stages the bundle + one JSON args file per call in a served dir, waits for #done, reads results back", async () => {
+    const { render, specs } = fakeRender((fn, args) => `${fn}(${args.join(",")})`);
+    const run = bundleRunner({ bundlePath: bundle, render });
+    const results = await run([
+      { fn: "__renderMermaid", args: ["mermaid-fence-1", "graph LR"] },
+      { fn: "__excalidrawToSvg", args: ["{}"] },
+    ]);
+    expect(results).toEqual([
+      { ok: true, value: "__renderMermaid(mermaid-fence-1,graph LR)" },
+      { ok: true, value: "__excalidrawToSvg({})" },
+    ]);
+    expect(specs).toHaveLength(1);
+    const spec = specs[0];
+    expect(spec.waitFor).toEqual({ selector: "#done", timeoutMs: 20_000 });
+    expect(path.dirname(spec.file)).toBe(spec.serveRoot);
+    expect(spec.steps).toHaveLength(2);
+    // Payload rides the served dir, not argv: the expression stays tiny.
+    for (const step of spec.steps) expect(step.kind === "eval" && step.expression.length < 300).toBe(true);
+    // Private per-script dir is cleaned up.
+    expect(fs.existsSync(spec.serveRoot!)).toBe(false);
+  });
+
+  test("a throwing call is an ERR result; the other calls in the script still succeed", async () => {
+    const { render } = fakeRender((_fn, args) => {
+      if (String(args[1]).includes("BROKEN")) throw new Error("Parse error on line 1");
+      return "<svg/>";
+    });
+    const run = bundleRunner({ bundlePath: bundle, render });
+    const results = await run([
+      { fn: "__renderMermaid", args: ["a", "ok"] },
+      { fn: "__renderMermaid", args: ["b", "BROKEN"] },
+      { fn: "__renderMermaid", args: ["c", "ok"] },
+    ]);
+    expect(results.map((r) => r.ok)).toEqual([true, false, true]);
+    expect(results[1]).toEqual({ ok: false, error: "Parse error on line 1" });
+  });
+
+  test("chunks at 40 calls per script (Aside's 120s script cap)", async () => {
+    const { render, specs } = fakeRender(() => "x");
+    const run = bundleRunner({ bundlePath: bundle, render });
+    const results = await run(Array.from({ length: 85 }, (_, i) => ({ fn: "__renderMermaid", args: [`m${i}`, "g"] })));
+    expect(results).toHaveLength(85);
+    expect(specs.map((s) => s.steps.length)).toEqual([40, 40, 5]);
+  });
+
+  test("a whole-script failure fails every call in it with the renderer's message", async () => {
+    const render = async (): Promise<RenderResult> => ({ ok: false, outputs: [], evals: {}, stdout: "", error: "aside repl did not run: spawn aside ENOENT" });
+    const run = bundleRunner({ bundlePath: bundle, render });
+    const results = await run([{ fn: "__renderMermaid", args: ["a", "g"] }, { fn: "__renderMermaid", args: ["b", "g"] }]);
+    expect(results).toHaveLength(2);
+    for (const r of results) {
+      expect(r.ok).toBe(false);
+      if (!r.ok) expect(r.error).toContain("diagram renderer: aside repl did not run");
+    }
+  });
+
+  test("an unreadable bundle fails every call without touching Aside; zero calls run nothing", async () => {
+    let rendered = 0;
+    const render = async (): Promise<RenderResult> => { rendered++; return { ok: true, outputs: [], evals: {}, stdout: "" }; };
+    const run = bundleRunner({ bundlePath: "/nonexistent/diagram-render.html", render });
+    expect(await run([])).toEqual([]);
+    const results = await run([{ fn: "__renderMermaid", args: ["a", "g"] }, { fn: "__renderMermaid", args: ["b", "g"] }]);
+    expect(results.map((r) => r.ok)).toEqual([false, false]);
+    if (!results[0].ok) expect(results[0].error).toContain("ENOENT");
+    expect(rendered).toBe(0);
+  });
+
 });
@@ -0,0 +1,15 @@
+/**
+ * Gate prerequisite shared by the make-pdf e2e gates: SOME browser the
+ * compiled binary can print through — the Aside app (macOS dev machines) or
+ * gstack's own browse binary (what the Linux free-tests lane builds via
+ * build:gates). Mirrors lib/aside-render's pickEngine() order.
+ */
+import { resolveBrowseBin } from "../../../lib/aside-render";
+import { asideAvailable } from "../../../test/helpers/aside-available";
+
+export const NO_BROWSER_REASON =
+  "no browser available (open the Aside app, or build gstack's own browser with `bun run build:gates`; GSTACK_SKIP_ASIDE=1 skips Aside).";
+
+export function browserAvailable(): boolean {
+  return asideAvailable() || resolveBrowseBin() !== null;
+}
@@ -25,6 +25,10 @@ const EXPECT_BINARIES = process.env.GSTACK_EXPECT_BINARIES === "1";
 describe("gate prerequisites (CI tripwire)", () => {
  test.skipIf(!EXPECT_BINARIES)("gate artifacts and tools exist when the lane promises them", () => {
    const missing: string[] = [];
+    // Aside itself is deliberately NOT asserted: CI runners have no Aside. The
+    // gates print through gstack's own browse binary there (the fallback in
+    // lib/aside-render), so THAT build artifact is promised alongside the
+    // make-pdf binary, the diagram bundle, and poppler.
    for (const rel of [
      "make-pdf/dist/pdf",
      "browse/dist/browse",
@@ -11,8 +11,8 @@
 * user actually cares about — features interact, and the combined
 * extraction is what predicts production quality.
 *
- * Gating: only runs when the compiled binary + browse + pdftotext are all
- * available. Skipped cleanly otherwise (local dev without full install).
+ * Gating: only runs when the compiled binary + a browser (Aside or browse) + pdftotext
+ * are all available. Skipped cleanly otherwise (local dev, CI runners).
 */

 import { describe, expect, test } from "bun:test";
@@ -22,16 +22,17 @@ import * as os from "node:os";
 import * as path from "node:path";

 import { copyPasteGate, resolvePdftotext } from "../../src/pdftotext";
+import { browserAvailable, NO_BROWSER_REASON } from "./browser-available";

 const FIXTURE = path.resolve(__dirname, "../fixtures/combined-gate.md");
 const EXPECTED = path.resolve(__dirname, "../fixtures/combined-gate.expected.txt");
 const ROOT = path.resolve(__dirname, "../../..");
 const PDF_BIN = path.join(ROOT, "make-pdf/dist/pdf");
-const BROWSE_BIN = path.join(ROOT, "browse/dist/browse");

 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}).` };
+  // Aside (macOS) or gstack's own browse binary (what CI builds) — a skip only when neither exists.
+  if (!browserAvailable()) return { ok: false, reason: NO_BROWSER_REASON };
  if (!fs.existsSync(FIXTURE)) return { ok: false, reason: `fixture missing (${FIXTURE}).` };
  if (!fs.existsSync(EXPECTED)) return { ok: false, reason: `expected.txt missing (${EXPECTED}).` };
  try { resolvePdftotext(); } catch (err: any) { return { ok: false, reason: err.message }; }
@@ -43,15 +44,11 @@ describe("combined-features copy-paste gate", () => {

  test.skipIf(!avail.ok)("fixture PDF extracts cleanly through pdftotext", () => {
    if (!avail.ok) return; // satisfies the type checker
-    // Use /tmp directly (browse's validateOutputPath allows /private/tmp,
-    // which macOS resolves /tmp to). os.tmpdir() returns /var/folders/...
-    // which is outside the safe-dirs allowlist.
-    const outputPdf = `/tmp/make-pdf-combined-gate-${process.pid}.pdf`;
+    const outputPdf = path.join(os.tmpdir(), `make-pdf-combined-gate-${process.pid}.pdf`);
    try {
      execFileSync(PDF_BIN, ["generate", FIXTURE, outputPdf, "--quiet"], {
        encoding: "utf8",
-        timeout: 30_000,
-        env: { ...process.env, BROWSE_BIN },
+        timeout: 60_000,
        stdio: ["ignore", "pipe", "pipe"],
      });
      expect(fs.existsSync(outputPdf)).toBe(true);
@@ -67,7 +64,7 @@ describe("combined-features copy-paste gate", () => {
    } finally {
      try { fs.unlinkSync(outputPdf); } catch { /* ignore */ }
    }
-  }, 30000);
+  }, 60000);

  if (!avail.ok) {
    test("prerequisites check", () => {
@@ -14,7 +14,8 @@
 *      colored pixels — text extraction can't fake that.
 *
 * Free-tier deterministic gate: runs under plain `bun test` when the compiled
- * binaries + poppler are available; hard-fails in CI when missing.
+ * binary, a browser (Aside or the browse binary), and poppler are available; self-skips otherwise (ci-prereqs.test.ts
+ * is the CI tripwire for the build artifacts).
 */

 import { describe, expect, test } from "bun:test";
@@ -23,11 +24,11 @@ import * as fs from "node:fs";
 import * as path from "node:path";

 import { resolvePopplerTool } from "../../src/pdftotext";
+import { browserAvailable, NO_BROWSER_REASON } from "./browser-available";

 const FIXTURE = path.resolve(__dirname, "../fixtures/diagram-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;
@@ -38,7 +39,8 @@ const SATURATION_DELTA = 60;

 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}).` };
+  // Aside (macOS) or gstack's own browse binary (what CI builds) — a skip only when neither exists.
+  if (!browserAvailable()) return { ok: false, reason: NO_BROWSER_REASON };
  if (!fs.existsSync(BUNDLE)) return { ok: false, reason: `diagram-render bundle missing (${BUNDLE}). Run bun run build:diagram-render.` };
  if (!fs.existsSync(FIXTURE)) return { ok: false, reason: `fixture missing (${FIXTURE}).` };
  if (!resolvePopplerTool("pdftotext")) return { ok: false, reason: "pdftotext not found (install poppler-utils)." };
@@ -80,7 +82,6 @@ describe("diagram render gate", () => {
    try {
      // No --quiet: stderr carries the downscale warning asserted below.
      const run = Bun.spawnSync([PDF_BIN, "generate", FIXTURE, outputPdf], {
-        env: { ...process.env, BROWSE_BIN },
        stdout: "pipe",
        stderr: "pipe",
        timeout: 120_000,
@@ -92,8 +93,8 @@ describe("diagram render gate", () => {
      expect(fs.existsSync(outputPdf)).toBe(true);

      // 0. Print-resolution downscale fired on the 4200px noise photo — this
-      //    is the only live coverage of __downscaleRaster AND the chunked
-      //    jsViaBuffer transport (the data URI exceeds the 100KB argv path).
+      //    is the only live coverage of __downscaleRaster AND the served-dir
+      //    payload transport (the data URI is far too big for argv).
      expect(stderr).toMatch(/downscaled huge-noise\.png 4200px → \d+px/);

      const pdftotext = resolvePopplerTool("pdftotext")!;
@@ -101,8 +102,8 @@ describe("diagram render gate", () => {

      // 1. Vector text from BOTH diagrams (multi-fence + id-collision check).
      //    The broken fence sits BETWEEN them in the fixture, so the second
-      //    diagram rendering at all proves the reset contract (D6.2): the
-      //    bundle page reloaded after the failure and kept working.
+      //    diagram rendering at all proves a failed fence never poisons the
+      //    batch (D6.2): the script kept going and the next render succeeded.
      for (const label of ["gatealphanode", "gatebetanode", "gategammanode", "gatedeltanode", "gateepsilonnode"]) {
        expect(text).toContain(label);
      }
@@ -148,8 +149,7 @@ describe("diagram render gate", () => {
      try {
        execFileSync(PDF_BIN, ["generate", md, path.join(workDir, "out.pdf"), "--quiet", "--strict"], {
          encoding: "utf8",
-          env: { ...process.env, BROWSE_BIN },
-          stdio: ["ignore", "pipe", "pipe"],
+            stdio: ["ignore", "pipe", "pipe"],
          timeout: CHILD_TIMEOUT_MS,
        });
      } catch (err: any) {
@@ -164,13 +164,9 @@ describe("diagram render gate", () => {
  }, 120000);

  if (!avail.ok) {
-    test("diagram gate prerequisites are present (hard-required in CI)", () => {
-      // Hard-require only where the binary is expected: the make-pdf gate
-      // workflow is macOS-only (path-filtered) and builds dist/pdf first.
-      // The Linux free lane deliberately doesn't build it — warn-skip there.
-      if (process.env.CI && process.platform === 'darwin') {
-        throw new Error(`diagram gate prerequisites missing in CI: ${avail.reason}`);
-      }
+    // A visible skip, never a failure: ci-prereqs.test.ts is the CI tripwire for
+    // the build artifacts + poppler this gate needs; CI prints through the browse binary it builds.
+    test("diagram gate prerequisites are present", () => {
      console.warn(`[skip] ${avail.reason}`);
    });
  }
@@ -22,8 +22,8 @@
 * Note: pdfimages -list is intentionally NOT used — macOS embeds color emoji as
 * Type 3 fonts, so pdfimages lists nothing even on a correct render.
 *
- * Gating: runs only when the compiled binary + browse + pdffonts + pdftoppm are
- * available AND a color-emoji font is installed for Chromium to fall back to.
+ * Gating: runs only when the compiled binary + a browser (Aside or browse) + pdffonts +
+ * pdftoppm are available AND a color-emoji font is installed to fall back to.
 * In CI (process.env.CI set) missing prerequisites are a HARD FAILURE, not a
 * skip — CI is expected to install poppler-utils + fonts-noto-color-emoji, so a
 * silent skip there would let the tofu regression ship behind a green build.
@@ -36,11 +36,11 @@ import * as fs from "node:fs";
 import * as path from "node:path";

 import { resolvePopplerTool } from "../../src/pdftotext";
+import { browserAvailable, NO_BROWSER_REASON } from "./browser-available";

 const FIXTURE = path.resolve(__dirname, "../fixtures/emoji-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");

 // Saturated-pixel floor. Measured ~1650 at 100dpi for the fixture's color
 // emoji; a tofu render yields ~0. 200 sits well clear of both.
@@ -50,9 +50,9 @@ const SATURATED_PIXEL_FLOOR = 200;
 const SATURATION_DELTA = 40;
 // Per-child wall-clock bound. Bun's test timeout doesn't reliably interrupt a
 // synchronous execFileSync, so each child gets its own ceiling — a wedged
-// browser/poppler binary (or a hostile GSTACK_*_BIN override) fails instead of
-// hanging the whole job.
-const CHILD_TIMEOUT_MS = 25_000;
+// browser session or poppler binary (or a hostile GSTACK_PDF*_BIN poppler override)
+// fails instead of hanging the whole job.
+const CHILD_TIMEOUT_MS = 60_000;

 /** Is a color-emoji font available for Chromium to fall back to? */
 function emojiFontAvailable(): boolean {
@@ -78,7 +78,8 @@ function emojiFontAvailable(): boolean {

 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}).` };
+  // Aside (macOS) or gstack's own browse binary (what CI builds) — a skip only when neither exists.
+  if (!browserAvailable()) return { ok: false, reason: NO_BROWSER_REASON };
  if (!fs.existsSync(FIXTURE)) return { ok: false, reason: `fixture missing (${FIXTURE}).` };
  if (!resolvePopplerTool("pdffonts")) return { ok: false, reason: "pdffonts not found (install poppler-utils)." };
  if (!resolvePopplerTool("pdftoppm")) return { ok: false, reason: "pdftoppm not found (install poppler-utils)." };
@@ -142,9 +143,6 @@ describe("emoji render gate", () => {

  test.skipIf(!avail.ok)("emoji render as color glyphs, not tofu", () => {
    if (!avail.ok) return; // type narrowing
-    // Private temp dir under /tmp: browse's validateOutputPath only allows
-    // /tmp and /private/tmp (not os.tmpdir()'s /var/folders), and mkdtemp
-    // dodges the predictable-path symlink/collision risk.
    const workDir = fs.mkdtempSync("/tmp/make-pdf-emoji-gate-");
    const outputPdf = path.join(workDir, "out.pdf");
    const ppmPrefix = path.join(workDir, "page");
@@ -152,7 +150,6 @@ describe("emoji render gate", () => {
    try {
      execFileSync(PDF_BIN, ["generate", FIXTURE, outputPdf, "--quiet"], {
        encoding: "utf8",
-        env: { ...process.env, BROWSE_BIN },
        stdio: ["ignore", "pipe", "pipe"],
        timeout: CHILD_TIMEOUT_MS,
      });
@@ -185,15 +182,9 @@ describe("emoji render gate", () => {
  }, 60000);

  if (!avail.ok) {
-    // In CI, missing prerequisites are a hard failure — a silent skip would let
-    // the Linux tofu regression ship behind a green build. Locally, just warn.
-    test("emoji gate prerequisites are present (hard-required in CI)", () => {
-      // Hard-require only where the binary is expected: the make-pdf gate
-      // workflow is macOS-only (path-filtered) and builds dist/pdf first.
-      // The Linux free lane deliberately doesn't build it — warn-skip there.
-      if (process.env.CI && process.platform === 'darwin') {
-        throw new Error(`emoji gate prerequisites missing in CI: ${avail.reason}`);
-      }
+    // A visible skip, never a failure: ci-prereqs.test.ts is the CI tripwire for
+    // the build artifacts + poppler this gate needs; CI prints through the browse binary it builds.
+    test("emoji gate prerequisites are present", () => {
      console.warn(`[skip] ${avail.reason}`);
    });
  }
@@ -16,17 +16,19 @@ import { execFileSync } from "node:child_process";
 import * as fs from "node:fs";
 import * as path from "node:path";

+import { browserAvailable, NO_BROWSER_REASON } from "./browser-available";
+
 const FIXTURE = path.resolve(__dirname, "../fixtures/diagram-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}).` };
+  // Aside (macOS) or gstack's own browse binary (what CI builds) — a skip only when neither exists.
+  if (!browserAvailable()) return { ok: false, reason: NO_BROWSER_REASON };
  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 (!Bun.which("unzip")) return { ok: false, reason: "unzip not found (needed for docx zip checks)." };
@@ -36,7 +38,6 @@ function prerequisitesAvailable(): { ok: true } | { ok: false; reason: string }
 function generate(to: string, outputPath: string): void {
  execFileSync(PDF_BIN, ["generate", FIXTURE, outputPath, "--quiet", "--to", to], {
    encoding: "utf8",
-    env: { ...process.env, BROWSE_BIN },
    stdio: ["ignore", "pipe", "pipe"],
    timeout: CHILD_TIMEOUT_MS,
  });
@@ -109,7 +110,6 @@ describe("output format gate", () => {
    try {
      execFileSync(PDF_BIN, ["generate", FIXTURE, "--to", "epub"], {
        encoding: "utf8",
-        env: { ...process.env, BROWSE_BIN },
        stdio: ["ignore", "pipe", "pipe"],
        timeout: CHILD_TIMEOUT_MS,
      });
@@ -121,13 +121,9 @@ describe("output format gate", () => {
  }, 60000);

  if (!avail.ok) {
-    test("format gate prerequisites are present (hard-required in CI)", () => {
-      // Hard-require only where the binary is expected: the make-pdf gate
-      // workflow is macOS-only (path-filtered) and builds dist/pdf first.
-      // The Linux free lane deliberately doesn't build it — warn-skip there.
-      if (process.env.CI && process.platform === 'darwin') {
-        throw new Error(`format gate prerequisites missing in CI: ${avail.reason}`);
-      }
+    // A visible skip, never a failure: ci-prereqs.test.ts is the CI tripwire for
+    // the build artifacts + poppler this gate needs; CI prints through the browse binary it builds.
+    test("format gate prerequisites are present", () => {
      console.warn(`[skip] ${avail.reason}`);
    });
  }
@@ -11,7 +11,7 @@
 *   - 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
+ * without page numbers, the print 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.
 */
@@ -22,18 +22,19 @@ import * as fs from "node:fs";
 import * as path from "node:path";

 import { resolvePopplerTool } from "../../src/pdftotext";
+import { browserAvailable, NO_BROWSER_REASON } from "./browser-available";

 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}).` };
+  // Aside (macOS) or gstack's own browse binary (what CI builds) — a skip only when neither exists.
+  if (!browserAvailable()) return { ok: false, reason: NO_BROWSER_REASON };
  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)." };
@@ -66,7 +67,6 @@ 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,
  });
@@ -141,13 +141,9 @@ describe("landscape promotion gate", () => {
  }, 120000);

  if (!avail.ok) {
-    test("landscape gate prerequisites are present (hard-required in CI)", () => {
-      // Hard-require only where the binary is expected: the make-pdf gate
-      // workflow is macOS-only (path-filtered) and builds dist/pdf first.
-      // The Linux free lane deliberately doesn't build it — warn-skip there.
-      if (process.env.CI && process.platform === 'darwin') {
-        throw new Error(`landscape gate prerequisites missing in CI: ${avail.reason}`);
-      }
+    // A visible skip, never a failure: ci-prereqs.test.ts is the CI tripwire for
+    // the build artifacts + poppler this gate needs; CI prints through the browse binary it builds.
+    test("landscape gate prerequisites are present", () => {
      console.warn(`[skip] ${avail.reason}`);
    });
  }
@@ -1,6 +1,6 @@
 /**
 * Unit tests for the image width policy + conservative auto-landscape
- * (image-policy.ts). Pure HTML-in/HTML-out — no browse daemon.
+ * (image-policy.ts). Pure HTML-in/HTML-out, no browser.
 *
 * The promotion heuristic is deliberately conservative (eng-review P4):
 * false negatives are cheap (add {page=landscape}), false positives feel
@@ -147,6 +147,30 @@ describe("findExecutable (pdftotext.ts)", () => {
  test("returns null when no extension matches", () => {
    expect(findExecutable("/nonexistent/path/to/nothing")).toBeNull();
  });
+
+  // access(X_OK) is TRUE for directories (they carry the traverse bit), so a bare
+  // X_OK probe once resolved a docs folder as "the binary". Only regular files count.
+  test("rejects a DIRECTORY even though it passes access(X_OK)", () => {
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "mkpdf-dir-"));
+    try {
+      fs.accessSync(dir, fs.constants.X_OK); // precondition: the bare probe passes
+      expect(findExecutable(dir)).toBeNull();
+    } finally {
+      fs.rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("rejects a directory that shadows the binary name", () => {
+    const base = fs.mkdtempSync(path.join(os.tmpdir(), "mkpdf-shadow-"));
+    const shadow = path.join(base, "pdftotext");
+    fs.mkdirSync(shadow);
+    fs.writeFileSync(path.join(shadow, "README.md"), "# not a binary\n");
+    try {
+      expect(findExecutable(shadow)).toBeNull();
+    } finally {
+      fs.rmSync(base, { recursive: true, force: true });
+    }
+  });
 });

 describe("resolvePdftotext (override resolution, v1.24-aligned)", () => {
@@ -1,6 +1,6 @@
 /**
 * Offline-posture sanitizer tests — raw-HTML fetch vectors beyond <img src>
- * (which the image inliner owns). No Playwright, no PDF generation.
+ * (which the image inliner owns). No browser, no PDF generation.
 *
 * Regression for: <style>@import, inline style="…url(https://…)…", and
 * <img srcset> surviving sanitizeUntrustedHtml, letting Chromium fetch
@@ -1,6 +1,6 @@
 /**
 * Renderer unit tests — pure-function assertions for render.ts, smartypants.ts,
- * and print-css.ts. No Playwright, no PDF generation.
+ * and print-css.ts. No browser, no PDF generation.
 */

 import { describe, expect, test } from "bun:test";
@@ -0,0 +1,259 @@
+/**
+ * `$P setup` smoke flow — make-pdf/src/setup.ts runSetup() — with no real
+ * browser probed or launched.
+ *
+ * runSetup() reads the engine through lib/aside-render's process-wide cache
+ * (pickEngine() with no arguments, and render() which consults the same
+ * cache), so `pickEngine(true, deps)` is the intended seam: prime it once with
+ * a stubbed Aside probe and a stubbed browse-binary resolver, then call
+ * runSetup(). A fake `browse` shell script plays gstack's own headless
+ * browser for the [2/5] render smoke and the [4/5] smoke PDF. process.exit is
+ * stubbed to throw so the exit code is observable; process.stderr.write is
+ * captured for the step lines.
+ *
+ * Also pins renderPdf()'s return value — the engine that actually rendered —
+ * which the orchestrator compares against the engine it announced.
+ */
+
+import { afterAll, beforeAll, 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 {
+  NO_BROWSER,
+  NO_BROWSER_HELP,
+  pickEngine,
+  renderTmpDir,
+  type AsideProbe,
+  type RenderResult,
+  type RenderSpec,
+} from "../../lib/aside-render";
+import { renderPdf } from "../src/asideClient";
+import { OUTPUT_TMP_DIR } from "../src/orchestrator";
+import { runSetup } from "../src/setup";
+import { ExitCode } from "../src/types";
+
+const isWin = process.platform === "win32";
+const PROBE_DETAIL = "primed by setup-smoke.test.ts";
+const noAside = (): AsideProbe => ({ ok: false, reason: "NEEDS_ASIDE", detail: PROBE_DETAIL });
+
+let tmp: string;
+
+beforeAll(() => {
+  tmp = fs.mkdtempSync(path.join(os.tmpdir(), "make-pdf-setup-smoke-"));
+});
+
+afterAll(() => {
+  fs.rmSync(tmp, { recursive: true, force: true });
+  // The engine cache is process-wide. The free runner gives every test file
+  // its own process, but under a bare multi-file `bun test` a later in-process
+  // caller must not inherit a fake binary that no longer exists: re-resolve
+  // gstack's real browse binary (Aside probe still stubbed — never a round-trip).
+  pickEngine(true, { probe: noAside });
+});
+
+// ─── helpers ──────────────────────────────────────────────────────────────────
+
+class ExitSentinel extends Error {
+  constructor(readonly code: number) {
+    super(`process.exit(${code})`);
+    this.name = "ExitSentinel";
+  }
+}
+
+/** Run `fn` with process.exit throwing a sentinel and process.stderr.write captured. Restores both. */
+async function captureRun<T>(fn: () => Promise<T>): Promise<{ result?: T; exit?: number; error?: unknown; stderr: string }> {
+  const chunks: string[] = [];
+  const origWrite = process.stderr.write;
+  const origExit = process.exit;
+  process.stderr.write = ((chunk: string | Uint8Array) => {
+    chunks.push(typeof chunk === "string" ? chunk : Buffer.from(chunk).toString("utf8"));
+    return true;
+  }) as typeof process.stderr.write;
+  process.exit = ((code?: number) => {
+    throw new ExitSentinel(code ?? 0);
+  }) as typeof process.exit;
+  try {
+    const result = await fn();
+    return { result, stderr: chunks.join("") };
+  } catch (e) {
+    if (e instanceof ExitSentinel) return { exit: e.code, stderr: chunks.join("") };
+    return { error: e, stderr: chunks.join("") };
+  } finally {
+    process.stderr.write = origWrite;
+    process.exit = origExit;
+  }
+}
+
+/**
+ * A stand-in for gstack's browse daemon CLI: `newtab --json` hands out a tab,
+ * `js` answers with `pageText`, `pdf --from-file <payload>` writes a fake PDF
+ * at the payload's `output` path when `pdf` is set (and nothing otherwise).
+ */
+function writeFakeBrowse(name: string, opts: { pageText?: string; pdf?: boolean; newtabFails?: boolean }): string {
+  const body = ["#!/bin/sh", 'case "$1" in'];
+  body.push(opts.newtabFails
+    ? '  newtab) echo "daemon refused: boom" >&2; exit 1 ;;'
+    : `  newtab) echo '{"tabId":7}' ;;`);
+  body.push(`  js) echo '${opts.pageText ?? "browser-ok"}' ;;`);
+  if (opts.pdf) {
+    body.push(
+      "  pdf)",
+      '    read -r payload < "$3"',
+      '    out="${payload#*\\"output\\":\\"}"',
+      '    out="${out%%\\"*}"',
+      "    printf '%%PDF-1.4 fake\\n' > \"$out\"",
+      "    ;;",
+    );
+  }
+  body.push("esac", "exit 0", "");
+  const file = path.join(tmp, name);
+  fs.writeFileSync(file, body.join("\n"), { mode: 0o755 });
+  return file;
+}
+
+/** The [2/5] smoke staging dirs currently under renderTmpDir(). */
+function smokeDirs(stage: string): string[] {
+  return fs.readdirSync(stage).filter((n) => n.startsWith("make-pdf-setup-")).sort();
+}
+
+const smokePdf = () => path.join(OUTPUT_TMP_DIR, `make-pdf-smoke-${process.pid}.pdf`);
+const smokeFixture = () => path.join(OUTPUT_TMP_DIR, `make-pdf-smoke-${process.pid}.md`);
+
+// ─── [1/5] browser check ──────────────────────────────────────────────────────
+
+describe("runSetup [1/5]: no browser at all", () => {
+  test("Aside absent and no browse binary: FAIL, the NO_BROWSER text with both remedies, exit 4, never reaches [2/5]", async () => {
+    pickEngine(true, { probe: noAside, resolveBin: () => null });
+    const run = await captureRun(() => runSetup());
+    expect(run.error).toBeUndefined();
+    expect(run.exit).toBe(ExitCode.BrowserUnavailable);
+    expect(run.exit).toBe(4);
+    expect(run.stderr).toContain("make-pdf setup — verifying install");
+    expect(run.stderr).toContain("[1/5] Checking for a browser... FAIL");
+    expect(run.stderr).toContain(NO_BROWSER);
+    expect(run.stderr).toContain("no browser available");
+    expect(run.stderr).toContain(NO_BROWSER_HELP);
+    expect(run.stderr).toContain(`(NEEDS_ASIDE: ${PROBE_DETAIL})`);
+    expect(run.stderr).not.toContain("[2/5]");
+  });
+});
+
+// ─── [2/5] render smoke through the fallback browser ──────────────────────────
+
+describe.skipIf(isWin)("runSetup [2/5]: render smoke through gstack's own browser", () => {
+  test("a browser that answers but the page text is wrong: FAIL, `could not render a page` + remedy, exit 4, smoke dir removed", async () => {
+    const fake = writeFakeBrowse("browse-wrong-text", { pageText: "not-the-smoke-page" });
+    pickEngine(true, { probe: noAside, resolveBin: () => fake });
+    const stage = renderTmpDir();
+    const before = smokeDirs(stage);
+
+    const run = await captureRun(() => runSetup());
+    expect(run.error).toBeUndefined();
+    expect(run.exit).toBe(ExitCode.BrowserUnavailable);
+    expect(run.stderr).toContain(`[1/5] Checking for a browser... gstack browser OK (fallback: ${fake}; Aside is not running)`);
+    expect(run.stderr).toContain("[2/5] Rendering through gstack browser... FAIL");
+    expect(run.stderr).toContain("gstack browser could not render a page: unexpected page text: not-the-smoke-page");
+    expect(run.stderr).toContain(`To fix: ${NO_BROWSER_HELP}`);
+    expect(run.stderr).toContain("open the Aside app");
+    expect(run.stderr).toContain("./setup");
+    expect(run.stderr).not.toContain("[3/5]");
+    expect(smokeDirs(stage)).toEqual(before); // finally { rmSync(smokeDir) } ran despite the exit
+  });
+
+  test("a daemon that refuses to open a tab surfaces browse's own error on the same FAIL path (exit 4)", async () => {
+    const fake = writeFakeBrowse("browse-refuses-newtab", { newtabFails: true });
+    pickEngine(true, { probe: noAside, resolveBin: () => fake });
+    const stage = renderTmpDir();
+    const before = smokeDirs(stage);
+
+    const run = await captureRun(() => runSetup());
+    expect(run.exit).toBe(ExitCode.BrowserUnavailable);
+    expect(run.stderr).toContain("[2/5] Rendering through gstack browser... FAIL");
+    expect(run.stderr).toContain("gstack browser could not render a page: browse newtab failed: daemon refused: boom");
+    expect(run.stderr).toContain(`To fix: ${NO_BROWSER_HELP}`);
+    expect(smokeDirs(stage)).toEqual(before);
+  });
+});
+
+// ─── [3/5]–[5/5] the rest of the flow with a fake browser ─────────────────────
+
+describe.skipIf(isWin)("runSetup [3/5]-[5/5]: pdftotext, smoke PDF, cheatsheet", () => {
+  test("happy path: every step reports, the smoke PDF lands at OUTPUT_TMP_DIR, the fixture is removed, no exit", async () => {
+    const fake = writeFakeBrowse("browse-happy", { pageText: "browser-ok", pdf: true });
+    pickEngine(true, { probe: noAside, resolveBin: () => fake });
+    const outPath = smokePdf();
+    const fixturePath = smokeFixture();
+    try {
+      const run = await captureRun(() => runSetup());
+      expect(run.error).toBeUndefined();
+      expect(run.exit).toBeUndefined();
+      expect(run.stderr).toContain(`[1/5] Checking for a browser... gstack browser OK (fallback: ${fake}; Aside is not running)`);
+      expect(run.stderr).toContain("[2/5] Rendering through gstack browser... OK");
+      // pdftotext is optional: OK where poppler is installed, SKIP with install hints otherwise.
+      expect(run.stderr).toMatch(/\[3\/5\] Checking pdftotext \(optional\)\.\.\. (OK \(|SKIP\n)/);
+      expect(run.stderr).toContain("[4/5] Generating smoke-test PDF...");
+      expect(run.stderr).toContain(`PASSED. Smoke test saved to ${outPath}`);
+      expect(run.stderr).toContain("[5/5] All checks passed.");
+      expect(run.stderr).toContain("make-pdf is ready. Try:");
+      expect(run.stderr).toContain(`Smoke-test PDF: ${outPath}`);
+      // The announced engine (browse) is the one that rendered: no mid-run note.
+      expect(run.stderr).not.toContain("mid-run");
+      expect(fs.readFileSync(outPath, "utf8")).toBe("%PDF-1.4 fake\n");
+      expect(fs.existsSync(fixturePath)).toBe(false);
+    } finally {
+      fs.rmSync(outPath, { force: true });
+      fs.rmSync(fixturePath, { force: true });
+    }
+  });
+
+  test("[4/5] smoke PDF failure (browser up, print produced nothing): FAILED with the render error, exit 2, fixture removed", async () => {
+    // Same fake, but `pdf` writes no artifact — a render error, not a missing browser.
+    const fake = writeFakeBrowse("browse-no-artifact", { pageText: "browser-ok", pdf: false });
+    pickEngine(true, { probe: noAside, resolveBin: () => fake });
+    const outPath = smokePdf();
+    const fixturePath = smokeFixture();
+    try {
+      const run = await captureRun(() => runSetup());
+      expect(run.error).toBeUndefined();
+      expect(run.exit).toBe(ExitCode.RenderError);
+      expect(run.exit).toBe(2);
+      expect(run.stderr).toContain("[2/5] Rendering through gstack browser... OK");
+      expect(run.stderr).toContain("[4/5] Generating smoke-test PDF...");
+      expect(run.stderr).toContain("        FAILED: PDF render failed: step 0 produced no artifact");
+      expect(run.stderr).not.toContain("[5/5]");
+      expect(fs.existsSync(outPath)).toBe(false);
+      expect(fs.existsSync(fixturePath)).toBe(false); // finally { unlinkSync(fixturePath) } ran despite the exit
+    } finally {
+      fs.rmSync(outPath, { force: true });
+      fs.rmSync(fixturePath, { force: true });
+    }
+  });
+});
+
+// ─── renderPdf returns the engine that rendered ───────────────────────────────
+
+describe("renderPdf reports which engine rendered", () => {
+  const injected = (engine: RenderResult["engine"]) => async (spec: RenderSpec): Promise<RenderResult> => {
+    const step = spec.steps[0];
+    return { ok: true, engine, outputs: step.kind === "pdf" ? [step.out] : [], evals: {}, stdout: "" };
+  };
+
+  test("resolves 'browse' when gstack's own browser printed the PDF", async () => {
+    await expect(renderPdf("<p>x</p>", { output: path.join(tmp, "browse.pdf") }, injected("browse"))).resolves.toBe("browse");
+  });
+
+  test("resolves 'aside' when Aside printed it", async () => {
+    await expect(renderPdf("<p>x</p>", { output: path.join(tmp, "aside.pdf") }, injected("aside"))).resolves.toBe("aside");
+  });
+
+  test("resolves undefined when the result names no engine (older render shapes)", async () => {
+    await expect(renderPdf("<p>x</p>", { output: path.join(tmp, "none.pdf") }, injected(undefined))).resolves.toBeUndefined();
+  });
+
+  test("a failed result still throws (the engine is never returned for a failure)", async () => {
+    const failing = async (): Promise<RenderResult> => ({ ok: false, engine: "browse", outputs: [], evals: {}, stdout: "", error: "browse pdf failed: boom" });
+    await expect(renderPdf("<p>x</p>", { output: path.join(tmp, "fail.pdf") }, failing)).rejects.toThrow(/PDF render failed: browse pdf failed: boom/);
+  });
+});