edododraw 0.1.3 → 0.1.4

package/dist-lib/engine/dsl/compile.d.ts

@@ -8,6 +8,12 @@ import type { AnnotationCmd, Program, Value } from "./ast.js";
 import { DiagnosticBag } from "./diagnostics.js";
 export interface CompileOptions {
     diagnostics?: DiagnosticBag;
+    /**
+     * Force the render mode, overriding the mode derived from the active theme
+     * name. Used by the app/embedder's light/dark toggle so any diagram can be
+     * viewed dark without editing its source. `undefined` = derive from the DSL.
+     */
+    mode?: "light" | "dark";
 }
 export interface CompileResult {
     scene: Scene;

package/dist-lib/engine/dsl/compile.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../../src/engine/dsl/compile.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,OAAO,KAAK,EACV,UAAU,EAOV,KAAK,EAGN,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EACV,aAAa,EAOb,OAAO,EAEP,KAAK,EACN,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAgBjD,MAAM,WAAW,cAAc;IAC7B,WAAW,CAAC,EAAE,aAAa,CAAC;CAC7B;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,KAAK,CAAC;IACb,WAAW,EAAE,aAAa,CAAC;CAC5B;AAUD,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,GAAE,cAAmB,GAAG,aAAa,CA6RzF;AA0UD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,QAAQ,GAAG,MAAM,GAAG,UAAU,GAAG,IAAI,CA0B9H"}
+{"version":3,"file":"compile.d.ts","sourceRoot":"","sources":["../../../src/engine/dsl/compile.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,OAAO,KAAK,EACV,UAAU,EAOV,KAAK,EAGN,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EACV,aAAa,EAOb,OAAO,EAEP,KAAK,EACN,MAAM,UAAU,CAAC;AAElB,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAgBjD,MAAM,WAAW,cAAc;IAC7B,WAAW,CAAC,EAAE,aAAa,CAAC;IAC5B;;;;OAIG;IACH,IAAI,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,KAAK,CAAC;IACb,WAAW,EAAE,aAAa,CAAC;CAC5B;AAUD,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,GAAE,cAAmB,GAAG,aAAa,CA+RzF;AAoWD,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,aAAa,EAAE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,EAAE,QAAQ,GAAG,MAAM,GAAG,UAAU,GAAG,IAAI,CA0B9H"}

package/dist-lib/engine/dsl/index.d.ts

@@ -10,7 +10,11 @@ export interface CompileEddResult {
     /** Formatted, human-readable diagnostics (one block each). */
     report: string[];
 }
-export declare function compileEdd(source: string): CompileEddResult;
+export interface CompileEddOptions {
+    /** Force light/dark render mode, overriding the DSL's declared theme. */
+    mode?: "light" | "dark";
+}
+export declare function compileEdd(source: string, opts?: CompileEddOptions): CompileEddResult;
 export { parse } from "./parser.js";
 export { compileProgram } from "./compile.js";
 export { lex } from "./lexer.js";

package/dist-lib/engine/dsl/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/engine/dsl/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,aAAa,EAAoB,MAAM,kBAAkB,CAAC;AAEnE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE/C,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,KAAK,CAAC;IACb,WAAW,EAAE,aAAa,CAAC;IAC3B,8DAA8D;IAC9D,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,CAK3D;AAED,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AACjC,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACnE,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/engine/dsl/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,aAAa,EAAoB,MAAM,kBAAkB,CAAC;AAEnE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE/C,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,KAAK,CAAC;IACb,WAAW,EAAE,aAAa,CAAC;IAC3B,8DAA8D;IAC9D,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC,yEAAyE;IACzE,IAAI,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;CACzB;AAED,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,GAAE,iBAAsB,GAAG,gBAAgB,CAKzF;AAED,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AACpC,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9C,OAAO,EAAE,GAAG,EAAE,MAAM,YAAY,CAAC;AACjC,OAAO,EAAE,aAAa,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACnE,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC"}

package/dist-lib/engine/render/svgRenderer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"svgRenderer.d.ts","sourceRoot":"","sources":["../../../src/engine/render/svgRenderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,KAAK,EAAE,KAAK,EAAa,MAAM,mBAAmB,CAAC;AAe1D,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;CACd;AAED,qBAAa,WAAW;IACtB,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC;IAChC,GAAG,EAAG,aAAa,CAAC;IACpB,OAAO,CAAC,IAAI,CAAkB;IAC9B,OAAO,CAAC,EAAE,CAAkB;IAC5B,KAAK,EAAG,WAAW,CAAC;IACpB,OAAO,CAAC,MAAM,CAA+B;IAC7C,WAAW,EAAG,WAAW,CAAC;IAC1B,OAAO,CAAC,EAAE,CAAqC;IAE/C,OAAO,CAAC,MAAM,CAA8C;IAC5D,OAAO,CAAC,QAAQ,CAAsB;IACtC,OAAO,CAAC,KAAK,CAAsB;gBAEvB,SAAS,EAAE,WAAW;IAIlC,KAAK,IAAI,IAAI;IAkDb,OAAO,IAAI,IAAI;IAIf,OAAO,CAAC,UAAU;IAelB,uDAAuD;IACvD,OAAO,IAAI;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE;IAMnC,eAAe,IAAI;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE;IAI3C,SAAS,IAAI,eAAe;IAI5B,WAAW,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI;IAOvC,aAAa,CAAC,CAAC,EAAE,KAAK,GAAG,KAAK;IAQ9B,aAAa,CAAC,CAAC,EAAE,KAAK,GAAG,KAAK;IAQ9B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,aAAa,GAAG,MAAM,GAAG,WAAW;IAI3F,6EAA6E;IAC7E,eAAe,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI;IAS1C;;;;OAIG;IACH,UAAU,CAAC,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,GAAG,IAAI;IAcxD,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAsC1B,OAAO,CAAC,UAAU;IAmBlB,OAAO,CAAC,SAAS;IA+BjB,OAAO,CAAC,SAAS;IAuBjB,OAAO,CAAC,gBAAgB;CA6BzB"}
+{"version":3,"file":"svgRenderer.d.ts","sourceRoot":"","sources":["../../../src/engine/render/svgRenderer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,KAAK,EAAE,KAAK,EAAa,MAAM,mBAAmB,CAAC;AAe1D,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;CACd;AAED,qBAAa,WAAW;IACtB,QAAQ,CAAC,SAAS,EAAE,WAAW,CAAC;IAChC,GAAG,EAAG,aAAa,CAAC;IACpB,OAAO,CAAC,IAAI,CAAkB;IAC9B,OAAO,CAAC,EAAE,CAAkB;IAC5B,KAAK,EAAG,WAAW,CAAC;IACpB,OAAO,CAAC,MAAM,CAA+B;IAC7C,WAAW,EAAG,WAAW,CAAC;IAC1B,OAAO,CAAC,EAAE,CAAqC;IAE/C,OAAO,CAAC,MAAM,CAA8C;IAC5D,OAAO,CAAC,QAAQ,CAAsB;IACtC,OAAO,CAAC,KAAK,CAAsB;gBAEvB,SAAS,EAAE,WAAW;IAIlC,KAAK,IAAI,IAAI;IAkDb,OAAO,IAAI,IAAI;IAIf,OAAO,CAAC,UAAU;IAelB,uDAAuD;IACvD,OAAO,IAAI;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE;IAMnC,eAAe,IAAI;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE;IAI3C,SAAS,IAAI,eAAe;IAI5B,WAAW,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI;IAOvC,aAAa,CAAC,CAAC,EAAE,KAAK,GAAG,KAAK;IAQ9B,aAAa,CAAC,CAAC,EAAE,KAAK,GAAG,KAAK;IAQ9B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,GAAG,OAAO,GAAG,aAAa,GAAG,MAAM,GAAG,WAAW;IAI3F,6EAA6E;IAC7E,eAAe,CAAC,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,IAAI;IAS1C;;;;OAIG;IACH,UAAU,CAAC,EAAE,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,GAAG,IAAI;IAcxD,MAAM,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IA6C1B,OAAO,CAAC,UAAU;IAmBlB,OAAO,CAAC,SAAS;IA+BjB,OAAO,CAAC,SAAS;IAuBjB,OAAO,CAAC,gBAAgB;CA6BzB"}

package/dist-lib/engine/scene/palette.d.ts

@@ -42,6 +42,14 @@ export declare const FILL_PALETTE: {
     readonly white: "#ffffff";
 };
 export type ColorName = keyof typeof STROKE_PALETTE;
+/**
+ * Perceived-luminance test for a color, used to pick a contrasting "ink"
+ * (stroke/text) in dark mode: a light fill wants dark ink, a dark (or absent)
+ * fill wants light ink. Only hex is measured precisely; named/rgb() colors —
+ * which in this engine are almost always the light Open-Colors pastels — default
+ * to "light" so their ink stays dark and readable.
+ */
+export declare function isLightColor(color: string | null | undefined): boolean;
 /**
  * Resolve a color token to a hex string.
  * - Named strokes: "green" -> #2f9e44

package/dist-lib/engine/scene/palette.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"palette.d.ts","sourceRoot":"","sources":["../../../src/engine/scene/palette.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;CAgBjB,CAAC;AAEX,uEAAuE;AACvE,eAAO,MAAM,YAAY;0BACF,MAAM,GAAG,IAAI;mBACpB,MAAM,GAAG,IAAI;;;;;;;;;;;;;;;;CAgBnB,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,MAAM,OAAO,cAAc,CAAC;AAEpD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAQjF;AAED,oFAAoF;AACpF,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAOpE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAKhF;AAED,oEAAoE;AACpE,eAAO,MAAM,cAAc;;;;;;;;CAQjB,CAAC;AAEX,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,YAAwB,GAAG,MAAM,CAMjG"}
+{"version":3,"file":"palette.d.ts","sourceRoot":"","sources":["../../../src/engine/scene/palette.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;CAgBjB,CAAC;AAEX,uEAAuE;AACvE,eAAO,MAAM,YAAY;0BACF,MAAM,GAAG,IAAI;mBACpB,MAAM,GAAG,IAAI;;;;;;;;;;;;;;;;CAgBnB,CAAC;AAEX,MAAM,MAAM,SAAS,GAAG,MAAM,OAAO,cAAc,CAAC;AAEpD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,OAAO,CAWtE;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAQjF;AAED,oFAAoF;AACpF,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAOpE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAKhF;AAED,oEAAoE;AACpE,eAAO,MAAM,cAAc;;;;;;;;CAQjB,CAAC;AAEX,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,QAAQ,YAAwB,GAAG,MAAM,CAMjG"}

package/dist-lib/index.js

@@ -1,4 +1,4 @@
-import { A, C, D, a, E, b, c, F, d, L, e, M, S, f, T, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v, w, x, y, z, B, G, H, I, J, K, N, O, P, Q, R, U, V, W, X, Y, Z, _, $, a0, a1, a2, a3, a4, a5, a6, a7, a8, a9, aa, ab, ac, ad, ae, af, ag, ah, ai, aj, ak, al, am, an, ao, ap } from "./chunks/EdodoDraw-BCfKu4Q3.js";
+import { A, C, D, a, E, b, c, F, d, L, e, M, S, f, T, g, h, i, j, k, l, m, n, o, p, q, r, s, t, u, v, w, x, y, z, B, G, H, I, J, K, N, O, P, Q, R, U, V, W, X, Y, Z, _, $, a0, a1, a2, a3, a4, a5, a6, a7, a8, a9, aa, ab, ac, ad, ae, af, ag, ah, ai, aj, ak, al, am, an, ao, ap, aq } from "./chunks/EdodoDraw-BdJowisU.js";
 export {
   A as AnnotationLayer,
   C as CameraController,
@@ -60,25 +60,26 @@ export {
   a3 as hitTestNode,
   a4 as injectMermaid,
   a5 as isEmptyBBox,
-  a6 as lerp,
-  a7 as listShapePlugins,
-  a8 as makeEdge,
-  a9 as makeNode,
-  aa as nodeBBox,
-  ab as nodeRect,
-  ac as nodeRectOf,
-  ad as pairedStrokeForFill,
-  ae as pointInRect,
-  af as rectCenter,
-  ag as rectToBBox,
-  ah as registerShape,
-  ai as renameNode,
-  aj as resolveAnchor,
-  ak as resolveFill,
-  al as resolveMarker,
-  am as resolveStroke,
-  an as sceneBBox,
-  ao as styleNode,
-  ap as writeOverrides
+  a6 as isLightColor,
+  a7 as lerp,
+  a8 as listShapePlugins,
+  a9 as makeEdge,
+  aa as makeNode,
+  ab as nodeBBox,
+  ac as nodeRect,
+  ad as nodeRectOf,
+  ae as pairedStrokeForFill,
+  af as pointInRect,
+  ag as rectCenter,
+  ah as rectToBBox,
+  ai as registerShape,
+  aj as renameNode,
+  ak as resolveAnchor,
+  al as resolveFill,
+  am as resolveMarker,
+  an as resolveStroke,
+  ao as sceneBBox,
+  ap as styleNode,
+  aq as writeOverrides
 };
 //# sourceMappingURL=index.js.map

package/dist-lib/lib/EdodoDraw.d.ts

@@ -49,6 +49,8 @@ export declare class EdodoDraw {
     private listeners;
     private textInput;
     private closeInput;
+    private colorScheme;
+    private hasRendered;
     private cleanup;
     constructor(container: HTMLElement, options?: EdodoDrawOptions);
     private onCameraFrame;
@@ -70,6 +72,15 @@ export declare class EdodoDraw {
     render(source: string): Promise<RenderResult>;
     getScene(): Scene;
     getSource(): string;
+    /**
+     * Force light/dark rendering, overriding the diagram's declared theme. Affects
+     * the canvas background, the dotted grid, and the diagram's default ink
+     * (strokes/text adapt for contrast on the dark canvas; explicit colors are
+     * kept). Pass `null` to fall back to the DSL's own theme. Re-renders the
+     * current source. Cheap and idempotent — no-ops if the scheme is unchanged.
+     */
+    setColorScheme(mode: "light" | "dark" | null): void;
+    getColorScheme(): "light" | "dark" | null;
     fit(animate?: boolean): void;
     focus(ids: string[], opts?: {
         zoom?: number;

package/dist-lib/lib/EdodoDraw.d.ts.map

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

package/dist-lib/lib/react.d.ts

@@ -14,12 +14,17 @@ export interface EdodoDrawViewProps extends EdodoDrawOptions {
     source: string;
     className?: string;
     style?: CSSProperties;
+    /**
+     * Force light/dark rendering, overriding the diagram's declared theme.
+     * `null`/omitted follows the DSL's own theme. See `EdodoDraw.setColorScheme`.
+     */
+    colorScheme?: "light" | "dark" | null;
     /** Called once with the imperative instance after mount. */
     onReady?: (edd: EdodoDraw) => void;
     onDiagnostics?: (diags: Diagnostic[]) => void;
     onState?: (state: PlayerState) => void;
 }
-export declare function EdodoDrawView({ source, className, style, onReady, onDiagnostics, onState, ...opts }: EdodoDrawViewProps): import("react").JSX.Element;
+export declare function EdodoDrawView({ source, className, style, colorScheme, onReady, onDiagnostics, onState, ...opts }: EdodoDrawViewProps): import("react").JSX.Element;
 export { EdodoDraw } from "./EdodoDraw.js";
 export type { EdodoDrawOptions } from "./EdodoDraw.js";
 //# sourceMappingURL=react.d.ts.map

package/dist-lib/lib/react.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../../src/lib/react.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAEhE,MAAM,WAAW,kBAAmB,SAAQ,gBAAgB;IAC1D,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,4DAA4D;IAC5D,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,SAAS,KAAK,IAAI,CAAC;IACnC,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,IAAI,CAAC;IAC9C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;CACxC;AAED,wBAAgB,aAAa,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,kBAAkB,+BAwBvH;AAED,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"react.d.ts","sourceRoot":"","sources":["../../src/lib/react.tsx"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,OAAO,CAAC;AAC3C,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,8BAA8B,CAAC;AAEhE,MAAM,WAAW,kBAAmB,SAAQ,gBAAgB;IAC1D,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB;;;OAGG;IACH,WAAW,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAAC;IACtC,4DAA4D;IAC5D,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,SAAS,KAAK,IAAI,CAAC;IACnC,aAAa,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,KAAK,IAAI,CAAC;IAC9C,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,WAAW,KAAK,IAAI,CAAC;CACxC;AAED,wBAAgB,aAAa,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,EAAE,kBAAkB,+BA8BpI;AAED,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,YAAY,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist-lib/llms-full.txt

@@ -1,4 +1,4 @@
-# EDodoDraw — complete documentation (v0.1.2)
+# EDodoDraw — complete documentation (v0.1.4)
 
 > A 100% code/syntax-to-diagram engine with the Excalidraw hand-drawn aesthetic, magic-move camera, scriptable + real-time annotations, animated arrows, and first-class Mermaid import.
 >
@@ -76,6 +76,8 @@ Everything else is optional layering on top.
 | `overrides { id at (x, y) [size (w, h)] … }` | Pinned positions/sizes (usually machine-written by direct editing — see §11). |
 | `mermaid """ … """` | Import a raw Mermaid diagram (see IMPORT_AND_EXPORT_GUIDE.md). |
 
+A theme whose **name contains `dark`** renders in dark mode (near‑black canvas, light default ink, dark grid). An embedder can override the diagram's declared theme at the view level — `EdodoDraw.setColorScheme("dark")`, `<EdodoDrawView colorScheme>`, or `compileEdd(src, { mode })` — so the same source follows a host app's light/dark toggle (see INTEGRATION_GUIDE.md). Colors you set explicitly are always kept; only *default* ink adapts for contrast.
+
 Comments: `// line`, `%% line` (Mermaid-style), `/* block */` (nestable).
 
 ---
@@ -310,16 +312,32 @@ timeline story {
 | Pan | `camera pan (x, y)` | `camera { pan: (x,y) }` |
 | Reset | `camera reset` | — |
 
-Shared modifiers: `zoom N` · `over <ms|s>` · `ease <easing>` · `pad N`.
-Easings: `linear ease ease-in ease-out ease-in-out back-out anticipate spring` — plus `magic` (an alias for the tuned spring). `spring(…)` is accepted and animates with the tuned spring; `cubic-bezier(…)` is accepted syntax but currently falls back to the default `ease-in-out` (parameters for both are reserved for a future release).
+Shared modifiers: `zoom N` · `over <ms|s>` (alias `duration`) · `ease <easing>` · `pad N`. Op aliases: `fit <target>` / `center <target>` / `follow <target>` all normalize to `focus`; `reset` → `fit-all`. `pan (x,y)` also accepts `pan to (x,y)` / `pan by (x,y)`.
+Easings: `linear ease ease-in ease-out ease-in-out back-out anticipate spring` — plus `magic` / `bounce` (aliases for the tuned spring). `spring(…)` is accepted and animates with the tuned spring; `cubic-bezier(…)` is accepted syntax but currently falls back to the default `ease-in-out` (parameters for both are reserved for a future release).
+An **explicit `zoom N` is applied uncapped** (a beat can zoom past the interactive limits); wheel/gesture zoom is clamped to 0.05–8×. Numeric contracts (fit padding/maxZoom, auto-duration) are in [CAMERA_AND_TIMELINE_GUIDE.md](CAMERA_AND_TIMELINE_GUIDE.md).
+
+### Reveal / hide (with entrance effects)
+
+`reveal { show <targets> }` reveals nodes/edges; `reveal { hide <targets> }` hides them. Visibility is **sticky** across beats until changed. Add an entrance animation with `with <effect>`, replayed each time the beat is entered:
+
+| Effect | `with …` | Also as a verb | Motion |
+|---|---|---|---|
+| Fade | `with fade-in` (alias `fade`) | `fade-in <t>` | opacity 0→1 (~0.4s) |
+| Pop | `with pop` (alias `emphasize`) | `pop <t>` | scale-bounce in (~0.45s) |
+| Draw-on | `with draw-on` (aliases `draw`, `sweep`) | `draw-on <t>` | left-to-right marker sweep (~0.5s) |
 
-### Reveal / hide
+```edd
+reveal { show all with fade-in }     // whole diagram fades in
+reveal { show [db, cache] with pop } // pop just these two
+reveal { draw-on [gw] }              // effect-verb form
+reveal { show legacy }               // no `with` -> instant (no animation)
+```
 
-`reveal { show all }`, `reveal { hide legacy }`, `reveal { show .critical with pop }`. Visibility is **sticky** across beats until changed. Beat annotations are cleared at the start of each beat (unless in the always-on `annotate` block).
+A plain `show`/`hide` with no effect is instant. Effects honor `prefers-reduced-motion`. Beat annotations are cleared at the start of each beat (unless in the always-on `annotate` block).
 
-### Beat properties
+### Beat & timeline properties
 
-`narrate: "caption"` (speaker note shown under the diagram), `hold: 2s` (dwell before auto-advance during Play).
+`narrate: "caption"` (speaker note shown under the diagram), `hold: 2s` (dwell before auto-advance during Play; alias `wait:`). At the `timeline { … }` level, `defaultEase: <easing>` sets the fallback easing for every beat that doesn't specify its own `ease`.
 
 ---
 
@@ -387,14 +405,29 @@ translate(vw/2, vh/2) · scale(zoom) · translate(-cx, -cy)
 
 ```ts
 const controller = new CameraController(renderer);
-await controller.fitAll(scene, { padding: 80 });
+await controller.fitAll(scene, { padding: 80 });           // frame everything
 await controller.focus(scene, ["db", "cache"], { zoom: 1.7, easing: "spring" });
-controller.zoomBy(1.2, screenPoint);   // wheel zoom around cursor
+await controller.focusBBox({ minX, minY, maxX, maxY }, { zoom: 2 }); // frame an arbitrary world box
+controller.zoomBy(1.2, screenPoint);   // wheel zoom around cursor (relative)
 controller.panByScreen(dx, dy);         // drag pan
 ```
 
 Mid-flight `animateTo` retargets smoothly from the current interpolated state — no snap.
 
+### Numeric contracts
+
+The behaviors an author or embedder can rely on (all from `controller.ts` / `fit.ts`):
+
+| Contract | Value |
+|---|---|
+| Zoom = scale factor | `1.0` = 100% (1 world unit = 1 screen px); `zoom: 1.7` = 170%. |
+| Wheel / `zoomBy` clamp | **0.05–8×** (5%–800%). |
+| Fit clamp | `fitAll`/`focusBBox` cap at **2.5×**; `focus`'s *computed* framing caps at **4×**. |
+| Explicit `zoom` | **Bypasses all clamps** — a passed `zoom` (DSL `camera … zoom N`, or `focus(..,{zoom})`) is applied as-is, so a beat can exceed the interactive limits. |
+| Auto-duration | When `over`/`durationMs` is omitted: `clamp(420 + dist·0.12 + |ln(zoomTo/zoomFrom)|·320, 420, 1300)` ms. |
+| Padding defaults | `fitAll` 80px, `focus`/`focusBBox` 90px, bare `cameraForBBox` 64px. |
+| Default easing | Compiled DSL beats default to **`ease-in-out`** (via `mapEasing`); a raw programmatic `animateTo` with no `easing` defaults to **`spring`**. |
+
 ## Interaction (built into the canvas)
 
 - **Wheel** → zoom around the cursor.
@@ -409,9 +442,10 @@ Mid-flight `animateTo` retargets smoothly from the current interpolated state
 |---|---|
 | Camera | **Sticky** — a beat with no `camera` keeps the current one. |
 | Visibility (`show`/`hide`) | **Sticky** until changed. |
+| Reveal effect (`with fade-in`/`pop`/`draw-on`) | **Beat-scoped** — replayed each time the beat is entered (only when animating). |
 | Annotations | **Beat-scoped** — replaced each beat (always-on `annotate` block persists underneath). |
 
-API: `player.load(scene)`, `play()`, `pause()`, `next()`, `prev()`, `restart()`, `goto(i)`. It emits `PlayerState { index, total, caption, stepName, playing }` for the UI. Auto-advance uses each beat's `hold:` (default 3.2s).
+API: `player.load(scene)`, `play()`, `pause()`, `next()`, `prev()`, `restart()`, `goto(i)`. It emits `PlayerState { index, total, caption, stepName, playing }` for the UI. **`index === -1`** is the home/overview state (before any beat; `stepName` is `"Overview"`) — `prev()` from beat 0 returns there and re-fits. Auto-advance uses each beat's `hold:` (default 3.2s).
 
 ```edd
 timeline story {
@@ -637,6 +671,10 @@ new EdodoDraw(container: HTMLElement, options?: EdodoDrawOptions)
 | `render` | `(source: string) => Promise<RenderResult>` | Compile + render. `RenderResult = { scene: Scene; diagnostics: Diagnostic[] }`. |
 | `getScene` | `() => Scene` | The current rendered scene (Scene IR). |
 | `getSource` | `() => string` | The last source string passed to `render`. |
+| `setColorScheme` | `(mode: "light" \| "dark" \| null) => void` | Force light/dark rendering, overriding the diagram's declared theme. Re-themes the canvas background, the dotted grid, and the diagram's default ink (strokes/text adapt for contrast on the dark canvas; **explicit** colors are kept). `null` falls back to the DSL's own theme. Idempotent + re-renders the current source. |
+| `getColorScheme` | `() => "light" \| "dark" \| null` | The current forced scheme (`null` = follow the DSL). |
+
+**Light / dark theming.** A diagram's theme comes from the DSL (`theme dark { … }` / `use theme …`); `setColorScheme` / the `colorScheme` prop *override* it for the view, so you can wire EDodoDraw straight to your app's theme toggle. In dark mode the canvas goes near‑black, the dotted grid follows `theme.gridColor`, and **default** ink flips to light for contrast — but any color **you** set (`fill: green`, `stroke: red`, `textColor:`) is preserved. One nuance: because the default fill style is hand‑drawn *hachure* (the dark canvas shows through), labels on unfilled and hachure‑filled nodes use light ink; only a **solid** light fill (`fillStyle: solid`) keeps dark ink. Forcing a scheme also re‑themes exports (`downloadSVG`/`PNG`) — you export what you see.
 
 ### Camera
 
@@ -723,7 +761,7 @@ event — see below), keeping the code the single source of truth:
 |---|---|---|
 | `"render"` | `RenderResult` `{ scene, diagnostics }` | After each successful `render()`. |
 | `"diagnostics"` | `Diagnostic[]` | After each `render()`, with compile diagnostics. |
-| `"state"` | `PlayerState` `{ index, total, caption, playing, stepName }` | Timeline position/playing changes. |
+| `"state"` | `PlayerState` `{ index, total, caption, playing, stepName }` | Timeline position/playing changes. `index === -1` is the home/overview state (before any beat; `stepName` is `"Overview"`). |
 | `"live"` | `LiveState` `{ tool, count, canUndo, canRedo, selected }` | Live-annotation tool/selection/undo state changes. |
 | `"edit"` | `source: string` | A direct-manipulation edit patched the source. Re-render with this new source (and mirror it into your code editor). |
 | `"editstate"` | `EditState` `{ tool, selected }` | Edit-mode tool or node selection changes (drive a property panel / toolbar highlight). |
@@ -737,7 +775,7 @@ const off = edd.on("diagnostics", (diags) => {
   if (errors.length) console.warn(errors.map((d) => `${d.code}: ${d.message}`).join("\n"));
 });
 // later: off();  // unsubscribe
-edd.on("state", (s) => console.log(`beat ${s.index + 1}/${s.total} — ${s.stepName}`));
+edd.on("state", (s) => console.log(s.index < 0 ? "Overview" : `beat ${s.index + 1}/${s.total} — ${s.stepName}`));
 
 // Direct-edit round-trip: the diagram is editable, and edits flow back to code.
 let source = "scene { rect a \"A\"\n a --> b }";
@@ -786,14 +824,20 @@ export function Diagram() {
 | `source` | `string` (required) | EDodoDraw source. Re-renders whenever it changes. |
 | `className` | `string` | On the host `<div>`. |
 | `style` | `CSSProperties` | Merged onto the host (which defaults to `width/height: 100%`). |
+| `colorScheme` | `"light" \| "dark" \| null` | Force light/dark rendering (see `setColorScheme`). Reactive — flip it to follow your app's theme. Omit/`null` follows the DSL's own theme. |
 | `onReady` | `(edd: EdodoDraw) => void` | Called **once** after mount with the imperative instance — use it to subscribe to events or grab a ref for camera/export. |
 | `onDiagnostics` | `(diags: Diagnostic[]) => void` | Wired to the `"diagnostics"` event. |
 | `onState` | `(state: PlayerState) => void` | Wired to the `"state"` event. |
 
 The host `<div>` fills its parent (`width/height: 100%`), so wrap it in a **sized**
 element. Note the `EdodoDrawOptions` props (`interactive`, `grid`, …) are read
-**once at mount**; only `source` is reactive. To change options at runtime, remount
-(e.g. via a React `key`).
+**once at mount**; `source` and `colorScheme` are reactive. To change other options
+at runtime, remount (e.g. via a React `key`).
+
+```tsx
+// follow the host app's theme (e.g. a "dark" boolean from your own toggle)
+<EdodoDrawView source={code} colorScheme={dark ? "dark" : "light"} />
+```
 
 ---
 
@@ -811,6 +855,11 @@ const { scene, diagnostics, report } = compileEdd(`scene { a -> b -> c }`);
 // report      : string[] — human-readable, source-annotated diagnostic blocks
 
 if (diagnostics.hasErrors) throw new Error(report.join("\n\n"));
+
+// Force a render mode (overrides the DSL's declared theme). Same knob the
+// facade's setColorScheme / <EdodoDrawView colorScheme> use under the hood:
+const dark = compileEdd(`scene { a -> b }`, { mode: "dark" });
+// dark.scene.theme.mode === "dark"; background + gridColor + default ink adapt.
 ```
 
 > `compileEdd` returns `diagnostics` as a **`DiagnosticBag`** (use `.items`,
@@ -1663,6 +1712,7 @@ timeline story {
 
   beat ingress "Traffic enters at the edge" {
     camera focus [client, cdn, gw] zoom 1.5 ease spring
+    reveal { show [client, cdn, gw] with pop }   // pop the entry path into focus
     annotate {
       point-at gw "single entry point" { from: ne, color: $accent }
       highlight cdn { color: yellow }
@@ -1671,6 +1721,7 @@ timeline story {
 
   beat services "Inside the app tier" {
     camera focus services zoom 1.6
+    reveal { show [auth, api, worker] with pop }
     annotate {
       spotlight services { dim: 0.72 }
       underline api "the hot path" { color: $accent }
@@ -1680,6 +1731,7 @@ timeline story {
 
   beat data "Where state lives" {
     camera focus data zoom 1.7 ease ease-in-out
+    reveal { draw-on [db, cache, queue] }        // sweep the data stores in
     annotate {
       callout db "primary of record" { placement: right }
       circle-mark queue "retry here"

package/dist-lib/react.js

@@ -1,7 +1,7 @@
 import { jsx } from "react/jsx-runtime";
 import { useRef, useEffect } from "react";
-import { c as EdodoDraw } from "./chunks/EdodoDraw-BCfKu4Q3.js";
-function EdodoDrawView({ source, className, style, onReady, onDiagnostics, onState, ...opts }) {
+import { c as EdodoDraw } from "./chunks/EdodoDraw-BdJowisU.js";
+function EdodoDrawView({ source, className, style, colorScheme, onReady, onDiagnostics, onState, ...opts }) {
   const hostRef = useRef(null);
   const eddRef = useRef(null);
   useEffect(() => {
@@ -9,6 +9,7 @@ function EdodoDrawView({ source, className, style, onReady, onDiagnostics, onSta
     if (!host) return;
     const edd = new EdodoDraw(host, opts);
     eddRef.current = edd;
+    if (colorScheme !== void 0) edd.setColorScheme(colorScheme);
     if (onDiagnostics) edd.on("diagnostics", onDiagnostics);
     if (onState) edd.on("state", onState);
     onReady?.(edd);
@@ -20,6 +21,9 @@ function EdodoDrawView({ source, className, style, onReady, onDiagnostics, onSta
   useEffect(() => {
     void eddRef.current?.render(source);
   }, [source]);
+  useEffect(() => {
+    eddRef.current?.setColorScheme(colorScheme ?? null);
+  }, [colorScheme]);
   return /* @__PURE__ */ jsx("div", { ref: hostRef, className, style: { width: "100%", height: "100%", ...style } });
 }
 export {

package/dist-lib/react.js.map

@@ -1 +1 @@
-{"version":3,"file":"react.js","sources":["../src/lib/react.tsx"],"sourcesContent":["/**\n * `edododraw/react` — a thin React wrapper over the EdodoDraw facade.\n *\n *   <EdodoDrawView source={code} interactive onReady={(edd) => …} />\n *\n * React is a peer dependency; nothing here is imported by the core entry.\n */\n\nimport { useEffect, useRef } from \"react\";\nimport type { CSSProperties } from \"react\";\nimport { EdodoDraw, type EdodoDrawOptions } from \"./EdodoDraw.js\";\nimport type { Diagnostic } from \"../engine/dsl/diagnostics.js\";\nimport type { PlayerState } from \"../engine/timeline/player.js\";\n\nexport interface EdodoDrawViewProps extends EdodoDrawOptions {\n  /** EDodoDraw source to render (re-renders whenever it changes). */\n  source: string;\n  className?: string;\n  style?: CSSProperties;\n  /** Called once with the imperative instance after mount. */\n  onReady?: (edd: EdodoDraw) => void;\n  onDiagnostics?: (diags: Diagnostic[]) => void;\n  onState?: (state: PlayerState) => void;\n}\n\nexport function EdodoDrawView({ source, className, style, onReady, onDiagnostics, onState, ...opts }: EdodoDrawViewProps) {\n  const hostRef = useRef<HTMLDivElement | null>(null);\n  const eddRef = useRef<EdodoDraw | null>(null);\n\n  useEffect(() => {\n    const host = hostRef.current;\n    if (!host) return;\n    const edd = new EdodoDraw(host, opts);\n    eddRef.current = edd;\n    if (onDiagnostics) edd.on(\"diagnostics\", onDiagnostics);\n    if (onState) edd.on(\"state\", onState);\n    onReady?.(edd);\n    return () => {\n      edd.destroy();\n      eddRef.current = null;\n    };\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, []);\n\n  useEffect(() => {\n    void eddRef.current?.render(source);\n  }, [source]);\n\n  return <div ref={hostRef} className={className} style={{ width: \"100%\", height: \"100%\", ...style }} />;\n}\n\nexport { EdodoDraw } from \"./EdodoDraw.js\";\nexport type { EdodoDrawOptions } from \"./EdodoDraw.js\";\n"],"names":[],"mappings":";;;AAyBO,SAAS,cAAc,EAAE,QAAQ,WAAW,OAAO,SAAS,eAAe,SAAS,GAAG,QAA4B;AACxH,QAAM,UAAU,OAA8B,IAAI;AAClD,QAAM,SAAS,OAAyB,IAAI;AAE5C,YAAU,MAAM;AACd,UAAM,OAAO,QAAQ;AACrB,QAAI,CAAC,KAAM;AACX,UAAM,MAAM,IAAI,UAAU,MAAM,IAAI;AACpC,WAAO,UAAU;AACjB,QAAI,cAAe,KAAI,GAAG,eAAe,aAAa;AACtD,QAAI,QAAS,KAAI,GAAG,SAAS,OAAO;AACpC,cAAU,GAAG;AACb,WAAO,MAAM;AACX,UAAI,QAAA;AACJ,aAAO,UAAU;AAAA,IACnB;AAAA,EAEF,GAAG,CAAA,CAAE;AAEL,YAAU,MAAM;AACd,SAAK,OAAO,SAAS,OAAO,MAAM;AAAA,EACpC,GAAG,CAAC,MAAM,CAAC;AAEX,SAAO,oBAAC,OAAA,EAAI,KAAK,SAAS,WAAsB,OAAO,EAAE,OAAO,QAAQ,QAAQ,QAAQ,GAAG,QAAM,CAAG;AACtG;"}
+{"version":3,"file":"react.js","sources":["../src/lib/react.tsx"],"sourcesContent":["/**\n * `edododraw/react` — a thin React wrapper over the EdodoDraw facade.\n *\n *   <EdodoDrawView source={code} interactive onReady={(edd) => …} />\n *\n * React is a peer dependency; nothing here is imported by the core entry.\n */\n\nimport { useEffect, useRef } from \"react\";\nimport type { CSSProperties } from \"react\";\nimport { EdodoDraw, type EdodoDrawOptions } from \"./EdodoDraw.js\";\nimport type { Diagnostic } from \"../engine/dsl/diagnostics.js\";\nimport type { PlayerState } from \"../engine/timeline/player.js\";\n\nexport interface EdodoDrawViewProps extends EdodoDrawOptions {\n  /** EDodoDraw source to render (re-renders whenever it changes). */\n  source: string;\n  className?: string;\n  style?: CSSProperties;\n  /**\n   * Force light/dark rendering, overriding the diagram's declared theme.\n   * `null`/omitted follows the DSL's own theme. See `EdodoDraw.setColorScheme`.\n   */\n  colorScheme?: \"light\" | \"dark\" | null;\n  /** Called once with the imperative instance after mount. */\n  onReady?: (edd: EdodoDraw) => void;\n  onDiagnostics?: (diags: Diagnostic[]) => void;\n  onState?: (state: PlayerState) => void;\n}\n\nexport function EdodoDrawView({ source, className, style, colorScheme, onReady, onDiagnostics, onState, ...opts }: EdodoDrawViewProps) {\n  const hostRef = useRef<HTMLDivElement | null>(null);\n  const eddRef = useRef<EdodoDraw | null>(null);\n\n  useEffect(() => {\n    const host = hostRef.current;\n    if (!host) return;\n    const edd = new EdodoDraw(host, opts);\n    eddRef.current = edd;\n    if (colorScheme !== undefined) edd.setColorScheme(colorScheme); // before first render → no flash\n    if (onDiagnostics) edd.on(\"diagnostics\", onDiagnostics);\n    if (onState) edd.on(\"state\", onState);\n    onReady?.(edd);\n    return () => {\n      edd.destroy();\n      eddRef.current = null;\n    };\n    // eslint-disable-next-line react-hooks/exhaustive-deps\n  }, []);\n\n  useEffect(() => {\n    void eddRef.current?.render(source);\n  }, [source]);\n\n  useEffect(() => {\n    // `undefined` and `null` both mean \"follow the DSL theme\" — revert either way.\n    eddRef.current?.setColorScheme(colorScheme ?? null);\n  }, [colorScheme]);\n\n  return <div ref={hostRef} className={className} style={{ width: \"100%\", height: \"100%\", ...style }} />;\n}\n\nexport { EdodoDraw } from \"./EdodoDraw.js\";\nexport type { EdodoDrawOptions } from \"./EdodoDraw.js\";\n"],"names":[],"mappings":";;;AA8BO,SAAS,cAAc,EAAE,QAAQ,WAAW,OAAO,aAAa,SAAS,eAAe,SAAS,GAAG,QAA4B;AACrI,QAAM,UAAU,OAA8B,IAAI;AAClD,QAAM,SAAS,OAAyB,IAAI;AAE5C,YAAU,MAAM;AACd,UAAM,OAAO,QAAQ;AACrB,QAAI,CAAC,KAAM;AACX,UAAM,MAAM,IAAI,UAAU,MAAM,IAAI;AACpC,WAAO,UAAU;AACjB,QAAI,gBAAgB,OAAW,KAAI,eAAe,WAAW;AAC7D,QAAI,cAAe,KAAI,GAAG,eAAe,aAAa;AACtD,QAAI,QAAS,KAAI,GAAG,SAAS,OAAO;AACpC,cAAU,GAAG;AACb,WAAO,MAAM;AACX,UAAI,QAAA;AACJ,aAAO,UAAU;AAAA,IACnB;AAAA,EAEF,GAAG,CAAA,CAAE;AAEL,YAAU,MAAM;AACd,SAAK,OAAO,SAAS,OAAO,MAAM;AAAA,EACpC,GAAG,CAAC,MAAM,CAAC;AAEX,YAAU,MAAM;AAEd,WAAO,SAAS,eAAe,eAAe,IAAI;AAAA,EACpD,GAAG,CAAC,WAAW,CAAC;AAEhB,SAAO,oBAAC,OAAA,EAAI,KAAK,SAAS,WAAsB,OAAO,EAAE,OAAO,QAAQ,QAAQ,QAAQ,GAAG,QAAM,CAAG;AACtG;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "edododraw",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "type": "module",
   "description": "A 100% code/syntax-to-diagram engine with the Excalidraw hand-drawn aesthetic, magic-move camera, scriptable + real-time annotations, animated arrows, and first-class Mermaid import.",
   "license": "MIT",