flowsvg 0.0.0-stage → 0.1.0

package/dist/node-content.js

@@ -0,0 +1,554 @@
+const DEFAULT_PADDING = 16;
+const ROUNDED_RECT_INSET = 4;
+const MAX_CYLINDER_CAP_RADIUS = 14;
+const DEFAULT_BLOCK_GAP = 14;
+const DEFAULT_ITEM_GAP = 12;
+const DEFAULT_TAG_GAP = 6;
+const TAG_SIZE = 11;
+const TAG_PADDING_X = 6;
+const TAG_PADDING_Y = 2;
+const LIST_MARKER_GAP = 8;
+const OVERFLOW_TOLERANCE = 0.000001;
+const MIN_LINE_HEIGHT = 20;
+const LINE_HEIGHT_RATIO = 1.35;
+const TITLE_SIZE = 20;
+const BODY_SIZE = 14;
+const AUXILIARY_SIZE = 12;
+const TITLE_WEIGHT = 700;
+const NORMAL_WEIGHT = 400;
+const MIN_FONT_WEIGHT = 100;
+const MAX_FONT_WEIGHT = 900;
+const NARROW_GLYPH_WIDTH_RATIO = 0.6;
+const GRAPH_NODE_RADIUS = 4;
+const GRAPH_LABEL_GAP = 7;
+const GRAPH_LABEL_SIZE = 12;
+const GRAPHEME_SEGMENTER = new Intl.Segmenter("en", { granularity: "grapheme" });
+/** Supported content shapes; node validators share this restriction. */
+export function supportsNodeContent(kind) {
+    return kind === "rect" || kind === "roundedRect" || kind === "cylinder";
+}
+/** Derive the clip from current absolute geometry, reserving shape contours before authored padding. */
+function contentSafeArea(bounds, padding, kind) {
+    const cornerInset = kind === "roundedRect" ? ROUNDED_RECT_INSET : 0;
+    // Match the current SVG cylinder cap; reserve its full diameter above and below the content.
+    const capInset = kind === "cylinder" ? Math.min(MAX_CYLINDER_CAP_RADIUS, bounds.height / 4) * 2 : 0;
+    const horizontalInset = padding + cornerInset;
+    const verticalInset = horizontalInset + capInset;
+    return {
+        x: bounds.x + horizontalInset,
+        y: bounds.y + verticalInset,
+        width: Math.max(0, bounds.width - horizontalInset * 2),
+        height: Math.max(0, bounds.height - verticalInset * 2)
+    };
+}
+/** Lay out current content from the top left, without DOM font measurement or authored-size changes. */
+export function layoutNodeContent(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 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;
+        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 };
+}
+/** Graph labels reuse text metrics; authored graph geometry is clipped instead of resized. */
+function layoutContentGraph(block, area, top, palette, blockIndex, graphs) {
+    const points = new Map(block.nodes.map((node) => [node.id, { x: area.x + node.x, y: top + node.y }]));
+    const nodes = block.nodes.map((node) => ({ ...points.get(node.id), radius: GRAPH_NODE_RADIUS,
+        fill: node.highlighted ? palette.accentText : palette.mutedText, highlighted: node.highlighted ?? false }));
+    const edges = block.edges.map((edge) => {
+        const from = points.get(edge.from), to = points.get(edge.to);
+        const highlighted = [edge.from, edge.to].every((id) => block.nodes.find((node) => node.id === id)?.highlighted);
+        return { x1: from.x, y1: from.y, x2: to.x, y2: to.y, color: highlighted ? palette.accentText : palette.mutedText, highlighted };
+    });
+    const parts = block.nodes.map((node) => {
+        const halfWidth = Math.max(0, Math.min(node.x, area.width - node.x));
+        const labelArea = { ...area, x: area.x + node.x - halfWidth, width: halfWidth * 2 };
+        return layoutTextPart(node.label, "body", { fontSize: GRAPH_LABEL_SIZE, fontWeight: node.highlighted ? 700 : 400, align: "center" }, labelArea, top + node.y - GRAPH_NODE_RADIUS - GRAPH_LABEL_GAP - GRAPH_LABEL_SIZE, palette, blockIndex);
+    });
+    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)
+            || 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) };
+}
+/** Include list indentation when checking the clip; a single oversized grapheme may exceed the body column. */
+function contentLineExceedsWidth(line, area) {
+    return line.width > area.width || line.spans.some((span) => span.x < area.x - OVERFLOW_TOLERANCE
+        || span.x + span.width > area.x + area.width + OVERFLOW_TOLERANCE);
+}
+/**
+ * Resolve role defaults once and reuse baseline/wrapping rules for every text part.
+ * A marked item's first line also reserves its marker size, so smaller source spans cannot lift the marker above the clip.
+ */
+function layoutTextPart(text, role, style, area, top, palette, blockIndex, itemIndex, minimumFirstLineSize = 0) {
+    const fontSize = style?.fontSize ?? (role === "title" ? TITLE_SIZE : role === "auxiliary" || role === "status" ? AUXILIARY_SIZE : role === "tag" ? TAG_SIZE : BODY_SIZE);
+    const fontWeight = style?.fontWeight ?? (role === "title" ? TITLE_WEIGHT : NORMAL_WEIGHT);
+    const color = style?.color ?? (role === "auxiliary" ? palette.mutedText : role === "tag" ? palette.tagText : role === "status" ? palette.accentText : palette.text);
+    const align = style?.align ?? "left";
+    const x = area.x + (align === "right" ? area.width : align === "center" ? area.width / 2 : 0);
+    const wrapped = wrapContentText(text, area.width, { fontSize, fontWeight, color, explicitColor: style?.color !== undefined });
+    let cursorY = top;
+    const lines = wrapped.map((glyphs, lineIndex) => {
+        const textSize = glyphs.length > 0 ? glyphs.reduce((largest, glyph) => Math.max(largest, glyph.style.fontSize), 0) : fontSize;
+        const size = Math.max(textSize, lineIndex === 0 ? minimumFirstLineSize : 0);
+        const width = glyphs.reduce((sum, glyph) => sum + glyph.width, 0);
+        const y = cursorY + size;
+        const startX = x - (align === "right" ? width : align === "center" ? width / 2 : 0);
+        const spans = collectContentSpans(glyphs, startX, y);
+        cursorY += Math.max(MIN_LINE_HEIGHT, size * LINE_HEIGHT_RATIO);
+        return { text: glyphs.map((glyph) => glyph.text).join(""), spans, x, y, width,
+            fontSize: size, fontWeight, color, align, role, blockIndex, ...(itemIndex === undefined ? {} : { itemIndex }) };
+    });
+    return { lines, tags: [], bottom: cursorY, widthOverflow: lines.some((line) => line.width > area.width) };
+}
+function layoutContentList(block, area, top, palette, blockIndex) {
+    let cursorY = top;
+    const lines = [];
+    const tags = [];
+    let widthOverflow = false;
+    const markerWidth = contentMarkerWidth(block);
+    const indent = markerWidth > 0 ? markerWidth + LIST_MARKER_GAP : 0;
+    const bodyArea = { ...area, x: area.x + indent, width: Math.max(0, area.width - indent) };
+    block.items.forEach((item, itemIndex) => {
+        if (!hasContentItem(item))
+            return;
+        if (lines.length > 0)
+            cursorY += block.style?.itemGap ?? DEFAULT_ITEM_GAP;
+        const itemStart = lines.length;
+        const markerSize = markerWidth === 0 ? 0 : item.body === undefined ? item.auxiliaryStyle?.fontSize ?? AUXILIARY_SIZE
+            : item.style?.fontSize ?? block.style?.fontSize ?? BODY_SIZE;
+        const header = layoutItemHeader(item, bodyArea, cursorY, palette, blockIndex, itemIndex, block.style?.tagGap ?? DEFAULT_TAG_GAP, markerSize);
+        lines.push(...header.lines);
+        tags.push(...header.tags);
+        widthOverflow ||= header.widthOverflow;
+        cursorY = header.bottom;
+        if (item.body !== undefined) {
+            const body = layoutTextPart(item.body, "body", inheritContentStyle(block.style, item.style), bodyArea, cursorY, palette, blockIndex, itemIndex, markerSize);
+            lines.push(...body.lines);
+            widthOverflow ||= body.widthOverflow;
+            cursorY = body.bottom;
+        }
+        if (item.auxiliary !== undefined) {
+            const auxiliary = layoutTextPart(item.auxiliary, "auxiliary", item.auxiliaryStyle, bodyArea, cursorY, palette, blockIndex, itemIndex, item.body === undefined ? markerSize : 0);
+            lines.push(...auxiliary.lines);
+            widthOverflow ||= auxiliary.widthOverflow;
+            cursorY = auxiliary.bottom;
+        }
+        if (markerWidth > 0) {
+            const first = lines[itemStart];
+            const style = item.body === undefined ? item.auxiliaryStyle : inheritContentStyle(block.style, item.style);
+            const marker = layoutTextPart(block.marker === "bullet" ? "•" : `${itemIndex + 1}.`, "marker", { ...style, fontSize: style?.fontSize ?? (item.body === undefined ? AUXILIARY_SIZE : BODY_SIZE), align: "left" }, { ...area, width: markerWidth }, top, palette, blockIndex, itemIndex).lines[0];
+            lines.splice(itemStart, 0, { ...marker, y: first.y, spans: marker.spans.map((span) => ({ ...span, y: first.y })) });
+        }
+    });
+    return { lines, tags, bottom: cursorY, widthOverflow };
+}
+/** Tags occupy rows first. Status shares a single row only when both natural widths fit. */
+function layoutItemHeader(item, area, top, palette, blockIndex, itemIndex, gap, markerSize) {
+    const header = layoutContentTags(item.tags ?? [], area, top, palette, blockIndex, itemIndex, gap, markerSize);
+    if (item.status === undefined)
+        return header;
+    const statusWidth = naturalContentWidth(item.status, item.statusStyle, AUXILIARY_SIZE);
+    const lastTag = header.tags.at(-1);
+    const occupied = lastTag ? lastTag.x + lastTag.width - area.x : 0;
+    const singleTagRow = header.tags.every((tag) => tag.y === top) && header.lines.length === header.tags.length;
+    const singleStatusLine = !contentTextString(item.status).match(/[\r\n]/);
+    const sameRow = singleTagRow && singleStatusLine && occupied + (lastTag ? gap : 0) + statusWidth <= area.width;
+    const statusTop = sameRow ? top : header.bottom;
+    let status = layoutTextPart(item.status, "status", { ...item.statusStyle, align: "right" }, area, statusTop, palette, blockIndex, itemIndex, markerSize);
+    let tags = header;
+    if (sameRow && header.lines.length > 0) {
+        const baseline = Math.max(...header.lines.map((line) => line.y), status.lines[0].y);
+        tags = shiftTagText(header, baseline - header.lines[0].y);
+        status = shiftContentPart(status, baseline - status.lines[0].y);
+    }
+    return { lines: [...tags.lines, ...status.lines], tags: tags.tags,
+        bottom: Math.max(tags.bottom, status.bottom), widthOverflow: tags.widthOverflow || status.widthOverflow };
+}
+/** Pack tag boxes in authored order; a long tag wraps inside its own padded full-width box. */
+function layoutContentTags(source, area, top, palette, blockIndex, itemIndex, gap, markerSize) {
+    let row = [];
+    let right = area.x;
+    let result = { lines: [], tags: [], bottom: top, widthOverflow: false };
+    const flush = () => {
+        if (row.length === 0)
+            return;
+        const rowTop = result.tags.length > 0 ? result.bottom + gap : top;
+        const parts = row.map(({ tag, tagIndex, width, x }) => layoutContentTag(tag, { ...area, x, width }, rowTop, palette, blockIndex, itemIndex, tagIndex, markerSize));
+        const baseline = Math.max(...parts.map((part) => part.lines[0].y));
+        const aligned = parts.map((part) => shiftTagText(part, baseline - part.lines[0].y));
+        result = { lines: [...result.lines, ...aligned.flatMap((part) => part.lines)],
+            tags: [...result.tags, ...aligned.flatMap((part) => part.tags)], bottom: Math.max(...aligned.map((part) => part.bottom)),
+            widthOverflow: result.widthOverflow || aligned.some((part) => part.widthOverflow) };
+        row = [];
+        right = area.x;
+    };
+    source.forEach((tag, tagIndex) => {
+        const width = Math.min(area.width, naturalContentWidth(tag.text, tag.style, TAG_SIZE) + TAG_PADDING_X * 2);
+        if (row.length > 0 && right + width > area.x + area.width)
+            flush();
+        row.push({ tag, tagIndex, width, x: right });
+        right += width + gap;
+    });
+    flush();
+    return result;
+}
+function layoutContentTag(tag, area, top, palette, blockIndex, itemIndex, tagIndex, markerSize) {
+    const textArea = { ...area, x: area.x + TAG_PADDING_X, width: Math.max(0, area.width - TAG_PADDING_X * 2) };
+    const result = layoutTextPart(tag.text, "tag", tag.style, textArea, top + TAG_PADDING_Y, palette, blockIndex, itemIndex, markerSize);
+    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 }] };
+}
+/** Baseline shifts preserve line spacing and expand tag backgrounds instead of moving the row boundary. */
+function shiftTagText(part, offset) {
+    return { ...shiftContentPart(part, offset), tags: part.tags.map((tag) => ({ ...tag, height: tag.height + offset })) };
+}
+function shiftContentPart(part, offset) {
+    return { ...part, bottom: part.bottom + offset,
+        lines: part.lines.map((line) => ({ ...line, y: line.y + offset, spans: line.spans.map((span) => ({ ...span, y: span.y + offset })) })) };
+}
+function contentTextString(text) {
+    return typeof text === "string" ? text : text.map((span) => span.text).join("");
+}
+function naturalContentWidth(text, style, defaultSize) {
+    const wrapped = wrapContentText(text, Number.MAX_VALUE, { fontSize: style?.fontSize ?? defaultSize,
+        fontWeight: style?.fontWeight ?? NORMAL_WEIGHT, color: style?.color ?? "#000000", explicitColor: style?.color !== undefined });
+    return Math.max(0, ...wrapped.map((glyphs) => glyphs.reduce((sum, glyph) => sum + glyph.width, 0)));
+}
+function hasContentItem(item) {
+    return item.body !== undefined || item.auxiliary !== undefined || item.status !== undefined || (item.tags?.length ?? 0) > 0;
+}
+/** Every item uses the same marker column, including multi-digit numbers and authored marker sizes. */
+function contentMarkerWidth(block) {
+    if (block.marker === undefined || block.marker === "none")
+        return 0;
+    return block.items.reduce((width, item, index) => {
+        if (!hasContentItem(item))
+            return width;
+        const size = item.body === undefined ? item.auxiliaryStyle?.fontSize ?? AUXILIARY_SIZE
+            : item.style?.fontSize ?? block.style?.fontSize ?? BODY_SIZE;
+        return Math.max(width, estimateContentWidth(block.marker === "bullet" ? "•" : `${index + 1}.`, size));
+    }, 0);
+}
+function inheritContentStyle(base, override) {
+    return { fontSize: override?.fontSize ?? base?.fontSize, fontWeight: override?.fontWeight ?? base?.fontWeight,
+        color: override?.color ?? base?.color, align: override?.align ?? base?.align };
+}
+/** Wrap combined source text, so a style boundary never creates an extra break opportunity. */
+function wrapContentText(text, maxWidth, baseStyle) {
+    const sources = typeof text === "string" ? [{ text }] : text;
+    const glyphs = segmentContentText(sources, baseStyle);
+    const explicitLines = [[]];
+    glyphs.forEach((glyph) => {
+        if (/^\r\n$|^[\r\n]$/.test(glyph.text))
+            explicitLines.push([]);
+        else
+            explicitLines.at(-1).push(glyph);
+    });
+    return explicitLines.flatMap((line) => wrapContentGlyphs(line, maxWidth));
+}
+/** Segment concatenated text before styling: a cluster crossing spans uses its first character's style. */
+function segmentContentText(sources, baseStyle) {
+    const combined = sources.map((source) => source.text).join("");
+    let sourceIndex = 0;
+    let sourceEnd = sources[0]?.text.length ?? 0;
+    return Array.from(GRAPHEME_SEGMENTER.segment(combined), ({ segment: text, index }) => {
+        while (index >= sourceEnd && sourceIndex < sources.length - 1) {
+            sourceIndex += 1;
+            sourceEnd += sources[sourceIndex].text.length;
+        }
+        const sourceStyle = sources[sourceIndex]?.style;
+        const style = { ...baseStyle, ...sourceStyle, explicitColor: sourceStyle?.color !== undefined || baseStyle.explicitColor };
+        return { text, sourceIndex, style, width: estimateContentWidth(text, style.fontSize) };
+    });
+}
+/** Prefer English spaces; fallback always consumes one character even when the safe area is empty. */
+function wrapContentGlyphs(glyphs, maxWidth) {
+    let remaining = glyphs;
+    const lines = [];
+    while (remaining.length > 0) {
+        let count = 0;
+        let width = 0;
+        while (count < remaining.length && width + remaining[count].width <= maxWidth) {
+            width += remaining[count].width;
+            count += 1;
+        }
+        if (count >= remaining.length) {
+            lines.push(remaining);
+            break;
+        }
+        const space = remaining.slice(0, count + 1).map((glyph) => glyph.text).lastIndexOf(" ");
+        const cut = space > 0 ? space : Math.max(1, count);
+        lines.push(remaining.slice(0, cut));
+        remaining = remaining.slice(cut);
+        while (remaining[0]?.text === " ")
+            remaining = remaining.slice(1);
+    }
+    return lines.length > 0 ? lines : [[]];
+}
+function collectContentSpans(glyphs, x, y) {
+    const spans = [];
+    let cursorX = x;
+    let sourceIndex = -1;
+    for (const glyph of glyphs) {
+        const previous = spans.at(-1);
+        if (previous && sourceIndex === glyph.sourceIndex) {
+            spans[spans.length - 1] = { ...previous, text: previous.text + glyph.text, width: previous.width + glyph.width };
+        }
+        else
+            spans.push({ text: glyph.text, x: cursorX, y, width: glyph.width, ...glyph.style });
+        cursorX += glyph.width;
+        sourceIndex = glyph.sourceIndex;
+    }
+    return spans;
+}
+/** Emoji sequences occupy one em; combining marks and format controls do not add independent advance. */
+function estimateContentWidth(text, fontSize) {
+    if (text === "•")
+        return fontSize * NARROW_GLYPH_WIDTH_RATIO;
+    if (/\p{Extended_Pictographic}|\p{Regional_Indicator}|\u20e3/u.test(text))
+        return fontSize;
+    return Array.from(text).filter((character) => !/\p{Mark}|\p{Default_Ignorable_Code_Point}/u.test(character))
+        .reduce((width, character) => width + fontSize * (character.codePointAt(0) > 0xff || "MWmw@%".includes(character) ? 1 : NARROW_GLYPH_WIDTH_RATIO), 0);
+}
+/** Validate nested content separately from shape and label-mode checks at the document boundary. */
+export function validateNodeContent(value, path, issues) {
+    if (!isRecord(value)) {
+        issues.push({ path, message: "must be an object" });
+        return;
+    }
+    rejectUnknownFields(value, ["blocks", "style"], path, issues);
+    if (!Array.isArray(value.blocks)) {
+        issues.push({ path: `${path}.blocks`, message: "must be an array" });
+        return;
+    }
+    validateContentSpacing(value.style, `${path}.style`, issues);
+    for (let index = 0; index < value.blocks.length; index += 1) {
+        if (!(index in value.blocks))
+            issues.push({ path: `${path}.blocks[${index}]`, message: "must be a value" });
+    }
+    value.blocks.forEach((block, index) => {
+        const blockPath = `${path}.blocks[${index}]`;
+        if (!isRecord(block)) {
+            issues.push({ path: blockPath, message: "must be an object" });
+            return;
+        }
+        if (block.type === "list") {
+            validateContentList(block, blockPath, issues);
+            return;
+        }
+        if (block.type === "graph") {
+            validateContentGraph(block, blockPath, issues);
+            return;
+        }
+        rejectUnknownFields(block, block.type === "paragraph" ? ["type", "text", "role", "style"] : ["type", "text", "style"], blockPath, issues);
+        if (block.type !== "title" && block.type !== "paragraph")
+            issues.push({ path: `${blockPath}.type`, message: "must be title, paragraph, list or graph" });
+        validateContentText(block.text, `${blockPath}.text`, issues);
+        validateContentTextStyle(block.style, `${blockPath}.style`, issues);
+        if (block.role !== undefined && block.role !== "body" && block.role !== "auxiliary")
+            issues.push({ path: `${blockPath}.role`, message: "must be body or auxiliary" });
+    });
+}
+function validateContentGraph(block, path, issues) {
+    rejectUnknownFields(block, ["type", "height", "nodes", "edges"], path, issues);
+    validateSpacingNumber(block.height, `${path}.height`, issues, true);
+    const ids = new Set();
+    if (!Array.isArray(block.nodes))
+        issues.push({ path: `${path}.nodes`, message: "must be an array" });
+    else
+        for (let index = 0; index < block.nodes.length; index += 1) {
+            const node = block.nodes[index];
+            const nodePath = `${path}.nodes[${index}]`;
+            if (!isRecord(node)) {
+                issues.push({ path: nodePath, message: "must be an object" });
+                continue;
+            }
+            rejectUnknownFields(node, ["id", "label", "x", "y", "highlighted"], nodePath, issues);
+            if (typeof node.id !== "string" || !node.id.trim() || ids.has(node.id))
+                issues.push({ path: `${nodePath}.id`, message: "must be a unique nonempty local ID" });
+            else
+                ids.add(node.id);
+            if (typeof node.label !== "string")
+                issues.push({ path: `${nodePath}.label`, message: "must be a string" });
+            for (const field of ["x", "y"])
+                validateSpacingNumber(node[field], `${nodePath}.${field}`, issues);
+            if (node.highlighted !== undefined && typeof node.highlighted !== "boolean")
+                issues.push({ path: `${nodePath}.highlighted`, message: "must be a boolean" });
+        }
+    if (!Array.isArray(block.edges)) {
+        issues.push({ path: `${path}.edges`, message: "must be an array" });
+        return;
+    }
+    for (let index = 0; index < block.edges.length; index += 1) {
+        const edge = block.edges[index];
+        const edgePath = `${path}.edges[${index}]`;
+        if (!isRecord(edge)) {
+            issues.push({ path: edgePath, message: "must be an object" });
+            continue;
+        }
+        rejectUnknownFields(edge, ["from", "to"], edgePath, issues);
+        for (const field of ["from", "to"]) {
+            if (typeof edge[field] !== "string" || !ids.has(edge[field]))
+                issues.push({ path: `${edgePath}.${field}`, message: "must reference a node in this graph block" });
+        }
+    }
+}
+/** List entries share controlled text validation and preserve the exact nested source path. */
+function validateContentList(block, path, issues) {
+    rejectUnknownFields(block, ["type", "marker", "items", "style"], path, issues);
+    if (block.marker !== undefined && block.marker !== "none" && block.marker !== "bullet" && block.marker !== "number") {
+        issues.push({ path: `${path}.marker`, message: "must be none, bullet or number" });
+    }
+    if (isRecord(block.style)) {
+        const { itemGap, tagGap, ...textStyle } = block.style;
+        validateContentTextStyle(textStyle, `${path}.style`, issues);
+        if (itemGap !== undefined)
+            validateSpacingNumber(itemGap, `${path}.style.itemGap`, issues);
+        if (tagGap !== undefined)
+            validateSpacingNumber(tagGap, `${path}.style.tagGap`, issues);
+    }
+    else
+        validateContentTextStyle(block.style, `${path}.style`, issues);
+    if (!Array.isArray(block.items)) {
+        issues.push({ path: `${path}.items`, message: "must be an array" });
+        return;
+    }
+    for (let index = 0; index < block.items.length; index += 1) {
+        const item = block.items[index];
+        const itemPath = `${path}.items[${index}]`;
+        if (!isRecord(item)) {
+            issues.push({ path: itemPath, message: "must be an object" });
+            continue;
+        }
+        rejectUnknownFields(item, ["body", "auxiliary", "style", "auxiliaryStyle", "tags", "status", "statusStyle"], itemPath, issues);
+        if (item.body !== undefined)
+            validateContentText(item.body, `${itemPath}.body`, issues);
+        if (item.auxiliary !== undefined)
+            validateContentText(item.auxiliary, `${itemPath}.auxiliary`, issues);
+        validateContentTags(item.tags, `${itemPath}.tags`, issues);
+        if (item.status !== undefined)
+            validateContentText(item.status, `${itemPath}.status`, issues);
+        validateContentTextStyle(item.statusStyle, `${itemPath}.statusStyle`, issues, true);
+        validateContentTextStyle(item.style, `${itemPath}.style`, issues);
+        validateContentTextStyle(item.auxiliaryStyle, `${itemPath}.auxiliaryStyle`, issues);
+    }
+}
+/** Validate finite tag styles while preserving the exact authored tag and inline-span paths. */
+function validateContentTags(value, path, issues) {
+    if (value === undefined)
+        return;
+    if (!Array.isArray(value)) {
+        issues.push({ path, message: "must be an array" });
+        return;
+    }
+    for (let index = 0; index < value.length; index += 1) {
+        const tag = value[index];
+        const tagPath = `${path}[${index}]`;
+        if (!isRecord(tag)) {
+            issues.push({ path: tagPath, message: "must be an object" });
+            continue;
+        }
+        rejectUnknownFields(tag, ["text", "style"], tagPath, issues);
+        validateContentText(tag.text, `${tagPath}.text`, issues);
+        if (!isRecord(tag.style)) {
+            validateContentTextStyle(tag.style, `${tagPath}.style`, issues, true);
+            continue;
+        }
+        const { fill, ...textStyle } = tag.style;
+        validateContentTextStyle(textStyle, `${tagPath}.style`, issues, true);
+        if (fill !== undefined)
+            validateColor(fill, `${tagPath}.style.fill`, issues);
+    }
+}
+/** Validate inline source values before evaluation; unknown fields keep their exact source position. */
+export function validateContentText(value, path, issues) {
+    if (typeof value === "string")
+        return;
+    if (!Array.isArray(value)) {
+        issues.push({ path, message: "must be a string or an array of text spans" });
+        return;
+    }
+    for (let index = 0; index < value.length; index += 1) {
+        const span = value[index];
+        const spanPath = `${path}[${index}]`;
+        if (!isRecord(span)) {
+            issues.push({ path: spanPath, message: "must be an object" });
+            continue;
+        }
+        rejectUnknownFields(span, ["text", "style"], spanPath, issues);
+        if (typeof span.text !== "string")
+            issues.push({ path: `${spanPath}.text`, message: "must be a string" });
+        validateContentTextStyle(span.style, `${spanPath}.style`, issues, true);
+    }
+}
+/** Validate the controlled style shared by content blocks; no CSS expression or external resource is accepted. */
+export function validateContentTextStyle(value, path, issues, inline = false) {
+    if (value === undefined)
+        return;
+    if (!isRecord(value)) {
+        issues.push({ path, message: "must be an object" });
+        return;
+    }
+    rejectUnknownFields(value, inline ? ["fontSize", "fontWeight", "color"] : ["fontSize", "fontWeight", "color", "align"], path, issues);
+    if (value.fontSize !== undefined)
+        validateSpacingNumber(value.fontSize, `${path}.fontSize`, issues, true);
+    if (value.fontWeight !== undefined && (typeof value.fontWeight !== "number" || !Number.isInteger(value.fontWeight) || value.fontWeight < MIN_FONT_WEIGHT || value.fontWeight > MAX_FONT_WEIGHT))
+        issues.push({ path: `${path}.fontWeight`, message: "must be an integer from 100 through 900" });
+    if (value.align !== undefined && value.align !== "left" && value.align !== "center" && value.align !== "right")
+        issues.push({ path: `${path}.align`, message: "must be left, center or right" });
+    if (value.color !== undefined)
+        validateColor(value.color, `${path}.color`, issues);
+}
+function validateColor(value, path, issues) {
+    if (typeof value !== "string" || !/^#(?:[\da-f]{3}|[\da-f]{4}|[\da-f]{6}|[\da-f]{8})$/i.test(value))
+        issues.push({ path, message: "must be a hexadecimal color" });
+}
+function validateContentSpacing(value, path, issues) {
+    if (value === undefined)
+        return;
+    if (!isRecord(value)) {
+        issues.push({ path, message: "must be an object" });
+        return;
+    }
+    rejectUnknownFields(value, ["padding", "blockGap"], path, issues);
+    for (const field of ["padding", "blockGap"]) {
+        if (value[field] !== undefined)
+            validateSpacingNumber(value[field], `${path}.${field}`, issues);
+    }
+}
+function validateSpacingNumber(value, path, issues, positive = false) {
+    if (typeof value !== "number" || !Number.isFinite(value))
+        issues.push({ path, message: "must be a finite number" });
+    else if (positive ? value <= 0 : value < 0)
+        issues.push({ path, message: positive ? "must be greater than zero" : "must be zero or greater" });
+}
+function isRecord(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function rejectUnknownFields(value, allowed, path, issues) {
+    for (const key of Object.keys(value))
+        if (!allowed.includes(key))
+            issues.push({ path: `${path}.${key}`, message: "unknown field" });
+}

package/dist/player-accessibility.d.ts

@@ -0,0 +1,16 @@
+/** Translate keyboard input and reduced-motion preferences to player actions without changing core timeline semantics. */
+interface KeyboardActions {
+    toggle(): void;
+    step(direction: 1 | -1): void;
+}
+/** Explicit values need no subscription; otherwise return the system preference with change notifications and cleanup. */
+export declare function observeReducedMotion(owner: Document, explicit: boolean | undefined, onChange: (reducedMotion: boolean) => void): {
+    value: boolean;
+    cleanup(): void;
+};
+/**
+ * Make the canvas focusable and handle Space/Arrow keys, returning a listener cleanup callback.
+ * Leave editable areas, native controls, modifier chords and repeated keys to their existing handlers.
+ */
+export declare function observeKeyboard(canvas: HTMLElement, actions: KeyboardActions): () => void;
+export {};

package/dist/player-accessibility.js

@@ -0,0 +1,36 @@
+const REDUCED_MOTION_QUERY = "(prefers-reduced-motion: reduce)";
+/** Explicit values need no subscription; otherwise return the system preference with change notifications and cleanup. */
+export function observeReducedMotion(owner, explicit, onChange) {
+    if (explicit !== undefined)
+        return { value: explicit, cleanup: () => { } };
+    const query = owner.defaultView?.matchMedia(REDUCED_MOTION_QUERY);
+    const handleChange = (event) => onChange(event.matches);
+    query?.addEventListener("change", handleChange);
+    return { value: query?.matches ?? false, cleanup: () => query?.removeEventListener("change", handleChange) };
+}
+/**
+ * Make the canvas focusable and handle Space/Arrow keys, returning a listener cleanup callback.
+ * Leave editable areas, native controls, modifier chords and repeated keys to their existing handlers.
+ */
+export function observeKeyboard(canvas, actions) {
+    canvas.tabIndex = 0;
+    canvas.setAttribute("aria-label", "Diagram playback");
+    canvas.setAttribute("aria-keyshortcuts", "Space ArrowLeft ArrowRight");
+    const handleKey = (event) => {
+        if (event.defaultPrevented || event.repeat || event.altKey || event.ctrlKey || event.metaKey || event.shiftKey)
+            return;
+        const target = event.target;
+        if (target instanceof HTMLElement && (target.isContentEditable || target.closest("button,input,select,textarea,a[href]")))
+            return;
+        if (event.key === " ") {
+            event.preventDefault();
+            actions.toggle();
+        }
+        else if (event.key === "ArrowLeft" || event.key === "ArrowRight") {
+            event.preventDefault();
+            actions.step(event.key === "ArrowLeft" ? -1 : 1);
+        }
+    };
+    canvas.addEventListener("keydown", handleKey);
+    return () => canvas.removeEventListener("keydown", handleKey);
+}

package/dist/player-controls.d.ts

@@ -0,0 +1,41 @@
+/** Built-in controls consume state and forward actions; the browser player owns evaluation and scheduling. */
+/** Scene selection metadata with its global start time in milliseconds. */
+interface SceneChoice {
+    id: string;
+    label: string;
+    startMs: number;
+}
+/** Controls forward user intent; the player remains the owner of time state. */
+interface ControlActions {
+    toggle(): void;
+    step(direction: 1 | -1): void;
+    seek(timeMs: number): void;
+    setSpeed(speed: number): void;
+}
+/** Player-state projection for controls; the scene list is replaced on document load. */
+interface ControlState {
+    timeMs: number;
+    totalDuration: number;
+    playing: boolean;
+    speed: number;
+    sceneId: string | null;
+    scenes: readonly SceneChoice[];
+}
+/**
+ * Persistent control DOM translates input to commands; render synchronizes labels, progress and disabled states.
+ * Own no clock or independent position; time-related controls are disabled for static documents.
+ */
+export declare class PlayerControls {
+    readonly element: HTMLDivElement;
+    private readonly play;
+    private readonly previous;
+    private readonly next;
+    private readonly progress;
+    private readonly scene;
+    private readonly speed;
+    private sceneChoices;
+    constructor(owner: Document, actions: ControlActions);
+    /** Update existing controls; scene choices change by reference and custom speeds are added as options. */
+    render(state: ControlState): void;
+}
+export type { SceneChoice };