npm - @figurestead/web - Versions diffs - 0.9.0-alpha.1 → 0.9.0-alpha.2 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (33) hide show

package/README.md +179 -5
package/THIRD_PARTY_NOTICES.md +12 -5
package/package.json +42 -5
package/src/accessibility.js +51 -11
package/src/canvas-scene.js +12 -5
package/src/clock.js +19 -8
package/src/core-renderers.js +9 -3
package/src/create-matrix-plot.js +86 -30
package/src/export-bundle.js +1 -1
package/src/extensions/temporal/shared.js +1 -1
package/src/figure-layout.js +3 -2
package/src/height-negotiation.js +77 -0
package/src/layout.js +4 -2
package/src/marks.js +2 -2
package/src/paper-profile.js +5 -1
package/src/renderers/scatter.js +3 -2
package/src/resolved-scene.js +42 -3
package/src/responsive-header.js +159 -0
package/src/schema.js +32 -9
package/src/scientific-layout.js +148 -0
package/src/screen-legibility.js +30 -0
package/src/statistics.js +21 -0
package/src/svg-export.js +23 -8
package/src/terminal-scene.js +2 -3
package/themes/deep_observatory_sage_core.json +28 -0
package/themes/lavender_fog_notebook.json +29 -0
package/themes/midnight_transit_signal_slate.json +28 -0
package/themes/registration_ink.json +28 -0
package/themes/slipware.json +28 -0
package/themes/ultraviolet_laboratory.json +29 -0
package/types/extensions/temporal.d.ts +45 -0
package/types/index.d.ts +640 -0
package/types/theme-json.d.ts +4 -0

package/README.md CHANGED Viewed

@@ -1,9 +1,183 @@
 # @figurestead/web experimental public alpha
+```sh
+npm install @figurestead/web@0.9.0-alpha.2
+```
 The package root provides Figurestead's accepted core rendering and custom
-renderer-registry APIs. `EXTENSION_RENDERERS` and `FIGURESTEAD_REGISTRY` are
-not root exports. The complete temporal extension is available from
-`@figurestead/web/extensions/temporal`.
+renderer-registry APIs. The complete temporal extension is available from
+`@figurestead/web/extensions/temporal`; it is intentionally not a root export.
+This package ships first-party TypeScript declarations for the root and
+temporal surfaces. Import contract, controller, option, state, error, theme,
+and temporal types directly from those package entrypoints—no downstream
+declaration shim or shadow schema is needed. TypeScript provides structural
+guidance; runtime validation remains authoritative for semantic constraints
+such as finite data, ordered domains, canonical colors, and matching
+cardinalities.
+Rendering requires a complete normalized figure contract. The repository's
+[runnable browser first-success example](https://github.com/CharlesMish/figurestead/tree/main/examples/browser-first-success)
+remains useful for source development. An installed-package consumer can render
+the same small scientific line without cloning the repository. Save these two
+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
+```
+<!-- figurestead-npm-first-success:index.html -->
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <title>Figurestead first success</title>
+    <style>
+      body { margin: 24px; background: #f1eee5; }
+      canvas { display: block; width: min(100%, 760px); height: auto; background: #fffdfa; }
+    </style>
+  </head>
+  <body>
+    <canvas id="figure" width="760" height="520" aria-label="Three-point Figurestead line example"></canvas>
+    <script type="module" src="./main.js"></script>
+  </body>
+</html>
+```
+<!-- figurestead-npm-first-success:main.js -->
+```js
+import {
+  createFigurestead,
+  resolveTheme,
+  validateThemePack,
+} from "@figurestead/web";
+import slipwarePack from "@figurestead/web/themes/slipware" with { type: "json" };
+const theme = resolveTheme(validateThemePack(slipwarePack), "slipware");
+const contract = {
+  schemaVersion: "0.4",
+  rendererApiVersion: "1",
+  theme,
+  profile: { key: "first_success", name: "First success", marker: "ring_core", markerSize: 42, markerAlpha: 0.84, edgeWidth: 1.05, coreFraction: 0.12, pointGlow: false, gridX: true, gridY: true, gridAlpha: 0.4, summaryGlow: false },
+  timeline: { rainIn: [0, 0], marksEnter: [0, 1], summaryCompiles: [0.8, 1], rainOut: [0, 0], settle: [0.9, 1] },
+  motion: { frames: 1, fps: 1, rainStreams: 0, rainGlyphs: 0, lightingPeak: 0, trailAlpha: 0, seed: 1, durationMs: 1 },
+  style: { glyphs: ["ring", "square", "triangle", "diamond"], lineStyles: ["solid", "dash", "dot", "dash-dot"], series: {} },
+  spec: { title: "Figurestead first success", subtitle: "One deterministic normalized line contract", xLabel: "observation", yLabel: "response", signature: "figurestead · first success", description: "One line with three observations." },
+  layout: { type: "grid", columns: 1, gap: 18, sharedX: false, sharedY: false },
+  view: { profile: "atlas", motion: "none", ambient: "none", strategy: "none" },
+  panels: [{ id: "line", renderer: "line", spec: { title: "Figurestead first success", xLabel: "observation", yLabel: "response", description: "One line with three observations." }, xScale: { type: "linear" }, yScale: { type: "linear" }, annotations: [], encoding: { interpolation: "linear" }, presentation: { panelSurface: true, frame: true, legend: "none", lineWidth: 2, markerScale: 1 }, data: { x: [0, 1, 2], revealOrder: "x", series: [{ key: "series-1", label: "Series 1", y: [0, 1, 0] }] } }],
+};
+const canvas = document.querySelector("#figure");
+const figure = createFigurestead(canvas, contract, { autoplay: false, reducedMotion: true });
+figure.resize();
+document.documentElement.dataset.figuresteadReady = "true";
+```
+This package also ships six curated theme subpaths generated byte-for-byte from
+Figurestead's canonical theme JSON rather than retyped as JavaScript constants.
+For example, in Node or TypeScript:
+```ts
+import {
+  applyTheme,
+  resolveTheme,
+  type FiguresteadContract,
+} from "@figurestead/web";
+import slipwarePack from "@figurestead/web/themes/slipware" with { type: "json" };
+export function withSlipware(contract: FiguresteadContract): FiguresteadContract {
+  return applyTheme(contract, resolveTheme(slipwarePack, "slipware"));
+}
+```
+The same explicit subpath works through the tested Vite browser route. Other
+curated subpaths are `registration-ink`, `ultraviolet-laboratory`,
+`lavender-fog-notebook`, `midnight-transit-signal-slate`, and
+`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`.
+Python and browser surfaces share normalized contract vocabulary and selected
+theme definitions. Shared semantics do not imply pixel-identical output or
+identical renderer coverage. In particular, the populated categorical matrix
+is currently Python-rendered; this package does not claim a browser categorical
+matrix renderer.
+## Controller failures
+`setConfig(next)` is transactional: a validation, compilation, renderer
+preparation, scene-resolution, composition, or accessibility-description error
+leaves the last accepted contract, scenes, pixels, companion, and motion state
+active. The original configuration error is thrown to the caller.
+Hosts may observe asynchronous renderer failures with the existing creation
+options pattern:
+```js
+const figure = createFigurestead(canvas, contract, {
+  onError(error, context) {
+    // context.phase is "draw" or "height-negotiation".
+    // error is the original renderer or host-callback error object.
+  },
+});
+```
+After a draw failure the controller is stopped, reports `playing: false` and
+`runtimeFailed: true`, and will not redraw through play, replay, resize, or
+reduced-motion changes. A later valid `setConfig()` clears that state and
+renders normally. Lifecycle notifications remain on `onState`; runtime failures
+are reported only through `onError`.
+## Responsive headers and host-owned height
+At compact live-Canvas widths, Figurestead preserves the established plot
+geometry and uses a bounded two-line title plus a one-line ellipsized subtitle
+when the host does not opt in to more height. Complete strings remain in the
+associated accessibility companion. Figurestead never changes host CSS by
+default.
+An auto-height host may opt in with one mount-scoped adapter. Figurestead's
+current measurement convention is the CSS-pixel border box reported by
+`canvas.getBoundingClientRect()` (including any reflected CSS transform). Retain
+the baseline independently in that same measurement space; do not derive it
+from the canvas after applying an earlier request:
+```js
+const baselineHeight = 196;
+const figure = createFigurestead(canvas, contract, {
+  heightNegotiation: {
+    getBaselineHeight() { return baselineHeight; },
+    requestPreferredHeight({ preferredHeight, signal }) {
+      if (!signal.aborted) canvas.style.height = `${preferredHeight}px`;
+    },
+  },
+});
+```
+State-driven or delayed hosts may apply on a later frame. The return value is
+not an acknowledgement; the host applies the absolute height and Figurestead's
+existing resize observation resolves the granted layout:
+```js
+requestPreferredHeight({ preferredHeight, signal }) {
+  requestAnimationFrame(() => {
+    if (!signal.aborted) canvas.style.height = `${preferredHeight}px`;
+  });
+}
+```
+Accepted contract, width, baseline, remount, and destroy transitions abort the
+prior signal. A host may decline or clamp a request; the fixed-height fallback
+then remains active without automatic retry in that generation. Host-applied
+CSS remains host state after `destroy()`. Before remount, the host either keeps
+that height intentionally or restores its independent baseline source; residual
+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.1. Source:
-<https://github.com/CharlesMish/figurestead/tree/main/web>.
+Version 0.9.0-alpha.2. [Source and full project documentation](https://github.com/CharlesMish/figurestead).

package/THIRD_PARTY_NOTICES.md CHANGED Viewed

@@ -25,11 +25,18 @@ only system font families and carries no downloaded font bytes or remote URL.
 ## Browser tooling observations
-The alpha verification environment used Playwright 1.61.1 and
-playwright-core 1.61.1 as
-Apache-2.0 development/test tooling and optional fsevents 2.3.2 as MIT. These
-packages and downloaded browsers are not intended npm-tarball members or
-top-level archive members. They remain test-tool provenance only.
+The alpha verification environment uses Playwright 1.62.0 and
+playwright-core 1.62.0 as Apache-2.0 development/test tooling, TypeScript 7.0.2
+as Apache-2.0 declaration-conformance tooling, and Vite 8.2.1 as MIT browser
+package-consumer tooling. Vite's resolved test-only tree includes rolldown
+1.2.4, @rolldown/pluginutils 1.0.1, @oxc-project/types 0.144.0, fdir 6.5.0,
+nanoid 3.3.18, picocolors 1.1.1, picomatch 4.0.5, postcss 8.5.26,
+source-map-js 1.2.1, tinyglobby 0.2.17, detect-libc 2.1.2, and optional native
+bindings recorded exactly in `package-lock.json`; lightningcss 1.33.0 is
+MPL-2.0 and the remaining listed Vite-tree packages use the licenses recorded
+in that lock. Optional fsevents resolves as 2.3.2 and 2.3.3 in the applicable
+tool trees. These packages and downloaded browsers are not intended npm-tarball
+members or top-level archive members. They remain test-tool provenance only.
 ## Placement and maintenance

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@figurestead/web",
-  "version": "0.9.0-alpha.1",
+  "version": "0.9.0-alpha.2",
   "private": false,
   "type": "module",
   "license": "MIT",
@@ -15,17 +15,54 @@
     "url": "https://github.com/CharlesMish/figurestead/issues"
   },
   "engines": {
-    "node": ">=24 <25"
+    "node": ">=22.22.0"
   },
+  "types": "./types/index.d.ts",
   "exports": {
-    ".": "./src/index.js",
-    "./extensions/temporal": "./src/extensions/temporal/index.js"
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./extensions/temporal": {
+      "types": "./types/extensions/temporal.d.ts",
+      "import": "./src/extensions/temporal/index.js"
+    },
+    "./themes/slipware": {
+      "types": "./types/theme-json.d.ts",
+      "default": "./themes/slipware.json"
+    },
+    "./themes/registration-ink": {
+      "types": "./types/theme-json.d.ts",
+      "default": "./themes/registration_ink.json"
+    },
+    "./themes/ultraviolet-laboratory": {
+      "types": "./types/theme-json.d.ts",
+      "default": "./themes/ultraviolet_laboratory.json"
+    },
+    "./themes/lavender-fog-notebook": {
+      "types": "./types/theme-json.d.ts",
+      "default": "./themes/lavender_fog_notebook.json"
+    },
+    "./themes/midnight-transit-signal-slate": {
+      "types": "./types/theme-json.d.ts",
+      "default": "./themes/midnight_transit_signal_slate.json"
+    },
+    "./themes/deep-observatory-sage-core": {
+      "types": "./types/theme-json.d.ts",
+      "default": "./themes/deep_observatory_sage_core.json"
+    }
   },
   "files": [
     "src",
+    "types",
+    "themes",
     "LICENSE",
     "README.md",
     "THIRD_PARTY_NOTICES.md",
     "TRADEMARKS.md"
-  ]
+  ],
+  "scripts": {
+    "prepack": "node scripts/curated-themes.mjs stage",
+    "postpack": "node scripts/curated-themes.mjs clean"
+  }
 }

package/src/accessibility.js CHANGED Viewed

@@ -1,16 +1,31 @@
 const el = (name, text) => { const node = document.createElement(name); if (text != null) node.textContent = text; return node; };
-function appendTable(root, panel, description) {
+function appendTable(root, panel, description, { interactive = false } = {}) {
   if (!description?.headers?.length || !Array.isArray(description.rows)) return;
-  const details = el("details"), summary = el("summary", `View ${panel.spec.title || panel.renderer} data`), table = el("table");
+  const table = el("table");
   table.append(el("caption", `${panel.spec.title || panel.renderer} data`));
   const head = el("thead"), body = el("tbody"), headingRow = el("tr");
   description.headers.forEach((value) => headingRow.append(el("th", value))); head.append(headingRow);
   description.rows.forEach((row) => { const tr = el("tr"); row.forEach((value, index) => { const cell = el(index === 0 ? "th" : "td", String(value)); if (index === 0) cell.scope = "row"; tr.append(cell); }); body.append(tr); });
-  table.append(head, body); details.append(summary, table); root.append(details);
+  table.append(head, body);
+  if (!interactive) { root.append(table); return; }
+  const details = el("details"), summary = el("summary", `View ${panel.spec.title || panel.renderer} data`);
+  details.append(summary, table); root.append(details);
 }
-export function createAccessibilityCompanion(canvas, contract, registry, { visible = false, table = true } = {}) {
+function annotationCoordinates(item, composedPanel, focusIndex) {
+  const composed = composedPanel?.composedAnnotations?.[focusIndex];
+  if (!item.anchorId) return composed?.status === "authored-coordinate" ? { x: item.x, y: item.y } : null;
+  if (!composed?.boundMarkId) return null;
+  const mark = composedPanel.marks?.find((candidate) => candidate.id === composed.boundMarkId);
+  if (!mark) return null;
+  const x = mark.x ?? mark.group ?? mark.xCategory ?? mark.evidence?.x ?? mark.evidence?.group;
+  const y = mark.y ?? mark.yCategory ?? mark.evidence?.y ?? mark.evidence?.yCategory;
+  const usable = (value) => (typeof value === "number" && Number.isFinite(value)) || (typeof value === "string" && value.length > 0);
+  return usable(x) && usable(y) ? { x, y } : null;
+}
+export function prepareAccessibilityCompanion(canvas, contract, registry, { visible = false, table = true, composedScene = null } = {}) {
   const id = `figurestead-${Math.random().toString(36).slice(2)}`, root = el("section");
   root.className = visible ? "figurestead-accessibility" : "figurestead-accessibility figurestead-sr-only";
   if (!visible) Object.assign(root.style, { position: "absolute", width: "1px", height: "1px", padding: "0", margin: "-1px", overflow: "hidden", clip: "rect(0, 0, 0, 0)", whiteSpace: "nowrap", border: "0" });
@@ -18,16 +33,41 @@ export function createAccessibilityCompanion(canvas, contract, registry, { visib
   if (contract.spec.subtitle) root.append(el("p", contract.spec.subtitle));
   const description = el("p", contract.spec.description || `${contract.panels.length}-panel scientific figure.`); description.id = `${id}-description`; root.append(description);
   contract.panels.forEach((panel, index) => {
-    const section = el("section"), heading = el("h3", panel.spec.title || `${panel.renderer.replaceAll("_", " ")} panel`), definition = registry.get(panel.renderer), described = definition.describe({ ...contract, renderer: panel.renderer, spec: { ...contract.spec, ...panel.spec }, data: panel.data });
-    heading.id = `${id}-panel-${index + 1}`; section.setAttribute("aria-labelledby", heading.id); section.append(heading);
+    const section = el("section"), panelTitle = panel.spec.title || `${panel.renderer.replaceAll("_", " ")} panel`, definition = registry.get(panel.renderer), described = definition.describe({ ...contract, renderer: panel.renderer, spec: { ...contract.spec, ...panel.spec }, data: panel.data }), composedPanel = composedScene?.panels?.[index];
+    const repeatsContractTitle = contract.panels.length === 1 && panelTitle.trim() === contract.spec.title.trim();
+    if (repeatsContractTitle) section.setAttribute("aria-labelledby", title.id);
+    else {
+      const heading = el("h3", panelTitle); heading.id = `${id}-panel-${index + 1}`;
+      section.setAttribute("aria-labelledby", heading.id); section.append(heading);
+    }
     if (panel.spec.description || described.summary) section.append(el("p", panel.spec.description || described.summary));
-    panel.annotations.filter((item) => item?.type === "focus" && typeof item.label === "string" && item.label.trim()).forEach((item) => {
-      section.append(el("p", `Focus annotation: ${item.label} at x ${item.x}, y ${item.y}.`));
+    panel.annotations.filter((item) => item?.type === "focus" && typeof item.label === "string" && item.label.trim()).forEach((item, focusIndex) => {
+      const coordinates = annotationCoordinates(item, composedPanel, focusIndex);
+      const suffix = coordinates ? ` at x ${coordinates.x}, y ${coordinates.y}.` : ".";
+      section.append(el("p", `Focus annotation: ${item.label}${suffix}`));
     });
     const dl = el("dl");
     [["Horizontal axis", panel.spec.xLabel || panel.xScale.label || "Unlabelled"], ["Vertical axis", panel.spec.yLabel || panel.yScale.label || "Unlabelled"], ["Renderer", panel.renderer.replaceAll("_", " ")]].forEach(([term, value]) => dl.append(el("dt", term), el("dd", value)));
-    section.append(dl); if (table) appendTable(section, panel, described); root.append(section);
+    section.append(dl); if (table) appendTable(section, panel, described, { interactive: visible }); root.append(section);
   });
-  canvas.setAttribute("role", "img"); canvas.setAttribute("aria-labelledby", `${title.id} ${description.id}`); canvas.after(root);
-  return { root, destroy() { root.remove(); canvas.removeAttribute("role"); canvas.removeAttribute("aria-labelledby"); } };
+  const labelledBy = `${title.id} ${description.id}`;
+  let attached = false;
+  return {
+    root,
+    attach() {
+      if (attached) return;
+      canvas.setAttribute("role", "img"); canvas.setAttribute("aria-labelledby", labelledBy); canvas.after(root); attached = true;
+    },
+    destroy() {
+      root.remove();
+      if (canvas.getAttribute("aria-labelledby") === labelledBy) { canvas.removeAttribute("role"); canvas.removeAttribute("aria-labelledby"); }
+      attached = false;
+    },
+  };
+}
+export function createAccessibilityCompanion(canvas, contract, registry, options) {
+  const companion = prepareAccessibilityCompanion(canvas, contract, registry, options);
+  companion.attach();
+  return companion;
 }

package/src/canvas-scene.js CHANGED Viewed

@@ -57,12 +57,13 @@ function drawAxes(context, panel, theme) {
   context.lineWidth = Math.max(0.6, 0.85 * layout.scale);
   context.strokeStyle = theme.spine; context.beginPath(); context.moveTo(plot.left, plot.top); context.lineTo(plot.left, plot.bottom); context.lineTo(plot.right, plot.bottom); context.stroke();
   const xSlot = axes.x.step?.() ?? Math.max(40, (plot.right - plot.left) / Math.max(1, axes.xTicks.length));
-  const rotateX = axes.xType === "band" && axes.xTicks.some((tick) => context.measureText(tick.label).width > xSlot * 0.92);
+  const rotateX = layout.text?.rotateX ?? (axes.xType === "band" && axes.xTicks.some((tick) => context.measureText(tick.label).width > xSlot * 0.92));
   context.textAlign = rotateX ? "right" : "center"; context.textBaseline = "top";
   axes.xTicks.forEach((tick) => {
     const x = tickPosition(axes.x, tick), label = fitLabel(context, tick.label, rotateX ? xSlot * 1.75 : xSlot * 0.92);
-    if (rotateX) { context.save(); context.translate(x, plot.bottom + 7 * layout.scale); context.rotate(-Math.PI / 4); context.fillText(label, 0, 0); context.restore(); }
-    else context.fillText(label, x, plot.bottom + 7 * layout.scale);
+    const y = layout.text?.xTickY ?? plot.bottom + 7 * layout.scale;
+    if (rotateX) { context.save(); context.translate(x, y); context.rotate(-Math.PI / 4); context.fillText(label, 0, 0); context.restore(); }
+    else context.fillText(label, x, y);
   });
   context.textAlign = "right"; context.textBaseline = "middle";
   axes.yTicks.forEach((tick) => context.fillText(fitLabel(context, tick.label, Math.max(26, plot.left - layout.rect.left - 12 * layout.scale)), plot.left - 7 * layout.scale, tickPosition(axes.y, tick)));
@@ -132,8 +133,14 @@ function drawPanelText(context, panel, theme) {
   const { layout, spec } = panel;
   context.save(); context.textAlign = "left"; context.textBaseline = "alphabetic";
   context.fillStyle = theme.mode === "paper" ? theme.label : theme.primary; context.font = `500 ${layout.font.title}px ${FONT_STACK}`;
-  context.fillText(spec.title || panel.renderer, layout.plot.left, layout.text?.titleY ?? layout.rect.top + 20 * layout.scale);
-  if (spec.subtitle) { context.fillStyle = theme.secondary; context.font = `italic ${layout.font.subtitle}px ${FONT_STACK}`; context.fillText(spec.subtitle, layout.plot.left, layout.text?.subtitleY ?? layout.rect.top + 39 * layout.scale); }
+  const responsive = layout.headerText;
+  if (responsive) responsive.title.lines.forEach((line, index) => context.fillText(line, layout.plot.left, responsive.title.baselines[index]));
+  else context.fillText(spec.title || panel.renderer, layout.plot.left, layout.text?.titleY ?? layout.rect.top + 20 * layout.scale);
+  if (spec.subtitle) {
+    context.fillStyle = theme.secondary; context.font = `italic ${layout.font.subtitle}px ${FONT_STACK}`;
+    if (responsive) responsive.subtitle.lines.forEach((line, index) => context.fillText(line, layout.plot.left, responsive.subtitle.baselines[index]));
+    else context.fillText(spec.subtitle, layout.plot.left, layout.text?.subtitleY ?? layout.rect.top + 39 * layout.scale);
+  }
   if (theme.mode !== "paper" && spec.signature && (layout.panelIndex ?? 0) === 0) {
     const provenance = layout.provenance ?? { left: layout.plot.left, y: layout.rect.bottom - 8 * layout.scale };
     context.fillStyle = theme.faint; context.font = `${layout.font.signature}px ${FONT_STACK}`; context.textAlign = "left";

package/src/clock.js CHANGED Viewed

@@ -1,27 +1,38 @@
 const clamp = (value) => Math.max(0, Math.min(1, value));
 export class AnimationClock {
-  constructor({ durationMs, draw, onState = () => {}, raf = globalThis.requestAnimationFrame?.bind(globalThis), cancel = globalThis.cancelAnimationFrame?.bind(globalThis) }) {
-    this.durationMs = durationMs; this.draw = draw; this.onState = onState;
+  constructor({ durationMs, draw, onState = () => {}, onError = null, raf = globalThis.requestAnimationFrame?.bind(globalThis), cancel = globalThis.cancelAnimationFrame?.bind(globalThis) }) {
+    this.durationMs = durationMs; this.draw = draw; this.onState = onState; this.onError = typeof onError === "function" ? onError : null;
     this.raf = raf || ((fn) => setTimeout(() => fn(performance.now()), 16));
     this.cancel = cancel || clearTimeout; this.progress = 0; this.playing = false;
-    this.frame = null; this.startedAt = null; this.destroyed = false;
+    this.frame = null; this.startedAt = null; this.destroyed = false; this.failed = false;
+  }
+  fail(error) {
+    this.playing = false; this.frame = null; this.startedAt = null; this.failed = true;
+    if (!this.onError) throw error;
+    try { this.onError(error, Object.freeze({ phase: "draw", progress: this.progress })); } catch { /* Error reporting must not reopen or destabilize the draw loop. */ }
+  }
+  render(progress = this.progress) {
+    if (this.destroyed || this.failed) return false;
+    this.progress = clamp(progress);
+    try { this.draw(this.progress); } catch (error) { this.fail(error); return false; }
+    return true;
   }
-  render(progress = this.progress) { this.progress = clamp(progress); this.draw(this.progress); }
   play() {
-    if (this.destroyed || this.playing || this.progress >= 1) return;
+    if (this.destroyed || this.failed || this.playing || this.progress >= 1) return;
     this.playing = true; this.startedAt = null; this.onState("playing");
     const tick = (now) => {
       if (!this.playing || this.destroyed) return;
       if (this.startedAt == null) this.startedAt = now - this.progress * this.durationMs;
-      this.render((now - this.startedAt) / this.durationMs);
+      if (!this.render((now - this.startedAt) / this.durationMs)) return;
       if (this.progress >= 1) { this.playing = false; this.frame = null; this.onState("complete"); return; }
       this.frame = this.raf(tick);
     };
     this.frame = this.raf(tick);
   }
   pause() { if (!this.playing) return; this.playing = false; if (this.frame != null) this.cancel(this.frame); this.frame = null; this.onState("paused"); }
-  replay() { this.pause(); this.render(0); this.play(); }
-  settle() { this.pause(); this.render(1); this.onState("complete"); }
+  replay() { this.pause(); if (this.render(0)) this.play(); }
+  settle() { this.pause(); if (this.render(1)) this.onState("complete"); }
+  resetFailure() { this.failed = false; }
   destroy() { this.pause(); this.destroyed = true; this.draw = () => {}; }
 }

package/src/core-renderers.js CHANGED Viewed

@@ -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]]]) }; },
 };