@figurestead/web 0.9.0-alpha.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Figurestead contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

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

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,39 @@
+# Third-party factual notice inventory
+
+Status: `EXPERIMENTAL PUBLIC-ALPHA FACTUAL NOTICE`
+
+This inventory records the dependency evidence used for the Figurestead
+experimental alpha; it makes no legal conclusion. Runtime dependencies are not
+vendored into the wheel, sdist, or npm tarball. The canonical Figurestead MIT
+text is supplied separately as `LICENSE`.
+
+## Python dependency observations
+
+An external Python 3.14.6 evidence environment resolved the current declared
+constraints on 2026-08-05 to Matplotlib 3.11.1, NumPy 2.5.1, Pillow 12.3.0,
+PyYAML 6.0.3, and setuptools 82.0.1, plus contourpy 1.3.3, cycler 0.12.1,
+fonttools 4.63.0, kiwisolver 1.5.0, packaging 26.3, pyparsing 3.3.2,
+python-dateutil 2.9.0.post0, and six 1.17.0. These versions are an evidence
+snapshot, not an approved runtime lock.
+
+The static-site PNGs are first-party deterministic synthetic Figurestead render
+outputs produced through Matplotlib. No font file is embedded as a separate
+site member. Matplotlib's evidence distribution includes its own license plus
+DejaVu and STIX font notices; rendered glyph provenance remains a review
+consideration. Site CSS names
+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.
+
+## Placement and maintenance
+
+Each Figurestead wheel, sdist, npm package, static-site bundle, and composition
+archive carries this file and `TRADEMARKS.md` beside its canonical `LICENSE`.
+Any newly resolved dependency version, copied source, font, image, or other
+byte requires a corresponding inventory update and review.

package/TRADEMARKS.md

@@ -0,0 +1,13 @@
+# Trademarks and names
+
+Figurestead is an independent project.
+
+Names of third-party products, services, organizations, and trademarks remain
+the property of their respective owners. Their appearance in factual dependency
+or compatibility notices does not imply affiliation, sponsorship, or
+endorsement.
+
+The experimental public-alpha distribution is intentionally limited to six
+curated Figurestead themes.
+Legacy or franchise-derived internal themes are not part of the public
+distribution.

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@figurestead/web",
+  "version": "0.9.0-alpha.1",
+  "private": false,
+  "type": "module",
+  "license": "MIT",
+  "description": "A framework-free scientific figure system for deterministic, inspectable Python and browser output.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CharlesMish/figurestead.git",
+    "directory": "web"
+  },
+  "homepage": "https://github.com/CharlesMish/figurestead#readme",
+  "bugs": {
+    "url": "https://github.com/CharlesMish/figurestead/issues"
+  },
+  "engines": {
+    "node": ">=24 <25"
+  },
+  "exports": {
+    ".": "./src/index.js",
+    "./extensions/temporal": "./src/extensions/temporal/index.js"
+  },
+  "files": [
+    "src",
+    "LICENSE",
+    "README.md",
+    "THIRD_PARTY_NOTICES.md",
+    "TRADEMARKS.md"
+  ]
+}

package/src/accessibility.js

@@ -0,0 +1,33 @@
+const el = (name, text) => { const node = document.createElement(name); if (text != null) node.textContent = text; return node; };
+
+function appendTable(root, panel, description) {
+  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");
+  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);
+}
+
+export function createAccessibilityCompanion(canvas, contract, registry, { visible = false, table = true } = {}) {
+  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" });
+  const title = el("h2", contract.spec.title); title.id = `${id}-title`; root.append(title);
+  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);
+    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}.`));
+    });
+    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);
+  });
+  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"); } };
+}

package/src/appearance.js

@@ -0,0 +1,25 @@
+import { applyApplicationProfile, resolveApplicationProfile } from "./application-profiles.js";
+import { cloneValue } from "./schema.js";
+import { applyTheme, resolvePalette, resolveTheme, themeForProfile } from "./theme-pack.js";
+
+export const APPEARANCE_VERSION = "figurestead.appearance/1";
+
+/**
+ * Resolve profile and palette/theme choices as one deliberate application step.
+ * Scientific data, encodings, domains, notes, and ordering are never rewritten.
+ */
+export function composeAppearance(input, options = {}) {
+  const profile = resolveApplicationProfile(options.profile ?? input.view?.profile ?? "atlas");
+  let result = cloneValue(input);
+  if (options.palettePack) {
+    if (!options.paletteKey) throw new TypeError("composeAppearance requires paletteKey with palettePack");
+    result = applyTheme(result, resolvePalette(options.palettePack, options.paletteKey, { mode: options.mode ?? profile.key }).theme);
+  } else if (options.themePack) {
+    if (!options.themeKey) throw new TypeError("composeAppearance requires themeKey with themePack");
+    result = applyTheme(result, resolveTheme(options.themePack, options.themeKey));
+  } else if (options.theme) {
+    result = applyTheme(result, options.theme);
+  }
+  result.theme = themeForProfile(result.theme, profile);
+  return applyApplicationProfile(result, profile, options);
+}

package/src/application-profiles.js

@@ -0,0 +1,76 @@
+import { cloneValue, FiguresteadConfigError } from "./schema.js";
+
+export const APPLICATION_PROFILE_VERSION = "figurestead.application-profile/1";
+
+const BUILT_INS = {
+  paper: {
+    key: "paper", name: "Paper", surface: "neutral", density: "compact",
+    typography: "publication", legend: "outside", ambient: "none", motion: "none",
+    lineWidth: 1.55, markerScale: 0.92, panelSurface: false, frame: false,
+  },
+  atlas: {
+    key: "atlas", name: "Atlas", surface: "themed", density: "balanced",
+    typography: "scientific", legend: "auto", ambient: "none", motion: "semantic",
+    lineWidth: 2.15, markerScale: 1.12, panelSurface: true, frame: true,
+  },
+  talk: {
+    key: "talk", name: "Talk", surface: "themed", density: "open",
+    typography: "display", legend: "auto", ambient: "none", motion: "semantic",
+    lineWidth: 2.75, markerScale: 1.34, panelSurface: true, frame: true,
+  },
+};
+
+export const APPLICATION_PROFILES = Object.freeze(Object.fromEntries(
+  Object.entries(BUILT_INS).map(([key, value]) => [key, Object.freeze(value)]),
+));
+
+export function resolveApplicationProfile(value = "atlas") {
+  const source = typeof value === "string" ? APPLICATION_PROFILES[value] : value;
+  if (!source || typeof source !== "object" || Array.isArray(source)) {
+    throw new FiguresteadConfigError(`unknown application profile; choose ${Object.keys(APPLICATION_PROFILES).join(", ")}`, "config.view.profile");
+  }
+  const key = source.key;
+  if (!APPLICATION_PROFILES[key] && typeof value === "string") {
+    throw new FiguresteadConfigError(`unknown application profile; choose ${Object.keys(APPLICATION_PROFILES).join(", ")}`, "config.view.profile");
+  }
+  for (const token of ["key", "name", "surface", "density", "typography", "legend", "ambient", "motion"]) {
+    if (typeof source[token] !== "string" || !source[token]) throw new FiguresteadConfigError("must be a non-empty string", `config.view.profile.${token}`);
+  }
+  for (const token of ["lineWidth", "markerScale"]) {
+    if (!Number.isFinite(source[token]) || source[token] <= 0) throw new FiguresteadConfigError("must be a positive number", `config.view.profile.${token}`);
+  }
+  for (const token of ["panelSurface", "frame"]) {
+    if (typeof source[token] !== "boolean") throw new FiguresteadConfigError("must be boolean", `config.view.profile.${token}`);
+  }
+  return Object.freeze(cloneValue(source));
+}
+
+export function applyApplicationProfile(input, profile = "atlas", options = {}) {
+  const result = cloneValue(input), resolved = resolveApplicationProfile(profile);
+  const previous = resolveApplicationProfile(result.view?.profile ?? "atlas");
+  const previousPresentation = {
+    panelSurface: previous.panelSurface, frame: previous.frame,
+    legend: previous.legend === "outside" ? "outside-right" : previous.legend === "auto" ? "auto" : "bottom-right",
+    lineWidth: previous.lineWidth, markerScale: previous.markerScale,
+  };
+  const motion = options.motion ?? resolved.motion;
+  const ambient = options.ambient ?? resolved.ambient;
+  result.view = {
+    profile: resolved.key,
+    motion,
+    ambient,
+    strategy: options.strategy ?? (motion === "semantic" ? "auto" : "none"),
+  };
+  result.panels = result.panels.map((panel) => {
+    const overrides = Object.fromEntries(Object.entries(panel.presentation ?? {}).filter(([key, value]) => previousPresentation[key] !== value));
+    return { ...panel, presentation: {
+      panelSurface: resolved.panelSurface,
+      frame: resolved.frame,
+      legend: options.legend ?? (resolved.legend === "outside" ? "outside-right" : resolved.legend === "auto" ? "auto" : "bottom-right"),
+      lineWidth: resolved.lineWidth,
+      markerScale: resolved.markerScale,
+      ...overrides,
+    } };
+  });
+  return result;
+}

package/src/atmosphere.js

@@ -0,0 +1,71 @@
+import { deriveSeed, mulberry32 } from "./random.js";
+import { smooth } from "./marks.js";
+import { windowProgress } from "./schema.js";
+
+const GLYPHS = [..."0123456789ABCDEFXYZ<>[]{}+=αβ∑∫≈"];
+
+export function prepareAtmosphere(motion) {
+  const random = mulberry32(deriveSeed(motion.seed, "atmosphere"));
+  return Array.from({ length: motion.rainStreams }, () => ({
+    x: 0.02 + random() * 0.96,
+    phase: random() * 1.45,
+    speed: 0.48 + random() * 0.47,
+    spacing: 0.045 + random() * 0.033,
+    base: 0.065 + random() * 0.065,
+    glyphs: Array.from({ length: motion.rainGlyphs }, () => GLYPHS[Math.floor(random() * GLYPHS.length)]),
+  }));
+}
+
+export function atmosphereState(progress, timeline, reducedMotion = false) {
+  if (reducedMotion || progress >= 1) return { rainEnvelope: 0, lightEnvelope: 0 };
+  const rise = smooth(windowProgress(progress, timeline.rainIn));
+  const fall = 1 - smooth(windowProgress(progress, timeline.rainOut));
+  const rainEnvelope = rise * fall;
+  const mark = Math.sin(Math.PI * windowProgress(progress, timeline.marksEnter)) ** 2;
+  return { rainEnvelope, lightEnvelope: 0.72 * rainEnvelope + 0.28 * mark };
+}
+
+export function drawAtmosphere(context, { config, layout, streams, progress, reducedMotion }) {
+  const state = atmosphereState(progress, config.timeline, reducedMotion);
+  if (state.rainEnvelope < 0.001 && state.lightEnvelope < 0.001) return;
+  const { plot } = layout;
+  context.save();
+  context.beginPath();
+  context.rect(plot.left, plot.top, plot.right - plot.left, plot.bottom - plot.top);
+  context.clip();
+
+  if (state.lightEnvelope > 0.001) {
+    streams.forEach((stream) => {
+      const x = plot.left + stream.x * (plot.right - plot.left);
+      const radius = Math.max(24, 55 * layout.scale);
+      const gradient = context.createLinearGradient(x - radius, 0, x + radius, 0);
+      gradient.addColorStop(0, "transparent");
+      gradient.addColorStop(0.5, config.theme.primary);
+      gradient.addColorStop(1, "transparent");
+      context.globalAlpha = config.motion.lightingPeak * state.lightEnvelope * 0.22;
+      context.fillStyle = gradient;
+      context.fillRect(x - radius, plot.top, radius * 2, plot.bottom - plot.top);
+    });
+  }
+
+  context.font = `${Math.max(8, 10 * layout.scale)}px ui-monospace, SFMono-Regular, Menlo, monospace`;
+  context.textAlign = "center";
+  context.textBaseline = "middle";
+  streams.forEach((stream) => {
+    const head = 1.18 - ((stream.phase + progress * stream.speed * 2.25) % 1.42);
+    stream.glyphs.forEach((glyph, index) => {
+      const normalizedY = head + index * stream.spacing;
+      if (normalizedY < 0 || normalizedY > 1) return;
+      const fade = Math.max(0.04, 1 - index / stream.glyphs.length);
+      context.globalAlpha = stream.base * fade * state.rainEnvelope;
+      context.fillStyle = index === 0 ? config.theme.summaryCore : config.theme.primary;
+      context.fillText(
+        glyph,
+        plot.left + stream.x * (plot.right - plot.left),
+        plot.bottom - normalizedY * (plot.bottom - plot.top),
+      );
+    });
+  });
+  context.restore();
+  context.globalAlpha = 1;
+}