flowsvg 0.1.0 → 0.2.0

package/dist/core/diagram.js

@@ -0,0 +1,481 @@
+/**
+ * Platform-independent diagram orchestration: compile documents and derive frames, geometry, hit tests and SVG.
+ * Validation owns document rules; this module owns cloning and freezing and does not read DOM, clocks or network.
+ */
+import { layoutNodeContent } from "./node-content.js";
+import { paintContentHighlight } from "./node-content-paint.js";
+import { CompiledTimeline } from "./timeline.js";
+import { mixColor } from "./color.js";
+import { DEFAULT_NODE_STROKE_WIDTH, DIAGRAM_FONT_FAMILY, NODE_CORNER_RADIUS, resolveThemePalette } from "./theme.js";
+import { DiagramValidationError, validateDocument } from "./validation.js";
+import { ARROW_MARKER_SIZE, emptyPathGeometry, isPointNearPath, routedTargetOffsets, pathLabelAnchor, routeEdge } from "./edge-geometry.js";
+import { formatNumber } from "./svg-number.js";
+/**
+ * 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, or derived flow timing is non-finite.
+ */
+export function createDiagram(input) {
+    const issues = validateDocument(input);
+    if (issues.length > 0)
+        throw new DiagramValidationError(issues);
+    return new CompiledDiagram(cloneDocument(input));
+}
+/** One-shot static SVG export; use createDiagram to reuse compilation across repeated evaluations or exports. */
+export function renderSvg(document, timeMs = 0, options) {
+    return createDiagram(document).renderSvg(timeMs, options);
+}
+/**
+ * Own the frozen document and compiled timeline; derive visual values, absolute geometry/text, routes, then camera.
+ * The ancestor index retains hierarchy; geometry is derived from current values on every frame to support group movement.
+ * See docs/adr/0001-platform-independent-core.md for the platform boundary.
+ */
+class CompiledDiagram {
+    totalDuration;
+    beats;
+    timeline;
+    document;
+    nodesById;
+    constructor(document) {
+        this.document = deepFreeze(document);
+        this.nodesById = new Map(document.nodes.map((node) => [node.id, node]));
+        // Resolve reference lengths from target snapshots using the same routing as ordinary frame evaluation.
+        // The second compilation changes timing only; authored transitions are capped at each effective beat duration.
+        const authoredTimeline = new CompiledTimeline(document);
+        const movementDurations = new Map();
+        let startMs = 0;
+        for (const [sceneIndex, scene] of document.scenes.entries()) {
+            scene.beats.forEach((beat, index) => {
+                const flows = beat.actions.filter((action) => action.type === "flow");
+                if (flows.length === 1) {
+                    const geometry = this.evaluateFrame(startMs, { reducedMotion: true }, authoredTimeline).edgeGeometries.get(flows[0].target);
+                    // Invalid finite-input arithmetic can produce NaN points even when geometry's zero-length fallback is finite.
+                    if (!Number.isFinite(geometry.length) || geometry.points.some((point) => !Number.isFinite(point.x) || !Number.isFinite(point.y))) {
+                        throw new DiagramValidationError([{ path: `scenes[${sceneIndex}].beats[${index}].durationMs`, message: "effective beat timing must be finite" }]);
+                    }
+                    movementDurations.set(`${scene.id}:${index}`, Math.max(MIN_FLOW_MOVEMENT_MS, geometry.length / FLOW_UNITS_PER_SECOND * MILLISECONDS_PER_SECOND));
+                }
+                startMs += beat.durationMs;
+            });
+        }
+        this.timeline = new CompiledTimeline(document, movementDurations);
+        this.totalDuration = this.timeline.totalDuration;
+        this.beats = this.timeline.schedule;
+    }
+    evaluateAt(timeMs, options = {}) {
+        return this.evaluateFrame(timeMs, options).frame;
+    }
+    evaluateFrame(timeMs, options = {}, compiledTimeline = this.timeline) {
+        const palette = resolvePalette(this.document, options);
+        const timeline = compiledTimeline.evaluateAt(timeMs, options, palette);
+        const currentNodes = new Map(this.document.nodes.map((node) => {
+            const values = timeline.objects.get(node.id).values;
+            return [node.id, { ...node, x: values.x ?? node.x, y: values.y ?? node.y, width: values.width ?? node.width, height: values.height ?? node.height, label: values.label, content: values.content ?? undefined }];
+        }));
+        const flowHighlights = resolveFlowHighlights(timeline.flows, this.document.edges, timeline.flowArrivalProgress, timeline.flowDepartureProgress);
+        const warnings = [];
+        const nodes = [...currentNodes.values()].map((node, index) => {
+            const position = this.resolvePosition(node.id, currentNodes);
+            const labelLines = node.label ? wrapText(node.label, Math.max(1, node.width - TEXT_PADDING * 2), NODE_TYPOGRAPHY) : [];
+            const labelCenterY = node.kind === "group" ? position.y + 24 : position.y + node.height / 2;
+            const labelBoxes = makeLabelBoxes(labelLines, position.x + node.width / 2, labelCenterY, NODE_TYPOGRAPHY);
+            if (node.label && labelLines.length * NODE_TYPOGRAPHY.lineHeight > Math.max(0, node.height - TEXT_PADDING * 2))
+                warnings.push({ path: `nodes[${index}].label`, objectId: node.id, code: "text-overflow", message: `label for node \"${node.id}\" exceeds its height` });
+            const visual = this.resolveVisibility(node.id, timeline.objects);
+            const own = timeline.objects.get(node.id);
+            const highlight = Math.max(own.highlight, flowHighlights.get(node.id) ?? 0);
+            const style = {
+                strokeWidth: DEFAULT_NODE_STROKE_WIDTH,
+                textColor: palette.text,
+                ...node.style,
+                fill: mixColor(own.values.fill ?? palette.fill, palette.highlightFill, highlight),
+                stroke: mixColor(own.values.stroke ?? palette.stroke, palette.highlight, highlight)
+            };
+            const contentLayout = node.content ? paintContentHighlight(layoutNodeContent(node.content, { ...position, width: node.width, height: node.height }, palette, node.kind), highlight, style.fill) : undefined;
+            if (contentLayout) {
+                for (const direction of ["width", "height"]) {
+                    if (contentLayout[direction === "width" ? "widthOverflow" : "heightOverflow"])
+                        warnings.push({ path: `nodes[${index}].content`, objectId: node.id, code: "text-overflow", message: `content for node "${node.id}" exceeds its ${direction}` });
+                }
+            }
+            return { ...node, contentLayout, ...visual, highlighted: own.highlighted || flowHighlights.has(node.id), style, x: position.x, y: position.y, labelLines, labelBoxes };
+        });
+        const nodeById = new Map(nodes.map((node) => [node.id, node]));
+        const targetOffsets = routedTargetOffsets(this.document.edges, nodeById);
+        const edgeGeometries = new Map();
+        const edges = this.document.edges.map((original) => {
+            const own = timeline.objects.get(original.id);
+            const activeFlow = timeline.flows.find((flow) => flow.target === original.id);
+            const edge = { ...original, label: own.values.label };
+            const from = nodeById.get(edge.from);
+            const to = nodeById.get(edge.to);
+            const visible = own.visible && Boolean(from?.visible && to?.visible);
+            // Take the minimum so simultaneous endpoint fades do not darken an edge again through multiplication.
+            const opacity = Math.min(own.opacity, from?.opacity ?? 0, to?.opacity ?? 0);
+            const style = {
+                ...edge.style,
+                strokeWidth: own.values.strokeWidth ?? edge.style?.strokeWidth ?? 2,
+                dashed: edge.style?.dashed ?? false,
+                stroke: mixColor(own.values.stroke ?? palette.edge, palette.highlight, Math.max(own.highlight, Number(activeFlow !== undefined) * (1 - timeline.flowDepartureProgress)))
+            };
+            const hasReverseCurve = edge.route === "curved" && this.document.edges.some((candidate) => candidate.id !== edge.id && candidate.route === "curved" && candidate.from === edge.to && candidate.to === edge.from);
+            // Both directions use the same lane magnitude; the perpendicular vector reverses with the edge,
+            // so the rendered relationships occupy opposite sides of their shared center line.
+            const reverseOffset = hasReverseCurve ? 1 : 0;
+            const geometry = from && to ? routeEdge({ ...edge, style }, from, to, nodes, { reverseOffset, targetOffset: targetOffsets.get(edge.id) ?? 0 }) : emptyPathGeometry();
+            edgeGeometries.set(edge.id, geometry);
+            const labelLines = edge.label ? wrapText(edge.label, Math.max(1, geometry.length - TEXT_PADDING * 2), EDGE_TYPOGRAPHY) : [];
+            const midpoint = pathLabelAnchor(geometry);
+            const flow = activeFlow && visible && opacity > 0 && !options.reducedMotion ? {
+                direction: activeFlow.direction,
+                progress: timeline.flowProgress,
+                point: geometry.pointAt(activeFlow.direction === "forward" ? timeline.flowProgress : 1 - timeline.flowProgress),
+                ...(activeFlow.text !== undefined ? { text: activeFlow.text } : {})
+            } : undefined;
+            return { ...edge, visible, opacity, highlighted: own.highlighted || activeFlow !== undefined, style, path: geometry.path, labelLines, labelBoxes: makeLabelBoxes(labelLines, midpoint.x, midpoint.y, EDGE_TYPOGRAPHY), ...(flow ? { flow } : {}) };
+        });
+        const camera = resolveCamera(this.document.viewport, timeline.focusBefore, timeline.focusAfter, timeline.transitionProgress, nodes, edges, edgeGeometries);
+        return {
+            frame: { timeMs: timeline.timeMs, sceneId: timeline.sceneId, beatId: timeline.beatId, beatProgress: timeline.beatProgress, nodes, edges, camera, warnings, ...(timeline.caption !== undefined ? { caption: timeline.caption } : {}) },
+            edgeGeometries
+        };
+    }
+    renderSvg(timeMs = 0, options = {}) {
+        const frame = this.evaluateAt(timeMs, options);
+        const palette = resolvePalette(this.document, options);
+        return serializeSvg(this.document, frame, palette);
+    }
+    hitTest(timeMs, point, options = {}) {
+        if (!Number.isFinite(point.x) || !Number.isFinite(point.y))
+            return null;
+        const evaluated = this.evaluateFrame(timeMs, options);
+        const frame = evaluated.frame;
+        const nodes = [...frame.nodes].reverse();
+        const containsPoint = (candidate) => candidate.visible && candidate.opacity > 0 && isPointInNode(point, candidate);
+        const node = nodes.find((candidate) => candidate.kind !== "group" && containsPoint(candidate));
+        if (node)
+            return { id: node.id, type: "node" };
+        const edge = [...frame.edges].reverse().find((candidate) => candidate.visible && candidate.opacity > 0 && isPointNearPath(point, evaluated.edgeGeometries.get(candidate.id) ?? emptyPathGeometry(), (candidate.style?.strokeWidth ?? 2) + HIT_TOLERANCE));
+        if (edge)
+            return { id: edge.id, type: "edge" };
+        const group = nodes.find((candidate) => candidate.kind === "group" && containsPoint(candidate));
+        return group ? { id: group.id, type: "node" } : null;
+    }
+    resolvePosition(id, nodes) {
+        const node = nodes.get(id);
+        if (!node)
+            return { x: 0, y: 0 };
+        const parent = node.parentId ? this.resolvePosition(node.parentId, nodes) : { x: 0, y: 0 };
+        return { x: node.x + parent.x, y: node.y + parent.y };
+    }
+    /** Intersect ancestor visibility and take minimum opacity without altering a child's stored state. */
+    resolveVisibility(id, states) {
+        const node = this.nodesById.get(id);
+        const own = states.get(id);
+        if (!node?.parentId)
+            return { visible: own.visible, opacity: own.opacity };
+        const parent = this.resolveVisibility(node.parentId, states);
+        return { visible: own.visible && parent.visible, opacity: Math.min(own.opacity, parent.opacity) };
+    }
+}
+const TEXT_PADDING = 12;
+const CONTENT_TAG_CORNER_RADIUS = 3;
+const NODE_TYPOGRAPHY = { fontSize: 16, lineHeight: 20, charWidth: 8.5 };
+const EDGE_TYPOGRAPHY = { fontSize: 14, lineHeight: 18, charWidth: 8.4 };
+const TEXT_DESCENT_RATIO = 0.25;
+const FLOW_TYPOGRAPHY = { fontSize: 12, lineHeight: 16, charWidth: 7.2 };
+const FLOW_CAPSULE_HEIGHT = 24;
+const FLOW_TEXT_PADDING = 10;
+const FLOW_DOT_RADIUS = 5;
+const FLOW_UNITS_PER_SECOND = 180;
+const MIN_FLOW_MOVEMENT_MS = 400;
+const MILLISECONDS_PER_SECOND = 1000;
+/**
+ * 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 function wrapText(label, maxWidth, typography = NODE_TYPOGRAPHY) {
+    const maxChars = Math.max(1, Math.floor(maxWidth / typography.charWidth));
+    const lines = [];
+    for (const explicitLine of label.split("\n")) {
+        if (explicitLine.length === 0) {
+            lines.push("");
+            continue;
+        }
+        // Code-point slicing keeps surrogate pairs intact even when only one character fits.
+        let remaining = Array.from(explicitLine);
+        while (remaining.length > maxChars) {
+            const candidate = remaining.slice(0, maxChars + 1);
+            const breakAt = candidate.lastIndexOf(" ");
+            const cut = breakAt > 0 ? breakAt : maxChars;
+            lines.push(remaining.slice(0, cut).join(""));
+            remaining = Array.from(remaining.slice(cut).join("").replace(/^\s+/, ""));
+        }
+        lines.push(remaining.join(""));
+    }
+    return lines;
+}
+/** Paint senders immediately and receivers after arrival, then remove single-flow paint before beat cleanup. */
+function resolveFlowHighlights(flows, edges, arrivalProgress, departureProgress) {
+    const highlights = new Map();
+    const amount = 1 - departureProgress;
+    for (const flow of flows) {
+        if (!flow.highlightParticipants)
+            continue;
+        const edge = edges.find((candidate) => candidate.id === flow.target);
+        if (!edge)
+            continue;
+        const sender = flow.direction === "forward" ? edge.from : edge.to;
+        const receiver = flow.direction === "forward" ? edge.to : edge.from;
+        highlights.set(sender, amount);
+        // Keep membership at zero paint so arrival does not change logical participant state.
+        highlights.set(receiver, Math.max(highlights.get(receiver) ?? 0, arrivalProgress * amount));
+    }
+    return highlights;
+}
+function makeLabelBoxes(lines, centerX, centerY, typography) {
+    const startY = centerY - ((lines.length - 1) * typography.lineHeight) / 2 + typography.fontSize * 0.35;
+    return lines.map((text, index) => ({ text, x: centerX, y: startY + index * typography.lineHeight }));
+}
+/** Serialize group backgrounds, edges, ordinary nodes, then labels; write the evaluated camera directly to viewBox. */
+function serializeSvg(document, frame, palette) {
+    const title = escapeText(document.title ?? "Diagram");
+    const edgeShapes = frame.edges.filter((edge) => edge.opacity > 0).map((edge) => {
+        const stroke = edge.style?.stroke ?? palette.edge;
+        const width = edge.style?.strokeWidth ?? 2;
+        const dash = edge.style?.dashed ? ' stroke-dasharray="6 4"' : "";
+        return `<path d="${escapeAttribute(edge.path)}" fill="none" stroke="${escapeAttribute(stroke)}" color="${escapeAttribute(stroke)}" stroke-width="${width}"${dash} marker-end="url(#diagram-arrow)" data-id="${escapeAttribute(edge.id)}" opacity="${edge.opacity}"/>`;
+    }).join("");
+    const groupShapes = frame.nodes.filter((node) => node.opacity > 0 && node.kind === "group").map((node) => serializeNodeShape(node, palette)).join("");
+    const nodeShapes = frame.nodes.filter((node) => node.opacity > 0 && node.kind !== "group").map((node) => serializeNodeShape(node, palette)).join("");
+    const labels = frame.edges.filter((edge) => edge.opacity > 0).map((edge) => serializeLabel(edge.labelLines, edge.labelBoxes, edge.style?.stroke ?? palette.text, EDGE_TYPOGRAPHY, edge.opacity, palette.background)).join("") + frame.nodes.filter((node) => node.opacity > 0).map((node) => serializeLabel(node.labelLines, node.labelBoxes, node.style?.textColor ?? palette.text, NODE_TYPOGRAPHY, node.opacity)).join("");
+    const contents = frame.nodes.filter((node) => node.opacity > 0 && node.contentLayout).map((node, index) => serializeNodeContent(node, index)).join("");
+    const flows = frame.edges.filter((edge) => edge.opacity > 0 && edge.flow).map((edge) => serializeFlowMarker(edge.flow, edge.id, palette, edge.opacity)).join("");
+    const marker = `<defs><marker id="diagram-arrow" viewBox="0 0 10 10" refX="9" refY="5" markerWidth="${ARROW_MARKER_SIZE}" markerHeight="${ARROW_MARKER_SIZE}" orient="auto-start-reverse"><path d="M 0 0 L 10 5 L 0 10 z" fill="context-stroke"/></marker></defs>`;
+    const ariaLabel = escapeAttribute(document.title ?? "Diagram");
+    const camera = `${formatNumber(frame.camera.x)} ${formatNumber(frame.camera.y)} ${formatNumber(frame.camera.width)} ${formatNumber(frame.camera.height)}`;
+    return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${camera}" role="img" aria-label="${ariaLabel}" font-family="${escapeAttribute(DIAGRAM_FONT_FAMILY)}"><title>${title}</title>${marker}<rect x="${formatNumber(frame.camera.x)}" y="${formatNumber(frame.camera.y)}" width="${formatNumber(frame.camera.width)}" height="${formatNumber(frame.camera.height)}" fill="${palette.background}"/>${groupShapes}${edgeShapes}${nodeShapes}${labels}${contents}${flows}</svg>`;
+}
+/** Serialize evaluated text and tag backgrounds inside one clip; authored content cannot introduce SVG markup or CSS. */
+function serializeNodeContent(node, index) {
+    const layout = node.contentLayout;
+    const safe = layout.safeArea;
+    // Include exact clip geometry so independent SVGs with different node dimensions do not share a clip definition.
+    const geometryKey = [safe.x, safe.y, safe.width, safe.height].map((value) => String(value).replaceAll("-", "n").replaceAll(".", "p").replaceAll("+", "a")).join("-");
+    const clipId = `diagram-content-clip-${index}-${geometryKey}`;
+    const clip = `<defs><clipPath id="${clipId}" clipPathUnits="userSpaceOnUse"><rect x="${formatNumber(safe.x)}" y="${formatNumber(safe.y)}" width="${formatNumber(safe.width)}" height="${formatNumber(safe.height)}"/></clipPath></defs>`;
+    const tags = layout.tags.map((tag) => `<rect x="${formatNumber(tag.x)}" y="${formatNumber(tag.y)}" width="${formatNumber(tag.width)}" height="${formatNumber(tag.height)}" rx="${formatNumber(tag.shape === "pill" ? tag.height / 2 : CONTENT_TAG_CORNER_RADIUS)}" fill="${escapeAttribute(tag.fill)}"/>`).join("");
+    const lines = layout.lines.map((line) => `<text x="${formatNumber(line.x)}" y="${formatNumber(line.y)}" fill="${escapeAttribute(line.color)}" font-size="${line.fontSize}" font-weight="${line.fontWeight}" text-anchor="${line.align === "left" ? "start" : line.align === "right" ? "end" : "middle"}">${line.spans.map((span) => `<tspan x="${formatNumber(span.x)}" y="${formatNumber(span.y)}" fill="${escapeAttribute(span.color)}" font-size="${span.fontSize}" font-weight="${span.fontWeight}" text-anchor="start">${escapeText(span.text)}</tspan>`).join("")}</text>`).join("");
+    const graphs = (layout.graphs ?? []).map((graph) => `<g data-content-graph="${graph.blockIndex}" aria-hidden="true">${graph.edges.map((edge) => `<line x1="${formatNumber(edge.x1)}" y1="${formatNumber(edge.y1)}" x2="${formatNumber(edge.x2)}" y2="${formatNumber(edge.y2)}" stroke="${edge.color}"/>`).join("")}${graph.nodes.map((point) => `<circle cx="${formatNumber(point.x)}" cy="${formatNumber(point.y)}" r="${point.radius}" fill="${point.fill}"/>`).join("")}</g>`).join("");
+    return `${clip}<g id="diagram-content-${index}" data-content-id="${escapeAttribute(node.id)}" clip-path="url(#${clipId})" opacity="${node.opacity}">${tags}${graphs}${lines}</g>`;
+}
+/** Keep markers decorative and horizontal; coordinates come only from the evaluated path point. */
+function serializeFlowMarker(flow, edgeId, palette, opacity) {
+    const attributes = `fill="${palette.highlight}" data-flow-id="${escapeAttribute(edgeId)}" opacity="${opacity}" pointer-events="none" aria-hidden="true"`;
+    if (flow.text === undefined)
+        return `<circle cx="${formatNumber(flow.point.x)}" cy="${formatNumber(flow.point.y)}" r="${FLOW_DOT_RADIUS}" ${attributes}/>`;
+    const width = Math.max(FLOW_CAPSULE_HEIGHT, estimateTextWidth(flow.text, FLOW_TYPOGRAPHY) + FLOW_TEXT_PADDING * 2);
+    const x = formatNumber(flow.point.x - width / 2);
+    const y = formatNumber(flow.point.y - FLOW_CAPSULE_HEIGHT / 2);
+    // Marker ink follows its saturated fill, independently of node text and interior highlight paint.
+    const text = `<text x="${formatNumber(flow.point.x)}" y="${formatNumber(flow.point.y + FLOW_TYPOGRAPHY.fontSize * 0.35)}" fill="${palette.highlightText}" font-size="${FLOW_TYPOGRAPHY.fontSize}" text-anchor="middle">${escapeText(flow.text)}</text>`;
+    return `<g ${attributes}><rect x="${x}" y="${y}" width="${formatNumber(width)}" height="${FLOW_CAPSULE_HEIGHT}" rx="${FLOW_CAPSULE_HEIGHT / 2}"/>${text}</g>`;
+}
+/** Reuse fixed code-point metrics without DOM measurements; reserve a full em for wide letters and Unicode. */
+function estimateTextWidth(text, typography) {
+    return Array.from(text).reduce((width, character) => {
+        const wide = character.codePointAt(0) > 0xff || "MWmw@%".includes(character);
+        return width + (wide ? typography.fontSize : typography.charWidth);
+    }, 0);
+}
+/** Serialize supported shapes with escaped color/identity attributes; labels are drawn in a separate text layer. */
+function serializeNodeShape(node, palette) {
+    const fill = node.style?.fill ?? palette.fill;
+    const stroke = node.style?.stroke ?? palette.stroke;
+    const width = node.style?.strokeWidth ?? DEFAULT_NODE_STROKE_WIDTH;
+    const dash = node.kind === "group" && node.style?.dashed ? ' stroke-dasharray="10 7"' : "";
+    const attrs = `fill="${escapeAttribute(fill)}" stroke="${escapeAttribute(stroke)}" stroke-width="${width}"${dash} data-id="${escapeAttribute(node.id)}" opacity="${node.opacity}"`;
+    if (node.kind === "ellipse")
+        return `<ellipse cx="${formatNumber(node.x + node.width / 2)}" cy="${formatNumber(node.y + node.height / 2)}" rx="${formatNumber(node.width / 2)}" ry="${formatNumber(node.height / 2)}" ${attrs}/>`;
+    if (node.kind === "cylinder") {
+        const ry = Math.min(14, node.height / 4);
+        const bottom = node.y + node.height - ry;
+        const bodyPath = `M ${formatNumber(node.x)} ${formatNumber(node.y + ry)} L ${formatNumber(node.x + node.width)} ${formatNumber(node.y + ry)} L ${formatNumber(node.x + node.width)} ${formatNumber(bottom)} A ${formatNumber(node.width / 2)} ${formatNumber(ry)} 0 0 1 ${formatNumber(node.x)} ${formatNumber(bottom)} Z`;
+        // Keep the cap as a filled sibling so the SVG fill rule cannot turn its interior into a hole.
+        // The group owns the only data-id, allowing hover and DOM synchronization to treat the cylinder as one node.
+        const cap = `<ellipse cx="${formatNumber(node.x + node.width / 2)}" cy="${formatNumber(node.y + ry)}" rx="${formatNumber(node.width / 2)}" ry="${formatNumber(ry)}"/>`;
+        return `<g ${attrs}><path d="${bodyPath}"/>${cap}</g>`;
+    }
+    const radius = node.kind === "roundedRect" ? ` rx="${Math.min(NODE_CORNER_RADIUS, node.width / 4, node.height / 4)}"` : "";
+    return `<rect x="${formatNumber(node.x)}" y="${formatNumber(node.y)}" width="${formatNumber(node.width)}" height="${formatNumber(node.height)}"${radius} ${attrs}/>`;
+}
+function serializeLabel(lines, boxes, color, typography, opacity = 1, background) {
+    if (lines.length === 0)
+        return "";
+    const x = boxes[0]?.x ?? 0;
+    const body = lines.map((line, index) => `<tspan x="${formatNumber(x)}" y="${formatNumber(boxes[index]?.y ?? 0)}">${escapeText(line)}</tspan>`).join("");
+    // Only edge labels need background isolation from the path beneath them.
+    const halo = background ? ` stroke="${escapeAttribute(background)}" stroke-width="6" stroke-linejoin="round" paint-order="stroke"` : "";
+    return `<text fill="${escapeAttribute(color)}"${halo} font-size="${typography.fontSize}" text-anchor="middle" opacity="${opacity}">${body}</text>`;
+}
+const FOCUS_PADDING = 24;
+const MIN_FITTED_HEIGHT = 1;
+const EDGE_LABEL_HALO_RADIUS = 3;
+const HIT_TOLERANCE = 6;
+/** Resolve both focus targets against current geometry, then interpolate cameras with the timeline's eased progress. */
+function resolveCamera(viewport, beforeTarget, afterTarget, progress, nodes, edges, edgeGeometries) {
+    const full = { x: 0, y: 0, width: viewport.width, height: fittedHeight(viewport, nodes, edges, edgeGeometries) };
+    const before = focusCamera(viewport, beforeTarget, nodes, edges, edgeGeometries) ?? full;
+    const after = focusCamera(viewport, afterTarget, nodes, edges, edgeGeometries) ?? full;
+    if (progress <= 0)
+        return before;
+    if (progress >= 1)
+        return after;
+    return {
+        x: before.x + (after.x - before.x) * progress,
+        y: before.y + (after.y - before.y) * progress,
+        width: before.width + (after.width - before.width) * progress,
+        height: before.height + (after.height - before.height) * progress
+    };
+}
+/** Full-view fitting keeps authored width and origin; include paint without changing node geometry. */
+function fittedHeight(viewport, nodes, edges, geometries) {
+    if (!viewport.fitHeight)
+        return viewport.height;
+    const bottoms = [];
+    for (const node of nodes) {
+        if (node.opacity <= 0)
+            continue;
+        bottoms.push(node.y + node.height + (node.style?.strokeWidth ?? DEFAULT_NODE_STROKE_WIDTH) / 2);
+        for (const bottom of labelBottoms(node.labelBoxes, NODE_TYPOGRAPHY))
+            bottoms.push(bottom);
+    }
+    for (const edge of edges) {
+        if (edge.opacity <= 0)
+            continue;
+        const geometry = geometries.get(edge.id);
+        if (geometry) {
+            const strokeWidth = edge.style?.strokeWidth ?? 2;
+            bottoms.push(geometry.paintedBottom + strokeWidth / 2, arrowBottom(geometry, strokeWidth));
+        }
+        for (const bottom of labelBottoms(edge.labelBoxes, EDGE_TYPOGRAPHY, EDGE_LABEL_HALO_RADIUS))
+            bottoms.push(bottom);
+        if (edge.flow)
+            bottoms.push(edge.flow.point.y + (edge.flow.text === undefined ? FLOW_DOT_RADIUS : FLOW_CAPSULE_HEIGHT / 2));
+    }
+    if (bottoms.length === 0)
+        return viewport.height;
+    const bottom = bottoms.reduce((maximum, value) => Math.max(maximum, value), 0);
+    const height = Math.max(MIN_FITTED_HEIGHT, Math.ceil(bottom + viewport.fitHeight.padding));
+    if (!Number.isFinite(height))
+        throw new DiagramValidationError([{ path: "viewport.fitHeight", message: "current painted geometry and padding must produce a finite height" }]);
+    return height;
+}
+/** Match the three SVG marker vertices around refX=9, refY=5 in its ten-unit viewBox. */
+function arrowBottom(geometry, strokeWidth) {
+    const end = geometry.points.at(-1);
+    if (!end)
+        return 0;
+    const direction = geometry.terminalDirection;
+    const markerScale = ARROW_MARKER_SIZE * strokeWidth;
+    const vertexOffset = Math.max(0.1 * direction.y, -0.9 * direction.y + 0.5 * Math.abs(direction.x));
+    return end.y + markerScale * vertexOffset;
+}
+/** Use the same deterministic text descent as node hit bounds; edge labels also paint a three-unit halo. */
+function labelBottoms(boxes, typography, halo = 0) {
+    return boxes.filter((line) => line.text.length > 0).map((line) => line.y + typography.fontSize * TEXT_DESCENT_RATIO + halo);
+}
+/** Pad bounds of the target, descendants and visible incident edges, preserving aspect ratio within the initial viewport. */
+function focusCamera(viewport, target, nodes, edges, edgeGeometries) {
+    if (!target)
+        return undefined;
+    const targetNode = nodes.find((node) => node.id === target);
+    if (!targetNode)
+        return undefined;
+    const targetIds = new Set(nodes.filter((node) => node.id === target || hasAncestor(node, target, nodes)).map((node) => node.id));
+    const bounds = nodes.filter((node) => targetIds.has(node.id)).map(nodeBounds);
+    for (const edge of edges) {
+        if (edge.visible && edge.opacity > 0 && (targetIds.has(edge.from) || targetIds.has(edge.to)))
+            bounds.push((edgeGeometries.get(edge.id) ?? emptyPathGeometry()).bounds);
+    }
+    const combined = combineBounds(bounds);
+    if (!combined)
+        return undefined;
+    const aspect = viewport.width / viewport.height;
+    const paddedWidth = combined.right - combined.left + FOCUS_PADDING * 2;
+    const paddedHeight = combined.bottom - combined.top + FOCUS_PADDING * 2;
+    let width = Math.max(paddedWidth, paddedHeight * aspect);
+    let height = Math.max(paddedHeight, paddedWidth / aspect);
+    if (width > viewport.width) {
+        width = viewport.width;
+        height = width / aspect;
+    }
+    if (height > viewport.height) {
+        height = viewport.height;
+        width = height * aspect;
+    }
+    const centerX = (combined.left + combined.right) / 2;
+    const centerY = (combined.top + combined.bottom) / 2;
+    const x = clampCamera(centerX - width / 2, 0, viewport.width - width);
+    const y = clampCamera(centerY - height / 2, 0, viewport.height - height);
+    return { x, y, width, height };
+}
+function hasAncestor(node, ancestorId, nodes) {
+    const byId = new Map(nodes.map((candidate) => [candidate.id, candidate]));
+    let parentId = node.parentId;
+    while (parentId) {
+        if (parentId === ancestorId)
+            return true;
+        parentId = byId.get(parentId)?.parentId;
+    }
+    return false;
+}
+function nodeBounds(node) {
+    return { left: node.x, top: node.y, right: node.x + node.width, bottom: node.y + node.height };
+}
+function combineBounds(bounds) {
+    if (bounds.length === 0)
+        return undefined;
+    return { left: Math.min(...bounds.map((bound) => bound.left)), top: Math.min(...bounds.map((bound) => bound.top)), right: Math.max(...bounds.map((bound) => bound.right)), bottom: Math.max(...bounds.map((bound) => bound.bottom)) };
+}
+function clampCamera(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+/** Include deterministic label bounds so overflowing text remains part of the node's interaction target. */
+function isPointInNode(point, node) {
+    const labelHit = node.labelBoxes.some((line) => {
+        if (line.text.length === 0)
+            return false;
+        const halfWidth = estimateTextWidth(line.text, NODE_TYPOGRAPHY) / 2;
+        return point.x >= line.x - halfWidth && point.x <= line.x + halfWidth
+            && point.y >= line.y - NODE_TYPOGRAPHY.fontSize && point.y <= line.y + NODE_TYPOGRAPHY.fontSize * TEXT_DESCENT_RATIO;
+    });
+    if (labelHit)
+        return true;
+    if (node.kind === "ellipse") {
+        const dx = (point.x - (node.x + node.width / 2)) / (node.width / 2);
+        const dy = (point.y - (node.y + node.height / 2)) / (node.height / 2);
+        return dx * dx + dy * dy <= 1;
+    }
+    return point.x >= node.x && point.x <= node.x + node.width && point.y >= node.y && point.y <= node.y + node.height;
+}
+function escapeText(value) {
+    return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;").replaceAll("'", "&apos;");
+}
+function escapeAttribute(value) {
+    return escapeText(value);
+}
+/** Validation restricts inputs to serializable documents; clone before freezing to isolate later author mutations. */
+function cloneDocument(document) {
+    return JSON.parse(JSON.stringify(document));
+}
+function deepFreeze(value) {
+    if (typeof value === "object" && value !== null) {
+        Object.freeze(value);
+        for (const child of Object.values(value))
+            deepFreeze(child);
+    }
+    return value;
+}
+function resolvePalette(document, options) {
+    return resolveThemePalette(options.theme ?? document.theme);
+}

package/dist/core/edge-geometry.d.ts

@@ -0,0 +1,45 @@
+import type { DiagramEdge, DiagramPoint, EvaluatedNode } from "./model.js";
+interface Point {
+    x: number;
+    y: number;
+}
+interface Rect {
+    left: number;
+    top: number;
+    right: number;
+    bottom: number;
+}
+/** SVG marker size in stroke-width units; routing uses the same footprint as serialization. */
+export declare const ARROW_MARKER_SIZE = 7;
+/** Internal path representation shared by SVG output, labels, bounds, hit testing and distance-based flow placement. */
+export interface PathGeometry {
+    readonly path: string;
+    readonly points: readonly Point[];
+    readonly length: number;
+    /** Exact final tangent for SVG marker bounds; sampled chords can differ on curves. */
+    readonly terminalDirection: Point;
+    /** Exact vertical paint extent for full-view fitting; independent of distance-sampling resolution. */
+    readonly paintedBottom: number;
+    readonly bounds: Rect;
+    pointAt(progress: number): Point;
+}
+export declare function emptyPathGeometry(): PathGeometry;
+export declare function isPointNearPath(point: DiagramPoint, geometry: PathGeometry, tolerance: number): boolean;
+/**
+ * Orthogonal routes prefer centered bridges and single outside channels before obstacle search.
+ * They reserve outward endpoint segments and the final bend before the straight marker approach.
+ * Separate ancestor frames set outside clearance but are not obstacles.
+ * Curved and orthogonal input slots follow source position with document-order ties, independently of timeline visibility.
+ * Routing uses visible separately from paint opacity: reveals block immediately, and hides block until completion.
+ */
+export declare function routeEdge(edge: DiagramEdge, from: EvaluatedNode, to: EvaluatedNode, nodes: readonly EvaluatedNode[], routing: {
+    reverseOffset: number;
+    targetOffset: number;
+}): PathGeometry;
+/** Order inputs across each side by source position; retain hidden edges so reveals cannot move other arrow tips. */
+export declare function routedTargetOffsets(edges: readonly DiagramEdge[], nodes: ReadonlyMap<string, EvaluatedNode>): ReadonlyMap<string, number>;
+export declare function pathLabelAnchor(geometry: PathGeometry): {
+    x: number;
+    y: number;
+};
+export {};