@figurestead/web 0.9.0-alpha.1

package/src/extensions/temporal/observations.js

@@ -0,0 +1,87 @@
+import { arrival } from "../../renderers/shared.js";
+import { drawScopePoint, drawText, pointMotionState } from "../../marks.js";
+import { drawBand, drawRule } from "../../primitives.js";
+import { contractReferenceBands, drawTemporalAxes, makeTemporalScales, postMarksProgress, temporalXDomain, temporalYDomain } from "./shared.js";
+
+export function prepareObservations(contract) {
+  const bands = contractReferenceBands(contract);
+  const points = contract.data.dates.map((date, index) => ({
+    date, x: Date.parse(`${date}T00:00:00Z`), y: contract.data.values[index], site: contract.data.site, colorIndex: 0, index,
+  }));
+  const arrived = arrival(points, contract, "x");
+  return { points: arrived, bands, settledAt: Math.max(...arrived.map((point) => point.delay + point.duration)) };
+}
+
+export function compileObservationsScene({ panel, contract, prepared, styles, markId, panelIndex, figure }) {
+  const marks = prepared.bands.map((band, index) => ({
+    id: markId(panel, "reference-band", index), kind: "reference-band", role: "context",
+    from: band.from, to: band.to, label: band.label, status: band.status,
+    style: {
+      colorIndex: (index + 1) % contract.theme.series.length,
+      color: contract.theme.series[(index + 1) % contract.theme.series.length],
+      edge: contract.theme.seriesEdges?.[(index + 1) % (contract.theme.seriesEdges?.length || 1)] ?? null,
+      lineStyle: "solid", lineWidth: 1,
+    },
+  }));
+  const pointStyle = styles.series ?? {
+    key: "series", colorIndex: 0, color: contract.theme.series[0],
+    edge: contract.theme.seriesEdges?.[0] ?? null, glyph: "ring", lineStyle: "solid", lineWidth: 1.6,
+  };
+  prepared.points.forEach((point) => marks.push({
+    id: markId(panel, "point", point.date, point.index), kind: "point", series: contract.data.site,
+    x: point.x, y: point.y, date: point.date, style: pointStyle,
+  }));
+  return {
+    marks,
+    categories: { x: null, y: null },
+    legend: [],
+    meta: {
+      showBandKey: !figure.layout.sharedY || panelIndex === 0,
+      provisionalReferenceBands: prepared.bands.length > 0,
+    },
+  };
+}
+
+export function observationDomains(contract, prepared) {
+  return {
+    x: temporalXDomain(contract, prepared.points.map((point) => point.x)),
+    y: temporalYDomain(contract, prepared.points.map((point) => point.y), prepared.bands),
+  };
+}
+
+export function drawObservations(context, env) {
+  const { contract, prepared, layout, progress, settled } = env;
+  const scales = makeTemporalScales(env.domains.x, env.domains.y, layout.plot);
+  const cp = postMarksProgress(progress, prepared, contract.timeline);
+  const panelIndex = env.figure && env.panel ? env.figure.panels.findIndex((panel) => panel.id === env.panel.id) : 0;
+  const columns = Math.max(1, env.figure?.layout.columns ?? 1);
+  const bottomRowStart = env.figure ? Math.floor((env.figure.panels.length - 1) / columns) * columns : 0;
+  const showX = !env.figure?.layout.sharedX || panelIndex >= bottomRowStart;
+  const showBandLabels = !env.figure?.layout.sharedY || panelIndex === 0;
+  prepared.bands.forEach((band, index) => {
+    if (cp <= 0) return;
+    const top = scales.y(band.to), bottom = scales.y(band.from);
+    const color = contract.theme.series[(index + 1) % contract.theme.series.length];
+    drawBand(context, { left: layout.plot.left, right: layout.plot.right, top, bottom, color, alpha: (0.045 + index * 0.04) * cp });
+    if (index > 0) drawRule(context, { x1: layout.plot.left, y1: bottom, x2: layout.plot.right, y2: bottom, color, alpha: 0.48 * cp, width: Math.max(0.7, layout.scale) });
+  });
+  if (showBandLabels && prepared.bands.length && cp > 0) {
+    const available = layout.plot.right - layout.plot.left;
+    context.save(); context.globalAlpha = 0.86 * cp; context.font = `${Math.max(7, layout.font.legend * 0.86)}px ui-monospace, monospace`;
+    context.textAlign = "left"; context.textBaseline = "middle"; let x = layout.plot.left;
+    prepared.bands.forEach((band, index) => {
+      const color = contract.theme.series[(index + 1) % contract.theme.series.length], label = `${band.from}–${band.to}`, swatch = Math.max(10, 13 * layout.scale);
+      context.fillStyle = color; context.globalAlpha = (0.32 + index * 0.15) * cp; context.fillRect(x, layout.plot.top - 14 * layout.scale, swatch, 5 * layout.scale);
+      context.globalAlpha = 0.86 * cp; context.fillStyle = contract.theme.secondary; context.fillText(label, x + swatch + 4 * layout.scale, layout.plot.top - 11 * layout.scale);
+      x += swatch + context.measureText(label).width + 17 * layout.scale;
+    });
+    if (x + 115 * layout.scale < layout.plot.left + available) { context.fillStyle = contract.theme.faint; context.fillText("Reference bands · provisional", x, layout.plot.top - 11 * layout.scale); }
+    context.restore();
+  }
+  drawTemporalAxes(context, { contract, layout, scales, showX });
+  prepared.points.forEach((point) => drawScopePoint(context, pointMotionState(point, progress, scales, layout.plot), {
+    color: contract.theme.series[0], radius: Math.max(3.2, Math.sqrt(contract.profile.markerSize) * 0.58 * layout.scale), trailAlpha: contract.motion.trailAlpha, settled,
+  }));
+  drawText(context, { config: contract, layout, legend: [] });
+  return scales;
+}

package/src/extensions/temporal/shared.js

@@ -0,0 +1,172 @@
+import { FiguresteadConfigError, requiredObject, requiredString, sameLength } from "../../schema.js";
+import { extent, formatTick, formatTimeTick, linearScale, parseTime, ticks, timeScale, timeTicks } from "../../scales.js";
+import { smooth } from "../../marks.js";
+
+export const DAY = 24 * 60 * 60 * 1000;
+export const PROVISIONAL_STATUS = "provisional_project_constant";
+export const PROVISIONAL_LABEL = "Provisional project constant; not a regulatory threshold";
+
+const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/;
+const FONT_STACK = "ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', monospace";
+
+export function normalizeDate(value, path) {
+  if (typeof value !== "string" || !DATE_ONLY.test(value)) {
+    throw new FiguresteadConfigError("must be a UTC date in YYYY-MM-DD form", path);
+  }
+  const milliseconds = Date.parse(`${value}T00:00:00Z`);
+  if (!Number.isFinite(milliseconds) || new Date(milliseconds).toISOString().slice(0, 10) !== value) {
+    throw new FiguresteadConfigError("must be a valid calendar date", path);
+  }
+  return value;
+}
+
+export function normalizeDates(value, path) {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new FiguresteadConfigError("must be a non-empty date array", path);
+  }
+  return value.map((item, index) => normalizeDate(item, `${path}[${index}]`));
+}
+
+export function normalizeSiteOrder(value, path) {
+  if (!Array.isArray(value) || value.length === 0) {
+    throw new FiguresteadConfigError("must be a non-empty site-order array", path);
+  }
+  const sites = value.map((item, index) => {
+    requiredString(item, `${path}[${index}]`);
+    return item;
+  });
+  if (new Set(sites).size !== sites.length) throw new FiguresteadConfigError("must contain unique sites", path);
+  return sites;
+}
+
+export function validateCoverageData(data, path = "config.data") {
+  requiredObject(data, path);
+  const dates = normalizeDates(data.dates, `${path}.dates`);
+  sameLength(data.sites, dates.length, `${path}.sites`);
+  const sites = data.sites.map((site, index) => {
+    requiredString(site, `${path}.sites[${index}]`);
+    return site;
+  });
+  const siteOrder = normalizeSiteOrder(data.siteOrder, `${path}.siteOrder`);
+  sites.forEach((site, index) => {
+    if (!siteOrder.includes(site)) throw new FiguresteadConfigError(`unknown site ${JSON.stringify(site)}`, `${path}.sites[${index}]`);
+  });
+  return { dates, sites, siteOrder };
+}
+
+export function validateObservationData(data, path = "config.data") {
+  requiredObject(data, path);
+  const dates = normalizeDates(data.dates, `${path}.dates`);
+  if (!Array.isArray(data.values) || data.values.length !== dates.length) {
+    throw new FiguresteadConfigError(`must contain exactly ${dates.length} items`, `${path}.values`);
+  }
+  const values = data.values.map((value, index) => {
+    if (typeof value !== "number" || !Number.isFinite(value)) throw new FiguresteadConfigError("must be a finite number", `${path}.values[${index}]`);
+    return value;
+  });
+  requiredString(data.site, `${path}.site`);
+  const referenceBands = normalizeReferenceBands(data.referenceBands ?? [], `${path}.referenceBands`);
+  return { dates, values, site: data.site, referenceBands };
+}
+
+export function normalizeReferenceBands(annotations, path = "config.annotations") {
+  if (!Array.isArray(annotations)) throw new FiguresteadConfigError("must be an array", path);
+  const bands = annotations.map((annotation, index) => {
+    const itemPath = `${path}[${index}]`;
+    requiredObject(annotation, itemPath);
+    if (annotation.type !== "reference_band") throw new FiguresteadConfigError("type must be reference_band", `${itemPath}.type`);
+    for (const key of ["from", "to"]) {
+      if (typeof annotation[key] !== "number" || !Number.isFinite(annotation[key])) throw new FiguresteadConfigError("must be a finite number", `${itemPath}.${key}`);
+    }
+    if (annotation.from >= annotation.to) throw new FiguresteadConfigError("from must be less than to", itemPath);
+    requiredString(annotation.label, `${itemPath}.label`);
+    if (annotation.status !== PROVISIONAL_STATUS) {
+      throw new FiguresteadConfigError(`must be ${JSON.stringify(PROVISIONAL_STATUS)}`, `${itemPath}.status`);
+    }
+    return { type: "reference_band", from: annotation.from, to: annotation.to, label: annotation.label, status: PROVISIONAL_STATUS };
+  });
+  bands.forEach((band, index) => {
+    if (index && band.from < bands[index - 1].to) throw new FiguresteadConfigError("reference bands must be ordered and non-overlapping", `${path}[${index}]`);
+  });
+  return bands;
+}
+
+export function contractReferenceBands(contract) {
+  const dataBands = normalizeReferenceBands(contract.data.referenceBands ?? [], "config.data.referenceBands");
+  if (!Array.isArray(contract.annotations) || contract.annotations.length === 0) return dataBands;
+  const annotationBands = normalizeReferenceBands(contract.annotations, "config.annotations");
+  if (JSON.stringify(annotationBands) !== JSON.stringify(dataBands)) {
+    throw new FiguresteadConfigError("must exactly match config.data.referenceBands so drawing and accessibility agree", "config.annotations");
+  }
+  return dataBands;
+}
+
+export function temporalXDomain(contract, milliseconds) {
+  if (contract.xScale?.domain) return contract.xScale.domain.map((value, index) => parseTime(value, `config.xScale.domain[${index}]`));
+  const low = Math.min(...milliseconds), high = Math.max(...milliseconds);
+  if (low === high) return [low - DAY, high + DAY];
+  const padding = Math.max(DAY, (high - low) * 0.025);
+  return [low - padding, high + padding];
+}
+
+export function temporalYDomain(contract, values, bands = []) {
+  if (contract.yScale?.domain) return [...contract.yScale.domain];
+  return extent([...values, ...bands.flatMap((band) => [band.from, band.to])]);
+}
+
+export function makeTemporalScales(xDomain, yDomain, plot) {
+  return {
+    x: timeScale(xDomain, [plot.left, plot.right]),
+    y: linearScale(yDomain, [plot.bottom, plot.top]),
+    xDomain,
+    yDomain,
+    xTicks: timeTicks(xDomain, 6),
+    yTicks: ticks(yDomain, 5),
+  };
+}
+
+export function postMarksProgress(progress, prepared, timeline) {
+  const settledAt = prepared.settledAt ?? 0;
+  if (progress <= settledAt) return 0;
+  const end = Math.max(settledAt + 1e-6, timeline.summaryCompiles[1]);
+  return smooth((progress - settledAt) / (end - settledAt));
+}
+
+export function drawTemporalAxes(context, { contract, layout, scales, plot = layout.plot, yLabels = null, showX = true, showY = true }) {
+  context.save();
+  context.lineWidth = Math.max(0.5, 0.6 * layout.scale);
+  context.strokeStyle = contract.theme.grid;
+  if (contract.profile.gridY) {
+    context.globalAlpha = contract.profile.gridAlpha;
+    (yLabels ? yLabels.map((_, index) => index) : scales.yTicks).forEach((value) => {
+      const y = scales.y(value); context.beginPath(); context.moveTo(plot.left, y); context.lineTo(plot.right, y); context.stroke();
+    });
+  }
+  if (contract.profile.gridX) {
+    context.globalAlpha = contract.profile.gridAlpha * 0.55;
+    scales.xTicks.forEach((value) => { const x = scales.x(value); context.beginPath(); context.moveTo(x, plot.top); context.lineTo(x, plot.bottom); context.stroke(); });
+  }
+  context.globalAlpha = 1; context.strokeStyle = contract.theme.spine; context.lineWidth = Math.max(0.7, 0.9 * layout.scale);
+  context.beginPath(); context.moveTo(plot.left, plot.top); context.lineTo(plot.left, plot.bottom); context.lineTo(plot.right, plot.bottom); context.stroke();
+  context.fillStyle = contract.theme.secondary; context.font = `${layout.font.axis}px ${FONT_STACK}`;
+  if (showX) {
+    context.textAlign = "center"; context.textBaseline = "top";
+    scales.xTicks.forEach((value) => context.fillText(formatTimeTick(value, scales.xDomain), scales.x(value), plot.bottom + 9 * layout.scale));
+  }
+  if (showY) {
+    context.textAlign = "right"; context.textBaseline = "middle";
+    if (yLabels) yLabels.forEach((label, index) => context.fillText(label, plot.left - 9 * layout.scale, scales.y(index), Math.max(30, plot.left - 14 * layout.scale)));
+    else scales.yTicks.forEach((value) => context.fillText(formatTick(value), plot.left - 9 * layout.scale, scales.y(value)));
+  }
+  if (showX && contract.spec.xLabel) {
+    context.textAlign = "center"; context.textBaseline = "bottom"; context.fillStyle = contract.theme.label;
+    context.fillText(contract.spec.xLabel, (plot.left + plot.right) / 2, layout.text?.xLabelY ?? layout.height - 9 * layout.scale);
+  }
+  if (contract.spec.yLabel) {
+    context.save(); context.translate(layout.text?.yLabelX ?? 18 * layout.scale, (plot.top + plot.bottom) / 2); context.rotate(-Math.PI / 2);
+    context.textAlign = "center"; context.textBaseline = "middle"; context.fillStyle = contract.theme.label; context.fillText(contract.spec.yLabel, 0, 0); context.restore();
+  }
+  context.restore();
+}
+
+export function yearStart(year) { return Date.parse(`${year}-01-01T00:00:00Z`); }

package/src/figure-layout.js

@@ -0,0 +1,70 @@
+import { deriveLayout } from "./layout.js";
+
+const clamp = (value, minimum, maximum) => Math.max(minimum, Math.min(maximum, value));
+
+const MINIMUM_PLOT_WIDTH = 160;
+const MINIMUM_PLOT_HEIGHT = 120;
+
+function deriveMultiPanelLayout(width, height, contract, columns, scale, outer, headerHeight, narrow, provenanceHeight) {
+  const rows = Math.ceil(contract.panels.length / columns);
+  const gap = clamp(contract.layout.gap * scale, narrow ? 8 : 10, narrow ? 20 : 38);
+  const contentTop = headerHeight;
+  const contentBottom = height - clamp(18 * scale, 10, 24) - provenanceHeight;
+  const availableWidth = width - outer * 2 - gap * (columns - 1);
+  const availableHeight = contentBottom - contentTop - gap * (rows - 1);
+  const cellWidth = availableWidth / columns;
+  const cellHeight = availableHeight / rows;
+  const panels = contract.panels.map((_, index) => {
+    const column = index % columns, row = Math.floor(index / columns);
+    const rect = {
+      left: outer + column * (cellWidth + gap),
+      top: contentTop + row * (cellHeight + gap),
+      right: outer + column * (cellWidth + gap) + cellWidth,
+      bottom: contentTop + row * (cellHeight + gap) + cellHeight,
+    };
+    const leftPad = clamp(cellWidth * 0.105, 48, 82), rightPad = clamp(cellWidth * 0.035, 16, 34);
+    const topPad = clamp(cellHeight * 0.16, 42, 68), bottomPad = clamp(cellHeight * 0.15, 42, 68);
+    return {
+      width, height, scale, rect, panelIndex: index,
+      plot: { left: rect.left + leftPad, right: rect.right - rightPad, top: rect.top + topPad, bottom: rect.bottom - bottomPad },
+      text: { titleY: rect.top + clamp(19 * scale, 14, 24), subtitleY: rect.top + clamp(37 * scale, 28, 46), xLabelY: rect.bottom - 7 * scale, yLabelX: rect.left + 12 * scale },
+      font: { title: clamp(14 * scale, 11, 17), subtitle: clamp(10 * scale, 8, 12), axis: clamp(10.5 * scale, narrow ? 10 : 8, 12), legend: clamp(9.5 * scale, narrow ? 9.5 : 8, 11), signature: clamp(8.5 * scale, narrow ? 8 : 7, 10) },
+      provenance: provenanceHeight ? { left: outer, right: width - outer, y: height - clamp(8 * scale, 7, 12) } : null,
+    };
+  });
+  return {
+    width, height, scale, panels,
+    plot: { left: outer, right: width - outer, top: contentTop, bottom: contentBottom },
+    header: { left: outer, titleY: clamp(30 * scale, 22, 38), subtitleY: clamp(53 * scale, 42, 66) },
+    font: { title: clamp(19 * scale, 14, 23), subtitle: clamp(11.5 * scale, 9, 14), axis: clamp(10.5 * scale, narrow ? 10 : 8, 12), legend: clamp(10 * scale, narrow ? 9.5 : 8, 12), signature: clamp(9 * scale, narrow ? 8 : 7, 10) },
+    provenance: provenanceHeight ? { left: outer, right: width - outer, y: height - clamp(8 * scale, 7, 12) } : null,
+  };
+}
+
+function hasSafePanelPlots(layout) {
+  return layout.panels.every((panel) =>
+    panel.plot.right - panel.plot.left >= MINIMUM_PLOT_WIDTH
+    && panel.plot.bottom - panel.plot.top >= MINIMUM_PLOT_HEIGHT);
+}
+
+export function deriveFigureLayout(width, height, contract) {
+  if (!contract || contract.panels.length === 1) {
+    const single = deriveLayout(width, height);
+    single.panels = [{ ...single, rect: { left: 0, top: 0, right: width, bottom: height }, panelIndex: 0 }];
+    single.header = null;
+    return single;
+  }
+  const scale = clamp(Math.min(width / 1160, height / 700), 0.55, 1.35);
+  const narrow = width <= 480 && height >= width * 1.5;
+  const outer = clamp(width * 0.035, 16, 42);
+  const headerHeight = narrow ? clamp(height * 0.085, 52, 68) : clamp(height * 0.13, 70, 108);
+  const provenanceHeight = contract.theme?.mode === "paper" || !contract.spec?.signature ? 0 : clamp(18 * scale, 14, 22);
+  const requestedColumns = Math.min(contract.layout.columns, contract.panels.length);
+  const legacyLayout = deriveMultiPanelLayout(width, height, contract, requestedColumns, scale, outer, headerHeight, narrow, provenanceHeight);
+  if (hasSafePanelPlots(legacyLayout)) return legacyLayout;
+  for (let columns = requestedColumns - 1; columns >= 1; columns -= 1) {
+    const candidate = deriveMultiPanelLayout(width, height, contract, columns, scale, outer, headerHeight, narrow, provenanceHeight);
+    if (hasSafePanelPlots(candidate)) return candidate;
+  }
+  return legacyLayout;
+}

package/src/figure.js

@@ -0,0 +1,42 @@
+export function panelContract(figure, panel) {
+  return {
+    schemaVersion: figure.schemaVersion,
+    rendererApiVersion: figure.rendererApiVersion,
+    theme: figure.theme,
+    profile: figure.profile,
+    timeline: figure.timeline,
+    motion: figure.motion,
+    view: figure.view,
+    style: figure.style,
+    applicationProfile: figure.applicationProfile,
+    seriesStyles: figure.seriesStyles,
+    renderer: panel.renderer,
+    spec: {
+      ...figure.spec,
+      ...panel.spec,
+      title: panel.spec.title || figure.spec.title,
+      subtitle: panel.spec.subtitle || (figure.panels.length === 1 ? figure.spec.subtitle : ""),
+      xLabel: panel.spec.xLabel || panel.xScale?.label || figure.spec.xLabel,
+      yLabel: panel.spec.yLabel || panel.yScale?.label || figure.spec.yLabel,
+    },
+    data: panel.data,
+    xScale: panel.xScale,
+    yScale: panel.yScale,
+    annotations: panel.annotations,
+    presentation: panel.presentation ?? null,
+    encoding: panel.encoding ?? { interpolation: panel.presentation?.curve ?? "linear" },
+  };
+}
+
+export function unionDomains(domains) {
+  const present = domains.filter((value) => Array.isArray(value) && value.length === 2 && value.every(Number.isFinite));
+  if (!present.length) return null;
+  return [Math.min(...present.map((value) => value[0])), Math.max(...present.map((value) => value[1]))];
+}
+
+export function resolvePanelDomains(figure, preparedPanels) {
+  const raw = preparedPanels.map(({ definition, contract, prepared }) => definition.domains(contract, prepared) || {});
+  const sharedX = figure.layout.sharedX ? unionDomains(raw.map((value) => value.x)) : null;
+  const sharedY = figure.layout.sharedY ? unionDomains(raw.map((value) => value.y)) : null;
+  return raw.map((value) => ({ ...value, x: sharedX || value.x, y: sharedY || value.y }));
+}

package/src/index.js

@@ -0,0 +1,30 @@
+export { createFigurestead } from "./create-matrix-plot.js";
+export { validateContract, FiguresteadConfigError, SCHEMA_VERSION, LEGACY_SCHEMA_VERSION } from "./schema.js";
+export { CORE_REGISTRY, CORE_RENDERERS } from "./core-renderers.js";
+export { createRendererRegistry, defineRenderer, RENDERER_API_VERSION } from "./registry.js";
+export { deriveFigureLayout } from "./figure-layout.js";
+export { linearScale, timeScale, bandScale, parseTime, timeTicks, formatTimeTick } from "./scales.js";
+export { drawRule, drawBand, drawBar, drawInterval, drawCell } from "./primitives.js";
+export { rendererConformance, assertRendererConformance } from "./renderer-test-kit.js";
+export { prepareLine, lineSegmentState } from "./renderers/line.js";
+export { SCIENTIFIC_POSE, applyEvidencePose, applyScientificPose } from "./presentation.js";
+export { APPLICATION_PROFILE_VERSION, APPLICATION_PROFILES, applyApplicationProfile, resolveApplicationProfile } from "./application-profiles.js";
+export { APPEARANCE_VERSION, composeAppearance } from "./appearance.js";
+export { SERIES_STYLE_VERSION, GLYPH_CYCLE, LINE_STYLE_CYCLE, HATCH_CYCLE, collectSeriesKeys, resolveSeriesStyles, styleForSeries } from "./series-style.js";
+export { TERMINAL_SCENE_VERSION, canonicalTerminalEvidence, compileFigureModel, compileTerminalScene, evidenceFingerprint, terminalEvidence } from "./terminal-scene.js";
+export { RESOLVED_SCENE_VERSION, RESOLVED_RENDERERS, isResolvedRenderer, resolveSceneFrame, resolveTerminalScene, resolvedTerminalGeometry } from "./resolved-scene.js";
+export { COMPOSED_SCENE_VERSION, auditComposition, composeResolvedScene } from "./composition.js";
+export { MOTION_PLAN_VERSION, ALLOWED_MOTION_CHANNELS, TERMINAL_MOTION_STATE, assertTerminalMotionIdentity, compileMotionPlan, markMotionState, strategyForRenderer } from "./motion-plan.js";
+export { exportFigureSvg, resolvedSceneToSvg, sceneToSvg } from "./svg-export.js";
+export { EXPORT_MANIFEST_VERSION, FIGURESTEAD_PACKAGE_VERSION, canvasToPngBlob, exportFigureArtifacts, stableStringify } from "./export-bundle.js";
+export { MOTION_RECIPE_VERSION, MOTION_RECIPES, applyMotionRecipe, resolveMotionRecipe } from "./motion-recipes.js";
+export { THEME_CATALOG_VERSION, auditThemeCatalog, catalogThemePack, mergeThemePacks } from "./theme-catalog.js";
+export { prepareScatter } from "./renderers/scatter.js";
+export { prepareStrip } from "./renderers/strip-summary.js";
+export { AnimationClock } from "./clock.js";
+export { THEME_PACK_VERSION, PALETTE_PACK_VERSION, applyTheme, contrastAudit, contrastRatio, loadThemePack, normalizeThemePackLenient, resolveTheme, resolvePalette, themeForProfile, validateAuthoredThemePack, validateThemePack, validatePalettePack } from "./theme-pack.js";
+export { RENDER_LAYER_ORDER, partitionPanelMarks, plotClipRect, renderLayerForMark, withCanvasPlotClip } from "./render-layers.js";
+export { validateEvidenceCoverage } from "./evidence-coverage.js";
+export { colorContrast, hexToOklab, hexToOklch, oklabDistance, oklchToHex, resolveContrastColor } from "./color-space.js";
+export { PAPER_FLOORS, PAPER_PROFILE_VERSION, PAPER_SURFACE, auditPaperTheme, resolvePaperTheme, themeResolutionForProfile } from "./paper-profile.js";
+export { PAPER_SIZE_PRESETS, auditPhysicalTypography, resolveExportSize } from "./physical-export.js";

package/src/layout.js

@@ -0,0 +1,41 @@
+const clamp = (value, minimum, maximum) => Math.max(minimum, Math.min(maximum, value));
+
+export const MIN_CANVAS_WIDTH = 320;
+export const MIN_CANVAS_HEIGHT = 240;
+
+export function deriveLayout(width, height) {
+  const scale = clamp(Math.min(width / 1160, height / 700), 0.55, 1.35);
+  const narrow = width <= 480;
+  const left = clamp(width * 0.083, 54, 100);
+  const right = clamp(width * 0.035, 22, 44);
+  const top = clamp(height * 0.154, 72, 112);
+  const bottom = clamp(height * 0.137, 58, 98);
+  return {
+    width,
+    height,
+    scale,
+    plot: { left, right: width - right, top, bottom: height - bottom },
+    font: {
+      title: clamp(19 * scale, 13, 22),
+      subtitle: clamp(12.5 * scale, 9, 14),
+      axis: clamp(12 * scale, narrow ? 10 : 9, 13),
+      legend: clamp(11.5 * scale, narrow ? 9.5 : 8.5, 13),
+      signature: clamp(10 * scale, narrow ? 8 : 7.5, 11),
+    },
+    provenance: { left, right: width - right, y: height - clamp(12 * scale, 10, 16) },
+  };
+}
+
+export function resizeCanvas(canvas, { dprCap = 2, layoutFactory = deriveLayout } = {}) {
+  const rect = canvas.getBoundingClientRect();
+  const width = Math.max(1, rect.width || canvas.clientWidth || MIN_CANVAS_WIDTH);
+  const height = Math.max(1, rect.height || canvas.clientHeight || width * 700 / 1160);
+  const dpr = Math.min(dprCap, globalThis.devicePixelRatio || 1);
+  const backingWidth = Math.max(1, Math.round(width * dpr));
+  const backingHeight = Math.max(1, Math.round(height * dpr));
+  if (canvas.width !== backingWidth) canvas.width = backingWidth;
+  if (canvas.height !== backingHeight) canvas.height = backingHeight;
+  const context = canvas.getContext("2d");
+  context.setTransform(dpr, 0, 0, dpr, 0, 0);
+  return { context, layout: layoutFactory(width, height), dpr };
+}

package/src/marks.js

@@ -0,0 +1,218 @@
+import { formatTick } from "./scales.js";
+import { windowProgress } from "./schema.js";
+
+export const clamp01 = (value) => Math.max(0, Math.min(1, value));
+export const smooth = (value) => {
+  const x = clamp01(value);
+  return x * x * (3 - 2 * x);
+};
+export const easeOut = (value) => 1 - (1 - clamp01(value)) ** 3;
+
+const FONT_STACK = "ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', monospace";
+
+export function compileProgress(progress, timeline) {
+  return smooth(windowProgress(progress, timeline.summaryCompiles));
+}
+
+export function pointMotionState(point, progress, scales, plot) {
+  const local = clamp01((progress - point.delay) / point.duration);
+  if (local >= 1) {
+    const finalX = scales.x(point.x), finalY = scales.y(point.y);
+    return { x: finalX, y: finalY, finalX, finalY, local: 1, eased: 1, visibility: 1 };
+  }
+  const eased = easeOut(local);
+  const finalX = scales.x(point.x);
+  const finalY = scales.y(point.y);
+  const startY = plot.top - point.startOffset * (plot.bottom - plot.top) * 0.35;
+  return {
+    x: finalX,
+    y: startY + (finalY - startY) * eased,
+    finalX,
+    finalY,
+    local,
+    eased,
+    visibility: smooth(clamp01(local / 0.15)),
+  };
+}
+
+function markerPath(context, x, y, radius, shape) {
+  context.beginPath();
+  if (shape === "square") context.rect(x - radius * 0.72, y - radius * 0.72, radius * 1.44, radius * 1.44);
+  else if (shape === "triangle") { context.moveTo(x, y - radius); context.lineTo(x + radius * 0.9, y + radius * 0.72); context.lineTo(x - radius * 0.9, y + radius * 0.72); context.closePath(); }
+  else if (shape === "diamond") { context.moveTo(x, y - radius); context.lineTo(x + radius, y); context.lineTo(x, y + radius); context.lineTo(x - radius, y); context.closePath(); }
+  else context.arc(x, y, radius, 0, Math.PI * 2);
+}
+
+export function drawScopePoint(context, state, { color, edge = null, radius, trailAlpha, settled, shape = "ring" }) {
+  if (state.visibility <= 0) return;
+  if (!settled) {
+    const trailLength = (0.05 + 0.34 * (1 - state.eased)) * radius * 12;
+    context.globalAlpha = trailAlpha * state.visibility * (1 - state.eased);
+    context.strokeStyle = color;
+    context.lineWidth = Math.max(0.6, radius * 0.13);
+    context.beginPath();
+    context.moveTo(state.x, state.y - 2);
+    context.lineTo(state.x, state.y - 2 - trailLength);
+    context.stroke();
+  }
+  context.globalAlpha = 0.065 * state.visibility * (0.4 + 0.6 * (1 - state.eased));
+  context.strokeStyle = color;
+  context.lineWidth = Math.max(1.5, radius * 0.3);
+  markerPath(context, state.x, state.y, radius * 1.7, shape);
+  context.stroke();
+  context.globalAlpha = 0.8 * state.visibility;
+  if (edge) {
+    context.strokeStyle = edge;
+    context.lineWidth = Math.max(1.5, radius * 0.34);
+    markerPath(context, state.x, state.y, radius, shape);
+    context.stroke();
+  }
+  context.strokeStyle = color;
+  context.lineWidth = Math.max(0.8, radius * 0.16);
+  markerPath(context, state.x, state.y, radius, shape);
+  context.stroke();
+  context.globalAlpha = 0.46 * state.visibility;
+  context.fillStyle = color;
+  markerPath(context, state.x, state.y, radius * 0.28, shape);
+  context.fill();
+  context.globalAlpha = 1;
+}
+
+export function drawAxes(context, { config, layout, scales, xTicks, yTicks, xCategories = null }) {
+  const { theme, profile, spec } = config;
+  const { plot, font } = layout;
+  context.save();
+  context.lineWidth = Math.max(0.5, 0.6 * layout.scale);
+  if (profile.gridY) {
+    context.strokeStyle = theme.grid;
+    context.globalAlpha = profile.gridAlpha;
+    yTicks.forEach((value) => {
+      const y = scales.y(value);
+      context.beginPath(); context.moveTo(plot.left, y); context.lineTo(plot.right, y); context.stroke();
+    });
+  }
+  if (profile.gridX) {
+    context.strokeStyle = theme.grid;
+    context.globalAlpha = profile.gridAlpha * 0.55;
+    xTicks.forEach((value) => {
+      const x = scales.x(value);
+      context.beginPath(); context.moveTo(x, plot.top); context.lineTo(x, plot.bottom); context.stroke();
+    });
+  }
+  context.globalAlpha = 1;
+  context.strokeStyle = theme.spine;
+  context.lineWidth = Math.max(0.7, 0.9 * layout.scale);
+  context.beginPath();
+  context.moveTo(plot.left, plot.top);
+  context.lineTo(plot.left, plot.bottom);
+  context.lineTo(plot.right, plot.bottom);
+  context.stroke();
+
+  context.fillStyle = theme.secondary;
+  context.font = `${font.axis}px ${FONT_STACK}`;
+  context.textAlign = "right";
+  context.textBaseline = "middle";
+  yTicks.forEach((value) => context.fillText(formatTick(value), plot.left - 9 * layout.scale, scales.y(value)));
+  context.textAlign = "center";
+  context.textBaseline = "top";
+  if (xCategories) {
+    xCategories.forEach((label, index) => context.fillText(label, scales.x(index), plot.bottom + 10 * layout.scale));
+  } else {
+    xTicks.forEach((value) => context.fillText(formatTick(value), scales.x(value), plot.bottom + 10 * layout.scale));
+  }
+
+  if (spec.xLabel) {
+    context.fillStyle = theme.label;
+    context.textBaseline = "bottom";
+    context.fillText(spec.xLabel, (plot.left + plot.right) / 2, layout.text?.xLabelY ?? layout.height - 9 * layout.scale);
+  }
+  if (spec.yLabel) {
+    context.save();
+    context.translate(layout.text?.yLabelX ?? 18 * layout.scale, (plot.top + plot.bottom) / 2);
+    context.rotate(-Math.PI / 2);
+    context.fillStyle = theme.label;
+    context.textBaseline = "middle";
+    context.fillText(spec.yLabel, 0, 0);
+    context.restore();
+  }
+  context.restore();
+}
+
+export function drawText(context, { config, layout, legend, legendPosition = "top-right", legendStyle = "point", seriesMarkers = [] }) {
+  const { theme, spec } = config;
+  const { plot, font } = layout;
+  context.save();
+  context.textAlign = "left";
+  context.textBaseline = "alphabetic";
+  context.fillStyle = theme.primary;
+  context.font = `500 ${font.title}px ${FONT_STACK}`;
+  if (theme.primaryEdge) {
+    context.strokeStyle = theme.primaryEdge;
+    context.lineWidth = Math.max(1, 1.5 * layout.scale);
+    context.strokeText(spec.title, plot.left, layout.text?.titleY ?? Math.max(font.title + 8, plot.top * 0.52));
+  }
+  context.fillText(spec.title, plot.left, layout.text?.titleY ?? Math.max(font.title + 8, plot.top * 0.52));
+  if (spec.subtitle) {
+    context.fillStyle = theme.secondary;
+    context.font = `italic ${font.subtitle}px ${FONT_STACK}`;
+    context.fillText(spec.subtitle, plot.left, layout.text?.subtitleY ?? Math.max(font.title + font.subtitle + 14, plot.top * 0.73));
+  }
+  context.fillStyle = theme.faint;
+  context.font = `${font.signature}px ${FONT_STACK}`;
+  const signatureLeft = legendPosition === "bottom-right";
+  context.textAlign = signatureLeft ? "left" : "right";
+  context.fillText(spec.signature, signatureLeft ? plot.left + 5 : plot.right - 5, plot.bottom - 8 * layout.scale);
+
+  context.font = `${font.legend}px ${FONT_STACK}`;
+  context.textBaseline = "middle";
+  if (legendPosition === "none") { context.restore(); return; }
+  legend.forEach((item, index) => {
+    const bottom = legendPosition.startsWith("bottom");
+    const left = legendPosition.endsWith("left");
+    const y = bottom
+      ? plot.bottom - (legend.length - index) * 20 * layout.scale
+      : plot.top + 14 * layout.scale + index * 20 * layout.scale;
+    const color = item.style?.color ?? theme.series[item.colorIndex % theme.series.length];
+    const edge = item.style?.edge ?? theme.seriesEdges?.[item.colorIndex % theme.series.length] ?? null;
+    const shape = item.style?.glyph ?? seriesMarkers[item.colorIndex % Math.max(1, seriesMarkers.length)] ?? "ring";
+    if (left) {
+      const x = plot.left + 14 * layout.scale;
+      if (legendStyle === "line") {
+        if (edge) { context.strokeStyle = edge; context.lineWidth = Math.max(2, 2.8 * layout.scale); context.beginPath(); context.moveTo(x - 3 * layout.scale, y); context.lineTo(x + 27 * layout.scale, y); context.stroke(); }
+        context.strokeStyle = color; context.lineWidth = Math.max(1.2, 1.65 * layout.scale); context.beginPath(); context.moveTo(x - 3 * layout.scale, y); context.lineTo(x + 27 * layout.scale, y); context.stroke();
+        markerPath(context, x + 12 * layout.scale, y, 4 * layout.scale, shape); context.stroke();
+      } else { context.strokeStyle = color; context.lineWidth = Math.max(0.8, 1.15 * layout.scale); markerPath(context, x, y, 5 * layout.scale, shape); context.stroke(); }
+      context.textAlign = "left"; context.fillStyle = theme.label;
+      context.fillText(item.label, x + (legendStyle === "line" ? 38 : 14) * layout.scale, y);
+    } else {
+      const tx = plot.right - 14 * layout.scale;
+      context.textAlign = "right"; context.fillStyle = theme.label;
+      context.fillText(item.label, tx, y);
+      const width = context.measureText(item.label).width;
+      const x = tx - width - 15 * layout.scale;
+      if (legendStyle === "line") {
+        if (edge) { context.strokeStyle = edge; context.lineWidth = Math.max(2, 2.8 * layout.scale); context.beginPath(); context.moveTo(x - 27 * layout.scale, y); context.lineTo(x + 3 * layout.scale, y); context.stroke(); }
+        context.strokeStyle = color; context.lineWidth = Math.max(1.2, 1.65 * layout.scale); context.beginPath(); context.moveTo(x - 27 * layout.scale, y); context.lineTo(x + 3 * layout.scale, y); context.stroke();
+        markerPath(context, x - 12 * layout.scale, y, 4 * layout.scale, shape); context.stroke();
+      } else { context.strokeStyle = color; context.lineWidth = Math.max(0.8, 1.15 * layout.scale); markerPath(context, x, y, 5 * layout.scale, shape); context.stroke(); }
+    }
+  });
+  context.restore();
+}
+
+export function drawFigureHeader(context, { config, layout }) {
+  if (!layout.header) return;
+  const fontStack = "ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', monospace";
+  context.save(); context.textAlign = "left"; context.textBaseline = "alphabetic";
+  context.fillStyle = config.theme.primary; context.font = `500 ${layout.font.title}px ${fontStack}`;
+  if (config.theme.primaryEdge) { context.strokeStyle = config.theme.primaryEdge; context.lineWidth = Math.max(1, 1.5 * layout.scale); context.strokeText(config.spec.title, layout.header.left, layout.header.titleY); }
+  context.fillText(config.spec.title, layout.header.left, layout.header.titleY);
+  if (config.spec.subtitle) { context.fillStyle = config.theme.secondary; context.font = `italic ${layout.font.subtitle}px ${fontStack}`; context.fillText(config.spec.subtitle, layout.header.left, layout.header.subtitleY); }
+  context.restore();
+}
+
+export function drawBackground(context, layout, theme) {
+  context.clearRect(0, 0, layout.width, layout.height);
+  context.fillStyle = theme.field;
+  context.fillRect(0, 0, layout.width, layout.height);
+}