@fasl-work/caos-app-shell 0.23.2 → 0.25.0

package/CHANGELOG.md

@@ -1,3 +1,43 @@
+## [0.25.000] - 2026-11-08
+
+Two gaps that CEFOP_DinHot's full gate found on its release build (shell 0.23.2; CAOS_APP_SHELL#207, #208; known defects 61 and 62).
+
+### Added
+
+- `VariantBar` `layout?: 'chips' | 'select'` (default `'chips'`, markup unchanged; known defect 61, SHW-063, issue 207). `'select'` draws the variants as one native select with the shell's display, the active variant's full label shown whole and wrapping inside the rail, and keeps the title with its count, the lane badge, the active variant's note, `data-variant-bar`, `data-variant-count`, `data-control="variant"`, the keyboard of a native select and the disabled options. A list of 14 long-named variants fits a 232 px rail at 1280 x 800 in en and es and in the wide-font pass (as chips it scrolled the rail: G5 441, ADR-0071.6 266 and G18 14 findings on DinHot).
+- `SelectDisplay` (`src/lib/SelectDisplay.tsx`, internal): the display of the case select, extracted so `CaseSelector` and `VariantBar` share one component; the case select's markup and behaviour are unchanged.
+- Gate plants: `variants-long-chips` (the long list as chips fails ADR-0071.6), `legit-variants-select` (the same list in `layout: 'select'` passes), `legit-chart-in-document`, `legit-chart-pointer-redispatch` and `chart-readout-scroll-move` (the document walk on a long page with a chart).
+
+### Fixed
+
+- A chart's readout no longer changes when the page scrolls under a resting pointer (known defect 62, SHC-103, issue 208, ADR-0017.2). The browser re-dispatches the pointer position (a mouseover, mouseenter and mousemove at the same client coordinates) to the chart that came under it, and sends a mouseleave at the same coordinates when the scroll takes the plot away; `UPlotChart` moved its cursor and readout on both, so the gate's document walk reported "document text changed during traversal" (reproduced on the shell's own fixture, three tabs of /experiments). `UPlotChart` now changes its cursor and readout only on a real pointer move, an enter or a leave by moving, or the keyboard; the held leave is applied at the next real move of the pointer, and a touch or a pen is never judged.
+
+### Adoption
+
+- A product with a long or long-named variant list sets `layout: 'select'` on its `variants` prop (`CaseWorkbench` forwards it to `VariantBar`); nothing else changes. A product with a short list keeps the chips.
+- Known defect 62: no product change. A product that worked around it (a pointer moved off the document before the walk, a readout excluded from the walk) removes the workaround. A chart scrolled away from a resting pointer keeps its last reading until the pointer next moves, leaves by moving, or the keyboard acts.
+
+## [0.24.000] - 2026-11-08
+
+Four defects that an ADR-0082 review of CAOS_ChancaDEM on 0.23.2 found (CAOS_MANAGE `wip/chancadem/viz-review-2026-11-07.md`, findings M11, M1, M3, m4).
+
+### Fixed
+
+- A scene callout no longer shows its state by colour alone (known defect 58, SHW-059, ADR-0082 rule 8). Every `SceneCallouts` card carries a state label, a word in the page language with a glyph of its own shape (en normal, warning, alarm, selected, inactive; es normal, aviso, alarma, seleccionado, inactivo), marked `data-callout-state-label`, on a row of its own; the border colour stays. A callout without a recognised state gets no label (G21 already fails it). The eyebrow wraps instead of ending in an ellipsis: on the shell's own fixture the Spanish eyebrows were cut by 19 to 58 px at 390 and 1280 px.
+- G21 measures the callouts at every size, theme and language of the gate matrix (known defect 59, SHG-090). Its callout checks (value and unit, state and state label, provenance, the 8 px clearance of the own anchor, no overlap, inside the stage, one leader per callout, no horizontal overflow) ran at the primary size, first theme and first language only, so ChancaDEM's cards overlapped by 2 to 6 px at 390x844 and in Spanish while the gate passed. The interaction, motion and performance checks stay at the primary size. The report lists the measured contexts (`storyContexts`). A new G21 check fails a callout whose state label is not visible (SHG-091).
+- Header callouts are laid out on their measured heights, in the order of their anchors (known defect 60, SHW-060, SHW-061). `layoutCalloutHeader` placed the cards in declaration order on nominal heights (68 px, 54 px compact), so a card that grew when its source wrapped covered the next row and a card anchored at the right could sit at the left with its leader across the subject. The layer now measures its cards (ResizeObserver) and lays them out again when a height changes; `layoutCalloutHeader(items, width, height, compact, heights?)` reads the cards in anchor x order (stable for equal x), sizes each row by its tallest card, takes the slot order with the fewest crossing leaders (the anchor order winning every tie) and narrows a compact card to the cell, never over its neighbour. `layoutSceneCallouts` takes the same optional `heights`.
+- At a phone width every verb of the story stepper is whole (SHW-062, review m4). A step is at least as wide as its number and verb and never wider than the row (a longer verb wraps inside its step, so a platform with a wider system font shows it whole too: the first candidate's main CI on Linux overflowed a 320 px row), the row scrolls on x, and `StoryFrame` brings the active step inside the row whenever it changes (keyboard, autoplay, deep link).
+
+### Added
+
+- `SceneCallouts` `onLayout?: (info: { bandHeight: number }) => void` and the CSS custom property `--caos-callout-band` (px) on the header layer: the distance from the top of the layer to the bottom of the lowest card after layout.
+
+### Adoption
+
+- Known defects 58 and 59: no product change beyond the product's own gate run on this release; a product that drew its own state word or glyph in the eyebrow to work around defect 58 removes it. A product whose cards overlapped only on a phone or in Spanish now fails G21 there and fixes its layout.
+- Known defect 60: a product that reserves a header band reads `--caos-callout-band` (CSS) or `onLayout` (JavaScript) instead of a band computed from the nominal 184x68 or 164x54 cards, and drops any local reordering of its callouts by anchor x.
+- The phone stepper: no product change; a product that shortened its step verbs to fit the 90 px columns may restore them.
+
 ## [0.23.002] - 2026-11-07
 
 ### Fixed

package/VERSION

@@ -1 +1 @@
-0.23.002
+0.25.000

package/dist/chart.js

@@ -5,6 +5,46 @@ import { useRef, useCallback, useState, useId, useEffect, useMemo } from 'react'
 import uPlot from 'uplot';
 import { jsxs, jsx, Fragment } from 'react/jsx-runtime';
 
+// src/chart/pointer.ts
+var SCROLL_WINDOW_MS = 300;
+var newTrack = () => ({ x: Number.NaN, y: Number.NaN, scrolledAt: -Infinity, type: "mouse" });
+function scrollSynthesised(t, e, now) {
+  if (t.type !== "mouse") return false;
+  if (!Number.isNaN(t.x)) return e.clientX === t.x && e.clientY === t.y;
+  return now - t.scrolledAt < SCROLL_WINDOW_MS && e.movementX === 0 && e.movementY === 0;
+}
+var track = null;
+var realMoveListeners = /* @__PURE__ */ new Set();
+function onRealMove(fn) {
+  realMoveListeners.add(fn);
+  return () => void realMoveListeners.delete(fn);
+}
+function pointerTrack() {
+  if (track) return track;
+  const t = newTrack();
+  track = t;
+  if (typeof window === "undefined") return t;
+  window.addEventListener("scroll", () => {
+    t.scrolledAt = performance.now();
+  }, { capture: true, passive: true });
+  const type = (e) => {
+    t.type = e.pointerType || "mouse";
+  };
+  window.addEventListener("pointerdown", type, { capture: true, passive: true });
+  window.addEventListener("pointermove", type, { capture: true, passive: true });
+  window.addEventListener(
+    "mousemove",
+    (e) => {
+      if (e.clientX === t.x && e.clientY === t.y) return;
+      t.x = e.clientX;
+      t.y = e.clientY;
+      for (const fn of [...realMoveListeners]) fn();
+    },
+    { passive: true }
+  );
+  return t;
+}
+
 // src/chart/uplotZoom.ts
 var rangeOf = (u, key) => [u.scales[key].min ?? 0, u.scales[key].max ?? 1];
 function createZoom(u, ctx) {
@@ -506,6 +546,7 @@ function nearestPoint(xs, ys, left, top) {
 }
 function UPlotChart({ x, y, series, marks, yMarks, onYMarkChange, height = 280, onCursor, onPick, parity, readout, hint, solo, title, zoomY, zoomOff }) {
   const lang = useShellLang();
+  pointerTrack();
   const theme = useThemeStore((s) => s.theme);
   const fill = height === "fill";
   const [measureRef, box] = useStageSize();
@@ -767,6 +808,27 @@ function UPlotChart({ x, y, series, marks, yMarks, onYMarkChange, height = 280,
         ],
         ready: [
           (u2) => {
+            const track2 = pointerTrack();
+            let heldLeave = false;
+            let replay = false;
+            const real = (e) => {
+              if (replay) return;
+              if (scrollSynthesised(track2, e, performance.now())) {
+                if (e.type === "mouseleave") heldLeave = true;
+                e.stopImmediatePropagation();
+              } else if (e.type !== "mouseleave") heldLeave = false;
+            };
+            u2.root.addEventListener("mousemove", real, true);
+            u2.root.addEventListener("mouseenter", real, true);
+            u2.root.addEventListener("mouseleave", real, true);
+            const stopHeld = onRealMove(() => {
+              if (!heldLeave) return;
+              heldLeave = false;
+              replay = true;
+              u2.over.dispatchEvent(new MouseEvent("mouseleave", { clientX: track2.x, clientY: track2.y }));
+              replay = false;
+            });
+            u2.hooks.destroy = [...u2.hooks.destroy ?? [], stopHeld];
             u2.over.addEventListener("click", () => {
               const idx = pickedRef.current;
               if (idx === null || idx === void 0 || !onPickRef.current) return;

package/dist/index.d.ts

@@ -1200,10 +1200,15 @@ interface VariantBarProps {
     onSelect: (id: string) => void;
     title?: BiText;
     lane?: Lane;
+    /** How the one-of-N choice is drawn. 'chips' (the default) is one scrollable row of chips; 'select' is one native select with the shell's display
+     * (the case select's: the active variant's full label shown whole, wrapping inside the rail), for a long or long-named list (ADR-0071 rule 7: 14
+     * methods named by their names drew a 605 px column of chips in a 713 px rail). The title with its count, the lane badge, the active variant's
+     * note, `data-variant-bar`, `data-variant-count` and `data-control="variant"` are the same in both. */
+    layout?: 'chips' | 'select';
 }
-/** The regimes of the selected case on ONE scrollable row (ADR-0071 rule 4), the active regime's lane, and the
- * one-line note of what it shows. Selecting a regime must change every view of the case. */
-declare function VariantBar({ variants, activeId, onSelect, title, lane }: VariantBarProps): react.JSX.Element;
+/** The regimes of the selected case on ONE scrollable row (ADR-0071 rule 4) or, with `layout: 'select'`, in one select (rule 7), the active
+ * regime's lane, and the one-line note of what it shows. Selecting a regime must change every view of the case. */
+declare function VariantBar({ variants, activeId, onSelect, title, lane, layout }: VariantBarProps): react.JSX.Element;
 
 /** One group of views of the selected case, named for the question the user is asking (ADR-0071 rule 5). */
 interface WorkbenchGroup {
@@ -1451,13 +1456,32 @@ interface CalloutBox {
     anchorX: number;
     anchorY: number;
 }
+/** Measured card heights in CSS pixels by callout id; a callout without one is laid out at the nominal height. */
+type CalloutHeights = Readonly<Record<string, number>>;
 /** Deterministic callout placement, exported so a product can test its scene geometry before rendering. */
-declare function layoutSceneCallouts(items: SceneCalloutDef[], width: number, height: number, compact?: boolean): CalloutBox[];
-/** Overlay anchored value labels on a stage; normalized anchors are reprojected by the product as the camera moves. */
-declare function SceneCallouts({ items, className, placement }: {
+declare function layoutSceneCallouts(items: SceneCalloutDef[], width: number, height: number, compact?: boolean, heights?: CalloutHeights): CalloutBox[];
+/**
+ * Callout cards in a reserved top band; leaders retain their individual scene anchors. The cards are read in the order of
+ * their anchors' x (stable for equal x) and placed in rows from left to right, each row as tall as its tallest card, so a card
+ * that grew when its text wrapped never covers the next row (known defect 60). `heights` are the measured card heights
+ * (SceneCallouts measures its cards and lays them out again when one changes); without them the nominal heights are used.
+ * When that order would make two leaders cross (anchors at different depths), the slot order with the fewest crossings is
+ * taken instead, the anchor order winning every tie. The boxes are returned in anchor x order.
+ */
+declare function layoutCalloutHeader(items: SceneCalloutDef[], width: number, height: number, compact?: boolean, heights?: CalloutHeights): CalloutBox[];
+/**
+ * Overlay anchored value labels on a stage; normalized anchors are reprojected by the product as the camera moves.
+ * The layer measures its cards and lays them out on their real heights. In the header placement it sets
+ * `--caos-callout-band` (px) on the layer and calls `onLayout` with the band height: the distance from the top of the
+ * layer to the bottom of the lowest card, which a product reserves above its drawing instead of a nominal band.
+ */
+declare function SceneCallouts({ items, className, placement, onLayout }: {
     items: SceneCalloutDef[];
     className?: string;
     placement?: 'anchored' | 'header';
+    onLayout?: (info: {
+        bandHeight: number;
+    }) => void;
 }): react.JSX.Element;
 
 interface Scene3DFrameProps {
@@ -1587,4 +1611,4 @@ declare function explodedOffsets(parts: ExplodedPart[], scale?: number): Record<
 declare function detailTier(distance: number): DetailTier;
 declare function sceneEnvironment(theme: 'light' | 'dark'): SceneEnvironment;
 
-export { BREAKPOINTS, BarChart, type BarChartProps, type BarDatum, BiText, Callout, type CalloutBox, type CalloutState, type CameraFlyOptions, type CameraFrame, type CameraPose, CardDeck, type CardDeckProps, type CaseDef, type CaseFocusConfig, type CaseGroup, type CaseKind, CaseSelector, type CaseSelectorProps, type CaseSelectorText, CaseWorkbench, type CaseWorkbenchProps, ChipGroup, type ChipGroupProps, type ChipOption, type Citation, CitationsProvider, Cite, DECK_TEXT, DOC_AREAS, type DeckCard, type DetailTier, DocPage, type DocPageProps, DocReferences, DocRefsScope, DocSection, type DocSectionProps, EXECUTIVE_SCHEMA_VERSION, Equation, type ExecutiveData, type ExecutiveProblem, ExecutiveView, type ExecutiveViewProps, type ExplodedPart, FLIP_LIMITS, FLIP_TEXT, FOCUS_PARAM, FOCUS_TEXT, FOUR_CS, Figure, FlipCard, type FlipCardProps, type FocusMode, type FocusModeConfig, type FocusModeOptions, FocusShell, type FocusShellProps, FormatOptions, Gauge, type GaugeProps, type GaugeZone, Glossary, type GlossaryEntry, InlineMath, Knob, type KnobProps, Landing, type Lane, LaneBadge, Lang, LanguageToggle, LinkedViewProvider, type LinkedViewSide, type LinkedViewState, type LinkedViewStore, MAX_PEER_TABS, MAX_WORKBENCH_GROUPS, type MotionOptions, type MotionStage, PanelBoundary, type PausedVizController, PlotCard, type PlotCardProps, type Provenance, Question, type QuestionProps, type RailSection, Readout, type ReadoutItem, type ReadoutProps, ReferenceList, Refs, Scene3DFrame, type Scene3DFrameProps, type SceneBounds, type SceneCalloutDef, SceneCallouts, type SceneEnvironment, type SelectionOrigin, Stage, type StageSize, Stat, type StatProps, type StoryAccent, StoryFrame, type StoryFrameProps, type StoryStep, type SubTabDef, SubTabs, type SubTabsProps, type SurfaceFocusConfig, 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, type Vec3, Verdict, type VerdictProps, type ViewFocusConfig, 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, cameraForBounds, caseKind, caseTooltip, casesInSource, createLinkedViewStore, createVizLoop, deckPosition, deckWindow, detailTier, explodedOffsets, firstAppearance, flowSpeed, flyCamera, groupByCategory, isStale, layoutSceneCallouts, makeStateKey, perPageFor, prefersReducedMotion, readCaseParam, readTheme, removeQueryParam, replaceQueryParam, runStagedTransition, sceneEnvironment, sourcesPresent, useFocusMode, useLinkedCursor, useLinkedItem, useLinkedView, usePausedViz, useStageSize, useThemeStore, useUrlView, useWorkbenchState, validateExecutive, viewParamOf, withCaseParam };
+export { BREAKPOINTS, BarChart, type BarChartProps, type BarDatum, BiText, Callout, type CalloutBox, type CalloutHeights, type CalloutState, type CameraFlyOptions, type CameraFrame, type CameraPose, CardDeck, type CardDeckProps, type CaseDef, type CaseFocusConfig, type CaseGroup, type CaseKind, CaseSelector, type CaseSelectorProps, type CaseSelectorText, CaseWorkbench, type CaseWorkbenchProps, ChipGroup, type ChipGroupProps, type ChipOption, type Citation, CitationsProvider, Cite, DECK_TEXT, DOC_AREAS, type DeckCard, type DetailTier, DocPage, type DocPageProps, DocReferences, DocRefsScope, DocSection, type DocSectionProps, EXECUTIVE_SCHEMA_VERSION, Equation, type ExecutiveData, type ExecutiveProblem, ExecutiveView, type ExecutiveViewProps, type ExplodedPart, FLIP_LIMITS, FLIP_TEXT, FOCUS_PARAM, FOCUS_TEXT, FOUR_CS, Figure, FlipCard, type FlipCardProps, type FocusMode, type FocusModeConfig, type FocusModeOptions, FocusShell, type FocusShellProps, FormatOptions, Gauge, type GaugeProps, type GaugeZone, Glossary, type GlossaryEntry, InlineMath, Knob, type KnobProps, Landing, type Lane, LaneBadge, Lang, LanguageToggle, LinkedViewProvider, type LinkedViewSide, type LinkedViewState, type LinkedViewStore, MAX_PEER_TABS, MAX_WORKBENCH_GROUPS, type MotionOptions, type MotionStage, PanelBoundary, type PausedVizController, PlotCard, type PlotCardProps, type Provenance, Question, type QuestionProps, type RailSection, Readout, type ReadoutItem, type ReadoutProps, ReferenceList, Refs, Scene3DFrame, type Scene3DFrameProps, type SceneBounds, type SceneCalloutDef, SceneCallouts, type SceneEnvironment, type SelectionOrigin, Stage, type StageSize, Stat, type StatProps, type StoryAccent, StoryFrame, type StoryFrameProps, type StoryStep, type SubTabDef, SubTabs, type SubTabsProps, type SurfaceFocusConfig, 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, type Vec3, Verdict, type VerdictProps, type ViewFocusConfig, 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, cameraForBounds, caseKind, caseTooltip, casesInSource, createLinkedViewStore, createVizLoop, deckPosition, deckWindow, detailTier, explodedOffsets, firstAppearance, flowSpeed, flyCamera, groupByCategory, isStale, layoutCalloutHeader, layoutSceneCallouts, makeStateKey, perPageFor, prefersReducedMotion, readCaseParam, readTheme, removeQueryParam, replaceQueryParam, runStagedTransition, sceneEnvironment, sourcesPresent, useFocusMode, useLinkedCursor, useLinkedItem, useLinkedView, usePausedViz, useStageSize, useThemeStore, useUrlView, useWorkbenchState, validateExecutive, viewParamOf, withCaseParam };

package/dist/index.js

@@ -702,6 +702,53 @@ function usePausedViz(frame, options = {}) {
   const restart = useCallback(() => loopRef.current?.restart(), []);
   return { playing, play, pause, toggle, restart };
 }
+function SelectDisplay({ names, selectedName, children }) {
+  const wrapRef = useRef(null);
+  const [minHeight, setMinHeight] = useState(null);
+  const nameKey = names.join("
");
+  useLayoutEffect(() => {
+    const wrap = wrapRef.current;
+    const display = wrap?.querySelector(".cs-select-display");
+    if (!wrap || !display) return void 0;
+    const all = nameKey ? nameKey.split("
") : [];
+    const measure = () => {
+      const st = getComputedStyle(display);
+      const room = display.clientWidth - parseFloat(st.paddingLeft) - parseFloat(st.paddingRight);
+      if (!(room > 0)) return;
+      const copy = document.createElement("span");
+      copy.className = "cs-select-text";
+      copy.setAttribute("aria-hidden", "true");
+      copy.setAttribute("style", `position:absolute;visibility:hidden;left:0;top:0;width:${room}px;display:block;overflow:visible;max-height:none;-webkit-line-clamp:unset;line-clamp:unset`);
+      display.append(copy);
+      let tallest = 0;
+      for (const n of all) {
+        copy.textContent = n;
+        tallest = Math.max(tallest, copy.getBoundingClientRect().height);
+      }
+      const line = parseFloat(getComputedStyle(copy).lineHeight) || parseFloat(st.fontSize) * 1.25;
+      copy.remove();
+      const frame = parseFloat(st.paddingTop) + parseFloat(st.paddingBottom) + parseFloat(st.borderTopWidth) + parseFloat(st.borderBottomWidth);
+      const next = tallest > line * 1.5 ? Math.ceil((tallest + frame) * 100) / 100 : null;
+      setMinHeight((prev) => prev === next ? prev : next);
+    };
+    measure();
+    let width = wrap.getBoundingClientRect().width;
+    const ro = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(() => {
+      const w = wrap.getBoundingClientRect().width;
+      if (w !== width) {
+        width = w;
+        measure();
+      }
+    });
+    ro?.observe(wrap);
+    void document.fonts?.ready.then(measure);
+    return () => ro?.disconnect();
+  }, [nameKey]);
+  return /* @__PURE__ */ jsxs("div", { className: "cs-select-wrap", ref: wrapRef, children: [
+    /* @__PURE__ */ jsx("div", { className: "cs-select-display", style: minHeight === null ? void 0 : { minHeight }, "aria-hidden": "true", children: /* @__PURE__ */ jsx("span", { className: "cs-select-text", children: selectedName }) }),
+    children
+  ] });
+}
 
 // src/case/caseModel.ts
 var caseKind = (c) => c.kind ?? "synthetic";
@@ -798,47 +845,6 @@ function CaseSelector(props) {
   const visible = casesInSource(cases, source);
   const groups = groupByCategory(visible);
   const modified = cases.find((c) => c.id === modifiedFromId) ?? null;
-  const wrapRef = useRef(null);
-  const [minHeight, setMinHeight] = useState(null);
-  const nameKey = visible.map((c) => c.name).join("
");
-  useLayoutEffect(() => {
-    const wrap = wrapRef.current;
-    const display = wrap?.querySelector(".cs-select-display");
-    if (!wrap || !display) return void 0;
-    const names = nameKey ? nameKey.split("
") : [];
-    const measure = () => {
-      const st = getComputedStyle(display);
-      const room = display.clientWidth - parseFloat(st.paddingLeft) - parseFloat(st.paddingRight);
-      if (!(room > 0)) return;
-      const copy = document.createElement("span");
-      copy.className = "cs-select-text";
-      copy.setAttribute("aria-hidden", "true");
-      copy.setAttribute("style", `position:absolute;visibility:hidden;left:0;top:0;width:${room}px;display:block;overflow:visible;max-height:none;-webkit-line-clamp:unset;line-clamp:unset`);
-      display.append(copy);
-      let tallest = 0;
-      for (const n of names) {
-        copy.textContent = n;
-        tallest = Math.max(tallest, copy.getBoundingClientRect().height);
-      }
-      const line = parseFloat(getComputedStyle(copy).lineHeight) || parseFloat(st.fontSize) * 1.25;
-      copy.remove();
-      const frame = parseFloat(st.paddingTop) + parseFloat(st.paddingBottom) + parseFloat(st.borderTopWidth) + parseFloat(st.borderBottomWidth);
-      const next = tallest > line * 1.5 ? Math.ceil((tallest + frame) * 100) / 100 : null;
-      setMinHeight((prev) => prev === next ? prev : next);
-    };
-    measure();
-    let width = wrap.getBoundingClientRect().width;
-    const ro = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(() => {
-      const w = wrap.getBoundingClientRect().width;
-      if (w !== width) {
-        width = w;
-        measure();
-      }
-    });
-    ro?.observe(wrap);
-    void document.fonts?.ready.then(measure);
-    return () => ro?.disconnect();
-  }, [layout, nameKey]);
   const options = groups.flatMap((g) => g.cases);
   const selectedName = (options.find((c) => c.id === selectedId) ?? options.find((c) => !c.disabled))?.name ?? "";
   const select = /* @__PURE__ */ jsx(
@@ -852,10 +858,7 @@ function CaseSelector(props) {
       children: groups.map((g) => /* @__PURE__ */ jsx("optgroup", { label: g.category || " ", children: g.cases.map((c) => /* @__PURE__ */ jsx("option", { value: c.id, disabled: c.disabled, title: caseTooltip(c) || void 0, children: c.name }, c.id)) }, g.category || "_"))
     }
   );
-  const selectBox = /* @__PURE__ */ jsxs("div", { className: "cs-select-wrap", ref: wrapRef, children: [
-    /* @__PURE__ */ jsx("div", { className: "cs-select-display", style: minHeight === null ? void 0 : { minHeight }, "aria-hidden": "true", children: /* @__PURE__ */ jsx("span", { className: "cs-select-text", children: selectedName }) }),
-    select
-  ] });
+  const selectBox = /* @__PURE__ */ jsx(SelectDisplay, { names: visible.map((c) => c.name), selectedName, children: select });
   return /* @__PURE__ */ jsxs("div", { className: `cs${className ? ` ${className}` : ""}`, role: "group", "aria-label": ariaLabel ?? "Case selector", children: [
     source && lanes.length > 1 && /* @__PURE__ */ jsxs("div", { className: "cs-source", children: [
       /* @__PURE__ */ jsx("span", { className: "cs-source-label", children: t2.source }),
@@ -3824,23 +3827,24 @@ function LaneBadge({ lane, provenance, label }) {
     provenance && /* @__PURE__ */ jsx("span", { className: `badge caos-prov caos-prov-${provenance}`, "data-provenance": provenance, children: pick(PROVENANCE_LABELS[provenance], lang) })
   ] });
 }
-function VariantBar({ variants, activeId, onSelect, title, lane }) {
+function VariantBar({ variants, activeId, onSelect, title, lane, layout = "chips" }) {
   const lang = useShellLang();
   const active = variants.find((v) => v.id === activeId) ?? variants[0];
   const shownLane = active?.lane ?? lane;
   const rowRef = useRef(null);
   useOverflowFade(rowRef, ".chip.on", [active?.id, variants.length, lang]);
+  const name = pick(title ?? { en: "Variants", es: "Variantes" }, lang);
   return /* @__PURE__ */ jsxs("div", { className: "caos-variant-bar", "data-variant-bar": "", "data-variant-count": variants.length, children: [
     /* @__PURE__ */ jsxs("div", { className: "caos-variant-head", children: [
       /* @__PURE__ */ jsxs("span", { className: "caos-variant-title", children: [
-        pick(title ?? { en: "Variants", es: "Variantes" }, lang),
+        name,
         " (",
         variants.length,
         ")"
       ] }),
       shownLane && /* @__PURE__ */ jsx(LaneBadge, { lane: shownLane })
     ] }),
-    /* @__PURE__ */ jsx("div", { className: "caos-chip-row", role: "radiogroup", "aria-label": pick(title ?? { en: "Variants", es: "Variantes" }, lang), "data-control": "variant", ref: rowRef, children: variants.map((v) => /* @__PURE__ */ jsx(
+    layout === "select" ? /* @__PURE__ */ jsx(SelectDisplay, { names: variants.map((v) => pick(v.label, lang)), selectedName: active ? pick(active.label, lang) : "", children: /* @__PURE__ */ jsx("select", { "data-control": "variant", className: "select cs-select cs-select-native", "aria-label": name, value: active?.id ?? "", onChange: (e) => onSelect(e.target.value), children: variants.map((v) => /* @__PURE__ */ jsx("option", { value: v.id, disabled: v.disabled, children: pick(v.label, lang) }, v.id)) }) }) : /* @__PURE__ */ jsx("div", { className: "caos-chip-row", role: "radiogroup", "aria-label": name, "data-control": "variant", ref: rowRef, children: variants.map((v) => /* @__PURE__ */ jsx(
       "button",
       {
         type: "button",
@@ -4169,6 +4173,15 @@ function StoryFrame({ steps, activeId, onStepChange, onExit, labels = {}, autoAd
   const activeIndex = Math.max(0, steps.findIndex((step) => step.id === activeId));
   const active = steps[activeIndex];
   const copy = useMemo(() => ({ ...DEFAULT_LABELS, ...labels }), [labels]);
+  const stepper = useRef(null);
+  useEffect(() => {
+    const row = stepper.current;
+    const link = row?.querySelector('[aria-current="step"]');
+    if (!row || !link) return;
+    const r = row.getBoundingClientRect(), l = link.getBoundingClientRect();
+    if (l.left < r.left) row.scrollLeft -= r.left - l.left;
+    else if (l.right > r.right) row.scrollLeft += Math.min(l.right - r.right, l.left - r.left);
+  }, [activeId]);
   useEffect(() => {
     if (steps.length < 3 || steps.length > 6) console.error("[caos-app-shell] A showcase story has 3 to 6 steps (ADR-0082 rule 3)");
   }, [steps.length]);
@@ -4232,7 +4245,7 @@ function StoryFrame({ steps, activeId, onStepChange, onExit, labels = {}, autoAd
         }, children: pick(copy.exit, lang) })
       ] })
     ] }),
-    /* @__PURE__ */ jsx("nav", { className: "caos-story-stepper", role: "tablist", "aria-label": pick(copy.steps, lang), children: steps.map((step) => /* @__PURE__ */ jsxs(Link, { role: "tab", "aria-selected": step.id === active.id, "aria-current": step.id === active.id ? "step" : void 0, to: step.href, "data-story-link": step.id, className: step.id === active.id ? "caos-story-step is-active" : "caos-story-step", onClick: () => {
+    /* @__PURE__ */ jsx("nav", { ref: stepper, className: "caos-story-stepper", role: "tablist", "aria-label": pick(copy.steps, lang), children: steps.map((step) => /* @__PURE__ */ jsxs(Link, { role: "tab", "aria-selected": step.id === active.id, "aria-current": step.id === active.id ? "step" : void 0, to: step.href, "data-story-link": step.id, className: step.id === active.id ? "caos-story-step is-active" : "caos-story-step", onClick: () => {
       setPlaying(false);
       onStepChange(step.id);
     }, children: [
@@ -4250,14 +4263,22 @@ function StoryFrame({ steps, activeId, onStepChange, onExit, labels = {}, autoAd
     ] }, active.id)
   ] });
 }
+var STATE_LABELS = {
+  alarm: { glyph: "\u25B2", en: "alarm", es: "alarma" },
+  warning: { glyph: "\u25C6", en: "warning", es: "aviso" },
+  normal: { glyph: "\u25CF", en: "normal", es: "normal" },
+  selected: { glyph: "\u25CE", en: "selected", es: "seleccionado" },
+  inactive: { glyph: "\u25CB", en: "inactive", es: "inactivo" }
+};
 var overlaps = (a, b) => a.left < b.left + b.width && a.left + a.width > b.left && a.top < b.top + b.height && a.top + a.height > b.top;
 var coversAnchor = (box, x, y, clearance = 8) => x >= box.left - clearance && x <= box.left + box.width + clearance && y >= box.top - clearance && y <= box.top + box.height + clearance;
-function layoutSceneCallouts(items, width, height, compact = false) {
+function layoutSceneCallouts(items, width, height, compact = false, heights) {
   const w = compact ? 142 : 184;
-  const h = compact ? 56 : 68;
+  const nominal = compact ? 56 : 68;
   const margin = 8;
   const boxes = [];
   for (const item of items) {
+    const h = heights?.[item.id] ?? nominal;
     const x = Math.max(0, Math.min(width, item.anchor.x * width));
     const y = Math.max(0, Math.min(height, item.anchor.y * height));
     const d = compact ? 82 : 112;
@@ -4275,19 +4296,67 @@ function layoutSceneCallouts(items, width, height, compact = false) {
   }
   return boxes;
 }
-function layoutCalloutHeader(items, width, height, compact = false) {
-  const w = compact ? 164 : 184, h = compact ? 54 : 68, margin = 8, gap = compact ? 6 : 8;
-  const columns = width < 520 ? 2 : Math.max(1, Math.min(items.length, Math.floor((width - margin * 2 + gap) / (w + gap))));
-  return items.map((item, index) => {
-    const column = index % columns, row = Math.floor(index / columns), count = Math.min(columns, items.length - row * columns);
-    const cell = (width - margin * 2 - gap * (count - 1)) / count;
-    return { id: item.id, left: margin + column * (cell + gap) + (cell - w) / 2, top: margin + row * (h + gap), width: w, height: h, anchorX: item.anchor.x * width, anchorY: item.anchor.y * height };
-  });
+function leadersCross(a, b) {
+  const [x1, y1, x2, y2] = [a.anchorX, a.anchorY, a.left + a.width / 2, a.top + a.height / 2];
+  const [x3, y3, x4, y4] = [b.anchorX, b.anchorY, b.left + b.width / 2, b.top + b.height / 2];
+  const d = (x2 - x1) * (y4 - y3) - (y2 - y1) * (x4 - x3);
+  if (Math.abs(d) < 1e-9) return false;
+  const t2 = ((x3 - x1) * (y4 - y3) - (y3 - y1) * (x4 - x3)) / d;
+  const u = ((x3 - x1) * (y2 - y1) - (y3 - y1) * (x2 - x1)) / d;
+  return t2 > 1e-6 && t2 < 1 - 1e-6 && u > 1e-6 && u < 1 - 1e-6;
+}
+function* orders(n, prefix = []) {
+  if (prefix.length === n) {
+    yield prefix;
+    return;
+  }
+  for (let i = 0; i < n; i += 1) if (!prefix.includes(i)) yield* orders(n, [...prefix, i]);
 }
-function SceneCallouts({ items, className, placement = "anchored" }) {
+function layoutCalloutHeader(items, width, height, compact = false, heights) {
+  const nominalW = compact ? 164 : 184, nominalH = compact ? 54 : 68, margin = 8, gap = compact ? 6 : 8;
+  const minW = compact ? 140 : nominalW;
+  const sorted = items.map((item, index) => ({ item, index })).sort((a, b) => a.item.anchor.x - b.item.anchor.x || a.index - b.index).map(({ item }) => item);
+  if (!sorted.length) return [];
+  const columns = Math.max(1, Math.min(sorted.length, Math.floor((width - margin * 2 + gap) / (minW + gap))));
+  const place = (slots) => {
+    const boxes = [];
+    let top = margin;
+    for (let start = 0; start < slots.length; start += columns) {
+      const row = slots.slice(start, start + columns);
+      const cell = (width - margin * 2 - gap * (row.length - 1)) / row.length;
+      const w = Math.max(0, Math.min(nominalW, cell));
+      const rowHeight = Math.max(...row.map((item) => heights?.[item.id] ?? nominalH));
+      row.forEach((item, column) => boxes.push({ id: item.id, left: margin + column * (cell + gap) + (cell - w) / 2, top, width: w, height: heights?.[item.id] ?? nominalH, anchorX: item.anchor.x * width, anchorY: item.anchor.y * height }));
+      top += rowHeight + gap;
+    }
+    return boxes;
+  };
+  const crossings = (boxes) => {
+    let count = 0;
+    for (let i = 0; i < boxes.length; i += 1) for (let j = i + 1; j < boxes.length; j += 1) if (leadersCross(boxes[i], boxes[j])) count += 1;
+    return count;
+  };
+  let best = place(sorted);
+  let fewest = crossings(best);
+  if (fewest > 0 && sorted.length <= 6) {
+    for (const order of orders(sorted.length)) {
+      const boxes = place(order.map((i) => sorted[i]));
+      const count = crossings(boxes);
+      if (count < fewest) {
+        best = boxes;
+        fewest = count;
+        if (count === 0) break;
+      }
+    }
+  }
+  const at = new Map(best.map((box) => [box.id, box]));
+  return sorted.map((item) => at.get(item.id));
+}
+function SceneCallouts({ items, className, placement = "anchored", onLayout }) {
   const lang = useShellLang();
   const host = useRef(null);
   const [size, setSize] = useState({ width: 0, height: 0 });
+  const [heights, setHeights] = useState({});
   useEffect(() => {
     const node = host.current;
     if (!node) return;
@@ -4298,15 +4367,44 @@ function SceneCallouts({ items, className, placement = "anchored" }) {
     observer.observe(node);
     return () => observer.disconnect();
   }, []);
+  const ids = items.map((item) => item.id).join("\0");
+  useEffect(() => {
+    const node = host.current;
+    if (!node) return;
+    const observer = new ResizeObserver((entries) => setHeights((previous) => {
+      let next = previous;
+      for (const entry of entries) {
+        const id = entry.target.dataset.caosCallout;
+        const measured2 = entry.borderBoxSize?.[0]?.blockSize ?? entry.target.offsetHeight;
+        if (id === void 0 || !(measured2 > 0) || Math.abs((previous[id] ?? -1) - measured2) <= 0.25) continue;
+        if (next === previous) next = { ...previous };
+        next[id] = measured2;
+      }
+      return next;
+    }));
+    node.querySelectorAll("[data-caos-callout]").forEach((card) => observer.observe(card));
+    return () => observer.disconnect();
+  }, [ids, placement]);
+  const compact = size.width < 640;
   const boxes = useMemo(() => {
-    if (placement === "anchored") return layoutSceneCallouts(items, size.width, size.height, size.width < 640);
-    return layoutCalloutHeader(items, size.width, size.height, size.width < 640);
-  }, [items, placement, size]);
-  return /* @__PURE__ */ jsxs("div", { ref: host, className: ["caos-callout-layer", className].filter(Boolean).join(" "), "aria-label": lang === "es" ? "Valores fijados a los componentes" : "Values anchored to components", "data-caos-callout-layer": "", "data-placement": placement, children: [
+    if (placement === "anchored") return layoutSceneCallouts(items, size.width, size.height, compact, heights);
+    return layoutCalloutHeader(items, size.width, size.height, compact, heights);
+  }, [items, placement, size, compact, heights]);
+  const nominalH = placement === "anchored" ? compact ? 56 : 68 : compact ? 54 : 68;
+  const bandHeight = placement === "header" && boxes.length ? Math.max(...boxes.map((box) => box.top + box.height)) : 0;
+  const measured = items.every((item) => heights[item.id] !== void 0);
+  const report = useRef(onLayout);
+  report.current = onLayout;
+  useEffect(() => {
+    if (placement === "header" && size.width > 0 && measured) report.current?.({ bandHeight });
+  }, [placement, size.width, measured, bandHeight]);
+  const style = placement === "header" ? { "--caos-callout-band": `${bandHeight}px` } : void 0;
+  return /* @__PURE__ */ jsxs("div", { ref: host, className: ["caos-callout-layer", className].filter(Boolean).join(" "), style, "aria-label": lang === "es" ? "Valores fijados a los componentes" : "Values anchored to components", "data-caos-callout-layer": "", "data-placement": placement, children: [
     /* @__PURE__ */ jsx("svg", { className: "caos-callout-leaders", "aria-hidden": "true", viewBox: `0 0 ${Math.max(1, size.width)} ${Math.max(1, size.height)}`, preserveAspectRatio: "none", children: boxes.map((box) => /* @__PURE__ */ jsx("line", { x1: box.anchorX, y1: box.anchorY, x2: box.left + box.width / 2, y2: box.top + box.height / 2, "data-caos-callout-leader": box.id }, box.id)) }),
     boxes.map((box) => {
       const item = items.find((candidate) => candidate.id === box.id);
-      return /* @__PURE__ */ jsxs("article", { className: "caos-scene-callout", "data-caos-callout": item.id, "data-callout-value": item.value, "data-callout-unit": pick(item.unit, lang), "data-callout-state": item.state, "data-callout-source": pick(item.source, lang), "data-callout-anchor-x": item.anchor.x, "data-callout-anchor-y": item.anchor.y, style: { left: box.left, top: box.top, width: box.width, minHeight: box.height }, children: [
+      const state = Object.prototype.hasOwnProperty.call(STATE_LABELS, item.state) ? STATE_LABELS[item.state] : null;
+      return /* @__PURE__ */ jsxs("article", { className: "caos-scene-callout", "data-caos-callout": item.id, "data-callout-value": item.value, "data-callout-unit": pick(item.unit, lang), "data-callout-state": item.state, "data-callout-source": pick(item.source, lang), "data-callout-anchor-x": item.anchor.x, "data-callout-anchor-y": item.anchor.y, style: { left: box.left, top: box.top, width: box.width, minHeight: nominalH }, children: [
         /* @__PURE__ */ jsx("span", { className: "caos-callout-eyebrow", title: pick(item.eyebrow, lang), children: pick(item.eyebrow, lang) }),
         /* @__PURE__ */ jsxs("strong", { title: `${item.value} ${pick(item.unit, lang)}`, children: [
           item.value,
@@ -4314,6 +4412,10 @@ function SceneCallouts({ items, className, placement = "anchored" }) {
           /* @__PURE__ */ jsx("small", { children: pick(item.unit, lang) })
         ] }),
         item.trend && /* @__PURE__ */ jsx("span", { className: `caos-callout-trend trend-${item.trend}`, "aria-label": item.trend, children: item.trend === "up" ? "\u2191" : item.trend === "down" ? "\u2193" : "\u2192" }),
+        state && /* @__PURE__ */ jsxs("span", { className: "caos-callout-state", "data-callout-state-label": "", children: [
+          /* @__PURE__ */ jsx("span", { className: "caos-callout-state-glyph", "aria-hidden": "true", "data-callout-state-glyph": "", children: state.glyph }),
+          state[lang]
+        ] }),
         /* @__PURE__ */ jsx("small", { className: "caos-callout-source", title: pick(item.source, lang), children: pick(item.source, lang) })
       ] }, box.id);
     })
@@ -4453,4 +4555,4 @@ function sceneEnvironment(theme) {
   return theme === "dark" ? { background: "#101a22", ground: "#202b33", key: { color: "#fff0d5", intensity: 2.1, castShadow: true }, fill: { color: "#98c5db", intensity: 0.8 }, ambient: { color: "#c9d7df", intensity: 1.1 } } : { background: "#e9eef0", ground: "#d6dee1", key: { color: "#fff8e9", intensity: 1.7, castShadow: true }, fill: { color: "#8eabb9", intensity: 0.65 }, ambient: { color: "#ffffff", intensity: 1.35 } };
 }
 
-export { AppShell, ArchitectureModal, BREAKPOINTS, BarChart, Callout, CardDeck, CaseSelector, CaseWorkbench, ChipGroup, CitationsProvider, Cite, DECK_TEXT, DOC_AREAS, DocPage, DocReferences, DocRefsScope, DocSection, EXECUTIVE_SCHEMA_VERSION, Equation, ExecutiveView, FLIP_LIMITS, FLIP_TEXT, FOCUS_PARAM, FOCUS_TEXT, FOUR_CS, Figure, FlipCard, FocusShell, Gauge, Glossary, InlineMath, Knob, Landing, LaneBadge, LanguageToggle, LinkedViewProvider, MAX_PEER_TABS, MAX_WORKBENCH_GROUPS, PanelBoundary, PlotCard, Question, Readout, ReferenceList, Refs, Scene3DFrame, SceneCallouts, Stat, StoryFrame, SubTabs, SurfacePage, TabGroups, Tabs, ThemeToggle, VariantBar, Verdict, ViewsRow, WorkbenchLayout, WorkbenchShell, WorkbenchStateContext, cameraForBounds, caseKind, caseTooltip, casesInSource, createLinkedViewStore, createVizLoop, deckPosition, deckWindow, detailTier, explodedOffsets, firstAppearance, flowSpeed, flyCamera, groupByCategory, isStale, layoutSceneCallouts, makeStateKey, perPageFor, prefersReducedMotion, readCaseParam, removeQueryParam, replaceQueryParam, runStagedTransition, sceneEnvironment, sourcesPresent, useFocusMode, useLinkedCursor, useLinkedItem, useLinkedView, usePausedViz, useUrlView, useWorkbenchState, validateArchitectureConfig, validateExecutive, viewParamOf, withCaseParam };
+export { AppShell, ArchitectureModal, BREAKPOINTS, BarChart, Callout, CardDeck, CaseSelector, CaseWorkbench, ChipGroup, CitationsProvider, Cite, DECK_TEXT, DOC_AREAS, DocPage, DocReferences, DocRefsScope, DocSection, EXECUTIVE_SCHEMA_VERSION, Equation, ExecutiveView, FLIP_LIMITS, FLIP_TEXT, FOCUS_PARAM, FOCUS_TEXT, FOUR_CS, Figure, FlipCard, FocusShell, Gauge, Glossary, InlineMath, Knob, Landing, LaneBadge, LanguageToggle, LinkedViewProvider, MAX_PEER_TABS, MAX_WORKBENCH_GROUPS, PanelBoundary, PlotCard, Question, Readout, ReferenceList, Refs, Scene3DFrame, SceneCallouts, Stat, StoryFrame, SubTabs, SurfacePage, TabGroups, Tabs, ThemeToggle, VariantBar, Verdict, ViewsRow, WorkbenchLayout, WorkbenchShell, WorkbenchStateContext, cameraForBounds, caseKind, caseTooltip, casesInSource, createLinkedViewStore, createVizLoop, deckPosition, deckWindow, detailTier, explodedOffsets, firstAppearance, flowSpeed, flyCamera, groupByCategory, isStale, layoutCalloutHeader, layoutSceneCallouts, makeStateKey, perPageFor, prefersReducedMotion, readCaseParam, removeQueryParam, replaceQueryParam, runStagedTransition, sceneEnvironment, sourcesPresent, useFocusMode, useLinkedCursor, useLinkedItem, useLinkedView, usePausedViz, useUrlView, useWorkbenchState, validateArchitectureConfig, validateExecutive, viewParamOf, withCaseParam };

package/gate/inpage.mjs

@@ -1583,6 +1583,8 @@ export function installLib() {
     const callouts = [...(stage?.querySelectorAll('[data-caos-callout]') ?? [])].filter(visible).map((element) => ({
       id: element.getAttribute('data-caos-callout'), value: element.getAttribute('data-callout-value'), unit: element.getAttribute('data-callout-unit'),
       state: element.getAttribute('data-callout-state'), source: element.getAttribute('data-callout-source'),
+      // the state as a reader sees it besides the colour (ADR-0082 rule 8): the visible text of the state label, empty when hidden or absent
+      stateLabel: (() => { const label = element.querySelector('[data-callout-state-label]'); return label && visible(label) ? (label.innerText ?? label.textContent ?? '').trim() : ''; })(),
       anchor: { x: Number(element.getAttribute('data-callout-anchor-x')), y: Number(element.getAttribute('data-callout-anchor-y')) }, box: box(element),
     }));
     const links = [...(story?.querySelectorAll('[data-story-link]') ?? [])].filter(visible).map((element) => ({ id: element.getAttribute('data-story-link'), href: element.getAttribute('href'), active: element.getAttribute('aria-selected') === 'true' }));

package/gate/run.mjs

@@ -35,6 +35,10 @@
 //   G20 chart interactions   every chart is one tab stop with an accessible name, described by a table of its values and a one-line summary,
 //                            and a zoomed chart resets (the + key zooms, the visible control shows, the 0 key resets); a chart that turns zoom
 //                            off says why (12 letters and digits at least) and is listed among the waivers (0.19.0)
+//   G21 showcase story       with --require-showcase: a directly linked 3 to 6 step story; its callouts carry value, unit, provenance and
+//                            a state shown as a word (not by colour alone), leave their own anchor clear, never overlap, stay on the stage
+//                            and have a leader each, at every size, theme and language of the matrix (0.24.0); interactions, motion and
+//                            performance at the primary size
 // plus the ADR-0071 and ADR-0017 measures (viewport, one-row tabs, rail without scroll, centred prose, captions,
 // references).
 
@@ -128,6 +132,7 @@ export async function runGate(o) {
   const focusReported = new Set(); // G18: an App without a Focus control is reported once per route and mode
   const waivers = []; // ADR-0017 2.1: every waiver a documentation page declares, with its verdict
   const docWalks = []; // the document walk's cost per state (samples and time against the budget it earned), for the report
+  const storyContexts = []; // G21: every context (size, theme, language) whose story routes had their callouts measured (0.24.0)
   // The smallest measured values against each floor, so a pass shows its margin (and a CI font change that eats it
   // is visible before it fails).
   const minima = { drawnShare: null, stageFill: null };
@@ -416,12 +421,41 @@ export async function runGate(o) {
       if (stories.length === 0) {
         fail('G21', { route: '/story', mode: 'routes' }, 'no /story/<step> route is declared; ADR-0082 requires a directly addressable guided story');
       } else {
+        const STATES = ['alarm', 'warning', 'normal', 'selected', 'inactive'];
+        // The callout checks of one story route in one context: content, state shown by more than colour, the own anchor
+        // left clear, no overlap, inside the stage, one leader each, no horizontal overflow. They run at every size, theme
+        // and language of the gate matrix (known defect 59, 0.24.0): a card grows with its text, so a layout that holds at
+        // 1280 in English can overlap on a phone or in Spanish.
+        const calloutChecks = async (page, at, f) => {
+          for (const call of f.calls) {
+            if (!call.value?.trim() || !call.unit?.trim()) fail('G21', at, `callout ${call.id} has no value or unit`);
+            if (!STATES.includes(call.state)) fail('G21', at, `callout ${call.id} has no recognised semantic state`);
+            // ADR-0082 rule 8: a state is never shown by colour alone (a word or an icon with it)
+            else if (!/[\p{L}]/u.test(call.stateLabel ?? '')) fail('G21', at, `callout ${call.id} shows its state by colour alone: no visible data-callout-state-label with its word (ADR-0082 rule 8)`);
+            if (!call.source?.trim()) fail('G21', at, `callout ${call.id} has no value provenance`);
+            if (![call.anchor?.x, call.anchor?.y].every((v) => Number.isFinite(v) && v >= 0 && v <= 1)) fail('G21', at, `callout ${call.id} has no normalized subject anchor`);
+            else if (call.box && f.stage) {
+              const x = f.stage.left + call.anchor.x * f.stage.width, y = f.stage.top + call.anchor.y * f.stage.height;
+              const clearance = 8;
+              if (x >= call.box.left - clearance && x <= call.box.right + clearance && y >= call.box.top - clearance && y <= call.box.bottom + clearance)
+                fail('G21', at, `callout ${call.id} covers its own subject anchor`);
+            }
+          }
+          for (let i = 0; i < f.calls.length; i += 1) for (let j = i + 1; j < f.calls.length; j += 1) {
+            const a = f.calls[i].box, b = f.calls[j].box;
+            if (a && b && a.left < b.right && a.right > b.left && a.top < b.bottom && a.bottom > b.top) fail('G21', at, `callouts ${f.calls[i].id} and ${f.calls[j].id} overlap`);
+          }
+          if (f.calls.some(({ box }) => !box || !f.stage || box.left < f.stage.left || box.right > f.stage.right || box.top < f.stage.top || box.bottom > f.stage.bottom)) fail('G21', at, 'one or more callouts escape the stage instead of following its subject');
+          if (f.calls.length && await page.locator('[data-story] [data-caos-callout-leader]').count() < f.calls.length) fail('G21', at, 'not every scene callout has a leader to its subject anchor');
+          if (f.scroll.width > f.viewport.width + 1) fail('G21', at, `story page overflows horizontally (${f.scroll.width}px in ${f.viewport.width}px)`);
+        };
         const size = primarySize;
         const [w, h] = size;
         const mode = `${w}x${h} ${themes[0]} ${langs[0]} story`;
         const ctx = await openContext(size, themes[0], langs[0]);
         const { page, sink } = await newPage(ctx);
         const visited = [];
+        storyContexts.push({ mode, routes: stories.length });
         for (const route of stories) {
           const at = { route, mode };
           const res = await page.goto(urlFor(route), { waitUntil: 'load', timeout: 30000 }).catch((e) => e);
@@ -440,28 +474,33 @@ export async function runGate(o) {
             if (share < 0.8) fail('G21', at, `story stage and docked panel cover ${(100 * share).toFixed(1)}% of the viewport (floor 80%, ADR-0082)`);
           }
           if (f.calls.length < 3) fail('G21', at, `stage has ${f.calls.length} visible anchored callouts; ADR-0082 requires at least 3`);
-          for (const call of f.calls) {
-            if (!call.value?.trim() || !call.unit?.trim()) fail('G21', at, `callout ${call.id} has no value or unit`);
-            if (!['alarm', 'warning', 'normal', 'selected', 'inactive'].includes(call.state)) fail('G21', at, `callout ${call.id} has no recognised semantic state`);
-            if (!call.source?.trim()) fail('G21', at, `callout ${call.id} has no value provenance`);
-            if (![call.anchor?.x, call.anchor?.y].every((v) => Number.isFinite(v) && v >= 0 && v <= 1)) fail('G21', at, `callout ${call.id} has no normalized subject anchor`);
-            else if (call.box && f.stage) {
-              const x = f.stage.left + call.anchor.x * f.stage.width, y = f.stage.top + call.anchor.y * f.stage.height;
-              const clearance = 8;
-              if (x >= call.box.left - clearance && x <= call.box.right + clearance && y >= call.box.top - clearance && y <= call.box.bottom + clearance)
-                fail('G21', at, `callout ${call.id} covers its own subject anchor`);
-            }
-          }
-          for (let i = 0; i < f.calls.length; i += 1) for (let j = i + 1; j < f.calls.length; j += 1) {
-            const a = f.calls[i].box, b = f.calls[j].box;
-            if (a && b && a.left < b.right && a.right > b.left && a.top < b.bottom && a.bottom > b.top) fail('G21', at, `callouts ${f.calls[i].id} and ${f.calls[j].id} overlap`);
-          }
-          if (f.calls.some(({ box }) => !box || box.left < f.stage.left || box.right > f.stage.right || box.top < f.stage.top || box.bottom > f.stage.bottom)) fail('G21', at, 'one or more callouts escape the stage instead of following its subject');
-          if (f.calls.length && await page.locator('[data-story] [data-caos-callout-leader]').count() < f.calls.length) fail('G21', at, 'not every scene callout has a leader to its subject anchor');
-          if (f.scroll.width > f.viewport.width + 1) fail('G21', at, `story page overflows horizontally (${f.scroll.width}px in ${f.viewport.width}px)`);
+          await calloutChecks(page, at, f);
           visited.push({ route, step: f.step, hrefs: f.links.map((x) => x.href) });
           drain(sink, at);
         }
+        // Every other context of the gate matrix: the callout checks only. The performance and interaction checks below stay
+        // at the primary size. Console errors of these loads are not drained here: the main walk loads the same routes in the
+        // same contexts and reports them there once.
+        for (const s of sizes) for (const theme of themes) for (const lang of langs) {
+          if (s === primarySize && theme === themes[0] && lang === langs[0]) continue;
+          const smode = `${s[0]}x${s[1]} ${theme} ${lang} story`;
+          const sctx = await openContext(s, theme, lang);
+          const { page: sp, sink: ssink } = await newPage(sctx);
+          for (const route of stories) {
+            const at = { route, mode: smode };
+            const res = await sp.goto(urlFor(route), { waitUntil: 'load', timeout: 30000 }).catch((e) => e);
+            const status = res && typeof res.status === 'function' ? res.status() : `error ${res?.message ?? res}`;
+            if (status !== 200) { fail('G21', at, `direct story link answered ${status}`); ssink.splice(0); continue; }
+            const settled = await settle(sp);
+            if (settled) fail('G21', at, `story did not settle: ${settled}`);
+            const f = await sp.evaluate(() => window.__caosGate.showcaseFacts());
+            if (!f.present) fail('G21', at, 'route does not render [data-story]');
+            else await calloutChecks(sp, at, f);
+            ssink.splice(0);
+          }
+          storyContexts.push({ mode: smode, routes: stories.length });
+          await sctx.close();
+        }
         const first = visited.find((x) => x.hrefs.length >= 3);
         if (first) {
           const hrefs = [...new Set(first.hrefs.map((href) => routeOf(new URL(href, base).href)).filter(Boolean))];
@@ -1290,6 +1329,7 @@ export async function runGate(o) {
       minima,
       waivers,
       docWalks,
+      storyContexts,
       checks,
       captures: captures.length,
       failures,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fasl-work/caos-app-shell",
-  "version": "0.23.2",
+  "version": "0.25.0",
   "description": "Shared web-app shell, workbench primitives, content primitives, design system and measured gate for the CAOS / Faena public apps (ADR-0016, ADR-0017, ADR-0071).",
   "license": "MIT",
   "author": "Felipe Santibáñez-Leal",

package/reserved-classes.json

@@ -34,6 +34,8 @@
     "caos-callout-layer",
     "caos-callout-leaders",
     "caos-callout-source",
+    "caos-callout-state",
+    "caos-callout-state-glyph",
     "caos-callout-trend",
     "caos-card",
     "caos-chart",
@@ -392,6 +394,8 @@
     "caos-callout-layer",
     "caos-callout-leaders",
     "caos-callout-source",
+    "caos-callout-state",
+    "caos-callout-state-glyph",
     "caos-callout-trend",
     "caos-card",
     "caos-chart",

package/styles.css

@@ -1025,13 +1025,18 @@ svg.lucide { flex: none; }
 .caos-scene-callout[data-callout-state="warning"] { border-left-color: var(--color-warn); }
 .caos-scene-callout[data-callout-state="normal"] { border-left-color: var(--color-good); }
 .caos-scene-callout[data-callout-state="inactive"] { border-left-color: var(--color-fg-faint); }
-.caos-callout-eyebrow { overflow: hidden; color: var(--color-fg); font: 700 .68rem var(--font-mono); letter-spacing: .05em; text-overflow: ellipsis; white-space: nowrap; }
+/* The eyebrow wraps instead of ending in an ellipsis (0.24.0): the cards are laid out on their measured heights, so a longer
+   Spanish eyebrow ("Alimentación del molino" in a 164 px card) is read whole and the card grows. */
+.caos-callout-eyebrow { min-width: 0; color: var(--color-fg); font: 700 .68rem/1.25 var(--font-mono); letter-spacing: .05em; overflow-wrap: anywhere; }
 .caos-scene-callout > strong { overflow: hidden; font: 700 .92rem var(--font-mono); font-variant-numeric: tabular-nums; text-overflow: ellipsis; white-space: nowrap; }
 .caos-scene-callout > strong small,.caos-callout-source { color: var(--color-fg); font-size: .68rem; font-weight: 500; }
 .caos-callout-trend { grid-column: 2; grid-row: 1 / span 2; align-self: center; font-size: 1.1rem; font-weight: 800; }
 .caos-callout-trend.trend-up { color: var(--color-bad); }
 .caos-callout-trend.trend-down { color: var(--color-good); }
 .caos-callout-source { grid-column: 1 / -1; }
+/* The state as a word with a glyph of its own shape (ADR-0082 rule 8, known defect 58): the border colour is not the only sign. */
+.caos-callout-state { grid-column: 1 / -1; display: flex; align-items: center; gap: .3em; min-width: 0; color: var(--color-fg); font: 700 .64rem/1.2 var(--font-mono); letter-spacing: .04em; white-space: nowrap; }
+.caos-callout-state-glyph { flex: none; font-size: .95em; line-height: 1; }
 @media (max-width: 760px) {
   .app-shell.immersive { height: auto; min-height: 100dvh; overflow: visible; }
   .app-shell.immersive > .page { display: block; overflow: visible; }
@@ -1043,7 +1048,13 @@ svg.lucide { flex: none; }
   .caos-story-actions { width: 100%; flex-wrap: wrap; justify-content: space-between; gap: .35rem; }
   .caos-story-controls { flex: 1 1 auto; justify-content: flex-start; gap: .35rem; }
   .caos-story button { min-height: 34px; padding: .3rem .5rem; font-size: .78rem; white-space: nowrap; }
-  .caos-story-stepper { grid-auto-columns: minmax(90px, 1fr); grid-auto-flow: column; grid-template-columns: unset; overflow-x: auto; }
+  /* every verb whole on a phone (review m4 of 0.23.2): a step is at least as wide as its number and verb, the row scrolls on x and
+     StoryFrame keeps the active step inside it */
+  .caos-story-stepper { container-type: inline-size; grid-auto-columns: minmax(max-content, 1fr); grid-auto-flow: column; grid-template-columns: unset; overflow-x: auto; }
+  /* a step is never wider than its row (100cqi of the stepper): a verb longer than the row wraps inside it, so End always shows the
+     last step whole, whatever width the platform's font gives the verb (Linux CI's system font overflowed a 320 px row in 0.24.0's first candidate) */
+  .caos-story-step { max-width: 100cqi; }
+  .caos-story-step-verb { overflow: visible; text-overflow: clip; white-space: normal; overflow-wrap: anywhere; }
   .caos-story-step-headline { display: none; }
   .caos-story-layout { grid-template-columns: minmax(0, 1fr); grid-template-rows: minmax(max(46dvh, var(--caos-story-stage-minimum, 300px)), auto) auto; }
   .caos-story-panel { max-height: 30dvh; }