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

package/src/core-renderers.js

@@ -5,9 +5,15 @@ import { prepareLine, drawLine } from "./renderers/line.js";
 import { prepareScatter, drawScatter } from "./renderers/scatter.js";
 import { prepareStrip, drawStrip, compileStripScene } from "./renderers/strip-summary.js";
 
+// Core numeric axes have one precedence rule: the authored scale constraint,
+// then the retained renderer-data override, then the finite data extent.
+export const resolveNumericDomain = (contract, axis, automaticDomain) => (
+  contract[`${axis}Scale`]?.domain ?? contract.data[`${axis}Domain`] ?? automaticDomain
+);
+
 const pointDomains = (contract, prepared) => ({
-  x: contract.data.xDomain || extent(prepared.points.map((point) => point.x)),
-  y: contract.data.yDomain || extent(prepared.points.map((point) => point.y)),
+  x: resolveNumericDomain(contract, "x", extent(prepared.points.map((point) => point.x))),
+  y: resolveNumericDomain(contract, "y", extent(prepared.points.map((point) => point.y))),
 });
 
 export const LINE_RENDERER = {
@@ -25,7 +31,7 @@ export const SCATTER_RENDERER = {
 export const STRIP_RENDERER = {
   key: "strip_summary", family: "distribution", apiVersion: RENDERER_API_VERSION,
   validateData: normalizeStripData, prepare: prepareStrip, compileScene: compileStripScene, draw: drawStrip,
-  domains(contract, prepared) { return { x: [-0.5, contract.data.groups.length - 0.5], y: contract.data.yDomain || extent(prepared.points.map((point) => point.y)) }; },
+  domains(contract, prepared) { return { x: [-0.5, contract.data.groups.length - 0.5], y: resolveNumericDomain(contract, "y", extent(prepared.points.map((point) => point.y))) }; },
   describe(contract) { return { summary: `${contract.data.values.length} observations across ${contract.data.groups.length} ordered groups.`, headers: ["group", contract.spec.yLabel || "value", "series"], rows: contract.data.values.map((value, index) => [contract.data.group[index], value, contract.data.seriesLabels[contract.data.series[index]]]) }; },
 };
 

package/src/create-matrix-plot.js

@@ -5,34 +5,71 @@ 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, retainRanks = true) => {
+    const model = compileFigureModel(candidate, { registry, directRanks: retainRanks ? Object.entries(scene?.directRanks ?? {}) : [] });
+    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`;
+    surface.context.textAlign = "left"; surface.context.textBaseline = "alphabetic"; surface.context.direction = "ltr";
+    const value = surface.context.measureText(String(text));
+    surface.context.restore();
+    return { width: value.width, ascent: value.actualBoundingBoxAscent, descent: value.actualBoundingBoxDescent, left: value.actualBoundingBoxLeft, right: value.actualBoundingBoxRight };
+  };
+  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;
@@ -43,7 +80,7 @@ export function createFigurestead(canvas, input, options = {}) {
     const frame = resolveSceneFrame(composedScene, p);
     preparedPanels.forEach((state, index) => {
       const resolved = isResolvedRenderer(state.panel.renderer);
-      const env = { contract: state.contract, prepared: state.prepared, layout: resolved ? composedScene.panels[index].layout : surface.layout.panels[index], domains: domains[index], progress: p, settled, panel: state.panel, figure: contract, scenePanel: scene.panels[index], motionPlan: scene.motionPlan.panels[index], reducedMotion: isReduced() };
+      const env = { contract: state.contract, prepared: state.prepared, layout: resolved ? frame.panels[index].layout : surface.layout.panels[index], domains: domains[index], progress: p, settled, panel: state.panel, figure: contract, scenePanel: scene.panels[index], motionPlan: scene.motionPlan.panels[index], reducedMotion: isReduced() };
       drawPanelSurface(surface.context, env);
       const scales = resolved ? drawResolvedPanel(surface.context, frame, index) : state.definition.draw(surface.context, env);
       if (!resolved) drawPresentationAnnotations(surface.context, { ...env, scales });
@@ -51,12 +88,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 +107,61 @@ 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 replace = (next, retainRanks = true) => {
+    const nextModel = prepareModel(next, retainRanks);
+    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); },
+    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);
+      // Data-only updates retain established line identities, including filtered keys.
+      // setConfig remains an explicit new style/theme contract.
+      if (contract.panels[0].renderer === "line") {
+        // Merge each override onto its complete established style, not over the key.
+        // Entries absent from this scene retain their saved style (or future override).
+        const retained = Object.fromEntries(Object.entries(scene.seriesStyles).map(([key, style]) =>
+          [key, { ...style, ...next.style.series[key] }]));
+        next.style.series = { ...next.style.series, ...retained };
+      }
+      next.panels[0].data = cloneValue(data); replace(next);
+    },
+    setConfig(next) { replace(next, false); },
+    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/direct-labels.js

@@ -0,0 +1,73 @@
+// Internal screen-down PAVA planner. No renderer presets or detached glyph cycle.
+export const DIRECT_FONT = "ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', monospace";
+export function solveDirectLabels(entries, lo, hi, height, gap = 4) {
+  const ordered = [...entries].sort((a,b)=>a.anchor-b.anchor || a.rank-b.rank);
+  const s=height+gap, low=lo+height/2, high=hi-height/2-(ordered.length-1)*s;
+  if (!ordered.length || high<low) return null;
+  const blocks=[];
+  ordered.forEach((e,i)=>{blocks.push({sum:e.anchor-i*s,n:1});
+    while(blocks.length>1 && blocks.at(-2).sum/blocks.at(-2).n>blocks.at(-1).sum/blocks.at(-1).n) {
+      const b=blocks.pop();blocks.at(-1).sum+=b.sum;blocks.at(-1).n+=b.n;
+    }
+  });
+  const z=blocks.flatMap(b=>Array(b.n).fill(Math.min(high,Math.max(low,b.sum/b.n))));
+  return ordered.map((e,i)=>({...e,center:z[i]+i*s}));
+}
+export function literalLabel(t) {return typeof t==='string' && !!t.trim() && /^[\x20-\x7e]+$/.test(t);}
+function contrast(a,b) {
+  const lum=c=>{const v=c.slice(1).match(/../g).map(x=>parseInt(x,16)/255).map(x=>x<=.04045?x/12.92:((x+.055)/1.055)**2.4);return v[0]*.2126+v[1]*.7152+v[2]*.0722;};
+  const x=lum(a),y=lum(b);return (Math.max(x,y)+.05)/(Math.min(x,y)+.05);
+}
+const fail=reason=>({status:'fallback',reason});
+export function planDirectLabels(scene, resolved, measure) {
+  if(resolved.panels.length!==1) return fail('unsupported-layout');
+  const p=resolved.panels[0], input=p.directLabelsInput, plot=p.axes.plot??p.layout.plot;
+  if(!input || p.renderer!=='line') return fail('unsupported-geometry');
+  const data=input.data;
+  if(data.series.length<2 || data.series.length>3) return fail('unsupported-series-count');
+  if(p.scales.x.type!=='linear'||p.scales.y.type!=='linear'||p.encoding.interpolation!=='linear'
+    ||input.pose || data.x.length<2 || data.x.some((x,i)=>!Number.isFinite(x)||(i>0&&x<=data.x[i-1]))
+    ||p.domain.x[0]>=p.domain.x[1]||p.domain.y[0]>=p.domain.y[1]) return fail('unsupported-geometry');
+  if(!data.series.every(s=>literalLabel(s.label)))return fail('unsupported-text');
+  if(p.annotations.length || !measure || p.layout.headerText || resolved.width<=480) return fail('unsupported-layout');
+  const entries=[];let markerHalf=0,textWidth=0,height=0;
+  for(const s of data.series) {
+    const x=data.x.at(-1),y=s.y.at(-1);
+    // Ordinary compileFigureModel evidence coverage has already admitted all observations.
+    const points=p.marks.filter(m=>m.kind==='point'&&m.series===s.key), point=points.at(-1);
+    if(!point?.lineIdentity || point.x!==x || point.y!==y || !['ring','square','triangle','diamond'].includes(point.style.glyph))return fail('unsupported-geometry');
+    // Native Canvas/SVG polygon strokes use miter joins. Include their tips,
+    // not just radius + half-width (triangle apex extends sqrt(5) half-widths).
+    const join = point.style.glyph==='triangle' ? Math.sqrt(5) : point.style.glyph==='diamond' ? Math.SQRT2 : 1;
+    const g=point.geometry,half=g.radius+join*(g.outlineWidth+(point.style.edge?1.3:0))/2;
+    if(g.cx-half<plot.left||g.cx+half>plot.right||g.cy-half<plot.top||g.cy+half>plot.bottom)return fail('terminal-marker-clipped');
+    let t;
+    try { t=measure(s.label,p.layout.font.legend,'normal'); } catch { return fail('unsupported-layout'); }
+    if(!t || !['width','ascent','descent','left','right'].every(k=>Number.isFinite(t[k])) || t.ascent+t.descent<=0)return fail('unsupported-layout');
+    const inks=[point.style.color,point.style.edge,scene.theme.label].filter(Boolean);
+    if(inks.some(c=>!/^#[0-9a-f]{6}$/i.test(c))) return fail('unsupported-geometry');
+    if(inks.some(c=>contrast(c,scene.theme.field)<3))return fail('ink-contrast');
+    entries.push({key:s.key,label:s.label,anchor:g.cy,rank:input.ranks[s.key],point,text:t,half});
+    markerHalf=Math.max(markerHalf,half);textWidth=Math.max(textWidth,t.left+t.right,t.width);height=Math.max(height,t.ascent+t.descent,half*2);
+  }
+  const H=height+4,required=12+markerHalf*2+6+textWidth+4;
+  const right=p.layout.rect.right-2,shrink=Math.max(0,required-(right-plot.right));
+  if(shrink>.25*(plot.right-plot.left)||plot.right-shrink-plot.left<160)return fail('horizontal-capacity');
+  const planned=solveDirectLabels(entries,plot.top,plot.bottom,H);
+  if(!planned)return fail('vertical-capacity');
+  const newRight=plot.right-shrink, markerX=newRight+12+markerHalf+2,textX=markerX+markerHalf+6;
+  const substrates=[scene.theme.field,p.presentation.panelSurface?scene.theme.panel:scene.theme.field];
+  const leaderColor=[scene.theme.secondary,scene.theme.label].find(c=>substrates.every(b=>contrast(c,b)>=3));
+  const output=[];
+  for(const e of planned) {
+    const anchorX=plot.left+(e.point.geometry.cx-plot.left)*(newRight-plot.left)/(plot.right-plot.left);
+    if(anchorX+e.half>newRight || anchorX-e.half<plot.left)return fail('terminal-marker-clipped');
+    const moved=Math.abs(e.center-e.anchor)>.75;
+    if(moved&&!leaderColor)return fail('ink-contrast');
+    output.push({...e,markerX,textX:textX+e.text.left,textY:e.center+(e.text.ascent-e.text.descent)/2,
+      marker:{...e.point,id:e.point.id+'/direct-label',geometry:{...e.point.geometry,cx:markerX,cy:e.center}},
+      leader:moved?{x1:anchorX+markerHalf+2,y1:e.anchor,x2:markerX-markerHalf-3,y2:e.center,color:leaderColor}:null,
+      box:{left:markerX-markerHalf-2,top:e.center-H/2,right:textX+textWidth+2,bottom:e.center+H/2}});
+  }
+  return {status:'placed',reason:null,entries:output,shrink,plot:{...plot,right:newRight},height:H,font:p.layout.font.legend};
+}

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.3";
 
 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/index.js

@@ -22,7 +22,7 @@ export { THEME_CATALOG_VERSION, auditThemeCatalog, catalogThemePack, mergeThemeP
 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 { THEME_PACK_VERSION, PALETTE_PACK_VERSION, applyTheme, contrastAudit, contrastRatio, renderedSeriesAudit, 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";

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/line-identity.js

@@ -0,0 +1,29 @@
+// Line-only prominence. Glyph identity/rhythm still come from series-style.js.
+// Units are CSS px; the same resolved geometry feeds Canvas and SVG.
+export function lineMarkerGeometry(style, scale = 1, markerScale = 1) {
+  const shapeScale = style.glyph === "square" ? 0.9 : style.glyph === "triangle" ? 1.1 : 1;
+  return { radius: 4.1 * Math.max(1, scale) * markerScale * shapeScale,
+    outlineWidth: 2 * Math.max(1, scale) };
+}
+
+// Append, don't begin: also used inside an own-line-only clipping path.
+export function appendMarkerPath(context, glyph, x, y, radius) {
+  if (glyph === "square") context.rect(x - radius, y - radius, radius * 2, radius * 2);
+  else if (glyph === "triangle") { context.moveTo(x, y - radius); context.lineTo(x + radius, y + radius); context.lineTo(x - radius, y + radius); context.closePath(); }
+  else if (glyph === "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.moveTo(x + radius, y); context.arc(x, y, radius, 0, Math.PI * 2); }
+}
+
+export function clipOwnLine(context, markers, plot) {
+  // Intersect individual complements: overlapping markers remain a union of holes.
+  // A single even-odd path containing every marker would incorrectly XOR overlaps.
+  for (const mark of markers) {
+    const m = mark.motion, g = mark.geometry;
+    if (m.opacity <= 0) continue;
+    context.beginPath();
+    context.rect(plot.left, plot.top, plot.right - plot.left, plot.bottom - plot.top);
+    appendMarkerPath(context, mark.style.glyph, g.cx + m.translateX, g.cy + m.translateY,
+      g.radius * Math.min(m.scaleX, m.scaleY));
+    context.clip("evenodd");
+  }
+}

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();