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

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

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 (38) hide show

package/README.md +214 -5
package/THIRD_PARTY_NOTICES.md +12 -5
package/package.json +42 -5
package/src/accessibility.js +51 -11
package/src/canvas-scene.js +55 -14
package/src/clock.js +19 -8
package/src/composition.js +18 -8
package/src/core-renderers.js +9 -3
package/src/create-matrix-plot.js +104 -34
package/src/direct-labels.js +73 -0
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/index.js +1 -1
package/src/layout.js +4 -2
package/src/line-identity.js +29 -0
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 +64 -7
package/src/responsive-header.js +159 -0
package/src/schema.js +34 -10
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 +60 -16
package/src/terminal-scene.js +11 -4
package/src/theme-pack.js +31 -0
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 +665 -0
package/types/theme-json.d.ts +4 -0

package/README.md CHANGED Viewed

@@ -1,9 +1,218 @@
 # @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.3
+```
 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.3
+```
+<!-- 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.3`.
+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.
+## 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
+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.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.
-Version 0.9.0-alpha.1. Source:
-<https://github.com/CharlesMish/figurestead/tree/main/web>.
+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/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.3",
   "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

@@ -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 }; }
@@ -57,12 +56,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)));
@@ -71,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";
@@ -81,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);
   });
@@ -132,8 +152,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";
@@ -159,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);
@@ -291,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/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/composition.js CHANGED Viewed

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