flowsvg 0.1.1 → 0.2.0

package/dist/core/diagram.js

@@ -8,11 +8,11 @@ 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 { emptyPathGeometry, isPointNearPath, pathLabelAnchor, routeEdge } from "./edge-geometry.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.
+ * @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);
@@ -31,25 +31,47 @@ export function renderSvg(document, timeMs = 0, options) {
  */
 class CompiledDiagram {
     totalDuration;
+    beats;
     timeline;
     document;
     nodesById;
     constructor(document) {
         this.document = deepFreeze(document);
-        this.timeline = new CompiledTimeline(document);
-        this.totalDuration = this.timeline.totalDuration;
         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 = {}) {
+    evaluateFrame(timeMs, options = {}, compiledTimeline = this.timeline) {
         const palette = resolvePalette(this.document, options);
-        const timeline = this.timeline.evaluateAt(timeMs, options, palette);
+        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);
@@ -60,27 +82,25 @@ class CompiledDiagram {
                 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 flowHighlighted = timeline.flows.some((flow) => {
-                const edge = this.document.edges.find((candidate) => candidate.id === flow.target);
-                return edge?.from === node.id || edge?.to === 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, Math.max(own.highlight, Number(flowHighlighted))),
-                stroke: mixColor(own.values.stroke ?? palette.stroke, palette.highlight, Math.max(own.highlight, Number(flowHighlighted)))
+                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), Math.max(own.highlight, Number(flowHighlighted)), style.fill) : undefined;
+            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 || flowHighlighted, style, x: position.x, y: position.y, labelLines, labelBoxes };
+            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);
@@ -95,20 +115,20 @@ class CompiledDiagram {
                 ...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)))
+                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, from, to, nodes, reverseOffset) : emptyPathGeometry();
+            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.beatProgress,
-                point: geometry.pointAt(activeFlow.direction === "forward" ? timeline.beatProgress : 1 - timeline.beatProgress),
+                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 } : {}) };
@@ -166,6 +186,9 @@ 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.
@@ -191,6 +214,24 @@ export function wrapText(label, maxWidth, typography = NODE_TYPOGRAPHY) {
     }
     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 }));
@@ -209,7 +250,7 @@ function serializeSvg(document, frame, palette) {
     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="7" markerHeight="7" orient="auto-start-reverse"><path d="M 0 0 L 10 5 L 0 10 z" fill="context-stroke"/></marker></defs>`;
+    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>`;
@@ -222,7 +263,7 @@ function serializeNodeContent(node, index) {
     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="${CONTENT_TAG_CORNER_RADIUS}" fill="${escapeAttribute(tag.fill)}"/>`).join("");
+    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>`;
@@ -277,10 +318,12 @@ function serializeLabel(lines, boxes, color, typography, opacity = 1, background
     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: viewport.height };
+    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)
@@ -294,6 +337,53 @@ function resolveCamera(viewport, beforeTarget, afterTarget, progress, nodes, edg
         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)

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

@@ -9,22 +9,35 @@ interface Rect {
     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;
 /**
- * Automatic orthogonal routing excludes endpoints and group frames from obstacles.
- * Explicit orthogonal ports reserve outward stubs and route around endpoint bodies as well.
+ * 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[], reverseOffset?: number): PathGeometry;
+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;