# Sacred Computer — full doc bundle > Concatenation of every AGENTS.md and SKILL.md in the sacred repo, in the same > order as https://sacred.computer/llms.txt. Sacred Computer (React) and Simulacrum > (CLI) are two halves of one framework — the React surface is documented in > components/AGENTS.md, the CLI surface in scripts/cli/AGENTS.md and > scripts/python/AGENTS.md. --- # AGENTS.md # AGENTS.md Orientation for any agent working in `www-sacred`. Read this before touching code. ## What this repo is `www-sacred` (npm package `srcl`) is an open-source React component library with terminal aesthetics. It is consumed in two ways: 1. **A Next.js 16 / React 19 site at `sacred.computer`** that renders every component in a kitchen sink at `app/page.tsx`. 2. **Simulacrum**, a zero-dependency CLI framework under `scripts/cli/lib/` (and a snake_case Python mirror under `scripts/python/sacred_cli/`) so the same layouts can render in a terminal. The React side and the Simulacrum side share a single source of truth for the palette: `scripts/cli/colors.json`. The CSS surface drives the same colors via `--theme-*` custom properties in `global.css`. ## Repo map - `app/` — Next.js App Router. `app/page.tsx` is the kitchen sink. `app/api/*` are tiny demo routes. `app/llm/[...path]/route.ts`, `app/llms.txt/route.ts`, and `app/llms-full.txt/route.ts` expose every `AGENTS.md` and `SKILL.md` as plain `text/markdown` URLs under `https://sacred.computer/llm/...` so external agents can fetch the sacred contract without `git clone`. - `components/` — Sacred React components. `components/AGENTS.md` is the canonical catalog of every component (one entry per `.tsx`, with props, theming tokens, and CLI primitive equivalent) — read this first when picking a component, before grepping. `components/examples/` contains larger demo surfaces (AS400, MessagesInterface, CLITemplate, InvoiceTemplate, ResultsList, OneLineLoaders). `components/SimpleTable.tsx` is the fluid HTML table the CLI port examples use — its column/status contract maps one-to-one onto the CLI framework's `formatRow` + `cardHeaderRow` primitives. `components/Window.tsx` is the React peer of the CLI window primitive — wrap a CLI port surface in `` to render the same dialog frame the alt-screen CLI shows. - `common/` — Constants and utilities shared across components. - `modules/` — Stand-alone modules (snake game, chess, etc.). - `scripts/cli/` — Simulacrum, the sacred CLI framework (CommonJS, zero dependencies). `lib/` is the framework, `lib/__tests__/` is the vitest suite (and the `dump_reference.js` fixture generator), `templates/` is the canonical TS template, `colors.json` is the shared palette. - `scripts/python/` — Simulacrum's Python mirror. `sacred_cli/` is the package, `sacred_cli/__tests__/` is the unittest suite (and the parity test against the JS fixture), `templates/` is the canonical Python template. - `scripts/test_python.js` — Node orchestrator for `npm run test:python`. Probes for `python3`, regenerates the JS fixture, then invokes `python3 -m unittest discover`. Skips with a warning if `python3` is missing. - `skills/` — Four porting skills (TS CLI, Python CLI, React-to-React, hostile React host). Read `skills/*/SKILL.md` before porting. - `.workdir/` — Read-only reference material from sibling projects. Never edit, never ship. ## Conventions - All new comments use `//NOTE(@YOUR_GITHUB_USERNAME): ...` (or `# NOTE(@YOUR_GITHUB_USERNAME): ...` in Python). Comments explain _why_, not _what_. Delete self-documenting comments on sight. - The CLI framework is intentionally zero-dependency CommonJS so TypeScript templates can `require` it via `tsx` with no build step. Do not add ESM imports inside `scripts/cli/lib/*`. - The Python framework mirrors the JS framework one-to-one but uses snake_case. The same `colors.json` is the single source of truth — do not duplicate the palette. The two runtimes are locked into byte-identical output by the parity suite under `scripts/python/sacred_cli/__tests__/test_parity.py`. When you change a JS module, port the change to its Python mirror in the same PR — `npm test` will fail otherwise. - React example components in `components/examples/*` should only depend on sacred's existing primitives (`Card`, `SimpleTable`, `Button`, `RowSpaceBetween`, etc.). The CLI port examples (`CLITemplate`, `InvoiceTemplate`, `ResultsList`) use `SimpleTable`, not `DataTable`, because `SimpleTable`'s column + status contract maps one-to-one onto `formatRow` and `cardHeaderRow`. Do not import from `scripts/cli/lib/*` from React — that code is Node-only and uses `process.stdout`. - Tests live in `scripts/cli/lib/__tests__/*.test.mjs` (vitest, JS), `components/__tests__/*.test.mjs` (vitest, sync guard for the component catalog), `app/llm/__tests__/*.test.mjs` (vitest, sync guard for the `/llm/...` URL surface), and `scripts/python/sacred_cli/__tests__/test_*.py` (unittest, Python). The vitest suite uses `createRequire` so ESM tests can pull in CJS source modules. `npm test` runs both suites; `npm run test:js` and `npm run test:python` run them individually. Run `npm test` before opening a PR. - Sacred CLI ports are static — no animation diffing system. The React side keeps its existing animation primitives (canvas snake, canvas platformer, etc.). The one exception is `OneLineLoaders.tsx` because the spinners are the entire point of that component. ## Scripts ```sh npm install # install deps npm run dev # Next.js dev server on http://localhost:10000 npm test # JS vitest suite + Python unittest + parity suite (chained) npm run test:js # only the JS vitest suite npm run test:python # only the Python suite (skips with a warning if python3 missing) npm run cli:typescript # render the canonical TS CLI template (alt screen, ESC to quit) npm run cli:python # render the canonical Python CLI template (alt screen, ESC to quit) ``` ## Where to start when porting - **React → CLI (TS):** read `skills/port-sacred-terminal-ui-to-typescript-cli/SKILL.md` and `scripts/cli/templates/template.ts`. - **React → CLI (Python):** read `skills/port-sacred-terminal-ui-to-python/SKILL.md` and `scripts/python/templates/template.py`. - **CLI → React (sacred host):** read `skills/port-sacred-terminal-ui-to-react-using-same-conventions/SKILL.md` and any of the `components/examples/CLITemplate.tsx` / `InvoiceTemplate.tsx` / `ResultsList.tsx` files. - **Sacred → foreign React app:** read `skills/port-sacred-terminal-ui-to-hostile-react-codebase/SKILL.md`. ## Keyboard and hotkey system Sacred uses a vendored copy of [react-hotkeys-hook](https://github.com/JohannesKlauss/react-hotkeys-hook) at `modules/hotkeys/`. The module is self-contained CommonJS-compatible React code — no npm dependency. It provides `useHotkeys`, `HotkeysProvider`, `isHotkeyPressed`, and `useRecordHotkeys`. ### Architecture - **`modules/hotkeys/parse-hotkeys.ts`** — parses key strings (`ctrl+a`, `ArrowDown`, `esc`) into a `Hotkey` descriptor with modifier flags (`alt`, `ctrl`, `meta`, `shift`, `mod`) and non-modifier key names. `mod` is a platform-aware shortcut: meta on macOS, ctrl elsewhere. - **`modules/hotkeys/validators.ts`** — matching logic: `isHotkeyMatchingKeyboardEvent` compares a live `KeyboardEvent` against a parsed `Hotkey`, respecting modifier state. Guards (`isHotkeyEnabledOnTag`, `isKeyboardEventTriggeredByInput`) suppress hotkeys when focus is inside form elements unless explicitly opted in. - **`modules/hotkeys/use-hotkeys.ts`** — the main hook. Attaches `keydown`/`keyup` listeners to either a ref'd DOM node or `document`. Supports `scopes` for conditional activation, `enableOnFormTags` / `enableOnContentEditable` overrides, `preventDefault`, and `keyup`-only mode. - **`modules/hotkeys/hotkeys-provider.tsx`** — React context for scope management (`enableScope`, `disableScope`, `toggleScope`) and a registry of all bound hotkeys via `BoundHotkeysProxyProvider`. `HotkeysProvider` is mounted at the app root in `components/Providers.tsx`, activating scope-based hotkey gating for the entire tree. - **`modules/hotkeys/is-hotkey-pressed.ts`** — global `Set` tracking all currently held keys via document-level `keydown`/`keyup` listeners. Used by `useHotkeys` for multi-key combination matching. Handles the macOS meta-key quirk (clears non-modifier keys when meta is released). - **`modules/hotkeys/use-record-hotkeys.ts`** — records key combinations pressed by the user into a `Set`, useful for UI that lets users define their own shortcuts. - **`modules/hotkeys/use-deep-equal-memo.ts`** — memoization helper using `Utilities.deepEqual` to prevent unnecessary re-renders when options objects are structurally equal. ### Where hotkeys are registered | Component | Hotkeys | Purpose | | --- | --- | --- | | `components/page/DefaultActionBar.tsx` | `ArrowDown`, `ArrowUp`, `ArrowRight`, `ArrowLeft`, `Enter`, `Space`, `ctrl+g`, `Escape` | Global focus navigation across all focusable elements + debug grid toggle + dismiss topmost modal | | `components/DropdownMenuTrigger.tsx` | Configurable via `hotkey` prop (e.g. `ctrl+o`, `ctrl+a`, `ctrl+t`) | Opens/closes a dropdown menu | | `components/DropdownMenu.tsx` | `Escape` | Closes the active dropdown (fallback for when focus is outside the menu container) | | `components/modals/ModalError.tsx` | `enter` | Closes the error modal | | `components/modals/ModalChess.tsx` | `enter` | Closes the chess modal | ### Where keyboard events are handled directly (onKeyDown / addEventListener) | Component | Keys | Purpose | | --- | --- | --- | | `components/DropdownMenu.tsx` | `ArrowDown`, `ArrowUp`, `Enter`, `Space`, `Escape` | Menu item navigation with focus wrapping, activation, and dismiss | | `components/DataTable.tsx` | `Enter`, arrow keys | Cell navigation and activation within the gradient table | | `components/ListItem.tsx` | `Enter`, arrow keys | Item activation and sequential focus traversal | | `components/Select.tsx` | `Enter`, `Space`, `Escape`, arrow keys | Open/close listbox, navigate and select options, dismiss | | `components/Input.tsx` | Native `onKeyDown` passthrough | Delegates to consumer callback | | `components/TextArea.tsx` | Native `onKeyDown` passthrough | Delegates to consumer callback | | `components/Checkbox.tsx` | Native `onKeyDown` via `` | Standard checkbox toggling | | `components/RadioButton.tsx` | Native `onKeyDown` via `` | Standard radio selection | | `components/ActionButton.tsx` | `Enter`, `Space` (inline) | Click activation for keyboard users | | `components/ActionListItem.tsx` | `Enter`, `Space` (inline) | Click activation for keyboard users | | `components/Accordion.tsx` | `Enter`, `Space` (inline) | Toggle open/close for keyboard users | | `components/TreeView.tsx` | `Enter`, `Space` (inline) | Toggle expand/collapse for keyboard users | | `components/CanvasPlatformer.tsx` | Arrow keys, `Space` (window listener) | Player movement and jumping | | `components/CanvasSnake.tsx` | Arrow keys (window listener) | Snake direction control | | `components/DOMSnake.tsx` | Arrow keys (window listener) | Snake direction control | ### Integration with the CLI framework The CLI framework (`scripts/cli/lib/app.js`) has its own keyboard system based on Node.js `process.stdin` raw mode. It handles `q`, `Escape` (quit), arrow keys (pagination/selection), and `Enter` (selection confirm). This is completely separate from the React hotkey module — the two systems share concepts but no code. ## Working agreements - Don't commit unless the user explicitly asks. Sacred ships releases manually. - Don't add features the task didn't ask for. If you find a tangential bug, surface it instead of fixing it silently. - Don't import from `.workdir/` at runtime. It is reference material only. - Don't break the kitchen sink. After any component change, render `app/page.tsx` mentally (or in `npm run dev`) and confirm nothing regresses. --- # components/AGENTS.md # AGENTS.md — components Canonical catalog of every React component sacred ships under `components/`. One entry per `.tsx` file directly under `components/`. The `examples/`, `modals/`, `svg/`, `page/`, and `detectors/` subdirectories are intentionally excluded — those are demos, modal bodies, icons, and runtime detectors that compose this library, not the library itself. The catalog is enforced by `components/__tests__/agents_md_sync.test.mjs`, which fails CI if a `.tsx` file is added under `components/` without a matching `## Heading` here, or vice versa. Adding a component without documenting it is a CI failure inside the same PR. ## How to read each entry - **Path** — repo-relative path of the source file. - **Purpose** — one factual sentence pulled from the source. The catalog never invents behavior. - **Props** — copied verbatim from the `interface` / `type Props` block in the source. If the component uses `React.forwardRef`, the inner Props type is what is shown. Sacred components are deliberately untyped or loosely typed in places — the catalog reflects that, it does not normalize. - **Theming tokens** — `var(--theme-*)`, `var(--ansi-*)`, `var(--color-*)`, `var(--font-*)`, and `var(--z-index-*)` references read from the matching `.module.css` file (or inline `style={{}}`). This is the contract that lets a port preserve colors across light/dark and the seven OKLCH tints. If a component has no `.module.css` and no inline tokens, the field reads `(none)`. - **CLI primitive** — the equivalent in the sacred CLI framework (`scripts/cli/lib/*` / `scripts/python/sacred_cli/*`). Pulled from the four port skills' mapping tables. If there is no equivalent — typically because the CLI framework is layout-only and the React component is interactive, animated, or browser-specific — the field reads `(React-only)` plus a one-phrase reason. - **Used by** — at least one concrete reference inside `app/page.tsx` (the kitchen sink) or `components/examples/*.tsx` so an agent can see the component in the wild. The catalog is the **what**. The four `skills/port-sacred-terminal-ui-to-*/SKILL.md` files remain the **how** — they walk through the procedural side of porting and they keep their own (scoped) component mapping tables for the porting workflow they describe. If you are porting a screen, read the skill first; if you just need to know which sacred component renders X, read this catalog. ## Out of scope (gaps to fill in follow-up tasks) - **Per-prop usage examples** — the catalog lists props but does not exhaustively show every meaningful prop combination. A "Storybook-lite" surface that embeds minimal usage snippets per component is a separate, larger task. - **Raw `.tsx` source mirror** — an agent that has read this catalog may want to fetch the raw component source over HTTP. The `/llm/...` URL surface intentionally only exposes Markdown contracts (`AGENTS.md` and `SKILL.md`). A `/llm/components/.tsx.txt` mirror is a follow-up task with a broader allowlist; it is deliberately not part of the first ship so the public surface stays tight. --- ## Accordion - **Path:** `components/Accordion.tsx` - **Purpose:** Click-to-toggle collapsible section with a title row and a children body. - **Props:** ```ts interface AccordionProps { defaultValue?: boolean; title: string; children?: React.ReactNode; } ``` - **Theming tokens:** `--theme-focused-foreground` - **CLI primitive:** (React-only) The CLI framework renders flat pages — there is no folding section concept. - **Used by:** `` in the kitchen sink (`app/page.tsx`). ## ASCIICanvas - **Path:** `components/ASCIICanvas.tsx` - **Purpose:** Animated ASCII art rendered in a `
` element using per-cell `` elements with DOM diffing.
- **Props:**
  ```ts
  { rows?: number }
  ```
- **Theming tokens:** `--font-size`, `--theme-line-height-base`
- **CLI primitive:** (React-only) The CLI framework is static — animation belongs on the React side.
- **Used by:** `` in the "ASCII CANVAS" accordion in `app/page.tsx`.

## ActionBar

- **Path:** `components/ActionBar.tsx`
- **Purpose:** Horizontal toolbar of action items, each with optional hotkey and nested dropdown menu.
- **Props:**
  ```ts
  interface ActionBarProps {
    items: ActionBarItem[];
  }
  ```
- **Theming tokens:** `--theme-background`, `--theme-border`
- **CLI primitive:** `buttonRow` plus repeated `button(hotkey, label)` calls. The CLI version is non-nested; nested dropdowns are React-only.
- **Used by:** `` inside the "ACTION BAR" accordion in `app/page.tsx`.

## ActionButton

- **Path:** `components/ActionButton.tsx`
- **Purpose:** Hotkey + label button pair, the React peer of the CLI `button` primitive.
- **Props:**
  ```ts
  interface ActionButtonProps {
    onClick?: () => void;
    hotkey?: any;
    children?: React.ReactNode;
    style?: any;
    rootStyle?: any;
    isSelected?: boolean;
  }
  ```
- **Theming tokens:** `--theme-button-background`, `--theme-button-foreground`, `--theme-focused-foreground`, `--theme-text`, `--font-family-mono`, `--font-size`
- **CLI primitive:** `button(hotkey, label)` in `scripts/cli/lib/button.js` (`button(hotkey, label)` in the Python mirror). Pair with `buttonRow(...)` to get the same left/right layout.
- **Used by:** `EXIT` in `components/examples/CLITemplate.tsx`, `components/examples/InvoiceTemplate.tsx`, `components/examples/ResultsList.tsx`, and the "ACTION BUTTONS" accordion in `app/page.tsx`. Every CLI port surface uses `ActionButton` (not `Button`) so it stays in lockstep with Simulacrum's `button(hotkey, label)` primitive.

## ActionListItem

- **Path:** `components/ActionListItem.tsx`
- **Purpose:** Menu row that renders as either an anchor or a button with a leading icon glyph.
- **Props:**
  ```ts
  interface ActionListItemProps {
    style?: React.CSSProperties;
    icon?: React.ReactNode;
    children?: React.ReactNode;
    href?: string;
    target?: string;
    onClick?: React.MouseEventHandler;
    role?: string;
  }
  ```
- **Theming tokens:** `--theme-button-background`, `--theme-button-foreground`, `--theme-focused-foreground`, `--theme-text`, `--theme-line-height-base`, `--font-size`
- **CLI primitive:** `cardRow(formatRow([icon, label], colSpec, innerW), innerW)`. The CLI has no anchor concept — interactive items are wired through `createApp({ interactive, onKey })`.
- **Used by:** `` inside the navigation example in `app/page.tsx`.

## AlertBanner

- **Path:** `components/AlertBanner.tsx`
- **Purpose:** Full-width inline notification banner for advisory or warning copy.
- **Props:**
  ```ts
  interface AlertBannerProps {
    style?: any;
    children?: any;
  }
  ```
- **Theming tokens:** `--theme-border`, `--theme-border-subdued`, `--theme-line-height-base`, `--font-size`
- **CLI primitive:** `cardTop('!', innerW)` + `cardRow(text, innerW)` + `cardBot(innerW)` — sacred CLI ships no dedicated banner glyph; an unlabeled card row is the convention.
- **Used by:** `When things reach the extreme, they alternate to the opposite.` in `app/page.tsx`.

## Avatar

- **Path:** `components/Avatar.tsx`
- **Purpose:** Square portrait image (or initials placeholder) with optional inline label and external link.
- **Props:**
  ```ts
  interface AvatarProps extends Omit, 'style' | 'className' | 'children'> {
    src?: string;
    href?: string;
    target?: string;
    style?: React.CSSProperties;
    children?: React.ReactNode;
  }
  ```
- **Theming tokens:** `--theme-window-shadow`, `--theme-focused-foreground`, `--theme-text`, `--theme-line-height-base`, `--font-size`
- **CLI primitive:** (React-only) The CLI is text-only; portraits do not exist there.
- **Used by:** `` inside the "AVATARS" accordion in `app/page.tsx`.

## Badge

- **Path:** `components/Badge.tsx`
- **Purpose:** Inline label chip used for short status / version markers next to titles.
- **Props:**
  ```ts
  interface BadgeProps extends React.HTMLAttributes {
    children?: React.ReactNode;
  }
  ```
- **Theming tokens:** `--theme-border`, `--theme-line-height-base`, `--font-family-mono`, `--font-size`
- **CLI primitive:** Plain string concatenated into a `cardRow`. The CLI framework has no badge glyph because monospace runs are already labeled at column boundaries.
- **Used by:** `{Package.version}` inside the navigation strip in `app/page.tsx`.

## BarLoader

- **Path:** `components/BarLoader.tsx`
- **Purpose:** Fill-style progress bar with optional auto-advancing interval mode.
- **Props:**
  ```ts
  interface BarLoaderProps {
    intervalRate?: number;
    progress?: number;
  }
  ```
- **Theming tokens:** `--theme-border`, `--theme-text`, `--theme-line-height-base`, `--font-size`
- **CLI primitive:** (React-only) Sacred CLI ports are static — there is no animation diff loop. If you want a CLI progress indicator, render a single `cardRow` with the percentage at draw time.
- **Used by:** `` and `` inside the "BAR LOADERS" accordion in `app/page.tsx`.

## BarProgress

- **Path:** `components/BarProgress.tsx`
- **Purpose:** Character-based progress bar that fills its container width with a configurable glyph.
- **Props:**
  ```ts
  interface BarProgressProps {
    intervalRate?: number;
    progress?: number;
    fillChar?: string;
  }
  ```
- **Theming tokens:** `--theme-border-subdued`
- **CLI primitive:** (React-only) Same reason as BarLoader — the CLI is static.
- **Used by:** `` inside `components/examples/OneLineLoaders.tsx`.

## Block

- **Path:** `components/Block.tsx`
- **Purpose:** Inline span block used as a 1ch placeholder or measurement spacer in monospace layouts.
- **Props:**
  ```ts
  interface BlockProps extends React.HTMLAttributes {
    children?: React.ReactNode;
  }
  ```
- **Theming tokens:** `--theme-text`, `--theme-line-height-base`, `--font-size`
- **CLI primitive:** A single space inside a `cardRow`. The CLI lays out by character grid, so a `` is implicit.
- **Used by:** `` as a sizing spacer in `app/page.tsx`.

## BlockLoader

- **Path:** `components/BlockLoader.tsx`
- **Purpose:** Single-glyph spinner cycling through a Unicode box-drawing or block animation sequence.
- **Props:**
  ```ts
  interface BlockLoaderProps extends Omit, 'children'> {
    mode?: number;
  }
  ```
- **Theming tokens:** `--theme-line-height-base`, `--font-size`
- **CLI primitive:** (React-only) Sacred CLI ports are static. `OneLineLoaders.tsx` is the explicit React-side carve-out for spinners.
- **Used by:** `` (and modes 1-11) inside the "BLOCK LOADERS" accordion in `app/page.tsx`.

## BreadCrumbs

- **Path:** `components/BreadCrumbs.tsx`
- **Purpose:** Linked breadcrumb trail with visual separators between hierarchy levels.
- **Props:**
  ```ts
  interface BreadCrumbsProps {
    items: BreadCrumbsItem[];
  }
  ```
- **Theming tokens:** `--theme-border`, `--theme-focused-foreground`, `--theme-text`, `--theme-line-height-base`
- **CLI primitive:** A `cardRow` with `path / segments / joined / by / slashes`. The CLI has no link concept.
- **Used by:** `` inside the "BREADCRUMBS" accordion in `app/page.tsx`.

## Button

- **Path:** `components/Button.tsx`
- **Purpose:** Two-theme HTML `` inside the "BUTTONS" accordion in `app/page.tsx`. Use `ActionButton` instead when porting CLI screens.

## ButtonGroup

- **Path:** `components/ButtonGroup.tsx`
- **Purpose:** Horizontal cluster of `ActionButton`s with selected-state highlighting and optional nested dropdown items.
- **Props:** _(untyped — `props.items: { body, hotkey?, selected?, onClick?, items?, openHotkey? }[]`, `props.isFull?: boolean`)_
- **Theming tokens:** (none)
- **CLI primitive:** `buttonRow(button(...), button(...), innerW)` repeated for each pair.
- **Used by:** `` inside the "BUTTON GROUP" accordion in `app/page.tsx`.

## CanvasPlatformer

- **Path:** `components/CanvasPlatformer.tsx`
- **Purpose:** ASCII-grid 2D platformer mini-game with gravity, block placement, keyboard controls, and touch region controls for mobile (left third = move left, right third = move right, center = jump, multi-touch supported). Renders via pre/span grid with DOM diffing instead of canvas.
- **Props:**
  ```ts
  interface PlatformerProps {
    rows?: number;
  }
  ```
- **Theming tokens:** `--theme-border`, `--theme-text`, `--theme-focused-foreground`, `--font-size`, `--theme-line-height-base`
- **CLI primitive:** (React-only) Sacred CLI ports are static; no animation diffing.
- **Used by:** `` inside the ModalCanvasPlatformer modal triggered from `app/page.tsx`.

## CanvasSnake

- **Path:** `components/CanvasSnake.tsx`
- **Purpose:** ASCII-grid Snake mini-game with directional input (keyboard arrows and swipe gestures on mobile) and food collection. Renders via pre/span grid with DOM diffing instead of canvas.
- **Props:**
  ```ts
  interface SnakeProps {
    rows?: number;
  }
  ```
- **Theming tokens:** `--theme-text`, `--theme-focused-foreground`, `--font-size`, `--theme-line-height-base`
- **CLI primitive:** (React-only) Same reason as CanvasPlatformer.
- **Used by:** `` inside the ModalCanvasSnake modal triggered from `app/page.tsx`.

## Card

- **Path:** `components/Card.tsx`
- **Purpose:** Box-drawing card with a title bar and three corner modes (`default`, `'left'`, `'right'`).
- **Props:**
  ```ts
  interface CardProps extends React.HTMLAttributes {
    children?: React.ReactNode;
    title?: string | any;
    mode?: string | any;
  }
  ```
- **Theming tokens:** `--theme-text`, `--theme-line-height-base`, `--font-size`
- **CLI primitive:** `cardTop(title, innerW)` + `cardRow(content, innerW)` + `cardBot(innerW)` (`scripts/cli/lib/card.js`).
- **Used by:** `...` repeated throughout `app/page.tsx`, and `` in `components/examples/CLITemplate.tsx`.

## CardDouble

- **Path:** `components/CardDouble.tsx`
- **Purpose:** Card variant with a double-stroke outer border, used for nested or emphasis groupings.
- **Props:**
  ```ts
  interface CardProps extends React.HTMLAttributes {
    children?: React.ReactNode;
    title?: string | any;
    mode?: string | any;
    style?: any;
  }
  ```
- **Theming tokens:** `--theme-text`, `--theme-line-height-base`, `--font-size`
- **CLI primitive:** (React-only) The sacred CLI framework only ships single-border cards in `scripts/cli/lib/card.js`.
- **Used by:** `...` inside `components/ComboBox.tsx`.

## Checkbox

- **Path:** `components/Checkbox.tsx`
- **Purpose:** Custom-styled checkbox with click + keyboard toggling and a children label slot.
- **Props:**
  ```ts
  interface CheckboxProps {
    style?: React.CSSProperties;
    checkboxStyle?: React.CSSProperties;
    name: string;
    defaultChecked?: boolean;
    onChange?: (event: React.ChangeEvent) => void;
    tabIndex?: number;
    children?: React.ReactNode;
  }
  ```
- **Theming tokens:** `--theme-border-subdued`, `--theme-button-background`, `--theme-button-foreground`, `--theme-focused-foreground`, `--theme-text`, `--theme-line-height-base`
- **CLI primitive:** `cardRow('[x] label', innerW)` rendered manually by the template; sacred CLI ships no checkbox primitive yet.
- **Used by:** `...` inside the "CHECKBOX" accordion in `app/page.tsx`.

## Chessboard

- **Path:** `components/Chessboard.tsx`
- **Purpose:** 8×8 grid renderer that draws Unicode chess pieces from a 2D position array.
- **Props:**
  ```ts
  interface ChessboardProps {
    board: string[][];
  }
  ```
- **Theming tokens:** `--theme-border-subdued`, `--theme-focused-foreground-subdued`, `--theme-focused-foreground`, `--theme-line-height-base`
- **CLI primitive:** (React-only) The CLI framework has no grid primitive; a CLI port would render the board with eight `cardRow` calls of joined glyphs.
- **Used by:** `` inside the "CHESSBOARD" accordion in `app/page.tsx`.

## CodeBlock

- **Path:** `components/CodeBlock.tsx`
- **Purpose:** Pre-formatted source code block with line numbers and a fixed monospace style.
- **Props:**
  ```ts
  interface CodeBlockProps extends React.HTMLAttributes {
    children?: React.ReactNode;
  }
  ```
- **Theming tokens:** `--theme-background`, `--theme-border-subdued`
- **CLI primitive:** A `cardRow` per line of source. The CLI has no syntax highlighting because the framework is colorless except for status columns.
- **Used by:** `...` inside the "CODE BLOCK" accordion in `app/page.tsx`.

## ComboBox

- **Path:** `components/ComboBox.tsx`
- **Purpose:** Searchable input + filtered result cards combo, optionally backed by a dataset.
- **Props:**
  ```ts
  interface ComboBoxProps {
    data: string[][];
    label?: string;
  }
  ```
- **Theming tokens:** (inherited from `Input` and `CardDouble`)
- **CLI primitive:** `createApp({ interactive: { count, onSelect } })` plus `cardSelectRow` for each filtered row. Sacred CLI's interactive selection lifecycle is the equivalent.
- **Used by:** `` inside the "COMBO BOX" accordion in `app/page.tsx`.

## ContentFluid

- **Path:** `components/ContentFluid.tsx`
- **Purpose:** Block container that expands to the full available width, used as the page-content shell.
- **Props:**
  ```ts
  interface ContentFluidProps extends React.HTMLAttributes {
    children?: React.ReactNode;
  }
  ```
- **Theming tokens:** (none)
- **CLI primitive:** `getInnerWidth(termW)` plus the surrounding window frame in `scripts/cli/lib/window.js` — the CLI framework computes width once and the templates fill it.
- **Used by:** `...` wraps the kitchen sink page body in `app/page.tsx`.

## DataTable

- **Path:** `components/DataTable.tsx`
- **Purpose:** Gradient-tinted interactive data table that animates background fill on cell change.
- **Props:**
  ```ts
  interface TableProps {
    data: string[][];
  }
  ```
- **Theming tokens:** `--theme-focused-foreground-subdued`, `--theme-focused-foreground`
- **CLI primitive:** (React-only) The CLI port story uses `SimpleTable` instead because `SimpleTable`'s column + status contract maps one-to-one onto `formatRow`. `DataTable`'s gradient backgrounds are not part of the CLI surface — do not use it for CLI ports.
- **Used by:** `` inside the "DATA TABLE" accordion in `app/page.tsx`.

## DatePicker

- **Path:** `components/DatePicker.tsx`
- **Purpose:** Calendar widget with month navigation and day cell selection in a 7-column grid.
- **Props:**
  ```ts
  interface DatePickerProps {
    year?: number;
    month?: number;
  }
  ```
- **Theming tokens:** `--theme-border-subdued`, `--theme-border`, `--theme-focused-foreground`, `--theme-text`, `--theme-line-height-base`
- **CLI primitive:** (React-only) No date grid in the CLI framework yet — a port would render rows of `formatRow` cells.
- **Used by:** `` inside the "DATE PICKER" accordion in `app/page.tsx`.

## DebugGrid

- **Path:** `components/DebugGrid.tsx`
- **Purpose:** Hidden character-grid overlay for visualizing alignment during layout work.
- **Props:** _(no props)_
- **Theming tokens:** `--theme-border`
- **CLI primitive:** (React-only) The CLI framework already snaps to character columns by definition.
- **Used by:** `` rendered above the kitchen sink in `app/page.tsx`.

## DefaultMetaTags

- **Path:** `components/DefaultMetaTags.tsx`
- **Purpose:** Static `` metadata block for viewport, language, and favicon defaults.
- **Props:** _(no props)_
- **Theming tokens:** (none)
- **CLI primitive:** (React-only) HTML metadata has no CLI analogue.
- **Used by:** `app/head.tsx` for the kitchen sink page.

## Dialog

- **Path:** `components/Dialog.tsx`
- **Purpose:** Lightweight modal dialog with a title slot, body slot, and OK/Cancel actions.
- **Props:**
  ```ts
  interface DialogProps {
    title?: React.ReactNode;
    children?: React.ReactNode;
    style?: React.CSSProperties;
    onConfirm?: () => void;
    onCancel?: () => void;
  }
  ```
- **Theming tokens:** `--theme-background`, `--theme-border-subdued`, `--theme-border`, `--theme-text`
- **CLI primitive:** A bordered card plus a `buttonRow(button('ESC','cancel'), button('↵','ok'), innerW)`.
- **Used by:** `...` inside the "DIALOG" accordion in `app/page.tsx`.

## Divider

- **Path:** `components/Divider.tsx`
- **Purpose:** Horizontal rule with three styles: single, double, and gradient.
- **Props:**
  ```ts
  interface DividerProps extends React.HTMLAttributes {
    children?: React.ReactNode;
    type?: string | any;
    style?: any;
  }
  ```
- **Theming tokens:** `--theme-border`, `--theme-text`, `--theme-line-height-base`, `--font-size`
- **CLI primitive:** A `cardRow` of `'─'` glyphs (or `'═'` for double) at full inner width. The CLI framework has no dedicated divider helper.
- **Used by:** `` inside the "DIVIDERS" accordion in `app/page.tsx`.

## DOMSnake

- **Path:** `components/DOMSnake.tsx`
- **Purpose:** DOM-grid Snake mini-game (sibling of `CanvasSnake`) using CSS cells instead of canvas pixels.
- **Props:**
  ```ts
  interface SnakeGameProps {
    width?: number;
    height?: number;
    startSpeed?: number;
  }
  ```
- **Theming tokens:** `--theme-focused-foreground`, `--theme-text`
- **CLI primitive:** (React-only) Animation game.
- **Used by:** `` inside the "DOM SNAKE" accordion in `app/page.tsx`.

## Drawer

- **Path:** `components/Drawer.tsx`
- **Purpose:** Collapsible sidebar drawer with a single toggle button and an animated hide/show state.
- **Props:**
  ```ts
  interface DrawerProps extends Omit, 'defaultValue'> {
    children?: React.ReactNode;
    defaultValue?: boolean;
  }
  ```
- **Theming tokens:** `--theme-background-input`, `--theme-button-foreground`, `--theme-focused-foreground`, `--theme-text`, `--theme-line-height-base`, `--font-size`
- **CLI primitive:** (React-only) The CLI alt-screen is a single window; there is no drawer concept.
- **Used by:** `...` inside the "DRAWER" accordion in `app/page.tsx`.

## DropdownMenu

- **Path:** `components/DropdownMenu.tsx`
- **Purpose:** Floating list of action items with `role="menu"`, arrow-key navigation with focus wrapping, Enter/Space activation, and Escape to dismiss. Each item receives `role="menuitem"`.
- **Props:**
  ```ts
  interface DropdownMenuProps extends React.HTMLAttributes {
    onClose?: (event?: MouseEvent | TouchEvent | KeyboardEvent) => void;
    items?: DropdownMenuItemProps[];
  }
  ```
- **Theming tokens:** `--theme-background-modal-footer`, `--theme-border`, `--theme-line-height-base`, `--font-size`
- **CLI primitive:** Sacred CLI's `createApp({ interactive: { count, onSelect } })` lifecycle plus `cardSelectRow` is the closest equivalent.
- **Used by:** Wired through `DropdownMenuTrigger` inside the "DROPDOWN MENU" accordion in `app/page.tsx`.

## DropdownMenuTrigger

- **Path:** `components/DropdownMenuTrigger.tsx`
- **Purpose:** Wrapper that opens an associated `DropdownMenu` on click or hotkey, dismisses on outside click, and returns focus to the trigger element when the menu closes.
- **Props:**
  ```ts
  interface DropdownMenuTriggerProps {
    children: React.ReactElement>;
    items: any;
    hotkey?: string;
  }
  ```
- **Theming tokens:** `--z-index-page-dropdown-menus`
- **CLI primitive:** (React-only) Hover/click trigger interaction is browser-specific.
- **Used by:** `...` inside the "DROPDOWN MENU" accordion in `app/page.tsx`.

## Grid

- **Path:** `components/Grid.tsx`
- **Purpose:** Responsive multi-column grid container that wraps its children in a flexible grid track.
- **Props:**
  ```ts
  interface GridProps extends React.HTMLAttributes {
    children?: React.ReactNode;
  }
  ```
- **Theming tokens:** `--theme-line-height-base`, `--font-size`
- **CLI primitive:** Multiple `cardRow(formatRow(...), innerW)` calls — the CLI framework treats every layout as a single column, multiple rows.
- **Used by:** `...` wraps the navigation strip near the top of `app/page.tsx`.

## HoverComponentTrigger

- **Path:** `components/HoverComponentTrigger.tsx`
- **Purpose:** Wrapper that pops a tooltip or popover on hover/click with auto-positioning and outside-click dismissal.
- **Props:**
  ```ts
  interface HoverComponentTriggerProps {
    children: React.ReactElement>;
    text: string;
    component: 'popover' | 'tooltip';
  }
  ```
- **Theming tokens:** `--z-index-page-popover`, `--z-index-page-tooltips`
- **CLI primitive:** (React-only) Hover-driven UI is browser-specific.
- **Used by:** `` inside the "TOOLTIP" accordion in `app/page.tsx`.

## Indent

- **Path:** `components/Indent.tsx`
- **Purpose:** Wrapper that applies a left padding to its children for nested content blocks.
- **Props:**
  ```ts
  interface IndentProps extends React.HTMLAttributes {
    children?: React.ReactNode;
  }
  ```
- **Theming tokens:** (none)
- **CLI primitive:** Manual `' '.repeat(N)` prefix inside `cardRow`. The CLI framework leaves indentation up to the template.
- **Used by:** `...` inside the "AVATARS" accordion in `app/page.tsx`.

## Input

- **Path:** `components/Input.tsx`
- **Purpose:** Single-line text input with a custom caret glyph, password masking, and optional label.
- **Props:**
  ```ts
  type InputProps = React.InputHTMLAttributes & {
    caretChars?: string | any;
    label?: string | any;
    isBlink?: boolean;
  };
  ```
- **Theming tokens:** `--theme-background-input`, `--theme-background`, `--theme-border`, `--theme-focused-foreground`, `--theme-overlay`, `--theme-text`, `--theme-line-height-base`, `--font-size`
- **CLI primitive:** (React-only) The CLI templates capture keystrokes through `createApp({ onKey })` and compose their own input strings — sacred CLI ships no boxed input primitive.
- **Used by:** `` inside the "INPUT" accordion in `app/page.tsx`.

## ListItem

- **Path:** `components/ListItem.tsx`
- **Purpose:** Keyboard-focusable list row with Enter / arrow-key navigation between siblings.
- **Props:** _(untyped — accepts standard `
  • ` HTML attributes)_
- **Theming tokens:** `--theme-focused-foreground`
- **CLI primitive:** `cardRow` with manual prefix glyphs.
- **Used by:** Inside `Navigation` and `BreadCrumbs` examples in `app/page.tsx`.

## MatrixLoader

- **Path:** `components/MatrixLoader.tsx`
- **Purpose:** Matrix-rain effect rendered via pre/span grid with DOM diffing. Configurable direction and Greek/Katakana glyph mode.
- **Props:**
  ```ts
  interface MatrixLoaderProps {
    rows?: number;
    direction?: undefined | 'top-to-bottom' | 'left-to-right';
    mode?: undefined | 'greek' | 'katakana';
  }
  ```
- **Theming tokens:** `--theme-text`, `--font-size`, `--theme-line-height-base`
- **CLI primitive:** (React-only) Animation surface.
- **Used by:** `` inside the ModalMatrixModes modal triggered from `app/page.tsx`.

## Message

- **Path:** `components/Message.tsx`
- **Purpose:** Chat message bubble (left-tail) for outgoing user messages.
- **Props:** _(untyped — accepts an optional children prop)_
- **Theming tokens:** `--theme-border-subdued`, `--theme-border`, `--theme-line-height-base`, `--font-size`
- **CLI primitive:** A `cardRow` per wrapped line with no special styling.
- **Used by:** `...` inside `components/examples/MessagesInterface.tsx`.

## MessageViewer

- **Path:** `components/MessageViewer.tsx`
- **Purpose:** Chat message bubble (right-tail) for incoming messages from another participant.
- **Props:** _(untyped — accepts an optional children prop)_
- **Theming tokens:** `--theme-focused-foreground`, `--theme-line-height-base`, `--font-size`
- **CLI primitive:** Same as `Message` — a `cardRow` per wrapped line.
- **Used by:** `...` inside `components/examples/MessagesInterface.tsx`.

## ModalStack

- **Path:** `components/ModalStack.tsx`
- **Purpose:** Stacked modal overlay container that manages z-index ordering and backdrop blur.
- **Props:** _(no props)_
- **Theming tokens:** `--z-index-page-modals`
- **CLI primitive:** (React-only) The CLI alt-screen has a single layer.
- **Used by:** Mounted by `Providers` for any `ModalTrigger` in the kitchen sink.

## ModalTrigger

- **Path:** `components/ModalTrigger.tsx`
- **Purpose:** Injects an `onClick` into its child via `React.cloneElement` that opens a modal component, chaining with any existing `onClick` the child already has. Keyboard-accessible because the child's own `onKeyDown` handler (which calls `onClick`) fires the injected callback directly.
- **Props:**
  ```ts
  interface ModalTriggerProps {
    children: React.ReactElement<{ onClick?: React.MouseEventHandler }>;
    modal: React.ComponentType;
    modalProps?: Record;
  }
  ```
- **Theming tokens:** (none)
- **CLI primitive:** (React-only) See `ModalStack`.
- **Used by:** `` inside the "MODAL" accordion in `app/page.tsx`.

## Navigation

- **Path:** `components/Navigation.tsx`
- **Purpose:** Top navigation bar with logo, left/right slot rails, and a center children slot.
- **Props:**
  ```ts
  interface NavigationProps extends React.HTMLAttributes {
    children?: React.ReactNode;
    logoHref?: string;
    logoTarget?: React.HTMLAttributeAnchorTarget;
    onClickLogo?: React.MouseEventHandler;
    logo?: React.ReactNode;
    left?: React.ReactNode;
    right?: React.ReactNode;
  }
  ```
- **Theming tokens:** `--theme-border`, `--theme-focused-foreground`, `--theme-text`, `--font-size`
- **CLI primitive:** A `buttonRow(left, right, innerW)` plus a leading `cardRow` for the title.
- **Used by:** Top of the kitchen sink in `app/page.tsx` (search for `` inside the "NUMBER RANGE SLIDER" accordion in `app/page.tsx`.

## Popover

- **Path:** `components/Popover.tsx`
- **Purpose:** Generic floating panel container reused by `DropdownMenu` and `HoverComponentTrigger`.
- **Props:**
  ```ts
  interface PopoverProps extends React.HTMLAttributes {}
  ```
- **Theming tokens:** `--theme-border-subdued`, `--theme-border`, `--theme-line-height-base`, `--font-size`
- **CLI primitive:** (React-only) See `DropdownMenu`.
- **Used by:** Mounted by `HoverComponentTrigger` in the "POPOVER" accordion in `app/page.tsx`.

## Providers

- **Path:** `components/Providers.tsx`
- **Purpose:** Top-level context provider wrapping the app in `HotkeysProvider` and `ModalProvider`.
- **Props:**
  ```ts
  interface ProvidersProps {
    children: React.ReactNode;
  }
  ```
- **Theming tokens:** (none)
- **CLI primitive:** (React-only) Sacred CLI is a single process; there is no provider tree.
- **Used by:** `app/layout.tsx`.

## RadioButton

- **Path:** `components/RadioButton.tsx`
- **Purpose:** Custom-styled radio input with click + arrow-key selection inside a `RadioButtonGroup`.
- **Props:**
  ```ts
  interface RadioButtonProps {
    style?: React.CSSProperties;
    name: string;
    value: string;
    selected?: boolean;
    onSelect?: (value: string) => void;
    children?: React.ReactNode;
  }
  ```
- **Theming tokens:** `--theme-background`, `--theme-border-subdued`, `--theme-button-background`, `--theme-button-foreground`, `--theme-focused-foreground`, `--theme-text`, `--theme-line-height-base`, `--font-size`
- **CLI primitive:** `cardSelectRow(content, innerW, isSelected)` driven by `createApp({ interactive: { count, onSelect } })`.
- **Used by:** Inside `RadioButtonGroup` in the "RADIO BUTTON" accordion in `app/page.tsx`.

## RadioButtonGroup

- **Path:** `components/RadioButtonGroup.tsx`
- **Purpose:** Container that owns the selected value across a list of `RadioButton` siblings.
- **Props:**
  ```ts
  interface RadioButtonGroupProps {
    options: { value: string; label: string }[];
    defaultValue?: string;
  }
  ```
- **Theming tokens:** (none)
- **CLI primitive:** Same as `RadioButton` — `createApp` with `interactive: { count, onSelect, persist: true }`.
- **Used by:** `` in the "RADIO BUTTON" accordion in `app/page.tsx`.

## Row

- **Path:** `components/Row.tsx`
- **Purpose:** Block-level row container with focus styling.
- **Props:**
  ```ts
  type RowProps = React.HTMLAttributes & {
    children?: React.ReactNode;
  };
  ```
- **Theming tokens:** `--theme-focused-foreground`
- **CLI primitive:** A single `cardRow(content, innerW)`.
- **Used by:** `...` near the top of `app/page.tsx`.

## RowEllipsis

- **Path:** `components/RowEllipsis.tsx`
- **Purpose:** Row container with `text-overflow: ellipsis` for single-line truncation.
- **Props:**
  ```ts
  type RowEllipsisProps = React.HTMLAttributes & {
    children?: React.ReactNode;
  };
  ```
- **Theming tokens:** `--theme-focused-foreground`
- **CLI primitive:** `truncateVisible(line, innerW)` from `scripts/cli/lib/ansi.js`.
- **Used by:** `...` inside list-item rows in `app/page.tsx`.

## RowSpaceBetween

- **Path:** `components/RowSpaceBetween.tsx`
- **Purpose:** Flexbox row that pushes its first and last child to opposite ends.
- **Props:**
  ```ts
  type RowSpaceBetweenProps = React.HTMLAttributes & {
    children?: React.ReactNode;
  };
  ```
- **Theming tokens:** `--theme-focused-foreground`
- **CLI primitive:** `buttonRow(left, right, innerW)` in `scripts/cli/lib/button.js`.
- **Used by:** `EXITSELECT` in `components/examples/CLITemplate.tsx`, with the same shape repeated in `components/examples/InvoiceTemplate.tsx` (ESC EXIT / ↵ SUBMIT) and `components/examples/ResultsList.tsx` (ESC EXIT / ← PREV → NEXT).

## Select

- **Path:** `components/Select.tsx`
- **Purpose:** Custom dropdown select with keyboard navigation and styled option list.
- **Props:**
  ```ts
  interface SelectProps {
    name: string;
    options: string[];
    placeholder?: string;
    defaultValue?: string;
    onChange?: (selectedValue: string) => void;
  }
  ```
- **Theming tokens:** `--theme-background`, `--theme-border-subdued`, `--theme-border`, `--theme-button-foreground`, `--theme-focused-foreground`, `--theme-text`, `--theme-line-height-base`, `--font-family-mono`, `--font-size`, `--z-index-page-select`
- **CLI primitive:** `createApp({ interactive: { count, onSelect } })` plus `cardSelectRow`.
- **Used by:** `