@fasl-work/caos-app-shell 0.22.0 → 0.23.1

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## [0.23.001] - 2026-11-07
+
+### Fixed
+
+- The gate's document walk (`G.readDocument`) verifies a long, fully readable documentation page instead of stopping at a fixed budget of 600 samples and 30 seconds (known defect 55, issue 196). The budget now scales with the document: every scrollport the walk visits grants the samples of its own grid (the positions along its scroll extent, y by x), and the time allowed is 30 seconds plus 500 ms for every sample granted, under two absolute ceilings (20,000 samples, 15 minutes), so a page that never settles still fails with the same message. The report lists the cost of every walked state (`docWalks`: samples and time against the budget earned).
+- The same walk counted a dense paragraph as unread when its inline math ended in a subscript and a comma followed at once: KaTeX builds a subscript from tables and an invisible 2px strut (`.vlist-s`) that overhang the math into the text beside it, and the hit test of the comma returned one of them instead of the paragraph. The hit test now looks through an element of the math that paints nothing at that point (no glyph of its own, no background, no border, no drawing) to the element beneath, and judges that by the unchanged rule (viewport, clip, scrollports, hit); math glyphs drawn over text still fail.
+
+### Adoption
+
+- No product change. A product pinned below 0.23.000 for this defect (CEFOP_DinHot, at 0.19.6) can move once a release carries this entry.
+
+## [0.23.000] - 2026-11-06
+
+### Added
+- Add the `StoryFrame.mobileStageMinHeight` option for products whose mobile scene, controls and three required callouts need a taller stage. The default remains 300 px and the panel stays below the stage. the product template's story showed the need when the 390 × 844 gate could not keep its plot labels, scrub control and callouts visible together.
+
 ## [0.22.000] - 2026-11-06
 
 ### Added

package/VERSION

@@ -1 +1 @@
-0.22.000
+0.23.001

package/dist/index.d.ts

@@ -1417,13 +1417,14 @@ interface StoryFrameProps {
         exit: BiText;
     }>;
     autoAdvanceMs?: number;
+    mobileStageMinHeight?: number;
     className?: string;
 }
 /**
  * A guided 3 to 6 step story over the same state as a product App. The product owns each step's real view and panel;
  * the shell owns the stepper, deep links, keyboard behavior, pause-on-interaction, and semantic structure (ADR-0082).
  */
-declare function StoryFrame({ steps, activeId, onStepChange, onExit, labels, autoAdvanceMs, className }: StoryFrameProps): react.JSX.Element | null;
+declare function StoryFrame({ steps, activeId, onStepChange, onExit, labels, autoAdvanceMs, mobileStageMinHeight, className }: StoryFrameProps): react.JSX.Element | null;
 
 type CalloutState = 'alarm' | 'warning' | 'normal' | 'selected' | 'inactive';
 interface SceneCalloutDef {

package/dist/index.js

@@ -4160,7 +4160,10 @@ var DEFAULT_LABELS = {
   pause: { en: "Pause story", es: "Pausar historia" },
   exit: { en: "Return to exploration", es: "Volver a explorar" }
 };
-function StoryFrame({ steps, activeId, onStepChange, onExit, labels = {}, autoAdvanceMs = 5e3, className }) {
+function StoryFrame({ steps, activeId, onStepChange, onExit, labels = {}, autoAdvanceMs = 5e3, mobileStageMinHeight = 300, className }) {
+  if (!Number.isInteger(mobileStageMinHeight) || mobileStageMinHeight < 300 || mobileStageMinHeight > 900) {
+    throw new RangeError("StoryFrame mobileStageMinHeight must be an integer from 300 through 900 CSS pixels");
+  }
   const lang = useShellLang();
   const [playing, setPlaying] = useState(false);
   const activeIndex = Math.max(0, steps.findIndex((step) => step.id === activeId));
@@ -4204,7 +4207,7 @@ function StoryFrame({ steps, activeId, onStepChange, onExit, labels = {}, autoAd
     }
   }
   if (!active) return null;
-  return /* @__PURE__ */ jsxs("section", { className: ["caos-story", "page-body", "wide", className].filter(Boolean).join(" "), "data-story": "", "data-story-step": active.id, "data-step-accent": active.accent, "aria-label": pick(copy.steps, lang), tabIndex: 0, onKeyDown, children: [
+  return /* @__PURE__ */ jsxs("section", { className: ["caos-story", "page-body", "wide", className].filter(Boolean).join(" "), style: { "--caos-story-stage-minimum": `${mobileStageMinHeight}px` }, "data-story": "", "data-story-step": active.id, "data-step-accent": active.accent, "aria-label": pick(copy.steps, lang), tabIndex: 0, onKeyDown, children: [
     /* @__PURE__ */ jsxs("header", { className: "caos-story-header", children: [
       /* @__PURE__ */ jsxs("div", { className: "caos-story-heading", children: [
         /* @__PURE__ */ jsxs("span", { className: "caos-story-verb", children: [

package/gate/inpage.mjs

@@ -923,8 +923,14 @@ export function installLib() {
   /** SHG-079..082: collect glyph evidence by real scrolling, then compute the existing metric once.
    * No DOM-presence fallback: every word fragment must fit the viewport, original clip bounds,
    * scrollports and hit tests. Text-node identities deduplicate overlapping observations.
+   *
+   * The budget scales with the document (CAOS_APP_SHELL#196, known defect 55). A fixed count stopped a long, fully
+   * readable page. Now every scrollport the walk visits grants the samples of its own grid (the positions along its
+   * scroll extent, y by x, at the walk's viewport step), and the time allowed is `baseMs` plus `msPerSample` for every
+   * sample granted. `baseSamples` covers the first sample and the clicks of the flip cards and carousels. Two ceilings
+   * stay absolute, so a page that never settles still fails with the same message: `ceilingSamples`, `ceilingMs`.
    */
-  G.readDocument = async ({ maxSamples = 600, timeoutMs = 30000 } = {}) => {
+  G.readDocument = async ({ baseSamples = 100, baseMs = 30000, msPerSample = 500, ceilingSamples = 20000, ceilingMs = 900000 } = {}) => {
     const page = document.querySelector('[data-doc-page]');
     if (!page || !visible(page)) return null;
     const started = performance.now();
@@ -934,9 +940,11 @@ export function installLib() {
     const nodes = new Map(), witnessed = new Set(), flips = new Map(), decks = new Map();
     const inkContext = document.createElement('canvas').getContext('2d');
     if (!inkContext) throw new Error('document glyph measurement canvas is unavailable');
-    let samples = 0;
+    let samples = 0, granted = baseSamples;
+    const budget = () => ({ samples: Math.min(granted, ceilingSamples), ms: Math.min(baseMs + granted * msPerSample, ceilingMs) });
     const check = () => {
-      if (++samples > maxSamples || performance.now() - started > timeoutMs) throw new Error(`document traversal exceeded ${maxSamples} samples or ${timeoutMs}ms; active document remains unverified`);
+      const limit = budget();
+      if (++samples > limit.samples || performance.now() - started > limit.ms) throw new Error(`document traversal exceeded ${limit.samples} samples or ${Math.round(limit.ms)}ms; active document remains unverified`);
       if (!page.isConnected || state.some((e) => !e.isConnected || e.getAttribute('aria-selected') !== 'true')) throw new Error('document traversal changed the active page/tab');
     };
     const frame = () => new Promise((resolve) => nativeRaf ? nativeRaf(() => nativeRaf(resolve)) : setTimeout(resolve, 32));
@@ -1038,9 +1046,23 @@ export function installLib() {
         const first = Math.ceil(start), last = Math.floor(end) - 1;
         return first <= last ? Math.max(first, Math.min(last, start + (end - start) * fraction)) : (start + end) / 2;
       };
+      // KaTeX builds a subscript from tables and a 2px strut (`.vlist-s`, a zero-width space in a 1px font) that overhang the
+      // box of the math into the text beside it, so the hit test of the first glyph after the math (a comma) returns a
+      // structural math element and not the paragraph. An element of the math that paints nothing at the point (no glyph of
+      // its own, no background, no border, no drawing) cannot hide the text: look through it at what lies beneath, and judge
+      // that by the same rule. A glyph of the math over the text is in the stack as a painting element, so it still fails.
+      const paints = (e) => {
+        if (/^(svg|img|canvas|video)$/i.test(e.tagName) || e.closest('svg')) return true;
+        if ([...e.childNodes].some((c) => c.nodeType === 3 && /[^\s\u200b]/.test(c.nodeValue))) return true;
+        const cs = getComputedStyle(e);
+        return (parseColor(cs.backgroundColor)?.a ?? 0) > 0 || cs.backgroundImage !== 'none'
+          || ['Top', 'Right', 'Bottom', 'Left'].some((side) => parseFloat(cs[`border${side}Width`]) > 0 && (parseColor(cs[`border${side}Color`])?.a ?? 0) > 0);
+      };
+      const inert = (e) => !parent.closest('.katex') && Boolean(e.closest('.katex')) && !paints(e);
       for (const q of [0.15, 0.5, 0.85]) for (const v of [0.15, 0.5, 0.85]) {
         const x = sampleAt(rect.left, rect.right, q), y = sampleAt(rect.top, rect.bottom, v);
-        const hit = document.elementFromPoint(x, y);
+        let hit = document.elementFromPoint(x, y);
+        if (hit && inert(hit)) hit = document.elementsFromPoint(x, y).find((e) => !inert(e)) ?? null;
         const transparentFallthrough = getComputedStyle(parent).pointerEvents === 'none' && hit?.contains(parent);
         if (!hit || !(hit === parent || (control ? parent.contains(hit) : transparentFallthrough)) || pseudoCover(parent,x,y)) return false;
         const link = parent.closest('a[href]');
@@ -1108,13 +1130,14 @@ export function installLib() {
     const positions = (max, size) => {
       const out = [0], step = Math.max(16, Math.floor(size * 0.65));
       for (let p = step; p < max; p += step) {
-        if (out.length > maxSamples) throw new Error('document scroll extent exceeds traversal budget');
+        if (out.length > ceilingSamples) throw new Error('document scroll extent exceeds traversal budget');
         out.push(p);
       }
       if (max > 0) out.push(max);
       return out;
     };
     const sweep = async () => {
+      granted += 1;
       sample();
       const containers = [...ancestorsUntil(page, document.body), page, ...page.querySelectorAll('*')].filter(scrollable);
       const de = document.scrollingElement;
@@ -1125,7 +1148,9 @@ export function installLib() {
         const s = getComputedStyle(e);
         const maxX = /auto|scroll/.test(s.overflowX) ? e.scrollWidth - e.clientWidth : 0;
         const maxY = e === de || /auto|scroll/.test(s.overflowY) ? e.scrollHeight - e.clientHeight : 0;
-        for (const y of positions(maxY, Math.min(e.clientHeight, innerHeight))) for (const x of positions(maxX, Math.min(e.clientWidth, innerWidth))) {
+        const ys = positions(maxY, Math.min(e.clientHeight, innerHeight)), xs = positions(maxX, Math.min(e.clientWidth, innerWidth));
+        granted += ys.length * xs.length; // this scrollport's grid is the work the budget must cover
+        for (const y of ys) for (const x of xs) {
           // A settled card/animated illustration may reduce incidental overflow between frames.
           // Clamp to the real extent; coverage still requires every fragment, never a partial word.
           const wantedX = Math.min(x, e.scrollWidth - e.clientWidth), wantedY = Math.min(y, e.scrollHeight - e.clientHeight);
@@ -1184,7 +1209,10 @@ export function installLib() {
         }
       }
       docEvidence = evidence;
-      return G.docPage();
+      const doc = G.docPage();
+      // what the walk cost, so a gate run can report samples and time per state
+      if (doc) doc.walk = { samples, budgetSamples: budget().samples, ms: Math.round(performance.now() - started), budgetMs: Math.round(budget().ms) };
+      return doc;
     } finally {
       docEvidence = null;
       try {

package/gate/run.mjs

@@ -127,6 +127,7 @@ export async function runGate(o) {
   const failures = [];
   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
   // 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 };
@@ -642,7 +643,7 @@ export async function runGate(o) {
     if (s.walkState?.doc) {
       try {
         const d = await page.evaluate(() => window.__caosGate.readDocument());
-        if (d) s.walkState.doc.push(d);
+        if (d) { s.walkState.doc.push(d); if (d.walk) docWalks.push({ route: where.route, lang: s.lang, trail: where.trail, ...d.walk }); }
       } catch (e) {
         fail('ADR-0017.2', where, `document readability traversal could not complete: ${e.message.split('\n')[0]}`);
       }
@@ -1288,6 +1289,7 @@ export async function runGate(o) {
       states,
       minima,
       waivers,
+      docWalks,
       checks,
       captures: captures.length,
       failures,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fasl-work/caos-app-shell",
-  "version": "0.22.0",
+  "version": "0.23.1",
   "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/styles.css

@@ -1044,9 +1044,9 @@ svg.lucide { flex: none; }
   .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; }
   .caos-story-step-headline { display: none; }
-  .caos-story-layout { grid-template-columns: minmax(0, 1fr); grid-template-rows: minmax(46dvh, 1fr) auto; }
+  .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; }
-  .caos-story-stage { min-height: 300px; }
+  .caos-story-stage { min-height: max(300px, var(--caos-story-stage-minimum, 300px)); }
   .caos-scene-callout { padding: .25rem .35rem; }
 }
 @media (prefers-reduced-motion: reduce) {