flowsvg 0.1.0 → 0.2.0

package/dist/export/browser.js

@@ -0,0 +1,172 @@
+/** Browser-only export owns its canvas, image URLs and inline encoder worker; core rendering stays DOM-free. */
+import { createDiagram } from "../core/diagram.js";
+import { resolveThemePalette } from "../core/theme.js";
+import { CAPTION_FONT, CAPTION_LINE_HEIGHT, CAPTION_PADDING_X, CAPTION_PADDING_Y, collectCaptions, preflightCaptions, wrapCaption } from "./captions.js";
+import { planGif, validateGifOptions } from "./plan.js";
+import { GIF_WORKER_SOURCE } from "./worker-source.js";
+import { GifExportError } from "./types.js";
+/**
+ * Return opaque GIF bytes without downloading or changing playback. Snapshot inputs synchronously
+ * and release task resources on success, failure or cancellation. Captions are measured before sampling.
+ * @throws {GifExportError} With a distinct code for invalid options/document, limits, caption overflow,
+ * unavailable browser services, rasterization, encoding or cancellation. See GifExportOptions for limits.
+ */
+export async function exportGif(input, options = {}) {
+    validateGifOptions(options);
+    const captured = { ...options };
+    checkAbort(captured.signal);
+    try {
+        createDiagram(input);
+    }
+    catch (cause) {
+        throw new GifExportError("document", "Invalid diagram document; correct the validation issues before exporting.", { cause });
+    }
+    const document = JSON.parse(JSON.stringify(input));
+    // GIF frames share the authored camera so changing live canvas height cannot stretch diagram pixels.
+    // Validate the original option above before omitting it from this private export snapshot.
+    const { fitHeight: _fitHeight, ...viewport } = document.viewport;
+    const diagram = createDiagram({ ...document, viewport });
+    const plan = planGif(document, diagram.totalDuration, captured);
+    if (typeof globalThis.document === "undefined" || typeof Worker !== "function")
+        throw new GifExportError("environment", "GIF export requires a modern browser with canvas and workers; use flowsvg/node in Node.");
+    const report = (phase, completed) => { checkAbort(captured.signal); captured.onProgress?.({ phase, completed, total: plan.frames.length }); checkAbort(captured.signal); };
+    report("preparing", 0);
+    const canvas = globalThis.document.createElement("canvas");
+    canvas.width = plan.width;
+    canvas.height = plan.height;
+    let worker;
+    let workerUrl;
+    const workerFailure = new AbortController();
+    const failWorker = (event) => workerFailure.abort(new GifExportError("encoding", `Worker failed: ${event.message || "startup or execution was blocked"}. Check Blob worker permissions and retry.`));
+    try {
+        const context = canvas.getContext("2d", { willReadFrequently: true });
+        if (!context)
+            throw new GifExportError("environment", "Canvas 2D is unavailable; enable browser canvas support.");
+        const captions = captured.includeCaptions === false ? [] : collectCaptions(diagram, plan.startMs, plan.endMs);
+        await waitForFonts([document.title ?? "中文", ...captions.map(({ text }) => text)].join("\n"), captured.signal);
+        preflightCaptions(context, captions, plan);
+        checkAbort(captured.signal);
+        workerUrl = URL.createObjectURL(new Blob([GIF_WORKER_SOURCE], { type: "text/javascript" }));
+        worker = createWorker(workerUrl);
+        // Startup errors can arrive while image decoding is pending, before the first frame request.
+        worker.addEventListener("error", failWorker);
+        for (const [index, frame] of plan.frames.entries()) {
+            report("sampling", index);
+            const caption = diagram.evaluateAt(frame.timeMs, plan).caption ?? "";
+            await paintFrame(context, canvas, diagram.renderSvg(frame.timeMs, plan), caption, plan, captured.signal, workerFailure.signal);
+            const pixels = readPixels(context, plan);
+            report("encoding", index);
+            await requestWorker(worker, { type: "frame", rgba: pixels.data.buffer, width: plan.width, height: plan.height, delayMs: frame.delayMs, repeat: plan.loopCount === 1 ? -1 : plan.loopCount === 0 ? 0 : plan.loopCount - 1 }, [pixels.data.buffer], captured.signal, workerFailure.signal);
+            await new Promise((resolve) => setTimeout(resolve, 0));
+        }
+        const result = await requestWorker(worker, { type: "finish" }, [], captured.signal, workerFailure.signal);
+        if (!result.bytes)
+            throw new GifExportError("encoding", "Encoder returned no bytes; retry with a smaller export.");
+        report("complete", plan.frames.length);
+        return result.bytes;
+    }
+    finally {
+        worker?.removeEventListener("error", failWorker);
+        worker?.terminate();
+        if (workerUrl)
+            URL.revokeObjectURL(workerUrl);
+        canvas.width = 0;
+        canvas.height = 0;
+    }
+}
+function checkAbort(signal, workerFailure) {
+    if (signal?.aborted)
+        throw new GifExportError("cancelled", "GIF export cancelled; start another export when ready.");
+    if (workerFailure?.aborted)
+        throw workerFailure.reason;
+}
+function requestWorker(worker, data, transfer, signal, workerFailure) {
+    checkAbort(signal, workerFailure);
+    return new Promise((resolve, reject) => {
+        const cleanup = () => { worker.removeEventListener("message", message); workerFailure.removeEventListener("abort", failure); signal?.removeEventListener("abort", abort); };
+        const abort = () => { cleanup(); reject(new GifExportError("cancelled", "GIF export cancelled; start another export when ready.")); };
+        const failure = () => { cleanup(); reject(workerFailure.reason); };
+        const message = (event) => { cleanup(); if (event.data.error)
+            reject(new GifExportError("encoding", `${event.data.error}; retry with a smaller export.`));
+        else
+            resolve(event.data); };
+        worker.addEventListener("message", message);
+        workerFailure.addEventListener("abort", failure, { once: true });
+        signal?.addEventListener("abort", abort, { once: true });
+        try {
+            worker.postMessage(data, transfer);
+        }
+        catch (cause) {
+            cleanup();
+            reject(new GifExportError("encoding", "Cannot send pixels to the encoder; retry the export.", { cause }));
+        }
+    });
+}
+async function paintFrame(context, canvas, svg, caption, plan, signal, workerFailure) {
+    checkAbort(signal, workerFailure);
+    const url = URL.createObjectURL(new Blob([svg], { type: "image/svg+xml" }));
+    const image = new Image();
+    try {
+        image.src = url;
+        await withAbort(image.decode(), signal, workerFailure);
+        checkAbort(signal, workerFailure);
+        const palette = resolveThemePalette(plan.theme);
+        context.fillStyle = palette.background;
+        context.fillRect(0, 0, canvas.width, canvas.height);
+        context.drawImage(image, 0, 0, plan.width, plan.diagramHeight);
+        if (!plan.captionHeight)
+            return;
+        context.font = CAPTION_FONT;
+        context.fillStyle = palette.text;
+        context.textBaseline = "top";
+        wrapCaption(context, caption, plan.width - CAPTION_PADDING_X * 2).forEach((line, index) => context.fillText(line, CAPTION_PADDING_X, plan.diagramHeight + CAPTION_PADDING_Y + index * CAPTION_LINE_HEIGHT));
+    }
+    catch (cause) {
+        if (cause instanceof GifExportError)
+            throw cause;
+        throw new GifExportError("rasterization", "Cannot rasterize the diagram; check browser SVG/canvas support and retry.", { cause });
+    }
+    finally {
+        image.src = "";
+        URL.revokeObjectURL(url);
+    }
+}
+/** Race browser services with cancellation and worker failure; detach both listeners on settlement. */
+function withAbort(promise, signal, workerFailure) {
+    checkAbort(signal, workerFailure);
+    return new Promise((resolve, reject) => {
+        const cleanup = () => { signal?.removeEventListener("abort", abort); workerFailure?.removeEventListener("abort", failure); };
+        const abort = () => { cleanup(); reject(new GifExportError("cancelled", "GIF export cancelled; start another export when ready.")); };
+        const failure = () => { cleanup(); reject(workerFailure?.reason); };
+        signal?.addEventListener("abort", abort, { once: true });
+        workerFailure?.addEventListener("abort", failure, { once: true });
+        Promise.resolve(promise).then((value) => { cleanup(); resolve(value); }, (error) => { cleanup(); reject(error); });
+    });
+}
+async function waitForFonts(text, signal) {
+    try {
+        await withAbort(globalThis.document.fonts.load(CAPTION_FONT, text), signal);
+        await withAbort(globalThis.document.fonts.ready, signal);
+    }
+    catch (cause) {
+        if (cause instanceof GifExportError)
+            throw cause;
+        throw new GifExportError("environment", "Cannot prepare system fonts; check browser font support and retry.", { cause });
+    }
+}
+function createWorker(url) {
+    try {
+        return new Worker(url);
+    }
+    catch (cause) {
+        throw new GifExportError("environment", "Cannot start the GIF worker; allow Blob workers in the browser content security policy.", { cause });
+    }
+}
+function readPixels(context, plan) {
+    try {
+        return context.getImageData(0, 0, plan.width, plan.height);
+    }
+    catch (cause) {
+        throw new GifExportError("rasterization", "Cannot read rendered pixels; check browser canvas permissions and retry.", { cause });
+    }
+}

package/dist/export/captions.d.ts

@@ -0,0 +1,18 @@
+/** Browser caption layout shares system font fallback with diagram SVG and preserves explicit newlines. */
+import type { Diagram } from "../core/diagram.js";
+import type { GifPlan } from "./plan.js";
+export declare const CAPTION_FONT = "16px system-ui, -apple-system, \"PingFang SC\", \"Microsoft YaHei\", \"Noto Sans CJK SC\", sans-serif";
+export declare const CAPTION_LINE_HEIGHT = 22;
+export declare const CAPTION_PADDING_X = 16;
+export declare const CAPTION_PADDING_Y = 12;
+/** Measure code-point wrapping at the available text width; callers must first set CAPTION_FONT. */
+export declare function wrapCaption(context: CanvasRenderingContext2D, text: string, width: number): string[];
+/** Effective plain text and the source location used in actionable overflow errors. */
+export interface CaptionInterval {
+    text: string;
+    location: string;
+}
+/** Enumerate compiled half-open intervals rather than samples; core already resolves caption inheritance. */
+export declare function collectCaptions(diagram: Diagram, startMs: number, endMs: number): CaptionInterval[];
+/** Measure every effective caption with the same fixed font, wrapping and spacing used by painting. */
+export declare function preflightCaptions(context: CanvasRenderingContext2D, captions: CaptionInterval[], plan: GifPlan): void;

package/dist/export/captions.js

@@ -0,0 +1,44 @@
+import { GifExportError } from "./types.js";
+import { DIAGRAM_FONT_FAMILY } from "../core/theme.js";
+export const CAPTION_FONT = `16px ${DIAGRAM_FONT_FAMILY}`;
+export const CAPTION_LINE_HEIGHT = 22;
+export const CAPTION_PADDING_X = 16;
+export const CAPTION_PADDING_Y = 12;
+/** Measure code-point wrapping at the available text width; callers must first set CAPTION_FONT. */
+export function wrapCaption(context, text, width) {
+    const lines = [];
+    for (const paragraph of text.split("\n")) {
+        let line = "";
+        for (const character of paragraph) {
+            if (line && context.measureText(line + character).width > width) {
+                lines.push(line);
+                line = "";
+            }
+            line += character;
+        }
+        lines.push(line);
+    }
+    return lines;
+}
+/** Enumerate compiled half-open intervals rather than samples; core already resolves caption inheritance. */
+export function collectCaptions(diagram, startMs, endMs) {
+    if (diagram.beats.length === 0)
+        return [{ text: diagram.evaluateAt(0).caption ?? "", location: "static document title" }];
+    return diagram.beats.filter((beat) => beat.startMs < endMs && beat.endMs > startMs).map((beat) => ({
+        text: beat.caption ?? "", location: `scene "${beat.sceneId}", beat ${beat.beatIndex + 1}`
+    }));
+}
+/** Measure every effective caption with the same fixed font, wrapping and spacing used by painting. */
+export function preflightCaptions(context, captions, plan) {
+    context.font = CAPTION_FONT;
+    const width = plan.width - CAPTION_PADDING_X * 2;
+    const height = plan.captionHeight - CAPTION_PADDING_Y * 2;
+    for (const { text, location } of captions) {
+        if (text === "")
+            continue;
+        const lines = wrapCaption(context, text, width);
+        if (lines.length * CAPTION_LINE_HEIGHT > height || lines.some((line) => context.measureText(line).width > width)) {
+            throw new GifExportError("caption-overflow", `Caption overflows at ${location}; increase captionHeight or width, shorten the text, or disable captions.`);
+        }
+    }
+}

package/dist/export/plan.d.ts

@@ -0,0 +1,25 @@
+/** Pure export planning: reject computable limits before any browser resource is allocated. */
+import type { DiagramDocument } from "../core/model.js";
+import { type GifExportOptions } from "./types.js";
+/** Source-time evaluation and its output delay, both in milliseconds. */
+export interface GifFrame {
+    timeMs: number;
+    delayMs: number;
+}
+/** Fixed integer pixel dimensions and a bounded sampling schedule shared by browser and Node. */
+export interface GifPlan {
+    width: number;
+    diagramHeight: number;
+    height: number;
+    captionHeight: number;
+    theme: "light" | "dark";
+    frames: GifFrame[];
+    startMs: number;
+    endMs: number;
+    reducedMotion: boolean;
+    loopCount: number;
+}
+/** Validate supplied fields before defaults or cancellation checks can hide malformed input. */
+export declare function validateGifOptions(options: GifExportOptions): void;
+/** Defaults export the complete timeline at 15 fps, capped at 1280px without upscaling, with a 1s final hold. */
+export declare function planGif(document: DiagramDocument, duration: number, options: GifExportOptions): GifPlan;

package/dist/export/plan.js

@@ -0,0 +1,94 @@
+import { GifExportError } from "./types.js";
+const MAX_DURATION_MS = 120_000;
+const MAX_FRAMES = 1800;
+const MAX_ENCODED_FRAMES = 1801;
+const MAX_FRAME_DELAY_TICKS = 65_535;
+const MAX_SIDE = 1920;
+const DEFAULT_MAX_WIDTH = 1280;
+const DEFAULT_FPS = 15;
+const DEFAULT_CAPTION_HEIGHT = 80;
+const DEFAULT_HOLD_MS = 1000;
+const MIN_FPS = 1;
+const MAX_FPS = 30;
+const MAX_TOTAL_PLAYS = 65_536;
+const GIF_TIME_UNIT_MS = 10;
+const SECOND_MS = 1000;
+/** Validate supplied fields before defaults or cancellation checks can hide malformed input. */
+export function validateGifOptions(options) {
+    if (options === null || typeof options !== "object" || Array.isArray(options)) {
+        throw new GifExportError("options", "Provide GIF options as an object.");
+    }
+    for (const name of ["width", "fps", "captionHeight", "startMs", "endMs", "speed", "finalHoldMs", "loopCount"]) {
+        const value = options[name];
+        if (value !== undefined && !Number.isFinite(value))
+            throw new GifExportError("options", `${name} must be a finite number.`);
+    }
+    for (const name of ["includeCaptions", "reducedMotion"]) {
+        if (options[name] !== undefined && typeof options[name] !== "boolean")
+            throw new GifExportError("options", `${name} must be a boolean.`);
+    }
+    if (options.theme !== undefined && options.theme !== "light" && options.theme !== "dark")
+        throw new GifExportError("options", "theme must be light or dark.");
+    if (options.captionHeight !== undefined && options.captionHeight < 0)
+        throw new GifExportError("options", "captionHeight must be nonnegative.");
+    if (options.onProgress !== undefined && typeof options.onProgress !== "function")
+        throw new GifExportError("options", "onProgress must be a function.");
+    if (options.signal !== undefined && !(options.signal instanceof AbortSignal))
+        throw new GifExportError("options", "signal must be an AbortSignal from an AbortController.");
+}
+/** Defaults export the complete timeline at 15 fps, capped at 1280px without upscaling, with a 1s final hold. */
+export function planGif(document, duration, options) {
+    validateGifOptions(options);
+    const width = options.width ?? Math.min(DEFAULT_MAX_WIDTH, document.viewport.width);
+    const fps = options.fps ?? DEFAULT_FPS;
+    const captionHeight = options.includeCaptions === false ? 0 : options.captionHeight ?? DEFAULT_CAPTION_HEIGHT;
+    const startMs = options.startMs ?? 0;
+    const endMs = options.endMs ?? duration;
+    const speed = options.speed ?? 1;
+    const hold = options.finalHoldMs ?? DEFAULT_HOLD_MS;
+    const loopCount = options.loopCount ?? 0;
+    for (const [name, value] of Object.entries({ width, fps, captionHeight, startMs, endMs, speed, finalHoldMs: hold, loopCount })) {
+        if (!Number.isFinite(value))
+            throw new GifExportError("options", `${name} must be finite; provide a valid number.`);
+    }
+    if (width <= 0 || speed <= 0 || hold < 0 || captionHeight < 0 || !Number.isInteger(fps) || fps < MIN_FPS || fps > MAX_FPS)
+        throw new GifExportError("options", "Use positive width/speed, nonnegative hold/caption height and an integer fps from 1 to 30.");
+    if (!Number.isInteger(loopCount) || loopCount < 0 || loopCount > MAX_TOTAL_PLAYS)
+        throw new GifExportError("options", "loopCount must be an integer from 0 to 65,536 (maximum total plays).");
+    if (!Number.isFinite(duration) || startMs < 0 || endMs > duration || (duration === 0 ? startMs !== 0 || endMs !== 0 : startMs >= endMs))
+        throw new GifExportError("options", "Choose a finite, nonempty range within the document timeline; static documents accept only zero.");
+    const outputWidth = Math.max(1, Math.round(width));
+    const diagramHeight = Math.max(1, Math.round(width * document.viewport.height / document.viewport.width));
+    const height = diagramHeight + Math.round(captionHeight);
+    const effectiveDuration = (endMs - startMs) / speed;
+    const proposedCount = duration === 0 ? 0 : Math.max(1, Math.ceil(effectiveDuration * fps / SECOND_MS));
+    // Rounding the division can otherwise add a zero-delay sample at the excluded endpoint.
+    const count = proposedCount > 1 && (proposedCount - 1) * SECOND_MS / fps >= effectiveDuration ? proposedCount - 1 : proposedCount;
+    if (effectiveDuration > MAX_DURATION_MS || count > MAX_FRAMES || Math.max(outputWidth, height) > MAX_SIDE)
+        throw new GifExportError("limit", "Reduce duration, fps or dimensions: limits are 120 seconds, 1800 samples and a 1920px final long edge.");
+    const holdTicks = duration === 0 ? Math.max(1, Math.round(hold / GIF_TIME_UNIT_MS)) : Math.round(hold / GIF_TIME_UNIT_MS);
+    const hasFinalFrame = duration === 0 || hold > 0 || endMs === duration;
+    // Each encoded GCE delay is 16-bit. Count worker splits before allocating or sampling.
+    const encodedFrames = count + (hasFinalFrame ? Math.max(1, Math.ceil(holdTicks / MAX_FRAME_DELAY_TICKS)) : 0);
+    if (encodedFrames > MAX_ENCODED_FRAMES)
+        throw new GifExportError("limit", "GIF requires more than 1801 encoded frames including final-hold splits; reduce finalHoldMs, duration or fps.");
+    const endLeftTime = duration === 0 ? 0 : previousTime(endMs);
+    const frames = [];
+    for (let index = 0; index < count; index++) {
+        const from = index * SECOND_MS / fps;
+        const until = Math.min(effectiveDuration, (index + 1) * SECOND_MS / fps);
+        frames.push({ timeMs: Math.min(endLeftTime, startMs + from * speed), delayMs: (Math.round(until / GIF_TIME_UNIT_MS) - Math.round(from / GIF_TIME_UNIT_MS)) * GIF_TIME_UNIT_MS });
+    }
+    const finalTime = endMs === duration ? endMs : endLeftTime;
+    // Preserve the global completed state even when it has no additional hold delay.
+    if (hasFinalFrame)
+        frames.push({ timeMs: finalTime, delayMs: holdTicks * GIF_TIME_UNIT_MS });
+    return { width: outputWidth, diagramHeight, height, captionHeight: Math.round(captionHeight), theme: options.theme ?? document.theme ?? "light", frames, startMs, endMs, reducedMotion: options.reducedMotion ?? false, loopCount };
+}
+/** Return the immediate predecessor of a positive finite time; epsilon subtraction can skip short beats. */
+function previousTime(timeMs) {
+    const bits = new DataView(new ArrayBuffer(8));
+    bits.setFloat64(0, timeMs);
+    bits.setBigUint64(0, bits.getBigUint64(0) - 1n);
+    return bits.getFloat64(0);
+}

package/dist/export/types.d.ts

@@ -0,0 +1,64 @@
+import type { ThemeName } from "../core/model.js";
+/** Stages belong to one independent export; counts represent acknowledged sampling frames. */
+export interface GifExportProgress {
+    phase: "preparing" | "sampling" | "encoding" | "complete";
+    completed: number;
+    total: number;
+}
+/**
+ * Browser export settings, captured at invocation; times are milliseconds.
+ * Animation is limited to 120 effective seconds and 1800 samples. The final GIF
+ * permits at most 1801 encoded frames, including splits of long final holds.
+ * The final long edge, including captions, must not exceed 1920 pixels.
+ * Invalid values and computable limits fail before canvas allocation or sampling.
+ */
+export interface GifExportOptions {
+    /** Explicit theme; otherwise use the document theme, then light. Never reads system preferences. */
+    theme?: ThemeName;
+    /** Inclusive source start, default 0. Evaluates the full document to retain earlier scene state. */
+    startMs?: number;
+    /**
+     * Exclusive source end, default total duration. A segment holds the end-left picture;
+     * the global end includes its completed state, even with finalHoldMs: 0.
+     * Animated ranges require 0 <= startMs < endMs <= total duration; static ranges require both 0.
+     */
+    endMs?: number;
+    /** Positive finite source-time multiplier, default 1. Output duration is source range / speed. */
+    speed?: number;
+    /**
+     * Positive diagram width in pixels, rounded to an integer. Diagram height preserves the authored viewport ratio.
+     * GIF ignores viewport.fitHeight for all frames to keep pixel dimensions and diagram scale stable.
+     * Defaults to min(viewport.width, 1280), without upscaling; captions add height below the diagram.
+     */
+    width?: number;
+    /** Integer samples per second from 1 to 30, default 15; cumulative GIF delay rounding avoids drift. */
+    fps?: number;
+    /** Include a fixed caption region below the diagram, default true. False removes that region. */
+    includeCaptions?: boolean;
+    /**
+     * Caption-region height in pixels, rounded to an integer; default 80, finite and nonnegative.
+     * Text uses 16px system font, 22px line height, 16px horizontal and 12px vertical padding.
+     * Every effective caption is measured before sampling; overflow reports its scene/beat without clipping or shrinking.
+     */
+    captionHeight?: number;
+    /** Zero means infinite looping (default); integers 1–65,536 mean total plays, with 1 playing once. */
+    loopCount?: number;
+    /**
+     * Additional final-picture delay, finite and nonnegative; default 1000. Zero adds no delay.
+     * Long delays split into bounded GIF frames and count toward the 1801 encoded-frame limit.
+     * Static documents produce one picture with at least 10ms delay, even when this value is zero.
+     */
+    finalHoldMs?: number;
+    /** Default false, independent of system preferences. True completes transitions and hides flow markers without changing duration. */
+    reducedMotion?: boolean;
+    /** Cancels this task with code cancelled; task-owned workers, images, canvas and object URLs are released on every exit. */
+    signal?: AbortSignal;
+    /** Reports preparing, sampling, encoding and complete. Cancellation never reports complete. Does not change player state. */
+    onProgress?: (progress: GifExportProgress) => void;
+}
+export type GifExportErrorCode = "options" | "limit" | "document" | "caption-overflow" | "environment" | "rasterization" | "encoding" | "cancelled";
+/** Distinguishable export failure with a message describing the corrective action. */
+export declare class GifExportError extends Error {
+    readonly code: GifExportErrorCode;
+    constructor(code: GifExportErrorCode, message: string, options?: ErrorOptions);
+}

package/dist/export/types.js

@@ -0,0 +1,9 @@
+/** Distinguishable export failure with a message describing the corrective action. */
+export class GifExportError extends Error {
+    code;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = "GifExportError";
+    }
+}

package/dist/export/worker-source.d.ts

@@ -0,0 +1 @@
+export declare const GIF_WORKER_SOURCE: string;

package/dist/export/worker-source.js

@@ -0,0 +1 @@
+export const GIF_WORKER_SOURCE = "(()=>{var se=Object.create;var W=Object.defineProperty;var le=Object.getOwnPropertyDescriptor;var ae=Object.getOwnPropertyNames;var fe=Object.getPrototypeOf,ue=Object.prototype.hasOwnProperty;var ge=(e,t)=>()=>(t||e((t={exports:{}}).exports,t),t.exports);var de=(e,t,o,n)=>{if(t&&typeof t==\"object\"||typeof t==\"function\")for(let r of ae(t))!ue.call(e,r)&&r!==o&&W(e,r,{get:()=>t[r],enumerable:!(n=le(t,r))||n.enumerable});return e};var he=(e,t,o)=>(o=e!=null?se(fe(e)):{},de(t||!e||!e.__esModule?W(o,\"default\",{value:e,enumerable:!0}):o,e));var ce=ge(H=>{var J=Object.defineProperty,we=e=>J(e,\"__esModule\",{value:!0}),ye=(e,t)=>{for(var o in t)J(e,o,{get:t[o],enumerable:!0})};we(H);ye(H,{GIFEncoder:()=>oe,applyPalette:()=>Ce,default:()=>qe,nearestColor:()=>Fe,nearestColorIndex:()=>ne,nearestColorIndexWithDistance:()=>re,prequantize:()=>ve,quantize:()=>xe,snapColorsToPalette:()=>Ee});var be={signature:\"GIF\",version:\"89a\",trailer:59,extensionIntroducer:33,applicationExtensionLabel:255,graphicControlExtensionLabel:249,imageSeparator:44,signatureSize:3,versionSize:3,globalColorTableFlagMask:128,colorResolutionMask:112,sortFlagMask:8,globalColorTableSizeMask:7,applicationIdentifierSize:8,applicationAuthCodeSize:3,disposalMethodMask:28,userInputFlagMask:2,transparentColorFlagMask:1,localColorTableFlagMask:128,interlaceFlagMask:64,idSortFlagMask:32,localColorTableSizeMask:7};function Q(e=256){let t=0,o=new Uint8Array(e);return{get buffer(){return o.buffer},reset(){t=0},bytesView(){return o.subarray(0,t)},bytes(){return o.slice(0,t)},writeByte(r){n(t+1),o[t]=r,t++},writeBytes(r,i=0,c=r.length){n(t+c);for(let l=0;l<c;l++)o[t++]=r[l+i]},writeBytesView(r,i=0,c=r.byteLength){n(t+c),o.set(r.subarray(i,i+c),t),t+=c}};function n(r){var i=o.length;if(i>=r)return;var c=1024*1024;r=Math.max(r,i*(i<c?2:1.125)>>>0),i!=0&&(r=Math.max(r,256));let l=o;o=new Uint8Array(r),t>0&&o.set(l.subarray(0,t),0)}}var V=12,Y=5003,pe=[0,1,3,7,15,31,63,127,255,511,1023,2047,4095,8191,16383,32767,65535];function Ae(e,t,o,n,r=Q(512),i=new Uint8Array(256),c=new Int32Array(Y),l=new Int32Array(Y)){let g=c.length,f=Math.max(2,n);i.fill(0),l.fill(0),c.fill(-1);let a=0,s=0,d=f+1,p=d,h=!1,w=p,B=(1<<w)-1,u=1<<d-1,I=u+1,M=u+2,y=0,x=o[0],F=0;for(let A=g;A<65536;A*=2)++F;F=8-F,r.writeByte(f),v(u);let b=o.length;for(let A=1;A<b;A++)e:{let k=o[A],E=(k<<V)+x,_=k<<F^x;if(c[_]===E){x=l[_];break e}let P=_===0?1:g-_;for(;c[_]>=0;)if(_-=P,_<0&&(_+=g),c[_]===E){x=l[_];break e}v(x),x=k,M<1<<V?(l[_]=M++,c[_]=E):(c.fill(-1),M=u+2,h=!0,v(u))}return v(x),v(I),r.writeByte(0),r.bytesView();function v(A){for(a&=pe[s],s>0?a|=A<<s:a=A,s+=w;s>=8;)i[y++]=a&255,y>=254&&(r.writeByte(y),r.writeBytesView(i,0,y),y=0),a>>=8,s-=8;if((M>B||h)&&(h?(w=p,B=(1<<w)-1,h=!1):(++w,B=w===V?1<<w:(1<<w)-1)),A==I){for(;s>0;)i[y++]=a&255,y>=254&&(r.writeByte(y),r.writeBytesView(i,0,y),y=0),a>>=8,s-=8;y>0&&(r.writeByte(y),r.writeBytesView(i,0,y),y=0)}}}var Me=Ae;function $(e,t,o){return e<<8&63488|t<<2&992|o>>3}function ee(e,t,o,n){return e>>4|t&240|(o&240)<<4|(n&240)<<8}function te(e,t,o){return e>>4<<8|t&240|o>>4}function q(e,t,o){return e<t?t:e>o?o:e}function S(e){return e*e}function Z(e,t,o){var n=0,r=1e100;let i=e[t],c=i.cnt,l=i.ac,g=i.rc,f=i.gc,a=i.bc;for(var s=i.fw;s!=0;s=e[s].fw){let p=e[s],h=p.cnt,w=c*h/(c+h);if(!(w>=r)){var d=0;o&&(d+=w*S(p.ac-l),d>=r)||(d+=w*S(p.rc-g),!(d>=r)&&(d+=w*S(p.gc-f),!(d>=r)&&(d+=w*S(p.bc-a),!(d>=r)&&(r=d,n=s))))}}i.err=r,i.nn=n}function O(){return{ac:0,rc:0,gc:0,bc:0,cnt:0,nn:0,fw:0,bk:0,tm:0,mtm:0,err:0}}function Be(e,t){let o=t===\"rgb444\"?4096:65536,n=new Array(o),r=e.length;if(t===\"rgba4444\")for(let i=0;i<r;++i){let c=e[i],l=c>>24&255,g=c>>16&255,f=c>>8&255,a=c&255,s=ee(a,f,g,l),d=s in n?n[s]:n[s]=O();d.rc+=a,d.gc+=f,d.bc+=g,d.ac+=l,d.cnt++}else if(t===\"rgb444\")for(let i=0;i<r;++i){let c=e[i],l=c>>16&255,g=c>>8&255,f=c&255,a=te(f,g,l),s=a in n?n[a]:n[a]=O();s.rc+=f,s.gc+=g,s.bc+=l,s.cnt++}else for(let i=0;i<r;++i){let c=e[i],l=c>>16&255,g=c>>8&255,f=c&255,a=$(f,g,l),s=a in n?n[a]:n[a]=O();s.rc+=f,s.gc+=g,s.bc+=l,s.cnt++}return n}function xe(e,t,o={}){let{format:n=\"rgb565\",clearAlpha:r=!0,clearAlphaColor:i=0,clearAlphaThreshold:c=0,oneBitAlpha:l=!1}=o;if(!e||!e.buffer)throw new Error(\"quantize() expected RGBA Uint8Array data\");if(!(e instanceof Uint8Array)&&!(e instanceof Uint8ClampedArray))throw new Error(\"quantize() expected RGBA Uint8Array data\");let g=new Uint32Array(e.buffer),f=o.useSqrt!==!1,a=n===\"rgba4444\",s=Be(g,n),d=s.length,p=d-1,h=new Uint32Array(d+1);for(var w=0,u=0;u<d;++u){let C=s[u];if(C!=null){var B=1/C.cnt;a&&(C.ac*=B),C.rc*=B,C.gc*=B,C.bc*=B,s[w++]=C}}S(t)/w<.022&&(f=!1);for(var u=0;u<w-1;++u)s[u].fw=u+1,s[u+1].bk=u,f&&(s[u].cnt=Math.sqrt(s[u].cnt));f&&(s[u].cnt=Math.sqrt(s[u].cnt));var I,M,y;for(u=0;u<w;++u){Z(s,u,!1);var x=s[u].err;for(M=++h[0];M>1&&(y=M>>1,!(s[I=h[y]].err<=x));M=y)h[M]=I;h[M]=u}var F=w-t;for(u=0;u<F;){for(var b;;){var v=h[1];if(b=s[v],b.tm>=b.mtm&&s[b.nn].mtm<=b.tm)break;b.mtm==p?v=h[1]=h[h[0]--]:(Z(s,v,!1),b.tm=u);var x=s[v].err;for(M=1;(y=M+M)<=h[0]&&(y<h[0]&&s[h[y]].err>s[h[y+1]].err&&y++,!(x<=s[I=h[y]].err));M=y)h[M]=I;h[M]=v}var A=s[b.nn],k=b.cnt,E=A.cnt,B=1/(k+E);a&&(b.ac=B*(k*b.ac+E*A.ac)),b.rc=B*(k*b.rc+E*A.rc),b.gc=B*(k*b.gc+E*A.gc),b.bc=B*(k*b.bc+E*A.bc),b.cnt+=A.cnt,b.mtm=++u,s[A.bk].fw=A.fw,s[A.fw].bk=A.bk,A.mtm=p}let _=[];var P=0;for(u=0;;++P){let R=q(Math.round(s[u].rc),0,255),C=q(Math.round(s[u].gc),0,255),L=q(Math.round(s[u].bc),0,255),T=255;a&&(T=q(Math.round(s[u].ac),0,255),l&&(T=T<=(typeof l==\"number\"?l:127)?0:255),r&&T<=c&&(R=C=L=i,T=0));let X=a?[R,C,L,T]:[R,C,L];if(_e(_,X)||_.push(X),(u=s[u].fw)==0)break}return _}function _e(e,t){for(let o=0;o<e.length;o++){let n=e[o],r=n[0]===t[0]&&n[1]===t[1]&&n[2]===t[2],i=n.length>=4&&t.length>=4?n[3]===t[3]:!0;if(r&&i)return!0}return!1}function G(e,t){var o=0,n;for(n=0;n<e.length;n++){let r=e[n]-t[n];o+=r*r}return o}function D(e,t){return t>1?Math.round(e/t)*t:e}function ve(e,{roundRGB:t=5,roundAlpha:o=10,oneBitAlpha:n=null}={}){let r=new Uint32Array(e.buffer);for(let i=0;i<r.length;i++){let c=r[i],l=c>>24&255,g=c>>16&255,f=c>>8&255,a=c&255;l=D(l,o),n&&(l=l<=(typeof n==\"number\"?n:127)?0:255),a=D(a,t),f=D(f,t),g=D(g,t),r[i]=l<<24|g<<16|f<<8|a<<0}}function Ce(e,t,o=\"rgb565\"){if(!e||!e.buffer)throw new Error(\"quantize() expected RGBA Uint8Array data\");if(!(e instanceof Uint8Array)&&!(e instanceof Uint8ClampedArray))throw new Error(\"quantize() expected RGBA Uint8Array data\");if(t.length>256)throw new Error(\"applyPalette() only works with 256 colors or less\");let n=new Uint32Array(e.buffer),r=n.length,i=o===\"rgb444\"?4096:65536,c=new Uint8Array(r),l=new Array(i),g=o===\"rgba4444\";if(o===\"rgba4444\")for(let f=0;f<r;f++){let a=n[f],s=a>>24&255,d=a>>16&255,p=a>>8&255,h=a&255,w=ee(h,p,d,s),B=w in l?l[w]:l[w]=Ie(h,p,d,s,t);c[f]=B}else{let f=o===\"rgb444\"?te:$;for(let a=0;a<r;a++){let s=n[a],d=s>>16&255,p=s>>8&255,h=s&255,w=f(h,p,d),B=w in l?l[w]:l[w]=ke(h,p,d,t);c[a]=B}}return c}function Ie(e,t,o,n,r){let i=0,c=1e100;for(let l=0;l<r.length;l++){let g=r[l],f=g[3],a=z(f-n);if(a>c)continue;let s=g[0];if(a+=z(s-e),a>c)continue;let d=g[1];if(a+=z(d-t),a>c)continue;let p=g[2];a+=z(p-o),!(a>c)&&(c=a,i=l)}return i}function ke(e,t,o,n){let r=0,i=1e100;for(let c=0;c<n.length;c++){let l=n[c],g=l[0],f=z(g-e);if(f>i)continue;let a=l[1];if(f+=z(a-t),f>i)continue;let s=l[2];f+=z(s-o),!(f>i)&&(i=f,r=c)}return r}function Ee(e,t,o=5){if(!e.length||!t.length)return;let n=e.map(c=>c.slice(0,3)),r=o*o,i=e[0].length;for(let c=0;c<t.length;c++){let l=t[c];l.length<i?l=[l[0],l[1],l[2],255]:l.length>i?l=l.slice(0,3):l=l.slice();let g=re(n,l.slice(0,3),G),f=g[0],a=g[1];a>0&&a<=r&&(e[f]=l)}}function z(e){return e*e}function ne(e,t,o=G){let n=1/0,r=-1;for(let i=0;i<e.length;i++){let c=e[i],l=o(t,c);l<n&&(n=l,r=i)}return r}function re(e,t,o=G){let n=1/0,r=-1;for(let i=0;i<e.length;i++){let c=e[i],l=o(t,c);l<n&&(n=l,r=i)}return[r,n]}function Fe(e,t,o=G){return e[ne(e,t,o)]}function oe(e={}){let{initialCapacity:t=4096,auto:o=!0}=e,n=Q(t),r=5003,i=new Uint8Array(256),c=new Int32Array(r),l=new Int32Array(r),g=!1;return{reset(){n.reset(),g=!1},finish(){n.writeByte(be.trailer)},bytes(){return n.bytes()},bytesView(){return n.bytesView()},get buffer(){return n.buffer},get stream(){return n},writeHeader:f,writeFrame(a,s,d,p={}){let{transparent:h=!1,transparentIndex:w=0,delay:B=0,palette:u=null,repeat:I=0,colorDepth:M=8,dispose:y=-1}=p,x=!1;if(o?g||(x=!0,f(),g=!0):x=!!p.first,s=Math.max(0,Math.floor(s)),d=Math.max(0,Math.floor(d)),x){if(!u)throw new Error(\"First frame must include a { palette } option\");ze(n,s,d,u,M),K(n,u),I>=0&&Te(n,I)}let F=Math.round(B/10);me(n,y,F,h,w);let b=!!u&&!x;Ue(n,s,d,b?u:null),b&&K(n,u),Se(n,a,s,d,M,i,c,l)}};function f(){ie(n,\"GIF89a\")}}function me(e,t,o,n,r){e.writeByte(33),e.writeByte(249),e.writeByte(4),r<0&&(r=0,n=!1);var i,c;n?(i=1,c=2):(i=0,c=0),t>=0&&(c=t&7),c<<=2,e.writeByte(0|c|0|i),m(e,o),e.writeByte(r||0),e.writeByte(0)}function ze(e,t,o,n,r=8){let l=j(n.length)-1,g=128|r-1<<4|0|l,f=0,a=0;m(e,t),m(e,o),e.writeBytes([g,f,a])}function Te(e,t){e.writeByte(33),e.writeByte(255),e.writeByte(11),ie(e,\"NETSCAPE2.0\"),e.writeByte(3),e.writeByte(1),m(e,t),e.writeByte(0)}function K(e,t){let o=1<<j(t.length);for(let n=0;n<o;n++){let r=[0,0,0];n<t.length&&(r=t[n]),e.writeByte(r[0]),e.writeByte(r[1]),e.writeByte(r[2])}}function Ue(e,t,o,n){if(e.writeByte(44),m(e,0),m(e,0),m(e,t),m(e,o),n){let c=j(n.length)-1;e.writeByte(128|c)}else e.writeByte(0)}function Se(e,t,o,n,r=8,i,c,l){Me(o,n,t,r,e,i,c,l)}function m(e,t){e.writeByte(t&255),e.writeByte(t>>8&255)}function ie(e,t){for(var o=0;o<t.length;o++)e.writeByte(t.charCodeAt(o))}function j(e){return Math.max(Math.ceil(Math.log2(e)),1)}var qe=oe});var U=he(ce(),1),N=(0,U.GIFEncoder)(),De=655350,Ge=256;self.onmessage=e=>{try{let t=e.data;if(t.type===\"finish\"){N.finish();let c=N.bytes();self.postMessage({bytes:c},{transfer:[c.buffer]});return}let o=new Uint8Array(t.rgba),n=(0,U.quantize)(o,Ge),r=(0,U.applyPalette)(o,n),i=t.delayMs;do{let c=Math.min(i,De);N.writeFrame(r,t.width,t.height,{palette:n,delay:c,repeat:t.repeat}),i-=c}while(i>0);self.postMessage({acknowledged:!0})}catch(t){self.postMessage({error:t instanceof Error?t.message:String(t)})}};})();\n";

package/dist/export.d.ts

@@ -0,0 +1,3 @@
+export { exportGif } from "./export/browser.js";
+export { GifExportError } from "./export/types.js";
+export type { GifExportOptions, GifExportProgress, GifExportErrorCode } from "./export/types.js";

package/dist/export.js

@@ -0,0 +1,2 @@
+export { exportGif } from "./export/browser.js";
+export { GifExportError } from "./export/types.js";

package/dist/index.d.ts

@@ -1 +1,7 @@
-export * from "./core.js";
+export { createDiagram, renderSvg, wrapText } from "./core/diagram.js";
+export type { Diagram } from "./core/diagram.js";
+export { validateDocument, DiagramValidationError } from "./core/validation.js";
+export type { NodeKind, EdgeRoute, PortDirection, FlowDirection, ThemeName, Viewport, NodeStyle, EdgeStyle, DiagramNode, DiagramEdge, DiagramDocument, Scene, Beat, DiagramBeat, NodeVisualState, EdgeVisualState, Action, ValidationIssue, EvaluateOptions, TextLine, EvaluatedNode, EvaluatedEdge, EdgeFlowMarker, LayoutWarning, CameraState, HitObjectType, HitObject, DiagramPoint, DiagramFrameState } from "./core/model.js";
+export type { NodeContent, ContentBlock, ContentListItem, ContentListStyle, ContentTag, ContentTagStyle, ContentTagBackground, ContentGraphBlock, ContentGraphNode, ContentGraphEdge, ContentGraphLayout, ContentText, ContentTextSpan, ContentSpanStyle, ContentSpan, ContentTextStyle, ContentAlignment, ContentSafeArea, ContentLine, NodeContentLayout } from "./core/node-content.js";
+export { measureNodeContent } from "./core/node-content-measurement.js";
+export type { NodeContentMeasurementInput, NodeContentMeasurement, NodeContentMeasurementDiagnostic } from "./core/node-content-measurement.js";

package/dist/index.js

@@ -1 +1,3 @@
-export * from "./core.js";
+export { createDiagram, renderSvg, wrapText } from "./core/diagram.js";
+export { validateDocument, DiagramValidationError } from "./core/validation.js";
+export { measureNodeContent } from "./core/node-content-measurement.js";

package/dist/node/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/node/cli.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+/** Node CLI: render completely, then atomically publish HTML/GIF; cancellation never publishes partial bytes. */
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { renderHtml, assertNodeRuntime } from "./html.js";
+import { exportGif } from "./gif.js";
+import { publishOutput } from "./output.js";
+const USAGE = `Usage: flowsvg INPUT.json --output OUTPUT --format html|gif [options]
+Common: --theme light|dark --overwrite
+HTML: --autoplay --no-controls --gif-export
+GIF: --executable-path PATH --start-ms N --end-ms N --speed N --width N --fps N
+     --no-captions --caption-height N --loop-count N --final-hold-ms N --reduced-motion
+GIF requires Node 20+ and preinstalled Chromium; browsers are never downloaded automatically.`;
+const CLI_OPTIONS = {
+    output: { type: "string", short: "o" }, format: { type: "string" }, theme: { type: "string" },
+    autoplay: { type: "boolean" }, "gif-export": { type: "boolean" }, "no-controls": { type: "boolean" }, overwrite: { type: "boolean" },
+    "executable-path": { type: "string" }, "start-ms": { type: "string" }, "end-ms": { type: "string" },
+    speed: { type: "string" }, width: { type: "string" }, fps: { type: "string" },
+    "no-captions": { type: "boolean" }, "caption-height": { type: "string" }, "loop-count": { type: "string" },
+    "final-hold-ms": { type: "string" }, "reduced-motion": { type: "boolean" }, help: { type: "boolean", short: "h" }
+};
+function parseCli() { return parseArgs({ allowPositionals: true, options: CLI_OPTIONS }); }
+async function main(signal) {
+    assertNodeRuntime();
+    const { values, positionals } = parseCli();
+    if (values.help) {
+        console.log(USAGE);
+        return;
+    }
+    if (positionals.length !== 1 || !values.output || !["html", "gif"].includes(values.format ?? ""))
+        throw new Error(USAGE);
+    if (values.theme !== undefined && values.theme !== "light" && values.theme !== "dark")
+        throw new Error("Theme must be light or dark.");
+    const input = JSON.parse(await readFile(resolve(positionals[0]), "utf8"));
+    signal.throwIfAborted();
+    const theme = values.theme;
+    const content = values.format === "gif"
+        ? await exportGif(input, gifOptions(values, theme, signal))
+        : await renderHtml(input, { theme, autoplay: values.autoplay, controls: !values["no-controls"], gifExport: values["gif-export"] });
+    await publishOutput(resolve(values.output), content, values.overwrite === true, signal);
+}
+function gifOptions(values, theme, signal) {
+    return {
+        theme, signal, executablePath: values["executable-path"],
+        startMs: numericOption(values["start-ms"], "start-ms"), endMs: numericOption(values["end-ms"], "end-ms"),
+        speed: numericOption(values.speed, "speed"), width: numericOption(values.width, "width"), fps: numericOption(values.fps, "fps"),
+        includeCaptions: !values["no-captions"], captionHeight: numericOption(values["caption-height"], "caption-height"),
+        loopCount: numericOption(values["loop-count"], "loop-count"), finalHoldMs: numericOption(values["final-hold-ms"], "final-hold-ms"),
+        reducedMotion: values["reduced-motion"],
+        onProgress: (progress) => { console.error(`FlowSVG: ${progress.phase} ${progress.completed}/${progress.total}`); }
+    };
+}
+function numericOption(value, name) {
+    if (value === undefined)
+        return undefined;
+    const number = Number(value);
+    if (value.trim() === "" || !Number.isFinite(number))
+        throw new Error(`--${name} requires a finite number.`);
+    return number;
+}
+const controller = new AbortController();
+const cancel = () => controller.abort(new Error("Export cancelled by signal."));
+process.on("SIGINT", cancel);
+process.on("SIGTERM", cancel);
+main(controller.signal).catch((error) => {
+    console.error(`FlowSVG: ${error instanceof Error ? error.message : String(error)}`);
+    process.exitCode = 1;
+}).finally(() => {
+    process.off("SIGINT", cancel);
+    process.off("SIGTERM", cancel);
+});

package/dist/node/gif.d.ts

@@ -0,0 +1,16 @@
+import type { Browser } from "playwright-core";
+import type { DiagramDocument } from "../core/model.js";
+import { type GifExportOptions } from "../export/types.js";
+/** Node-only browser selection. Choose browser or executablePath; a supplied browser remains caller-owned. */
+export interface NodeGifExportOptions extends GifExportOptions {
+    /** Use an already installed Chromium executable. This function never downloads a browser. */
+    executablePath?: string;
+    /** Already connected/launched Playwright browser; only the task's isolated context is closed. */
+    browser?: Browser;
+}
+/**
+ * Return GIF bytes using the same exporter as flowsvg/export. Requires Node 20+ and preinstalled Chromium.
+ * Snapshot inputs before asynchronous work. Success, error and cancellation release task-owned resources;
+ * a supplied browser is never closed. Progress is forwarded from the browser exporter.
+ */
+export declare function exportGif(document: DiagramDocument, options?: NodeGifExportOptions): Promise<Uint8Array>;