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

package/src/resolved-scene.js

@@ -1,4 +1,7 @@
+import { planDirectLabels } from "./direct-labels.js";
+import { lineMarkerGeometry } from "./line-identity.js";
 import { deriveFigureLayout } from "./figure-layout.js";
+import { refineScientificLayout } from "./scientific-layout.js";
 import { markMotionState } from "./motion-plan.js";
 import { monotoneSegmentControls } from "./renderers/line.js";
 import { bandScale, formatTick, formatTimeTick, linearScale, timeScale, ticks, timeTicks } from "./scales.js";
@@ -54,6 +57,18 @@ function panelLayout(source, panel) {
   return layout;
 }
 
+function preparedPanelLayout(source) {
+  return {
+    ...source,
+    rect: source.rect ? cloneRect(source.rect) : { left: 0, top: 0, right: source.width, bottom: source.height },
+    plot: cloneRect(source.plot),
+    text: source.text ? { ...source.text } : null,
+    font: { ...source.font },
+    provenance: source.provenance ? { ...source.provenance } : null,
+    legend: source.legend ? { ...source.legend } : null,
+  };
+}
+
 function numericScale(type, domain, range) {
   return type === "time" ? timeScale(domain, range) : linearScale(domain, range);
 }
@@ -81,7 +96,7 @@ function pointGeometry(mark, axes, radius) {
   return { cx, cy, radius };
 }
 
-function lineGeometry(panel, axes, radius) {
+function lineGeometry(panel, axes, scale) {
   const controls = new Map();
   const series = [...new Set(panel.marks.filter((mark) => mark.kind === "point").map((mark) => mark.series))];
   series.forEach((key) => {
@@ -91,7 +106,10 @@ function lineGeometry(panel, axes, radius) {
   });
   const segmentIndex = new Map();
   return panel.marks.map((mark) => {
-    if (mark.kind === "point") return { ...mark, geometry: pointGeometry(mark, axes, radius) };
+    if (mark.kind === "point") {
+      const marker = lineMarkerGeometry(mark.style, scale, panel.presentation?.markerScale ?? 1);
+      return { ...mark, lineIdentity: true, geometry: { ...pointGeometry(mark, axes, marker.radius), outlineWidth: marker.outlineWidth } };
+    }
     if (mark.kind !== "segment") return { ...mark };
     const index = segmentIndex.get(mark.series) ?? 0; segmentIndex.set(mark.series, index + 1);
     const control = controls.get(`${mark.series}\u0000${index}`);
@@ -113,6 +131,28 @@ function scatterGeometry(panel, axes, radius) {
   });
 }
 
+function fallbackPointGeometry(panel, axes, radius) {
+  return panel.marks.map((mark) => {
+    if (mark.kind === "point") return { ...mark, geometry: pointGeometry(mark, axes, radius) };
+    if (mark.kind !== "renderer-mark") return { ...mark, geometry: null };
+    const evidence = mark.evidence ?? {};
+    const hasX = evidence.x != null || (evidence.group != null && axes.x.bandwidth);
+    const hasY = evidence.y != null || (evidence.yCategory != null && axes.y.bandwidth);
+    if (!hasX || !hasY) return { ...mark, geometry: null };
+    const candidate = {
+      x: evidence.x,
+      y: evidence.y,
+      group: evidence.group,
+      yCategory: evidence.yCategory,
+      xOffset: evidence.xOffset,
+    };
+    const geometry = pointGeometry(candidate, axes, radius);
+    return Number.isFinite(geometry.cx) && Number.isFinite(geometry.cy)
+      ? { ...mark, geometry }
+      : { ...mark, geometry: null };
+  });
+}
+
 function barGeometry(panel, axes, layout) {
   const horizontal = panel.orientation === "horizontal", categories = horizontal ? panel.categories.y : panel.categories.x;
   const category = horizontal ? axes.y : axes.x, value = horizontal ? axes.x : axes.y;
@@ -211,26 +251,43 @@ export function isResolvedRenderer(renderer) { return RESOLVED_RENDERERS.include
 
 export function resolveTerminalScene(scene, options = {}) {
   const width = options.width ?? 960, height = options.height ?? 600;
-  const layout = deriveFigureLayout(width, height, { panels: scene.panels, layout: scene.layout, theme: scene.theme, spec: scene.spec });
+  const layout = options.layout ?? deriveFigureLayout(width, height, { panels: scene.panels, layout: scene.layout, theme: scene.theme, spec: scene.spec });
   const panels = scene.panels.map((panel, index) => {
-    const resolvedLayout = panelLayout(layout.panels[index], panel);
+    let resolvedLayout = options.refineLayout === false ? preparedPanelLayout(layout.panels[index]) : panelLayout(layout.panels[index], panel);
     let axes = resolveAxes(panel, resolvedLayout), marks, plots = null;
+    for (let pass = 0; options.refineLayout !== false && pass < 2; pass += 1) {
+      resolvedLayout = refineScientificLayout(resolvedLayout, panel, axes, { measureText: options.measureText, themeMode: scene.theme.mode });
+      axes = resolveAxes(panel, resolvedLayout);
+    }
     const radius = Math.max(3.2, Math.sqrt(scene.profile.markerSize) * 0.62 * resolvedLayout.scale) * (panel.presentation?.markerScale ?? 1);
-    if (panel.renderer === "line") marks = lineGeometry(panel, axes, radius);
+    if (panel.renderer === "line") marks = lineGeometry(panel, axes, resolvedLayout.scale);
     else if (panel.renderer === "scatter") marks = scatterGeometry(panel, axes, radius);
     else if (["categorical_bar", "categorical_layered_bar"].includes(panel.renderer)) marks = barGeometry(panel, axes, resolvedLayout);
     else if (panel.renderer === "categorical_matrix") { const matrix = matrixGeometry(panel, resolvedLayout, scene.theme); marks = matrix.marks; axes = matrix.axes; }
     else if (panel.renderer === "temporal_coverage") { const coverage = coverageGeometry(panel, resolvedLayout, radius); marks = coverage.marks; axes = coverage.axes; plots = coverage.plots; }
     else if (["interval_comparison", "strip_summary", "temporal_observations", "paired_points", "reference_improvement"].includes(panel.renderer)) marks = extensionGeometry(panel, axes, resolvedLayout, radius);
-    else marks = panel.marks.map((mark) => ({ ...mark, geometry: null }));
+    else marks = fallbackPointGeometry(panel, axes, radius);
     const evidenceFrame = cloneRect(plots ? resolvedLayout.plot : (axes.plot ?? resolvedLayout.plot));
     return { ...panel, layout: resolvedLayout, axes, plots, evidenceFrame, marks, resolved: isResolvedRenderer(panel.renderer) };
   });
-  return deepFreeze({ schemaVersion: RESOLVED_SCENE_VERSION, sourceSceneVersion: scene.schemaVersion, width, height, theme: scene.theme, spec: scene.spec, profile: scene.profile, applicationProfile: scene.applicationProfile, view: scene.view, layout, panels, motionPlan: scene.motionPlan });
+  const result = { schemaVersion: RESOLVED_SCENE_VERSION, sourceSceneVersion: scene.schemaVersion, width, height, theme: scene.theme, spec: scene.spec, profile: scene.profile, applicationProfile: scene.applicationProfile, view: scene.view, layout, panels, motionPlan: scene.motionPlan };
+  if (scene.directLabels && !options.directPass) {
+    const plan = planDirectLabels(scene, result, options.measureText);
+    if (plan.status === "placed") {
+      const baseline = deepFreeze(result), p = panels[0];
+      const adjusted = { ...p.layout, plot: plan.plot };
+      const proposal = resolveTerminalScene(scene, { ...options, layout: { ...layout, panels: [adjusted] }, refineLayout: false, directPass: true });
+      return deepFreeze({ ...proposal, directLabelPlan: plan, fallbackScene: baseline,
+        panels: proposal.panels.map(panel => ({ ...panel, directLabelPlan: plan })) });
+    }
+    result.directLabelPlan = plan;
+  }
+  return deepFreeze(result);
 }
 
 export function resolveSceneFrame(resolvedScene, progress = 1) {
   const p = clamp01(progress);
+  if (p < 1 && resolvedScene.fallbackScene) resolvedScene = { ...resolvedScene.fallbackScene, directLabelPlan: { status: "fallback", reason: "unsupported-layout" } };
   return {
     ...resolvedScene,
     progress: p,

package/src/responsive-header.js

@@ -0,0 +1,159 @@
+import { resolveTerminalScene } from "./resolved-scene.js";
+
+export const RESPONSIVE_HEADER_MAX_WIDTH = 480;
+
+const FONT_STACK = "ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', monospace";
+const finitePositive = (value) => typeof value === "number" && Number.isFinite(value) && value > 0;
+
+function metric(measureText, text, fontSize, style) {
+  return measureText?.(String(text), fontSize, style) ?? { width: String(text).length * fontSize * 0.602 };
+}
+
+function ellipsis(text, maximumWidth, measure) {
+  const source = String(text).trim();
+  if (measure(source).width <= maximumWidth) return { lines: [source], complete: true };
+  let candidate = source;
+  while (candidate && measure(`${candidate}…`).width > maximumWidth) candidate = candidate.slice(0, -1).trimEnd();
+  return { lines: [`${candidate}…`], complete: false };
+}
+
+function wrap(text, maximumWidth, maximumLines, measure) {
+  const words = String(text).trim().split(/\s+/).filter(Boolean);
+  if (!words.length) return { lines: [], complete: true };
+  const lines = [];
+  let truncated = false;
+  let cursor = 0;
+  while (cursor < words.length && lines.length < maximumLines) {
+    let line = words[cursor++];
+    if (measure(line).width > maximumWidth) {
+      lines.push(ellipsis(line, maximumWidth, measure).lines[0]);
+      truncated = true;
+      continue;
+    }
+    while (cursor < words.length && measure(`${line} ${words[cursor]}`).width <= maximumWidth) line += ` ${words[cursor++]}`;
+    lines.push(line);
+  }
+  const complete = cursor === words.length && !truncated;
+  if (cursor < words.length) lines[lines.length - 1] = ellipsis(`${lines.at(-1)} ${words.slice(cursor).join(" ")}`, maximumWidth, measure).lines[0];
+  return { lines, complete };
+}
+
+function shiftRect(value, delta) {
+  if (!value) return value;
+  return { ...value, top: value.top + delta, bottom: value.bottom + delta };
+}
+
+function shiftLayout(source, height, delta) {
+  const text = { ...(source.text ?? {}) };
+  for (const key of ["xLabelY", "xLabelBaselineY", "xTickY", "xTickBaselineY"]) if (typeof text[key] === "number") text[key] += delta;
+  const annotationBounds = source.annotationBounds ? {
+    ...source.annotationBounds,
+    plot: shiftRect(source.annotationBounds.plot, delta),
+    xTicks: shiftRect(source.annotationBounds.xTicks, delta),
+    xTitle: shiftRect(source.annotationBounds.xTitle, delta),
+    provenance: shiftRect(source.annotationBounds.provenance, delta),
+    yTicks: shiftRect(source.annotationBounds.yTicks, delta),
+    yTitle: shiftRect(source.annotationBounds.yTitle, delta),
+  } : null;
+  return {
+    ...source,
+    height,
+    rect: { ...source.rect, bottom: source.rect.bottom + delta },
+    plot: shiftRect(source.plot, delta),
+    text,
+    provenance: source.provenance ? { ...source.provenance, y: source.provenance.y + delta } : null,
+    legend: source.legend ? { ...source.legend, top: source.legend.top + delta, bottom: source.legend.bottom + delta } : null,
+    annotationBounds,
+  };
+}
+
+function headerPlan(panel, measureText, availableExtra, negotiated) {
+  const { layout, spec } = panel;
+  const maximumWidth = Math.max(1, layout.plot.right - layout.plot.left);
+  const titleMeasure = (text) => metric(measureText, text, layout.font.title, "500");
+  const subtitleMeasure = (text) => metric(measureText, text, layout.font.subtitle, "italic");
+  const desiredTitle = wrap(spec.title || panel.renderer, maximumWidth, 2, titleMeasure);
+  const desiredSubtitle = spec.subtitle ? wrap(spec.subtitle, maximumWidth, 2, subtitleMeasure) : { lines: [], complete: true };
+  const titleLineHeight = layout.font.title * 1.22;
+  const subtitleLineHeight = layout.font.subtitle * 1.35;
+  const desiredExtra = (desiredTitle.lines.length - 1) * titleLineHeight + Math.max(0, desiredSubtitle.lines.length - 1) * subtitleLineHeight;
+  const titleBaseline = layout.text?.titleY ?? Math.max(layout.font.title + 8, layout.plot.top * 0.52);
+  const baseSubtitleBaseline = layout.text?.subtitleY ?? Math.max(layout.font.title + layout.font.subtitle + 14, layout.plot.top * 0.73);
+  let title = desiredTitle;
+  let subtitle = desiredSubtitle;
+  let policy = negotiated && availableExtra + 0.01 >= desiredExtra ? "B" : "C";
+  if (policy === "C") {
+    subtitle = spec.subtitle ? ellipsis(spec.subtitle, maximumWidth, subtitleMeasure) : { lines: [], complete: true };
+    if (title.lines.length > 1) {
+      const subtitleBaseline = baseSubtitleBaseline + titleLineHeight;
+      const subtitleDescent = layout.font.subtitle * 0.22;
+      if (subtitle.lines.length && subtitleBaseline + subtitleDescent > layout.plot.top + availableExtra) title = ellipsis(spec.title || panel.renderer, maximumWidth, titleMeasure);
+    }
+  }
+  const subtitleBaseline = baseSubtitleBaseline + Math.max(0, title.lines.length - 1) * titleLineHeight;
+  return {
+    policy,
+    desiredExtra,
+    title: { ...title, lineHeight: titleLineHeight, baselines: title.lines.map((_, index) => titleBaseline + index * titleLineHeight) },
+    subtitle: { ...subtitle, lineHeight: subtitleLineHeight, baselines: subtitle.lines.map((_, index) => subtitleBaseline + index * subtitleLineHeight) },
+  };
+}
+
+export function fixedResponsiveHeader(panel, measureText) {
+  return headerPlan(panel, measureText, 0, false);
+}
+
+/** Internal live-Canvas layout policy. Fixed SVG serialization reuses only the C text plan. */
+export function resolveResponsiveCanvasScene(scene, options = {}) {
+  const width = options.width;
+  const height = options.height;
+  const baselineHeight = finitePositive(options.baselineHeight) ? options.baselineHeight : null;
+  const compactSingle = width <= RESPONSIVE_HEADER_MAX_WIDTH && scene.panels.length === 1 && scene.theme.mode !== "paper";
+  if (!compactSingle) {
+    const layoutHeight = baselineHeight != null && height >= baselineHeight ? baselineHeight : height;
+    const baseline = resolveTerminalScene(scene, { width, height: layoutHeight, measureText: options.measureText });
+    const rootLayout = layoutHeight === height ? null : {
+      ...baseline.layout,
+      height,
+      panels: baseline.panels.map((panel) => panel.layout),
+    };
+    const resolved = rootLayout
+      ? resolveTerminalScene(scene, { width, height, measureText: options.measureText, layout: rootLayout, refineLayout: false })
+      : baseline;
+    return { resolved, preferredHeight: baselineHeight, baselineHeight, header: null };
+  }
+
+  const layoutHeight = baselineHeight ?? height;
+  const baseline = resolveTerminalScene(scene, { width, height: layoutHeight, measureText: options.measureText });
+  const availableExtra = baselineHeight ? Math.max(0, height - baselineHeight) : 0;
+  const desiredPlan = headerPlan(baseline.panels[0], options.measureText, availableExtra, baselineHeight != null);
+  const preferredHeight = baselineHeight == null ? null : baselineHeight + Math.ceil(desiredPlan.desiredExtra);
+  // A host may clamp below its own intrinsic baseline. In that degraded case the
+  // fixed-height C policy must resolve against the real canvas, rather than let
+  // baseline geometry extend beyond the available field.
+  const belowBaseline = baselineHeight != null && height < baselineHeight;
+  const renderedBase = belowBaseline
+    ? resolveTerminalScene(scene, { width, height, measureText: options.measureText })
+    : baseline;
+  const delta = baselineHeight == null || belowBaseline ? 0 : Math.max(0, height - baselineHeight);
+  const panelLayout = shiftLayout(renderedBase.panels[0].layout, height, delta);
+  const plan = headerPlan({ ...renderedBase.panels[0], layout: panelLayout }, options.measureText, delta, baselineHeight != null && !belowBaseline);
+  panelLayout.headerText = Object.freeze({
+    policy: plan.policy,
+    baselineHeight,
+    preferredHeight,
+    appliedExtra: delta,
+    desiredExtra: desiredPlan.desiredExtra,
+    title: plan.title,
+    subtitle: plan.subtitle,
+  });
+  const rootLayout = {
+    ...renderedBase.layout,
+    height,
+    plot: shiftRect(renderedBase.layout.plot, delta),
+    provenance: renderedBase.layout.provenance ? { ...renderedBase.layout.provenance, y: renderedBase.layout.provenance.y + delta } : null,
+    panels: [panelLayout],
+  };
+  const resolved = resolveTerminalScene(scene, { width, height, measureText: options.measureText, layout: rootLayout, refineLayout: false });
+  return { resolved, preferredHeight, baselineHeight, header: resolved.panels[0].layout.headerText };
+}

package/src/schema.js

@@ -1,3 +1,5 @@
+import { linearFit } from "./statistics.js";
+
 export const SCHEMA_VERSION = "0.4";
 export const LEGACY_SCHEMA_VERSION = "0.3";
 export const RENDERER_API_VERSION = "1";
@@ -29,6 +31,14 @@ export function requiredString(value, path) {
   }
 }
 
+const CANONICAL_COLOR = /^#[0-9a-fA-F]{6}$/;
+
+export function requiredColor(value, path) {
+  if (typeof value !== "string" || !CANONICAL_COLOR.test(value)) {
+    throw new FiguresteadConfigError("must be a canonical #RRGGBB color", path);
+  }
+}
+
 export function numberArray(value, path, { allowEmpty = false } = {}) {
   if (!Array.isArray(value) || (!allowEmpty && value.length === 0)) {
     throw new FiguresteadConfigError("must be a non-empty numeric array", path);
@@ -62,21 +72,27 @@ function timelineWindow(value, path) {
   }
 }
 
-function validateTheme(theme) {
-  requiredObject(theme, "config.theme");
-  ["key", "name", "field", "panel", "grid", "spine", "label", "secondary", "faint", "primary", "summaryCore", "warm"]
-    .forEach((key) => requiredString(theme[key], `config.theme.${key}`));
+export function validateThemeColors(theme, path = "config.theme") {
+  requiredObject(theme, path);
+  ["field", "panel", "grid", "spine", "label", "secondary", "faint", "primary", "summaryCore", "warm"]
+    .forEach((key) => requiredColor(theme[key], `${path}.${key}`));
   if (!Array.isArray(theme.series) || !theme.series.length) {
-    throw new FiguresteadConfigError("must be a non-empty color array", "config.theme.series");
+    throw new FiguresteadConfigError("must be a non-empty color array", `${path}.series`);
   }
-  theme.series.forEach((color, index) => requiredString(color, `config.theme.series[${index}]`));
-  for (const key of ["primaryEdge", "summaryEdge"]) if (theme[key] != null) requiredString(theme[key], `config.theme.${key}`);
+  theme.series.forEach((color, index) => requiredColor(color, `${path}.series[${index}]`));
+  for (const key of ["primaryEdge", "summaryEdge"]) if (theme[key] != null) requiredColor(theme[key], `${path}.${key}`);
   if (theme.seriesEdges != null) {
-    if (!Array.isArray(theme.seriesEdges) || theme.seriesEdges.length !== theme.series.length) throw new FiguresteadConfigError(`must contain exactly ${theme.series.length} colors`, "config.theme.seriesEdges");
-    theme.seriesEdges.forEach((color, index) => requiredString(color, `config.theme.seriesEdges[${index}]`));
+    if (!Array.isArray(theme.seriesEdges) || theme.seriesEdges.length !== theme.series.length) throw new FiguresteadConfigError(`must contain exactly ${theme.series.length} colors`, `${path}.seriesEdges`);
+    theme.seriesEdges.forEach((color, index) => requiredColor(color, `${path}.seriesEdges[${index}]`));
   }
 }
 
+function validateTheme(theme) {
+  requiredObject(theme, "config.theme");
+  ["key", "name"].forEach((key) => requiredString(theme[key], `config.theme.${key}`));
+  validateThemeColors(theme);
+}
+
 function validateProfile(profile) {
   requiredObject(profile, "config.profile");
   ["key", "name", "marker"].forEach((key) => requiredString(profile[key], `config.profile.${key}`));
@@ -170,6 +186,13 @@ export function normalizeScatterData(data, basePath = "config.data") {
   if (summary !== null && summary !== "linear_fit") {
     throw new FiguresteadConfigError("must be null or 'linear_fit'", `${basePath}.summary`);
   }
+  if (summary === "linear_fit") {
+    try {
+      linearFit(x, y);
+    } catch (error) {
+      throw new FiguresteadConfigError(error.message, `${basePath}.summary`);
+    }
+  }
   return {
     x, y, series: series.map(String), seriesLabels: normalizeSeriesLabels(keys, data.seriesLabels), summary,
     xDomain: domain(data.xDomain, `${basePath}.xDomain`), yDomain: domain(data.yDomain, `${basePath}.yDomain`),
@@ -292,9 +315,10 @@ function normalizeStyle(value) {
   glyphs.forEach((glyph, index) => { if (!MARKER_TYPES.has(glyph)) throw new FiguresteadConfigError("is not a supported glyph", `config.style.glyphs[${index}]`); });
   const lineStyles = style.lineStyles ?? ["solid", "dash", "dot", "dash-dot"];
   if (!Array.isArray(lineStyles) || !lineStyles.length || lineStyles.some((item) => !["solid", "dash", "dot", "dash-dot"].includes(item))) throw new FiguresteadConfigError("must contain supported line styles", "config.style.lineStyles");
+  if (style.directLabels != null && typeof style.directLabels !== "boolean") throw new FiguresteadConfigError("must be boolean", "config.style.directLabels");
   const series = style.series ?? {};
   requiredObject(series, "config.style.series");
-  return { glyphs: [...glyphs], lineStyles: [...lineStyles], series: cloneValue(series) };
+  return { glyphs: [...glyphs], lineStyles: [...lineStyles], series: cloneValue(series), ...(style.directLabels ? { directLabels: true } : {}) };
 }
 
 function normalizePanel(panel, index, figureSpec, registry) {

package/src/scientific-layout.js

@@ -0,0 +1,148 @@
+const clamp = (value, minimum, maximum) => Math.max(minimum, Math.min(maximum, value));
+
+const DEFAULT_FONT_WIDTH = 0.602;
+
+function fallbackMetric(text, fontSize) {
+  return {
+    width: String(text).length * fontSize * DEFAULT_FONT_WIDTH,
+    ascent: fontSize * 0.78,
+    descent: fontSize * 0.22,
+  };
+}
+
+function normalizedMetric(measureText, text, fontSize) {
+  const measured = measureText?.(String(text), fontSize) ?? fallbackMetric(text, fontSize);
+  const ascent = measured.ascent ?? measured.actualBoundingBoxAscent ?? fontSize * 0.78;
+  const descent = measured.descent ?? measured.actualBoundingBoxDescent ?? fontSize * 0.22;
+  return { width: measured.width, ascent, descent, height: ascent + descent };
+}
+
+function annotationGaps(scale) {
+  return {
+    outer: clamp(7 * scale, 4, 10),
+    plotTick: clamp(7 * scale, 4, 9),
+    tickTitle: clamp(7 * scale, 4, 9),
+    titleFooter: clamp(8 * scale, 5, 10),
+    yTitleTick: clamp(8 * scale, 5, 10),
+  };
+}
+
+function xTickDepth(axes, plot, metric) {
+  const slot = axes.x.step?.() ?? Math.max(40, (plot.right - plot.left) / Math.max(1, axes.xTicks.length));
+  const metrics = axes.xTicks.map((tick) => metric(tick.label));
+  const rotate = axes.xType === "band" && metrics.some((value) => value.width > slot * 0.92);
+  const depth = metrics.length
+    ? Math.max(...metrics.map((value) => rotate ? (value.width + value.height) / Math.sqrt(2) : value.height))
+    : 0;
+  return { rotate, depth, metrics };
+}
+
+/**
+ * Internal annotation layout pass. It deliberately consumes resolved tick strings
+ * rather than guessing from canvas size. No contract or renderer API is exposed.
+ */
+export function refineScientificLayout(source, panel, axes, options = {}) {
+  const layout = {
+    ...source,
+    rect: { ...source.rect }, plot: { ...source.plot }, font: { ...source.font },
+    text: { ...(source.text ?? {}) }, provenance: source.provenance ? { ...source.provenance } : null,
+    legend: source.legend ? { ...source.legend } : null,
+  };
+  const { rect, font, scale } = layout, gaps = annotationGaps(scale);
+  const axisMetric = (text) => normalizedMetric(options.measureText, text, font.axis);
+  const signatureMetric = (text) => normalizedMetric(options.measureText, text, font.signature);
+  const xTitleMetric = panel.spec.xLabel ? axisMetric(panel.spec.xLabel) : null;
+  const yTitleMetric = panel.spec.yLabel ? axisMetric(panel.spec.yLabel) : null;
+  const footerMetric = panel.spec.signature ? signatureMetric(panel.spec.signature) : null;
+  const hasLocalFooter = Boolean(
+    footerMetric && options.themeMode !== "paper" && (layout.panelIndex ?? 0) === 0
+    && (!layout.provenance || layout.provenance.y <= rect.bottom)
+  );
+
+  const provisionalPlot = { ...layout.plot };
+  const xTick = xTickDepth(axes, provisionalPlot, axisMetric);
+  const yTickMetrics = axes.yTicks.map((tick) => axisMetric(tick.label));
+  const yTickWidth = yTickMetrics.length ? Math.max(...yTickMetrics.map((value) => value.width)) : 0;
+
+  let cursorBottom = rect.bottom - gaps.outer;
+  let provenance = null;
+  if (hasLocalFooter) {
+    const baseline = cursorBottom - footerMetric.descent;
+    provenance = {
+      left: 0, right: rect.right - gaps.outer, y: baseline,
+      bounds: { left: 0, right: 0, top: baseline - footerMetric.ascent, bottom: baseline + footerMetric.descent },
+    };
+    cursorBottom = provenance.bounds.top - gaps.titleFooter;
+  }
+  let xTitle = null;
+  if (xTitleMetric) {
+    xTitle = { left: 0, right: 0, top: cursorBottom - xTitleMetric.height, bottom: cursorBottom };
+    cursorBottom = xTitle.top - gaps.tickTitle;
+  }
+  const xTicks = {
+    left: 0, right: 0,
+    top: cursorBottom - xTick.depth,
+    bottom: cursorBottom,
+  };
+  const requestedPlotBottom = xTicks.top - gaps.plotTick;
+  const availablePlotHeight = Math.max(0, requestedPlotBottom - layout.plot.top);
+  const minimumPlotHeight = Math.min(120, availablePlotHeight);
+  layout.plot.bottom = Math.max(layout.plot.top + minimumPlotHeight, requestedPlotBottom);
+
+  const yTitleThickness = yTitleMetric?.height ?? 0;
+  const requestedPlotLeft = rect.left + gaps.outer + yTitleThickness
+    + (yTitleMetric && yTickWidth ? gaps.yTitleTick : 0) + yTickWidth + gaps.plotTick;
+  layout.plot.left = Math.min(layout.plot.right - 160, requestedPlotLeft);
+
+  const xCenter = (layout.plot.left + layout.plot.right) / 2;
+  xTicks.left = layout.plot.left; xTicks.right = layout.plot.right;
+  if (xTitle) {
+    xTitle.left = xCenter - xTitleMetric.width / 2;
+    xTitle.right = xCenter + xTitleMetric.width / 2;
+    layout.text.xLabelY = xTitle.bottom;
+    layout.text.xLabelBaselineY = xTitle.top + xTitleMetric.ascent;
+  }
+  layout.text.xTickY = xTicks.top;
+  layout.text.xTickBaselineY = xTicks.top + (xTick.metrics[0]?.ascent ?? font.axis * 0.78);
+  layout.text.rotateX = xTick.rotate;
+
+  const yTicks = {
+    left: layout.plot.left - gaps.plotTick - yTickWidth,
+    right: layout.plot.left - gaps.plotTick,
+    top: layout.plot.top, bottom: layout.plot.bottom,
+  };
+  let yTitle = null;
+  if (yTitleMetric) {
+    const right = yTicks.left - (yTickWidth ? gaps.yTitleTick : 0);
+    yTitle = { left: right - yTitleMetric.height, right, top: layout.plot.top, bottom: layout.plot.bottom };
+    layout.text.yLabelX = yTitle.left;
+  }
+
+  if (provenance) {
+    provenance.left = layout.plot.left;
+    provenance.bounds.left = provenance.left;
+    provenance.bounds.right = provenance.left + footerMetric.width;
+    layout.provenance = { left: provenance.left, right: provenance.right, y: provenance.y };
+  } else if (layout.provenance?.y <= rect.bottom) {
+    layout.provenance = null;
+  }
+  if (layout.legend) {
+    layout.legend = layout.legend.outside
+      ? { ...layout.legend, top: layout.plot.top, bottom: layout.plot.bottom }
+      : { ...layout.legend, left: layout.plot.left, right: layout.plot.right, top: layout.plot.top, bottom: layout.plot.bottom };
+  }
+
+  layout.annotationBounds = {
+    plot: { ...layout.plot }, xTicks, xTitle, provenance: provenance?.bounds ?? null, yTicks, yTitle,
+    gaps: {
+      plotToXTicks: xTicks.top - layout.plot.bottom,
+      xTicksToTitle: xTitle ? xTitle.top - xTicks.bottom : null,
+      xTitleToProvenance: xTitle && provenance ? provenance.bounds.top - xTitle.bottom : null,
+      xTicksToProvenance: !xTitle && provenance ? provenance.bounds.top - xTicks.bottom : null,
+      yTitleToTicks: yTitle ? yTicks.left - yTitle.right : null,
+      yTicksToPlot: layout.plot.left - yTicks.right,
+    },
+    rotateX: xTick.rotate,
+  };
+  return layout;
+}

package/src/screen-legibility.js

@@ -0,0 +1,30 @@
+import { resolveContrastColor } from "./color-space.js";
+
+export const SCREEN_LEGIBILITY_VERSION = "figurestead.screen-legibility/1";
+
+// Figurestead project floors for browser-rendered evidence. These are not
+// assertions of conformance with an external accessibility standard.
+export const SCREEN_PROJECT_LEGIBILITY_FLOORS = Object.freeze({
+  provenanceContrast: 3.4,
+  compactProvenancePx: 9,
+});
+
+export function resolveScreenTheme(source) {
+  const resolution = resolveContrastColor(
+    source.faint,
+    source.field,
+    SCREEN_PROJECT_LEGIBILITY_FLOORS.provenanceContrast,
+  );
+  const theme = { ...source, faint: resolution.color };
+  return Object.freeze({
+    theme: Object.freeze(theme),
+    report: Object.freeze({
+      schemaVersion: SCREEN_LEGIBILITY_VERSION,
+      policy: "Figurestead screen/project legibility floor",
+      token: "faint",
+      surface: "field",
+      minimum: SCREEN_PROJECT_LEGIBILITY_FLOORS.provenanceContrast,
+      resolution: Object.freeze({ ...resolution }),
+    }),
+  });
+}

package/src/statistics.js

@@ -0,0 +1,21 @@
+export function linearFit(x, y) {
+  if (!Array.isArray(x) || !Array.isArray(y) || x.length !== y.length) {
+    throw new TypeError("linear_fit requires x and y arrays of equal length");
+  }
+  if (x.length < 2) throw new TypeError("linear_fit requires at least two finite observations");
+  if (!x.every(Number.isFinite) || !y.every(Number.isFinite)) {
+    throw new TypeError("linear_fit requires finite x and y values");
+  }
+  if (new Set(x).size < 2) throw new TypeError("linear_fit requires at least two distinct finite x values");
+
+  const meanX = x.reduce((sum, value) => sum + value, 0) / x.length;
+  const meanY = y.reduce((sum, value) => sum + value, 0) / y.length;
+  let numerator = 0;
+  let denominator = 0;
+  for (let index = 0; index < x.length; index += 1) {
+    const centeredX = x[index] - meanX;
+    numerator += centeredX * (y[index] - meanY);
+    denominator += centeredX * centeredX;
+  }
+  return { slope: numerator / denominator, intercept: meanY - (numerator / denominator) * meanX };
+}