@figurestead/web 0.9.0-alpha.1

package/src/svg-export.js

@@ -0,0 +1,232 @@
+import { CORE_REGISTRY } from "./core-renderers.js";
+import { compileTerminalScene, evidenceFingerprint } from "./terminal-scene.js";
+import { resolveTerminalScene } from "./resolved-scene.js";
+import { composeResolvedScene } from "./composition.js";
+import { partitionPanelMarks, plotClipRect } from "./render-layers.js";
+import { resolveExportSize } from "./physical-export.js";
+
+const esc = (value) => String(value).replace(/[&<>"']/g, (char) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&apos;" }[char]));
+const attrs = (value) => Object.entries(value).filter(([, item]) => item != null).map(([key, item]) => `${key}="${esc(item)}"`).join(" ");
+const FONT = "ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace";
+
+function hashText(value) {
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < value.length; index += 1) { hash ^= value.charCodeAt(index); hash = Math.imul(hash, 0x01000193); }
+  return (hash >>> 0).toString(16).padStart(8, "0");
+}
+
+function safeId(value) { return String(value).replace(/[^a-zA-Z0-9_-]+/g, "-").replace(/^-+|-+$/g, "") || "figurestead"; }
+
+function svgNamespace(composed, scene, options) {
+  if (options.idPrefix != null && !String(options.idPrefix).trim()) throw new TypeError("idPrefix must be a non-empty string");
+  if (options.idPrefix != null) return safeId(options.idPrefix);
+  const evidence = scene ? evidenceFingerprint(scene) : `fnv1a32-${hashText(JSON.stringify({ title: composed.spec.title, panels: composed.panels.map((panel) => panel.id) }))}`;
+  return safeId(`figurestead-${evidence}-${composed.width}x${composed.height}`);
+}
+
+function dash(style) { return style === "dash" ? "7 4" : style === "dot" ? "2 4" : style === "dash-dot" ? "8 3 2 3" : null; }
+function marker(mark) {
+  const { cx, cy, radius } = mark.geometry, common = { "data-mark-id": mark.id, fill: "none", stroke: mark.style.color, "stroke-width": 1.5 };
+  if (mark.style.glyph === "square") return `<rect ${attrs({ ...common, x: cx - radius, y: cy - radius, width: radius * 2, height: radius * 2 })}/>`;
+  if (mark.style.glyph === "triangle") return `<path ${attrs({ ...common, d: `M ${cx} ${cy - radius} L ${cx + radius} ${cy + radius} L ${cx - radius} ${cy + radius} Z` })}/>`;
+  if (mark.style.glyph === "diamond") return `<path ${attrs({ ...common, d: `M ${cx} ${cy - radius} L ${cx + radius} ${cy} L ${cx} ${cy + radius} L ${cx - radius} ${cy} Z` })}/>`;
+  return `<circle ${attrs({ ...common, cx, cy, r: radius })}/>`;
+}
+
+function segment(mark) {
+  const g = mark.geometry, d = g.c1x == null ? `M ${g.x1} ${g.y1} L ${g.x2} ${g.y2}` : `M ${g.x1} ${g.y1} C ${g.c1x} ${g.c1y} ${g.c2x} ${g.c2y} ${g.x2} ${g.y2}`;
+  return `<path ${attrs({ "data-mark-id": mark.id, d, fill: "none", stroke: mark.style.color, "stroke-width": mark.style.lineWidth ?? 1.6, "stroke-dasharray": dash(mark.style.lineStyle), "stroke-linecap": "round" })}/>`;
+}
+
+function bar(mark, theme) {
+  const g = mark.geometry;
+  if (mark.missing) return `<text ${attrs({ "data-mark-id": mark.id, x: (g.left + g.right) / 2, y: (g.top + g.bottom) / 2, fill: theme.warm, "text-anchor": "middle" })}>×</text>`;
+  const fillOpacity = theme.mode === "paper" ? 1 : g.alpha;
+  return `<g data-mark-id="${esc(mark.id)}"><rect ${attrs({ x: g.left, y: g.top, width: g.right - g.left, height: g.bottom - g.top, fill: mark.style.color, "fill-opacity": fillOpacity, stroke: mark.style.edge ?? mark.style.color })}/>${theme.mode === "paper" ? barHatch(g, mark.style.hatch, mark.style.edge ?? theme.label) : ""}</g>`;
+}
+
+function barHatch(g, hatch, color) {
+  if (!hatch || hatch === "none") return "";
+  const spacing = 6, height = g.bottom - g.top, pieces = [];
+  const line = (x1, y1, x2, y2) => pieces.push(`M ${x1} ${y1} L ${x2} ${y2}`);
+  if (["diag", "cross"].includes(hatch)) for (let x = g.left - height; x <= g.right; x += spacing) {
+    const fromX = Math.max(g.left, x), toX = Math.min(g.right, x + height);
+    if (toX >= fromX) line(fromX, g.bottom - (fromX - x), toX, g.bottom - (toX - x));
+  }
+  if (hatch === "cross") for (let x = g.left; x <= g.right + height; x += spacing) {
+    const fromX = Math.min(g.right, x), toX = Math.max(g.left, x - height);
+    if (fromX >= toX) line(fromX, g.bottom - (x - fromX), toX, g.bottom - (x - toX));
+  }
+  if (hatch === "vertical") for (let x = g.left + spacing / 2; x < g.right; x += spacing) line(x, g.top, x, g.bottom);
+  return pieces.length ? `<path ${attrs({ d: pieces.join(" "), fill: "none", stroke: color, "stroke-width": 0.75, "stroke-opacity": 0.34 })}/>` : "";
+}
+
+function cell(mark, theme, fontSize) {
+  const g = mark.geometry, label = mark.label ? `<text ${attrs({ x: (g.left + g.right) / 2, y: (g.top + g.bottom) / 2, fill: g.labelColor ?? theme.label, "font-size": fontSize, "text-anchor": "middle", "dominant-baseline": "middle" })}>${esc(mark.label)}</text>` : "";
+  const status = mark.status === "insufficient" ? `<path ${attrs({ d: `M ${g.left} ${g.bottom} L ${g.right} ${g.top}`, stroke: theme.warm })}/>` : "";
+  return `<g data-mark-id="${esc(mark.id)}"><rect ${attrs({ x: g.left, y: g.top, width: g.right - g.left, height: g.bottom - g.top, fill: g.fill, stroke: mark.style.edge, "data-status": mark.status })}/>${status}${label}</g>`;
+}
+
+function interval(mark, theme) {
+  const g = mark.geometry;
+  return `<g ${attrs({ "data-mark-id": mark.id, stroke: mark.style.color, "stroke-width": mark.style.lineWidth ?? 1.6, "stroke-dasharray": dash(mark.style.lineStyle), "stroke-opacity": theme.mode === "paper" ? 1 : (mark.role === "context" ? 0.62 : 0.9), fill: "none" })}><path d="M ${g.x1} ${g.y} L ${g.x2} ${g.y}"/><path d="M ${g.x1} ${g.y - g.cap} L ${g.x1} ${g.y + g.cap} M ${g.x2} ${g.y - g.cap} L ${g.x2} ${g.y + g.cap}"/></g>`;
+}
+
+function connector(mark, theme) {
+  const g = mark.geometry;
+  return `<path ${attrs({ "data-mark-id": mark.id, d: `M ${g.x1} ${g.y} L ${g.x2} ${g.y}`, fill: "none", stroke: mark.style.color, "stroke-width": mark.style.lineWidth ?? 1.35, "stroke-opacity": theme.mode === "paper" ? 1 : 0.72 })}/>`;
+}
+
+function connectorLabel(mark, panel, theme) {
+  const g = mark.geometry, leftFirst = g.x1 <= g.x2, pad = 6 * panel.layout.scale;
+  const delta = `${mark.delta >= 0 ? "+" : ""}${Number(mark.delta.toPrecision(4))}`;
+  return `<g data-label-for="${esc(mark.id)}"><text ${attrs({ x: g.x1 + (leftFirst ? -pad : pad), y: g.y - 7 * panel.layout.scale, fill: theme.series[0], "font-size": panel.layout.font.legend, "text-anchor": leftFirst ? "end" : "start" })}>${esc(mark.endpointALabel)}</text><text ${attrs({ x: g.x2 + (leftFirst ? pad : -pad), y: g.y + 7 * panel.layout.scale, fill: theme.series[1 % theme.series.length], "font-size": panel.layout.font.legend, "text-anchor": leftFirst ? "start" : "end" })}>${esc(mark.endpointBLabel)}</text><text ${attrs({ x: (g.x1 + g.x2) / 2, y: g.y - 18 * panel.layout.scale, fill: theme.label, "font-size": panel.layout.font.legend, "text-anchor": "middle" })}>${esc(delta)}</text></g>`;
+}
+
+function referenceBand(mark) {
+  const g = mark.geometry;
+  return `<g data-mark-id="${esc(mark.id)}"><rect ${attrs({ x: g.left, y: g.top, width: g.right - g.left, height: g.bottom - g.top, fill: mark.style.color, "fill-opacity": 0.1, "data-status": mark.status, "data-label": mark.label })}/><path ${attrs({ d: `M ${g.left} ${g.bottom} L ${g.right} ${g.bottom}`, stroke: mark.style.color, "stroke-opacity": 0.45 })}/></g>`;
+}
+
+function baseline(mark, panel) {
+  const g = mark.geometry;
+  return `<path ${attrs({ "data-mark-id": mark.id, d: `M ${g.x} ${g.top} L ${g.x} ${g.bottom}`, stroke: mark.style.color, "stroke-width": mark.style.lineWidth ?? 1.2, "stroke-dasharray": dash(mark.style.lineStyle) })}/>`;
+}
+
+function baselineLabel(mark, panel) {
+  const g = mark.geometry;
+  return `<text ${attrs({ "data-label-for": mark.id, x: g.x, y: g.top - 5 * panel.layout.scale, fill: mark.style.color, "font-size": panel.layout.font.legend, "text-anchor": "middle" })}>${esc(mark.label)}</text>`;
+}
+
+function rowBand(mark) {
+  const g = mark.geometry;
+  return `<rect ${attrs({ "data-mark-id": mark.id, x: g.left, y: g.top, width: g.right - g.left, height: g.bottom - g.top, fill: mark.style.color, "fill-opacity": 0.28 })}/>`;
+}
+
+function rug(mark) {
+  const g = mark.geometry;
+  return `<path ${attrs({ "data-mark-id": mark.id, d: `M ${g.x} ${g.y - g.halfHeight} L ${g.x} ${g.y + g.halfHeight}`, stroke: mark.style.color, "stroke-width": mark.style.lineWidth ?? 1.35 })}/>`;
+}
+
+function temporalBar(mark, panel, theme) {
+  const g = mark.geometry;
+  return `<rect ${attrs({ "data-mark-id": mark.id, x: g.left, y: g.top, width: Math.max(0, g.right - g.left), height: g.bottom - g.top, fill: mark.style.color, "fill-opacity": theme.mode === "paper" ? 1 : 0.24, stroke: mark.style.edge ?? mark.style.color })}/>`;
+}
+
+function temporalBarLabel(mark, panel, theme) {
+  const g = mark.geometry;
+  return `<text ${attrs({ "data-label-for": mark.id, x: g.labelX, y: g.labelY, fill: theme.secondary, "font-size": Math.max(7, panel.layout.font.axis * 0.75), "text-anchor": "middle" })}>${esc(mark.value)}</text>`;
+}
+
+function tickPosition(axis, tick) { const value = axis(tick.value); return axis.bandwidth ? value + axis.bandwidth() / 2 : value; }
+function grid(panel, theme, profile) {
+  const plot = panel.axes.plot ?? panel.layout.plot, pieces = [];
+  if (panel.axes.xType !== "band" && profile.gridX) panel.axes.xTicks.forEach((tick) => {
+    const x = tickPosition(panel.axes.x, tick); pieces.push(`<path ${attrs({ d: `M ${x} ${plot.top} L ${x} ${plot.bottom}`, stroke: theme.grid, "stroke-width": Math.max(0.6, 0.85 * panel.layout.scale), "stroke-opacity": profile.gridAlpha * 0.5 })}/>`);
+  });
+  if (panel.axes.yType !== "band" && profile.gridY) panel.axes.yTicks.forEach((tick) => {
+    const y = tickPosition(panel.axes.y, tick); pieces.push(`<path ${attrs({ d: `M ${plot.left} ${y} L ${plot.right} ${y}`, stroke: theme.grid, "stroke-width": Math.max(0.6, 0.85 * panel.layout.scale), "stroke-opacity": profile.gridAlpha * 0.5 })}/>`);
+  });
+  return pieces.join("");
+}
+
+function panelSurface(panel, theme) {
+  if (!panel.presentation?.panelSurface) return "";
+  const plot = panel.layout.plot;
+  return `<rect ${attrs({
+    x: plot.left, y: plot.top, width: plot.right - plot.left, height: plot.bottom - plot.top,
+    fill: theme.panel,
+    stroke: panel.presentation.frame ? theme.spine : null,
+    "stroke-opacity": panel.presentation.frame ? 0.48 : null,
+    "stroke-width": panel.presentation.frame ? Math.max(0.6, 0.75 * panel.layout.scale) : null,
+  })}/>`;
+}
+
+function axes(panel, theme) {
+  const plot = panel.axes.plot ?? panel.layout.plot, { font } = panel.layout, pieces = [`<path ${attrs({ d: `M ${plot.left} ${plot.top} L ${plot.left} ${plot.bottom} L ${plot.right} ${plot.bottom}`, fill: "none", stroke: theme.spine })}/>`];
+  const slot = panel.axes.x.step?.() ?? Math.max(40, (plot.right - plot.left) / Math.max(1, panel.axes.xTicks.length));
+  const rotate = panel.axes.xType === "band" && panel.axes.xTicks.some((tick) => String(tick.label).length * font.axis * 0.62 > slot * 0.92);
+  panel.axes.xTicks.forEach((tick) => { const x = tickPosition(panel.axes.x, tick), y = plot.bottom + 16 * panel.layout.scale; pieces.push(`<text ${attrs({ x, y, fill: theme.secondary, "font-size": font.axis, "text-anchor": rotate ? "end" : "middle", transform: rotate ? `rotate(-45 ${x} ${y})` : null })}>${esc(tick.label)}</text>`); });
+  panel.axes.yTicks.forEach((tick) => pieces.push(`<text ${attrs({ x: plot.left - 7 * panel.layout.scale, y: tickPosition(panel.axes.y, tick), fill: theme.secondary, "font-size": font.axis, "text-anchor": "end", "dominant-baseline": "middle" })}>${esc(tick.label)}</text>`));
+  if (panel.spec.xLabel) pieces.push(`<text ${attrs({ x: (plot.left + plot.right) / 2, y: panel.layout.rect.bottom - 6 * panel.layout.scale, fill: theme.label, "font-size": font.axis, "text-anchor": "middle" })}>${esc(panel.spec.xLabel)}</text>`);
+  if (panel.spec.yLabel) pieces.push(`<text ${attrs({ x: panel.layout.rect.left + 12 * panel.layout.scale, y: (plot.top + plot.bottom) / 2, fill: theme.label, "font-size": font.axis, transform: `rotate(-90 ${panel.layout.rect.left + 12 * panel.layout.scale} ${(plot.top + plot.bottom) / 2})`, "text-anchor": "middle" })}>${esc(panel.spec.yLabel)}</text>`);
+  return pieces.join("");
+}
+
+function legend(panel, theme) {
+  if (panel.presentation?.legend === "none") return "";
+  const insideTop = panel.layout.plot.bottom - Math.max(14, 14 + (panel.legend.length - 1) * 20) * panel.layout.scale;
+  return panel.legend.map((item, index) => {
+    const entry = panel.layout.legend.entries?.[index];
+    const x = entry?.markerX ?? (panel.layout.legend.outside ? panel.layout.legend.left : panel.layout.plot.right - 24 * panel.layout.scale);
+    const textX = entry?.textX ?? (panel.layout.legend.outside ? x + 12 * panel.layout.scale : x - 10 * panel.layout.scale);
+    const y = entry?.y ?? (panel.layout.legend.outside ? panel.layout.legend.top + (14 + index * 20) * panel.layout.scale : insideTop + index * 20 * panel.layout.scale), style = item.style ?? {};
+    const point = `<circle ${attrs({ cx: x, cy: y, r: 4 * panel.layout.scale, fill: "none", stroke: style.color ?? theme.series[item.colorIndex % theme.series.length] })}/>`;
+    const label = entry?.displayLabel ?? item.label;
+    return `${point}<text ${attrs({ x: textX, y, fill: theme.label, "font-size": panel.layout.font.legend, "text-anchor": entry?.textAnchor ?? (panel.layout.legend.outside ? "start" : "end"), "dominant-baseline": "middle", "data-full-label": item.label })}><title>${esc(item.label)}</title>${esc(label)}</text>`;
+  }).join("");
+}
+
+function annotations(panel, theme) {
+  return (panel.composedAnnotations ?? []).filter((annotation) => annotation.geometry).map((annotation) => {
+    const g = annotation.geometry, direction = g.labelX < g.anchorX ? -1 : 1;
+    const leader = `M ${g.anchorX + direction * g.radius * 0.7} ${g.anchorY} L ${g.labelX + (g.textAnchor === "end" ? 8 : -8) * panel.layout.scale} ${g.labelY - 5 * panel.layout.scale}`;
+    const label = annotation.displayLabel ?? annotation.label;
+    return `<g ${attrs({ "data-focus-id": annotation.id, "data-focus-status": annotation.status, "data-anchor-mark-id": annotation.boundMarkId, "data-full-label": annotation.label })}><title>${esc(annotation.label)}</title><circle ${attrs({ cx: g.anchorX, cy: g.anchorY, r: g.radius * 1.45, fill: "none", stroke: theme.primary, "stroke-width": Math.max(3, g.radius * 0.62), "stroke-opacity": 0.13 })}/><path ${attrs({ d: leader, fill: "none", stroke: theme.summaryCore, "stroke-width": Math.max(1, 1.25 * panel.layout.scale) })}/><circle ${attrs({ cx: g.anchorX, cy: g.anchorY, r: g.radius, fill: theme.summaryCore, stroke: theme.seriesEdges?.[0] ?? theme.primaryEdge ?? theme.field, "stroke-width": Math.max(1.4, 1.9 * panel.layout.scale) })}/><text ${attrs({ x: g.labelX, y: g.labelY, fill: theme.summaryCore, stroke: theme.field, "stroke-width": Math.max(1.6, 2.2 * panel.layout.scale), "paint-order": "stroke", "font-size": Math.max(9, panel.layout.font.legend * 1.06), "font-weight": 600, "text-anchor": g.textAnchor, "dominant-baseline": "middle" })}>${esc(label)}</text></g>`;
+  }).join("");
+}
+
+function matrixLegend(panel, theme, namespace) {
+  if (panel.renderer !== "categorical_matrix" || !panel.valueScale || !panel.marks.length) return "";
+  const width = Math.min(190 * panel.layout.scale, (panel.layout.plot.right - panel.layout.plot.left) * 0.42), left = panel.layout.plot.right - width;
+  const top = panel.layout.plot.top - 28 * panel.layout.scale, height = Math.max(5, 7 * panel.layout.scale), style = panel.marks[0].style, id = `${namespace}-${safeId(panel.id)}-matrix-gradient`;
+  return `<defs><linearGradient id="${esc(id)}"><stop offset="0%" stop-color="${esc(style.low)}"/><stop offset="68%" stop-color="${esc(style.color)}"/><stop offset="100%" stop-color="${esc(style.high)}"/></linearGradient></defs><text ${attrs({ x: left, y: top - 3 * panel.layout.scale, fill: theme.label, "font-size": panel.layout.font.legend })}>${esc(panel.valueScale.label)}</text><rect ${attrs({ x: left, y: top, width, height, fill: `url(#${id})`, stroke: theme.spine })}/><text ${attrs({ x: left, y: top + height + 12 * panel.layout.scale, fill: theme.secondary, "font-size": panel.layout.font.legend })}>${esc(panel.valueScale.domain[0])}</text><text ${attrs({ x: left + width, y: top + height + 12 * panel.layout.scale, fill: theme.secondary, "font-size": panel.layout.font.legend, "text-anchor": "end" })}>${esc(panel.valueScale.domain[1])}</text>`;
+}
+
+function panelSvg(panel, theme, profile, namespace) {
+  if (!panel.resolved) throw new TypeError(`SVG export requires a scene-aware renderer; ${panel.renderer} remains on the compatibility path`);
+  const render = (mark) => mark.kind === "point" ? marker(mark)
+    : ["segment", "summary-line"].includes(mark.kind) ? segment(mark)
+      : mark.kind === "median-rule" ? segment(mark)
+      : mark.kind === "bar" ? bar(mark, theme)
+        : mark.kind === "cell" ? cell(mark, theme, panel.layout.font.axis)
+          : mark.kind === "interval" ? interval(mark, theme)
+            : mark.kind === "connector" ? connector(mark, theme)
+              : mark.kind === "reference-band" ? referenceBand(mark)
+                : mark.kind === "baseline-rule" ? baseline(mark, panel)
+                  : mark.kind === "row-band" ? rowBand(mark)
+                    : mark.kind === "rug" ? rug(mark)
+                      : mark.kind === "temporal-bar" ? temporalBar(mark, panel, theme) : "";
+  const layers = partitionPanelMarks(panel.marks), plot = plotClipRect(panel), clipId = `${namespace}-${safeId(panel.id)}-evidence-clip`;
+  const renderLayer = (name, marks) => `<g data-layer="${name}" clip-path="url(#${clipId})">${marks.map(render).join("")}</g>`;
+  const dataMarks = [...layers.data.filter((mark) => mark.kind !== "point"), ...layers.data.filter((mark) => mark.kind === "point")];
+  const dataLabels = panel.marks.map((mark) => mark.kind === "connector" ? connectorLabel(mark, panel, theme)
+    : mark.kind === "baseline-rule" ? baselineLabel(mark, panel)
+      : mark.kind === "temporal-bar" ? temporalBarLabel(mark, panel, theme) : "").join("");
+  const denominator = panel.meta?.denominator ? `<text ${attrs({ x: panel.layout.plot.right, y: panel.layout.plot.top - 5 * panel.layout.scale, fill: theme.warm, "font-size": panel.layout.font.signature, "text-anchor": "end" })}>${esc(`${panel.meta.denominator.label}: ${panel.meta.denominator.value}`)}</text>` : "";
+  const title = `<text ${attrs({ x: panel.layout.plot.left, y: panel.layout.text?.titleY ?? panel.layout.rect.top + 20, fill: theme.mode === "paper" ? theme.label : theme.primary, "font-size": panel.layout.font.title })}>${esc(panel.spec.title || panel.renderer)}</text>`;
+  const provenance = theme.mode !== "paper" && panel.spec.signature && (panel.layout.panelIndex ?? 0) === 0
+    ? `<text ${attrs({ x: panel.layout.provenance?.left ?? panel.layout.plot.left, y: panel.layout.provenance?.y ?? panel.layout.rect.bottom - 8 * panel.layout.scale, fill: theme.faint, "font-size": panel.layout.font.signature, "text-anchor": "start", "data-layer": "provenance" })}>${esc(panel.spec.signature)}</text>` : "";
+  return `<g ${attrs({ "data-panel-id": panel.id, "data-renderer": panel.renderer, "data-denominator": panel.denominator == null ? null : JSON.stringify(panel.denominator), "data-x-category-order": panel.categories.x?.join("|"), "data-y-category-order": panel.categories.y?.join("|") })}><defs><clipPath id="${esc(clipId)}" clipPathUnits="userSpaceOnUse"><rect ${attrs({ x: plot.left, y: plot.top, width: plot.right - plot.left, height: plot.bottom - plot.top })}/></clipPath></defs><g data-layer="surface">${panelSurface(panel, theme)}</g><g data-layer="grid">${grid(panel, theme, profile)}</g>${renderLayer("reference", layers.reference)}${renderLayer("data", dataMarks)}${renderLayer("summary", layers.summary)}<g data-layer="axes">${title}${axes(panel, theme)}${provenance}</g><g data-layer="annotations">${dataLabels}${annotations(panel, theme)}</g><g data-layer="legend">${legend(panel, theme)}${matrixLegend(panel, theme, namespace)}${denominator}</g></g>`;
+}
+
+export function resolvedSceneToSvg(resolved, options = {}) {
+  const composed = resolved.schemaVersion === "figurestead.composed-scene/1" ? resolved : composeResolvedScene(resolved);
+  const scene = options.sourceScene, namespace = svgNamespace(composed, scene, options);
+  const exportSize = options.exportSize ?? resolveExportSize({ ...options, width: composed.width, height: composed.height });
+  const title = composed.spec.title, description = [composed.spec.description || composed.spec.subtitle || "Scientific figure", composed.spec.note, ...composed.panels.flatMap((panel) => panel.notes ?? [])].filter(Boolean).join(" ");
+  const titleId = `${namespace}-title`, descId = `${namespace}-desc`;
+  const header = composed.layout.header ? `<text ${attrs({ x: composed.layout.header.left, y: composed.layout.header.titleY, fill: composed.theme.mode === "paper" ? composed.theme.label : composed.theme.primary, "font-size": composed.layout.font.title })}>${esc(title)}</text>` : "";
+  return `<svg xmlns="http://www.w3.org/2000/svg" ${attrs({ width: exportSize.widthAttribute, height: exportSize.heightAttribute, viewBox: `0 0 ${composed.width} ${composed.height}`, role: "img", "aria-labelledby": `${titleId} ${descId}`, "data-scene-version": composed.sourceSceneVersion, "data-resolved-scene-version": composed.resolvedSceneVersion, "data-composed-scene-version": composed.schemaVersion, "data-evidence-fingerprint": scene ? evidenceFingerprint(scene) : null, "data-physical-width-mm": exportSize.physical?.widthMm })}><title id="${titleId}">${esc(title)}</title><desc id="${descId}">${esc(description)}</desc><rect width="100%" height="100%" fill="${composed.theme.field}"/>${header}${composed.panels.map((panel) => panelSvg(panel, composed.theme, composed.profile, namespace)).join("")}</svg>`;
+}
+
+export function sceneToSvg(scene, options = {}) {
+  const exportSize = resolveExportSize(options);
+  const resolved = resolveTerminalScene(scene, { width: exportSize.width, height: exportSize.height });
+  return resolvedSceneToSvg(composeResolvedScene(resolved), { ...options, exportSize, sourceScene: scene });
+}
+
+export function exportFigureSvg(input, options = {}) {
+  const scene = input?.schemaVersion === "figurestead.scene/1" ? input : compileTerminalScene(input, { registry: options.registry ?? CORE_REGISTRY });
+  return sceneToSvg(scene, options);
+}

package/src/terminal-scene.js

@@ -0,0 +1,215 @@
+import { validateContract } from "./schema.js";
+import { CORE_REGISTRY } from "./core-renderers.js";
+import { panelContract } from "./figure.js";
+import { resolvePanelDomains } from "./figure.js";
+import { resolveApplicationProfile } from "./application-profiles.js";
+import { legendWithStyles, resolveSeriesStyles } from "./series-style.js";
+import { compileMotionPlan, assertTerminalMotionIdentity } from "./motion-plan.js";
+import { auditPaperTheme, themeResolutionForProfile } from "./paper-profile.js";
+import { validateEvidenceCoverage } from "./evidence-coverage.js";
+
+export const TERMINAL_SCENE_VERSION = "figurestead.scene/1";
+
+function deepFreeze(value) {
+  if (!value || typeof value !== "object" || Object.isFrozen(value)) return value;
+  Object.values(value).forEach(deepFreeze);
+  return Object.freeze(value);
+}
+
+const markId = (panel, kind, ...parts) => [panel.id, kind, ...parts].map((item) => String(item).replace(/[^a-zA-Z0-9_.-]+/g, "-")).join("/");
+
+function lineMarks(panel, contract, prepared, styles) {
+  const marks = [];
+  contract.data.series.forEach((series) => {
+    const style = styles[series.key], points = prepared.points.filter((point) => point.series === series.key).sort((a, b) => a.index - b.index);
+    points.forEach((point) => marks.push({
+      id: markId(panel, "point", series.key, point.index), kind: "point", series: series.key,
+      x: point.x, y: point.y, style,
+    }));
+    for (let index = 1; index < points.length; index += 1) marks.push({
+      id: markId(panel, "segment", series.key, index - 1, index), kind: "segment", series: series.key,
+      interpolation: contract.encoding.interpolation,
+      from: { x: points[index - 1].x, y: points[index - 1].y },
+      to: { x: points[index].x, y: points[index].y }, style,
+    });
+  });
+  return marks;
+}
+
+function scatterMarks(panel, contract, prepared, styles) {
+  const marks = prepared.points.map((point) => ({
+    id: markId(panel, "point", point.series, point.index), kind: "point", series: point.series,
+    x: point.x, y: point.y, style: styles[point.series],
+  }));
+  if (contract.data.summary === "linear_fit") {
+    const n = prepared.points.length, sx = prepared.points.reduce((a, p) => a + p.x, 0), sy = prepared.points.reduce((a, p) => a + p.y, 0);
+    const sxx = prepared.points.reduce((a, p) => a + p.x * p.x, 0), sxy = prepared.points.reduce((a, p) => a + p.x * p.y, 0);
+    const slope = (n * sxy - sx * sy) / (n * sxx - sx * sx || 1), intercept = (sy - slope * sx) / n;
+    marks.push({ id: markId(panel, "summary", "linear-fit"), kind: "summary-line", role: "model", slope, intercept, style: { color: contract.theme.summaryCore, edge: contract.theme.summaryEdge ?? null, lineStyle: "solid" } });
+  }
+  return marks;
+}
+
+function barMarks(panel, contract, prepared, styles) {
+  return prepared.entries.map((entry) => ({
+    id: markId(panel, "bar", entry.series, entry.category), kind: "bar", series: entry.series,
+    category: entry.category, value: entry.value, missing: entry.missing,
+    orientation: contract.data.orientation, layer: entry.layer, seriesIndex: entry.seriesIndex,
+    categoryIndex: entry.categoryIndex, style: styles[entry.series],
+  }));
+}
+
+function matrixMarks(panel, contract, prepared) {
+  const style = { color: contract.theme.primary, low: contract.theme.panel, high: contract.theme.summaryCore, edge: contract.theme.spine };
+  return prepared.points.map((point) => ({
+    id: markId(panel, "cell", point.yCategory, point.xCategory), kind: "cell",
+    xCategory: point.xCategory, yCategory: point.yCategory, value: point.value,
+    status: point.status, label: point.label, diagonalMode: contract.data.diagonalMode, style,
+  }));
+}
+
+function fallbackMarks(panel, prepared, styles) {
+  return (prepared.points ?? []).map((point, index) => {
+    const series = String(point.series ?? "series");
+    return { id: markId(panel, "mark", series, point.id ?? point.index ?? index), kind: "renderer-mark", series, evidence: { ...point }, style: styles[series] ?? null };
+  });
+}
+
+function compileMarks(panel, child, prepared, styles, definition, context = {}) {
+  if (typeof definition.compileScene === "function") {
+    const compiled = definition.compileScene({ panel, contract: child, prepared, styles, markId, ...context });
+    if (!compiled || !Array.isArray(compiled.marks)) throw new TypeError(`renderer ${panel.renderer}.compileScene must return { marks }`);
+    return compiled;
+  }
+  if (panel.renderer === "line") return lineMarks(panel, child, prepared, styles);
+  if (panel.renderer === "scatter") return scatterMarks(panel, child, prepared, styles);
+  if (["categorical_bar", "categorical_layered_bar"].includes(panel.renderer)) return barMarks(panel, child, prepared, styles);
+  if (panel.renderer === "categorical_matrix") return matrixMarks(panel, child, prepared);
+  return { marks: fallbackMarks(panel, prepared, styles) };
+}
+
+function seriesKeys(child) {
+  if (Array.isArray(child.data.series) && child.data.series.length && typeof child.data.series[0] === "object") return child.data.series.map((item) => item.key);
+  if (Array.isArray(child.data.series)) return [...new Set(child.data.series.map(String))];
+  return [];
+}
+
+function profilePresentation(profile) {
+  return {
+    panelSurface: profile.panelSurface,
+    frame: profile.frame,
+    legend: profile.legend === "outside" ? "outside-right" : profile.legend === "auto" ? "auto" : "bottom-right",
+    lineWidth: profile.lineWidth,
+    markerScale: profile.markerScale,
+  };
+}
+
+export function compileFigureModel(input, options = {}) {
+  const registry = options.registry ?? CORE_REGISTRY;
+  const contract = validateContract(input, registry);
+  const applicationProfile = resolveApplicationProfile(contract.view.profile);
+  contract.applicationProfile = applicationProfile;
+  const themeResolution = themeResolutionForProfile(contract.theme, applicationProfile);
+  contract.theme = themeResolution.theme;
+  if (input.view?.profile && input.view.motion == null) contract.view.motion = applicationProfile.motion;
+  if (input.view?.profile && input.view.ambient == null) contract.view.ambient = applicationProfile.ambient;
+  if (input.view?.profile && input.view.strategy == null) contract.view.strategy = contract.view.motion === "semantic" ? "auto" : "none";
+  contract.panels = contract.panels.map((panel) => ({
+    ...panel,
+    presentation: { ...profilePresentation(applicationProfile), ...(panel.presentation ?? {}) },
+  }));
+  const styles = resolveSeriesStyles(contract);
+  contract.seriesStyles = styles;
+  contract.appearanceReport = applicationProfile.key === "paper" ? {
+    resolution: themeResolution.report,
+    audit: auditPaperTheme(contract.theme, styles),
+  } : null;
+  const preparedPanels = contract.panels.map((panel) => {
+    const definition = registry.get(panel.renderer), child = panelContract(contract, panel);
+    return { panel, definition, contract: child, prepared: definition.prepare(child) };
+  });
+  const domains = resolvePanelDomains(contract, preparedPanels);
+  const panels = preparedPanels.map(({ panel, definition, contract: child, prepared }, panelIndex) => {
+    const keys = seriesKeys(child), legend = prepared.legend ?? keys.map((key, colorIndex) => ({ key, label: key, colorIndex }));
+    const compiled = compileMarks(panel, child, prepared, styles, definition, { panelIndex, figure: contract });
+    const defaultMarks = Array.isArray(compiled) ? compiled : compiled.marks;
+    const defaultCategories = {
+      x: child.data.xCategories ?? (child.data.orientation === "vertical" ? child.data.categories : null),
+      y: child.data.yCategories ?? (child.data.orientation === "horizontal" ? child.data.categories : null),
+    };
+    return {
+      id: panel.id, renderer: panel.renderer, family: definition.family,
+      spec: child.spec, scales: compiled.scales ?? { x: child.xScale, y: child.yScale }, encoding: child.encoding,
+      domain: domains[panelIndex], presentation: child.presentation,
+      categories: compiled.categories ?? defaultCategories,
+      categoryLabels: compiled.categoryLabels ?? null,
+      orientation: compiled.orientation ?? child.data.orientation ?? null,
+      valueScale: child.data.valueScale ?? null,
+      denominator: child.data.denominator ?? child.data.n ?? null,
+      annotations: child.annotations ?? [],
+      notes: [child.spec.note, ...(child.annotations ?? []).filter((item) => item?.type === "scientific_note").map((item) => item.text)].filter(Boolean),
+      legend: compiled.legend ?? legendWithStyles(legend, keys, styles),
+      meta: compiled.meta ?? null,
+      marks: defaultMarks,
+    };
+  });
+  const scene = {
+    schemaVersion: TERMINAL_SCENE_VERSION,
+    contractSchemaVersion: contract.schemaVersion,
+    rendererApiVersion: contract.rendererApiVersion,
+    spec: contract.spec,
+    applicationProfile,
+    view: contract.view, layout: contract.layout, profile: contract.profile,
+    timeline: contract.timeline, motion: contract.motion, style: contract.style,
+    theme: contract.theme,
+    appearanceReport: contract.appearanceReport,
+    seriesStyles: styles,
+    panels,
+  };
+  scene.evidenceCoverage = validateEvidenceCoverage(panels);
+  scene.motionPlan = compileMotionPlan(scene, contract.view);
+  assertTerminalMotionIdentity(scene.motionPlan, scene);
+  deepFreeze(scene);
+  return Object.freeze({ contract, scene, preparedPanels, domains });
+}
+
+export function compileTerminalScene(input, options = {}) {
+  return compileFigureModel(input, options).scene;
+}
+
+export function terminalEvidence(scene) {
+  return scene.panels.map((panel) => ({ panelId: panel.id, marks: panel.marks.map((mark) => ({ ...mark })) }));
+}
+
+function sorted(value) {
+  if (Array.isArray(value)) return value.map(sorted);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(Object.keys(value).sort().map((key) => [key, sorted(value[key])]));
+}
+
+export function canonicalTerminalEvidence(scene) {
+  return sorted({
+    schemaVersion: scene.schemaVersion,
+    contractSchemaVersion: scene.contractSchemaVersion,
+    spec: { title: scene.spec.title, description: scene.spec.description, note: scene.spec.note },
+    seriesIdentity: Object.fromEntries(Object.entries(scene.seriesStyles).map(([key, style]) => [key, {
+      key, glyph: style.glyph, lineStyle: style.lineStyle,
+    }])),
+    panels: scene.panels.map((panel) => ({
+      id: panel.id, renderer: panel.renderer, encoding: panel.encoding, domain: panel.domain,
+      categories: panel.categories, denominator: panel.denominator, notes: panel.notes,
+      ...(panel.categoryLabels ? { categoryLabels: panel.categoryLabels } : {}),
+      marks: panel.marks.map(({ style: _style, ...mark }) => mark),
+    })),
+  });
+}
+
+export function evidenceFingerprint(scene) {
+  const text = JSON.stringify(canonicalTerminalEvidence(scene));
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < text.length; index += 1) {
+    hash ^= text.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return `fnv1a32-${(hash >>> 0).toString(16).padStart(8, "0")}`;
+}

package/src/theme-catalog.js

@@ -0,0 +1,34 @@
+import { contrastAudit, validateThemePack } from "./theme-pack.js";
+import { cloneValue } from "./schema.js";
+
+export const THEME_CATALOG_VERSION = "figurestead.theme-catalog/1";
+
+function deepFreeze(value) {
+  if (!value || typeof value !== "object" || Object.isFrozen(value)) return value;
+  Object.values(value).forEach(deepFreeze);
+  return Object.freeze(value);
+}
+
+export function mergeThemePacks(packs, options = {}) {
+  if (!Array.isArray(packs) || !packs.length) throw new TypeError("mergeThemePacks requires one or more theme packs");
+  const themes = {}, sources = {};
+  packs.forEach((source, index) => {
+    const pack = validateThemePack(source);
+    Object.entries(pack.themes).forEach(([key, theme]) => {
+      if (themes[key]) throw new TypeError(`duplicate theme key ${key} in ${pack.name} and ${sources[key]}`);
+      themes[key] = theme; sources[key] = pack.name || `pack-${index + 1}`;
+    });
+  });
+  return deepFreeze({ schemaVersion: THEME_CATALOG_VERSION, name: options.name ?? "Figurestead theme catalog", themes, sources });
+}
+
+export function auditThemeCatalog(catalog) {
+  if (!catalog || catalog.schemaVersion !== THEME_CATALOG_VERSION) throw new TypeError("auditThemeCatalog requires a Figurestead theme catalog");
+  const themes = Object.entries(catalog.themes).map(([key, theme]) => ({ key, source: catalog.sources[key], findings: contrastAudit(theme) }));
+  return deepFreeze({ themes, total: themes.length, warnings: themes.reduce((count, item) => count + item.findings.length, 0), clean: themes.every((item) => item.findings.length === 0) });
+}
+
+export function catalogThemePack(catalog) {
+  if (!catalog || catalog.schemaVersion !== THEME_CATALOG_VERSION) throw new TypeError("catalogThemePack requires a Figurestead theme catalog");
+  return { schemaVersion: "figurestead.theme-pack/1", name: catalog.name, themes: cloneValue(catalog.themes), drafts: {} };
+}