Files
gstack/make-pdf/src/diagram-prepass.ts
T
Garry Tanandcapy-ai[bot] 0dbc60708e fix(make-pdf): read local images only from the document's directory, and only image files (GST-1747) (#4113)
* fix(make-pdf): read local images only from the document's directory, and only image files (GST-1747)

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix(make-pdf): inline a local file only when its bytes match its image format

A file with an image extension now needs that format's signature (or a recognized size header) before it is inlined; anything else gets the blocked placeholder, and --strict throws. The docx ICNS test now sees the local file blocked by the prepass and the inline data URI dropped by the docx guard.

Review-Finding: p1/specialist-batched#1 reader=security
Review-Finding: p1/specialist-batched#2 reader=testing
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

* fix(make-pdf): compare image paths with path.relative so a root-level document keeps its images

A markdown file at the filesystem root made the containment prefix '//' (or 'C:\\'), which no path matched.

Review-Finding: v1/adversarial-native#5 reader=adversarial-native
Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>

---------

Co-authored-by: capy-ai[bot] <230910855+capy-ai[bot]@users.noreply.github.com>
2026-11-07 06:53:27 +00:00

868 lines
35 KiB
TypeScript
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
/**
* Diagram + image pre-pass. Runs between "read markdown" and render() in the
* orchestrator, and owns everything that needs the diagram-render bundle.
*
* markdown ─▶ extractDiagramFences() ──▶ render() (marked+sanitize+smarty)
* │ fences → placeholder tokens │
* │ ▼
* └─▶ renderFenceSlots() ───────────▶ substituteSlots(html, slots)
* one browser render per batch │
* error ⇒ diagnostic block ▼
* inlineLocalImages(html)
* data URIs, probe dims from bytes,
* downscale >2x content box @300dpi,
* remote warn / missing placeholder /
* --strict hard-fail
*
* Placeholders survive marked, the sanitizer, and smartypants because they are
* plain hyphenated lowercase tokens with no quotes or HTML. Slot HTML is run
* through the same sanitizer as user content before substitution (the bundle
* renders with securityLevel strict — the sanitizer is the second layer).
*
* 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";
import * as os from "node:os";
import * as path from "node:path";
import * as crypto from "node:crypto";
import { fileURLToPath } from "node:url";
import { render as renderHtml, renderTmpDir } from "../../lib/aside-render";
import { escapeHtml, sanitizeUntrustedHtml } from "./render";
import { imageDims } from "./image-size";
// ─── Types ────────────────────────────────────────────────────────────
export interface DiagramFence {
/** "mermaid" | "excalidraw" */
lang: string;
/** Fence body (the diagram source). */
source: string;
/** Optional title="..." from the fence info string (a11y label, D6.4). */
title?: string;
/** Optional page=landscape|portrait fence directive (image-policy override). */
page?: "landscape" | "portrait";
/** render=false → leave as a plain code block (escape hatch, D6.3). */
render: boolean;
/** Placeholder token substituted into the markdown. */
token: string;
/** 1-based ordinal among rendered fences (unique ids, aria fallback). */
ordinal: number;
}
export interface FenceExtraction {
markdown: string;
fences: DiagramFence[];
}
export interface PrepassWarnings {
warn: (msg: string) => void;
}
export interface PrepassImageOptions {
/** Directory of the source markdown — relative image paths resolve here. */
inputDir: string;
/** Hard-fail on missing/remote images instead of warn (D6.1). */
strict: boolean;
/** Remote images are left untouched when network is explicitly allowed. */
allowNetwork: boolean;
/** Physical content-box width in inches (page width minus margins). */
contentWidthIn: number;
warn: (msg: string) => void;
/** Bundle runner for print-resolution downscaling; null = inline at full size. */
run: BundleRun | null;
}
/** Print-resolution policy (eng-review D4): downscale rasters wider than
* 2 × contentWidth × 300dpi down to contentWidth × 300dpi. */
const PRINT_DPI = 300;
const DOWNSCALE_FACTOR = 2;
/** Per-image read ceiling — bounds memory before any policy runs. */
const MAX_IMAGE_BYTES = 64 * 1024 * 1024;
export class StrictModeError extends Error {
constructor(msg: string) {
super(msg);
this.name = "StrictModeError";
}
}
// ─── Fence extraction (pure) ──────────────────────────────────────────
const DIAGRAM_LANGS = new Set(["mermaid", "excalidraw"]);
/**
* Extract column-0 ```mermaid / ```excalidraw fences, replacing each with a
* unique placeholder token paragraph. Backtick and tilde fences, any length
* >= 3; closers must be at least as long as the opener (CommonMark). Fences
* with `render=false` are left untouched.
*
* Two deliberate conservatisms (red-team finding — the original version
* reconstructed fences at column 0 and restructured lists):
* - Non-diagram fences replay as their ORIGINAL raw lines, byte-for-byte
* (only a render=false flag is removed, in place, preserving indent).
* - INDENTED diagram fences (inside lists/quotes) are NOT extracted — a
* column-0 placeholder would split the list. They replay verbatim as code.
*/
export function extractDiagramFences(markdown: string): FenceExtraction {
const lines = markdown.split("\n");
const out: string[] = [];
const fences: DiagramFence[] = [];
const runId = crypto.randomBytes(4).toString("hex");
let i = 0;
let openFence: {
char: string; len: number; indent: number; info: string;
rawOpener: string; body: string[];
} | null = null;
let ordinal = 0;
while (i < lines.length) {
const line = lines[i];
if (openFence) {
const close = matchFenceLine(line);
if (close && close.char === openFence.char && close.len >= openFence.len && close.info === "") {
const info = parseInfoString(openFence.info);
if (DIAGRAM_LANGS.has(info.lang) && info.render && openFence.indent === 0) {
ordinal++;
const token = `gstack-diagram-slot-${runId}-${ordinal}`;
fences.push({
lang: info.lang,
source: openFence.body.join("\n"),
title: info.title,
page: info.page,
render: true,
token,
ordinal,
});
out.push("", token, "");
} else {
// Not extracted (other language, render=false, or indented): replay
// the ORIGINAL lines verbatim; only strip a render=false flag.
out.push(stripRenderFalse(openFence.rawOpener));
out.push(...openFence.body);
out.push(line);
}
openFence = null;
i++;
continue;
}
openFence.body.push(line);
i++;
continue;
}
const open = matchFenceLine(line);
if (open && open.info !== "") {
openFence = { ...open, rawOpener: line, body: [] };
i++;
continue;
}
if (open) {
// Anonymous fence (plain code block) — copy through to its closer so a
// ```mermaid example INSIDE a plain fence is never extracted.
out.push(line);
i++;
while (i < lines.length) {
const l = lines[i];
const close = matchFenceLine(l);
out.push(l);
i++;
if (close && close.char === open.char && close.len >= open.len && close.info === "") break;
}
continue;
}
out.push(line);
i++;
}
// Unclosed fence at EOF: replay verbatim (CommonMark treats it as code to EOF).
if (openFence) {
out.push(openFence.rawOpener);
out.push(...openFence.body);
}
return { markdown: out.join("\n"), fences };
}
function matchFenceLine(line: string): { char: string; len: number; indent: number; info: string } | null {
const m = line.match(/^( {0,3})(`{3,}|~{3,})\s*(.*)$/);
if (!m) return null;
return { indent: m[1].length, char: m[2][0], len: m[2].length, info: m[3].trim() };
}
/** Remove a render=false flag from a raw opener line, preserving everything else. */
function stripRenderFalse(rawOpener: string): string {
return rawOpener.replace(/\s*\brender\s*=\s*false\b/i, "");
}
/** Parse a fence info string: `mermaid`, `mermaid render=false`,
* `mermaid title="Auth flow"`, `mermaid page=landscape`. */
export function parseInfoString(info: string): {
lang: string; render: boolean; title?: string; page?: "landscape" | "portrait";
} {
const lang = (info.match(/^\S+/)?.[0] ?? "").toLowerCase();
const render = !/\brender\s*=\s*false\b/i.test(info);
const title = info.match(/\btitle\s*=\s*"([^"]*)"/i)?.[1]
?? info.match(/\btitle\s*=\s*'([^']*)'/i)?.[1];
const pageRaw = info.match(/\bpage\s*=\s*(landscape|portrait)\b/i)?.[1]?.toLowerCase();
const page = pageRaw === "landscape" || pageRaw === "portrait" ? pageRaw : undefined;
return { lang, render, title, page };
}
// ─── Slot substitution (pure) ─────────────────────────────────────────
/**
* Replace placeholder tokens in rendered HTML with their final slot HTML.
* marked wraps the bare token line in <p>…</p>; replace the wrapper too so
* the figure isn't nested inside a paragraph.
*/
export function substituteSlots(html: string, slots: Map<string, string>): string {
let s = html;
for (const [token, slotHtml] of slots) {
// Function replacement is load-bearing: slot HTML carries user/LLM-authored
// diagram label text, and string-form replace() expands $&, $', $` patterns
// inside it — a label containing "$'" would duplicate the document tail.
const wrapped = new RegExp(`<p>\\s*${token}\\s*</p>`, "g");
const replaced = s.replace(wrapped, () => slotHtml);
s = replaced !== s ? replaced : s.split(token).join(slotHtml);
}
return s;
}
/**
* Visible diagnostic block for a failed fence render — never silent raw code
* (eng-review: explicit error blocks). Sanitizer-safe: all dynamic content is
* HTML-escaped.
*/
export function buildDiagnosticBlock(fence: DiagramFence, errorMessage: string): string {
const excerpt = fence.source.split("\n").slice(0, 8).join("\n");
const truncated = fence.source.split("\n").length > 8 ? "\n…" : "";
return [
`<figure class="diagram diagram-error" role="img" aria-label="${escapeHtml(diagramLabel(fence))} (failed to render)">`,
`<figcaption class="diagram-error-title">Diagram failed to render (${escapeHtml(fence.lang)})</figcaption>`,
`<pre class="diagram-error-detail">${escapeHtml(errorMessage.trim())}\n\n${escapeHtml(excerpt + truncated)}</pre>`,
`</figure>`,
].join("\n");
}
/**
* Wrap a rendered SVG in an accessible figure (D6.4). The raw fence source is
* preserved base64-encoded in a data attribute — an HTML comment would need
* `--` escaping, which corrupts every mermaid arrow (`-->`) and breaks
* round-trip recovery.
*/
export function buildDiagramFigure(fence: DiagramFence, svg: string): string {
const label = diagramLabel(fence);
const cleanSvg = sanitizeUntrustedHtml(svg);
const captioned = fence.title
? `\n<figcaption class="diagram-caption">${escapeHtml(fence.title)}</figcaption>`
: "";
const pageAttr = fence.page ? ` data-gstack-page="${fence.page}"` : "";
const sourceB64 = Buffer.from(fence.source, "utf8").toString("base64");
return [
`<figure class="diagram" role="img" aria-label="${escapeHtml(label)}"${pageAttr}` +
` data-gstack-lang="${escapeHtml(fence.lang)}" data-gstack-source="${sourceB64}">`,
cleanSvg,
captioned,
`</figure>`,
].join("\n");
}
/** Recover the original fence source from a rendered figure (round-trip). */
export function decodeFigureSource(figureHtml: string): string | null {
const m = figureHtml.match(/\bdata-gstack-source="([A-Za-z0-9+/=]*)"/);
if (!m) return null;
try {
return Buffer.from(m[1], "base64").toString("utf8");
} catch {
return null;
}
}
function diagramLabel(fence: DiagramFence): string {
return fence.title ?? `diagram ${fence.ordinal}`;
}
// ─── 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 READY_TIMEOUT_MS = 20_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;
/**
* 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 {
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 });
}
return results;
};
}
/**
* 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 });
}
}
/** Resolve dist/diagram-render.html: env override → repo-relative (dev) → global install. */
export function resolveBundlePath(env: NodeJS.ProcessEnv = process.env): string {
const candidates = [
env.GSTACK_DIAGRAM_BUNDLE,
// dev: make-pdf/src/* → repo root lib/. (In a compiled binary this is the
// virtual /$bunfs/root and simply never exists — harmless.)
path.resolve(import.meta.dir, "../../lib/diagram-render/dist/diagram-render.html"),
// compiled binary at <root>/make-pdf/dist/pdf → <root>/lib/… — same shape
// in the repo and in the ~/.claude/skills/gstack global install. argv[0]
// is the literal string "bun" in compiled binaries; execPath is real.
path.resolve(path.dirname(process.execPath), "../../lib/diagram-render/dist/diagram-render.html"),
path.join(os.homedir(), ".claude/skills/gstack/lib/diagram-render/dist/diagram-render.html"),
].filter((p): p is string => !!p);
for (const p of candidates) {
if (fs.existsSync(p)) return p;
}
throw new Error(
"diagram-render bundle not found. Tried:\n" +
candidates.map((c) => ` - ${c}`).join("\n") +
"\nRun `bun run build:diagram-render` (repo) or re-run ./setup (install).",
);
}
// ─── Fence rendering ──────────────────────────────────────────────────
/**
* Render every extracted fence to its slot HTML in one batch. A failed fence
* yields a visible diagnostic block; the others still render.
*/
export async function renderFenceSlots(
fences: DiagramFence[],
run: BundleRun,
warn: (msg: string) => void,
): 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) {
if (fence.lang !== "mermaid") {
try {
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;
}
// ─── DOCX rasterization (eng-review D6.5, P8) ─────────────────────────
/**
* 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. Two passes: swap
* each target for a token while collecting its bundle call, run the batch,
* substitute results.
*/
export async function rasterizeDiagramFigures(
html: string,
run: BundleRun,
contentWidthIn: number,
warn: (msg: string) => void,
): 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(
/<figure class="diagram"[^>]*>[\s\S]*?<\/figure>/gi,
(figure) => {
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";
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");
},
);
},
);
// 2. SVG data-URI images (inlined .svg files) → PNG.
out = out.replace(/<img\b[^>]*>/gi, (tag) => {
const m = tag.match(SRC_RE);
const src = m?.[2] ?? m?.[3] ?? "";
if (!src.startsWith("data:image/svg+xml")) return tag;
const svgText = Buffer.from(src.slice(src.indexOf(",") + 1), "base64").toString("utf8");
return enqueue(
svgText,
// Function replacement: data URIs can contain $-patterns.
(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;
}
/**
* Diagnostic figures → plain <p>/<pre> for the DOCX converter, which drops
* <figure> elements it can't map. An invisible error is the one thing the
* diagnostic contract forbids. Pure — no render tab needed.
*/
export function convertDiagnosticsForDocx(html: string): string {
return html.replace(
/<figure class="diagram diagram-error"[^>]*>([\s\S]*?)<\/figure>/gi,
(_full, body: string) => {
const title = body.match(/<figcaption[^>]*>([\s\S]*?)<\/figcaption>/i)?.[1] ?? "Diagram failed to render";
const detail = body.match(/<pre[^>]*>([\s\S]*?)<\/pre>/i)?.[1] ?? "";
return `<p><strong>${title}</strong></p>\n<pre>${detail}</pre>`;
},
);
}
// ─── Image inlining (eng-review D1 + D4 + D6.1) ───────────────────────
const IMG_TAG_RE = /<img\b[^>]*>/gi;
const SRC_RE = /\bsrc\s*=\s*("([^"]*)"|'([^']*)')/i;
/**
* Inline every local <img> as a data URI, probe intrinsic dimensions from the
* bytes, and annotate the tag with data-gstack-px-width/-height for the width
* policy. Oversized rasters are downscaled to print resolution via the bundle
* tab. Missing files become visible placeholders (or throw under --strict);
* remote URLs warn (offline posture) unless --allow-network.
*/
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 };
}> = [];
const out = html.replace(IMG_TAG_RE, (tag) => {
const srcMatch = tag.match(SRC_RE);
if (!srcMatch) return tag;
const src = srcMatch[2] ?? srcMatch[3] ?? "";
if (src.startsWith("data:")) return annotateFromDataUri(tag, src);
// Windows drive-letter paths (C:/x.png, C:\x.png) look like single-letter
// URL schemes — they are local paths, not URLs.
const isDrivePath = /^[a-zA-Z]:[\\/]/.test(src);
if (!isDrivePath && /^[a-z][a-z0-9+.-]*:/i.test(src)) {
// Absolute URL with a scheme (http, https, file, …)
if (opts.allowNetwork && /^https?:/i.test(src)) return tag;
if (/^https?:/i.test(src)) {
const msg = `remote image blocked (offline posture): ${src}`;
if (opts.strict) throw new StrictModeError(msg + " — re-run without --strict or pass --allow-network");
opts.warn(msg);
// Leaving the tag would make Chromium fetch it at print time anyway —
// the warn would be a lie. Replace with a visible placeholder.
return buildBlockedRemotePlaceholder(src);
}
// file:// and friends fall through to the local path branch
if (!src.startsWith("file:")) return tag;
}
// decodeURIComponent throws on malformed escapes (foo%zz.png) — a broken
// URL must degrade to the missing-image path, not crash the run.
let decodedSrc = src;
try {
decodedSrc = decodeURIComponent(src);
} catch { /* keep raw src */ }
const filePath = src.startsWith("file:")
? fileURLToPath(src)
: isDrivePath
? path.resolve(src)
: path.resolve(opts.inputDir, decodedSrc);
const cached = memo.get(filePath);
if (cached !== undefined) return rewriteImgTag(tag, cached);
if (!fs.existsSync(filePath)) {
const msg = `image not found: ${src} (resolved to ${filePath})`;
if (opts.strict) throw new StrictModeError(msg);
opts.warn(msg);
return buildMissingImagePlaceholder(src);
}
// Out-of-tree files are never read: rendering untrusted markdown must not
// copy files from elsewhere on disk into a shareable document. Visible
// placeholder by default; --strict makes it fatal.
// Compare REAL paths — a symlink inside the input dir pointing outside
// would otherwise pass a string-prefix check (Codex adversarial finding).
// Runs after the existence check: realpath of a missing file can't
// resolve, and on macOS /var vs /private/var would false-positive.
const inputRoot = safeRealpath(path.resolve(opts.inputDir));
const realFilePath = safeRealpath(filePath);
if (!isInsideDir(realFilePath, inputRoot)) {
const msg = `image resolves OUTSIDE the input directory: ${src} → ${realFilePath}`;
if (opts.strict) throw new StrictModeError(msg + " — move it under the markdown's directory");
opts.warn(msg);
return buildBlockedLocalPlaceholder("outside the document directory", src);
}
// Bound the read BEFORE reading: a markdown image pointing at a special
// file (fifo, device) would hang readFileSync, and a multi-GB file would
// exhaust memory before any policy ran.
let stat: fs.Stats;
try {
stat = fs.statSync(filePath);
} catch {
opts.warn(`image unreadable: ${src}`);
return buildMissingImagePlaceholder(src);
}
if (!stat.isFile()) {
const msg = `image is not a regular file: ${src}`;
if (opts.strict) throw new StrictModeError(msg);
opts.warn(msg);
return buildMissingImagePlaceholder(src);
}
if (stat.size > MAX_IMAGE_BYTES) {
const msg = `image exceeds ${Math.round(MAX_IMAGE_BYTES / 1024 / 1024)}MB cap: ${src} (${Math.round(stat.size / 1024 / 1024)}MB)`;
if (opts.strict) throw new StrictModeError(msg);
opts.warn(msg);
return buildMissingImagePlaceholder(src);
}
const buf = fs.readFileSync(filePath);
const dims = imageDims(buf);
const mime = dims?.mime ?? signedExtensionMime(buf, filePath);
if (mime === "application/octet-stream") {
const msg = `not a recognized image (png, jpeg, gif, webp, svg): ${src}`;
if (opts.strict) throw new StrictModeError(msg);
opts.warn(msg);
return buildBlockedLocalPlaceholder("not an image", src);
}
// Print-resolution normalization (D4): rasters only — SVG scales free.
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)!);
}
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. */
function rewriteImgTag(tag: string, entry: { dataUri: string; attrs: string }): string {
// Function replacement: data URIs are user-content-derived; string-form
// replace() would expand $-patterns inside them.
let out = tag.replace(SRC_RE, () => `src="${entry.dataUri}"`);
if (entry.attrs) out = out.replace(/^<img\b/i, () => `<img${entry.attrs}`);
return out;
}
function annotateFromDataUri(tag: string, src: string): string {
try {
const b64 = src.slice(src.indexOf(",") + 1);
const head = Buffer.from(b64.slice(0, 8192), "base64");
const dims = imageDims(head);
if (!dims) return tag;
return tag.replace(
/^<img\b/i,
`<img data-gstack-px-width="${Math.round(dims.width)}" data-gstack-px-height="${Math.round(dims.height)}"`,
);
} catch {
return tag;
}
}
function buildMissingImagePlaceholder(src: string): string {
return (
`<span class="image-missing" role="img" aria-label="missing image">` +
`[missing image: ${escapeHtml(src)}]</span>`
);
}
function buildBlockedRemotePlaceholder(src: string): string {
return (
`<span class="image-missing" role="img" aria-label="remote image blocked">` +
`[remote image blocked (use --allow-network): ${escapeHtml(src)}]</span>`
);
}
function buildBlockedLocalPlaceholder(reason: string, src: string): string {
return (
`<span class="image-missing" role="img" aria-label="image blocked">` +
`[image blocked (${reason}): ${escapeHtml(src)}]</span>`
);
}
function isInsideDir(p: string, dir: string): boolean {
const rel = path.relative(dir, p);
return rel !== "" && rel !== ".." && !rel.startsWith(".." + path.sep) && !path.isAbsolute(rel);
}
/** realpath that degrades to the input path when resolution fails. */
function safeRealpath(p: string): string {
try {
return fs.realpathSync(p);
} catch {
return p;
}
}
const IMAGE_SIGNATURES: Record<string, (b: Buffer) => boolean> = {
"image/png": (b) => b.length >= 8 && b.readUInt32BE(0) === 0x89504e47 && b.readUInt32BE(4) === 0x0d0a1a0a,
"image/jpeg": (b) => b.length >= 3 && b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff,
"image/gif": (b) => /^GIF8[79]a/.test(b.toString("ascii", 0, 6)),
"image/webp": (b) => b.toString("ascii", 0, 4) === "RIFF" && b.toString("ascii", 8, 12) === "WEBP",
"image/svg+xml": (b) => /<svg[\s>]/i.test(b.toString("utf8", 0, 65536)),
};
/** The extension's image MIME, only when the bytes carry that format's signature. */
function signedExtensionMime(buf: Buffer, p: string): string {
const mime = mimeFromExtension(p);
return IMAGE_SIGNATURES[mime]?.(buf) ? mime : "application/octet-stream";
}
function mimeFromExtension(p: string): string {
switch (path.extname(p).toLowerCase()) {
case ".png": return "image/png";
case ".jpg":
case ".jpeg": return "image/jpeg";
case ".gif": return "image/gif";
case ".webp": return "image/webp";
case ".svg": return "image/svg+xml";
default: return "application/octet-stream";
}
}
// ─── Content-box math ─────────────────────────────────────────────────
const PAGE_WIDTHS_IN: Record<string, number> = {
letter: 8.5,
a4: 8.27,
legal: 8.5,
tabloid: 11,
};
/** Parse a CSS dimension ("1in" | "72pt" | "25mm" | "2.54cm") to inches. */
export function dimToInches(dim: string | undefined, fallbackIn: number): number {
if (!dim) return fallbackIn;
const m = dim.trim().match(/^([0-9.]+)\s*(in|pt|cm|mm|px)?$/i);
if (!m) return fallbackIn;
const v = parseFloat(m[1]);
switch ((m[2] ?? "in").toLowerCase()) {
case "in": return v;
case "pt": return v / 72;
case "cm": return v / 2.54;
case "mm": return v / 25.4;
case "px": return v / 96;
default: return fallbackIn;
}
}
export function contentWidthInches(opts: {
pageSize?: string;
margins?: string;
marginLeft?: string;
marginRight?: string;
}): number {
const pageW = PAGE_WIDTHS_IN[opts.pageSize ?? "letter"] ?? 8.5;
const left = dimToInches(opts.marginLeft ?? opts.margins, 1);
const right = dimToInches(opts.marginRight ?? opts.margins, 1);
return Math.max(1, pageW - left - right);
}
const PAGE_HEIGHTS_IN: Record<string, number> = {
letter: 11,
a4: 11.69,
legal: 14,
tabloid: 17,
};
/**
* Content box of the rotated (landscape) named page: portrait page HEIGHT
* becomes the landscape width; portrait WIDTH becomes the landscape height.
* Used by image-policy to vertically center promoted blocks.
*/
export function landscapeContentBox(opts: {
pageSize?: string;
margins?: string;
marginLeft?: string;
marginRight?: string;
marginTop?: string;
marginBottom?: string;
}): { contentWIn: number; contentHIn: number } {
const size = opts.pageSize ?? "letter";
const pageH = PAGE_HEIGHTS_IN[size] ?? 11;
const pageW = PAGE_WIDTHS_IN[size] ?? 8.5;
const left = dimToInches(opts.marginLeft ?? opts.margins, 1);
const right = dimToInches(opts.marginRight ?? opts.margins, 1);
const top = dimToInches(opts.marginTop ?? opts.margins, 1);
const bottom = dimToInches(opts.marginBottom ?? opts.margins, 1);
return {
contentWIn: Math.max(1, pageH - left - right),
contentHIn: Math.max(1, pageW - top - bottom),
};
}
// ─── tiny helpers ─────────────────────────────────────────────────────
// escapeHtml is imported from ./render — single definition, no drift.
function firstLine(s: string): string {
return s.split("\n")[0].slice(0, 200);
}