@fasl-work/caos-app-shell 0.6.8 → 0.7.0

package/dist/index.d.ts

@@ -1,105 +1,11 @@
+export { A as AppShell, a as ArchTab, b as ArchitectureConfig, c as ArchitectureModal, L as LANG_STORAGE_KEY, S as STANDARD_ROUTES, d as ShellConfig, e as ShellRoute, T as THEME_BOOT_SCRIPT, f as THEME_STORAGE_KEY, v as validateArchitectureConfig } from './keys-CnvqkckF.js';
 import * as react from 'react';
-import { ReactNode } from 'react';
+import { ReactNode, Component, ErrorInfo } from 'react';
 import * as zustand from 'zustand';
-
-interface ArchTab {
-    id: string;
-    /** tab label. */
-    en: string;
-    es: string;
-    /** the explanation body (paragraphs separated by a blank line). */
-    body_en: string;
-    body_es: string;
-    /**
-     * an inline '<svg…>…</svg>' string OR a path under the app's public/ (fetched + inlined).
-     *
-     * ONE file carries BOTH languages (ADR-0058). Tag each translatable `<text>` twice at the same
-     * coordinates, `class="… l-en"` and `class="… l-es"`; the modal wrapper sets `data-arch-lang`
-     * and the shell stylesheet shows exactly one. Two files would be two things to keep in step, and
-     * the one that is not on screen is the one that goes stale. Anything language-neutral (a number,
-     * a file name, an identifier) needs no pair.
-     */
-    svg: string;
-}
-interface ArchitectureConfig {
-    /** modal title override (defaults to "Architecture / How it works"). */
-    title_en?: string;
-    title_es?: string;
-    tabs: ArchTab[];
-}
-declare function ArchitectureModal({ config, onClose }: {
-    config: ArchitectureConfig;
-    onClose: () => void;
-}): react.JSX.Element | null;
-
-interface ShellRoute {
-    path: string;
-    en: string;
-    es: string;
-}
-interface ShellConfig {
-    /** Brand: product name + optional lucide icon element (defaults to a generic mark). */
-    product: {
-        name: string;
-        mark?: ReactNode;
-    };
-    /** Top-level routes for the header nav. 0–1 entries → nav hidden (e.g. the Faena hub). */
-    routes?: ShellRoute[];
-    /** External links. personal/portfolio default to Felipe's canonical URLs (kept identical app-to-app). */
-    links: {
-        github: string;
-        personal?: string;
-        portfolio?: string;
-    };
-    /** Human version string (X.XX.XXX) shown in the footer. */
-    version: string;
-    /** In-app Architecture / "How it works" modal (ADR-0058). When present, an ⓘ button appears in the header. */
-    architecture?: ArchitectureConfig;
-    /** Footer provenance + honesty (ADR-0016 §2): the real data/engine source with citation +
-     * license (e.g. "Engine: lingbot-map (arXiv:2604.14141, Apache-2.0)") and the one-line honest
-     * disclaimer of how the app runs. Both optional, both bilingual. */
-    footer?: {
-        /** Explicit product attribution, or false when the product excludes personal attribution. */
-        attribution?: {
-            en: string;
-            es: string;
-        } | false;
-        /** The consuming product's license; the shell's MIT license is not inherited by applications. */
-        license?: {
-            en: string;
-            es: string;
-        };
-        provenance?: {
-            en: string;
-            es: string;
-        };
-        disclaimer?: {
-            en: string;
-            es: string;
-        };
-    };
-    /**
-     * Routes whose surface IS the viewport (ADR-0071 rule 1): on these the shell adds
-     * `.app-shell.fixed`, which sizes the page to 100dvh and lets flex distribute the
-     * height, so the ONE container that owns long content scrolls and the document
-     * never does. A doc route is not listed and keeps the document scroll. Matching is
-     * exact, or by prefix for a non-root path (`/lab` matches `/lab/case-1`).
-     *
-     * The stylesheet has carried `.app-shell.fixed` with the note "apps that fill the
-     * viewport add it" since the containment fix, and no app could: this component
-     * rendered a fixed class string. Measured on Porvenir before this field existed:
-     * every tab of the App route scrolled the document by 200 to 770px.
-     */
-    fixedRoutes?: string[];
-    /** Every route fixed: a single-surface app (a hub, a one-page tool). */
-    fixed?: boolean;
-}
-/** The shared CAOS/Faena app shell: sticky header (brand + nav + icon-links + lang/theme) + footer.
- * Wrap your <Routes> (or single landing) in it, inside a Router. */
-declare function AppShell({ config, children }: {
-    config: ShellConfig;
-    children: ReactNode;
-}): react.JSX.Element;
+import { F as FormatOptions } from './tokens-BCqyHYx2.js';
+export { N as NOT_AVAILABLE, a as SHELL_TOKENS, S as ShellToken, f as formatNumber, r as resolveToken, u as useFormat, b as useThemeTokens } from './tokens-BCqyHYx2.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';
 
 /** One authenticated workbench destination rendered by the shared responsive navigation frame. */
 interface WorkbenchRoute {
@@ -131,6 +37,22 @@ interface WorkbenchShellProps {
 /** Shared CAOS frame for authenticated consoles with desktop sidebar and mobile bottom navigation. */
 declare function WorkbenchShell({ brand, routes, navigationLabel, children, sidebarFooter, headerLead, headerActions, overlays, mainId, className, }: WorkbenchShellProps): react.JSX.Element;
 
+interface FocusShellProps {
+    stage: ReactNode;
+    rail: ReactNode;
+    title: string;
+    description: string;
+    hud: Array<{
+        label: string;
+        value: string;
+    }>;
+    onExit: () => void;
+    exitLabel: string;
+    stageLabel: string;
+}
+/** Full-viewport, scenario-scoped analysis frame. The product supplies only its instrument and controls. */
+declare function FocusShell({ stage, rail, title, description, hud, onExit, exitLabel, stageLabel }: FocusShellProps): react.JSX.Element;
+
 /** Light/dark icon toggle. Shows the icon of the theme you would switch TO. */
 declare function ThemeToggle(): react.JSX.Element;
 
@@ -147,15 +69,25 @@ interface ThemeState {
 }
 declare const useThemeStore: zustand.UseBoundStore<zustand.StoreApi<ThemeState>>;
 
-type Lang = 'en' | 'es';
-interface LangState {
-    lang: Lang;
-    setLang: (l: Lang) => void;
-    toggle: () => void;
+interface Props {
+    /** Which view this boundary protects; logged and shown so the failure is located, not guessed. */
+    panel: string;
+    children: ReactNode;
+}
+interface State {
+    error: Error | null;
+}
+/**
+ * An error boundary around one view. A failing chart or panel shows an inline message in its own frame instead of
+ * blanking the whole page, and the failure is logged with its panel id, which the measured gate fails on (failure
+ * class 20 of the 2026-10-04 history: white screens and silent failures).
+ */
+declare class PanelBoundary extends Component<Props, State> {
+    state: State;
+    static getDerivedStateFromError(error: Error): State;
+    componentDidCatch(error: Error, info: ErrorInfo): void;
+    render(): ReactNode;
 }
-declare const useLangStore: zustand.UseBoundStore<zustand.StoreApi<LangState>>;
-/** Current language, for app pages that render language-branched long-form content. */
-declare const useShellLang: () => Lang;
 
 /** Return `false` from a frame to end the current pass (the animation is complete); return `true`
  *  or nothing to keep going. `dt` = ms since the previous frame, `elapsed` = ms since this pass
@@ -167,13 +99,13 @@ interface VizLoopOptions {
     /** Auto-complete the pass once `elapsed` reaches this many ms (a hard cap so a frame that never
      *  returns false still stops). The final frame is drawn clamped to exactly this value. */
     durationMs?: number;
-    /** Fired once each time the loop stops on its own (a completed pass with loop=false) — not on a
+    /** Fired once each time the loop stops on its own (a completed pass with loop=false), not on a
      *  manual pause and not on a visibility halt. */
     onComplete?: () => void;
     /** Notified whenever the running state changes, so a React wrapper can mirror it into state. */
     onPlayingChange?: (playing: boolean) => void;
 }
-/** Injected side effects — real ones in the hook, fakes in tests. The frame timestamp comes from
+/** Injected side effects, real ones in the hook, fakes in tests. The frame timestamp comes from
  *  the rAF callback argument, so no separate clock is needed. */
 interface VizLoopDeps {
     raf: (cb: (now: number) => void) => number;
@@ -206,7 +138,7 @@ interface PausedVizController {
     restart: () => void;
 }
 interface UsePausedVizOptions extends VizLoopOptions {
-    /** Begin playing on mount. Default false — the mandatory no-autoplay default: a page must never
+    /** Begin playing on mount. Default false, the mandatory no-autoplay default: a page must never
      *  burn CPU unattended. Opt in only for a view the user explicitly expects to move on arrival. */
     autoStart?: boolean;
 }
@@ -224,7 +156,7 @@ declare function usePausedViz(frame: VizFrame, options?: UsePausedVizOptions): P
 
 type CaseKind = 'synthetic' | 'real' | 'uploaded';
 interface CaseDef {
-    /** stable slug — the value used in the ?case= deep link and reported to onSelect. */
+    /** stable slug, the value used in the ?case= deep link and reported to onSelect. */
     id: string;
     /** short human name shown ON the chip next to the id (never demoted to a tooltip-only string). */
     name: string;
@@ -232,9 +164,9 @@ interface CaseDef {
     category?: string;
     /** which source lane this case belongs to. Defaults to 'synthetic'. */
     kind?: CaseKind;
-    /** validation anchor (e.g. "published optimum 26,086,899") — surfaced in the chip tooltip. */
+    /** validation anchor (e.g. "published optimum 26,086,899"), surfaced in the chip tooltip. */
     anchor?: string;
-    /** expected-range hint — surfaced in the chip tooltip. */
+    /** expected-range hint, surfaced in the chip tooltip. */
     expectedBand?: string;
     disabled?: boolean;
 }
@@ -272,7 +204,7 @@ interface CaseSelectorProps {
     selectedId: string;
     onSelect: (id: string) => void;
     /** When provided, renders the first-level source control and filters cases to the active lane.
-     *  Controlled — pair with onSourceChange. Omit for a single-lane deck (no source control). */
+     *  Controlled, pair with onSourceChange. Omit for a single-lane deck (no source control). */
     source?: CaseKind;
     onSourceChange?: (k: CaseKind) => void;
     /** Overrides the default locked-knobs explanation shown for a non-synthetic source. */
@@ -301,7 +233,7 @@ interface CaseSelectorProps {
     layout?: 'chips' | 'select';
 }
 /**
- * CaseSelector v2 — the shared source + case picker. Renders (1) an optional first-level source
+ * CaseSelector v2, the shared source + case picker. Renders (1) an optional first-level source
  * segmented control (Synthetic | Real | Uploaded, only the lanes present), (2) a labelled group per
  * case category, each case a chip showing "ID · name" with its validation anchor as the tooltip and
  * a source tag, (3) a locked-knobs explanation when a non-synthetic source is active, and (4) a
@@ -317,25 +249,72 @@ interface TabDef {
     label: ReactNode;
     content: ReactNode;
 }
-/** Accessible roving-tabindex tab strip (arrow-key nav, aria wiring). Accent-soft pill for active. */
-declare function Tabs({ tabs, initial, ariaLabel }: {
+/** At most about six peers, then group by the question (ADR-0071 rule 5). */
+declare const MAX_PEER_TABS = 6;
+interface TabsProps {
     tabs: TabDef[];
+    /** Uncontrolled: the first selected tab. */
     initial?: string;
+    /** Controlled: the selected tab, owned by the app (for example a view held in the URL). */
+    value?: string;
+    /** Called on every selection, controlled or not. */
+    onChange?: (id: string) => void;
     ariaLabel?: string;
-}): react.JSX.Element;
+}
+/**
+ * Accessible roving-tabindex tab strip on ONE row (ADR-0071 rule 4): arrow keys, Home and End; only the active panel
+ * is rendered, inside an error boundary; a row wider than its box fades the hidden end. Controlled when `value` is
+ * given (known shell defect 6). More than six peers is reported (rule 5).
+ */
+declare function Tabs({ tabs, initial, value, onChange, ariaLabel }: TabsProps): react.JSX.Element;
 
 interface SubTabDef {
     id: string;
     label: ReactNode;
     content: ReactNode;
 }
-/** Second-level tabs nested inside a Tabs panel. Lighter chips; optional vertical left rail. */
-declare function SubTabs({ tabs, initial, ariaLabel, orientation, }: {
+interface SubTabsProps {
     tabs: SubTabDef[];
     initial?: string;
+    /** Controlled selection (known shell defect 6). */
+    value?: string;
+    onChange?: (id: string) => void;
     ariaLabel?: string;
     orientation?: 'horizontal' | 'vertical';
-}): react.JSX.Element;
+}
+/**
+ * Second-level tabs nested inside a Tabs panel: lighter chips, or a vertical left rail for deep content. Only the
+ * active panel is rendered, inside an error boundary; controlled when `value` is given; more than six peers is
+ * reported (ADR-0071 rule 5).
+ */
+declare function SubTabs({ tabs, initial, value, onChange, ariaLabel, orientation }: SubTabsProps): react.JSX.Element;
+
+interface TabGroupDef {
+    id: string;
+    /** The question the group answers (ADR-0071 rule 5: group by the user's question). */
+    label: ReactNode;
+    tabs: SubTabDef[];
+}
+interface TabGroupsProps {
+    groups: TabGroupDef[];
+    /** Controlled selection as `group` and `tab` ids (for example held in the URL). */
+    value?: {
+        group: string;
+        tab?: string;
+    };
+    onChange?: (value: {
+        group: string;
+        tab: string;
+    }) => void;
+    ariaLabel?: string;
+}
+/**
+ * Grouped navigation for more than six views: one row of at most six groups, then the sub-tabs of the open group
+ * only, each its own single row (ADR-0071 rules 4 and 5). No hover menus: every view is reached by plain clicks on
+ * visible tabs, which a pointer and a keyboard can both operate (rule 9; menus that swallowed the first click were a
+ * recorded failure).
+ */
+declare function TabGroups({ groups, value, onChange, ariaLabel }: TabGroupsProps): react.JSX.Element;
 
 /** A left-bordered note box. `honest` = amber (caveats/limits), `strong` = accent, `note` = neutral. */
 declare function Callout({ variant, title, children, }: {
@@ -344,7 +323,8 @@ declare function Callout({ variant, title, children, }: {
     children: ReactNode;
 }): react.JSX.Element;
 
-/** A display equation rendered with KaTeX, with an optional caption. */
+/** A display equation rendered with KaTeX and its caption. ADR-0017 s2 requires every display equation to carry a
+ * bilingual caption that defines its symbols; a missing one is reported on the console, which the gate fails on. */
 declare function Equation({ tex, caption }: {
     tex: string;
     caption?: ReactNode;
@@ -363,8 +343,9 @@ declare function Figure({ caption, children }: {
 
 interface Citation {
     id: string;
-    /** Short inline label, e.g. "Little 1961". */
-    label: string;
+    /** Short inline label, e.g. "Little 1961"; `{ en, es }` when it has words to translate ("Laplante and
+     * Staunton" / "Laplante y Staunton"), known shell defect 9. The bibliographic record stays verbatim. */
+    label: BiText;
     /** Full bibliographic string for the reference list. */
     citation: string;
     doi?: string;
@@ -385,10 +366,324 @@ declare function Refs({ ids, label }: {
     ids: string[];
     label: string;
 }): react.JSX.Element;
-/** Full ordered bibliography. Omit `ids` to render every provided citation. */
+/** Full ordered bibliography. Omit `ids` to render every provided citation.
+ * @deprecated ADR-0017 s4 bans a bottom-of-page bibliography; end each section with `Refs` (or use `DocSection`).
+ * Kept so existing products still compile; it reports itself on the console, which the gate fails on. */
 declare function ReferenceList({ ids, heading }: {
     ids?: string[];
     heading?: string;
 }): react.JSX.Element;
 
-export { AppShell, type ArchTab, type ArchitectureConfig, ArchitectureModal, Callout, type CaseDef, type CaseGroup, type CaseKind, CaseSelector, type CaseSelectorProps, type CaseSelectorText, type Citation, CitationsProvider, Cite, Equation, Figure, InlineMath, type Lang, LanguageToggle, type PausedVizController, ReferenceList, Refs, type ShellConfig, type ShellRoute, type SubTabDef, SubTabs, type TabDef, Tabs, type Theme, ThemeToggle, type UsePausedVizOptions, type VizFrame, type VizLoop, type VizLoopDeps, type VizLoopOptions, type WorkbenchRoute, WorkbenchShell, type WorkbenchShellProps, applyTheme, caseKind, caseTooltip, casesInSource, createVizLoop, groupByCategory, readCaseParam, readTheme, sourcesPresent, useLangStore, usePausedViz, useShellLang, useThemeStore, withCaseParam };
+/**
+ * A documentation route (Introduction, Methodology, Implementation, Experiments, Benchmark): the page head with
+ * its title and lede, then sections. `wide` for a route with a sub-tab rail (ADR-0071 rule 2, amended
+ * 2026-09-04); a single prose column keeps the reading width and is centred (ADR-0017 §1).
+ */
+declare function DocPage({ title, lede, wide, children }: {
+    title: BiText;
+    lede: ReactNode;
+    wide?: boolean;
+    children: ReactNode;
+}): react.JSX.Element;
+interface DocSectionProps {
+    title: BiText;
+    id?: string;
+    /** Citation ids for this section only, rendered as one inline `Refs` row at its end (ADR-0017 §4). */
+    refs?: string[];
+    /** Required when a section cites nothing, so the absence is a stated choice the gate can read. */
+    noRefsReason?: BiText;
+    children: ReactNode;
+}
+/** One section of a documentation route, ending in its own references. */
+declare function DocSection({ title, id, refs, noRefsReason, children }: DocSectionProps): react.JSX.Element;
+
+/** One section of the control rail. A rail whose content does not fit is SPLIT into sections, one shown at a
+ * time, never scrolled (ADR-0071 rule 6: a panel must show its own controls). */
+interface RailSection {
+    id: string;
+    label: BiText;
+    content: ReactNode;
+}
+interface WorkbenchLayoutProps {
+    /** The control rail: case and variant pickers, parameters, the live readout. Either one node or sections. */
+    rail: ReactNode | RailSection[];
+    /** Shown above the rail (and above its sections): the case and variant pickers, which every section shares. */
+    railHead?: ReactNode;
+    /** The instrument: the views of the selected case. It takes the rest of the viewport (ADR-0071 rules 2, 8). */
+    children: ReactNode;
+    /** Accessible name of the rail. */
+    railLabel?: BiText;
+    className?: string;
+}
+/**
+ * The App route of a CAOS product: a sized control rail beside the instrument, on the full viewport.
+ *
+ * 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`.
+ */
+declare function WorkbenchLayout({ rail, railHead, children, railLabel, className }: WorkbenchLayoutProps): react.JSX.Element;
+
+/** Where a value on screen came from: observed data, a generator, or a published reference. */
+type Provenance = 'real' | 'synthetic' | 'published';
+/** The selection the instrument shows, and the key that identifies it (S10 of the 2026-10-04 requirements). */
+interface WorkbenchState {
+    stateKey: string;
+    caseId?: string;
+    variantId?: string;
+    source?: string;
+}
+declare const WorkbenchStateContext: react.Context<WorkbenchState | null>;
+/** The current workbench selection, or null outside a `CaseWorkbench`. */
+declare function useWorkbenchState(): WorkbenchState | null;
+/**
+ * A short, deterministic key for a selection: case, variant, source and every control value. A view that shows data
+ * computed for another key is stale, and says so (failure classes 8 and 17: views that silently kept an old result
+ * after a control changed). FNV-1a over a canonical serialisation.
+ */
+declare function makeStateKey(parts: Record<string, unknown>): string;
+/** True when a view's data key is known and differs from the workbench's current key. */
+declare function isStale(dataKey: string | undefined, current: WorkbenchState | null): boolean;
+
+/** Where a value on screen was computed (ADR-0057 lanes, ADR-0069 s5). */
+type Lane = 'live' | 'replay' | 'offline';
+/** Badges that state honestly which lane produced what is shown (recomputed live, replayed from a committed
+ * artifact, or available only offline) and, when given, whether it rests on real, synthetic or published data
+ * (failure class 17 of the 2026-10-04 history: live versus replay honesty). */
+declare function LaneBadge({ lane, provenance, label }: {
+    lane: Lane;
+    provenance?: Provenance;
+    label?: BiText;
+}): react.JSX.Element;
+
+/** One configured regime of a case: a full parameter vector, never a cosmetic label (ADR-0016 §9). */
+interface VariantDef {
+    id: string;
+    label: BiText;
+    /** One line: what this regime shows. */
+    note?: BiText;
+    /** The lane of this variant's result, when it differs from the bar's. */
+    lane?: Lane;
+    disabled?: boolean;
+}
+interface VariantBarProps {
+    variants: VariantDef[];
+    activeId: string;
+    onSelect: (id: string) => void;
+    title?: BiText;
+    lane?: Lane;
+}
+/** The regimes of the selected case on ONE scrollable row (ADR-0071 rule 4), the active regime's lane, and the
+ * one-line note of what it shows. Selecting a regime must change every view of the case. */
+declare function VariantBar({ variants, activeId, onSelect, title, lane }: VariantBarProps): react.JSX.Element;
+
+/** One group of views of the selected case, named for the question the user is asking (ADR-0071 rule 5). */
+interface WorkbenchGroup {
+    id: string;
+    label: BiText;
+    /** Which lane produced this group's views, and what data they rest on. Each view shows its own badges (PlotCard,
+     * Readout); these are written on the panel as `data-lane` and `data-provenance`. */
+    lane?: Lane;
+    provenance?: Provenance;
+    content: ReactNode;
+}
+interface CaseWorkbenchProps {
+    /** The selected case (written as `data-case`). */
+    caseId: string;
+    /** The case picker, shown first in the rail. Omit only for a workbench with a single case. */
+    cases?: CaseSelectorProps;
+    /** The data source of the case (for example `real` or `synthetic`), written as `data-source`. */
+    source?: string;
+    /** Every control value of the instrument; with the case and variant it forms the state key (S10). */
+    controls?: Record<string, unknown>;
+    /** A workbench whose views have no live control declares it, so the reactivity gate does not expect one. */
+    replayOnly?: boolean;
+    /** The regimes of the case, shown in the rail under the case picker; omit only for a case with no meaningful
+     * parametric or temporal family. */
+    variants?: VariantBarProps;
+    /** The rest of the rail: the case's parameters (Knob, ChipGroup) and its live values (Readout, Gauge, Verdict),
+     * as one node or as sections shown one at a time (ADR-0071 rule 6). */
+    rail?: ReactNode | RailSection[];
+    railLabel?: BiText;
+    /** The instrument: the case's own question groups (for example Model, Validation, Impact, Findings). */
+    groups: WorkbenchGroup[];
+    /** The comparison across the case's variants (one metric per regime; selecting one loads it). */
+    compare?: {
+        label?: BiText;
+        lane?: Lane;
+        provenance?: Provenance;
+        content: ReactNode;
+    };
+    /** The deep write-up of the case: problem, variables, equations, assumptions, what each variant shows, how to read
+     * the views (ADR-0016 s9.B). Always present. */
+    context: {
+        label?: BiText;
+        content: ReactNode;
+    };
+    /** Controlled group selection (for example held in the URL). */
+    group?: string;
+    onGroupChange?: (id: string) => void;
+    ariaLabel?: BiText;
+}
+declare const MAX_WORKBENCH_GROUPS = 6;
+/**
+ * The App route of a product (ADR-0016 s9, ADR-0071 as amended 2026-10-04): the control rail beside the instrument on
+ * the full viewport. The rail holds, in order, the case picker, the variants of the case, and the product's
+ * 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).
+ *
+ * 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
+ * `data-state-key` on the instrument so the gate can check that the instrument shows what was asked for.
+ */
+declare function CaseWorkbench(props: CaseWorkbenchProps): react.JSX.Element;
+
+type Tone = 'good' | 'warn' | 'bad' | 'accent' | 'neutral';
+interface ReadoutItem {
+    label: BiText;
+    /** A number, or `null`/`undefined` when it is not available. NaN is reported and shown as not available. */
+    value?: number | null;
+    /** A categorical value shown as text instead of a number. */
+    text?: BiText;
+    /** The unit, bilingual when it is a word (people / personas), a plain string when it is a symbol (d, %). Required
+     * unless `unitless` is set (failure class 23: readouts without units). */
+    unit?: BiText;
+    unitless?: boolean;
+    /** What the quantity is, in one line (ADR-0017 s3.8: every variable is self-explanatory). */
+    hint?: BiText;
+    /** An explicit tone, or a tone derived from `better` and the `good`/`bad` thresholds, never from the sign. */
+    tone?: Tone;
+    better?: 'higher' | 'lower';
+    good?: number;
+    bad?: number;
+    format?: FormatOptions;
+}
+interface ReadoutProps {
+    items: ReadoutItem[];
+    title?: BiText;
+    /** Which lane computed these values, and what data they rest on (required, failure class 17). */
+    lane: Lane;
+    provenance: Provenance;
+    /** The workbench state key these values were computed for; differing from the current key shows them as stale. */
+    dataKey?: string;
+}
+/** The live readout: labelled values with units that update with every control (ADR-0017 s3.3). */
+declare function Readout({ items, title, lane, provenance, dataKey }: ReadoutProps): react.JSX.Element;
+interface GaugeZone {
+    from: number;
+    to: number;
+    tone: Tone;
+    label: BiText;
+}
+interface GaugeProps {
+    title: BiText;
+    value: number | null | undefined;
+    min: number;
+    max: number;
+    zones: GaugeZone[];
+    unit?: BiText;
+    unitless?: boolean;
+    format?: FormatOptions;
+}
+/** A value against labelled zones on a linear scale, the needle at the value (ADR-0017 s3.3). */
+declare function Gauge({ title, value, min, max, zones, unit, unitless, format }: GaugeProps): react.JSX.Element;
+type VerdictProps = {
+    title: BiText;
+    /** Title and verdict on one row, for a verdict that sits above a drawing and must not take its height. */
+    compact?: boolean;
+    children?: ReactNode;
+} & ({
+    code: string;
+    messages: Record<string, {
+        tone: Tone;
+        text: BiText;
+    }>;
+} | {
+    tone: Tone;
+    verdict: BiText;
+});
+/** The verdict panel: the current diagnosis in one line, coloured by its tone. A status code goes through a
+ * `messages` map, and an unmapped code is reported (failure class 23: raw status codes on screen). */
+declare function Verdict(props: VerdictProps): react.JSX.Element;
+interface PlotCardProps {
+    title: BiText;
+    /** Which lane produced this view and what data it rests on (required, failure class 17). */
+    lane: Lane;
+    provenance: Provenance;
+    /** The workbench state key the data was computed for; a different key shows the view as stale. */
+    dataKey?: string;
+    actions?: ReactNode;
+    note?: BiText;
+    /** The view takes the height its panel leaves (a chart or stage that should fill the instrument, ADR-0071 rule 8);
+     * views marked `fill` in one panel share that height. A `Stage` or `UPlotChart height="fill"` inside it gets a
+     * real size from it instead of a guessed one (failure class 4). */
+    fill?: boolean;
+    children: ReactNode;
+}
+/** A framed view with a title row, its lane and provenance, the unit every chart or table sits in. Its body is
+ * protected by an error boundary, so one failing chart never blanks the page (failure class 20). */
+declare function PlotCard({ title, lane, provenance, dataKey, actions, note, fill, children }: PlotCardProps): react.JSX.Element;
+
+interface KnobProps {
+    /** Stable id, written as `data-control` so the gate can enumerate and move every control. */
+    id: string;
+    label: BiText;
+    value: number;
+    min: number;
+    max: number;
+    step: number;
+    unit?: BiText;
+    /** What the parameter is (ADR-0017 s3.8). */
+    hint?: BiText;
+    format?: FormatOptions;
+    disabled?: boolean;
+    onChange: (value: number) => void;
+}
+/**
+ * A continuous parameter of the case (ADR-0017 s3.2): a labelled slider with its value and unit shown. Registered as
+ * a control (`data-control`), so the gate can change it and require that some view's state key changes (failure
+ * class 8: controls that change nothing).
+ */
+declare function Knob({ id, label, value, min, max, step, unit, hint, format, disabled, onChange }: KnobProps): react.JSX.Element;
+interface ChipOption {
+    id: string;
+    label: BiText;
+    hint?: BiText;
+    disabled?: boolean;
+}
+interface ChipGroupProps {
+    id: string;
+    label: BiText;
+    options: ChipOption[];
+    value: string;
+    onChange: (id: string) => void;
+}
+/** A small one-of-N choice as chips on one row, registered as a control. For a categorised or long list use the
+ * `CaseSelector` select mode instead (ADR-0071 rule 7). */
+declare function ChipGroup({ id, label, options, value, onChange }: ChipGroupProps): react.JSX.Element;
+
+interface StageSize {
+    width: number;
+    height: number;
+}
+/**
+ * The size of an element, observed through a callback ref and a ResizeObserver, so a canvas is sized from its real
+ * box and never from viewport units, and is not built before it has a size (failure class 4: instruments drawn at
+ * zero or at a guessed size).
+ */
+declare function useStageSize(): [(el: HTMLElement | null) => void, StageSize];
+/**
+ * The drawing surface of an instrument. It renders its children only once it has a non-zero size, passes that size
+ * down, and declares what it drew (`data-drawn`, `data-width`, `data-height`) so the gate measures the drawing, not
+ * the host. A stage that never gets a size is reported.
+ */
+declare function Stage({ label, children, className }: {
+    label: BiText;
+    children: (size: StageSize) => ReactNode;
+    className?: string;
+}): react.JSX.Element;
+
+export { BiText, Callout, type CaseDef, type CaseGroup, type CaseKind, CaseSelector, type CaseSelectorProps, type CaseSelectorText, CaseWorkbench, type CaseWorkbenchProps, ChipGroup, type ChipGroupProps, type ChipOption, type Citation, CitationsProvider, Cite, DocPage, DocSection, type DocSectionProps, Equation, Figure, FocusShell, type FocusShellProps, FormatOptions, Gauge, type GaugeProps, type GaugeZone, InlineMath, Knob, type KnobProps, type Lane, LaneBadge, Lang, LanguageToggle, MAX_PEER_TABS, MAX_WORKBENCH_GROUPS, PanelBoundary, type PausedVizController, PlotCard, type PlotCardProps, type Provenance, type RailSection, Readout, type ReadoutItem, type ReadoutProps, ReferenceList, Refs, Stage, type StageSize, type SubTabDef, SubTabs, type SubTabsProps, 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 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, groupByCategory, isStale, makeStateKey, readCaseParam, readTheme, sourcesPresent, usePausedViz, useStageSize, useThemeStore, useWorkbenchState, withCaseParam };