mirror of
https://github.com/garrytan/gstack.git
synced 2026-09-10 23:19:09 +02:00
* 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>
533 lines
24 KiB
TypeScript
533 lines
24 KiB
TypeScript
/**
|
||
* Unit tests for the diagram pre-pass: fence extraction, info-string parsing,
|
||
* slot substitution, diagnostic blocks, image inlining policy, and the
|
||
* byte-level image dimension prober, and the bundle runner's script shape
|
||
* (render function injected). No live Aside required — `run: null` makes
|
||
* downscale paths no-ops.
|
||
*/
|
||
import { afterAll, describe, expect, test } from "bun:test";
|
||
import * as fs from "node:fs";
|
||
import * as os from "node:os";
|
||
import * as path from "node:path";
|
||
import zlib from "node:zlib";
|
||
|
||
import {
|
||
StrictModeError,
|
||
buildDiagnosticBlock,
|
||
bundleRunner,
|
||
buildDiagramFigure,
|
||
contentWidthInches,
|
||
dimToInches,
|
||
extractDiagramFences,
|
||
inlineLocalImages,
|
||
parseInfoString,
|
||
substituteSlots,
|
||
decodeFigureSource,
|
||
} from "../src/diagram-prepass";
|
||
import { imageDims } from "../src/image-size";
|
||
import type { RenderResult, RenderSpec } from "../../lib/aside-render";
|
||
|
||
// ─── fence extraction ─────────────────────────────────────────────────
|
||
|
||
describe("extractDiagramFences", () => {
|
||
test("extracts a mermaid fence and replaces it with a token paragraph", () => {
|
||
const md = "# T\n\n```mermaid\ngraph LR\n A --> B\n```\n\ntail";
|
||
const { markdown, fences } = extractDiagramFences(md);
|
||
expect(fences).toHaveLength(1);
|
||
expect(fences[0].lang).toBe("mermaid");
|
||
expect(fences[0].source).toBe("graph LR\n A --> B");
|
||
expect(markdown).toContain(fences[0].token);
|
||
expect(markdown).not.toContain("```mermaid");
|
||
});
|
||
|
||
test("extracts excalidraw fences", () => {
|
||
const md = '```excalidraw\n{"type":"excalidraw","elements":[]}\n```';
|
||
const { fences } = extractDiagramFences(md);
|
||
expect(fences).toHaveLength(1);
|
||
expect(fences[0].lang).toBe("excalidraw");
|
||
});
|
||
|
||
test("render=false keeps the fence as code and strips the flag", () => {
|
||
const md = "```mermaid render=false\ngraph LR\n X --> Y\n```";
|
||
const { markdown, fences } = extractDiagramFences(md);
|
||
expect(fences).toHaveLength(0);
|
||
expect(markdown).toContain("```mermaid\ngraph LR");
|
||
expect(markdown).not.toContain("render=false");
|
||
});
|
||
|
||
test("title is captured from the info string", () => {
|
||
const md = '```mermaid title="Auth flow"\ngraph LR\n A --> B\n```';
|
||
const { fences } = extractDiagramFences(md);
|
||
expect(fences[0].title).toBe("Auth flow");
|
||
});
|
||
|
||
test("non-diagram fences pass through untouched", () => {
|
||
const md = "```js\nconst a = 1;\n```";
|
||
const { markdown, fences } = extractDiagramFences(md);
|
||
expect(fences).toHaveLength(0);
|
||
expect(markdown).toBe(md);
|
||
});
|
||
|
||
test("a mermaid example inside a plain fence is never extracted", () => {
|
||
const md = "````\n```mermaid\ngraph LR\n```\n````";
|
||
const { markdown, fences } = extractDiagramFences(md);
|
||
expect(fences).toHaveLength(0);
|
||
expect(markdown).toBe(md);
|
||
});
|
||
|
||
test("tilde fences work", () => {
|
||
const md = "~~~mermaid\ngraph TD\n A --> B\n~~~";
|
||
const { fences } = extractDiagramFences(md);
|
||
expect(fences).toHaveLength(1);
|
||
});
|
||
|
||
test("unclosed fence at EOF replays verbatim", () => {
|
||
const md = "```mermaid\ngraph LR\n A --> B";
|
||
const { markdown, fences } = extractDiagramFences(md);
|
||
expect(fences).toHaveLength(0);
|
||
expect(markdown).toBe(md);
|
||
});
|
||
|
||
test("multiple fences get distinct ordinals and tokens", () => {
|
||
const md = "```mermaid\nA\n```\n\nmiddle\n\n```mermaid\nB\n```";
|
||
const { fences } = extractDiagramFences(md);
|
||
expect(fences).toHaveLength(2);
|
||
expect(fences[0].ordinal).toBe(1);
|
||
expect(fences[1].ordinal).toBe(2);
|
||
expect(fences[0].token).not.toBe(fences[1].token);
|
||
});
|
||
});
|
||
|
||
describe("parseInfoString", () => {
|
||
test("plain language", () => {
|
||
expect(parseInfoString("mermaid")).toEqual({ lang: "mermaid", render: true, title: undefined });
|
||
});
|
||
test("render=false", () => {
|
||
expect(parseInfoString("mermaid render=false").render).toBe(false);
|
||
});
|
||
test("single-quoted title", () => {
|
||
expect(parseInfoString("mermaid title='Hi there'").title).toBe("Hi there");
|
||
});
|
||
});
|
||
|
||
// ─── slots ────────────────────────────────────────────────────────────
|
||
|
||
describe("substituteSlots", () => {
|
||
test("replaces the <p>-wrapped token with slot HTML", () => {
|
||
const slots = new Map([["gstack-diagram-slot-ab-1", "<figure>X</figure>"]]);
|
||
const html = "<h1>T</h1>\n<p>gstack-diagram-slot-ab-1</p>\n<p>tail</p>";
|
||
const out = substituteSlots(html, slots);
|
||
expect(out).toContain("<figure>X</figure>");
|
||
expect(out).not.toContain("gstack-diagram-slot");
|
||
expect(out).not.toContain("<p><figure>");
|
||
});
|
||
});
|
||
|
||
describe("diagnostic + figure blocks", () => {
|
||
const fence = {
|
||
lang: "mermaid", source: "graph LR\n A --> B", render: true,
|
||
token: "t", ordinal: 3, title: undefined,
|
||
};
|
||
test("diagnostic block escapes error content and names the lang", () => {
|
||
const block = buildDiagnosticBlock(fence, 'Parse <error> "quoted"');
|
||
expect(block).toContain("diagram-error");
|
||
expect(block).toContain("Diagram failed to render (mermaid)");
|
||
expect(block).toContain("Parse <error>");
|
||
expect(block).not.toContain("<error>");
|
||
});
|
||
test("figure carries role=img and ordinal-based aria-label fallback", () => {
|
||
const fig = buildDiagramFigure(fence, "<svg></svg>");
|
||
expect(fig).toContain('role="img"');
|
||
expect(fig).toContain('aria-label="diagram 3"');
|
||
expect(fig).toContain("<svg></svg>");
|
||
});
|
||
test("figure strips scripts from SVG (sanitizer second layer)", () => {
|
||
const fig = buildDiagramFigure(fence, "<svg><script>alert(1)</script><g/></svg>");
|
||
expect(fig).not.toContain("<script>");
|
||
});
|
||
test("title becomes aria-label and caption", () => {
|
||
const fig = buildDiagramFigure({ ...fence, title: "Auth flow" }, "<svg></svg>");
|
||
expect(fig).toContain('aria-label="Auth flow"');
|
||
expect(fig).toContain("diagram-caption");
|
||
});
|
||
test("embedded source round-trips mermaid arrows exactly", () => {
|
||
const source = "graph LR\n A --> B\n B -->|label with $& and `ticks`| C";
|
||
const fig = buildDiagramFigure({ ...fence, source }, "<svg></svg>");
|
||
expect(decodeFigureSource(fig)).toBe(source);
|
||
});
|
||
test("slot substitution is immune to $-replacement patterns in labels", () => {
|
||
const slotHtml = `<figure>label says $' and $& here</figure>`;
|
||
const out = substituteSlots("<p>tok-x</p><p>tail</p>", new Map([["tok-x", slotHtml]]));
|
||
expect(out).toContain("label says $' and $& here");
|
||
expect(out).toContain("<p>tail</p>");
|
||
expect(out).not.toContain("tailtail"); // $' expansion would duplicate the tail
|
||
});
|
||
});
|
||
|
||
// ─── image dimension probing ──────────────────────────────────────────
|
||
|
||
function tinyPng(w: number, h: number): Buffer {
|
||
const chunk = (t: string, d: Buffer) => {
|
||
const body = Buffer.concat([Buffer.from(t, "ascii"), d]);
|
||
const len = Buffer.alloc(4);
|
||
len.writeUInt32BE(d.length);
|
||
const crc = Buffer.alloc(4);
|
||
crc.writeUInt32BE(zlib.crc32 ? zlib.crc32(body) : 0);
|
||
return Buffer.concat([len, body, crc]);
|
||
};
|
||
const ihdr = Buffer.alloc(13);
|
||
ihdr.writeUInt32BE(w, 0);
|
||
ihdr.writeUInt32BE(h, 4);
|
||
ihdr[8] = 8; ihdr[9] = 2;
|
||
const raw = Buffer.concat(
|
||
Array.from({ length: h }, () => Buffer.concat([Buffer.from([0]), Buffer.alloc(w * 3, 0x80)])),
|
||
);
|
||
return Buffer.concat([
|
||
Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
|
||
chunk("IHDR", ihdr),
|
||
chunk("IDAT", zlib.deflateSync(raw)),
|
||
chunk("IEND", Buffer.alloc(0)),
|
||
]);
|
||
}
|
||
|
||
describe("imageDims", () => {
|
||
test("PNG", () => {
|
||
expect(imageDims(tinyPng(640, 480))).toEqual({ width: 640, height: 480, mime: "image/png" });
|
||
});
|
||
test("GIF", () => {
|
||
const b = Buffer.alloc(13);
|
||
b.write("GIF89a", 0, "ascii");
|
||
b.writeUInt16LE(320, 6);
|
||
b.writeUInt16LE(200, 8);
|
||
expect(imageDims(b)).toEqual({ width: 320, height: 200, mime: "image/gif" });
|
||
});
|
||
test("JPEG (SOF0)", () => {
|
||
const b = Buffer.from([
|
||
0xff, 0xd8, // SOI
|
||
0xff, 0xe0, 0x00, 0x04, 0x00, 0x00, // APP0 len 4
|
||
0xff, 0xc0, 0x00, 0x0b, 0x08, 0x01, 0x00, 0x02, 0x00, 0x03, 0x00, 0x00, 0x00, // SOF0 h=256 w=512
|
||
]);
|
||
expect(imageDims(b)).toEqual({ width: 512, height: 256, mime: "image/jpeg" });
|
||
});
|
||
test("SVG via width/height attrs", () => {
|
||
const b = Buffer.from('<svg xmlns="x" width="800" height="400"></svg>');
|
||
expect(imageDims(b)).toEqual({ width: 800, height: 400, mime: "image/svg+xml" });
|
||
});
|
||
test("SVG via viewBox", () => {
|
||
const b = Buffer.from('<svg viewBox="0 0 1200 600"></svg>');
|
||
expect(imageDims(b)).toEqual({ width: 1200, height: 600, mime: "image/svg+xml" });
|
||
});
|
||
test("unknown bytes → null", () => {
|
||
expect(imageDims(Buffer.from("definitely not an image, sorry"))).toBeNull();
|
||
});
|
||
});
|
||
|
||
// ─── content-box math ─────────────────────────────────────────────────
|
||
|
||
describe("content width", () => {
|
||
test("letter with 1in margins = 6.5in", () => {
|
||
expect(contentWidthInches({})).toBeCloseTo(6.5);
|
||
});
|
||
test("a4 with 25mm margins", () => {
|
||
expect(contentWidthInches({ pageSize: "a4", margins: "25mm" })).toBeCloseTo(8.27 - 50 / 25.4, 2);
|
||
});
|
||
test("dimToInches parses pt/cm/mm/px", () => {
|
||
expect(dimToInches("72pt", 1)).toBeCloseTo(1);
|
||
expect(dimToInches("2.54cm", 1)).toBeCloseTo(1);
|
||
expect(dimToInches("25.4mm", 1)).toBeCloseTo(1);
|
||
expect(dimToInches("96px", 1)).toBeCloseTo(1);
|
||
expect(dimToInches("garbage", 1.5)).toBe(1.5);
|
||
});
|
||
});
|
||
|
||
// ─── image inlining ───────────────────────────────────────────────────
|
||
|
||
describe("inlineLocalImages", () => {
|
||
const dir = fs.mkdtempSync(path.join(os.tmpdir(), "prepass-img-"));
|
||
fs.writeFileSync(path.join(dir, "ok.png"), tinyPng(40, 20));
|
||
afterAll(() => {
|
||
try { fs.rmSync(dir, { recursive: true, force: true }); } catch { /* best-effort */ }
|
||
});
|
||
|
||
const base = {
|
||
inputDir: dir,
|
||
strict: false,
|
||
allowNetwork: false,
|
||
contentWidthIn: 6.5,
|
||
run: null,
|
||
};
|
||
|
||
test("local image becomes a data URI with probed dimensions", async () => {
|
||
const warnings: string[] = [];
|
||
const out = await inlineLocalImages(`<img src="ok.png" alt="x">`, { ...base, warn: (m) => warnings.push(m) });
|
||
expect(out).toContain("data:image/png;base64,");
|
||
expect(out).toContain('data-gstack-px-width="40"');
|
||
expect(out).toContain('data-gstack-px-height="20"');
|
||
expect(warnings).toHaveLength(0);
|
||
});
|
||
|
||
test("missing image → visible placeholder + warning", async () => {
|
||
const warnings: string[] = [];
|
||
const out = await inlineLocalImages(`<img src="nope.png">`, { ...base, warn: (m) => warnings.push(m) });
|
||
expect(out).toContain("image-missing");
|
||
expect(out).toContain("nope.png");
|
||
expect(warnings.length).toBe(1);
|
||
});
|
||
|
||
test("missing image + --strict → StrictModeError", async () => {
|
||
await expect(
|
||
inlineLocalImages(`<img src="nope.png">`, { ...base, strict: true, warn: () => {} }),
|
||
).rejects.toThrow(StrictModeError);
|
||
});
|
||
|
||
test("remote image is BLOCKED with a visible placeholder (offline posture)", async () => {
|
||
// Leaving the tag would make Chromium fetch it at print time anyway —
|
||
// the offline posture must remove the src, not just warn about it.
|
||
const warnings: string[] = [];
|
||
const tag = `<img src="https://example.com/x.png">`;
|
||
const out = await inlineLocalImages(tag, { ...base, warn: (m) => warnings.push(m) });
|
||
expect(out).not.toContain("https://example.com/x.png\"");
|
||
expect(out).toContain("remote image blocked");
|
||
expect(warnings[0]).toContain("offline");
|
||
});
|
||
|
||
test("symlink escaping the input dir is caught by the realpath check", async () => {
|
||
const outside = fs.mkdtempSync(path.join(os.tmpdir(), "prepass-symlink-"));
|
||
fs.writeFileSync(path.join(outside, "secret.png"), tinyPng(5, 5));
|
||
const link = path.join(dir, "innocent.png");
|
||
try {
|
||
fs.symlinkSync(path.join(outside, "secret.png"), link);
|
||
const warnings: string[] = [];
|
||
await inlineLocalImages(`<img src="innocent.png">`, { ...base, warn: (m) => warnings.push(m) });
|
||
expect(warnings.some((w) => w.includes("OUTSIDE the input directory"))).toBe(true);
|
||
} finally {
|
||
try { fs.unlinkSync(link); } catch { /* ignore */ }
|
||
fs.rmSync(outside, { recursive: true, force: true });
|
||
}
|
||
});
|
||
|
||
test("special files and oversized images degrade to placeholders, never hang", async () => {
|
||
// Directory masquerading as an image — not a regular file.
|
||
fs.mkdirSync(path.join(dir, "dir.png"), { recursive: true });
|
||
const warnings: string[] = [];
|
||
const out = await inlineLocalImages(`<img src="dir.png">`, { ...base, warn: (m) => warnings.push(m) });
|
||
expect(out).toContain("image-missing");
|
||
expect(warnings.some((w) => w.includes("not a regular file"))).toBe(true);
|
||
});
|
||
|
||
test("malformed percent-encoding degrades to missing-image, never throws", async () => {
|
||
const warnings: string[] = [];
|
||
const out = await inlineLocalImages(`<img src="foo%zz.png">`, { ...base, warn: (m) => warnings.push(m) });
|
||
expect(out).toContain("image-missing");
|
||
});
|
||
|
||
test("remote image + --allow-network passes silently", async () => {
|
||
const warnings: string[] = [];
|
||
const tag = `<img src="https://example.com/x.png">`;
|
||
const out = await inlineLocalImages(tag, { ...base, allowNetwork: true, warn: (m) => warnings.push(m) });
|
||
expect(out).toBe(tag);
|
||
expect(warnings).toHaveLength(0);
|
||
});
|
||
|
||
test("remote image + --strict → StrictModeError", async () => {
|
||
await expect(
|
||
inlineLocalImages(`<img src="https://example.com/x.png">`, { ...base, strict: true, warn: () => {} }),
|
||
).rejects.toThrow(StrictModeError);
|
||
});
|
||
|
||
test("existing data URI gets dimension annotations only", async () => {
|
||
const uri = `data:image/png;base64,${tinyPng(33, 44).toString("base64")}`;
|
||
const out = await inlineLocalImages(`<img src="${uri}">`, { ...base, warn: () => {} });
|
||
expect(out).toContain('data-gstack-px-width="33"');
|
||
expect(out).toContain('data-gstack-px-height="44"');
|
||
});
|
||
|
||
test("out-of-tree image reads warn (never silent) and still inline", async () => {
|
||
const outside = fs.mkdtempSync(path.join(os.tmpdir(), "prepass-outside-"));
|
||
fs.writeFileSync(path.join(outside, "ext.png"), tinyPng(10, 10));
|
||
try {
|
||
const warnings: string[] = [];
|
||
const out = await inlineLocalImages(`<img src="${path.join(outside, "ext.png")}">`, {
|
||
...base, warn: (m) => warnings.push(m),
|
||
});
|
||
expect(out).toContain("data:image/png;base64,");
|
||
expect(warnings.some((w) => w.includes("OUTSIDE the input directory"))).toBe(true);
|
||
} finally {
|
||
fs.rmSync(outside, { recursive: true, force: true });
|
||
}
|
||
});
|
||
|
||
test("out-of-tree image + --strict → StrictModeError", async () => {
|
||
const outside = fs.mkdtempSync(path.join(os.tmpdir(), "prepass-outside-"));
|
||
fs.writeFileSync(path.join(outside, "ext.png"), tinyPng(10, 10));
|
||
try {
|
||
await expect(
|
||
inlineLocalImages(`<img src="${path.join(outside, "ext.png")}">`, {
|
||
...base, strict: true, warn: () => {},
|
||
}),
|
||
).rejects.toThrow(StrictModeError);
|
||
} finally {
|
||
fs.rmSync(outside, { recursive: true, force: true });
|
||
}
|
||
});
|
||
|
||
test("Windows drive-letter src is treated as a local path, not a URL scheme", async () => {
|
||
// C:/x.png matches the single-letter-scheme regex — it must reach the
|
||
// local-path branch (and the missing-file placeholder), never silently
|
||
// pass through as an unknown URL.
|
||
const warnings: string[] = [];
|
||
const out = await inlineLocalImages(`<img src="C:/missing/x.png">`, { ...base, warn: (m) => warnings.push(m) });
|
||
expect(out).toContain("image-missing");
|
||
// Two warnings: it's out-of-tree (resolved outside inputDir) AND missing.
|
||
expect(warnings.some((w) => w.includes("image not found"))).toBe(true);
|
||
});
|
||
|
||
test("indented fences inside lists replay byte-for-byte (no list splitting)", () => {
|
||
const md = "- item\n\n ```js\n code();\n ```\n\n- next";
|
||
const { markdown, fences } = extractDiagramFences(md);
|
||
expect(fences).toHaveLength(0);
|
||
expect(markdown).toBe(md);
|
||
});
|
||
|
||
test("indented mermaid fences are NOT extracted (column-0 placeholder would split the list)", () => {
|
||
const md = "- item\n\n ```mermaid\n graph LR\n ```\n";
|
||
const { markdown, fences } = extractDiagramFences(md);
|
||
expect(fences).toHaveLength(0);
|
||
expect(markdown).toBe(md);
|
||
});
|
||
|
||
test("oversized raster without a tab inlines at full size with no downscale", async () => {
|
||
// 6000px-wide PNG header (body irrelevant for probing; file must exist)
|
||
fs.writeFileSync(path.join(dir, "wide.png"), tinyPng(6000, 100));
|
||
const warnings: string[] = [];
|
||
const out = await inlineLocalImages(`<img src="wide.png">`, { ...base, warn: (m) => warnings.push(m) });
|
||
expect(out).toContain('data-gstack-px-width="6000"');
|
||
});
|
||
|
||
test("oversized raster WITH a runner: one __downscaleRaster batch, token swapped for the scaled bytes", async () => {
|
||
fs.writeFileSync(path.join(dir, "wide2.png"), tinyPng(6000, 100));
|
||
const calls: Array<{ fn: string; args: unknown[] }> = [];
|
||
const run = async (batch: Array<{ fn: string; args: unknown[] }>) => {
|
||
calls.push(...batch);
|
||
return batch.map(() => ({ ok: true as const, value: "data:image/png;base64,U0NBTEVE" }));
|
||
};
|
||
const warnings: string[] = [];
|
||
// Same image twice: read/downscaled once, both tags rewritten.
|
||
const out = await inlineLocalImages(`<img src="wide2.png"> <img src="wide2.png" alt="b">`, { ...base, run, warn: (m) => warnings.push(m) });
|
||
expect(calls).toHaveLength(1);
|
||
expect(calls[0].fn).toBe("__downscaleRaster");
|
||
expect(String(calls[0].args[0])).toStartWith("data:image/png;base64,");
|
||
expect(calls[0].args[1]).toBe(1950); // 6.5in × 300dpi
|
||
expect(out.match(/data:image\/png;base64,U0NBTEVE/g)).toHaveLength(2);
|
||
expect(out).toContain('data-gstack-px-width="1950"');
|
||
expect(out).not.toContain("gstack-downscale-slot");
|
||
expect(warnings.some((w) => w.includes("downscaled wide2.png 6000px"))).toBe(true);
|
||
});
|
||
|
||
test("a failed downscale falls back to the full-size bytes with a warning", async () => {
|
||
fs.writeFileSync(path.join(dir, "wide3.png"), tinyPng(6000, 100));
|
||
const run = async (batch: unknown[]) => batch.map(() => ({ ok: false as const, error: "image decode failed" }));
|
||
const warnings: string[] = [];
|
||
const out = await inlineLocalImages(`<img src="wide3.png">`, { ...base, run, warn: (m) => warnings.push(m) });
|
||
expect(out).toContain('data-gstack-px-width="6000"');
|
||
expect(out).toContain("data:image/png;base64,");
|
||
expect(out).not.toContain("gstack-downscale-slot");
|
||
expect(warnings.some((w) => w.includes("downscale failed"))).toBe(true);
|
||
});
|
||
});
|
||
|
||
// ─── bundle runner (script shape, injected render) ────────────────────
|
||
|
||
describe("bundleRunner", () => {
|
||
const bundle = path.join(os.tmpdir(), `fake-bundle-${process.pid}.html`);
|
||
fs.writeFileSync(bundle, "<!doctype html><div id=done>ready</div>");
|
||
afterAll(() => { try { fs.unlinkSync(bundle); } catch { /* best-effort */ } });
|
||
|
||
/** Fake Aside: asserts the spec shape and writes OK:/ERR: result files. */
|
||
function fakeRender(script: (fn: string, args: unknown[]) => string) {
|
||
const specs: RenderSpec[] = [];
|
||
const render = async (spec: RenderSpec): Promise<RenderResult> => {
|
||
specs.push(spec);
|
||
for (const step of spec.steps) {
|
||
if (step.kind !== "eval" || !step.out) throw new Error("expected eval steps with out files");
|
||
const i = Number(step.expression.match(/call-(\d+)\.json/)![1]);
|
||
const fn = step.expression.match(/window\["(__\w+)"\]/)![1];
|
||
const args = JSON.parse(fs.readFileSync(path.join(spec.serveRoot!, `call-${i}.json`), "utf8"));
|
||
let text: string;
|
||
try { text = "OK:" + script(fn, args); } catch (e: any) { text = "ERR:" + e.message; }
|
||
fs.writeFileSync(step.out, text);
|
||
}
|
||
return { ok: true, outputs: [], evals: {}, stdout: "" };
|
||
};
|
||
return { render, specs };
|
||
}
|
||
|
||
test("stages the bundle + one JSON args file per call in a served dir, waits for #done, reads results back", async () => {
|
||
const { render, specs } = fakeRender((fn, args) => `${fn}(${args.join(",")})`);
|
||
const run = bundleRunner({ bundlePath: bundle, render });
|
||
const results = await run([
|
||
{ fn: "__renderMermaid", args: ["mermaid-fence-1", "graph LR"] },
|
||
{ fn: "__excalidrawToSvg", args: ["{}"] },
|
||
]);
|
||
expect(results).toEqual([
|
||
{ ok: true, value: "__renderMermaid(mermaid-fence-1,graph LR)" },
|
||
{ ok: true, value: "__excalidrawToSvg({})" },
|
||
]);
|
||
expect(specs).toHaveLength(1);
|
||
const spec = specs[0];
|
||
expect(spec.waitFor).toEqual({ selector: "#done", timeoutMs: 20_000 });
|
||
expect(path.dirname(spec.file)).toBe(spec.serveRoot);
|
||
expect(spec.steps).toHaveLength(2);
|
||
// Payload rides the served dir, not argv: the expression stays tiny.
|
||
for (const step of spec.steps) expect(step.kind === "eval" && step.expression.length < 300).toBe(true);
|
||
// Private per-script dir is cleaned up.
|
||
expect(fs.existsSync(spec.serveRoot!)).toBe(false);
|
||
});
|
||
|
||
test("a throwing call is an ERR result; the other calls in the script still succeed", async () => {
|
||
const { render } = fakeRender((_fn, args) => {
|
||
if (String(args[1]).includes("BROKEN")) throw new Error("Parse error on line 1");
|
||
return "<svg/>";
|
||
});
|
||
const run = bundleRunner({ bundlePath: bundle, render });
|
||
const results = await run([
|
||
{ fn: "__renderMermaid", args: ["a", "ok"] },
|
||
{ fn: "__renderMermaid", args: ["b", "BROKEN"] },
|
||
{ fn: "__renderMermaid", args: ["c", "ok"] },
|
||
]);
|
||
expect(results.map((r) => r.ok)).toEqual([true, false, true]);
|
||
expect(results[1]).toEqual({ ok: false, error: "Parse error on line 1" });
|
||
});
|
||
|
||
test("chunks at 40 calls per script (Aside's 120s script cap)", async () => {
|
||
const { render, specs } = fakeRender(() => "x");
|
||
const run = bundleRunner({ bundlePath: bundle, render });
|
||
const results = await run(Array.from({ length: 85 }, (_, i) => ({ fn: "__renderMermaid", args: [`m${i}`, "g"] })));
|
||
expect(results).toHaveLength(85);
|
||
expect(specs.map((s) => s.steps.length)).toEqual([40, 40, 5]);
|
||
});
|
||
|
||
test("a whole-script failure fails every call in it with the renderer's message", async () => {
|
||
const render = async (): Promise<RenderResult> => ({ ok: false, outputs: [], evals: {}, stdout: "", error: "aside repl did not run: spawn aside ENOENT" });
|
||
const run = bundleRunner({ bundlePath: bundle, render });
|
||
const results = await run([{ fn: "__renderMermaid", args: ["a", "g"] }, { fn: "__renderMermaid", args: ["b", "g"] }]);
|
||
expect(results).toHaveLength(2);
|
||
for (const r of results) {
|
||
expect(r.ok).toBe(false);
|
||
if (!r.ok) expect(r.error).toContain("diagram renderer: aside repl did not run");
|
||
}
|
||
});
|
||
|
||
test("an unreadable bundle fails every call without touching Aside; zero calls run nothing", async () => {
|
||
let rendered = 0;
|
||
const render = async (): Promise<RenderResult> => { rendered++; return { ok: true, outputs: [], evals: {}, stdout: "" }; };
|
||
const run = bundleRunner({ bundlePath: "/nonexistent/diagram-render.html", render });
|
||
expect(await run([])).toEqual([]);
|
||
const results = await run([{ fn: "__renderMermaid", args: ["a", "g"] }, { fn: "__renderMermaid", args: ["b", "g"] }]);
|
||
expect(results.map((r) => r.ok)).toEqual([false, false]);
|
||
if (!results[0].ok) expect(results[0].error).toContain("ENOENT");
|
||
expect(rendered).toBe(0);
|
||
});
|
||
|
||
});
|