flowsvg 0.1.0 → 0.1.1

package/dist/core/edge-geometry.js

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

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

@@ -1,9 +1,5 @@
-/**
- * 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. */
@@ -258,49 +254,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/{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";

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 { 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 {
@@ -53,6 +53,4 @@ export declare class CompiledTimeline {
     /** 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 {};

package/dist/{timeline.js → core/timeline.js}

@@ -1,3 +1,4 @@
+import { mixColor } from "./color.js";
 const DEFAULT_TRANSITION_MS = 250;
 const NUMERIC_VISUAL_FIELDS = ["x", "y", "width", "height", "opacity", "strokeWidth"];
 const DEFAULT_STROKE_WIDTH = 2;
@@ -145,20 +146,3 @@ function interpolateValues(source, target, progress, palette) {
         stroke: mixColor(source.values.stroke ?? strokeFallback, target.values.stroke ?? strokeFallback, progress)
     };
 }
-/** Interpolate validated hexadecimal RGB/RGBA channels; preserve endpoint strings and normalize intermediate colors. */
-export function mixColor(source, target, progress) {
-    if (progress === 0)
-        return source;
-    if (progress === 1)
-        return target;
-    const channels = (color) => {
-        const hex = color.slice(1);
-        const expanded = hex.length <= 4 ? [...hex].map((digit) => digit + digit).join("") : hex;
-        return [0, 2, 4, 6].map((offset) => offset < expanded.length ? parseInt(expanded.slice(offset, offset + 2), 16) : 255);
-    };
-    const from = channels(source);
-    const to = channels(target);
-    const values = from.map((value, index) => Math.round(value + (to[index] - value) * progress));
-    const hex = values.map((value) => value.toString(16).padStart(2, "0"));
-    return `#${hex.slice(0, values[3] === 255 ? 3 : 4).join("")}`;
-}

package/dist/core/validation.d.ts

@@ -0,0 +1,11 @@
+import type { ValidationIssue } from "./model.js";
+/** 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[];