flowsvg 0.1.1 → 0.2.0

package/dist/core/node-content.js

@@ -43,26 +43,44 @@ function contentSafeArea(bounds, padding, kind) {
 }
 /** Lay out current content from the top left, without DOM font measurement or authored-size changes. */
 export function layoutNodeContent(content, bounds, palette, kind) {
+    return layoutNodeContentWithMetrics(content, bounds, palette, kind).layout;
+}
+/**
+ * Internal layout shared by fixed-size evaluation and author-time measurement.
+ * contentHeight includes complete line boxes, padded tags, graph block heights and all authored gaps.
+ * overflows retain only width limits and graph-internal height limits; outer node height remains adjustable.
+ */
+export function layoutNodeContentWithMetrics(content, bounds, palette, kind) {
     const safeArea = contentSafeArea(bounds, content.style?.padding ?? DEFAULT_PADDING, kind);
     let cursorY = safeArea.y;
     let widthOverflow = false;
     let heightOverflow = false;
     const tags = [];
     const graphs = [];
+    const overflows = [];
     const lines = content.blocks.flatMap((block, blockIndex) => {
         const result = block.type === "graph"
             ? layoutContentGraph(block, safeArea, cursorY, palette, blockIndex, graphs)
             : block.type === "list"
                 ? layoutContentList(block, safeArea, cursorY, palette, blockIndex)
                 : layoutTextPart(block.text, block.type === "title" ? "title" : block.role ?? "body", block.style, safeArea, cursorY, palette, blockIndex);
-        widthOverflow ||= result.widthOverflow;
+        const blockWidthOverflow = result.widthOverflow || result.lines.some((line) => contentLineExceedsWidth(line, safeArea));
+        if (blockWidthOverflow)
+            overflows.push({ blockIndex, dimension: "width" });
+        if (result.heightOverflow)
+            overflows.push({ blockIndex, dimension: "height" });
+        widthOverflow ||= blockWidthOverflow;
         heightOverflow ||= result.heightOverflow ?? false;
         tags.push(...result.tags);
         cursorY = result.bottom + (blockIndex < content.blocks.length - 1 ? content.style?.blockGap ?? DEFAULT_BLOCK_GAP : 0);
         return result.lines;
     });
-    return { safeArea, lines, tags, ...(graphs.length ? { graphs } : {}), widthOverflow: widthOverflow || lines.some((line) => contentLineExceedsWidth(line, safeArea)),
-        heightOverflow: heightOverflow || cursorY > safeArea.y + safeArea.height };
+    return { contentHeight: cursorY - safeArea.y, overflows, layout: {
+            safeArea, lines, tags, ...(graphs.length ? { graphs } : {}),
+            widthOverflow,
+            // Authored positions change accumulation rounding; use the same geometric tolerance as width checks.
+            heightOverflow: heightOverflow || cursorY > safeArea.y + safeArea.height + OVERFLOW_TOLERANCE
+        } };
 }
 /** Graph labels reuse text metrics; authored graph geometry is clipped instead of resized. */
 function layoutContentGraph(block, area, top, palette, blockIndex, graphs) {
@@ -82,7 +100,9 @@ function layoutContentGraph(block, area, top, palette, blockIndex, graphs) {
     graphs.push({ blockIndex, nodes, edges });
     return { lines: parts.flatMap((part) => part.lines), tags: [],
         bottom: top + block.height,
-        heightOverflow: parts.some((part) => part.lines.some((line) => line.y - line.fontSize < top) || part.bottom > top + block.height)
+        // Recovering a label top from its absolute baseline can round across the block boundary.
+        heightOverflow: parts.some((part) => part.lines.some((line) => line.y - line.fontSize < top - OVERFLOW_TOLERANCE)
+            || part.bottom > top + block.height)
             || block.nodes.some((node) => node.y - GRAPH_NODE_RADIUS < 0 || node.y + GRAPH_NODE_RADIUS > block.height),
         widthOverflow: parts.some((part) => part.widthOverflow) || block.nodes.some((node) => node.x < GRAPH_NODE_RADIUS
             || node.x + GRAPH_NODE_RADIUS > area.width) };
@@ -215,7 +235,8 @@ function layoutContentTag(tag, area, top, palette, blockIndex, itemIndex, tagInd
     return { ...result, widthOverflow: result.widthOverflow || area.width < TAG_PADDING_X * 2,
         lines: result.lines.map((line) => ({ ...line, tagIndex })), bottom: result.bottom + TAG_PADDING_Y,
         tags: [{ x: area.x, y: top, width: area.width, height: result.bottom - top + TAG_PADDING_Y,
-                fill: tag.style?.fill ?? palette.tagFill, explicitFill: tag.style?.fill !== undefined, blockIndex, itemIndex, tagIndex }] };
+                fill: tag.style?.fill ?? palette.tagFill, explicitFill: tag.style?.fill !== undefined,
+                ...(tag.style?.shape === undefined ? {} : { shape: tag.style.shape }), blockIndex, itemIndex, tagIndex }] };
 }
 /** Baseline shifts preserve line spacing and expand tag backgrounds instead of moving the row boundary. */
 function shiftTagText(part, offset) {
@@ -473,10 +494,13 @@ function validateContentTags(value, path, issues) {
             validateContentTextStyle(tag.style, `${tagPath}.style`, issues, true);
             continue;
         }
-        const { fill, ...textStyle } = tag.style;
+        const { fill, shape, ...textStyle } = tag.style;
         validateContentTextStyle(textStyle, `${tagPath}.style`, issues, true);
         if (fill !== undefined)
             validateColor(fill, `${tagPath}.style.fill`, issues);
+        if (shape !== undefined && shape !== "rounded" && shape !== "pill") {
+            issues.push({ path: `${tagPath}.style.shape`, message: "must be rounded or pill" });
+        }
     }
 }
 /** Validate inline source values before evaluation; unknown fields keep their exact source position. */

package/dist/core/timeline.d.ts

@@ -2,7 +2,7 @@
  * Deterministic global timeline: compile actions/snapshots and evaluate base styles, visibility, highlights and focus.
  * Spatial layout and SVG output belong to the core; theme defaults are supplied only during evaluation.
  */
-import type { DiagramDocument, EvaluateOptions, FlowDirection, NodeVisualState, EdgeVisualState } from "./model.js";
+import type { DiagramBeat, DiagramDocument, EvaluateOptions, FlowDirection, NodeVisualState, EdgeVisualState } from "./model.js";
 type VisualValues = NodeVisualState & EdgeVisualState;
 /** Evaluation-time theme defaults; unspecified snapshot colors remain unresolved so compilation does not fix a theme. */
 export interface TimelinePalette {
@@ -10,11 +10,12 @@ export interface TimelinePalette {
     stroke: string;
     edge: string;
 }
-/** One transfer in a synchronized beat-local group; no transfer persists in inherited snapshots. */
+/** One beat-local transfer; single-flow movement may finish before its beat, and no flow persists in snapshots. */
 export interface CompiledFlow {
     target: string;
     direction: FlowDirection;
     text?: string;
+    highlightParticipants: boolean;
 }
 /** Object transition result; highlight is the overlay weight, while highlighted is the target logical state. */
 export interface TimelineObject {
@@ -30,6 +31,12 @@ export interface TimelineFrame {
     sceneId: string | null;
     beatId: string | null;
     beatProgress: number;
+    /** Linear movement completion, clamped at arrival while the beat retains temporary highlights. */
+    flowProgress: number;
+    /** Single-flow receiver paint after arrival; independent of logical highlights and opening transitions. */
+    flowArrivalProgress: number;
+    /** Single-flow automatic paint removal during the last 200 ms; logical flags and marker lifetime are unchanged. */
+    flowDepartureProgress: number;
     transitionProgress: number;
     focusBefore: string | null;
     focusAfter: string | null;
@@ -44,10 +51,11 @@ export interface TimelineFrame {
  */
 export declare class CompiledTimeline {
     readonly totalDuration: number;
+    readonly schedule: readonly DiagramBeat[];
     private readonly beats;
     private readonly initial;
     private readonly title?;
-    constructor(document: DiagramDocument);
+    constructor(document: DiagramDocument, movementDurations?: ReadonlyMap<string, number>);
     /** Clamp finite times globally; reduced motion skips interpolation but preserves beat selection and total duration. */
     evaluateAt(timeMs: number, options: EvaluateOptions, palette: TimelinePalette): TimelineFrame;
     /** Select the next beat at endMs, retaining the last beat at total duration; static documents return undefined. */

package/dist/core/timeline.js

@@ -1,5 +1,10 @@
 import { mixColor } from "./color.js";
+import { DiagramValidationError } from "./validation.js";
 const DEFAULT_TRANSITION_MS = 250;
+const FLOW_ARRIVAL_TRANSITION_MS = 200;
+const FLOW_FULL_HIGHLIGHT_HOLD_MS = 100;
+const FLOW_DEPARTURE_TRANSITION_MS = 200;
+const FLOW_ARRIVAL_HOLD_MS = FLOW_ARRIVAL_TRANSITION_MS + FLOW_FULL_HIGHLIGHT_HOLD_MS + FLOW_DEPARTURE_TRANSITION_MS;
 const NUMERIC_VISUAL_FIELDS = ["x", "y", "width", "height", "opacity", "strokeWidth"];
 const DEFAULT_STROKE_WIDTH = 2;
 /**
@@ -9,10 +14,11 @@ const DEFAULT_STROKE_WIDTH = 2;
  */
 export class CompiledTimeline {
     totalDuration;
+    schedule;
     beats;
     initial;
     title;
-    constructor(document) {
+    constructor(document, movementDurations = new Map()) {
         this.initial = new Map([
             ...document.nodes.map((node) => [node.id, {
                     visible: node.visible !== false, highlighted: false, kind: "node", values: {
@@ -31,7 +37,7 @@ export class CompiledTimeline {
         let focus = null;
         let startMs = 0;
         let caption = document.title;
-        for (const scene of document.scenes) {
+        for (const [sceneIndex, scene] of document.scenes.entries()) {
             scene.beats.forEach((beat, index) => {
                 // Copy the index, then replace changed objects/values so earlier beat snapshots retain their original state.
                 const after = new Map(state);
@@ -39,7 +45,8 @@ export class CompiledTimeline {
                 const flows = [];
                 for (const action of beat.actions) {
                     if (action.type === "flow") {
-                        flows.push({ target: action.target, direction: action.direction, ...(action.text !== undefined ? { text: action.text } : {}) });
+                        flows.push({ target: action.target, direction: action.direction, highlightParticipants: action.highlightParticipants ?? true,
+                            ...(action.text !== undefined ? { text: action.text } : {}) });
                         continue;
                     }
                     if (action.type === "focus") {
@@ -64,13 +71,25 @@ export class CompiledTimeline {
                     }
                 }
                 caption = beat.caption ?? caption;
-                const endMs = startMs + beat.durationMs;
-                beats.push({ startMs, endMs, transitionMs: beat.transitionMs ?? Math.min(DEFAULT_TRANSITION_MS, beat.durationMs), sceneId: scene.id, beatId: `${scene.id}:${index}`, caption, focusBefore, focusAfter: focus, before: state, after, flows });
+                const beatId = `${scene.id}:${index}`;
+                const movementMs = movementDurations.get(beatId) ?? beat.durationMs;
+                // Reference compilation keeps authored timing; effective single-flow beats own a fixed arrival hold.
+                const durationMs = movementDurations.has(beatId) ? movementMs + FLOW_ARRIVAL_HOLD_MS : beat.durationMs;
+                const endMs = startMs + durationMs;
+                // A shortened beat must finish its opening transition before the next snapshot takes over.
+                const transitionMs = Math.min(durationMs, beat.transitionMs ?? Math.min(DEFAULT_TRANSITION_MS, beat.durationMs));
+                if (!Number.isFinite(movementMs) || !Number.isFinite(endMs)) {
+                    throw new DiagramValidationError([{ path: `scenes[${sceneIndex}].beats[${index}].durationMs`, message: "effective beat timing must be finite" }]);
+                }
+                beats.push({ startMs, endMs, movementMs, transitionMs, sceneId: scene.id, beatId, beatIndex: index, caption, focusBefore, focusAfter: focus, before: state, after, flows });
                 state = after;
                 startMs = endMs;
             });
         }
         this.beats = beats;
+        this.schedule = Object.freeze(beats.map(({ sceneId, beatId, beatIndex, startMs, endMs, caption }) => Object.freeze({
+            sceneId, beatId, beatIndex, startMs, endMs, ...(caption !== undefined ? { caption } : {})
+        })));
         this.totalDuration = startMs;
     }
     /** Clamp finite times globally; reduced motion skips interpolation but preserves beat selection and total duration. */
@@ -98,6 +117,11 @@ export class CompiledTimeline {
             sceneId: beat?.sceneId ?? null,
             beatId: beat?.beatId ?? null,
             beatProgress: beat ? (time - beat.startMs) / (beat.endMs - beat.startMs) : 0,
+            flowProgress: beat ? Math.min(1, (time - beat.startMs) / beat.movementMs) : 0,
+            flowArrivalProgress: !beat || options.reducedMotion || beat.flows.length !== 1 ? 1
+                : easeInOutCubic(Math.max(0, Math.min(1, (time - beat.startMs - beat.movementMs) / FLOW_ARRIVAL_TRANSITION_MS))),
+            flowDepartureProgress: !beat || options.reducedMotion || beat.flows.length !== 1 ? 0
+                : easeInOutCubic(Math.max(0, Math.min(1, (time - beat.endMs + FLOW_DEPARTURE_TRANSITION_MS) / FLOW_DEPARTURE_TRANSITION_MS))),
             transitionProgress: progress,
             focusBefore: beat?.focusBefore ?? null,
             focusAfter: beat?.focusAfter ?? null,

package/dist/core/validation.d.ts

@@ -1,5 +1,5 @@
 import type { ValidationIssue } from "./model.js";
-/** Compilation error for invalid documents; issues contains all field problems found by validation. */
+/** Validation error for invalid documents or author-time measurement inputs; issues retains all affected field paths. */
 export declare class DiagramValidationError extends Error {
     readonly issues: readonly ValidationIssue[];
     constructor(issues: ValidationIssue[]);

package/dist/core/validation.js

@@ -1,6 +1,6 @@
 /** Validate document fields, references and action conflicts without mutating input; content rules stay shared. */
 import { supportsNodeContent, validateNodeContent } from "./node-content.js";
-/** Compilation error for invalid documents; issues contains all field problems found by validation. */
+/** Validation error for invalid documents or author-time measurement inputs; issues retains all affected field paths. */
 export class DiagramValidationError extends Error {
     issues;
     constructor(issues) {
@@ -30,9 +30,17 @@ export function validateDocument(input) {
         issues.push({ path: "viewport", message: "must be an object" });
     }
     else {
-        validateUnknownFields(viewport, ["width", "height"], "viewport", issues);
+        validateUnknownFields(viewport, ["width", "height", "fitHeight"], "viewport", issues);
         validatePositiveFinite(viewport.width, "viewport.width", issues);
         validatePositiveFinite(viewport.height, "viewport.height", issues);
+        if (viewport.fitHeight !== undefined) {
+            if (!isRecord(viewport.fitHeight))
+                issues.push({ path: "viewport.fitHeight", message: "must be an object" });
+            else {
+                validateUnknownFields(viewport.fitHeight, ["padding"], "viewport.fitHeight", issues);
+                validateNonNegativeFinite(viewport.fitHeight.padding, "viewport.fitHeight.padding", issues);
+            }
+        }
     }
     if (!Array.isArray(input.nodes))
         issues.push({ path: "nodes", message: "must be an array" });
@@ -298,7 +306,7 @@ function validateAction(action, path, allIds, nodeById, edgeById, assignments, i
     const allowedByType = {
         show: ["type", "target"], hide: ["type", "target"], highlight: ["type", "target"], unhighlight: ["type", "target"],
         updateNode: ["type", "target", "value"], updateEdge: ["type", "target", "value"], focus: ["type", "target"],
-        flow: ["type", "target", "direction", "text"]
+        flow: ["type", "target", "direction", "text", "highlightParticipants"]
     };
     const allowed = Object.hasOwn(allowedByType, type) ? allowedByType[type] : undefined;
     if (!allowed) {
@@ -332,6 +340,8 @@ function validateAction(action, path, allIds, nodeById, edgeById, assignments, i
             issues.push({ path: `${path}.direction`, message: "must be forward or reverse" });
         if (action.text !== undefined && typeof action.text !== "string")
             issues.push({ path: `${path}.text`, message: "must be a string" });
+        if (action.highlightParticipants !== undefined && typeof action.highlightParticipants !== "boolean")
+            issues.push({ path: `${path}.highlightParticipants`, message: "must be a boolean" });
         // Reserve the edge independently of other field errors so invalid directions cannot hide duplicate transfers.
         if (isNonEmptyString(action.target) && edgeById.has(action.target))
             addAssignment(`flow:${action.target}`, `${path}.target`, assignments, issues);

package/dist/export/browser.d.ts

@@ -0,0 +1,9 @@
+import type { DiagramDocument } from "../core/model.js";
+import { type GifExportOptions } 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 declare function exportGif(input: DiagramDocument, options?: GifExportOptions): Promise<Uint8Array>;

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);
+}