@figurestead/web 0.9.0-alpha.1 → 0.9.0-alpha.3

package/src/svg-export.js

@@ -1,11 +1,16 @@
+import { DIRECT_FONT } from "./direct-labels.js";
+import { lineMarkerGeometry } from "./line-identity.js";
 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";
+import { validateThemeColors } from "./schema.js";
+import { fixedResponsiveHeader, RESPONSIVE_HEADER_MAX_WIDTH } from "./responsive-header.js";
 
-const esc = (value) => String(value).replace(/[&<>"']/g, (char) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&apos;" }[char]));
+const xmlValue = (value) => String(value).replace(/[^\u0009\u000A\u000D\u0020-\uD7FF\uE000-\uFFFD\u{10000}-\u{10FFFF}]/gu, "\uFFFD");
+const esc = (value) => xmlValue(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";
 
@@ -25,17 +30,29 @@ function svgNamespace(composed, scene, options) {
 }
 
 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 };
+function marker(mark, appearance = null) {
+  const { cx, cy, radius } = mark.geometry, common = { "data-mark-id": mark.id, fill: "none", stroke: mark.style.color, "stroke-width": mark.lineIdentity ? mark.geometry.outlineWidth : 1.5, ...appearance };
   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) {
+function segment(mark, extra = {}) {
   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" })}/>`;
+  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", ...extra })}/>`;
+}
+
+function linePoint(mark) {
+  const edge = mark.style.edge ? marker(mark, { stroke: mark.style.edge, "stroke-width": mark.geometry.outlineWidth + 1.3 }) : "";
+  return edge + marker(mark);
+}
+
+function maskedLine(mark, points, bounds, id) {
+  // Luminance mask is applied only to this series' line (never the panel/grid).
+  const mask = `<mask ${attrs({ id, maskUnits: "userSpaceOnUse", x: bounds.left, y: bounds.top, width: bounds.right - bounds.left, height: bounds.bottom - bounds.top, "mask-type": "luminance" })}><rect ${attrs({ x: bounds.left, y: bounds.top, width: bounds.right - bounds.left, height: bounds.bottom - bounds.top, fill: "white" })}/>${points.map(p => marker(p, { fill: "black", stroke: "none", "data-mark-id": null })).join("")}</mask>`;
+  const edge = mark.style.edge ? segment(mark, { stroke: mark.style.edge, "stroke-width": mark.style.lineWidth + 1.3 }) : "";
+  return `<defs>${mask}</defs><g mask="url(#${esc(id)})">${edge}${segment(mark)}</g>`;
 }
 
 function bar(mark, theme) {
@@ -145,15 +162,20 @@ function panelSurface(panel, theme) {
 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>`); });
+  const rotate = panel.layout.text?.rotateX ?? (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 = panel.layout.text?.xTickBaselineY ?? 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>`);
+  if (panel.spec.xLabel) pieces.push(`<text ${attrs({ x: (plot.left + plot.right) / 2, y: panel.layout.text?.xLabelBaselineY ?? 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) { const x = panel.layout.text?.yLabelX ?? panel.layout.rect.left + 12 * panel.layout.scale; pieces.push(`<text ${attrs({ x, y: (plot.top + plot.bottom) / 2, fill: theme.label, "font-size": font.axis, transform: `rotate(-90 ${x} ${(plot.top + plot.bottom) / 2})`, "text-anchor": "middle", "dominant-baseline": "hanging" })}>${esc(panel.spec.yLabel)}</text>`); }
   return pieces.join("");
 }
 
-function legend(panel, theme) {
+function legend(panel, theme, namespace) {
+  if (panel.directLabelPlan?.status === "placed") return panel.directLabelPlan.entries.map(e => {
+    const l=e.leader;
+    return (l ? `<path ${attrs({d:`M ${l.x1} ${l.y1} L ${l.x2} ${l.y2}`,fill:"none",stroke:l.color,"stroke-width":.7})}/>` : "")
+      + linePoint(e.marker) + `<text ${attrs({x:e.textX,y:e.textY,fill:theme.label,"font-family":DIRECT_FONT,"font-size":panel.directLabelPlan.font,"xml:space":"preserve"})}>${esc(e.label)}</text>`;
+  }).join("");
   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) => {
@@ -161,7 +183,14 @@ function legend(panel, theme) {
     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] })}/>`;
+    let point = `<circle ${attrs({ cx: x, cy: y, r: 4 * panel.layout.scale, fill: "none", stroke: style.color ?? theme.series[item.colorIndex % theme.series.length] })}/>`;
+    if (panel.renderer === "line") {
+      const mark = { id: `${panel.id}-legend-${index}`, lineIdentity: true, style,
+        geometry: { cx: x, cy: y, ...lineMarkerGeometry(style, panel.layout.scale, panel.presentation?.markerScale ?? 1) } };
+      const half = 12 * Math.max(1, panel.layout.scale);
+      point = maskedLine({ ...mark, geometry: { x1: x - half, y1: y, x2: x + half, y2: y } }, [mark],
+        { left: x - half - 3, right: x + half + 3, top: y - 10, bottom: y + 10 }, `${namespace}-${safeId(panel.id)}-legend-${index}`) + linePoint(mark);
+    }
     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("");
@@ -183,9 +212,22 @@ function matrixLegend(panel, theme, namespace) {
   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) {
+function panelHeaderSvg(panel, theme, responsive) {
+  const titleFill = theme.mode === "paper" ? theme.label : theme.primary;
+  if (!responsive) {
+    return `<text ${attrs({ x: panel.layout.plot.left, y: panel.layout.text?.titleY ?? panel.layout.rect.top + 20, fill: titleFill, "font-size": panel.layout.font.title })}>${esc(panel.spec.title || panel.renderer)}</text>`;
+  }
+  const title = `<text ${attrs({ fill: titleFill, "font-size": panel.layout.font.title, "data-header-part": "title", "data-full-text": panel.spec.title || panel.renderer })}>${responsive.title.lines.map((line, index) => `<tspan ${attrs({ x: panel.layout.plot.left, y: responsive.title.baselines[index] })}>${esc(line)}</tspan>`).join("")}</text>`;
+  const subtitle = panel.spec.subtitle ? `<text ${attrs({ fill: theme.secondary, "font-size": panel.layout.font.subtitle, "font-style": "italic", "data-header-part": "subtitle", "data-full-text": panel.spec.subtitle })}>${responsive.subtitle.lines.map((line, index) => `<tspan ${attrs({ x: panel.layout.plot.left, y: responsive.subtitle.baselines[index] })}>${esc(line)}</tspan>`).join("")}</text>` : "";
+  return `<g ${attrs({ "data-responsive-header": responsive.policy })}>${title}${subtitle}</g>`;
+}
+
+function panelSvg(panel, theme, profile, namespace, responsive = null) {
   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)
+  const render = (mark) => panel.renderer === "line" && mark.kind === "segment"
+    ? maskedLine(mark, panel.marks.filter(p => p.lineIdentity && p.series === mark.series), plotClipRect(panel), `${namespace}-${safeId(panel.id)}-${hashText(mark.id)}-identity`)
+    : mark.lineIdentity ? linePoint(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)
@@ -204,20 +246,22 @@ function panelSvg(panel, theme, profile, namespace) {
     : 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 title = panelHeaderSvg(panel, theme, responsive);
   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>`;
+  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, namespace)}${matrixLegend(panel, theme, namespace)}${denominator}</g></g>`;
 }
 
 export function resolvedSceneToSvg(resolved, options = {}) {
   const composed = resolved.schemaVersion === "figurestead.composed-scene/1" ? resolved : composeResolvedScene(resolved);
+  validateThemeColors(composed.theme, "scene.theme");
   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>`;
+  const fixedResponsive = composed.width <= RESPONSIVE_HEADER_MAX_WIDTH && composed.panels.length === 1 && composed.theme.mode !== "paper";
+  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 ${attrs({ width: "100%", height: "100%", fill: composed.theme.field })}/>${header}${composed.panels.map((panel) => panelSvg(panel, composed.theme, composed.profile, namespace, panel.layout.headerText ?? (fixedResponsive ? fixedResponsiveHeader(panel) : null))).join("")}</svg>`;
 }
 
 export function sceneToSvg(scene, options = {}) {

package/src/terminal-scene.js

@@ -3,10 +3,11 @@ 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 { collectSeriesKeys, 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";
+import { linearFit } from "./statistics.js";
 
 export const TERMINAL_SCENE_VERSION = "figurestead.scene/1";
 
@@ -42,9 +43,7 @@ function scatterMarks(panel, contract, prepared, styles) {
     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;
+    const { slope, intercept } = linearFit(prepared.points.map((point) => point.x), prepared.points.map((point) => point.y));
     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;
@@ -118,6 +117,9 @@ export function compileFigureModel(input, options = {}) {
     ...panel,
     presentation: { ...profilePresentation(applicationProfile), ...(panel.presentation ?? {}) },
   }));
+  if (contract.style.directLabels && contract.panels.some(p => p.presentation.legend === "none")) throw new TypeError("directLabels requires the ordinary legend for fallback");
+  const directRanks = new Map(options.directRanks ?? []);
+  if (contract.style.directLabels) for (const key of collectSeriesKeys(contract)) if (!directRanks.has(key)) directRanks.set(key, directRanks.size);
   const styles = resolveSeriesStyles(contract);
   contract.seriesStyles = styles;
   contract.appearanceReport = applicationProfile.key === "paper" ? {
@@ -150,10 +152,15 @@ export function compileFigureModel(input, options = {}) {
       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,
+      ...(contract.style.directLabels ? { directLabelsInput: { data: panel.renderer === "line" ? { ...child.data, series: child.data.series.map((s,i) => {
+        const authored = (input.panels?.[panelIndex]?.data ?? input.data)?.series?.[i];
+        return { ...s, label: authored && Object.hasOwn(authored,"label") ? authored.label : s.label };
+      }) } : child.data, ranks: Object.fromEntries(directRanks), pose: !!panel.presentation.curve && panel.presentation.curve !== "linear" || !!panel.presentation.seriesMarkers } } : {}),
       marks: defaultMarks,
     };
   });
   const scene = {
+    ...(contract.style.directLabels ? { directLabels: true, directRanks: Object.fromEntries(directRanks) } : {}),
     schemaVersion: TERMINAL_SCENE_VERSION,
     contractSchemaVersion: contract.schemaVersion,
     rendererApiVersion: contract.rendererApiVersion,

package/src/theme-pack.js

@@ -251,6 +251,7 @@ export function contrastRatio(left, right) {
   return colorContrast(left, right);
 }
 
+/** Authored palette inspection; does not model renderer compositing. */
 export function contrastAudit(theme) {
   if (theme.mode === "paper") return auditPaperTheme(theme).findings;
   const findings = [];
@@ -266,3 +267,33 @@ export function contrastAudit(theme) {
   });
   return findings;
 }
+
+/** Supplied theme series colors in a caller-supplied single-layer context.
+ * Theme-level seriesEdges reject; contract/style overrides are not inspected.
+ * Callers must account for effective mark colors/layers before claiming rendered
+ * contrast. Verified line segments do not include companion markers/points.
+ * No defaults: encoded-sRGB blend, then luminance; passes = ratio >= 3 exactly.
+ * Final ULPs may differ across runtimes; this is not physical certification.
+ */
+export function renderedSeriesAudit(theme, context) {
+  object(context, "renderContext");
+  const fields = ["substrate", "opacity", "compositing"];
+  if (Object.keys(context).length !== fields.length || fields.some(key => !hasOwn(context, key))) {
+    throw new FiguresteadConfigError("requires exactly substrate, opacity, compositing", "renderContext");
+  }
+  const { substrate, opacity, compositing } = context;
+  if (typeof substrate !== "string" || substrate.length !== 7 || !COLOR.test(substrate)) throw new FiguresteadConfigError("must be an opaque #RRGGBB color", "renderContext.substrate");
+  if (typeof opacity !== "number" || !Number.isFinite(opacity) || opacity < 0 || opacity > 1) throw new FiguresteadConfigError("must be a finite number in [0, 1]", "renderContext.opacity");
+  if (compositing !== "srgb-source-over") throw new FiguresteadConfigError("must be srgb-source-over", "renderContext.compositing");
+  if (theme.seriesEdges?.length) throw new FiguresteadConfigError("layered series edges are not supported by this single-layer audit", "theme.seriesEdges");
+  if (!Array.isArray(theme.series) || !theme.series.length || theme.series.some(c => typeof c !== "string" || c.length !== 7 || !COLOR.test(c))) throw new FiguresteadConfigError("must contain opaque #RRGGBB colors", "theme.series");
+  const background = hexChannels(substrate).map(c => c / 255);
+  const luminance = channels => channels.map(c => c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4)
+    .reduce((sum, c, i) => sum + c * [0.2126, 0.7152, 0.0722][i], 0);
+  const back = luminance(background);
+  return theme.series.map((color, index) => {
+    const effectiveColor = hexChannels(color).map((c, i) => opacity * c / 255 + (1 - opacity) * background[i]);
+    const front = luminance(effectiveColor), ratio = (Math.max(front, back) + 0.05) / (Math.min(front, back) + 0.05);
+    return { token: `series[${index}]`, color, substrate, opacity, compositing, effectiveColor, ratio, minimum: 3, passes: ratio >= 3 };
+  });
+}

package/themes/deep_observatory_sage_core.json

@@ -0,0 +1,28 @@
+{
+  "drafts": {},
+  "name": "Deep Observatory / Sage Core",
+  "schemaVersion": "figurestead.theme-pack/1",
+  "themes": {
+    "deep_observatory_sage_core": {
+      "faint": "#71817C",
+      "field": "#10171D",
+      "grid": "#29393A",
+      "key": "deep_observatory_sage_core",
+      "label": "#E3ECE8",
+      "name": "Deep Observatory / Sage Core",
+      "panel": "#19252A",
+      "primary": "#5A9FA4",
+      "secondary": "#A8B5AE",
+      "series": [
+        "#5A9FA4",
+        "#C59C3E",
+        "#B44D4F",
+        "#8A76C4",
+        "#7BB888"
+      ],
+      "spine": "#748780",
+      "summaryCore": "#C1C7BC",
+      "warm": "#D45A34"
+    }
+  }
+}

package/themes/lavender_fog_notebook.json

@@ -0,0 +1,29 @@
+{
+  "drafts": {},
+  "name": "Lavender Fog Notebook",
+  "schemaVersion": "figurestead.theme-pack/1",
+  "themes": {
+    "lavender_fog_notebook": {
+      "faint": "#7B718B",
+      "field": "#F4F1F8",
+      "grid": "#DDD7E7",
+      "key": "lavender_fog_notebook",
+      "label": "#201B2B",
+      "name": "Lavender Fog Notebook",
+      "panel": "#FCFAFF",
+      "primary": "#6855A8",
+      "secondary": "#51495F",
+      "series": [
+        "#6855A8",
+        "#18776D",
+        "#9B5B16",
+        "#A44E5E",
+        "#326D9B",
+        "#52752C"
+      ],
+      "spine": "#9087A1",
+      "summaryCore": "#18776D",
+      "warm": "#A44E5E"
+    }
+  }
+}

package/themes/midnight_transit_signal_slate.json

@@ -0,0 +1,28 @@
+{
+  "drafts": {},
+  "name": "Midnight Transit / Signal Slate",
+  "schemaVersion": "figurestead.theme-pack/1",
+  "themes": {
+    "midnight_transit_signal_slate": {
+      "faint": "#637980",
+      "field": "#0A1522",
+      "grid": "#263D4E",
+      "key": "midnight_transit_signal_slate",
+      "label": "#DDE7E5",
+      "name": "Midnight Transit / Signal Slate",
+      "panel": "#13243A",
+      "primary": "#5EA5C8",
+      "secondary": "#9EAFB3",
+      "series": [
+        "#5EA5C8",
+        "#8BAF81",
+        "#B6696B",
+        "#8B69A3",
+        "#CDAD33"
+      ],
+      "spine": "#708A93",
+      "summaryCore": "#C3C8BC",
+      "warm": "#E06018"
+    }
+  }
+}

package/themes/registration_ink.json

@@ -0,0 +1,28 @@
+{
+  "drafts": {},
+  "name": "Registration Ink",
+  "schemaVersion": "figurestead.theme-pack/1",
+  "themes": {
+    "registration_ink": {
+      "faint": "#94877B",
+      "field": "#E7DFD2",
+      "grid": "#D7CCC0",
+      "key": "registration_ink",
+      "label": "#271E1B",
+      "name": "Registration Ink",
+      "panel": "#F5EFE4",
+      "primary": "#9C3038",
+      "secondary": "#62564F",
+      "series": [
+        "#9C3038",
+        "#1C6673",
+        "#4E3E78",
+        "#B16D28",
+        "#6C2948"
+      ],
+      "spine": "#806F64",
+      "summaryCore": "#241B1C",
+      "warm": "#A83A9A"
+    }
+  }
+}

package/themes/slipware.json

@@ -0,0 +1,28 @@
+{
+  "drafts": {},
+  "name": "Slipware",
+  "schemaVersion": "figurestead.theme-pack/1",
+  "themes": {
+    "slipware": {
+      "faint": "#9C8F84",
+      "field": "#E0D3C4",
+      "grid": "#DCD1C2",
+      "key": "slipware",
+      "label": "#2B2320",
+      "name": "Slipware",
+      "panel": "#FAF5EE",
+      "primary": "#1B4C8A",
+      "secondary": "#6B5D53",
+      "series": [
+        "#1B4C8A",
+        "#143F33",
+        "#0E766E",
+        "#8B7A16",
+        "#3C97AC"
+      ],
+      "spine": "#6E6055",
+      "summaryCore": "#0E0A08",
+      "warm": "#B4552A"
+    }
+  }
+}

package/themes/ultraviolet_laboratory.json

@@ -0,0 +1,29 @@
+{
+  "drafts": {},
+  "name": "Ultraviolet Laboratory",
+  "schemaVersion": "figurestead.theme-pack/1",
+  "themes": {
+    "ultraviolet_laboratory": {
+      "faint": "#8D83B2",
+      "field": "#0D0B18",
+      "grid": "#302A4E",
+      "key": "ultraviolet_laboratory",
+      "label": "#F6F2FF",
+      "name": "Ultraviolet Laboratory",
+      "panel": "#171329",
+      "primary": "#B59BFF",
+      "secondary": "#C9C0E5",
+      "series": [
+        "#B59BFF",
+        "#67D7C4",
+        "#F2A65A",
+        "#E57FA6",
+        "#8DB7FF",
+        "#BBD66B"
+      ],
+      "spine": "#4D4672",
+      "summaryCore": "#67D7C4",
+      "warm": "#F2A65A"
+    }
+  }
+}

package/types/extensions/temporal.d.ts

@@ -0,0 +1,45 @@
+import type {
+  FiguresteadContract,
+  FiguresteadPanelBase,
+  RendererDefinition,
+  UnknownRecord,
+} from "@figurestead/web";
+
+export type FiguresteadDate = string;
+
+export interface TemporalCoverageData {
+  dates: FiguresteadDate[];
+  sites: string[];
+  siteOrder: string[];
+}
+
+export interface TemporalReferenceBand {
+  type: "reference_band";
+  from: number;
+  to: number;
+  label: string;
+  status: "provisional_project_constant";
+}
+
+export interface TemporalObservationData {
+  dates: FiguresteadDate[];
+  values: number[];
+  site: string;
+  referenceBands?: TemporalReferenceBand[];
+}
+
+export type TemporalCoveragePanel = FiguresteadPanelBase<"temporal_coverage", TemporalCoverageData>;
+export type TemporalObservationsPanel = FiguresteadPanelBase<"temporal_observations", TemporalObservationData>;
+export type TemporalPanel = TemporalCoveragePanel | TemporalObservationsPanel;
+export type TemporalFiguresteadContract = FiguresteadContract<TemporalPanel>;
+
+export const TEMPORAL_COVERAGE_RENDERER: Readonly<RendererDefinition<TemporalCoverageData>>;
+export const TEMPORAL_OBSERVATIONS_RENDERER: Readonly<RendererDefinition<TemporalObservationData>>;
+export const TEMPORAL_RENDERERS: readonly [typeof TEMPORAL_COVERAGE_RENDERER, typeof TEMPORAL_OBSERVATIONS_RENDERER];
+export const PROVISIONAL_LABEL: "Provisional project constant; not a regulatory threshold";
+export const PROVISIONAL_STATUS: "provisional_project_constant";
+
+export function validateCoverageData(data: unknown, path?: string): TemporalCoverageData;
+export function validateObservationData(data: unknown, path?: string): TemporalObservationData;
+export function compileCoverageScene(context: UnknownRecord): UnknownRecord;
+export function compileObservationsScene(context: UnknownRecord): UnknownRecord;