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-12 16:08:59 +02:00 · 2026-09-06 08:54:25 -07:00
parent c241216637
commit 0530392821
172 changed files with 12044 additions and 4676 deletions
@@ -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";
  }
 }