vizcraft 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # vizcraft
 
+## 0.3.0
+
+### Minor Changes
+
+- [`c5ffe75`](https://github.com/ChipiKaf/vizcraft/commit/c5ffe7546a2e2148618db057c24aea01ecf097e0) Thanks [@ChipiKaf](https://github.com/ChipiKaf)! - Add improved overlay api
+
+## 0.2.2
+
+### Patch Changes
+
+- [`7c9eb18`](https://github.com/ChipiKaf/vizcraft/commit/7c9eb185e727bde899b4779c4661d8b176db8549) Thanks [@ChipiKaf](https://github.com/ChipiKaf)! - update documentation
+
 ## 0.2.1
 
 ### Patch Changes

package/README.md

@@ -7,7 +7,7 @@
 [![Snapshot](https://github.com/ChipiKaf/vizcraft/actions/workflows/snapshot.yml/badge.svg)](https://github.com/ChipiKaf/vizcraft/actions/workflows/snapshot.yml)
 [![license](https://img.shields.io/npm/l/vizcraft.svg)](LICENSE)
 
-📖 Full documentation: https://vizcraft-docs.vercel.app/
+📖 Full documentation: [docs here](https://vizcraft-docs.vercel.app/docs/intro)
 
 **A declarative, builder-based library for creating animated SVG network visualizations and algorithm demos.**
 
@@ -41,7 +41,6 @@ import { viz } from 'vizcraft';
 const builder = viz().view(800, 600);
 
 builder
-  .view(500, 500)
   .node('a')
   .at(100, 100)
   .circle(15)
@@ -57,21 +56,21 @@ const container = document.getElementById('viz-basic');
 if (container) builder.mount(container);
 ```
 
-More walkthroughs and examples: https://vizcraft-docs.vercel.app/
+More walkthroughs and examples: [docs here](https://vizcraft-docs.vercel.app/docs/examples).
 
 ## 📚 Documentation (Topics)
 
-Full documentation site: https://vizcraft-docs.vercel.app/
+Full documentation site: [docs here](https://vizcraft-docs.vercel.app/docs/intro)
 
-For a guided walkthrough, the repo docs are organized like this:
+Docs topics (same as the sidebar):
 
-- [Introduction](../../packages/docs/docs/intro.md)
-- [Examples](../../packages/docs/docs/examples.mdx)
-- [Essentials](../../packages/docs/docs/essentials.mdx)
-- [Animations](../../packages/docs/docs/animations/index.mdx)
-  - [Animation Builder API](../../packages/docs/docs/animations/animation-builder-api.mdx)
-- [Advanced](../../packages/docs/docs/advanced.mdx)
-- [Types](../../packages/docs/docs/types.mdx)
+- [Introduction](https://vizcraft-docs.vercel.app/docs/intro)
+- [Examples](https://vizcraft-docs.vercel.app/docs/examples)
+- [Essentials](https://vizcraft-docs.vercel.app/docs/essentials)
+- [Animations](https://vizcraft-docs.vercel.app/docs/animations)
+  - [Animation Builder API](https://vizcraft-docs.vercel.app/docs/animations/animation-builder-api)
+- [Advanced](https://vizcraft-docs.vercel.app/docs/advanced)
+- [Types](https://vizcraft-docs.vercel.app/docs/types)
 
 Run the docs locally (monorepo):
 
@@ -122,7 +121,7 @@ b.edge('n1', 'n2')
 
 ### Animations
 
-See the full Animations guide: https://vizcraft-docs.vercel.app/
+See the full Animations guide [docs here](https://vizcraft-docs.vercel.app/docs/animations).
 
 VizCraft supports **two complementary animation approaches**:
 
@@ -153,7 +152,7 @@ b.node('a')
 
 2. **Data-only timeline animations (`AnimationSpec`)** (sequenced tweens)
 
-- Author with `builder.animate((anim) => ...)`.
+- Author with `builder.animate((aBuilder) => ...)`.
 - VizCraft stores compiled specs on the scene as `scene.animationSpecs`.
 - Play them with `builder.play()`.
 
@@ -174,8 +173,8 @@ b.node('a')
   .arrow()
   .done();
 
-b.animate((anim) =>
-  anim
+b.animate((aBuilder) =>
+  aBuilder
     .node('a')
     .to({ x: 200, opacity: 0.35 }, { duration: 600 })
     .node('b')
@@ -206,8 +205,10 @@ b.node('a')
   .edge('a', 'b', 'e1')
   .done();
 
-b.animate((anim) =>
-  anim.edge('a', 'b', 'e1').to({ strokeDashoffset: -120 }, { duration: 900 })
+b.animate((aBuilder) =>
+  aBuilder
+    .edge('a', 'b', 'e1')
+    .to({ strokeDashoffset: -120 }, { duration: 900 })
 );
 ```
 
@@ -216,8 +217,8 @@ b.animate((anim) =>
 Specs can carry adapter extensions so you can animate your own numeric properties:
 
 ```ts
-b.animate((anim) =>
-  anim
+b.animate((aBuilder) =>
+  aBuilder
     .extendAdapter((adapter) => {
       adapter.register?.('node', 'r', {
         get: (target) => adapter.get(target, 'r'),

package/dist/anim/animationBuilder.d.ts

@@ -38,6 +38,8 @@ export declare class AnimationBuilder {
     extendAdapter(cb: ExtendAdapter): this;
     /** Select a node by id (compiles to target `node:<id>`). */
     node(id: string): this;
+    /** Select an overlay by key (compiles to target `overlay:<key>`). */
+    overlay(key: string): this;
     /**
      * Select an edge.
      *

package/dist/anim/animationBuilder.js

@@ -30,6 +30,11 @@ export class AnimationBuilder {
         this.currentTarget = toTarget('node', id);
         return this;
     }
+    /** Select an overlay by key (compiles to target `overlay:<key>`). */
+    overlay(key) {
+        this.currentTarget = toTarget('overlay', key);
+        return this;
+    }
     edge(a, b, c) {
         const id = b === undefined ? a : (c ?? `${a}->${b}`);
         this.currentTarget = toTarget('edge', id);
@@ -56,7 +61,7 @@ export class AnimationBuilder {
      */
     to(props, opts) {
         if (!this.currentTarget) {
-            throw new Error('AnimationBuilder.to(): no target selected (call node(...) or edge(...))');
+            throw new Error('AnimationBuilder.to(): no target selected (call node(...), edge(...), or overlay(...))');
         }
         const duration = Math.max(0, opts.duration);
         const easing = opts.easing;

package/dist/anim/spec.d.ts

@@ -1,4 +1,4 @@
-export type AnimationTarget = (`node:${string}` | `edge:${string}`) | (string & {});
+export type AnimationTarget = (`node:${string}` | `edge:${string}` | `overlay:${string}`) | (string & {});
 export type CoreAnimProperty = 'x' | 'y' | 'opacity' | 'scale' | 'rotation' | 'strokeDashoffset';
 export type AnimProperty = CoreAnimProperty | (string & {});
 export type Ease = 'linear' | 'easeIn' | 'easeOut' | 'easeInOut';

package/dist/anim/vizcraftAdapter.js

@@ -1,13 +1,21 @@
+import { OVERLAY_RUNTIME_DIRTY } from '../types';
 import { createRegistryAdapter } from './registryAdapter';
 export function createVizCraftAdapter(scene, requestRender) {
     const nodesById = new Map(scene.nodes.map((n) => [n.id, n]));
     const edgesById = new Map(scene.edges.map((e) => [e.id, e]));
+    const overlays = scene.overlays ?? [];
+    const overlaysByKey = new Map();
+    for (const spec of overlays) {
+        const key = spec.key ?? spec.id;
+        overlaysByKey.set(key, spec);
+    }
     const adapter = createRegistryAdapter({
         flush: requestRender,
     });
     // register node/edge target resolvers and props using ergonomic handles
     const node = adapter.kind('node', (id) => nodesById.get(id));
     const edge = adapter.kind('edge', (id) => edgesById.get(id));
+    const overlay = adapter.kind('overlay', (key) => overlaysByKey.get(key));
     node
         .prop('x', {
         get: (el) => {
@@ -75,5 +83,64 @@ export function createVizCraftAdapter(scene, requestRender) {
             e.runtime.strokeDashoffset = v;
         },
     });
-    return adapter;
+    // Overlay params: allow animating arbitrary numeric fields on `spec.params`.
+    //
+    // This intentionally uses a generic reader/writer so users can animate
+    // custom overlays without needing adapter extensions.
+    const overlayParamReader = (el, prop) => {
+        const spec = el;
+        const params = spec.params;
+        const v = params?.[prop];
+        return typeof v === 'number' && Number.isFinite(v) ? v : undefined;
+    };
+    const overlayParamWriter = (el, prop, value) => {
+        const spec = el;
+        const existing = spec.params;
+        const params = existing && typeof existing === 'object' && !Array.isArray(existing)
+            ? existing
+            : {};
+        params[prop] = value;
+        // Ensure we keep reference stable in case params was undefined or non-object.
+        spec.params = params;
+        // Mark dirty so patchRuntime can avoid re-rendering unaffected overlays.
+        spec[OVERLAY_RUNTIME_DIRTY] = true;
+    };
+    const resolveOverlayFromTarget = (target) => {
+        const t = String(target);
+        if (!t.startsWith('overlay:'))
+            return undefined;
+        const key = t.slice('overlay:'.length);
+        return overlaysByKey.get(key);
+    };
+    // Register core overlay props we know are numeric today.
+    // Users can still register more via adapter extensions if they prefer explicitness.
+    overlay.prop('progress', {
+        get: (el) => overlayParamReader(el, 'progress'),
+        set: (el, v) => overlayParamWriter(el, 'progress', v),
+    });
+    // Make overlays fully generic: any numeric `spec.params[prop]` is animatable.
+    //
+    // `createRegistryAdapter` requires per-prop registration; for overlays we provide
+    // a fallback so custom overlays don't need adapter extensions.
+    const baseGet = adapter.get;
+    const baseSet = adapter.set;
+    return {
+        ...adapter,
+        get(target, prop) {
+            const v = baseGet(target, prop);
+            if (v !== undefined)
+                return v;
+            const spec = resolveOverlayFromTarget(target);
+            if (!spec)
+                return undefined;
+            return overlayParamReader(spec, String(prop));
+        },
+        set(target, prop, value) {
+            baseSet(target, prop, value);
+            const spec = resolveOverlayFromTarget(target);
+            if (!spec)
+                return;
+            overlayParamWriter(spec, String(prop), value);
+        },
+    };
 }

package/dist/builder.d.ts

@@ -1,4 +1,5 @@
-import type { VizScene, VizNode, VizEdge, NodeLabel, EdgeLabel, AnimationConfig, VizGridConfig } from './types';
+import type { VizScene, VizNode, VizEdge, NodeLabel, EdgeLabel, AnimationConfig, OverlayId, OverlayParams, VizGridConfig } from './types';
+import { OverlayBuilder } from './overlayBuilder';
 import type { AnimationSpec } from './anim/spec';
 import { type AnimationBuilder, type AnimatableProps, type TweenOptions } from './anim/animationBuilder';
 import { type PlaybackController } from './anim/playback';
@@ -13,6 +14,9 @@ interface VizBuilder {
      * The compiled spec is also stored on the built scene as `scene.animationSpecs`.
      */
     animate(cb: (anim: AnimationBuilder) => unknown): AnimationSpec;
+    /** Fluent overlay authoring (compiles to overlay specs and stores on the built scene). */
+    overlay(cb: (overlay: OverlayBuilder) => unknown): VizBuilder;
+    overlay<K extends OverlayId>(id: K, params: OverlayParams<K>, key?: string): VizBuilder;
     overlay<T>(id: string, params: T, key?: string): VizBuilder;
     node(id: string): NodeBuilder;
     edge(from: string, to: string, id?: string): EdgeBuilder;
@@ -67,6 +71,8 @@ interface NodeBuilder {
     done(): VizBuilder;
     node(id: string): NodeBuilder;
     edge(from: string, to: string, id?: string): EdgeBuilder;
+    overlay(cb: (overlay: OverlayBuilder) => unknown): VizBuilder;
+    overlay<K extends OverlayId>(id: K, params: OverlayParams<K>, key?: string): VizBuilder;
     overlay<T>(id: string, params: T, key?: string): VizBuilder;
     build(): VizScene;
     svg(): string;
@@ -87,6 +93,8 @@ interface EdgeBuilder {
     done(): VizBuilder;
     node(id: string): NodeBuilder;
     edge(from: string, to: string, id?: string): EdgeBuilder;
+    overlay(cb: (overlay: OverlayBuilder) => unknown): VizBuilder;
+    overlay<K extends OverlayId>(id: K, params: OverlayParams<K>, key?: string): VizBuilder;
     overlay<T>(id: string, params: T, key?: string): VizBuilder;
     build(): VizScene;
     svg(): string;

package/dist/builder.js

@@ -1,6 +1,8 @@
+import { OVERLAY_RUNTIME_DIRTY } from './types';
 import { DEFAULT_VIZ_CSS } from './styles';
 import { defaultCoreAnimationRegistry } from './animations';
 import { defaultCoreOverlayRegistry } from './overlays';
+import { OverlayBuilder } from './overlayBuilder';
 import { createRuntimePatchCtx, patchRuntime, } from './runtimePatcher';
 import { buildAnimationSpec, } from './anim/animationBuilder';
 import { createBuilderPlayback, } from './anim/playback';
@@ -75,14 +77,16 @@ class VizBuilderImpl {
         this._gridConfig = { cols, rows, padding };
         return this;
     }
-    /**
-     * Adds an overlay to the scene.
-     * @param id The ID of the overlay
-     * @param params The parameters of the overlay
-     * @param key The key of the overlay
-     * @returns The builder
-     */
-    overlay(id, params, key) {
+    overlay(arg1, arg2, arg3) {
+        if (typeof arg1 === 'function') {
+            const overlay = new OverlayBuilder();
+            arg1(overlay);
+            this._overlays.push(...overlay.build());
+            return this;
+        }
+        const id = arg1;
+        const params = arg2;
+        const key = arg3;
         this._overlays.push({ id, params, key });
         return this;
     }
@@ -274,6 +278,92 @@ class VizBuilderImpl {
             runtimePatchCtxBySvg.set(svg, ctx);
         }
         patchRuntime(scene, ctx);
+        // Keep overlays in sync during animation playback.
+        //
+        // Animations flush via `patchRuntime()` (to avoid full re-mounts). Nodes/edges
+        // are patched via `runtimePatcher`, but overlays are registry-rendered and
+        // need an explicit reconcile pass to reflect animated `spec.params` changes.
+        const overlayLayer = svg.querySelector('[data-viz-layer="overlays"]') ||
+            svg.querySelector('.viz-layer-overlays');
+        if (overlayLayer) {
+            const overlays = scene.overlays ?? [];
+            const nodesById = new Map(scene.nodes.map((n) => [n.id, n]));
+            const edgesById = new Map(scene.edges.map((e) => [e.id, e]));
+            const svgNS = 'http://www.w3.org/2000/svg';
+            // 1) Map existing overlay groups
+            const existingOverlayGroups = Array.from(overlayLayer.children).filter((el) => el.tagName === 'g');
+            const existingOverlaysMap = new Map();
+            existingOverlayGroups.forEach((el) => {
+                const id = el.getAttribute('data-overlay-id');
+                if (id)
+                    existingOverlaysMap.set(id, el);
+            });
+            // Fast decision: if nothing is dirty and keys match, skip overlay work.
+            const overlayKeyCountMatches = overlays.length === existingOverlaysMap.size;
+            let needsOverlayPass = !overlayKeyCountMatches;
+            const dirtyOverlays = [];
+            if (!needsOverlayPass) {
+                for (const spec of overlays) {
+                    const uniqueKey = spec.key || spec.id;
+                    if (!existingOverlaysMap.has(uniqueKey)) {
+                        needsOverlayPass = true;
+                        break;
+                    }
+                    if (spec[OVERLAY_RUNTIME_DIRTY]) {
+                        dirtyOverlays.push(spec);
+                    }
+                }
+            }
+            if (!needsOverlayPass && dirtyOverlays.length === 0)
+                return;
+            const processedOverlayIds = new Set();
+            // 2) Render/update overlays
+            const toUpdate = needsOverlayPass ? overlays : dirtyOverlays;
+            toUpdate.forEach((spec) => {
+                const renderer = defaultCoreOverlayRegistry.get(spec.id);
+                if (!renderer)
+                    return;
+                const uniqueKey = spec.key || spec.id;
+                processedOverlayIds.add(uniqueKey);
+                let group = existingOverlaysMap.get(uniqueKey);
+                if (!group) {
+                    group = document.createElementNS(svgNS, 'g');
+                    group.setAttribute('data-overlay-id', uniqueKey);
+                    group.setAttribute('data-viz-role', 'overlay-group');
+                    overlayLayer.appendChild(group);
+                }
+                // Keep wrapper class in sync even when reusing an existing group.
+                const expectedClass = `viz-overlay-${spec.id}${spec.className ? ` ${spec.className}` : ''}`;
+                const currentClass = group.getAttribute('class');
+                if (currentClass !== expectedClass) {
+                    group.setAttribute('class', expectedClass);
+                }
+                const overlayCtx = {
+                    spec,
+                    nodesById,
+                    edgesById,
+                    scene,
+                    registry: defaultCoreOverlayRegistry,
+                };
+                if (renderer.update) {
+                    renderer.update(overlayCtx, group);
+                }
+                else {
+                    group.innerHTML = renderer.render(overlayCtx);
+                }
+                // Clear dirty flag after successful update.
+                delete spec[OVERLAY_RUNTIME_DIRTY];
+            });
+            // 3) Remove stale overlays only if keys may have changed.
+            if (!overlayKeyCountMatches) {
+                existingOverlayGroups.forEach((el) => {
+                    const id = el.getAttribute('data-overlay-id');
+                    if (id && !processedOverlayIds.has(id)) {
+                        el.remove();
+                    }
+                });
+            }
+        }
     }
     /**
      * Renders the scene to the DOM.
@@ -620,15 +710,17 @@ class VizBuilderImpl {
                     if (!group) {
                         group = document.createElementNS(svgNS, 'g');
                         group.setAttribute('data-overlay-id', uniqueKey);
-                        group.setAttribute('class', `viz-overlay-${spec.id}`);
                         group.setAttribute('data-viz-role', 'overlay-group');
                         overlayLayer.appendChild(group);
                     }
+                    // Keep wrapper class in sync even when reusing an existing group.
+                    group.setAttribute('class', `viz-overlay-${spec.id}${spec.className ? ` ${spec.className}` : ''}`);
                     const ctx = {
                         spec,
                         nodesById,
                         edgesById: new Map(edges.map((e) => [e.id, e])),
                         scene,
+                        registry: defaultCoreOverlayRegistry,
                     };
                     if (renderer.update) {
                         renderer.update(ctx, group);
@@ -798,7 +890,13 @@ class VizBuilderImpl {
             overlays.forEach((spec) => {
                 const renderer = defaultCoreOverlayRegistry.get(spec.id);
                 if (renderer) {
-                    svgContent += renderer.render({ spec, nodesById, edgesById, scene });
+                    svgContent += renderer.render({
+                        spec,
+                        nodesById,
+                        edgesById,
+                        scene,
+                        registry: defaultCoreOverlayRegistry,
+                    });
                 }
             });
             svgContent += '</g>';
@@ -932,8 +1030,10 @@ class NodeBuilderImpl {
     edge(from, to, id) {
         return this.parent.edge(from, to, id);
     }
-    overlay(id, params, key) {
-        return this.parent.overlay(id, params, key);
+    overlay(arg1, arg2, arg3) {
+        if (typeof arg1 === 'function')
+            return this.parent.overlay(arg1);
+        return this.parent.overlay(arg1, arg2, arg3);
     }
     build() {
         return this.parent.build();
@@ -1026,8 +1126,10 @@ class EdgeBuilderImpl {
     edge(from, to, id) {
         return this.parent.edge(from, to, id || `${from}->${to}`); // Default ID to from->to
     }
-    overlay(id, params, key) {
-        return this.parent.overlay(id, params, key);
+    overlay(arg1, arg2, arg3) {
+        if (typeof arg1 === 'function')
+            return this.parent.overlay(arg1);
+        return this.parent.overlay(arg1, arg2, arg3);
     }
     build() {
         return this.parent.build();

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export * from './builder';
 export * from './styles';
 export * from './animations';
 export * from './overlays';
+export * from './overlayBuilder';
 export * from './anim/spec';
 export * from './anim/animationBuilder';
 export * from './anim/playback';

package/dist/index.js

@@ -3,6 +3,7 @@ export * from './builder';
 export * from './styles';
 export * from './animations';
 export * from './overlays';
+export * from './overlayBuilder';
 export * from './anim/spec';
 export * from './anim/animationBuilder';
 export * from './anim/playback';

package/dist/overlayBuilder.d.ts

@@ -0,0 +1,50 @@
+import type { OverlayId, OverlayParams, VizOverlaySpec } from './types';
+import type { CircleOverlayParams, GroupOverlayParams, RectOverlayParams, TextOverlayParams } from './overlays';
+export type OverlayAddOptions = {
+    /** Optional stable key used to uniquely identify an overlay instance. */
+    key?: string;
+    /** Optional class applied by the overlay renderer. */
+    className?: string;
+};
+/**
+ * Fluent overlay authoring.
+ *
+ * - Produces portable `VizOverlaySpec[]` data (rendering remains registry-driven).
+ * - Typed by `OverlayKindRegistry` when available, with a back-compat escape hatch.
+ */
+export declare class OverlayBuilder {
+    private readonly specs;
+    private readonly keyCounters;
+    /**
+     * Add an overlay spec.
+     *
+     * Overload 1: typed overlay ids via `OverlayKindRegistry`.
+     */
+    add<K extends OverlayId>(id: K, params: OverlayParams<K>, options?: OverlayAddOptions): this;
+    /**
+     * Add an overlay spec.
+     *
+     * Overload 2: back-compat escape hatch for arbitrary ids.
+     */
+    add(id: string, params: any, options?: OverlayAddOptions): this;
+    /** Remove overlays by key, or (if unkeyed) by id. */
+    remove(keyOrId: string): this;
+    /** Remove all overlays. */
+    clear(): this;
+    build(): VizOverlaySpec[];
+    /** Add a generic rectangle overlay (built-in, no custom registry needed). */
+    rect(params: RectOverlayParams, options?: OverlayAddOptions): this;
+    /** Add a generic circle overlay (built-in, no custom registry needed). */
+    circle(params: CircleOverlayParams, options?: OverlayAddOptions): this;
+    /** Add a generic text overlay (built-in, no custom registry needed). */
+    text(params: TextOverlayParams, options?: OverlayAddOptions): this;
+    /**
+     * Add a composite group overlay (built-in).
+     *
+     * Children are authored via the callback and rendered inside a single SVG <g>.
+     * You can animate the group by targeting its key and tweening `x`, `y`, `scale`, `rotation`, `opacity`.
+     */
+    group(params: Omit<GroupOverlayParams, 'children'>, buildChildren: (overlay: OverlayBuilder) => unknown, options?: OverlayAddOptions): this;
+}
+/** Convenience helper for one-off overlay list compilation. */
+export declare function buildOverlaySpecs(cb: (overlay: OverlayBuilder) => unknown): VizOverlaySpec[];

package/dist/overlayBuilder.js

@@ -0,0 +1,80 @@
+/**
+ * Fluent overlay authoring.
+ *
+ * - Produces portable `VizOverlaySpec[]` data (rendering remains registry-driven).
+ * - Typed by `OverlayKindRegistry` when available, with a back-compat escape hatch.
+ */
+export class OverlayBuilder {
+    specs = [];
+    keyCounters = new Map();
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    add(id, params, options) {
+        const className = options?.className;
+        // If a user adds multiple overlays of the same id without keys, they will
+        // collide at reconcile time (since the DOM layer uses `key || id`).
+        // We auto-generate a stable-ish key in that case.
+        let key = options?.key;
+        if (!key) {
+            const hasUnkeyedSameId = this.specs.some((s) => s.id === id && (s.key === undefined || s.key === ''));
+            if (hasUnkeyedSameId) {
+                const next = (this.keyCounters.get(id) ?? 0) + 1;
+                this.keyCounters.set(id, next);
+                key = `${id}#${next}`;
+            }
+        }
+        this.specs.push({ id, params, key, className });
+        return this;
+    }
+    /** Remove overlays by key, or (if unkeyed) by id. */
+    remove(keyOrId) {
+        for (let i = this.specs.length - 1; i >= 0; i--) {
+            const s = this.specs[i];
+            if (!s)
+                continue;
+            const matchesKey = s.key === keyOrId;
+            const matchesUnkeyedId = !s.key && s.id === keyOrId;
+            if (matchesKey || matchesUnkeyedId)
+                this.specs.splice(i, 1);
+        }
+        return this;
+    }
+    /** Remove all overlays. */
+    clear() {
+        this.specs.length = 0;
+        this.keyCounters.clear();
+        return this;
+    }
+    build() {
+        return [...this.specs];
+    }
+    /** Add a generic rectangle overlay (built-in, no custom registry needed). */
+    rect(params, options) {
+        return this.add('rect', params, options);
+    }
+    /** Add a generic circle overlay (built-in, no custom registry needed). */
+    circle(params, options) {
+        return this.add('circle', params, options);
+    }
+    /** Add a generic text overlay (built-in, no custom registry needed). */
+    text(params, options) {
+        return this.add('text', params, options);
+    }
+    /**
+     * Add a composite group overlay (built-in).
+     *
+     * Children are authored via the callback and rendered inside a single SVG <g>.
+     * You can animate the group by targeting its key and tweening `x`, `y`, `scale`, `rotation`, `opacity`.
+     */
+    group(params, buildChildren, options) {
+        const childOverlay = new OverlayBuilder();
+        buildChildren(childOverlay);
+        const children = childOverlay.build();
+        return this.add('group', { ...params, children }, options);
+    }
+}
+/** Convenience helper for one-off overlay list compilation. */
+export function buildOverlaySpecs(cb) {
+    const overlay = new OverlayBuilder();
+    cb(overlay);
+    return overlay.build();
+}

package/dist/overlays.d.ts

@@ -1,9 +1,115 @@
 import type { VizNode, VizEdge, VizOverlaySpec, VizScene } from './types';
+export type SignalOverlayParams = {
+    from: string;
+    to: string;
+    progress: number;
+    magnitude?: number;
+};
+export type GridLabelsOverlayParams = {
+    colLabels?: Record<number, string>;
+    rowLabels?: Record<number, string>;
+    yOffset?: number;
+    xOffset?: number;
+};
+export interface DataPoint {
+    id: string;
+    currentNodeId: string;
+    [key: string]: any;
+}
+export type DataPointsOverlayParams = {
+    points: DataPoint[];
+};
+export type RectOverlayParams = {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    rx?: number;
+    ry?: number;
+    opacity?: number;
+    /** SVG fill (defaults to a visible blue). Can be overridden by CSS via className. */
+    fill?: string;
+    /** SVG stroke (defaults to a visible blue). Can be overridden by CSS via className. */
+    stroke?: string;
+    /** SVG stroke-width (defaults to 3). Can be overridden by CSS via className. */
+    strokeWidth?: number;
+};
+export type CircleOverlayParams = {
+    x: number;
+    y: number;
+    r: number;
+    opacity?: number;
+    /** SVG fill (defaults to a visible blue). Can be overridden by CSS via className. */
+    fill?: string;
+    /** SVG stroke (defaults to a visible blue). Can be overridden by CSS via className. */
+    stroke?: string;
+    /** SVG stroke-width (defaults to 3). Can be overridden by CSS via className. */
+    strokeWidth?: number;
+};
+export type TextOverlayParams = {
+    x: number;
+    y: number;
+    text: string;
+    opacity?: number;
+    /** SVG fill color (defaults to #111). Can be overridden by CSS via className. */
+    fill?: string;
+    fontSize?: number;
+    fontWeight?: string | number;
+    textAnchor?: 'start' | 'middle' | 'end';
+    dominantBaseline?: string;
+};
+export type GroupOverlayParams = {
+    /**
+     * Translate (group-local origin).
+     *
+     * If `from`/`to` are provided, these act as an additional offset.
+     */
+    x?: number;
+    y?: number;
+    /**
+     * Optional node ids used to drive the group's position via `progress`.
+     *
+     * When set, the group will translate along the line from `from` to `to`.
+     */
+    from?: string;
+    to?: string;
+    /** Interpolation 0..1 used when `from`/`to` are set. */
+    progress?: number;
+    /**
+     * Optional "pulse" value 0..1.
+     *
+     * When provided, it scales the group slightly (in addition to `scale`).
+     */
+    magnitude?: number;
+    /** Scale around group origin. */
+    scale?: number;
+    /** Rotate (degrees) around group origin. */
+    rotation?: number;
+    /** Group opacity (multiplies with child opacity). */
+    opacity?: number;
+    /** Child overlays rendered inside this group. Coordinates are group-local. */
+    children: VizOverlaySpec[];
+};
+declare module './types' {
+    interface OverlayKindRegistry {
+        signal: SignalOverlayParams;
+        'grid-labels': GridLabelsOverlayParams;
+        'data-points': DataPointsOverlayParams;
+        /** Generic overlay primitives (no custom registry needed). */
+        rect: RectOverlayParams;
+        circle: CircleOverlayParams;
+        text: TextOverlayParams;
+        /** Overlay container that can hold child overlays and be animated as a unit. */
+        group: GroupOverlayParams;
+    }
+}
 export interface CoreOverlayRenderContext<T = any> {
     spec: VizOverlaySpec<T>;
     nodesById: Map<string, VizNode>;
     edgesById: Map<string, VizEdge>;
     scene: VizScene;
+    /** Registry reference (useful for composite overlays like `group`). */
+    registry?: CoreOverlayRegistry;
 }
 export interface CoreOverlayRenderer<T = any> {
     render: (ctx: CoreOverlayRenderContext<T>) => string;
@@ -14,25 +120,11 @@ export declare class CoreOverlayRegistry {
     register(id: string, renderer: CoreOverlayRenderer): this;
     get(id: string): CoreOverlayRenderer<any> | undefined;
 }
-export declare const coreSignalOverlay: CoreOverlayRenderer<{
-    from: string;
-    to: string;
-    progress: number;
-    magnitude?: number;
-}>;
-export declare const coreGridLabelsOverlay: CoreOverlayRenderer<{
-    colLabels?: Record<number, string>;
-    rowLabels?: Record<number, string>;
-    yOffset?: number;
-    xOffset?: number;
-}>;
-interface DataPoint {
-    id: string;
-    currentNodeId: string;
-    [key: string]: any;
-}
-export declare const coreDataPointOverlay: CoreOverlayRenderer<{
-    points: DataPoint[];
-}>;
+export declare const coreSignalOverlay: CoreOverlayRenderer<SignalOverlayParams>;
+export declare const coreGridLabelsOverlay: CoreOverlayRenderer<GridLabelsOverlayParams>;
+export declare const coreDataPointOverlay: CoreOverlayRenderer<DataPointsOverlayParams>;
+export declare const coreRectOverlay: CoreOverlayRenderer<RectOverlayParams>;
+export declare const coreCircleOverlay: CoreOverlayRenderer<CircleOverlayParams>;
+export declare const coreTextOverlay: CoreOverlayRenderer<TextOverlayParams>;
+export declare const coreGroupOverlay: CoreOverlayRenderer<GroupOverlayParams>;
 export declare const defaultCoreOverlayRegistry: CoreOverlayRegistry;
-export {};

package/dist/overlays.js

@@ -64,6 +64,7 @@ export const coreGridLabelsOverlay = {
         return output;
     },
 };
+// ... (OverlayRegistry and other exports remain unchanged) ...
 // Built-in Overlay: Data Points
 export const coreDataPointOverlay = {
     render: ({ spec, nodesById }) => {
@@ -133,7 +134,324 @@ export const coreDataPointOverlay = {
         });
     },
 };
+// Generic Overlay: Rect
+export const coreRectOverlay = {
+    render: ({ spec }) => {
+        const { x, y, w, h, rx, ry, opacity, fill, stroke, strokeWidth } = spec.params;
+        const cls = spec.className ?? 'viz-overlay-rect';
+        const rxAttr = rx !== undefined ? ` rx="${rx}"` : '';
+        const ryAttr = ry !== undefined ? ` ry="${ry}"` : '';
+        const opAttr = opacity !== undefined ? ` opacity="${opacity}"` : '';
+        const usingDefaultFill = fill === undefined;
+        const usingDefaultStroke = stroke === undefined;
+        const resolvedFill = fill ?? '#3b82f6';
+        const resolvedStroke = stroke ?? '#3b82f6';
+        const resolvedStrokeWidth = strokeWidth ?? 3;
+        const fillOpacityAttr = usingDefaultFill ? ' fill-opacity="0.12"' : '';
+        const strokeOpacityAttr = usingDefaultStroke ? ' stroke-opacity="0.9"' : '';
+        return `<rect x="${x}" y="${y}" width="${w}" height="${h}" fill="${resolvedFill}"${fillOpacityAttr} stroke="${resolvedStroke}"${strokeOpacityAttr} stroke-width="${resolvedStrokeWidth}"${rxAttr}${ryAttr}${opAttr} class="${cls}" />`;
+    },
+    update: ({ spec }, container) => {
+        const svgNS = 'http://www.w3.org/2000/svg';
+        const { x, y, w, h, rx, ry, opacity, fill, stroke, strokeWidth } = spec.params;
+        const cls = spec.className ?? 'viz-overlay-rect';
+        let rect = container.querySelector('rect');
+        if (!rect) {
+            rect = document.createElementNS(svgNS, 'rect');
+            container.appendChild(rect);
+        }
+        rect.setAttribute('x', String(x));
+        rect.setAttribute('y', String(y));
+        rect.setAttribute('width', String(w));
+        rect.setAttribute('height', String(h));
+        if (fill === undefined) {
+            rect.setAttribute('fill', '#3b82f6');
+            rect.setAttribute('fill-opacity', '0.12');
+        }
+        else {
+            rect.setAttribute('fill', fill);
+            rect.removeAttribute('fill-opacity');
+        }
+        if (stroke === undefined) {
+            rect.setAttribute('stroke', '#3b82f6');
+            rect.setAttribute('stroke-opacity', '0.9');
+        }
+        else {
+            rect.setAttribute('stroke', stroke);
+            rect.removeAttribute('stroke-opacity');
+        }
+        rect.setAttribute('stroke-width', String(strokeWidth ?? 3));
+        if (rx !== undefined)
+            rect.setAttribute('rx', String(rx));
+        else
+            rect.removeAttribute('rx');
+        if (ry !== undefined)
+            rect.setAttribute('ry', String(ry));
+        else
+            rect.removeAttribute('ry');
+        if (opacity !== undefined)
+            rect.setAttribute('opacity', String(opacity));
+        else
+            rect.removeAttribute('opacity');
+        rect.setAttribute('class', cls);
+    },
+};
+// Generic Overlay: Circle
+export const coreCircleOverlay = {
+    render: ({ spec }) => {
+        const { x, y, r, opacity, fill, stroke, strokeWidth } = spec.params;
+        const cls = spec.className ?? 'viz-overlay-circle';
+        const opAttr = opacity !== undefined ? ` opacity="${opacity}"` : '';
+        const usingDefaultFill = fill === undefined;
+        const usingDefaultStroke = stroke === undefined;
+        const resolvedFill = fill ?? '#3b82f6';
+        const resolvedStroke = stroke ?? '#3b82f6';
+        const resolvedStrokeWidth = strokeWidth ?? 3;
+        const fillOpacityAttr = usingDefaultFill ? ' fill-opacity="0.12"' : '';
+        const strokeOpacityAttr = usingDefaultStroke ? ' stroke-opacity="0.9"' : '';
+        return `<circle cx="${x}" cy="${y}" r="${r}" fill="${resolvedFill}"${fillOpacityAttr} stroke="${resolvedStroke}"${strokeOpacityAttr} stroke-width="${resolvedStrokeWidth}"${opAttr} class="${cls}" />`;
+    },
+    update: ({ spec }, container) => {
+        const svgNS = 'http://www.w3.org/2000/svg';
+        const { x, y, r, opacity, fill, stroke, strokeWidth } = spec.params;
+        const cls = spec.className ?? 'viz-overlay-circle';
+        let circle = container.querySelector('circle');
+        if (!circle) {
+            circle = document.createElementNS(svgNS, 'circle');
+            container.appendChild(circle);
+        }
+        circle.setAttribute('cx', String(x));
+        circle.setAttribute('cy', String(y));
+        circle.setAttribute('r', String(r));
+        if (fill === undefined) {
+            circle.setAttribute('fill', '#3b82f6');
+            circle.setAttribute('fill-opacity', '0.12');
+        }
+        else {
+            circle.setAttribute('fill', fill);
+            circle.removeAttribute('fill-opacity');
+        }
+        if (stroke === undefined) {
+            circle.setAttribute('stroke', '#3b82f6');
+            circle.setAttribute('stroke-opacity', '0.9');
+        }
+        else {
+            circle.setAttribute('stroke', stroke);
+            circle.removeAttribute('stroke-opacity');
+        }
+        circle.setAttribute('stroke-width', String(strokeWidth ?? 3));
+        if (opacity !== undefined)
+            circle.setAttribute('opacity', String(opacity));
+        else
+            circle.removeAttribute('opacity');
+        circle.setAttribute('class', cls);
+    },
+};
+// Generic Overlay: Text
+export const coreTextOverlay = {
+    render: ({ spec }) => {
+        const { x, y, text, opacity, fill, fontSize, fontWeight, textAnchor, dominantBaseline, } = spec.params;
+        const cls = spec.className ?? 'viz-overlay-text';
+        const opAttr = opacity !== undefined ? ` opacity="${opacity}"` : '';
+        const fsAttr = fontSize !== undefined ? ` font-size="${fontSize}"` : '';
+        const fwAttr = fontWeight !== undefined ? ` font-weight="${fontWeight}"` : '';
+        const taAttr = textAnchor !== undefined ? ` text-anchor="${textAnchor}"` : '';
+        const dbAttr = dominantBaseline !== undefined
+            ? ` dominant-baseline="${dominantBaseline}"`
+            : '';
+        // Basic text rendering; users should avoid untrusted HTML here.
+        const resolvedFill = fill ?? '#111';
+        return `<text x="${x}" y="${y}" fill="${resolvedFill}"${opAttr}${fsAttr}${fwAttr}${taAttr}${dbAttr} class="${cls}">${text}</text>`;
+    },
+    update: ({ spec }, container) => {
+        const svgNS = 'http://www.w3.org/2000/svg';
+        const { x, y, text, opacity, fill, fontSize, fontWeight, textAnchor, dominantBaseline, } = spec.params;
+        const cls = spec.className ?? 'viz-overlay-text';
+        let el = container.querySelector('text');
+        if (!el) {
+            el = document.createElementNS(svgNS, 'text');
+            container.appendChild(el);
+        }
+        el.setAttribute('x', String(x));
+        el.setAttribute('y', String(y));
+        el.setAttribute('fill', fill ?? '#111');
+        if (opacity !== undefined)
+            el.setAttribute('opacity', String(opacity));
+        else
+            el.removeAttribute('opacity');
+        if (fontSize !== undefined)
+            el.setAttribute('font-size', String(fontSize));
+        else
+            el.removeAttribute('font-size');
+        if (fontWeight !== undefined)
+            el.setAttribute('font-weight', String(fontWeight));
+        else
+            el.removeAttribute('font-weight');
+        if (textAnchor !== undefined)
+            el.setAttribute('text-anchor', textAnchor);
+        else
+            el.removeAttribute('text-anchor');
+        if (dominantBaseline !== undefined)
+            el.setAttribute('dominant-baseline', dominantBaseline);
+        else
+            el.removeAttribute('dominant-baseline');
+        el.setAttribute('class', cls);
+        el.textContent = text;
+    },
+};
+function groupTransform(params) {
+    const tx = params.x ?? 0;
+    const ty = params.y ?? 0;
+    const s = params.scale ?? 1;
+    const r = params.rotation ?? 0;
+    // translate first so scale/rotation occur around the group origin.
+    const parts = [`translate(${tx}, ${ty})`];
+    if (r)
+        parts.push(`rotate(${r})`);
+    if (s !== 1)
+        parts.push(`scale(${s})`);
+    return parts.join(' ');
+}
+function clamp01(v) {
+    if (v < 0)
+        return 0;
+    if (v > 1)
+        return 1;
+    return v;
+}
+function effectiveNodePos(node) {
+    return {
+        x: node.runtime?.x ?? node.pos.x,
+        y: node.runtime?.y ?? node.pos.y,
+    };
+}
+function resolveGroupTransformInputs(params, nodesById) {
+    const baseX = params.x ?? 0;
+    const baseY = params.y ?? 0;
+    let x = baseX;
+    let y = baseY;
+    if (params.from && params.to) {
+        const start = nodesById.get(params.from);
+        const end = nodesById.get(params.to);
+        if (start && end) {
+            const p = clamp01(params.progress ?? 0);
+            const a = effectiveNodePos(start);
+            const b = effectiveNodePos(end);
+            x = a.x + (b.x - a.x) * p + baseX;
+            y = a.y + (b.y - a.y) * p + baseY;
+        }
+    }
+    const userScale = params.scale ?? 1;
+    const m = params.magnitude;
+    const magScale = m === undefined ? 1 : 0.85 + 0.3 * clamp01(Math.abs(m));
+    const scale = userScale * magScale;
+    return {
+        x,
+        y,
+        scale,
+        rotation: params.rotation ?? 0,
+    };
+}
+// Composite Overlay: Group
+export const coreGroupOverlay = {
+    render: ({ spec, nodesById, edgesById, scene, registry }) => {
+        const { children, opacity } = spec.params;
+        const inputs = resolveGroupTransformInputs(spec.params, nodesById);
+        const tr = groupTransform(inputs);
+        const opAttr = opacity !== undefined ? ` opacity="${opacity}"` : '';
+        const reg = registry;
+        if (!reg) {
+            // Best-effort render even if registry is missing.
+            return `<g transform="${tr}"${opAttr}></g>`;
+        }
+        let output = `<g transform="${tr}"${opAttr}>`;
+        children.forEach((childSpec, idx) => {
+            const renderer = reg.get(childSpec.id);
+            if (!renderer)
+                return;
+            const childCtx = {
+                spec: childSpec,
+                nodesById,
+                edgesById,
+                scene,
+                registry: reg,
+            };
+            // Wrap children in their own <g> so update() has stable containers.
+            const key = childSpec.key
+                ? `key:${childSpec.key}`
+                : `idx:${idx}:${childSpec.id}`;
+            output += `<g data-viz-role="overlay-child" data-overlay-child-id="${key}">`;
+            output += renderer.render(childCtx);
+            output += '</g>';
+        });
+        output += '</g>';
+        return output;
+    },
+    update: ({ spec, nodesById, edgesById, scene, registry }, container) => {
+        const reg = registry;
+        if (!reg)
+            return;
+        const { children, opacity } = spec.params;
+        const inputs = resolveGroupTransformInputs(spec.params, nodesById);
+        container.setAttribute('transform', groupTransform(inputs));
+        if (opacity !== undefined) {
+            container.setAttribute('opacity', String(opacity));
+        }
+        else {
+            container.removeAttribute('opacity');
+        }
+        const svgNS = 'http://www.w3.org/2000/svg';
+        const existing = new Map();
+        Array.from(container.children).forEach((child) => {
+            if (child instanceof SVGGElement) {
+                const id = child.getAttribute('data-overlay-child-id');
+                if (id)
+                    existing.set(id, child);
+            }
+        });
+        const keep = new Set();
+        children.forEach((childSpec, idx) => {
+            const renderer = reg.get(childSpec.id);
+            if (!renderer)
+                return;
+            const key = childSpec.key
+                ? `key:${childSpec.key}`
+                : `idx:${idx}:${childSpec.id}`;
+            keep.add(key);
+            let childGroup = existing.get(key);
+            if (!childGroup) {
+                childGroup = document.createElementNS(svgNS, 'g');
+                childGroup.setAttribute('data-viz-role', 'overlay-child');
+                childGroup.setAttribute('data-overlay-child-id', key);
+                container.appendChild(childGroup);
+            }
+            const childCtx = {
+                spec: childSpec,
+                nodesById,
+                edgesById,
+                scene,
+                registry: reg,
+            };
+            if (renderer.update) {
+                renderer.update(childCtx, childGroup);
+            }
+            else {
+                childGroup.innerHTML = renderer.render(childCtx);
+            }
+        });
+        existing.forEach((el, id) => {
+            if (!keep.has(id))
+                el.remove();
+        });
+    },
+};
 export const defaultCoreOverlayRegistry = new CoreOverlayRegistry()
     .register('signal', coreSignalOverlay)
     .register('grid-labels', coreGridLabelsOverlay)
-    .register('data-points', coreDataPointOverlay);
+    .register('data-points', coreDataPointOverlay)
+    // Generic primitives
+    .register('rect', coreRectOverlay)
+    .register('circle', coreCircleOverlay)
+    .register('text', coreTextOverlay)
+    // Composite overlays
+    .register('group', coreGroupOverlay);

package/dist/styles.d.ts

@@ -1 +1 @@
-export declare const DEFAULT_VIZ_CSS = "\n.viz-canvas {\n  width: 100%;\n  height: 100%;\n  display: flex;\n  justify-content: center;\n  align-items: center;\n}\n\n.viz-node-label,\n.viz-edge-label {\n  dominant-baseline: middle;\n  alignment-baseline: middle;\n  transform: translateY(-0.1em);\n}\n\n.viz-canvas svg {\n  width: 100%;\n  height: 100%;\n  overflow: visible;\n}\n\n/* Keyframes */\n@keyframes vizFlow {\n  from {\n    stroke-dashoffset: 20;\n  }\n  to {\n    stroke-dashoffset: 0;\n  }\n}\n\n/* Animation Classes */\n\n/* Flow Animation (Dashed line moving) */\n.viz-anim-flow .viz-edge {\n  stroke-dasharray: 5, 5;\n  animation: vizFlow var(--viz-anim-duration, 2s) linear infinite;\n}\n\n/* Node Transition */\n.viz-node-group {\n    transition: transform 0.3s ease-out, opacity 0.3s ease-out;\n}\n\n/* Overlay Classes */\n.viz-grid-label {\n  fill: #6B7280;\n  font-size: 14px;\n  font-weight: 600;\n  opacity: 1;\n}\n\n.viz-signal {\n    fill: #3B82F6;\n    cursor: pointer;\n    pointer-events: all; \n    transition: transform 0.2s ease-out, fill 0.2s ease-out;\n}\n\n.viz-signal .viz-signal-shape {\n    fill: inherit;\n}\n\n.viz-signal:hover {\n    fill: #60A5FA;\n    transform: scale(1.5);\n}\n\n.viz-data-point {\n  fill: #F59E0B;\n  transition: cx 0.3s ease-out, cy 0.3s ease-out;\n}\n";
+export declare const DEFAULT_VIZ_CSS = "\n.viz-canvas {\n  width: 100%;\n  height: 100%;\n  display: flex;\n  justify-content: center;\n  align-items: center;\n}\n\n.viz-node-label,\n.viz-edge-label {\n  text-anchor: middle;\n  dominant-baseline: middle;\n  alignment-baseline: middle;\n  transform: translateY(0);\n}\n\n.viz-canvas svg {\n  width: 100%;\n  height: 100%;\n  overflow: visible;\n}\n\n/* Keyframes */\n@keyframes vizFlow {\n  from {\n    stroke-dashoffset: 20;\n  }\n  to {\n    stroke-dashoffset: 0;\n  }\n}\n\n/* Animation Classes */\n\n/* Flow Animation (Dashed line moving) */\n.viz-anim-flow .viz-edge {\n  stroke-dasharray: 5, 5;\n  animation: vizFlow var(--viz-anim-duration, 2s) linear infinite;\n}\n\n/* Node Transition */\n.viz-node-group {\n    transition: transform 0.3s ease-out, opacity 0.3s ease-out;\n}\n\n/* Overlay Classes */\n.viz-grid-label {\n  fill: #6B7280;\n  font-size: 14px;\n  font-weight: 600;\n  opacity: 1;\n}\n\n.viz-signal {\n    fill: #3B82F6;\n    cursor: pointer;\n    pointer-events: all; \n    transition: transform 0.2s ease-out, fill 0.2s ease-out;\n}\n\n.viz-signal .viz-signal-shape {\n    fill: inherit;\n}\n\n.viz-signal:hover {\n    fill: #60A5FA;\n    transform: scale(1.5);\n}\n\n.viz-data-point {\n  fill: #F59E0B;\n  transition: cx 0.3s ease-out, cy 0.3s ease-out;\n}\n";

package/dist/styles.js

@@ -9,9 +9,10 @@ export const DEFAULT_VIZ_CSS = `
 
 .viz-node-label,
 .viz-edge-label {
+  text-anchor: middle;
   dominant-baseline: middle;
   alignment-baseline: middle;
-  transform: translateY(-0.1em);
+  transform: translateY(0);
 }
 
 .viz-canvas svg {

package/dist/types.d.ts

@@ -86,6 +86,34 @@ export interface VizEdge {
     onClick?: (id: string, edge: VizEdge) => void;
     animations?: VizAnimSpec[];
 }
+/**
+ * Overlay kind -> params mapping.
+ *
+ * This interface is intentionally empty in core and is meant to be augmented by:
+ * - core overlays (in this repo)
+ * - downstream libraries/apps (via TS module augmentation)
+ */
+export interface OverlayKindRegistry {
+}
+/** Internal runtime flag used to mark overlays as needing a DOM update. */
+export declare const OVERLAY_RUNTIME_DIRTY: unique symbol;
+/** String overlay ids that are known/typed via `OverlayKindRegistry`. */
+export type KnownOverlayId = Extract<keyof OverlayKindRegistry, string>;
+/** Any overlay id (typed known ids + arbitrary custom ids). */
+export type OverlayId = KnownOverlayId | (string & {});
+/**
+ * Params type for a given overlay id.
+ * - Known ids resolve to their registered params type.
+ * - Unknown/custom ids fall back to `unknown` (escape hatch).
+ */
+export type OverlayParams<K extends string> = K extends KnownOverlayId ? OverlayKindRegistry[K] : unknown;
+/** A type-safe overlay spec keyed by overlay id. */
+export type TypedVizOverlaySpec<K extends OverlayId = OverlayId> = {
+    id: K;
+    key?: string;
+    params: OverlayParams<K>;
+    className?: string;
+};
 export type VizOverlaySpec<T = any> = {
     id: string;
     key?: string;

package/dist/types.js

@@ -1 +1,2 @@
-export {};
+/** Internal runtime flag used to mark overlays as needing a DOM update. */
+export const OVERLAY_RUNTIME_DIRTY = Symbol('vizcraft.overlay.runtimeDirty');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vizcraft",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "A fluent, type-safe SVG scene builder for composing nodes, edges, animations, and overlays with incremental DOM updates and no framework dependency.",
   "keywords": [
     "visualization",