orcareplay 0.1.0

package/dist/out.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Terminal output.
+ *
+ * The CLI is most of this product's surface, and most of its output ends up somewhere that is not
+ * a terminal — a CI log, a pipe into grep, a pasted GitHub issue. So: colour only on a real TTY,
+ * no animation that corrupts a log, one greppable `level event key=value` line per fact, and
+ * errors that say what happened, what it means, and what to run next.
+ */
+export declare function stripAnsi(s: string): string;
+export type Scalar = string | number | boolean | null | undefined;
+export type Fields = Record<string, Scalar>;
+/**
+ * One structured fact, before it is turned into a line of text.
+ *
+ * The same record that becomes `warn capture.empty exchanges=0 …` on a terminal. A caller that
+ * embedded orca has no stdout to read, and an agent asking for `--json` should not be handed
+ * prose to parse — so every fact is available as data at the point it is emitted, and the line is
+ * a rendering of it rather than the only form it ever takes.
+ *
+ * Fields arrive redacted, exactly as the terminal would show them: a key must not reach a JSON
+ * consumer just because it took a different route out.
+ */
+export interface LogEntry {
+    level: 'info' | 'warn' | 'error' | 'debug';
+    event: string;
+    fields: Record<string, Scalar>;
+}
+export interface OutputOptions {
+    write: (s: string) => void;
+    /** Receives every fact as data, in the order it was emitted. */
+    sink?: (entry: LogEntry) => void;
+    isTTY?: boolean;
+    env?: Record<string, string | undefined>;
+    verbose?: boolean;
+    ci?: boolean;
+    /** Explicit override from `--no-color`. Wins over TTY detection and NO_COLOR alike. */
+    color?: boolean;
+}
+export interface Failure {
+    event: string;
+    /** What happened. */
+    what: string;
+    /** What it means — the part that turns a message into an explanation. */
+    why?: string;
+    /** The next command to run. An error without this is a bug report we will receive instead. */
+    next?: string;
+}
+export declare class Output {
+    #private;
+    constructor(opts: OutputOptions);
+    get isVerbose(): boolean;
+    info(event: string, fields?: Fields): void;
+    warn(event: string, fields?: Fields): void;
+    error(event: string, fields?: Fields): void;
+    debug(event: string, fields?: Fields): void;
+    /** One line per phase. Always printed, including under --ci. */
+    phase(event: string, fields?: Fields): void;
+    /**
+     * Transient status. Printed only on an interactive TTY: in a pipe it is noise, and in CI it
+     * turns a log into thousands of lines of escape codes.
+     */
+    progress(message: string): void;
+    /** Free-form text for help and reports, where key=value would be worse than prose. */
+    plain(message?: string): void;
+    failure(f: Failure): void;
+    /** Aligned columns, no box drawing — a table people can pipe into awk. */
+    table(headers: string[], rows: string[][]): void;
+}
+//# sourceMappingURL=out.d.ts.map

package/dist/out.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"out.d.ts","sourceRoot":"","sources":["../src/out.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAcH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAE3C;AAkBD,MAAM,MAAM,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC;AAClE,MAAM,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAE5C;;;;;;;;;;GAUG;AACH,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;IAC3C,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3B,gEAAgE;IAChE,IAAI,CAAC,EAAE,CAAC,KAAK,EAAE,QAAQ,KAAK,IAAI,CAAC;IACjC,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC;IACzC,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,EAAE,CAAC,EAAE,OAAO,CAAC;IACb,uFAAuF;IACvF,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,OAAO;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,qBAAqB;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,yEAAyE;IACzE,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,8FAA8F;IAC9F,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,qBAAa,MAAM;;gBAQL,IAAI,EAAE,aAAa;IAa/B,IAAI,SAAS,IAAI,OAAO,CAEvB;IAED,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,GAAE,MAAW,GAAG,IAAI;IAI9C,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,GAAE,MAAW,GAAG,IAAI;IAI9C,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,GAAE,MAAW,GAAG,IAAI;IAI/C,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,GAAE,MAAW,GAAG,IAAI;IAK/C,gEAAgE;IAChE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,GAAE,MAAW,GAAG,IAAI;IAI/C;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IAK/B,sFAAsF;IACtF,KAAK,CAAC,OAAO,SAAK,GAAG,IAAI;IAIzB,OAAO,CAAC,CAAC,EAAE,OAAO,GAAG,IAAI;IAOzB,0EAA0E;IAC1E,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,IAAI;CAiCjD"}

package/dist/out.js

@@ -0,0 +1,138 @@
+/**
+ * Terminal output.
+ *
+ * The CLI is most of this product's surface, and most of its output ends up somewhere that is not
+ * a terminal — a CI log, a pipe into grep, a pasted GitHub issue. So: colour only on a real TTY,
+ * no animation that corrupts a log, one greppable `level event key=value` line per fact, and
+ * errors that say what happened, what it means, and what to run next.
+ */
+const ESC = String.fromCharCode(27);
+const CSI = `${ESC}[`;
+const STYLE = {
+    dim: `${CSI}2m`,
+    bold: `${CSI}1m`,
+    reset: `${CSI}0m`,
+};
+/** Matches SGR sequences without embedding a raw control character in source. */
+const ANSI_RE = new RegExp(`${ESC}\\[[0-9;]*m`, 'g');
+export function stripAnsi(s) {
+    return s.replace(ANSI_RE, '');
+}
+/**
+ * Shapes that must never reach a terminal. §7 applies to output, not only to disk: terminals
+ * scroll into screenshots, and a key printed once is a key leaked forever.
+ */
+const SECRET_PATTERNS = [
+    /\bsk-[A-Za-z0-9_-]{16,}/,
+    /\bgh[pousr]_[A-Za-z0-9]{20,}/,
+    /\bAKIA[0-9A-Z]{16}\b/,
+    /\bxox[baprs]-[A-Za-z0-9-]{10,}/,
+    /\bAIza[0-9A-Za-z_-]{35}\b/,
+    /\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/,
+];
+/** Keys whose value is secret by name, whatever it happens to look like. */
+const SECRET_KEYS = /^(api[_-]?key|key|token|secret|password|authorization|cookie)$/i;
+export class Output {
+    #write;
+    #color;
+    #tty;
+    #verbose;
+    #ci;
+    #sink;
+    constructor(opts) {
+        const env = opts.env ?? {};
+        this.#write = opts.write;
+        this.#sink = opts.sink;
+        this.#tty = opts.isTTY ?? false;
+        this.#ci = opts.ci ?? false;
+        this.#verbose = opts.verbose ?? false;
+        // NO_COLOR is honoured whatever its value; see no-color.org. An explicit `color: false` from
+        // `--no-color` overrides everything — it is the flag people reach for when a log has come out
+        // unreadable, so it has to win rather than be one input among several.
+        this.#color = opts.color ?? (this.#tty && !this.#ci && env.NO_COLOR === undefined);
+    }
+    get isVerbose() {
+        return this.#verbose;
+    }
+    info(event, fields = {}) {
+        this.#line('info', event, fields);
+    }
+    warn(event, fields = {}) {
+        this.#line('warn', event, fields, STYLE.bold);
+    }
+    error(event, fields = {}) {
+        this.#line('error', event, fields, STYLE.bold);
+    }
+    debug(event, fields = {}) {
+        if (!this.#verbose)
+            return;
+        this.#line('debug', event, fields, STYLE.dim);
+    }
+    /** One line per phase. Always printed, including under --ci. */
+    phase(event, fields = {}) {
+        this.#line('info', event, fields);
+    }
+    /**
+     * Transient status. Printed only on an interactive TTY: in a pipe it is noise, and in CI it
+     * turns a log into thousands of lines of escape codes.
+     */
+    progress(message) {
+        if (!this.#tty || this.#ci)
+            return;
+        this.#write(`${this.#paint(STYLE.dim)}${message}${this.#paint(STYLE.reset)}\n`);
+    }
+    /** Free-form text for help and reports, where key=value would be worse than prose. */
+    plain(message = '') {
+        this.#write(`${message}\n`);
+    }
+    failure(f) {
+        this.error(f.event, {});
+        this.plain(`  ${f.what}`);
+        if (f.why)
+            this.plain(`  ${f.why}`);
+        if (f.next)
+            this.plain(`  next: ${f.next}`);
+    }
+    /** Aligned columns, no box drawing — a table people can pipe into awk. */
+    table(headers, rows) {
+        const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? '').length)));
+        const render = (cells) => cells
+            .map((c, i) => (i === cells.length - 1 ? c : c.padEnd(widths[i] ?? 0)))
+            .join('  ')
+            .trimEnd();
+        this.#write(`${this.#paint(STYLE.dim)}${render(headers)}${this.#paint(STYLE.reset)}\n`);
+        for (const row of rows)
+            this.#write(`${render(row)}\n`);
+    }
+    #paint(code) {
+        return this.#color ? code : '';
+    }
+    #line(level, event, fields, style) {
+        const parts = [level, event];
+        const structured = {};
+        for (const [k, v] of Object.entries(fields)) {
+            if (v === undefined || v === null)
+                continue;
+            // Redacted once, for both destinations. A secret must not reach a JSON consumer merely
+            // because it left by a different door than the terminal.
+            structured[k] = redactValue(k, v);
+            parts.push(`${k}=${formatValue(k, v)}`);
+        }
+        this.#sink?.({ level: level, event, fields: structured });
+        const body = parts.join(' ');
+        this.#write(`${style ? this.#paint(style) : ''}${body}${style ? this.#paint(STYLE.reset) : ''}\n`);
+    }
+}
+function isSecret(key, raw) {
+    return SECRET_KEYS.test(key) || SECRET_PATTERNS.some((re) => re.test(raw));
+}
+/** The value as data — the number or boolean kept as itself, anything secret replaced. */
+function redactValue(key, value) {
+    return isSecret(key, String(value)) ? '<redacted>' : (value ?? null);
+}
+function formatValue(key, value) {
+    const raw = String(value);
+    const text = isSecret(key, raw) ? '<redacted>' : raw;
+    return /[\s"]/.test(text) ? JSON.stringify(text) : text;
+}
+//# sourceMappingURL=out.js.map

package/dist/out.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"out.js","sourceRoot":"","sources":["../src/out.ts"],"names":[],"mappings":"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"}

package/dist/rasterize.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Turning a card into a raster, for the places SVG does not go.
+ *
+ * SVG renders in a GitHub issue and nowhere else that matters: X will not accept it as an upload,
+ * and Slack and Discord give it no inline preview. So the card someone actually posts is a PNG,
+ * and the one that animates is a GIF.
+ *
+ * Neither needs a dependency in `package.json`, and deliberately does not have one.
+ * `docs/media/README.md` keeps `playwright-core`, `pngjs` and `gifenc` out so that everyone running
+ * `npm ci` to work on orca does not pay for a browser download, and a picture command is not a
+ * reason to reverse that. They are imported at the moment of use and their absence is an
+ * actionable message naming the one line that fixes it — the same line the docs already give for
+ * regenerating README art.
+ *
+ * `scripts/render-demo.mjs` established the encoding approach and the reason for it: the ffmpeg
+ * that ships with Playwright is stripped to what Playwright needs and has neither a PNG decoder
+ * nor a GIF muxer, so shelling out to it fails silently at both ends. The encoder is JavaScript
+ * for that reason.
+ */
+/** Everything the raster path needs, in the order the install line should list them. */
+export declare const RENDER_DEPS: readonly ["playwright-core", "pngjs", "gifenc"];
+export type CardFormat = 'svg' | 'png' | 'gif';
+export interface CardTarget {
+    path: string;
+    format: CardFormat;
+}
+/**
+ * The path and format to write a card to, or a refusal naming what orca can write.
+ *
+ * Refusing beats succeeding falsely. Writing SVG bytes into a file called `.png` produced a file
+ * no image viewer opens and a success line explaining nothing, and `.png` is precisely the request
+ * people make, because it is the format that posts where SVG does not.
+ */
+export declare function cardTarget(name: string, flag: string): CardTarget;
+export interface GifFrame {
+    /** How many events of the chain this frame shows. */
+    reveal: number;
+    /** How long it is held, in milliseconds. */
+    delayMs: number;
+}
+/**
+ * One frame per hop, with the hold carried in the frame rather than in a frame rate.
+ *
+ * The alternative — a frame every 40ms — is how 107 near-identical PNGs became a 5.5 MB GIF for
+ * the README hero, when 22 self-timed frames said exactly the same thing. The last frame rests
+ * long enough to read the finished card before the loop starts over.
+ */
+export declare function gifFrames(events: number): GifFrame[];
+/** Which of the optional packages are not installed. Empty means the raster path will work. */
+export declare function missingRenderDeps(): Promise<string[]>;
+/** The message shown when a raster was asked for and the toolchain is not here. */
+export declare function installHint(missing: string[], format: CardFormat): string;
+/** One SVG as a PNG, at 2× so it stays sharp when a client scales it down. */
+export declare function svgToPng(svg: string): Promise<Buffer>;
+/**
+ * A sequence of SVGs as one animated GIF.
+ *
+ * The palette is quantised once from the final frame, which carries every colour the sequence
+ * ever shows, so nothing shifts hue partway through — the failure mode of quantising per frame.
+ */
+export declare function svgsToGif(svgs: string[], delays: number[]): Promise<Buffer>;
+//# sourceMappingURL=rasterize.d.ts.map

package/dist/rasterize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rasterize.d.ts","sourceRoot":"","sources":["../src/rasterize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAaH,wFAAwF;AACxF,eAAO,MAAM,WAAW,iDAAkD,CAAC;AAE3E,MAAM,MAAM,UAAU,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,CAAC;AAE/C,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,UAAU,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,UAAU,CAQjE;AAED,MAAM,WAAW,QAAQ;IACvB,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,OAAO,EAAE,MAAM,CAAC;CACjB;AAKD;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,EAAE,CAMpD;AAED,+FAA+F;AAC/F,wBAAsB,iBAAiB,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAU3D;AAED,mFAAmF;AACnF,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,UAAU,GAAG,MAAM,CAOzE;AAwCD,8EAA8E;AAC9E,wBAAsB,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAQ3D;AAED;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CA0CjF"}

package/dist/rasterize.js

@@ -0,0 +1,154 @@
+/**
+ * Turning a card into a raster, for the places SVG does not go.
+ *
+ * SVG renders in a GitHub issue and nowhere else that matters: X will not accept it as an upload,
+ * and Slack and Discord give it no inline preview. So the card someone actually posts is a PNG,
+ * and the one that animates is a GIF.
+ *
+ * Neither needs a dependency in `package.json`, and deliberately does not have one.
+ * `docs/media/README.md` keeps `playwright-core`, `pngjs` and `gifenc` out so that everyone running
+ * `npm ci` to work on orca does not pay for a browser download, and a picture command is not a
+ * reason to reverse that. They are imported at the moment of use and their absence is an
+ * actionable message naming the one line that fixes it — the same line the docs already give for
+ * regenerating README art.
+ *
+ * `scripts/render-demo.mjs` established the encoding approach and the reason for it: the ffmpeg
+ * that ships with Playwright is stripped to what Playwright needs and has neither a PNG decoder
+ * nor a GIF muxer, so shelling out to it fails silently at both ends. The encoder is JavaScript
+ * for that reason.
+ */
+/**
+ * Import a package orca does not depend on.
+ *
+ * The specifier is a variable on purpose: a literal makes TypeScript resolve the module at build
+ * time, and these are precisely the modules that are not there. Typing the result as `unknown`
+ * keeps every call site honest about that.
+ */
+async function loadOptional(name) {
+    return (await import(name));
+}
+/** Everything the raster path needs, in the order the install line should list them. */
+export const RENDER_DEPS = ['playwright-core', 'pngjs', 'gifenc'];
+/**
+ * The path and format to write a card to, or a refusal naming what orca can write.
+ *
+ * Refusing beats succeeding falsely. Writing SVG bytes into a file called `.png` produced a file
+ * no image viewer opens and a success line explaining nothing, and `.png` is precisely the request
+ * people make, because it is the format that posts where SVG does not.
+ */
+export function cardTarget(name, flag) {
+    const ext = /\.([A-Za-z0-9]+)$/.exec(name)?.[1]?.toLowerCase();
+    if (ext === 'svg' || ext === 'png' || ext === 'gif')
+        return { path: name, format: ext };
+    throw new Error(ext === undefined
+        ? `${flag} needs a filename ending in .svg, .png or .gif — got ${JSON.stringify(name)}`
+        : `${flag} cannot write .${ext}. Name it .svg, .png or .gif instead.`);
+}
+const FRAME_HOLD_MS = 520;
+const FINAL_HOLD_MS = 2600;
+/**
+ * One frame per hop, with the hold carried in the frame rather than in a frame rate.
+ *
+ * The alternative — a frame every 40ms — is how 107 near-identical PNGs became a 5.5 MB GIF for
+ * the README hero, when 22 self-timed frames said exactly the same thing. The last frame rests
+ * long enough to read the finished card before the loop starts over.
+ */
+export function gifFrames(events) {
+    if (events <= 0)
+        return [];
+    return Array.from({ length: events }, (_, i) => ({
+        reveal: i + 1,
+        delayMs: i === events - 1 ? FINAL_HOLD_MS : FRAME_HOLD_MS,
+    }));
+}
+/** Which of the optional packages are not installed. Empty means the raster path will work. */
+export async function missingRenderDeps() {
+    const missing = [];
+    for (const name of RENDER_DEPS) {
+        try {
+            await loadOptional(name);
+        }
+        catch {
+            missing.push(name);
+        }
+    }
+    return missing;
+}
+/** The message shown when a raster was asked for and the toolchain is not here. */
+export function installHint(missing, format) {
+    return (`writing a .${format} needs ${missing.join(', ')}, which orca does not depend on: ` +
+        'a browser download is not something everyone running `npm ci` should pay for.\n' +
+        `  npm i --no-save ${RENDER_DEPS.join(' ')}\n` +
+        '  …then run this again, or write a .svg, which never needs anything.');
+}
+async function requireRenderDeps(format) {
+    const missing = await missingRenderDeps();
+    if (missing.length > 0)
+        throw new Error(installHint(missing, format));
+}
+/** Load Playwright's Chromium, preferring an explicit executable when one is configured. */
+async function launchChromium() {
+    const { chromium } = (await loadOptional('playwright-core'));
+    const exe = process.env['ORCA_CHROMIUM'] ?? process.env['PLAYWRIGHT_CHROMIUM_EXECUTABLE'];
+    const browser = await chromium.launch(exe === undefined ? {} : { executablePath: exe });
+    return {
+        async shot(svg) {
+            const page = await browser.newPage({ deviceScaleFactor: 2 });
+            // A transparent body would composite the card onto whatever the viewer paints behind it.
+            // The card draws its own ground, so the page only has to not add one of its own.
+            await page.setContent(`<body style="margin:0">${svg}</body>`);
+            const buffer = await page.locator('svg').screenshot({ omitBackground: true });
+            await page.close();
+            return buffer;
+        },
+        close: () => browser.close(),
+    };
+}
+/** One SVG as a PNG, at 2× so it stays sharp when a client scales it down. */
+export async function svgToPng(svg) {
+    await requireRenderDeps('png');
+    const browser = await launchChromium();
+    try {
+        return await browser.shot(svg);
+    }
+    finally {
+        await browser.close();
+    }
+}
+/**
+ * A sequence of SVGs as one animated GIF.
+ *
+ * The palette is quantised once from the final frame, which carries every colour the sequence
+ * ever shows, so nothing shifts hue partway through — the failure mode of quantising per frame.
+ */
+export async function svgsToGif(svgs, delays) {
+    await requireRenderDeps('gif');
+    if (svgs.length === 0)
+        throw new Error('nothing to animate: the chain has no events');
+    const { PNG } = (await loadOptional('pngjs'));
+    const gifenc = (await loadOptional('gifenc'));
+    const mod = (gifenc.GIFEncoder ? gifenc : (gifenc.default ?? gifenc));
+    const browser = await launchChromium();
+    try {
+        const frames = [];
+        for (const svg of svgs)
+            frames.push(PNG.sync.read(await browser.shot(svg)));
+        const enc = mod.GIFEncoder();
+        const last = frames[frames.length - 1];
+        const palette = mod.quantize(new Uint8ClampedArray(last.data), 32, { format: 'rgb565' });
+        for (const [i, frame] of frames.entries()) {
+            const indexed = mod.applyPalette(new Uint8ClampedArray(frame.data), palette, 'rgb565');
+            enc.writeFrame(indexed, frame.width, frame.height, {
+                palette: i === 0 ? palette : undefined,
+                delay: delays[i] ?? FRAME_HOLD_MS,
+                repeat: 0,
+            });
+        }
+        enc.finish();
+        return Buffer.from(enc.bytes());
+    }
+    finally {
+        await browser.close();
+    }
+}
+//# sourceMappingURL=rasterize.js.map

package/dist/rasterize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rasterize.js","sourceRoot":"","sources":["../src/rasterize.ts"],"names":[],"mappings":"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"}

package/dist/serial.d.ts

@@ -0,0 +1,19 @@
+/**
+ * A one-at-a-time work queue for trace writes.
+ *
+ * The recorder is driven by proxy callbacks, which arrive whenever an exchange completes. Running
+ * those handlers concurrently is not merely untidy: each one snapshots the workspace, and two
+ * overlapping `git add` invocations collide on `index.lock` and fail. Serializing also keeps
+ * `seq` in the order exchanges actually happened, which the whole format depends on.
+ *
+ * A failing task must not stall or silently empty the queue — one bad write should cost one event,
+ * not the rest of the run — so errors are collected and re-thrown at `drain()`.
+ */
+export declare class SerialQueue {
+    #private;
+    push(task: () => Promise<void>): void;
+    /** Wait for everything queued so far, including work queued by those tasks. */
+    drain(): Promise<void>;
+    errors(): unknown[];
+}
+//# sourceMappingURL=serial.d.ts.map

package/dist/serial.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serial.d.ts","sourceRoot":"","sources":["../src/serial.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,qBAAa,WAAW;;IAItB,IAAI,CAAC,IAAI,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IAOrC,+EAA+E;IACzE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAW5B,MAAM,IAAI,OAAO,EAAE;CAGpB"}

package/dist/serial.js

@@ -0,0 +1,34 @@
+/**
+ * A one-at-a-time work queue for trace writes.
+ *
+ * The recorder is driven by proxy callbacks, which arrive whenever an exchange completes. Running
+ * those handlers concurrently is not merely untidy: each one snapshots the workspace, and two
+ * overlapping `git add` invocations collide on `index.lock` and fail. Serializing also keeps
+ * `seq` in the order exchanges actually happened, which the whole format depends on.
+ *
+ * A failing task must not stall or silently empty the queue — one bad write should cost one event,
+ * not the rest of the run — so errors are collected and re-thrown at `drain()`.
+ */
+export class SerialQueue {
+    #tail = Promise.resolve();
+    #errors = [];
+    push(task) {
+        this.#tail = this.#tail.then(() => task().catch((err) => void this.#errors.push(err)), () => task().catch((err) => void this.#errors.push(err)));
+    }
+    /** Wait for everything queued so far, including work queued by those tasks. */
+    async drain() {
+        let previous;
+        // A task may enqueue more work, so keep waiting until the tail stops moving.
+        while (previous !== this.#tail) {
+            previous = this.#tail;
+            await previous;
+        }
+        const [first] = this.#errors;
+        if (first !== undefined)
+            throw first instanceof Error ? first : new Error(String(first));
+    }
+    errors() {
+        return this.#errors.slice();
+    }
+}
+//# sourceMappingURL=serial.js.map

package/dist/serial.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serial.js","sourceRoot":"","sources":["../src/serial.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,MAAM,OAAO,WAAW;IACtB,KAAK,GAAkB,OAAO,CAAC,OAAO,EAAE,CAAC;IAChC,OAAO,GAAc,EAAE,CAAC;IAEjC,IAAI,CAAC,IAAyB;QAC5B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAC1B,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE,CAAC,KAAK,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EACjE,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE,CAAC,KAAK,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAClE,CAAC;IACJ,CAAC;IAED,+EAA+E;IAC/E,KAAK,CAAC,KAAK;QACT,IAAI,QAAmC,CAAC;QACxC,6EAA6E;QAC7E,OAAO,QAAQ,KAAK,IAAI,CAAC,KAAK,EAAE,CAAC;YAC/B,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC;YACtB,MAAM,QAAQ,CAAC;QACjB,CAAC;QACD,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC;QAC7B,IAAI,KAAK,KAAK,SAAS;YAAE,MAAM,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAC3F,CAAC;IAED,MAAM;QACJ,OAAO,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IAC9B,CAAC;CACF"}

package/dist/share-card.d.ts

@@ -0,0 +1,73 @@
+import type { RunGraph } from '@orcareplay/core';
+import type { CompareRow } from './commands/compare.js';
+/**
+ * A comparison table as one self-contained SVG.
+ *
+ * The compare table is the most shareable thing OrcaReplay produces — a model-versus-model result
+ * grounded in a real task rather than a synthetic benchmark. It is only worth sharing if it says
+ * what it measured, so the card carries the fork point and the verify command alongside the
+ * verdicts. A cost column with no stated verdict command is a number people will quote out of
+ * context.
+ *
+ * Monochrome and dependency-free for the same reason the viewer is: it has to survive being
+ * dropped into an issue, a README, a chat window, or a dark-mode client, and it has to render
+ * with nothing installed.
+ */
+export interface CardMeta {
+    runId: string;
+    forkPoint: number;
+    verify?: string;
+}
+export declare function renderCompareCard(rows: CompareRow[], meta: CardMeta): string;
+export interface ChainCardMeta {
+    runId: string;
+    /**
+     * How many of the chain's events to draw, for one frame of an animation. The card keeps the
+     * geometry of the whole chain either way — a frame that resized to its own content would make
+     * the finished GIF jump as it built.
+     */
+    reveal?: number;
+}
+/**
+ * One causal chain as a self-contained SVG.
+ *
+ * The timeline answers "what happened"; this answers "what produced this", which is the shape of
+ * the thing worth showing someone else. It carries three things a picture that travels without
+ * its trace has to carry on its own face: the claim, stated first; the command that reproduces it;
+ * and — where any hop was inferred — the fact that it was, because a dashed line nobody explains
+ * launders a guess into a fact.
+ *
+ * Monochrome and dependency-free for the same reason the viewer is: it has to survive being
+ * dropped into an issue, a README, a chat window or a dark-mode client with nothing installed.
+ */
+export declare function renderChainCard(graph: RunGraph, meta: ChainCardMeta): string;
+export interface GraphCardMeta {
+    runId: string;
+    /** Seqs to light up — normally one causal chain. Everything else is drawn dim. */
+    highlight: Set<number>;
+}
+export interface ScopedGraph extends RunGraph {
+    /** True when turns were dropped to keep the picture readable. Said on the card. */
+    narrowed: boolean;
+    /** Events that belong to no lane, or fell outside the scope. Counted on the card. */
+    omitted: number;
+    turns: number[];
+}
+/**
+ * The part of a graph worth drawing, narrowed when a whole run would be a hairball.
+ *
+ * A pane that draws all 400 events of a real run is strictly worse than the list beside it, so
+ * past `max` drawable events this keeps only the turns the highlighted chain touches. Narrowing
+ * is recorded rather than silent: a picture of part of a run that looks like a picture of the run
+ * is the same failure as an inferred edge that looks recorded.
+ */
+export declare function scopeForCard(graph: RunGraph, highlight: Set<number>, max?: number): ScopedGraph;
+/**
+ * A whole run as a causal graph: time left to right, kind of thing top to bottom.
+ *
+ * The chain card follows one path; this shows the shape. Two things only the shape gives you —
+ * the run's repeating motif, so anything that breaks it is worth a look, and an event with no edge
+ * leaving it, which is an absence a list cannot show at all.
+ */
+export declare function renderGraphCard(graph: RunGraph | ScopedGraph, meta: GraphCardMeta): string;
+//# sourceMappingURL=share-card.d.ts.map

package/dist/share-card.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"share-card.d.ts","sourceRoot":"","sources":["../src/share-card.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAa,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAE5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AAExD;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAOD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,UAAU,EAAE,EAAE,IAAI,EAAE,QAAQ,GAAG,MAAM,CAuD5E;AAMD,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAOD;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,aAAa,GAAG,MAAM,CAyE5E;AA0GD,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,kFAAkF;IAClF,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACxB;AAED,MAAM,WAAW,WAAY,SAAQ,QAAQ;IAC3C,mFAAmF;IACnF,QAAQ,EAAE,OAAO,CAAC;IAClB,qFAAqF;IACrF,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAqBD;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,QAAQ,EAAE,SAAS,EAAE,GAAG,CAAC,MAAM,CAAC,EAAE,GAAG,SAAK,GAAG,WAAW,CAwB3F;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,QAAQ,GAAG,WAAW,EAAE,IAAI,EAAE,aAAa,GAAG,MAAM,CAqH1F"}