Garry TanandClaude Fable 5.1
444f8feff8
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>
diagram-render
Offline diagram rendering for make-pdf and /diagram. One self-contained HTML
page (dist/diagram-render.html, ~9MB) bundles mermaid, the excalidraw export
utilities, and the official mermaid→excalidraw converter. Callers open it
through lib/aside-render.ts (the TypeScript API make-pdf embeds) or
bin/gstack-render.ts (the CLI the /diagram skill runs) — in the Aside browser
when it is running, otherwise in gstack's own headless browser (the browse
daemon; ENGINE= on the CLI's first line says which). Either way the page's
directory is served on 127.0.0.1 for one render, --eval calls the page API,
and --out copies each result out (strings verbatim, data URLs as bytes).
The built page is committed (eng-review D2): rendering works with zero
network at install time and render time, and there is no npm supply-chain
surface in ./setup. The drift test (test/diagram-render-drift.test.ts)
fails CI if dist/ is edited by hand or falls out of sync with BUILD_INFO.json.
Page API (window functions)
| Function | In → Out |
|---|---|
__renderMermaid(id, text) |
mermaid text → SVG string. id must be unique per fence (mermaid-fence-<n>) — it namespaces every internal SVG id. |
__mermaidToExcalidraw(text) |
mermaid text → .excalidraw scene JSON (flowcharts and sequence diagrams as editable elements; other types fall back to one image element and log Error processing Mermaid diagram to the console). |
__excalidrawToSvg(sceneJson) |
scene JSON → SVG string (Excalifont embedded, offline). |
__rasterize(svg, targetWidthPx) |
SVG → PNG data URL. Callers own DPI math: targetWidthPx = placed width (in) × 300. Throws on tainted canvas. |
__downscaleRaster(dataUri, targetWidthPx, mime) |
raster data URI → smaller data URI at targetWidthPx (same mime). make-pdf uses it to normalize oversized photos to print resolution. |
__mountForScreenshot(svg, px) |
taint-proof fallback: mounts SVG at #raster-stage for gstack-render --screenshot out.png --selector '#raster-stage'. |
__probeImage(src) |
data URI/URL → {width, height} JSON. |
__bundleInfo |
{ name, deps } — pinned dependency versions baked at build. |
Readiness: poll until #status text is ready (or gstack-render ... --wait-selector '#done').
Page errors accumulate in window.__errors.
Updating
# 1. edit the exact pin in package.json
cd lib/diagram-render && bun install
# 2. rebuild (deterministic; build twice → same sha)
bun run build
# 3. commit package.json + bun.lock + dist/ together
Render contract details (securityLevel strict, htmlLabels false, print-css font
lock, <base href> + </scri escaping) are documented in src/entry.ts and
scripts/build.ts — read both before touching either.