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

package/src/create-matrix-plot.js

@@ -5,34 +5,70 @@ import { prepareAtmosphere, drawAtmosphere } from "./atmosphere.js";
 import { drawBackground, drawFigureHeader } from "./marks.js";
 import { CORE_REGISTRY } from "./core-renderers.js";
 import { AnimationClock } from "./clock.js";
-import { createAccessibilityCompanion } from "./accessibility.js";
+import { createAccessibilityCompanion, prepareAccessibilityCompanion } from "./accessibility.js";
 import { drawPanelSurface, drawPresentationAnnotations } from "./presentation.js";
 import { compileFigureModel } from "./terminal-scene.js";
-import { isResolvedRenderer, resolveSceneFrame, resolveTerminalScene } from "./resolved-scene.js";
+import { isResolvedRenderer, resolveSceneFrame } from "./resolved-scene.js";
 import { drawResolvedPanel } from "./canvas-scene.js";
 import { composeResolvedScene } from "./composition.js";
+import { resolveResponsiveCanvasScene } from "./responsive-header.js";
+import { createHeightNegotiator, validateHeightNegotiation } from "./height-negotiation.js";
 
 export function createFigurestead(canvas, input, options = {}) {
   if (!(canvas instanceof HTMLCanvasElement)) throw new TypeError("createFigurestead requires an HTMLCanvasElement");
   const registry = options.registry ?? CORE_REGISTRY;
   if (registry.apiVersion !== "1") throw new TypeError("Figurestead requires renderer registry API 1");
+  const heightNegotiation = validateHeightNegotiation(options.heightNegotiation);
   let contract = input, scene = null, preparedPanels = [], domains = [], atmosphere, surface, resolvedScene = null, composedScene = null, clock = null, destroyed = false;
-  let reducedOverride = options.reducedMotion ?? null, companion = null;
+  let reducedOverride = options.reducedMotion ?? null, companion = null, contractRevision = 0;
+  const heightNegotiator = createHeightNegotiator(canvas, heightNegotiation, options.onError);
   const media = globalThis.matchMedia?.("(prefers-reduced-motion: reduce)");
   const isReduced = () => reducedOverride == null ? Boolean(media?.matches) : Boolean(reducedOverride);
 
-  const prepare = () => {
-    const model = compileFigureModel(contract, { registry });
-    contract = model.contract; scene = model.scene; preparedPanels = model.preparedPanels; domains = model.domains;
-    atmosphere = contract.view.ambient === "matrix" ? prepareAtmosphere(contract.motion) : [];
+  const prepareModel = (candidate) => {
+    const model = compileFigureModel(candidate, { registry });
+    return { ...model, atmosphere: model.contract.view.ambient === "matrix" ? prepareAtmosphere(model.contract.motion) : [] };
   };
-  const layoutFactory = (width, height) => deriveFigureLayout(width, height, contract);
+  const applyModel = (model) => {
+    contract = model.contract; scene = model.scene; preparedPanels = model.preparedPanels; domains = model.domains; atmosphere = model.atmosphere;
+  };
+  const layoutFactory = (width, height, candidate = contract) => deriveFigureLayout(width, height, candidate);
+  const measuredText = (text, fontSize, style = "normal") => {
+    surface.context.save();
+    const prefix = style === "italic" ? "italic " : style === "500" ? "500 " : "";
+    surface.context.font = `${prefix}${fontSize}px ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', monospace`;
+    const value = surface.context.measureText(String(text));
+    surface.context.restore();
+    return { width: value.width, ascent: value.actualBoundingBoxAscent, descent: value.actualBoundingBoxDescent };
+  };
+  const observedBox = () => {
+    const rect = canvas.getBoundingClientRect();
+    return { width: rect.width, height: rect.height, visible: rect.width > 0 && rect.height > 0 && canvas.getClientRects().length > 0 };
+  };
+  const prepareResolution = (candidateScene, width, height, baselineResult) => {
+    const responsive = resolveResponsiveCanvasScene(candidateScene, {
+      width, height, baselineHeight: baselineResult.value, measureText: measuredText,
+    });
+    return { ...responsive, composed: composeResolvedScene(responsive.resolved), baselineError: baselineResult.error };
+  };
+  const commitNegotiation = (prepared, box) => heightNegotiator.commit({
+    contractRevision,
+    width: box.visible ? box.width : 0,
+    baselineHeight: prepared.baselineHeight,
+    preferredHeight: prepared.preferredHeight,
+    baselineError: prepared.baselineError,
+  });
   const resize = () => {
     if (destroyed) return;
+    const box = observedBox();
     surface = resizeCanvas(canvas, { dprCap: options.dprCap ?? 2, layoutFactory });
-    resolvedScene = resolveTerminalScene(scene, { width: surface.layout.width, height: surface.layout.height });
-    composedScene = composeResolvedScene(resolvedScene);
-    if (clock) draw(clock.progress);
+    const baseline = box.visible ? heightNegotiator.baseline(box.width, box.height) : { value: null, error: null };
+    const prepared = prepareResolution(scene, surface.layout.width, surface.layout.height, baseline);
+    resolvedScene = prepared.resolved;
+    composedScene = prepared.composed;
+    surface = { ...surface, layout: resolvedScene.layout };
+    if (clock) clock.render(clock.progress);
+    commitNegotiation(prepared, box);
   };
   const draw = (progress) => {
     if (!surface || destroyed) return;
@@ -51,12 +87,17 @@ export function createFigurestead(canvas, input, options = {}) {
     options.onProgress?.(p);
   };
 
-  prepare(); surface = resizeCanvas(canvas, { dprCap: options.dprCap ?? 2, layoutFactory });
-  resolvedScene = resolveTerminalScene(scene, { width: surface.layout.width, height: surface.layout.height });
-  composedScene = composeResolvedScene(resolvedScene);
-  clock = new AnimationClock({ durationMs: contract.motion.durationMs, draw, onState: options.onState });
-  companion = createAccessibilityCompanion(canvas, contract, registry, options.accessibility);
+  applyModel(prepareModel(input)); surface = resizeCanvas(canvas, { dprCap: options.dprCap ?? 2, layoutFactory });
+  const initialBox = observedBox();
+  const initialBaseline = initialBox.visible ? heightNegotiator.baseline(initialBox.width, initialBox.height) : { value: null, error: null };
+  const initialResolution = prepareResolution(scene, surface.layout.width, surface.layout.height, initialBaseline);
+  resolvedScene = initialResolution.resolved;
+  composedScene = initialResolution.composed;
+  surface = { ...surface, layout: resolvedScene.layout };
+  clock = new AnimationClock({ durationMs: contract.motion.durationMs, draw, onState: options.onState, onError: options.onError });
+  companion = createAccessibilityCompanion(canvas, contract, registry, { ...options.accessibility, composedScene });
   clock.render(isReduced() ? 1 : 0);
+  commitNegotiation(initialResolution, initialBox);
 
   let autoplayUsed = false, wasPlayingBeforeHidden = false;
   const resizeObserver = globalThis.ResizeObserver ? new ResizeObserver(resize) : null; resizeObserver?.observe(canvas);
@@ -65,33 +106,48 @@ export function createFigurestead(canvas, input, options = {}) {
   }, { threshold: [.35] }) : null;
   if (options.autoplay !== false) { if (intersectionObserver) intersectionObserver.observe(canvas); else { autoplayUsed = true; isReduced() ? clock.settle() : clock.play(); } }
   const visibility = () => { if (document.hidden) { wasPlayingBeforeHidden = clock.playing; clock.pause(); } else if (wasPlayingBeforeHidden) { wasPlayingBeforeHidden = false; clock.play(); } };
-  const mediaChange = () => { if (reducedOverride == null) isReduced() ? clock.settle() : draw(clock.progress); };
+  const mediaChange = () => { if (reducedOverride == null) isReduced() ? clock.settle() : clock.render(clock.progress); };
   document.addEventListener("visibilitychange", visibility); media?.addEventListener?.("change", mediaChange);
 
   const replace = (next) => {
-    clock.pause(); contract = next; prepare(); clock.durationMs = contract.motion.durationMs;
-    surface = resizeCanvas(canvas, { dprCap: options.dprCap ?? 2, layoutFactory });
-    resolvedScene = resolveTerminalScene(scene, { width: surface.layout.width, height: surface.layout.height });
-    composedScene = composeResolvedScene(resolvedScene);
-    companion.destroy(); companion = createAccessibilityCompanion(canvas, contract, registry, options.accessibility); clock.settle();
+    const nextModel = prepareModel(next);
+    const box = observedBox();
+    const baseline = box.visible ? heightNegotiator.baseline(box.width, box.height) : { value: null, error: null };
+    const nextResolution = prepareResolution(nextModel.scene, surface.layout.width, surface.layout.height, baseline);
+    const nextCompanion = prepareAccessibilityCompanion(canvas, nextModel.contract, registry, { ...options.accessibility, composedScene: nextResolution.composed });
+    const nextSurface = resizeCanvas(canvas, { dprCap: options.dprCap ?? 2, layoutFactory: (width, height) => layoutFactory(width, height, nextModel.contract) });
+    clock.pause();
+    applyModel(nextModel);
+    contractRevision += 1;
+    resolvedScene = nextResolution.resolved; composedScene = nextResolution.composed;
+    surface = { ...nextSurface, layout: resolvedScene.layout };
+    clock.durationMs = contract.motion.durationMs; clock.resetFailure();
+    nextCompanion.attach(); companion.destroy(); companion = nextCompanion; clock.settle();
+    commitNegotiation(nextResolution, box);
   };
   return Object.freeze({
     play() { if (isReduced()) clock.settle(); else clock.play(); }, pause() { clock.pause(); }, replay() { if (isReduced()) clock.settle(); else clock.replay(); },
     setData(data) { if (contract.panels.length !== 1) throw new TypeError("setData is available only for single-panel figures; use setConfig for multi-panel figures"); const next = cloneValue(contract); next.panels[0].data = cloneValue(data); replace(next); },
     setConfig(next) { replace(next); },
-    setReducedMotion(value) { if (value !== null && typeof value !== "boolean") throw new TypeError("reduced motion must be true, false, or null"); reducedOverride = value; isReduced() ? clock.settle() : draw(clock.progress); },
+    setReducedMotion(value) { if (value !== null && typeof value !== "boolean") throw new TypeError("reduced motion must be true, false, or null"); reducedOverride = value; isReduced() ? clock.settle() : clock.render(clock.progress); },
     resize,
-    destroy() { if (destroyed) return; destroyed = true; clock.destroy(); resizeObserver?.disconnect(); intersectionObserver?.disconnect(); document.removeEventListener("visibilitychange", visibility); media?.removeEventListener?.("change", mediaChange); companion.destroy(); },
-    getState() { return { progress: clock.progress, playing: clock.playing, reducedMotion: isReduced(), renderers: contract.panels.map((panel) => panel.renderer), sceneVersion: scene.schemaVersion, resolvedSceneVersion: resolvedScene.schemaVersion, composedSceneVersion: composedScene.schemaVersion, profile: contract.view.profile, destroyed }; },
+    destroy() { if (destroyed) return; destroyed = true; heightNegotiator.destroy(); clock.destroy(); resizeObserver?.disconnect(); intersectionObserver?.disconnect(); document.removeEventListener("visibilitychange", visibility); media?.removeEventListener?.("change", mediaChange); companion.destroy(); },
+    getState() { return { progress: clock.progress, playing: clock.playing, reducedMotion: isReduced(), runtimeFailed: clock.failed, renderers: contract.panels.map((panel) => panel.renderer), sceneVersion: scene.schemaVersion, resolvedSceneVersion: resolvedScene.schemaVersion, composedSceneVersion: composedScene.schemaVersion, profile: contract.view.profile, destroyed }; },
     getScene() { return scene; },
     getResolvedScene() { return resolvedScene; },
     getComposedScene() { return composedScene; },
     getFinalCoordinates() {
-      return preparedPanels.map((state, index) => {
-        if (isResolvedRenderer(state.panel.renderer)) return { panelId: state.panel.id, points: resolvedScene.panels[index].marks.filter((mark) => mark.kind === "point").map((mark) => ({ x: mark.geometry.cx, y: mark.geometry.cy, dataX: mark.x ?? mark.group, dataY: mark.y ?? mark.yCategory })) };
-        const scales = state.definition.draw(surface.context, { contract: state.contract, prepared: state.prepared, layout: surface.layout.panels[index], domains: domains[index], progress: 1, settled: true, panel: state.panel, figure: contract });
-        return { panelId: state.panel.id, points: (state.prepared.points ?? []).map((point) => ({ x: scales?.x?.(point.x), y: scales?.y?.(point.y), dataX: point.x, dataY: point.y })) };
-      });
+      return resolvedScene.panels.map((panel) => ({
+        panelId: panel.id,
+        points: panel.marks
+          .filter((mark) => ["point", "renderer-mark"].includes(mark.kind) && Number.isFinite(mark.geometry?.cx) && Number.isFinite(mark.geometry?.cy))
+          .map((mark) => ({
+            x: mark.geometry.cx,
+            y: mark.geometry.cy,
+            dataX: mark.x ?? mark.group ?? mark.evidence?.x ?? mark.evidence?.group,
+            dataY: mark.y ?? mark.yCategory ?? mark.evidence?.y ?? mark.evidence?.yCategory,
+          })),
+      }));
     },
   });
 }

package/src/export-bundle.js

@@ -6,7 +6,7 @@ import { compileTerminalScene, evidenceFingerprint } from "./terminal-scene.js";
 import { auditPhysicalTypography, resolveExportSize } from "./physical-export.js";
 
 export const EXPORT_MANIFEST_VERSION = "figurestead.export-manifest/1";
-export const FIGURESTEAD_PACKAGE_VERSION = "0.9.0-alpha.1";
+export const FIGURESTEAD_PACKAGE_VERSION = "0.9.0-alpha.2";
 
 function sorted(value) {
   if (Array.isArray(value)) return value.map(sorted);

package/src/extensions/temporal/shared.js

@@ -151,7 +151,7 @@ export function drawTemporalAxes(context, { contract, layout, scales, plot = lay
   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));
+    scales.xTicks.forEach((value) => context.fillText(formatTimeTick(value, scales.xDomain), scales.x(value), layout.text?.xTickY ?? plot.bottom + 9 * layout.scale));
   }
   if (showY) {
     context.textAlign = "right"; context.textBaseline = "middle";

package/src/figure-layout.js

@@ -1,4 +1,5 @@
 import { deriveLayout } from "./layout.js";
+import { SCREEN_PROJECT_LEGIBILITY_FLOORS } from "./screen-legibility.js";
 
 const clamp = (value, minimum, maximum) => Math.max(minimum, Math.min(maximum, value));
 
@@ -28,7 +29,7 @@ function deriveMultiPanelLayout(width, height, contract, columns, scale, outer,
       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) },
+      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 ? SCREEN_PROJECT_LEGIBILITY_FLOORS.compactProvenancePx : 7, 10) },
       provenance: provenanceHeight ? { left: outer, right: width - outer, y: height - clamp(8 * scale, 7, 12) } : null,
     };
   });
@@ -36,7 +37,7 @@ function deriveMultiPanelLayout(width, height, contract, columns, scale, outer,
     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) },
+    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 ? SCREEN_PROJECT_LEGIBILITY_FLOORS.compactProvenancePx : 7, 10) },
     provenance: provenanceHeight ? { left: outer, right: width - outer, y: height - clamp(8 * scale, 7, 12) } : null,
   };
 }

package/src/height-negotiation.js

@@ -0,0 +1,77 @@
+const finitePositive = (value) => typeof value === "number" && Number.isFinite(value) && value > 0;
+const normalize = (value) => Math.round(value * 1000) / 1000;
+
+export function validateHeightNegotiation(value) {
+  if (value == null) return null;
+  if (typeof value !== "object" || typeof value.getBaselineHeight !== "function" || typeof value.requestPreferredHeight !== "function") {
+    throw new TypeError("heightNegotiation requires getBaselineHeight(context) and requestPreferredHeight(request)");
+  }
+  return value;
+}
+
+export function createHeightNegotiator(canvas, adapter, reportError) {
+  let destroyed = false;
+  let generation = null;
+  let controller = null;
+  let serial = 0;
+
+  const abort = () => {
+    controller?.abort();
+    controller = null;
+    generation = null;
+  };
+  const safeReport = (error, context) => {
+    try { reportError?.(error, Object.freeze({ phase: "height-negotiation", ...context })); } catch { /* Host reporting cannot destabilize the controller. */ }
+  };
+
+  const baseline = (width, currentHeight) => {
+    if (!adapter || destroyed || !finitePositive(width) || !finitePositive(currentHeight)) return { value: null, error: null };
+    try {
+      const value = adapter.getBaselineHeight(Object.freeze({ canvas, width, currentHeight }));
+      return { value: finitePositive(value) ? normalize(value) : null, error: null };
+    } catch (error) {
+      return { value: null, error };
+    }
+  };
+
+  const commit = ({ contractRevision, width, baselineHeight, preferredHeight, baselineError = null }) => {
+    if (!adapter || destroyed) return;
+    if (baselineError) {
+      abort();
+      safeReport(baselineError, { operation: "baseline", width, baselineHeight: null, preferredHeight: null });
+      return;
+    }
+    if (![width, baselineHeight, preferredHeight].every(finitePositive)) { abort(); return; }
+    const key = `${contractRevision}:${normalize(width)}:${normalize(baselineHeight)}`;
+    if (key !== generation) {
+      abort();
+      generation = key;
+      controller = new AbortController();
+    }
+    const requestHeight = normalize(preferredHeight);
+    if (controller.requestedHeight === requestHeight) return;
+    controller.requestedHeight = requestHeight;
+    const requestController = controller;
+    const requestSerial = ++serial;
+    queueMicrotask(() => {
+      if (destroyed || requestController.signal.aborted || requestSerial !== serial || requestController !== controller) return;
+      try {
+        const returned = adapter.requestPreferredHeight(Object.freeze({
+          preferredHeight: requestHeight,
+          baselineHeight: normalize(baselineHeight),
+          width: normalize(width),
+          signal: requestController.signal,
+        }));
+        // Promise fulfillment is not an acknowledgement. Rejection is observed only
+        // to prevent an unhandled host error; it never retries or changes layout state.
+        if (returned && typeof returned.then === "function") Promise.resolve(returned).catch((error) => {
+          safeReport(error, { operation: "request", width: normalize(width), baselineHeight: normalize(baselineHeight), preferredHeight: requestHeight });
+        });
+      } catch (error) {
+        safeReport(error, { operation: "request", width: normalize(width), baselineHeight: normalize(baselineHeight), preferredHeight: requestHeight });
+      }
+    });
+  };
+
+  return Object.freeze({ baseline, commit, abort, destroy() { if (destroyed) return; destroyed = true; abort(); serial += 1; } });
+}

package/src/layout.js

@@ -1,3 +1,5 @@
+import { SCREEN_PROJECT_LEGIBILITY_FLOORS } from "./screen-legibility.js";
+
 const clamp = (value, minimum, maximum) => Math.max(minimum, Math.min(maximum, value));
 
 export const MIN_CANVAS_WIDTH = 320;
@@ -16,11 +18,11 @@ export function deriveLayout(width, height) {
     scale,
     plot: { left, right: width - right, top, bottom: height - bottom },
     font: {
-      title: clamp(19 * scale, 13, 22),
+      title: clamp(19 * scale, 14, 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),
+      signature: clamp(10 * scale, narrow ? SCREEN_PROJECT_LEGIBILITY_FLOORS.compactProvenancePx : 7.5, 11),
     },
     provenance: { left, right: width - right, y: height - clamp(12 * scale, 10, 16) },
   };

package/src/marks.js

@@ -116,9 +116,9 @@ export function drawAxes(context, { config, layout, scales, xTicks, yTicks, xCat
   context.textAlign = "center";
   context.textBaseline = "top";
   if (xCategories) {
-    xCategories.forEach((label, index) => context.fillText(label, scales.x(index), plot.bottom + 10 * layout.scale));
+    xCategories.forEach((label, index) => context.fillText(label, scales.x(index), layout.text?.xTickY ?? plot.bottom + 10 * layout.scale));
   } else {
-    xTicks.forEach((value) => context.fillText(formatTick(value), scales.x(value), plot.bottom + 10 * layout.scale));
+    xTicks.forEach((value) => context.fillText(formatTick(value), scales.x(value), layout.text?.xTickY ?? plot.bottom + 10 * layout.scale));
   }
 
   if (spec.xLabel) {

package/src/paper-profile.js

@@ -1,4 +1,5 @@
 import { colorContrast, hexToOklab, resolveContrastColor } from "./color-space.js";
+import { resolveScreenTheme } from "./screen-legibility.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 });
@@ -72,7 +73,10 @@ export function resolvePaperTheme(source) {
 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 (key !== "paper") {
+    if (source.mode === "paper") return Object.freeze({ theme: clone(source), report: null });
+    return resolveScreenTheme(clone(source));
+  }
   if (source.mode === "paper") return Object.freeze({ theme: clone(source), report: auditPaperTheme(source) });
   return resolvePaperTheme(source);
 }

package/src/renderers/scatter.js

@@ -1,6 +1,7 @@
 import { arrival, numericScales } from "./shared.js";
 import { compileProgress, drawAxes, drawScopePoint, drawText, pointMotionState } from "../marks.js";
 import { styleForSeries } from "../series-style.js";
+import { linearFit } from "../statistics.js";
 
 export function prepareScatter(contract) {
   const keys = [...new Set(contract.data.series)];
@@ -13,8 +14,8 @@ export function drawScatter(context, env) {
   drawAxes(context, { config: contract, layout, scales, xTicks: scales.xTicks, yTicks: scales.yTicks });
   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.x = state.finalX; state.y = state.finalY; } drawScopePoint(context, state, { color: style.color, edge: style.edge, radius: Math.max(3.5, Math.sqrt(contract.profile.markerSize) * 0.64 * layout.scale) * (presentation.markerScale ?? 1), trailAlpha: contract.motion.trailAlpha, settled: settled || contract.view?.motion === "semantic", shape: style.glyph }); });
   if (contract.data.summary === "linear_fit") {
-    const n = prepared.points.length, sx = prepared.points.reduce((a,p)=>a+p.x,0), sy = prepared.points.reduce((a,p)=>a+p.y,0), sxx = prepared.points.reduce((a,p)=>a+p.x*p.x,0), sxy = prepared.points.reduce((a,p)=>a+p.x*p.y,0);
-    const slope = (n*sxy-sx*sy)/(n*sxx-sx*sx || 1), intercept=(sy-slope*sx)/n, cp=compileProgress(progress, contract.timeline), x0=scales.xDomain[0], x1=x0+(scales.xDomain[1]-x0)*cp;
+    const { slope, intercept } = linearFit(prepared.points.map((point) => point.x), prepared.points.map((point) => point.y));
+    const cp=compileProgress(progress, contract.timeline), x0=scales.xDomain[0], x1=x0+(scales.xDomain[1]-x0)*cp;
     context.save();
     if (contract.theme.summaryEdge) { context.strokeStyle=contract.theme.summaryEdge; context.globalAlpha=.62*cp; context.lineWidth=Math.max(2,2.8*layout.scale); context.beginPath(); context.moveTo(scales.x(x0),scales.y(intercept+slope*x0)); context.lineTo(scales.x(x1),scales.y(intercept+slope*x1)); context.stroke(); }
     context.strokeStyle=contract.theme.summaryCore; context.globalAlpha=.72*cp; context.lineWidth=Math.max(1,1.5*layout.scale); context.beginPath(); context.moveTo(scales.x(x0),scales.y(intercept+slope*x0)); context.lineTo(scales.x(x1),scales.y(intercept+slope*x1)); context.stroke(); context.restore();

package/src/resolved-scene.js

@@ -1,4 +1,5 @@
 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 +55,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);
 }
@@ -113,6 +126,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,10 +246,14 @@ 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);
     else if (panel.renderer === "scatter") marks = scatterGeometry(panel, axes, radius);
@@ -222,7 +261,7 @@ export function resolveTerminalScene(scene, options = {}) {
     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) };
   });

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 };
+}