CalvinBackup/gstack
1
0
Fork 0
mirror of https://github.com/garrytan/gstack.git synced 2026-09-12 07:59:02 +02:00
Code Issues Packages Projects Releases Wiki Activity

refactor(make-pdf): print through Aside first, the bundled browser otherwise

Browse Source 
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>
This commit is contained in:
Sina
2026-09-05 16:48:37 -04:00
co-authored by Claude Fable 5.1
parent c0ac82461e
commit f74d3a1a63
29 changed files with 976 additions and 1262 deletions
Download Patch File Download Diff File Expand all files Collapse all files
make-pdf/src/asideClient.ts
+120
View File
@@ -0,0 +1,120 @@
/**
* 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,
lengthToInches,
paperInches,
render,
renderTmpDir,
type PdfStepOptions,
} 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;
}
const PAGE_NUMBER_FOOTER =
'<div style="font-size:9pt; font-family:Helvetica,Arial,sans-serif; color:#666; ' +
'width:100%; text-align:center;">' +
'<span class="pageNumber"></span> of <span class="totalPages"></span>' +
"</div>";
/**
* 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<void> {
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");
} 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}`);
}
make-pdf/src/browseClient.ts
-428
View File
@@ -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");
}
make-pdf/src/cli.ts
+6 -5
View File
@@ -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}`);
make-pdf/src/commands.ts
+1 -1
View File
@@ -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: [],
make-pdf/src/diagram-prepass.ts
+207 -219
View File
@@ -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. */
make-pdf/src/orchestrator.ts
+87 -156
View File
@@ -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,73 +216,37 @@ 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 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}`);
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}`);
// 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 */ }
}
const kb = Math.round(fs.statSync(outputPath).size / 1024);
progress.done(`${rendered.meta.wordCount} words · ${kb}KB · ${outputPath}`);
return outputPath;
}
@@ -327,7 +263,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 +293,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 +311,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" :
make-pdf/src/pdftotext.ts
+2 -2
View File
@@ -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 {
make-pdf/src/print-css.ts
+2 -2
View File
@@ -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.
make-pdf/src/render.ts
+2 -2
View File
@@ -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: {
make-pdf/src/setup.ts
+29 -27
View File
@@ -1,52 +1,54 @@
/**
* `$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 { pickEngine, render, renderTmpDir } from "../../lib/aside-render";
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.stderr.write(`\n${engine.error}\n`);
process.exit(4);
}
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.stderr.write(`\n${via} could not render a page: ${err.message}\n`);
process.exit(4);
} 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 +78,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 {
make-pdf/src/types.ts
+10 -37
View File
@@ -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";
}
}