@figurestead/web 0.9.0-alpha.1

package/src/motion-plan.js

@@ -0,0 +1,66 @@
+import { clamp01, smooth } from "./marks.js";
+
+export const MOTION_PLAN_VERSION = "figurestead.motion-plan/1";
+export const ALLOWED_MOTION_CHANNELS = Object.freeze(["opacity", "translate", "scale", "clip", "glow"]);
+export const TERMINAL_MOTION_STATE = Object.freeze({ opacity: 1, translateX: 0, translateY: 0, scaleX: 1, scaleY: 1, clip: 1, glow: 0 });
+
+const STRATEGY_CHANNELS = Object.freeze({
+  none: [], reveal: ["opacity", "clip"], points_then_connect: ["opacity", "translate", "clip", "glow"],
+  bar_grow: ["opacity", "scale", "clip"], matrix_illuminate: ["opacity", "glow"],
+});
+
+const AUTO = Object.freeze({
+  line: "points_then_connect", scatter: "points_then_connect",
+  categorical_bar: "bar_grow", categorical_layered_bar: "bar_grow",
+  categorical_matrix: "matrix_illuminate",
+  interval_comparison: "points_then_connect",
+  strip_summary: "points_then_connect",
+  temporal_coverage: "reveal",
+  temporal_observations: "reveal",
+  paired_points: "points_then_connect",
+  reference_improvement: "reveal",
+});
+
+export function strategyForRenderer(renderer, requested = "auto") {
+  if (requested === "auto") return AUTO[renderer] ?? "reveal";
+  return requested ?? "none";
+}
+
+export function compileMotionPlan(scene, view = {}) {
+  const motion = view.motion ?? "none", requested = view.strategy ?? "auto";
+  const panels = scene.panels.map((panel) => ({
+    panelId: panel.id,
+    renderer: panel.renderer,
+    strategy: motion === "none" ? "none" : strategyForRenderer(panel.renderer, requested),
+    targets: panel.marks.map((mark, index) => {
+      const strategy = motion === "none" ? "none" : strategyForRenderer(panel.renderer, requested);
+      return { id: mark.id, order: index, channels: [...(STRATEGY_CHANNELS[strategy] ?? STRATEGY_CHANNELS.reveal)] };
+    }),
+  }));
+  return Object.freeze({ schemaVersion: MOTION_PLAN_VERSION, motion, panels });
+}
+
+export function markMotionState(mark, index, count, progress, strategy = "reveal") {
+  if (progress >= 1 || strategy === "none") return { ...TERMINAL_MOTION_STATE };
+  const stagger = count <= 1 ? 0 : (index / (count - 1)) * 0.28;
+  const local = smooth(clamp01((progress - stagger) / Math.max(1e-9, 1 - stagger)));
+  if (strategy === "points_then_connect") {
+    const point = mark.kind === "point", pointLocal = smooth(clamp01(local / 0.62));
+    const lineLocal = smooth(clamp01((local - 0.48) / 0.52));
+    return { opacity: point ? pointLocal : lineLocal, translateX: 0, translateY: point ? (1 - pointLocal) * -12 : 0, scaleX: 1, scaleY: 1, clip: point ? 1 : lineLocal, glow: point ? Math.sin(Math.PI * pointLocal) * 0.18 : 0 };
+  }
+  if (strategy === "bar_grow") return { opacity: local, translateX: 0, translateY: 0, scaleX: mark.orientation === "horizontal" ? local : 1, scaleY: mark.orientation === "horizontal" ? 1 : local, clip: local, glow: 0 };
+  if (strategy === "matrix_illuminate") return { opacity: local, translateX: 0, translateY: 0, scaleX: 1, scaleY: 1, clip: 1, glow: Math.sin(Math.PI * local) * 0.14 };
+  return { opacity: local, translateX: 0, translateY: 0, scaleX: 1, scaleY: 1, clip: local, glow: 0 };
+}
+
+export function assertTerminalMotionIdentity(plan, scene) {
+  plan.panels.forEach((panel) => {
+    const scenePanel = scene.panels.find((item) => item.id === panel.panelId);
+    panel.targets.forEach((target, index) => {
+      const state = markMotionState(scenePanel.marks[index], index, panel.targets.length, 1, panel.strategy);
+      if (Object.entries(TERMINAL_MOTION_STATE).some(([channel, value]) => state[channel] !== value)) throw new Error(`motion plan ${target.id} changes terminal evidence`);
+    });
+  });
+  return true;
+}

package/src/motion-recipes.js

@@ -0,0 +1,39 @@
+import { cloneValue } from "./schema.js";
+
+export const MOTION_RECIPE_VERSION = "figurestead.motion-recipe/1";
+const MOTION_VALUES = new Set(["none", "semantic", "legacy"]);
+const AMBIENT_VALUES = new Set(["none", "matrix"]);
+const STRATEGY_VALUES = new Set(["auto", "none", "reveal", "points_then_connect", "bar_grow", "matrix_illuminate"]);
+
+export const MOTION_RECIPES = Object.freeze({
+  static: Object.freeze({ key: "static", name: "Static", motion: "none", ambient: "none", strategy: "none", durationMs: 1, lightingPeak: 0 }),
+  restrained: Object.freeze({ key: "restrained", name: "Restrained", motion: "semantic", ambient: "none", strategy: "auto", durationMs: 1800, lightingPeak: 0.035 }),
+  expressive: Object.freeze({ key: "expressive", name: "Expressive", motion: "semantic", ambient: "none", strategy: "auto", durationMs: 2800, lightingPeak: 0.075 }),
+  matrix_origin: Object.freeze({ key: "matrix_origin", name: "Matrix origin", motion: "semantic", ambient: "matrix", strategy: "auto", durationMs: 3200, lightingPeak: 0.08 }),
+});
+
+export function resolveMotionRecipe(value = "restrained") {
+  const recipe = typeof value === "string" ? MOTION_RECIPES[value] : value;
+  if (!recipe || typeof recipe !== "object") throw new TypeError(`unknown motion recipe; choose ${Object.keys(MOTION_RECIPES).join(", ")}`);
+  for (const key of ["key", "motion", "ambient", "strategy"]) if (typeof recipe[key] !== "string" || !recipe[key]) throw new TypeError(`motion recipe ${key} must be a non-empty string`);
+  if (!MOTION_VALUES.has(recipe.motion)) throw new TypeError(`motion recipe motion must be one of ${[...MOTION_VALUES].join(", ")}`);
+  if (!AMBIENT_VALUES.has(recipe.ambient)) throw new TypeError(`motion recipe ambient must be one of ${[...AMBIENT_VALUES].join(", ")}`);
+  if (!STRATEGY_VALUES.has(recipe.strategy)) throw new TypeError(`motion recipe strategy is unsupported`);
+  if (!Number.isFinite(recipe.durationMs) || recipe.durationMs <= 0) throw new TypeError("motion recipe durationMs must be a positive finite number");
+  if (!Number.isFinite(recipe.lightingPeak) || recipe.lightingPeak < 0 || recipe.lightingPeak > 1) throw new TypeError("motion recipe lightingPeak must be between 0 and 1");
+  return Object.freeze({ ...recipe });
+}
+
+export function applyMotionRecipe(input, recipe = "restrained") {
+  const result = cloneValue(input), value = resolveMotionRecipe(recipe);
+  if (!result || typeof result !== "object" || !result.motion || typeof result.motion !== "object" || Array.isArray(result.motion)) {
+    throw new TypeError("applyMotionRecipe requires a Figurestead contract with a motion object");
+  }
+  result.view = { ...(result.view ?? {}), motion: value.motion, ambient: value.ambient, strategy: value.strategy };
+  result.motion = {
+    ...result.motion,
+    durationMs: value.durationMs,
+    lightingPeak: value.lightingPeak,
+  };
+  return result;
+}

package/src/paper-profile.js

@@ -0,0 +1,78 @@
+import { colorContrast, hexToOklab, resolveContrastColor } from "./color-space.js";
+
+export const PAPER_PROFILE_VERSION = "figurestead.paper-profile/1";
+export const PAPER_FLOORS = Object.freeze({ text: 4.5, evidence: 3, thinEvidenceTarget: 4, pairwiseLightness: 0.1, identityWarning: 0.12 });
+export const PAPER_SURFACE = Object.freeze({
+  field: "#FFFFFF", panel: "#FBFBF8", grid: "#D9DEDA", spine: "#66736D",
+  label: "#17211D", secondary: "#4C5C55", faint: "#727E79",
+});
+
+const rounded = (value) => Number(value.toFixed(3));
+
+function resolveRole(source, role, surface, minimum, report) {
+  const result = resolveContrastColor(source[role], surface, minimum);
+  report.resolutions.push({ token: role, ...result, contrast: rounded(result.contrast), identityDelta: rounded(result.identityDelta), lightnessDelta: rounded(result.lightnessDelta), chromaReduction: rounded(result.chromaReduction), hueDelta: rounded(result.hueDelta) });
+  if (result.identityDelta > PAPER_FLOORS.identityWarning) report.findings.push({ level: "warning", code: "palette-identity-loss", token: role, delta: rounded(result.identityDelta) });
+  return result.color;
+}
+
+export function auditPaperTheme(theme, seriesStyles = null) {
+  const findings = [], checks = [];
+  for (const token of ["label", "secondary"]) {
+    const ratio = colorContrast(theme[token], theme.panel); checks.push({ token, surface: "panel", ratio: rounded(ratio), minimum: PAPER_FLOORS.text });
+    if (ratio < PAPER_FLOORS.text) findings.push({ level: "error", code: "contrast", token, surface: "panel", ratio: rounded(ratio), minimum: PAPER_FLOORS.text });
+  }
+  for (const token of ["primary", "summaryCore", "warm"]) {
+    const ratio = colorContrast(theme[token], theme.panel); checks.push({ token, surface: "panel", ratio: rounded(ratio), minimum: PAPER_FLOORS.evidence });
+    if (ratio < PAPER_FLOORS.evidence) findings.push({ level: "error", code: "contrast", token, surface: "panel", ratio: rounded(ratio), minimum: PAPER_FLOORS.evidence });
+    else if (ratio < PAPER_FLOORS.thinEvidenceTarget) findings.push({ level: "warning", code: "thin-evidence-contrast", token, ratio: rounded(ratio), target: PAPER_FLOORS.thinEvidenceTarget });
+  }
+  theme.series.forEach((color, index) => {
+    const ratio = colorContrast(color, theme.panel); checks.push({ token: `series[${index}]`, surface: "panel", ratio: rounded(ratio), minimum: PAPER_FLOORS.evidence });
+    if (ratio < PAPER_FLOORS.evidence) findings.push({ level: "error", code: "contrast", token: `series[${index}]`, surface: "panel", ratio: rounded(ratio), minimum: PAPER_FLOORS.evidence });
+  });
+  const activeIndexes = seriesStyles
+    ? [...new Set(Object.values(seriesStyles).map((item) => item.colorIndex))].sort((a, b) => a - b)
+    : theme.series.map((_, index) => index);
+  for (let aIndex = 0; aIndex < activeIndexes.length; aIndex += 1) for (let bIndex = aIndex + 1; bIndex < activeIndexes.length; bIndex += 1) {
+    const left = activeIndexes[aIndex], right = activeIndexes[bIndex];
+    const a = hexToOklab(theme.series[left]), b = hexToOklab(theme.series[right]), deltaL = Math.abs(a.L - b.L);
+    const leftStyle = seriesStyles ? Object.values(seriesStyles).find((item) => item.colorIndex === left) : null;
+    const rightStyle = seriesStyles ? Object.values(seriesStyles).find((item) => item.colorIndex === right) : null;
+    const redundant = Boolean(leftStyle && rightStyle && (leftStyle.glyph !== rightStyle.glyph || leftStyle.lineStyle !== rightStyle.lineStyle || leftStyle.hatch !== rightStyle.hatch));
+    if (deltaL < PAPER_FLOORS.pairwiseLightness && !redundant) findings.push({ level: "warning", code: "pairwise-lightness", series: [left, right], deltaL: rounded(deltaL), redundant: false });
+  }
+  return Object.freeze({ schemaVersion: PAPER_PROFILE_VERSION, clean: findings.every((item) => item.level !== "error"), checks: Object.freeze(checks), findings: Object.freeze(findings) });
+}
+
+export function resolvePaperTheme(source) {
+  const report = { schemaVersion: PAPER_PROFILE_VERSION, resolutions: [], findings: [] };
+  const theme = {
+    ...source, ...PAPER_SURFACE, mode: "paper",
+    key: source.key.endsWith("-paper") ? source.key : `${source.key}-paper`,
+    name: source.name.endsWith(" · Paper") ? source.name : `${source.name} · Paper`,
+  };
+  theme.primary = resolveRole(source, "primary", theme.panel, PAPER_FLOORS.thinEvidenceTarget, report);
+  theme.summaryCore = resolveRole(source, "summaryCore", theme.panel, PAPER_FLOORS.thinEvidenceTarget, report);
+  theme.warm = resolveRole(source, "warm", theme.panel, PAPER_FLOORS.evidence, report);
+  theme.series = source.series.map((color, index) => {
+    const result = resolveContrastColor(color, theme.panel, PAPER_FLOORS.evidence);
+    report.resolutions.push({ token: `series[${index}]`, ...result, contrast: rounded(result.contrast), identityDelta: rounded(result.identityDelta), lightnessDelta: rounded(result.lightnessDelta), chromaReduction: rounded(result.chromaReduction), hueDelta: rounded(result.hueDelta) });
+    if (result.identityDelta > PAPER_FLOORS.identityWarning) report.findings.push({ level: "warning", code: "palette-identity-loss", token: `series[${index}]`, delta: rounded(result.identityDelta) });
+    return result.color;
+  });
+  if (source.primaryEdge) theme.primaryEdge = resolveContrastColor(source.primaryEdge, theme.panel, PAPER_FLOORS.evidence).color;
+  if (source.summaryEdge) theme.summaryEdge = resolveContrastColor(source.summaryEdge, theme.panel, PAPER_FLOORS.evidence).color;
+  theme.seriesEdges = (source.seriesEdges ?? theme.series.map(() => PAPER_SURFACE.label)).map((color) => resolveContrastColor(color, theme.panel, PAPER_FLOORS.evidence).color);
+  const audit = auditPaperTheme(theme);
+  report.findings.push(...audit.findings);
+  return Object.freeze({ theme: Object.freeze(theme), report: Object.freeze({ ...report, audit, clean: audit.clean }) });
+}
+
+export function themeResolutionForProfile(source, profile = "atlas") {
+  const key = typeof profile === "string" ? profile : profile?.key;
+  const clone = (value) => JSON.parse(JSON.stringify(value));
+  if (key !== "paper") return Object.freeze({ theme: clone(source), report: null });
+  if (source.mode === "paper") return Object.freeze({ theme: clone(source), report: auditPaperTheme(source) });
+  return resolvePaperTheme(source);
+}

package/src/physical-export.js

@@ -0,0 +1,34 @@
+export const PAPER_SIZE_PRESETS = Object.freeze({ "paper-single": 89, "paper-double": 183 });
+const MM_PER_INCH = 25.4, CSS_DPI = 96, PT_PER_INCH = 72;
+
+function positive(value, name) {
+  if (!Number.isFinite(value) || value <= 0) throw new TypeError(`${name} must be a positive finite number`);
+  return value;
+}
+
+export function resolveExportSize(options = {}) {
+  const presetWidth = options.paperSize == null ? null : PAPER_SIZE_PRESETS[options.paperSize];
+  if (options.paperSize != null && presetWidth == null) throw new TypeError(`paperSize must be ${Object.keys(PAPER_SIZE_PRESETS).join(" or ")}`);
+  const widthMm = options.physicalWidthMm == null ? presetWidth : positive(options.physicalWidthMm, "physicalWidthMm");
+  const width = positive(options.width ?? (widthMm ? Math.round(widthMm * CSS_DPI / MM_PER_INCH) : 960), "width");
+  const height = positive(options.height ?? Math.max(240, Math.round(width * 0.625)), "height");
+  if (!widthMm) return Object.freeze({ width, height, physical: null, widthAttribute: width, heightAttribute: height });
+  const heightMm = widthMm * height / width;
+  return Object.freeze({
+    width, height, widthAttribute: `${rounded(widthMm)}mm`, heightAttribute: `${rounded(heightMm)}mm`,
+    physical: Object.freeze({ preset: options.paperSize ?? "custom", widthMm: rounded(widthMm), heightMm: rounded(heightMm), minLabelPt: positive(options.minLabelPt ?? 6, "minLabelPt") }),
+  });
+}
+
+const rounded = (value) => Number(value.toFixed(3));
+
+export function auditPhysicalTypography(composed, physical) {
+  if (!physical) return null;
+  const scale = physical.widthMm / composed.width * PT_PER_INCH / MM_PER_INCH;
+  const labels = composed.panels.flatMap((panel) => [
+    [panel.id, "axis", panel.layout.font.axis], [panel.id, "legend", panel.layout.font.legend],
+    [panel.id, "title", panel.layout.font.title], [panel.id, "subtitle", panel.layout.font.subtitle],
+  ]).map(([panelId, role, units]) => ({ panelId, role, points: rounded(units * scale) }));
+  const minimum = Math.min(...labels.map((item) => item.points));
+  return Object.freeze({ clean: minimum >= physical.minLabelPt, minimumPt: minimum, requiredPt: physical.minLabelPt, labels: Object.freeze(labels) });
+}

package/src/presentation.js

@@ -0,0 +1,127 @@
+import { cloneValue, windowProgress } from "./schema.js";
+import { clamp01, smooth } from "./marks.js";
+
+export const SCIENTIFIC_POSE = Object.freeze({
+  panelSurface: true,
+  frame: true,
+  curve: "monotone",
+  legend: "auto",
+  lineWidth: 2.35,
+  markerScale: 1.22,
+  seriesMarkers: Object.freeze(["ring", "square"]),
+});
+
+export function applyScientificPose(input, options = {}) {
+  const result = cloneValue(input);
+  if (!Array.isArray(result?.panels) || !result.panels.length) throw new TypeError("applyScientificPose requires a v0.4 contract with one or more panels");
+  const panelIds = new Set(result.panels.map((panel) => panel.id));
+  result.panels = result.panels.map((panel) => {
+    const presentation = {
+      panelSurface: true,
+      frame: true,
+      legend: options.legend ?? "auto",
+      markerScale: options.markerScale ?? SCIENTIFIC_POSE.markerScale,
+      ...(panel.renderer === "line" ? {
+        curve: options.curve ?? "monotone",
+        lineWidth: options.lineWidth ?? SCIENTIFIC_POSE.lineWidth,
+        seriesMarkers: options.seriesMarkers ?? ["ring", "square"],
+      } : {}),
+      ...(panel.presentation ?? {}),
+    };
+    return {
+      ...panel,
+      presentation,
+      ...(panel.renderer === "line" ? { encoding: { ...(panel.encoding ?? {}), interpolation: options.curve ?? panel.presentation?.curve ?? "monotone" } } : {}),
+    };
+  });
+  for (const focus of options.focus ?? []) {
+    if (!panelIds.has(focus.panelId)) throw new TypeError(`unknown focus panel ${focus.panelId}`);
+    const panel = result.panels.find((item) => item.id === focus.panelId);
+    panel.annotations = [...(panel.annotations ?? []), {
+      type: "focus", ...(focus.anchorId ? { anchorId: focus.anchorId } : { x: focus.x, y: focus.y, space: focus.space }), label: focus.label,
+      dx: focus.dx ?? 68, dy: focus.dy ?? 28,
+    }];
+  }
+  return result;
+}
+
+export function applyEvidencePose(input, options = {}) {
+  const focus = options.focus ?? [];
+  if (!Array.isArray(focus)) throw new TypeError("options.focus must be an array");
+  focus.forEach((item, index) => {
+    if (typeof item?.panelId !== "string" || !item.panelId.trim()) throw new TypeError(`focus[${index}].panelId must identify a panel`);
+    if (typeof item.anchorId !== "string" || !item.anchorId.trim()) throw new TypeError(`focus[${index}].anchorId must identify a compiled evidence mark`);
+    if (typeof item.label !== "string" || !item.label.trim()) throw new TypeError(`focus[${index}].label must be a non-empty string`);
+  });
+  return applyScientificPose(input, { ...options, focus });
+}
+
+export function drawPanelSurface(context, { contract, layout }) {
+  if (!contract.presentation?.panelSurface) return;
+  const { plot } = layout;
+  context.save();
+  context.fillStyle = contract.theme.panel;
+  context.fillRect(plot.left, plot.top, plot.right - plot.left, plot.bottom - plot.top);
+  if (contract.presentation.frame) {
+    context.strokeStyle = contract.theme.spine;
+    context.globalAlpha = 0.48;
+    context.lineWidth = Math.max(0.6, 0.75 * layout.scale);
+    context.strokeRect(plot.left, plot.top, plot.right - plot.left, plot.bottom - plot.top);
+  }
+  context.restore();
+}
+
+function position(annotation, scales, plot) {
+  if (annotation.space === "plot") {
+    return {
+      x: plot.left + clamp01(annotation.x) * (plot.right - plot.left),
+      y: plot.bottom - clamp01(annotation.y) * (plot.bottom - plot.top),
+    };
+  }
+  if (typeof scales?.x !== "function" || typeof scales?.y !== "function") return null;
+  const x = scales.x(annotation.x), y = scales.y(annotation.y);
+  return Number.isFinite(x) && Number.isFinite(y) ? { x, y } : null;
+}
+
+export function drawPresentationAnnotations(context, { contract, layout, scales, progress }) {
+  const focus = contract.annotations.filter((item) => item?.type === "focus");
+  if (!focus.length) return;
+  const reveal = smooth(windowProgress(progress, contract.timeline.summaryCompiles));
+  if (reveal <= 0) return;
+  const { plot } = layout, theme = contract.theme;
+  focus.forEach((annotation) => {
+    const point = position(annotation, scales, plot);
+    if (!point || typeof annotation.label !== "string" || !annotation.label.trim()) return;
+    const dx = Number.isFinite(annotation.dx) ? annotation.dx * layout.scale : 68 * layout.scale;
+    const dy = Number.isFinite(annotation.dy) ? annotation.dy * layout.scale : 28 * layout.scale;
+    const rawX = point.x + dx, rawY = point.y + dy;
+    const labelX = Math.max(plot.left + 26 * layout.scale, Math.min(plot.right - 26 * layout.scale, rawX));
+    const labelY = Math.max(plot.top + 22 * layout.scale, Math.min(plot.bottom - 20 * layout.scale, rawY));
+    const radius = Math.max(6.5, 8.4 * layout.scale) * reveal;
+    const fill = theme.summaryCore;
+    const edge = theme.seriesEdges?.[0] ?? theme.primaryEdge ?? theme.field;
+    context.save();
+    context.globalAlpha = reveal;
+    context.strokeStyle = theme.primary;
+    context.lineWidth = Math.max(3, radius * 0.62);
+    context.globalAlpha = 0.13 * reveal;
+    context.beginPath(); context.arc(point.x, point.y, radius * 1.45, 0, Math.PI * 2); context.stroke();
+    context.globalAlpha = 0.92 * reveal;
+    context.strokeStyle = fill;
+    context.lineWidth = Math.max(1, 1.25 * layout.scale);
+    context.beginPath(); context.moveTo(point.x + radius * 0.7, point.y + radius * 0.55); context.lineTo(labelX - 8 * layout.scale, labelY - 5 * layout.scale); context.stroke();
+    context.fillStyle = fill;
+    context.strokeStyle = edge;
+    context.lineWidth = Math.max(1.4, 1.9 * layout.scale);
+    context.beginPath(); context.arc(point.x, point.y, radius, 0, Math.PI * 2); context.fill(); context.stroke();
+    context.font = `600 ${Math.max(9, layout.font.legend * 1.06)}px ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace`;
+    context.textAlign = dx < 0 ? "right" : "left";
+    context.textBaseline = "middle";
+    context.strokeStyle = theme.field;
+    context.lineWidth = Math.max(1.6, 2.2 * layout.scale);
+    context.strokeText(annotation.label, labelX, labelY);
+    context.fillStyle = fill;
+    context.fillText(annotation.label, labelX, labelY);
+    context.restore();
+  });
+}

package/src/primitives.js

@@ -0,0 +1,24 @@
+export function drawRule(context, { x1, y1, x2, y2, color, alpha = 0.7, width = 1, dash = [] }) {
+  context.save(); context.strokeStyle = color; context.globalAlpha = alpha; context.lineWidth = width; context.setLineDash?.(dash);
+  context.beginPath(); context.moveTo(x1, y1); context.lineTo(x2, y2); context.stroke(); context.restore();
+}
+
+export function drawBand(context, { left, top, right, bottom, color, alpha = 0.08 }) {
+  context.save(); context.fillStyle = color; context.globalAlpha = alpha; context.fillRect(left, top, right - left, bottom - top); context.restore();
+}
+
+export function drawBar(context, { left, top, right, bottom, color, alpha = 0.55, stroke = null, lineWidth = 1 }) {
+  const width = Math.max(0, right - left), height = Math.max(0, bottom - top);
+  context.save(); context.fillStyle = color; context.globalAlpha = alpha; context.fillRect(left, top, width, height);
+  if (stroke) { context.strokeStyle = stroke; context.lineWidth = lineWidth; context.strokeRect(left, top, width, height); }
+  context.restore();
+}
+
+export function drawInterval(context, { x1, x2, y, color, alpha = 0.7, width = 1.4, cap = 0 }) {
+  drawRule(context, { x1, y1: y, x2, y2: y, color, alpha, width });
+  if (cap > 0) { drawRule(context, { x1, y1: y - cap, x2: x1, y2: y + cap, color, alpha, width }); drawRule(context, { x1: x2, y1: y - cap, x2, y2: y + cap, color, alpha, width }); }
+}
+
+export function drawCell(context, { left, top, right, bottom, color, alpha = 1, stroke = null }) {
+  drawBar(context, { left, top, right, bottom, color, alpha, stroke, lineWidth: 0.5 });
+}

package/src/random.js

@@ -0,0 +1,26 @@
+export function mulberry32(seed) {
+  let value = seed >>> 0;
+  return () => {
+    value |= 0;
+    value = (value + 0x6D2B79F5) | 0;
+    let t = Math.imul(value ^ (value >>> 15), 1 | value);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+}
+
+export function gaussian(random) {
+  let u = 0;
+  let v = 0;
+  while (!u) u = random();
+  while (!v) v = random();
+  return Math.sqrt(-2 * Math.log(u)) * Math.cos(2 * Math.PI * v);
+}
+
+export function deriveSeed(seed, namespace) {
+  let hash = seed >>> 0;
+  for (let index = 0; index < namespace.length; index += 1) {
+    hash = Math.imul(hash ^ namespace.charCodeAt(index), 16777619) >>> 0;
+  }
+  return hash;
+}

package/src/registry.js

@@ -0,0 +1,29 @@
+export const RENDERER_API_VERSION = "1";
+
+export function defineRenderer(definition) {
+  if (!definition || typeof definition !== "object") throw new TypeError("renderer definition must be an object");
+  if (typeof definition.key !== "string" || !definition.key.trim()) throw new TypeError("renderer.key must be a non-empty string");
+  if (definition.apiVersion !== RENDERER_API_VERSION) throw new TypeError(`renderer ${definition.key} requires apiVersion ${RENDERER_API_VERSION}`);
+  ["validateData", "prepare", "draw", "describe"].forEach((method) => {
+    if (typeof definition[method] !== "function") throw new TypeError(`renderer ${definition.key}.${method} must be a function`);
+  });
+  return Object.freeze({ family: "other", domains: () => ({}), ...definition });
+}
+
+export function createRendererRegistry(definitions = []) {
+  const entries = new Map();
+  definitions.forEach((candidate) => {
+    const definition = defineRenderer(candidate);
+    if (entries.has(definition.key)) throw new TypeError(`duplicate renderer key ${definition.key}`);
+    entries.set(definition.key, definition);
+  });
+  const api = {
+    apiVersion: RENDERER_API_VERSION,
+    get(key) { return entries.get(key) ?? null; },
+    has(key) { return entries.has(key); },
+    keys() { return Object.freeze([...entries.keys()]); },
+    definitions() { return Object.freeze([...entries.values()]); },
+    with(...more) { return createRendererRegistry([...entries.values(), ...more.flat()]); },
+  };
+  return Object.freeze(api);
+}

package/src/render-layers.js

@@ -0,0 +1,35 @@
+export const RENDER_LAYER_ORDER = Object.freeze([
+  "surface", "grid", "reference", "data", "summary", "axes", "annotations", "legend",
+]);
+
+const REFERENCE_MARKS = new Set(["reference-band", "row-band", "baseline-rule"]);
+const SUMMARY_MARKS = new Set(["summary-line", "median-rule"]);
+
+export function renderLayerForMark(mark) {
+  if (REFERENCE_MARKS.has(mark?.kind)) return "reference";
+  if (SUMMARY_MARKS.has(mark?.kind) || mark?.role === "summary") return "summary";
+  return "data";
+}
+
+export function partitionPanelMarks(marks = []) {
+  const layers = { reference: [], data: [], summary: [] };
+  marks.forEach((mark) => layers[renderLayerForMark(mark)].push(mark));
+  return layers;
+}
+
+export function plotClipRect(panel) {
+  const plot = panel?.evidenceFrame ?? panel?.axes?.plot ?? panel?.layout?.plot;
+  if (!plot || ![plot.left, plot.top, plot.right, plot.bottom].every(Number.isFinite)) {
+    throw new TypeError("resolved panel must expose a finite evidence-frame rectangle");
+  }
+  return Object.freeze({ left: plot.left, top: plot.top, right: plot.right, bottom: plot.bottom });
+}
+
+export function withCanvasPlotClip(context, panel, draw) {
+  const plot = plotClipRect(panel);
+  context.save();
+  context.beginPath();
+  context.rect(plot.left, plot.top, plot.right - plot.left, plot.bottom - plot.top);
+  context.clip();
+  try { return draw(plot); } finally { context.restore(); }
+}

package/src/renderer-test-kit.js

@@ -0,0 +1,29 @@
+import { RENDERER_API_VERSION } from "./registry.js";
+
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === "object") return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonical(value[key])]));
+  return value;
+}
+
+const stable = (value) => JSON.stringify(canonical(value));
+
+export function rendererConformance(definition, contract) {
+  const errors = [];
+  if (definition.apiVersion !== RENDERER_API_VERSION) errors.push(`apiVersion must be ${RENDERER_API_VERSION}`);
+  ["key", "validateData", "prepare", "draw", "describe"].forEach((name) => { if (definition[name] == null) errors.push(`missing ${name}`); });
+  let first, second;
+  try { first = definition.prepare(contract); second = definition.prepare(contract); } catch (error) { errors.push(`prepare failed: ${error.message}`); }
+  if (first !== undefined && stable(first) !== stable(second)) errors.push("prepare is not deterministic");
+  try {
+    const description = definition.describe(contract, first);
+    if (!description || typeof description.summary !== "string" || !Array.isArray(description.headers) || !Array.isArray(description.rows)) errors.push("describe must return summary, headers, and rows");
+  } catch (error) { errors.push(`describe failed: ${error.message}`); }
+  return Object.freeze({ ok: errors.length === 0, errors: Object.freeze(errors) });
+}
+
+export function assertRendererConformance(definition, contract) {
+  const result = rendererConformance(definition, contract);
+  if (!result.ok) throw new Error(`renderer ${definition.key ?? "unknown"} failed conformance: ${result.errors.join("; ")}`);
+  return result;
+}

package/src/renderers/line.js

@@ -0,0 +1,133 @@
+import { arrival, numericScales } from "./shared.js";
+import { clamp01, drawAxes, drawScopePoint, drawText, pointMotionState, smooth } from "../marks.js";
+import { styleForSeries } from "../series-style.js";
+
+export function prepareLine(contract) {
+  const points = contract.data.series.flatMap((series, colorIndex) => contract.data.x.map((x, index) => ({ x, y: series.y[index], colorIndex, series: series.key, index })));
+  return { points: arrival(points, contract, contract.data.revealOrder), legend: contract.data.series.map((s, colorIndex) => ({ label: s.label, colorIndex })) };
+}
+
+export function lineSegmentState(left, right, progress, scales, compileDuration = 0.055) {
+  const availableAt = Math.max(left.delay + left.duration, right.delay + right.duration);
+  const compile = smooth(clamp01((progress - availableAt) / compileDuration));
+  const x1 = scales.x(left.x), y1 = scales.y(left.y);
+  const finalX2 = scales.x(right.x), finalY2 = scales.y(right.y);
+  return {
+    visible: compile > 0,
+    compile,
+    x1,
+    y1,
+    x2: x1 + (finalX2 - x1) * compile,
+    y2: y1 + (finalY2 - y1) * compile,
+    finalX2,
+    finalY2,
+    availableAt,
+  };
+}
+
+export function monotoneSegmentControls(points) {
+  if (points.length < 2) return [];
+  const delta = [];
+  for (let index = 0; index < points.length - 1; index += 1) {
+    const width = points[index + 1].x - points[index].x;
+    if (!(width > 0)) return null;
+    delta.push((points[index + 1].y - points[index].y) / width);
+  }
+  const tangent = points.map((_, index) => {
+    if (index === 0) return delta[0];
+    if (index === points.length - 1) return delta[delta.length - 1];
+    return (delta[index - 1] + delta[index]) / 2;
+  });
+  delta.forEach((slope, index) => {
+    if (slope === 0) {
+      tangent[index] = 0;
+      tangent[index + 1] = 0;
+      return;
+    }
+    const left = tangent[index] / slope, right = tangent[index + 1] / slope;
+    const length = left * left + right * right;
+    if (length > 9) {
+      const scale = 3 / Math.sqrt(length);
+      tangent[index] = scale * left * slope;
+      tangent[index + 1] = scale * right * slope;
+    }
+  });
+  return delta.map((_, index) => {
+    const left = points[index], right = points[index + 1], width = right.x - left.x;
+    return {
+      c1: { x: left.x + width / 3, y: left.y + tangent[index] * width / 3 },
+      c2: { x: right.x - width / 3, y: right.y - tangent[index + 1] * width / 3 },
+    };
+  });
+}
+
+function splitCubic(p0, c1, c2, p1, progress) {
+  const mix = (left, right) => ({ x: left.x + (right.x - left.x) * progress, y: left.y + (right.y - left.y) * progress });
+  const a = mix(p0, c1), b = mix(c1, c2), c = mix(c2, p1);
+  const d = mix(a, b), e = mix(b, c);
+  return { c1: a, c2: d, end: mix(d, e) };
+}
+
+function segmentPath(context, segment, controls, scales) {
+  context.beginPath();
+  context.moveTo(segment.x1, segment.y1);
+  if (!controls) {
+    context.lineTo(segment.x2, segment.y2);
+    return;
+  }
+  const p0 = { x: segment.x1, y: segment.y1 };
+  const c1 = { x: scales.x(controls.c1.x), y: scales.y(controls.c1.y) };
+  const c2 = { x: scales.x(controls.c2.x), y: scales.y(controls.c2.y) };
+  const p1 = { x: segment.finalX2, y: segment.finalY2 };
+  const partial = segment.compile < 1 ? splitCubic(p0, c1, c2, p1, segment.compile) : { c1, c2, end: p1 };
+  context.bezierCurveTo(partial.c1.x, partial.c1.y, partial.c2.x, partial.c2.y, partial.end.x, partial.end.y);
+}
+
+export function drawLine(context, env) {
+  const { contract, prepared, layout, progress, settled } = env;
+  const presentation = contract.presentation ?? {};
+  const scales = numericScales(prepared.points, contract.data, layout, { domains: env.domains });
+  drawAxes(context, { config: contract, layout, scales, xTicks: scales.xTicks, yTicks: scales.yTicks });
+  contract.data.series.forEach((series, colorIndex) => {
+    const points = prepared.points.filter((p) => p.colorIndex === colorIndex);
+    const controls = contract.encoding?.interpolation === "monotone" ? monotoneSegmentControls(points) : null;
+    const style = styleForSeries(env, series.key, colorIndex), color = style.color, edge = style.edge;
+    for (let index = 1; index < points.length; index += 1) {
+      const segment = lineSegmentState(points[index - 1], points[index], progress, scales);
+      if (!segment.visible) continue;
+      context.save();
+      if (segment.compile < 1) {
+        context.strokeStyle = contract.theme.summaryCore;
+        context.lineWidth = Math.max(2.2, ((presentation.lineWidth ?? 1) + 3.2) * layout.scale);
+        context.globalAlpha = 0.13 * Math.sin(Math.PI * segment.compile);
+        segmentPath(context, segment, controls?.[index - 1], scales); context.stroke();
+      }
+      if (edge) {
+        context.strokeStyle = edge;
+        context.lineWidth = Math.max(2, ((presentation.lineWidth ?? 1.35) + 1.45) * layout.scale);
+        context.globalAlpha = 0.62 * Math.min(1, segment.compile * 1.6);
+        segmentPath(context, segment, controls?.[index - 1], scales); context.stroke();
+      }
+      context.strokeStyle = color;
+      context.lineWidth = Math.max(1, (style.lineWidth ?? presentation.lineWidth ?? 1.35) * layout.scale);
+      context.setLineDash?.(style.lineStyle === "dash" ? [7, 4] : style.lineStyle === "dot" ? [2, 4] : style.lineStyle === "dash-dot" ? [8, 3, 2, 3] : []);
+      context.globalAlpha = 0.72 * Math.min(1, segment.compile * 1.6);
+      segmentPath(context, segment, controls?.[index - 1], scales); context.stroke();
+      context.restore();
+    }
+  });
+  prepared.points.forEach((point) => {
+    const style = styleForSeries(env, point.series, point.colorIndex), state = pointMotionState(point, progress, scales, layout.plot);
+    if (contract.view?.motion === "semantic") { state.y = state.finalY; state.x = state.finalX; }
+    drawScopePoint(context, state, {
+    color: style.color,
+    edge: style.edge,
+    radius: Math.max(3.4, Math.sqrt(contract.profile.markerSize) * 0.62 * layout.scale) * (presentation.markerScale ?? 1),
+    trailAlpha: contract.motion.trailAlpha,
+    settled: settled || contract.view?.motion === "semantic",
+    shape: style.glyph,
+  }); });
+  const legend = prepared.legend.map((item, index) => ({ ...item, style: styleForSeries(env, contract.data.series[index].key, index) }));
+  drawText(context, { config: contract, layout, legend, legendPosition: presentation.legend ?? "top-right", legendStyle: "line", seriesMarkers: presentation.seriesMarkers ?? [] });
+  return scales;
+}