@figurestead/web 0.9.0-alpha.1

package/src/composition.js

@@ -0,0 +1,201 @@
+export const COMPOSED_SCENE_VERSION = "figurestead.composed-scene/1";
+
+const BACKGROUND_KINDS = new Set(["reference-band", "row-band"]);
+const CORNERS = Object.freeze(["top-right", "top-left", "bottom-right", "bottom-left"]);
+
+const clamp = (value, low, high) => Math.max(low, Math.min(high, value));
+const finite = (value) => typeof value === "number" && Number.isFinite(value);
+
+function deepFreeze(value) {
+  if (!value || typeof value !== "object" || Object.isFrozen(value)) return value;
+  Object.values(value).forEach(deepFreeze);
+  return Object.freeze(value);
+}
+
+function rect(left, top, right, bottom) {
+  return { left, top, right, bottom, width: Math.max(0, right - left), height: Math.max(0, bottom - top) };
+}
+
+function overlap(left, right) {
+  if (!left || !right) return 0;
+  return Math.max(0, Math.min(left.right, right.right) - Math.max(left.left, right.left))
+    * Math.max(0, Math.min(left.bottom, right.bottom) - Math.max(left.top, right.top));
+}
+
+function markBounds(mark) {
+  const g = mark.geometry;
+  if (!g) return null;
+  if (finite(g.cx) && finite(g.cy)) return rect(g.cx - (g.radius ?? 3), g.cy - (g.radius ?? 3), g.cx + (g.radius ?? 3), g.cy + (g.radius ?? 3));
+  if ([g.left, g.top, g.right, g.bottom].every(finite)) return rect(g.left, g.top, g.right, g.bottom);
+  if ([g.x1, g.y1, g.x2, g.y2].every(finite)) return rect(Math.min(g.x1, g.x2) - 2, Math.min(g.y1, g.y2) - 2, Math.max(g.x1, g.x2) + 2, Math.max(g.y1, g.y2) + 2);
+  if ([g.x1, g.x2, g.y].every(finite)) return rect(Math.min(g.x1, g.x2) - 2, g.y - (g.cap ?? 3), Math.max(g.x1, g.x2) + 2, g.y + (g.cap ?? 3));
+  if (finite(g.x) && finite(g.y)) return rect(g.x - 3, g.y - (g.halfHeight ?? 3), g.x + 3, g.y + (g.halfHeight ?? 3));
+  if (finite(g.x) && finite(g.top) && finite(g.bottom)) return rect(g.x - 2, g.top, g.x + 2, g.bottom);
+  return null;
+}
+
+function markAnchor(mark) {
+  const g = mark?.geometry;
+  if (!g) return null;
+  if (finite(g.cx) && finite(g.cy)) return { x: g.cx, y: g.cy };
+  if ([g.left, g.top, g.right, g.bottom].every(finite)) return { x: (g.left + g.right) / 2, y: (g.top + g.bottom) / 2 };
+  if ([g.x1, g.y1, g.x2, g.y2].every(finite)) return { x: g.x2, y: g.y2 };
+  if ([g.x1, g.x2, g.y].every(finite)) return { x: (g.x1 + g.x2) / 2, y: g.y };
+  if (finite(g.x) && finite(g.y)) return { x: g.x, y: g.y };
+  if (finite(g.x) && finite(g.top) && finite(g.bottom)) return { x: g.x, y: (g.top + g.bottom) / 2 };
+  return null;
+}
+
+function fitText(value, maxWidth, fontSize) {
+  const text = String(value);
+  const averageGlyph = Math.max(1, fontSize * 0.62);
+  const maxChars = Math.max(2, Math.floor(maxWidth / averageGlyph));
+  if (text.length <= maxChars) return text;
+  return `${text.slice(0, Math.max(1, maxChars - 1))}…`;
+}
+
+function legendDimensions(panel) {
+  const scale = panel.layout.scale;
+  const font = panel.layout.font.legend;
+  const plot = panel.axes.plot ?? panel.layout.plot;
+  const labelWidth = panel.legend.reduce((width, item) => Math.max(width, String(item.label).length * font * 0.62), 0);
+  return {
+    width: Math.min(Math.max(72 * scale, labelWidth + 34 * scale), Math.max(24, plot.right - plot.left - 24 * scale)),
+    height: Math.min(Math.max(18 * scale, (12 + Math.max(0, panel.legend.length - 1) * 20) * scale), Math.max(18, plot.bottom - plot.top - 24 * scale)),
+  };
+}
+
+function legendCandidate(panel, position, dimensions) {
+  const plot = panel.layout.plot, pad = 12 * panel.layout.scale;
+  const left = position.endsWith("right") ? plot.right - pad - dimensions.width : plot.left + pad;
+  const top = position.startsWith("bottom") ? plot.bottom - pad - dimensions.height : plot.top + pad;
+  return rect(left, top, left + dimensions.width, top + dimensions.height);
+}
+
+function legendScore(panel, box) {
+  const area = Math.max(1, box.width * box.height);
+  return panel.marks.reduce((score, mark) => {
+    if (BACKGROUND_KINDS.has(mark.kind)) return score;
+    return score + overlap(box, markBounds(mark)) / area;
+  }, 0);
+}
+
+function legendEntries(panel, box, position, outside) {
+  const scale = panel.layout.scale, right = position.endsWith("right"), markerInset = 8 * scale;
+  const count = panel.legend.length;
+  const topInset = Math.min(12 * scale, box.height / 2);
+  const bottomInset = Math.min(8 * scale, box.height / 2);
+  const step = count > 1 ? Math.min(20 * scale, Math.max(1, (box.height - topInset - bottomInset) / (count - 1))) : 0;
+  return panel.legend.map((item, index) => {
+    const y = clamp(box.top + topInset + index * step, box.top, box.bottom);
+    const textAnchor = outside || !right ? "start" : "end";
+    const markerX = textAnchor === "start" ? box.left + markerInset : box.right - markerInset;
+    const textX = textAnchor === "start" ? box.left + 20 * scale : box.right - 20 * scale;
+    const maxTextWidth = Math.max(8, textAnchor === "start" ? box.right - textX : textX - box.left);
+    return { markerX, textX, y, textAnchor, displayLabel: fitText(item.label, maxTextWidth, panel.layout.font.legend) };
+  });
+}
+
+function composeLegend(panel) {
+  if (panel.presentation?.legend === "none" || !panel.legend.length) return { ...panel.layout.legend, position: "none", box: null, entries: [] };
+  if (panel.layout.legend.outside || panel.presentation?.legend === "outside-right") {
+    const source = panel.layout.legend;
+    const box = rect(source.left, source.top, source.right, source.bottom);
+    return { ...source, position: "outside-right", box, entries: legendEntries(panel, box, "top-left", true) };
+  }
+  const dimensions = legendDimensions(panel);
+  const requested = panel.presentation?.legend ?? "auto";
+  const candidates = (requested === "auto" ? CORNERS : [requested]).map((position, order) => {
+    const box = legendCandidate(panel, position, dimensions);
+    return { position, box, score: legendScore(panel, box), order };
+  }).sort((left, right) => left.score - right.score || left.order - right.order);
+  const winner = candidates[0];
+  return { ...panel.layout.legend, outside: false, position: winner.position, box: winner.box, score: winner.score, entries: legendEntries(panel, winner.box, winner.position, false) };
+}
+
+function coordinateAnchor(panel, annotation) {
+  const plot = panel.axes.plot ?? panel.layout.plot;
+  if (annotation.space === "plot" && finite(annotation.x) && finite(annotation.y)) {
+    return { x: plot.left + clamp(annotation.x, 0, 1) * (plot.right - plot.left), y: plot.bottom - clamp(annotation.y, 0, 1) * (plot.bottom - plot.top) };
+  }
+  if (typeof panel.axes?.x !== "function" || typeof panel.axes?.y !== "function") return null;
+  const x = panel.axes.x(annotation.x), y = panel.axes.y(annotation.y);
+  return finite(x) && finite(y) ? { x, y } : null;
+}
+
+function labelCandidates(panel, annotation, anchor, legendBox, occupied = []) {
+  const plot = panel.axes.plot ?? panel.layout.plot, scale = panel.layout.scale;
+  const font = Math.max(9, panel.layout.font.legend * 1.06);
+  const pad = Math.max(4, 8 * scale);
+  const maxWidth = Math.max(12, plot.right - plot.left - pad * 2);
+  const width = Math.min(maxWidth, Math.max(42 * scale, String(annotation.label).length * font * 0.62 + 10 * scale));
+  const displayLabel = fitText(annotation.label, width - 4 * scale, font), height = Math.min(20 * scale, Math.max(12, plot.bottom - plot.top));
+  const dx = finite(annotation.dx) ? annotation.dx * scale : 68 * scale;
+  const dy = finite(annotation.dy) ? annotation.dy * scale : 28 * scale;
+  const offsets = [[dx, dy], [-dx, dy], [dx, -dy], [-dx, -dy]];
+  const dataBounds = panel.marks.filter((mark) => !BACKGROUND_KINDS.has(mark.kind)).map(markBounds).filter(Boolean);
+  return offsets.map(([offsetX, offsetY], order) => {
+    const rightAligned = offsetX < 0;
+    const labelX = rightAligned
+      ? clamp(anchor.x + offsetX, plot.left + width + pad, plot.right - pad)
+      : clamp(anchor.x + offsetX, plot.left + pad, plot.right - width - pad);
+    const labelY = clamp(anchor.y + offsetY, plot.top + height / 2, plot.bottom - height / 2);
+    const box = rightAligned
+      ? rect(labelX - width, labelY - height / 2, labelX, labelY + height / 2)
+      : rect(labelX, labelY - height / 2, labelX + width, labelY + height / 2);
+    const leaderLength = Math.hypot(labelX - anchor.x, labelY - anchor.y);
+    const score = overlap(box, legendBox) * 12
+      + occupied.reduce((sum, item) => sum + overlap(box, item) * 16, 0)
+      + dataBounds.reduce((sum, item) => sum + overlap(box, item), 0)
+      + leaderLength * 0.002;
+    return { labelX, labelY, box, displayLabel, textAnchor: rightAligned ? "end" : "start", score, order };
+  }).sort((left, right) => left.score - right.score || left.order - right.order);
+}
+
+function composeAnnotations(panel, legendBox) {
+  const occupied = [];
+  return (panel.annotations ?? []).filter((item) => item?.type === "focus" && typeof item.label === "string" && item.label.trim()).map((annotation, index) => {
+    const boundMark = annotation.anchorId ? panel.marks.find((mark) => mark.id === annotation.anchorId) : null;
+    const anchor = boundMark ? markAnchor(boundMark) : annotation.anchorId ? null : coordinateAnchor(panel, annotation);
+    const status = boundMark && anchor ? "evidence-bound" : annotation.anchorId ? "missing-anchor" : anchor ? "authored-coordinate" : "unresolved";
+    if (!anchor) return { id: `${panel.id}/focus/${index}`, type: "focus", label: annotation.label, status, boundMarkId: null, geometry: null };
+    const label = labelCandidates(panel, annotation, anchor, legendBox, occupied)[0];
+    occupied.push(label.box);
+    return {
+      id: `${panel.id}/focus/${index}`, type: "focus", label: annotation.label, displayLabel: label.displayLabel, status,
+      boundMarkId: boundMark?.id ?? null,
+      geometry: { anchorX: anchor.x, anchorY: anchor.y, labelX: label.labelX, labelY: label.labelY, labelBox: label.box, textAnchor: label.textAnchor, radius: Math.max(6.5, 8.4 * panel.layout.scale) },
+    };
+  });
+}
+
+export function auditComposition(scene) {
+  const annotations = scene.panels.flatMap((panel) => panel.composedAnnotations ?? []);
+  const count = (status) => annotations.filter((item) => item.status === status).length;
+  return Object.freeze({
+    annotations: annotations.length,
+    evidenceBound: count("evidence-bound"),
+    authoredCoordinates: count("authored-coordinate"),
+    missingAnchors: count("missing-anchor"),
+    unresolved: count("unresolved"),
+    clean: count("missing-anchor") + count("unresolved") === 0,
+  });
+}
+
+export function composeResolvedScene(resolvedScene) {
+  if (!resolvedScene || resolvedScene.schemaVersion !== "figurestead.resolved-scene/1") throw new TypeError("composeResolvedScene requires a resolved Figurestead scene");
+  const panels = resolvedScene.panels.map((panel) => {
+    const legend = composeLegend(panel);
+    const layout = { ...panel.layout, legend };
+    const composedPanel = { ...panel, layout };
+    return { ...composedPanel, composedAnnotations: composeAnnotations(composedPanel, legend.box) };
+  });
+  const result = {
+    ...resolvedScene,
+    schemaVersion: COMPOSED_SCENE_VERSION,
+    resolvedSceneVersion: resolvedScene.schemaVersion,
+    panels,
+  };
+  result.compositionAudit = auditComposition(result);
+  return deepFreeze(result);
+}

package/src/core-renderers.js

@@ -0,0 +1,33 @@
+import { createRendererRegistry, RENDERER_API_VERSION } from "./registry.js";
+import { normalizeLineData, normalizeScatterData, normalizeStripData } from "./schema.js";
+import { extent } from "./scales.js";
+import { prepareLine, drawLine } from "./renderers/line.js";
+import { prepareScatter, drawScatter } from "./renderers/scatter.js";
+import { prepareStrip, drawStrip, compileStripScene } from "./renderers/strip-summary.js";
+
+const pointDomains = (contract, prepared) => ({
+  x: contract.data.xDomain || extent(prepared.points.map((point) => point.x)),
+  y: contract.data.yDomain || extent(prepared.points.map((point) => point.y)),
+});
+
+export const LINE_RENDERER = {
+  key: "line", family: "trend", apiVersion: RENDERER_API_VERSION,
+  validateData: normalizeLineData, prepare: prepareLine, draw: drawLine, domains: pointDomains,
+  describe(contract) { return { summary: `${contract.data.series.length} connected series.`, headers: [contract.spec.xLabel || "x", ...contract.data.series.map((series) => series.label)], rows: contract.data.x.map((x, index) => [x, ...contract.data.series.map((series) => series.y[index])]) }; },
+};
+
+export const SCATTER_RENDERER = {
+  key: "scatter", family: "relationship", apiVersion: RENDERER_API_VERSION,
+  validateData: normalizeScatterData, prepare: prepareScatter, draw: drawScatter, domains: pointDomains,
+  describe(contract) { return { summary: `${contract.data.x.length} unconnected observations.`, headers: [contract.spec.xLabel || "x", contract.spec.yLabel || "y", "series"], rows: contract.data.x.map((x, index) => [x, contract.data.y[index], contract.data.seriesLabels[contract.data.series[index]]]) }; },
+};
+
+export const STRIP_RENDERER = {
+  key: "strip_summary", family: "distribution", apiVersion: RENDERER_API_VERSION,
+  validateData: normalizeStripData, prepare: prepareStrip, compileScene: compileStripScene, draw: drawStrip,
+  domains(contract, prepared) { return { x: [-0.5, contract.data.groups.length - 0.5], y: contract.data.yDomain || extent(prepared.points.map((point) => point.y)) }; },
+  describe(contract) { return { summary: `${contract.data.values.length} observations across ${contract.data.groups.length} ordered groups.`, headers: ["group", contract.spec.yLabel || "value", "series"], rows: contract.data.values.map((value, index) => [contract.data.group[index], value, contract.data.seriesLabels[contract.data.series[index]]]) }; },
+};
+
+export const CORE_RENDERERS = Object.freeze([LINE_RENDERER, SCATTER_RENDERER, STRIP_RENDERER]);
+export const CORE_REGISTRY = createRendererRegistry(CORE_RENDERERS);

package/src/create-matrix-plot.js

@@ -0,0 +1,97 @@
+import { cloneValue } from "./schema.js";
+import { resizeCanvas } from "./layout.js";
+import { deriveFigureLayout } from "./figure-layout.js";
+import { prepareAtmosphere, drawAtmosphere } from "./atmosphere.js";
+import { drawBackground, drawFigureHeader } from "./marks.js";
+import { CORE_REGISTRY } from "./core-renderers.js";
+import { AnimationClock } from "./clock.js";
+import { createAccessibilityCompanion } from "./accessibility.js";
+import { drawPanelSurface, drawPresentationAnnotations } from "./presentation.js";
+import { compileFigureModel } from "./terminal-scene.js";
+import { isResolvedRenderer, resolveSceneFrame, resolveTerminalScene } from "./resolved-scene.js";
+import { drawResolvedPanel } from "./canvas-scene.js";
+import { composeResolvedScene } from "./composition.js";
+
+export function createFigurestead(canvas, input, options = {}) {
+  if (!(canvas instanceof HTMLCanvasElement)) throw new TypeError("createFigurestead requires an HTMLCanvasElement");
+  const registry = options.registry ?? CORE_REGISTRY;
+  if (registry.apiVersion !== "1") throw new TypeError("Figurestead requires renderer registry API 1");
+  let contract = input, scene = null, preparedPanels = [], domains = [], atmosphere, surface, resolvedScene = null, composedScene = null, clock = null, destroyed = false;
+  let reducedOverride = options.reducedMotion ?? null, companion = null;
+  const media = globalThis.matchMedia?.("(prefers-reduced-motion: reduce)");
+  const isReduced = () => reducedOverride == null ? Boolean(media?.matches) : Boolean(reducedOverride);
+
+  const prepare = () => {
+    const model = compileFigureModel(contract, { registry });
+    contract = model.contract; scene = model.scene; preparedPanels = model.preparedPanels; domains = model.domains;
+    atmosphere = contract.view.ambient === "matrix" ? prepareAtmosphere(contract.motion) : [];
+  };
+  const layoutFactory = (width, height) => deriveFigureLayout(width, height, contract);
+  const resize = () => {
+    if (destroyed) return;
+    surface = resizeCanvas(canvas, { dprCap: options.dprCap ?? 2, layoutFactory });
+    resolvedScene = resolveTerminalScene(scene, { width: surface.layout.width, height: surface.layout.height });
+    composedScene = composeResolvedScene(resolvedScene);
+    if (clock) draw(clock.progress);
+  };
+  const draw = (progress) => {
+    if (!surface || destroyed) return;
+    const p = isReduced() ? 1 : progress, settled = p >= 1;
+    drawBackground(surface.context, surface.layout, contract.theme);
+    drawAtmosphere(surface.context, { config: contract, layout: surface.layout, streams: atmosphere, progress: p, reducedMotion: isReduced() || settled });
+    drawFigureHeader(surface.context, { config: contract, layout: surface.layout });
+    const frame = resolveSceneFrame(composedScene, p);
+    preparedPanels.forEach((state, index) => {
+      const resolved = isResolvedRenderer(state.panel.renderer);
+      const env = { contract: state.contract, prepared: state.prepared, layout: resolved ? composedScene.panels[index].layout : surface.layout.panels[index], domains: domains[index], progress: p, settled, panel: state.panel, figure: contract, scenePanel: scene.panels[index], motionPlan: scene.motionPlan.panels[index], reducedMotion: isReduced() };
+      drawPanelSurface(surface.context, env);
+      const scales = resolved ? drawResolvedPanel(surface.context, frame, index) : state.definition.draw(surface.context, env);
+      if (!resolved) drawPresentationAnnotations(surface.context, { ...env, scales });
+    });
+    options.onProgress?.(p);
+  };
+
+  prepare(); surface = resizeCanvas(canvas, { dprCap: options.dprCap ?? 2, layoutFactory });
+  resolvedScene = resolveTerminalScene(scene, { width: surface.layout.width, height: surface.layout.height });
+  composedScene = composeResolvedScene(resolvedScene);
+  clock = new AnimationClock({ durationMs: contract.motion.durationMs, draw, onState: options.onState });
+  companion = createAccessibilityCompanion(canvas, contract, registry, options.accessibility);
+  clock.render(isReduced() ? 1 : 0);
+
+  let autoplayUsed = false, wasPlayingBeforeHidden = false;
+  const resizeObserver = globalThis.ResizeObserver ? new ResizeObserver(resize) : null; resizeObserver?.observe(canvas);
+  const intersectionObserver = globalThis.IntersectionObserver ? new IntersectionObserver((entries) => {
+    if (!document.hidden && !autoplayUsed && entries.some((entry) => entry.isIntersecting && entry.intersectionRatio >= .35)) { autoplayUsed = true; intersectionObserver.disconnect(); isReduced() ? clock.settle() : clock.play(); }
+  }, { threshold: [.35] }) : null;
+  if (options.autoplay !== false) { if (intersectionObserver) intersectionObserver.observe(canvas); else { autoplayUsed = true; isReduced() ? clock.settle() : clock.play(); } }
+  const visibility = () => { if (document.hidden) { wasPlayingBeforeHidden = clock.playing; clock.pause(); } else if (wasPlayingBeforeHidden) { wasPlayingBeforeHidden = false; clock.play(); } };
+  const mediaChange = () => { if (reducedOverride == null) isReduced() ? clock.settle() : draw(clock.progress); };
+  document.addEventListener("visibilitychange", visibility); media?.addEventListener?.("change", mediaChange);
+
+  const replace = (next) => {
+    clock.pause(); contract = next; prepare(); clock.durationMs = contract.motion.durationMs;
+    surface = resizeCanvas(canvas, { dprCap: options.dprCap ?? 2, layoutFactory });
+    resolvedScene = resolveTerminalScene(scene, { width: surface.layout.width, height: surface.layout.height });
+    composedScene = composeResolvedScene(resolvedScene);
+    companion.destroy(); companion = createAccessibilityCompanion(canvas, contract, registry, options.accessibility); clock.settle();
+  };
+  return Object.freeze({
+    play() { if (isReduced()) clock.settle(); else clock.play(); }, pause() { clock.pause(); }, replay() { if (isReduced()) clock.settle(); else clock.replay(); },
+    setData(data) { if (contract.panels.length !== 1) throw new TypeError("setData is available only for single-panel figures; use setConfig for multi-panel figures"); const next = cloneValue(contract); next.panels[0].data = cloneValue(data); replace(next); },
+    setConfig(next) { replace(next); },
+    setReducedMotion(value) { if (value !== null && typeof value !== "boolean") throw new TypeError("reduced motion must be true, false, or null"); reducedOverride = value; isReduced() ? clock.settle() : draw(clock.progress); },
+    resize,
+    destroy() { if (destroyed) return; destroyed = true; clock.destroy(); resizeObserver?.disconnect(); intersectionObserver?.disconnect(); document.removeEventListener("visibilitychange", visibility); media?.removeEventListener?.("change", mediaChange); companion.destroy(); },
+    getState() { return { progress: clock.progress, playing: clock.playing, reducedMotion: isReduced(), renderers: contract.panels.map((panel) => panel.renderer), sceneVersion: scene.schemaVersion, resolvedSceneVersion: resolvedScene.schemaVersion, composedSceneVersion: composedScene.schemaVersion, profile: contract.view.profile, destroyed }; },
+    getScene() { return scene; },
+    getResolvedScene() { return resolvedScene; },
+    getComposedScene() { return composedScene; },
+    getFinalCoordinates() {
+      return preparedPanels.map((state, index) => {
+        if (isResolvedRenderer(state.panel.renderer)) return { panelId: state.panel.id, points: resolvedScene.panels[index].marks.filter((mark) => mark.kind === "point").map((mark) => ({ x: mark.geometry.cx, y: mark.geometry.cy, dataX: mark.x ?? mark.group, dataY: mark.y ?? mark.yCategory })) };
+        const scales = state.definition.draw(surface.context, { contract: state.contract, prepared: state.prepared, layout: surface.layout.panels[index], domains: domains[index], progress: 1, settled: true, panel: state.panel, figure: contract });
+        return { panelId: state.panel.id, points: (state.prepared.points ?? []).map((point) => ({ x: scales?.x?.(point.x), y: scales?.y?.(point.y), dataX: point.x, dataY: point.y })) };
+      });
+    },
+  });
+}

package/src/evidence-coverage.js

@@ -0,0 +1,80 @@
+import { FiguresteadConfigError } from "./schema.js";
+
+const finite = (value) => typeof value === "number" && Number.isFinite(value);
+
+function numericCoordinate(axis, value, path, values) {
+  if (finite(value)) values.push({ axis, value, path });
+}
+
+function timeCoordinate(axis, value, path, values) {
+  const parsed = finite(value) ? value : Date.parse(value);
+  if (Number.isFinite(parsed)) values.push({ axis, value: parsed, path });
+}
+
+function coordinate(axis, value, path, panel, values) {
+  if (panel.scales?.[axis]?.type === "time") timeCoordinate(axis, value, path, values);
+  else numericCoordinate(axis, value, path, values);
+}
+
+function markCoordinates(panel, mark) {
+  const values = [], base = `panels.${panel.id}.marks.${mark.id}`;
+  if (mark.kind === "point") {
+    coordinate("x", mark.x, `${base}.x`, panel, values);
+    coordinate("y", mark.y, `${base}.y`, panel, values);
+  } else if (mark.kind === "bar") {
+    const axis = mark.orientation === "horizontal" ? "x" : "y";
+    numericCoordinate(axis, 0, `${base}.baseline`, values);
+    if (!mark.missing) numericCoordinate(axis, mark.value, `${base}.value`, values);
+  } else if (mark.kind === "interval") {
+    numericCoordinate("x", mark.low, `${base}.low`, values);
+    numericCoordinate("x", mark.high, `${base}.high`, values);
+    numericCoordinate("x", mark.observed, `${base}.observed`, values);
+  } else if (mark.kind === "connector") {
+    numericCoordinate("x", mark.x1, `${base}.x1`, values);
+    numericCoordinate("x", mark.x2, `${base}.x2`, values);
+  } else if (mark.kind === "reference-band") {
+    numericCoordinate("y", mark.from, `${base}.from`, values);
+    numericCoordinate("y", mark.to, `${base}.to`, values);
+  } else if (mark.kind === "baseline-rule") {
+    numericCoordinate("x", mark.x, `${base}.x`, values);
+  } else if (mark.kind === "rug") {
+    coordinate("x", mark.x, `${base}.x`, panel, values);
+  } else if (mark.kind === "temporal-bar") {
+    coordinate("x", mark.xFrom, `${base}.xFrom`, panel, values);
+    coordinate("x", mark.xTo, `${base}.xTo`, panel, values);
+  } else if (mark.kind === "median-rule") {
+    numericCoordinate("y", mark.y, `${base}.y`, values);
+  }
+  // Segments repeat validated point evidence. Summary/model geometry and curve
+  // control points are renderer output and may honestly require clipping.
+  return values;
+}
+
+function normalizedDomain(panel, axis) {
+  const value = panel.domain?.[axis];
+  if (!Array.isArray(value) || value.length !== 2) return null;
+  if (panel.scales?.[axis]?.type !== "time") return value;
+  return value.map((item) => finite(item) ? item : Date.parse(item));
+}
+
+export function validateEvidenceCoverage(panels) {
+  const findings = [];
+  panels.forEach((panel) => {
+    panel.marks.forEach((mark) => markCoordinates(panel, mark).forEach((item) => {
+      const domain = normalizedDomain(panel, item.axis);
+      if (!domain || !domain.every(Number.isFinite)) return;
+      if (item.value < domain[0] || item.value > domain[1]) findings.push({
+        panelId: panel.id, markId: mark.id, axis: item.axis, value: item.value,
+        domain: [...domain], path: item.path,
+      });
+    }));
+  });
+  if (findings.length) {
+    const first = findings[0];
+    throw new FiguresteadConfigError(
+      `evidence value ${first.value} falls outside ${first.axis} domain [${first.domain.join(", ")}]; clipping may not hide evidence`,
+      first.path,
+    );
+  }
+  return Object.freeze({ clean: true, checkedPanels: panels.length, findings: Object.freeze(findings) });
+}

package/src/export-bundle.js

@@ -0,0 +1,83 @@
+import { CORE_REGISTRY } from "./core-renderers.js";
+import { composeResolvedScene } from "./composition.js";
+import { resolveTerminalScene, resolvedTerminalGeometry } from "./resolved-scene.js";
+import { resolvedSceneToSvg } from "./svg-export.js";
+import { compileTerminalScene, evidenceFingerprint } from "./terminal-scene.js";
+import { auditPhysicalTypography, resolveExportSize } from "./physical-export.js";
+
+export const EXPORT_MANIFEST_VERSION = "figurestead.export-manifest/1";
+export const FIGURESTEAD_PACKAGE_VERSION = "0.9.0-alpha.1";
+
+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 stableStringify(value, space = 2) {
+  return JSON.stringify(sorted(value), null, space);
+}
+
+function contentFingerprint(value) {
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < value.length; index += 1) {
+    hash ^= value.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return `fnv1a32:${(hash >>> 0).toString(16).padStart(8, "0")}`;
+}
+
+function dimension(value, name) {
+  if (!Number.isFinite(value) || value <= 0) throw new TypeError(`${name} must be a positive finite number`);
+  return value;
+}
+
+export function exportFigureArtifacts(input, options = {}) {
+  const registry = options.registry ?? CORE_REGISTRY;
+  const exportSize = resolveExportSize(options), width = dimension(exportSize.width, "width"), height = dimension(exportSize.height, "height");
+  const scene = input?.schemaVersion === "figurestead.scene/1" ? input : compileTerminalScene(input, { registry });
+  const resolved = resolveTerminalScene(scene, { width, height }), composed = composeResolvedScene(resolved);
+  const svg = resolvedSceneToSvg(composed, { ...options, exportSize, sourceScene: scene });
+  const sceneJson = stableStringify(scene);
+  const geometryJson = stableStringify({ schemaVersion: "figurestead.geometry-export/1", width, height, panels: resolvedTerminalGeometry(composed), composition: composed.panels.map((panel) => ({ panelId: panel.id, legend: panel.layout.legend, annotations: panel.composedAnnotations })) });
+  const manifest = {
+    formatVersion: EXPORT_MANIFEST_VERSION,
+    packageVersion: FIGURESTEAD_PACKAGE_VERSION,
+    sourceSceneVersion: scene.schemaVersion,
+    resolvedSceneVersion: resolved.schemaVersion,
+    composedSceneVersion: composed.schemaVersion,
+    contractSchemaVersion: scene.contractSchemaVersion,
+    rendererApiVersion: scene.rendererApiVersion,
+    evidenceFingerprint: evidenceFingerprint(scene),
+    dimensions: { width, height },
+    physical: exportSize.physical ? { ...exportSize.physical, typographyAudit: auditPhysicalTypography(composed, exportSize.physical) } : null,
+    profile: scene.applicationProfile?.key ?? scene.view?.profile ?? null,
+    theme: { key: scene.theme.key, name: scene.theme.name },
+    appearanceAudit: scene.appearanceReport,
+    evidenceCoverage: scene.evidenceCoverage,
+    renderers: scene.panels.map((panel) => ({ panelId: panel.id, renderer: panel.renderer, marks: panel.marks.length })),
+    annotationAudit: composed.compositionAudit,
+    contentFingerprints: {
+      algorithm: "fnv1a32",
+      svg: contentFingerprint(svg),
+      scene: contentFingerprint(sceneJson),
+      geometry: contentFingerprint(geometryJson),
+    },
+    artifacts: { svg: "figure.svg", scene: "scene.json", geometry: "geometry.json", manifest: "manifest.json", png: "figure.png" },
+  };
+  return Object.freeze({
+    scene,
+    resolved,
+    composed,
+    svg,
+    sceneJson,
+    geometryJson,
+    manifest: Object.freeze(manifest),
+    manifestJson: stableStringify(manifest),
+  });
+}
+
+export function canvasToPngBlob(canvas, options = {}) {
+  if (!canvas || typeof canvas.toBlob !== "function") return Promise.reject(new TypeError("canvasToPngBlob requires a canvas with toBlob"));
+  return new Promise((resolve, reject) => canvas.toBlob((blob) => blob ? resolve(blob) : reject(new Error("PNG encoding returned no data")), "image/png", options.quality));
+}

package/src/extensions/temporal/coverage.js

@@ -0,0 +1,96 @@
+import { arrival } from "../../renderers/shared.js";
+import { drawText, pointMotionState } from "../../marks.js";
+import { drawBar } from "../../primitives.js";
+import { linearScale } from "../../scales.js";
+import { drawTemporalAxes, makeTemporalScales, postMarksProgress, temporalXDomain, yearStart } from "./shared.js";
+
+export function prepareCoverage(contract) {
+  const points = contract.data.dates.map((date, index) => ({
+    date, x: Date.parse(`${date}T00:00:00Z`), y: contract.data.siteOrder.indexOf(contract.data.sites[index]),
+    site: contract.data.sites[index], colorIndex: contract.data.siteOrder.indexOf(contract.data.sites[index]), index,
+  }));
+  const arrived = arrival(points, contract, "x");
+  const years = new Map();
+  points.forEach((point) => {
+    const year = Number(point.date.slice(0, 4));
+    if (!years.has(year)) years.set(year, { year, sites: new Set(), observations: 0 });
+    years.get(year).sites.add(point.site); years.get(year).observations += 1;
+  });
+  const annual = [...years.values()].sort((a, b) => a.year - b.year).map((item) => ({ year: item.year, siteCount: item.sites.size, observationCount: item.observations }));
+  return { points: arrived, annual, settledAt: Math.max(...arrived.map((point) => point.delay + point.duration)) };
+}
+
+export function compileCoverageScene({ panel, contract, prepared, markId }) {
+  const marks = prepared.annual.map((item) => ({
+    id: markId(panel, "annual-count", item.year), kind: "temporal-bar", role: "summary",
+    year: item.year, xFrom: yearStart(item.year), xTo: yearStart(item.year + 1),
+    value: item.siteCount, observationCount: item.observationCount,
+    maximum: contract.data.siteOrder.length,
+    style: { color: contract.theme.secondary, edge: contract.theme.spine, lineStyle: "solid", lineWidth: 1 },
+  }));
+  prepared.points.forEach((point) => marks.push({
+    id: markId(panel, "rug", point.date, point.site, point.index), kind: "rug", series: point.site,
+    x: point.x, yCategory: point.site, date: point.date,
+    style: {
+      key: point.site, colorIndex: point.colorIndex,
+      color: contract.theme.series[point.colorIndex % contract.theme.series.length],
+      edge: contract.theme.seriesEdges?.[point.colorIndex % (contract.theme.seriesEdges?.length || 1)] ?? null,
+      glyph: "ring", lineStyle: "solid", lineWidth: 1.35,
+    },
+  }));
+  return {
+    marks,
+    categories: { x: null, y: [...contract.data.siteOrder] },
+    scales: { x: contract.xScale, y: { ...contract.yScale, type: "band" } },
+    legend: [],
+    meta: { coverage: true, maximumSites: contract.data.siteOrder.length },
+  };
+}
+
+function drawRugMark(context, state, { color, scale, settled, trailAlpha }) {
+  if (state.visibility <= 0) return;
+  context.save(); context.strokeStyle = color;
+  if (!settled) {
+    context.globalAlpha = trailAlpha * state.visibility * (1 - state.eased); context.lineWidth = Math.max(0.6, 0.8 * scale);
+    context.beginPath(); context.moveTo(state.x, state.y - 3 * scale); context.lineTo(state.x, state.y - (8 + 20 * (1 - state.eased)) * scale); context.stroke();
+  }
+  context.globalAlpha = 0.82 * state.visibility; context.lineWidth = Math.max(1, 1.35 * scale);
+  context.beginPath(); context.moveTo(state.x, state.y - 5 * scale); context.lineTo(state.x, state.y + 5 * scale); context.stroke(); context.restore();
+}
+
+export function coverageDomains(contract, prepared) {
+  const evidenceExtent = [
+    ...prepared.points.map((point) => point.x),
+    ...prepared.annual.flatMap((item) => [yearStart(item.year), yearStart(item.year + 1)]),
+  ];
+  return { x: temporalXDomain(contract, evidenceExtent), y: [-0.5, contract.data.siteOrder.length - 0.5] };
+}
+
+export function drawCoverage(context, env) {
+  const { contract, prepared, layout, progress, settled } = env;
+  const height = layout.plot.bottom - layout.plot.top;
+  const countPlot = { ...layout.plot, bottom: layout.plot.top + Math.min(48 * layout.scale, height * 0.22) };
+  const rugPlot = { ...layout.plot, top: countPlot.bottom + Math.max(8, 10 * layout.scale) };
+  const xDomain = env.domains.x, yDomain = [-0.5, contract.data.siteOrder.length - 0.5];
+  const scales = makeTemporalScales(xDomain, yDomain, rugPlot);
+  scales.y = linearScale(yDomain, [rugPlot.top, rugPlot.bottom]);
+  drawTemporalAxes(context, { contract, layout, scales, plot: rugPlot, yLabels: contract.data.siteOrder });
+  const cp = postMarksProgress(progress, prepared, contract.timeline);
+  if (cp > 0 && prepared.annual.length) {
+    const maximum = Math.max(1, contract.data.siteOrder.length);
+    prepared.annual.forEach((item) => {
+      const left = Math.max(countPlot.left, scales.x(yearStart(item.year)) + 1);
+      const right = Math.min(countPlot.right, scales.x(yearStart(item.year + 1)) - 1);
+      if (right <= left) return;
+      const barHeight = (countPlot.bottom - countPlot.top - 12 * layout.scale) * item.siteCount / maximum * cp;
+      drawBar(context, { left, right, top: countPlot.bottom - barHeight, bottom: countPlot.bottom, color: contract.theme.secondary, alpha: 0.24 * cp });
+      context.save(); context.globalAlpha = cp; context.fillStyle = contract.theme.secondary; context.font = `${Math.max(7, layout.font.axis * 0.75)}px ui-monospace, monospace`;
+      context.textAlign = "center"; context.textBaseline = "bottom"; context.fillText(String(item.siteCount), (left + right) / 2, countPlot.bottom - barHeight - 2); context.restore();
+    });
+  }
+  prepared.points.forEach((point) => drawRugMark(context, pointMotionState(point, progress, scales, rugPlot), {
+    color: contract.theme.series[point.colorIndex % contract.theme.series.length], scale: layout.scale, settled, trailAlpha: contract.motion.trailAlpha,
+  }));
+  drawText(context, { config: contract, layout, legend: [] });
+  return scales;
+}

package/src/extensions/temporal/index.js

@@ -0,0 +1,43 @@
+import { defineRenderer, RENDERER_API_VERSION } from "../../registry.js";
+import { prepareCoverage, coverageDomains, drawCoverage, compileCoverageScene } from "./coverage.js";
+import { prepareObservations, observationDomains, drawObservations, compileObservationsScene } from "./observations.js";
+import { normalizeReferenceBands, PROVISIONAL_LABEL, validateCoverageData, validateObservationData } from "./shared.js";
+
+export const TEMPORAL_COVERAGE_RENDERER = defineRenderer({
+  key: "temporal_coverage", family: "temporal", apiVersion: RENDERER_API_VERSION,
+  validateData: validateCoverageData, prepare: prepareCoverage, compileScene: compileCoverageScene, domains: coverageDomains, draw: drawCoverage,
+  describe(contract) {
+    const annual = new Map();
+    contract.data.dates.forEach((date, index) => {
+      const year = date.slice(0, 4); if (!annual.has(year)) annual.set(year, new Set()); annual.get(year).add(contract.data.sites[index]);
+    });
+    return {
+      summary: `${contract.data.dates.length} exact, sparse dated observations across ${contract.data.siteOrder.length} ordered sites. Annual counts are distinct sampled sites, not continuous coverage.`,
+      headers: ["date", "site", "distinct sites sampled that year"],
+      rows: contract.data.dates.map((date, index) => [date, contract.data.sites[index], annual.get(date.slice(0, 4)).size]),
+    };
+  },
+});
+
+export const TEMPORAL_OBSERVATIONS_RENDERER = defineRenderer({
+  key: "temporal_observations", family: "temporal", apiVersion: RENDERER_API_VERSION,
+  validateData: validateObservationData, prepare: prepareObservations, compileScene: compileObservationsScene, domains: observationDomains, draw: drawObservations,
+  describe(contract) {
+    const bands = normalizeReferenceBands(contract.data.referenceBands ?? [], "config.data.referenceBands");
+    const bandFor = (value) => bands.find((band, index) => value >= band.from && (value < band.to || (index === bands.length - 1 && value <= band.to)));
+    return {
+      summary: `${contract.data.values.length} sparse, unconnected observations for ${contract.data.site}.${bands.length ? ` Reference bands are ${PROVISIONAL_LABEL.toLowerCase()}.` : ""}`,
+      headers: ["date", "site", contract.spec.yLabel || "value", "project reference band"],
+      rows: contract.data.dates.map((date, index) => {
+        const band = bandFor(contract.data.values[index]);
+        return [date, contract.data.site, contract.data.values[index], band ? `${band.label} — ${PROVISIONAL_LABEL}` : "None"];
+      }),
+    };
+  },
+});
+
+export const TEMPORAL_RENDERERS = Object.freeze([TEMPORAL_COVERAGE_RENDERER, TEMPORAL_OBSERVATIONS_RENDERER]);
+
+export { PROVISIONAL_LABEL, PROVISIONAL_STATUS, validateCoverageData, validateObservationData } from "./shared.js";
+export { compileCoverageScene } from "./coverage.js";
+export { compileObservationsScene } from "./observations.js";