@fasl-work/caos-app-shell 0.9.4 → 0.11.0

package/README.md

@@ -70,7 +70,11 @@ const config: ShellConfig = {
   Every control writes `data-control`. `PlotCard` and `Readout` take `lane`, `provenance` and a `dataKey`:
   pass `useWorkbenchState().stateKey` as captured when the computation started (rail and instrument share it), and
   a view still showing an earlier selection is overlaid as stale. Anything that loads declares
-  `data-state="loading"` until it is ready; the gate waits for that, never for the network.
+  `data-state="loading"` until it is ready; the gate waits for that, never for the network. A view whose data is absent declares
+  `data-state="unavailable"` on an element a reader can see (a visible box of 40 by 12 px at least inside the instrument,
+  opaque, its text painted inside the box: not pushed out by `text-indent`, cut by `clip-path` or under 8 px) whose rendered text states the reason (12 letters or digits in two words at least) and renders no drawing element;
+  the gate then accepts it under G6, while an unreadable note, a declaration without a reason, or one beside a blank,
+  collapsed or invisible chart still fails. The gate checks that a reason exists, not that it is true.
 - **Fill the instrument:** `<PlotCard fill>` takes the height its panel leaves (several `fill` cards share it, a
   `.caos-views-row` puts them side by side), and a `Stage` or `<UPlotChart height="fill">` inside it gets a real
   size. A table (`.caos-table`) is sized to its rows: put it above the drawing of the same numbers, never alone.
@@ -99,7 +103,12 @@ const config: ShellConfig = {
   reader cannot scroll to, see whole or click (G5), blank or underfilled drawings and an instrument under half the
   viewport (G6), a view that never settles (G7), loops at rest (G8), controls that change nothing (G9), labels cut or
   overlapping in a drawing, also in a wider fallback font (G10), a decimal point on a Spanish page (G11), a vertical
-  sub-tab list that scrolls away (G12), text under WCAG AA contrast (G13). The report
+  sub-tab list that scrolls away (G12), text under WCAG AA contrast (G13, every language on a documentation page), and a documentation page without the
+  required areas of its kind (`ADR-0017.2`: executive and technical Introduction, Methodology, Implementation,
+  Experiments, Benchmark; declared with `<DocSection area="...">`, waived only with a reason of 12 letters or digits in two
+  words through `floorWaivers`; the executive view opens first, every Introduction section sits in a view, a method cites
+  references, a `live` control is registered with `data-control`, and a tab list inside a section belongs to it;
+  [docs/04](docs/04_views.md)). The report
   (`gate-output/gate-report.json`) lists every failure and the smallest margins against each floor; `index.html`
   beside it shows every capture (G14). Details: [docs/07](docs/07_gate.md).
 - **Your own CSS:** never restyle a class of `reserved-classes.json` `components`; a `modifiers` word (`on`,

package/bin/caos-shell-gate.mjs

@@ -13,7 +13,7 @@
 //   --sizes 390x844,...,2560x1440  --themes light,dark  --langs en,es
 //   --case-sample id1,id2        cases walked outside the primary mode; default the first and the last
 //   --single-case                the workbench has one case and no case control
-//   --idle-ms 3000  --settle-ms 15000  --text-floor 400  --instrument-min 0.5  --stage-fill-min 0.3
+//   --idle-ms 3000  --settle-ms 15000  --text-floor 400  --instrument-min 0.5  --stage-fill-min 0.3  --stage-floor 140
 //   --wide-font-sizes 390x844,1280x800   the sizes of the wide-font pass (G10); --no-wide-font skips it
 //   --out gate-output            report (gate-report.json), screenshots (shots/) and the capture index (index.html)
 // Needs `playwright` in the consuming project (optional peer dependency). Exit 1 on any failure, 2 on misuse.
@@ -49,6 +49,7 @@ const options = {
   textFloor: num('text-floor'),
   instrumentMin: num('instrument-min'),
   stageFillMin: num('stage-fill-min'),
+  stageFloor: num('stage-floor'),
   wideFontSizes: args['wide-font-sizes'],
   wideFont: args['no-wide-font'] === true ? false : undefined,
   out: args.out,
@@ -65,6 +66,7 @@ try {
 const shown = report.failures.slice(0, 80);
 for (const f of shown) console.log(`FAIL [${f.check}] ${f.route} ${f.mode}${f.trail ? ` (${f.trail})` : ''}: ${f.message}`);
 if (report.failures.length > shown.length) console.log(`... and ${report.failures.length - shown.length} more in ${options.out ?? 'gate-output'}/gate-report.json`);
+for (const w of report.waivers ?? []) console.log(`WAIVER ${w.route} (${w.lang}) ${w.floor}: ${w.reason}${w.valid ? '' : ' [refused]'}`);
 const counts = Object.entries(report.checks).map(([k, n]) => `${k} ${n}`).join(', ');
 console.log(report.ok ? `caos-shell-gate: OK, ${report.states} measured states` : `caos-shell-gate: ${report.failures.length} failure(s) in ${report.states} measured states (${counts})`);
 process.exit(report.ok ? 0 : 1);

package/chart.css

@@ -16,7 +16,9 @@
 .caos-chart-swatch { flex: none; width: 16px; height: 0; border-top: 2px solid var(--swatch); }
 .caos-chart-key[data-dash] .caos-chart-swatch { border-top-style: dashed; }
 .caos-chart-key[data-mode="points"] .caos-chart-swatch { width: 7px; height: 7px; border: 0; border-radius: 50%; background: var(--swatch); }
-/* A parity plot is square and centred in its box; a chart whose points can be picked shows a pointer. */
+/* A parity plot is square and centred in its box, across and, when it fills a box taller than it is wide, down (it
+   sat at the top with the spare height under it until 0.10.0); a chart whose points can be picked shows a pointer. */
 .caos-chart[data-parity] .uplot { margin-inline: auto; }
+.caos-chart.fill[data-parity] > .caos-chart-plot { display: flex; align-items: center; justify-content: center; }
 .caos-chart[data-pick] .u-over { cursor: pointer; }
 .caos-chart .u-cursor-x, .caos-chart .u-cursor-y { border-color: var(--color-fg-faint) !important; }

package/dist/chart.d.ts

@@ -14,12 +14,20 @@ interface ChartSeries {
     dash?: number[];
     /** `points` draws markers only (a scatter of cases over a curve); `null` values are simply absent. */
     mode?: 'line' | 'points';
+    /** The marker diameter of a `points` series, in CSS pixels (9 by default): a larger one rings the selected case. */
+    size?: number;
 }
 interface ChartAxis {
     label: BiText;
     unit?: BiText;
     format?: FormatOptions;
 }
+/** What a reference line says (CAOS_APP_SHELL#94): `warn` an amber threshold (the default), `bad` a red one, `good` a
+ * level to reach, `neutral` a level that is no alarm (a nominal size, "no bias"). The line and its label take the tone's
+ * colour. */
+type YMarkTone = 'warn' | 'bad' | 'good' | 'neutral';
+/** The shell colour token of each tone of a reference line. */
+declare const YMARK_TONE_TOKENS: Record<YMarkTone, ShellColorToken>;
 interface UPlotChartProps {
     /** The x values and their axis. A time axis must be declared (`time: true`); uPlot otherwise reads numbers as
      * epoch seconds and labels ticks as dates (failure class 7). */
@@ -38,17 +46,32 @@ interface UPlotChartProps {
         x: number;
         label: BiText;
     }[];
+    /** Horizontal reference lines at y values, labelled at their right end (a null model's constant prediction, a
+     * target, a limit). */
+    yMarks?: {
+        y: number;
+        label: BiText;
+        tone?: YMarkTone;
+    }[];
     /** Height in pixels, or `fill` to take the container's height (inside `PlotCard fill`); the width is always the
      * container's. */
     height?: number | 'fill';
     /** Called with the index under the cursor (or null), for linked views; the index is the caller's, before any
      * sorting by x. */
     onCursor?: (index: number | null) => void;
-    /** Called with the caller's index of the point under the cursor when the plot is clicked (select a case, a blast). */
+    /** Called with the caller's index of the point under the cursor when the plot is clicked (select a case, a blast).
+     * On a chart whose series are all `points` (a scatter, a parity plot) the point under the cursor is the one nearest
+     * the pointer in the plane, not the one nearest in x. */
     onPick?: (index: number) => void;
     /** A parity plot: predicted (the series) against observed (x) on one shared range, in a square box, with the
-     * identity line. Unsorted x is allowed (the chart sorts it and maps every index back). */
+     * identity line. Unsorted x is allowed (the chart sorts it and maps every index back). The range takes in the
+     * reference lines (`yMarks`), so a null model's level is always in view. */
     parity?: boolean;
+    /** The readout under the plot for the point under the cursor (the caller's index), in place of the list of values:
+     * a scatter names its case ("Mg1, Murgul: measured 23.0 cm, predicted 25.1 cm"). */
+    readout?: (index: number) => string;
+    /** The readout at rest; by default "Hover the chart to read the values". */
+    hint?: BiText;
 }
 /** The colour and dash of a series: its own, or the rotation's; when the rotation comes round (a seventh series
  * repeats the first colour) the repeat is dashed, so two series never look the same (CAOS_Fragmenta drew this for
@@ -61,6 +84,14 @@ declare function seriesStyle(s: ChartSeries, i: number): {
 declare function sortOrder(xs: readonly number[]): number[] | null;
 /** One range for both axes of a parity plot, padded by 5% of the span on each side. */
 declare function parityRange(...arrays: readonly (readonly (number | null)[])[]): [number, number];
+/**
+ * The data's y extent widened to take in the levels of the reference lines, so a line is always drawn (CAOS_APP_SHELL#94;
+ * a constant series pulled the range to it, a mark did not). A log axis takes in only the levels above 0. Returns the
+ * extent unchanged when every level is inside it; `null` ends (no data) take the levels alone. An end a level pushed out
+ * moves a further `pad` of the span (of the span in decades on a log axis), so the line sits inside the frame, not on it;
+ * the caller applies uPlot's own padding after this.
+ */
+declare function rangeWithLevels(min: number | null, max: number | null, levels: readonly number[], log?: boolean, pad?: number): [number, number] | null;
 /**
  * The tick steps an axis may use. With fixed `decimals` (scaled by 100 for a percent) only multiples of the smallest
  * difference its labels can show, so no two ticks read the same: an integer axis ticks at integers, never at 1.5,
@@ -96,6 +127,26 @@ declare function drawMarks(u: uPlot, marks: {
     halo: string;
     family: string;
 }): void;
+/**
+ * The horizontal reference lines of a chart and their labels: a dashed line across the plot, its label at the right
+ * end above the line (below it when the line runs along the top), inside the plot, haloed; a label that would overlap
+ * the one placed before it moves left of it. A line outside the y range is not drawn. A mark's `color` (the tone's) draws
+ * its line and its label; without one `style.color` does.
+ */
+declare function drawYMarks(u: uPlot, marks: {
+    y: number;
+    label: string;
+    color?: string;
+}[], style: {
+    color: string;
+    halo: string;
+    family: string;
+}): void;
+/**
+ * The index of the point nearest (left, top) in the plane, over every series, or null when no point has a value.
+ * `xs` and every column of `ys` are positions in the same pixels as (left, top); a null position is no point.
+ */
+declare function nearestPoint(xs: readonly number[], ys: readonly (readonly (number | null)[])[], left: number, top: number): number | null;
 /**
  * The house chart (S12 of the 2026-10-04 requirements; uPlot, ADR on interactive charts). It is built only once its
  * box has a size; it resolves the theme's colours to concrete values and rebuilds when the theme or language changes
@@ -107,6 +158,6 @@ declare function drawMarks(u: uPlot, marks: {
  * (known shell defect 17). An axis with fixed decimals ticks only where its labels differ (`tickSteps`). The host
  * declares `data-series`, `data-axis-titles`, `data-ticks-cut`, `data-ticks-repeat` and `data-drawn` for the gate.
  */
-declare function UPlotChart({ x, y, series, marks, height, onCursor, onPick, parity }: UPlotChartProps): react.JSX.Element;
+declare function UPlotChart({ x, y, series, marks, yMarks, height, onCursor, onPick, parity, readout, hint }: UPlotChartProps): react.JSX.Element;
 
-export { type ChartAxis, type ChartSeries, LOG_TABLE_FLOOR, UPlotChart, type UPlotChartProps, drawMarks, logDecades, parityRange, repeatedLabels, seriesStyle, smallestPositive, sortOrder, tickSteps };
+export { type ChartAxis, type ChartSeries, LOG_TABLE_FLOOR, UPlotChart, type UPlotChartProps, YMARK_TONE_TOKENS, type YMarkTone, drawMarks, drawYMarks, logDecades, nearestPoint, parityRange, rangeWithLevels, repeatedLabels, seriesStyle, smallestPositive, sortOrder, tickSteps };

package/dist/chart.js

@@ -4,6 +4,12 @@ import { useRef, useCallback, useState, useMemo, useEffect } from 'react';
 import uPlot from 'uplot';
 import { jsxs, jsx } from 'react/jsx-runtime';
 
+var YMARK_TONE_TOKENS = {
+  warn: "--color-warn",
+  bad: "--color-bad",
+  good: "--color-good",
+  neutral: "--color-fg-subtle"
+};
 var ROTATION = ["--color-accent", "--color-magenta", "--color-accent-2", "--color-good", "--color-warn", "--color-bad"];
 function seriesStyle(s, i) {
   const color = s.color ?? ROTATION[i % ROTATION.length];
@@ -30,6 +36,30 @@ function parityRange(...arrays) {
   const pad = (hi - lo || Math.abs(hi) || 1) * 0.05;
   return [lo - pad, hi + pad];
 }
+function rangeWithLevels(min, max, levels, log = false, pad = 0) {
+  const d0 = min !== null && Number.isFinite(min) ? min : Infinity;
+  const d1 = max !== null && Number.isFinite(max) ? max : -Infinity;
+  let lo = d0;
+  let hi = d1;
+  for (const v of levels) {
+    if (!Number.isFinite(v) || log && !(v > 0)) continue;
+    lo = Math.min(lo, v);
+    hi = Math.max(hi, v);
+  }
+  if (!Number.isFinite(lo) || !Number.isFinite(hi)) return null;
+  if (pad > 0 && (lo < d0 || hi > d1)) {
+    if (log && lo > 0) {
+      const room = (Math.log10(hi) - Math.log10(lo) || 1) * pad;
+      if (lo < d0) lo = lo / 10 ** room;
+      if (hi > d1) hi = hi * 10 ** room;
+    } else {
+      const room = (hi - lo || Math.abs(hi) || 1) * pad;
+      if (lo < d0) lo -= room;
+      if (hi > d1) hi += room;
+    }
+  }
+  return [lo, hi];
+}
 var STEPS = [];
 for (let e = -16; e <= 16; e++) for (const m of [1, 2, 2.5, 5]) STEPS.push(Number((m * 10 ** e).toPrecision(3)));
 function tickSteps(fmt) {
@@ -57,6 +87,7 @@ var DECADE_AXIS = {
   splits: (_u, _i, min, max) => logDecades(min, max),
   filter: (_u, splits) => splits
 };
+var PARITY_TICK_SPACE = 40;
 function repeatedLabels(labels) {
   let n = 0;
   for (let i = 1; i < labels.length; i++) if (labels[i] && labels[i] === labels[i - 1]) n++;
@@ -102,7 +133,67 @@ function drawMarks(u, marks, style) {
   }
   ctx.restore();
 }
-function UPlotChart({ x, y, series, marks, height = 280, onCursor, onPick, parity }) {
+function drawYMarks(u, marks, style) {
+  const ctx = u.ctx;
+  const pr = uPlot.pxRatio || 1;
+  const left = u.bbox.left;
+  const right = u.bbox.left + u.bbox.width;
+  const top = u.bbox.top;
+  const bottom = u.bbox.top + u.bbox.height;
+  const gap = 4 * pr;
+  const textH = 11 * pr;
+  const placed = [];
+  ctx.save();
+  ctx.font = `${Math.round(11 * pr)}px ${style.family}`;
+  ctx.textBaseline = "alphabetic";
+  ctx.lineJoin = "round";
+  for (const m of [...marks].sort((a, b) => b.y - a.y)) {
+    const py = u.valToPos(m.y, "y", true);
+    if (!Number.isFinite(py) || py < top - 0.5 || py > bottom + 0.5) continue;
+    const color = m.color ?? style.color;
+    ctx.strokeStyle = color;
+    ctx.lineWidth = Math.max(1, pr);
+    ctx.setLineDash([2 * pr, 4 * pr]);
+    ctx.beginPath();
+    ctx.moveTo(left, py);
+    ctx.lineTo(right, py);
+    ctx.stroke();
+    ctx.setLineDash([]);
+    const w = ctx.measureText(m.label).width;
+    const base = py - gap - textH < top ? py + gap + textH : py - gap;
+    let x1 = right - gap;
+    while (placed.some((p) => x1 - w < p.x1 + gap && x1 > p.x0 - gap && base - textH < p.y1 && base > p.y0)) {
+      x1 = Math.min(...placed.filter((p) => base - textH < p.y1 && base > p.y0).map((p) => p.x0)) - 2 * gap;
+    }
+    const x0 = Math.max(left + gap, x1 - w);
+    placed.push({ x0, x1: x0 + w, y0: base - textH, y1: base });
+    ctx.textAlign = "left";
+    ctx.lineWidth = 3 * pr;
+    ctx.strokeStyle = style.halo;
+    ctx.strokeText(m.label, x0, base);
+    ctx.fillStyle = color;
+    ctx.fillText(m.label, x0, base);
+  }
+  ctx.restore();
+}
+function nearestPoint(xs, ys, left, top) {
+  let best = null;
+  let bestD = Infinity;
+  for (let i = 0; i < xs.length; i++) {
+    if (!Number.isFinite(xs[i])) continue;
+    for (const col of ys) {
+      const y = col[i];
+      if (y === null || y === void 0 || !Number.isFinite(y)) continue;
+      const d = (xs[i] - left) ** 2 + (y - top) ** 2;
+      if (d < bestD) {
+        bestD = d;
+        best = i;
+      }
+    }
+  }
+  return best;
+}
+function UPlotChart({ x, y, series, marks, yMarks, height = 280, onCursor, onPick, parity, readout, hint }) {
   const lang = useShellLang();
   const theme = useThemeStore((s) => s.theme);
   const fill = height === "fill";
@@ -124,36 +215,41 @@ function UPlotChart({ x, y, series, marks, height = 280, onCursor, onPick, parit
   onCursorRef.current = onCursor;
   const onPickRef = useRef(onPick);
   onPickRef.current = onPick;
+  const pickedRef = useRef(null);
   const order = useMemo(() => sortOrder(x.values), [x.values]);
   const orderRef = useRef(order);
   orderRef.current = order;
   const xs = useMemo(() => order ? order.map((i) => x.values[i]) : x.values, [order, x.values]);
   const ys = useMemo(() => series.map((s) => order ? order.map((i) => s.values[i] ?? null) : s.values), [order, series]);
-  const range = useMemo(() => parity ? parityRange(xs, ...ys) : null, [parity, xs, ys]);
+  const levels = useMemo(() => (yMarks ?? []).map((m) => m.y), [yMarks]);
+  const range = useMemo(() => parity ? parityRange(xs, ...ys, levels) : null, [parity, xs, ys, levels]);
+  const yLevels = !parity && !y.range && levels.length > 0 ? levels : null;
   const tiny = useMemo(
     () => ({
       x: Boolean(x.log) && smallestPositive([xs], range) < LOG_TABLE_FLOOR,
-      y: Boolean(y.log) && smallestPositive(ys, range ?? y.range) < LOG_TABLE_FLOOR
+      y: Boolean(y.log) && smallestPositive(yLevels ? [...ys, yLevels] : ys, range ?? y.range) < LOG_TABLE_FLOOR
     }),
-    [x.log, y.log, xs, ys, range, y.range]
+    [x.log, y.log, xs, ys, range, y.range, yLevels]
   );
   const xLabel = pick(x.label, lang);
   const yLabel = pick(y.label, lang);
   const xUnit = x.unit ? pick(x.unit, lang) : "";
   const yUnit = y.unit ? pick(y.unit, lang) : "";
   const structure = JSON.stringify({
-    s: series.map((s, i) => [pick(s.label, lang), seriesStyle(s, i), s.width ?? 2, s.mode ?? "line"]),
+    s: series.map((s, i) => [pick(s.label, lang), seriesStyle(s, i), s.width ?? 2, s.mode ?? "line", s.size ?? 9]),
     x: [xLabel, xUnit, Boolean(x.time), Boolean(x.log), x.format ?? null, tiny.x],
     p: range,
     pick: Boolean(onPick),
     y: [yLabel, yUnit, Boolean(y.log), y.range ?? null, y.format ?? null, tiny.y],
     m: (marks ?? []).map((m) => [m.x, pick(m.label, lang)]),
+    ym: (yMarks ?? []).map((m) => [m.y, pick(m.label, lang), m.tone ?? "warn"]),
     theme,
     lang,
     h,
     w: width
   });
   const data = useMemo(() => [xs, ...ys], [xs, ys]);
+  const scatter = series.length > 0 && series.every((s) => s.mode === "points");
   useEffect(() => {
     const el = plotRef.current;
     if (!el || width <= 0 || h <= 0) return;
@@ -167,14 +263,30 @@ function UPlotChart({ x, y, series, marks, height = 280, onCursor, onPick, parit
       const labels = formatTicks(vals, lang, fmt ?? { digits: 4 });
       repeats[axis] = repeatedLabels(labels);
       hostRef.current?.setAttribute("data-ticks-repeat", String(repeats.x + repeats.y));
+      hostRef.current?.setAttribute(`data-ticks-${axis}`, String(labels.filter((l) => l).length));
       return labels;
     };
+    const near = { left: NaN, top: NaN, idx: null };
+    const nearest = (u) => {
+      const { left, top } = u.cursor;
+      if (left === void 0 || top === void 0 || left < 0 || top < 0) return null;
+      if (left !== near.left || top !== near.top) {
+        const d = u.data;
+        const px = d[0].map((v) => v === null ? NaN : u.valToPos(v, "x"));
+        const py = d.slice(1).map((col) => col.map((v) => v === null ? null : u.valToPos(v, "y")));
+        near.left = left;
+        near.top = top;
+        near.idx = nearestPoint(px, py, left, top);
+      }
+      return near.idx;
+    };
     const xSteps = x.time || x.log ? void 0 : tickSteps(x.format);
     const ySteps = y.log ? void 0 : tickSteps(y.format);
     const opts = {
       width,
       height: h,
       legend: { show: false },
+      ...scatter ? { cursor: { dataIdx: (u, sIdx, closest) => sIdx === 0 ? closest : nearest(u) ?? closest } } : {},
       // a log axis labels the ticks uPlot keeps and passes null for the rest, which formatTicks leaves blank
       scales: {
         // a log x axis spans the data, not the decades around it (uPlot rounds out to the next decade, which left an
@@ -184,7 +296,17 @@ function UPlotChart({ x, y, series, marks, height = 280, onCursor, onPick, parit
           distr: x.log ? 3 : 1,
           ...range ? { range } : x.log ? { range: (_u, min, max) => [min, max] } : {}
         },
-        y: { distr: y.log ? 3 : 1, ...range ? { range } : y.range ? { range: y.range } : {} }
+        y: {
+          distr: y.log ? 3 : 1,
+          ...range ? { range } : y.range ? { range: y.range } : yLevels ? {
+            // uPlot's own range of the data and the levels: its padding, its decade snap on a log axis
+            range: (u, dmin, dmax) => {
+              const w = rangeWithLevels(dmin, dmax, yLevels, Boolean(y.log), 0.05);
+              if (!w) return [dmin, dmax];
+              return y.log ? uPlot.rangeLog(w[0], w[1], u.scales.y.log ?? 10, false) : uPlot.rangeNum(w[0], w[1], 0.1, true);
+            }
+          } : {}
+        }
       },
       axes: [
         {
@@ -196,6 +318,7 @@ function UPlotChart({ x, y, series, marks, height = 280, onCursor, onPick, parit
           labelFont: font,
           values: x.time ? void 0 : tick(x.format, "x"),
           ...xSteps ? { incrs: xSteps } : {},
+          ...range ? { space: PARITY_TICK_SPACE } : {},
           ...tiny.x ? DECADE_AXIS : {}
         },
         {
@@ -207,6 +330,7 @@ function UPlotChart({ x, y, series, marks, height = 280, onCursor, onPick, parit
           labelFont: font,
           values: tick(y.format, "y"),
           ...ySteps ? { incrs: ySteps } : {},
+          ...range ? { space: PARITY_TICK_SPACE } : {},
           ...tiny.y ? DECADE_AXIS : {},
           // Sized to the longest tick label. uPlot draws in device pixels with a font scaled by its pixel ratio, so the
           // label is measured in that font and divided back (measuring the unscaled font and dividing by the ratio
@@ -225,13 +349,14 @@ function UPlotChart({ x, y, series, marks, height = 280, onCursor, onPick, parit
         ...series.map((s, i) => {
           const style = seriesStyle(s, i);
           const stroke = resolveToken(style.color, "#4a8");
-          return s.mode === "points" ? { label: pick(s.label, lang), stroke, width: 1.5, paths: () => null, points: { show: true, space: 0, size: 9, fill: stroke } } : { label: pick(s.label, lang), stroke, width: s.width ?? 2, dash: style.dash, spanGaps: false, points: { show: false } };
+          return s.mode === "points" ? { label: pick(s.label, lang), stroke, width: 1.5, paths: () => null, points: { show: true, space: 0, size: s.size ?? 9, fill: stroke } } : { label: pick(s.label, lang), stroke, width: s.width ?? 2, dash: style.dash, spanGaps: false, points: { show: false } };
         })
       ],
       hooks: {
         setCursor: [
           (u) => {
-            const idx = u.cursor.idx ?? null;
+            const idx = scatter ? nearest(u) : u.cursor.idx ?? null;
+            pickedRef.current = idx;
             setCursor(idx);
             onCursorRef.current?.(idx === null ? null : orderRef.current ? orderRef.current[idx] : idx);
           }
@@ -239,7 +364,7 @@ function UPlotChart({ x, y, series, marks, height = 280, onCursor, onPick, parit
         ready: [
           (u) => {
             u.over.addEventListener("click", () => {
-              const idx = u.cursor.idx;
+              const idx = pickedRef.current;
               if (idx === null || idx === void 0 || !onPickRef.current) return;
               onPickRef.current(orderRef.current ? orderRef.current[idx] : idx);
             });
@@ -260,12 +385,9 @@ function UPlotChart({ x, y, series, marks, height = 280, onCursor, onPick, parit
               ctx.stroke();
               ctx.restore();
             }
-            if (!marks?.length) return;
-            drawMarks(u, marks.map((m) => ({ x: m.x, label: pick(m.label, lang) })), {
-              color: resolveToken("--color-warn", "#c80"),
-              halo: surface,
-              family
-            });
+            const markStyle = { color: resolveToken("--color-warn", "#c80"), halo: surface, family };
+            if (yMarks?.length) drawYMarks(u, yMarks.map((m) => ({ y: m.y, label: pick(m.label, lang), color: resolveToken(YMARK_TONE_TOKENS[m.tone ?? "warn"], "#c80") })), markStyle);
+            if (marks?.length) drawMarks(u, marks.map((m) => ({ x: m.x, label: pick(m.label, lang) })), markStyle);
           }
         ]
       }
@@ -280,12 +402,10 @@ function UPlotChart({ x, y, series, marks, height = 280, onCursor, onPick, parit
   useEffect(() => {
     uRef.current?.setData(data);
   }, [data]);
-  const read = cursor !== null ? [
+  const read = cursor !== null && readout ? readout(order ? order[cursor] : cursor) : cursor !== null ? [
     `${xLabel} ${formatNumber(xs[cursor], lang, x.format ?? { digits: 4 })}${xUnit ? `${NBSP}${xUnit}` : ""}`,
-    ...series.map(
-      (s, k) => `${pick(s.label, lang)} ${formatNumber(ys[k][cursor] ?? null, lang, y.format ?? { digits: 4 })}${yUnit ? `${NBSP}${yUnit}` : ""}`
-    )
-  ].join(" \xB7 ") : lang === "es" ? "Pase el cursor sobre el gr\xE1fico para leer los valores" : "Hover the chart to read the values";
+    ...series.map((s, k) => ({ s, v: ys[k][cursor] ?? null })).filter(({ v }) => !scatter || v !== null).map(({ s, v }) => `${pick(s.label, lang)} ${formatNumber(v, lang, y.format ?? { digits: 4 })}${yUnit ? `${NBSP}${yUnit}` : ""}`)
+  ].join(" \xB7 ") : hint ? pick(hint, lang) : lang === "es" ? "Pase el cursor sobre el gr\xE1fico para leer los valores" : "Hover the chart to read the values";
   return /* @__PURE__ */ jsxs(
     "div",
     {
@@ -299,6 +419,7 @@ function UPlotChart({ x, y, series, marks, height = 280, onCursor, onPick, parit
       "data-parity": parity ? "1" : void 0,
       "data-log-x": x.log ? "1" : void 0,
       "data-pick": onPick ? "1" : void 0,
+      "data-y-marks": yMarks?.length ? String(yMarks.length) : void 0,
       children: [
         /* @__PURE__ */ jsx("div", { ref: setPlot, className: "caos-chart-plot" }),
         series.length > 1 && /* @__PURE__ */ jsx("ul", { className: "caos-chart-legend", "aria-label": lang === "es" ? "Series del gr\xE1fico" : "Series of the chart", children: series.map((s, i) => /* @__PURE__ */ jsxs("li", { className: "caos-chart-key", "data-mode": s.mode ?? "line", "data-dash": seriesStyle(s, i).dash ? "1" : void 0, children: [
@@ -311,4 +432,4 @@ function UPlotChart({ x, y, series, marks, height = 280, onCursor, onPick, parit
   );
 }
 
-export { LOG_TABLE_FLOOR, UPlotChart, drawMarks, logDecades, parityRange, repeatedLabels, seriesStyle, smallestPositive, sortOrder, tickSteps };
+export { LOG_TABLE_FLOOR, UPlotChart, YMARK_TONE_TOKENS, drawMarks, drawYMarks, logDecades, nearestPoint, parityRange, rangeWithLevels, repeatedLabels, seriesStyle, smallestPositive, sortOrder, tickSteps };

package/dist/index.d.ts

@@ -361,14 +361,30 @@ declare function Cite({ id, paren }: {
     id: string;
     paren?: boolean;
 }): react.JSX.Element;
+/** The citation ids of a scope in the order of first appearance: each id once, sections in the order given. */
+declare function firstAppearance(sections: readonly (readonly string[])[]): string[];
+/**
+ * A scope that lists the references of the sections inside it, once, at its own end: the `DocPage`, and each open panel
+ * of `Tabs` and `SubTabs` (the innermost scope wins). Sections register in a layout effect; the order is their order in
+ * the document (not the order of registration), so a section that mounts later keeps its place. It adds no element of
+ * its own, and nothing renders while no section registered an id.
+ */
+declare function DocRefsScope({ children }: {
+    children: ReactNode;
+}): react.JSX.Element;
+/** The end-of-scope references block (ADR-0017 s4, shell 0.11.0): the full citation of each id, once, as an ordered list. */
+declare function DocReferences({ ids }: {
+    ids: string[];
+}): react.JSX.Element | null;
 /** A short inline "Refs: a · b · c" row (e.g. under a deep sub-tab). */
 declare function Refs({ ids, label }: {
     ids: string[];
     label: string;
 }): react.JSX.Element;
 /** Full ordered bibliography. Omit `ids` to render every provided citation.
- * @deprecated ADR-0017 s4 bans a bottom-of-page bibliography; end each section with `Refs` (or use `DocSection`).
- * Kept so existing products still compile; it reports itself on the console, which the gate fails on. */
+ * @deprecated Superseded by the end-of-page references block that `DocPage` and the tab panels render from their
+ * `DocSection`s (ADR-0017 s4). Kept so existing products still compile; it reports itself on the console, which the
+ * gate fails on. */
 declare function ReferenceList({ ids, heading }: {
     ids?: string[];
     heading?: string;
@@ -377,25 +393,91 @@ declare function ReferenceList({ ids, heading }: {
 /**
  * A documentation route (Introduction, Methodology, Implementation, Experiments, Benchmark): the page head with
  * its title and lede, then sections. `wide` for a route with a sub-tab rail (ADR-0071 rule 2, amended
- * 2026-09-04); a single prose column keeps the reading width and is centred (ADR-0017 §1).
+ * 2026-09-04); a single prose column keeps the reading width and is centred (ADR-0017 §1). Text takes the full width
+ * of the column, and the references of its sections are listed once at the end of the page (ADR-0017 §4).
+ */
+/**
+ * The areas a section may declare, per documentation route (ADR-0017 section 2.1). The gate's table (`gate/areas.mjs`)
+ * holds each area's rule; `test/docFloors.test.ts` keeps these names equal to that table's.
  */
-declare function DocPage({ title, lede, wide, children }: {
+declare const DOC_AREAS: {
+    readonly '/introduction': readonly ["initiative", "outcomes", "positioning", "credibility", "problem", "principles", "math", "pipeline", "honesty"];
+    readonly '/methodology': readonly ["method"];
+    readonly '/implementation': readonly ["architecture", "reproducibility", "engine", "lanes", "contract", "deployment"];
+    readonly '/experiments': readonly ["question", "metrics", "protocol", "datasets"];
+    readonly '/benchmark': readonly ["results", "comparison", "robustness", "live", "provenance", "caveat"];
+};
+interface DocPageProps {
     title: BiText;
     lede: ReactNode;
     wide?: boolean;
+    /**
+     * The required areas this page cannot carry, each with the reason (ADR-0017 section 2.1): rendered as
+     * `data-floor-waiver="<floor>: <reason>"`, separated by `; ` (a reason holds no semicolon). The gate skips a waived
+     * floor, lists the waiver, and fails one whose reason has fewer than 12 characters or whose floor is unknown.
+     */
+    floorWaivers?: Array<{
+        floor: string;
+        reason: BiText;
+    }>;
     children: ReactNode;
-}): react.JSX.Element;
+}
+declare function DocPage({ title, lede, wide, floorWaivers, children }: DocPageProps): react.JSX.Element;
 interface DocSectionProps {
     title: BiText;
     id?: string;
-    /** Citation ids for this section only, rendered as one inline `Refs` row at its end (ADR-0017 §4). */
+    /** The required area this section covers (ADR-0017 section 2.1), rendered as `data-area`; the vocabulary is fixed per page (`gate/areas.mjs`). */
+    area?: string;
+    /** Methodology only: the kind of the method this section describes, rendered as `data-method-kind`. */
+    kind?: 'classical' | 'learned';
+    /** Citation ids this section cites; they are listed in the references block at the end of the page or open tab (ADR-0017 §4). */
     refs?: string[];
     /** Required when a section cites nothing, so the absence is a stated choice the gate can read. */
     noRefsReason?: BiText;
     children: ReactNode;
 }
-/** One section of a documentation route, ending in its own references. */
-declare function DocSection({ title, id, refs, noRefsReason, children }: DocSectionProps): react.JSX.Element;
+/** One section of a documentation route; its references are registered with the nearest scope, not rendered here. */
+declare function DocSection({ title, id, area, kind, refs, noRefsReason, children }: DocSectionProps): react.JSX.Element;
+
+interface GlossaryEntry {
+    /** The symbol or term: a plain string (a symbol such as `S(t)`) or both languages. */
+    term: BiText;
+    definition: BiText;
+}
+/**
+ * The symbol glossary of the governing mathematics (ADR-0017 section 2.1, area `math`): one `<dt>` and `<dd>` per entry,
+ * in a `<dl>` that declares `data-glossary`. The gate counts its items and requires at least 10.
+ */
+declare function Glossary({ entries, ariaLabel }: {
+    entries: GlossaryEntry[];
+    ariaLabel?: BiText;
+}): react.JSX.Element;
+
+interface StatProps {
+    /** The number as written, for example `42` or `3.5`. */
+    value: BiText;
+    /** Its unit, for example `% of downtime` (a statement without a unit is not quantified). */
+    unit: BiText;
+    /** Where the number comes from (a document, a measurement, a dataset): shown beside it and declared as `data-stat-source`. */
+    source: BiText;
+}
+/**
+ * A quantified statement (ADR-0017 section 2.1, the executive view): a value, its unit and its source, rendered as
+ * `data-stat` so the gate can count the claims of value that carry a number. A claim without all three is not a stat.
+ */
+declare function Stat({ value, unit, source }: StatProps): react.JSX.Element;
+
+interface QuestionProps {
+    /** The business question the executive would ask. */
+    question: ReactNode;
+    /** The plain answer, with the evidence and the honest limits. */
+    answer: ReactNode;
+}
+/**
+ * One question and its answer (ADR-0017 section 2.1, executive view, area `credibility`), rendered as `data-qa` with
+ * `data-question` and `data-answer` so the gate can count the pairs that hold both.
+ */
+declare function Question({ question, answer }: QuestionProps): react.JSX.Element;
 
 interface SurfacePageProps {
     /** The route's heading; omit it when the header's active route already names the surface. */
@@ -836,4 +918,4 @@ interface ViewsRowProps {
  */
 declare function ViewsRow({ children, shares }: ViewsRowProps): react.JSX.Element;
 
-export { BREAKPOINTS, BarChart, type BarChartProps, type BarDatum, BiText, Callout, type CaseDef, type CaseGroup, type CaseKind, CaseSelector, type CaseSelectorProps, type CaseSelectorText, CaseWorkbench, type CaseWorkbenchProps, ChipGroup, type ChipGroupProps, type ChipOption, type Citation, CitationsProvider, Cite, DocPage, DocSection, type DocSectionProps, Equation, Figure, type FittedLabel, FocusShell, type FocusShellProps, FormatOptions, Gauge, type GaugeProps, type GaugeZone, InlineMath, Knob, type KnobProps, type Lane, LaneBadge, Lang, LanguageToggle, MAX_PEER_TABS, MAX_WORKBENCH_GROUPS, PanelBoundary, type PausedVizController, PlotCard, type PlotCardProps, type Provenance, type RailSection, Readout, type ReadoutItem, type ReadoutProps, ReferenceList, Refs, Stage, type StageSize, type SubTabDef, SubTabs, type SubTabsProps, SurfacePage, type SurfacePageProps, type TabDef, type TabGroupDef, TabGroups, type TabGroupsProps, Tabs, type TabsProps, type Theme, ThemeToggle, type Tone, type UsePausedVizOptions, VariantBar, type VariantBarProps, type VariantDef, Verdict, type VerdictProps, ViewsRow, type ViewsRowProps, type VizFrame, type VizLoop, type VizLoopDeps, type VizLoopOptions, type WorkbenchGroup, WorkbenchLayout, type WorkbenchLayoutProps, type WorkbenchRoute, WorkbenchShell, type WorkbenchShellProps, type WorkbenchState, WorkbenchStateContext, applyTheme, caseKind, caseTooltip, casesInSource, createVizLoop, fitLabel, fontFamily, groupByCategory, isStale, makeStateKey, niceStep, niceTicks, readCaseParam, readTheme, replaceQueryParam, sourcesPresent, textWidth, usePausedViz, useStageSize, useThemeStore, useUrlView, useWorkbenchState, viewParamOf, widestLabel, withCaseParam };
+export { BREAKPOINTS, BarChart, type BarChartProps, type BarDatum, BiText, Callout, type CaseDef, type CaseGroup, type CaseKind, CaseSelector, type CaseSelectorProps, type CaseSelectorText, CaseWorkbench, type CaseWorkbenchProps, ChipGroup, type ChipGroupProps, type ChipOption, type Citation, CitationsProvider, Cite, DOC_AREAS, DocPage, type DocPageProps, DocReferences, DocRefsScope, DocSection, type DocSectionProps, Equation, Figure, type FittedLabel, FocusShell, type FocusShellProps, FormatOptions, Gauge, type GaugeProps, type GaugeZone, Glossary, type GlossaryEntry, InlineMath, Knob, type KnobProps, type Lane, LaneBadge, Lang, LanguageToggle, MAX_PEER_TABS, MAX_WORKBENCH_GROUPS, PanelBoundary, type PausedVizController, PlotCard, type PlotCardProps, type Provenance, Question, type QuestionProps, type RailSection, Readout, type ReadoutItem, type ReadoutProps, ReferenceList, Refs, Stage, type StageSize, Stat, type StatProps, type SubTabDef, SubTabs, type SubTabsProps, SurfacePage, type SurfacePageProps, type TabDef, type TabGroupDef, TabGroups, type TabGroupsProps, Tabs, type TabsProps, type Theme, ThemeToggle, type Tone, type UsePausedVizOptions, VariantBar, type VariantBarProps, type VariantDef, Verdict, type VerdictProps, ViewsRow, type ViewsRowProps, type VizFrame, type VizLoop, type VizLoopDeps, type VizLoopOptions, type WorkbenchGroup, WorkbenchLayout, type WorkbenchLayoutProps, type WorkbenchRoute, WorkbenchShell, type WorkbenchShellProps, type WorkbenchState, WorkbenchStateContext, applyTheme, caseKind, caseTooltip, casesInSource, createVizLoop, firstAppearance, fitLabel, fontFamily, groupByCategory, isStale, makeStateKey, niceStep, niceTicks, readCaseParam, readTheme, replaceQueryParam, sourcesPresent, textWidth, usePausedViz, useStageSize, useThemeStore, useUrlView, useWorkbenchState, viewParamOf, widestLabel, withCaseParam };