flowsvg 0.0.0-stage → 0.1.1

package/dist/core/timeline.js

@@ -0,0 +1,148 @@
+import { mixColor } from "./color.js";
+const DEFAULT_TRANSITION_MS = 250;
+const NUMERIC_VISUAL_FIELDS = ["x", "y", "width", "height", "opacity", "strokeWidth"];
+const DEFAULT_STROKE_WIDTH = 2;
+/**
+ * Flatten scenes into continuous beats and compile snapshots once; queries locate beats by binary search.
+ * Each beat inherits the previous final state; evaluation is independent of query order and clocks.
+ * See docs/adr/0002-continuous-global-timeline.md for time semantics.
+ */
+export class CompiledTimeline {
+    totalDuration;
+    beats;
+    initial;
+    title;
+    constructor(document) {
+        this.initial = new Map([
+            ...document.nodes.map((node) => [node.id, {
+                    visible: node.visible !== false, highlighted: false, kind: "node", values: {
+                        x: node.x, y: node.y, width: node.width, height: node.height, label: node.label, content: node.content, fill: node.style?.fill, stroke: node.style?.stroke, opacity: 1
+                    }
+                }]),
+            ...document.edges.map((edge) => [edge.id, {
+                    visible: edge.visible !== false, highlighted: false, kind: "edge", values: {
+                        label: edge.label, stroke: edge.style?.stroke, strokeWidth: edge.style?.strokeWidth ?? DEFAULT_STROKE_WIDTH, opacity: 1
+                    }
+                }])
+        ]);
+        this.title = document.title;
+        const beats = [];
+        let state = this.initial;
+        let focus = null;
+        let startMs = 0;
+        let caption = document.title;
+        for (const scene of document.scenes) {
+            scene.beats.forEach((beat, index) => {
+                // Copy the index, then replace changed objects/values so earlier beat snapshots retain their original state.
+                const after = new Map(state);
+                const focusBefore = focus;
+                const flows = [];
+                for (const action of beat.actions) {
+                    if (action.type === "flow") {
+                        flows.push({ target: action.target, direction: action.direction, ...(action.text !== undefined ? { text: action.text } : {}) });
+                        continue;
+                    }
+                    if (action.type === "focus") {
+                        focus = action.target;
+                        continue;
+                    }
+                    const previous = after.get(action.target);
+                    if (!previous)
+                        continue;
+                    if (action.type === "updateNode" || action.type === "updateEdge") {
+                        // Content and label share one display mode. Clear the other value in the snapshot,
+                        // including content:null, so later beats cannot revive historical text.
+                        const modeReset = action.type !== "updateNode" ? {}
+                            : Object.hasOwn(action.value, "content") ? { label: undefined }
+                                : Object.hasOwn(action.value, "label") ? { content: undefined } : {};
+                        after.set(action.target, { ...previous, values: { ...previous.values, ...modeReset, ...action.value } });
+                    }
+                    else {
+                        after.set(action.target, action.type === "show" || action.type === "hide"
+                            ? { ...previous, visible: action.type === "show" }
+                            : { ...previous, highlighted: action.type === "highlight" });
+                    }
+                }
+                caption = beat.caption ?? caption;
+                const endMs = startMs + beat.durationMs;
+                beats.push({ startMs, endMs, transitionMs: beat.transitionMs ?? Math.min(DEFAULT_TRANSITION_MS, beat.durationMs), sceneId: scene.id, beatId: `${scene.id}:${index}`, caption, focusBefore, focusAfter: focus, before: state, after, flows });
+                state = after;
+                startMs = endMs;
+            });
+        }
+        this.beats = beats;
+        this.totalDuration = startMs;
+    }
+    /** Clamp finite times globally; reduced motion skips interpolation but preserves beat selection and total duration. */
+    evaluateAt(timeMs, options, palette) {
+        const time = Number.isFinite(timeMs) ? Math.max(0, Math.min(timeMs, this.totalDuration)) : 0;
+        const beat = this.findBeat(time);
+        const progress = !beat || options.reducedMotion || beat.transitionMs === 0 ? 1 : easeInOutCubic(Math.min(1, (time - beat.startMs) / beat.transitionMs));
+        const before = beat?.before ?? this.initial;
+        const after = beat?.after ?? this.initial;
+        const objects = new Map([...after].map(([id, target]) => {
+            const source = before.get(id) ?? target;
+            const values = interpolateValues(source, target, progress, palette);
+            const visibilityOpacity = Number(source.visible) + (Number(target.visible) - Number(source.visible)) * progress;
+            return [id, {
+                    values,
+                    // Reveals block routing from their start; hides remain obstacles until complete. Hit tests also check opacity.
+                    visible: target.visible || (source.visible && progress < 1),
+                    opacity: Math.min(values.opacity ?? 1, visibilityOpacity),
+                    highlighted: target.highlighted,
+                    highlight: Number(source.highlighted) + (Number(target.highlighted) - Number(source.highlighted)) * progress
+                }];
+        }));
+        return {
+            timeMs: time,
+            sceneId: beat?.sceneId ?? null,
+            beatId: beat?.beatId ?? null,
+            beatProgress: beat ? (time - beat.startMs) / (beat.endMs - beat.startMs) : 0,
+            transitionProgress: progress,
+            focusBefore: beat?.focusBefore ?? null,
+            focusAfter: beat?.focusAfter ?? null,
+            caption: beat?.caption ?? this.title,
+            objects,
+            flows: beat && time < beat.endMs ? beat.flows : []
+        };
+    }
+    /** Select the next beat at endMs, retaining the last beat at total duration; static documents return undefined. */
+    findBeat(timeMs) {
+        let low = 0;
+        let high = this.beats.length - 1;
+        while (low < high) {
+            const middle = Math.floor((low + high) / 2);
+            if (timeMs < this.beats[middle].endMs)
+                high = middle;
+            else
+                low = middle + 1;
+        }
+        return this.beats[low];
+    }
+}
+function easeInOutCubic(progress) {
+    return progress < 0.5 ? 4 * progress ** 3 : 1 - (-2 * progress + 2) ** 3 / 2;
+}
+/**
+ * Labels and whole node content take target values immediately; numbers/colors interpolate, returning exact values at endpoints.
+ * Interpolate base colors here; the core applies the highlight overlay afterward.
+ */
+function interpolateValues(source, target, progress, palette) {
+    if (progress === 0)
+        return { ...source.values, label: target.values.label, content: target.values.content };
+    if (progress === 1)
+        return { ...target.values };
+    const numericValues = Object.fromEntries(NUMERIC_VISUAL_FIELDS.flatMap((key) => {
+        const from = source.values[key];
+        const to = target.values[key];
+        // Weighted sums avoid overflow from subtracting widely separated finite endpoints first.
+        return from === undefined || to === undefined ? [] : [[key, from * (1 - progress) + to * progress]];
+    }));
+    const strokeFallback = target.kind === "node" ? palette.stroke : palette.edge;
+    return {
+        ...target.values,
+        ...numericValues,
+        fill: mixColor(source.values.fill ?? palette.fill, target.values.fill ?? palette.fill, progress),
+        stroke: mixColor(source.values.stroke ?? strokeFallback, target.values.stroke ?? strokeFallback, progress)
+    };
+}

package/dist/core/validation.d.ts

@@ -0,0 +1,11 @@
+import type { ValidationIssue } from "./model.js";
+/** 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[];

package/dist/core/validation.js

@@ -0,0 +1,389 @@
+/** Validate document fields, references and action conflicts without mutating input; content rules stay shared. */
+import { supportsNodeContent, validateNodeContent } from "./node-content.js";
+/** Compilation error for invalid documents; issues contains all field problems found by validation. */
+export class DiagramValidationError extends Error {
+    issues;
+    constructor(issues) {
+        super(`Invalid diagram document (${issues.length} issue${issues.length === 1 ? "" : "s"})`);
+        this.name = "DiagramValidationError";
+        this.issues = issues;
+    }
+}
+/**
+ * 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 function validateDocument(input) {
+    const issues = [];
+    if (!isRecord(input)) {
+        return [{ path: "$", message: "document must be an object" }];
+    }
+    validateUnknownFields(input, ["version", "title", "viewport", "theme", "nodes", "edges", "scenes"], "$", issues);
+    if (input.version !== 1)
+        issues.push({ path: "version", message: "must be 1" });
+    if (input.title !== undefined && typeof input.title !== "string")
+        issues.push({ path: "title", message: "must be a string" });
+    if (input.theme !== undefined && input.theme !== "light" && input.theme !== "dark")
+        issues.push({ path: "theme", message: "must be light or dark" });
+    const viewport = input.viewport;
+    if (!isRecord(viewport)) {
+        issues.push({ path: "viewport", message: "must be an object" });
+    }
+    else {
+        validateUnknownFields(viewport, ["width", "height"], "viewport", issues);
+        validatePositiveFinite(viewport.width, "viewport.width", issues);
+        validatePositiveFinite(viewport.height, "viewport.height", issues);
+    }
+    if (!Array.isArray(input.nodes))
+        issues.push({ path: "nodes", message: "must be an array" });
+    if (!Array.isArray(input.edges))
+        issues.push({ path: "edges", message: "must be an array" });
+    if (!Array.isArray(input.scenes))
+        issues.push({ path: "scenes", message: "must be an array" });
+    const nodes = Array.isArray(input.nodes) ? input.nodes : [];
+    const edges = Array.isArray(input.edges) ? input.edges : [];
+    const scenes = Array.isArray(input.scenes) ? input.scenes : [];
+    validateDenseArray(nodes, "nodes", issues);
+    validateDenseArray(edges, "edges", issues);
+    validateDenseArray(scenes, "scenes", issues);
+    const ids = new Set();
+    nodes.forEach((node, index) => {
+        const path = `nodes[${index}]`;
+        if (!isRecord(node)) {
+            issues.push({ path, message: "must be an object" });
+            return;
+        }
+        validateUnknownFields(node, ["id", "kind", "x", "y", "width", "height", "label", "content", "parentId", "visible", "style"], path, issues);
+        if (!isNonEmptyString(node.id))
+            issues.push({ path: `${path}.id`, message: "must be a non-empty string" });
+        else if (ids.has(node.id))
+            issues.push({ path: `${path}.id`, message: `duplicate id \"${node.id}\"` });
+        else
+            ids.add(node.id);
+        if (!isNodeKind(node.kind))
+            issues.push({ path: `${path}.kind`, message: "must be a supported node kind" });
+        validateFinite(node.x, `${path}.x`, issues);
+        validateFinite(node.y, `${path}.y`, issues);
+        validatePositiveFinite(node.width, `${path}.width`, issues);
+        validatePositiveFinite(node.height, `${path}.height`, issues);
+        if (node.label !== undefined && typeof node.label !== "string")
+            issues.push({ path: `${path}.label`, message: "must be a string" });
+        if (node.content !== undefined) {
+            validateNodeContent(node.content, `${path}.content`, issues);
+            if (node.label !== undefined)
+                issues.push({ path: `${path}.content`, message: "must not be declared together with label" });
+            if (!supportsNodeContent(node.kind))
+                issues.push({ path: `${path}.content`, message: "requires a rect, roundedRect or cylinder node" });
+        }
+        if (node.parentId !== undefined && !isNonEmptyString(node.parentId))
+            issues.push({ path: `${path}.parentId`, message: "must be a non-empty string" });
+        if (node.visible !== undefined && typeof node.visible !== "boolean")
+            issues.push({ path: `${path}.visible`, message: "must be a boolean" });
+        validateNodeStyle(node.style, `${path}.style`, issues);
+    });
+    const nodeById = new Map();
+    nodes.forEach((node) => {
+        if (isRecord(node) && isNonEmptyString(node.id))
+            nodeById.set(node.id, node);
+    });
+    nodes.forEach((node, index) => {
+        if (isRecord(node) && node.parentId !== undefined && isNonEmptyString(node.parentId)) {
+            const parent = nodeById.get(node.parentId);
+            if (!parent)
+                issues.push({ path: `nodes[${index}].parentId`, message: "must reference an existing node" });
+            else if (parent.kind !== "group")
+                issues.push({ path: `nodes[${index}].parentId`, message: "must reference a group node" });
+        }
+    });
+    validateParentCycles(nodes, nodeById, issues);
+    const edgeById = new Map();
+    edges.forEach((edge, index) => {
+        const path = `edges[${index}]`;
+        if (!isRecord(edge)) {
+            issues.push({ path, message: "must be an object" });
+            return;
+        }
+        validateUnknownFields(edge, ["id", "from", "to", "label", "route", "fromPort", "toPort", "visible", "style"], path, issues);
+        if (!isNonEmptyString(edge.id))
+            issues.push({ path: `${path}.id`, message: "must be a non-empty string" });
+        else if (ids.has(edge.id))
+            issues.push({ path: `${path}.id`, message: `duplicate id \"${edge.id}\"` });
+        else {
+            ids.add(edge.id);
+            edgeById.set(edge.id, edge);
+        }
+        validateEdgeEndpoint(edge.from, `${path}.from`, nodeById, issues);
+        validateEdgeEndpoint(edge.to, `${path}.to`, nodeById, issues);
+        if (edge.label !== undefined && typeof edge.label !== "string")
+            issues.push({ path: `${path}.label`, message: "must be a string" });
+        if (edge.route !== undefined && edge.route !== "straight" && edge.route !== "orthogonal" && edge.route !== "curved")
+            issues.push({ path: `${path}.route`, message: "must be straight, orthogonal or curved" });
+        if (edge.fromPort !== undefined && !isPortDirection(edge.fromPort))
+            issues.push({ path: `${path}.fromPort`, message: "must be top, right, bottom or left" });
+        if (edge.toPort !== undefined && !isPortDirection(edge.toPort))
+            issues.push({ path: `${path}.toPort`, message: "must be top, right, bottom or left" });
+        if (edge.visible !== undefined && typeof edge.visible !== "boolean")
+            issues.push({ path: `${path}.visible`, message: "must be a boolean" });
+        validateEdgeStyle(edge.style, `${path}.style`, issues);
+    });
+    const allIds = new Set([...nodeById.keys(), ...edgeById.keys()]);
+    const sceneIds = new Set();
+    scenes.forEach((scene, sceneIndex) => {
+        const path = `scenes[${sceneIndex}]`;
+        if (!isRecord(scene)) {
+            issues.push({ path, message: "must be an object" });
+            return;
+        }
+        validateUnknownFields(scene, ["id", "label", "beats"], path, issues);
+        if (!isNonEmptyString(scene.id))
+            issues.push({ path: `${path}.id`, message: "must be a non-empty string" });
+        else if (sceneIds.has(scene.id))
+            issues.push({ path: `${path}.id`, message: `duplicate id \"${scene.id}\"` });
+        else
+            sceneIds.add(scene.id);
+        if (!isNonEmptyString(scene.label))
+            issues.push({ path: `${path}.label`, message: "must be a non-empty string" });
+        if (!Array.isArray(scene.beats))
+            issues.push({ path: `${path}.beats`, message: "must be an array" });
+        else {
+            validateDenseArray(scene.beats, `${path}.beats`, issues);
+            if (scene.beats.length === 0)
+                issues.push({ path: `${path}.beats`, message: "must contain at least one beat" });
+            scene.beats.forEach((beat, beatIndex) => validateBeat(beat, `${path}.beats[${beatIndex}]`, allIds, nodeById, edgeById, issues));
+        }
+    });
+    return issues;
+}
+function isRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0;
+}
+function isNodeKind(value) {
+    return value === "rect" || value === "roundedRect" || value === "ellipse" || value === "cylinder" || value === "group";
+}
+function isPortDirection(value) {
+    return value === "top" || value === "right" || value === "bottom" || value === "left";
+}
+function validateFinite(value, path, issues) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        issues.push({ path, message: "must be a finite number" });
+}
+function validatePositiveFinite(value, path, issues) {
+    validateFinite(value, path, issues);
+    if (typeof value === "number" && Number.isFinite(value) && value <= 0)
+        issues.push({ path, message: "must be greater than zero" });
+}
+function validateNonNegativeFinite(value, path, issues) {
+    validateFinite(value, path, issues);
+    if (typeof value === "number" && Number.isFinite(value) && value < 0)
+        issues.push({ path, message: "must be zero or greater" });
+}
+function validateUnknownFields(record, allowed, path, issues) {
+    const allowedFields = new Set(allowed);
+    for (const key of Object.keys(record))
+        if (!allowedFields.has(key))
+            issues.push({ path: path === "$" ? key : `${path}.${key}`, message: "unknown field" });
+}
+function validateDenseArray(values, path, issues) {
+    for (let index = 0; index < values.length; index += 1)
+        if (!(index in values))
+            issues.push({ path: `${path}[${index}]`, message: "must be a value" });
+}
+/** Restrict colors to interpolable hexadecimal data, excluding CSS expressions and external resource references. */
+function validateColor(value, path, issues) {
+    if (typeof value !== "string" || !/^#(?:[\da-f]{3}|[\da-f]{4}|[\da-f]{6}|[\da-f]{8})$/i.test(value))
+        issues.push({ path, message: "must be a hexadecimal color" });
+}
+function validateNodeStyle(style, path, issues) {
+    if (style === undefined)
+        return;
+    if (!isRecord(style)) {
+        issues.push({ path, message: "must be an object" });
+        return;
+    }
+    validateUnknownFields(style, ["fill", "stroke", "strokeWidth", "textColor", "dashed"], path, issues);
+    for (const key of ["fill", "stroke", "textColor"])
+        if (style[key] !== undefined)
+            validateColor(style[key], `${path}.${key}`, issues);
+    if (style.strokeWidth !== undefined)
+        validateNonNegativeFinite(style.strokeWidth, `${path}.strokeWidth`, issues);
+    if (style.dashed !== undefined && typeof style.dashed !== "boolean")
+        issues.push({ path: `${path}.dashed`, message: "must be a boolean" });
+}
+function validateEdgeStyle(style, path, issues) {
+    if (style === undefined)
+        return;
+    if (!isRecord(style)) {
+        issues.push({ path, message: "must be an object" });
+        return;
+    }
+    validateUnknownFields(style, ["stroke", "strokeWidth", "dashed"], path, issues);
+    if (style.stroke !== undefined)
+        validateColor(style.stroke, `${path}.stroke`, issues);
+    if (style.strokeWidth !== undefined)
+        validateNonNegativeFinite(style.strokeWidth, `${path}.strokeWidth`, issues);
+    if (style.dashed !== undefined && typeof style.dashed !== "boolean")
+        issues.push({ path: `${path}.dashed`, message: "must be a boolean" });
+}
+function validateEdgeEndpoint(value, path, nodeById, issues) {
+    if (!isNonEmptyString(value)) {
+        issues.push({ path, message: "must reference an existing node" });
+        return;
+    }
+    const node = nodeById.get(value);
+    if (!node)
+        issues.push({ path, message: "must reference an existing node" });
+}
+/** Reject parent cycles at load time so later position and visibility recursion terminates. */
+function validateParentCycles(nodes, nodeById, issues) {
+    const reported = new Set();
+    for (const [id, node] of nodeById) {
+        const chain = new Set();
+        let current = id;
+        while (current) {
+            if (chain.has(current)) {
+                const index = nodes.findIndex((candidate) => isRecord(candidate) && candidate.id === id);
+                const path = index >= 0 ? `nodes[${index}].parentId` : "nodes.parentId";
+                if (!reported.has(path)) {
+                    issues.push({ path, message: "group parent references form a cycle" });
+                    reported.add(path);
+                }
+                break;
+            }
+            chain.add(current);
+            const parentValue = nodeById.get(current)?.parentId;
+            current = isNonEmptyString(parentValue) ? parentValue : undefined;
+        }
+    }
+}
+/** Track assignment keys per beat: allow different fields on one target but reject duplicate writes to a field. */
+function validateBeat(beat, path, allIds, nodeById, edgeById, issues) {
+    if (!isRecord(beat)) {
+        issues.push({ path, message: "must be an object" });
+        return;
+    }
+    validateUnknownFields(beat, ["durationMs", "transitionMs", "caption", "actions"], path, issues);
+    validatePositiveFinite(beat.durationMs, `${path}.durationMs`, issues);
+    if (beat.transitionMs !== undefined) {
+        validateNonNegativeFinite(beat.transitionMs, `${path}.transitionMs`, issues);
+        if (typeof beat.durationMs === "number" && Number.isFinite(beat.durationMs) && typeof beat.transitionMs === "number" && Number.isFinite(beat.transitionMs) && beat.transitionMs > beat.durationMs)
+            issues.push({ path: `${path}.transitionMs`, message: "must not exceed durationMs" });
+    }
+    if (beat.caption !== undefined && typeof beat.caption !== "string")
+        issues.push({ path: `${path}.caption`, message: "must be a string" });
+    if (!Array.isArray(beat.actions)) {
+        issues.push({ path: `${path}.actions`, message: "must be an array" });
+        return;
+    }
+    validateDenseArray(beat.actions, `${path}.actions`, issues);
+    const assignments = new Set();
+    beat.actions.forEach((action, index) => validateAction(action, `${path}.actions[${index}]`, allIds, nodeById, edgeById, assignments, issues));
+}
+/** Validate fields/targets by action kind; visibility and highlight keys are separate from ordinary style updates. */
+function validateAction(action, path, allIds, nodeById, edgeById, assignments, issues) {
+    if (!isRecord(action)) {
+        issues.push({ path, message: "must be an object" });
+        return;
+    }
+    if (typeof action.type !== "string") {
+        issues.push({ path: `${path}.type`, message: "must be a supported action" });
+        return;
+    }
+    const type = action.type;
+    const allowedByType = {
+        show: ["type", "target"], hide: ["type", "target"], highlight: ["type", "target"], unhighlight: ["type", "target"],
+        updateNode: ["type", "target", "value"], updateEdge: ["type", "target", "value"], focus: ["type", "target"],
+        flow: ["type", "target", "direction", "text"]
+    };
+    const allowed = Object.hasOwn(allowedByType, type) ? allowedByType[type] : undefined;
+    if (!allowed) {
+        issues.push({ path: `${path}.type`, message: "unknown action" });
+        return;
+    }
+    validateUnknownFields(action, allowed, path, issues);
+    if (["show", "hide", "highlight", "unhighlight"].includes(type)) {
+        if (!isNonEmptyString(action.target)) {
+            issues.push({ path: `${path}.target`, message: "must reference an existing object" });
+            return;
+        }
+        if (!allIds.has(action.target))
+            issues.push({ path: `${path}.target`, message: "must reference an existing object" });
+        addAssignment(`${type === "show" || type === "hide" ? "visibility" : "highlight"}:${action.target}`, path, assignments, issues);
+        return;
+    }
+    if (type === "focus") {
+        if (action.target !== null && (!isNonEmptyString(action.target) || !nodeById.has(action.target)))
+            issues.push({ path: `${path}.target`, message: "must reference a node or group" });
+        if (action.target === null || (isNonEmptyString(action.target) && nodeById.has(action.target)))
+            addAssignment("focus", path, assignments, issues);
+        return;
+    }
+    if (type === "flow") {
+        if (!isNonEmptyString(action.target))
+            issues.push({ path: `${path}.target`, message: "must reference an existing edge" });
+        else if (!edgeById.has(action.target))
+            issues.push({ path: `${path}.target`, message: "must reference an existing edge" });
+        if (action.direction !== "forward" && action.direction !== "reverse")
+            issues.push({ path: `${path}.direction`, message: "must be forward or reverse" });
+        if (action.text !== undefined && typeof action.text !== "string")
+            issues.push({ path: `${path}.text`, message: "must be a string" });
+        // Reserve the edge independently of other field errors so invalid directions cannot hide duplicate transfers.
+        if (isNonEmptyString(action.target) && edgeById.has(action.target))
+            addAssignment(`flow:${action.target}`, `${path}.target`, assignments, issues);
+        return;
+    }
+    if (!isNonEmptyString(action.target)) {
+        issues.push({ path: `${path}.target`, message: `must reference a ${type === "updateNode" ? "node" : "edge"}` });
+    }
+    else if (type === "updateNode" ? !nodeById.has(action.target) : !edgeById.has(action.target))
+        issues.push({ path: `${path}.target`, message: `must reference an existing ${type === "updateNode" ? "node" : "edge"}` });
+    validateUpdateValue(action.value, `${path}.value`, type === "updateNode", assignments, action.target, issues);
+    const targetNode = typeof action.target === "string" ? nodeById.get(action.target) : undefined;
+    if (type === "updateNode" && targetNode && isRecord(action.value) && action.value.content !== undefined && action.value.content !== null && !supportsNodeContent(targetNode.kind)) {
+        issues.push({ path: `${path}.value.content`, message: "requires a rect, roundedRect or cylinder node" });
+    }
+}
+function validateUpdateValue(value, path, isNode, assignments, target, issues) {
+    if (!isRecord(value)) {
+        issues.push({ path, message: "must be an object" });
+        return;
+    }
+    const allowed = isNode ? ["x", "y", "width", "height", "label", "content", "fill", "stroke", "opacity"] : ["label", "stroke", "strokeWidth", "opacity"];
+    validateUnknownFields(value, allowed, path, issues);
+    if (isNode && Object.hasOwn(value, "label") && Object.hasOwn(value, "content")) {
+        issues.push({ path: `${path}.content`, message: "must not be declared together with label" });
+    }
+    for (const key of Object.keys(value)) {
+        if (!allowed.includes(key))
+            continue;
+        // Both node text fields replace the same display mode, even across separate actions.
+        const assignmentField = isNode && (key === "label" || key === "content") ? "text-mode" : key;
+        addAssignment(`${isNode ? "node" : "edge"}:${String(target)}:${assignmentField}`, `${path}.${key}`, assignments, issues);
+        const field = value[key];
+        if (["x", "y", "width", "height", "opacity"].includes(key))
+            validateFinite(field, `${path}.${key}`, issues);
+        if (key === "strokeWidth")
+            validateNonNegativeFinite(field, `${path}.${key}`, issues);
+        if (["width", "height"].includes(key) && typeof field === "number" && field <= 0)
+            issues.push({ path: `${path}.${key}`, message: "must be greater than zero" });
+        if (key === "opacity" && typeof field === "number" && (field < 0 || field > 1))
+            issues.push({ path: `${path}.${key}`, message: "must be between zero and one" });
+        if (["fill", "stroke"].includes(key))
+            validateColor(field, `${path}.${key}`, issues);
+        if (key === "label" && typeof field !== "string")
+            issues.push({ path: `${path}.${key}`, message: "must be a string" });
+        if (key === "content" && field !== null)
+            validateNodeContent(field, `${path}.${key}`, issues);
+    }
+}
+function addAssignment(key, path, assignments, issues) {
+    if (assignments.has(key))
+        issues.push({ path, message: "duplicate beat assignment" });
+    else
+        assignments.add(key);
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { createDiagram, renderSvg, wrapText } from "./core/diagram.js";
+export type { Diagram } from "./core/diagram.js";
+export { validateDocument, DiagramValidationError } from "./core/validation.js";
+export type { NodeKind, EdgeRoute, PortDirection, FlowDirection, ThemeName, Viewport, NodeStyle, EdgeStyle, DiagramNode, DiagramEdge, DiagramDocument, Scene, Beat, NodeVisualState, EdgeVisualState, Action, ValidationIssue, EvaluateOptions, TextLine, EvaluatedNode, EvaluatedEdge, EdgeFlowMarker, LayoutWarning, CameraState, HitObjectType, HitObject, DiagramPoint, DiagramFrameState } from "./core/model.js";
+export type { NodeContent, ContentBlock, ContentListItem, ContentListStyle, ContentTag, ContentTagStyle, ContentTagBackground, ContentGraphBlock, ContentGraphNode, ContentGraphEdge, ContentGraphLayout, ContentText, ContentTextSpan, ContentSpanStyle, ContentSpan, ContentTextStyle, ContentAlignment, ContentSafeArea, ContentLine, NodeContentLayout } from "./core/node-content.js";

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createDiagram, renderSvg, wrapText } from "./core/diagram.js";
+export { validateDocument, DiagramValidationError } from "./core/validation.js";

package/dist/react.d.ts

@@ -0,0 +1,3 @@
+/** Public React adapter entry. */
+export { FlowPlayer } from "./adapters/react.js";
+export type { FlowPlayerHandle, FlowPlayerProps } from "./adapters/react.js";

package/dist/react.js

@@ -0,0 +1,2 @@
+/** Public React adapter entry. */
+export { FlowPlayer } from "./adapters/react.js";

package/dist/styles.css

@@ -0,0 +1,47 @@
+/* Control and canvas focus styles; CSS variables customize controls only. The core theme resolves diagram colors. */
+.flowsvg-canvas:focus-visible {
+  outline: 3px solid #2563eb;
+  outline-offset: 3px;
+}
+
+.flowsvg-controls {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.75rem;
+  color: var(--flowsvg-control-color, #172033);
+  background: var(--flowsvg-control-background, #ffffff);
+  font: 1rem/1.4 system-ui, sans-serif;
+}
+
+.flowsvg-controls :is(button, input, select) {
+  box-sizing: border-box;
+  min-height: 2.75rem;
+  max-width: 100%;
+  color: var(--flowsvg-control-color, #172033);
+  background: var(--flowsvg-control-background, #ffffff);
+  border: 1px solid var(--flowsvg-control-border, #64748b);
+  border-radius: 0.25rem;
+  font: inherit;
+  accent-color: var(--flowsvg-control-accent, #2563eb);
+}
+
+.flowsvg-controls :is(button, select) {
+  padding: 0.5rem 0.75rem;
+}
+
+.flowsvg-controls :is(button, input, select):focus-visible {
+  outline: 3px solid var(--flowsvg-control-focus, #2563eb);
+  outline-offset: 3px;
+}
+
+.flowsvg-controls :disabled {
+  opacity: 0.55;
+  cursor: default;
+}
+
+.flowsvg-controls input[type="range"] {
+  flex: 1 1 10rem;
+  min-width: 4rem;
+}

package/dist/vue.d.ts

@@ -0,0 +1,3 @@
+/** Public Vue adapter entry. */
+export { FlowPlayer } from "./adapters/vue.js";
+export type { FlowPlayerHandle, FlowPlayerProps } from "./adapters/vue.js";

package/dist/vue.js

@@ -0,0 +1,2 @@
+/** Public Vue adapter entry. */
+export { FlowPlayer } from "./adapters/vue.js";

package/dist/web-component.d.ts

@@ -0,0 +1,3 @@
+/** Public Web Component entry. */
+export { FLOW_PLAYER_TAG, FlowPlayerElement, defineFlowPlayer } from "./adapters/web-component.js";
+export type { FlowPlayerElementErrorDetail, FlowPlayerElementOptions } from "./adapters/web-component.js";

package/dist/web-component.js

@@ -0,0 +1,2 @@
+/** Public Web Component entry. */
+export { FLOW_PLAYER_TAG, FlowPlayerElement, defineFlowPlayer } from "./adapters/web-component.js";