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-10-04 02:16:56 +02:00 · 2026-09-06 08:54:25 -07:00
1 parent c241216637
commit 0530392821
@@ -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" :