flowsvg 0.1.1 → 0.2.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,5 +1,7 @@
 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, NodeVisualState, EdgeVisualState, Action, ValidationIssue, EvaluateOptions, TextLine, EvaluatedNode, EvaluatedEdge, EdgeFlowMarker, LayoutWarning, CameraState, HitObjectType, HitObject, DiagramPoint, DiagramFrameState } from "./core/model.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,2 +1,3 @@
 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>;

package/dist/node/gif.js

@@ -0,0 +1,184 @@
+/** Node GIF bridge. Reuse the built browser exporter in an isolated, offline Chromium page. */
+import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+import { createDiagram } from "../core/diagram.js";
+import { planGif, validateGifOptions } from "../export/plan.js";
+import { GifExportError } from "../export/types.js";
+import { assertNodeRuntime } from "./html.js";
+/**
+ * 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 async function exportGif(document, options = {}) {
+    assertNodeRuntime();
+    validateGifOptions(options);
+    const { browser: externalBrowser, executablePath, signal, onProgress, ...settings } = options;
+    const snapshot = snapshotInput(document, "document");
+    const fixedOptions = snapshotInput(settings, "options");
+    if (executablePath !== undefined && (typeof executablePath !== "string" || executablePath.length === 0)) {
+        throw new GifExportError("options", "executablePath must identify an installed Chromium executable.");
+    }
+    if (externalBrowser !== undefined && executablePath !== undefined)
+        throw new GifExportError("options", "Choose browser or executablePath, not both.");
+    throwIfCancelled(signal);
+    let duration;
+    try {
+        duration = createDiagram(snapshot).totalDuration;
+    }
+    catch (cause) {
+        throw new GifExportError("document", "Invalid diagram document. Correct validation issues before exporting.", { cause });
+    }
+    planGif(snapshot, duration, fixedOptions);
+    const job = new BrowserExportJob(signal, onProgress);
+    try {
+        return await job.run(snapshot, fixedOptions, externalBrowser, executablePath);
+    }
+    finally {
+        await job.dispose();
+    }
+}
+/** Own one export page/context, optional launched browser and temporary directory. Abort also interrupts launch. */
+class BrowserExportJob {
+    signal;
+    onProgress;
+    browser;
+    context;
+    page;
+    directory;
+    ownedBrowser = false;
+    contextClosing;
+    callbackError;
+    callbackFailed = false;
+    rejectAbort;
+    cancellation;
+    abort = () => {
+        this.rejectAbort?.(cancelledError());
+        // Closing the isolated context interrupts font/raster/worker work even if the page cannot evaluate abort.
+        // dispose() awaits this same promise and reports cleanup failures after releasing other resources.
+        void this.closeContext().catch(() => undefined);
+    };
+    constructor(signal, onProgress) {
+        this.signal = signal;
+        this.onProgress = onProgress;
+        this.cancellation = new Promise((_, reject) => { this.rejectAbort = reject; });
+        // A cancellation can arrive during a file read, before launch starts observing this promise.
+        void this.cancellation.catch(() => undefined);
+        this.signal?.addEventListener("abort", this.abort, { once: true });
+    }
+    async run(document, options, externalBrowser, executablePath) {
+        try {
+            return await this.execute(document, options, externalBrowser, executablePath);
+        }
+        catch (error) {
+            if (this.callbackFailed)
+                throw new GifExportError("encoding", "GIF progress callback failed. Correct the callback and retry.", { cause: this.callbackError });
+            throwIfCancelled(this.signal);
+            if (error instanceof GifExportError)
+                throw error;
+            throw new GifExportError("environment", "Cannot run Chromium GIF export. Prepare Chromium with npx --no-install playwright-core install chromium (and --with-deps on supported Linux), or set executablePath to an installed Chromium executable.", { cause: error });
+        }
+    }
+    async execute(document, options, externalBrowser, executablePath) {
+        const script = await readFile(new URL("../portable/export.js", import.meta.url), "utf8");
+        throwIfCancelled(this.signal);
+        this.browser = externalBrowser ?? await this.launch(executablePath);
+        this.ownedBrowser = externalBrowser === undefined;
+        throwIfCancelled(this.signal);
+        this.context = await this.browser.newContext({ offline: true });
+        throwIfCancelled(this.signal);
+        this.page = await this.context.newPage();
+        await this.page.exposeFunction("flowSvgProgress", (progress) => {
+            if (this.signal?.aborted)
+                return;
+            try {
+                this.onProgress?.(progress);
+            }
+            catch (error) {
+                this.callbackFailed = true;
+                this.callbackError = error;
+                this.abort();
+            }
+        });
+        this.directory = await mkdtemp(join(tmpdir(), "flowsvg-gif-"));
+        const html = join(this.directory, "export.html");
+        await writeFile(html, `<meta charset="utf-8"><script>${script}</script>`);
+        throwIfCancelled(this.signal);
+        await this.page.goto(pathToFileURL(html).href);
+        const result = await this.page.evaluate(async ({ document, options }) => {
+            const bridge = globalThis;
+            const controller = new AbortController();
+            const progressPending = [];
+            try {
+                const bytes = await bridge.FlowSVGExport.exportGif(document, {
+                    ...options, signal: controller.signal,
+                    onProgress: (progress) => { progressPending.push(bridge.flowSvgProgress(progress)); }
+                });
+                await Promise.all(progressPending);
+                return { bytes: Array.from(bytes) };
+            }
+            catch (error) {
+                const failure = error;
+                return { error: { code: failure.code ?? "encoding", message: failure.message ?? "Browser GIF export failed." } };
+            }
+        }, { document, options });
+        throwIfCancelled(this.signal);
+        if ("error" in result)
+            throw new GifExportError(result.error.code, result.error.message);
+        return Uint8Array.from(result.bytes);
+    }
+    async launch(executablePath) {
+        let automation;
+        try {
+            automation = await import("playwright-core");
+        }
+        catch (error) {
+            throw new GifExportError("environment", "GIF export requires playwright-core. Reinstall flowsvg with its runtime dependencies, then prepare Chromium explicitly.", { cause: error });
+        }
+        throwIfCancelled(this.signal);
+        // The host/CLI owns process signals; Playwright defaults can otherwise exit before our cleanup.
+        const launched = automation.chromium.launch({ executablePath, handleSIGINT: false, handleSIGTERM: false, handleSIGHUP: false }).then(async (browser) => {
+            // A cancelled launch can settle after run() returned; close that late process.
+            if (this.signal?.aborted) {
+                await browser.close();
+                throw cancelledError();
+            }
+            return browser;
+        });
+        return await Promise.race([launched, this.cancellation]);
+    }
+    closeContext() {
+        if (this.context)
+            this.contextClosing ??= this.context.close();
+        return this.contextClosing ?? Promise.resolve();
+    }
+    async dispose() {
+        this.signal?.removeEventListener("abort", this.abort);
+        try {
+            await this.closeContext();
+        }
+        finally {
+            try {
+                if (this.ownedBrowser)
+                    await this.browser?.close();
+            }
+            finally {
+                if (this.directory)
+                    await rm(this.directory, { recursive: true, force: true });
+            }
+        }
+    }
+}
+function cancelledError() { return new GifExportError("cancelled", "GIF export was cancelled. Start a new export when ready."); }
+function throwIfCancelled(signal) { if (signal?.aborted)
+    throw cancelledError(); }
+function snapshotInput(value, code) {
+    try {
+        return structuredClone(value);
+    }
+    catch (cause) {
+        throw new GifExportError(code, `GIF ${code} must contain serializable values. Remove functions or other unsupported values and retry.`, { cause });
+    }
+}

package/dist/node/html.d.ts

@@ -0,0 +1,19 @@
+import type { DiagramDocument, ThemeName } from "../core/model.js";
+/** Offline playback options. Default to document/light theme, paused at zero, with controls and caption. */
+export interface HtmlRenderOptions {
+    theme?: ThemeName;
+    autoplay?: boolean;
+    /** Defaults to false. Loop live playback; GIF loopCount remains an independent export option. */
+    loop?: boolean;
+    controls?: boolean;
+    /** Embed offline GIF export assets and show GIF controls when controls are visible. Defaults to false. */
+    gifExport?: boolean;
+}
+/**
+ * Return one offline HTML file containing validated data, the player, CSS and optional GIF assets. Requires Node 20+.
+ * Text remains data, including HTML delimiters and Unicode separators. No browser is required.
+ * @throws For invalid documents/options, an unsupported Node runtime, or missing built assets.
+ */
+export declare function renderHtml(document: DiagramDocument, options?: HtmlRenderOptions): Promise<string>;
+/** Fail before reading files or allocating browser resources on the Node-only path. */
+export declare function assertNodeRuntime(): void;

package/dist/node/html.js

@@ -0,0 +1,61 @@
+/** Node-only HTML assembly. Read versioned built assets; never start a browser or import automation/encoding dependencies. */
+import { readFile } from "node:fs/promises";
+import { createDiagram } from "../core/diagram.js";
+import { DIAGRAM_FONT_FAMILY, resolveThemePalette } from "../core/theme.js";
+/**
+ * Return one offline HTML file containing validated data, the player, CSS and optional GIF assets. Requires Node 20+.
+ * Text remains data, including HTML delimiters and Unicode separators. No browser is required.
+ * @throws For invalid documents/options, an unsupported Node runtime, or missing built assets.
+ */
+export async function renderHtml(document, options = {}) {
+    assertNodeRuntime();
+    const snapshot = structuredClone(document);
+    const playbackOptions = structuredClone(options);
+    createDiagram(snapshot);
+    validateOptions(playbackOptions);
+    const [script, styles, exporter] = await Promise.all([
+        readFile(new URL("../portable/player.js", import.meta.url), "utf8"),
+        readFile(new URL("../portable/styles.css", import.meta.url), "utf8"),
+        playbackOptions.gifExport ? readFile(new URL("../portable/export.js", import.meta.url), "utf8") : ""
+    ]);
+    const data = escapeJson({ document: snapshot, options: playbackOptions });
+    const title = escapeHtml(snapshot.title ?? "FlowSVG");
+    const palette = resolveThemePalette(playbackOptions.theme ?? snapshot.theme);
+    const pageStyles = `body{margin:0;background:${palette.background};color:${palette.text};font-family:${DIAGRAM_FONT_FAMILY}}
+#flowsvg-player{max-width:1280px;margin:auto}.flowsvg-canvas svg{display:block;width:100%}
+.flowsvg-caption{padding:0 16px;white-space:pre-wrap}
+.flowsvg-controls{--flowsvg-control-background:${palette.background};--flowsvg-control-color:${palette.text}}`;
+    return `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
+<title>${title}</title><style>${styles}\n${pageStyles}</style></head>
+<body><main id="flowsvg-player"></main>
+<script id="flowsvg-data" type="application/json">${data}</script>
+${exporter ? `<script>${exporter}</script>\n` : ""}<script>${script}</script></body></html>`;
+}
+/** Fail before reading files or allocating browser resources on the Node-only path. */
+export function assertNodeRuntime() {
+    const MIN_NODE_MAJOR = 20;
+    if (Number(process.versions.node.split(".")[0]) < MIN_NODE_MAJOR) {
+        throw new Error("FlowSVG Node tools require Node 20 or newer. Upgrade Node and retry.");
+    }
+}
+function validateOptions(options) {
+    if (options.theme !== undefined && options.theme !== "light" && options.theme !== "dark") {
+        throw new Error("HTML theme must be light or dark.");
+    }
+    for (const key of ["autoplay", "controls", "gifExport", "loop"]) {
+        if (options[key] !== undefined && typeof options[key] !== "boolean") {
+            throw new Error(`HTML ${key} must be a boolean.`);
+        }
+    }
+}
+function escapeJson(value) {
+    const ESCAPES = {
+        "<": "\\u003c", ">": "\\u003e", "&": "\\u0026", "\u2028": "\\u2028", "\u2029": "\\u2029"
+    };
+    return JSON.stringify(value).replace(/[<>&\u2028\u2029]/g, (character) => ESCAPES[character]);
+}
+function escapeHtml(value) {
+    const ESCAPES = { "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" };
+    return value.replace(/[&<>"']/g, (character) => ESCAPES[character]);
+}

package/dist/node/output.d.ts

@@ -0,0 +1,2 @@
+/** Atomically publish complete bytes or text. Only explicit overwrite replaces an existing output. */
+export declare function publishOutput(destination: string, content: string | Uint8Array, overwrite: boolean, signal: AbortSignal): Promise<void>;

package/dist/node/output.js

@@ -0,0 +1,22 @@
+/** Publish complete CLI output on the destination filesystem; exclusive linking protects concurrent writers. */
+import { randomUUID } from "node:crypto";
+import { link, rename, unlink, writeFile } from "node:fs/promises";
+/** Atomically publish complete bytes or text. Only explicit overwrite replaces an existing output. */
+export async function publishOutput(destination, content, overwrite, signal) {
+    signal.throwIfAborted();
+    const temporaryPath = `${destination}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temporaryPath, content, { flag: "wx", signal });
+        signal.throwIfAborted();
+        if (overwrite)
+            await rename(temporaryPath, destination);
+        else
+            await link(temporaryPath, destination);
+    }
+    finally {
+        await unlink(temporaryPath).catch((error) => {
+            if (!(error instanceof Error && "code" in error && error.code === "ENOENT"))
+                throw error;
+        });
+    }
+}

package/dist/node.d.ts

@@ -0,0 +1,6 @@
+export { renderHtml } from "./node/html.js";
+export type { HtmlRenderOptions } from "./node/html.js";
+export { exportGif } from "./node/gif.js";
+export type { NodeGifExportOptions } from "./node/gif.js";
+export { GifExportError } from "./export/types.js";
+export type { GifExportOptions, GifExportProgress, GifExportErrorCode } from "./export/types.js";

package/dist/node.js

@@ -0,0 +1,3 @@
+export { renderHtml } from "./node/html.js";
+export { exportGif } from "./node/gif.js";
+export { GifExportError } from "./export/types.js";

package/dist/portable/LICENSE.esbuild.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 Evan Wallace
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/portable/LICENSE.flowsvg.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zac_ma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/portable/LICENSE.gifenc.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+Copyright (c) 2017 Matt DesLauriers
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR
+OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE
+OR OTHER DEALINGS IN THE SOFTWARE.
+