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

package/README.md

@@ -1,7 +1,9 @@
 # @figurestead/web experimental public alpha
 
+This README targets `0.9.0-alpha.3`. Registry commands require that exact version to be available; review candidates are installed from their retained tarball. To follow the prerelease channel intentionally, use `npm install @figurestead/web@alpha`; an unqualified install follows `latest`, not necessarily this alpha.
+
 ```sh
-npm install @figurestead/web@0.9.0-alpha.2
+npm install @figurestead/web@0.9.0-alpha.3
 ```
 
 The package root provides Figurestead's accepted core rendering and custom
@@ -24,7 +26,7 @@ files after installing `@figurestead/web` and run them through a normal ESM
 browser tool such as Vite.
 
 ```sh
-npm install @figurestead/web@0.9.0-alpha.2
+npm install @figurestead/web@0.9.0-alpha.3
 ```
 
 <!-- figurestead-npm-first-success:index.html -->
@@ -100,7 +102,7 @@ curated subpaths are `registration-ink`, `ultraviolet-laboratory`,
 `deep-observatory-sage-core` under `@figurestead/web/themes/`.
 
 The declarations and all six curated-theme subpaths above are included in
-`@figurestead/web@0.9.0-alpha.2`.
+`@figurestead/web@0.9.0-alpha.3`.
 
 Python and browser surfaces share normalized contract vocabulary and selected
 theme definitions. Shared semantics do not imply pixel-identical output or
@@ -108,6 +110,16 @@ identical renderer coverage. In particular, the populated categorical matrix
 is currently Python-rendered; this package does not claim a browser categorical
 matrix renderer.
 
+## Line identity and direct labels
+
+Default line series combine color with persistent open **circle (S1), square (S2), and upright triangle (S3)** markers and matching line-and-marker legends. Line rhythm remains an independent semantic channel. `setData` retains established keyed identity through supported filtering/reordering and partial style overrides. `setConfig` replaces the contract.
+
+Lavender Fog Notebook is the reference light theme; Ultraviolet Laboratory is the reference dark theme for the [bounded three-series line profile](https://github.com/CharlesMish/figurestead/blob/main/docs/reference-themes.md), not universal accessibility, CVD or print qualification. Product defaults are unchanged.
+
+Opt in with `style: { ...contract.style, directLabels: true }` (`style.directLabels: true`). Direct labels reuse the actual body marker identity beside the traces. V1 covers ordinary one-panel, 2–3-series line figures with single-line printable ASCII labels. Unsupported or insufficient layouts fall back atomically to the ordinary legend. This treatment does not support Unicode, multiline or math interpretation; printable ASCII math punctuation is literal. Active browser transitions use ordinary treatment until settled, and exports without trustworthy measurement retain the ordinary legend.
+
+See the [ordinary/direct-label example](https://github.com/CharlesMish/figurestead/tree/main/examples/direct-series-labels) and [detailed direct-label contract](https://github.com/CharlesMish/figurestead/blob/main/docs/direct-series-labels.md). The [explicit rendered-series contrast audit](https://github.com/CharlesMish/figurestead/blob/main/docs/rendered-series-contrast.md) measures caller-specified rendering facts separately from the static palette audit.
+
 ## Controller failures
 
 `setConfig(next)` is transactional: a validation, compilation, renderer
@@ -180,4 +192,27 @@ preferred height is never inferred as the next baseline by Figurestead.
 Height negotiation applies only to live Canvas rendering. SVG, paper, and
 explicitly dimensioned exports retain their requested dimensions.
 
-Version 0.9.0-alpha.2. [Source and full project documentation](https://github.com/CharlesMish/figurestead).
+Version 0.9.0-alpha.3. [Source and full project documentation](https://github.com/CharlesMish/figurestead).
+
+## Rendered series contrast
+
+`contrastAudit(theme)` remains a static authored-palette inspection.
+`renderedSeriesAudit(theme, { substrate, opacity, compositing: "srgb-source-over" })`
+measures the supplied theme's series colors in the caller-supplied single-layer
+context. The opaque `#RRGGBB` substrate and opacity in [0,1] are required; no
+renderer/surface defaults are inferred. Results retain unrounded effective sRGB
+channels and ratio. The exact policy is `passes = ratio >= 3`, without an epsilon
+or display-rounding rule. Values effectively on the floating-point threshold may
+classify differently across Python/JavaScript final ULPs; this is not physical
+certification. Figures and colors are never changed.
+
+Nonempty **theme-level** `seriesEdges` are conservatively rejected. Per-series
+contract/style overrides can independently change the rendered color or add an
+edge; they are not inspected by that theme-level check. The caller must account
+for those overrides before interpreting the result as a rendered-mark measurement.
+
+Verified Canvas line **segments** use panel or field with effective .78 (Firefox
+exposes its float32 value); SVG line **segments** use panel or field at 1. Python's
+verified default line **polyline** uses field/.88. Companion markers/points may
+have different opacity and are outside those contexts. This is not an assessment
+of glow, antialias boundaries, every layered mark or whole-figure accessibility.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@figurestead/web",
-  "version": "0.9.0-alpha.2",
+  "version": "0.9.0-alpha.3",
   "private": false,
   "type": "module",
   "license": "MIT",

package/src/canvas-scene.js

@@ -1,13 +1,12 @@
+import { DIRECT_FONT } from "./direct-labels.js";
+import { appendMarkerPath, clipOwnLine, lineMarkerGeometry } from "./line-identity.js";
 import { partitionPanelMarks, withCanvasPlotClip } from "./render-layers.js";
 
 const FONT_STACK = "ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', monospace";
 
 function markerPath(context, glyph, x, y, radius) {
   context.beginPath();
-  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.arc(x, y, radius, 0, Math.PI * 2);
+  appendMarkerPath(context, glyph, x, y, radius);
 }
 
 function mixPoint(a, b, t) { return { x: a.x + (b.x - a.x) * t, y: a.y + (b.y - a.y) * t }; }
@@ -72,7 +71,18 @@ function drawAxes(context, panel, theme) {
   context.restore();
 }
 
+function drawDirectLabels(context, plan, theme) {
+  context.save(); context.font = `${plan.font}px ${DIRECT_FONT}`; context.textAlign = "left"; context.textBaseline = "alphabetic"; context.direction = "ltr";
+  for (const e of plan.entries) {
+    if (e.leader) { const l=e.leader;context.globalAlpha=1;context.strokeStyle=l.color;context.lineWidth=.7;context.setLineDash([]);context.beginPath();context.moveTo(l.x1,l.y1);context.lineTo(l.x2,l.y2);context.stroke(); }
+    drawPoint(context, {...e.marker, motion:{opacity:1,scaleX:1,scaleY:1,translateX:0,translateY:0}});
+    context.globalAlpha=1;context.fillStyle=theme.label;context.fillText(e.label,e.textX,e.textY);
+  }
+  context.restore();
+}
+
 function drawLegend(context, panel, theme) {
+  if (panel.directLabelPlan?.status === "placed") return drawDirectLabels(context, panel.directLabelPlan, theme);
   if (panel.presentation?.legend === "none" || !panel.legend.length) return;
   const { layout } = panel, outside = layout.legend.outside;
   context.save(); context.font = `${layout.font.legend}px ${FONT_STACK}`; context.textBaseline = "middle";
@@ -82,8 +92,17 @@ function drawLegend(context, panel, theme) {
     const x = entry?.markerX ?? (outside ? layout.legend.left : layout.plot.right - 24 * layout.scale);
     const textX = entry?.textX ?? (outside ? x + 12 * layout.scale : x - 10 * layout.scale);
     const y = entry?.y ?? (outside ? layout.legend.top + (14 + index * 20) * layout.scale : insideTop + index * 20 * layout.scale);
-    context.strokeStyle = style.edge ?? style.color ?? theme.series[item.colorIndex % theme.series.length]; context.lineWidth = Math.max(1, 1.2 * layout.scale);
-    markerPath(context, style.glyph ?? "ring", x, y, 4 * layout.scale); context.stroke();
+    if (panel.renderer === "line") {
+      const geometry = { cx: x, cy: y, ...lineMarkerGeometry(style, layout.scale, panel.presentation?.markerScale ?? 1) };
+      const point = { lineIdentity: true, style, geometry, motion: { opacity: 1, scaleX: 1, scaleY: 1, translateX: 0, translateY: 0 } };
+      const half = 12 * Math.max(1, layout.scale);
+      drawLine(context, { style, geometry: { x1: x - half, y1: y, x2: x + half, y2: y }, motion: { opacity: 1, clip: 1 } }, theme, [point],
+        { left: x - half - 3, right: x + half + 3, top: y - 10, bottom: y + 10 });
+      drawPoint(context, point);
+    } else {
+      context.strokeStyle = style.edge ?? style.color ?? theme.series[item.colorIndex % theme.series.length]; context.lineWidth = Math.max(1, 1.2 * layout.scale);
+      markerPath(context, style.glyph ?? "ring", x, y, 4 * layout.scale); context.stroke();
+    }
     context.fillStyle = theme.label;
     context.textAlign = entry?.textAnchor ?? (outside ? "left" : "right"); context.fillText(entry?.displayLabel ?? item.label, textX, y);
   });
@@ -166,16 +185,29 @@ function drawBandKey(context, panel, theme) {
 
 function drawPoint(context, mark) {
   const motion = mark.motion, g = mark.geometry, x = g.cx + motion.translateX, y = g.cy + motion.translateY, radius = g.radius * Math.min(motion.scaleX, motion.scaleY);
-  context.save(); context.globalAlpha = motion.opacity; context.strokeStyle = mark.style.edge ?? mark.style.color; context.lineWidth = Math.max(1.6, radius * 0.58);
+  context.save(); context.globalAlpha = motion.opacity;
+  if (mark.lineIdentity) {
+    context.setLineDash([]);
+    context.strokeStyle = mark.style.edge ?? mark.style.color;
+    context.lineWidth = g.outlineWidth + (mark.style.edge ? 1.3 : 0);
+    markerPath(context, mark.style.glyph, x, y, radius); context.stroke();
+    if (mark.style.edge) {
+      context.strokeStyle = mark.style.color; context.lineWidth = g.outlineWidth;
+      markerPath(context, mark.style.glyph, x, y, radius); context.stroke();
+    }
+    context.restore(); return;
+  }
+  context.strokeStyle = mark.style.edge ?? mark.style.color; context.lineWidth = Math.max(1.6, radius * 0.58);
   markerPath(context, mark.style.glyph, x, y, radius); context.stroke();
   context.strokeStyle = mark.style.color; context.lineWidth = Math.max(0.9, radius * 0.24); markerPath(context, mark.style.glyph, x, y, radius); context.stroke();
   if (motion.glow > 0) { context.globalAlpha = motion.glow; context.lineWidth = radius; markerPath(context, mark.style.glyph, x, y, radius * 1.45); context.stroke(); }
   context.restore();
 }
 
-function drawLine(context, mark, theme) {
+function drawLine(context, mark, theme, markers = [], plot = null) {
   const motion = mark.motion;
   context.save(); context.globalAlpha = motion.opacity * (theme.mode === "paper" ? 1 : 0.78); context.strokeStyle = mark.style.edge ?? mark.style.color;
+  if (markers.length) clipOwnLine(context, markers, plot);
   context.lineWidth = Math.max(1, (mark.style.lineWidth ?? 1.6) + (mark.style.edge ? 1.3 : 0));
   context.setLineDash?.(mark.style.lineStyle === "dash" ? [7, 4] : mark.style.lineStyle === "dot" ? [2, 4] : mark.style.lineStyle === "dash-dot" ? [8, 3, 2, 3] : []);
   strokeSegment(context, mark.geometry, motion.clip);
@@ -298,7 +330,9 @@ export function drawResolvedPanel(context, frame, panelIndex) {
   const drawMark = (mark) => {
     if (!mark.geometry || mark.motion.opacity <= 0) return;
     if (mark.kind === "point") drawPoint(context, mark);
-    else if (["segment", "summary-line"].includes(mark.kind)) drawLine(context, mark, theme);
+    else if (["segment", "summary-line"].includes(mark.kind)) drawLine(context, mark, theme,
+      panel.renderer === "line" ? panel.marks.filter(p => p.lineIdentity && p.series === mark.series) : [],
+      panel.axes.plot ?? panel.layout.plot);
     else if (mark.kind === "median-rule") drawLine(context, mark, theme);
     else if (mark.kind === "bar") drawBar(context, mark, theme);
     else if (mark.kind === "cell") drawCell(context, mark, theme, panel.layout.font.axis);

package/src/composition.js

@@ -54,14 +54,22 @@ function fitText(value, maxWidth, fontSize) {
   return `${text.slice(0, Math.max(1, maxChars - 1))}…`;
 }
 
+function lineLegendStep(panel) {
+  // Body-sized markers need unscaled clearance even in compact layouts.
+  const halfHeight = panel.marks.filter(mark => mark.lineIdentity)
+    .reduce((size, mark) => Math.max(size, mark.geometry.radius + mark.geometry.outlineWidth / 2), 0);
+  return 2 * halfHeight + 4;
+}
+
 function legendDimensions(panel) {
   const scale = panel.layout.scale;
   const font = panel.layout.font.legend;
   const plot = panel.axes.plot ?? panel.layout.plot;
   const labelWidth = panel.legend.reduce((width, item) => Math.max(width, String(item.label).length * font * 0.62), 0);
   return {
-    width: Math.min(Math.max(72 * scale, labelWidth + 34 * scale), Math.max(24, plot.right - plot.left - 24 * scale)),
-    height: Math.min(Math.max(18 * scale, (12 + Math.max(0, panel.legend.length - 1) * 20) * scale), Math.max(18, plot.bottom - plot.top - 24 * scale)),
+    width: Math.min(Math.max(72 * scale, labelWidth + (panel.renderer === "line" ? 56 * Math.max(1, scale) : 34 * scale)), Math.max(24, plot.right - plot.left - 24 * scale)),
+    height: Math.min(panel.renderer === "line" ? lineLegendStep(panel) * panel.legend.length
+      : Math.max(18 * scale, (12 + Math.max(0, panel.legend.length - 1) * 20) * scale), Math.max(18, plot.bottom - plot.top - 24 * scale)),
   };
 }
 
@@ -83,14 +91,15 @@ function legendScore(panel, box) {
 function legendEntries(panel, box, position, outside) {
   const scale = panel.layout.scale, right = position.endsWith("right"), markerInset = 8 * scale;
   const count = panel.legend.length;
-  const topInset = Math.min(12 * scale, box.height / 2);
-  const bottomInset = Math.min(8 * scale, box.height / 2);
-  const step = count > 1 ? Math.min(20 * scale, Math.max(1, (box.height - topInset - bottomInset) / (count - 1))) : 0;
+  const lineStep = panel.renderer === "line" ? lineLegendStep(panel) : null;
+  const topInset = Math.min(lineStep == null ? 12 * scale : lineStep / 2, box.height / 2);
+  const bottomInset = Math.min(lineStep == null ? 8 * scale : lineStep / 2, box.height / 2);
+  const step = count > 1 ? Math.min(lineStep ?? 20 * scale, Math.max(1, (box.height - topInset - bottomInset) / (count - 1))) : 0;
   return panel.legend.map((item, index) => {
     const y = clamp(box.top + topInset + index * step, box.top, box.bottom);
-    const textAnchor = outside || !right ? "start" : "end";
-    const markerX = textAnchor === "start" ? box.left + markerInset : box.right - markerInset;
-    const textX = textAnchor === "start" ? box.left + 20 * scale : box.right - 20 * scale;
+    const textAnchor = panel.renderer === "line" || outside || !right ? "start" : "end";
+    const markerX = panel.renderer === "line" ? box.left + 18 * Math.max(1, scale) : textAnchor === "start" ? box.left + markerInset : box.right - markerInset;
+    const textX = panel.renderer === "line" ? box.left + 36 * Math.max(1, scale) : textAnchor === "start" ? box.left + 20 * scale : box.right - 20 * scale;
     const maxTextWidth = Math.max(8, textAnchor === "start" ? box.right - textX : textX - box.left);
     return { markerX, textX, y, textAnchor, displayLabel: fitText(item.label, maxTextWidth, panel.layout.font.legend) };
   });
@@ -194,6 +203,7 @@ export function composeResolvedScene(resolvedScene) {
     ...resolvedScene,
     schemaVersion: COMPOSED_SCENE_VERSION,
     resolvedSceneVersion: resolvedScene.schemaVersion,
+    ...(resolvedScene.fallbackScene ? { fallbackScene: composeResolvedScene(resolvedScene.fallbackScene) } : {}),
     panels,
   };
   result.compositionAudit = auditComposition(result);

package/src/create-matrix-plot.js

@@ -25,8 +25,8 @@ export function createFigurestead(canvas, input, options = {}) {
   const media = globalThis.matchMedia?.("(prefers-reduced-motion: reduce)");
   const isReduced = () => reducedOverride == null ? Boolean(media?.matches) : Boolean(reducedOverride);
 
-  const prepareModel = (candidate) => {
-    const model = compileFigureModel(candidate, { registry });
+  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 applyModel = (model) => {
@@ -37,9 +37,10 @@ export function createFigurestead(canvas, input, options = {}) {
     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 };
+    return { width: value.width, ascent: value.actualBoundingBoxAscent, descent: value.actualBoundingBoxDescent, left: value.actualBoundingBoxLeft, right: value.actualBoundingBoxRight };
   };
   const observedBox = () => {
     const rect = canvas.getBoundingClientRect();
@@ -79,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 });
@@ -109,8 +110,8 @@ export function createFigurestead(canvas, input, options = {}) {
   const mediaChange = () => { if (reducedOverride == null) isReduced() ? clock.settle() : clock.render(clock.progress); };
   document.addEventListener("visibilitychange", visibility); media?.addEventListener?.("change", mediaChange);
 
-  const replace = (next) => {
-    const nextModel = prepareModel(next);
+  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);
@@ -127,8 +128,21 @@ export function createFigurestead(canvas, input, options = {}) {
   };
   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); },
+    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; heightNegotiator.destroy(); clock.destroy(); resizeObserver?.disconnect(); intersectionObserver?.disconnect(); document.removeEventListener("visibilitychange", visibility); media?.removeEventListener?.("change", mediaChange); companion.destroy(); },

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.2";
+export const FIGURESTEAD_PACKAGE_VERSION = "0.9.0-alpha.3";
 
 function sorted(value) {
   if (Array.isArray(value)) return value.map(sorted);

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/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/resolved-scene.js

@@ -1,3 +1,5 @@
+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";
@@ -94,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) => {
@@ -104,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}`);
@@ -255,7 +260,7 @@ export function resolveTerminalScene(scene, options = {}) {
       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; }
@@ -265,11 +270,24 @@ export function resolveTerminalScene(scene, options = {}) {
     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/schema.js

@@ -315,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/svg-export.js

@@ -1,3 +1,5 @@
+import { DIRECT_FONT } from "./direct-labels.js";
+import { lineMarkerGeometry } from "./line-identity.js";
 import { CORE_REGISTRY } from "./core-renderers.js";
 import { compileTerminalScene, evidenceFingerprint } from "./terminal-scene.js";
 import { resolveTerminalScene } from "./resolved-scene.js";
@@ -28,17 +30,29 @@ function svgNamespace(composed, scene, options) {
 }
 
 function dash(style) { return style === "dash" ? "7 4" : style === "dot" ? "2 4" : style === "dash-dot" ? "8 3 2 3" : null; }
-function marker(mark) {
-  const { cx, cy, radius } = mark.geometry, common = { "data-mark-id": mark.id, fill: "none", stroke: mark.style.color, "stroke-width": 1.5 };
+function marker(mark, appearance = null) {
+  const { cx, cy, radius } = mark.geometry, common = { "data-mark-id": mark.id, fill: "none", stroke: mark.style.color, "stroke-width": mark.lineIdentity ? mark.geometry.outlineWidth : 1.5, ...appearance };
   if (mark.style.glyph === "square") return `<rect ${attrs({ ...common, x: cx - radius, y: cy - radius, width: radius * 2, height: radius * 2 })}/>`;
   if (mark.style.glyph === "triangle") return `<path ${attrs({ ...common, d: `M ${cx} ${cy - radius} L ${cx + radius} ${cy + radius} L ${cx - radius} ${cy + radius} Z` })}/>`;
   if (mark.style.glyph === "diamond") return `<path ${attrs({ ...common, d: `M ${cx} ${cy - radius} L ${cx + radius} ${cy} L ${cx} ${cy + radius} L ${cx - radius} ${cy} Z` })}/>`;
   return `<circle ${attrs({ ...common, cx, cy, r: radius })}/>`;
 }
 
-function segment(mark) {
+function segment(mark, extra = {}) {
   const g = mark.geometry, d = g.c1x == null ? `M ${g.x1} ${g.y1} L ${g.x2} ${g.y2}` : `M ${g.x1} ${g.y1} C ${g.c1x} ${g.c1y} ${g.c2x} ${g.c2y} ${g.x2} ${g.y2}`;
-  return `<path ${attrs({ "data-mark-id": mark.id, d, fill: "none", stroke: mark.style.color, "stroke-width": mark.style.lineWidth ?? 1.6, "stroke-dasharray": dash(mark.style.lineStyle), "stroke-linecap": "round" })}/>`;
+  return `<path ${attrs({ "data-mark-id": mark.id, d, fill: "none", stroke: mark.style.color, "stroke-width": mark.style.lineWidth ?? 1.6, "stroke-dasharray": dash(mark.style.lineStyle), "stroke-linecap": "round", ...extra })}/>`;
+}
+
+function linePoint(mark) {
+  const edge = mark.style.edge ? marker(mark, { stroke: mark.style.edge, "stroke-width": mark.geometry.outlineWidth + 1.3 }) : "";
+  return edge + marker(mark);
+}
+
+function maskedLine(mark, points, bounds, id) {
+  // Luminance mask is applied only to this series' line (never the panel/grid).
+  const mask = `<mask ${attrs({ id, maskUnits: "userSpaceOnUse", x: bounds.left, y: bounds.top, width: bounds.right - bounds.left, height: bounds.bottom - bounds.top, "mask-type": "luminance" })}><rect ${attrs({ x: bounds.left, y: bounds.top, width: bounds.right - bounds.left, height: bounds.bottom - bounds.top, fill: "white" })}/>${points.map(p => marker(p, { fill: "black", stroke: "none", "data-mark-id": null })).join("")}</mask>`;
+  const edge = mark.style.edge ? segment(mark, { stroke: mark.style.edge, "stroke-width": mark.style.lineWidth + 1.3 }) : "";
+  return `<defs>${mask}</defs><g mask="url(#${esc(id)})">${edge}${segment(mark)}</g>`;
 }
 
 function bar(mark, theme) {
@@ -156,7 +170,12 @@ function axes(panel, theme) {
   return pieces.join("");
 }
 
-function legend(panel, theme) {
+function legend(panel, theme, namespace) {
+  if (panel.directLabelPlan?.status === "placed") return panel.directLabelPlan.entries.map(e => {
+    const l=e.leader;
+    return (l ? `<path ${attrs({d:`M ${l.x1} ${l.y1} L ${l.x2} ${l.y2}`,fill:"none",stroke:l.color,"stroke-width":.7})}/>` : "")
+      + linePoint(e.marker) + `<text ${attrs({x:e.textX,y:e.textY,fill:theme.label,"font-family":DIRECT_FONT,"font-size":panel.directLabelPlan.font,"xml:space":"preserve"})}>${esc(e.label)}</text>`;
+  }).join("");
   if (panel.presentation?.legend === "none") return "";
   const insideTop = panel.layout.plot.bottom - Math.max(14, 14 + (panel.legend.length - 1) * 20) * panel.layout.scale;
   return panel.legend.map((item, index) => {
@@ -164,7 +183,14 @@ function legend(panel, theme) {
     const x = entry?.markerX ?? (panel.layout.legend.outside ? panel.layout.legend.left : panel.layout.plot.right - 24 * panel.layout.scale);
     const textX = entry?.textX ?? (panel.layout.legend.outside ? x + 12 * panel.layout.scale : x - 10 * panel.layout.scale);
     const y = entry?.y ?? (panel.layout.legend.outside ? panel.layout.legend.top + (14 + index * 20) * panel.layout.scale : insideTop + index * 20 * panel.layout.scale), style = item.style ?? {};
-    const point = `<circle ${attrs({ cx: x, cy: y, r: 4 * panel.layout.scale, fill: "none", stroke: style.color ?? theme.series[item.colorIndex % theme.series.length] })}/>`;
+    let point = `<circle ${attrs({ cx: x, cy: y, r: 4 * panel.layout.scale, fill: "none", stroke: style.color ?? theme.series[item.colorIndex % theme.series.length] })}/>`;
+    if (panel.renderer === "line") {
+      const mark = { id: `${panel.id}-legend-${index}`, lineIdentity: true, style,
+        geometry: { cx: x, cy: y, ...lineMarkerGeometry(style, panel.layout.scale, panel.presentation?.markerScale ?? 1) } };
+      const half = 12 * Math.max(1, panel.layout.scale);
+      point = maskedLine({ ...mark, geometry: { x1: x - half, y1: y, x2: x + half, y2: y } }, [mark],
+        { left: x - half - 3, right: x + half + 3, top: y - 10, bottom: y + 10 }, `${namespace}-${safeId(panel.id)}-legend-${index}`) + linePoint(mark);
+    }
     const label = entry?.displayLabel ?? item.label;
     return `${point}<text ${attrs({ x: textX, y, fill: theme.label, "font-size": panel.layout.font.legend, "text-anchor": entry?.textAnchor ?? (panel.layout.legend.outside ? "start" : "end"), "dominant-baseline": "middle", "data-full-label": item.label })}><title>${esc(item.label)}</title>${esc(label)}</text>`;
   }).join("");
@@ -198,7 +224,10 @@ function panelHeaderSvg(panel, theme, responsive) {
 
 function panelSvg(panel, theme, profile, namespace, responsive = null) {
   if (!panel.resolved) throw new TypeError(`SVG export requires a scene-aware renderer; ${panel.renderer} remains on the compatibility path`);
-  const render = (mark) => mark.kind === "point" ? marker(mark)
+  const render = (mark) => panel.renderer === "line" && mark.kind === "segment"
+    ? maskedLine(mark, panel.marks.filter(p => p.lineIdentity && p.series === mark.series), plotClipRect(panel), `${namespace}-${safeId(panel.id)}-${hashText(mark.id)}-identity`)
+    : mark.lineIdentity ? linePoint(mark)
+    : mark.kind === "point" ? marker(mark)
     : ["segment", "summary-line"].includes(mark.kind) ? segment(mark)
       : mark.kind === "median-rule" ? segment(mark)
       : mark.kind === "bar" ? bar(mark, theme)
@@ -220,7 +249,7 @@ function panelSvg(panel, theme, profile, namespace, responsive = null) {
   const title = panelHeaderSvg(panel, theme, responsive);
   const provenance = theme.mode !== "paper" && panel.spec.signature && (panel.layout.panelIndex ?? 0) === 0
     ? `<text ${attrs({ x: panel.layout.provenance?.left ?? panel.layout.plot.left, y: panel.layout.provenance?.y ?? panel.layout.rect.bottom - 8 * panel.layout.scale, fill: theme.faint, "font-size": panel.layout.font.signature, "text-anchor": "start", "data-layer": "provenance" })}>${esc(panel.spec.signature)}</text>` : "";
-  return `<g ${attrs({ "data-panel-id": panel.id, "data-renderer": panel.renderer, "data-denominator": panel.denominator == null ? null : JSON.stringify(panel.denominator), "data-x-category-order": panel.categories.x?.join("|"), "data-y-category-order": panel.categories.y?.join("|") })}><defs><clipPath id="${esc(clipId)}" clipPathUnits="userSpaceOnUse"><rect ${attrs({ x: plot.left, y: plot.top, width: plot.right - plot.left, height: plot.bottom - plot.top })}/></clipPath></defs><g data-layer="surface">${panelSurface(panel, theme)}</g><g data-layer="grid">${grid(panel, theme, profile)}</g>${renderLayer("reference", layers.reference)}${renderLayer("data", dataMarks)}${renderLayer("summary", layers.summary)}<g data-layer="axes">${title}${axes(panel, theme)}${provenance}</g><g data-layer="annotations">${dataLabels}${annotations(panel, theme)}</g><g data-layer="legend">${legend(panel, theme)}${matrixLegend(panel, theme, namespace)}${denominator}</g></g>`;
+  return `<g ${attrs({ "data-panel-id": panel.id, "data-renderer": panel.renderer, "data-denominator": panel.denominator == null ? null : JSON.stringify(panel.denominator), "data-x-category-order": panel.categories.x?.join("|"), "data-y-category-order": panel.categories.y?.join("|") })}><defs><clipPath id="${esc(clipId)}" clipPathUnits="userSpaceOnUse"><rect ${attrs({ x: plot.left, y: plot.top, width: plot.right - plot.left, height: plot.bottom - plot.top })}/></clipPath></defs><g data-layer="surface">${panelSurface(panel, theme)}</g><g data-layer="grid">${grid(panel, theme, profile)}</g>${renderLayer("reference", layers.reference)}${renderLayer("data", dataMarks)}${renderLayer("summary", layers.summary)}<g data-layer="axes">${title}${axes(panel, theme)}${provenance}</g><g data-layer="annotations">${dataLabels}${annotations(panel, theme)}</g><g data-layer="legend">${legend(panel, theme, namespace)}${matrixLegend(panel, theme, namespace)}${denominator}</g></g>`;
 }
 
 export function resolvedSceneToSvg(resolved, options = {}) {

package/src/terminal-scene.js

@@ -3,7 +3,7 @@ import { CORE_REGISTRY } from "./core-renderers.js";
 import { panelContract } from "./figure.js";
 import { resolvePanelDomains } from "./figure.js";
 import { resolveApplicationProfile } from "./application-profiles.js";
-import { legendWithStyles, resolveSeriesStyles } from "./series-style.js";
+import { collectSeriesKeys, legendWithStyles, resolveSeriesStyles } from "./series-style.js";
 import { compileMotionPlan, assertTerminalMotionIdentity } from "./motion-plan.js";
 import { auditPaperTheme, themeResolutionForProfile } from "./paper-profile.js";
 import { validateEvidenceCoverage } from "./evidence-coverage.js";
@@ -117,6 +117,9 @@ export function compileFigureModel(input, options = {}) {
     ...panel,
     presentation: { ...profilePresentation(applicationProfile), ...(panel.presentation ?? {}) },
   }));
+  if (contract.style.directLabels && contract.panels.some(p => p.presentation.legend === "none")) throw new TypeError("directLabels requires the ordinary legend for fallback");
+  const directRanks = new Map(options.directRanks ?? []);
+  if (contract.style.directLabels) for (const key of collectSeriesKeys(contract)) if (!directRanks.has(key)) directRanks.set(key, directRanks.size);
   const styles = resolveSeriesStyles(contract);
   contract.seriesStyles = styles;
   contract.appearanceReport = applicationProfile.key === "paper" ? {
@@ -149,10 +152,15 @@ export function compileFigureModel(input, options = {}) {
       notes: [child.spec.note, ...(child.annotations ?? []).filter((item) => item?.type === "scientific_note").map((item) => item.text)].filter(Boolean),
       legend: compiled.legend ?? legendWithStyles(legend, keys, styles),
       meta: compiled.meta ?? null,
+      ...(contract.style.directLabels ? { directLabelsInput: { data: panel.renderer === "line" ? { ...child.data, series: child.data.series.map((s,i) => {
+        const authored = (input.panels?.[panelIndex]?.data ?? input.data)?.series?.[i];
+        return { ...s, label: authored && Object.hasOwn(authored,"label") ? authored.label : s.label };
+      }) } : child.data, ranks: Object.fromEntries(directRanks), pose: !!panel.presentation.curve && panel.presentation.curve !== "linear" || !!panel.presentation.seriesMarkers } } : {}),
       marks: defaultMarks,
     };
   });
   const scene = {
+    ...(contract.style.directLabels ? { directLabels: true, directRanks: Object.fromEntries(directRanks) } : {}),
     schemaVersion: TERMINAL_SCENE_VERSION,
     contractSchemaVersion: contract.schemaVersion,
     rendererApiVersion: contract.rendererApiVersion,

package/src/theme-pack.js

@@ -251,6 +251,7 @@ export function contrastRatio(left, right) {
   return colorContrast(left, right);
 }
 
+/** Authored palette inspection; does not model renderer compositing. */
 export function contrastAudit(theme) {
   if (theme.mode === "paper") return auditPaperTheme(theme).findings;
   const findings = [];
@@ -266,3 +267,33 @@ export function contrastAudit(theme) {
   });
   return findings;
 }
+
+/** Supplied theme series colors in a caller-supplied single-layer context.
+ * Theme-level seriesEdges reject; contract/style overrides are not inspected.
+ * Callers must account for effective mark colors/layers before claiming rendered
+ * contrast. Verified line segments do not include companion markers/points.
+ * No defaults: encoded-sRGB blend, then luminance; passes = ratio >= 3 exactly.
+ * Final ULPs may differ across runtimes; this is not physical certification.
+ */
+export function renderedSeriesAudit(theme, context) {
+  object(context, "renderContext");
+  const fields = ["substrate", "opacity", "compositing"];
+  if (Object.keys(context).length !== fields.length || fields.some(key => !hasOwn(context, key))) {
+    throw new FiguresteadConfigError("requires exactly substrate, opacity, compositing", "renderContext");
+  }
+  const { substrate, opacity, compositing } = context;
+  if (typeof substrate !== "string" || substrate.length !== 7 || !COLOR.test(substrate)) throw new FiguresteadConfigError("must be an opaque #RRGGBB color", "renderContext.substrate");
+  if (typeof opacity !== "number" || !Number.isFinite(opacity) || opacity < 0 || opacity > 1) throw new FiguresteadConfigError("must be a finite number in [0, 1]", "renderContext.opacity");
+  if (compositing !== "srgb-source-over") throw new FiguresteadConfigError("must be srgb-source-over", "renderContext.compositing");
+  if (theme.seriesEdges?.length) throw new FiguresteadConfigError("layered series edges are not supported by this single-layer audit", "theme.seriesEdges");
+  if (!Array.isArray(theme.series) || !theme.series.length || theme.series.some(c => typeof c !== "string" || c.length !== 7 || !COLOR.test(c))) throw new FiguresteadConfigError("must contain opaque #RRGGBB colors", "theme.series");
+  const background = hexChannels(substrate).map(c => c / 255);
+  const luminance = channels => channels.map(c => c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4)
+    .reduce((sum, c, i) => sum + c * [0.2126, 0.7152, 0.0722][i], 0);
+  const back = luminance(background);
+  return theme.series.map((color, index) => {
+    const effectiveColor = hexChannels(color).map((c, i) => opacity * c / 255 + (1 - opacity) * background[i]);
+    const front = luminance(effectiveColor), ratio = (Math.max(front, back) + 0.05) / (Math.min(front, back) + 0.05);
+    return { token: `series[${index}]`, color, substrate, opacity, compositing, effectiveColor, ratio, minimum: 3, passes: ratio >= 3 };
+  });
+}

package/types/index.d.ts

@@ -162,6 +162,8 @@ export interface SeriesStyleOverride {
 }
 
 export interface FiguresteadStyle {
+  /** Opt-in single-panel terminal line labels; ordinary legend on unsupported/failed fit. */
+  directLabels?: boolean;
   glyphs: MarkerGlyph[];
   lineStyles: LineStyle[];
   series: Record<string, SeriesStyleOverride>;
@@ -529,7 +531,7 @@ export function evidenceFingerprint(scene: TerminalScene): string;
 export const RESOLVED_SCENE_VERSION: "figurestead.resolved-scene/1";
 export const RESOLVED_RENDERERS: readonly string[];
 export function isResolvedRenderer(renderer: string): boolean;
-export function resolveTerminalScene(scene: TerminalScene, options?: { width?: number; height?: number; measureText?: (text: string, fontSize: number) => { width: number; ascent?: number; descent?: number } }): ResolvedScene;
+export function resolveTerminalScene(scene: TerminalScene, options?: { width?: number; height?: number; measureText?: (text: string, fontSize: number) => { width: number; ascent?: number; descent?: number; left?: number; right?: number } }): ResolvedScene;
 export function resolveSceneFrame(scene: ResolvedScene, progress?: number): ResolvedScene;
 export function resolveSceneFrame(scene: ComposedScene, progress?: number): ComposedScene;
 export function resolvedTerminalGeometry(scene: ResolvedScene | ComposedScene): UnknownRecord[];
@@ -609,6 +611,29 @@ export function validatePalettePack(input: PalettePack): UnknownRecord;
 export function resolvePalette(pack: PalettePack, key: string, options?: { mode?: ApplicationProfileKey }): UnknownRecord & { theme: FiguresteadTheme };
 export function contrastRatio(left: CanonicalColor, right: CanonicalColor): number;
 export function contrastAudit(theme: FiguresteadTheme): UnknownRecord[];
+/** Caller-supplied single-layer facts; no renderer, substrate or opacity defaults. */
+export interface SeriesRenderContext {
+  substrate: CanonicalColor;
+  opacity: number;
+  compositing: "srgb-source-over";
+}
+export interface RenderedSeriesContrast {
+  token: string;
+  color: CanonicalColor;
+  substrate: CanonicalColor;
+  opacity: number;
+  compositing: "srgb-source-over";
+  /** Unrounded encoded sRGB channels, each in [0, 1]. */
+  effectiveColor: number[];
+  ratio: number;
+  minimum: 3;
+  passes: boolean;
+}
+/** Rejects nonempty theme-level seriesEdges, not contract/style overrides.
+ * Caller must account for effective colors/layers. Line segment contexts exclude
+ * companion markers. Unrounded ratio >= 3; final ULPs may differ across runtimes.
+ */
+export function renderedSeriesAudit(theme: FiguresteadTheme, context: SeriesRenderContext): RenderedSeriesContrast[];
 
 export const RENDER_LAYER_ORDER: readonly string[];
 export function renderLayerForMark(mark: UnknownRecord): string;