@fasl-work/caos-app-shell 0.19.12 → 0.20.0

package/gate/run.mjs

@@ -9,8 +9,8 @@
 //                            are JSON, not the HTML fallback; a missing asset answers 404; doc text clears a floor
 //   G5 scroll and reach      boxes inside the viewport, the rail and their scrollers; tall views scroll; nothing is
 //                            cut; truncated text carries its full text; a select shows its whole selected text (0.17.0); every control reachable by the pointer
-//   G6 painted area          drawing surfaces have painted pixels, fill their stage, and cover at least half the
-//                            viewport on the App route, measured on the screenshot, never on a host box
+//   G6 painted area          drawing surfaces have painted pixels, fill their stage, and cover at least 60% of the
+//                            viewport on the App route, measured on the screenshot, never on a host box (ADR-0082)
 //   G7 walk everything       every route, tab, sub-tab and case, at five sizes, both themes, both languages,
 //                            waiting for declared state (data-state, data-stale, data-drawn), never networkidle
 //   G8 idle at rest          no sustained animation frames or DOM mutations after load and after a tab switch
@@ -55,7 +55,7 @@ export const DEFAULTS = {
   idleMs: 3000,
   settleMs: 15000,
   textFloor: 400,
-  instrumentMin: 0.5,
+  instrumentMin: 0.6,
   stageFillMin: 0.3,
   stageFloor: 140,
   viewportMinWidth: 1280,
@@ -64,6 +64,7 @@ export const DEFAULTS = {
   wideFont: true,
   wideFontSizes: '390x844,1280x800',
   requireFocus: false,
+  requireShowcase: false,
 };
 
 /** The wide fallback font of the G10 pass: wider than the Windows and macOS sans fonts; DejaVu Sans is what a Linux
@@ -243,7 +244,6 @@ export async function runGate(o) {
       if (res.status() !== 404) fail('G4', { route: '/__caos_gate_missing__.json' }, `a missing asset answered ${res.status()}, not 404 (an SPA fallback hides missing artifacts and broken deep links)`);
       await ctx.close();
     }
-
     // ---- G1: the subject, and the route list (from the header nav unless given).
     let routes = opt.routes ? String(opt.routes).split(',').map((r) => r.trim()).filter(Boolean) : null;
     {
@@ -265,6 +265,7 @@ export async function runGate(o) {
       sink.splice(0);
       await ctx.close();
     }
+    const storyRoutes = new Set(routes.filter((route) => /^\/story(?:\/|$)/.test(route)));
 
     // ---- G18 on a surface App: under --require-focus the App route must be among the measured routes, or nothing would be measured
     if (opt.requireFocus && workbenchRoutes.size === 0 && !routes.includes(appRoute)) {
@@ -380,7 +381,7 @@ export async function runGate(o) {
 
           if (primary) {
             // ADR-0071 rule 9 / G5: every header route reached by a real pointer click from the App route.
-            for (const route of routes.filter((r) => r !== workbenchRoute)) {
+            for (const route of routes.filter((r) => r !== workbenchRoute && !storyRoutes.has(r))) {
               await page.goto(urlFor(workbenchRoute), { waitUntil: 'load', timeout: 30000 }).catch(() => undefined);
               await settle(page);
               const link = page.locator('header nav a[href]');
@@ -408,6 +409,159 @@ export async function runGate(o) {
       }
     }
 
+    // ---- G21 (ADR-0082): a required showcase story must be a real, directly addressable 3–6 step experience.
+    if (opt.requireShowcase) {
+      const stories = routes.filter((route) => /^\/story(?:\/|$)/.test(route));
+      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 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 = [];
+        for (const route of stories) {
+          const at = { route, mode };
+          const res = await page.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}`); continue; }
+          const settled = await settle(page);
+          if (settled) fail('G21', at, `story did not settle: ${settled}`);
+          const f = await page.evaluate(() => window.__caosGate.showcaseFacts());
+          if (!f.present) { fail('G21', at, 'route does not render [data-story]'); continue; }
+          if (f.count < 3 || f.count > 6) fail('G21', at, `story has ${f.count} visible steps; ADR-0082 requires 3 to 6`);
+          if (!f.headline || !/\d/.test(f.headline)) fail('G21', at, `step headline does not state a numeric finding ("${f.headline}")`);
+          if (f.headlineWords > 12) fail('G21', at, `finding headline has ${f.headlineWords} words; ADR-0082 caps it at 12`);
+          if (!f.stage || !f.panel || !f.layout) fail('G21', at, 'story needs one visible stage and one docked panel');
+          if (f.layout && w >= opt.viewportMinWidth) {
+            const share = (f.layout.width * f.layout.height) / (w * h);
+            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)`);
+          visited.push({ route, step: f.step, hrefs: f.links.map((x) => x.href) });
+          drain(sink, at);
+        }
+        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))];
+          if (hrefs.length < 3 || hrefs.some((href) => !stories.includes(href))) fail('G21', { route: first.route, mode }, `stepper links do not directly address at least three declared story steps (${hrefs.join(', ') || 'none'})`);
+          await page.goto(urlFor(first.route), { waitUntil: 'load', timeout: 30000 }).catch(() => undefined);
+          await settle(page);
+          const perf = await page.evaluate(() => window.__caosGate.storyPerformanceFacts());
+          if (perf.lcp === null || perf.lcp > 2500) fail('G21', { route: first.route, mode }, `story LCP is ${perf.lcp === null ? 'unavailable' : `${perf.lcp.toFixed(0)} ms`}; ADR-0082 ceiling is 2500 ms`);
+          const assetBytes = perf.assets3d.reduce((sum, asset) => sum + asset.bytes, 0);
+          if (perf.assets3d.some((asset) => !asset.bytes)) fail('G21', { route: first.route, mode }, 'a 3D asset has no measurable compressed transfer size');
+          if (assetBytes > 15 * 1024 * 1024) fail('G21', { route: first.route, mode }, `compressed 3D assets total ${(assetBytes / 1024 / 1024).toFixed(2)} MiB; ADR-0082 ceiling is 15 MiB`);
+          const main = page.locator('[data-story]').first();
+          await main.focus().catch(() => undefined);
+          await page.keyboard.press('End').catch(() => undefined);
+          await page.waitForFunction((step) => window.__caosGate.showcaseFacts().step !== step, first.step, { timeout: 3000 }).catch(() => undefined);
+          const endFacts = await page.evaluate(() => window.__caosGate.showcaseFacts());
+          if (endFacts.step === first.step) fail('G21', { route: first.route, mode }, 'End key does not move the story to its final step');
+          await page.keyboard.press('Home').catch(() => undefined);
+          await page.waitForFunction((step) => window.__caosGate.showcaseFacts().step === step, first.step, { timeout: 3000 }).catch(() => undefined);
+          const homeFacts = await page.evaluate(() => window.__caosGate.showcaseFacts());
+          if (homeFacts.step !== first.step) fail('G21', { route: first.route, mode }, 'Home key does not return the story to its first step');
+          const sceneItem = page.locator('[data-story] [data-linked-view="scene"][data-linked-id]').first();
+          const panelItem = (id) => page.locator(`[data-story] [data-linked-view="panel"][data-linked-id="${id}"]`).first();
+          if (!(await sceneItem.count())) fail('G21', { route: first.route, mode }, 'story has no selectable linked scene objects');
+          else {
+            const id = await sceneItem.getAttribute('data-linked-id');
+            const panelMatch = panelItem(id);
+            if (!(await panelMatch.count())) fail('G21', { route: first.route, mode }, `scene object ${id} has no linked panel item`);
+            else {
+              await sceneItem.evaluate((el) => el.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true, view: window })));
+              await page.waitForFunction((target) => document.querySelector(`[data-linked-view="panel"][data-linked-id="${CSS.escape(target)}"][data-linked-selected="true"]`), id, { timeout: 2000 }).catch(() => undefined);
+              if (await panelMatch.getAttribute('data-linked-selected') !== 'true') fail('G21', { route: first.route, mode }, `selecting scene object ${id} does not select the matching panel item`);
+              await panelMatch.evaluate((el) => el.dispatchEvent(new MouseEvent('click', { bubbles: true, cancelable: true, view: window })));
+              await page.waitForFunction((target) => document.querySelector(`[data-linked-view="scene"][data-linked-id="${CSS.escape(target)}"][data-linked-selected="true"]`), id, { timeout: 2000 }).catch(() => undefined);
+              if (await sceneItem.getAttribute('data-linked-selected') !== 'true') fail('G21', { route: first.route, mode }, `selecting panel item ${id} does not highlight the matching scene object`);
+            }
+          }
+          const cursorInput = page.locator('[data-story] [data-linked-cursor]').first();
+          if (!(await cursorInput.count())) fail('G21', { route: first.route, mode }, 'story has no shared scrub control for linked scene and plots');
+          else {
+            await cursorInput.evaluate((el) => { const input = el; const min = Number(input.min || 0), max = Number(input.max || 100); const next = String(Math.round(min + (max - min) * .63)); Object.getOwnPropertyDescriptor(HTMLInputElement.prototype, 'value').set.call(input, next); input.dispatchEvent(new Event('input', { bubbles: true })); input.dispatchEvent(new Event('change', { bubbles: true })); });
+            await page.waitForTimeout(80);
+            const cursorFacts = await page.evaluate(() => window.__caosGate.showcaseFacts());
+            const value = cursorFacts.cursorInputs[0]?.value;
+            if (!cursorFacts.cursors.length || cursorFacts.cursors.some((position) => position !== value)) fail('G21', { route: first.route, mode }, 'scrubbing does not move every linked-view marker to the same cursor');
+          }
+          const play = page.locator('[data-story] button[aria-pressed]').first();
+          if (!(await play.count())) fail('G21', { route: first.route, mode }, 'story has no play/pause control with an observable state');
+          else {
+            await play.click();
+            if (await play.getAttribute('aria-pressed') !== 'true') fail('G21', { route: first.route, mode }, 'play control does not enter playing state');
+            const link = page.locator('[data-story-link]').nth(1);
+            await link.click();
+            if (await page.locator('[data-story] button[aria-pressed]').first().getAttribute('aria-pressed') !== 'false') fail('G21', { route: first.route, mode }, 'story autoplay does not pause on reader interaction');
+          }
+          // Measure a real step change against ADR-0082: eased stage motion, interaction latency and frames while it moves.
+          await page.evaluate(() => { window.__caosGate.resetStoryInteractions(); window.__caosGate.storyFrameSample = window.__caosGate.sampleStoryFrames(1600); });
+          const next = page.locator('[data-story] .caos-story-controls button').nth(2);
+          if (await next.isEnabled()) {
+            await next.click();
+            await page.waitForTimeout(90);
+            const earlyMotion = await page.evaluate(() => window.__caosGate.showcaseFacts().motion);
+            await page.waitForTimeout(260);
+            const lateMotion = await page.evaluate(() => window.__caosGate.showcaseFacts().motion);
+            if (!earlyMotion || earlyMotion.animationName === 'none' || earlyMotion.animationName === 'auto' || earlyMotion.transform === 'none' || earlyMotion.transform === 'matrix(1, 0, 0, 1, 0, 0)') fail('G21', { route: first.route, mode }, 'story step has no visible eased stage transition');
+            else if (Number.parseFloat(earlyMotion.animationDuration) * (earlyMotion.animationDuration.endsWith('ms') ? 1 : 1000) < 200) fail('G21', { route: first.route, mode }, `normal stage transition is shorter than 200 ms (${earlyMotion.animationDuration})`);
+            if (!lateMotion || lateMotion.transform !== 'matrix(1, 0, 0, 1, 0, 0)') fail('G21', { route: first.route, mode }, 'the staged transition does not settle at its final state');
+          }
+          const frameFacts = await page.evaluate(() => window.__caosGate.storyFrameSample);
+          if (!frameFacts || frameFacts.median === null || frameFacts.p05 === null) fail('G21', { route: first.route, mode }, 'story animation frame rate could not be measured');
+          else {
+            if (frameFacts.median < 55) fail('G21', { route: first.route, mode }, `story median is ${frameFacts.median.toFixed(1)} fps; ADR-0082 floor is 55 fps`);
+            if (frameFacts.p05 < 30) fail('G21', { route: first.route, mode }, `story fifth-percentile frame rate is ${frameFacts.p05.toFixed(1)} fps; ADR-0082 floor is 30 fps`);
+          }
+          const interactions = await page.evaluate(() => window.__caosGate.storyPerformanceFacts().events);
+          if (!interactions.length) fail('G21', { route: first.route, mode }, 'browser interaction latency was not measurable');
+          else if (Math.max(...interactions.map((entry) => entry.duration)) > 200) fail('G21', { route: first.route, mode }, `story interaction latency is ${Math.max(...interactions.map((entry) => entry.duration)).toFixed(0)} ms; ADR-0082 ceiling is 200 ms`);
+          await page.emulateMedia({ reducedMotion: 'reduce' });
+          const anyOtherLink = page.locator('[data-story-link]').nth(1);
+          if (await anyOtherLink.count()) {
+            await anyOtherLink.click();
+            const reducedMotion = await page.evaluate(() => window.__caosGate.showcaseFacts().motion);
+            const durationMs = reducedMotion ? Number.parseFloat(reducedMotion.animationDuration) * (reducedMotion.animationDuration.endsWith('ms') ? 1 : 1000) : Infinity;
+            if (reducedMotion?.animationName !== 'none' && durationMs > 150) fail('G21', { route: first.route, mode: 'reduced motion' }, `stage motion lasts ${durationMs} ms with reduced motion requested; ceiling is 150 ms`);
+          }
+        }
+        // The mobile story uses one column: the docked panel follows the stage and the three critical callouts remain visible.
+        const mobile = await openContext([390, 844], themes[0], langs[0]);
+        const { page: phone, sink: phoneSink } = await newPage(mobile);
+        await phone.goto(urlFor(stories[0]), { waitUntil: 'load', timeout: 30000 }).catch(() => undefined);
+        await settle(phone);
+        const mobileFacts = await phone.evaluate(() => window.__caosGate.showcaseFacts());
+        if (mobileFacts.calls.length !== 3) fail('G21', { route: stories[0], mode: '390x844 mobile story' }, `mobile story shows ${mobileFacts.calls.length} callouts; ADR-0082 requires the three primary callouts`);
+        if (!mobileFacts.stage || !mobileFacts.panel || mobileFacts.panel.top < mobileFacts.stage.bottom - 1) fail('G21', { route: stories[0], mode: '390x844 mobile story' }, 'the docked panel does not sit below the scene on mobile');
+        if (mobileFacts.scroll.width > mobileFacts.viewport.width + 1) fail('G21', { route: stories[0], mode: '390x844 mobile story' }, `mobile story overflows horizontally (${mobileFacts.scroll.width}px in ${mobileFacts.viewport.width}px)`);
+        drain(phoneSink, { route: stories[0], mode: '390x844 mobile story' });
+        await mobile.close();
+        await ctx.close();
+      }
+    }
+
     // ---- G10: the wide-font pass. Every route, tab and sampled case again, in Spanish (the longer labels) when it is
     // measured, rendered in the wide fallback font from the first frame: what a reader with wider fonts sees.
     if (opt.wideFont !== false && opt.wideFontSizes) {
@@ -938,7 +1092,7 @@ export async function runGate(o) {
     const big = s.w >= opt.viewportMinWidth;
     if (big && f.rail && f.rail.scroll > f.rail.client + 1) fail('G18', at, `${label}: the rail scrolls (${f.rail.scroll}px of content in ${f.rail.client}px)`);
     if (f.tabRows.some((r) => r > 1)) fail('G18', at, `${label}: a tab row wraps onto ${Math.max(...f.tabRows)} rows`);
-    if (big && f.share < opt.instrumentMin) fail('G18', at, `${label}: the stage covers ${(100 * f.share).toFixed(1)}% of the viewport (floor ${(100 * opt.instrumentMin).toFixed(0)}%)`);
+    if (big && f.share < 0.8) fail('G18', at, `${label}: the stage covers ${(100 * f.share).toFixed(1)}% of the viewport (floor 80% on Focus and story routes, ADR-0082)`);
     if (f.exitInside === false) fail('G18', at, `${label}: the exit control is outside the viewport`);
     for (const c of f.covered) fail('G18', at, `${label}: ${c.chrome} covers the control "${c.control}" (the stage must clear the Focus chrome)`);
     if (f.cutSelects.count) fail('G5', at, `${label}: ${f.cutSelects.count} select(s) cut the selected text (a case name cut in its box, or a display that names another case than the one the select holds, or a plain select with a text wider than its room): ${f.cutSelects.list.join('; ')}`);

package/package.json

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

@@ -30,6 +30,11 @@
     "caos-bars-legend",
     "caos-bars-readout",
     "caos-bars-swatch",
+    "caos-callout-eyebrow",
+    "caos-callout-layer",
+    "caos-callout-leaders",
+    "caos-callout-source",
+    "caos-callout-trend",
     "caos-card",
     "caos-chart",
     "caos-chart-axis-title",
@@ -158,12 +163,34 @@
     "caos-readout-title",
     "caos-readout-unit",
     "caos-readout-value",
+    "caos-scene-callout",
+    "caos-scene3d-controls",
+    "caos-scene3d-frame",
+    "caos-scene3d-legend",
+    "caos-scene3d-renderer",
+    "caos-scene3d-status",
+    "caos-scene3d-viewport",
     "caos-stage",
     "caos-stale",
     "caos-stale-note",
     "caos-stale-overlay",
     "caos-stat-source",
     "caos-stat-value",
+    "caos-story",
+    "caos-story-actions",
+    "caos-story-controls",
+    "caos-story-header",
+    "caos-story-heading",
+    "caos-story-headline",
+    "caos-story-layout",
+    "caos-story-panel",
+    "caos-story-stage",
+    "caos-story-step",
+    "caos-story-step-headline",
+    "caos-story-step-number",
+    "caos-story-step-verb",
+    "caos-story-stepper",
+    "caos-story-verb",
     "caos-surface",
     "caos-surface-actions",
     "caos-surface-body",
@@ -318,12 +345,15 @@
     "fill",
     "fixed",
     "good",
+    "is-active",
     "live",
     "lucide",
     "on",
     "precomputed",
     "primary",
     "rev",
+    "trend-down",
+    "trend-up",
     "warn",
     "wide"
   ],
@@ -356,6 +386,11 @@
     "caos-bars-legend",
     "caos-bars-readout",
     "caos-bars-swatch",
+    "caos-callout-eyebrow",
+    "caos-callout-layer",
+    "caos-callout-leaders",
+    "caos-callout-source",
+    "caos-callout-trend",
     "caos-card",
     "caos-chart",
     "caos-chart-axis-title",
@@ -486,12 +521,34 @@
     "caos-readout-title",
     "caos-readout-unit",
     "caos-readout-value",
+    "caos-scene-callout",
+    "caos-scene3d-controls",
+    "caos-scene3d-frame",
+    "caos-scene3d-legend",
+    "caos-scene3d-renderer",
+    "caos-scene3d-status",
+    "caos-scene3d-viewport",
     "caos-stage",
     "caos-stale",
     "caos-stale-note",
     "caos-stale-overlay",
     "caos-stat-source",
     "caos-stat-value",
+    "caos-story",
+    "caos-story-actions",
+    "caos-story-controls",
+    "caos-story-header",
+    "caos-story-heading",
+    "caos-story-headline",
+    "caos-story-layout",
+    "caos-story-panel",
+    "caos-story-stage",
+    "caos-story-step",
+    "caos-story-step-headline",
+    "caos-story-step-number",
+    "caos-story-step-verb",
+    "caos-story-stepper",
+    "caos-story-verb",
     "caos-surface",
     "caos-surface-actions",
     "caos-surface-body",
@@ -595,6 +652,7 @@
     "header-sep",
     "hint",
     "icon-btn",
+    "is-active",
     "katex",
     "l-en",
     "l-es",
@@ -644,6 +702,8 @@
     "tone-good",
     "tone-neutral",
     "tone-warn",
+    "trend-down",
+    "trend-up",
     "two-col",
     "uplot",
     "warn",

package/styles.css

@@ -39,6 +39,11 @@
   --color-good: #3fb950;
   --color-warn: #d29922;
   --color-bad: #f85149;
+  --color-step-1: #56d4e5;
+  --color-step-2: #79c0ff;
+  --color-step-3: #d2a8ff;
+  --color-step-4: #7ee787;
+  --color-step-5: #ffca80;
   --color-shadow: 0 1px 2px rgba(0, 0, 0, 0.4), 0 6px 16px rgba(0, 0, 0, 0.45);
   color-scheme: dark;
 }
@@ -60,6 +65,11 @@
   --color-good: #197c36;
   --color-warn: #946300;
   --color-bad: #cf222e;
+  --color-step-1: #0550ae;
+  --color-step-2: #0969da;
+  --color-step-3: #6639ba;
+  --color-step-4: #1a7f37;
+  --color-step-5: #9a6700;
   --color-shadow: 0 1px 2px rgba(31, 35, 40, 0.06), 0 4px 10px rgba(31, 35, 40, 0.04);
 }
 
@@ -235,9 +245,11 @@ code, kbd { font-family: var(--font-mono); }
 /* A WORKBENCH or a SURFACE is not prose: capping an instrument at the reading width wastes every pixel beyond it. */
 .page-body.wide { max-width: var(--maxw-wide); padding-inline: 1.25rem; }
 .app-shell.fixed .page-body.wide { flex: 1 1 auto; min-height: 0; padding-top: 0.75rem; padding-bottom: 0.75rem; }
+.app-shell.fixed .page-body.wide.caos-wb { padding-top: 0.15rem; padding-bottom: 0.15rem; }
+.app-shell.fixed.contain:has(.caos-wb) > .site-header .header-inner { height: 48px; }
 
 /* Workbench (WorkbenchLayout): a sized rail beside the instrument, on the full viewport. */
-.caos-wb { display: grid; grid-template-columns: var(--rail-w) minmax(0, 1fr); gap: 0.9rem; align-items: stretch; min-width: 0; padding-top: 0.75rem; padding-bottom: 0.75rem; }
+.caos-wb { --rail-w: clamp(232px, 17vw, 320px); display: grid; grid-template-columns: var(--rail-w) minmax(0, 1fr); gap: 0.6rem; align-items: stretch; min-width: 0; padding-top: 0.4rem; padding-bottom: 0.4rem; }
 .page-body.wide.caos-wb { padding-inline: var(--space-4); }
 .caos-wb > * { min-width: 0; }
 .app-shell.fixed.contain > .page > .caos-wb { flex: 1 1 auto; min-height: 0; }
@@ -619,7 +631,7 @@ svg.lucide { flex: none; }
 .caos-verdict.compact .caos-verdict-text { margin: 0; }
 
 /* PlotCard: the frame every chart or table sits in. */
-.caos-plot { margin: 0; background: var(--color-surface); border: 1px solid var(--color-border); border-radius: var(--radius-lg); padding: 0.45rem 0.6rem 0.4rem; min-width: 0; }
+.caos-plot { margin: 0; background: var(--color-surface); border: 1px solid var(--color-border); border-radius: var(--radius-lg); padding: 0.25rem 0.6rem 0.2rem; min-width: 0; }
 .caos-plot-head { display: flex; flex-wrap: wrap; justify-content: space-between; align-items: center; gap: var(--space-2); margin-bottom: 0.2rem; font-style: normal; text-align: left; min-height: 1.5rem; min-width: 0; }
 .caos-plot-head .badge { font-size: 0.68rem; padding: 0.05rem 0.45rem; }
 .caos-plot-title { min-width: 0; overflow-wrap: anywhere; font-size: var(--text-sm); color: var(--color-fg-subtle); font-weight: 600; }
@@ -629,6 +641,7 @@ svg.lucide { flex: none; }
 .caos-plot-note { margin: 0.4rem 0 0; font-size: 0.78rem; color: var(--color-fg-faint); }
 .caos-plot.fill { display: flex; flex-direction: column; flex: 1 1 auto; min-height: 0; }
 .caos-plot.fill > .caos-plot-body { flex: 1 1 0; min-height: 0; overflow: hidden; }
+.caos-plot.fill > .caos-plot-body > .caos-table { height: 100%; }
 /* The note of a filling card keeps at most 35% of the card and scrolls beyond it, so the drawing keeps a floor
    (CAOS_APP_SHELL#95: a long note left plots of 10 to 90 px at 1280 x 800). */
 .caos-plot.fill > .caos-plot-note { flex: 0 1 auto; max-height: 35%; overflow-y: auto; }
@@ -641,14 +654,14 @@ svg.lucide { flex: none; }
   [data-caos-note-fit] .caos-plot.fill > .caos-plot-note { max-height: none; min-height: 0; }
 }
 
-/* The stage floor of a filling card (shell 0.11.2; the gate's G6 floor, `--stage-floor` 140 px). At 1280 px and wider the
+/* The stage floor of a filling card (shell 0.11.2; the gate's G6 floor, `--stage-floor` 146 px). At 1280 px and wider the
    body of a filling card, the box the gate measures, keeps at least the floor itself, so the card grows when its header
    or its note wraps (a narrow column, the Spanish title, two badges, the wide font) and the containing panel scrolls
    when the cards do not fit (ADR-0071; the rail never does). 0.11.1 derived a card height from a fixed chrome instead,
    and a header that wrapped to a third line left the stage under the floor (CAOS_Contraste 0.07.000: 138 px; a
    400 px column with a note: 106 px). Below 1280 px the document scrolls and nothing changes. */
 @media (min-width: 1280px) {
-  .caos-plot.fill > .caos-plot-body { min-height: var(--caos-stage-floor, 140px); }
+  .caos-plot.fill > .caos-plot-body { min-height: var(--caos-stage-floor, 146px); }
 }
 
 /* A row of views side by side. Every view of the row takes an equal share, a filling card included (known shell
@@ -713,6 +726,12 @@ svg.lucide { flex: none; }
 .caos-table th.caos-col-text, .caos-table td.caos-col-text { text-align: left; white-space: normal; min-width: 16ch; }
 .caos-table thead th { position: sticky; top: 0; background: var(--color-surface); color: var(--color-fg-subtle); font-weight: 600; border-bottom-color: var(--color-fg-faint); }
 .caos-table tbody tr:hover { background: var(--color-surface-2); }
+/* A full-height table is a plotted view too: use taller rows on a very tall desktop so its data occupies the
+   instrument instead of leaving the lower half of a 1440 px stage visually empty (ADR-0082 G6). */
+@media (min-width: 2400px) and (min-height: 1200px) {
+  .caos-plot.fill > .caos-plot-body > .caos-table th,
+  .caos-plot.fill > .caos-plot-body > .caos-table td { padding-block: 0.58rem; }
+}
 
 @media (max-width: 900px) {
   /* The views of a row stack; a filling view gets a fixed readable height instead of the panel's. */
@@ -931,6 +950,83 @@ svg.lucide { flex: none; }
 .tabs-has-slot > .tabs-slot { grid-column: 2; grid-row: 1; align-self: stretch; display: flex; align-items: center; padding-bottom: 0.4rem; margin-bottom: 0.9rem; border-bottom: 1px solid var(--color-border); }
 .tabs-has-slot > .tabs-slot > .caos-focus-enter { align-self: center; padding-block: 0.2rem; }
 .tabs-has-slot > .tabpanel { grid-column: 1 / -1; grid-row: 2; }
+
+/* ADR-0082 showcase frame: one focused stage, one docked panel, readable step navigation and anchored scene notes. */
+.caos-story { display: flex; flex-direction: column; gap: 0; min-width: 0; min-height: 0; height: 100%; padding: 0; color: var(--color-fg); background: var(--color-bg); }
+body:has([data-story]) .app-shell > .site-header,
+body:has([data-story]) .app-shell > .site-footer { display: none !important; }
+body:has([data-story]) .app-shell > .page { display: flex; flex: 1 1 auto; min-height: 0; overflow: hidden; padding: 0; }
+body:has([data-story]) .app-shell > .page > .caos-story { width: 100%; height: 100%; flex: 1 1 auto; }
+.caos-story-header { display: flex; align-items: center; justify-content: space-between; gap: var(--space-4); min-width: 0; }
+.caos-story-heading { min-width: 0; }
+.caos-story-verb { display: block; color: var(--color-step-1); font: 700 var(--text-xs) var(--font-mono); letter-spacing: .09em; text-transform: uppercase; }
+.caos-story-headline { margin: .1rem 0; font-size: clamp(1rem, 1.6vw, 1.45rem); line-height: 1.2; }
+.caos-story-heading > p { margin: .15rem 0 0; color: var(--color-fg-subtle); font-size: var(--text-sm); }
+.caos-story[data-step-accent="1"] .caos-story-verb { color: var(--color-step-1); }
+.caos-story[data-step-accent="2"] .caos-story-verb { color: var(--color-step-2); }
+.caos-story[data-step-accent="3"] .caos-story-verb { color: var(--color-step-3); }
+.caos-story[data-step-accent="4"] .caos-story-verb { color: var(--color-step-4); }
+.caos-story[data-step-accent="5"] .caos-story-verb { color: var(--color-step-5); }
+.caos-story-actions,.caos-story-controls { display: flex; align-items: center; gap: var(--space-2); }
+.caos-story button { min-height: 36px; padding: .35rem .65rem; color: var(--color-fg); background: var(--color-surface); border: 1px solid var(--color-border); border-radius: var(--radius-md); cursor: pointer; }
+.caos-story button:disabled { opacity: .55; cursor: not-allowed; }
+.caos-story-stepper { display: grid; grid-template-columns: repeat(auto-fit, minmax(120px, 1fr)); gap: var(--space-2); min-width: 0; }
+.caos-story-step { display: grid; grid-template-columns: auto minmax(0, 1fr); grid-template-rows: auto auto; align-items: center; column-gap: .55rem; min-width: 0; min-height: 40px; padding: .2rem .55rem; color: var(--color-fg-subtle); background: var(--color-surface); border: 1px solid var(--color-border); border-radius: var(--radius-md); text-decoration: none; }
+.caos-story-step:hover { color: var(--color-fg); text-decoration: none; }
+.caos-story-step.is-active { color: var(--color-fg); border-color: var(--color-accent); box-shadow: inset 3px 0 var(--color-accent); }
+.caos-story-step-number { grid-row: 1 / span 2; display: grid; place-items: center; width: 1.55rem; height: 1.55rem; border: 1px solid currentColor; border-radius: 50%; font: 700 var(--text-xs) var(--font-mono); }
+.caos-story-step-verb { overflow: hidden; color: var(--color-fg); font-weight: 700; text-overflow: ellipsis; white-space: nowrap; }
+.caos-story-step-headline { overflow: hidden; color: var(--color-fg-subtle); font-size: var(--text-xs); text-overflow: ellipsis; white-space: nowrap; }
+.caos-story-controls { justify-content: flex-end; }
+.caos-story-layout { display: grid; grid-template-columns: minmax(0, 1fr) minmax(260px, 29%); gap: var(--space-3); flex: 1 1 auto; min-width: 0; min-height: 0; }
+.caos-story-stage { position: relative; isolation: isolate; min-width: 0; min-height: 360px; overflow: hidden; background: var(--color-surface); border: 1px solid var(--color-border); border-radius: var(--radius-lg); }
+.caos-story-stage > :not(.caos-callout-layer) { width: 100%; height: 100%; }
+.caos-story-panel { min-width: 0; min-height: 0; overflow: auto; padding: var(--space-3); background: var(--color-surface); border: 1px solid var(--color-border); border-radius: var(--radius-lg); }
+/* A route change first moves the instrument into view, then the docked evidence panel; the sequence is short and tied to the finding. */
+[data-story-transition] > .caos-story-stage { animation: caos-story-stage-enter 320ms cubic-bezier(.2,.72,.26,1) both; }
+[data-story-transition] > .caos-story-panel { animation: caos-story-panel-enter 240ms cubic-bezier(.2,.72,.26,1) 100ms both; }
+@keyframes caos-story-stage-enter { from { transform: translateY(7px) scale(.994); } to { transform: translateY(0) scale(1); } }
+@keyframes caos-story-panel-enter { from { transform: translateY(6px); } to { transform: translateY(0); } }
+.caos-callout-layer { position: absolute; z-index: 4; inset: 0; overflow: hidden; pointer-events: none; }
+.caos-scene3d-frame { display: grid; grid-template-rows: auto minmax(0, 1fr); min-width: 0; min-height: 0; width: 100%; height: 100%; overflow: hidden; background: var(--color-bg); color: var(--color-fg); }
+.caos-scene3d-controls { display: flex; align-items: center; flex-wrap: wrap; gap: var(--space-2); min-width: 0; padding: var(--space-2) var(--space-3); border-block-end: 1px solid var(--color-border); background: var(--color-surface); }
+.caos-scene3d-viewport { position: relative; min-width: 0; min-height: 0; overflow: hidden; isolation: isolate; }
+.caos-scene3d-renderer, .caos-scene3d-renderer > canvas, .caos-scene3d-renderer > svg { display: block; width: 100%; height: 100%; min-width: 0; min-height: 0; }
+.caos-scene3d-status { position: absolute; inset-inline-start: var(--space-3); inset-block-end: var(--space-3); z-index: 2; max-width: min(32rem, calc(100% - 2 * var(--space-3))); padding: var(--space-2) var(--space-3); border: 1px solid var(--color-border); border-radius: var(--radius-sm); background: var(--color-surface); color: var(--color-fg); }
+.caos-scene3d-legend { position: absolute; inset-inline-end: var(--space-3); inset-block-end: var(--space-3); z-index: 2; max-width: min(24rem, calc(100% - 2 * var(--space-3))); padding: var(--space-2) var(--space-3); border: 1px solid var(--color-border); border-radius: var(--radius-sm); background: var(--color-surface); color: var(--color-fg); }
+.caos-callout-leaders { position: absolute; inset: 0; width: 100%; height: 100%; overflow: visible; pointer-events: none; }
+.caos-callout-leaders line { stroke: var(--color-fg-faint); stroke-width: 1.1; stroke-dasharray: 2 4; opacity: .52; }
+.caos-scene-callout { position: absolute; display: grid; grid-template-columns: minmax(0, 1fr) auto; align-content: center; gap: .05rem .4rem; padding: .35rem .5rem; color: var(--color-fg); background: color-mix(in srgb, var(--color-surface) 94%, transparent); border: 1px solid var(--color-border); border-left: 3px solid var(--color-accent); border-radius: var(--radius-md); box-shadow: var(--color-shadow); backdrop-filter: blur(8px); }
+.caos-scene-callout[data-callout-state="alarm"] { border-left-color: var(--color-bad); }
+.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; }
+.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; }
+@media (max-width: 760px) {
+  body:has([data-story]) .app-shell > .page { overflow-y: auto; }
+  .caos-story { height: auto; min-height: 100%; }
+  .caos-story-header { display: grid; grid-template-columns: minmax(0, 1fr); align-items: start; gap: .45rem; }
+  .caos-story-heading { width: 100%; }
+  .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; }
+  .caos-story-step-headline { display: none; }
+  .caos-story-layout { grid-template-columns: minmax(0, 1fr); grid-template-rows: minmax(46dvh, 1fr) auto; }
+  .caos-story-panel { max-height: 30dvh; }
+  .caos-story-stage { min-height: 300px; }
+  .caos-scene-callout { padding: .25rem .35rem; }
+}
+@media (prefers-reduced-motion: reduce) {
+  .caos-story *, .caos-callout-layer * { scroll-behavior: auto !important; animation-duration: .01ms !important; transition-duration: .01ms !important; }
+  [data-story-transition] > .caos-story-stage, [data-story-transition] > .caos-story-panel { animation: none !important; }
+}
 /* The same slot in the workbench's group tab row (shell 0.17.0, BL-074): the Focus control of the App ends the row, so the case select keeps
    the rail head's whole width. The tab row's own spacing (a tighter rule than the surface's) is repeated under the slot. */
 .caos-cw > .tabs.tabs-has-slot { display: grid; grid-template-columns: minmax(0, 1fr) auto; grid-template-rows: auto minmax(0, 1fr); column-gap: 0.5rem; }