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

package/CHANGELOG.md

@@ -1,3 +1,20 @@
+## [0.20.000] - 2026-11-05
+
+### Added
+
+- Add ADR-0082 showcase primitives: direct-link `StoryFrame`, sourced and unit-bearing scene callouts, reciprocal linked scene/panel selection and shared cursor hooks, eased story transitions with an instant reduced-motion path, 3D camera/bounds/rate/explosion/LOD/environment helpers, semantic state and story-accent tokens.
+- Add the renderer-agnostic `Scene3DFrame` for full-size product-owned scenes with separate controls, legend and availability; prevent callout cards from covering their authored subject anchors and make G21 fail on planted occlusion.
+- Raise the measured App drawing floor to 60% and Focus floor to 80%; extend G21 to check direct routes, 3–6 steps, numeric headlines of at most 12 words, stage/panel geometry, callout value/unit/state/provenance/anchor, reciprocal selection and cursor scrubbing, keyboard navigation, pause-on-interaction, reduced motion, mobile stacking, LCP, FPS, interaction latency and compressed 3D asset size.
+
+### Fixed
+
+- Tighten the contained workbench's vertical chrome so the App stage can meet the 60% visualization floor without removing product navigation or controls.
+
+### Evidence boundary
+
+- G21 checks that the story exposes traceable values, units, semantic states and provenance, and that its linked controls update reciprocally. The product gate still has to establish that each value and source describes its actual scientific artifact; the shell cannot infer product-domain truth.
+- The product SDD and visual review remain responsible for verifying that the six views answer their declared domain questions and that uncertainty and before/after comparisons use valid shared scales and data.
+
 ## [0.19.012] - 2026-11-01
 
 ### Fixed

package/VERSION

@@ -1 +1 @@
-0.19.012
+0.20.000

package/bin/caos-shell-gate.mjs

@@ -16,16 +16,18 @@
 //   --sizes 390x844,...,2560x1440  --themes light,dark  --langs en,es
 //   --case-sample id1,id2        cases walked outside the primary mode; default the first and the last
 //   --single-case                the workbench has one case and no case control
-//   --idle-ms 3000  --settle-ms 15000  --text-floor 400  --instrument-min 0.5  --stage-fill-min 0.3  --stage-floor 140
+//   --idle-ms 3000  --settle-ms 15000  --text-floor 400  --instrument-min 0.6  --stage-fill-min 0.3  --stage-floor 140
 //   --wide-font-sizes 390x844,1280x800   the sizes of the wide-font pass (G10); --no-wide-font skips it
 //   --require-focus              fail an App without a Focus control (G18; ADR-0070 requires one in a product with simulations); on a surface
 //                                App, one with no view that offers it
+//   --require-showcase            fail when no /story/<step> routes exist or the story misses ADR-0082's direct-link,
+//                                stage, panel, finding, callout, keyboard and pause checks (also pass story routes in --routes)
 //   --out gate-output            report (gate-report.json), screenshots (shots/) and the capture index (index.html)
 // Needs `playwright` in the consuming project (optional peer dependency). Exit 1 on any failure, 2 on misuse.
 
 import { runGate } from '../gate/run.mjs';
 
-const FLAGS = new Set(['single-case', 'no-wide-font', 'require-focus', 'spa-fallback']);
+const FLAGS = new Set(['single-case', 'no-wide-font', 'require-focus', 'require-showcase', 'spa-fallback']);
 const args = {};
 const argv = process.argv.slice(2);
 for (let i = 0; i < argv.length; i += 1) {
@@ -51,6 +53,7 @@ const options = {
   caseSample: args['case-sample'],
   singleCase: args['single-case'] === true,
   requireFocus: args['require-focus'] === true,
+  requireShowcase: args['require-showcase'] === true,
   spaFallback: args['spa-fallback'] === true,
   idleMs: num('idle-ms'),
   settleMs: num('settle-ms'),

package/dist/chart.d.ts

@@ -1,7 +1,7 @@
 import * as react from 'react';
 import uPlot from 'uplot';
-import { F as FormatOptions, S as ShellColorToken } from './tokens-BvU9bFPw.js';
-export { r as referenceLineName, a as repeatedLabels } from './tokens-BvU9bFPw.js';
+import { F as FormatOptions, S as ShellColorToken } from './tokens-CIdhVv-t.js';
+export { r as referenceLineName, a as repeatedLabels } from './tokens-CIdhVv-t.js';
 import { B as BiText, L as Lang } from './text-BlY47nIt.js';
 import 'zustand';
 

package/dist/chart.js

@@ -1,5 +1,5 @@
-import { pick, placeXLabel, placeYLabel, useShellLang, useThemeStore, useStageSize, defaultChartName, axisTitleFits, resolveToken, dateNames, DRAG_THRESHOLD, sameData, NBSP, formatNumber, thinRows, chartSummary, referenceLineName, ZOOM_HINT, CHART_ROLE, ChartSummary, ChartDataTable, ResetZoomButton, formatTicks, countOverlaps, isZoomed, formatTime, keyAction, KEY_PAN, KEY_ZOOM, firstVisible, stepIndex, wheelFactor, pinchState, repeatedLabels, panRange, zoomRange, revealValue, brushRange, leastLabelSpan, MIN_SPAN_SHARE } from './chunk-FXPSZD6X.js';
-export { referenceLineName, repeatedLabels } from './chunk-FXPSZD6X.js';
+import { pick, placeXLabel, placeYLabel, useShellLang, useThemeStore, useStageSize, defaultChartName, axisTitleFits, resolveToken, dateNames, DRAG_THRESHOLD, sameData, NBSP, formatNumber, thinRows, chartSummary, referenceLineName, ZOOM_HINT, CHART_ROLE, ChartSummary, ChartDataTable, ResetZoomButton, formatTicks, countOverlaps, isZoomed, formatTime, keyAction, KEY_PAN, KEY_ZOOM, firstVisible, stepIndex, wheelFactor, pinchState, repeatedLabels, panRange, zoomRange, revealValue, brushRange, leastLabelSpan, MIN_SPAN_SHARE } from './chunk-FPPJQC2J.js';
+export { referenceLineName, repeatedLabels } from './chunk-FPPJQC2J.js';
 import './chunk-33WTUQ7Q.js';
 import { useRef, useCallback, useState, useId, useEffect, useMemo } from 'react';
 import uPlot from 'uplot';

package/dist/{chunk-FXPSZD6X.js → chunk-FPPJQC2J.js}

@@ -90,6 +90,11 @@ var SHELL_TOKENS = [
   "--color-good",
   "--color-warn",
   "--color-bad",
+  "--color-step-1",
+  "--color-step-2",
+  "--color-step-3",
+  "--color-step-4",
+  "--color-step-5",
   "--color-shadow",
   "--font-sans",
   "--font-mono",

package/dist/index.d.ts

@@ -1,11 +1,12 @@
 export { A as APP_ROUTE, a as AppShell, b as ArchTab, c as ArchitectureConfig, d as ArchitectureModal, L as LANDING_ROUTE, e as LANG_STORAGE_KEY, S as STANDARD_ROUTES, f as ShellConfig, g as ShellRoute, T as THEME_BOOT_SCRIPT, h as THEME_STORAGE_KEY, v as validateArchitectureConfig } from './keys-DDQGijwQ.js';
 import * as react from 'react';
-import { ReactNode, Component, ErrorInfo } from 'react';
+import { ReactNode, Component, ErrorInfo, ChangeEvent } from 'react';
 import * as zustand from 'zustand';
-import { F as FormatOptions } from './tokens-BvU9bFPw.js';
-export { b as FittedLabel, N as NBSP, c as NOT_AVAILABLE, d as SCIENTIFIC_BELOW, e as SHELL_TOKENS, S as ShellColorToken, f as ShellToken, g as fitLabel, h as fontFamily, i as formatNumber, j as formatTicks, n as niceStep, k as niceTicks, l as resolveToken, t as textWidth, u as useFormat, m as useThemeTokens, w as widestLabel } from './tokens-BvU9bFPw.js';
+import { F as FormatOptions } from './tokens-CIdhVv-t.js';
+export { b as FittedLabel, N as NBSP, c as NOT_AVAILABLE, d as SCIENTIFIC_BELOW, e as SHELL_TOKENS, S as ShellColorToken, f as ShellToken, g as fitLabel, h as fontFamily, i as formatNumber, j as formatTicks, n as niceStep, k as niceTicks, l as resolveToken, t as textWidth, u as useFormat, m as useThemeTokens, w as widestLabel } from './tokens-CIdhVv-t.js';
 import { L as Lang, B as BiText } from './text-BlY47nIt.js';
 export { p as pick, u as useLangStore, a as useShellLang } from './text-BlY47nIt.js';
+import { StoreApi } from 'zustand/vanilla';
 
 /**
  * The landing route of a product (shell 0.13.0, Felipe 2026-10-13: "the shell and the apps must land at the Introduction,
@@ -1175,7 +1176,7 @@ interface WorkbenchLayoutProps {
  * Renders `.page-body.wide.caos-wb`: no reading-width cap (a workbench is not prose, ADR-0071 rule 2),
  * `min-width: 0` down the tree so no row pushes the page wider than the screen (rule 3), a rail with an
  * explicit width that never scrolls (rule 6), and an instrument marked `data-instrument` so the measured gate
- * can check that it covers at least half of the viewport (rule 8). Pair with `ShellConfig.contain`.
+ * can check that it covers at least 60% of the viewport, and Focus at least 80% (ADR-0082). Pair with `ShellConfig.contain`.
  */
 declare function WorkbenchLayout({ rail, railHead, children, railLabel, className }: WorkbenchLayoutProps): react.JSX.Element;
 
@@ -1268,7 +1269,7 @@ declare const MAX_WORKBENCH_GROUPS = 6;
  * parameters and live values; the instrument holds ONE row of at most six question groups in a fixed order (the
  * instrument groups, the variant comparison, the context write-up) and the open group's views, which take the
  * height that row leaves. Pickers, parameters and numbers sit in the rail so the drawing keeps the instrument
- * (rule 8: at least half the viewport is drawn).
+ * (rule 8: at least 60% of the viewport is drawn on the App route).
  *
  * It provides the selection's state key to every `PlotCard` and `Readout` in the rail and the instrument, so a view
  * still showing data for an earlier selection says so, and it writes `data-case`, `data-variant`, `data-source` and
@@ -1382,4 +1383,199 @@ interface ViewsRowProps {
  */
 declare function ViewsRow({ children, shares }: ViewsRowProps): react.JSX.Element;
 
-export { BREAKPOINTS, BarChart, type BarChartProps, type BarDatum, BiText, Callout, 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, DocPage, type DocPageProps, DocReferences, DocRefsScope, DocSection, type DocSectionProps, EXECUTIVE_SCHEMA_VERSION, Equation, type ExecutiveData, type ExecutiveProblem, ExecutiveView, type ExecutiveViewProps, 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, MAX_PEER_TABS, MAX_WORKBENCH_GROUPS, PanelBoundary, type PausedVizController, PlotCard, type PlotCardProps, type Provenance, Question, type QuestionProps, type RailSection, Readout, type ReadoutItem, type ReadoutProps, ReferenceList, Refs, Stage, type StageSize, Stat, type StatProps, type SubTabDef, SubTabs, type SubTabsProps, 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, 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, caseKind, caseTooltip, casesInSource, createVizLoop, deckPosition, deckWindow, firstAppearance, groupByCategory, isStale, makeStateKey, perPageFor, readCaseParam, readTheme, removeQueryParam, replaceQueryParam, sourcesPresent, useFocusMode, usePausedViz, useStageSize, useThemeStore, useUrlView, useWorkbenchState, validateExecutive, viewParamOf, withCaseParam };
+type StoryAccent = 1 | 2 | 3 | 4 | 5;
+interface StoryStep {
+    id: string;
+    number: number;
+    verb: BiText;
+    headline: BiText;
+    summary: BiText;
+    href: string;
+    accent: StoryAccent;
+    stage: ReactNode;
+    panel: ReactNode;
+}
+interface StoryFrameProps {
+    steps: StoryStep[];
+    activeId: string;
+    onStepChange: (id: string) => void;
+    onExit?: () => void;
+    labels?: Partial<{
+        steps: BiText;
+        previous: BiText;
+        next: BiText;
+        play: BiText;
+        pause: BiText;
+        exit: BiText;
+    }>;
+    autoAdvanceMs?: 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;
+
+type CalloutState = 'alarm' | 'warning' | 'normal' | 'selected' | 'inactive';
+interface SceneCalloutDef {
+    id: string;
+    eyebrow: BiText;
+    value: string;
+    /** Every displayed quantity carries its physical unit (or a domain ratio name). */
+    unit: BiText;
+    state: CalloutState;
+    anchor: {
+        x: number;
+        y: number;
+    };
+    /** Provenance or derivation for the displayed value, in the reader's language. */
+    source: BiText;
+    trend?: 'up' | 'down' | 'flat';
+}
+interface CalloutBox {
+    id: string;
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+    anchorX: number;
+    anchorY: 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 }: {
+    items: SceneCalloutDef[];
+    className?: string;
+    placement?: 'anchored' | 'header';
+}): react.JSX.Element;
+
+interface Scene3DFrameProps {
+    /** A concise accessible name for the authored 3D scene. */
+    label: string;
+    legendLabel?: string;
+    /** The product-owned WebGL/canvas/SVG renderer and controls. The shared shell never invents geometry. */
+    children: ReactNode;
+    controls?: ReactNode;
+    legend?: ReactNode;
+    status?: ReactNode;
+    className?: string;
+}
+/** Renderer-agnostic 3D composition frame: one full-size scene with separate controls, legend and availability. */
+declare function Scene3DFrame({ label, legendLabel, children, controls, legend, status, className }: Scene3DFrameProps): react.JSX.Element;
+
+type SelectionOrigin = 'scene' | 'panel' | 'series' | 'external';
+type LinkedViewSide = 'scene' | 'panel';
+interface LinkedViewState {
+    selectedId: string | null;
+    cursor: number | null;
+    seriesId: string | null;
+    origin: SelectionOrigin;
+    select: (id: string | null, origin: SelectionOrigin) => void;
+    scrub: (cursor: number | null) => void;
+    showSeries: (id: string | null) => void;
+}
+type LinkedViewStore = StoreApi<LinkedViewState>;
+declare function createLinkedViewStore(initial?: Partial<Pick<LinkedViewState, 'selectedId' | 'cursor' | 'seriesId'>>): LinkedViewStore;
+declare function LinkedViewProvider({ children, initial }: {
+    children: ReactNode;
+    initial?: Partial<Pick<LinkedViewState, 'selectedId' | 'cursor' | 'seriesId'>>;
+}): react.JSX.Element;
+/** Scene selection, panel selection and time scrubbing share one store rather than shadowing one another. */
+declare function useLinkedView<T>(selector: (state: LinkedViewState) => T): T;
+/** Attributes and action for one selectable object in either linked view; spread onto a native button or SVG group. */
+declare function useLinkedItem(id: string, side: LinkedViewSide): {
+    readonly 'data-linked-id': string;
+    readonly 'data-linked-view': LinkedViewSide;
+    readonly 'data-linked-selected': "true" | "false";
+    readonly 'aria-pressed': boolean;
+    readonly onClick: () => void;
+};
+/** Shared scrub value and marker metadata for a chart/profile input and its matching scene marker. */
+declare function useLinkedCursor(): {
+    readonly cursor: number | null;
+    readonly scrub: (cursor: number | null) => void;
+    readonly inputProps: {
+        readonly 'data-linked-cursor': "";
+        readonly value: number;
+        readonly onChange: (event: ChangeEvent<HTMLInputElement>) => void;
+    };
+    readonly markerProps: {
+        readonly 'data-linked-cursor-marker': "";
+        readonly 'data-linked-cursor-position': number | "";
+    };
+};
+
+interface MotionStage {
+    run: () => void;
+    durationMs?: number;
+}
+interface MotionOptions {
+    reducedMotion?: boolean;
+    signal?: AbortSignal;
+    onStage?: (index: number) => void;
+}
+declare function prefersReducedMotion(): boolean;
+/** Apply a sequence in reading order; reduced motion applies each state immediately. */
+declare function runStagedTransition(stages: MotionStage[], options?: MotionOptions): Promise<void>;
+interface CameraPose {
+    position: readonly [number, number, number];
+    target: readonly [number, number, number];
+}
+interface CameraFrame {
+    setPosition: (x: number, y: number, z: number) => void;
+    lookAt: (x: number, y: number, z: number) => void;
+}
+interface CameraFlyOptions extends MotionOptions {
+    durationMs?: number;
+    onFrame?: (progress: number) => void;
+}
+/** Eased, interruptible camera flight without binding the shell to a particular WebGL renderer. */
+declare function flyCamera(frame: CameraFrame, from: CameraPose, to: CameraPose, options?: CameraFlyOptions): Promise<void>;
+
+interface Vec3 {
+    x: number;
+    y: number;
+    z: number;
+}
+interface SceneBounds {
+    min: Vec3;
+    max: Vec3;
+}
+type DetailTier = 'high' | 'medium' | 'low';
+interface ExplodedPart {
+    id: string;
+    center: Vec3;
+}
+interface SceneEnvironment {
+    background: string;
+    ground: string;
+    key: {
+        color: string;
+        intensity: number;
+        castShadow: boolean;
+    };
+    fill: {
+        color: string;
+        intensity: number;
+    };
+    ambient: {
+        color: string;
+        intensity: number;
+    };
+}
+/** Frame a model from its authored bounds and camera aspect. The margin keeps end geometry out of the frustum. */
+declare function cameraForBounds(bounds: SceneBounds, aspect: number, fovDegrees?: number, margin?: number): {
+    target: readonly [number, number, number];
+    position: readonly [number, number, number];
+    distance: number;
+};
+/** A bounded, monotone encoding for stream animation; zero flow is static and high rates never become frantic. */
+declare function flowSpeed(rate: number, referenceRate: number): number;
+/** Stable radial separation for authored cutaway parts, centred on the model bounds. */
+declare function explodedOffsets(parts: ExplodedPart[], scale?: number): Record<string, Vec3>;
+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 };