@fasl-work/caos-app-shell 0.1.0

package/README.md

@@ -0,0 +1,59 @@
+# @fasl-work/caos-app-shell
+
+The shared **web-app shell + content primitives + design system** for the CAOS / Faena public apps
+(implements [ADR-0016](https://github.com/fsantibanezleal)). Define the header, footer, theme, language
+toggle and content primitives **once** here; every app consumes them so the chrome is identical and a
+fix lands in one place.
+
+## Install
+
+```bash
+npm i @fasl-work/caos-app-shell
+# peer deps (the app provides them):
+npm i react react-dom react-router-dom lucide-react katex zustand
+```
+
+## Use
+
+```tsx
+// main.tsx
+import { applyTheme, readTheme } from "@fasl-work/caos-app-shell";
+import "@fasl-work/caos-app-shell/styles.css";
+applyTheme(readTheme()); // (an inline script in index.html should also set data-theme pre-paint)
+
+// router / app
+import { BrowserRouter, Routes, Route } from "react-router-dom";
+import { AppShell, type ShellConfig } from "@fasl-work/caos-app-shell";
+
+const config: ShellConfig = {
+  product: { name: "RotorVitals" },
+  routes: [
+    { path: "/", en: "App", es: "App" },
+    { path: "/introduction", en: "Introduction", es: "Introducción" },
+    { path: "/methodology", en: "Methodology", es: "Metodología" },
+    { path: "/implementation", en: "Implementation", es: "Implementación" },
+    { path: "/experiments", en: "Experiments", es: "Experimentos" },
+  ],
+  links: { github: "https://github.com/fsantibanezleal/CAOS_RotorVitals" }, // personal/portfolio default in
+  version: "0.01.000",
+};
+
+<BrowserRouter>
+  <AppShell config={config}>
+    <Routes>{/* /  = the tool (landing); the rest are deep pages */}</Routes>
+  </AppShell>
+</BrowserRouter>
+```
+
+- **Land on the tool:** make `/` your interactive tool; Introduction/Methodology/etc. are separate routes.
+- **Hub case (Faena):** pass `routes: []` (or one) → the nav is hidden, header/footer identical.
+- **Deep pages:** compose with `Tabs`, `SubTabs`, `Equation`/`InlineMath`, `Callout`, `Figure`, and
+  `CitationsProvider` + `Cite`/`Refs`/`ReferenceList`. Read the current language with `useShellLang()`.
+
+## Exports
+
+`AppShell`, `ThemeToggle`, `LanguageToggle`, `useThemeStore`, `applyTheme`, `readTheme`, `useLangStore`,
+`useShellLang`, `Tabs`, `SubTabs`, `Callout`, `Equation`, `InlineMath`, `Figure`, `CitationsProvider`,
+`Cite`, `Refs`, `ReferenceList`, plus the `@fasl-work/caos-app-shell/styles.css` design system.
+
+MIT · part of the Faena mining-analytics hub.

package/dist/index.d.ts

@@ -0,0 +1,139 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import * as zustand from 'zustand';
+
+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;
+}
+/** 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;
+
+/** Light/dark icon toggle. Shows the icon of the theme you would switch TO. */
+declare function ThemeToggle(): react.JSX.Element;
+
+/** Language toggle. Shows the current 2-letter code; pressing it swaps and persists. */
+declare function LanguageToggle(): react.JSX.Element;
+
+type Theme = 'light' | 'dark';
+declare function readTheme(): Theme;
+declare function applyTheme(t: Theme): void;
+interface ThemeState {
+    theme: Theme;
+    toggleTheme: () => void;
+    setTheme: (t: Theme) => void;
+}
+declare const useThemeStore: zustand.UseBoundStore<zustand.StoreApi<ThemeState>>;
+
+type Lang = 'en' | 'es';
+interface LangState {
+    lang: Lang;
+    setLang: (l: Lang) => void;
+    toggle: () => void;
+}
+declare const useLangStore: zustand.UseBoundStore<zustand.StoreApi<LangState>>;
+/** Current language, for app pages that render language-branched long-form content. */
+declare const useShellLang: () => Lang;
+
+interface TabDef {
+    id: string;
+    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 }: {
+    tabs: TabDef[];
+    initial?: string;
+    ariaLabel?: string;
+}): 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, }: {
+    tabs: SubTabDef[];
+    initial?: string;
+    ariaLabel?: string;
+    orientation?: 'horizontal' | 'vertical';
+}): react.JSX.Element;
+
+/** A left-bordered note box. `honest` = amber (caveats/limits), `strong` = accent, `note` = neutral. */
+declare function Callout({ variant, title, children, }: {
+    variant?: 'note' | 'honest' | 'strong';
+    title?: ReactNode;
+    children: ReactNode;
+}): react.JSX.Element;
+
+/** A display equation rendered with KaTeX, with an optional caption. */
+declare function Equation({ tex, caption }: {
+    tex: string;
+    caption?: ReactNode;
+}): react.JSX.Element;
+/** Inline math for use within a sentence. */
+declare function InlineMath({ tex }: {
+    tex: string;
+}): react.JSX.Element;
+
+/** Wraps an inline SVG schematic (or any figure) with a centered caption. Theme-aware figures use
+ * the `dg-*` / `fig-svg` classes from styles.css and CSS palette variables (follow light/dark). */
+declare function Figure({ caption, children }: {
+    caption?: ReactNode;
+    children: ReactNode;
+}): react.JSX.Element;
+
+interface Citation {
+    id: string;
+    /** Short inline label, e.g. "Little 1961". */
+    label: string;
+    /** Full bibliographic string for the reference list. */
+    citation: string;
+    doi?: string;
+    url?: string;
+}
+/** Provide the app's citation list once (e.g. at the page root) so <Cite>/<ReferenceList> resolve ids. */
+declare function CitationsProvider({ items, children }: {
+    items: Citation[];
+    children: ReactNode;
+}): react.JSX.Element;
+/** Inline reference linked to its DOI/URL, e.g. "(Little 1961)". */
+declare function Cite({ id, paren }: {
+    id: string;
+    paren?: boolean;
+}): react.JSX.Element;
+/** A short inline "Refs: a · b · c" row (e.g. under a deep sub-tab). */
+declare function Refs({ ids, label }: {
+    ids: string[];
+    label: string;
+}): react.JSX.Element;
+/** Full ordered bibliography. Omit `ids` to render every provided citation. */
+declare function ReferenceList({ ids, heading }: {
+    ids?: string[];
+    heading?: string;
+}): react.JSX.Element;
+
+export { AppShell, Callout, type Citation, CitationsProvider, Cite, Equation, Figure, InlineMath, type Lang, LanguageToggle, ReferenceList, Refs, type ShellConfig, type ShellRoute, type SubTabDef, SubTabs, type TabDef, Tabs, type Theme, ThemeToggle, applyTheme, readTheme, useLangStore, useShellLang, useThemeStore };

package/dist/index.js

@@ -0,0 +1,371 @@
+import { NavLink } from 'react-router-dom';
+import { Sun, Moon, Languages, Boxes, Github, Globe, Briefcase } from 'lucide-react';
+import { create } from 'zustand';
+import { jsxs, jsx } from 'react/jsx-runtime';
+import { createContext, useId, useState, useContext } from 'react';
+import katex from 'katex';
+
+// src/shell/AppShell.tsx
+var KEY = "caos.lang";
+function readLang() {
+  try {
+    const s = localStorage.getItem(KEY);
+    if (s === "en" || s === "es") return s;
+  } catch {
+  }
+  return "en";
+}
+var useLangStore = create((set, get) => ({
+  lang: readLang(),
+  setLang: (l) => {
+    try {
+      localStorage.setItem(KEY, l);
+    } catch {
+    }
+    set({ lang: l });
+  },
+  toggle: () => {
+    const next = get().lang === "en" ? "es" : "en";
+    try {
+      localStorage.setItem(KEY, next);
+    } catch {
+    }
+    set({ lang: next });
+  }
+}));
+var useShellLang = () => useLangStore((s) => s.lang);
+
+// src/lib/chrome.ts
+var CHROME = {
+  en: {
+    github: "Source on GitHub",
+    personal: "Personal site",
+    portfolio: "Portfolio",
+    toggleTheme: "Toggle light / dark",
+    toggleLanguage: "Switch language",
+    light: "Light",
+    dark: "Dark",
+    attribution: "Built by Felipe Santib\xE1\xF1ez-Leal",
+    complement: "A CAOS research project",
+    license: "MIT licensed \xB7 open source",
+    version: "v"
+  },
+  es: {
+    github: "C\xF3digo en GitHub",
+    personal: "Sitio personal",
+    portfolio: "Portafolio",
+    toggleTheme: "Cambiar claro / oscuro",
+    toggleLanguage: "Cambiar idioma",
+    light: "Claro",
+    dark: "Oscuro",
+    attribution: "Hecho por Felipe Santib\xE1\xF1ez-Leal",
+    complement: "Un proyecto de investigaci\xF3n CAOS",
+    license: "Licencia MIT \xB7 c\xF3digo abierto",
+    version: "v"
+  }
+};
+var chrome = (lang) => CHROME[lang];
+var KEY2 = "caos.theme";
+function readTheme() {
+  try {
+    const s = localStorage.getItem(KEY2);
+    if (s === "light" || s === "dark") return s;
+    return window.matchMedia("(prefers-color-scheme: light)").matches ? "light" : "dark";
+  } catch {
+    return "dark";
+  }
+}
+function applyTheme(t) {
+  try {
+    document.documentElement.dataset.theme = t;
+  } catch {
+  }
+}
+var useThemeStore = create((set, get) => ({
+  theme: readTheme(),
+  toggleTheme: () => {
+    const next = get().theme === "dark" ? "light" : "dark";
+    applyTheme(next);
+    try {
+      localStorage.setItem(KEY2, next);
+    } catch {
+    }
+    set({ theme: next });
+  },
+  setTheme: (t) => {
+    applyTheme(t);
+    try {
+      localStorage.setItem(KEY2, t);
+    } catch {
+    }
+    set({ theme: t });
+  }
+}));
+function ThemeToggle() {
+  const theme = useThemeStore((s) => s.theme);
+  const toggleTheme = useThemeStore((s) => s.toggleTheme);
+  const c = chrome(useShellLang());
+  return /* @__PURE__ */ jsxs("button", { type: "button", className: "icon-btn", onClick: toggleTheme, "aria-label": c.toggleTheme, title: c.toggleTheme, children: [
+    theme === "dark" ? /* @__PURE__ */ jsx(Sun, { size: 18, "aria-hidden": "true" }) : /* @__PURE__ */ jsx(Moon, { size: 18, "aria-hidden": "true" }),
+    /* @__PURE__ */ jsx("span", { className: "sr-only", children: theme === "dark" ? c.light : c.dark })
+  ] });
+}
+function LanguageToggle() {
+  const lang = useLangStore((s) => s.lang);
+  const toggle = useLangStore((s) => s.toggle);
+  const c = chrome(lang);
+  return /* @__PURE__ */ jsxs("button", { type: "button", className: "icon-btn", onClick: toggle, "aria-label": c.toggleLanguage, title: c.toggleLanguage, children: [
+    /* @__PURE__ */ jsx(Languages, { size: 18, "aria-hidden": "true" }),
+    /* @__PURE__ */ jsx("span", { className: "lang-code", children: lang })
+  ] });
+}
+var PERSONAL = "https://fsantibanezleal.github.io";
+var PORTFOLIO = "https://fasl-work.com";
+function AppShell({ config, children }) {
+  const lang = useShellLang();
+  const c = chrome(lang);
+  const routes = config.routes ?? [];
+  const personal = config.links.personal ?? PERSONAL;
+  const portfolio = config.links.portfolio ?? PORTFOLIO;
+  return /* @__PURE__ */ jsxs("div", { className: "app-shell", children: [
+    /* @__PURE__ */ jsx("header", { className: "site-header", children: /* @__PURE__ */ jsxs("div", { className: "header-inner", children: [
+      /* @__PURE__ */ jsxs(NavLink, { to: "/", className: "brand", "aria-label": config.product.name, children: [
+        /* @__PURE__ */ jsx("span", { className: "brand-mark", children: config.product.mark ?? /* @__PURE__ */ jsx(Boxes, { size: 18, "aria-hidden": "true" }) }),
+        /* @__PURE__ */ jsx("span", { children: config.product.name })
+      ] }),
+      routes.length > 1 && /* @__PURE__ */ jsx("nav", { className: "main-nav", "aria-label": config.product.name, children: routes.map((r) => /* @__PURE__ */ jsx(
+        NavLink,
+        {
+          to: r.path,
+          end: r.path === "/",
+          className: ({ isActive }) => isActive ? "nav-link active" : "nav-link",
+          children: lang === "es" ? r.es : r.en
+        },
+        r.path
+      )) }),
+      /* @__PURE__ */ jsxs("div", { className: "header-actions", children: [
+        /* @__PURE__ */ jsx("a", { className: "icon-btn", href: config.links.github, target: "_blank", rel: "noreferrer noopener", "aria-label": c.github, title: c.github, children: /* @__PURE__ */ jsx(Github, { size: 18, "aria-hidden": "true" }) }),
+        /* @__PURE__ */ jsx("a", { className: "icon-btn", href: personal, target: "_blank", rel: "noreferrer noopener", "aria-label": c.personal, title: c.personal, children: /* @__PURE__ */ jsx(Globe, { size: 18, "aria-hidden": "true" }) }),
+        /* @__PURE__ */ jsx("a", { className: "icon-btn", href: portfolio, target: "_blank", rel: "noreferrer noopener", "aria-label": c.portfolio, title: c.portfolio, children: /* @__PURE__ */ jsx(Briefcase, { size: 18, "aria-hidden": "true" }) }),
+        /* @__PURE__ */ jsx("span", { className: "header-sep", "aria-hidden": "true" }),
+        /* @__PURE__ */ jsx(LanguageToggle, {}),
+        /* @__PURE__ */ jsx(ThemeToggle, {})
+      ] })
+    ] }) }),
+    /* @__PURE__ */ jsx("main", { className: "page", children }),
+    /* @__PURE__ */ jsx("footer", { className: "site-footer", children: /* @__PURE__ */ jsxs("div", { className: "footer-inner", children: [
+      /* @__PURE__ */ jsxs("div", { className: "footer-meta", children: [
+        /* @__PURE__ */ jsx("span", { children: c.attribution }),
+        /* @__PURE__ */ jsx("span", { "aria-hidden": "true", children: "\xB7" }),
+        /* @__PURE__ */ jsx("span", { children: c.complement })
+      ] }),
+      /* @__PURE__ */ jsxs("div", { className: "footer-meta", children: [
+        /* @__PURE__ */ jsx("a", { href: config.links.github, target: "_blank", rel: "noreferrer noopener", children: c.github }),
+        /* @__PURE__ */ jsx("span", { "aria-hidden": "true", children: "\xB7" }),
+        /* @__PURE__ */ jsx("a", { href: personal, target: "_blank", rel: "noreferrer noopener", children: c.personal }),
+        /* @__PURE__ */ jsx("span", { "aria-hidden": "true", children: "\xB7" }),
+        /* @__PURE__ */ jsx("a", { href: portfolio, target: "_blank", rel: "noreferrer noopener", children: c.portfolio }),
+        /* @__PURE__ */ jsx("span", { "aria-hidden": "true", children: "\xB7" }),
+        /* @__PURE__ */ jsx("span", { className: "faint", children: c.license }),
+        /* @__PURE__ */ jsx("span", { className: "footer-build", children: /* @__PURE__ */ jsxs("span", { children: [
+          c.version,
+          config.version
+        ] }) })
+      ] })
+    ] }) })
+  ] });
+}
+function Tabs({ tabs, initial, ariaLabel }) {
+  const baseId = useId();
+  const first = tabs[0]?.id ?? "";
+  const [active, setActive] = useState(initial ?? first);
+  function onKeyDown(e, idx) {
+    if (e.key !== "ArrowRight" && e.key !== "ArrowLeft" && e.key !== "Home" && e.key !== "End") return;
+    e.preventDefault();
+    let next = idx;
+    if (e.key === "ArrowRight") next = (idx + 1) % tabs.length;
+    else if (e.key === "ArrowLeft") next = (idx - 1 + tabs.length) % tabs.length;
+    else if (e.key === "Home") next = 0;
+    else if (e.key === "End") next = tabs.length - 1;
+    const target = tabs[next];
+    if (target) {
+      setActive(target.id);
+      document.getElementById(`${baseId}-tab-${target.id}`)?.focus();
+    }
+  }
+  return /* @__PURE__ */ jsxs("div", { className: "tabs", children: [
+    /* @__PURE__ */ jsx("div", { className: "tablist", role: "tablist", "aria-label": ariaLabel, children: tabs.map((tab, idx) => {
+      const selected = tab.id === active;
+      return /* @__PURE__ */ jsx(
+        "button",
+        {
+          id: `${baseId}-tab-${tab.id}`,
+          role: "tab",
+          type: "button",
+          "aria-selected": selected,
+          "aria-controls": `${baseId}-panel-${tab.id}`,
+          tabIndex: selected ? 0 : -1,
+          className: selected ? "tab active" : "tab",
+          onClick: () => setActive(tab.id),
+          onKeyDown: (e) => onKeyDown(e, idx),
+          children: tab.label
+        },
+        tab.id
+      );
+    }) }),
+    tabs.map((tab) => /* @__PURE__ */ jsx(
+      "div",
+      {
+        id: `${baseId}-panel-${tab.id}`,
+        role: "tabpanel",
+        "aria-labelledby": `${baseId}-tab-${tab.id}`,
+        hidden: tab.id !== active,
+        tabIndex: 0,
+        className: "tabpanel",
+        children: tab.id === active ? tab.content : null
+      },
+      tab.id
+    ))
+  ] });
+}
+function SubTabs({
+  tabs,
+  initial,
+  ariaLabel,
+  orientation = "horizontal"
+}) {
+  const baseId = useId();
+  const first = tabs[0]?.id ?? "";
+  const [active, setActive] = useState(initial ?? first);
+  const vertical = orientation === "vertical";
+  function onKeyDown(e, idx) {
+    const fwd = vertical ? "ArrowDown" : "ArrowRight";
+    const back = vertical ? "ArrowUp" : "ArrowLeft";
+    if (e.key !== fwd && e.key !== back && e.key !== "Home" && e.key !== "End") return;
+    e.preventDefault();
+    let next = idx;
+    if (e.key === fwd) next = (idx + 1) % tabs.length;
+    else if (e.key === back) next = (idx - 1 + tabs.length) % tabs.length;
+    else if (e.key === "Home") next = 0;
+    else if (e.key === "End") next = tabs.length - 1;
+    const target = tabs[next];
+    if (target) {
+      setActive(target.id);
+      document.getElementById(`${baseId}-subtab-${target.id}`)?.focus();
+    }
+  }
+  return /* @__PURE__ */ jsxs("div", { className: vertical ? "subtabs subtabs-vertical" : "subtabs", children: [
+    /* @__PURE__ */ jsx("div", { className: "subtablist", role: "tablist", "aria-label": ariaLabel, "aria-orientation": vertical ? "vertical" : "horizontal", children: tabs.map((tab, idx) => {
+      const selected = tab.id === active;
+      return /* @__PURE__ */ jsx(
+        "button",
+        {
+          id: `${baseId}-subtab-${tab.id}`,
+          role: "tab",
+          type: "button",
+          "aria-selected": selected,
+          "aria-controls": `${baseId}-subpanel-${tab.id}`,
+          tabIndex: selected ? 0 : -1,
+          className: selected ? "subtab active" : "subtab",
+          onClick: () => setActive(tab.id),
+          onKeyDown: (e) => onKeyDown(e, idx),
+          children: tab.label
+        },
+        tab.id
+      );
+    }) }),
+    /* @__PURE__ */ jsx("div", { className: "subtabpanels", children: tabs.map((tab) => /* @__PURE__ */ jsx(
+      "div",
+      {
+        id: `${baseId}-subpanel-${tab.id}`,
+        role: "tabpanel",
+        "aria-labelledby": `${baseId}-subtab-${tab.id}`,
+        hidden: tab.id !== active,
+        tabIndex: 0,
+        className: "subtabpanel",
+        children: tab.id === active ? tab.content : null
+      },
+      tab.id
+    )) })
+  ] });
+}
+function Callout({
+  variant = "note",
+  title,
+  children
+}) {
+  const cls = variant === "honest" ? "callout callout-honest" : variant === "strong" ? "callout callout-strong" : "callout callout-note";
+  return /* @__PURE__ */ jsxs("div", { className: cls, children: [
+    title && /* @__PURE__ */ jsx("p", { className: "callout-title", children: title }),
+    /* @__PURE__ */ jsx("div", { className: "callout-body", children })
+  ] });
+}
+function Equation({ tex, caption }) {
+  const html = katex.renderToString(tex, { displayMode: true, throwOnError: false });
+  return /* @__PURE__ */ jsxs("div", { className: "equation", children: [
+    /* @__PURE__ */ jsx("div", { dangerouslySetInnerHTML: { __html: html } }),
+    caption && /* @__PURE__ */ jsx("div", { className: "equation-caption", children: caption })
+  ] });
+}
+function InlineMath({ tex }) {
+  const html = katex.renderToString(tex, { displayMode: false, throwOnError: false });
+  return /* @__PURE__ */ jsx("span", { dangerouslySetInnerHTML: { __html: html } });
+}
+function Figure({ caption, children }) {
+  return /* @__PURE__ */ jsxs("figure", { className: "figure", children: [
+    children,
+    caption && /* @__PURE__ */ jsx("figcaption", { className: "figure-caption", children: caption })
+  ] });
+}
+var CitationsContext = createContext({ list: [], byId: {} });
+function CitationsProvider({ items, children }) {
+  const byId = {};
+  for (const c of items) byId[c.id] = c;
+  return /* @__PURE__ */ jsx(CitationsContext.Provider, { value: { list: items, byId }, children });
+}
+function href(c) {
+  return c.doi ? `https://doi.org/${c.doi}` : c.url;
+}
+function Cite({ id, paren = true }) {
+  const { byId } = useContext(CitationsContext);
+  const c = byId[id];
+  if (!c) return /* @__PURE__ */ jsxs("cite", { className: "cite-inline", children: [
+    "[",
+    id,
+    "]"
+  ] });
+  const h = href(c);
+  const label = h ? /* @__PURE__ */ jsx("a", { href: h, target: "_blank", rel: "noreferrer noopener", children: c.label }) : /* @__PURE__ */ jsx("span", { children: c.label });
+  return /* @__PURE__ */ jsxs("cite", { className: "cite-inline", children: [
+    paren ? "(" : null,
+    label,
+    paren ? ")" : null
+  ] });
+}
+function Refs({ ids, label }) {
+  return /* @__PURE__ */ jsxs("p", { className: "th-refs", children: [
+    /* @__PURE__ */ jsx("span", { className: "th-refs-label", children: label }),
+    " ",
+    ids.map((id, i) => /* @__PURE__ */ jsxs("span", { children: [
+      i > 0 ? " \xB7 " : null,
+      /* @__PURE__ */ jsx(Cite, { id, paren: false })
+    ] }, id))
+  ] });
+}
+function ReferenceList({ ids, heading }) {
+  const { list, byId } = useContext(CitationsContext);
+  const items = ids ? ids.map((k) => byId[k]).filter(Boolean) : list;
+  return /* @__PURE__ */ jsxs("section", { className: "references", "aria-label": heading ?? "References", children: [
+    heading ? /* @__PURE__ */ jsx("h2", { children: heading }) : null,
+    /* @__PURE__ */ jsx("ol", { className: "reference-list", children: items.map((c) => {
+      const h = href(c);
+      return /* @__PURE__ */ jsxs("li", { children: [
+        /* @__PURE__ */ jsx("span", { children: c.citation }),
+        " ",
+        h ? /* @__PURE__ */ jsx("a", { href: h, target: "_blank", rel: "noreferrer noopener", className: "faint", children: c.doi ? `doi:${c.doi}` : "link" }) : null
+      ] }, c.id);
+    }) })
+  ] });
+}
+
+export { AppShell, Callout, CitationsProvider, Cite, Equation, Figure, InlineMath, LanguageToggle, ReferenceList, Refs, SubTabs, Tabs, ThemeToggle, applyTheme, readTheme, useLangStore, useShellLang, useThemeStore };

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@fasl-work/caos-app-shell",
+  "version": "0.1.0",
+  "description": "Shared web-app shell + content primitives + design system for the CAOS / Faena public apps (ADR-0016).",
+  "license": "MIT",
+  "author": "Felipe Santibáñez-Leal",
+  "repository": "github:fsantibanezleal/CAOS_APP_SHELL",
+  "type": "module",
+  "publishConfig": { "access": "public" },
+  "sideEffects": ["*.css"],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./styles.css": "./styles.css"
+  },
+  "files": ["dist", "styles.css"],
+  "scripts": {
+    "build": "tsup",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "katex": "^0.16.0",
+    "lucide-react": "^0.400.0 || ^0.500.0",
+    "react": "^18 || ^19",
+    "react-dom": "^18 || ^19",
+    "react-router-dom": "^6 || ^7",
+    "zustand": "^4 || ^5"
+  },
+  "devDependencies": {
+    "@types/katex": "^0.16.7",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "katex": "^0.16.11",
+    "lucide-react": "^0.469.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-router-dom": "^7.1.1",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.3",
+    "zustand": "^5.0.2"
+  }
+}

package/styles.css

@@ -0,0 +1,221 @@
+@import "katex/dist/katex.min.css";
+
+/* @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"; */
+
+:root,
+[data-theme="dark"] {
+  --color-bg: #0d1117;
+  --color-surface: #161b22;
+  --color-surface-2: #1c2230;
+  --color-border: #30363d;
+  --color-fg: #c9d1d9;
+  --color-fg-subtle: #9aa6b2;
+  --color-fg-faint: #6c7785;
+  --color-accent: #58a6ff;
+  --color-accent-fg: #0d1117;
+  --color-accent-soft: #132036;
+  --color-accent-2: #3fb1c8;
+  --color-magenta: #f778ba;
+  --color-good: #3fb950;
+  --color-warn: #d29922;
+  --color-bad: #f85149;
+  --color-shadow: 0 1px 2px rgba(0, 0, 0, 0.4), 0 6px 16px rgba(0, 0, 0, 0.45);
+  --font-sans: ui-sans-serif, system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+  --font-mono: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
+  --maxw: 1200px;
+}
+
+[data-theme="light"] {
+  --color-bg: #f6f8fa;
+  --color-surface: #ffffff;
+  --color-surface-2: #f0f3f6;
+  --color-border: #d0d7de;
+  --color-fg: #1f2328;
+  --color-fg-subtle: #57606a;
+  --color-fg-faint: #6e7781;
+  --color-accent: #0969da;
+  --color-accent-fg: #ffffff;
+  --color-accent-soft: #ddf4ff;
+  --color-accent-2: #0a7c8a;
+  --color-magenta: #bf3989;
+  --color-good: #1a7f37;
+  --color-warn: #9a6700;
+  --color-bad: #cf222e;
+  --color-shadow: 0 1px 2px rgba(31, 35, 40, 0.06), 0 4px 10px rgba(31, 35, 40, 0.04);
+}
+
+* { box-sizing: border-box; }
+html, body, #root { height: 100%; }
+body {
+  margin: 0;
+  font-family: var(--font-sans);
+  background-color: var(--color-bg);
+  color: var(--color-fg);
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+  line-height: 1.55;
+}
+a { color: var(--color-accent); text-decoration: none; }
+a:hover { text-decoration: underline; }
+button { font: inherit; cursor: pointer; color: inherit; }
+h1, h2, h3, h4 { line-height: 1.2; font-weight: 650; letter-spacing: -0.01em; }
+code, kbd { font-family: var(--font-mono); }
+
+/* ── Layout primitives ── */
+.app-shell { min-height: 100vh; display: flex; flex-direction: column; background: var(--color-bg); color: var(--color-fg); }
+.container { width: 100%; max-width: var(--maxw); margin-inline: auto; padding-inline: 1.5rem; }
+.page { flex: 1 1 auto; width: 100%; }
+.page-body { width: 100%; max-width: var(--maxw); margin-inline: auto; padding: 2.25rem 1.5rem 3rem; }
+.muted { color: var(--color-fg-subtle); }
+.faint { color: var(--color-fg-faint); }
+.mono { font-family: var(--font-mono); font-size: 0.9em; }
+.small { font-size: 0.84rem; }
+.card { background: var(--color-surface); border: 1px solid var(--color-border); border-radius: 10px; padding: 1.25rem 1.5rem; box-shadow: var(--color-shadow); }
+.badge { display: inline-flex; align-items: center; gap: 0.35rem; font-size: 0.78rem; padding: 0.15rem 0.55rem; border-radius: 999px; border: 1px solid var(--color-border); background: var(--color-surface-2); color: var(--color-fg-subtle); }
+.badge.live { color: var(--color-good); border-color: color-mix(in oklab, var(--color-good) 45%, transparent); }
+.badge.precomputed, .badge.accent { color: var(--color-accent); border-color: color-mix(in oklab, var(--color-accent) 45%, transparent); }
+.badge.warn { color: var(--color-warn); border-color: color-mix(in oklab, var(--color-warn) 45%, transparent); }
+
+/* ── Header ── */
+.site-header { position: sticky; top: 0; z-index: 50; border-bottom: 1px solid var(--color-border); background: color-mix(in oklab, var(--color-bg) 82%, transparent); backdrop-filter: blur(8px); }
+.header-inner { max-width: var(--maxw); margin-inline: auto; height: 56px; padding-inline: 1.5rem; display: flex; align-items: center; gap: 1rem; }
+.brand { display: inline-flex; align-items: center; gap: 0.5rem; font-weight: 700; letter-spacing: -0.02em; color: var(--color-fg); }
+.brand:hover { text-decoration: none; }
+.brand .brand-mark { color: var(--color-accent); display: inline-flex; flex: none; }
+.main-nav { display: flex; align-items: center; gap: 0.15rem; }
+.nav-link { padding: 0.4rem 0.7rem; border-radius: 6px; font-size: 0.9rem; color: var(--color-fg-subtle); transition: color 0.15s, background-color 0.15s; }
+.nav-link:hover { text-decoration: none; color: var(--color-fg); }
+.nav-link.active { color: var(--color-accent); background: var(--color-accent-soft); font-weight: 600; }
+.header-actions { margin-left: auto; display: inline-flex; align-items: center; gap: 0.15rem; }
+.icon-btn { display: inline-flex; align-items: center; justify-content: center; gap: 0.3rem; padding: 0.4rem 0.5rem; border-radius: 6px; background: transparent; border: none; color: var(--color-fg-subtle); opacity: 0.85; transition: opacity 0.15s, color 0.15s; }
+.icon-btn:hover { opacity: 1; color: var(--color-fg); text-decoration: none; }
+.icon-btn svg { display: block; flex: none; }
+.lang-code { font-size: 0.72rem; text-transform: uppercase; letter-spacing: 0.06em; font-weight: 600; }
+.header-sep { width: 1px; height: 20px; margin-inline: 0.4rem; background: var(--color-border); }
+
+/* ── Footer ── */
+.site-footer { border-top: 1px solid var(--color-border); margin-top: 3rem; background: var(--color-surface); }
+.footer-inner { max-width: var(--maxw); margin-inline: auto; padding: 1.5rem; display: flex; flex-direction: column; gap: 0.9rem; font-size: 0.85rem; color: var(--color-fg-faint); }
+.footer-meta { display: flex; flex-wrap: wrap; align-items: center; gap: 0.5rem 0.75rem; }
+.footer-build { margin-left: auto; font-family: var(--font-mono); font-size: 0.72rem; color: var(--color-fg-faint); display: inline-flex; gap: 0.6rem; flex-wrap: wrap; }
+
+/* ── 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 (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) */
+.prose { font-size: 0.98rem; }
+.prose section { margin-block: 1.75rem; }
+.measure { max-width: 70ch; }
+.fig-row { display: grid; grid-template-columns: 1.1fr 1fr; gap: 1.5rem; align-items: center; margin-block: 1.5rem; }
+.fig-row.rev { grid-template-columns: 1fr 1.1fr; }
+@media (max-width: 820px) { .fig-row, .fig-row.rev { grid-template-columns: 1fr; } }
+.def-grid { display: grid; grid-template-columns: repeat(auto-fit, minmax(240px, 1fr)); gap: 1rem; margin-block: 1.25rem; }
+.def { background: var(--color-surface); border: 1px solid var(--color-border); border-radius: 10px; padding: 0.9rem 1.1rem; }
+.def h4 { margin: 0 0 0.3rem; color: var(--color-accent); font-size: 0.95rem; }
+.def p { margin: 0; font-size: 0.9rem; color: var(--color-fg-subtle); }
+.assume { margin-block: 1rem; padding: 0.85rem 1rem; background: var(--color-surface-2); border: 1px solid var(--color-border); border-radius: 8px; }
+.assume-title { margin: 0 0 0.4rem; font-size: 0.76rem; font-weight: 650; text-transform: uppercase; letter-spacing: 0.04em; color: var(--color-fg-faint); }
+.assume ul { margin: 0; padding-left: 1.2rem; color: var(--color-fg-subtle); }
+.assume li { margin-block: 0.3rem; font-size: 0.92rem; }
+.references { margin-top: 2.5rem; border-top: 1px solid var(--color-border); padding-top: 1rem; }
+.reference-list { font-size: 0.85rem; color: var(--color-fg-subtle); line-height: 1.5; padding-left: 1.4rem; }
+.reference-list li { margin-block: 0.5rem; }
+.cite-inline { font-style: normal; font-size: 0.92em; color: var(--color-fg-subtle); }
+.th-refs { margin-top: 1.25rem; padding-top: 0.6rem; border-top: 1px dashed var(--color-border); font-size: 0.85rem; color: var(--color-fg-subtle); }
+.th-refs-label { font-weight: 650; color: var(--color-fg-faint); }
+.prose h2 { font-size: 1.3rem; margin-block: 1.4rem 0.6rem; }
+.prose h3 { font-size: 1.06rem; margin-block: 1.1rem 0.4rem; }
+.prose p { margin-block: 0.6rem; }
+.prose ul, .prose ol { margin-block: 0.5rem; padding-left: 1.3rem; }
+.prose li { margin-block: 0.35rem; }
+.page-head { border-bottom: 1px solid var(--color-border); padding-bottom: 1rem; margin-bottom: 1.25rem; }
+.page-head h1 { font-size: 1.7rem; margin: 0 0 0.4rem; }
+.lede { color: var(--color-fg-subtle); font-size: 1.08rem; margin: 0; max-width: 70ch; }
+.two-col { display: grid; grid-template-columns: 1fr 1fr; gap: 1.25rem; margin-block: 1.5rem; }
+@media (max-width: 760px) { .two-col { grid-template-columns: 1fr; } }
+.tick-list, .cross-list { list-style: none; padding-left: 0; margin: 0.4rem 0 0; }
+.tick-list li, .cross-list li { position: relative; padding-left: 1.5rem; margin-block: 0.5rem; }
+.tick-list li::before { content: "✓"; position: absolute; left: 0; color: var(--color-good); font-weight: 700; }
+.cross-list li::before { content: "✕"; position: absolute; left: 0; color: var(--color-fg-faint); font-weight: 700; }
+
+/* ── Callouts ── */
+.callout { margin-block: 1rem; padding: 0.8rem 1.1rem; border-left: 3px solid var(--color-border); background: var(--color-surface-2); border-radius: 0 8px 8px 0; }
+.callout-honest { border-left-color: var(--color-warn); }
+.callout-strong { border-left-color: var(--color-accent); background: var(--color-accent-soft); }
+.callout-note { border-left-color: var(--color-fg-faint); }
+.callout-title { font-weight: 650; margin: 0 0 0.4rem; color: var(--color-fg); }
+.callout-body { color: var(--color-fg-subtle); }
+.callout-body p:first-child { margin-top: 0; }
+.callout-body p:last-child { margin-bottom: 0; }
+
+/* ── Tabs ── */
+.tablist { display: flex; gap: 0.35rem; padding-bottom: 0.6rem; margin-bottom: 1.5rem; border-bottom: 1px solid var(--color-border); flex-wrap: wrap; }
+.tab { padding: 0.5rem 1rem; border: 1px solid transparent; border-radius: 8px; background: transparent; color: var(--color-fg-subtle); font-size: 0.92rem; font-weight: 550; transition: color 0.15s, background-color 0.15s, border-color 0.15s; }
+.tab:hover { color: var(--color-fg); background: var(--color-surface-2); }
+.tab.active { color: var(--color-accent); background: var(--color-accent-soft); border-color: color-mix(in oklab, var(--color-accent) 35%, transparent); font-weight: 650; }
+.tabpanel:focus, .subtabpanel:focus { outline: none; }
+.subtabs { margin-block: 1rem; }
+.subtablist { display: flex; gap: 0.3rem; flex-wrap: wrap; margin-bottom: 1.1rem; }
+.subtab { padding: 0.32rem 0.8rem; border: 1px solid var(--color-border); border-radius: 999px; background: var(--color-surface); color: var(--color-fg-subtle); font-size: 0.84rem; font-weight: 500; transition: color 0.15s, background-color 0.15s, border-color 0.15s; }
+.subtab:hover { color: var(--color-fg); border-color: var(--color-fg-faint); }
+.subtab.active { color: var(--color-accent); background: var(--color-accent-soft); border-color: color-mix(in oklab, var(--color-accent) 40%, transparent); font-weight: 600; }
+.subtabs-vertical { display: grid; grid-template-columns: minmax(180px, 240px) 1fr; gap: 1.5rem; align-items: start; }
+.subtabs-vertical .subtablist { flex-direction: column; margin-bottom: 0; }
+.subtabs-vertical .subtab { text-align: left; border-radius: 8px; }
+@media (max-width: 760px) { .subtabs-vertical { grid-template-columns: 1fr; } .subtabs-vertical .subtablist { flex-direction: row; } }
+
+/* ── Equations / figures ── */
+.equation { margin: 1rem 0; padding: 0.9rem 1rem; background: var(--color-surface); border: 1px solid var(--color-border); border-radius: 8px; overflow-x: auto; }
+.equation-caption { margin-top: 0.5rem; font-size: 0.82rem; color: var(--color-fg-faint); text-align: center; }
+.katex { color: var(--color-fg); }
+.figure { margin: 1.5rem 0; }
+.figure-caption, .fig-cap { text-align: center; font-size: 0.84rem; color: var(--color-fg-faint); margin-top: 0.6rem; font-style: italic; }
+
+/* ── Theme-aware inline SVG figures (teaching diagrams) ── */
+.fig-svg { width: 100%; max-width: 560px; height: auto; display: block; margin-inline: auto; }
+.fig-svg.wide { max-width: 760px; }
+.dg-axis { stroke: var(--color-fg-faint); stroke-width: 1.3; }
+.dg-axis-label { fill: var(--color-fg-subtle); font: 12px var(--font-sans); }
+.dg-tick { fill: var(--color-fg-faint); font: 11px var(--font-mono); }
+.dg-grid { stroke: var(--color-border); stroke-width: 0.5; opacity: 0.6; }
+.dg-curve { fill: none; stroke: var(--color-accent); stroke-width: 2.2; stroke-linejoin: round; }
+.dg-curve-2 { fill: none; stroke: var(--color-magenta); stroke-width: 2; }
+.dg-curve-faint { fill: none; stroke: var(--color-fg-faint); stroke-width: 1.4; stroke-dasharray: 4 3; }
+.dg-asymptote { stroke: var(--color-bad); stroke-width: 1.4; stroke-dasharray: 4 4; }
+.dg-marker { stroke: var(--color-warn); stroke-width: 1.2; stroke-dasharray: 3 3; }
+.dg-marker-label { fill: var(--color-warn); font: 600 11px var(--font-mono); }
+.dg-note { fill: var(--color-fg-faint); font: italic 11px var(--font-sans); }
+.dg-fill-accent { fill: color-mix(in oklab, var(--color-accent) 16%, transparent); stroke: var(--color-accent); stroke-width: 1; }
+.dg-fill-warn { fill: color-mix(in oklab, var(--color-warn) 16%, transparent); stroke: var(--color-warn); stroke-width: 1; }
+.dg-box { fill: var(--color-surface); stroke: var(--color-border); stroke-width: 1.3; }
+.dg-box.accent { stroke: var(--color-accent); fill: var(--color-accent-soft); }
+.dg-box.good { stroke: var(--color-good); }
+.dg-box-title { fill: var(--color-fg); font: 650 12px var(--font-sans); }
+.dg-box-title.accent { fill: var(--color-accent); }
+.dg-box-sub { fill: var(--color-fg-subtle); font: 10.5px var(--font-mono); }
+.dg-node { fill: var(--color-surface); stroke: var(--color-accent); stroke-width: 1.4; }
+.dg-node-label { fill: var(--color-fg); font: 600 12px var(--font-mono); }
+.dg-edge { stroke: var(--color-fg-faint); stroke-width: 1.4; fill: none; }
+.dg-edge-label { fill: var(--color-fg-subtle); font: 11px var(--font-mono); }
+.dg-arrowhead { fill: var(--color-fg-faint); }
+.dg-bar { fill: var(--color-accent); }
+.dg-bar-2 { fill: var(--color-magenta); }
+.dg-bar-label { fill: var(--color-fg-subtle); font: 11px var(--font-sans); }
+
+/* ── Generic controls ── */
+.btn { border: 1px solid var(--color-border); background: var(--color-surface-2); color: var(--color-fg); padding: 0.4rem 0.9rem; border-radius: 8px; font-weight: 600; font-size: 0.88rem; display: inline-flex; align-items: center; gap: 0.35rem; }
+.btn:hover { border-color: var(--color-fg-faint); }
+.btn.primary { background: var(--color-accent); color: var(--color-accent-fg); border-color: var(--color-accent); }
+.btn:disabled { opacity: 0.5; cursor: default; }
+.select { background: var(--color-surface-2); color: var(--color-fg); border: 1px solid var(--color-border); border-radius: 8px; padding: 0.35rem 0.5rem; font-size: 0.85rem; }
+.hint { font-size: 0.8rem; color: var(--color-fg-faint); margin: 0; }
+.banner { padding: 0.6rem 0.9rem; border-radius: 8px; font-size: 0.85rem; margin-block: 0.6rem; border-left: 3px solid var(--color-border); background: var(--color-surface-2); }
+.banner.warn { border-left-color: var(--color-warn); color: var(--color-warn); }
+.banner.error { border-left-color: var(--color-bad); color: var(--color-bad); }
+.range { width: 100%; accent-color: var(--color-accent); }