flowsvg 0.1.0 → 0.2.0

package/dist/{core.d.ts → core/model.d.ts}

@@ -1,12 +1,8 @@
-/**
- * Platform-independent core: validate and compile documents, then derive geometry, hit tests and static SVG.
- * The browser consumes these results; this module does not read the DOM, network, system theme or browser clock.
- */
-import { type NodeContent, type NodeContentLayout } from "./node-content.js";
-export type { NodeContent, ContentBlock, ContentListItem, ContentListStyle, ContentTag, ContentTagStyle, ContentTagBackground, ContentGraphBlock, ContentGraphNode, ContentGraphEdge, ContentGraphLayout, ContentText, ContentTextSpan, ContentSpanStyle, ContentSpan, ContentTextStyle, ContentAlignment, ContentSafeArea, ContentLine, NodeContentLayout } from "./node-content.js";
+/** Shared serializable document and evaluated-frame types; no runtime or platform dependencies. */
+import type { NodeContent, NodeContentLayout } from "./node-content.js";
 /** Supported shapes; a group also supplies the origin and visibility constraints for its children. */
 export type NodeKind = "rect" | "roundedRect" | "ellipse" | "cylinder" | "group";
-/** Route families generated from node geometry; orthogonal routes avoid obstacles, and curved routes use cubic Bézier controls. */
+/** 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";
@@ -18,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 {
@@ -62,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;
@@ -87,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;
@@ -128,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.
  */
@@ -152,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 {
@@ -160,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. */
@@ -187,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[];
@@ -207,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. */
@@ -258,49 +280,3 @@ export interface DiagramFrameState {
     caption?: string;
     warnings: LayoutWarning[];
 }
-/** Compilation error for invalid documents; issues contains all field problems found by validation. */
-export declare class DiagramValidationError extends Error {
-    readonly issues: readonly ValidationIssue[];
-    constructor(issues: ValidationIssue[]);
-}
-/**
- * Validate document structure, values and references; an empty list means validation passed.
- * Accumulate issues across inspectable branches without mutating input or producing a partial Diagram.
- */
-export declare function validateDocument(input: unknown): ValidationIssue[];
-/**
- * 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.
- */
-export declare function createDiagram(input: DiagramDocument): Diagram;
-/** One-shot static SVG export; use createDiagram to reuse compilation across repeated evaluations or exports. */
-export declare function renderSvg(document: DiagramDocument, timeMs?: number, options?: EvaluateOptions): string;
-/** Compiled diagram independent of the DOM, network and clock; each query evaluates from its time and options. */
-export interface Diagram {
-    /** Global timeline duration in milliseconds; zero for static diagrams. */
-    readonly totalDuration: number;
-    /**
-     * Evaluate a frame; finite times clamp to [0, totalDuration], and non-finite times become zero.
-     * Beat intervals include their start and exclude their end; totalDuration returns the completed final beat.
-     */
-    evaluateAt(timeMs: number, options?: EvaluateOptions): DiagramFrameState;
-    /** Serialize the same frame as self-contained static SVG with escaped text and resolved colors, without controls. */
-    renderSvg(timeMs?: number, options?: EvaluateOptions): string;
-    /**
-     * Hit-test document coordinates in paint order: ordinary nodes, then edges, then group backgrounds.
-     * Objects within each layer are searched in reverse document order.
-     * Node hits include their visible label area. Hidden/zero-opacity objects are excluded.
-     * Return null for no hit or non-finite coordinates.
-     */
-    hitTest(timeMs: number, point: DiagramPoint, options?: EvaluateOptions): HitObject | null;
-}
-interface Typography {
-    fontSize: number;
-    lineHeight: number;
-    charWidth: number;
-}
-/**
- * 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 declare function wrapText(label: string, maxWidth: number, typography?: Typography): string[];

package/dist/core/model.js

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

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/{node-content-paint.d.ts → core/node-content-paint.d.ts}

@@ -4,7 +4,7 @@
  */
 import type { NodeContentLayout } from "./node-content.js";
 /**
- * Blend only default paint by the node highlight amount; preserve safe areas, metrics and author provenance.
- * The evaluated fill selects readable ink during transitions: naive light-to-dark ink blending loses contrast midway.
+ * Retain theme-specific semantic ink and tag fills; preserve geometry and explicit author colors.
+ * Check default ink against the evaluated fill because authored base fills can cross low-contrast transition colors.
  */
 export declare function paintContentHighlight(layout: NodeContentLayout, amount: number, fill: string): NodeContentLayout;

package/dist/{node-content-paint.js → core/node-content-paint.js}

@@ -1,42 +1,33 @@
-import { mixColor } from "./timeline.js";
-const HIGHLIGHT_CONTENT_COLORS = {
-    title: "#172033", body: "#172033", marker: "#172033", auxiliary: "#354158", tag: "#164b9b", status: "#16466b"
-};
-const HIGHLIGHT_TAG_FILL = "#eaf1ff";
 const MIN_CONTENT_CONTRAST = 4.5;
 const CONTRAST_DARK_INK = "#000000";
 const CONTRAST_LIGHT_INK = "#ffffff";
 /**
- * Blend only default paint by the node highlight amount; preserve safe areas, metrics and author provenance.
- * The evaluated fill selects readable ink during transitions: naive light-to-dark ink blending loses contrast midway.
+ * Retain theme-specific semantic ink and tag fills; preserve geometry and explicit author colors.
+ * Check default ink against the evaluated fill because authored base fills can cross low-contrast transition colors.
  */
 export function paintContentHighlight(layout, amount, fill) {
     if (amount === 0)
         return layout;
-    const tags = layout.tags.map((tag) => ({ ...tag, fill: tag.explicitFill ? tag.fill : mixColor(tag.fill, HIGHLIGHT_TAG_FILL, amount) }));
     return {
-        ...layout, tags,
+        ...layout,
         ...(layout.graphs ? { graphs: layout.graphs.map((graph) => ({ ...graph,
-                nodes: graph.nodes.map((node) => ({ ...node, fill: readableDefaultInk(node.fill, HIGHLIGHT_CONTENT_COLORS[node.highlighted ? "status" : "auxiliary"], amount, fill) })),
-                edges: graph.edges.map((edge) => ({ ...edge, color: readableDefaultInk(edge.color, HIGHLIGHT_CONTENT_COLORS[edge.highlighted ? "status" : "auxiliary"], amount, fill) }))
+                nodes: graph.nodes.map((node) => ({ ...node, fill: readableDefaultInk(node.fill, fill) })),
+                edges: graph.edges.map((edge) => ({ ...edge, color: readableDefaultInk(edge.color, fill) }))
             })) } : {}),
         lines: layout.lines.map((line) => {
-            const tag = line.role === "tag" ? tags.find((candidate) => candidate.blockIndex === line.blockIndex
+            const tag = line.role === "tag" ? layout.tags.find((candidate) => candidate.blockIndex === line.blockIndex
                 && candidate.itemIndex === line.itemIndex && candidate.tagIndex === line.tagIndex) : undefined;
             const background = tag?.fill ?? fill;
-            const paint = (color) => readableDefaultInk(color, HIGHLIGHT_CONTENT_COLORS[line.role], amount, background);
+            const paint = (color) => readableDefaultInk(color, background);
             const spans = line.spans.map((span) => ({ ...span, color: span.explicitColor ? span.color : paint(span.color) }));
             return { ...line, spans, color: spans[0]?.color ?? paint(line.color) };
         })
     };
 }
-/** Retain semantic ink when it meets contrast; use opaque dark/light ink only across the transition's narrow middle. */
-function readableDefaultInk(source, target, amount, background) {
-    const blended = mixColor(source, target, amount);
-    for (const candidate of [blended, source, target]) {
-        if (contrastRatio(candidate, background) >= MIN_CONTENT_CONTRAST)
-            return candidate;
-    }
+/** Keep semantic ink when readable; otherwise select opaque dark/light ink without changing author colors. */
+function readableDefaultInk(source, background) {
+    if (contrastRatio(source, background) >= MIN_CONTENT_CONTRAST)
+        return source;
     return contrastRatio(CONTRAST_DARK_INK, background) >= contrastRatio(CONTRAST_LIGHT_INK, background)
         ? CONTRAST_DARK_INK : CONTRAST_LIGHT_INK;
 }

package/dist/{node-content.d.ts → core/node-content.d.ts}

@@ -2,7 +2,7 @@
  * Deterministic node-content model and layout. The core supplies current absolute node geometry and theme colors.
  * This module does not measure browser fonts or mutate authored dimensions; SVG consumes its evaluated lines and tag backgrounds.
  */
-import type { NodeKind, ValidationIssue } from "./core.js";
+import type { NodeKind, ValidationIssue } from "./model.js";
 import type { ThemePalette } from "./theme.js";
 /** Horizontal placement within the current content safe area. */
 export type ContentAlignment = "left" | "center" | "right";
@@ -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. */

package/dist/{node-content.js → core/node-content.js}

@@ -43,26 +43,44 @@ function contentSafeArea(bounds, padding, kind) {
 }
 /** Lay out current content from the top left, without DOM font measurement or authored-size changes. */
 export function layoutNodeContent(content, bounds, palette, kind) {
+    return layoutNodeContentWithMetrics(content, bounds, palette, kind).layout;
+}
+/**
+ * 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 function layoutNodeContentWithMetrics(content, bounds, palette, kind) {
     const safeArea = contentSafeArea(bounds, content.style?.padding ?? DEFAULT_PADDING, kind);
     let cursorY = safeArea.y;
     let widthOverflow = false;
     let heightOverflow = false;
     const tags = [];
     const graphs = [];
+    const overflows = [];
     const lines = content.blocks.flatMap((block, blockIndex) => {
         const result = block.type === "graph"
             ? layoutContentGraph(block, safeArea, cursorY, palette, blockIndex, graphs)
             : block.type === "list"
                 ? layoutContentList(block, safeArea, cursorY, palette, blockIndex)
                 : layoutTextPart(block.text, block.type === "title" ? "title" : block.role ?? "body", block.style, safeArea, cursorY, palette, blockIndex);
-        widthOverflow ||= result.widthOverflow;
+        const blockWidthOverflow = result.widthOverflow || result.lines.some((line) => contentLineExceedsWidth(line, safeArea));
+        if (blockWidthOverflow)
+            overflows.push({ blockIndex, dimension: "width" });
+        if (result.heightOverflow)
+            overflows.push({ blockIndex, dimension: "height" });
+        widthOverflow ||= blockWidthOverflow;
         heightOverflow ||= result.heightOverflow ?? false;
         tags.push(...result.tags);
         cursorY = result.bottom + (blockIndex < content.blocks.length - 1 ? content.style?.blockGap ?? DEFAULT_BLOCK_GAP : 0);
         return result.lines;
     });
-    return { safeArea, lines, tags, ...(graphs.length ? { graphs } : {}), widthOverflow: widthOverflow || lines.some((line) => contentLineExceedsWidth(line, safeArea)),
-        heightOverflow: heightOverflow || cursorY > safeArea.y + safeArea.height };
+    return { contentHeight: cursorY - safeArea.y, overflows, layout: {
+            safeArea, lines, tags, ...(graphs.length ? { graphs } : {}),
+            widthOverflow,
+            // Authored positions change accumulation rounding; use the same geometric tolerance as width checks.
+            heightOverflow: heightOverflow || cursorY > safeArea.y + safeArea.height + OVERFLOW_TOLERANCE
+        } };
 }
 /** Graph labels reuse text metrics; authored graph geometry is clipped instead of resized. */
 function layoutContentGraph(block, area, top, palette, blockIndex, graphs) {
@@ -82,7 +100,9 @@ function layoutContentGraph(block, area, top, palette, blockIndex, graphs) {
     graphs.push({ blockIndex, nodes, edges });
     return { lines: parts.flatMap((part) => part.lines), tags: [],
         bottom: top + block.height,
-        heightOverflow: parts.some((part) => part.lines.some((line) => line.y - line.fontSize < top) || part.bottom > top + block.height)
+        // Recovering a label top from its absolute baseline can round across the block boundary.
+        heightOverflow: parts.some((part) => part.lines.some((line) => line.y - line.fontSize < top - OVERFLOW_TOLERANCE)
+            || part.bottom > top + block.height)
             || block.nodes.some((node) => node.y - GRAPH_NODE_RADIUS < 0 || node.y + GRAPH_NODE_RADIUS > block.height),
         widthOverflow: parts.some((part) => part.widthOverflow) || block.nodes.some((node) => node.x < GRAPH_NODE_RADIUS
             || node.x + GRAPH_NODE_RADIUS > area.width) };
@@ -215,7 +235,8 @@ function layoutContentTag(tag, area, top, palette, blockIndex, itemIndex, tagInd
     return { ...result, widthOverflow: result.widthOverflow || area.width < TAG_PADDING_X * 2,
         lines: result.lines.map((line) => ({ ...line, tagIndex })), bottom: result.bottom + TAG_PADDING_Y,
         tags: [{ x: area.x, y: top, width: area.width, height: result.bottom - top + TAG_PADDING_Y,
-                fill: tag.style?.fill ?? palette.tagFill, explicitFill: tag.style?.fill !== undefined, blockIndex, itemIndex, tagIndex }] };
+                fill: tag.style?.fill ?? palette.tagFill, explicitFill: tag.style?.fill !== undefined,
+                ...(tag.style?.shape === undefined ? {} : { shape: tag.style.shape }), blockIndex, itemIndex, tagIndex }] };
 }
 /** Baseline shifts preserve line spacing and expand tag backgrounds instead of moving the row boundary. */
 function shiftTagText(part, offset) {
@@ -473,10 +494,13 @@ function validateContentTags(value, path, issues) {
             validateContentTextStyle(tag.style, `${tagPath}.style`, issues, true);
             continue;
         }
-        const { fill, ...textStyle } = tag.style;
+        const { fill, shape, ...textStyle } = tag.style;
         validateContentTextStyle(textStyle, `${tagPath}.style`, issues, true);
         if (fill !== undefined)
             validateColor(fill, `${tagPath}.style.fill`, issues);
+        if (shape !== undefined && shape !== "rounded" && shape !== "pill") {
+            issues.push({ path: `${tagPath}.style.shape`, message: "must be rounded or pill" });
+        }
     }
 }
 /** Validate inline source values before evaluation; unknown fields keep their exact source position. */

package/dist/core/svg-number.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Shared SVG number serialization. Geometry and SVG serialization use this
+ * deterministic format so moving either implementation cannot change output.
+ */
+export declare function formatNumber(value: number): string;

package/dist/core/svg-number.js

@@ -0,0 +1,7 @@
+/**
+ * Shared SVG number serialization. Geometry and SVG serialization use this
+ * deterministic format so moving either implementation cannot change output.
+ */
+export function formatNumber(value) {
+    return Number.isInteger(value) ? String(value) : String(Number(value.toFixed(3)));
+}

package/dist/{theme.d.ts → core/theme.d.ts}

@@ -9,7 +9,13 @@ export interface ThemePalette {
     tagFill: string;
     accentText: string;
     edge: string;
+    /** Border and flow-marker emphasis; node interiors use highlightFill instead. */
     highlight: string;
+    highlightFill: string;
+    highlightText: string;
 }
+export declare const DEFAULT_NODE_STROKE_WIDTH = 1.2;
+export declare const NODE_CORNER_RADIUS = 8;
+export declare const DIAGRAM_FONT_FAMILY = "system-ui, -apple-system, \"PingFang SC\", \"Microsoft YaHei\", \"Noto Sans CJK SC\", sans-serif";
 /** Select a palette without consulting browser preferences. */
 export declare function resolveThemePalette(theme: "light" | "dark" | undefined): ThemePalette;

package/dist/core/theme.js

@@ -0,0 +1,17 @@
+const LIGHT_PALETTE = {
+    background: "#ffffff", fill: "#ffffff", stroke: "#cfd8e3", text: "#1d2939", mutedText: "#5a6473",
+    tagText: "#1d4fa8", tagFill: "#eaf1ff", accentText: "#1d4fa8", edge: "#8892a4",
+    highlight: "#2a63c8", highlightFill: "#eaf1ff", highlightText: "#ffffff"
+};
+const DARK_PALETTE = {
+    background: "#101828", fill: "#1d2939", stroke: "#475467", text: "#f2f4f7", mutedText: "#b8c2d1",
+    tagText: "#caddff", tagFill: "#253b5c", accentText: "#9bbfff", edge: "#98a2b3",
+    highlight: "#8ab4f8", highlightFill: "#233b60", highlightText: "#101828"
+};
+export const DEFAULT_NODE_STROKE_WIDTH = 1.2;
+export const NODE_CORNER_RADIUS = 8;
+export const DIAGRAM_FONT_FAMILY = 'system-ui, -apple-system, "PingFang SC", "Microsoft YaHei", "Noto Sans CJK SC", sans-serif';
+/** Select a palette without consulting browser preferences. */
+export function resolveThemePalette(theme) {
+    return theme === "dark" ? DARK_PALETTE : LIGHT_PALETTE;
+}

package/dist/{timeline.d.ts → core/timeline.d.ts}

@@ -2,7 +2,7 @@
  * Deterministic global timeline: compile actions/snapshots and evaluate base styles, visibility, highlights and focus.
  * Spatial layout and SVG output belong to the core; theme defaults are supplied only during evaluation.
  */
-import type { DiagramDocument, EvaluateOptions, FlowDirection, NodeVisualState, EdgeVisualState } from "./core.js";
+import type { DiagramBeat, DiagramDocument, EvaluateOptions, FlowDirection, NodeVisualState, EdgeVisualState } from "./model.js";
 type VisualValues = NodeVisualState & EdgeVisualState;
 /** Evaluation-time theme defaults; unspecified snapshot colors remain unresolved so compilation does not fix a theme. */
 export interface TimelinePalette {
@@ -10,11 +10,12 @@ export interface TimelinePalette {
     stroke: string;
     edge: string;
 }
-/** One transfer in a synchronized beat-local group; no transfer persists in inherited snapshots. */
+/** One beat-local transfer; single-flow movement may finish before its beat, and no flow persists in snapshots. */
 export interface CompiledFlow {
     target: string;
     direction: FlowDirection;
     text?: string;
+    highlightParticipants: boolean;
 }
 /** Object transition result; highlight is the overlay weight, while highlighted is the target logical state. */
 export interface TimelineObject {
@@ -30,6 +31,12 @@ export interface TimelineFrame {
     sceneId: string | null;
     beatId: string | null;
     beatProgress: number;
+    /** Linear movement completion, clamped at arrival while the beat retains temporary highlights. */
+    flowProgress: number;
+    /** Single-flow receiver paint after arrival; independent of logical highlights and opening transitions. */
+    flowArrivalProgress: number;
+    /** Single-flow automatic paint removal during the last 200 ms; logical flags and marker lifetime are unchanged. */
+    flowDepartureProgress: number;
     transitionProgress: number;
     focusBefore: string | null;
     focusAfter: string | null;
@@ -44,15 +51,14 @@ export interface TimelineFrame {
  */
 export declare class CompiledTimeline {
     readonly totalDuration: number;
+    readonly schedule: readonly DiagramBeat[];
     private readonly beats;
     private readonly initial;
     private readonly title?;
-    constructor(document: DiagramDocument);
+    constructor(document: DiagramDocument, movementDurations?: ReadonlyMap<string, number>);
     /** Clamp finite times globally; reduced motion skips interpolation but preserves beat selection and total duration. */
     evaluateAt(timeMs: number, options: EvaluateOptions, palette: TimelinePalette): TimelineFrame;
     /** Select the next beat at endMs, retaining the last beat at total duration; static documents return undefined. */
     private findBeat;
 }
-/** Interpolate validated hexadecimal RGB/RGBA channels; preserve endpoint strings and normalize intermediate colors. */
-export declare function mixColor(source: string, target: string, progress: number): string;
 export {};