@fasl-work/caos-app-shell 0.6.7 → 0.6.13

package/README.md

@@ -57,7 +57,7 @@ const config: ShellConfig = {
   (labelled groups, `Synthetic | Real | Uploaded` source control, locked-knobs explanation, divergence
   badge, `?case=` deep-linking).
 - **Animated views:** drive every canvas/3D loop through `usePausedViz` (default paused, run-once,
-  halt on a hidden tab) — never call `requestAnimationFrame` directly.
+  halt on a hidden tab), never call `requestAnimationFrame` directly.
 
 ## Exports
 

package/dist/index.d.ts

@@ -131,6 +131,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;
 
@@ -167,13 +183,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 +222,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 +240,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 +248,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 +288,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 +317,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
@@ -391,4 +407,4 @@ declare function ReferenceList({ ids, heading }: {
     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 };
+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, FocusShell, type FocusShellProps, 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 };

package/dist/index.js

@@ -324,6 +324,7 @@ function AppShell({ config, children }) {
         {
           to: r.path,
           end: r.path === "/",
+          onFocus: (event) => event.currentTarget.scrollIntoView({ block: "nearest", inline: "nearest" }),
           className: ({ isActive }) => isActive ? "nav-link active" : "nav-link",
           children: lang === "es" ? r.es : r.en
         },
@@ -359,7 +360,7 @@ function AppShell({ config, children }) {
         /* @__PURE__ */ jsx("span", { children: config.footer.provenance[lang] })
       ] }),
       /* @__PURE__ */ jsx("span", { "aria-hidden": "true", children: "\xB7" }),
-      /* @__PURE__ */ jsx("a", { href: config.links.github, target: "_blank", rel: "noreferrer noopener", children: c.github }),
+      /* @__PURE__ */ jsx("a", { href: config.links.github, target: "_blank", rel: "noreferrer noopener", onFocus: (event) => event.currentTarget.scrollIntoView({ block: "nearest", inline: "nearest" }), children: c.github }),
       /* @__PURE__ */ jsx("span", { "aria-hidden": "true", children: "\xB7" }),
       /* @__PURE__ */ jsx("span", { className: "faint", children: config.footer?.license?.[lang] ?? c.license }),
       config.footer?.disclaimer && /* @__PURE__ */ jsxs(Fragment, { children: [
@@ -418,6 +419,27 @@ function WorkbenchShell({
     overlays
   ] });
 }
+function FocusShell({ stage, rail, title, description, hud, onExit, exitLabel, stageLabel }) {
+  return /* @__PURE__ */ jsxs("main", { className: "caos-focus-shell", children: [
+    /* @__PURE__ */ jsxs("section", { className: "caos-focus-stage", "aria-label": stageLabel, children: [
+      /* @__PURE__ */ jsx("div", { className: "caos-focus-instrument", children: stage }),
+      /* @__PURE__ */ jsxs("div", { className: "caos-focus-label", children: [
+        /* @__PURE__ */ jsx("strong", { children: title }),
+        /* @__PURE__ */ jsx("span", { children: description })
+      ] }),
+      /* @__PURE__ */ jsx("div", { className: "caos-focus-hud", "aria-label": "HUD", children: hud.map((item) => /* @__PURE__ */ jsxs("div", { children: [
+        /* @__PURE__ */ jsx("strong", { children: item.value }),
+        /* @__PURE__ */ jsx("span", { children: item.label })
+      ] }, item.label)) }),
+      /* @__PURE__ */ jsxs("div", { className: "caos-focus-actions", children: [
+        /* @__PURE__ */ jsx(LanguageToggle, {}),
+        /* @__PURE__ */ jsx(ThemeToggle, {}),
+        /* @__PURE__ */ jsx("button", { type: "button", onClick: onExit, children: exitLabel })
+      ] })
+    ] }),
+    /* @__PURE__ */ jsx("aside", { className: "caos-focus-rail", children: rail })
+  ] });
+}
 
 // src/lib/vizLoop.ts
 function createVizLoop(frame, options, deps) {
@@ -600,7 +622,7 @@ var TEXT = {
     synthetic: "Synthetic",
     real: "Real",
     uploaded: "Uploaded",
-    lockedNote: "Scenario knobs are locked on a real sample \u2014 you pick which datum; every tool runs on it as-is.",
+    lockedNote: "Scenario knobs are locked on a real sample: you pick which datum; every tool runs on it as-is.",
     modifiedPrefix: "modified from",
     reset: "reset"
   },
@@ -909,4 +931,4 @@ function ReferenceList({ ids, heading }) {
   ] });
 }
 
-export { AppShell, ArchitectureModal, Callout, CaseSelector, CitationsProvider, Cite, Equation, Figure, InlineMath, LanguageToggle, ReferenceList, Refs, SubTabs, Tabs, ThemeToggle, WorkbenchShell, applyTheme, caseKind, caseTooltip, casesInSource, createVizLoop, groupByCategory, readCaseParam, readTheme, sourcesPresent, useLangStore, usePausedViz, useShellLang, useThemeStore, withCaseParam };
+export { AppShell, ArchitectureModal, Callout, CaseSelector, CitationsProvider, Cite, Equation, Figure, FocusShell, InlineMath, LanguageToggle, ReferenceList, Refs, SubTabs, Tabs, ThemeToggle, WorkbenchShell, applyTheme, caseKind, caseTooltip, casesInSource, createVizLoop, groupByCategory, readCaseParam, readTheme, sourcesPresent, useLangStore, usePausedViz, useShellLang, useThemeStore, withCaseParam };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fasl-work/caos-app-shell",
-  "version": "0.6.7",
+  "version": "0.6.13",
   "description": "Shared web-app shell + content primitives + design system for the CAOS / Faena public apps (ADR-0016).",
   "license": "MIT",
   "author": "Felipe Santibáñez-Leal",
@@ -30,6 +30,7 @@
     "build": "tsup",
     "test": "node --import tsx --test \"test/**/*.test.ts\" \"test/**/*.test.tsx\"",
     "test:browser": "node --import tsx --test \"e2e/**/*.test.ts\"",
+    "prepare": "npm run build",
     "prepublishOnly": "npm run build"
   },
   "peerDependencies": {

package/styles.css

@@ -1,6 +1,6 @@
 @import "katex/dist/katex.min.css";
 
-/* @fasl-work/caos-app-shell — shared design system (ADR-0016 + visual-standards palette).
+/* @fasl-work/caos-app-shell, shared design system (ADR-0016 + visual-standards palette).
  * Theming via CSS custom properties keyed on data-theme on <html> (set pre-paint by an inline
  * script in index.html, kept in sync by the shell theme store). Import once per app:
  *   import "@fasl-work/caos-app-shell/styles.css"; */
@@ -110,7 +110,22 @@ code, kbd { font-family: var(--font-mono); }
 /* ── Misc ── */
 .sr-only { position: absolute; width: 1px; height: 1px; padding: 0; margin: -1px; overflow: hidden; clip: rect(0,0,0,0); white-space: nowrap; border: 0; }
 :where(a[href], button:not([disabled]), [tabindex]:not([tabindex="-1"])):focus-visible { outline: 2px solid var(--color-accent); outline-offset: 2px; border-radius: 4px; }
-@media (max-width: 760px) { .main-nav { display: none; } }
+@media (max-width: 760px) {
+  /* ADR-0071: route navigation shares the header row; it owns the horizontal
+     scroll instead of adding a permanent second row above every instrument. */
+  .header-inner { height: 52px; min-height: 0; flex-wrap: nowrap; gap: 0.3rem; padding-inline: 0.55rem; }
+  .brand, .header-actions { flex: none; white-space: nowrap; }
+  .brand { gap: 0.25rem; font-size: 0.8rem; }
+  .header-actions { margin-left: 0; gap: 0; }
+  .header-actions .icon-btn { padding: 0.25rem; }
+  .header-sep { margin-inline: 0.15rem; }
+  .main-nav { flex: 1 1 0; min-width: 0; overflow-x: auto; overflow-y: hidden; white-space: nowrap; padding: 2px 0; scrollbar-width: none; }
+  .main-nav::-webkit-scrollbar { display: none; }
+  .main-nav .nav-link { flex: none; padding: 0.3rem 0.3rem; font-size: 0.7rem; }
+}
+@media (max-width: 380px) {
+  .brand span:last-child { display: none; }
+}
 @media (prefers-reduced-motion: reduce) { *, *::before, *::after { animation-duration: 0.01ms !important; transition-duration: 0.01ms !important; } }
 
 /* ── Prose / content pages ── (fill the page-body width with grids/figures/sub-tab rails, not a narrow column) */
@@ -319,6 +334,14 @@ html, body { overflow-x: hidden; }
    text stays (ADR-0016 s2: provenance and the honest disclaimer are the footer's job); it is set
    compact, so it takes two to three lines, not five. */
 .app-shell.fixed .site-footer .footer-inner { padding: 0.45rem 1.5rem; gap: 0.4rem; font-size: 0.74rem; line-height: 1.3; }
+@media (max-width: 760px) {
+  /* A long, correctly attributed provenance must not consume the instrument.
+     Footer metadata remains accessible by horizontal scroll and keyboard focus. */
+  .app-shell.fixed .site-footer .footer-inner { padding: 0.35rem 0.55rem; }
+  .app-shell.fixed .footer-meta { flex-wrap: nowrap; overflow-x: auto; white-space: nowrap; scrollbar-width: none; }
+  .app-shell.fixed .footer-meta::-webkit-scrollbar { display: none; }
+  .app-shell.fixed .footer-meta > * { flex: none; }
+}
 
 /* ADR-0058 diagram i18n. A hand-authored architecture SVG carries BOTH languages inside ONE file,
    and the modal wrapper picks one. Two files would be two things to keep in step, and the one not
@@ -332,3 +355,29 @@ html, body { overflow-x: hidden; }
 /* The compact one-of-N case picker (ADR-0071 rule 7). Ten cases in four categories
    cost a 308px chip block, 21% of a 2560x1440 viewport, and one row as a dropdown. */
 .cs-select { width: 100%; max-width: 460px; }
+
+/* ADR-0070: additive, shell-owned, full-viewport scenario focus frame. */
+.caos-focus-shell { position: fixed; inset: 0; z-index: 100; display: grid; grid-template-columns: minmax(0,1fr) clamp(300px,20vw,340px); min-width: 0; height: 100dvh; background: var(--color-bg); color: var(--color-fg); }
+.caos-focus-stage { position: relative; min-width: 0; min-height: 0; overflow: hidden; background: var(--color-bg); }
+.caos-focus-instrument { position: absolute; inset: 0; min-width: 0; min-height: 0; }
+.caos-focus-label, .caos-focus-hud > div { background: color-mix(in oklab,var(--color-surface) 82%,transparent); backdrop-filter: blur(6px); border: 1px solid var(--color-border); border-radius: 6px; }
+.caos-focus-label { position: absolute; top: 14px; left: 14px; max-width: min(46ch,calc(100% - 230px)); display: grid; gap: 4px; padding: 10px 12px; pointer-events: none; }
+.caos-focus-label strong { font-size: 0.96rem; line-height: 1.2; }
+.caos-focus-label span { font-size: 0.78rem; line-height: 1.4; color: var(--color-fg-subtle); }
+.caos-focus-hud { position: absolute; left: 14px; top: 104px; display: grid; gap: 6px; pointer-events: none; }
+.caos-focus-hud > div { display: grid; gap: 1px; padding: 7px 10px; min-width: 120px; }
+.caos-focus-hud strong { font: 700 1rem var(--font-mono,monospace); }
+.caos-focus-hud span { color: var(--color-fg-subtle); font-size: 0.61rem; font-weight: 700; text-transform: uppercase; letter-spacing: 0.07em; }
+.caos-focus-actions { position: absolute; top: 12px; right: 12px; display: flex; gap: 6px; align-items: center; padding: 4px; border: 1px solid var(--color-border); border-radius: 6px; background: color-mix(in oklab,var(--color-surface) 90%,transparent); backdrop-filter: blur(6px); }
+.caos-focus-actions button { border: 0; border-radius: 4px; padding: 6px 9px; background: var(--color-surface-2); color: var(--color-fg); font-size: 0.75rem; font-weight: 700; cursor: pointer; }
+.caos-focus-rail { min-width: 0; min-height: 0; overflow-y: auto; overscroll-behavior: contain; border-left: 1px solid var(--color-border); background: var(--color-surface); }
+@media (max-width: 860px) {
+  .caos-focus-shell { grid-template-columns: minmax(0,1fr); grid-template-rows: minmax(0,54dvh) minmax(0,46dvh); }
+  .caos-focus-rail { border-left: 0; border-top: 1px solid var(--color-border); }
+  .caos-focus-label { max-width: calc(100% - 16px); top: 49px; left: 8px; padding: 6px 8px; }
+  .caos-focus-hud { top: auto; bottom: 8px; left: 8px; right: 8px; display: grid; grid-template-columns: repeat(4,minmax(0,1fr)); gap: 4px; }
+  .caos-focus-hud > div { min-width: 0; padding: 5px; }
+  .caos-focus-hud strong { font-size: 0.72rem; white-space: nowrap; }
+  .caos-focus-hud span { font-size: 0.48rem; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .caos-focus-actions { top: 7px; right: 7px; }
+}