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

package/CHANGELOG.md

@@ -1,3 +1,24 @@
+## [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.24.000

package/dist/index.d.ts

@@ -1451,13 +1451,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 +1606,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

@@ -4169,6 +4169,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 +4241,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 +4259,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 +4292,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 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" }) {
+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 +4363,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 +4408,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 +4551,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.24.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; }