flowsvg 0.1.1 → 0.2.0

package/dist/core/edge-geometry.js

@@ -12,12 +12,22 @@ function straightPoints(from, to) {
     return [start, end];
 }
 const ROUTING_GAP = 8;
+const PORT_SPACING = 24;
+const MIN_ARROW_APPROACH = 24;
+const ORTHOGONAL_BEND_RADIUS = 12;
+const BEND_SAMPLE_COUNT = 16;
+const BEND_CLEARANCE_EPSILON = 0.002;
+const BEND_RADIUS_SEARCH_STEPS = 16;
+const BEND_RADIUS_PRECISION = 1000;
+const CYLINDER_CAP_RADIUS = 14;
+/** SVG marker size in stroke-width units; routing uses the same footprint as serialization. */
+export const ARROW_MARKER_SIZE = 7;
 const FOCUS_PADDING = 24;
 const HIT_TOLERANCE = 6;
 export function emptyPathGeometry() {
     return createPathGeometry([]);
 }
-function createPathGeometry(points, serializedPath) {
+function createPathGeometry(points, serializedPath, terminalControl, paintedBottom) {
     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) }));
@@ -31,6 +41,8 @@ function createPathGeometry(points, serializedPath) {
         path,
         points: compact,
         length: length || 1,
+        terminalDirection: terminalDirection(compact, terminalControl),
+        paintedBottom: paintedBottom ?? bounds.bottom,
         bounds,
         pointAt(progress) {
             if (compact.length === 0)
@@ -53,6 +65,88 @@ function createPathGeometry(points, serializedPath) {
         }
     };
 }
+/** Use the exact final cubic control, or the final straight run, for the SVG marker orientation. */
+function terminalDirection(points, control) {
+    const end = points.at(-1);
+    const previous = control ?? points.at(-2);
+    if (!end || !previous)
+        return { x: 1, y: 0 };
+    const dx = end.x - previous.x;
+    const dy = end.y - previous.y;
+    const length = Math.hypot(dx, dy);
+    return length > 0 ? { x: dx / length, y: dy / length } : { x: 1, y: 0 };
+}
+/**
+ * Trim orthogonal corners into quadratic bends. Adjacent trims cannot overlap,
+ * and the final run retains the marker approach. SVG and distance consumers
+ * share the same controls; conservative hull checks protect stroked node bounds.
+ */
+function createRoundedGeometry(points, obstacles, strokeWidth) {
+    const route = simplifyPoints(points);
+    if (route.length < 3)
+        return createPathGeometry(route);
+    const samples = [route[0]];
+    const commands = [`M ${formatNumber(route[0].x)} ${formatNumber(route[0].y)}`];
+    const approach = Math.max(MIN_ARROW_APPROACH, strokeWidth * ARROW_MARKER_SIZE + ROUTING_GAP);
+    for (let index = 1; index < route.length - 1; index += 1) {
+        const previous = route[index - 1];
+        const corner = route[index];
+        const next = route[index + 1];
+        const incoming = Math.hypot(corner.x - previous.x, corner.y - previous.y);
+        const outgoing = Math.hypot(next.x - corner.x, next.y - corner.y);
+        const turns = (corner.x - previous.x) * (next.x - corner.x) + (corner.y - previous.y) * (next.y - corner.y) === 0;
+        const maximum = turns ? Math.max(0, Math.min(ORTHOGONAL_BEND_RADIUS, incoming / 2, outgoing / 2, index === route.length - 2 ? outgoing - Math.min(approach, outgoing) : ORTHOGONAL_BEND_RADIUS)) : 0;
+        const radius = clearBendRadius(corner, previous, next, maximum, obstacles, strokeWidth / 2);
+        const entry = moveToward(corner, previous, radius);
+        const exit = moveToward(corner, next, radius);
+        commands.push(`L ${formatNumber(entry.x)} ${formatNumber(entry.y)}`);
+        samples.push(entry);
+        if (radius === 0)
+            continue;
+        commands.push(`Q ${formatNumber(corner.x)} ${formatNumber(corner.y)} ${formatNumber(exit.x)} ${formatNumber(exit.y)}`);
+        for (let sample = 1; sample <= BEND_SAMPLE_COUNT; sample += 1) {
+            const progress = sample / BEND_SAMPLE_COUNT;
+            const inverse = 1 - progress;
+            samples.push({ x: inverse ** 2 * entry.x + 2 * inverse * progress * corner.x + progress ** 2 * exit.x,
+                y: inverse ** 2 * entry.y + 2 * inverse * progress * corner.y + progress ** 2 * exit.y });
+        }
+    }
+    const end = route.at(-1);
+    commands.push(`L ${formatNumber(end.x)} ${formatNumber(end.y)}`);
+    samples.push(end);
+    return createPathGeometry(samples, commands.join(" "));
+}
+function moveToward(origin, target, distance) {
+    const length = Math.hypot(target.x - origin.x, target.y - origin.y);
+    return { x: origin.x + (target.x - origin.x) / length * distance,
+        y: origin.y + (target.y - origin.y) / length * distance };
+}
+/** Shrinking the control hull cannot create a new collision. Retain a rounding margin for SVG serialization. */
+function clearBendRadius(corner, previous, next, maximum, obstacles, strokeRadius) {
+    const clear = (radius) => {
+        const entry = moveToward(corner, previous, radius);
+        const exit = moveToward(corner, next, radius);
+        const margin = strokeRadius + BEND_CLEARANCE_EPSILON;
+        return !obstacles.some((bounds) => Math.min(entry.x, corner.x, exit.x) < bounds.right + margin
+            && Math.max(entry.x, corner.x, exit.x) > bounds.left - margin
+            && Math.min(entry.y, corner.y, exit.y) < bounds.bottom + margin
+            && Math.max(entry.y, corner.y, exit.y) > bounds.top - margin);
+    };
+    if (maximum === 0 || !clear(0))
+        return 0;
+    if (clear(maximum))
+        return maximum;
+    let lower = 0;
+    let upper = maximum;
+    for (let iteration = 0; iteration < BEND_RADIUS_SEARCH_STEPS; iteration += 1) {
+        const candidate = (lower + upper) / 2;
+        if (clear(candidate))
+            lower = candidate;
+        else
+            upper = candidate;
+    }
+    return Math.floor(lower * BEND_RADIUS_PRECISION) / BEND_RADIUS_PRECISION;
+}
 /** Build sampled geometry for a cubic curve while retaining the exact cubic command for SVG output. */
 function createCurveGeometry(start, controlStart, controlEnd, end) {
     const samples = [];
@@ -66,7 +160,30 @@ function createCurveGeometry(start, controlStart, controlEnd, end) {
         });
     }
     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);
+    return createPathGeometry(samples, path, controlEnd, cubicBottom(start, controlStart, controlEnd, end));
+}
+/** Solve the cubic's vertical derivative; sampled flow points can miss the painted lower extremum. */
+function cubicBottom(start, first, second, end) {
+    const scale = Math.max(Math.abs(start.y), Math.abs(first.y), Math.abs(second.y), Math.abs(end.y), 1);
+    const a = start.y / scale;
+    const b = first.y / scale;
+    const c = second.y / scale;
+    const d = end.y / scale;
+    const quadratic = -a + 3 * b - 3 * c + d;
+    const linear = 2 * (a - 2 * b + c);
+    const constant = b - a;
+    const discriminant = linear * linear - 4 * quadratic * constant;
+    const roots = quadratic === 0 ? linear === 0 ? [] : [-constant / linear]
+        : discriminant < 0 ? [] : [(-linear - Math.sqrt(discriminant)) / (2 * quadratic), (-linear + Math.sqrt(discriminant)) / (2 * quadratic)];
+    let bottom = Math.max(start.y, end.y);
+    for (const progress of roots) {
+        if (progress <= 0 || progress >= 1)
+            continue;
+        const inverse = 1 - progress;
+        const value = inverse ** 3 * start.y + 3 * inverse ** 2 * progress * first.y + 3 * inverse * progress ** 2 * second.y + progress ** 3 * end.y;
+        bottom = Math.max(bottom, value);
+    }
+    return bottom;
 }
 /** 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) {
@@ -86,7 +203,7 @@ function createSeparatedCurveGeometry(start, controlStart, midpoint, controlMidS
     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);
+    return createPathGeometry(samples, path, controlEnd, Math.max(cubicBottom(start, controlStart, controlMidStart, midpoint), cubicBottom(midpoint, controlMidEnd, controlEnd, end)));
 }
 export function isPointNearPath(point, geometry, tolerance) {
     for (let index = 1; index < geometry.points.length; index += 1)
@@ -103,18 +220,20 @@ function distanceToSegment(point, start, end) {
     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.
+ * 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 function routeEdge(edge, from, to, nodes, reverseOffset = 0) {
+export function routeEdge(edge, from, to, nodes, routing) {
     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);
+        const end = portPoint(to, toDirection, routing.targetOffset);
+        return curvedPath(start, end, fromDirection, toDirection, routing.reverseOffset);
     }
     if (edge.route !== "orthogonal") {
         const points = edge.fromPort || edge.toPort
@@ -122,43 +241,146 @@ export function routeEdge(edge, from, to, nodes, reverseOffset = 0) {
             : 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));
+        .map(nodeBounds);
+    return createRoundedGeometry(orthogonalPortPath(edge, from, to, obstacles, routing.targetOffset, nodes), [...obstacles, nodeBounds(from), nodeBounds(to)], edge.style?.strokeWidth ?? 2);
+}
+/** Order inputs across each side by source position; retain hidden edges so reveals cannot move other arrow tips. */
+export function routedTargetOffsets(edges, nodes) {
+    const groups = new Map();
+    for (const edge of edges) {
+        if (edge.route !== "orthogonal" && edge.route !== "curved")
+            continue;
+        const from = nodes.get(edge.from);
+        const to = nodes.get(edge.to);
+        if (!from || !to)
+            continue;
+        const side = edge.toPort ?? automaticPorts(from, to).to;
+        const key = JSON.stringify([to.id, side]);
+        const group = groups.get(key);
+        const position = side === "top" || side === "bottom" ? from.x + from.width / 2 : from.y + from.height / 2;
+        groups.set(key, { node: to, side, inputs: [...(group?.inputs ?? []), { id: edge.id, position }] });
+    }
+    const offsets = new Map();
+    for (const { node, side, inputs } of groups.values()) {
+        const span = side === "top" || side === "bottom" ? node.width : node.height;
+        const spacing = Math.min(PORT_SPACING, span / (2 * inputs.length));
+        [...inputs].sort((left, right) => left.position - right.position)
+            .forEach((edge, index) => offsets.set(edge.id, (index - (inputs.length - 1) / 2) * spacing));
+    }
+    return offsets;
+}
+function nodeBounds(node) {
+    return { left: node.x, top: node.y, right: node.x + node.width, bottom: node.y + node.height };
 }
-function routingBounds(node) {
+function routingBounds(bounds, side, approach = ROUTING_GAP) {
     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
+        left: bounds.left - (side === "left" ? approach : ROUTING_GAP),
+        top: bounds.top - (side === "top" ? approach : ROUTING_GAP),
+        right: bounds.right + (side === "right" ? approach : ROUTING_GAP),
+        bottom: bounds.bottom + (side === "bottom" ? approach : 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) {
+/** Extend the target obstacle through the final bend and arrow approach so grid search cannot fold back into either reservation. */
+function orthogonalPortPath(edge, from, to, obstacles, targetOffset, nodes) {
     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)]);
+    const end = portPoint(to, toDirection, targetOffset);
+    const approach = Math.max(MIN_ARROW_APPROACH, (edge.style?.strokeWidth ?? 2) * ARROW_MARKER_SIZE + ROUTING_GAP);
+    const fromOutline = nodeBounds(from);
+    const toOutline = nodeBounds(to);
+    const fromRun = availablePortRun(portStub(start, fromDirection, fromOutline), fromDirection, ROUTING_GAP, [...obstacles, toOutline]);
+    // Tight gaps clamp the preferred bridge lane to these stubs before the bend radius is reduced.
+    const toRun = availablePortRun(portStub(end, toDirection, toOutline), toDirection, approach + ORTHOGONAL_BEND_RADIUS, [...obstacles, fromOutline]);
+    const fromBounds = routingBounds(fromOutline, fromDirection, fromRun);
+    const toBounds = routingBounds(toOutline, toDirection, toRun);
+    const startStub = portStub(start, fromDirection, fromBounds);
+    const endStub = portStub(end, toDirection, toBounds);
+    const routingObstacles = [...obstacles.map((bounds) => routingBounds(bounds)), fromBounds, toBounds];
+    const preferred = preferredPortPath(startStub, endStub, fromDirection, toDirection, [fromOutline, toOutline, ...separateAncestorBounds(from, to, nodes)], approach);
+    const clear = preferred && preferred.every((point, index) => index === 0
+        || !blockedSegment(preferred[index - 1], point, routingObstacles));
+    const middle = clear ? preferred : orthogonalPath(startStub, endStub, routingObstacles);
     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)
+/** Prefer a centered bridge or a single outside channel; obstacle search handles unsafe candidates. */
+function preferredPortPath(start, end, from, to, outlines, clearance) {
+    const vertical = from === "top" || from === "bottom";
+    if (vertical !== (to === "top" || to === "bottom"))
+        return undefined;
+    const axis = vertical ? "y" : "x";
+    const normal = portNormal(from);
+    const sign = vertical ? normal.y : normal.x;
+    let lane;
+    if (from === to) {
+        const boundary = vertical ? (sign < 0 ? "top" : "bottom") : (sign < 0 ? "left" : "right");
+        const extents = outlines.map((bounds) => bounds[boundary]);
+        const naturalLane = (sign < 0 ? Math.min(...extents) : Math.max(...extents)) + sign * clearance;
+        // Ancestor clearance and endpoint reservations have separate responsibilities:
+        // move outward only when a reserved endpoint stub extends beyond the natural lane.
+        lane = sign < 0 ? Math.min(naturalLane, start[axis], end[axis]) : Math.max(naturalLane, start[axis], end[axis]);
+    }
+    else {
+        // Stubs bound the legal turning interval, including the target's arrow footprint.
+        if ((end[axis] - start[axis]) * sign < 0)
+            return undefined;
+        const first = outlines[0];
+        const last = outlines[1];
+        const sourceSide = vertical ? (sign < 0 ? first.top : first.bottom) : (sign < 0 ? first.left : first.right);
+        const targetSide = vertical ? (sign < 0 ? last.bottom : last.top) : (sign < 0 ? last.right : last.left);
+        const midpoint = (sourceSide + targetSide) / 2;
+        lane = Math.max(Math.min(start[axis], end[axis]), Math.min(Math.max(start[axis], end[axis]), midpoint));
+    }
+    return simplifyPoints([start, { ...start, [axis]: lane }, { ...end, [axis]: lane }, end]);
+}
+/** Only separate ancestor frames affect outside lanes; a shared container must not push an internal edge outside. */
+function separateAncestorBounds(from, to, nodes) {
+    const byId = new Map(nodes.map((node) => [node.id, node]));
+    const ancestors = (node) => {
+        const result = [];
+        let parent = node.parentId ? byId.get(node.parentId) : undefined;
+        while (parent) {
+            result.push(parent);
+            parent = parent.parentId ? byId.get(parent.parentId) : undefined;
+        }
+        return result;
     };
+    const sourceAncestors = ancestors(from);
+    const targetAncestors = ancestors(to);
+    const sourceIds = new Set([from.id, ...sourceAncestors.map(({ id }) => id)]);
+    const targetIds = new Set([to.id, ...targetAncestors.map(({ id }) => id)]);
+    return [...sourceAncestors.filter(({ id }) => !targetIds.has(id)),
+        ...targetAncestors.filter(({ id }) => !sourceIds.has(id))].map(nodeBounds);
+}
+/** Share narrow endpoint gaps instead of putting a reserved stub inside the opposite node. */
+function availablePortRun(point, side, desired, obstacles) {
+    const vertical = side === "top" || side === "bottom";
+    const normal = portNormal(side);
+    return obstacles.reduce((run, bounds) => {
+        const transverse = vertical ? point.x : point.y;
+        const minimum = vertical ? bounds.left : bounds.top;
+        const maximum = vertical ? bounds.right : bounds.bottom;
+        if (transverse < minimum - ROUTING_GAP || transverse > maximum + ROUTING_GAP)
+            return run;
+        const distance = vertical
+            ? (side === "top" ? bounds.bottom - point.y : bounds.top - point.y) * normal.y
+            : (side === "left" ? bounds.right - point.x : bounds.left - point.x) * normal.x;
+        if (distance < 0)
+            return run;
+        return Math.min(run, Math.max(distance - ROUTING_GAP, distance / 2));
+    }, desired);
+}
+function portStub(point, direction, bounds) {
+    if (direction === "top")
+        return { x: point.x, y: bounds.top };
+    if (direction === "bottom")
+        return { x: point.x, y: bounds.bottom };
+    if (direction === "left")
+        return { x: bounds.left, y: point.y };
+    return { x: bounds.right, y: point.y };
 }
 /** Select cardinal sides from the dominant center-to-center axis for automatic routes. */
 function automaticPorts(from, to) {
@@ -173,15 +395,20 @@ function automaticPorts(from, to) {
     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) {
+function portPoint(node, direction, offset = 0) {
     const center = { x: node.x + node.width / 2, y: node.y + node.height / 2 };
+    const vertical = direction === "top" || direction === "bottom";
+    const radius = (vertical ? node.width : node.height) / 2;
+    const contour = Math.sqrt(Math.max(0, 1 - (offset / radius) ** 2));
+    const inset = node.kind === "ellipse" ? (vertical ? node.height : node.width) / 2 * (1 - contour)
+        : node.kind === "cylinder" && vertical ? Math.min(CYLINDER_CAP_RADIUS, node.height / 4) * (1 - contour) : 0;
     if (direction === "top")
-        return { x: center.x, y: node.y };
+        return { x: center.x + offset, y: node.y + inset };
     if (direction === "right")
-        return { x: node.x + node.width, y: center.y };
+        return { x: node.x + node.width - inset, y: center.y + offset };
     if (direction === "bottom")
-        return { x: center.x, y: node.y + node.height };
-    return { x: node.x, y: center.y };
+        return { x: center.x + offset, y: node.y + node.height - inset };
+    return { x: node.x + inset, y: center.y + offset };
 }
 /** Generate a smooth cubic route whose endpoint tangents follow port normals. */
 function curvedPath(start, end, fromDirection, toDirection, separation) {

package/dist/core/model.d.ts

@@ -2,7 +2,7 @@
 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. */
+/** Route families generated from node geometry; orthogonal routes avoid obstacles with rounded bends, 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";
@@ -14,6 +14,14 @@ export type ThemeName = "light" | "dark";
 export interface Viewport {
     width: number;
     height: number;
+    /**
+     * Fit full-view height to current painted geometry plus finite nonnegative bottom padding, in diagram units.
+     * Round height outward to whole units. Keep origin and authored width; empty frames use authored height. Explicit focus keeps authored viewport semantics.
+     * GIF export uses authored fixed dimensions for every frame to preserve diagram scale.
+     */
+    fitHeight?: {
+        padding: number;
+    };
 }
 /** Initial base style; colors accept hexadecimal RGB/RGBA only, and dashed is used for group borders. */
 export interface NodeStyle {
@@ -58,7 +66,7 @@ export interface DiagramEdge {
     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. */
+    /** Optional target side, otherwise selected automatically. Same-side curved and orthogonal inputs receive separate positions, including hidden inputs. */
     toPort?: PortDirection;
     visible?: boolean;
     style?: EdgeStyle;
@@ -83,15 +91,26 @@ export interface Scene {
     label: string;
     beats: Beat[];
 }
+/** Immutable effective beat interval in global milliseconds; caption includes inherited text. */
+export interface DiagramBeat {
+    readonly sceneId: string;
+    readonly beatId: string;
+    /** Zero-based index within the scene. */
+    readonly beatIndex: number;
+    readonly startMs: number;
+    readonly endMs: number;
+    readonly caption?: string;
+}
 /**
  * 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.
+ * One flow moves at a reference 180 diagram units/second with a 400 ms minimum, then uses a 500 ms post-arrival interval.
+ * Single-flow duration replaces authored timing; multiple flows share authored full-beat progress. All flows expire without inheritance.
  */
 export interface Beat {
-    /** Total length in milliseconds, including the transition and any remaining hold time. */
+    /** Authored beat length in milliseconds for no-flow/multi-flow beats; one flow uses movement plus 500 ms. */
     durationMs: number;
-    /** Opening transition in milliseconds; defaults to min(250, durationMs), and zero applies changes immediately. */
+    /** Opening transition in milliseconds; defaults to min(250, durationMs), clamps to effective beat length, and zero applies changes immediately. */
     transitionMs?: number;
     /** Replaces the inherited caption at the beat start; an empty string clears it. */
     caption?: string;
@@ -124,7 +143,11 @@ export interface EdgeVisualState {
 }
 /**
  * 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.
+ * Flow markers and their temporary highlights expire at the beat end without changing persistent layers.
+ * Flows highlight their edge and, by default, both endpoints; highlightParticipants: false excludes the endpoints.
+ * Single-flow receiver paint fades in for 200 ms after arrival, holds for 100 ms, then automatic node/edge paint fades out for 200 ms.
+ * Logical participant flags and markers last for the whole beat; explicit highlights retain authored timing.
+ * Reduced motion skips paint interpolation. Multiple flows retain synchronized endpoint paint.
  * 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.
  */
@@ -148,6 +171,8 @@ export type Action = {
     direction: FlowDirection;
     /** Plain short message for this transfer; provided text uses a horizontal capsule instead of a dot. */
     text?: string;
+    /** Defaults to true. False disables temporary endpoint highlights; explicit highlights and the flow edge are unchanged. */
+    highlightParticipants?: boolean;
 };
 /** Validation path and reason, for example scenes[0].beats[1].actions[0].target. */
 export interface ValidationIssue {
@@ -156,13 +181,13 @@ export interface ValidationIssue {
 }
 /**
  * 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.
+ * reducedMotion completes transitions immediately and hides flow markers while retaining the flow's configured 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. */
+    /** Apply target values immediately and hide flow markers; retain configured flow highlights, beat durations and selection. */
     reducedMotion?: boolean;
 }
 /** Deterministically laid-out line; x/y specify its centered anchor and text baseline in SVG document coordinates. */
@@ -183,6 +208,7 @@ export interface EvaluatedNode extends DiagramNode {
     visible: boolean;
     /** Effective opacity in [0, 1], including visibility transitions and ancestor opacity. */
     opacity: number;
+    /** Logical highlight state; automatic single-flow paint can still be pending or interpolating. */
     highlighted: boolean;
     labelLines: string[];
     labelBoxes: TextLine[];
@@ -203,7 +229,7 @@ export interface EvaluatedEdge extends DiagramEdge {
 /** 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). */
+    /** Linear movement completion in [0, 1]; a single flow holds at 1 until its beat ends. */
     progress: number;
     point: DiagramPoint;
     /** Unmodified beat-local message; SVG uses deterministic code-point widths and keeps the capsule horizontal. */

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

@@ -0,0 +1,34 @@
+/** Author-time content measurement shares deterministic core layout and never reads browser font metrics. */
+import { type NodeContent } from "./node-content.js";
+/** Inputs use diagram units and the same content styles as fixed-size nodes. */
+export interface NodeContentMeasurementInput {
+    kind: "rect" | "roundedRect" | "cylinder";
+    /** Positive finite node width in diagram units. */
+    width: number;
+    /** One content version or a nonempty collection; caller-owned objects and arrays are never mutated. */
+    content: NodeContent | readonly NodeContent[];
+}
+/** Unresolved overflow for a zero-based content version and its source path. */
+export interface NodeContentMeasurementDiagnostic {
+    /** A single content object uses index zero. */
+    versionIndex: number;
+    /** Normalized source path, such as content[1].blocks[0]. */
+    path: string;
+    /** Height refers to overflow inside a fixed-height graph block. */
+    dimension: "width" | "height";
+    message: string;
+}
+/** A fixed node height in diagram units; diagnostics can still require content or width changes. */
+export interface NodeContentMeasurement {
+    /** Positive finite recommended node height, including complete line boxes and shape clearance. */
+    height: number;
+    diagnostics: NodeContentMeasurementDiagnostic[];
+}
+/**
+ * Measure content before creating a document, using deterministic SDK text estimates rather than browser fonts.
+ * Multiple versions share their largest required height. Diagnostics retain every unresolved block overflow.
+ * The caller writes the result into explicit node dimensions; input objects and arrays remain unchanged.
+ * Finite source values can overflow height arithmetic; validation issues identify every affected content version.
+ * @throws {DiagramValidationError} If input is invalid or any required node height is non-finite.
+ */
+export declare function measureNodeContent(input: NodeContentMeasurementInput): NodeContentMeasurement;

package/dist/core/node-content-measurement.js

@@ -0,0 +1,66 @@
+/** Author-time content measurement shares deterministic core layout and never reads browser font metrics. */
+import { layoutNodeContentWithMetrics, supportsNodeContent, validateNodeContent } from "./node-content.js";
+import { DiagramValidationError } from "./validation.js";
+import { resolveThemePalette } from "./theme.js";
+/**
+ * Measure content before creating a document, using deterministic SDK text estimates rather than browser fonts.
+ * Multiple versions share their largest required height. Diagnostics retain every unresolved block overflow.
+ * The caller writes the result into explicit node dimensions; input objects and arrays remain unchanged.
+ * Finite source values can overflow height arithmetic; validation issues identify every affected content version.
+ * @throws {DiagramValidationError} If input is invalid or any required node height is non-finite.
+ */
+export function measureNodeContent(input) {
+    const issues = validateMeasurementInput(input);
+    if (issues.length > 0)
+        throw new DiagramValidationError(issues);
+    const versions = isContentVersions(input.content) ? input.content : [input.content];
+    const diagnostics = [];
+    const heights = versions.map((content, versionIndex) => {
+        // Saturate shape clearance once. Any nonempty cylinder needs more height than its capped end reserves.
+        const { contentHeight, layout, overflows } = layoutNodeContentWithMetrics(content, { x: 0, y: 0, width: input.width, height: Number.MAX_VALUE }, resolveThemePalette(undefined), input.kind);
+        // Append separately so overflowing block counts cannot exceed the engine's function-argument limit.
+        for (const { blockIndex, dimension } of overflows) {
+            diagnostics.push({ versionIndex, path: `content[${versionIndex}].blocks[${blockIndex}]`, dimension,
+                message: dimension === "width" ? "content exceeds the available width; increasing node height cannot fix this overflow"
+                    : "graph content exceeds its fixed block height; increasing node height cannot fix this overflow"
+            });
+        }
+        const height = contentHeight + layout.safeArea.y * 2;
+        // Individually finite source values can still overflow when line heights, gaps and insets are combined.
+        if (!Number.isFinite(height)) {
+            issues.push({ path: `content[${versionIndex}]`, message: "required node height must be finite" });
+        }
+        return height;
+    });
+    if (issues.length > 0)
+        throw new DiagramValidationError(issues);
+    return { height: heights.reduce((largest, height) => Math.max(largest, height), 1), diagnostics };
+}
+function isContentVersions(value) {
+    return Array.isArray(value);
+}
+/** Reuse document content validation before layout so malformed JavaScript inputs receive field errors. */
+function validateMeasurementInput(input) {
+    if (typeof input !== "object" || input === null || Array.isArray(input)) {
+        return [{ path: "$", message: "measurement input must be an object" }];
+    }
+    const issues = [];
+    for (const field of Object.keys(input)) {
+        if (!["kind", "width", "content"].includes(field))
+            issues.push({ path: field, message: "unknown field" });
+    }
+    if (!("kind" in input) || !supportsNodeContent(input.kind)) {
+        issues.push({ path: "kind", message: "must be rect, roundedRect or cylinder" });
+    }
+    if (!("width" in input) || typeof input.width !== "number" || !Number.isFinite(input.width) || input.width <= 0) {
+        issues.push({ path: "width", message: "must be a finite number greater than zero" });
+    }
+    const content = "content" in input ? input.content : undefined;
+    const versions = Array.isArray(content) ? content : [content];
+    if (versions.length === 0)
+        issues.push({ path: "content", message: "must contain at least one content version" });
+    for (let index = 0; index < versions.length; index += 1) {
+        validateNodeContent(versions[index], `content[${index}]`, issues);
+    }
+    return issues;
+}

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

@@ -27,6 +27,8 @@ export type ContentText = string | ContentTextSpan[];
 /** Controlled tag typography and optional background; tags remain left-aligned within the item. */
 export interface ContentTagStyle extends ContentSpanStyle {
     fill?: string;
+    /** Rounded corners by default; pill uses half the final tag height without changing text layout. */
+    shape?: "rounded" | "pill";
 }
 /** A decorative text tag, without an independent identity or interaction. */
 export interface ContentTag {
@@ -159,6 +161,8 @@ export interface ContentLine {
 export interface ContentTagBackground extends ContentSafeArea {
     fill: string;
     explicitFill: boolean;
+    /** Omitted shape uses the default rounded corners; pill follows the final aligned height. */
+    shape?: ContentTagStyle["shape"];
     blockIndex: number;
     itemIndex: number;
     tagIndex: number;
@@ -176,6 +180,19 @@ export interface NodeContentLayout {
 export declare function supportsNodeContent(kind: unknown): boolean;
 /** Lay out current content from the top left, without DOM font measurement or authored-size changes. */
 export declare function layoutNodeContent(content: NodeContent, bounds: ContentSafeArea, palette: ThemePalette, kind: NodeKind): NodeContentLayout;
+/**
+ * Internal layout shared by fixed-size evaluation and author-time measurement.
+ * contentHeight includes complete line boxes, padded tags, graph block heights and all authored gaps.
+ * overflows retain only width limits and graph-internal height limits; outer node height remains adjustable.
+ */
+export declare function layoutNodeContentWithMetrics(content: NodeContent, bounds: ContentSafeArea, palette: ThemePalette, kind: NodeKind): {
+    layout: NodeContentLayout;
+    contentHeight: number;
+    overflows: {
+        blockIndex: number;
+        dimension: "width" | "height";
+    }[];
+};
 /** Validate nested content separately from shape and label-mode checks at the document boundary. */
 export declare function validateNodeContent(value: unknown, path: string, issues: ValidationIssue[]): void;
 /** Validate inline source values before evaluation; unknown fields keep their exact source position. */