flowsvg 0.0.0-stage → 0.1.1

package/dist/core/edge-geometry.js

@@ -0,0 +1,382 @@
+/**
+ * Platform-independent edge geometry. This module owns routing, sampled path
+ * distance, label anchors and line hit testing; diagram evaluation owns the
+ * surrounding frame state and consumes this internal interface.
+ */
+import { formatNumber } from "./svg-number.js";
+function straightPoints(from, to) {
+    const fromCenter = { x: from.x + from.width / 2, y: from.y + from.height / 2 };
+    const toCenter = { x: to.x + to.width / 2, y: to.y + to.height / 2 };
+    const start = boundaryPoint(from, toCenter);
+    const end = boundaryPoint(to, fromCenter);
+    return [start, end];
+}
+const ROUTING_GAP = 8;
+const FOCUS_PADDING = 24;
+const HIT_TOLERANCE = 6;
+export function emptyPathGeometry() {
+    return createPathGeometry([]);
+}
+function createPathGeometry(points, serializedPath) {
+    const compact = simplifyPoints(points);
+    const path = serializedPath ?? pointsToPath(compact);
+    const segments = compact.slice(1).map((end, index) => ({ start: compact[index], end, length: Math.hypot(end.x - compact[index].x, end.y - compact[index].y) }));
+    const length = segments.reduce((total, segment) => total + segment.length, 0);
+    const xs = compact.map((point) => point.x);
+    const ys = compact.map((point) => point.y);
+    const bounds = xs.length === 0
+        ? { left: 0, top: 0, right: 0, bottom: 0 }
+        : { left: Math.min(...xs), top: Math.min(...ys), right: Math.max(...xs), bottom: Math.max(...ys) };
+    return {
+        path,
+        points: compact,
+        length: length || 1,
+        bounds,
+        pointAt(progress) {
+            if (compact.length === 0)
+                return { x: 0, y: 0 };
+            if (compact.length === 1 || length === 0)
+                return compact[0];
+            const distance = Math.min(1, Math.max(0, progress)) * length;
+            let traversed = 0;
+            for (const segment of segments) {
+                if (distance <= traversed + segment.length) {
+                    const ratio = segment.length === 0 ? 0 : (distance - traversed) / segment.length;
+                    return {
+                        x: segment.start.x + (segment.end.x - segment.start.x) * ratio,
+                        y: segment.start.y + (segment.end.y - segment.start.y) * ratio
+                    };
+                }
+                traversed += segment.length;
+            }
+            return compact.at(-1);
+        }
+    };
+}
+/** Build sampled geometry for a cubic curve while retaining the exact cubic command for SVG output. */
+function createCurveGeometry(start, controlStart, controlEnd, end) {
+    const samples = [];
+    const sampleCount = 32;
+    for (let index = 0; index <= sampleCount; index += 1) {
+        const progress = index / sampleCount;
+        const inverse = 1 - progress;
+        samples.push({
+            x: inverse ** 3 * start.x + 3 * inverse ** 2 * progress * controlStart.x + 3 * inverse * progress ** 2 * controlEnd.x + progress ** 3 * end.x,
+            y: inverse ** 3 * start.y + 3 * inverse ** 2 * progress * controlStart.y + 3 * inverse * progress ** 2 * controlEnd.y + progress ** 3 * end.y
+        });
+    }
+    const path = `M ${formatNumber(start.x)} ${formatNumber(start.y)} C ${formatNumber(controlStart.x)} ${formatNumber(controlStart.y)} ${formatNumber(controlEnd.x)} ${formatNumber(controlEnd.y)} ${formatNumber(end.x)} ${formatNumber(end.y)}`;
+    return createPathGeometry(samples, path);
+}
+/** Build a two-segment cubic route used for opposite relationships; endpoint tangents remain exact port normals. */
+function createSeparatedCurveGeometry(start, controlStart, midpoint, controlMidStart, controlMidEnd, controlEnd, end) {
+    const samples = [];
+    const sampleSegment = (first, firstControl, secondControl, last) => {
+        for (let index = 0; index <= 16; index += 1) {
+            if (samples.length > 0 && index === 0)
+                continue;
+            const progress = index / 16;
+            const inverse = 1 - progress;
+            samples.push({
+                x: inverse ** 3 * first.x + 3 * inverse ** 2 * progress * firstControl.x + 3 * inverse * progress ** 2 * secondControl.x + progress ** 3 * last.x,
+                y: inverse ** 3 * first.y + 3 * inverse ** 2 * progress * firstControl.y + 3 * inverse * progress ** 2 * secondControl.y + progress ** 3 * last.y
+            });
+        }
+    };
+    sampleSegment(start, controlStart, controlMidStart, midpoint);
+    sampleSegment(midpoint, controlMidEnd, controlEnd, end);
+    const path = `M ${formatNumber(start.x)} ${formatNumber(start.y)} C ${formatNumber(controlStart.x)} ${formatNumber(controlStart.y)} ${formatNumber(controlMidStart.x)} ${formatNumber(controlMidStart.y)} ${formatNumber(midpoint.x)} ${formatNumber(midpoint.y)} C ${formatNumber(controlMidEnd.x)} ${formatNumber(controlMidEnd.y)} ${formatNumber(controlEnd.x)} ${formatNumber(controlEnd.y)} ${formatNumber(end.x)} ${formatNumber(end.y)}`;
+    return createPathGeometry(samples, path);
+}
+export function isPointNearPath(point, geometry, tolerance) {
+    for (let index = 1; index < geometry.points.length; index += 1)
+        if (distanceToSegment(point, geometry.points[index - 1], geometry.points[index]) <= tolerance)
+            return true;
+    return false;
+}
+function distanceToSegment(point, start, end) {
+    const dx = end.x - start.x;
+    const dy = end.y - start.y;
+    if (dx === 0 && dy === 0)
+        return Math.hypot(point.x - start.x, point.y - start.y);
+    const factor = Math.max(0, Math.min(1, ((point.x - start.x) * dx + (point.y - start.y) * dy) / (dx * dx + dy * dy)));
+    return Math.hypot(point.x - (start.x + factor * dx), point.y - (start.y + factor * dy));
+}
+/**
+ * Automatic orthogonal routing excludes endpoints and group frames from obstacles.
+ * Explicit orthogonal ports reserve outward stubs and route around endpoint bodies as well.
+ * Routing uses visible separately from paint opacity: reveals block immediately, and hides block until completion.
+ */
+export function routeEdge(edge, from, to, nodes, reverseOffset = 0) {
+    if (edge.route === "curved") {
+        const automatic = automaticPorts(from, to);
+        const fromDirection = edge.fromPort ?? automatic.from;
+        const toDirection = edge.toPort ?? automatic.to;
+        const start = portPoint(from, fromDirection);
+        const end = portPoint(to, toDirection);
+        return curvedPath(start, end, fromDirection, toDirection, reverseOffset);
+    }
+    if (edge.route !== "orthogonal") {
+        const points = edge.fromPort || edge.toPort
+            ? [portPoint(from, edge.fromPort ?? automaticPorts(from, to).from), portPoint(to, edge.toPort ?? automaticPorts(from, to).to)]
+            : straightPoints(from, to);
+        return createPathGeometry(points);
+    }
+    const { start, end } = orthogonalAttachments(from, to, edge.fromPort, edge.toPort);
+    const obstacles = nodes
+        .filter((node) => node.visible && node.kind !== "group" && node.id !== from.id && node.id !== to.id)
+        .map(routingBounds);
+    if (edge.fromPort || edge.toPort)
+        return createPathGeometry(explicitOrthogonalPath(edge, from, to, obstacles));
+    return createPathGeometry(orthogonalPath(start, end, obstacles));
+}
+function routingBounds(node) {
+    return {
+        left: node.x - ROUTING_GAP,
+        top: node.y - ROUTING_GAP,
+        right: node.x + node.width + ROUTING_GAP,
+        bottom: node.y + node.height + ROUTING_GAP
+    };
+}
+/** Reserve endpoint-normal segments before grid search so a backside port cannot route through its own node. */
+function explicitOrthogonalPath(edge, from, to, obstacles) {
+    const automatic = automaticPorts(from, to);
+    const fromDirection = edge.fromPort ?? automatic.from;
+    const toDirection = edge.toPort ?? automatic.to;
+    const start = portPoint(from, fromDirection);
+    const end = portPoint(to, toDirection);
+    const fromNormal = portNormal(fromDirection);
+    const toNormal = portNormal(toDirection);
+    const startStub = { x: start.x + fromNormal.x * ROUTING_GAP, y: start.y + fromNormal.y * ROUTING_GAP };
+    const endStub = { x: end.x + toNormal.x * ROUTING_GAP, y: end.y + toNormal.y * ROUTING_GAP };
+    const middle = orthogonalPath(startStub, endStub, [...obstacles, routingBounds(from), routingBounds(to)]);
+    return [start, ...middle, end];
+}
+/** Choose rectangular attachment sides along the dominant center-to-center axis for orthogonal connections. */
+function orthogonalAttachments(from, to, fromPort, toPort) {
+    const automatic = automaticPorts(from, to);
+    return {
+        start: portPoint(from, fromPort ?? automatic.from),
+        end: portPoint(to, toPort ?? automatic.to)
+    };
+}
+/** Select cardinal sides from the dominant center-to-center axis for automatic routes. */
+function automaticPorts(from, to) {
+    const fromCenter = { x: from.x + from.width / 2, y: from.y + from.height / 2 };
+    const toCenter = { x: to.x + to.width / 2, y: to.y + to.height / 2 };
+    const horizontal = Math.abs(toCenter.x - fromCenter.x) >= Math.abs(toCenter.y - fromCenter.y);
+    if (horizontal) {
+        const right = toCenter.x >= fromCenter.x;
+        return { from: right ? "right" : "left", to: right ? "left" : "right" };
+    }
+    const bottom = toCenter.y >= fromCenter.y;
+    return { from: bottom ? "bottom" : "top", to: bottom ? "top" : "bottom" };
+}
+/** Return the actual outline point for a cardinal side, including ellipse contours. */
+function portPoint(node, direction) {
+    const center = { x: node.x + node.width / 2, y: node.y + node.height / 2 };
+    if (direction === "top")
+        return { x: center.x, y: node.y };
+    if (direction === "right")
+        return { x: node.x + node.width, y: center.y };
+    if (direction === "bottom")
+        return { x: center.x, y: node.y + node.height };
+    return { x: node.x, y: center.y };
+}
+/** Generate a smooth cubic route whose endpoint tangents follow port normals. */
+function curvedPath(start, end, fromDirection, toDirection, separation) {
+    const distance = Math.hypot(end.x - start.x, end.y - start.y);
+    const tangentLength = Math.max(24, distance * 0.32);
+    const fromNormal = portNormal(fromDirection);
+    const toNormal = portNormal(toDirection);
+    const perpendicular = { x: -(end.y - start.y), y: end.x - start.x };
+    const perpendicularLength = Math.hypot(perpendicular.x, perpendicular.y) || 1;
+    const lane = separation * Math.min(72, Math.max(28, distance * 0.16));
+    if (separation !== 0) {
+        const midpoint = {
+            x: (start.x + end.x) / 2 + perpendicular.x / perpendicularLength * lane,
+            y: (start.y + end.y) / 2 + perpendicular.y / perpendicularLength * lane
+        };
+        const chord = { x: end.x - start.x, y: end.y - start.y };
+        const chordLength = Math.hypot(chord.x, chord.y) || 1;
+        const joinTangent = { x: chord.x / chordLength, y: chord.y / chordLength };
+        return createSeparatedCurveGeometry(start, { x: start.x + fromNormal.x * tangentLength, y: start.y + fromNormal.y * tangentLength }, midpoint, { x: midpoint.x - joinTangent.x * tangentLength * 0.5, y: midpoint.y - joinTangent.y * tangentLength * 0.5 }, { x: midpoint.x + joinTangent.x * tangentLength * 0.5, y: midpoint.y + joinTangent.y * tangentLength * 0.5 }, { x: end.x + toNormal.x * tangentLength, y: end.y + toNormal.y * tangentLength }, end);
+    }
+    const controlStart = {
+        x: start.x + fromNormal.x * tangentLength + perpendicular.x / perpendicularLength * lane,
+        y: start.y + fromNormal.y * tangentLength + perpendicular.y / perpendicularLength * lane
+    };
+    const controlEnd = {
+        x: end.x + toNormal.x * tangentLength + perpendicular.x / perpendicularLength * lane,
+        y: end.y + toNormal.y * tangentLength + perpendicular.y / perpendicularLength * lane
+    };
+    return createCurveGeometry(start, controlStart, controlEnd, end);
+}
+function portNormal(direction) {
+    if (direction === "top")
+        return { x: 0, y: -1 };
+    if (direction === "right")
+        return { x: 1, y: 0 };
+    if (direction === "bottom")
+        return { x: 0, y: 1 };
+    return { x: -1, y: 0 };
+}
+/**
+ * Breadth-first search the grid of endpoints and obstacle boundaries, using fixed neighbor order for determinism.
+ * Grid-step search does not guarantee shortest geometric length or fewest bends; fall back to a fixed elbow if blocked.
+ */
+function orthogonalPath(start, end, obstacles) {
+    const xs = uniqueSorted([start.x, end.x, ...obstacles.flatMap((rect) => [rect.left, rect.right])]);
+    const ys = uniqueSorted([start.y, end.y, ...obstacles.flatMap((rect) => [rect.top, rect.bottom])]);
+    const xIndex = new Map(xs.map((value, index) => [value, index]));
+    const yIndex = new Map(ys.map((value, index) => [value, index]));
+    const startKey = pointKey(start);
+    const endKey = pointKey(end);
+    const queue = [start];
+    const previous = new Map([[startKey, undefined]]);
+    const preferredHorizontal = Math.abs(end.x - start.x) >= Math.abs(end.y - start.y);
+    const directions = preferredHorizontal
+        ? [[1, 0], [0, -1], [0, 1], [-1, 0]]
+        : [[0, 1], [1, 0], [-1, 0], [0, -1]];
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (pointKey(current) === endKey)
+            break;
+        const currentX = xIndex.get(current.x);
+        const currentY = yIndex.get(current.y);
+        if (currentX === undefined || currentY === undefined)
+            continue;
+        for (const [dx, dy] of directions) {
+            const nextX = xs[currentX + dx];
+            const nextY = ys[currentY + dy];
+            if (nextX === undefined || nextY === undefined)
+                continue;
+            const next = { x: nextX, y: nextY };
+            const key = pointKey(next);
+            if (previous.has(key) || isInsideObstacle(next, obstacles) || blockedSegment(current, next, obstacles))
+                continue;
+            previous.set(key, current);
+            queue.push(next);
+        }
+    }
+    const points = [];
+    if (previous.has(endKey)) {
+        let current = end;
+        while (current) {
+            points.push(current);
+            current = previous.get(pointKey(current));
+        }
+        points.reverse();
+    }
+    else {
+        const middle = preferredHorizontal ? { x: end.x, y: start.y } : { x: start.x, y: end.y };
+        points.push(start, middle, end);
+    }
+    return removeMicroTurns(points, obstacles);
+}
+/** Replace tiny obstacle-detour turns with a wider elbow when the replacement remains collision-free. */
+function removeMicroTurns(points, obstacles) {
+    const result = [...points];
+    const minimum = ROUTING_GAP * 2;
+    for (let index = 1; index + 2 < result.length; index += 1) {
+        const before = result[index - 1];
+        const first = result[index];
+        const second = result[index + 1];
+        const after = result[index + 2];
+        const shortLength = Math.abs(second.x - first.x) + Math.abs(second.y - first.y);
+        if (shortLength >= minimum)
+            continue;
+        const candidate = before.x === first.x
+            ? { x: first.x, y: after.y }
+            : { x: after.x, y: first.y };
+        if (isInsideObstacle(candidate, obstacles) || blockedSegment(before, candidate, obstacles) || blockedSegment(candidate, after, obstacles))
+            continue;
+        result.splice(index, 2, candidate);
+        index = Math.max(0, index - 2);
+    }
+    return result;
+}
+/** Remove consecutive duplicates and collinear intermediate points to keep SVG paths compact. */
+function pointsToPath(points) {
+    return simplifyPoints(points).map((point, index) => `${index === 0 ? "M" : "L"} ${formatNumber(point.x)} ${formatNumber(point.y)}`).join(" ");
+}
+/** Keep collinear reversals: removing an extremum would shorten flow distance and truncate path bounds. */
+function simplifyPoints(points) {
+    const compact = [];
+    for (const point of points) {
+        const previous = compact.at(-1);
+        if (!previous || previous.x !== point.x || previous.y !== point.y)
+            compact.push(point);
+    }
+    const simplified = [];
+    for (const point of compact) {
+        const previous = simplified.at(-1);
+        const beforePrevious = simplified.at(-2);
+        const continuesDirection = previous && beforePrevious
+            && (previous.x - beforePrevious.x) * (point.x - previous.x) + (previous.y - beforePrevious.y) * (point.y - previous.y) >= 0;
+        if (previous && beforePrevious && continuesDirection && (beforePrevious.x === previous.x && previous.x === point.x || beforePrevious.y === previous.y && previous.y === point.y)) {
+            simplified[simplified.length - 1] = point;
+        }
+        else {
+            simplified.push(point);
+        }
+    }
+    return simplified;
+}
+/** Obstacles already include ROUTING_GAP; allow boundary contact and reject only segments crossing their interiors. */
+function blockedSegment(start, end, obstacles) {
+    for (const obstacle of obstacles) {
+        if (start.x === end.x) {
+            if (start.x > obstacle.left && start.x < obstacle.right && rangesOverlap(start.y, end.y, obstacle.top, obstacle.bottom))
+                return true;
+        }
+        else if (start.y === end.y && start.y > obstacle.top && start.y < obstacle.bottom && rangesOverlap(start.x, end.x, obstacle.left, obstacle.right)) {
+            return true;
+        }
+    }
+    return false;
+}
+function isInsideObstacle(point, obstacles) {
+    return obstacles.some((obstacle) => point.x > obstacle.left && point.x < obstacle.right && point.y > obstacle.top && point.y < obstacle.bottom);
+}
+function rangesOverlap(firstStart, firstEnd, secondStart, secondEnd) {
+    return Math.max(Math.min(firstStart, firstEnd), secondStart) < Math.min(Math.max(firstStart, firstEnd), secondEnd);
+}
+function pointKey(point) {
+    return `${point.x},${point.y}`;
+}
+function uniqueSorted(values) {
+    return [...new Set(values)].sort((left, right) => left - right);
+}
+/** Project straight connections onto the ellipse contour, or the bounding rectangle for other shapes. */
+function boundaryPoint(node, toward) {
+    const center = { x: node.x + node.width / 2, y: node.y + node.height / 2 };
+    const dx = toward.x - center.x;
+    const dy = toward.y - center.y;
+    if (dx === 0 && dy === 0)
+        return center;
+    const normalizedX = dx / (node.width / 2);
+    const normalizedY = dy / (node.height / 2);
+    const scale = 1 / (node.kind === "ellipse"
+        ? Math.hypot(normalizedX, normalizedY)
+        : Math.max(Math.abs(normalizedX), Math.abs(normalizedY)));
+    return { x: center.x + dx * scale, y: center.y + dy * scale };
+}
+export function pathLabelAnchor(geometry) {
+    const points = geometry.points;
+    if (points.length < 2)
+        return { x: 0, y: -12 };
+    let longest = { start: points[0], end: points[1], length: 0 };
+    for (let index = 1; index < points.length; index += 1) {
+        const start = points[index - 1];
+        const end = points[index];
+        const length = Math.hypot(end.x - start.x, end.y - start.y);
+        if (length > longest.length)
+            longest = { start, end, length };
+    }
+    const horizontal = longest.start.y === longest.end.y;
+    return {
+        x: (longest.start.x + longest.end.x) / 2 + (horizontal ? 0 : 20),
+        y: (longest.start.y + longest.end.y) / 2 + (horizontal ? -12 : 0)
+    };
+}

package/dist/core/model.d.ts

@@ -0,0 +1,256 @@
+/** Shared serializable document and evaluated-frame types; no runtime or platform dependencies. */
+import type { NodeContent, 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[];
+}

package/dist/core/model.js

@@ -0,0 +1 @@
+export {};

package/dist/core/node-content-paint.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Shared node-content highlight paint for core timeline causes and browser-only hover.
+ * Paint consumes evaluated geometry and preserves explicit author colors; it never lays out text again.
+ */
+import type { NodeContentLayout } from "./node-content.js";
+/**
+ * Retain theme-specific semantic ink and tag fills; preserve geometry and explicit author colors.
+ * Check default ink against the evaluated fill because authored base fills can cross low-contrast transition colors.
+ */
+export declare function paintContentHighlight(layout: NodeContentLayout, amount: number, fill: string): NodeContentLayout;