flowsvg 0.0.0-stage → 0.1.0

package/dist/browser.js

@@ -0,0 +1,353 @@
+/**
+ * Browser player: own the clock, DOM, controls and input, forwarding time and visual options to the core.
+ * Importing does not access the DOM; createPlayer allocates mount resources and destroy releases them.
+ */
+import { paintContentHighlight } from "./node-content-paint.js";
+import { updateSvgDom } from "./svg-dom.js";
+import { attachPlayerLifecycle } from "./player-lifecycle.js";
+import { observeKeyboard, observeReducedMotion } from "./player-accessibility.js";
+import { PlayerControls } from "./player-controls.js";
+import { resolveThemePalette } from "./theme.js";
+import { createDiagram } from "./core.js";
+/**
+ * Mount a player using the host document and observe browser motion preferences unless explicitly overridden.
+ * Replaces host children; destroy an existing player before replacing it on the same host.
+ * @throws {DiagramValidationError} For an invalid initial document, before an instance exists to emit error.
+ */
+export function createPlayer(host, document, options = {}) {
+    const initial = createDiagram(document);
+    return new BrowserPlayer(host, initial, document, options);
+}
+/**
+ * Own one compiled Diagram and advance time with RAF; core results drive the canvas, caption and controls.
+ * Retain cleanup callbacks for lifecycle, media preferences and pointer listeners, releasing them on destroy.
+ */
+class BrowserPlayer {
+    element;
+    diagram;
+    options;
+    timeMs = 0;
+    speed = 1;
+    playing = false;
+    destroyed = false;
+    frameHandle;
+    lastTimestamp;
+    frame;
+    canvas;
+    caption;
+    controls;
+    scenes;
+    beatStarts;
+    detachLifecycle;
+    stopKeyboard;
+    stopMotion;
+    stopPointer;
+    themeOverride;
+    pointerPosition;
+    hoveredHit = null;
+    constructor(host, diagram, document, options) {
+        this.element = host;
+        this.diagram = diagram;
+        this.beatStarts = collectBeatStarts(document);
+        this.scenes = collectScenes(document);
+        const owner = host.ownerDocument;
+        const motion = observeReducedMotion(owner, options.reducedMotion, (reducedMotion) => {
+            if (this.destroyed)
+                return;
+            this.options = { ...this.options, reducedMotion };
+            this.updateFrame();
+        });
+        this.stopMotion = motion.cleanup;
+        this.themeOverride = options.theme;
+        this.options = { ...options, theme: options.theme ?? document.theme ?? "light", reducedMotion: motion.value };
+        this.frame = diagram.evaluateAt(0, this.options);
+        this.canvas = owner.createElement("div");
+        this.canvas.className = "flowsvg-canvas";
+        this.stopKeyboard = observeKeyboard(this.canvas, { toggle: this.togglePlayback, step: (direction) => this.step(direction) });
+        this.caption = owner.createElement("p");
+        this.caption.className = "flowsvg-caption";
+        this.caption.setAttribute("aria-live", "polite");
+        this.caption.setAttribute("aria-atomic", "true");
+        if (options.controls !== false) {
+            this.controls = new PlayerControls(owner, {
+                toggle: this.togglePlayback,
+                step: (direction) => this.step(direction),
+                seek: (timeMs) => this.seek(timeMs),
+                setSpeed: (speed) => this.setSpeed(speed)
+            });
+        }
+        host.replaceChildren(this.canvas, this.caption, ...(this.controls ? [this.controls.element] : []));
+        this.render();
+        this.stopPointer = observePointer(this.canvas, {
+            move: (event) => this.handlePointer("hover", event),
+            leave: () => this.clearPointer(),
+            click: (event) => this.handlePointer("click", event)
+        });
+        this.detachLifecycle = attachPlayerLifecycle(host, this.canvas, () => this.pause());
+    }
+    play() {
+        if (this.destroyed || this.playing || this.element.ownerDocument.visibilityState === "hidden" || this.diagram.totalDuration <= this.timeMs)
+            return;
+        this.playing = true;
+        this.lastTimestamp = undefined;
+        this.renderControls();
+        this.emit("playstatechange");
+        this.scheduleFrame();
+    }
+    pause() {
+        if (this.destroyed || !this.playing)
+            return;
+        this.playing = false;
+        if (this.frameHandle !== undefined)
+            cancelAnimationFrame(this.frameHandle);
+        this.frameHandle = undefined;
+        this.renderControls();
+        this.emit("playstatechange");
+    }
+    seek(timeMs) {
+        if (this.destroyed)
+            return;
+        this.timeMs = clamp(timeMs, 0, this.diagram.totalDuration);
+        this.lastTimestamp = undefined;
+        this.updateFrame();
+        if (this.timeMs >= this.diagram.totalDuration)
+            this.pause();
+    }
+    step(direction) {
+        if (this.destroyed)
+            return;
+        this.pause();
+        const starts = direction > 0 ? this.beatStarts : [...this.beatStarts].reverse();
+        const target = starts.find((start) => direction > 0 ? start > this.timeMs : start < this.timeMs);
+        this.seek(target ?? (direction > 0 ? this.diagram.totalDuration : 0));
+    }
+    setSpeed(speed) {
+        if (this.destroyed || !Number.isFinite(speed) || speed <= 0)
+            return;
+        this.speed = speed;
+        this.renderControls();
+    }
+    load(document) {
+        if (this.destroyed)
+            return;
+        try {
+            // Keep the old player intact until compilation succeeds so invalid loads do not interrupt valid playback.
+            const diagram = createDiagram(document);
+            this.pause();
+            if (this.destroyed)
+                return;
+            this.diagram = diagram;
+            this.options = { ...this.options, theme: this.themeOverride ?? document.theme ?? "light" };
+            this.beatStarts = collectBeatStarts(document);
+            this.scenes = collectScenes(document);
+            this.timeMs = 0;
+            // A replacement document owns new interaction targets, even when it reuses the same node IDs.
+            this.pointerPosition = undefined;
+            this.updateFrame();
+        }
+        catch (error) {
+            this.emit("error", { ...this.state(), error: error instanceof Error ? error : new Error(String(error)) });
+        }
+    }
+    getState() {
+        return this.state();
+    }
+    destroy() {
+        if (this.destroyed)
+            return;
+        // Block dispatch/rescheduling before releasing resources; do not call pause, which would emit an event.
+        this.destroyed = true;
+        this.playing = false;
+        if (this.frameHandle !== undefined)
+            cancelAnimationFrame(this.frameHandle);
+        this.frameHandle = undefined;
+        this.lastTimestamp = undefined;
+        this.detachLifecycle();
+        this.stopKeyboard();
+        this.stopMotion();
+        this.stopPointer();
+        this.pointerPosition = undefined;
+        this.hoveredHit = null;
+        this.element.replaceChildren();
+    }
+    /** The first RAF establishes a baseline; seek clears it so elapsed time from the old position is not reused. */
+    tick = (timestamp) => {
+        if (!this.playing || this.destroyed)
+            return;
+        this.frameHandle = undefined;
+        const previous = this.lastTimestamp ?? timestamp;
+        this.lastTimestamp = timestamp;
+        this.timeMs += (timestamp - previous) * this.speed;
+        if (this.timeMs >= this.diagram.totalDuration) {
+            this.timeMs = this.diagram.totalDuration;
+            this.updateFrame();
+            this.pause();
+            return;
+        }
+        this.updateFrame();
+        this.scheduleFrame();
+    };
+    /** Event listeners may restart playback synchronously; never queue a second frame owned by the same player. */
+    scheduleFrame() {
+        if (this.destroyed || !this.playing || this.frameHandle !== undefined)
+            return;
+        this.frameHandle = requestAnimationFrame(this.tick);
+    }
+    /** Update the frame before notifying consumers so listeners observe the rendered position. */
+    updateFrame() {
+        const previousBeat = this.frame.beatId;
+        const previousScene = this.frame.sceneId;
+        this.frame = this.diagram.evaluateAt(this.timeMs, this.options);
+        this.render();
+        if (previousBeat !== this.frame.beatId || previousScene !== this.frame.sceneId)
+            this.emit("stepchange");
+        this.emit("timeupdate");
+    }
+    togglePlayback = () => {
+        if (this.playing)
+            this.pause();
+        else
+            this.play();
+    };
+    render() {
+        updateSvgDom(this.canvas, this.diagram.renderSvg(this.timeMs, this.options));
+        this.canvas.style.aspectRatio = `${this.frame.camera.width} / ${this.frame.camera.height}`;
+        this.updateHover();
+        this.caption.textContent = this.frame.caption ?? "";
+        this.renderControls();
+    }
+    renderControls() {
+        this.controls?.render({ ...this.state(), sceneId: this.frame.sceneId, scenes: this.scenes });
+    }
+    state() {
+        return { timeMs: this.timeMs, totalDuration: this.diagram.totalDuration, playing: this.playing, speed: this.speed, frame: this.frame };
+    }
+    handlePointer(type, event) {
+        if (this.destroyed)
+            return;
+        if (type === "hover") {
+            this.pointerPosition = { clientX: event.clientX, clientY: event.clientY };
+            updateSvgDom(this.canvas, this.diagram.renderSvg(this.timeMs, this.options));
+            this.updateHover(true);
+            return;
+        }
+        if (type === "click")
+            event.stopPropagation();
+        const point = pointerToDiagramPoint(this.canvas, this.frame.camera, event);
+        const hit = this.diagram.hitTest(this.timeMs, point, this.options);
+        const detail = hit ? { ...hit, point, timeMs: this.timeMs, sceneId: this.frame.sceneId, beatId: this.frame.beatId } : null;
+        this.emit("click", detail);
+        this.emit("objectclick", detail);
+    }
+    /** Re-hit the saved screen position after camera/geometry updates; hover never changes the core hit geometry. */
+    updateHover(emitAlways = false) {
+        const point = this.pointerPosition ? pointerToDiagramPoint(this.canvas, this.frame.camera, this.pointerPosition) : undefined;
+        const hit = point ? this.diagram.hitTest(this.timeMs, point, this.options) : null;
+        if (hit?.type === "node") {
+            const shape = Array.from(this.canvas.querySelectorAll("[data-id]")).find((element) => element.getAttribute("data-id") === hit.id);
+            const color = resolveThemePalette(this.options.theme).highlight;
+            const node = this.frame.nodes.find((candidate) => candidate.id === hit.id);
+            // Border-only hover preserves all current timeline and content paint unless fill feedback is explicitly enabled.
+            if (this.options.hoverFill)
+                shape?.setAttribute("fill", color);
+            shape?.setAttribute("stroke", color);
+            const layout = node?.contentLayout;
+            const content = Array.from(this.canvas.querySelectorAll("[data-content-id]")).find((element) => element.getAttribute("data-content-id") === hit.id);
+            if (this.options.hoverFill && content && layout)
+                paintHoveredContent(content, paintContentHighlight(layout, 1, color));
+        }
+        const changed = hit?.id !== this.hoveredHit?.id || hit?.type !== this.hoveredHit?.type;
+        this.hoveredHit = hit;
+        if (!emitAlways && !changed)
+            return;
+        const detail = hit && point ? { ...hit, point, timeMs: this.timeMs, sceneId: this.frame.sceneId, beatId: this.frame.beatId } : null;
+        this.emit("hover", detail);
+        this.emit("objecthover", detail);
+    }
+    clearPointer() {
+        if (this.destroyed)
+            return;
+        this.pointerPosition = undefined;
+        updateSvgDom(this.canvas, this.diagram.renderSvg(this.timeMs, this.options));
+        this.updateHover(true);
+    }
+    emit(type, detail) {
+        if (!this.destroyed)
+            this.element.dispatchEvent(new CustomEvent(type, { detail: detail === undefined ? this.state() : detail }));
+    }
+}
+/** Apply the shared paint result to current decorative children; no child receives a separate interaction identity. */
+function paintHoveredContent(content, layout) {
+    const tags = content.querySelectorAll("rect");
+    layout.tags.forEach((tag, index) => tags[index]?.setAttribute("fill", tag.fill));
+    const texts = content.querySelectorAll("text");
+    layout.lines.forEach((line, index) => {
+        const text = texts[index];
+        text?.setAttribute("fill", line.color);
+        const spans = text?.querySelectorAll("tspan");
+        line.spans.forEach((span, spanIndex) => spans?.[spanIndex]?.setAttribute("fill", span.color));
+    });
+    const graphs = content.querySelectorAll("[data-content-graph]");
+    layout.graphs?.forEach((graph, index) => {
+        const circles = graphs[index]?.querySelectorAll("circle");
+        const edges = graphs[index]?.querySelectorAll("line");
+        graph.nodes.forEach((node, nodeIndex) => circles?.[nodeIndex]?.setAttribute("fill", node.fill));
+        graph.edges.forEach((edge, edgeIndex) => edges?.[edgeIndex]?.setAttribute("stroke", edge.color));
+    });
+}
+function clamp(value, min, max) {
+    return Number.isFinite(value) ? Math.min(max, Math.max(min, value)) : min;
+}
+function collectBeatStarts(document) {
+    let startMs = 0;
+    return document.scenes.flatMap((scene) => scene.beats.map((beat) => {
+        const start = startMs;
+        startMs += beat.durationMs;
+        return start;
+    }));
+}
+function collectScenes(document) {
+    let startMs = 0;
+    return document.scenes.map((scene) => {
+        const choice = { id: scene.id, label: scene.label, startMs };
+        startMs += scene.beats.reduce((duration, beat) => duration + beat.durationMs, 0);
+        return choice;
+    });
+}
+function observePointer(canvas, handlers) {
+    const onMove = (event) => handlers.move(event);
+    const onLeave = () => handlers.leave();
+    const onClick = (event) => handlers.click(event);
+    canvas.addEventListener("pointermove", onMove);
+    canvas.addEventListener("pointerleave", onLeave);
+    canvas.addEventListener("pointercancel", onLeave);
+    canvas.addEventListener("click", onClick);
+    return () => {
+        canvas.removeEventListener("pointermove", onMove);
+        canvas.removeEventListener("pointerleave", onLeave);
+        canvas.removeEventListener("pointercancel", onLeave);
+        canvas.removeEventListener("click", onClick);
+    };
+}
+/**
+ * Prefer the inverse SVG screen transform for scaling/letterboxing; otherwise map the element rectangle to the camera.
+ * The rectangle fallback lacks full SVG transform information and is only an approximation.
+ */
+function pointerToDiagramPoint(canvas, camera, event) {
+    const svg = canvas.querySelector("svg");
+    const matrix = svg?.getScreenCTM?.();
+    if (matrix) {
+        const inverse = matrix.inverse();
+        return {
+            x: event.clientX * inverse.a + event.clientY * inverse.c + inverse.e,
+            y: event.clientX * inverse.b + event.clientY * inverse.d + inverse.f
+        };
+    }
+    const bounds = svg?.getBoundingClientRect() ?? canvas.getBoundingClientRect();
+    const width = bounds.width || 1;
+    const height = bounds.height || 1;
+    return {
+        x: camera.x + ((event.clientX - bounds.left) / width) * camera.width,
+        y: camera.y + ((event.clientY - bounds.top) / height) * camera.height
+    };
+}

package/dist/core.d.ts

@@ -0,0 +1,306 @@
+/**
+ * Platform-independent core: validate and compile documents, then derive geometry, hit tests and static SVG.
+ * The browser consumes these results; this module does not read the DOM, network, system theme or browser clock.
+ */
+import { type NodeContent, type NodeContentLayout } from "./node-content.js";
+export type { NodeContent, ContentBlock, ContentListItem, ContentListStyle, ContentTag, ContentTagStyle, ContentTagBackground, ContentGraphBlock, ContentGraphNode, ContentGraphEdge, ContentGraphLayout, ContentText, ContentTextSpan, ContentSpanStyle, ContentSpan, ContentTextStyle, ContentAlignment, ContentSafeArea, ContentLine, NodeContentLayout } from "./node-content.js";
+/** Supported shapes; a group also supplies the origin and visibility constraints for its children. */
+export type NodeKind = "rect" | "roundedRect" | "ellipse" | "cylinder" | "group";
+/** Route families generated from node geometry; orthogonal routes avoid obstacles, and curved routes use cubic Bézier controls. */
+export type EdgeRoute = "straight" | "orthogonal" | "curved";
+/** Cardinal node sides used for explicit edge attachments. */
+export type PortDirection = "top" | "right" | "bottom" | "left";
+/** Direction used by a beat-local transfer marker; it does not change the static edge arrow. */
+export type FlowDirection = "forward" | "reverse";
+/** Explicit diagram palette; the core does not read the system theme. */
+export type ThemeName = "light" | "dark";
+/** Initial viewport in diagram units; width and height must be finite positive numbers. */
+export interface Viewport {
+    width: number;
+    height: number;
+}
+/** Initial base style; colors accept hexadecimal RGB/RGBA only, and dashed is used for group borders. */
+export interface NodeStyle {
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    textColor?: string;
+    dashed?: boolean;
+}
+/** Initial edge style; omitted values use the evaluation theme and default stroke width. */
+export interface EdgeStyle {
+    stroke?: string;
+    strokeWidth?: number;
+    dashed?: boolean;
+}
+/**
+ * Initial node authored in parent-group coordinates, or document coordinates when parentId is absent.
+ * Dimensions are explicit; groups do not clip children, and visible defaults to true.
+ */
+export interface DiagramNode {
+    id: string;
+    kind: NodeKind;
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    label?: string;
+    /** Ordered content for rect, roundedRect or cylinder nodes; mutually exclusive with label and never resizes the node. */
+    content?: NodeContent;
+    /** Parent group ID; x/y are offsets from that group's current origin. */
+    parentId?: string;
+    /** Initial logical visibility, defaulting to true; ancestor visibility can still mask this node. */
+    visible?: boolean;
+    style?: NodeStyle;
+}
+/** Directed relation between two nodes or group boundaries; route defaults to straight, and hidden endpoints mask the edge. */
+export interface DiagramEdge {
+    id: string;
+    from: string;
+    to: string;
+    label?: string;
+    route?: EdgeRoute;
+    /** Optional cardinal side for the source attachment; omitted values use geometry-aware automatic routing. */
+    fromPort?: PortDirection;
+    /** Optional cardinal side for the target attachment; omitted values use geometry-aware automatic routing. */
+    toPort?: PortDirection;
+    visible?: boolean;
+    style?: EdgeStyle;
+}
+/**
+ * Serializable version-1 document. Node and edge IDs are globally unique; an empty scenes array defines a static diagram.
+ * Nodes and edges define the initial state; each scene inherits the preceding scene's final persistent state.
+ * Flow markers and their temporary highlights belong only to their active beat.
+ */
+export interface DiagramDocument {
+    version: 1;
+    title?: string;
+    viewport: Viewport;
+    theme?: ThemeName;
+    nodes: DiagramNode[];
+    edges: DiagramEdge[];
+    scenes: Scene[];
+}
+/** Named scene on the continuous global timeline; contains at least one beat. */
+export interface Scene {
+    id: string;
+    label: string;
+    beats: Beat[];
+}
+/**
+ * Persistent actions take effect from the beat start and inherit into later beats; durationMs must be positive.
+ * transitionMs defaults to min(250, durationMs) within [0, durationMs]; omitted captions inherit the previous text.
+ * Flows on distinct edges share the full beat progress and expire together without inheritance, independently of transitionMs.
+ */
+export interface Beat {
+    /** Total length in milliseconds, including the transition and any remaining hold time. */
+    durationMs: number;
+    /** Opening transition in milliseconds; defaults to min(250, durationMs), and zero applies changes immediately. */
+    transitionMs?: number;
+    /** Replaces the inherited caption at the beat start; an empty string clears it. */
+    caption?: string;
+    actions: Action[];
+}
+/**
+ * Base values accepted by updateNode; coordinates remain parent-relative and opacity is within [0, 1].
+ * label/content are mutually exclusive within a beat and replace the display mode at its start.
+ * Content replacement and clearing preserve authored dimensions unless geometry is explicitly updated.
+ */
+export interface NodeVisualState {
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    /** Switch to simple-label mode at the beat start, clearing structured content. */
+    label?: string;
+    /** Replace all content at the beat start; null clears content without restoring a previous label. */
+    content?: NodeContent | null;
+    fill?: string;
+    stroke?: string;
+    opacity?: number;
+}
+/** Base values accepted by updateEdge; colors and numbers interpolate, while labels switch at the beat start. */
+export interface EdgeVisualState {
+    label?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    opacity?: number;
+}
+/**
+ * Declarative beat action. Visibility, explicit highlighting, base updates and focus persist into later beats.
+ * Flow markers and their temporary participant highlights expire at the beat end without changing persistent layers.
+ * focus accepts a node/group ID or null for the full view; duplicate assignments within one beat are rejected.
+ * A beat permits at most one flow per edge, regardless of direction; other visual layers can coexist.
+ */
+export type Action = {
+    type: "show" | "hide" | "highlight" | "unhighlight";
+    target: string;
+} | {
+    type: "updateNode";
+    target: string;
+    value: Partial<NodeVisualState>;
+} | {
+    type: "updateEdge";
+    target: string;
+    value: Partial<EdgeVisualState>;
+} | {
+    type: "focus";
+    target: string | null;
+} | {
+    type: "flow";
+    target: string;
+    direction: FlowDirection;
+    /** Plain short message for this transfer; provided text uses a horizontal capsule instead of a dot. */
+    text?: string;
+};
+/** Validation path and reason, for example scenes[0].beats[1].actions[0].target. */
+export interface ValidationIssue {
+    path: string;
+    message: string;
+}
+/**
+ * Reproducible visual options: theme overrides the document theme, with light as the final default.
+ * reducedMotion completes transitions immediately and hides flow markers while retaining flow participant highlights.
+ * Beat durations and timeline positions do not change.
+ */
+export interface EvaluateOptions {
+    /** Override the document theme; the final fallback is light. */
+    theme?: ThemeName;
+    /** Apply target values immediately and hide flow markers; retain participant highlights, beat durations and selection. */
+    reducedMotion?: boolean;
+}
+/** Deterministically laid-out line; x/y specify its centered anchor and text baseline in SVG document coordinates. */
+export interface TextLine {
+    text: string;
+    x: number;
+    y: number;
+}
+/**
+ * Node after timeline and ancestor-group evaluation; x/y are absolute document coordinates.
+ * visible tracks participation in visibility/routing; it can be true at a reveal start with zero opacity.
+ * labelLines/labelBoxes retain overflowing text; drawing and hit testing still require positive opacity.
+ */
+export interface EvaluatedNode extends DiagramNode {
+    x: number;
+    y: number;
+    /** Logical visibility after ancestor masking; a reveal may be visible with zero opacity. */
+    visible: boolean;
+    /** Effective opacity in [0, 1], including visibility transitions and ancestor opacity. */
+    opacity: number;
+    highlighted: boolean;
+    labelLines: string[];
+    labelBoxes: TextLine[];
+    /** Structured text geometry and clip region; absent in simple-label mode. */
+    contentLayout?: NodeContentLayout;
+}
+/** Evaluated edge; opacity includes endpoint/ancestor masking, and path contains SVG line or cubic commands in document coordinates. */
+export interface EvaluatedEdge extends DiagramEdge {
+    visible: boolean;
+    opacity: number;
+    highlighted: boolean;
+    path: string;
+    labelLines: string[];
+    labelBoxes: TextLine[];
+    /** Beat-local marker state, omitted outside an active beat or when reduced motion hides it. */
+    flow?: EdgeFlowMarker;
+}
+/** Deterministic transfer state derived from the current beat and edge path. */
+export interface EdgeFlowMarker {
+    direction: FlowDirection;
+    /** Linear completion from the selected direction's start, in the inclusive range [0, 1). */
+    progress: number;
+    point: DiagramPoint;
+    /** Unmodified beat-local message; SVG uses deterministic code-point widths and keeps the capsule horizontal. */
+    text?: string;
+}
+/** Non-blocking text overflow warning; objectId identifies the object and path locates its document field. */
+export interface LayoutWarning {
+    path: string;
+    message: string;
+    code: "text-overflow";
+    objectId: string;
+}
+/** SVG viewBox in document coordinates; focusing preserves the initial viewport aspect ratio. */
+export interface CameraState {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** Hit category; groups are also reported as nodes. */
+export type HitObjectType = "node" | "edge";
+/** Identity of a hit object, without DOM references, so it can be used outside browsers. */
+export interface HitObject {
+    id: string;
+    type: HitObjectType;
+}
+/** Point in absolute document coordinates; browser screen coordinates must first be mapped through the viewBox. */
+export interface DiagramPoint {
+    x: number;
+    y: number;
+}
+/**
+ * Complete frame for a time and visual options, shared by SVG export, the browser and consumers.
+ * sceneId/beatId are null for static diagrams; beatId is `${scene.id}:${beatIndex}` with a zero-based index.
+ * beatProgress spans the whole beat, unlike the eased progress used only during its opening transition.
+ */
+export interface DiagramFrameState {
+    /** Clamped global time in milliseconds. */
+    timeMs: number;
+    sceneId: string | null;
+    /** `${scene.id}:${beatIndex}`, with a zero-based index; null for static diagrams. */
+    beatId: string | null;
+    /** Linear progress in [0, 1] over the whole beat; zero for static diagrams. */
+    beatProgress: number;
+    nodes: EvaluatedNode[];
+    edges: EvaluatedEdge[];
+    camera: CameraState;
+    caption?: string;
+    warnings: LayoutWarning[];
+}
+/** Compilation error for invalid documents; issues contains all field problems found by validation. */
+export declare class DiagramValidationError extends Error {
+    readonly issues: readonly ValidationIssue[];
+    constructor(issues: ValidationIssue[]);
+}
+/**
+ * Validate document structure, values and references; an empty list means validation passed.
+ * Accumulate issues across inspectable branches without mutating input or producing a partial Diagram.
+ */
+export declare function validateDocument(input: unknown): ValidationIssue[];
+/**
+ * Validate and copy a document, then compile its timeline; later input mutations cannot affect evaluation.
+ * @throws {DiagramValidationError} If document structure, values or references are invalid.
+ */
+export declare function createDiagram(input: DiagramDocument): Diagram;
+/** One-shot static SVG export; use createDiagram to reuse compilation across repeated evaluations or exports. */
+export declare function renderSvg(document: DiagramDocument, timeMs?: number, options?: EvaluateOptions): string;
+/** Compiled diagram independent of the DOM, network and clock; each query evaluates from its time and options. */
+export interface Diagram {
+    /** Global timeline duration in milliseconds; zero for static diagrams. */
+    readonly totalDuration: number;
+    /**
+     * Evaluate a frame; finite times clamp to [0, totalDuration], and non-finite times become zero.
+     * Beat intervals include their start and exclude their end; totalDuration returns the completed final beat.
+     */
+    evaluateAt(timeMs: number, options?: EvaluateOptions): DiagramFrameState;
+    /** Serialize the same frame as self-contained static SVG with escaped text and resolved colors, without controls. */
+    renderSvg(timeMs?: number, options?: EvaluateOptions): string;
+    /**
+     * Hit-test document coordinates in paint order: ordinary nodes, then edges, then group backgrounds.
+     * Objects within each layer are searched in reverse document order.
+     * Node hits include their visible label area. Hidden/zero-opacity objects are excluded.
+     * Return null for no hit or non-finite coordinates.
+     */
+    hitTest(timeMs: number, point: DiagramPoint, options?: EvaluateOptions): HitObject | null;
+}
+interface Typography {
+    fontSize: number;
+    lineHeight: number;
+    charWidth: number;
+}
+/**
+ * Estimate wrapping with fixed code-point widths, preserving explicit empty lines and preferring spaces as breaks.
+ * No font/DOM measurement is used; this handles width only, while frame evaluation reports height overflow.
+ */
+export declare function wrapText(label: string, maxWidth: number, typography?: Typography): string[];