# jarvis-react-ui

> Sharp, dark, HUD-style React 19 component library (JARVIS look: JetBrains Mono, glow instead of shadows): primitives, inputs, dialogs, toasts, tables, charts, a window/slot-grid system, a CSS and a Three.js orb, and built-in UI sound effects.

Version 0.5.0. Docs: https://joeyash.github.io/jarvis_ui_lib/

## Usage rules

- Install `jarvis-react-ui` with its peers `react` and `react-dom` (^19) and `lucide-react`. `three` is an optional peer, needed only for `ThreeOrb`.
- Import the stylesheet once at the app root: `import 'jarvis-react-ui/style.css';`. Tailwind is not required in the consuming project.
- Import components, hooks and types from the package root only: `import { Button, Panel } from 'jarvis-react-ui';`. Never deep-import from `jarvis-react-ui/dist/...`.
- `ThreeOrb`, `createOrb` and `OrbEngine` come from `jarvis-react-ui/orb` (separate entry so `three` stays out of the main bundle). `CssOrb` is in the main entry.
- Wrap the app once in `JarvisProvider` (UI sounds, toasts, `useJarvis()`). `useToast()` and `useJarvis()` throw outside of it; without a provider the other components work but stay silent.
- Give the page the dark surface: `body { background: var(--bg); color: var(--text); }`. Style with the design tokens (`var(--accent)`, ...), not hard-coded colors.
- Every component accepts `className`; components wrapping a native element accept its attributes and forward `ref`.
- Layout: use `Stack` (rows/columns) and `Grid` (columns) with token gaps (`xs`–`xl`); sizes via the project's own CSS classes, or Tailwind only if the project has Tailwind. The demos below use Tailwind utilities (`flex gap-3`, `w-[280px]`) for layout; without Tailwind, replace them with `Stack`, `Grid` or own CSS. Do not rely on utility classes from `style.css`: it contains only an internal subset that changes between releases.
- Windows built at runtime from JSON (e.g. by an assistant): `UiRenderer`, `useUiWindows` and `validateUiSpec` come from `jarvis-react-ui/generative`. A spec may only use the components and props of `UI_REGISTRY` (see the UiRenderer page); validate specs before opening them. The JSON Schema of a spec and Claude tool definitions ship as `jarvis-react-ui/ui-schema.json` and `jarvis-react-ui/ui-tools.json`.
- Use only the props listed in the API tables; do not invent props or variants. Helper types used by props (e.g. `TabItem`, `TableColumn<T>`) are documented under "Type" after each API table.

# Overview

## What's inside

- **Primitives**: buttons, inputs, switches, pills, metrics, progress bars, sparklines, panels and
  decorative HUD layers such as corner brackets, scanlines and light traces.
- **Compositions**: navigation lists, tabs, tables, code blocks, callouts, a HUD shell, a status
  dock and the `WindowManager`.
- **Window system**: draggable, resizable windows on a 9-slot snap grid, with the hooks to build
  your own.
- **Orbs**: `CssOrb` with five states in the main entry, `ThreeOrb` in `jarvis-react-ui/orb`.
- **Sound**: an audio engine and React hooks that give every interactive component hover and click
  sounds.

Start with [Installation](https://joeyash.github.io/jarvis_ui_lib/getting-started/installation.md), then build your first screen in
[Usage](https://joeyash.github.io/jarvis_ui_lib/getting-started/usage.md).

# Installation

Install the package and its peer dependencies, import the stylesheet once, and you are ready to
render your first component.

## Install the package

```bash
npm i jarvis-react-ui
```

The library has three peer dependencies. Install them if your project does not have them yet:

```bash
npm i react react-dom lucide-react
```

| Package              | Version  | Why                                                                   |
| -------------------- | -------- | --------------------------------------------------------------------- |
| `react`, `react-dom` | `^19`    | The components use React 19 APIs.                                     |
| `lucide-react`       | `^1`     | Icons used inside components and accepted by `Icon` and `IconButton`. |
| `three`              | optional | Only for `ThreeOrb` from `jarvis-react-ui/orb`.                       |

## Import the stylesheet

Import the compiled stylesheet once, at the root of your app:

```tsx
// main.tsx
import 'jarvis-react-ui/style.css';
```

It contains the design tokens (CSS custom properties), the compiled utility layer the components
use, keyframes and all component styles. It also loads JetBrains Mono from Google Fonts and includes
Tailwind's preflight reset. You do **not** need Tailwind in your project.

> The preflight reset normalizes margins, headings and form elements. Import the stylesheet before
> your own styles so your rules win.

## Package entry points

| Import                      | Contents                                                   |
| --------------------------- | ---------------------------------------------------------- |
| `jarvis-react-ui`           | All components, hooks, the audio API, utilities and types. |
| `jarvis-react-ui/orb`       | `ThreeOrb`, `createOrb` and `OrbEngine` (needs `three`).   |
| `jarvis-react-ui/style.css` | The stylesheet.                                            |
| `jarvis-react-ui/sounds/*`  | The bundled sound files.                                   |

The package is ESM only and ships TypeScript declarations. The Three.js orb lives in its own entry,
so `three` never ends up in your bundle unless you import it.

## Upgrading

After `npm install jarvis-react-ui@<new version>`, restart the Vite dev server with
`npm run dev -- --force` (or delete `node_modules/.vite`). npm writes package files with fixed
timestamps, so Vite's dependency cache may keep serving the old `style.css` or JavaScript
otherwise.

## Next steps

- Build a first screen in [Usage](https://joeyash.github.io/jarvis_ui_lib/getting-started/usage.md).
- Turn on sounds in [Sound effects](https://joeyash.github.io/jarvis_ui_lib/getting-started/sound.md).
- Change the colors in [Theming](https://joeyash.github.io/jarvis_ui_lib/customization/theming.md).

# Usage

Components are plain React components with typed props. Compose them like any other UI kit; the
HUD look comes from the shared design tokens.

## Wrap your app

Mount [JarvisProvider](https://joeyash.github.io/jarvis_ui_lib/components/jarvis-provider.md) once at the root. It sets up UI sounds, toasts
and the `useJarvis()` controls:

```tsx
// main.tsx
import 'jarvis-react-ui/style.css';
import { createRoot } from 'react-dom/client';
import { JarvisProvider } from 'jarvis-react-ui';
import { App } from './App';

createRoot(document.getElementById('root') as HTMLElement).render(
    <JarvisProvider>
        <App />
    </JarvisProvider>,
);
```

## A first panel

```tsx
import { Button, Metric, Panel, Pill, useToast } from 'jarvis-react-ui';

export function App() {
    const { toast } = useToast();
    return (
        <Panel title="System">
            <Metric value={42} unit="%" />
            <Pill variant="ok">online</Pill>
            <Button onClick={() => toast({ variant: 'success', title: 'Diagnostics passed' })}>
                Run diagnostics
            </Button>
        </Panel>
    );
}
```

## Dark background

The components are designed for the dark JARVIS background. Give your page the background token so
everything sits on the right surface:

```css
body {
    background: var(--bg);
    color: var(--text);
}
```

For the full HUD look, add the decorative layers `GridBackground`, `Scanlines` and
`ViewportCorners`, or the complete `HUDShell` frame.

## Layout

The components bring their own styles; the layout around them is yours. Size and place them with
`className` and your own CSS (or Tailwind, if your project uses it):

```css
.reactor-panel {
    width: 320px;
    height: 220px;
}
```

For rows, columns and grids use [Stack](https://joeyash.github.io/jarvis_ui_lib/components/stack.md) and [Grid](https://joeyash.github.io/jarvis_ui_lib/components/grid.md): they space
their children with the design tokens and need no Tailwind.

```tsx
<Stack direction="row" align="center" gap="sm">
    <Pill variant="ok">online</Pill>
    <Button>Run diagnostics</Button>
</Stack>
```

The demos on these pages lay themselves out with Tailwind utilities such as `flex gap-3`. Without
Tailwind in your project, replace those with `Stack`, `Grid` or your own CSS: the utility classes
inside `style.css` are an internal subset and not meant for your markup (see
[Tailwind](https://joeyash.github.io/jarvis_ui_lib/customization/tailwind.md)).

## Props and refs

- Every component accepts `className`, merged onto its root element.
- Components that wrap a native element (`Button`, `IconButton`, `Input`, `Link`, `Switch`) accept
  that element's attributes (`onClick`, `disabled`, `aria-*`, ...) and forward their `ref`.
- Controlled and uncontrolled modes follow React conventions: `value` / `defaultValue` with
  `onValueChange` (Tabs), `checked` / `defaultChecked` with `onCheckedChange` (Switch).

Each component page ends with an **API** table generated from the TypeScript types, so it always
matches the source.

## Client-side routing

Links and navigation entries render real `<a>` elements. To use them with a router, prevent the
default navigation and call your router instead:

```tsx
import { useNavigate } from 'react-router';
import { NavList } from 'jarvis-react-ui';

export function Sidebar() {
    const navigate = useNavigate();
    return (
        <NavList
            groups={groups}
            onItemClick={(item, event) => {
                event.preventDefault();
                navigate(item.href);
            }}
        />
    );
}
```

This documentation site is built exactly like that, using only `jarvis-react-ui` components.

## TypeScript

All props, variants and helper types are exported next to their component:

```ts
import type { ButtonProps, ButtonVariant, TableColumn } from 'jarvis-react-ui';
```

# Sound effects

Interactive components play short UI sounds (hover, click, drag, boot, ...) through a React
context. Without a provider they stay silent, so audio is strictly opt-in.

## Enable sound

[JarvisProvider](https://joeyash.github.io/jarvis_ui_lib/components/jarvis-provider.md) turns sound on for the whole app. Sound is on by
default; `sfx={false}` starts muted, and `useJarvis()` returns `{ isMuted, toggleMute }` for a mute
switch. The user's choice is stored in `localStorage`, so it survives reloads. Try the **SFX** switch
in the header of this site.

```tsx
import { JarvisProvider } from 'jarvis-react-ui';

<JarvisProvider sfx={false}>
    <App />
</JarvisProvider>;
```

### Manual setup

Without `JarvisProvider`, mount the audio engine yourself and pass it to `SfxProvider`:

```tsx
import type { ReactNode } from 'react';
import { SfxProvider, useAudioEngine } from 'jarvis-react-ui';

export function SoundRoot({ children }: { children: ReactNode }) {
    const { playOneShot, play, stop } = useAudioEngine('idle', true, false, {
        initialMuted: false,
    });
    return (
        <SfxProvider playOneShot={playOneShot} play={play} stop={stop}>
            {children}
        </SfxProvider>
    );
}
```

> Browsers only start audio after a user gesture. The first sounds play after the first click or key
> press on the page.

## Serve the sound files

The sound files ship inside the package under `public/sounds`. The engine loads them from a base URL
that defaults to `/sounds/` on your site.

**Option 1: copy them into your static folder** (no configuration):

```bash
cp -r node_modules/jarvis-react-ui/public/sounds public/sounds
```

**Option 2: point `soundBaseUrl` at your own path or a CDN** (pin the version in the URL):

```tsx
const { playOneShot, play, stop } = useAudioEngine('idle', true, false, {
    soundBaseUrl: 'https://cdn.jsdelivr.net/npm/jarvis-react-ui@0.1.0/public/sounds/',
});
```

The value may be relative or absolute; a trailing slash is added if missing. Query strings and
hashes are rejected. The engine is a process-wide singleton, so the last applied URL wins. A CDN must
send CORS headers (unpkg and jsDelivr do). Missing files are logged and skipped; nothing throws.

## Sounds in your own components

| Hook                    | Use                                                                                            |
| ----------------------- | ---------------------------------------------------------------------------------------------- |
| `useClickSfx(onClick)`  | Wraps a click handler: plays `click`, then calls yours.                                        |
| `useHoverSfx('button')` | Returns an `onMouseEnter` handler that plays a throttled hover sound (`'panel'` for surfaces). |
| `useSfx()`              | `{ playOneShot, play, stop }` for any other sound event.                                       |

```tsx
import { useClickSfx, useHoverSfx } from 'jarvis-react-ui';

export function ScanButton({ onScan }: { onScan: () => void }) {
    const onMouseEnter = useHoverSfx('button');
    const onClick = useClickSfx(onScan);
    return (
        <button type="button" onMouseEnter={onMouseEnter} onClick={onClick} data-sfx-hover="button">
            Scan
        </button>
    );
}
```

Mark buttons with `data-sfx-hover="button"` so the hover sound of a surrounding panel does not play
on top of the button's own.

# JarvisProvider

The root provider of a JARVIS app. It starts the audio engine for UI sounds, provides toasts and
exposes app-level controls through `useJarvis()`. Wrap your app in it once.

```ts
import { JarvisProvider } from 'jarvis-react-ui';
```

## Setup

```tsx
import 'jarvis-react-ui/style.css';
import { createRoot } from 'react-dom/client';
import { JarvisProvider } from 'jarvis-react-ui';
import { App } from './App';

createRoot(document.getElementById('root') as HTMLElement).render(
    <JarvisProvider>
        <App />
    </JarvisProvider>,
);
```

Everything below it can use [useToast](https://joeyash.github.io/jarvis_ui_lib/components/toast.md), `useJarvis()` and the sound hooks, and
all interactive components play their sounds.

```tsx
import { Button, Panel, useJarvis, useToast } from 'jarvis-react-ui';

export default function Everything() {
    const { isMuted } = useJarvis();
    const { toast } = useToast();

    return (
        <Panel title="SYSTEM" className="w-[280px]">
            <div className="flex flex-col items-start gap-3">
                <span className="text-[11px] text-text-secondary">
                    Sound {isMuted ? 'off' : 'on'} · toasts ready
                </span>
                <Button
                    variant="primary"
                    onClick={() =>
                        toast({ variant: 'success', title: 'Diagnostics passed', duration: 3000 })
                    }
                >
                    Run diagnostics
                </Button>
            </div>
        </Panel>
    );
}
```

## Sound

Sound is **on by default**. Browsers only start audio after the first click or key press.

- `sfx={false}` starts muted. Users can still switch sound on, e.g. with a toggle bound to
  `useJarvis()`.
- `useJarvis()` returns `{ isMuted, toggleMute }`. The user's choice is stored in `localStorage` and
  wins over the `sfx` prop on the next visit.
- `soundBaseUrl` points the engine at your copy of the sound files or a CDN, see
  [Sound effects](https://joeyash.github.io/jarvis_ui_lib/getting-started/sound.md).

```tsx
import { Button, Pill, Switch, useJarvis } from 'jarvis-react-ui';

export default function MuteToggle() {
    const { isMuted, toggleMute } = useJarvis();

    return (
        <>
            <Switch label="UI sound" checked={!isMuted} onCheckedChange={toggleMute} />
            <Pill variant={isMuted ? 'default' : 'info'}>{isMuted ? 'muted' : 'live'}</Pill>
            <Button>Hover and click me</Button>
        </>
    );
}
```

```tsx
<JarvisProvider sfx={false} soundBaseUrl="/assets/sounds/">
    <App />
</JarvisProvider>
```

## Assistant state

`orbState`, `connected` and `heartbeat` feed the audio engine's state sounds (ambient loop, scan
while listening, offline alerts). Pass your assistant's current state to keep the soundscape in sync
with the orb.

## Toasts

`toastPlacement`, `toastMax` and `toastDuration` configure the built-in
[ToastProvider](https://joeyash.github.io/jarvis_ui_lib/components/toast-provider.md).

## Without JarvisProvider

The building blocks stay available on their own: `SfxProvider` with `useAudioEngine` for sound and
`ToastProvider` for toasts.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  | Your app. |
| `connected` | `boolean` | `true` | Connection state; `false` plays the disconnect/offline sounds. |
| `heartbeat` | `boolean` | `false` | Plays a heartbeat loop while idle. |
| `orbState` | `'idle' \| 'listening' \| 'thinking' \| 'speaking' \| 'follow_up' \| 'working'` | `'idle'` | Assistant state driving the ambient/state sounds of the audio engine. |
| `sfx` | `boolean` | `true` | Whether UI sounds start enabled. `false` starts muted; `useJarvis().toggleMute()` can still switch them on. A preference the user set earlier (stored in `localStorage`) wins. |
| `soundBaseUrl` | `string` | `'/sounds/'` | Where the sound files are served from, e.g. a CDN URL. |
| `toastDuration` | `number` | `5000` | Default toast lifetime in ms. |
| `toastMax` | `number` | `3` | Maximum number of toasts shown at once. |
| `toastPlacement` | `'bottom-right' \| 'top-right' \| 'bottom-center' \| 'top-center'` | `'bottom-right'` | Corner or edge where toasts appear. |

# Using with AI

The docs are also published as plain Markdown for AI coding assistants, so they use the real
props and imports instead of guessing. The same files ship in the npm package and always match
the installed version.

## On the web

The docs site follows the [llms.txt](https://llmstxt.org) convention:

| File                                                                      | Contents                                                                        |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| [`/llms.txt`](https://joeyash.github.io/jarvis_ui_lib/llms.txt)           | Usage rules and a link to every page, with a one-line summary.                  |
| [`/llms-full.txt`](https://joeyash.github.io/jarvis_ui_lib/llms-full.txt) | Every page in one file, with the demo code and the API tables.                  |
| `/<page>.md`                                                              | One page as Markdown, e.g. `/components/button.md` for this site's Button page. |

Point a chat assistant at `llms-full.txt`, or at the `.md` pages it needs.

## In the package

The package contains the same content for the version you installed:

| File                                              | Contents                                                                                  |
| ------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| `node_modules/jarvis-react-ui/dist/llms.txt`      | Usage rules and the page index.                                                           |
| `node_modules/jarvis-react-ui/dist/llms-full.txt` | All pages with demo code and API tables.                                                  |
| `node_modules/jarvis-react-ui/dist/api.json`      | Every public component: entry point, props (type, default, description) and demo sources. |

They are also exported as `jarvis-react-ui/llms.txt`, `jarvis-react-ui/llms-full.txt` and
`jarvis-react-ui/api.json`, so tools can resolve them with `require.resolve`.

## Tell your assistant

Coding agents read project instructions such as `CLAUDE.md`, `AGENTS.md` or `.cursorrules`. Add a
short note so they load the docs before writing UI code:

```md
## UI components

This app uses `jarvis-react-ui`. Before building or changing UI, read
`node_modules/jarvis-react-ui/dist/llms-full.txt` and use only the components, props and imports
documented there.
```

`llms-full.txt` is large. Agents that search files can read `api.json` or grep `llms-full.txt` for
the component they need instead of loading all of it.

## Let an assistant build windows

The files above help assistants that **write code** with the library. To let a model **build UI at
runtime**, for example a voice assistant that opens a video window or a volume control, use the
generative entry: the model sends JSON specs through tools, and
[UiRenderer](https://joeyash.github.io/jarvis_ui_lib/components/ui-renderer.md) renders them with library components. The package ships the
JSON Schema (`jarvis-react-ui/ui-schema.json`) and ready-made tool definitions
(`jarvis-react-ui/ui-tools.json`); see [Connecting an assistant](https://joeyash.github.io/jarvis_ui_lib/generative/assistant.md).

# Theming

Every color, glow, radius, spacing step and timing is a CSS custom property. Components read
only those tokens, so overriding a few variables re-themes the whole library at runtime.

## Theme the whole app

Override the variables on `:root`, after importing the stylesheet:

```css
:root {
    --accent: #e8a84c;
    --accent-bright: #ffc76e;
    --accent-dim: #a1702d;
    --border-bright: #4f3d2a;

    /* glows: the component stylesheets read --glow*, the glow utilities read --shadow-glow* */
    --glow: 0 0 8px #e8a84caa;
    --glow-strong: 0 0 20px #e8a84ccc, 0 0 40px #e8a84c44;
    --shadow-glow: 0 0 8px #e8a84caa;
    --shadow-glow-strong: 0 0 20px #e8a84ccc, 0 0 40px #e8a84c44;
}
```

You can also change them from JavaScript, e.g. `document.documentElement.style.setProperty('--accent', color)`,
to switch themes at runtime.

## Theme one area

The utility colors are aliases declared on `:root` (`--color-accent: var(--accent)`), so they are
resolved there. To re-theme only a sub-tree, set the alias next to the token:

```css
.my-area {
    --accent: #e8a84c;
    --color-accent: #e8a84c;
}
```

## Playground

Pick a preset. It is applied to the preview only, and the CSS below it is the complete scoped
override, including the `--color-*` and `--shadow-glow*` aliases.

## What to override

- **Accent**: `--accent`, `--accent-bright`, `--accent-dim` drive buttons, focus rings, active
  states, the orb and most chrome.
- **Glow**: `--glow` / `--glow-strong` (component stylesheets) and `--shadow-glow` /
  `--shadow-glow-strong` (glow utilities) hold literal colors, so override them together with the
  accent.
- **Surfaces**: `--bg`, `--surface`, `--surface-raised`, `--border`, `--border-bright`.
- **Text**: `--text`, `--text-secondary`, `--text-muted`.
- **Status**: `--success`, `--warning`, `--error`.

The full list with current values is on [Design tokens](https://joeyash.github.io/jarvis_ui_lib/customization/tokens.md).

## Design rules

The look depends on a few rules that the tokens alone do not enforce. Keep them when you build your
own components next to the library:

- Sharp edges: radius 2px by default, never more than 4px.
- Glow instead of drop shadows.
- JetBrains Mono everywhere, uppercase labels with letter spacing.
- Dark only. There is no light theme.

# Design tokens

The tokens live in one stylesheet as CSS custom properties on `:root`. The tables below are read
from that file at build time, so they always match the installed version.

Use them in your own CSS with `var(--name)`. To change them, see [Theming](https://joeyash.github.io/jarvis_ui_lib/customization/theming.md).

### Core palette

| Token | Value | Note |
| --- | --- | --- |
| `--bg` | `#050508` |  |
| `--surface` | `#0d0d14` |  |
| `--surface-raised` | `#12121c` |  |
| `--border` | `#1a1a2e` |  |
| `--border-bright` | `#2a3d4f` |  |

### Blue accent spectrum

| Token | Value | Note |
| --- | --- | --- |
| `--accent` | `#4ca8e8` | orb idle, primary |
| `--accent-bright` | `#6ec4ff` | thinking, hover |
| `--accent-speak` | `#5ab8f0` | speaking |
| `--accent-dim` | `#2d6aa1` | inactive state |

### Text

| Token | Value | Note |
| --- | --- | --- |
| `--text` | `#e8f4ff` |  |
| `--text-secondary` | `#6b8fa8` |  |
| `--text-muted` | `#2a3d4f` |  |

### Semantic

| Token | Value | Note |
| --- | --- | --- |
| `--warning` | `#e8b24c` |  |
| `--error` | `#e85a5a` |  |
| `--success` | `#4ce8a8` |  |

### Glow system

| Token | Value | Note |
| --- | --- | --- |
| `--glow` | `0 0 8px #4ca8e8aa` |  |
| `--glow-strong` | `0 0 20px #4ca8e8cc, 0 0 40px #4ca8e844` |  |
| `--glow-inner` | `inset 0 0 12px #4ca8e822` |  |
| `--glow-warn` | `0 0 8px #e8b24caa` |  |
| `--glow-error` | `0 0 8px #e85a5aaa` |  |

### Panel tint

| Token | Value | Note |
| --- | --- | --- |
| `--panel-bg` | `rgba(13, 13, 20, 0.75)` |  |
| `--panel-blur` | `blur(12px)` |  |
| `--panel-opacity` | `1` |  |

### Type

| Token | Value | Note |
| --- | --- | --- |
| `--font` | `'JetBrains Mono', ui-monospace, Menlo, monospace` |  |

### Radii — NEVER exceed these

| Token | Value | Note |
| --- | --- | --- |
| `--r-0` | `0` |  |
| `--r-1` | `2px` | default |
| `--r-2` | `4px` | maximum allowed |

### Spacing

| Token | Value | Note |
| --- | --- | --- |
| `--s-1` | `4px` |  |
| `--s-2` | `8px` |  |
| `--s-3` | `12px` |  |
| `--s-4` | `16px` |  |
| `--s-5` | `24px` |  |
| `--s-6` | `32px` |  |
| `--s-7` | `48px` |  |

### Elevation as z-layers

| Token | Value | Note |
| --- | --- | --- |
| `--z-orb` | `0` |  |
| `--z-panel` | `10` |  |
| `--z-status` | `20` |  |
| `--z-topbar` | `30` |  |
| `--z-dev` | `40` |  |
| `--z-modal` | `50` |  |

### Motion

| Token | Value | Note |
| --- | --- | --- |
| `--ease` | `cubic-bezier(0.4, 0, 0.2, 1)` |  |
| `--dur-fast` | `120ms` |  |
| `--dur-base` | `200ms` |  |
| `--dur-slow` | `300ms` |  |
| `--dur-ambient` | `1400ms` |  |

# Tailwind

The library is styled with Tailwind v4 internally, but ships compiled CSS. You do not need
Tailwind. If your project uses it, you can map the same tokens into your own theme.

## Without Tailwind

Nothing to do. `jarvis-react-ui/style.css` contains everything the components need. Write your own
styles with the CSS variables:

```css
.my-card {
    background: var(--surface);
    border: 1px solid var(--border);
    color: var(--text-secondary);
}
```

> **Warning: Don't use the utility classes without Tailwind**
>
> The stylesheet also contains some Tailwind utility classes (`flex`, `h-[120px]`, ...), but only
> the ones the components happen to use internally. They are not part of the public API: most
> utilities are missing, and the set changes between releases. Without Tailwind in your project,
> do not put utility classes in your own markup. Use [Stack](https://joeyash.github.io/jarvis_ui_lib/components/stack.md) and
> [Grid](https://joeyash.github.io/jarvis_ui_lib/components/grid.md) for layout and your own CSS classes with the tokens, as above.

The docs demos use Tailwind utilities for their layout (`flex gap-3`, `w-[280px]`, ...). Without
Tailwind, replace them with `Stack`, `Grid` or your own CSS when you copy a demo; the component props
stay the same.

## With Tailwind v4

Map the tokens in your `@theme` block to get utilities like `bg-surface`, `text-accent` or
`border-border` that follow runtime overrides:

```css
@import 'tailwindcss';

@theme {
    --color-bg: var(--bg);
    --color-surface: var(--surface);
    --color-border: var(--border);
    --color-accent: var(--accent);
    --color-accent-bright: var(--accent-bright);
    --color-text: var(--text);
    --color-text-secondary: var(--text-secondary);
    --font-mono: 'JetBrains Mono', ui-monospace, Menlo, monospace;
}
```

Import `jarvis-react-ui/style.css` before your Tailwind entry. Both stylesheets contain the preflight
reset; that is harmless.

## What follows runtime overrides

| Kind                                  | Follows overrides    | Why                                                                                                                |
| ------------------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------ |
| Colors (`bg-*`, `text-*`, `border-*`) | Yes                  | The theme colors point at the CSS variables (set on `:root`, or set the `--color-*` alias on a sub-tree).          |
| Glow (`shadow-glow*`)                 | Via `--shadow-glow*` | The utilities read `--shadow-glow*`, not `--glow*`; override both.                                                 |
| Spacing, z-index, durations           | No                   | Compiled as literal values; use the `--s-*`, `--z-*`, `--dur-*` variables directly where you need runtime control. |
| Radius                                | Fixed                | The scale is capped at 2px and 4px by design.                                                                      |

# Stack

Lays out its children in a column or a row with spacing from the design tokens. It covers most
layout needs without Tailwind, and it is the layout building block for generated windows.

```ts
import { Stack } from 'jarvis-react-ui';
```

## Column

By default the children stack top to bottom and stretch to the full width. `gap` takes a spacing
step: `xs` (4px), `sm` (8px), `md` (12px, the default), `lg` (24px), `xl` (32px) or `none`. The
steps read the `--s-*` tokens, so they follow a theme.

```tsx
import { Button, Label, Metric, Stack } from 'jarvis-react-ui';

export default function Column() {
    return (
        <Stack gap="sm">
            <Label>Reactor output</Label>
            <Metric value={87} unit="%" />
            <Button variant="primary">Run diagnostics</Button>
        </Stack>
    );
}
```

## Row

`direction="row"` lays the children out left to right. `align` sets the cross-axis alignment,
`justify` the distribution along the row, and `wrap` lets them flow onto further lines. Stacks nest.

```tsx
import { Button, Pill, Stack } from 'jarvis-react-ui';

export default function Row() {
    return (
        <Stack direction="row" align="center" justify="between" gap="md" wrap className="w-full">
            <Stack direction="row" align="center" gap="xs">
                <Pill variant="ok">online</Pill>
                <Pill>3 tasks</Pill>
            </Stack>
            <Stack direction="row" gap="sm">
                <Button size="sm">Cancel</Button>
                <Button size="sm" variant="primary">
                    Engage
                </Button>
            </Stack>
        </Stack>
    );
}
```

## Accessibility

Stack renders a plain `<div>` and adds no semantics. Pass `role` or `aria-*` attributes when the group
needs them; they reach the root element, and so does the `ref`.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `'start' \| 'center' \| 'end' \| 'stretch' \| 'baseline'` | `'stretch'` | Alignment across the direction (`align-items`). |
| `children` | `ReactNode` |  | Content to lay out. |
| `className` | `string` |  | Additional class names for the root `<div>`. |
| `direction` | `'column' \| 'row'` | `'column'` | Lays the children out in a column (top to bottom) or a row (left to right). |
| `gap` | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Space between the children. |
| `justify` | `'start' \| 'center' \| 'end' \| 'between' \| 'around'` | `'start'` | Distribution along the direction (`justify-content`). |
| `wrap` | `boolean` | `false` | Lets the children wrap onto further lines. |

Also accepts inherited props from `HTMLAttributes` (54), `AriaAttributes` (53), `DOMAttributes` (169), `RefAttributes` (1), `Attributes` (1).

# Grid

Lays out its children in equal columns with spacing from the design tokens: a fixed number of
columns, or as many as fit.

```ts
import { Grid } from 'jarvis-react-ui';
```

## Fixed columns

`columns` takes 1 to 6 equal columns. `gap` uses the same steps as [Stack](https://joeyash.github.io/jarvis_ui_lib/components/stack.md).

```tsx
import { Grid, Label, Metric, Stack } from 'jarvis-react-ui';

const READINGS = [
    { label: 'CPU', value: 42 },
    { label: 'GPU', value: 67 },
    { label: 'RAM', value: 58 },
];

export default function Columns() {
    return (
        <Grid columns={3} gap="lg" className="w-full">
            {READINGS.map((r) => (
                <Stack key={r.label} gap="xs">
                    <Label>{r.label}</Label>
                    <Metric value={r.value} unit="%" />
                </Stack>
            ))}
        </Grid>
    );
}
```

## Auto-fit

With `columns="auto"` (the default) the grid fits as many columns of at least `minColumnWidth`
pixels as the width allows, and reflows when it changes, e.g. when a window is resized. On narrower
containers a column never gets wider than the container. Like any grid, it fills the width of a block
container; inside a flex container (such as a row `Stack`) give it a width.

```tsx
import { GlassCard, Grid } from 'jarvis-react-ui';

const SYSTEMS = ['Radar', 'Comms', 'Shields', 'Thrusters', 'Life support', 'Navigation'];

export default function Auto() {
    return (
        <Grid minColumnWidth={140} gap="sm" className="w-full">
            {SYSTEMS.map((name) => (
                <GlassCard key={name} title={name}>
                    nominal
                </GlassCard>
            ))}
        </Grid>
    );
}
```

## Accessibility

Grid renders a plain `<div>` with `display: grid` and adds no semantics. The reading order is the
order of the children.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `align` | `'start' \| 'center' \| 'end' \| 'stretch'` | `'stretch'` | Vertical alignment of the cells within their row. |
| `children` | `ReactNode` |  | Cells, one per child. |
| `className` | `string` |  | Additional class names for the root `<div>`. |
| `columns` | `1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 'auto'` | `'auto'` | Number of equal columns, or `auto` for as many columns of `minColumnWidth` as fit. |
| `gap` | `'none' \| 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'md'` | Space between rows and columns (`--s-*` tokens). |
| `minColumnWidth` | `number` | `160` | Minimum column width in px for `columns="auto"`. |

Also accepts inherited props from `HTMLAttributes` (54), `AriaAttributes` (53), `DOMAttributes` (169), `RefAttributes` (1), `Attributes` (1).

# Button

Buttons trigger an action. They come in four variants, two sizes, and play the hover and click
sounds of the JARVIS sound set.

```ts
import { Button } from 'jarvis-react-ui';
```

## Variants

Use `primary` for the main action of a view, `secondary` (the default) for regular actions, `ghost`
for low-emphasis actions and `danger` for destructive ones.

```tsx
import { Button } from 'jarvis-react-ui';

export default function Variants() {
    return (
        <>
            <Button variant="primary">Engage</Button>
            <Button>Standby</Button>
            <Button variant="ghost">Details</Button>
            <Button variant="danger">Abort</Button>
        </>
    );
}
```

## Sizes

```tsx
import { Button } from 'jarvis-react-ui';

export default function Sizes() {
    return (
        <>
            <Button size="sm">Small</Button>
            <Button size="md">Medium</Button>
        </>
    );
}
```

## Disabled

A disabled button is dimmed, cannot be focused by click and does not fire `onClick`.

```tsx
import { Button } from 'jarvis-react-ui';

export default function Disabled() {
    return (
        <>
            <Button variant="primary" disabled>
                Engage
            </Button>
            <Button disabled>Standby</Button>
        </>
    );
}
```

## With an icon

Put an icon from `lucide-react` next to the label. Mark it `aria-hidden` because the label already
names the action. For icon-only buttons use [IconButton](https://joeyash.github.io/jarvis_ui_lib/components/icon-button.md).

```tsx
import { Power, Radar } from 'lucide-react';
import { Button } from 'jarvis-react-ui';

export default function WithIcon() {
    return (
        <>
            <Button variant="primary">
                <span className="inline-flex items-center gap-2">
                    <Power size={12} aria-hidden="true" /> Boot
                </span>
            </Button>
            <Button>
                <span className="inline-flex items-center gap-2">
                    <Radar size={12} aria-hidden="true" /> Scan
                </span>
            </Button>
        </>
    );
}
```

## Sound

Hovering plays `hover_button` and clicking plays `click` through the nearest `SfxProvider`. Without a
provider the button stays silent. See [Sound effects](https://joeyash.github.io/jarvis_ui_lib/getting-started/sound.md).

## Accessibility

- Renders a native `<button>`, so keyboard and screen reader support come for free.
- The focus ring is visible on keyboard focus only (`focus-visible`).
- The label is the accessible name; keep it short and verb-first.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  | Button label, optionally combined with an icon. |
| `className` | `string` |  | Additional class names for the `<button>` element. |
| `size` | `'sm' \| 'md'` | `'md'` | Padding and font size. |
| `variant` | `'primary' \| 'secondary' \| 'ghost' \| 'danger'` | `'secondary'` | Visual emphasis: `primary` (filled accent), `secondary` (accent outline), `ghost` (muted outline) or `danger` (error outline that fills on hover). |

Also accepts inherited props from `ButtonHTMLAttributes` (10), `HTMLAttributes` (54), `AriaAttributes` (53), `DOMAttributes` (169), `RefAttributes` (1), `Attributes` (1).

# IconButton

A square button that shows only a `lucide-react` icon. Use it for compact toolbar actions; the
required `label` gives it an accessible name.

```ts
import { IconButton } from 'jarvis-react-ui';
```

## Variants

`ghost` (the default) is borderless until hovered and suits dense toolbars. `secondary`, `primary`
and `danger` mirror the [Button](https://joeyash.github.io/jarvis_ui_lib/components/button.md) variants.

```tsx
import { Copy, Download, Power, Trash2 } from 'lucide-react';
import { IconButton } from 'jarvis-react-ui';

export default function Variants() {
    return (
        <>
            <IconButton icon={Copy} label="Copy" />
            <IconButton icon={Download} label="Download" variant="secondary" />
            <IconButton icon={Power} label="Power on" variant="primary" />
            <IconButton icon={Trash2} label="Delete" variant="danger" />
        </>
    );
}
```

## Sizes

`sm` is a 24px square with a 12px icon, `md` (the default) is 30px with a 14px icon.

```tsx
import { Settings } from 'lucide-react';
import { IconButton } from 'jarvis-react-ui';

export default function Sizes() {
    return (
        <>
            <IconButton icon={Settings} label="Settings" size="sm" variant="secondary" />
            <IconButton icon={Settings} label="Settings" size="md" variant="secondary" />
        </>
    );
}
```

## Toggle

Pass `pressed` to turn the button into a toggle. It highlights the button and sets `aria-pressed`.
Keep the `label` constant (for example "Mute") and let `pressed` carry the state.

```tsx
import { useState } from 'react';
import { Volume2, VolumeX } from 'lucide-react';
import { IconButton } from 'jarvis-react-ui';

export default function Toggle() {
    const [muted, setMuted] = useState(false);

    return (
        <IconButton
            icon={muted ? VolumeX : Volume2}
            label="Mute"
            pressed={muted}
            onClick={() => setMuted((m) => !m)}
        />
    );
}
```

## Disabled

```tsx
import { RefreshCw } from 'lucide-react';
import { IconButton } from 'jarvis-react-ui';

export default function Disabled() {
    return (
        <>
            <IconButton icon={RefreshCw} label="Refresh" disabled />
            <IconButton icon={RefreshCw} label="Refresh" variant="secondary" disabled />
        </>
    );
}
```

## With a tooltip

The label is only announced to assistive technology. Wrap the button in a
[Tooltip](https://joeyash.github.io/jarvis_ui_lib/components/tooltip.md) to show a hint to sighted users as well.

## Sound

Hovering plays `hover_button` and clicking plays `click` through the nearest `SfxProvider`. Without a
provider the button stays silent. See [Sound effects](https://joeyash.github.io/jarvis_ui_lib/getting-started/sound.md).

## Accessibility

- Renders a native `<button type="button">` with `aria-label` set from `label`.
- The icon is rendered with `aria-hidden="true"`.
- `pressed` maps to `aria-pressed`; leave it `undefined` for a plain action button.
- The focus ring is visible on keyboard focus only (`focus-visible`).

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` (required) | `LucideIcon` |  | Lucide icon component to render, e.g. `Copy` from `lucide-react`. |
| `label` (required) | `string` |  | Accessible name. Required because the button has no visible text. |
| `className` | `string` |  | Additional class names for the `<button>` element. |
| `pressed` | `boolean` |  | Marks the button as toggled on (`aria-pressed`) and highlights it. |
| `size` | `'sm' \| 'md'` | `'md'` | Square size: `sm` is 24px, `md` is 30px. |
| `variant` | `'ghost' \| 'secondary' \| 'primary' \| 'danger'` | `'ghost'` | Visual style. |

Also accepts inherited props from `ButtonHTMLAttributes` (10), `HTMLAttributes` (54), `AriaAttributes` (53), `DOMAttributes` (169), `RefAttributes` (1), `Attributes` (1).

# Link

A styled anchor for inline text links, secondary links and navigation. It can open external
pages in a new tab and mark the current page in a navigation bar.

```ts
import { Link } from 'jarvis-react-ui';
```

## Variants

`accent` (the default) is the inline link with a dashed underline. `muted` is a quieter link for
secondary content. `nav` is the uppercase style for navigation bars.

```tsx
import { Link } from 'jarvis-react-ui';

export default function Variants() {
    return (
        <p className="text-[11px] text-text-secondary">
            Read the <Link href="#api">API reference</Link> or the{' '}
            <Link href="#accessibility" variant="muted">
                accessibility notes
            </Link>
            .
        </p>
    );
}
```

## External

`external` opens the link in a new tab with `rel="noopener noreferrer"` and appends an external-link
icon.

```tsx
import { Link } from 'jarvis-react-ui';

export default function External() {
    return (
        <Link href="https://github.com/JoeyAsh/jarvis_ui_lib" external>
            Source on GitHub
        </Link>
    );
}
```

## Navigation

Use `variant="nav"` with `active` on the link of the current page. With a client-side router, call
`event.preventDefault()` in `onClick` and navigate yourself, or wrap your router's link component.

```tsx
import { useState } from 'react';
import { Link } from 'jarvis-react-ui';

const SECTIONS = ['Overview', 'Systems', 'Telemetry'];

export default function Navigation() {
    const [current, setCurrent] = useState('Overview');

    return (
        <nav aria-label="Sections" className="flex items-center gap-5">
            {SECTIONS.map((section) => (
                <Link
                    key={section}
                    href={`#${section.toLowerCase()}`}
                    variant="nav"
                    active={section === current}
                    onClick={(e) => {
                        e.preventDefault();
                        setCurrent(section);
                    }}
                >
                    {section}
                </Link>
            ))}
        </nav>
    );
}
```

## Sound

Hovering plays `hover_button` and clicking plays `click` through the nearest `SfxProvider`. See
[Sound effects](https://joeyash.github.io/jarvis_ui_lib/getting-started/sound.md).

## Accessibility

- Renders a native `<a>`, so it is focusable and activates with Enter. Always pass an `href`.
- `active` sets `aria-current="page"`.
- The external-link icon is `aria-hidden`. If the link text does not make clear that it opens a new
  tab, say so in the text.
- The focus outline is visible on keyboard focus only (`focus-visible`).

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  | Link text. With `external`, the external-link icon is appended after it. |
| `active` | `boolean` | `false` | Marks the link as the current page (`aria-current="page"`) and highlights it. |
| `className` | `string` |  | Additional class names for the `<a>` element. |
| `external` | `boolean` | `false` | Opens in a new tab with `rel="noopener noreferrer"` and shows an external-link icon. |
| `variant` | `'accent' \| 'muted' \| 'nav'` | `'accent'` | Visual style: `accent` for inline text links, `muted` for secondary links, `nav` for uppercase navigation links. |

Also accepts inherited props from `AnchorHTMLAttributes` (8), `HTMLAttributes` (54), `AriaAttributes` (53), `DOMAttributes` (169), `RefAttributes` (1), `Attributes` (1).

# Tooltip

A small text bubble that explains its trigger on hover or keyboard focus. It is the standard
companion of [IconButton](https://joeyash.github.io/jarvis_ui_lib/components/icon-button.md).

```ts
import { Tooltip } from 'jarvis-react-ui';
```

## Basic

Wrap a single focusable element. The tooltip opens after `delayMs` (300ms by default) on hover and
immediately on keyboard focus.

```tsx
import { Copy } from 'lucide-react';
import { IconButton, Tooltip } from 'jarvis-react-ui';

export default function Basic() {
    return (
        <Tooltip content="Copy code">
            <IconButton icon={Copy} label="Copy" />
        </Tooltip>
    );
}
```

## Placements

`placement` puts the bubble on the `top` (default), `bottom`, `left` or `right` of the trigger.
The bubble does not flip when it runs out of space, so choose a side with room.

```tsx
import { Button, Tooltip } from 'jarvis-react-ui';

export default function Placements() {
    return (
        <>
            <Tooltip content="Above" placement="top">
                <Button size="sm">Top</Button>
            </Tooltip>
            <Tooltip content="Below" placement="bottom">
                <Button size="sm">Bottom</Button>
            </Tooltip>
            <Tooltip content="To the left" placement="left">
                <Button size="sm">Left</Button>
            </Tooltip>
            <Tooltip content="To the right" placement="right">
                <Button size="sm">Right</Button>
            </Tooltip>
        </>
    );
}
```

## Toolbar

A row of icon buttons with tooltips below them. `delayMs={0}` opens them instantly while the
pointer sweeps across the toolbar.

```tsx
import { FileCode, Maximize2, Volume2 } from 'lucide-react';
import { IconButton, Tooltip } from 'jarvis-react-ui';

export default function Toolbar() {
    return (
        <div className="flex items-center gap-1">
            <Tooltip content="View source" placement="bottom" delayMs={0}>
                <IconButton icon={FileCode} label="Source" />
            </Tooltip>
            <Tooltip content="Toggle sound" placement="bottom" delayMs={0}>
                <IconButton icon={Volume2} label="Sound" />
            </Tooltip>
            <Tooltip content="Fullscreen" placement="bottom" delayMs={0}>
                <IconButton icon={Maximize2} label="Fullscreen" />
            </Tooltip>
        </div>
    );
}
```

> **Note: Positioning**
>
> The bubble is absolutely positioned next to the trigger, not portaled. Ancestors with `overflow:
> hidden` clip it.

## Accessibility

- The bubble has `role="tooltip"` and an id; while it is open the trigger gets `aria-describedby`
  pointing at it.
- It opens on focus and closes on blur and on Escape.
- Tooltip content is a supplementary description. Do not put interactive content in it, and do not
  rely on it as the only accessible name of the trigger (give an `IconButton` its `label`).
- `disabled` keeps the tooltip mounted but never shows it.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactElement<TooltipTriggerProps>` |  | The trigger: a single element. It receives `aria-describedby` while the tooltip is open. |
| `content` (required) | `ReactNode` |  | Text or content shown in the tooltip bubble. |
| `className` | `string` |  | Additional class names for the tooltip bubble (`role="tooltip"`), not the trigger wrapper. |
| `delayMs` | `number` | `300` | Delay in ms before the tooltip opens on hover. Keyboard focus opens it immediately. |
| `disabled` | `boolean` | `false` | Disables the tooltip without removing it from the tree. |
| `placement` | `'top' \| 'bottom' \| 'left' \| 'right'` | `'top'` | Side of the trigger the tooltip appears on. |

### Type `TooltipTriggerProps`

Props the tooltip injects into its trigger element.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-describedby` | `string` |  | Id of the tooltip bubble while it is open, so screen readers announce it. |

# Divider

A hairline that separates content. It runs horizontally or vertically, can fade in the accent
color and can carry a small caption.

```ts
import { Divider } from 'jarvis-react-ui';
```

## Variants

`default` uses the border color. `accent` draws a line in the accent color that fades out at both
ends.

```tsx
import { Divider } from 'jarvis-react-ui';

export default function Variants() {
    return (
        <div className="flex w-full flex-col gap-6">
            <Divider />
            <Divider variant="accent" />
        </div>
    );
}
```

## With a label

`label` centers a small uppercase caption in a horizontal divider. Use it to title groups of
content.

```tsx
import { Divider } from 'jarvis-react-ui';

export default function WithLabel() {
    return (
        <div className="flex w-full flex-col gap-6">
            <Divider label="Telemetry" />
            <Divider label="Diagnostics" variant="accent" />
        </div>
    );
}
```

## Vertical

`orientation="vertical"` stretches to the height of its flex row. Use it to group actions in a
toolbar.

```tsx
import { Copy, Download, Settings, Trash2 } from 'lucide-react';
import { Divider, IconButton } from 'jarvis-react-ui';

export default function Vertical() {
    return (
        <div className="flex items-center gap-1 border border-border rounded-[2px] p-1">
            <IconButton icon={Copy} label="Copy" size="sm" />
            <IconButton icon={Download} label="Download" size="sm" />
            <Divider orientation="vertical" className="mx-1" />
            <IconButton icon={Settings} label="Settings" size="sm" />
            <IconButton icon={Trash2} label="Delete" size="sm" variant="danger" />
        </div>
    );
}
```

## Accessibility

- Renders a `<div role="separator">` with `aria-orientation` set to `horizontal` or `vertical`.
- A `label` is plain text inside the separator; it is not a heading. Use a real heading when the
  caption titles a section.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` |  | Additional class names for the root `role="separator"` element (the row when labelled). |
| `label` | `ReactNode` |  | Optional caption centered in a horizontal divider. |
| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Direction of the line. A vertical divider stretches to the height of its flex row. |
| `variant` | `'default' \| 'accent'` | `'default'` | `accent` draws a fading accent-colored line instead of the border color. |

# Pill

A small uppercase tag with a hairline border. Use it to show the state of a system, a connection
or a task at a glance.

```ts
import { Pill } from 'jarvis-react-ui';
```

## Variants

`default` is neutral. `ok`, `warn` and `err` map to the success, warning and error colors, and
`info` uses the bright accent for transient states such as syncing.

```tsx
import { Pill } from 'jarvis-react-ui';

export default function Variants() {
    return (
        <>
            <Pill>Idle</Pill>
            <Pill variant="ok">Online</Pill>
            <Pill variant="warn">Degraded</Pill>
            <Pill variant="err">Offline</Pill>
            <Pill variant="info">Syncing</Pill>
        </>
    );
}
```

## Status list

Pair pills with a [Label](https://joeyash.github.io/jarvis_ui_lib/components/label.md) to build a compact status readout. Keep the pill text
to one or two words.

```tsx
import { Label, Pill } from 'jarvis-react-ui';

const SUBSYSTEMS = [
    { name: 'Repulsors', status: 'Armed', variant: 'ok' },
    { name: 'Life support', status: 'Nominal', variant: 'ok' },
    { name: 'Uplink', status: 'Lagging', variant: 'warn' },
    { name: 'Flight control', status: 'Fault', variant: 'err' },
] as const;

export default function StatusList() {
    return (
        <ul className="flex w-full max-w-[280px] flex-col gap-2">
            {SUBSYSTEMS.map((s) => (
                <li key={s.name} className="flex items-center justify-between">
                    <Label>{s.name}</Label>
                    <Pill variant={s.variant}>{s.status}</Pill>
                </li>
            ))}
        </ul>
    );
}
```

## Accessibility

- Renders a plain `<span>`; it has no role and is not focusable. Native attributes (`id`, `title`,
  `aria-*`, `data-*`) are forwarded to it.
- The text is the only status information for screen readers. Do not rely on color alone: the word
  inside the pill must name the state.
- For a status that changes live and must be announced, set `aria-live="polite"` on the pill or
  wrap the readout in an element with it.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  | Short status text shown inside the pill; rendered uppercase. |
| `className` | `string` |  | Additional class names for the root `<span>`. |
| `variant` | `'default' \| 'ok' \| 'warn' \| 'err' \| 'info'` | `'default'` | Status color of the text and border: neutral, success, warning, error or accent. |

Also accepts inherited props from `HTMLAttributes` (54), `AriaAttributes` (53), `DOMAttributes` (169).

# Label

A small uppercase caption in the secondary text color. Use it to name a reading, a group of
values or a form control.

```ts
import { Label } from 'jarvis-react-ui';
```

## Captions

Put a `Label` above or next to the value it names, such as a [Metric](https://joeyash.github.io/jarvis_ui_lib/components/metric.md). `dim`
switches to the muted color for less important captions.

```tsx
import { Label, Metric } from 'jarvis-react-ui';

export default function Basic() {
    return (
        <div className="flex gap-8">
            <div className="flex flex-col gap-1">
                <Label>Core temp</Label>
                <Metric value="41.2" unit="°C" />
            </div>
            <div className="flex flex-col gap-1">
                <Label dim>Last sync</Label>
                <Metric value="00:42" unit="ago" small />
            </div>
        </div>
    );
}
```

## Form controls

With `htmlFor`, the label renders as a native `<label>` bound to the control with that `id`.
Clicking the label then focuses the field. Without `htmlFor` it renders a `<span>`.

```tsx
import { Input, Label } from 'jarvis-react-ui';

export default function WithControl() {
    return (
        <div className="flex flex-col gap-2">
            <Label htmlFor="callsign">Callsign</Label>
            <Input id="callsign" placeholder="MK-XLII" />
        </div>
    );
}
```

## Naming a group

Without `htmlFor` the label is a `<span>`. Native attributes such as `id`, `title`, `aria-*` and
`data-*` are forwarded on both the `<span>` and the `<label>`, so give the label an `id` and point
`aria-labelledby` of a group, region or custom widget at it.

```tsx
import { Label, Metric, Pill } from 'jarvis-react-ui';

export default function LabelledBy() {
    return (
        <div role="group" aria-labelledby="reactor-label" className="flex flex-col gap-1">
            <Label id="reactor-label">Arc reactor</Label>
            <div className="flex items-center gap-3">
                <Metric value="98.6" unit="%" />
                <Pill variant="ok">Stable</Pill>
            </div>
        </div>
    );
}
```

## Accessibility

- With `htmlFor` it is a real `<label>`, so the text becomes the accessible name of the control.
- Without `htmlFor` it is a `<span>` with no semantics of its own. Give it an `id` and reference it
  with `aria-labelledby` to make it the accessible name of another element.
- The text is transformed to uppercase by CSS only. Write captions in normal case so screen readers
  do not spell them out letter by letter.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  | Caption text; rendered small and uppercase. |
| `className` | `string` |  | Additional class names for the root element (`<label>` or `<span>`). |
| `dim` | `boolean` | `false` | Uses the muted text color instead of the secondary one, for less important captions. |
| `htmlFor` | `string` |  | Id of a form control; when set, the label renders as a native `<label>` bound to it, otherwise as a `<span>`. |

Also accepts inherited props from `HTMLAttributes` (54), `AriaAttributes` (53), `DOMAttributes` (169).

# Mono

A text element in JetBrains Mono with four size steps and three text colors. Use it for body
text, readouts and log lines inside HUD panels.

```ts
import { Mono } from 'jarvis-react-ui';
```

## Sizes

`xs` is 9px, `sm` 10px, `md` (the default) 11px and `lg` 13px.

```tsx
import { Mono } from 'jarvis-react-ui';

export default function Sizes() {
    return (
        <div className="flex flex-col gap-2">
            <Mono size="xs">xs · SYS.BOOT 0x00FF</Mono>
            <Mono size="sm">sm · SYS.BOOT 0x00FF</Mono>
            <Mono size="md">md · SYS.BOOT 0x00FF</Mono>
            <Mono size="lg">lg · SYS.BOOT 0x00FF</Mono>
        </div>
    );
}
```

## Colors

The default uses the primary text color. `secondary` steps it down, `muted` steps it down further
for timestamps and other low-priority text. When both are set, `muted` wins.

```tsx
import { Mono } from 'jarvis-react-ui';

export default function Colors() {
    return (
        <div className="flex flex-col gap-2">
            <Mono>Reactor output stable at 3.2 GJ/s</Mono>
            <Mono secondary>Next diagnostic in 14 min</Mono>
            <Mono muted>Log rotated · 2,048 entries archived</Mono>
        </div>
    );
}
```

## Element

`Mono` renders a `<span>` by default. Use `as` to render a different element, such as `p`, `code`
or `time`, so the text keeps its meaning in the document.

```tsx
import { Mono } from 'jarvis-react-ui';

export default function AsElement() {
    return (
        <div className="flex flex-col gap-2">
            <Mono as="time" dateTime="2026-10-03T09:04:17Z" size="lg">
                09:04:17Z
            </Mono>
            <Mono as="code" secondary>
                uplink --channel 7 --encrypt
            </Mono>
            <Mono as="p" muted size="sm">
                Last handshake 312 ms ago.
            </Mono>
        </div>
    );
}
```

Native attributes (`id`, `title`, `aria-*`, `data-*`, event handlers) are forwarded to the rendered
element, including `dateTime` for `as="time"`.

## Accessibility

- Renders the element given in `as` with no extra role, so semantics come from that element.
- Pick a fitting element (`p` for paragraphs, `code` for commands) instead of styling a `<span>`.
- `muted` text has lower contrast; do not use it for information the user must read.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  | Text to render in the monospace font. |
| `as` | `ElementType` | `span` | Element or component to render instead of a `<span>`, e.g. `'p'`, `'code'` or `'time'`. |
| `className` | `string` |  | Additional class names for the rendered element. |
| `dateTime` | `string` |  | Machine-readable date or time, forwarded to the element; use it with `as="time"`. |
| `muted` | `boolean` | `false` | Uses the muted text color; takes precedence over `secondary`. |
| `secondary` | `boolean` | `false` | Uses the secondary text color instead of the primary one. |
| `size` | `'xs' \| 'sm' \| 'md' \| 'lg'` | `'md'` | Font size step: `xs` 9px, `sm` 10px, `md` 11px, `lg` 13px. |

Also accepts inherited props from `HTMLAttributes` (54), `AriaAttributes` (53), `DOMAttributes` (169).

# Metric

A numeric reading in the bright accent color with an optional unit. Its digits use tabular
figures, so values that update live do not make the layout jump.

```ts
import { Metric } from 'jarvis-react-ui';
```

## Value and unit

`value` accepts a number or any node; format it yourself (thousands separators, durations).
`unit` is shown after it in a small muted font. Pair it with a [Label](https://joeyash.github.io/jarvis_ui_lib/components/label.md) that names
the reading.

```tsx
import { Label, Metric } from 'jarvis-react-ui';

const READINGS = [
    { label: 'CPU', value: '42', unit: '%' },
    { label: 'Latency', value: '18', unit: 'ms' },
    { label: 'Altitude', value: '1,204', unit: 'm' },
    { label: 'Uptime', value: '73:12:05' },
];

export default function Units() {
    return (
        <div className="flex flex-wrap gap-8">
            {READINGS.map((r) => (
                <div key={r.label} className="flex flex-col gap-1">
                    <Label>{r.label}</Label>
                    <Metric value={r.value} unit={r.unit} />
                </div>
            ))}
        </div>
    );
}
```

## Warning

`warn` switches the value to the warning color. Derive it from a threshold so the reading flags
itself when it leaves the safe range.

```tsx
import { Label, Metric } from 'jarvis-react-ui';

const READINGS = [
    { label: 'Core temp', value: 64, unit: '°C', limit: 80 },
    { label: 'Hull stress', value: 91, unit: '%', limit: 75 },
];

export default function Warn() {
    return (
        <div className="flex gap-8">
            {READINGS.map((r) => (
                <div key={r.label} className="flex flex-col gap-1">
                    <Label>{r.label}</Label>
                    <Metric value={r.value} unit={r.unit} warn={r.value > r.limit} />
                </div>
            ))}
        </div>
    );
}
```

## Small

`small` renders the value at 12px instead of 14px. Use it in dense lists and table-like rows.

```tsx
import { Label, Metric } from 'jarvis-react-ui';

const ROWS = [
    { label: 'Packets in', value: '12,480', unit: '/s' },
    { label: 'Packets out', value: '9,312', unit: '/s' },
    { label: 'Dropped', value: '214', unit: '/s', warn: true },
];

export default function Small() {
    return (
        <dl className="flex w-full max-w-[240px] flex-col gap-1">
            {ROWS.map((r) => (
                <div key={r.label} className="flex items-baseline justify-between">
                    <dt>
                        <Label>{r.label}</Label>
                    </dt>
                    <dd>
                        <Metric value={r.value} unit={r.unit} warn={r.warn} small />
                    </dd>
                </div>
            ))}
        </dl>
    );
}
```

## Accessibility

- Renders a `<span>` with the value and a `<small>` for the unit; it has no role. Native attributes
  (`id`, `title`, `aria-*`, `data-*`) are forwarded to the `<span>`.
- Screen readers read value and unit as one string. Prefer units that read well (`ms`, `%`) or name
  the unit in the label.
- `warn` is shown by color only. When the warning matters, also say it in text, for example with a
  [Pill](https://joeyash.github.io/jarvis_ui_lib/components/pill.md).

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `ReactNode` |  | The reading itself, rendered in tabular figures so changing digits do not shift the layout. |
| `className` | `string` |  | Additional class names for the root `<span>`. |
| `small` | `boolean` | `false` | Renders the value at 12px instead of 14px for dense rows. |
| `unit` | `string` |  | Unit shown after the value in a small muted `<small>`, e.g. `'%'`, `'ms'` or `'°C'`. |
| `warn` | `boolean` | `false` | Colors the value in the warning color to flag an out-of-range reading. |

Also accepts inherited props from `HTMLAttributes` (54), `AriaAttributes` (53), `DOMAttributes` (169).

# ProgressBar

A thin glowing bar that shows a fraction of a whole: load, capacity or the progress of a task.
It fills the width of its container.

```ts
import { ProgressBar } from 'jarvis-react-ui';
```

## Variants

`accent` (the default) and `bright` are for normal readings; `warn` uses the warning color for a
value that needs attention. Each variant has a matching glow.

```tsx
import { Label, ProgressBar } from 'jarvis-react-ui';

export default function Variants() {
    return (
        <div className="flex w-full max-w-[320px] flex-col gap-4">
            <div className="flex flex-col gap-2">
                <Label>CPU · 42%</Label>
                <ProgressBar value={0.42} aria-label="CPU" />
            </div>
            <div className="flex flex-col gap-2">
                <Label>Memory · 70%</Label>
                <ProgressBar value={0.7} variant="bright" aria-label="Memory" />
            </div>
            <div className="flex flex-col gap-2">
                <Label>Power reserve · 15%</Label>
                <ProgressBar value={0.15} variant="warn" aria-label="Power reserve" />
            </div>
        </div>
    );
}
```

## Heights

`thin` (the default) is 2px and suits dense panels. `normal` is 4px for a bar that is the main
content of a row.

```tsx
import { ProgressBar } from 'jarvis-react-ui';

export default function Heights() {
    return (
        <div className="flex w-full max-w-[320px] flex-col gap-4">
            <ProgressBar value={0.55} aria-label="Shield charge" />
            <ProgressBar value={0.55} height="normal" aria-label="Shield charge" />
        </div>
    );
}
```

## Live progress

`value` is a fraction from `0` to `1`; values outside that range are clamped. Width changes animate
smoothly, so you can update it as often as new data arrives.

```tsx
import { useEffect, useState } from 'react';
import { Label, Metric, ProgressBar } from 'jarvis-react-ui';

export default function Live() {
    const [value, setValue] = useState(0);

    useEffect(() => {
        const id = setInterval(() => {
            setValue((v) => (v >= 1 ? 0 : Math.min(1, v + 0.04)));
        }, 200);
        return () => clearInterval(id);
    }, []);

    return (
        <div className="flex w-full max-w-[320px] flex-col gap-2">
            <div className="flex items-baseline justify-between">
                <Label>Firmware upload</Label>
                <Metric value={Math.round(value * 100)} unit="%" small />
            </div>
            <ProgressBar value={value} height="normal" aria-label="Firmware upload" />
        </div>
    );
}
```

## Width

The bar takes the full width of its parent. Set the width on a wrapper or pass a width class via
`className`, which lands on the track element.

## Accessibility

- Renders `role="progressbar"` with `aria-valuemin="0"`, `aria-valuemax="100"` and
  `aria-valuenow` set to the rounded percentage.
- Always give it an accessible name with `aria-label`; a visible caption next to it is not linked
  automatically.
- The bar is not focusable and has no keyboard interaction.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `value` (required) | `number` |  | Progress as a fraction from `0` to `1`; values outside that range are clamped. |
| `aria-label` | `string` |  | Accessible name of the progress bar; set it unless a visible label is linked another way. |
| `className` | `string` |  | Additional class names for the root `role="progressbar"` track; set its width here. |
| `height` | `'thin' \| 'normal'` | `'thin'` | Track height: `thin` is 2px, `normal` is 4px. |
| `variant` | `'accent' \| 'bright' \| 'warn'` | `'accent'` | Fill color: the accent, the brighter accent or the warning color, each with a matching glow. |

# Sparkline

A tiny line chart with a soft fill, without axes or labels. Use it to show the trend of a
reading next to its current value.

```ts
import { Sparkline } from 'jarvis-react-ui';
```

## Variants

`accent` (the default) draws the line in the accent color; `warn` uses the warning color for a
series that is out of range.

```tsx
import { Label, Sparkline } from 'jarvis-react-ui';

const CPU = [32, 41, 38, 45, 52, 48, 61, 57, 49, 44, 51, 47];
const TEMP = [61, 63, 66, 70, 74, 79, 83, 86, 85, 88, 91, 90];

export default function Variants() {
    return (
        <div className="flex w-full max-w-[320px] flex-col gap-4">
            <div className="flex flex-col gap-1">
                <Label>CPU load</Label>
                <Sparkline data={CPU} aria-label="CPU load, last 12 samples" />
            </div>
            <div className="flex flex-col gap-1">
                <Label>Core temp</Label>
                <Sparkline data={TEMP} variant="warn" aria-label="Core temperature, rising" />
            </div>
        </div>
    );
}
```

## Scaling and height

The series is scaled between its own minimum and maximum, so the shape always fills the chart. The
line stretches to the full width of its container; `height` sets the height in pixels (28 by
default). At least two values are needed to draw a line.

```tsx
import { Sparkline } from 'jarvis-react-ui';

const SIGNAL = [12, 18, 9, 22, 30, 26, 35, 28, 40, 33, 45, 38, 50, 42];

export default function Height() {
    return (
        <div className="flex w-full max-w-[320px] flex-col gap-4">
            <Sparkline data={SIGNAL} height={16} />
            <Sparkline data={SIGNAL} />
            <Sparkline data={SIGNAL} height={56} />
        </div>
    );
}
```

`width` only sets the width of the internal coordinate system. Because the SVG stretches, it rarely
needs changing.

## Live data

Keep a fixed-length array in state and append new samples while dropping the oldest. Combine it with
a [Metric](https://joeyash.github.io/jarvis_ui_lib/components/metric.md) for the current value, and switch `variant` when a threshold is
crossed.

```tsx
import { useEffect, useState } from 'react';
import { Label, Metric, Sparkline } from 'jarvis-react-ui';

const SAMPLES = 30;

export default function Live() {
    const [data, setData] = useState<number[]>(() => Array.from({ length: SAMPLES }, () => 50));

    useEffect(() => {
        const id = setInterval(() => {
            setData((prev) => {
                const last = prev[prev.length - 1] ?? 50;
                const next = Math.max(0, Math.min(100, last + (Math.random() - 0.5) * 20));
                return [...prev.slice(1), next];
            });
        }, 500);
        return () => clearInterval(id);
    }, []);

    const current = Math.round(data[data.length - 1] ?? 0);
    const high = current > 80;

    return (
        <div className="flex w-full max-w-[320px] flex-col gap-1">
            <div className="flex items-baseline justify-between">
                <Label>Network throughput</Label>
                <Metric value={current} unit="Mb/s" warn={high} small />
            </div>
            <Sparkline
                data={data}
                variant={high ? 'warn' : 'accent'}
                height={40}
                aria-label="Network throughput, live"
            />
        </div>
    );
}
```

## Accessibility

- Without `aria-label` the SVG has no role and no name; screen readers skip over it. Use this when
  the current value is already shown as text next to it.
- With `aria-label` the SVG gets `role="img"`. Describe the trend in words ("CPU load, rising"),
  since the individual values are not exposed.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `data` (required) | `number[]` |  | Series of values, oldest first; scaled to fit between its own minimum and maximum. Needs at least two points to draw. |
| `aria-label` | `string` |  | Accessible description of the chart; when set, the SVG gets `role="img"`. |
| `className` | `string` |  | Additional class names for the root `<svg>` (full width by default). |
| `height` | `number` | `28` | Height of the chart in pixels. |
| `variant` | `'accent' \| 'warn'` | `'accent'` | Line and fill color: the accent or the warning color. |
| `width` | `number` | `100` | Width of the SVG coordinate system; the line always stretches to the container width. |

# Icon

Renders a `lucide-react` icon at one of three HUD sizes with a consistent stroke width. Use it
for status glyphs and icons next to text.

```ts
import { Icon } from 'jarvis-react-ui';
```

## Sizes

Pass the icon component itself (not an element) to `icon`. `sm` is 12px, `md` (the default) 14px
and `lg` 16px; every size uses a 1.75 stroke.

```tsx
import { Cpu } from 'lucide-react';
import { Icon } from 'jarvis-react-ui';

export default function Sizes() {
    return (
        <div className="flex items-center gap-6 text-accent">
            <Icon icon={Cpu} size="sm" aria-label="CPU" />
            <Icon icon={Cpu} size="md" aria-label="CPU" />
            <Icon icon={Cpu} size="lg" aria-label="CPU" />
        </div>
    );
}
```

## Color

The icon draws in `currentColor`. Set a text color class on the icon via `className`, or on a parent
element.

## Decorative icons

Icons are decorative by default: without an `aria-label` the `<svg>` gets `aria-hidden="true"`, so
screen readers skip it. Use this when the text next to the icon already says everything.

```tsx
import { Battery, Thermometer, Wifi } from 'lucide-react';
import { Icon, Mono } from 'jarvis-react-ui';

export default function Decorative() {
    return (
        <div className="flex flex-col gap-2">
            <span className="flex items-center gap-2">
                <Icon icon={Wifi} size="sm" className="text-accent" />
                <Mono>Uplink · secure</Mono>
            </span>
            <span className="flex items-center gap-2">
                <Icon icon={Thermometer} size="sm" className="text-warning" />
                <Mono>Core temp · 87 °C</Mono>
            </span>
            <span className="flex items-center gap-2">
                <Icon icon={Battery} size="sm" className="text-success" />
                <Mono>Reserve · 94%</Mono>
            </span>
        </div>
    );
}
```

## Meaningful icons

An icon that stands on its own and carries information needs an `aria-label`; the `<svg>` then gets
`role="img"` and that label as its accessible name. For a clickable icon use
[IconButton](https://joeyash.github.io/jarvis_ui_lib/components/icon-button.md) instead.

```tsx
import { ShieldAlert, ShieldCheck } from 'lucide-react';
import { Icon } from 'jarvis-react-ui';

export default function Standalone() {
    return (
        <div className="flex items-center gap-4">
            <Icon icon={ShieldCheck} size="lg" className="text-success" aria-label="Shields up" />
            <Icon icon={ShieldAlert} size="lg" className="text-error" aria-label="Shields down" />
        </div>
    );
}
```

## Accessibility

- Renders the lucide `<svg>`. Without `aria-label` it is `aria-hidden="true"` (decorative); with
  `aria-label` it gets `role="img"` and that name.
- An explicit `aria-hidden` always wins over the default.
- The ref points at the `<svg>` element.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `icon` (required) | `LucideIcon` |  | The `lucide-react` icon component to render, e.g. `Cpu`. |
| `aria-hidden` | `boolean \| 'true' \| 'false'` |  | Hides the icon from assistive technology. When omitted it is `true` unless `aria-label` is set, so icons are decorative by default. |
| `aria-label` | `string` |  | Accessible name for an icon that carries meaning on its own; also sets `role="img"` on the `<svg>`. |
| `className` | `string` |  | Additional class names for the `<svg>` element; color it with a text color class. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Icon size: `sm` 12px, `md` 14px, `lg` 16px, with a 1.75 stroke. |

Also accepts inherited props from `RefAttributes` (1), `Attributes` (1).

# Hint

A muted line of text that tells the user about a keyboard shortcut. `Hint.Key` renders a single
key chip and also works on its own, for example inside an [Input](https://joeyash.github.io/jarvis_ui_lib/components/input.md).

```ts
import { Hint } from 'jarvis-react-ui';
```

## Inline

`position="inline"` keeps the hint in the document flow. Mix text and `Hint.Key` chips freely.

```tsx
import { Hint } from 'jarvis-react-ui';

export default function Inline() {
    return (
        <Hint position="inline">
            Push to talk · <Hint.Key>Space</Hint.Key> · Mute · <Hint.Key>Ctrl+.</Hint.Key>
        </Hint>
    );
}
```

## Fixed in the corner

The default `position="fixed-br"` pins the hint 16px from the bottom-right corner of the viewport,
above the page content, via the `lib-hint--fixed-br` modifier class. Render it once per screen for the most important shortcut.

```tsx
import { Hint } from 'jarvis-react-ui';

export default function Fixed() {
    return (
        <Hint>
            Command palette · <Hint.Key>Ctrl K</Hint.Key>
        </Hint>
    );
}
```

A fixed hint escapes to the viewport. To keep it inside a preview container, give the container
`relative overflow-hidden transform-gpu` and an explicit height.

## Key chips

`Hint.Key` renders a small [Kbd](https://joeyash.github.io/jarvis_ui_lib/components/kbd.md) chip (a `<kbd>` in a hairline frame with the
accent color) with spacing for running text. Use it anywhere a shortcut is mentioned, such as the end
adornment of an input; for other sizes use `Kbd` directly.

```tsx
import { Search } from 'lucide-react';
import { Hint, Input } from 'jarvis-react-ui';

export default function KeyChip() {
    return (
        <Input
            aria-label="Search systems"
            placeholder="Search systems…"
            startAdornment={<Search size={12} aria-hidden="true" />}
            endAdornment={<Hint.Key>/</Hint.Key>}
        />
    );
}
```

### Hint.Key props

| Prop        | Type        | Default | Description                                     |
| ----------- | ----------- | ------- | ----------------------------------------------- |
| `children`  | `ReactNode` | —       | Key or key combination to show, e.g. `SPACE`.   |
| `className` | `string`    | —       | Additional class names for the `<kbd>` element. |

The position union is exported as the `HintPosition` type.

## Accessibility

- `Hint` is a plain `<div>` with no role; `Hint.Key` is a native `<kbd>`, which marks keyboard input
  for assistive technology.
- The hint only describes a shortcut; the shortcut itself must be implemented by your app.
- The text is uppercase by CSS. Write key names in normal case (`Ctrl K`), so they are read as words.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  | Hint text, usually mixed with `Hint.Key` chips. |
| `className` | `string` |  | Additional class names for the root `<div>`. |
| `position` | `'fixed-br' \| 'inline'` | `'fixed-br'` | `fixed-br` pins the hint to the bottom-right corner of the viewport (class `lib-hint--fixed-br`); `inline` keeps it in the flow. |

# Kbd

A keyboard key chip. Use it to show shortcuts in hints, menus, tooltips and docs. It renders a
semantic `<kbd>` element.

```ts
import { Kbd } from 'jarvis-react-ui';
```

## Shortcuts

Use one `Kbd` per key for combinations, or a single one with the whole combo (`<Kbd>Ctrl K</Kbd>`).

```tsx
import { Kbd } from 'jarvis-react-ui';

export default function Shortcuts() {
    return (
        <dl className="m-0 grid grid-cols-[auto_1fr] items-center gap-x-6 gap-y-2 text-[11px] text-text-secondary">
            <dt className="flex gap-1">
                <Kbd>Ctrl</Kbd>
                <Kbd>K</Kbd>
            </dt>
            <dd className="m-0">Search the docs</dd>
            <dt className="flex gap-1">
                <Kbd>Space</Kbd>
            </dt>
            <dd className="m-0">Push to talk</dd>
            <dt className="flex gap-1">
                <Kbd>Esc</Kbd>
            </dt>
            <dd className="m-0">Close dialog</dd>
        </dl>
    );
}
```

## Sizes

`sm` (default) fits inline text and inputs; `md` suits headings and larger hints.

```tsx
import { Kbd } from 'jarvis-react-ui';

export default function Sizes() {
    return (
        <>
            <Kbd>Ctrl K</Kbd>
            <Kbd size="md">Ctrl K</Kbd>
        </>
    );
}
```

`Kbd` also works as an end adornment of [Input](https://joeyash.github.io/jarvis_ui_lib/components/input.md), as the search field of this
site does.

## Accessibility

The `<kbd>` element tells assistive technology that the text is keyboard input. Write key names as
words (`Ctrl`, `Esc`) rather than symbols only, and give platform variants (`Ctrl` / `⌘`) where
they differ.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  | The key or key combination, e.g. `Ctrl K`. Use one `Kbd` per key for combos if you prefer. |
| `className` | `string` |  | Additional class names for the `<kbd>` element. |
| `size` | `'sm' \| 'md'` | `'sm'` | Text size of the chip. |

Also accepts inherited props from `HTMLAttributes` (54), `AriaAttributes` (53), `DOMAttributes` (169), `RefAttributes` (1), `Attributes` (1).

# Toast

Toasts are short, non-blocking notifications that appear in a corner and close themselves. Call
`useToast()` anywhere below a `JarvisProvider` (or `ToastProvider`) to show one.

```ts
import { Toast } from 'jarvis-react-ui';
```

## Show a toast

`toast(options)` shows a notification and returns its id. The four variants change the color, the
icon and the sound: `success` plays `confirm`, `error` plays `error`.

```tsx
import { Button, useToast } from 'jarvis-react-ui';

export default function Variants() {
    const { toast } = useToast();

    return (
        <>
            <Button onClick={() => toast({ title: 'Uplink established' })}>Info</Button>
            <Button onClick={() => toast({ variant: 'success', title: 'Diagnostics passed' })}>
                Success
            </Button>
            <Button onClick={() => toast({ variant: 'warning', title: 'Power at 18%' })}>
                Warning
            </Button>
            <Button
                variant="danger"
                onClick={() => toast({ variant: 'error', title: 'Connection lost' })}
            >
                Error
            </Button>
        </>
    );
}
```

```tsx
import { useToast } from 'jarvis-react-ui';

const { toast } = useToast();
toast({ variant: 'success', title: 'Diagnostics passed' });
```

## Title and description

Keep the title to a few words and put details in `description`.

```tsx
import { Button, useToast } from 'jarvis-react-ui';

export default function WithDescription() {
    const { toast } = useToast();

    return (
        <Button
            variant="primary"
            onClick={() =>
                toast({
                    variant: 'success',
                    title: 'Profile saved',
                    description: 'Your changes are synced to all devices.',
                })
            }
        >
            Save profile
        </Button>
    );
}
```

## Action

An `action` adds a button, typically **Undo**. Clicking it runs the handler and closes the toast.

```tsx
import { useState } from 'react';
import { Button, Pill, useToast } from 'jarvis-react-ui';

export default function WithAction() {
    const { toast } = useToast();
    const [archived, setArchived] = useState(false);

    function archive() {
        setArchived(true);
        toast({
            title: 'Log archived',
            action: { label: 'Undo', onClick: () => setArchived(false) },
        });
    }

    return (
        <>
            <Button onClick={archive} disabled={archived}>
                Archive log
            </Button>
            <Pill variant={archived ? 'warn' : 'ok'}>{archived ? 'archived' : 'active'}</Pill>
        </>
    );
}
```

## Duration

Toasts close after 5 seconds by default; the bar at the bottom shows the remaining time. The timer
pauses while the pointer is over the toast or focus is inside it. Pass `duration: Infinity` for
messages that must be dismissed by hand, and `dismiss(id)` to close one from code.

```tsx
import { Button, useToast } from 'jarvis-react-ui';

export default function Duration() {
    const { toast, dismiss } = useToast();

    return (
        <>
            <Button onClick={() => toast({ title: 'Quick notice', duration: 1500 })}>1.5 s</Button>
            <Button
                onClick={() =>
                    toast({
                        id: 'reactor',
                        variant: 'error',
                        title: 'Reactor offline',
                        description: 'Stays until dismissed.',
                        duration: Infinity,
                    })
                }
            >
                Sticky
            </Button>
            <Button variant="ghost" onClick={() => dismiss('reactor')}>
                Dismiss sticky
            </Button>
        </>
    );
}
```

Reusing an `id` replaces the visible toast instead of stacking a new one, which suits repeated
events such as "Copied". This site does exactly that when you copy a code block.

## The Toast element

`Toast` is the presentational element the provider renders. Use it directly to build your own
notification area or to show a toast inline. It does not close itself; `duration` only draws the
countdown bar.

```tsx
import { Toast } from 'jarvis-react-ui';

export default function Static() {
    return (
        <div className="flex w-full max-w-[360px] flex-col gap-2">
            <Toast
                variant="success"
                title="Diagnostics passed"
                description="All systems nominal."
                duration={5000}
                paused
                onDismiss={() => undefined}
            />
            <Toast
                variant="warning"
                title="Power at 18%"
                action={{ label: 'Reroute', onClick: () => undefined }}
            />
        </div>
    );
}
```

## Options

| Option        | Type                                          | Default  | Description                               |
| ------------- | --------------------------------------------- | -------- | ----------------------------------------- |
| `title`       | `ReactNode`                                   | —        | Bold first line.                          |
| `description` | `ReactNode`                                   | —        | Message text below the title.             |
| `variant`     | `'info' \| 'success' \| 'warning' \| 'error'` | `'info'` | Color, icon, sound and ARIA role.         |
| `duration`    | `number`                                      | `5000`   | Lifetime in ms; `Infinity` keeps it open. |
| `action`      | `{ label: string; onClick: () => void }`      | —        | Action button; also closes the toast.     |
| `id`          | `string`                                      | auto     | Reuse to replace an existing toast.       |

Every option is optional. Pass at least a `title` or a `description`; one of them is enough.

`useToast()` returns `{ toast, dismiss, dismissAll }` and throws when no provider is mounted.
Placement, the number of visible toasts and the default duration are set on
[ToastProvider](https://joeyash.github.io/jarvis_ui_lib/components/toast-provider.md) or [JarvisProvider](https://joeyash.github.io/jarvis_ui_lib/components/jarvis-provider.md).

## Accessibility

- Toasts render inside a labelled `aria-live="polite"` region, so screen readers announce them
  without moving focus.
- Toasts use `role="status"`; `error` toasts use `role="alert"` and are announced immediately.
- The timer pauses on hover and keyboard focus, and **Escape** closes the focused toast.
- Do not put information only in a toast that the user cannot find again elsewhere.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `action` | `ToastAction` |  | Optional action button, e.g. `{ label: 'Undo', onClick }`. |
| `className` | `string` |  | Additional class names for the root element. |
| `description` | `ReactNode` |  | Message text below the title. |
| `duration` | `number` |  | Lifetime in ms; draws a countdown bar of that length. Omit or pass `Infinity` for no bar. The toast does not close itself; `ToastProvider` handles timing. |
| `onDismiss` | `(() => void)` |  | Shows a close button that calls this handler. |
| `paused` | `boolean` | `false` | Pauses the countdown bar (e.g. while hovered). |
| `title` | `ReactNode` |  | Bold first line. |
| `variant` | `'info' \| 'success' \| 'warning' \| 'error'` | `'info'` | Semantic color, icon and ARIA role (`error` uses `role="alert"`). |

Also accepts inherited props from `HTMLAttributes` (53), `AriaAttributes` (53), `DOMAttributes` (170), `RefAttributes` (1), `Attributes` (1).

### Type `ToastAction`

Action button shown in a toast, e.g. `{ label: 'Undo', onClick: undo }`.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` |  | Button text, e.g. `Undo`. |
| `onClick` (required) | `() => void` |  | Called when the action button is clicked. |

# Panel

Panels are the framed surfaces of the HUD: a translucent glass body with corner brackets, side
rails, a light trace and a header strip. They hold the content of a dashboard tile or a window.

```ts
import { Panel } from 'jarvis-react-ui';
```

## Basic

A panel is as wide as its container and, without a set height, grows with its content. Size it
with `className` (a class from your own CSS, or Tailwind utilities if your project uses Tailwind)
or with `style`. With a fixed height the body scrolls when its content overflows. The body has 12px
padding, so content such as [Tabs](https://joeyash.github.io/jarvis_ui_lib/components/tabs.md) needs no extra spacing.

```tsx
import { Panel } from 'jarvis-react-ui';

export default function Basic() {
    return (
        <Panel title="Diagnostics" className="w-[280px] h-[120px]">
            <span className="text-text-secondary">All subsystems nominal.</span>
        </Panel>
    );
}
```

## Header

The header shows an optional index glyph (`ix`), the `title`, three status dots, optional `actions`
and an optional `badge`, in that order. Use [IconButton](https://joeyash.github.io/jarvis_ui_lib/components/icon-button.md) for actions.

```tsx
import { RefreshCw, Settings } from 'lucide-react';
import { IconButton, Metric, Panel } from 'jarvis-react-ui';

export default function Header() {
    return (
        <Panel
            ix="◈"
            title="System Vitals"
            badge="LIVE"
            actions={
                <>
                    <IconButton icon={RefreshCw} label="Refresh" size="sm" />
                    <IconButton icon={Settings} label="Settings" size="sm" />
                </>
            }
            className="w-[316px] h-[150px]"
        >
            <div className="grid grid-cols-2 gap-3">
                <Metric value={42} unit="%" />
                <Metric value={68} unit="°C" warn />
            </div>
        </Panel>
    );
}
```

## Focus

`focused` switches the border to the accent color and turns on an animated bloom. The panel does not
track focus itself: `onFocus` fires on mouse down anywhere inside it, so keep the focused id in state
and pass it back.

```tsx
import { useState } from 'react';
import { Panel } from 'jarvis-react-ui';

const PANELS = ['Transcript', 'Agenda', 'Now Playing'];

export default function Focus() {
    const [focused, setFocused] = useState('Transcript');

    return (
        <>
            {PANELS.map((title) => (
                <Panel
                    key={title}
                    title={title}
                    focused={focused === title}
                    onFocus={() => setFocused(title)}
                    className="w-[200px] h-[110px]"
                >
                    <span className="text-text-secondary">
                        {focused === title ? 'Focused' : 'Click to focus'}
                    </span>
                </Panel>
            ))}
        </>
    );
}
```

> **Note: Building windows**
>
> For draggable, slot-docked panels use [WindowManager](https://joeyash.github.io/jarvis_ui_lib/components/window-manager.md). Its windows
> are Panels wired through `headerRef`, `onHeaderPointerDown` and `onHeaderClick` for dragging and
> double-click docking. You rarely need these three props yourself.

## Sound

Hovering a panel plays `hover_panel` through the nearest `SfxProvider`. Without a provider the panel
stays silent. See [Sound effects](https://joeyash.github.io/jarvis_ui_lib/getting-started/sound.md).

## Accessibility

- The panel is a presentational `<div>` without a landmark role. Wrap it in a `<section>` with an
  `aria-label` when the panel is a distinct region of the page.
- `focused` is purely visual and does not move keyboard focus.
- Header `actions` should be real buttons with accessible names, such as `IconButton` with `label`.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `actions` | `ReactNode` |  | Controls rendered in the header between the dots and the badge, e.g. icon buttons. |
| `badge` | `ReactNode` |  | Tag shown at the right end of the header, e.g. `LIVE`. |
| `children` | `ReactNode` |  | Panel body content. |
| `className` | `string` |  | Additional class names for the root element, e.g. width and height utilities. |
| `focused` | `boolean` | `false` | Highlights the panel: accent border and a stronger, animated bloom. |
| `headerRef` | `Ref<HTMLDivElement>` |  | Ref to the header element, e.g. to measure it or attach a drag handle. |
| `ix` | `ReactNode` |  | Index glyph shown before the title in the header, e.g. `◈`. |
| `onFocus` | `(() => void)` |  | Called on mouse down anywhere in the panel; use it to set `focused`. |
| `onHeaderClick` | `((e: MouseEvent<HTMLDivElement, MouseEvent>) => void)` |  | Click handler on the header; used for double-click detection by `Window`. |
| `onHeaderPointerDown` | `PointerEventHandler<HTMLDivElement>` |  | Pointer-down handler on the header; used as a drag handle by `Window`. |
| `style` | `CSSProperties` |  | Inline style for the root element, e.g. `{ width: 320, height: 220 }`. |
| `title` | `ReactNode` |  | Header title. |

# TopBar

The TopBar is the status strip at the top of the HUD. It has three slots, left, center and
right, and carries the panel chrome: corner brackets and a light trace that circles its border.

```ts
import { TopBar } from 'jarvis-react-ui';
```

## Positions

`position` decides how the bar is placed:

| Value    | Behavior                                                                                       |
| -------- | ---------------------------------------------------------------------------------------------- |
| `fixed`  | Default. Pinned to the viewport, 10px from the top, left and right edges, above other content. |
| `sticky` | Full width in the document flow; sticks 10px below the top of its scroll container.            |
| `static` | Full width in the document flow, like a normal block, e.g. inside a page header or a card.     |

The bar is always 40px high. With `fixed`, leave room at the top of your layout: the slot grid of
[WindowManager](https://joeyash.github.io/jarvis_ui_lib/components/window-manager.md) reserves the top 60px for it.

## Static

```tsx
import { BrandMark, TopBar } from 'jarvis-react-ui';

export default function Static() {
    return (
        <TopBar
            position="static"
            left={<span className="text-[11px] text-text">09:04:17</span>}
            center={
                <span className="text-[9px] tracking-[8px] text-text-muted uppercase">
                    JARVIS / <b className="text-accent-bright font-medium">MK XLII</b>
                </span>
            }
            right={<BrandMark />}
        />
    );
}
```

## Slots

Each slot takes any React node. Use the left slot for time or status text, the center for a title
and the right for a brand mark or actions.

```tsx
import { Bell, Settings } from 'lucide-react';
import { BrandMark, IconButton, StatusBadge, TopBar } from 'jarvis-react-ui';

export default function Actions() {
    return (
        <TopBar
            position="static"
            left={<BrandMark />}
            center={<StatusBadge label="LINK · SECURE" state="online" pulse />}
            right={
                <span className="flex items-center gap-1">
                    <IconButton icon={Bell} label="Notifications" size="sm" />
                    <IconButton icon={Settings} label="Settings" size="sm" />
                </span>
            }
        />
    );
}
```

## Sticky

Scroll the log: the bar stays at the top of the scroll container.

```tsx
import { TopBar } from 'jarvis-react-ui';

const LINES = Array.from(
    { length: 12 },
    (_, i) => `LOG ${String(i + 1).padStart(2, '0')} · telemetry received`,
);

export default function Sticky() {
    return (
        <div className="h-[220px] w-full overflow-y-auto border border-border px-3 pb-3">
            <TopBar
                position="sticky"
                left={<span className="text-[11px] text-text">EVENT LOG</span>}
                right={<span className="text-[9px] text-text-muted">SCROLL ↓</span>}
            />
            <ul className="mt-4 flex flex-col gap-2 text-[11px] text-text-secondary">
                {LINES.map((line) => (
                    <li key={line}>{line}</li>
                ))}
            </ul>
        </div>
    );
}
```

## Fixed

The default. In this demo the bar is pinned to the demo frame, because the frame creates a
containing block; in an app it is pinned to the viewport.

```tsx
import { BrandMark, TopBar } from 'jarvis-react-ui';

export default function Fixed() {
    return (
        <TopBar
            left={<span className="text-[11px] text-text">09:04:17</span>}
            center={<span className="text-[9px] tracking-[8px] text-text-muted">JARVIS</span>}
            right={<BrandMark />}
        />
    );
}
```

## Accessibility

- The TopBar renders plain `<div>` elements without a landmark role. If it acts as the page header,
  wrap it in a `<header>` element.
- Keep interactive content in the slots keyboard accessible, e.g. `Button`, or `IconButton` with a
  `label`.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `center` | `ReactNode` |  | Content of the centered slot, e.g. a title. |
| `className` | `string` |  | Additional class names for the root element. |
| `left` | `ReactNode` |  | Content of the left slot, e.g. a clock or status text. |
| `position` | `'fixed' \| 'sticky' \| 'static'` | `'fixed'` | `fixed` pins the bar 10px from the top of the viewport (HUD default), `sticky` keeps it in the document flow and sticks it to the top while scrolling, `static` renders it inline. |
| `right` | `ReactNode` |  | Content of the right slot, e.g. a brand mark or actions. |

# BrandMark

The spaced-out `J A R V I S` wordmark in muted text, with an optional `MK XLII` subline. Use it
as the brand in a top bar or a status dock.

```ts
import { BrandMark } from 'jarvis-react-ui';
```

## Wordmark

Without props it renders the wordmark only. `sub` adds the subline below it.

```tsx
import { BrandMark } from 'jarvis-react-ui';

export default function Basic() {
    return (
        <div className="flex items-center gap-16">
            <BrandMark />
            <BrandMark sub />
        </div>
    );
}
```

## In a top bar

The mark is centered in its own box, so it fits any slot of a [TopBar](https://joeyash.github.io/jarvis_ui_lib/components/top-bar.md).

```tsx
import { BrandMark, Pill, TopBar } from 'jarvis-react-ui';

export default function InTopBar() {
    return (
        <TopBar
            position="static"
            left={<span className="text-[11px] text-text">09:04:17</span>}
            center={<BrandMark sub />}
            right={<Pill variant="ok">Online</Pill>}
        />
    );
}
```

## Accessibility

- Renders a `<div>` with two `<span>`s and no role.
- The letters are separated by spaces, so screen readers read them one by one ("J, A, R, V, I,
  S"). When the brand name matters to the user, provide it elsewhere as text, for example in the
  page title.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` |  | Additional class names for the root `<div>`. |
| `sub` | `boolean` | `false` | Adds the `MK XLII` subline below the wordmark. |

# Input

A single-line text field in a hairline HUD frame. It accepts icons or keyboard hints on either
side, comes in two sizes and has an invalid state for validation errors.

```ts
import { Input } from 'jarvis-react-ui';
```

## Basic

`Input` passes every native `<input>` attribute through (`value`, `onChange`, `type`, `name`,
`placeholder`, ...). The ref points at the native `<input>`.

```tsx
import { Input } from 'jarvis-react-ui';

export default function Basic() {
    return <Input aria-label="Callsign" placeholder="Enter callsign" />;
}
```

## Adornments

`startAdornment` and `endAdornment` render inside the frame, before and after the text. Use them for
an icon, a keyboard hint built with `Hint.Key`, a unit or a small action.

```tsx
import { Search } from 'lucide-react';
import { Hint, Input } from 'jarvis-react-ui';

export default function WithAdornments() {
    return (
        <Input
            aria-label="Search docs"
            placeholder="Search docs…"
            startAdornment={<Search size={12} aria-hidden="true" />}
            endAdornment={<Hint.Key>CTRL K</Hint.Key>}
        />
    );
}
```

## Sizes

`sm` is 26px high, `md` (the default) is 32px. The field is 220px wide; set `fullWidth` to fill its
container instead.

```tsx
import { Input } from 'jarvis-react-ui';

export default function Sizes() {
    return (
        <>
            <Input aria-label="Small" size="sm" placeholder="size sm" />
            <Input aria-label="Medium" size="md" placeholder="size md" />
        </>
    );
}
```

## Invalid

`invalid` switches the frame to the error color and sets `aria-invalid` on the input. The component
renders no helper text itself: place the message next to it and link it with `aria-describedby`.

```tsx
import { useId } from 'react';
import { Input } from 'jarvis-react-ui';

export default function Invalid() {
    const helpId = useId();

    return (
        <div className="flex flex-col gap-[6px]">
            <Input
                aria-label="Accent color"
                aria-describedby={helpId}
                defaultValue="#zz00ff"
                invalid
            />
            <span id={helpId} className="text-[10px] text-error">
                Use a hex color such as #4ca8e8.
            </span>
        </div>
    );
}
```

## Controlled

Drive the field with `value` and `onChange` like a native input. Here a clear button appears in the
end adornment once there is text.

```tsx
import { useState } from 'react';
import { Search, X } from 'lucide-react';
import { IconButton, Input } from 'jarvis-react-ui';

export default function Controlled() {
    const [query, setQuery] = useState('');

    return (
        <Input
            aria-label="Filter systems"
            placeholder="Filter systems…"
            value={query}
            onChange={(e) => setQuery(e.target.value)}
            startAdornment={<Search size={12} aria-hidden="true" />}
            endAdornment={
                query === '' ? undefined : (
                    <IconButton icon={X} label="Clear" size="sm" onClick={() => setQuery('')} />
                )
            }
        />
    );
}
```

## Disabled

`disabled` is forwarded to the native input; the frame dims and hover sounds stop.

```tsx
import { Input } from 'jarvis-react-ui';

export default function Disabled() {
    return <Input aria-label="Uplink" placeholder="Uplink offline" disabled />;
}
```

## Styling

`className` goes to the outer frame (border, size, width); `inputClassName` goes to the native
`<input>` element.

## Sound

Hovering the frame plays `hover_button` through the nearest `SfxProvider` (not while disabled).
Typing is silent. See [Sound effects](https://joeyash.github.io/jarvis_ui_lib/getting-started/sound.md).

## Accessibility

- Renders a native `<input>`; all keyboard behavior is the browser's.
- There is no built-in label. Provide a visible `<label htmlFor>` or an `aria-label`; a placeholder
  is not a label.
- `invalid` sets `aria-invalid="true"`. Reference the error message with `aria-describedby`.
- Adornments are decorative by default: mark icons `aria-hidden`. Interactive adornments (such as a
  clear [IconButton](https://joeyash.github.io/jarvis_ui_lib/components/icon-button.md)) need their own accessible name.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` |  | Additional class names for the outer frame `<div>` that holds input and adornments. |
| `endAdornment` | `ReactNode` |  | Content rendered after the text, e.g. a keyboard hint or a clear button. |
| `fullWidth` | `boolean` | `false` | Stretches the field to the width of its container. |
| `inputClassName` | `string` |  | Additional class names for the native `<input>` element. |
| `invalid` | `boolean` | `false` | Marks the field as invalid: error border and `aria-invalid`. |
| `size` | `'sm' \| 'md'` | `'md'` | Height and font size of the field. |
| `startAdornment` | `ReactNode` |  | Content rendered before the text, e.g. an `Icon`. |

Also accepts inherited props from `InputHTMLAttributes` (30), `HTMLAttributes` (54), `AriaAttributes` (53), `DOMAttributes` (169), `RefAttributes` (1), `Attributes` (1).

# Textarea

A multi-line text field in the same hairline frame as [Input](https://joeyash.github.io/jarvis_ui_lib/components/input.md), for notes,
prompts and log entries.

```ts
import { Textarea } from 'jarvis-react-ui';
```

## Basic

`rows` sets the visible lines (3 by default), `size` the font size and padding. The field is 320px
wide; `fullWidth` stretches it to its container. Users can resize it vertically.

```tsx
import { Textarea } from 'jarvis-react-ui';

export default function Basic() {
    return (
        <div className="flex flex-col gap-3">
            <Textarea aria-label="Mission notes" placeholder="Mission notes…" />
            <Textarea aria-label="Compact notes" placeholder="Compact" size="sm" rows={2} />
        </div>
    );
}
```

## Auto resize

`autoResize` grows the field with its content, from `rows` up to `maxRows` lines; beyond that it
scrolls. It works with controlled and uncontrolled values.

```tsx
import { useState } from 'react';
import { Textarea } from 'jarvis-react-ui';

export default function AutoResize() {
    const [text, setText] = useState('Type a few lines: the field grows up to six lines.');

    return (
        <Textarea
            aria-label="Log entry"
            value={text}
            onChange={(e) => setText(e.target.value)}
            autoResize
            rows={2}
            maxRows={6}
        />
    );
}
```

## States

`invalid` shows the error border and sets `aria-invalid`; `disabled` dims the field.

```tsx
import { Textarea } from 'jarvis-react-ui';

export default function States() {
    return (
        <div className="flex flex-col gap-3">
            <Textarea aria-label="Invalid" invalid defaultValue="Checksum mismatch" rows={2} />
            <Textarea aria-label="Disabled" disabled defaultValue="Read only" rows={2} />
        </div>
    );
}
```

## Sound

Hovering plays `hover_button` through the nearest `SfxProvider`. See
[Sound effects](https://joeyash.github.io/jarvis_ui_lib/getting-started/sound.md).

## Accessibility

- Renders a native `<textarea>`; name it with `aria-label` or a `<label htmlFor>`.
- `invalid` sets `aria-invalid`. Describe the error in text and link it with `aria-describedby`.
- The `ref` is forwarded to the textarea.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `autoResize` | `boolean` | `false` | Grows the field with its content instead of scrolling, between `rows` and `maxRows` lines. |
| `className` | `string` |  | Additional class names for the `<textarea>`. |
| `fullWidth` | `boolean` | `false` | Stretches the field to the width of its container. |
| `invalid` | `boolean` | `false` | Marks the field as invalid: error border and `aria-invalid`. |
| `maxRows` | `number` | `12` | Upper limit for `autoResize`, in lines; the field scrolls beyond it. |
| `rows` | `number` | `3` | Visible lines; with `autoResize` the minimum height. |
| `size` | `'sm' \| 'md'` | `'md'` | Font size and padding. |

Also accepts inherited props from `TextareaHTMLAttributes` (14), `HTMLAttributes` (54), `AriaAttributes` (53), `DOMAttributes` (169), `RefAttributes` (1), `Attributes` (1).

# Select

A dropdown to pick one option from a list. The list opens in a portal, so it is never clipped by
a scrolling window body and stays above floating windows.

```ts
import { Select } from 'jarvis-react-ui';
```

## Basic

Pass the options as `options`, each with a unique `value` and a `label`. `placeholder` is shown
while nothing is selected; disabled options can't be picked.

```tsx
import { Select } from 'jarvis-react-ui';

export default function Basic() {
    return (
        <Select
            aria-label="Voice"
            placeholder="Choose a voice…"
            options={[
                { value: 'jarvis', label: 'JARVIS' },
                { value: 'friday', label: 'FRIDAY' },
                { value: 'edith', label: 'EDITH' },
                { value: 'karen', label: 'KAREN', disabled: true },
            ]}
        />
    );
}
```

## Controlled, with icons

Pass `value` and update it in `onValueChange`. `icon` shows content before the label, in the list
and in the trigger.

```tsx
import { useState } from 'react';
import { Globe, Moon, Sun } from 'lucide-react';
import { Select } from 'jarvis-react-ui';

export default function Controlled() {
    const [theme, setTheme] = useState('night');

    return (
        <div className="flex flex-col gap-3">
            <Select
                aria-label="Display mode"
                value={theme}
                onValueChange={setTheme}
                options={[
                    { value: 'night', label: 'Night', icon: <Moon size={12} /> },
                    { value: 'day', label: 'Day', icon: <Sun size={12} /> },
                    { value: 'auto', label: 'Follow location', icon: <Globe size={12} /> },
                ]}
            />
            <span className="text-[10px] text-text-secondary">Value: {theme}</span>
        </div>
    );
}
```

## States

`size="sm"` for dense layouts, `invalid` for validation errors, `disabled` to lock it. With `name`
the value is submitted with a surrounding `<form>`.

```tsx
import { Select } from 'jarvis-react-ui';

const OPTIONS = [
    { value: 'a', label: 'Alpha' },
    { value: 'b', label: 'Bravo' },
];

export default function States() {
    return (
        <div className="flex flex-col gap-3">
            <Select aria-label="Small" size="sm" options={OPTIONS} defaultValue="a" />
            <Select aria-label="Invalid" invalid options={OPTIONS} />
            <Select aria-label="Disabled" disabled options={OPTIONS} defaultValue="b" />
        </div>
    );
}
```

## Sound

Opening plays `menu_open`, closing `menu_close` and picking an option `click`; hovering the trigger
plays `hover_button`. See [Sound effects](https://joeyash.github.io/jarvis_ui_lib/getting-started/sound.md).

## Accessibility

- The trigger is a button with `role="combobox"`, `aria-haspopup="listbox"`, `aria-expanded` and
  `aria-controls`; name it with `aria-label`, `aria-labelledby` or a `<label htmlFor={id}>`.
- ArrowDown, ArrowUp, Enter and Space open the list. In the list, the arrows move the active option
  (`aria-activedescendant`) and skip disabled ones, Home and End jump to the ends, typing letters
  jumps to a matching label, Enter or Space picks it, and Escape closes the list and returns focus to
  the trigger. Escape does not close a surrounding floating window.
- A pointer down outside the list closes it.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `options` (required) | `SelectOption[]` |  | Options in display order. |
| `aria-label` | `string` |  | Accessible name of the trigger. Use it or `aria-labelledby`. |
| `aria-labelledby` | `string` |  | Id of an element that names the select. |
| `className` | `string` |  | Additional class names for the trigger button. |
| `defaultValue` | `string` |  | Initially selected value when uncontrolled. |
| `disabled` | `boolean` | `false` | Disables the select. |
| `fullWidth` | `boolean` | `false` | Stretches the trigger to the width of its container. |
| `id` | `string` |  | Id of the trigger button, e.g. for a `<label htmlFor>`. |
| `invalid` | `boolean` | `false` | Marks the field as invalid: error border and `aria-invalid`. |
| `name` | `string` |  | Name for a hidden input, so the value is submitted with a surrounding `<form>`. |
| `onValueChange` | `((value: string) => void)` |  | Called with the new value when the user picks an option. |
| `placeholder` | `string` | `Select…` | Text shown in the trigger while nothing is selected. |
| `size` | `'sm' \| 'md'` | `'md'` | Height and font size of the trigger. |
| `value` | `string` |  | Controlled selected value. Leave undefined to use `defaultValue`. |

### Type `SelectOption`

One option of a `Select`.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` |  | Text shown in the list and, when selected, in the trigger. Also used for typeahead. |
| `value` (required) | `string` |  | Unique value of the option, reported through `onValueChange`. |
| `disabled` | `boolean` | `false` | Disables the option. |
| `icon` | `ReactNode` |  | Icon or other content shown before the label. |

# Checkbox

A checkbox for options that are submitted or applied together. For a setting that takes effect
immediately, use a [Switch](https://joeyash.github.io/jarvis_ui_lib/components/switch.md).

```ts
import { Checkbox } from 'jarvis-react-ui';
```

## Basic

Without `checked` the checkbox keeps its own state; set the start state with `defaultChecked`.
`size="sm"` makes box and text smaller.

```tsx
import { Checkbox } from 'jarvis-react-ui';

export default function Basic() {
    return (
        <div className="flex flex-col gap-3">
            <Checkbox label="Auto-scan" defaultChecked />
            <Checkbox label="Night mode" />
            <Checkbox label="Telemetry" size="sm" />
            <Checkbox label="Locked" defaultChecked disabled />
        </div>
    );
}
```

## Indeterminate

`indeterminate` shows a dash for a mixed state, typically on a "select all" box when only some
items are selected. Clicking it reports `true`. Control `checked` and `indeterminate` together from
the state of the items.

```tsx
import { useState } from 'react';
import { Checkbox } from 'jarvis-react-ui';

const SYSTEMS = ['Radar', 'Comms', 'Shields'];

export default function Indeterminate() {
    const [active, setActive] = useState<string[]>(['Radar']);
    const all = active.length === SYSTEMS.length;

    return (
        <div className="flex flex-col gap-3">
            <Checkbox
                label="All systems"
                checked={all}
                indeterminate={active.length > 0 && !all}
                onCheckedChange={(on) => setActive(on ? SYSTEMS : [])}
            />
            <div className="flex flex-col gap-2 pl-5">
                {SYSTEMS.map((name) => (
                    <Checkbox
                        key={name}
                        label={name}
                        checked={active.includes(name)}
                        onCheckedChange={(on) =>
                            setActive(on ? [...active, name] : active.filter((n) => n !== name))
                        }
                    />
                ))}
            </div>
        </div>
    );
}
```

## Sound

Hovering plays `hover_button` and toggling plays `click` through the nearest `SfxProvider`. See
[Sound effects](https://joeyash.github.io/jarvis_ui_lib/getting-started/sound.md).

## Accessibility

- A real `<input type="checkbox">` stays in the DOM, visually hidden; the box graphic is
  `aria-hidden`. Space toggles it, and it works in forms with `name` and `value`.
- The `label` wraps the input, so it is the accessible name and clicking it toggles the box.
- `indeterminate` sets the native property, so screen readers announce "mixed".
- The `ref` is forwarded to the input.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` | `boolean` |  | Controlled checked state. Leave undefined to use `defaultChecked`. |
| `className` | `string` |  | Additional class names for the root `<label>` (wraps box and label). |
| `defaultChecked` | `boolean` | `false` | Initial state when uncontrolled. |
| `indeterminate` | `boolean` | `false` | Shows a dash for a mixed state, e.g. a "select all" box when only some items are selected. Clicking it reports `true`. |
| `label` | `ReactNode` |  | Visible label next to the box; also the accessible name. |
| `onCheckedChange` | `((checked: boolean) => void)` |  | Called with the new state when the user toggles the checkbox. |
| `size` | `'sm' \| 'md'` | `'md'` | Box and text size. |

Also accepts inherited props from `InputHTMLAttributes` (28), `HTMLAttributes` (53), `AriaAttributes` (53), `DOMAttributes` (168), `RefAttributes` (1), `Attributes` (1).

# RadioGroup

A set of mutually exclusive options. Use it when all choices should stay visible; for long lists
use a [Select](https://joeyash.github.io/jarvis_ui_lib/components/select.md).

```ts
import { RadioGroup } from 'jarvis-react-ui';
```

## Basic

Pass the options as `items`, each with a unique `value` and a `label`. Without `value` the group
keeps its own state; `defaultValue` sets the start selection.

```tsx
import { RadioGroup } from 'jarvis-react-ui';

export default function Basic() {
    return (
        <RadioGroup
            aria-label="Render quality"
            defaultValue="high"
            items={[
                { value: 'low', label: 'Low' },
                { value: 'high', label: 'High' },
                { value: 'ultra', label: 'Ultra' },
            ]}
        />
    );
}
```

## Descriptions and disabled options

`description` adds a muted second line; `disabled` on an item skips it. Control the group with
`value` and `onValueChange`.

```tsx
import { useState } from 'react';
import { RadioGroup } from 'jarvis-react-ui';

export default function Descriptions() {
    const [mode, setMode] = useState('assist');

    return (
        <div className="flex flex-col gap-3">
            <RadioGroup
                aria-label="Autopilot mode"
                value={mode}
                onValueChange={setMode}
                items={[
                    { value: 'manual', label: 'Manual', description: 'You fly, JARVIS watches.' },
                    { value: 'assist', label: 'Assist', description: 'Course corrections only.' },
                    {
                        value: 'full',
                        label: 'Full',
                        description: 'Requires clearance.',
                        disabled: true,
                    },
                ]}
            />
            <span className="text-[10px] text-text-secondary">Mode: {mode}</span>
        </div>
    );
}
```

## Horizontal

`orientation="horizontal"` puts the options in a row, `size="sm"` makes them smaller.

```tsx
import { RadioGroup } from 'jarvis-react-ui';

export default function Horizontal() {
    return (
        <RadioGroup
            aria-label="Units"
            orientation="horizontal"
            size="sm"
            defaultValue="metric"
            items={[
                { value: 'metric', label: 'Metric' },
                { value: 'imperial', label: 'Imperial' },
            ]}
        />
    );
}
```

## Sound

Hovering an option plays `hover_button` and selecting plays `click` through the nearest
`SfxProvider`. See [Sound effects](https://joeyash.github.io/jarvis_ui_lib/getting-started/sound.md).

## Accessibility

- The group has `role="radiogroup"` (name it with `aria-label` or `aria-labelledby`); each option is
  a button with `role="radio"` and `aria-checked`.
- The group is one Tab stop (roving focus): Tab focuses the selected option, or the first enabled
  one. Arrow keys move the selection and skip disabled options; Home and End jump to the first and
  last option; Space selects the focused option.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `RadioItem[]` |  | Options in display order. |
| `aria-label` | `string` |  | Accessible name of the group. Use it or `aria-labelledby`. |
| `aria-labelledby` | `string` |  | Id of an element that names the group. |
| `className` | `string` |  | Additional class names for the `role="radiogroup"` element. |
| `defaultValue` | `string` |  | Initially selected value when uncontrolled; without it nothing is selected. |
| `disabled` | `boolean` | `false` | Disables the whole group. |
| `onValueChange` | `((value: string) => void)` |  | Called with the new value when the user selects an option. |
| `orientation` | `'vertical' \| 'horizontal'` | `'vertical'` | Stacks the options (`vertical`) or puts them in a row (`horizontal`). |
| `size` | `'sm' \| 'md'` | `'md'` | Dot and text size. |
| `value` | `string` |  | Controlled selected value. Leave undefined to use `defaultValue`. |

### Type `RadioItem`

One option of a `RadioGroup`.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `ReactNode` |  | Visible label; also the accessible name of the option. |
| `value` (required) | `string` |  | Unique value of the option, reported through `onValueChange`. |
| `description` | `ReactNode` |  | Muted second line below the label. |
| `disabled` | `boolean` | `false` | Disables the option. |

# Switch

An on/off toggle for settings that take effect immediately. The track glows in the accent color
when the switch is on.

```ts
import { Switch } from 'jarvis-react-ui';
```

## Uncontrolled

Without `checked` the switch keeps its own state. Set the initial state with `defaultChecked`.

```tsx
import { Switch } from 'jarvis-react-ui';

export default function Uncontrolled() {
    return (
        <>
            <Switch label="Scanlines" />
            <Switch label="Grid" defaultChecked />
        </>
    );
}
```

## Controlled

Pass `checked` and update it in `onCheckedChange`, which receives the new state.

```tsx
import { useState } from 'react';
import { Switch } from 'jarvis-react-ui';

export default function Controlled() {
    const [sound, setSound] = useState(true);

    return (
        <div className="flex flex-col items-start gap-2">
            <Switch label="Sound" checked={sound} onCheckedChange={setSound} />
            <span className="text-[10px] text-text-muted">Audio {sound ? 'online' : 'muted'}</span>
        </div>
    );
}
```

> **Note: onClick**
>
> `onClick` runs before the toggle. Call `event.preventDefault()` in it to veto the change.

## Sizes

```tsx
import { Switch } from 'jarvis-react-ui';

export default function Sizes() {
    return (
        <>
            <Switch size="sm" label="Compact" defaultChecked />
            <Switch size="md" label="Default" defaultChecked />
        </>
    );
}
```

## Disabled

```tsx
import { Switch } from 'jarvis-react-ui';

export default function Disabled() {
    return (
        <>
            <Switch label="Autopilot" disabled />
            <Switch label="Telemetry" defaultChecked disabled />
        </>
    );
}
```

## Sound

Hovering plays `hover_button` and toggling plays `click` through the nearest `SfxProvider`. See
[Sound effects](https://joeyash.github.io/jarvis_ui_lib/getting-started/sound.md).

## Accessibility

- Renders a native `<button type="button">` with `role="switch"` and `aria-checked`, so Space and
  Enter toggle it.
- The `label` is rendered inside the button and becomes its accessible name. Without a `label`,
  pass `aria-label`.
- The track graphic is `aria-hidden`.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `checked` | `boolean` |  | Controlled on/off state. Leave undefined to use `defaultChecked`. |
| `className` | `string` |  | Additional class names for the root `<button role="switch">` (wraps track and label). |
| `defaultChecked` | `boolean` | `false` | Initial state when uncontrolled. |
| `label` | `ReactNode` |  | Visible label next to the track; also the accessible name. |
| `onCheckedChange` | `((checked: boolean) => void)` |  | Called with the new state when the user toggles the switch. |
| `size` | `'sm' \| 'md'` | `'md'` | Track size. |

Also accepts inherited props from `ButtonHTMLAttributes` (10), `HTMLAttributes` (53), `AriaAttributes` (53), `DOMAttributes` (168), `RefAttributes` (1), `Attributes` (1).

# Slider

A horizontal range input for values such as volume, gain or a scan radius. Drag the glowing
thumb, click anywhere on the track, or use the keyboard.

```ts
import { Slider } from 'jarvis-react-ui';
```

## Basic

`label` names the slider and is shown above the track; `showValue` adds the current value on the
right. Without a visible label pass `aria-label`.

```tsx
import { Slider } from 'jarvis-react-ui';

export default function Basic() {
    return <Slider label="Volume" defaultValue={40} showValue />;
}
```

## Range, step and format

`min`, `max` and `step` define the range; the value always snaps to a step. `formatValue` formats
the readout and the value announced by screen readers.

```tsx
import { Slider } from 'jarvis-react-ui';

export default function Range() {
    return (
        <div className="flex flex-col gap-5">
            <Slider
                label="Scan radius"
                min={50}
                max={500}
                step={50}
                defaultValue={200}
                showValue
                formatValue={(v) => `${v} m`}
            />
            <Slider
                label="Gain"
                min={0}
                max={1}
                step={0.05}
                defaultValue={0.6}
                showValue
                formatValue={(v) => `${Math.round(v * 100)} %`}
                size="sm"
            />
        </div>
    );
}
```

## Controlled

Pass `value` and update it in `onValueChange`, which fires on every move. `onValueCommit` fires once
when a drag ends or after a key press: use it for expensive work such as saving a setting.

```tsx
import { useState } from 'react';
import { Metric, Slider } from 'jarvis-react-ui';

export default function Controlled() {
    const [power, setPower] = useState(72);
    const [committed, setCommitted] = useState(72);

    return (
        <div className="flex flex-col gap-3">
            <Metric value={power} unit="%" />
            <Slider
                aria-label="Reactor output"
                value={power}
                onValueChange={setPower}
                onValueCommit={setCommitted}
            />
            <span className="text-[10px] text-text-secondary">Last committed: {committed} %</span>
            <Slider aria-label="Locked" defaultValue={30} disabled />
        </div>
    );
}
```

## Sound

Hovering plays `hover_button`; a drag plays `drag_start` and `drag_end` through the nearest
`SfxProvider`. See [Sound effects](https://joeyash.github.io/jarvis_ui_lib/getting-started/sound.md).

## Accessibility

- The thumb has `role="slider"` with `aria-valuemin`, `aria-valuemax`, `aria-valuenow` and, with
  `formatValue`, `aria-valuetext`. The `label` names it through `aria-labelledby`.
- Arrow keys change the value by one step, PageUp and PageDown by ten steps, Home and End jump to
  `min` and `max`.
- `disabled` removes the thumb from the tab order and sets `aria-disabled`.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-label` | `string` |  | Accessible name when there is no visible `label`. |
| `className` | `string` |  | Additional class names for the root element. |
| `defaultValue` | `number` | `min` | Initial value when uncontrolled. |
| `disabled` | `boolean` | `false` | Disables dragging and keyboard input. |
| `formatValue` | `((value: number) => string)` |  | Formats the value for the readout and for `aria-valuetext`, e.g. `(v) => \`${v} %\``. |
| `fullWidth` | `boolean` | `false` | Stretches the slider to the width of its container instead of 220px. |
| `label` | `ReactNode` |  | Visible label above the track; also the accessible name of the slider. |
| `max` | `number` | `100` | Highest value. |
| `min` | `number` | `0` | Lowest value. |
| `onValueChange` | `((value: number) => void)` |  | Called with every new value while the user drags or presses a key. |
| `onValueCommit` | `((value: number) => void)` |  | Called once with the final value when a drag ends or after a key press. |
| `showValue` | `boolean` | `false` | Shows the formatted value next to the label. |
| `size` | `'sm' \| 'md'` | `'md'` | Track and thumb size. |
| `step` | `number` | `1` | Step between values; the value snaps to it. |
| `value` | `number` |  | Controlled value. Leave undefined to use `defaultValue`. |

Also accepts inherited props from `HTMLAttributes` (53), `AriaAttributes` (52), `DOMAttributes` (168), `RefAttributes` (1), `Attributes` (1).

# CornerBrackets

CornerBrackets draws four small L-shaped marks at the corners of its content, the signature
frame of the HUD. Wrap any box in it to give it the same targeting look as a
[Panel](https://joeyash.github.io/jarvis_ui_lib/components/panel.md).

```ts
import { CornerBrackets } from 'jarvis-react-ui';
```

## Basic

CornerBrackets renders a `relative` wrapper `<div>` around its children and places the brackets 2px
outside the wrapper's edges. Padding on `className` moves the brackets away from the content.

```tsx
import { CornerBrackets } from 'jarvis-react-ui';

export default function Basic() {
    return (
        <CornerBrackets className="p-3">
            <div className="border border-border px-6 py-4 text-[10px] text-text-secondary">
                CPU · 42%
            </div>
        </CornerBrackets>
    );
}
```

## Focused

`focused` brightens the brackets to `--accent-bright` at full opacity. The change fades over 200ms,
so it works well for hover, selection or an active state you keep in your own state.

```tsx
import { useState } from 'react';
import { CornerBrackets, Switch } from 'jarvis-react-ui';

export default function Focused() {
    const [focused, setFocused] = useState(true);

    return (
        <div className="flex flex-col items-center gap-4">
            <CornerBrackets focused={focused} className="p-3">
                <div className="border border-border px-6 py-4 text-[10px] text-accent">
                    {focused ? 'FOCUSED' : 'IDLE'}
                </div>
            </CornerBrackets>
            <Switch label="Focused" size="sm" checked={focused} onCheckedChange={setFocused} />
        </div>
    );
}
```

## Sizes

`size` sets the length of each bracket arm in pixels. The default is 12.

```tsx
import { CornerBrackets } from 'jarvis-react-ui';

const SIZES = [8, 12, 20];

export default function Sizes() {
    return (
        <>
            {SIZES.map((size) => (
                <CornerBrackets key={size} size={size} className="p-3">
                    <div className="px-6 py-4 text-[10px] text-text-secondary">size={size}</div>
                </CornerBrackets>
            ))}
        </>
    );
}
```

> **Note: Panels already have brackets**
>
> [Panel](https://joeyash.github.io/jarvis_ui_lib/components/panel.md) and [TopBar](https://joeyash.github.io/jarvis_ui_lib/components/top-bar.md) draw their own corner brackets. Use
> CornerBrackets for custom surfaces; see [LightTrace](https://joeyash.github.io/jarvis_ui_lib/components/light-trace.md) for a card that
> combines it with the other chrome layers.

## Accessibility

- The four brackets are `aria-hidden` and ignore pointer events; only the children are exposed to
  assistive technology.
- The wrapper is a plain `<div>` without a role. `focused` is purely visual and does not move
  keyboard focus.
- The only motion is a 200ms color and opacity transition when `focused` changes; with
  `prefers-reduced-motion: reduce` the change is instant.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` |  | Content framed by the brackets; the brackets sit 2px outside the wrapper's edges. |
| `className` | `string` |  | Additional class names for the relative wrapper `<div>`, e.g. padding to move the brackets away from the content. |
| `focused` | `boolean` | `false` | Brightens the brackets to `--accent-bright` at full opacity; changes fade over 200ms. |
| `size` | `number` | `12` | Length of each bracket arm in pixels (injected as `--cb-size` on the wrapper). |

# Scanlines

Scanlines lays fine horizontal CRT lines over its content. Use it to give a readout, a metric or
a media tile the look of a HUD display.

```ts
import { Scanlines } from 'jarvis-react-ui';
```

## Basic

Scanlines wraps its children in a `relative`, `overflow-hidden` `<div>` and draws the lines on top
with a screen blend, so the content stays readable. Style the wrapper with `className`.

```tsx
import { Scanlines } from 'jarvis-react-ui';

export default function Basic() {
    return (
        <Scanlines className="w-[260px] border border-border bg-surface px-6 py-4">
            <div className="text-[10px] uppercase tracking-[1px] text-text-secondary">
                NET · 12.3 Mb/s
            </div>
        </Scanlines>
    );
}
```

## Sweep

`sweep` adds a light band that moves across the content in a loop, e.g. while data is loading or
streaming in.

```tsx
import { Scanlines } from 'jarvis-react-ui';

export default function Sweep() {
    return (
        <Scanlines sweep className="w-[260px] border border-border bg-surface px-6 py-4">
            <div className="text-[10px] uppercase tracking-[1px] text-accent">Receiving data…</div>
        </Scanlines>
    );
}
```

For a full-screen scanline layer use [Scene](https://joeyash.github.io/jarvis_ui_lib/components/scene.md), which includes one.

## Accessibility

- The scanline overlay and the sweep band are `aria-hidden` and ignore pointer events; the children
  stay fully accessible and clickable.
- With `prefers-reduced-motion: reduce` both the scanlines and the sweep band are hidden
  (`motion-reduce:hidden`), and only the content remains.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  | Content rendered underneath the scanline overlay. |
| `className` | `string` |  | Additional class names for the wrapper `<div>` (relative, overflow hidden), e.g. border and padding. |
| `sweep` | `boolean` | `false` | Adds a light band that sweeps horizontally across the content in a loop. |

# GridBackground

GridBackground is a faint blueprint grid behind the whole page. It fades out toward the edges
with a radial mask, so it frames the content without competing with it.

```ts
import { GridBackground } from 'jarvis-react-ui';
```

## Basic

The grid is a `fixed`, full-viewport layer with `z-index: 0`. Render it once near the root of your
app and give the content that should sit on top a position (e.g. `relative`). `gridSize` sets the
cell size in pixels; the default is 44.

The demo frames on this site use a GridBackground themselves. Here, the demo frame contains the
fixed layer; in an app it covers the viewport.

```tsx
import { GridBackground } from 'jarvis-react-ui';

export default function Basic() {
    return (
        <>
            <GridBackground gridSize={22} />
            <span className="relative text-[10px] uppercase tracking-[2px] text-text-muted">
                Grid underlay
            </span>
        </>
    );
}
```

## Drift

`drift` scrolls the grid slowly in a loop, by one cell every `gridSize / 10` seconds.

```tsx
import { GridBackground } from 'jarvis-react-ui';

export default function Drift() {
    return (
        <>
            <GridBackground drift gridSize={66} />
            <span className="relative text-[10px] uppercase tracking-[2px] text-text-muted">
                Drifting grid
            </span>
        </>
    );
}
```

For a complete backdrop with grid, stars, scanlines and vignette use [Scene](https://joeyash.github.io/jarvis_ui_lib/components/scene.md).

## Accessibility

- The layer is `aria-hidden` and ignores pointer events.
- The grid is very low contrast and carries no information. Its lines are tinted from `--accent`.
- With `prefers-reduced-motion: reduce` the `drift` animation stops and the grid stays still.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` |  | Additional class names for the fixed, full-viewport layer `<div>`, e.g. a z-index utility. |
| `drift` | `boolean` | `false` | Slowly scrolls the grid diagonally in a loop; stays still under `prefers-reduced-motion: reduce`. |
| `gridSize` | `number` | `44` | Size of one grid cell in pixels (injected as `--jlib-grid-size`). |

# GlowFrame

GlowFrame is a hairline frame with an accent glow around its content. Use it to highlight a
single element, such as the current voice state or an active readout.

```ts
import { GlowFrame } from 'jarvis-react-ui';
```

## Static glow

By default the frame shows the `--glow` halo; `strong` switches to the larger `--glow-strong`. The
frame is a `<div>` with a 1px `--accent-dim` border and 2px radius; add padding with `className`.

```tsx
import { GlowFrame } from 'jarvis-react-ui';

export default function Static() {
    return (
        <>
            <GlowFrame className="px-6 py-4">
                <span className="text-[10px] text-text-secondary">Default glow</span>
            </GlowFrame>
            <GlowFrame strong className="px-6 py-4">
                <span className="text-[10px] text-accent">LISTENING…</span>
            </GlowFrame>
        </>
    );
}
```

## Breathe

`breathe` replaces the static glow with a slow pulse between `--glow` and `--glow-strong`.

```tsx
import { GlowFrame } from 'jarvis-react-ui';

export default function Breathe() {
    return (
        <GlowFrame breathe className="px-6 py-4">
            <span className="text-[10px] uppercase tracking-[1px] text-accent">Standby</span>
        </GlowFrame>
    );
}
```

## Accessibility

- GlowFrame is a plain `<div>` without a role; the glow is purely visual. Do not rely on it alone
  to convey state, also put the state into text.
- With `prefers-reduced-motion: reduce` the `breathe` pulse stops and the static glow (`--glow`, or
  `--glow-strong` with `strong`) is shown instead.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  | Content inside the glowing frame. |
| `breathe` | `boolean` | `false` | Pulses the glow in a slow loop; under `prefers-reduced-motion: reduce` the static glow is shown instead. |
| `className` | `string` |  | Additional class names for the frame `<div>`, e.g. padding. |
| `strong` | `boolean` | `false` | Uses the stronger `--glow-strong` halo instead of `--glow` for the static glow (also the reduced-motion fallback of `breathe`). |

# Reticle

Reticle is a small crosshair glyph. Use it as a decorative marker next to labels, in corners or
on targets.

```ts
import { Reticle } from 'jarvis-react-ui';
```

## Sizes

`size` sets width and height in pixels; the default is 12. The lines are 1px wide at every size.

```tsx
import { Reticle } from 'jarvis-react-ui';

export default function Sizes() {
    return (
        <div className="flex items-center gap-6">
            <Reticle size={10} />
            <Reticle />
            <Reticle size={20} />
            <Reticle size={32} />
        </div>
    );
}
```

## In a heading

The lines use `currentColor` and default to the accent color. Change it with a text color utility on
`className`, e.g. `text-text-muted`.

```tsx
import { Reticle } from 'jarvis-react-ui';

export default function InHeading() {
    return (
        <div className="flex items-center gap-2">
            <Reticle size={10} className="text-text-muted" />
            <span className="text-[10px] uppercase tracking-[2px] text-text-secondary">
                Target lock
            </span>
            <Reticle size={10} className="text-text-muted" />
        </div>
    );
}
```

## Accessibility

- Reticle renders a `<span role="presentation">` that is `aria-hidden` by default.
- If the crosshair carries meaning, set `aria-hidden={false}` and put the meaning into nearby text;
  the glyph itself has no accessible name.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-hidden` | `boolean \| 'true' \| 'false'` | `'true'` | Hides the crosshair from assistive technology; leave it on for decorative use. |
| `className` | `string` |  | Additional class names for the root `<span>`; set the line color with a text color utility, e.g. `text-text-muted`. |
| `size` | `number` | `12` | Width and height of the crosshair in pixels. |

# LightTrace

LightTrace sends four short strips of light around the border of its parent. It marks a surface
as live or active.

```ts
import { LightTrace } from 'jarvis-react-ui';
```

## Basic

LightTrace is absolutely positioned 1px outside its parent's padding box, so it runs over a 1px
border. Give the parent `position: relative` (the `relative` utility). One full lap takes six
seconds.

```tsx
import { LightTrace } from 'jarvis-react-ui';

export default function Basic() {
    return (
        <div className="relative w-[280px] border border-border px-6 py-4">
            <LightTrace />
            <span className="text-[10px] text-text-secondary">Uplink active</span>
        </div>
    );
}
```

## Color

`color` takes any CSS color. It tints the tails of the strips, and the bright center and its glow
become a lightened mix of the same color, so the whole trace follows it. Without `color` the tails
use `--accent` and the center `--accent-bright`. Prefer theme variables such as `var(--warning)`.

```tsx
import { LightTrace } from 'jarvis-react-ui';

export default function Color() {
    return (
        <div className="relative w-[280px] border border-border px-6 py-4">
            <LightTrace color="var(--warning)" />
            <span className="text-[10px] text-warning">Thermal warning</span>
        </div>
    );
}
```

## Building a custom card

LightTrace, [PanelBloom](https://joeyash.github.io/jarvis_ui_lib/components/panel-bloom.md), [PanelRails](https://joeyash.github.io/jarvis_ui_lib/components/panel-rails.md) and
[CornerBrackets](https://joeyash.github.io/jarvis_ui_lib/components/corner-brackets.md) are the layers a [Panel](https://joeyash.github.io/jarvis_ui_lib/components/panel.md) is made of.
Combine them to give your own surfaces the same chrome. Put the layers first and give the content
`relative` so it paints above them.

```tsx
import { useState } from 'react';
import { CornerBrackets, LightTrace, PanelBloom, PanelRails, Switch } from 'jarvis-react-ui';

export default function CustomCard() {
    const [active, setActive] = useState(true);

    return (
        <div className="flex flex-col items-center gap-4">
            <CornerBrackets focused={active}>
                <div className="relative h-[120px] w-[260px] border border-border bg-surface">
                    <PanelBloom active={active} />
                    <PanelRails visible={active} />
                    <LightTrace />
                    <div className="relative border-b border-border px-3 py-[6px] text-[9px] uppercase tracking-[2px] text-text-secondary">
                        Reactor core
                    </div>
                    <div className="relative px-3 py-2 text-[11px] text-text">Output 3.2 GW</div>
                </div>
            </CornerBrackets>
            <Switch label="Active" size="sm" checked={active} onCheckedChange={setActive} />
        </div>
    );
}
```

## Accessibility

- The trace is `aria-hidden` and ignores pointer events.
- With `prefers-reduced-motion: reduce` the strips are not animated and not drawn; the trace is
  hidden.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` |  | Additional class names for the absolutely positioned trace `<span>`. |
| `color` | `string` | `'var(--accent)'` | CSS color of the moving light strips (sets `--lt-color`). It tints the tails, and the bright center and glow become a lightened mix of the same color. Without it the tails use `--accent` and the center `--accent-bright`. |

# PanelBloom

PanelBloom is a soft accent glow that fills a surface from its top and bottom edges. Use it to
show that a surface is focused or active.

```ts
import { PanelBloom } from 'jarvis-react-ui';
```

## Active

PanelBloom covers its parent (`position: absolute; inset: 0`), so the parent needs `relative`.
When `active` is false the bloom is invisible; turning it on fades it in over 300ms and starts a
slow brightness pulse. Put content after the bloom and give it `relative` so it paints on top.

```tsx
import { useState } from 'react';
import { PanelBloom, Switch } from 'jarvis-react-ui';

export default function Basic() {
    const [active, setActive] = useState(true);

    return (
        <div className="flex flex-col items-center gap-4">
            <div className="relative flex h-[90px] w-[260px] items-center justify-center border border-accent">
                <PanelBloom active={active} />
                <span className="relative text-[9px] uppercase tracking-[1px] text-accent">
                    {active ? 'Bloom active' : 'Bloom off'}
                </span>
            </div>
            <Switch label="Active" size="sm" checked={active} onCheckedChange={setActive} />
        </div>
    );
}
```

[Panel](https://joeyash.github.io/jarvis_ui_lib/components/panel.md) has its own bloom tied to `focused`. To combine PanelBloom with the other
chrome layers, see the custom card on [LightTrace](https://joeyash.github.io/jarvis_ui_lib/components/light-trace.md).

## Accessibility

- The bloom is `aria-hidden` and ignores pointer events. It is a purely visual cue, so pair it with
  a state that is exposed otherwise, e.g. `aria-selected` or a text label.
- The pulse runs while `active` is true. With `prefers-reduced-motion: reduce` the bloom appears
  and disappears without fade or pulse and stays at a constant brightness.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `active` | `boolean` | `false` | Fades the bloom in and makes it pulse in brightness; when false it is invisible. Under `prefers-reduced-motion: reduce` it appears without fade or pulse. |
| `className` | `string` |  | Additional class names for the absolutely positioned bloom `<div>`. |

# PanelRails

PanelRails adds two dashed vertical rails just outside the left and right edges of a surface.
Use them as an extra highlight for a hovered or selected panel.

```ts
import { PanelRails } from 'jarvis-react-ui';
```

## Visible

PanelRails covers its parent (`position: absolute; inset: 0`), so the parent needs `relative` and
must not clip overflow: the rails sit 4px outside its edges. They start 26px below the top, leaving
room for a header strip, and end 4px above the bottom. `visible` fades them in over 300ms.

```tsx
import { useState } from 'react';
import { PanelRails, Switch } from 'jarvis-react-ui';

export default function Basic() {
    const [visible, setVisible] = useState(true);

    return (
        <div className="flex flex-col items-center gap-4">
            <div className="relative h-[110px] w-[260px] border border-border bg-surface">
                <PanelRails visible={visible} />
                <div className="border-b border-border px-3 py-[6px] text-[9px] uppercase tracking-[2px] text-text-secondary">
                    Telemetry
                </div>
            </div>
            <Switch label="Visible" size="sm" checked={visible} onCheckedChange={setVisible} />
        </div>
    );
}
```

To combine PanelRails with the other chrome layers, see the custom card on
[LightTrace](https://joeyash.github.io/jarvis_ui_lib/components/light-trace.md).

## Accessibility

- The rails are `aria-hidden` and ignore pointer events. They are a purely visual cue.
- The only motion is the 300ms opacity transition when `visible` changes.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` |  | Additional class names for the absolutely positioned rails container `<div>`. |
| `visible` | `boolean` | `false` | Fades the dashed rails in; when false they are fully transparent. |

# ViewportCorners

ViewportCorners pins four large L-shaped marks to the corners of the screen, each with a small
glowing dot. They frame the whole HUD like the corners of a viewfinder.

```ts
import { ViewportCorners } from 'jarvis-react-ui';
```

## Basic

The corners are `position: fixed`, 6px from each edge, with `z-index: 4`. Render them once near the
root of your app. In this demo the frame contains them; in an app they sit in the viewport corners.

```tsx
import { ViewportCorners } from 'jarvis-react-ui';

export default function Basic() {
    return (
        <>
            <ViewportCorners />
            <span className="text-[10px] uppercase tracking-[2px] text-text-muted">Viewport</span>
        </>
    );
}
```

`HUDShell` renders ViewportCorners by default (`viewportCorners`). See
[Scene](https://joeyash.github.io/jarvis_ui_lib/components/scene.md) for a full backdrop that combines them with a Reactor.

## Accessibility

- All four corners are `aria-hidden` and ignore pointer events, so they never block clicks on
  content underneath.
- There is no wrapper element: `className` is applied to **each** of the four corner `<span>`s, so
  a utility such as `opacity-30` affects all corners alike. Every corner also carries a position
  class (`tl`, `tr`, `bl`, `br`) for corner-specific styling in your own CSS.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` |  | Additional class names applied to **each** of the four fixed corner `<span>` elements (there is no wrapper element), e.g. `opacity-30` dims all four corners. Position-specific styling can target the `tl`, `tr`, `bl` and `br` classes the corners also carry. |

# StarField

StarField scatters tiny twinkling stars over a surface. Use it for a deep-space backdrop behind
the orb or inside a dark tile.

```ts
import { StarField } from 'jarvis-react-ui';
```

## Basic

StarField covers its parent (`position: absolute; inset: 0`) at 60% opacity, so the parent needs
`relative` and usually a dark background. Each star twinkles on a four-second loop with its own
phase.

```tsx
import { StarField } from 'jarvis-react-ui';

export default function Basic() {
    return (
        <div className="relative flex h-[120px] w-[320px] items-center justify-center overflow-hidden border border-border bg-bg">
            <StarField />
            <span className="relative text-[10px] uppercase tracking-[2px] text-text-muted">
                Deep space
            </span>
        </div>
    );
}
```

## Count

`count` sets the number of stars; the default is 60. Star positions are computed deterministically
from their index, so the same count always produces the same sky, on the server and on the client.

```tsx
import { StarField } from 'jarvis-react-ui';

const COUNTS = [20, 60, 150];

export default function Count() {
    return (
        <>
            {COUNTS.map((count) => (
                <div
                    key={count}
                    className="relative flex h-[90px] w-[160px] items-end justify-center overflow-hidden border border-border bg-bg pb-2"
                >
                    <StarField count={count} />
                    <span className="relative text-[9px] text-text-muted">count={count}</span>
                </div>
            ))}
        </>
    );
}
```

[Scene](https://joeyash.github.io/jarvis_ui_lib/components/scene.md) includes a StarField; its `starCount` prop sets the count.

## Accessibility

- The star layer is `aria-hidden` and ignores pointer events.
- With `prefers-reduced-motion: reduce` the twinkle stops and every star stays at a constant,
  medium brightness.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` |  | Additional class names for the absolutely positioned star layer `<div>`. |
| `count` | `number` | `60` | Number of stars; positions are deterministic, so the same count always gives the same sky. The twinkle stops under `prefers-reduced-motion: reduce`. |

# Reactor

Reactor is a large, soft hemisphere of accent light rising from the bottom of the screen, with a
thin arc at its rim. It gives the space below the orb an ambient glow.

```ts
import { Reactor } from 'jarvis-react-ui';
```

## Basic

Reactor is a 900px circle, `position: fixed`, centered horizontally and pushed 360px below the
bottom edge, with `z-index: 0`. Render it once near the root of your app, after the backdrop, and
give content on top a position. The size is fixed and tuned for full-height viewports; in the
shorter demo frame only the lower part of the glow is visible.

```tsx
import { Reactor } from 'jarvis-react-ui';

export default function Basic() {
    return (
        <>
            <Reactor />
            <span className="relative text-[10px] uppercase tracking-[2px] text-text-muted">
                Reactor glow
            </span>
        </>
    );
}
```

`HUDShell` renders a Reactor by default (`reactor`). See
[Scene](https://joeyash.github.io/jarvis_ui_lib/components/scene.md) for a full backdrop that layers Reactor on top of the scene.

## Accessibility

- The glow is `aria-hidden`, ignores pointer events and does not animate. It is tinted from
  `--accent`.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` |  | Additional class names for the fixed, bottom-centered glow `<div>`. |

# Scene

Scene is the full-screen backdrop of the HUD: a dark radial background with a drifting grid,
scanlines, stars, a vignette, film grain and a horizon glow. Render it once behind everything
else.

```ts
import { Scene } from 'jarvis-react-ui';
```

## Basic

Scene is a `fixed`, full-viewport layer with `z-index: 0` and an opaque background. Content that
should appear above it needs a position (e.g. `relative`) and must come after it in the tree. In
this demo the frame contains the layer; in an app it covers the viewport.

```tsx
import { Scene } from 'jarvis-react-ui';

export default function Basic() {
    return (
        <>
            <Scene />
            <span className="relative text-[10px] uppercase tracking-[2px] text-text-secondary">
                J.A.R.V.I.S.
            </span>
        </>
    );
}
```

## Layers

`grid`, `stars` and `scanlines` switch the optional layers off; all three are on by default. The
background, vignette, grain and horizon glow are always drawn.

```tsx
import { Scene } from 'jarvis-react-ui';

export default function Layers() {
    return (
        <>
            <Scene stars={false} scanlines={false} />
            <span className="relative text-[10px] uppercase tracking-[2px] text-text-secondary">
                Grid only
            </span>
        </>
    );
}
```

## Star count

`starCount` sets the number of stars in the built-in [StarField](https://joeyash.github.io/jarvis_ui_lib/components/star-field.md); the
default is 60. Use fewer for a calmer backdrop or more for a denser sky.

```tsx
import { Scene } from 'jarvis-react-ui';

export default function StarCount() {
    return (
        <>
            <Scene grid={false} scanlines={false} starCount={200} />
            <span className="relative text-[10px] uppercase tracking-[2px] text-text-secondary">
                200 stars
            </span>
        </>
    );
}
```

## Backdrop

Combine Scene with a [Reactor](https://joeyash.github.io/jarvis_ui_lib/components/reactor.md) and [ViewportCorners](https://joeyash.github.io/jarvis_ui_lib/components/viewport-corners.md)
for the complete HUD backdrop, then put your panels on top. `HUDShell`
renders exactly this stack for you, with props to toggle each piece.

```tsx
import { Panel, Reactor, Scene, ViewportCorners } from 'jarvis-react-ui';

export default function Backdrop() {
    return (
        <>
            <Scene />
            <Reactor />
            <ViewportCorners />
            <Panel title="Diagnostics" className="relative h-[120px] w-[280px]">
                <span className="text-text-secondary">All subsystems nominal.</span>
            </Panel>
        </>
    );
}
```

## Accessibility

- The whole backdrop is `aria-hidden`. Its layers ignore pointer events.
- With `prefers-reduced-motion: reduce` the grid drift and the star twinkle stop, so the backdrop
  is static. The grid and stars stay visible.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` |  | Additional class names for the fixed, full-viewport backdrop `<div>`. |
| `grid` | `boolean` | `true` | Shows the drifting background grid; the drift stops under `prefers-reduced-motion`. |
| `scanlines` | `boolean` | `true` | Shows the fine horizontal scanline overlay. |
| `starCount` | `number` | `60` | Number of stars in the StarField; ignored when `stars` is false. |
| `stars` | `boolean` | `true` | Shows a twinkling StarField (`starCount` stars); the twinkle stops under `prefers-reduced-motion`. |

# PushToTalkButton

The round microphone button of the voice HUD. It toggles the mic and, while `active`, shows two
pulsing rings and a stronger glow so the user can see that JARVIS is listening.

```ts
import { PushToTalkButton } from 'jarvis-react-ui';
```

## Toggle the microphone

The button is fully controlled: keep the mic state yourself, pass it as `active` and flip it in
`onClick`. `onClick` is a normal button click handler and receives the click event; a handler
without arguments such as `() => setLive((v) => !v)` works too. A dashed rim rotates slowly in both
states.

```tsx
import { useState } from 'react';
import { PushToTalkButton } from 'jarvis-react-ui';

export default function Toggle() {
    const [live, setLive] = useState(false);

    return (
        <div className="flex flex-col items-center gap-4">
            <PushToTalkButton active={live} onClick={() => setLive((v) => !v)} />
            <span className="text-[10px] uppercase tracking-[1px] text-text-muted">
                Mic {live ? 'live' : 'off'}
            </span>
        </div>
    );
}
```

## Hold to talk

All native `<button>` attributes and events are forwarded, including `disabled`, `id`, `ref` and
the pointer and keyboard events. For walkie-talkie style input, turn the mic on in `onPointerDown`
and off in `onPointerUp`; also stop on `onPointerLeave` and `onPointerCancel` so the mic does not
stay live when the pointer slides off or the browser cancels the gesture. `onKeyDown`/`onKeyUp` for
Space give keyboard users the same hold behavior (ignore `e.repeat` while the key is held).

```tsx
import { useState } from 'react';
import { PushToTalkButton } from 'jarvis-react-ui';

export default function HoldToTalk() {
    const [live, setLive] = useState(false);
    const start = () => setLive(true);
    const stop = () => setLive(false);

    return (
        <div className="flex flex-col items-center gap-4">
            <PushToTalkButton
                active={live}
                aria-label="Hold to talk"
                onPointerDown={start}
                onPointerUp={stop}
                onPointerLeave={stop}
                onPointerCancel={stop}
                onKeyDown={(e) => {
                    if (e.key === ' ' && !e.repeat) start();
                }}
                onKeyUp={(e) => {
                    if (e.key === ' ') stop();
                }}
            />
            <span className="text-[10px] uppercase tracking-[1px] text-text-muted">
                {live ? 'Listening · release to send' : 'Hold to talk'}
            </span>
        </div>
    );
}
```

## Custom content

`children` replace the default `Mic` icon. Mark the icon `aria-hidden` and describe the action with
`aria-label`, because the button has no visible text.

```tsx
import { useState } from 'react';
import { Radio } from 'lucide-react';
import { PushToTalkButton } from 'jarvis-react-ui';

export default function CustomContent() {
    const [open, setOpen] = useState(false);

    return (
        <PushToTalkButton
            active={open}
            onClick={() => setOpen((v) => !v)}
            aria-label="Open radio channel"
        >
            <Radio size={24} strokeWidth={1.8} aria-hidden="true" />
        </PushToTalkButton>
    );
}
```

> **Warning: ariaLabel is deprecated**
>
> The `ariaLabel` prop still works but is deprecated. Use the standard `aria-label` attribute
> instead; when both are set, `aria-label` wins.

## With the orb state

In an assistant UI the button usually drives the orb state (`AppOrbState`) rather than a plain
boolean. Here a click moves `idle` to `listening`, a second click ends the turn (`thinking`), and the
reply plays out as `speaking` before returning to `idle`. A [WaveformMeter](https://joeyash.github.io/jarvis_ui_lib/components/waveform-meter.md)
on each side runs while audio flows, and a [StatusLabel](https://joeyash.github.io/jarvis_ui_lib/components/status-label.md) names the state.

```tsx
import { useEffect, useState } from 'react';
import { PushToTalkButton, StatusLabel, WaveformMeter } from 'jarvis-react-ui';
import type { AppOrbState } from 'jarvis-react-ui';

/** States that advance on their own: [next state, delay in ms]. */
const AUTO_NEXT: Partial<Record<AppOrbState, [AppOrbState, number]>> = {
    thinking: ['speaking', 1200],
    speaking: ['idle', 2400],
};

export default function VoiceLoop() {
    const [state, setState] = useState<AppOrbState>('idle');

    useEffect(() => {
        const next = AUTO_NEXT[state];
        if (next === undefined) return;
        const id = setTimeout(() => setState(next[0]), next[1]);
        return () => clearTimeout(id);
    }, [state]);

    function handleClick() {
        setState((s) => (s === 'idle' ? 'listening' : s === 'listening' ? 'thinking' : s));
    }

    const audible = state === 'listening' || state === 'speaking';

    return (
        <div className="flex flex-col items-center gap-5">
            <div className="flex items-center gap-6">
                <WaveformMeter active={audible} />
                <PushToTalkButton active={state === 'listening'} onClick={handleClick} />
                <WaveformMeter active={audible} mirrored />
            </div>
            <StatusLabel state={state} />
        </div>
    );
}
```

For a global keyboard shortcut (for example Space anywhere on the page), listen for
`keydown`/`keyup` in your app and update `active` yourself; a [Hint](https://joeyash.github.io/jarvis_ui_lib/components/hint.md) can advertise
the key.

## Sound

Hovering plays `hover_button` and clicking plays `click` through the nearest `SfxProvider`. Without a
provider the button stays silent. Pointer and key handlers you pass do not play extra sounds. See
[Sound effects](https://joeyash.github.io/jarvis_ui_lib/getting-started/sound.md).

## Accessibility

- Renders a native `<button type="button">`, so it is focusable and Enter and Space activate it.
  `disabled` disables it and dims it.
- `aria-label` (default `Push to talk`) is the accessible name; the icon is decorative. The
  deprecated `ariaLabel` prop is used only when `aria-label` is not set.
- `aria-pressed` mirrors `active`, so screen readers announce it as a toggle button that is pressed
  while the mic is live. Pass `aria-pressed` yourself to override it.
- The focus ring (2px accent outline) is visible on keyboard focus only (`focus-visible`).

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `active` | `boolean` | `false` | Whether the microphone is live; shows the pulse rings and a stronger glow, and sets `aria-pressed`. |
| `aria-label` | `string` | `'Push to talk'` | Accessible name of the button, rendered as `aria-label`. Wins over the deprecated `ariaLabel`. |
| `ariaLabel` | `string` |  | Accessible name of the button. @deprecated Use the standard `aria-label` attribute instead; `aria-label` wins when both are set. |
| `children` | `ReactNode` |  | Content of the button; replaces the default microphone icon when set. |
| `className` | `string` |  | Extra classes for the root `<button>` element. |
| `onClick` | `MouseEventHandler<HTMLButtonElement>` |  | Called when the button is clicked, after the `click` sound plays. Handlers that take no arguments (`() => void`) work as well. |

Also accepts inherited props from `ButtonHTMLAttributes` (10), `HTMLAttributes` (54), `AriaAttributes` (52), `DOMAttributes` (168), `RefAttributes` (1), `Attributes` (1).

# WaveformMeter

A row of animated accent bars that signals live audio, such as the user speaking or JARVIS
answering. It is purely decorative and does not measure a real signal.

```ts
import { WaveformMeter } from 'jarvis-react-ui';
```

## Active and inactive

The meter animates by default. Set `active={false}` when no audio flows: the bars shrink to dim 3px
stubs and the animation pauses, so the layout does not jump.

```tsx
import { WaveformMeter } from 'jarvis-react-ui';

export default function ActiveInactive() {
    return (
        <>
            <WaveformMeter />
            <WaveformMeter active={false} />
        </>
    );
}
```

## Bar count

`barCount` sets the number of bars (12 by default). Every bar gets its own animation delay, so
meters of any length ripple instead of moving in sync.

```tsx
import { WaveformMeter } from 'jarvis-react-ui';

export default function BarCount() {
    return (
        <div className="flex items-end gap-8">
            <WaveformMeter barCount={6} />
            <WaveformMeter />
            <WaveformMeter barCount={24} />
        </div>
    );
}
```

## Mirrored

`mirrored` flips the meter horizontally. Use a normal and a mirrored meter on both sides of a label
or a [PushToTalkButton](https://joeyash.github.io/jarvis_ui_lib/components/push-to-talk-button.md) for a symmetric layout.

```tsx
import { WaveformMeter } from 'jarvis-react-ui';

export default function Mirrored() {
    return (
        <div className="flex items-center gap-4">
            <WaveformMeter />
            <span className="text-[10px] uppercase tracking-[2px] text-accent-bright">
                Voice in
            </span>
            <WaveformMeter mirrored />
        </div>
    );
}
```

## With the orb state

Drive `active` from the orb state: the meter usually runs while the state is `listening` or
`speaking` and rests otherwise. This demo cycles through the states on a timer; the
[PushToTalkButton](https://joeyash.github.io/jarvis_ui_lib/components/push-to-talk-button.md) page shows a full voice turn.

```tsx
import { useEffect, useState } from 'react';
import { StatusLabel, WaveformMeter } from 'jarvis-react-ui';
import type { AppOrbState } from 'jarvis-react-ui';

const CYCLE: AppOrbState[] = ['idle', 'listening', 'thinking', 'speaking', 'follow_up', 'working'];

export default function OrbStateCycle() {
    const [index, setIndex] = useState(0);
    const state = CYCLE[index % CYCLE.length] ?? 'idle';
    const audible = state === 'listening' || state === 'speaking';

    useEffect(() => {
        const id = setInterval(() => setIndex((i) => i + 1), 1800);
        return () => clearInterval(id);
    }, []);

    return (
        <div className="flex items-center gap-6">
            <WaveformMeter active={audible} />
            <StatusLabel state={state} />
            <WaveformMeter active={audible} mirrored />
        </div>
    );
}
```

For a smaller meter that sits inline with text, use [WaveStrip](https://joeyash.github.io/jarvis_ui_lib/components/wave-strip.md).

## Accessibility

- The meter is `aria-hidden`: it carries no information a screen reader user needs. Announce the
  voice state in text, for example with [StatusLabel](https://joeyash.github.io/jarvis_ui_lib/components/status-label.md).
- The bars animate continuously while `active`; turn the meter off when audio stops.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `active` | `boolean` | `true` | Whether the bars animate; when `false` they collapse to dim 3px stubs. |
| `barCount` | `number` | `12` | Number of bars to render; every bar gets its own staggered animation delay. |
| `className` | `string` |  | Extra classes for the root `<div>` element. |
| `mirrored` | `boolean` | `false` | Flips the meter horizontally, for the right-hand side of a symmetric layout. |

# WaveStrip

A compact, seven-bar waveform that sits inline with text, for example next to a "now playing"
caption. It is the small sibling of [WaveformMeter](https://joeyash.github.io/jarvis_ui_lib/components/waveform-meter.md).

```ts
import { WaveStrip } from 'jarvis-react-ui';
```

## Inline with text

WaveStrip renders a 12px tall `inline-flex` `<span>`, so it lines up with small caption text. Put a
`mirrored` strip on the other side of the text for a symmetric look.

```tsx
import { WaveStrip } from 'jarvis-react-ui';

export default function NowPlaying() {
    return (
        <div className="flex items-center gap-2 text-[10px] uppercase tracking-[1px] text-text-secondary">
            <WaveStrip />
            <span>Now playing · Back in Black</span>
            <WaveStrip mirrored />
        </div>
    );
}
```

## Paused

With `active={false}` the bars collapse to dim 2px stubs and stop moving. Toggle it with your
playback state.

```tsx
import { useState } from 'react';
import { Pause, Play } from 'lucide-react';
import { IconButton, WaveStrip } from 'jarvis-react-ui';

export default function Paused() {
    const [playing, setPlaying] = useState(false);

    return (
        <div className="flex items-center gap-3 text-[10px] uppercase tracking-[1px] text-text-secondary">
            <IconButton
                icon={playing ? Pause : Play}
                label={playing ? 'Pause' : 'Play'}
                size="sm"
                onClick={() => setPlaying((v) => !v)}
            />
            <WaveStrip active={playing} />
            <span>{playing ? 'Playing' : 'Paused'}</span>
        </div>
    );
}
```

## Accessibility

- The strip is `aria-hidden`; the text next to it must carry the meaning (for example "Playing" or
  "Paused").
- It has no interactive behavior and plays no sound.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `active` | `boolean` | `true` | Whether the seven bars animate; when `false` they collapse to dim 2px stubs. |
| `className` | `string` |  | Extra classes for the root `<span>` element. |
| `mirrored` | `boolean` | `false` | Flips the strip horizontally, for the trailing side of a label. |

# StatusLabel

A two-line caption for the orb: the current voice state on top and a spaced-out brand mark
below. Place it under the orb or the [PushToTalkButton](https://joeyash.github.io/jarvis_ui_lib/components/push-to-talk-button.md).

```ts
import { StatusLabel } from 'jarvis-react-ui';
```

## States

`state` takes an `AppOrbState` and maps it to a built-in text. Every state except `idle` is shown
in the bright accent color.

| `state`     | Text           |
| ----------- | -------------- |
| `idle`      | `READY`        |
| `listening` | `listening...` |
| `thinking`  | `thinking...`  |
| `speaking`  | `speaking...`  |
| `follow_up` | `follow-up...` |
| `working`   | `working...`   |

```tsx
import { StatusLabel } from 'jarvis-react-ui';
import type { AppOrbState } from 'jarvis-react-ui';

const STATES: AppOrbState[] = ['idle', 'listening', 'thinking', 'speaking', 'follow_up', 'working'];

export default function States() {
    return (
        <div className="grid grid-cols-2 gap-6 sm:grid-cols-3">
            {STATES.map((state) => (
                <div key={state} className="flex flex-col items-center gap-2">
                    <StatusLabel state={state} />
                    <code className="text-[9px] text-text-muted">{state}</code>
                </div>
            ))}
        </div>
    );
}
```

## Custom texts and localization

`labels` overrides the text per state, for example to translate it. It is a partial map: states you
leave out keep their built-in text.

```tsx
import { StatusLabel } from 'jarvis-react-ui';
import type { AppOrbState } from 'jarvis-react-ui';

const GERMAN: Partial<Record<AppOrbState, string>> = {
    idle: 'BEREIT',
    listening: 'hört zu...',
    thinking: 'denkt nach...',
    speaking: 'spricht...',
    follow_up: 'Rückfrage...',
    working: 'arbeitet...',
};

export default function Localized() {
    return (
        <div className="flex gap-10">
            <StatusLabel state="idle" labels={GERMAN} />
            <StatusLabel state="thinking" labels={GERMAN} />
            <StatusLabel state="follow_up" labels={GERMAN} />
        </div>
    );
}
```

## Custom brand

`brand` replaces the default `J A R V I S` mark. Spaces between the letters are part of the string;
the component only adds letter spacing.

```tsx
import { StatusLabel } from 'jarvis-react-ui';

export default function CustomBrand() {
    return <StatusLabel state="thinking" brand="F R I D A Y" />;
}
```

## With the orb state

Feed StatusLabel the same state as your orb and pair it with
[WaveformMeter](https://joeyash.github.io/jarvis_ui_lib/components/waveform-meter.md)s that run while audio flows. This demo cycles through
the states on a timer; in an app the state comes from your voice pipeline. To switch states by
hand while developing, use [StateSimulator](https://joeyash.github.io/jarvis_ui_lib/components/state-simulator.md).

```tsx
import { useEffect, useState } from 'react';
import { StatusLabel, WaveformMeter } from 'jarvis-react-ui';
import type { AppOrbState } from 'jarvis-react-ui';

const CYCLE: AppOrbState[] = ['idle', 'listening', 'thinking', 'speaking', 'follow_up', 'working'];

export default function OrbStateCycle() {
    const [index, setIndex] = useState(0);
    const state = CYCLE[index % CYCLE.length] ?? 'idle';
    const audible = state === 'listening' || state === 'speaking';

    useEffect(() => {
        const id = setInterval(() => setIndex((i) => i + 1), 1800);
        return () => clearInterval(id);
    }, []);

    return (
        <div className="flex items-center gap-6">
            <WaveformMeter active={audible} />
            <StatusLabel state={state} />
            <WaveformMeter active={audible} mirrored />
        </div>
    );
}
```

## Announce state changes

Set `live` on the one StatusLabel that represents the assistant state. The status text becomes a
polite live region, so screen readers announce each new state after the current speech:

```tsx
<StatusLabel state={state} live />
```

The demos on this page leave `live` off, because the cycling demo would announce a change every
couple of seconds.

## Accessibility

- By default the label is plain text and state changes are not announced. Set `live` to make the
  status text a polite live region (`role="status"`, `aria-live="polite"`), so screen readers
  announce each new state without interrupting. Render only one live StatusLabel per screen, or
  every copy is announced.
- It ignores pointer events (`pointer-events: none`), so it never blocks clicks on the orb behind
  it.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `state` (required) | `'idle' \| 'listening' \| 'thinking' \| 'speaking' \| 'follow_up' \| 'working'` |  | Current orb state; selects the status text (`READY`, `listening...`, ...) and highlights it in the accent color for every state except `idle`. |
| `brand` | `string` | `J A R V I S` | Brand text shown in small, widely spaced letters below the status. |
| `className` | `string` |  | Extra classes for the root `<div>` element. |
| `labels` | `Partial<Record<AppOrbState, string>>` |  | Custom status texts per state, e.g. for localization; states you leave out keep their built-in text (`READY`, `listening...`, `thinking...`, `speaking...`, `follow-up...`, `working...`). |
| `live` | `boolean` | `false` | Turns the status text into a polite live region (`role="status"`, `aria-live="polite"`), so screen readers announce state changes. |

### Type `AppOrbState`

Full app-layer orb state — a superset of `OrbState` that includes
states handled above the base state machine.

Components and hooks should use `AppOrbState` for their props / return values.

```ts
type AppOrbState = OrbState | 'working';
```

### Type `OrbState`

States that drive the JARVIS orb visual and audio state machine.
Single source of truth — copied from src/types.ts.

```ts
type OrbState = 'idle' | 'listening' | 'thinking' | 'speaking' | 'follow_up';
```

# Callout

Callouts highlight a short note, tip or warning next to the content it belongs to. Four semantic
variants set the accent color and the default icon.

```ts
import { Callout } from 'jarvis-react-ui';
```

## Variants

`info` (the default) is for neutral notes, `success` confirms a good state, `warning` flags
something to watch out for and `error` reports a failure. Each variant brings its own icon.

```tsx
import { Callout } from 'jarvis-react-ui';

export default function Variants() {
    return (
        <div className="flex w-full max-w-[420px] flex-col gap-2">
            <Callout>Telemetry refreshes every five seconds.</Callout>
            <Callout variant="success">All subsystems online.</Callout>
            <Callout variant="warning">Reactor output above 90 percent.</Callout>
            <Callout variant="error">Uplink lost. Retrying in 10 seconds.</Callout>
        </div>
    );
}
```

## With a title

`title` adds a small uppercase heading in the variant color above the body.

```tsx
import { Callout } from 'jarvis-react-ui';

export default function WithTitle() {
    return (
        <div className="flex w-full max-w-[420px] flex-col gap-2">
            <Callout title="Note">Import style.css once at the root of your app.</Callout>
            <Callout variant="warning" title="Heads up">
                ThreeOrb needs the optional three peer dependency.
            </Callout>
        </div>
    );
}
```

## Custom icon or no icon

Pass any `lucide-react` icon component to `icon` to replace the variant icon, or `icon={false}` to
render none. The color still follows the variant.

```tsx
import { Lightbulb } from 'lucide-react';
import { Callout } from 'jarvis-react-ui';

export default function CustomIcon() {
    return (
        <div className="flex w-full max-w-[420px] flex-col gap-2">
            <Callout icon={Lightbulb} title="Tip">
                Hold Shift while dragging a window to swap it with another slot.
            </Callout>
            <Callout icon={false}>A plain note without an icon.</Callout>
        </div>
    );
}
```

This documentation uses `Callout` for its own notes, and Markdown blockquotes (`> ...`) on these
pages render as an `info` callout.

## Accessibility

- The root element has `role="note"`, so screen readers announce it as supplementary content.
- The icon is decorative and marked `aria-hidden`; put the meaning into `title` or the body text
  instead of relying on color or icon alone.
- A callout is not a live region. For messages that appear in response to an action, wrap it in
  your own `aria-live` container.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  | Body content. |
| `className` | `string` |  | Additional class names for the root `role="note"` element. |
| `icon` | `false \| LucideIcon` |  | Overrides the variant icon; pass `false` to render no icon. |
| `title` | `ReactNode` |  | Bold heading line above the body. |
| `variant` | `'info' \| 'success' \| 'warning' \| 'error'` | `'info'` | Semantic color and default icon. |

# CodeBlock

CodeBlock shows a snippet of source code in a dark frame with an optional header for a file
name, a language label, custom actions and a copy-to-clipboard button.

```ts
import { CodeBlock } from 'jarvis-react-ui';
```

## Basic

Pass the source as `code`. It is rendered as plain text, so no escaping is needed. The copy button
is on by default.

```tsx
import { CodeBlock } from 'jarvis-react-ui';

export default function Basic() {
    return <CodeBlock code="npm install jarvis-react-ui" />;
}
```

## Title and language

`title` (usually a file name) and `language` are shown in the header. The language is only a label;
CodeBlock does not highlight code by itself.

```tsx
import { CodeBlock } from 'jarvis-react-ui';

const SOURCE = `import { Button } from 'jarvis-react-ui';

export function App() {
    return <Button variant="primary">Engage</Button>;
}`;

export default function TitleAndLanguage() {
    return <CodeBlock title="App.tsx" language="tsx" code={SOURCE} />;
}
```

## Header actions

`actions` renders extra controls at the right end of the header, before the copy button. Use small
icon buttons such as [IconButton](https://joeyash.github.io/jarvis_ui_lib/components/icon-button.md) with `size="sm"`.

```tsx
import { useState } from 'react';
import { WrapText } from 'lucide-react';
import { CodeBlock, IconButton } from 'jarvis-react-ui';

const SOURCE = `const status = await fetch('/api/reactor/status').then((res) => res.json()); // a deliberately long line`;

export default function WithActions() {
    const [wrap, setWrap] = useState(false);

    return (
        <CodeBlock
            className={wrap ? '[&_pre]:whitespace-pre-wrap' : undefined}
            title="status.ts"
            language="ts"
            code={SOURCE}
            actions={
                <IconButton
                    icon={WrapText}
                    label={wrap ? 'Disable line wrap' : 'Enable line wrap'}
                    size="sm"
                    aria-pressed={wrap}
                    onClick={() => setWrap((w) => !w)}
                />
            }
        />
    );
}
```

## Not copyable

Set `copyable={false}` to hide the copy button, e.g. for logs or output that nobody should paste.
Without `title`, `language`, `actions` and the copy button, the header is not rendered at all.

```tsx
import { CodeBlock } from 'jarvis-react-ui';

export default function NotCopyable() {
    return (
        <CodeBlock
            language="log"
            copyable={false}
            code={
                '[12:04:31] link established\n[12:04:32] handshake ok\n[12:04:33] streaming telemetry'
            }
        />
    );
}
```

## Copy feedback

`onCopy` is called with the code after it reached the clipboard. Combine it with
[useToast](https://joeyash.github.io/jarvis_ui_lib/components/toast.md) to confirm the copy; reusing a toast `id` keeps repeated copies from
stacking.

```tsx
import { CodeBlock, useToast } from 'jarvis-react-ui';

export default function CopyToast() {
    const { toast } = useToast();

    return (
        <CodeBlock
            className="w-full"
            code="npm i jarvis-react-ui"
            language="bash"
            onCopy={() => toast({ id: 'copied', variant: 'success', title: 'Copied' })}
        />
    );
}
```

## Syntax highlighting

CodeBlock does not ship a highlighter. To show colored code, highlight it yourself (ideally at
build time, e.g. with [shiki](https://shiki.style)) and pass the resulting markup as `html`. It is
injected into the `<code>` element, while `code` is still used for the copy button. Every code
sample on this site works that way: the demo sources are highlighted by shiki during the build and
handed to `CodeBlock` together with the raw source.

```tsx
import { CodeBlock } from 'jarvis-react-ui';

const CODE = "import { Button } from 'jarvis-react-ui';";

// Trusted markup generated at build time (e.g. by shiki), never user input.
const HTML =
    '<span class="text-accent-bright">import</span> { Button } ' +
    '<span class="text-accent-bright">from</span> ' +
    '<span class="text-success">\'jarvis-react-ui\'</span>;';

export default function Highlighted() {
    return <CodeBlock title="App.tsx" language="tsx" code={CODE} html={HTML} />;
}
```

> **Warning: Trusted markup only**
>
> `html` is injected with `dangerouslySetInnerHTML` and is not sanitized. Only pass markup that
> you generated yourself from trusted sources. Never pass user input, URL parameters or API
> responses, because that opens the door to cross-site scripting (XSS).

## Accessibility

- The code is rendered in a native `<pre><code>`, which scrolls horizontally for long lines and
  keeps whitespace intact.
- The copy button is an [IconButton](https://joeyash.github.io/jarvis_ui_lib/components/icon-button.md) labelled "Copy code"; after a
  successful copy its label and tooltip switch to "Copied" for 1.5 seconds.
- Copying uses the async Clipboard API, which browsers only allow in secure contexts (HTTPS or
  localhost). Where it is unavailable the button does nothing.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `code` (required) | `string` |  | Raw source code. Copied to the clipboard and rendered as plain text when `html` is absent. |
| `actions` | `ReactNode` |  | Content rendered at the right end of the header, next to the copy button. |
| `className` | `string` |  | Additional class names for the outer frame (wraps the header and the `<pre>`). |
| `copyable` | `boolean` | `true` | Shows the copy-to-clipboard button. |
| `html` | `string` |  | Pre-highlighted markup for the inside of the `<code>` element, e.g. produced by shiki at build time. It is injected as HTML, so it must come from a trusted source, never from user input. |
| `language` | `string` |  | Language label shown in the header, e.g. `tsx`. |
| `onCopy` | `((code: string) => void)` |  | Called with the code after it was copied to the clipboard, e.g. to show a toast. Not called when copying fails or the clipboard API is unavailable. |
| `title` | `ReactNode` |  | Title shown in the header, e.g. a file name. |

# Dialog

A modal dialog for confirmations and short forms. It renders above the page, keeps keyboard
focus inside, and returns focus to the trigger when it closes.

```ts
import { Dialog } from 'jarvis-react-ui';
```

## Confirmation

The dialog is controlled: keep `open` in state and update it in `onOpenChange`. Put the buttons in
`actions`; they appear in the footer, right-aligned.

```tsx
import { useState } from 'react';
import { Button, Dialog, useToast } from 'jarvis-react-ui';

export default function Confirm() {
    const [open, setOpen] = useState(false);
    const { toast } = useToast();

    function purge() {
        setOpen(false);
        toast({ variant: 'success', title: 'Cache purged' });
    }

    return (
        <>
            <Button variant="danger" onClick={() => setOpen(true)}>
                Purge cache
            </Button>
            <Dialog
                open={open}
                onOpenChange={setOpen}
                title="Purge cache"
                description="All cached telemetry will be deleted."
                size="sm"
                actions={
                    <>
                        <Button variant="ghost" size="sm" onClick={() => setOpen(false)}>
                            Cancel
                        </Button>
                        <Button variant="danger" size="sm" onClick={purge}>
                            Purge
                        </Button>
                    </>
                }
            >
                This cannot be undone. Running sessions keep their data.
            </Dialog>
        </>
    );
}
```

## Form

`initialFocusRef` chooses the element that gets focus when the dialog opens, here the input. Without
it, the first focusable element (usually the close button) gets focus.

```tsx
import { useRef, useState } from 'react';
import type { FormEvent } from 'react';
import { Button, Dialog, Input, Label } from 'jarvis-react-ui';

export default function Form() {
    const [open, setOpen] = useState(false);
    const [callsign, setCallsign] = useState('JARVIS');
    const inputRef = useRef<HTMLInputElement>(null);

    function submit(e: FormEvent<HTMLFormElement>) {
        e.preventDefault();
        setOpen(false);
    }

    return (
        <>
            <Button onClick={() => setOpen(true)}>Rename: {callsign}</Button>
            <Dialog
                open={open}
                onOpenChange={setOpen}
                title="Rename assistant"
                initialFocusRef={inputRef}
            >
                <form id="rename-form" onSubmit={submit} className="flex flex-col gap-2">
                    <Label htmlFor="callsign">Callsign</Label>
                    <Input
                        id="callsign"
                        ref={inputRef}
                        fullWidth
                        value={callsign}
                        onChange={(e) => setCallsign(e.target.value)}
                    />
                    <div className="flex justify-end gap-2 pt-2">
                        <Button
                            type="button"
                            variant="ghost"
                            size="sm"
                            onClick={() => setOpen(false)}
                        >
                            Cancel
                        </Button>
                        <Button type="submit" variant="primary" size="sm">
                            Save
                        </Button>
                    </div>
                </form>
            </Dialog>
        </>
    );
}
```

## Sizes

`sm`, `md` (default) and `lg` cap the width at 360, 520 and 720px. Long content scrolls inside the
body while the header and footer stay visible.

```tsx
import { useState } from 'react';
import { Button, Dialog } from 'jarvis-react-ui';
import type { DialogSize } from 'jarvis-react-ui';

const SIZES: DialogSize[] = ['sm', 'md', 'lg'];

export default function Sizes() {
    const [size, setSize] = useState<DialogSize | null>(null);

    return (
        <>
            {SIZES.map((s) => (
                <Button key={s} onClick={() => setSize(s)}>
                    {s}
                </Button>
            ))}
            <Dialog
                open={size !== null}
                onOpenChange={() => setSize(null)}
                title={`Size ${size ?? ''}`}
                size={size ?? 'md'}
            >
                The panel is at most {size === 'sm' ? 360 : size === 'lg' ? 720 : 520}px wide and
                never wider than the viewport.
            </Dialog>
        </>
    );
}
```

## Closing

The dialog calls `onOpenChange(false)` when the user presses **Escape**, clicks the backdrop or uses
the close button. Set `closeOnBackdrop={false}` for dialogs that must be answered explicitly, and
`showClose={false}` to hide the close button.

## Accessibility

- `role="dialog"` with `aria-modal="true"`, named by `title` (`aria-labelledby`) and described by
  `description` (`aria-describedby`). Use `hideTitle` to keep the name while hiding the heading.
- Focus moves into the dialog on open, **Tab** and **Shift+Tab** cycle inside it, and focus returns to
  the previously focused element on close.
- Page scrolling is locked while the dialog is open.
- The dialog is portaled to `document.body`, so ancestors with `overflow: hidden` or `transform`
  cannot clip it.

## Sound

Opening plays `menu_open`, closing plays `menu_close`.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onOpenChange` (required) | `(open: boolean) => void` |  | Called with `false` when the user closes the dialog (Escape, backdrop, close button). |
| `open` (required) | `boolean` |  | Whether the dialog is shown. The dialog is controlled. |
| `title` (required) | `ReactNode` |  | Heading of the dialog; also its accessible name. |
| `actions` | `ReactNode` |  | Footer content, typically buttons, aligned to the right. |
| `children` | `ReactNode` |  | Dialog body. |
| `className` | `string` |  | Additional class names for the dialog panel. |
| `closeOnBackdrop` | `boolean` | `true` | Closes the dialog when the backdrop is clicked. |
| `description` | `ReactNode` |  | Optional text below the title; referenced by `aria-describedby`. |
| `hideTitle` | `boolean` | `false` | Hides the title visually while keeping it as the accessible name. |
| `initialFocusRef` | `RefObject<HTMLElement \| null>` |  | Element that receives focus when the dialog opens. Defaults to the first focusable element. |
| `showClose` | `boolean` | `true` | Shows the close button in the header. |
| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Maximum width: `sm` 360px, `md` 520px, `lg` 720px. |

# GlassCard

GlassCard is a [Panel](https://joeyash.github.io/jarvis_ui_lib/components/panel.md) in an `inline-block` wrapper, framed by the panel's
own corner brackets. Use it for standalone dashboard tiles that size themselves to their
content.

```ts
import { GlassCard } from 'jarvis-react-ui';
```

## Basic

The outer wrapper is an `inline-block` and takes the size of the panel inside it. Size the panel
through `bodyClassName`; `className` goes to the wrapper and suits margins or positioning. Only
one set of corner brackets is drawn: the panel's own, which lengthen on hover.

```tsx
import { GlassCard } from 'jarvis-react-ui';

export default function Basic() {
    return (
        <GlassCard title="System" bodyClassName="w-[260px] h-[110px]">
            <span className="text-text-secondary">CPU · 42%</span>
        </GlassCard>
    );
}
```

## Focus

`focused` switches the panel to its focused look: longer corner brackets in the bright accent, an
accent border and an animated bloom. GlassCard does not track focus itself, so keep the focused card
in state.

```tsx
import { useState } from 'react';
import { Button, GlassCard } from 'jarvis-react-ui';

export default function Focused() {
    const [focused, setFocused] = useState(true);

    return (
        <div className="flex flex-col items-center gap-6">
            <GlassCard title="Uplink" focused={focused} bodyClassName="w-[260px] h-[110px]">
                <span className={focused ? 'text-accent' : 'text-text-secondary'}>
                    {focused ? 'Focused' : 'Standby'}
                </span>
            </GlassCard>
            <Button size="sm" onClick={() => setFocused((f) => !f)}>
                {focused ? 'Blur' : 'Focus'}
            </Button>
        </div>
    );
}
```

## Dashboard tiles

GlassCard takes any content. Combine it with [Metric](https://joeyash.github.io/jarvis_ui_lib/components/metric.md) and
[StatusBadge](https://joeyash.github.io/jarvis_ui_lib/components/status-badge.md) for compact status tiles. For header actions, an index glyph
or a badge, use a [Panel](https://joeyash.github.io/jarvis_ui_lib/components/panel.md) directly; GlassCard only forwards `title`.

```tsx
import { GlassCard, Metric, StatusBadge } from 'jarvis-react-ui';

export default function Dashboard() {
    return (
        <>
            <GlassCard title="Vitals" bodyClassName="w-[220px] h-[120px]">
                <div className="grid grid-cols-2 gap-3">
                    <Metric value={42} unit="%" />
                    <Metric value={68} unit="°C" warn />
                </div>
            </GlassCard>
            <GlassCard title="Network" bodyClassName="w-[220px] h-[120px]">
                <div className="flex flex-col gap-2">
                    <StatusBadge label="Uplink · secure" />
                    <StatusBadge state="warn" label="Relay · degraded" />
                    <StatusBadge state="offline" label="Backup · offline" />
                </div>
            </GlassCard>
        </>
    );
}
```

## Sound

Hovering the card plays `hover_panel` through the nearest `SfxProvider`, like every Panel. Without a
provider it stays silent. See [Sound effects](https://joeyash.github.io/jarvis_ui_lib/getting-started/sound.md).

## Accessibility

- GlassCard renders presentational `<div>`s without a landmark role; the brackets are decorative
  empty elements. Wrap it in a `<section>` with an `aria-label` when it is a distinct region.
- `focused` is purely visual and does not move keyboard focus.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `bodyClassName` | `string` |  | Additional class names for the inner Panel's root element, e.g. its width and height. |
| `children` | `ReactNode` |  | Content of the panel body. |
| `className` | `string` |  | Additional class names for the outer wrapper `<div>` (a relative `inline-block`). |
| `focused` | `boolean` | `false` | Switches the panel to its focused look: longer, brighter corner brackets, accent border and bloom. Purely visual; it does not move keyboard focus. |
| `title` | `string` |  | Header title of the inner Panel; without it the panel has no header strip. |

# HUDShell

HUDShell is the full-screen frame of a JARVIS app. It draws the complete backdrop and gives you
slots for the top bar, the orb, your panels and the voice dock, layered in the right order.
Start every app with it.

```ts
import { HUDShell } from 'jarvis-react-ui';
```

## Starting an app

Wrap the app in [JarvisProvider](https://joeyash.github.io/jarvis_ui_lib/components/jarvis-provider.md) for sound and toasts, then render
HUDShell as its root element and fill the slots.

```tsx
import 'jarvis-react-ui/style.css';
import { createRoot } from 'react-dom/client';
import { JarvisProvider } from 'jarvis-react-ui';
import { App } from './App'; // renders <HUDShell ...> like the demo below

createRoot(document.getElementById('root') as HTMLElement).render(
    <JarvisProvider>
        <App />
    </JarvisProvider>,
);
```

The demo shows a typical `App`: a [TopBar](https://joeyash.github.io/jarvis_ui_lib/components/top-bar.md) with a
[StatusBadge](https://joeyash.github.io/jarvis_ui_lib/components/status-badge.md), a [CssOrb](https://joeyash.github.io/jarvis_ui_lib/components/css-orb.md), two panels and a
[StatusDock](https://joeyash.github.io/jarvis_ui_lib/components/status-dock.md) that share one `AppOrbState`. Click the microphone to switch
between `idle` and `listening`. The demo shrinks the orb with `scale-[0.6]` to fit the frame; drop
that class in a full-screen app.

```tsx
import { useState } from 'react';
import {
    BrandMark,
    CssOrb,
    HUDShell,
    Metric,
    Panel,
    StatusBadge,
    StatusDock,
    TopBar,
} from 'jarvis-react-ui';
import type { AppOrbState } from 'jarvis-react-ui';

export default function AppShell() {
    const [state, setState] = useState<AppOrbState>('idle');

    return (
        <HUDShell
            topbar={<TopBar left={<BrandMark />} right={<StatusBadge />} />}
            orb={<CssOrb state={state} particles={false} className="scale-[0.6]" />}
            dock={
                <StatusDock
                    state={state}
                    onPTT={() => setState((s) => (s === 'idle' ? 'listening' : 'idle'))}
                />
            }
        >
            <div className="flex justify-between px-5 pt-16">
                <Panel title="Vitals" className="w-[180px]">
                    <Metric value={42} unit="%" />
                </Panel>
                <Panel title="Agenda" className="w-[180px]">
                    <span className="text-text-secondary">10:30 · Briefing</span>
                </Panel>
            </div>
        </HUDShell>
    );
}
```

## Layers

HUDShell is a `position: fixed; inset: 0` element. From back to front it renders:

| Layer                                            | Rendered   | Toggle                           |
| ------------------------------------------------ | ---------- | -------------------------------- |
| [Scene](https://joeyash.github.io/jarvis_ui_lib/components/scene.md) background            | always     | `scene` (grid, stars, scanlines) |
| [Reactor](https://joeyash.github.io/jarvis_ui_lib/components/reactor.md) glow              | by default | `reactor={false}`                |
| [ViewportCorners](https://joeyash.github.io/jarvis_ui_lib/components/viewport-corners.md)  | by default | `viewportCorners={false}`        |
| `orb` slot, full-screen and click-through (z 0)  | when set   | —                                |
| `children` in a relative layer (z 10)            | when set   | —                                |
| `dock` slot, rendered as is (StatusDock is z 25) | when set   | —                                |
| `topbar` slot (z 30)                             | when set   | —                                |

The `children` layer starts at the top of the screen, spans its width and is only as tall as its
content. Lay out your panels inside it, or use [WindowManager](https://joeyash.github.io/jarvis_ui_lib/components/window-manager.md) for draggable windows.

```tsx
import { HUDShell, Panel } from 'jarvis-react-ui';

export default function Basic() {
    return (
        <HUDShell>
            <div className="p-6">
                <Panel title="Diagnostics" className="h-[120px] w-[280px]">
                    <span className="text-text-secondary">All subsystems nominal.</span>
                </Panel>
            </div>
        </HUDShell>
    );
}
```

`scene` switches off single Scene layers; the dark background, vignette, grain and horizon glow
always stay. `reactor` and `viewportCorners` remove the glow and the corner marks.

```tsx
import { HUDShell, Panel } from 'jarvis-react-ui';

export default function Layers() {
    return (
        <HUDShell
            scene={{ stars: false, scanlines: false }}
            reactor={false}
            viewportCorners={false}
        >
            <div className="p-6">
                <Panel title="Minimal" className="h-[120px] w-[280px]">
                    <span className="text-text-secondary">Grid only, no reactor or corners.</span>
                </Panel>
            </div>
        </HUDShell>
    );
}
```

## Idle mode

`idle` dims and blurs every [Panel](https://joeyash.github.io/jarvis_ui_lib/components/panel.md) inside `children` and fades the top bar, so
only the orb remains in focus. The `children` layer becomes `inert` while idle: it is
click-through, its controls leave the tab order and it is hidden from assistive technology. Entering
and leaving idle both crossfade (instantly under `prefers-reduced-motion`). Use it when the
assistant has been inactive for a while. The top bar stays interactive, which is where this demo
puts the toggle.

```tsx
import { useState } from 'react';
import { BrandMark, Button, HUDShell, Panel, TopBar } from 'jarvis-react-ui';

export default function Idle() {
    const [idle, setIdle] = useState(false);

    return (
        <HUDShell
            idle={idle}
            topbar={
                <TopBar
                    left={<BrandMark />}
                    right={
                        <Button size="sm" variant="ghost" onClick={() => setIdle((v) => !v)}>
                            {idle ? 'Wake' : 'Idle'}
                        </Button>
                    }
                />
            }
        >
            <div className="flex justify-center px-5 pt-20">
                <Panel title="Transcript" className="h-[140px] w-[300px]">
                    <span className="text-text-secondary">
                        {idle ? 'Panels are dimmed and click-through.' : 'Awaiting input.'}
                    </span>
                </Panel>
            </div>
        </HUDShell>
    );
}
```

## Working state

Set `working` while a tool call runs. HUDShell adds the `is-working` class to its root, which draws
an accent light trace sweeping along the top edge and a soft accent vignette breathing at the
screen edges. Under `prefers-reduced-motion` both stay still: the trace becomes a static hairline
across the top. The amber working look of the orb still comes from passing `state="working"` to
the orb itself; you can target `.hud-shell.is-working` for further styles of your own.

```tsx
import { useState } from 'react';
import { BrandMark, Button, HUDShell, Panel, TopBar } from 'jarvis-react-ui';

export default function Working() {
    const [working, setWorking] = useState(true);

    return (
        <HUDShell
            working={working}
            topbar={
                <TopBar
                    left={<BrandMark />}
                    right={
                        <Button size="sm" variant="ghost" onClick={() => setWorking((v) => !v)}>
                            {working ? 'Done' : 'Run tool'}
                        </Button>
                    }
                />
            }
        >
            <div className="flex justify-center px-5 pt-20">
                <Panel title="Tool call" className="h-[140px] w-[300px]">
                    <span className="text-text-secondary">
                        {working ? 'Fetching weather data...' : 'Idle.'}
                    </span>
                </Panel>
            </div>
        </HUDShell>
    );
}
```

## Accessibility

- HUDShell renders plain `<div>`s without landmark roles. Give your content its own structure, for
  example a `<main>` around the panels and a `<nav>` in the top bar.
- The Scene, Reactor and ViewportCorners layers are `aria-hidden` and ignore pointer events; the
  orb layer ignores pointer events as well.
- Idle mode sets `inert` on the `children` layer, so the dimmed panels cannot be clicked or
  focused and are hidden from assistive technology until `idle` is `false` again. The top bar,
  orb and dock slots stay interactive.
- The working effect is decorative pseudo-element chrome and is not announced; pair it with a
  visible or live status (for example [StatusDock](https://joeyash.github.io/jarvis_ui_lib/components/status-dock.md)).

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` |  | Panels and windows; rendered in a relative layer above the orb (z-index 10). |
| `className` | `string` |  | Additional class names for the fixed, full-screen root `<div>`. |
| `dock` | `ReactNode` |  | Dock slot, typically a StatusDock; rendered as is, so it keeps its own fixed position. |
| `idle` | `boolean` | `false` | Idle mode: dims and blurs the panels in `children`, makes them `inert` (click-through and removed from the tab order and accessibility tree) and fades the top bar. Entering and leaving idle both crossfade. |
| `orb` | `ReactNode` |  | Orb slot, typically a CssOrb or ThreeOrb; rendered in a full-screen, click-through layer behind the panels. |
| `reactor` | `boolean` | `true` | Renders the Reactor glow at the bottom edge. |
| `scene` | `{ grid?: boolean; stars?: boolean; scanlines?: boolean \| undefined; } \| undefined` |  | Optional layers of the background Scene; each one is on unless set to `false`. |
| `style` | `CSSProperties` |  | Inline styles for the root `<div>`; use it to inject CSS custom properties. |
| `topbar` | `ReactNode` |  | Top bar slot, typically a TopBar; rendered above everything else (z-index 30). |
| `viewportCorners` | `boolean` | `true` | Renders the ViewportCorners marks in the four corners. |
| `working` | `boolean` | `false` | Working mode for tool-call activity: adds the `is-working` class to the root, which draws an accent light trace sweeping along the top edge and a soft breathing accent vignette at the screen edges (static under `prefers-reduced-motion`). |

# NavList

NavList is a vertical navigation list for sidebars: grouped link entries with optional headings,
trailing badges and a highlighted current entry. The sidebar of this documentation is a NavList.

```ts
import { NavList } from 'jarvis-react-ui';
```

## Groups and badges

`groups` is an array of blocks. Each group has an optional `label` (omit it for an ungrouped block
at the top) and its `items`. An item needs a unique `id`, a `label` and an `href`; `badge` adds
trailing content such as a `Pill`. The entry whose `id` equals `activeId` is
highlighted.

```tsx
import { NavList, Pill } from 'jarvis-react-ui';
import type { NavListGroup } from 'jarvis-react-ui';

const GROUPS: NavListGroup[] = [
    { items: [{ id: 'overview', label: 'Overview', href: '#overview' }] },
    {
        label: 'Systems',
        items: [
            { id: 'power', label: 'Power', href: '#power' },
            { id: 'comms', label: 'Comms', href: '#comms', badge: <Pill variant="warn">2</Pill> },
            { id: 'sensors', label: 'Sensors', href: '#sensors' },
        ],
    },
    {
        label: 'Labs',
        items: [
            {
                id: 'orb',
                label: 'Orb studio',
                href: '#orb',
                badge: <Pill variant="info">new</Pill>,
            },
        ],
    },
];

export default function Groups() {
    return <NavList className="w-[220px]" aria-label="Systems" groups={GROUPS} activeId="power" />;
}
```

## Client-side routing

Entries are real `<a href>` links, so the list works without JavaScript and supports opening in a
new tab. `onItemClick` runs before the browser follows the link; call `event.preventDefault()` to
handle navigation yourself and update `activeId`.

```tsx
import { useState } from 'react';
import { NavList } from 'jarvis-react-ui';
import type { NavListGroup } from 'jarvis-react-ui';

const GROUPS: NavListGroup[] = [
    {
        label: 'Mission',
        items: [
            { id: 'brief', label: 'Briefing', href: '#brief' },
            { id: 'route', label: 'Route', href: '#route' },
            { id: 'debrief', label: 'Debrief', href: '#debrief' },
        ],
    },
];

export default function ClientSide() {
    const [active, setActive] = useState('brief');

    return (
        <div className="flex items-start gap-6">
            <NavList
                className="w-[200px]"
                aria-label="Mission"
                groups={GROUPS}
                activeId={active}
                onItemClick={(item, e) => {
                    e.preventDefault();
                    setActive(item.id);
                }}
            />
            <p className="m-0 font-mono text-[11px] text-text-secondary">
                Active: <span className="text-accent">{active}</span>
            </p>
        </div>
    );
}
```

With a router, derive `activeId` from the current location and navigate in `onItemClick`. Let
modified clicks (Ctrl, Cmd, Shift, middle button) through so "open in new tab" keeps working. This
is how the sidebar of this site is wired up with React Router:

```tsx
import { useLocation, useNavigate } from 'react-router';
import { NavList } from 'jarvis-react-ui';
import type { NavListGroup } from 'jarvis-react-ui';

const GROUPS: NavListGroup[] = [
    {
        label: 'Components',
        items: [
            { id: 'button', label: 'Button', href: '/components/button' },
            { id: 'tabs', label: 'Tabs', href: '/components/tabs' },
        ],
    },
];

export function Sidebar() {
    const navigate = useNavigate();
    const { pathname } = useLocation();

    return (
        <NavList
            aria-label="Documentation"
            groups={GROUPS}
            activeId={pathname.split('/').pop()}
            onItemClick={(item, e) => {
                if (e.metaKey || e.ctrlKey || e.shiftKey || e.button !== 0) return;
                e.preventDefault();
                void navigate(item.href);
            }}
        />
    );
}
```

## Sound

Hovering an entry plays `hover_button` and clicking plays `click` through the nearest
`SfxProvider`. Without a provider the list stays silent. See [Sound effects](https://joeyash.github.io/jarvis_ui_lib/getting-started/sound.md).

## Accessibility

- Renders a `<nav>` landmark named by `aria-label` (default "Navigation"). Give each NavList on a
  page a distinct name.
- Every group is a `<ul>` list of `<li>` items, so screen readers announce the number of entries.
- The active entry gets `aria-current="page"` in addition to the visual highlight.
- Entries are native links: Tab moves between them, Enter follows them, and the focus outline is
  visible on keyboard focus.
- Group labels are plain text, not headings, so they do not appear in the heading outline.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `groups` (required) | `NavListGroup[]` |  | Navigation groups in display order. |
| `activeId` | `string` |  | Id of the current entry; it is highlighted and gets `aria-current="page"`. |
| `aria-label` | `string` | `Navigation` | Accessible name of the `<nav>` landmark. |
| `className` | `string` |  | Additional class names for the root `<nav>` element. |
| `onItemClick` | `((item: NavListItem, event: MouseEvent<HTMLAnchorElement, MouseEvent>) => void)` |  | Called when an entry is clicked, before the browser follows the link. Call `event.preventDefault()` to handle navigation yourself (e.g. with a client-side router). |

### Type `NavListGroup`

A titled block of `NavList` entries.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `NavListItem[]` |  | Entries in this group. |
| `label` | `string` |  | Group heading. Omit for an ungrouped block at the top. |

### Type `NavListItem`

A single link entry of a `NavList`.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `href` (required) | `string` |  | Link target. Entries are rendered as anchors so they work without JavaScript. |
| `id` (required) | `string` |  | Unique id of the entry; compared with `activeId`. |
| `label` (required) | `ReactNode` |  | Visible text of the entry. |
| `badge` | `ReactNode` |  | Optional trailing badge, e.g. a `Pill` saying "new". |

# StatusBadge

A small connection indicator: a colored dot followed by an uppercase label. Put it in a
[TopBar](https://joeyash.github.io/jarvis_ui_lib/components/top-bar.md) or a panel header to show whether a link or service is up.

```ts
import { StatusBadge } from 'jarvis-react-ui';
```

## States

`state` sets the dot color. The label is free text; without one the badge reads `LINK · SECURE`.

| `state`   | Dot color  |
| --------- | ---------- |
| `online`  | green      |
| `warn`    | amber      |
| `offline` | muted gray |

```tsx
import { StatusBadge } from 'jarvis-react-ui';

export default function States() {
    return (
        <>
            <StatusBadge state="online" label="Link · secure" />
            <StatusBadge state="warn" label="Degraded" />
            <StatusBadge state="offline" label="Offline" />
        </>
    );
}
```

## Pulse

While `state` is `online`, the dot pulses by default: it fades and shrinks slightly about once a
second. Set `pulse={false}` for a steady dot. `warn` and `offline` never pulse, and the pulse stops
for users who prefer reduced motion.

```tsx
import { StatusBadge } from 'jarvis-react-ui';

export default function Pulse() {
    return (
        <>
            <StatusBadge label="Pulsing" />
            <StatusBadge label="Steady" pulse={false} />
        </>
    );
}
```

## Live connection

Drive `state` and `label` from your connection status. This demo cycles through the states on a
timer.

```tsx
import { useEffect, useState } from 'react';
import { BrandMark, StatusBadge, TopBar } from 'jarvis-react-ui';
import type { StatusBadgeState } from 'jarvis-react-ui';

const CYCLE: StatusBadgeState[] = ['online', 'warn', 'offline'];

const LABELS: Record<StatusBadgeState, string> = {
    online: 'Link · secure',
    warn: 'Link · unstable',
    offline: 'Link · lost',
};

export default function LiveConnection() {
    const [index, setIndex] = useState(0);
    const state = CYCLE[index % CYCLE.length] ?? 'online';

    useEffect(() => {
        const id = setInterval(() => setIndex((i) => i + 1), 2000);
        return () => clearInterval(id);
    }, []);

    return (
        <TopBar
            position="static"
            left={<BrandMark />}
            right={<StatusBadge state={state} label={LABELS[state]} />}
        />
    );
}
```

## Accessibility

- The badge is plain text in a `<span>`. The state is only conveyed by the dot color, so make the
  `label` say it too (`Link · lost`, not just `Link`).
- It is not a live region, so changes are not announced. If screen reader users need to know when
  the connection drops, also announce it, for example with a [Toast](https://joeyash.github.io/jarvis_ui_lib/components/toast.md).
- The pulse animation is switched off under `prefers-reduced-motion`.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `className` | `string` |  | Additional class names for the root `<span>`. |
| `label` | `string` | `LINK · SECURE` | Text next to the status dot; displayed in uppercase. |
| `pulse` | `boolean` | `true` | Lets the dot pulse while `state` is `online`; ignored for the other states and under `prefers-reduced-motion`. |
| `state` | `'online' \| 'offline' \| 'warn'` | `'online'` | Connection state; sets the dot color: `online` green, `warn` amber, `offline` muted gray. |

# StatusDock

The voice control at the bottom center of the HUD: a push-to-talk button between two waveform
meters, with the current assistant state underneath. It is driven by a single `AppOrbState`.

```ts
import { StatusDock } from 'jarvis-react-ui';
```

## Basic

StatusDock is `position: fixed`, centered horizontally 24px above the bottom edge, with
`z-index: 25`. Render it once near the root of your app, or pass it to the `dock` slot of
[HUDShell](https://joeyash.github.io/jarvis_ui_lib/components/hud-shell.md). `onPTT` fires when the button is clicked; update your state
there. In this demo the frame contains it; in an app it sits at the bottom of the viewport.

```tsx
import { useState } from 'react';
import { StatusDock } from 'jarvis-react-ui';
import type { AppOrbState } from 'jarvis-react-ui';

export default function Basic() {
    const [state, setState] = useState<AppOrbState>('idle');

    return (
        <StatusDock
            state={state}
            onPTT={() => setState((s) => (s === 'idle' ? 'listening' : 'idle'))}
        />
    );
}
```

## States

`state` takes an `AppOrbState`, the same value you pass to the orb. Every state except `idle` starts
the [WaveformMeter](https://joeyash.github.io/jarvis_ui_lib/components/waveform-meter.md)s and marks the
[PushToTalkButton](https://joeyash.github.io/jarvis_ui_lib/components/push-to-talk-button.md) as active. The text below comes from
[StatusLabel](https://joeyash.github.io/jarvis_ui_lib/components/status-label.md): `READY` when idle, otherwise `listening...`,
`thinking...`, `speaking...`, `working...` or `follow-up...`.

```tsx
import { useState } from 'react';
import { Button, StatusDock } from 'jarvis-react-ui';
import type { AppOrbState } from 'jarvis-react-ui';

const STATES: AppOrbState[] = ['idle', 'listening', 'thinking', 'speaking', 'working'];

export default function States() {
    const [state, setState] = useState<AppOrbState>('thinking');

    return (
        <>
            <div className="flex flex-wrap justify-center gap-2 self-start">
                {STATES.map((s) => (
                    <Button
                        key={s}
                        size="sm"
                        variant={state === s ? 'primary' : 'ghost'}
                        onClick={() => setState(s)}
                    >
                        {s}
                    </Button>
                ))}
            </div>
            <StatusDock state={state} />
        </>
    );
}
```

```tsx
import { CssOrb, StatusDock } from 'jarvis-react-ui';
import type { AppOrbState } from 'jarvis-react-ui';

function Assistant({ state, onTalk }: { state: AppOrbState; onTalk: () => void }) {
    return (
        <>
            <CssOrb state={state} />
            <StatusDock state={state} onPTT={onTalk} />
        </>
    );
}
```

## Localization

`labels` replaces the status texts per state; states you leave out keep their built-in text.
`pttLabel` renames the built-in button and becomes its accessible name, and `brand` replaces the
`J A R V I S` line under the status.

```tsx
import { useState } from 'react';
import { StatusDock } from 'jarvis-react-ui';

const LABELS = {
    idle: 'BEREIT',
    listening: 'hört zu …',
    thinking: 'denkt nach …',
    speaking: 'spricht …',
    follow_up: 'Rückfrage …',
    working: 'arbeitet …',
};

export default function Localized() {
    const [talking, setTalking] = useState(false);

    return (
        <StatusDock
            state={talking ? 'listening' : 'idle'}
            labels={LABELS}
            pttLabel="Sprechen"
            onPTT={() => setTalking((v) => !v)}
        />
    );
}
```

## Custom button

`ptt` replaces the built-in button. Pass your own `PushToTalkButton` to change its icon or other
props; `onPTT` and `pttLabel` are then unused, so wire the click on your button.

```tsx
import { useState } from 'react';
import { Radio } from 'lucide-react';
import { PushToTalkButton, StatusDock } from 'jarvis-react-ui';

export default function CustomPtt() {
    const [live, setLive] = useState(false);

    return (
        <StatusDock
            state={live ? 'speaking' : 'idle'}
            ptt={
                <PushToTalkButton
                    active={live}
                    aria-label="Broadcast"
                    onClick={() => setLive((v) => !v)}
                >
                    <Radio size={24} strokeWidth={1.8} aria-hidden="true" />
                </PushToTalkButton>
            }
        />
    );
}
```

## Sound

The built-in push-to-talk button plays `hover_button` on hover and `click` on click through the
nearest `SfxProvider`. The meters and the label are silent.

## Accessibility

- The push-to-talk button is a native `<button>` named `Push to talk` (or `pttLabel`) with
  `aria-pressed` set while `state` is not `idle`. It works with **Enter** and **Space**.
- The waveform meters are `aria-hidden`.
- The state text is a polite live region (`role="status"`), so screen readers announce state
  changes such as `listening...` without interrupting.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `state` (required) | `'idle' \| 'listening' \| 'thinking' \| 'speaking' \| 'follow_up' \| 'working'` |  | Current assistant state. Every state except `idle` runs the waveform meters and marks the push-to-talk button as active; the StatusLabel shows the matching text, and screen readers announce each change (the label is a polite live region). |
| `brand` | `string` | `'J A R V I S'` | Brand text shown in small, widely spaced letters below the status. |
| `className` | `string` |  | Additional class names for the root `<div>`, which is fixed to the bottom center. |
| `labels` | `Partial<Record<AppOrbState, string>>` |  | Custom status texts per state for the built-in StatusLabel, e.g. for localization; states you leave out keep their built-in text (`READY`, `listening...`, `thinking...`, `speaking...`, `follow-up...`, `working...`). |
| `onPTT` | `(() => void)` |  | Called when the built-in push-to-talk button is clicked; unused when `ptt` is set. |
| `ptt` | `ReactNode` |  | Replaces the built-in PushToTalkButton between the two meters, e.g. with a customized one. |
| `pttLabel` | `string` | `'Push to talk'` | Accessible name of the built-in push-to-talk button, e.g. for localization; unused when `ptt` is set. |

### Type `AppOrbState`

Full app-layer orb state — a superset of `OrbState` that includes
states handled above the base state machine.

Components and hooks should use `AppOrbState` for their props / return values.

```ts
type AppOrbState = OrbState | 'working';
```

### Type `OrbState`

States that drive the JARVIS orb visual and audio state machine.
Single source of truth — copied from src/types.ts.

```ts
type OrbState = 'idle' | 'listening' | 'thinking' | 'speaking' | 'follow_up';
```

# Table

Table renders typed rows as a data table. Columns describe how each cell is rendered, so the
same row objects can carry plain values, pills or any other content.

```ts
import { Table } from 'jarvis-react-ui';
```

## Columns and rows

`Table` is generic over the row type. Each `TableColumn<T>` has a unique `key`, a `header` and a
`render(row, index)` function that returns the cell content. `align` sets the alignment of header
and cells (right-align numbers), and `className` is applied to every cell of the column, which is
handy for widths. `getRowKey` must return a stable, unique key per row.

```tsx
import { Pill, Table } from 'jarvis-react-ui';
import type { TableColumn } from 'jarvis-react-ui';

interface Subsystem {
    id: string;
    name: string;
    status: 'online' | 'degraded' | 'offline';
    load: number;
}

const ROWS: Subsystem[] = [
    { id: 'pwr', name: 'Power core', status: 'online', load: 72 },
    { id: 'com', name: 'Comms array', status: 'degraded', load: 38 },
    { id: 'nav', name: 'Navigation', status: 'online', load: 15 },
    { id: 'def', name: 'Defense grid', status: 'offline', load: 0 },
];

const STATUS_PILL = { online: 'ok', degraded: 'warn', offline: 'err' } as const;

const COLUMNS: TableColumn<Subsystem>[] = [
    { key: 'name', header: 'Subsystem', render: (row) => row.name },
    {
        key: 'status',
        header: 'Status',
        align: 'center',
        render: (row) => <Pill variant={STATUS_PILL[row.status]}>{row.status}</Pill>,
    },
    {
        key: 'load',
        header: 'Load',
        align: 'right',
        className: 'w-[80px] tabular-nums',
        render: (row) => `${row.load}%`,
    },
];

export default function Basic() {
    return (
        <Table
            caption="Subsystem status"
            columns={COLUMNS}
            rows={ROWS}
            getRowKey={(row) => row.id}
        />
    );
}
```

Define columns outside the component (or memoize them) so they are not recreated on every render.
TypeScript infers `T` from `rows` and checks every `render` function against it.

## Dense with a visible caption

`dense` tightens the cell padding for compact lists such as logs. The `caption` is always present
for screen readers; `showCaption` also shows it as a small heading above the table.

```tsx
import { Table } from 'jarvis-react-ui';
import type { TableColumn } from 'jarvis-react-ui';

interface LogEntry {
    time: string;
    source: string;
    message: string;
}

const ROWS: LogEntry[] = [
    { time: '12:04:31', source: 'uplink', message: 'Link established' },
    { time: '12:04:32', source: 'auth', message: 'Handshake ok' },
    { time: '12:04:33', source: 'telemetry', message: 'Streaming started' },
];

const COLUMNS: TableColumn<LogEntry>[] = [
    { key: 'time', header: 'Time', className: 'w-[90px] text-text-muted', render: (r) => r.time },
    {
        key: 'source',
        header: 'Source',
        className: 'w-[110px] text-accent',
        render: (r) => r.source,
    },
    { key: 'message', header: 'Message', render: (r) => r.message },
];

export default function DenseWithCaption() {
    return (
        <Table
            caption="Event log"
            showCaption
            dense
            columns={COLUMNS}
            rows={ROWS}
            getRowKey={(r, index) => `${r.time}-${index}`}
        />
    );
}
```

## Empty state

When `rows` is empty, a single full-width row shows `emptyText` (default "No data").

```tsx
import { Table } from 'jarvis-react-ui';
import type { TableColumn } from 'jarvis-react-ui';

interface Alert {
    id: string;
    level: string;
    message: string;
}

const COLUMNS: TableColumn<Alert>[] = [
    { key: 'level', header: 'Level', render: (r) => r.level },
    { key: 'message', header: 'Message', render: (r) => r.message },
];

export default function Empty() {
    return (
        <Table
            caption="Open alerts"
            columns={COLUMNS}
            rows={[]}
            getRowKey={(r) => r.id}
            emptyText="No open alerts. All systems nominal."
        />
    );
}
```

The API tables on every component page of this site are rendered with `Table`.

## Accessibility

- Renders a native `<table>` with `<thead>`, `<tbody>` and `<th scope="col">` header cells.
- Always pass a `caption`: it names the table for assistive technology. Without `showCaption` it is
  visually hidden but still read out.
- The table sits in a horizontally scrollable container, so wide tables do not break the layout on
  small screens.
- Rows are not interactive. If a row needs an action, put a button or link into a cell.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `columns` (required) | `TableColumn<T>[]` |  | Column definitions in display order. |
| `getRowKey` (required) | `(row: T, index: number) => string` |  | Returns a stable unique key for a row. |
| `rows` (required) | `T[]` |  | Data rows. |
| `caption` | `ReactNode` |  | Accessible caption, rendered visually hidden unless `showCaption` is set. |
| `className` | `string` |  | Additional class names for the scroll container that wraps the `<table>`. |
| `dense` | `boolean` | `false` | Tighter cell padding. |
| `emptyText` | `ReactNode` | `No data` | Content shown in a single full-width row when `rows` is empty. |
| `showCaption` | `boolean` | `false` | Shows the caption above the table. |

### Type `TableColumn<T>`

Definition of one `Table` column; `T` is the row type.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `header` (required) | `ReactNode` |  | Header cell content. |
| `key` (required) | `string` |  | Unique key of the column; used as the React key of its cells. |
| `render` (required) | `(row: T, index: number) => ReactNode` |  | Renders the cell content for a row; `index` is the row's position in `rows`. |
| `align` | `TableAlign` | `'left'` | Horizontal alignment of header and cells. |
| `className` | `string` |  | Extra class name for every cell in this column, e.g. one that sets the column width. |

### Type `TableAlign`

Horizontal alignment of a `Table` column.

```ts
type TableAlign = 'left' | 'center' | 'right';
```

# Tabs

Tabs switch between panels of related content in the same place. Only the selected panel is
rendered, and the tab bar has room for actions on the right.

```ts
import { Tabs } from 'jarvis-react-ui';
```

## Basic

Pass the tabs as `items`, each with a unique `value`, a `label` and its panel `content`. Without
`value` the component manages the selection itself and starts with `defaultValue`, or the first
enabled tab.

```tsx
import { CodeBlock, Tabs } from 'jarvis-react-ui';

export default function Basic() {
    return (
        <Tabs
            aria-label="Package manager"
            items={[
                {
                    value: 'npm',
                    label: 'npm',
                    content: <CodeBlock code="npm install jarvis-react-ui" />,
                },
                {
                    value: 'pnpm',
                    label: 'pnpm',
                    content: <CodeBlock code="pnpm add jarvis-react-ui" />,
                },
                {
                    value: 'yarn',
                    label: 'yarn',
                    content: <CodeBlock code="yarn add jarvis-react-ui" />,
                },
            ]}
        />
    );
}
```

## Controlled

Pass `value` and `onValueChange` to own the selection, e.g. to sync it with the URL or to change
it from elsewhere. `onValueChange` is also called in uncontrolled mode.

```tsx
import { useState } from 'react';
import { Button, Tabs } from 'jarvis-react-ui';

export default function Controlled() {
    const [tab, setTab] = useState('status');

    return (
        <div className="flex w-full flex-col gap-3">
            <Tabs
                aria-label="Reactor"
                value={tab}
                onValueChange={setTab}
                panelClassName="text-[11px] text-text-secondary"
                items={[
                    { value: 'status', label: 'Status', content: 'Output stable at 72 percent.' },
                    { value: 'history', label: 'History', content: 'No incidents in 30 days.' },
                    { value: 'config', label: 'Config', content: 'Auto-throttle enabled.' },
                ]}
            />
            <div className="flex items-center gap-2">
                <Button size="sm" onClick={() => setTab('status')}>
                    Reset
                </Button>
                <span className="font-mono text-[10px] text-text-muted">value: {tab}</span>
            </div>
        </div>
    );
}
```

## Disabled tab

A tab with `disabled: true` is dimmed, cannot be clicked and is skipped by the arrow keys.

```tsx
import { Tabs } from 'jarvis-react-ui';

export default function DisabledTab() {
    return (
        <Tabs
            aria-label="Sensors"
            panelClassName="text-[11px] text-text-secondary"
            items={[
                { value: 'radar', label: 'Radar', content: '3 contacts in range.' },
                { value: 'lidar', label: 'Lidar', content: 'Calibrating.', disabled: true },
                { value: 'thermal', label: 'Thermal', content: 'No heat signatures.' },
            ]}
        />
    );
}
```

## Actions

`actions` renders content at the right end of the tab bar, such as a small
[IconButton](https://joeyash.github.io/jarvis_ui_lib/components/icon-button.md). Actions belong to the whole tab set, not to a single tab.

```tsx
import { useState } from 'react';
import { RefreshCw } from 'lucide-react';
import { IconButton, Tabs } from 'jarvis-react-ui';

export default function WithActions() {
    const [refreshed, setRefreshed] = useState(0);

    return (
        <Tabs
            aria-label="Logs"
            panelClassName="text-[11px] text-text-secondary"
            actions={
                <IconButton
                    icon={RefreshCw}
                    label="Refresh logs"
                    size="sm"
                    onClick={() => setRefreshed((n) => n + 1)}
                />
            }
            items={[
                { value: 'all', label: 'All', content: `128 entries, refreshed ${refreshed}x.` },
                {
                    value: 'errors',
                    label: 'Errors',
                    content: `2 entries, refreshed ${refreshed}x.`,
                },
            ]}
        />
    );
}
```

Use `panelClassName` to style the panel container, e.g. its typography or padding.

## Keyboard

| Key                        | Action                                                                           |
| -------------------------- | -------------------------------------------------------------------------------- |
| `Tab`                      | Moves focus into the tab list (to the selected tab) and on to the panel content. |
| `ArrowRight` / `ArrowLeft` | Selects the next / previous enabled tab, wrapping around.                        |
| `Home` / `End`             | Selects the first / last enabled tab.                                            |

Selection follows focus: moving with the arrow keys selects the tab immediately.

## Sound

Hovering a tab plays `hover_button` and selecting a different tab plays `click` through the
nearest `SfxProvider`. Without a provider the tabs stay silent. See
[Sound effects](https://joeyash.github.io/jarvis_ui_lib/getting-started/sound.md).

## Accessibility

- Follows the WAI-ARIA tabs pattern: a `role="tablist"` of `role="tab"` buttons and one
  `role="tabpanel"`.
- Name the tab list with `aria-label`.
- Each tab has `aria-selected` and `aria-controls` pointing at the panel; the panel is labelled by
  its tab through `aria-labelledby`.
- Roving tabindex: only the selected tab is in the tab order (`tabIndex={0}`), the others have
  `tabIndex={-1}` and are reached with the arrow keys.
- Disabled tabs use the native `disabled` attribute.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `items` (required) | `TabItem[]` |  | Tabs in display order. |
| `actions` | `ReactNode` |  | Content rendered at the right end of the tab bar, e.g. an `IconButton`. |
| `aria-label` | `string` |  | Accessible name of the tab list. |
| `className` | `string` |  | Additional class names for the root element (wraps the tab bar and the panel). |
| `defaultValue` | `string` | `the first enabled tab` | Initially selected value when uncontrolled. |
| `onValueChange` | `((value: string) => void)` |  | Called with the new value when the user selects a tab. |
| `panelClassName` | `string` |  | Additional class names for the `role="tabpanel"` container. |
| `value` | `string` |  | Controlled selected value. Leave undefined to use `defaultValue`. |

### Type `TabItem`

A single tab of a `Tabs` component.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `content` (required) | `ReactNode` |  | Panel content shown while the tab is selected. |
| `label` (required) | `ReactNode` |  | Text of the tab button. |
| `value` (required) | `string` |  | Unique value identifying the tab. |
| `disabled` | `boolean` | `false` | Disables the tab. |

# ToastProvider

The provider behind `useToast()`. It keeps the list of toasts, handles their timers and renders
the notification stack. `JarvisProvider` already includes it.

```ts
import { ToastProvider } from 'jarvis-react-ui';
```

## Setup

Most apps get it through [JarvisProvider](https://joeyash.github.io/jarvis_ui_lib/components/jarvis-provider.md). Use `ToastProvider` on its
own when you manage sound yourself or need a separate toast area for part of the app.

```tsx
import { ToastProvider } from 'jarvis-react-ui';

export function Root({ children }: { children: React.ReactNode }) {
    return <ToastProvider placement="top-right">{children}</ToastProvider>;
}
```

## Placement

The stack is fixed to a corner or edge of the viewport: `bottom-right` (default), `top-right`,
`bottom-center` or `top-center`. Inside an element with a `transform`, such as the demo frame below,
it stays within that element.

```tsx
import { useState } from 'react';
import { Button, ToastProvider, useToast } from 'jarvis-react-ui';
import type { ToastPlacement } from 'jarvis-react-ui';

const PLACEMENTS: ToastPlacement[] = ['bottom-right', 'top-right', 'bottom-center', 'top-center'];

function Trigger({ placement }: { placement: ToastPlacement }) {
    const { toast } = useToast();
    return <Button onClick={() => toast({ title: `Shown ${placement}` })}>Show toast</Button>;
}

export default function Placement() {
    const [placement, setPlacement] = useState<ToastPlacement>('top-right');

    return (
        <div className="flex flex-col items-center gap-4">
            <div className="flex flex-wrap justify-center gap-2">
                {PLACEMENTS.map((p) => (
                    <Button
                        key={p}
                        size="sm"
                        variant={p === placement ? 'primary' : 'ghost'}
                        onClick={() => setPlacement(p)}
                    >
                        {p}
                    </Button>
                ))}
            </div>
            <ToastProvider placement={placement}>
                <Trigger placement={placement} />
            </ToastProvider>
        </div>
    );
}
```

## Queue

At most `max` toasts (default 3) are visible. Further toasts wait in a queue and appear as soon as a
visible one closes.

```tsx
import { Button, ToastProvider, useToast } from 'jarvis-react-ui';

function Burst() {
    const { toast, dismissAll } = useToast();

    function burst() {
        for (let i = 1; i <= 5; i++) {
            toast({ title: `Sensor ${i} online`, duration: 3000 });
        }
    }

    return (
        <>
            <Button onClick={burst}>Fire 5 toasts</Button>
            <Button variant="ghost" onClick={dismissAll}>
                Clear
            </Button>
        </>
    );
}

export default function Queue() {
    return (
        <ToastProvider max={2} placement="top-right">
            <Burst />
        </ToastProvider>
    );
}
```

## Accessibility

The stack is a `<section>` with `aria-live="polite"` and an accessible name (`label`, default
"Notifications"). See [Toast](https://joeyash.github.io/jarvis_ui_lib/components/toast.md) for keyboard and screen reader behavior.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `children` (required) | `ReactNode` |  | The app (or part of it) that may call `useToast()`. |
| `duration` | `number` | `5000` | Default lifetime in ms for toasts without their own `duration`. |
| `label` | `string` | `Notifications` | Accessible name of the notification region. |
| `max` | `number` | `3` | Maximum number of toasts shown at once; further toasts wait in a queue. |
| `placement` | `'bottom-right' \| 'top-right' \| 'bottom-center' \| 'top-center'` | `'bottom-right'` | Screen corner or edge the toasts stack at. |

# WindowManager

WindowManager lays out a set of windows on a fixed slot grid. Windows dock into slots, can be
dragged onto other slots to move or swap, and can be undocked into free-floating, resizable
windows.

```ts
import { WindowManager } from 'jarvis-react-ui';
```

## Slot grid

The grid has nine slots: three in the left column (`L1`–`L3`), three in the right column
(`R1`–`R3`) and three in the bottom strip (`B1`–`B3`). The columns are 316px wide, the bottom strip
is 140px high, and the top 60px stay free for a [TopBar](https://joeyash.github.io/jarvis_ui_lib/components/top-bar.md). The grid is computed
from the size of the WindowManager, which fills its containing block (`position: fixed; inset: 0`):
the viewport, or the nearest ancestor with a `transform`. Column slots share the height left
between the top bar and the bottom strip (at least 60px each), so the 420px demo stages below dock
their windows in the bottom strip.

## Basic

`assignments` maps window ids to slots and is controlled: keep it in state and update it in
`onAssignmentsChange`. Drag a window header onto another slot to move it, or onto an occupied slot to
swap the two windows.

```tsx
import { useState } from 'react';
import { WindowManager } from 'jarvis-react-ui';
import type { ManagedWindow, SlotId } from 'jarvis-react-ui';

const WINDOWS: ManagedWindow[] = [
    { id: 'system', title: 'System', ix: '◈', itemRenderer: () => 'CPU 42% · RAM 61%' },
    { id: 'transcript', title: 'Transcript', ix: '▸', itemRenderer: () => 'Listening…' },
    { id: 'agenda', title: 'Agenda', ix: '▦', itemRenderer: () => '09:30 · Standup' },
];

export default function Basic() {
    const [assignments, setAssignments] = useState<Record<string, SlotId>>({
        system: 'B1',
        transcript: 'B2',
        agenda: 'B3',
    });

    return (
        <WindowManager
            windows={WINDOWS}
            assignments={assignments}
            onAssignmentsChange={setAssignments}
        />
    );
}
```

## Compact and expanded

Every window has a mode. `compact` windows are docked in their slot. Click the undock button in the
header, or double-click the header, to switch to `expanded`: the window floats above the grid, larger
than its slot, and can be dragged freely and resized from its edges and corners. The dock button
switches back.

`itemRenderer` receives `{ mode, focused, dragging }`, so a window can show a compact summary while
docked and more detail while expanded.

```tsx
import { useState } from 'react';
import { Metric, Sparkline, WindowManager } from 'jarvis-react-ui';
import type { ManagedWindow, SlotId } from 'jarvis-react-ui';

const WINDOWS: ManagedWindow[] = [
    {
        id: 'cpu',
        title: 'CPU',
        badge: 'LIVE',
        itemRenderer: ({ mode }) =>
            mode === 'compact' ? (
                <Metric value={42} unit="%" small />
            ) : (
                <div className="flex flex-col gap-3">
                    <Metric value={42} unit="%" />
                    <Sparkline data={[30, 42, 38, 51, 47, 42, 45, 39]} />
                </div>
            ),
    },
];

export default function Modes() {
    const [assignments, setAssignments] = useState<Record<string, SlotId>>({ cpu: 'B2' });
    const [focusedId, setFocusedId] = useState<string | null>(null);

    return (
        <WindowManager
            windows={WINDOWS}
            assignments={assignments}
            onAssignmentsChange={setAssignments}
            focusedId={focusedId}
            onFocusChange={setFocusedId}
        />
    );
}
```

## Controlled state

`focusedId` and `modes` can be controlled too. Focus moves to a window when it is pressed, dragged or
toggled, and `onFocusChange` receives `null` on a pointer down outside every window. Omit `modes` to
let WindowManager track modes itself; `onModesChange` fires either way.

```tsx
import { useState } from 'react';
import { Mono, WindowManager } from 'jarvis-react-ui';
import type { ManagedWindow, PanelMode, SlotId } from 'jarvis-react-ui';

const WINDOWS: ManagedWindow[] = [
    { id: 'system', title: 'System', ix: '◈', itemRenderer: ({ mode }) => mode },
    { id: 'agenda', title: 'Agenda', ix: '▦', itemRenderer: ({ mode }) => mode },
];

export default function Controlled() {
    const [assignments, setAssignments] = useState<Record<string, SlotId>>({
        system: 'B1',
        agenda: 'B3',
    });
    const [focusedId, setFocusedId] = useState<string | null>('system');
    const [modes, setModes] = useState<Record<string, PanelMode>>({});

    return (
        <>
            <Mono size="sm" secondary>
                focus: {focusedId ?? 'none'} · slots:{' '}
                {Object.entries(assignments)
                    .map(([id, slot]) => `${id}→${slot}`)
                    .join(' ')}{' '}
                · modes: {WINDOWS.map((w) => `${w.id}→${modes[w.id] ?? 'compact'}`).join(' ')}
            </Mono>
            <WindowManager
                windows={WINDOWS}
                assignments={assignments}
                onAssignmentsChange={setAssignments}
                focusedId={focusedId}
                onFocusChange={setFocusedId}
                modes={modes}
                onModesChange={setModes}
            />
        </>
    );
}
```

## Reset

The reset button in each header docks the window, clears any custom size and moves it back to its
home slot. Home slots come from `homeAssignments`; changes to the prop are used by the next reset.
Without `homeAssignments`, the `assignments` of the first render are the home slots.

## Controlled expanded rects

Pass `expandedRects` to own the positions and sizes of expanded windows, e.g. to persist them.
WindowManager then stops storing them and reports every change through `onExpandedRectsChange`:
the default rect when a window is undocked, the final position when a drag ends, each step of a
resize and the removal on reset. Apply the map you receive, otherwise the window snaps back.
`onExpandedRectsChange` also fires when `expandedRects` is omitted.

```tsx
import { useState } from 'react';
import { Mono, WindowManager } from 'jarvis-react-ui';
import type { ExpandedRect, ManagedWindow, SlotId } from 'jarvis-react-ui';

const WINDOWS: ManagedWindow[] = [
    { id: 'map', title: 'Map', ix: '◎', itemRenderer: () => 'Undock, then drag or resize me.' },
];

export default function ControlledRects() {
    const [assignments, setAssignments] = useState<Record<string, SlotId>>({ map: 'B2' });
    const [rects, setRects] = useState<Record<string, ExpandedRect>>({});
    const rect = rects.map;

    return (
        <>
            <Mono size="sm" secondary>
                map: {rect ? `${rect.x},${rect.y} ${rect.w}×${rect.h}` : 'docked'}
            </Mono>
            <WindowManager
                windows={WINDOWS}
                assignments={assignments}
                onAssignmentsChange={setAssignments}
                expandedRects={rects}
                onExpandedRectsChange={setRects}
            />
        </>
    );
}
```

## Floating windows

Windows created at runtime, for example by an assistant, usually have no slot. Mark them
`floating`: they need no entry in `assignments`, are always expanded, can be moved and resized but
not docked, and there is no limit to how many are open. Without `defaultRect` they open centred and
each further one is offset by 24px. The window used last is drawn on top.

Floating windows are closable by default: the close button and Escape (while focus is inside the
window) call `onClose` with the id. Remove the window from `windows` to close it; WindowManager then
forgets its position. Set `closable: true` to give a docked window a close button as well.

```tsx
import { useState } from 'react';
import { Button, Metric, WindowManager } from 'jarvis-react-ui';
import type { ManagedWindow } from 'jarvis-react-ui';

export default function Floating() {
    const [windows, setWindows] = useState<ManagedWindow[]>([]);
    const [focusedId, setFocusedId] = useState<string | null>(null);
    const [count, setCount] = useState(0);

    const open = () => {
        const id = `scan-${count + 1}`;
        setCount(count + 1);
        setWindows([
            ...windows,
            {
                id,
                title: `Scan ${count + 1}`,
                badge: 'NEW',
                floating: true,
                defaultRect: { x: 40 + (count % 6) * 32, y: 80 + (count % 6) * 24, w: 260, h: 150 },
                itemRenderer: () => <Metric value={(count + 1) * 17} unit="%" />,
            },
        ]);
    };

    return (
        <>
            <div className="absolute top-3 left-3 z-[1]">
                <Button variant="primary" onClick={open}>
                    Open window
                </Button>
            </div>
            <WindowManager
                windows={windows}
                assignments={{}}
                onAssignmentsChange={() => undefined}
                focusedId={focusedId}
                onFocusChange={setFocusedId}
                onClose={(id) => setWindows(windows.filter((w) => w.id !== id))}
            />
        </>
    );
}
```

## Windows

Each entry of `windows` is a `ManagedWindow`:

| Field          | Type                                            | Description                                                   |
| -------------- | ----------------------------------------------- | ------------------------------------------------------------- |
| `id`           | `string`                                        | Unique id; the key in `assignments`, `modes` and `focusedId`. |
| `title`        | `ReactNode`                                     | Header title; also the accessible name of the window region.  |
| `ix`           | `ReactNode`                                     | Index glyph before the title.                                 |
| `badge`        | `ReactNode`                                     | Tag at the right end of the header.                           |
| `itemRenderer` | `(props: PanelContentRenderProps) => ReactNode` | Renders the body; receives `mode`, `focused` and `dragging`.  |
| `floating`     | `boolean`                                       | Opens free-floating without a slot (see above).               |
| `defaultRect`  | `ExpandedRect`                                  | Initial position and size of a floating window.               |
| `closable`     | `boolean`                                       | Close button; default `true` for floating windows.            |

A docked window without an entry in `assignments` is not rendered.

## Sound

Through the nearest `SfxProvider`, dragging plays `drag_start`, a looping `drag_move` and `drag_end`;
resizing loops `resize`; the undock and dock buttons play `click` plus `expand` or `collapse`, and a
header double-click plays `expand` or `collapse`; the reset button plays `click` plus `recall`. A new
floating window plays `menu_open`; closing a window plays `click` plus `menu_close` (Escape plays
`menu_close`). See [Sound effects](https://joeyash.github.io/jarvis_ui_lib/getting-started/sound.md).

## Accessibility

- Each window is a non-modal `role="region"` named by its `title` through `aria-labelledby`.
- The reset and dock buttons are native buttons with accessible names; the dock button is the
  keyboard equivalent of the header double-click.
- A closable floating window is focusable (`tabIndex={-1}`); Escape closes it while focus is inside.
  Controls inside the window that use Escape themselves (e.g. a dropdown) should call
  `preventDefault()` so the window stays open.
- Dragging, swapping and resizing are pointer-only; there are no keyboard shortcuts for them. Offer
  another way to rearrange content (e.g. by updating `assignments`) when keyboard users need it.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `assignments` (required) | `Record<string, SlotId>` |  | Window id → slot id (controlled). Each window is docked in its assigned slot. |
| `onAssignmentsChange` (required) | `(next: Record<string, SlotId>) => void` |  | Called with the next assignments when a window is dropped on another slot (move), on an occupied slot (swap) or reset to its home slot. |
| `windows` (required) | `ManagedWindow[]` |  | Windows to render. A docked window without an entry in `assignments` is not rendered; `floating` windows need no assignment. |
| `className` | `string` |  | Additional class names for the root element. |
| `expandedRects` | `Record<string, ExpandedRect>` |  | Window id → free-floating rect (controlled). When set, WindowManager no longer stores positions itself: apply the maps passed to `onExpandedRectsChange` to move and resize expanded windows. Omit it to let WindowManager track them. |
| `focusedId` | `string \| null` | `null` | Id of the focused window (controlled); `null` for none. |
| `homeAssignments` | `Record<string, SlotId>` |  | Home slots restored by a window's Reset button. Changes to this prop are picked up by the next reset. Without it, the `assignments` of the first render are used. |
| `modes` | `Record<string, PanelMode>` |  | Window id → `compact` \| `expanded` (controlled). Missing ids are `compact`. Omit it to let WindowManager track modes internally. |
| `onClose` | `((id: string) => void)` |  | Called with the window id when its close button is clicked (or Escape is pressed in a focused floating window). Remove the window from `windows` to close it. |
| `onExpandedRectsChange` | `((next: Record<string, ExpandedRect>) => void)` |  | Called with the full next rect map when a window is undocked, an expanded window is moved (on drag end) or resized (on every resize move), or a window is reset. Fires in both controlled and uncontrolled mode. |
| `onFocusChange` | `((id: string \| null) => void)` |  | Called with a window id when a window is pressed, dragged or toggled, and with `null` on a pointer down outside every window. |
| `onModesChange` | `((next: Record<string, PanelMode>) => void)` |  | Called with the full next mode map when a window is undocked, docked or reset. Fires in both controlled and uncontrolled mode. |

### Type `SlotId`

Fixed 3×3 Dock grid slot geometry.

Left column (top → bottom):   L1, L2, L3
Right column (top → bottom):  R1, R2, R3
Bottom strip (left → right):  B1, B2, B3

```ts
type SlotId = 'L1' | 'L2' | 'L3' | 'R1' | 'R2' | 'R3' | 'B1' | 'B2' | 'B3';
```

### Type `ManagedWindow`

One window rendered by `WindowManager`.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` |  | Unique window id; used as the key in `assignments`, `modes` and `focusedId`. |
| `itemRenderer` (required) | `(props: PanelContentRenderProps) => ReactNode` |  | Render-prop content. Receives the current mode, focused state, and dragging state so the consumer can render compact vs expanded views. |
| `badge` | `ReactNode` |  | Tag shown at the right end of the header, e.g. `LIVE`. |
| `closable` | `boolean` | `true for floating windows, false for docked ones` | Shows a close button in the header that calls `onClose`; floating windows also close with Escape while focused. |
| `defaultRect` | `ExpandedRect` |  | Initial position and size of a floating window, relative to the container. Without it, floating windows open centred and cascade by 24px. Ignored once the window has a rect in `expandedRects`. |
| `defaultSize` | `{ w: number; h: number }` | `{ w: 480, h: 320 }` | Initial size of a floating window without `defaultRect`; it still opens centred and cascades. |
| `floating` | `boolean` | `false` | Opens the window free-floating instead of docked: it needs no entry in `assignments`, is always `expanded`, can be moved and resized but not docked, and has no slot limit. Use it for windows created at runtime. |
| `ix` | `ReactNode` |  | Index glyph shown before the title, e.g. `◈`. |
| `title` | `ReactNode` |  | Header title. It also names the window region (`aria-labelledby`). |

### Type `ExpandedRect`

Rectangular geometry used for the expanded (free-floating) position.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `h` (required) | `number` |  | Height in px. |
| `w` (required) | `number` |  | Width in px. |
| `x` (required) | `number` |  | Left edge in px. |
| `y` (required) | `number` |  | Top edge in px. |

### Type `PanelMode`

`compact`: docked in a slot. `expanded`: free-floating and resizable.

```ts
type PanelMode = 'compact' | 'expanded';
```

### Type `PanelContentRenderProps`

Window state passed to `itemRenderer`, so content can adapt to docked or floating mode.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `dragging` (required) | `boolean` |  | Whether the window is being dragged or resized right now. |
| `focused` (required) | `boolean` |  | Whether the window is currently focused. |
| `mode` (required) | `PanelMode` |  | `compact` while docked in a slot, `expanded` while free-floating. |

# LineChart

Shows how values change over an ordered axis such as time. Lines are drawn as SVG in the token
colors, scale to their container and can be inspected by pointer or keyboard.

```ts
import { LineChart } from 'jarvis-react-ui';
```

## Basic

Pass the values as `series` and one label per point as `labels`. `formatValue` formats the y-axis,
the tooltip and the screen-reader table.

```tsx
import { LineChart } from 'jarvis-react-ui';

export default function Basic() {
    return (
        <LineChart
            className="w-full"
            aria-label="CPU load over the day"
            labels={['00', '03', '06', '09', '12', '15', '18', '21']}
            series={[{ id: 'cpu', label: 'CPU', data: [18, 12, 15, 48, 72, 66, 51, 30] }]}
            formatValue={(v) => `${v}%`}
        />
    );
}
```

## Data format

All three charts ([LineChart](https://joeyash.github.io/jarvis_ui_lib/components/line-chart.md), [AreaChart](https://joeyash.github.io/jarvis_ui_lib/components/area-chart.md) and
[BarChart](https://joeyash.github.io/jarvis_ui_lib/components/bar-chart.md)) take the same data:

```ts
import type { ChartSeries } from 'jarvis-react-ui';

const series: ChartSeries[] = [
    { id: 'cpu', label: 'CPU', data: [18, 12, 48, 72] },
    { id: 'gpu', label: 'GPU', data: [10, 8, 32, 88], color: 'warning' },
];
```

`color` is one of `accent`, `bright`, `success`, `warning`, `error` or `muted`. Without it, series
get colors in that order. The colors are the theme tokens, so charts follow
[theming](https://joeyash.github.io/jarvis_ui_lib/customization/theming.md).

## Multiple series and curves

`curve="smooth"` draws curved lines; `showDots` marks every point. The legend appears automatically
for more than one series (`showLegend` overrides it).

```tsx
import { LineChart } from 'jarvis-react-ui';

export default function MultiSeries() {
    return (
        <LineChart
            className="w-full"
            aria-label="Core temperatures"
            labels={['Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat', 'Sun']}
            curve="smooth"
            showDots
            series={[
                { id: 'core', label: 'Core', data: [61, 64, 70, 68, 75, 72, 66] },
                {
                    id: 'shell',
                    label: 'Shell',
                    data: [40, 42, 47, 46, 51, 49, 44],
                    color: 'success',
                },
                { id: 'limit', label: 'Limit', data: [80, 80, 80, 80, 80, 80, 80], color: 'error' },
            ]}
            formatValue={(v) => `${v}°`}
        />
    );
}
```

## Live data

Charts are plain props-in, SVG-out components: update `series` and they redraw. Fix the axis with
`yMin` / `yMax` so it does not jump while the values move.

```tsx
import { useEffect, useState } from 'react';
import { LineChart } from 'jarvis-react-ui';

const WINDOW = 24;

function nextValue(prev: number): number {
    return Math.max(0, Math.min(100, prev + (Math.random() - 0.5) * 18));
}

export default function Live() {
    const [data, setData] = useState(() => Array.from({ length: WINDOW }, () => 40));

    useEffect(() => {
        const id = setInterval(() => {
            setData((d) => [...d.slice(1), nextValue(d[d.length - 1] ?? 40)]);
        }, 800);
        return () => clearInterval(id);
    }, []);

    return (
        <LineChart
            className="w-full"
            aria-label="Live uplink throughput"
            series={[{ id: 'uplink', label: 'Uplink', data, color: 'success' }]}
            labels={data.map((_, i) => `${i - WINDOW + 1}s`)}
            yMin={0}
            yMax={100}
            formatValue={(v) => `${Math.round(v)} MB/s`}
            height={160}
        />
    );
}
```

## Axis

The y-axis range comes from the data, rounded to "nice" ticks (`yTicks` sets the approximate count).
`yMin` and `yMax` override it. X labels are thinned out automatically when there are many points.

## Accessibility

- The chart has an accessible name from `aria-label` (required).
- A visually hidden table lists all values for screen readers.
- Hover shows a tooltip with all series at that position. For keyboard users the chart contains a
  focusable inspection control: **Tab** to it and use the **arrow keys** to move between positions;
  the current values are announced.
- Colors are not the only signal: the legend, tooltip and table name every series.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-label` (required) | `string` |  | Accessible name of the chart; also the caption of the screen-reader data table. |
| `series` (required) | `ChartSeries[]` |  | Data series to draw. |
| `className` | `string` |  | Additional class names for the root element. |
| `curve` | `'linear' \| 'smooth'` | `'linear'` | `smooth` draws curved lines through the points. |
| `formatValue` | `((value: number) => string)` |  | Formats values on the y-axis and in the tooltip. |
| `height` | `number` | `200` | Height of the plot in pixels (axes and legend add to it). |
| `labels` | `string[]` |  | X-axis labels, one per data point. Defaults to `1, 2, 3, …`. |
| `showDots` | `boolean` | `false` | Draws a dot at every data point (the hovered position always shows dots). |
| `showGrid` | `boolean` | `true` | Draws horizontal grid lines at the y ticks. |
| `showLegend` | `boolean` |  | Shows the legend; defaults to `true` for more than one series. |
| `showTooltip` | `boolean` | `true` | Shows the hover/keyboard tooltip with the values at a position. |
| `yMax` | `number` |  | Upper bound of the y-axis; computed from the data when omitted. |
| `yMin` | `number` |  | Lower bound of the y-axis; computed from the data when omitted. |
| `yTicks` | `number` | `4` | Approximate number of y-axis ticks. |

### Type `ChartSeries`

One data series of a `LineChart`, `AreaChart` or `BarChart`.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `data` (required) | `number[]` |  | One value per x position (same length as `labels`). |
| `id` (required) | `string` |  | Unique id of the series. |
| `label` (required) | `string` |  | Name shown in the legend, tooltip and screen-reader table. |
| `color` | `ChartColor` |  | Token color; defaults to a color by series position. |

### Type `ChartColor`

Token color of a chart series.

```ts
type ChartColor = 'accent' | 'bright' | 'success' | 'warning' | 'error' | 'muted';
```

# AreaChart

A line chart with the area below the line filled. Use it for volumes over time, and stack the
series to show how parts add up to a total.

```ts
import { AreaChart } from 'jarvis-react-ui';
```

## Basic

```tsx
import { AreaChart } from 'jarvis-react-ui';

export default function Basic() {
    return (
        <AreaChart
            className="w-full"
            aria-label="Memory usage"
            labels={['00', '04', '08', '12', '16', '20']}
            curve="smooth"
            series={[{ id: 'mem', label: 'Memory', data: [3.1, 2.8, 5.6, 7.9, 7.2, 4.4] }]}
            formatValue={(v) => `${v} GB`}
        />
    );
}
```

## Stacked

`stacked` places each series on top of the previous one, so the upper edge shows the total. The
tooltip and table still list the individual values.

```tsx
import { AreaChart } from 'jarvis-react-ui';

export default function Stacked() {
    return (
        <AreaChart
            className="w-full"
            aria-label="Power output by source"
            labels={['00', '04', '08', '12', '16', '20']}
            stacked
            series={[
                { id: 'arc', label: 'Arc reactor', data: [60, 62, 58, 64, 66, 61] },
                { id: 'solar', label: 'Solar', data: [0, 4, 28, 40, 22, 2], color: 'success' },
                { id: 'grid', label: 'Grid', data: [12, 10, 6, 4, 8, 14], color: 'muted' },
            ]}
            formatValue={(v) => `${v} kW`}
        />
    );
}
```

## Data, colors and axis

AreaChart takes the same `series`, `labels`, colors and axis props as
[LineChart](https://joeyash.github.io/jarvis_ui_lib/components/line-chart.md#data-format). The y-axis always includes zero, so areas start
from the baseline.

## Accessibility

Same as [LineChart](https://joeyash.github.io/jarvis_ui_lib/components/line-chart.md#accessibility): `aria-label`, a screen-reader table, and
a keyboard inspection control (Tab, then arrow keys).

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-label` (required) | `string` |  | Accessible name of the chart; also the caption of the screen-reader data table. |
| `series` (required) | `ChartSeries[]` |  | Data series to draw. |
| `className` | `string` |  | Additional class names for the root element. |
| `curve` | `'linear' \| 'smooth'` | `'linear'` | `smooth` draws curved edges. |
| `formatValue` | `((value: number) => string)` |  | Formats values on the y-axis and in the tooltip. |
| `height` | `number` | `200` | Height of the plot in pixels (axes and legend add to it). |
| `labels` | `string[]` |  | X-axis labels, one per data point. Defaults to `1, 2, 3, …`. |
| `showGrid` | `boolean` | `true` | Draws horizontal grid lines at the y ticks. |
| `showLegend` | `boolean` |  | Shows the legend; defaults to `true` for more than one series. |
| `showTooltip` | `boolean` | `true` | Shows the hover/keyboard tooltip with the values at a position. |
| `stacked` | `boolean` | `false` | Stacks the series on top of each other instead of overlapping them. |
| `yMax` | `number` |  | Upper bound of the y-axis; computed from the data when omitted. |
| `yMin` | `number` |  | Lower bound of the y-axis; computed from the data when omitted. |
| `yTicks` | `number` | `4` | Approximate number of y-axis ticks. |

### Type `ChartSeries`

One data series of a `LineChart`, `AreaChart` or `BarChart`.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `data` (required) | `number[]` |  | One value per x position (same length as `labels`). |
| `id` (required) | `string` |  | Unique id of the series. |
| `label` (required) | `string` |  | Name shown in the legend, tooltip and screen-reader table. |
| `color` | `ChartColor` |  | Token color; defaults to a color by series position. |

### Type `ChartColor`

Token color of a chart series.

```ts
type ChartColor = 'accent' | 'bright' | 'success' | 'warning' | 'error' | 'muted';
```

# BarChart

Compares values across categories. Several series are grouped side by side or stacked into one
bar per category; negative values grow downward from zero.

```ts
import { BarChart } from 'jarvis-react-ui';
```

## Grouped

Each category gets one bar per series, side by side.

```tsx
import { BarChart } from 'jarvis-react-ui';

export default function Grouped() {
    return (
        <BarChart
            className="w-full"
            aria-label="Network traffic per hour"
            labels={['00', '04', '08', '12', '16', '20']}
            series={[
                { id: 'in', label: 'Inbound', data: [12, 30, 22, 41, 18, 9] },
                { id: 'out', label: 'Outbound', data: [8, 14, 19, 25, 12, 6], color: 'bright' },
            ]}
            formatValue={(v) => `${v} GB`}
        />
    );
}
```

## Stacked

`stacked` puts the series on top of each other, so the bar height is the total.

```tsx
import { BarChart } from 'jarvis-react-ui';

export default function Stacked() {
    return (
        <BarChart
            className="w-full"
            aria-label="Requests by status"
            labels={['Mon', 'Tue', 'Wed', 'Thu', 'Fri']}
            stacked
            series={[
                { id: 'ok', label: '2xx', data: [920, 1040, 980, 1210, 1130], color: 'success' },
                { id: 'warn', label: '4xx', data: [40, 52, 38, 61, 44], color: 'warning' },
                { id: 'err', label: '5xx', data: [6, 3, 18, 4, 2], color: 'error' },
            ]}
        />
    );
}
```

## Negative values

The y-axis always includes zero. Positive bars grow up from it, negative bars grow down.

```tsx
import { BarChart } from 'jarvis-react-ui';

export default function Delta() {
    return (
        <BarChart
            className="w-full"
            aria-label="Battery charge change per hour"
            labels={['08', '09', '10', '11', '12', '13', '14']}
            series={[{ id: 'delta', label: 'Change', data: [12, 8, -4, -15, -6, 9, 14] }]}
            formatValue={(v) => `${v > 0 ? '+' : ''}${v}%`}
            height={160}
        />
    );
}
```

## Data, colors and axis

BarChart takes the same `series`, `labels`, colors and axis props as
[LineChart](https://joeyash.github.io/jarvis_ui_lib/components/line-chart.md#data-format). Hovering a category dims the others.

## Accessibility

Same as [LineChart](https://joeyash.github.io/jarvis_ui_lib/components/line-chart.md#accessibility): `aria-label`, a screen-reader table, and
a keyboard inspection control (Tab, then arrow keys).

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `aria-label` (required) | `string` |  | Accessible name of the chart; also the caption of the screen-reader data table. |
| `series` (required) | `ChartSeries[]` |  | Data series to draw. |
| `className` | `string` |  | Additional class names for the root element. |
| `formatValue` | `((value: number) => string)` |  | Formats values on the y-axis and in the tooltip. |
| `height` | `number` | `200` | Height of the plot in pixels (axes and legend add to it). |
| `labels` | `string[]` |  | X-axis labels, one per data point. Defaults to `1, 2, 3, …`. |
| `showGrid` | `boolean` | `true` | Draws horizontal grid lines at the y ticks. |
| `showLegend` | `boolean` |  | Shows the legend; defaults to `true` for more than one series. |
| `showTooltip` | `boolean` | `true` | Shows the hover/keyboard tooltip with the values at a position. |
| `stacked` | `boolean` | `false` | Stacks the series into one bar per position instead of grouping them side by side. |
| `yMax` | `number` |  | Upper bound of the y-axis; computed from the data when omitted. |
| `yMin` | `number` |  | Lower bound of the y-axis; computed from the data when omitted. |
| `yTicks` | `number` | `4` | Approximate number of y-axis ticks. |

### Type `ChartSeries`

One data series of a `LineChart`, `AreaChart` or `BarChart`.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `data` (required) | `number[]` |  | One value per x position (same length as `labels`). |
| `id` (required) | `string` |  | Unique id of the series. |
| `label` (required) | `string` |  | Name shown in the legend, tooltip and screen-reader table. |
| `color` | `ChartColor` |  | Token color; defaults to a color by series position. |

### Type `ChartColor`

Token color of a chart series.

```ts
type ChartColor = 'accent' | 'bright' | 'success' | 'warning' | 'error' | 'muted';
```

# MediaControls

Transport controls for any media source: play/pause, seek bar, time, mute and volume, plus
optional previous/next and fullscreen. They only report what the user does, so they drive a
video, an audio file, a YouTube player or a speaker in another room alike.

```ts
import { MediaControls } from 'jarvis-react-ui';
```

## Basic

MediaControls is fully controlled: pass `playing`, `currentTime`, `duration`, `volume` and `muted`
from your player and handle the callbacks. `onSeek` fires once when a drag on the seek bar ends, so
a player is not flooded with seeks while dragging; the time readout follows the drag meanwhile.
Buttons for previous, next and fullscreen appear when you pass their handler.

```tsx
import { useEffect, useState } from 'react';
import { MediaControls } from 'jarvis-react-ui';

const DURATION = 214;

export default function Basic() {
    const [playing, setPlaying] = useState(false);
    const [time, setTime] = useState(37);
    const [volume, setVolume] = useState(0.7);
    const [muted, setMuted] = useState(false);

    // Stands in for a real player: advances the time while "playing".
    useEffect(() => {
        if (!playing) return;
        const id = setInterval(() => setTime((t) => Math.min(DURATION, t + 1)), 1000);
        return () => clearInterval(id);
    }, [playing]);

    return (
        <MediaControls
            title="Mission briefing · 03"
            playing={playing}
            currentTime={time}
            duration={DURATION}
            volume={volume}
            muted={muted}
            onPlayPause={() => setPlaying(!playing)}
            onSeek={setTime}
            onVolumeChange={setVolume}
            onMutedChange={setMuted}
            onPrevious={() => setTime(0)}
            onNext={() => setTime(DURATION)}
        />
    );
}
```

## Live and minimal

A `duration` of `0`, `NaN` or `Infinity` means unknown or live: the seek bar is disabled and `LIVE`
replaces the total time. Without `onVolumeChange` and `onMutedChange` the volume controls are
hidden.

```tsx
import { useState } from 'react';
import { MediaControls } from 'jarvis-react-ui';

export default function Live() {
    const [playing, setPlaying] = useState(true);

    return (
        <MediaControls
            size="sm"
            aria-label="Radio controls"
            playing={playing}
            currentTime={0}
            duration={Infinity}
            onPlayPause={() => setPlaying(!playing)}
        />
    );
}
```

For a ready-made player use [MediaPlayer](https://joeyash.github.io/jarvis_ui_lib/components/media-player.md) (video and audio files) or
[YouTubePlayer](https://joeyash.github.io/jarvis_ui_lib/components/you-tube-player.md).

## Sound

The buttons play `hover_button` and `click`; dragging a slider plays `drag_start` and `drag_end`,
through the nearest `SfxProvider`. See [Sound effects](https://joeyash.github.io/jarvis_ui_lib/getting-started/sound.md).

## Accessibility

- The controls are a `role="group"` named **Media controls** (change it with `aria-label`). The
  buttons are named **Play** / **Pause**, **Mute** / **Unmute** (with `aria-pressed`),
  **Previous**, **Next** and **Fullscreen**; the sliders **Seek** (with the time as
  `aria-valuetext`) and **Volume**.
- Shortcuts while focus is inside the controls: `K` plays or pauses, `M` mutes, ← and → seek 5
  seconds. Keys a focused slider uses itself are left to it.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `currentTime` (required) | `number` |  | Playback position in seconds. |
| `duration` (required) | `number` |  | Length in seconds. `0`, `NaN` or `Infinity` (unknown or live) disables the seek bar and shows `LIVE` instead of the total time. |
| `onPlayPause` (required) | `() => void` |  | Called when the play/pause button is pressed (or `K` while the controls have focus). |
| `playing` (required) | `boolean` |  | Whether the media is playing; switches the play/pause button. |
| `aria-label` | `string` | `Media controls` | Accessible name of the controls group. |
| `className` | `string` |  | Additional class names for the root `role="group"` element. |
| `disabled` | `boolean` | `false` | Disables all controls, e.g. while the media is loading. |
| `muted` | `boolean` | `false` | Whether the sound is muted; switches the mute button. |
| `onFullscreen` | `(() => void)` |  | Shows a fullscreen button. |
| `onMutedChange` | `((muted: boolean) => void)` |  | Called with the new muted state (mute button or `M`). Hides the mute button if omitted. |
| `onNext` | `(() => void)` |  | Shows a next-track button. |
| `onPrevious` | `(() => void)` |  | Shows a previous-track button. |
| `onSeek` | `((time: number) => void)` |  | Called with the target time in seconds when the user seeks: at the end of a drag on the seek bar, on its arrow keys, or with ←/→ (±5 s) while the controls have focus. |
| `onVolumeChange` | `((volume: number) => void)` |  | Called with the new volume (0–1) while the volume slider moves. Hides the slider if omitted. |
| `size` | `'sm' \| 'md'` | `'md'` | Button and text size. |
| `title` | `ReactNode` |  | Title shown above the controls, e.g. the track name. |
| `volume` | `number` | `1` | Volume from 0 to 1. |

# MediaPlayer

Plays a video or audio file with the HUD [MediaControls](https://joeyash.github.io/jarvis_ui_lib/components/media-controls.md) instead of
the browser's own controls. Through its ref, code (or a voice assistant) can play, pause, seek
and change the volume.

```ts
import { MediaPlayer } from 'jarvis-react-ui';
```

## Video

Pass the file as `src`. The video sits in a 16:9 frame as wide as its container, with a large play
button until it starts. `poster` shows an image before playback, and `captions` adds a WebVTT
captions track, which you should provide for spoken content.

```tsx
import { MediaPlayer } from 'jarvis-react-ui';

export default function Video() {
    return (
        <MediaPlayer
            title="Flower · CC0"
            src="https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4"
        />
    );
}
```

## Audio

`kind="audio"` renders a compact player: a [WaveStrip](https://joeyash.github.io/jarvis_ui_lib/components/wave-strip.md) that moves while
playing, the title and the controls.

```tsx
import { MediaPlayer } from 'jarvis-react-ui';

export default function Audio() {
    return (
        <MediaPlayer
            kind="audio"
            title="T-Rex roar · CC0"
            src="https://interactive-examples.mdn.mozilla.net/media/cc0-audio/t-rex-roar.mp3"
            size="sm"
        />
    );
}
```

## Control it from code

The ref is a `MediaHandle` with `play()`, `pause()`, `seek(seconds)`, `setVolume(0–1)` and
`setMuted(boolean)`. [YouTubePlayer](https://joeyash.github.io/jarvis_ui_lib/components/you-tube-player.md) has the same handle, so commands
like "pause" or "skip 30 seconds" work the same for both.

```tsx
import { useRef } from 'react';
import { Button, MediaPlayer } from 'jarvis-react-ui';
import type { MediaHandle } from 'jarvis-react-ui';

export default function Programmatic() {
    const player = useRef<MediaHandle>(null);

    return (
        <div className="flex flex-col gap-3">
            <div className="flex flex-wrap gap-2">
                <Button size="sm" onClick={() => void player.current?.play()}>
                    Play
                </Button>
                <Button size="sm" onClick={() => player.current?.pause()}>
                    Pause
                </Button>
                <Button size="sm" onClick={() => player.current?.seek(2)}>
                    Jump to 0:02
                </Button>
                <Button size="sm" onClick={() => player.current?.setVolume(0.2)}>
                    Volume 20 %
                </Button>
            </div>
            <MediaPlayer
                ref={player}
                src="https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4"
            />
        </div>
    );
}
```

> **Warning: Autoplay**
>
> Browsers only autoplay media without sound, or after the user interacted with the page. With
> `autoPlay`, also set `defaultMuted` if playback must start on its own.

## Sound

The controls play `hover_button`, `click`, `drag_start` and `drag_end` through the nearest
`SfxProvider`; the media itself plays through the normal browser audio. See
[Sound effects](https://joeyash.github.io/jarvis_ui_lib/getting-started/sound.md).

## Accessibility

- Uses the native `<video>` / `<audio>` element with a `<track kind="captions">` for `captions`.
- All controls are keyboard accessible, with the shortcuts of
  [MediaControls](https://joeyash.github.io/jarvis_ui_lib/components/media-controls.md) (`K`, `M`, ←, →).
- If the media fails to load, the controls are disabled and **Media unavailable** is shown.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `src` (required) | `string` |  | URL of the video or audio file. |
| `autoPlay` | `boolean` | `false` | Starts playing on mount. Browsers allow it only muted or after a user gesture. |
| `captions` | `MediaCaptions` |  | Captions for a video; strongly recommended for spoken content. |
| `className` | `string` |  | Additional class names for the root element. |
| `defaultMuted` | `boolean` | `false` | Starts muted. |
| `defaultVolume` | `number` | `1` | Initial volume from 0 to 1. |
| `kind` | `'video' \| 'audio'` | `'video'` | `video` shows the picture in a 16:9 frame; `audio` shows a compact player. |
| `loop` | `boolean` | `false` | Starts again at the end. |
| `onEnded` | `(() => void)` |  | Called when playback reaches the end (not with `loop`). |
| `onError` | `(() => void)` |  | Called when the media cannot be loaded or played. |
| `poster` | `string` |  | Image shown before a video starts. |
| `size` | `'sm' \| 'md'` | `'md'` | Size of the controls. |
| `title` | `ReactNode` |  | Title shown in the player, e.g. the track or clip name. |

Also accepts inherited props from `RefAttributes` (1), `Attributes` (1).

### Type `MediaCaptions`

A captions track for a video, in WebVTT format.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `label` (required) | `string` |  | Name shown in the browser's captions menu, e.g. `English`. |
| `src` (required) | `string` |  | URL of the `.vtt` file. |
| `srcLang` (required) | `string` |  | Language of the captions, e.g. `en`. |

# YouTubePlayer

Plays a YouTube video through the YouTube IFrame Player API, with the HUD
[MediaControls](https://joeyash.github.io/jarvis_ui_lib/components/media-controls.md) instead of YouTube's own controls.

```ts
import { YouTubePlayer } from 'jarvis-react-ui';
```

## Basic

Pass the video id from the URL (`youtube.com/watch?v=<videoId>`). The controls are enabled once the
player is ready. `start` begins at a position in seconds; the ref is the same `MediaHandle` as
[MediaPlayer](https://joeyash.github.io/jarvis_ui_lib/components/media-player.md)'s.

```tsx
import { YouTubePlayer } from 'jarvis-react-ui';

export default function Basic() {
    return <YouTubePlayer videoId="aqz-KE-bpKQ" title="Big Buck Bunny · Blender Foundation" />;
}
```

## In a floating window

A typical assistant flow: the user asks for a video, the app looks up its id and opens a
[floating window](https://joeyash.github.io/jarvis_ui_lib/components/window-manager.md) with the player.

```tsx
import { useState } from 'react';
import { Button, WindowManager, YouTubePlayer } from 'jarvis-react-ui';
import type { ManagedWindow } from 'jarvis-react-ui';

export default function InWindow() {
    const [windows, setWindows] = useState<ManagedWindow[]>([]);

    const open = () =>
        setWindows([
            {
                id: 'video',
                title: 'Now playing',
                floating: true,
                defaultRect: { x: 24, y: 70, w: 420, h: 330 },
                itemRenderer: () => <YouTubePlayer videoId="aqz-KE-bpKQ" size="sm" autoPlay />,
            },
        ]);

    return (
        <>
            <div className="absolute top-3 left-3 z-[1]">
                <Button variant="primary" onClick={open} disabled={windows.length > 0}>
                    Show video
                </Button>
            </div>
            <WindowManager
                windows={windows}
                assignments={{}}
                onAssignmentsChange={() => undefined}
                onClose={() => setWindows([])}
            />
        </>
    );
}
```

## External script and privacy

> **Warning: Loads code from YouTube**
>
> On first mount the component adds the script `https://www.youtube.com/iframe_api` to the page
> (once; an existing `window.YT` is reused). The video itself is served by YouTube. By default it
> uses the privacy-enhanced host `youtube-nocookie.com`, which sets no cookies until the video
> plays; `privacyEnhanced={false}` uses `youtube.com`. Mention the embed in your privacy notice
> and allow both hosts in a Content Security Policy (`script-src`, `frame-src`).

## When a video cannot be embedded

Some owners disable embedding (error `101` or `150`). The player then shows **Embedding is
disabled for this video** with a **Watch on YouTube** link. Invalid ids, removed videos and a
blocked script show their own message; `onError` receives the code.

## Sound

The controls play `hover_button`, `click`, `drag_start` and `drag_end` through the nearest
`SfxProvider`. See [Sound effects](https://joeyash.github.io/jarvis_ui_lib/getting-started/sound.md).

## Accessibility

- YouTube's own controls and keyboard shortcuts are turned off; the HUD controls and their
  shortcuts (`K`, `M`, ←, →) replace them.
- Error messages are announced through `role="alert"`.
- Captions are controlled by YouTube's settings for the video.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `videoId` (required) | `string` |  | YouTube video id, e.g. `aqz-KE-bpKQ` from `youtube.com/watch?v=aqz-KE-bpKQ`. |
| `autoPlay` | `boolean` | `false` | Starts playing when ready. Browsers allow it only muted or after a user gesture. |
| `className` | `string` |  | Additional class names for the root element. |
| `defaultMuted` | `boolean` | `false` | Starts muted. |
| `onEnded` | `(() => void)` |  | Called when the video ends. |
| `onError` | `((code: number) => void)` |  | Called with the YouTube error code (2 invalid id, 5 player error, 100 not found, 101/150 embedding not allowed). |
| `privacyEnhanced` | `boolean` | `true` | Loads the player from `youtube-nocookie.com` (privacy-enhanced mode: no cookies until the video plays). |
| `size` | `'sm' \| 'md'` | `'md'` | Size of the controls. |
| `start` | `number` | `0` | Starts at this position in seconds. |
| `title` | `ReactNode` |  | Title shown above the video. |

Also accepts inherited props from `RefAttributes` (1), `Attributes` (1).

# WebFrame

Shows a web page inside your interface, for example in a floating window, with a small toolbar:
the address, reload and "open in new tab".

```ts
import { WebFrame } from 'jarvis-react-ui';
```

## Basic

Pass the page as `url`; only `http:` and `https:` addresses are loaded, anything else shows an
error. `title` names the embedded page for screen readers (default: the host). Without `height` the
frame fills the height of its container, e.g. a window; `height` sets a fixed height in pixels.

```tsx
import { WebFrame } from 'jarvis-react-ui';

export default function Basic() {
    return (
        <WebFrame
            url="https://www.openstreetmap.org/export/embed.html?bbox=8.52,47.36,8.56,47.38"
            title="Map"
            height={320}
        />
    );
}
```

## In a floating window

```tsx
import { useState } from 'react';
import { Button, WebFrame, WindowManager } from 'jarvis-react-ui';
import type { ManagedWindow } from 'jarvis-react-ui';

export default function InWindow() {
    const [windows, setWindows] = useState<ManagedWindow[]>([]);

    const open = () =>
        setWindows([
            {
                id: 'browser',
                title: 'Browser',
                floating: true,
                defaultRect: { x: 24, y: 70, w: 480, h: 320 },
                itemRenderer: () => <WebFrame url="https://example.com" />,
            },
        ]);

    return (
        <>
            <div className="absolute top-3 left-3 z-[1]">
                <Button variant="primary" onClick={open} disabled={windows.length > 0}>
                    Open browser window
                </Button>
            </div>
            <WindowManager
                windows={windows}
                assignments={{}}
                onAssignmentsChange={() => undefined}
                onClose={() => setWindows([])}
            />
        </>
    );
}
```

## Pages that cannot be embedded

> **Warning: Many sites forbid embedding**
>
> Sites such as GitHub or Google send `X-Frame-Options` or a `frame-ancestors` policy, and the
> browser then leaves the frame empty. A page cannot detect this reliably, so the "Open in new
> tab" button is always there. For a real browser window inside your app, use a webview in
> Electron or Tauri.

```tsx
import { WebFrame } from 'jarvis-react-ui';

export default function Blocked() {
    // github.com forbids embedding: the frame stays empty, "Open in new tab" still works.
    return <WebFrame url="https://github.com" height={200} />;
}
```

## Security

The page runs in a sandboxed iframe. The default `sandbox` allows scripts, its own origin, forms and
popups, which most pages need; pass a stricter value (`""` blocks everything) for untrusted content.
`allow` grants features like `fullscreen` or `autoplay`. The page gets only the origin as referrer,
and "open in new tab" opens without `window.opener`.

## Sound

The toolbar buttons play `hover_button` and `click` through the nearest `SfxProvider`. See
[Sound effects](https://joeyash.github.io/jarvis_ui_lib/getting-started/sound.md).

## Accessibility

- The iframe is named by `title` (or the host). The toolbar buttons are named **Reload** and **Open
  in new tab**.
- An invalid address is announced with `role="alert"`.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `url` (required) | `string` |  | Address of the page to show. Only `http:` and `https:` URLs are loaded. |
| `allow` | `string` |  | Features the page may use (the iframe `allow` attribute), e.g. `'fullscreen; autoplay'`. |
| `className` | `string` |  | Additional class names for the root element. |
| `height` | `number` |  | Fixed height in px. Without it the frame fills the height of its container. |
| `onLoad` | `(() => void)` |  | Called when the page has loaded. |
| `sandbox` | `string` | `allow-scripts allow-same-origin allow-forms allow-popups` | Restrictions for the embedded page (the iframe `sandbox` attribute). Pass an empty string for the strictest sandbox. |
| `title` | `string` | `the URL's host` | Accessible name of the embedded page, also shown in the toolbar. |
| `toolbar` | `boolean` | `true` | Shows the toolbar with address, reload and "open in new tab". |

# Window

Window is the draggable, resizable panel shell that [WindowManager](https://joeyash.github.io/jarvis_ui_lib/components/window-manager.md)
places on its slot grid. Use it directly when you build your own window layout; for the standard
nine-slot HUD, use WindowManager.

```ts
import { Window } from 'jarvis-react-ui';
```

## Basic

A Window is absolutely positioned at `position` (`x`, `y`, `w`, `h` in pixels) inside its nearest
positioned ancestor. The header shows `ix`, `title` and `badge`, and `itemRenderer` renders the
body.

```tsx
import { Window } from 'jarvis-react-ui';

export default function Basic() {
    return (
        <div className="relative h-[200px] w-[320px]">
            <Window
                id="system"
                title="System"
                ix="◈"
                badge="LIVE"
                position={{ x: 0, y: 0, w: 320, h: 200 }}
                draggable={false}
                itemRenderer={() => 'CPU 42% · RAM 61% · NET 12 MB/s'}
            />
        </div>
    );
}
```

## Compact and expanded

Every window has a `mode`:

- `compact` is the docked state. Resize handles are hidden, and the header shows an **Undock**
  button when you pass `onModeToggle`.
- `expanded` is the free-floating state. The window gets an accent hairline and glow, the eight edge
  and corner handles become active (when `resizable`), and the header shows a **Dock** button.

Window does not switch modes itself. Clicking the dock/undock button or double-clicking the header
calls `onModeToggle`, and you set the new `mode`. `itemRenderer` receives `{ mode, focused,
dragging }`, so the body can show a compact summary while docked and more detail while expanded.

WindowManager uses the modes like this: a compact window lives in a slot, and dragging its header
moves it to another slot or swaps it with the window there, with
[SnapOverlay](https://joeyash.github.io/jarvis_ui_lib/components/snap-overlay.md) and [SwapOverlay](https://joeyash.github.io/jarvis_ui_lib/components/swap-overlay.md) as feedback. An
expanded window floats above the grid at a larger size, can be dragged anywhere and resized, and
the reset button docks it back into its home slot.

## Dragging and resizing

The window never moves itself: `position` is controlled. `onDragMove` and `onResizeMove` report the
pointer offset from the start of the gesture (`dx`, `dy`), and `onResizeMove` also reports the
handle direction (`n`, `se`, ...). Remember the rect when the gesture starts and apply the offset
to it. `onDragStart` and `onResizeStart` receive the native `pointerdown` `PointerEvent`, like the
move and end callbacks. Drag the header below, undock the window, then drag its edges.

```tsx
import { useRef, useState } from 'react';
import { Window } from 'jarvis-react-ui';
import type { PanelMode, ResizeDir } from 'jarvis-react-ui';

type Rect = { x: number; y: number; w: number; h: number };

const START: Rect = { x: 16, y: 16, w: 300, h: 150 };

function resize(r: Rect, dir: ResizeDir, dx: number, dy: number): Rect {
    const next = { ...r };
    if (dir.includes('e')) next.w = Math.max(200, r.w + dx);
    if (dir.includes('s')) next.h = Math.max(100, r.h + dy);
    if (dir.includes('w')) next.w = Math.max(200, r.w - dx);
    if (dir.includes('n')) next.h = Math.max(100, r.h - dy);
    if (dir.includes('w')) next.x = r.x + r.w - next.w;
    if (dir.includes('n')) next.y = r.y + r.h - next.h;
    return next;
}

export default function DragAndResize() {
    const [rect, setRect] = useState<Rect>(START);
    const [mode, setMode] = useState<PanelMode>('compact');
    const origin = useRef(rect);

    return (
        <div className="relative h-[340px] w-full">
            <Window
                id="notes"
                title="Notes"
                ix="▸"
                position={rect}
                mode={mode}
                onDragStart={() => {
                    origin.current = rect;
                }}
                onDragMove={(_id, dx, dy) =>
                    setRect({
                        ...origin.current,
                        x: origin.current.x + dx,
                        y: origin.current.y + dy,
                    })
                }
                onResizeStart={() => {
                    origin.current = rect;
                }}
                onResizeMove={(_id, dir, dx, dy) => setRect(resize(origin.current, dir, dx, dy))}
                onModeToggle={() => setMode((m) => (m === 'compact' ? 'expanded' : 'compact'))}
                onReset={() => {
                    setRect(START);
                    setMode('compact');
                }}
                itemRenderer={({ mode: m }) =>
                    m === 'compact'
                        ? 'Drag the header. Undock to resize.'
                        : 'Expanded: drag the edges and corners to resize.'
                }
            />
        </div>
    );
}
```

During a gesture the root element gets `data-state="dragging"` or `"resizing"`. The other values of
`state` (`snap-preview`, `swap-preview`, `settling`, `focused`) are styling hooks for the parent:
`settling` animates position and size changes, and `focused` raises the window above its siblings.
Position and size reach the stylesheet as the CSS variables `--lib-window-x`, `--lib-window-y`,
`--lib-window-w` and `--lib-window-h` on the root element.
To build drag-and-drop between slots, combine Window with [useSlotDrag](https://joeyash.github.io/jarvis_ui_lib/hooks/use-slot-drag.md) and
the [slot grid helpers](https://joeyash.github.io/jarvis_ui_lib/utilities/slot-grid.md).

## Header actions

The reset, dock/undock and close buttons are only rendered when you pass `onReset`, `onModeToggle`
or `onClose`. Pressing them never starts a drag. `stackIndex` raises an expanded window above
others with a lower index; [WindowManager](https://joeyash.github.io/jarvis_ui_lib/components/window-manager.md) sets it for you.

```tsx
import { useState } from 'react';
import { Button, Window } from 'jarvis-react-ui';

export default function HeaderActions() {
    const [open, setOpen] = useState(true);
    const [resets, setResets] = useState(0);

    if (!open) return <Button onClick={() => setOpen(true)}>Reopen window</Button>;

    return (
        <div className="relative h-[180px] w-[320px]">
            <Window
                id="agenda"
                title="Agenda"
                ix="▦"
                position={{ x: 0, y: 0, w: 320, h: 180 }}
                draggable={false}
                onReset={() => setResets((n) => n + 1)}
                onClose={() => setOpen(false)}
                itemRenderer={() => `09:30 · Standup — reset ${resets}×`}
            />
        </div>
    );
}
```

## Sound

Through the nearest `SfxProvider`:

- Dragging the header plays `drag_start`, loops `drag_move` and plays `drag_end`.
- Resizing loops `resize` until the pointer is released.
- The reset button plays `click` and `recall`; the dock/undock button plays `click` plus `expand`
  (undock) or `collapse` (dock); the close button plays `click` and `menu_close`.
- Double-clicking the header plays the same `expand` or `collapse` sound as the dock/undock button
  (without the `click`).
- Hovering the window plays `hover_panel`; hovering a header button plays `hover_button`.

See [Sound effects](https://joeyash.github.io/jarvis_ui_lib/getting-started/sound.md).

## Accessibility

- The root is a non-modal `role="region"` landmark. `aria-labelledby` points at the title element,
  so any `title` (string or element) names it; without a title the region is unnamed.
- Window does not move or trap focus; Tab moves through its content in document order like any
  other part of the page.
- The header buttons are native buttons named **Reset window**, **Undock window** / **Dock window**
  and **Close window**, so they work with the keyboard. The dock/undock button is the keyboard
  equivalent of the header double-click.
- With `closeOnEscape` and `onClose`, the window is focusable (`tabIndex={-1}`) and Escape calls
  `onClose` while focus is inside it.
- Dragging and resizing are pointer-only: there are no arrow-key or other keyboard shortcuts to
  move or resize a window. Offer another way to move or resize content when keyboard users need
  it.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` (required) | `string` |  | Unique window id; passed back as the first argument of every callback. |
| `itemRenderer` (required) | `(props: PanelContentRenderProps) => ReactNode` |  | Renders the window body; receives the current `mode`, `focused` and `dragging`. |
| `position` (required) | `{ x: number; y: number; w: number; h: number; }` |  | Position and size in pixels, relative to the nearest positioned ancestor. The window does not move itself: apply the deltas from `onDragMove` / `onResizeMove` to this rect. |
| `badge` | `ReactNode` |  | Tag shown at the right end of the header. |
| `className` | `string` |  | Extra classes for the root `<div role="region">` element. |
| `closeOnEscape` | `boolean` | `false` | Calls `onClose` when Escape is pressed while focus is inside the window. |
| `draggable` | `boolean` | `true` | Whether the header can be dragged. |
| `focused` | `boolean` | `false` | Whether the window is focused; highlights the panel chrome. |
| `ix` | `ReactNode` |  | Index glyph shown before the title in the header. |
| `mode` | `'compact' \| 'expanded'` | `'compact'` | `compact` hides the resize handles and shows the undock button, `expanded` shows the handles and the dock button. |
| `onClose` | `((id: string) => void)` |  | Shows a close button in the header and is called when it is clicked. Closing plays the `menu_close` sound. |
| `onDragEnd` | `((id: string, e: PointerEvent) => void)` |  | Called when the header drag ends (pointer up or cancel). |
| `onDragMove` | `((id: string, dx: number, dy: number, e: PointerEvent) => void)` |  | Called on every pointer move of a header drag with the offset from the drag start. |
| `onDragStart` | `((id: string, e: PointerEvent) => void)` |  | Called with the native `pointerdown` event when a header drag starts (not on the header buttons). |
| `onFocus` | `((id: string) => void)` |  | Called with the id on any pointer down inside the window. |
| `onModeToggle` | `((id: string) => void)` |  | Shows a dock/undock button in the header; called when it is clicked or the header is double-clicked. Both play the `expand` / `collapse` sound. |
| `onReset` | `((id: string) => void)` |  | Shows a reset button in the header and is called when it is clicked. |
| `onResizeEnd` | `((id: string, e: PointerEvent) => void)` |  | Called when the resize ends. |
| `onResizeMove` | `((id: string, dir: ResizeDir, dx: number, dy: number, e: PointerEvent) => void)` |  | Called on every pointer move of a resize with the handle direction and offset. |
| `onResizeStart` | `((id: string, dir: ResizeDir, e: PointerEvent) => void)` |  | Called with the native `pointerdown` event when a resize starts on one of the eight edge and corner handles. |
| `resizable` | `boolean` | `true` | Whether the resize handles are rendered; they are visible in `expanded` mode only. |
| `stackIndex` | `number` | `0` | Stacking rank among expanded windows; a higher rank is drawn on top. Set by `WindowManager` to bring the last used floating window to the front. |
| `state` | `'idle' \| 'dragging' \| 'snap-preview' \| 'swap-preview' \| 'settling' \| 'focused' \| 'resizing'` | `'idle'` | Visual state; `dragging` and `resizing` are also set automatically during a gesture. |
| `title` | `ReactNode` |  | Header title. It also names the window region (`aria-labelledby` points at it). |

### Type `PanelContentRenderProps`

Window state passed to `itemRenderer`, so content can adapt to docked or floating mode.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `dragging` (required) | `boolean` |  | Whether the window is being dragged or resized right now. |
| `focused` (required) | `boolean` |  | Whether the window is currently focused. |
| `mode` (required) | `PanelMode` |  | `compact` while docked in a slot, `expanded` while free-floating. |

### Type `ResizeDir`

Edge or corner a window is resized from, as compass directions (`se` = bottom-right corner).

```ts
type ResizeDir = 'n' | 's' | 'e' | 'w' | 'ne' | 'nw' | 'se' | 'sw';
```

### Type `PanelMode`

`compact`: docked in a slot. `expanded`: free-floating and resizable.

```ts
type PanelMode = 'compact' | 'expanded';
```

# SnapOverlay

SnapOverlay draws the nine slots of the window grid as glowing drop zones and highlights the one
under the pointer. [WindowManager](https://joeyash.github.io/jarvis_ui_lib/components/window-manager.md) shows it while a docked window is
dragged.

```ts
import { SnapOverlay } from 'jarvis-react-ui';
```

## Drop zones

While `active`, every slot in `slotRects` is drawn as an outlined zone, and `hoveredSlot` gets a
stronger fill and a pulse. The overlay is a `position: fixed` layer over its containing block (the
viewport, or the nearest ancestor with a `transform`) and ignores the pointer, so it never blocks
the drag below it. Each zone gets its rect as the CSS variables `--lib-snap-zone-x`, `-y`, `-w`
and `-h`. Move the pointer over the stage.

```tsx
import { useEffect, useRef, useState } from 'react';
import type { PointerEvent } from 'react';
import { Mono, SLOT_IDS, SnapOverlay, computeSlot, slotAtPoint } from 'jarvis-react-ui';
import type { SlotId, SlotRect } from 'jarvis-react-ui';

// The slot grid is made for a full viewport; to fit the demo frame it is computed at 2× and halved.
// In an app, pass the viewport size: computeAllSlots(innerWidth, innerHeight).
function demoSlots(w: number, h: number): Record<SlotId, SlotRect> {
    const rects = {} as Record<SlotId, SlotRect>;
    for (const id of SLOT_IDS) {
        const r = computeSlot(id, w * 2, h * 2);
        rects[id] = { x: r.x / 2, y: r.y / 2, w: r.w / 2, h: r.h / 2 };
    }
    return rects;
}

export default function HoverSlots() {
    const stageRef = useRef<HTMLDivElement>(null);
    const [size, setSize] = useState({ w: 0, h: 0 });
    const [hovered, setHovered] = useState<SlotId | null>(null);

    useEffect(() => {
        const stage = stageRef.current;
        if (!stage) return;
        const observer = new ResizeObserver(() =>
            setSize({ w: stage.clientWidth, h: stage.clientHeight }),
        );
        observer.observe(stage);
        return () => observer.disconnect();
    }, []);

    const slotRects = demoSlots(size.w, size.h);

    const handlePointerMove = (e: PointerEvent<HTMLDivElement>) => {
        const box = e.currentTarget.getBoundingClientRect();
        setHovered(slotAtPoint(e.clientX - box.left, e.clientY - box.top, slotRects));
    };

    return (
        <div className="flex w-full flex-col gap-3">
            <Mono size="sm" secondary>
                Move the pointer over the stage · hovered: {hovered ?? 'none'}
            </Mono>
            {/* transform-gpu makes the stage the containing block of the fixed overlay. */}
            <div
                ref={stageRef}
                className="relative h-[300px] w-full overflow-hidden transform-gpu"
                onPointerMove={handlePointerMove}
                onPointerLeave={() => setHovered(null)}
            >
                <SnapOverlay active={size.w > 0} slotRects={slotRects} hoveredSlot={hovered} />
            </div>
        </div>
    );
}
```

## In WindowManager

WindowManager renders SnapOverlay for every drag of a `compact` window: `active` is on for the whole
drag, `slotRects` is the grid computed from the WindowManager's size, and `hoveredSlot` is the slot
under the pointer. When that slot is occupied, [SwapOverlay](https://joeyash.github.io/jarvis_ui_lib/components/swap-overlay.md) also marks
the window that would be swapped. Expanded windows drag freely and show no overlay.

## Standalone use

Use SnapOverlay when you lay out [Window](https://joeyash.github.io/jarvis_ui_lib/components/window.md) elements yourself:

- Compute the rects with `computeAllSlots(width, height)` from the
  [slot grid helpers](https://joeyash.github.io/jarvis_ui_lib/utilities/slot-grid.md).
- Track the drag with [useSlotDrag](https://joeyash.github.io/jarvis_ui_lib/hooks/use-slot-drag.md): pass `slotDragState.dragging` to
  `active` and `slotDragState.snapTarget` to `hoveredSlot`.
- On drop, assign the window to the final `snapTarget`.

```tsx
import { SnapOverlay, computeAllSlots } from 'jarvis-react-ui';

const slotRects = computeAllSlots(window.innerWidth, window.innerHeight);

<SnapOverlay
    active={slotDragState.dragging}
    slotRects={slotRects}
    hoveredSlot={slotDragState.snapTarget}
/>;
```

## Accessibility

The overlay is decorative: its root is `aria-hidden` and it takes no pointer events. Announce the
result of a drop elsewhere if it matters, and offer a keyboard alternative to dragging.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `active` (required) | `boolean` |  | Whether the slot zones are drawn; while `false` only an empty layer is rendered. |
| `hoveredSlot` (required) | `SlotId \| null` |  | Slot under the pointer; its zone is highlighted and pulses. `null` highlights none. |
| `slotRects` (required) | `Record<SlotId, SlotRect>` |  | Rect of every slot, usually from `computeAllSlots(width, height)`. |
| `className` | `string` |  | Extra classes for the root `<div>` element (the fixed full-size layer). |

### Type `SlotId`

Fixed 3×3 Dock grid slot geometry.

Left column (top → bottom):   L1, L2, L3
Right column (top → bottom):  R1, R2, R3
Bottom strip (left → right):  B1, B2, B3

```ts
type SlotId = 'L1' | 'L2' | 'L3' | 'R1' | 'R2' | 'R3' | 'B1' | 'B2' | 'B3';
```

### Type `SlotRect`

Rectangular geometry (pixel-absolute, viewport-relative).

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `h` (required) | `number` |  | Height in px. |
| `w` (required) | `number` |  | Width in px. |
| `x` (required) | `number` |  | Left edge in px. |
| `y` (required) | `number` |  | Top edge in px. |

# SwapOverlay

SwapOverlay draws a dashed ghost over the window that a drop would swap with.
[WindowManager](https://joeyash.github.io/jarvis_ui_lib/components/window-manager.md) shows it while a docked window is dragged onto an
occupied slot.

```ts
import { SwapOverlay } from 'jarvis-react-ui';
```

## Swap ghost

When `active` is on and `ghostRect` is set, a dashed outline covers that rect; `hovered` gives it a
stronger fill and glow. Like [SnapOverlay](https://joeyash.github.io/jarvis_ui_lib/components/snap-overlay.md), the overlay is a
`position: fixed` layer over its containing block and ignores the pointer. The ghost gets its rect
as the CSS variables `--lib-swap-ghost-x`, `-y`, `-w` and `-h`.

```tsx
import { useState } from 'react';
import { SwapOverlay, Switch, Window } from 'jarvis-react-ui';

const TARGET = { x: 0, y: 0, w: 300, h: 160 };

export default function Basic() {
    const [active, setActive] = useState(true);
    const [hovered, setHovered] = useState(false);

    return (
        <div className="flex flex-col items-center gap-4">
            <div className="flex gap-6">
                <Switch label="Active" checked={active} onCheckedChange={setActive} />
                <Switch label="Hovered" checked={hovered} onCheckedChange={setHovered} />
            </div>
            {/* transform-gpu makes this box the containing block of the fixed overlay. */}
            <div className="relative h-[160px] w-[300px] transform-gpu">
                <Window
                    id="agenda"
                    title="Agenda"
                    ix="▦"
                    position={TARGET}
                    draggable={false}
                    itemRenderer={() => '09:30 · Standup'}
                />
                <SwapOverlay active={active} ghostRect={TARGET} hovered={hovered} />
            </div>
        </div>
    );
}
```

## In WindowManager

During a drag of a `compact` window, WindowManager checks whether the slot under the pointer holds
another window. If it does, SwapOverlay is turned on with `hovered`, and `ghostRect` is that
window's slot, so the user sees which window will trade places. SnapOverlay keeps highlighting the
target slot at the same time.

## Standalone use

With [useSlotDrag](https://joeyash.github.io/jarvis_ui_lib/hooks/use-slot-drag.md), `slotDragState.swapTarget` is the id of the window in the
hovered slot. Look up its slot rect (see the [slot grid helpers](https://joeyash.github.io/jarvis_ui_lib/utilities/slot-grid.md)) and pass it
as `ghostRect`:

```tsx
const { swapTarget } = slotDragState;
const swapRect = swapTarget !== null ? slotRects[assignments[swapTarget]] : null;

<SwapOverlay active={swapRect !== null} ghostRect={swapRect} hovered />;
```

## Accessibility

The overlay is decorative: its root is `aria-hidden` and it takes no pointer events.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `active` (required) | `boolean` |  | Whether the ghost is drawn; nothing is drawn while `false` or without a `ghostRect`. |
| `ghostRect` (required) | `SlotRect \| null` |  | Rect of the window that would be swapped, or `null` for no ghost. |
| `className` | `string` |  | Extra classes for the root `<div>` element (the fixed full-size layer). |
| `hovered` | `boolean` | `false` | Highlights the ghost with a stronger fill and glow, e.g. while the drop would swap. |

### Type `SlotRect`

Rectangular geometry (pixel-absolute, viewport-relative).

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `h` (required) | `number` |  | Height in px. |
| `w` (required) | `number` |  | Width in px. |
| `x` (required) | `number` |  | Left edge in px. |
| `y` (required) | `number` |  | Top edge in px. |

# SlotGhost

SlotGhost is a dashed placeholder for an empty slot, with an optional caption. Use it to show
where windows can go in a custom window layout.

```ts
import { SlotGhost } from 'jarvis-react-ui';
```

## Basic

SlotGhost is absolutely positioned at `rect` inside its nearest positioned ancestor; the rect is
applied through the CSS variables `--lib-slot-ghost-x`, `-y`, `-w` and `-h`. `label` adds a small
uppercase caption in the middle.

```tsx
import { SlotGhost } from 'jarvis-react-ui';

export default function Basic() {
    return (
        <div className="relative h-[120px] w-[412px]">
            <SlotGhost rect={{ x: 0, y: 0, w: 200, h: 120 }} label="Empty slot" />
            <SlotGhost rect={{ x: 212, y: 0, w: 200, h: 120 }} />
        </div>
    );
}
```

## Empty slots

Render a SlotGhost for every slot without a window, so the grid stays readable while it is partly
empty. Unlike the overlays, SlotGhost is positioned `absolute`, not `fixed`, and sits in the same
layer as your windows.

```tsx
import { useEffect, useRef, useState } from 'react';
import { SLOT_IDS, SlotGhost, Window, computeSlot } from 'jarvis-react-ui';
import type { SlotId, SlotRect } from 'jarvis-react-ui';

const ASSIGNED: Partial<Record<SlotId, string>> = { L1: 'System', R2: 'Agenda', B2: 'Transcript' };

// The slot grid is made for a full viewport; to fit the demo frame it is computed at 2× and halved.
function demoSlot(id: SlotId, w: number, h: number): SlotRect {
    const r = computeSlot(id, w * 2, h * 2);
    return { x: r.x / 2, y: r.y / 2, w: r.w / 2, h: r.h / 2 };
}

export default function EmptySlots() {
    const stageRef = useRef<HTMLDivElement>(null);
    const [size, setSize] = useState({ w: 0, h: 0 });

    useEffect(() => {
        const stage = stageRef.current;
        if (!stage) return;
        const observer = new ResizeObserver(() =>
            setSize({ w: stage.clientWidth, h: stage.clientHeight }),
        );
        observer.observe(stage);
        return () => observer.disconnect();
    }, []);

    return (
        <div ref={stageRef} className="relative h-[340px] w-full overflow-hidden">
            {size.w > 0 &&
                SLOT_IDS.map((id) => {
                    const rect = demoSlot(id, size.w, size.h);
                    const title = ASSIGNED[id];
                    return title === undefined ? (
                        <SlotGhost key={id} rect={rect} label={id} />
                    ) : (
                        <Window
                            key={id}
                            id={id}
                            title={title}
                            position={rect}
                            draggable={false}
                            itemRenderer={() => id}
                        />
                    );
                })}
        </div>
    );
}
```

> **Note: Not part of WindowManager**
>
> [WindowManager](https://joeyash.github.io/jarvis_ui_lib/components/window-manager.md) does not render SlotGhost; its empty slots stay
> blank. SlotGhost is a building block for layouts you assemble yourself from
> [Window](https://joeyash.github.io/jarvis_ui_lib/components/window.md), [useSlotDrag](https://joeyash.github.io/jarvis_ui_lib/hooks/use-slot-drag.md) and the [slot grid
> helpers](https://joeyash.github.io/jarvis_ui_lib/utilities/slot-grid.md).

## Accessibility

SlotGhost is decorative: its root is `aria-hidden`, so the label is not announced, and it takes no
pointer events.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `rect` (required) | `SlotRect` |  | Position and size in pixels, relative to the nearest positioned ancestor. |
| `className` | `string` |  | Extra classes for the root `<div>` element (the dashed placeholder). |
| `label` | `string` |  | Small uppercase caption centred in the placeholder, e.g. the slot id. |

### Type `SlotRect`

Rectangular geometry (pixel-absolute, viewport-relative).

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `h` (required) | `number` |  | Height in px. |
| `w` (required) | `number` |  | Width in px. |
| `x` (required) | `number` |  | Left edge in px. |
| `y` (required) | `number` |  | Top edge in px. |

# CssOrb

CssOrb is the animated JARVIS orb, built from CSS gradients, rings and a few orbiting particles.
It shows the assistant's state at a glance and needs no WebGL. For the Three.js particle version
see [ThreeOrb](https://joeyash.github.io/jarvis_ui_lib/components/three-orb.md).

```ts
import { CssOrb } from 'jarvis-react-ui';
```

## States

`state` takes an `AppOrbState`. CssOrb gives five of them their own look:

| State       | Look                                                                  |
| ----------- | --------------------------------------------------------------------- |
| `idle`      | The blue core floats slowly up and down.                              |
| `listening` | The core breathes, and three pulse rings expand outward from it.      |
| `thinking`  | The core's color slowly shifts in hue and saturation.                 |
| `speaking`  | The core's glow pulses quickly, like a voice level.                   |
| `working`   | Core, rings, ticks, pulses and particles turn amber; the glow pulses. |

`follow_up`, the sixth `AppOrbState` value, has no style of its own and looks like `idle`. The demo
cycles through the five styled states every three seconds.

The states come from a voice assistant, but they work for any app: use `idle` when nothing happens,
`listening` while waiting for or receiving input, `thinking` while computing an answer, `speaking`
while presenting a result and `working` for background tasks (a scan, a sync, a tool run).

```tsx
import { useEffect, useState } from 'react';
import { CssOrb, StatusLabel } from 'jarvis-react-ui';
import type { AppOrbState } from 'jarvis-react-ui';

const STATES: AppOrbState[] = ['idle', 'listening', 'thinking', 'speaking', 'working'];

export default function Cycle() {
    const [index, setIndex] = useState(0);

    useEffect(() => {
        const timer = setInterval(() => setIndex((i) => (i + 1) % STATES.length), 3000);
        return () => clearInterval(timer);
    }, []);

    const state = STATES[index] ?? 'idle';

    return (
        <div className="relative h-[356px] w-full overflow-hidden">
            <CssOrb state={state} />
            <StatusLabel state={state} className="absolute bottom-0 left-1/2 -translate-x-1/2" />
        </div>
    );
}
```

## Rings and particles

`rings` draws five concentric rings (360 to 920px wide) and a rotating tick ring around the core.
`particles` adds six dots orbiting at a radius of 180 to 330px. Both are on by default; turn them off for a
quieter orb or a small container. Pick a state with the
[StateSimulator](https://joeyash.github.io/jarvis_ui_lib/components/state-simulator.md) to compare.

```tsx
import { useState } from 'react';
import { CssOrb, StateSimulator, Switch } from 'jarvis-react-ui';
import type { AppOrbState } from 'jarvis-react-ui';

export default function StatePicker() {
    const [state, setState] = useState<AppOrbState>('listening');
    const [rings, setRings] = useState(true);
    const [particles, setParticles] = useState(true);

    return (
        <div className="flex w-full flex-col items-center gap-3">
            <StateSimulator state={state} onChange={setState} position="inline" />
            <div className="flex gap-6">
                <Switch size="sm" label="Rings" checked={rings} onCheckedChange={setRings} />
                <Switch
                    size="sm"
                    label="Particles"
                    checked={particles}
                    onCheckedChange={setParticles}
                />
            </div>
            <div className="relative h-[260px] w-full overflow-hidden">
                <CssOrb state={state} rings={rings} particles={particles} />
            </div>
        </div>
    );
}
```

## Sizing

The root element is a zero-size anchor centred (`left: 50%; top: 50%`) in its nearest positioned
ancestor. The orb has no size prop; its parts have fixed sizes:

| Part                | Diameter     |
| ------------------- | ------------ |
| Core                | 280px        |
| Particles           | 360 to 660px |
| Rings and tick ring | 360 to 920px |

Place the orb in a `position: relative` container with a fixed height, and add `overflow: hidden`
when it should not spill over the surrounding layout. As a rule of thumb:

- Full orb: a container of about 920 × 920px, or a full-screen background where the outer rings may
  be cut off.
- Smaller boxes (300 to 700px): turn `rings` off and, below about 660px, `particles` too. The core
  needs at least 300 × 300px.

```tsx
<div style={{ position: 'relative', height: 360, overflow: 'hidden' }}>
    <CssOrb state="idle" rings={false} particles={false} />
</div>
```

## Accessibility

- By default the orb is decorative: the root is `aria-hidden="true"`, so assistive technology
  skips it. Show the state as text as well, for example with a
  [StatusLabel](https://joeyash.github.io/jarvis_ui_lib/components/status-label.md).
- Pass `aria-label` when the orb itself should be announced. The root then gets `role="img"` and
  that label, and is no longer hidden:

```tsx
<CssOrb state={state} aria-label={`Assistant ${state}`} />
```

- With `prefers-reduced-motion: reduce`, the CSS animations of the core, rings and pulses stop, and
  the particles' `requestAnimationFrame` loop does not run: they stay parked at their start
  positions. CssOrb follows changes of the preference while it is mounted.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `state` (required) | `'idle' \| 'listening' \| 'thinking' \| 'speaking' \| 'follow_up' \| 'working'` |  | Orb state: sets the core animation, the listening pulses and the amber `working` recolor. |
| `aria-label` | `string` |  | Accessible name for the orb. When set, the root gets `role="img"` and this label; when omitted, the whole orb is decorative (`aria-hidden="true"`). |
| `className` | `string` |  | Extra classes for the root `<div>` element (the centred anchor of the orb). |
| `particles` | `boolean` | `true` | Draws six particles orbiting the core, animated with `requestAnimationFrame`. Under `prefers-reduced-motion: reduce` the frame loop does not run and the particles stay still. |
| `rings` | `boolean` | `true` | Draws the five concentric rings and the rotating tick ring around the core. |

# ThreeOrb

ThreeOrb renders the JARVIS orb in WebGL with Three.js, in six visual designs, either as a
full-screen background layer or inside a container. It ships in its own entry point,
`jarvis-react-ui/orb`, so Three.js only loads when you use it. For a lightweight CSS version see
[CssOrb](https://joeyash.github.io/jarvis_ui_lib/components/css-orb.md).

```ts
import { ThreeOrb } from 'jarvis-react-ui/orb';
```

## Installation

`three` is an optional peer dependency of `jarvis-react-ui`. Install it next to the library when
you use ThreeOrb or `createOrb`:

```bash
npm install three
```

ThreeOrb, `createOrb` and the `OrbEngine` type are not exported from `jarvis-react-ui`; import them
from `jarvis-react-ui/orb`.

## Lazy loading

Load ThreeOrb with `React.lazy` and wrap it in `Suspense`, so Three.js is split into its own chunk
and fetched on first render. Changing `state` makes the particles transition to the new state;
`working` is shown as `thinking`.

```tsx
import { Suspense, lazy, useState } from 'react';
import { Mono, StateSimulator } from 'jarvis-react-ui';
import type { AppOrbState } from 'jarvis-react-ui';

// Loads Three.js and the orb engine in their own chunk on first render.
const ThreeOrb = lazy(() => import('jarvis-react-ui/orb').then((m) => ({ default: m.ThreeOrb })));

export default function LazyLoaded() {
    const [state, setState] = useState<AppOrbState>('idle');

    return (
        <>
            <Suspense fallback={<Mono muted>Loading orb…</Mono>}>
                {/* fill="container": fills the demo frame instead of the viewport. */}
                <div className="absolute inset-0">
                    <ThreeOrb state={state} fill="container" />
                </div>
            </Suspense>
            <StateSimulator
                state={state}
                onChange={setState}
                position="inline"
                className="relative z-10"
            />
        </>
    );
}
```

```tsx
import { Suspense, lazy } from 'react';

const ThreeOrb = lazy(() => import('jarvis-react-ui/orb').then((m) => ({ default: m.ThreeOrb })));

<Suspense fallback={null}>
    <ThreeOrb state="listening" />
</Suspense>;
```

## Variants

`variant` picks the design. `constellation` (the default) is the original particle cloud; `particle`,
`halo`, `signal`, `reactor` and `lattice` are bloom-lit holographic designs, each loaded as its own
chunk the first time it is used. Try them in the playground: switch the design and the state, drag to
rotate and scroll to zoom, turn on the microphone (processed locally in your browser) or let the demo
cycle through the states.

```tsx
import { Suspense, lazy, useEffect, useState } from 'react';
import { Button, Mono, Switch, useToast } from 'jarvis-react-ui';
import type { ThreeOrbVariant } from 'jarvis-react-ui/orb';

const ThreeOrb = lazy(() => import('jarvis-react-ui/orb').then((m) => ({ default: m.ThreeOrb })));

const VARIANTS: Record<ThreeOrbVariant, string> = {
    constellation: 'The original orb: particle cloud with connecting lines (default).',
    particle: 'Glowing core, particle shell, tilted orbital rings and shockwaves.',
    halo: 'Particle orb with finer points, a faint inner shell and softer rings.',
    signal: 'Particle orb with traveling light currents and clearer orbital arcs.',
    reactor: 'Energy core, counter-rotating segmented rings, amber telemetry, audio iris.',
    lattice: 'Faceted crystal core, geodesic lattice, tick rings and a 128-bar spectrum.',
};
const STATES = ['idle', 'listening', 'working', 'speaking'] as const;
type DemoState = (typeof STATES)[number];

export default function VariantPlayground() {
    const { toast } = useToast();
    const [variant, setVariant] = useState<ThreeOrbVariant>('particle');
    const [state, setState] = useState<DemoState>('idle');
    const [lowQuality, setLowQuality] = useState(false);
    const [cycle, setCycle] = useState(false);
    const [mic, setMic] = useState(false);
    const [analyser, setAnalyser] = useState<AnalyserNode | null>(null);

    // Demo cycle: next state every 5 s.
    useEffect(() => {
        if (!cycle) return undefined;
        const id = window.setInterval(() => {
            setState((s) => STATES[(STATES.indexOf(s) + 1) % STATES.length] ?? 'idle');
        }, 5000);
        return () => window.clearInterval(id);
    }, [cycle]);

    // Microphone → AnalyserNode (processed locally, nothing is sent).
    useEffect(() => {
        if (!mic) return undefined;
        let ctx: AudioContext | null = null;
        let stream: MediaStream | null = null;
        let cancelled = false;
        navigator.mediaDevices
            .getUserMedia({ audio: { echoCancellation: true, noiseSuppression: true } })
            .then((media) => {
                stream = media;
                if (cancelled) return;
                ctx = new AudioContext();
                const node = ctx.createAnalyser();
                node.fftSize = 1024;
                node.smoothingTimeConstant = 0.55;
                ctx.createMediaStreamSource(media).connect(node);
                setAnalyser(node);
                setState('listening');
            })
            .catch(() => {
                toast({ title: 'Microphone unavailable', variant: 'error' });
                setMic(false);
            });
        return () => {
            cancelled = true;
            stream?.getTracks().forEach((track) => track.stop());
            void ctx?.close();
            setAnalyser(null);
        };
    }, [mic, toast]);

    return (
        <div className="relative flex h-full w-full flex-col">
            <div className="absolute inset-0">
                <Suspense fallback={<Mono muted>Loading orb…</Mono>}>
                    <ThreeOrb
                        state={state}
                        variant={variant}
                        quality={lowQuality ? 'low' : 'high'}
                        analyser={analyser}
                        fill="container"
                        interactive
                    />
                </Suspense>
            </div>
            <div className="pointer-events-none relative z-10 flex flex-wrap gap-2 p-3">
                {(Object.keys(VARIANTS) as ThreeOrbVariant[]).map((v) => (
                    <Button
                        key={v}
                        size="sm"
                        variant={v === variant ? 'primary' : 'ghost'}
                        aria-pressed={v === variant}
                        onClick={() => setVariant(v)}
                        className="pointer-events-auto"
                    >
                        {v}
                    </Button>
                ))}
            </div>
            <div className="pointer-events-none relative z-10 mt-auto flex flex-col gap-3 p-3">
                <Mono muted size="sm">
                    {VARIANTS[variant]} Drag to rotate, scroll to zoom.
                </Mono>
                <div className="flex flex-wrap items-center gap-2">
                    {STATES.map((s) => (
                        <Button
                            key={s}
                            size="sm"
                            variant={s === state ? 'secondary' : 'ghost'}
                            aria-pressed={s === state}
                            onClick={() => setState(s)}
                            className="pointer-events-auto"
                        >
                            {s}
                        </Button>
                    ))}
                    <Switch
                        size="sm"
                        label="Mic"
                        checked={mic}
                        onCheckedChange={setMic}
                        className="pointer-events-auto"
                    />
                    <Switch
                        size="sm"
                        label="Demo cycle"
                        checked={cycle}
                        onCheckedChange={setCycle}
                        className="pointer-events-auto"
                    />
                    <Switch
                        size="sm"
                        label="Low quality"
                        checked={lowQuality}
                        onCheckedChange={setLowQuality}
                        className="pointer-events-auto"
                    />
                </div>
            </div>
        </div>
    );
}
```

```tsx
<div className="h-96">
    <ThreeOrb state="listening" variant="reactor" fill="container" interactive />
</div>
```

The variant designs know four states. `thinking` and `working` show as `working`, `follow_up` as
`listening`.

## Audio input

Pass a Web Audio `AnalyserNode` as `analyser`, for example from the microphone or from your TTS
playback. In `listening` and `speaking` the variant designs read its level and 16 frequency bands
(80 Hz – 8 kHz) every frame; without an analyser they animate with a simulated voice.
`constellation` reacts to the analyser in every state.

```tsx
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const ctx = new AudioContext();
const analyser = ctx.createAnalyser();
analyser.fftSize = 1024;
analyser.smoothingTimeConstant = 0.55;
ctx.createMediaStreamSource(stream).connect(analyser);

<ThreeOrb state="listening" variant="lattice" analyser={analyser} />;
```

## Quality and interaction

`quality="low"` renders the variant designs with fewer particles, pixel ratio 1 and half-resolution
bloom, for integrated or mobile GPUs. `interactive` lets the user rotate (drag) and zoom (scroll) the
variant designs; it also makes a `viewport` orb take pointer events, so use it with
`fill="container"` or when nothing has to be clicked behind the orb. Both are ignored by
`constellation`.

## Canvas and layout

With `fill="container"` the orb fills its parent element, which needs a size. With the default
`fill="viewport"` the canvas is `position: fixed` at the top-left corner, sized to the window (it follows window
resizes), sits at `z-index: 0` and ignores the pointer, so it works as a background layer behind
the HUD. Every variant renders on a transparent canvas: only the orb and its glow are drawn, so put
your background color or [GridBackground](https://joeyash.github.io/jarvis_ui_lib/components/grid-background.md) behind it. In the `orb` slot
of [HUDShell](https://joeyash.github.io/jarvis_ui_lib/components/hud-shell.md), the shell's grid, stars and horizon stay visible around the
orb. Inside an ancestor with a `transform`, the fixed canvas is positioned relative to that
ancestor instead of the viewport; this demo uses `className="h-full! w-full!"` to fit it into the
demo frame.

```tsx
import { Suspense, lazy } from 'react';
import { HUDShell } from 'jarvis-react-ui';

const ThreeOrb = lazy(() => import('jarvis-react-ui/orb').then((m) => ({ default: m.ThreeOrb })));

export default function OverScene() {
    return (
        <HUDShell
            orb={
                <Suspense fallback={null}>
                    {/* The canvas is transparent: grid, stars and horizon stay visible. */}
                    <ThreeOrb state="idle" variant="particle" className="h-full! w-full!" />
                </Suspense>
            }
        />
    );
}
```

## Without React

`createOrb(canvas, options)` drives the same engine on any `<canvas>`. It returns an `OrbEngine`
with the full API, including mock audio and the follow-up ring, which ThreeOrb does not expose:

```ts
import { createOrb } from 'jarvis-react-ui/orb';
import type { OrbEngine } from 'jarvis-react-ui/orb';

const canvas = document.querySelector('canvas');
if (canvas) {
    const orb: OrbEngine = createOrb(canvas, { alpha: true }); // alpha: transparent background

    orb.setState('listening'); // 'idle' | 'listening' | 'thinking' | 'speaking' | 'follow_up'
    orb.setAnalyser(analyserNode); // react to a Web Audio AnalyserNode, or null
    orb.setMockMode('speaking'); // fake audio levels for previews; null turns it off
    orb.setFollowUp(true, 12); // follow-up pulse and countdown ring (seconds left)

    // Later: stop rendering and remove the resize listener.
    orb.destroy();
}
```

The engine renders at window size and listens for window resizes.

The variant designs work the same way with `createVariantOrb(variant, container, { quality })`. It
resolves to an `OrbRenderer` whose canvas fills `container` (a `ResizeObserver` follows its size):

```ts
import { createVariantOrb } from 'jarvis-react-ui/orb';

const orb = await createVariantOrb('halo', container, { quality: 'high' });
orb.setState('speaking'); // 'idle' | 'listening' | 'working' | 'speaking'
orb.onFrame = () => orb.setAudio(level, bands); // per frame: level 0..1, 16 bands 0..1
orb.dispose(); // stop rendering, free GPU resources, remove the canvas
```

## Accessibility

By default the orb is decorative: its root is `aria-hidden="true"` and, unless `interactive`, takes no
pointer events.
Show the assistant's state as text too, for example with a
[StatusLabel](https://joeyash.github.io/jarvis_ui_lib/components/status-label.md). Pass `aria-label` when the orb itself should be announced;
the root then gets `role="img"` and that label. The orbs do not check `prefers-reduced-motion`; render
a static alternative such as `<CssOrb>` (whose CSS animations stop under reduced motion) when the
user asks for less motion.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `state` (required) | `'idle' \| 'listening' \| 'thinking' \| 'speaking' \| 'follow_up' \| 'working'` |  | Assistant state the orb animates to. Each design maps the states it doesn't have itself. |
| `analyser` | `AnalyserNode \| null` | `null` | Audio source, e.g. a microphone or TTS `AnalyserNode`; drives level and frequency bands. Without it, the variant designs use a simulated voice in `listening` and `speaking`. |
| `aria-label` | `string` |  | Accessible name for the orb. When set, the root gets `role="img"` and this label; when omitted, the orb is decorative (`aria-hidden="true"`). |
| `className` | `string` |  | Additional class names for the root element (the canvas for `constellation` in the viewport). |
| `fill` | `'viewport' \| 'container'` | `'viewport'` | Where the orb renders: the whole viewport behind the UI, or its parent element. |
| `interactive` | `boolean` | `false` | Lets the user rotate (drag) and zoom (scroll) the variant designs. Ignored by `constellation`. |
| `quality` | `'high' \| 'low'` | `'high'` | Render quality of the variant designs: `low` uses fewer particles, pixel ratio 1 and half-resolution bloom for weak GPUs. Ignored by `constellation`. |
| `variant` | `'constellation' \| 'particle' \| 'halo' \| 'signal' \| 'reactor' \| 'lattice'` | `'constellation'` | Visual design. `constellation` is the original orb; `particle`, `halo`, `signal`, `reactor` and `lattice` are lazily loaded on first use. |

# UiRenderer

Renders a window from a JSON spec, for example one an assistant produced: a tree of library
components with state, bindings, conditions and actions. Nothing has to exist in your code
beforehand, and only allowlisted components and props can be used.

```ts
import { UiRenderer } from 'jarvis-react-ui/generative';
```

## Basic

A spec has an `id`, initial `state` and a `root` node. Each node names a component (`type`) and
sets its `props`; `{ "$bind": "volume" }` binds a control to a state value in both directions, and
`visibleIf` shows a node only while a condition holds. Text may contain `{{key}}` templates.

```tsx
import { UiRenderer } from 'jarvis-react-ui/generative';
import type { UiWindowSpec } from 'jarvis-react-ui/generative';

// The kind of JSON an assistant returns when asked for "a volume control".
const SPEC: UiWindowSpec = {
    id: 'volume',
    state: { volume: 40, muted: false },
    root: {
        type: 'Stack',
        props: { gap: 'md' },
        children: [
            {
                type: 'Slider',
                props: {
                    label: 'Volume',
                    value: { $bind: 'volume' },
                    showValue: true,
                    formatValue: '{value} %',
                },
            },
            { type: 'Switch', props: { label: 'Mute', checked: { $bind: 'muted' } } },
            {
                type: 'Pill',
                props: { variant: 'warn' },
                children: 'Muted',
                visibleIf: { state: 'muted' },
            },
            {
                type: 'Mono',
                children: 'Output at {{volume}} %',
                visibleIf: { state: 'muted', eq: false },
            },
        ],
    },
};

export default function Basic() {
    return <UiRenderer spec={SPEC} />;
}
```

## The spec

```json
{
    "id": "volume",
    "title": "Volume",
    "size": { "w": 360, "h": 240 },
    "state": { "volume": 40, "muted": false },
    "root": {
        "type": "Stack",
        "children": [
            {
                "type": "Slider",
                "props": {
                    "label": "Volume",
                    "value": { "$bind": "volume" },
                    "formatValue": "{value} %"
                }
            },
            {
                "type": "Mono",
                "children": "Output at {{volume}} %",
                "visibleIf": { "state": "muted", "eq": false }
            },
            {
                "type": "Button",
                "children": "Apply",
                "on": { "onClick": { "emit": "apply", "payload": { "$state": "volume" } } }
            }
        ]
    }
}
```

| Part                | Meaning                                                                                                    |
| ------------------- | ---------------------------------------------------------------------------------------------------------- |
| `type`              | A component from the allowlist (`UI_REGISTRY`); others render a placeholder.                               |
| `props`             | Allowed props of that component; others are ignored.                                                       |
| `{ "$state": "k" }` | Reads a state value.                                                                                       |
| `{ "$bind": "k" }`  | Two-way binding on `value` / `checked`; the change handler is wired for you.                               |
| `"…{{k}}…"`         | Template in any text.                                                                                      |
| `children`          | Text, or an array of nodes for layout components.                                                          |
| `on`                | Actions per event prop: `{ "set": "k", "value"? }`, `{ "toggle": "k" }`, `{ "emit": "name", "payload"? }`. |
| `visibleIf`         | `{ "state": "k" }` (truthy), `{ "state": "k", "eq": v }` or `{ "state": "k", "ne": v }`.                   |
| `id`                | Makes a player addressable through `call(...)`.                                                            |

Some props are translated: text props (`label`, `title`, …) take text or a nested node, icon props
take a name from `UI_ICONS` (`"Play"`), format functions take a template (`"{value} %"`), `Table`
takes `columns: [{ key, header, align? }]` and `rows` objects, and `Tabs` items take text or a node
as `content`.

## Several windows

`useUiWindows()` manages generated windows for a [WindowManager](https://joeyash.github.io/jarvis_ui_lib/components/window-manager.md): `open`
validates a spec and opens it as a floating window (an existing id is replaced), `patchState`
changes a window's state without rebuilding it, `call` controls players, and `onAction` receives
every `emit`. Try opening both windows, then the buttons.

```tsx
import { useState } from 'react';
import { Button, Mono, Stack, WindowManager } from 'jarvis-react-ui';
import { useUiWindows } from 'jarvis-react-ui/generative';
import type { UiWindowSpec } from 'jarvis-react-ui/generative';

const VIDEO: UiWindowSpec = {
    id: 'video',
    title: 'Video',
    size: { w: 420, h: 320 },
    root: { type: 'YouTubePlayer', id: 'player', props: { videoId: 'aqz-KE-bpKQ', size: 'sm' } },
};

const VOLUME: UiWindowSpec = {
    id: 'volume',
    title: 'Volume',
    size: { w: 280, h: 160 },
    state: { volume: 40 },
    root: {
        type: 'Stack',
        children: [
            {
                type: 'Slider',
                props: { label: 'Volume', value: { $bind: 'volume' }, showValue: true },
            },
            {
                type: 'Button',
                children: 'Apply',
                on: { onClick: { emit: 'apply_volume', payload: { $state: 'volume' } } },
            },
        ],
    },
};

export default function Windows() {
    const [log, setLog] = useState('—');
    const ui = useUiWindows({
        onAction: (e) => setLog(`${e.windowId} → ${e.name}(${JSON.stringify(e.payload)})`),
    });

    return (
        <>
            <Stack direction="row" gap="sm" wrap className="absolute top-3 left-3 z-[1]">
                <Button size="sm" onClick={() => ui.open(VIDEO)}>
                    Open video
                </Button>
                <Button size="sm" onClick={() => ui.open(VOLUME)}>
                    Open volume
                </Button>
                <Button size="sm" onClick={() => ui.patchState('volume', { volume: 20 })}>
                    Set volume 20
                </Button>
                <Button size="sm" onClick={() => ui.call('video', 'player', 'seek', 90)}>
                    Jump to 1:30
                </Button>
                <Mono size="xs" secondary>
                    {log}
                </Mono>
            </Stack>
            <WindowManager
                windows={ui.windows}
                assignments={{}}
                onAssignmentsChange={() => undefined}
                onClose={ui.onClose}
            />
        </>
    );
}
```

## Validation

`validateUiSpec(spec)` returns every problem with its JSON path, so you can send them back to the
model and ask for a fixed spec. `open` refuses invalid specs; `UiRenderer` renders what it can and
reports the rest through `onError`.

```tsx
import { CodeBlock } from 'jarvis-react-ui';
import { validateUiSpec } from 'jarvis-react-ui/generative';

// A spec with mistakes, as a model might produce it.
const SPEC = {
    id: 'broken',
    state: { level: 3 },
    root: {
        type: 'Stack',
        children: [
            { type: 'ThreeOrb' },
            { type: 'Slider', props: { value: { $bind: 'volume' }, color: 'red' } },
            { type: 'Link', props: { href: 'javascript:alert(1)' }, children: 'Click' },
        ],
    },
};

export default function Validation() {
    const { errors } = validateUiSpec(SPEC);
    const text = errors.map((e) => `${e.path}: ${e.message}`).join('\n');
    return <CodeBlock code={text} language="text" title="validateUiSpec(spec).errors" />;
}
```

## Safety

- Only components and props in `UI_REGISTRY` are rendered. There is no way to set `className`,
  inline styles, raw HTML (`CodeBlock.html` is not allowed) or event handlers other than actions.
- Links, media sources and web frames accept only `http(s)` URLs or relative paths; `WebFrame`'s
  sandbox cannot be changed from a spec.
- Text is always rendered as text. Specs are limited to 24 levels and 500 nodes.

## Accessibility

The rendered components keep their own semantics and keyboard support. Ask the model for labels:
`label` on form controls, `aria-label` where there is no visible text.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `spec` (required) | `UiWindowSpec` |  | The window spec to render; only its `root` and initial `state` are used here. |
| `onAction` | `((event: UiActionEvent) => void)` |  | Called for every `emit` action. |
| `onError` | `((errors: UiSpecError[]) => void)` |  | Called with the problems `validateUiSpec` finds; invalid parts render as placeholders. |
| `onStateChange` | `((state: UiState) => void)` |  | Called with the full next state whenever a binding or a `set` / `toggle` action changes it. |
| `state` | `UiState` |  | Controlled state. Leave undefined to keep the state inside the renderer, starting from `spec.state`. |

Also accepts inherited props from `RefAttributes` (1), `Attributes` (1).

# Connecting an assistant

Let a language model build and control windows: give it the four tools the package ships,
validate what it sends, and run the calls with `useUiWindows`. The model never writes code, only
JSON that the [UiRenderer](https://joeyash.github.io/jarvis_ui_lib/components/ui-renderer.md) turns into library components.

## The flow

1. The user asks: "Show me the latest video of X and a volume control."
2. Your backend sends the request to the model together with the tools from
   `jarvis-react-ui/ui-tools.json`.
3. The model answers with tool calls: `open_window` with a spec, later `update_window` ("set the
   volume to 20"), `control_player` ("skip to 1:30") or `close_window`.
4. Your UI runs each call with `useUiWindows` and returns the result, including validation errors,
   so the model can correct itself.

## Try a spec

Edit the JSON on the left: the window on the right follows, and invalid specs show the errors a
model would get back.

```tsx
import { useMemo, useState } from 'react';
import { Callout, Grid, Panel, Textarea } from 'jarvis-react-ui';
import { UiRenderer, validateUiSpec } from 'jarvis-react-ui/generative';
import type { UiWindowSpec } from 'jarvis-react-ui/generative';

const START = JSON.stringify(
    {
        id: 'scan',
        title: 'Scan',
        state: { radius: 200, live: true },
        root: {
            type: 'Stack',
            children: [
                {
                    type: 'Slider',
                    props: {
                        label: 'Radius',
                        min: 50,
                        max: 500,
                        step: 50,
                        value: { $bind: 'radius' },
                        showValue: true,
                        formatValue: '{value} m',
                    },
                },
                { type: 'Switch', props: { label: 'Live', checked: { $bind: 'live' } } },
                {
                    type: 'Pill',
                    props: { variant: 'ok' },
                    children: 'scanning {{radius}} m',
                    visibleIf: { state: 'live' },
                },
            ],
        },
    },
    null,
    2,
);

export default function Playground() {
    const [text, setText] = useState(START);

    const result = useMemo(() => {
        try {
            const spec: unknown = JSON.parse(text);
            const validation = validateUiSpec(spec);
            return validation.ok
                ? { spec: spec as UiWindowSpec, errors: [] }
                : { spec: null, errors: validation.errors.map((e) => `${e.path}: ${e.message}`) };
        } catch (error) {
            return { spec: null, errors: [`Invalid JSON: ${String(error)}`] };
        }
    }, [text]);

    return (
        <Grid columns={2} gap="md" align="start" className="w-full">
            <Textarea
                aria-label="Spec JSON"
                value={text}
                onChange={(e) => setText(e.target.value)}
                rows={18}
                fullWidth
                size="sm"
                spellCheck={false}
            />
            {result.spec !== null ? (
                <Panel title={result.spec.title} className="w-full">
                    <UiRenderer key={text} spec={result.spec} />
                </Panel>
            ) : (
                <Callout variant="error" title="Spec rejected">
                    {result.errors.join('\n')}
                </Callout>
            )}
        </Grid>
    );
}
```

## The tools

The package ships two files, generated from the component types on every build:

| File                             | Contents                                                                                               |
| -------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `jarvis-react-ui/ui-schema.json` | JSON Schema of a window spec: every allowed component and prop with its type and description.          |
| `jarvis-react-ui/ui-tools.json`  | Tool definitions for the Claude API: `open_window`, `update_window`, `control_player`, `close_window`. |

Pass `ui-tools.json` as `tools` unchanged. The schema is large (about 60 kB), so cache it with
prompt caching; it only changes when you update the package.

## Running the tool calls in the UI

The tool names map one to one onto `useUiWindows`:

```tsx
import type { UiJson, UiMethod, UiState, UseUiWindowsResult } from 'jarvis-react-ui/generative';

/** Runs one tool call from the model; `content` goes back as the tool result. */
export function runUiTool(
    ui: UseUiWindowsResult,
    name: string,
    input: Record<string, UiJson>,
): { content: string; isError: boolean } {
    switch (name) {
        case 'open_window': {
            const result = ui.open(input);
            const errors = result.errors.map((e) => `${e.path}: ${e.message}`).join('\n');
            return { content: result.ok ? 'opened' : errors, isError: !result.ok };
        }
        case 'update_window': {
            const ok = ui.patchState(String(input.id), input.state as UiState);
            return { content: ok ? 'updated' : 'no such window', isError: !ok };
        }
        case 'control_player': {
            const args = input.value === undefined ? [] : [input.value];
            const method = input.method as UiMethod;
            const ok = ui.call(String(input.window_id), String(input.node_id), method, ...args);
            return { content: ok ? 'done' : 'no such player or method', isError: !ok };
        }
        case 'close_window':
            ui.close(String(input.id));
            return { content: 'closed', isError: false };
        default:
            return { content: `unknown tool ${name}`, isError: true };
    }
}
```

## Calling the model

Call the model where your API key lives: a backend, or the main process of an Electron or Tauri
app. Never ship the key to the browser. A minimal loop with the Anthropic TypeScript SDK, where
`sendToUi` forwards a tool call to the UI (for example over a WebSocket) and resolves with the
result of `runUiTool`:

```ts
import Anthropic from '@anthropic-ai/sdk';
import uiTools from 'jarvis-react-ui/ui-tools.json';

const client = new Anthropic();
const tools = uiTools as Anthropic.Beta.BetaTool[];

export async function ask(
    userText: string,
    sendToUi: (name: string, input: unknown) => Promise<{ content: string; isError: boolean }>,
): Promise<string> {
    const messages: Anthropic.Beta.BetaMessageParam[] = [{ role: 'user', content: userText }];

    while (true) {
        const response = await client.beta.messages.create({
            model: 'claude-opus-5-5',
            max_tokens: 16000,
            betas: ['server-side-fallback-2026-07-01'],
            fallbacks: 'default',
            system: 'You control the windows of a HUD interface. Build them only with the tools.',
            tools,
            messages,
        });
        if (response.stop_reason === 'refusal') return 'The request was declined.';

        messages.push({ role: 'assistant', content: response.content });
        const calls = response.content.filter(
            (b): b is Anthropic.Beta.BetaToolUseBlock => b.type === 'tool_use',
        );
        if (calls.length === 0) {
            return response.content.map((b) => (b.type === 'text' ? b.text : '')).join('');
        }

        // Run all calls, then return all results in one user message.
        const results = await Promise.all(calls.map((c) => sendToUi(c.name, c.input)));
        messages.push({
            role: 'user',
            content: calls.map((c, i) => ({
                type: 'tool_result' as const,
                tool_use_id: c.id,
                content: results[i]?.content ?? '',
                is_error: results[i]?.isError,
            })),
        });
    }
}
```

The `fallbacks` option lets the API retry on another model if a request is declined; drop it if you
don't want that.

## Safety

The model can only use what the allowlist (`UI_REGISTRY`) permits. Specs cannot set classes, styles,
raw HTML or arbitrary event handlers; URLs must be `http(s)` or relative paths; `WebFrame` keeps its
sandbox. `open` validates every spec before rendering, and `UiRenderer` drops anything that slips
through. Treat model output like any other untrusted input: ask for confirmation before acting on
`emit` events that change data outside the UI.

# Sound hooks

`useClickSfx`, `useHoverSfx` and `useSfx` give your own components the same UI sounds as the
library components. They read the nearest `SfxProvider`, which `JarvisProvider` sets up.

```ts
import { useClickSfx, useHoverSfx, useSfx } from 'jarvis-react-ui';
```

## Usage

```tsx
import { useClickSfx, useHoverSfx, useSfx } from 'jarvis-react-ui';

export default function CustomControl() {
    const onMouseEnter = useHoverSfx('button');
    const onClick = useClickSfx(() => undefined);
    const { playOneShot } = useSfx();

    return (
        <>
            <button
                type="button"
                data-sfx-hover="button"
                onMouseEnter={onMouseEnter}
                onClick={onClick}
                className="border border-accent px-4 py-2 text-[11px] uppercase tracking-[1px] text-accent"
            >
                Custom control
            </button>
            <button
                type="button"
                onClick={() => playOneShot('confirm')}
                className="border border-success px-4 py-2 text-[11px] uppercase tracking-[1px] text-success"
            >
                Play confirm
            </button>
        </>
    );
}
```

## useClickSfx

```ts
function useClickSfx<E>(handler?: (event: E) => void): (event: E) => void;
```

Wraps a click handler: plays `click`, then calls yours. Pass the result to `onClick`. The returned
function is memoized on `handler`.

## useHoverSfx

```ts
function useHoverSfx(
    target: 'button' | 'panel',
    options?: { throttleMs?: number },
): (e: MouseEvent) => void;
```

Returns an `onMouseEnter` handler that plays `hover_button` or `hover_panel`, throttled to one sound
per 150ms by default. With `'panel'` it stays silent while the pointer enters a child marked
`data-sfx-hover="button"`, so a button inside a panel does not play both sounds. Mark your own
buttons with that attribute.

## useSfx

```ts
function useSfx(): {
    playOneShot: (event: SfxEvent) => void;
    play: (event: SfxEvent) => void; // looping sounds
    stop: (event: SfxEvent) => void;
};
```

Plays any sound event directly, e.g. `confirm`, `error`, `transition` or `scan`. The full list is the
`SfxEvent` type and `SFX_CONFIG`.

## Without a provider

All three hooks work outside a provider; they simply play nothing. Components therefore never break
in tests or in apps that do not want sound.

## SfxProvider

`SfxProvider` takes `playOneShot`, `play` and `stop` and passes them down. Use it directly to plug in
your own audio implementation, or let [JarvisProvider](https://joeyash.github.io/jarvis_ui_lib/components/jarvis-provider.md) wire it to the
built-in [audio engine](https://joeyash.github.io/jarvis_ui_lib/hooks/use-audio-engine.md).

# useAudioEngine

The React binding of the Web Audio engine that plays all UI sounds. `JarvisProvider` calls it
for you; use it directly only for a custom setup.

```ts
import { useAudioEngine } from 'jarvis-react-ui';

const { isMuted, toggleMute, playOneShot, play, stop, engine } = useAudioEngine(
    orbState, // AppOrbState: 'idle' | 'listening' | 'thinking' | 'speaking' | 'working' | 'follow_up'
    connected, // boolean
    heartbeatEnabled, // boolean, default false
    { soundBaseUrl, initialMuted }, // optional
);
```

## What it does

- Loads the sound files from `soundBaseUrl` (default `/sounds/`) and plays them through one shared
  `AudioContext`.
- Starts audio on the first pointer or key press (browsers block audio before a user gesture), then
  plays `boot` and the ambient loop.
- Follows `orbState`: scan loop and ducking while listening, thinking/working loops, speech start and
  end, barge-in, and an idle pulse after 30 seconds.
- Follows `connected`: plays the disconnect and offline sounds after a short grace period.
- Stores the mute choice in `localStorage` (`jarvis.sfx.muted`).

## Options

| Option         | Type      | Default      | Description                                                    |
| -------------- | --------- | ------------ | -------------------------------------------------------------- |
| `soundBaseUrl` | `string`  | `'/sounds/'` | Path or CDN URL of the sound files; a trailing slash is added. |
| `initialMuted` | `boolean` | `false`      | Mute state when the user has no stored preference yet.         |

## Return value

| Field                         | Description                                               |
| ----------------------------- | --------------------------------------------------------- |
| `isMuted`                     | Current mute state.                                       |
| `toggleMute()`                | Mutes or unmutes and stores the choice.                   |
| `playOneShot(event)`          | Plays a sound once.                                       |
| `play(event)` / `stop(event)` | Starts and stops looping sounds.                          |
| `engine`                      | The shared `AudioEngine` singleton, for advanced control. |

Pass `playOneShot`, `play` and `stop` to `SfxProvider` so components can use them, see
[Sound effects](https://joeyash.github.io/jarvis_ui_lib/getting-started/sound.md).

> The engine is a process-wide singleton. Mount `useAudioEngine` once, high in the tree.

# useDraggable

A low-level pointer drag hook. It tracks the drag offset, keeps the pointer captured when it
leaves the element and plays the drag sounds. `Window` and `useSlotDrag` build on it.

```ts
import { useDraggable } from 'jarvis-react-ui';

const { onPointerDown, dragging } = useDraggable({ onStart, onMove, onEnd, disabled });
```

## Usage

Attach `onPointerDown` to the drag handle. `onMove` receives the live offset (`dx`, `dy`) from the
drag start; commit the position in `onEnd`.

```tsx
import { useState } from 'react';
import type { CSSProperties } from 'react';
import { Panel, useDraggable } from 'jarvis-react-ui';

export default function DragBox() {
    const [pos, setPos] = useState({ x: 0, y: 0 });
    const [live, setLive] = useState({ dx: 0, dy: 0 });

    const { onPointerDown, dragging } = useDraggable({
        onMove: (state) => setLive({ dx: state.dx, dy: state.dy }),
        onEnd: (state) => {
            setPos((p) => ({ x: p.x + state.dx, y: p.y + state.dy }));
            setLive({ dx: 0, dy: 0 });
        },
    });

    const offset = {
        '--x': `${pos.x + live.dx}px`,
        '--y': `${pos.y + live.dy}px`,
    } as CSSProperties;

    return (
        <div className="translate-x-[var(--x)] translate-y-[var(--y)]" style={offset}>
            <Panel title={dragging ? 'DRAGGING…' : 'DRAG ME'} className="w-[200px]">
                <div
                    role="presentation"
                    onPointerDown={onPointerDown}
                    className="cursor-grab select-none py-4 text-center text-[10px] text-text-secondary active:cursor-grabbing"
                >
                    Grab here · dx {live.dx} · dy {live.dy}
                </div>
            </Panel>
        </div>
    );
}
```

## Options

| Option     | Type                                          | Description                        |
| ---------- | --------------------------------------------- | ---------------------------------- |
| `onStart`  | `(e: PointerEvent) => void`                   | Called when the drag begins.       |
| `onMove`   | `(state: DragState, e: PointerEvent) => void` | Called on every pointer move.      |
| `onEnd`    | `(state: DragState, e: PointerEvent) => void` | Called on pointer up.              |
| `disabled` | `boolean`                                     | Ignores pointer down while `true`. |

`DragState` is `{ dragging, startX, startY, dx, dy }`. The hook returns `onPointerDown` and the
current `dragging` flag for styling.

## Sound

Plays `drag_start`, loops `drag_move` while dragging and plays `drag_end` on release.

## Accessibility

Pointer only. Offer a keyboard alternative (e.g. arrow buttons or a slot picker) when dragging is
the only way to change a layout.

## Related

- [useResizable](https://joeyash.github.io/jarvis_ui_lib/hooks/use-resizable.md) for resize handles.
- [useSlotDrag](https://joeyash.github.io/jarvis_ui_lib/hooks/use-slot-drag.md) adds snap and swap targets on the slot grid.

# useResizable

A low-level pointer resize hook. `onPointerDown(dir)` creates a handler per edge or corner and
reports the resize offset while the pointer moves.

```ts
import { useResizable } from 'jarvis-react-ui';

const { onPointerDown, resizing, dir } = useResizable({ onStart, onMove, onEnd, disabled });
```

## Usage

Render a handle per direction and attach `onPointerDown('se')`, `onPointerDown('e')` and so on. Apply
`dx` / `dy` to the size in `onMove` and commit it in `onEnd`. Clamp to a minimum size yourself.

```tsx
import { useState } from 'react';
import type { CSSProperties } from 'react';
import { useResizable } from 'jarvis-react-ui';

const MIN = 120;

export default function ResizeBox() {
    const [size, setSize] = useState({ w: 220, h: 140 });
    const [delta, setDelta] = useState({ dx: 0, dy: 0 });

    const { onPointerDown, resizing } = useResizable({
        onMove: (state) => setDelta({ dx: state.dx, dy: state.dy }),
        onEnd: (state) => {
            setSize((s) => ({
                w: Math.max(MIN, s.w + state.dx),
                h: Math.max(MIN / 2, s.h + state.dy),
            }));
            setDelta({ dx: 0, dy: 0 });
        },
    });

    const w = Math.max(MIN, size.w + delta.dx);
    const h = Math.max(MIN / 2, size.h + delta.dy);

    return (
        <div
            className="relative flex w-[var(--w)] h-[var(--h)] items-center justify-center border border-border-bright bg-surface text-[10px] text-text-secondary"
            style={{ '--w': `${w}px`, '--h': `${h}px` } as CSSProperties}
        >
            {Math.round(w)} × {Math.round(h)} {resizing && '· resizing'}
            <span
                role="presentation"
                onPointerDown={onPointerDown('se')}
                className="absolute -right-[5px] -bottom-[5px] h-[10px] w-[10px] cursor-se-resize border border-accent bg-bg"
            />
        </div>
    );
}
```

## Options

| Option     | Type                                            | Description                        |
| ---------- | ----------------------------------------------- | ---------------------------------- |
| `onStart`  | `(dir: ResizeDir, e: PointerEvent) => void`     | Called when a resize begins.       |
| `onMove`   | `(state: ResizeState, e: PointerEvent) => void` | Called on every pointer move.      |
| `onEnd`    | `(state: ResizeState, e: PointerEvent) => void` | Called on pointer up.              |
| `disabled` | `boolean`                                       | Ignores pointer down while `true`. |

`ResizeDir` is `'n' | 's' | 'e' | 'w' | 'ne' | 'nw' | 'se' | 'sw'`. `ResizeState` is
`{ resizing, dir, startX, startY, dx, dy }`.

## Sound

Loops `resize` while resizing.

## Accessibility

Pointer only; provide keyboard controls if resizing changes content the user needs.

# useSlotDrag

A drag hook for the 9-slot grid. While dragging it reports which slot is under the pointer and
whether a window already sits there, so you can show snap and swap previews. `WindowManager` is
built on it.

```ts
import { useSlotDrag } from 'jarvis-react-ui';

const { onPointerDown, slotDragState } = useSlotDrag({
    windowId: 'system',
    assignments, // Record<windowId, SlotId>
    viewportW,
    viewportH,
    onDragEnd: (id, state) => {
        if (state.snapTarget) moveOrSwap(id, state.snapTarget, state.swapTarget);
    },
});
```

## When to use it

Use [WindowManager](https://joeyash.github.io/jarvis_ui_lib/components/window-manager.md) for the complete behavior. Reach for `useSlotDrag`
when you build your own window layout on the same grid, together with
[SnapOverlay](https://joeyash.github.io/jarvis_ui_lib/components/snap-overlay.md), [SwapOverlay](https://joeyash.github.io/jarvis_ui_lib/components/swap-overlay.md) and
[SlotGhost](https://joeyash.github.io/jarvis_ui_lib/components/slot-ghost.md) for the visual feedback.

## Options

| Option                    | Type                     | Description                                        |
| ------------------------- | ------------------------ | -------------------------------------------------- |
| `windowId`                | `string`                 | Id of the dragged window.                          |
| `assignments`             | `Record<string, SlotId>` | Current window → slot mapping.                     |
| `viewportW` / `viewportH` | `number`                 | Size the slot grid is computed for.                |
| `onDragStart`             | `(id, e) => void`        | Called when the drag begins.                       |
| `onDragMove`              | `(id, state, e) => void` | Called on every move with the live targets.        |
| `onDragEnd`               | `(id, state, e) => void` | Called on release; `state.snapTarget` is the drop. |
| `disabled`                | `boolean`                | Disables dragging.                                 |

## State

`slotDragState` is `{ dragging, snapTarget, swapTarget, dx, dy }`:

- `snapTarget`: the slot under the pointer, or `null` outside the grid.
- `swapTarget`: the id of the window already in `snapTarget`, or `null` when it is free.

The grid geometry comes from [computeAllSlots](https://joeyash.github.io/jarvis_ui_lib/utilities/slot-grid.md). Drag sounds come from
[useDraggable](https://joeyash.github.io/jarvis_ui_lib/hooks/use-draggable.md).

# Slot grid

The geometry behind the window system: nine fixed slots around the edges of the viewport,
leaving the center free for the orb.

```ts
import {
    computeSlot,
    computeAllSlots,
    slotAtPoint,
    SLOT_IDS,
    TOP_BAR_HEIGHT,
    SLOT_MARGIN,
    COLUMN_WIDTH,
    BOTTOM_STRIP_HEIGHT,
} from 'jarvis-react-ui';
import type { SlotId, SlotRect } from 'jarvis-react-ui';
```

## Layout

- Left column `L1`–`L3` and right column `R1`–`R3`, each `COLUMN_WIDTH` (316px) wide.
- Bottom strip `B1`–`B3`, `BOTTOM_STRIP_HEIGHT` (140px) high.
- `TOP_BAR_HEIGHT` (60px) stays free for a [TopBar](https://joeyash.github.io/jarvis_ui_lib/components/top-bar.md); `SLOT_MARGIN` (12px) is the
  gap between slots and edges.

```tsx
import type { CSSProperties } from 'react';
import { computeAllSlots, SLOT_IDS } from 'jarvis-react-ui';

// Slot geometry for a 1280 × 800 viewport, drawn at 40 % scale.
const VIEWPORT = { w: 1280, h: 800 };
const SCALE = 0.4;

export default function SlotMap() {
    const slots = computeAllSlots(VIEWPORT.w, VIEWPORT.h);

    return (
        <div
            className="relative w-[var(--w)] h-[var(--h)] border border-border bg-bg"
            style={
                {
                    '--w': `${VIEWPORT.w * SCALE}px`,
                    '--h': `${VIEWPORT.h * SCALE}px`,
                } as CSSProperties
            }
        >
            {SLOT_IDS.map((id) => {
                const r = slots[id];
                return (
                    <div
                        key={id}
                        className="absolute left-[var(--x)] top-[var(--y)] w-[var(--sw)] h-[var(--sh)] flex items-center justify-center border border-accent-dim bg-[rgba(76,168,232,0.06)] text-[9px] tracking-[1px] text-accent"
                        style={
                            {
                                '--x': `${r.x * SCALE}px`,
                                '--y': `${r.y * SCALE}px`,
                                '--sw': `${r.w * SCALE}px`,
                                '--sh': `${r.h * SCALE}px`,
                            } as CSSProperties
                        }
                    >
                        {id}
                    </div>
                );
            })}
        </div>
    );
}
```

## Functions

| Function                         | Returns                    | Description                                    |
| -------------------------------- | -------------------------- | ---------------------------------------------- |
| `computeSlot(id, width, height)` | `SlotRect`                 | Rectangle of one slot for a viewport size.     |
| `computeAllSlots(width, height)` | `Record<SlotId, SlotRect>` | All nine rectangles.                           |
| `slotAtPoint(x, y, rects)`       | `SlotId \| null`           | The slot containing a point, e.g. the pointer. |

`SlotRect` is `{ x, y, w, h }` in pixels relative to the viewport (or the container the window
system fills). `SLOT_IDS` lists the ids in visual order.

# cx & time helpers

Small, dependency-free helpers the components use internally and that are handy in HUD apps: a
class name joiner and formatters for clocks, ages and durations.

```ts
import { cx, formatTime, relativeTime, formatAge, formatDuration } from 'jarvis-react-ui';
```

```tsx
import { useEffect, useState } from 'react';
import { cx, formatAge, formatDuration, formatTime, relativeTime, Table } from 'jarvis-react-ui';
import type { TableColumn } from 'jarvis-react-ui';

interface Row {
    call: string;
    result: string;
}

const COLUMNS: TableColumn<Row>[] = [
    { key: 'call', header: 'Call', render: (r) => <code className="text-accent">{r.call}</code> },
    { key: 'result', header: 'Result', render: (r) => <code>{r.result}</code> },
];

export default function TimeHelpers() {
    const [bootedAt] = useState(() => new Date().toISOString());
    const [now, setNow] = useState(() => new Date());

    useEffect(() => {
        const id = setInterval(() => setNow(new Date()), 1000);
        return () => clearInterval(id);
    }, []);

    const uptime = now.getTime() - new Date(bootedAt).getTime();
    const rows: Row[] = [
        { call: 'formatTime(bootedAt)', result: formatTime(bootedAt) },
        { call: 'relativeTime(bootedAt)', result: relativeTime(bootedAt) },
        { call: 'formatAge(bootedAt, now)', result: formatAge(bootedAt, now) },
        { call: 'formatDuration(uptime)', result: formatDuration(uptime) },
        { call: "cx('a', uptime > 5000 && 'b')", result: cx('a', uptime > 5000 && 'b') },
    ];

    return <Table columns={COLUMNS} rows={rows} getRowKey={(r) => r.call} dense />;
}
```

## cx

```ts
cx('base', isActive && 'active', { muted: isMuted }, ['a', 'b']);
```

Joins strings, numbers, arrays and objects (keys with truthy values) into one class string and skips
falsy values. It does not merge conflicting Tailwind classes; the last one in the generated
stylesheet wins.

## Time helpers

| Function               | Example output | Description                                       |
| ---------------------- | -------------- | ------------------------------------------------- |
| `formatTime(iso)`      | `14:30`        | 24-hour clock time of an ISO timestamp.           |
| `relativeTime(iso)`    | `1m`           | Compact age: `now`, `Xs`, `Xm`, `Xh`, `Xd`.       |
| `formatAge(iso, now?)` | `3m ago`       | Readable age; `now` defaults to the current time. |
| `formatDuration(ms)`   | `1m 30s`       | Duration in the two largest units.                |

All of them take ISO 8601 strings (or milliseconds) and use the browser's local time zone.

# StateSimulator

A development toolbar with one button per orb state. Use it to preview how the orb and the voice
UI react to each `AppOrbState` without a real voice pipeline.

```ts
import { StateSimulator } from 'jarvis-react-ui';
```

> **Warning: Development aid**
>
> StateSimulator is meant for showcases, prototypes and debugging. Do not ship it in a production
> UI; render it behind a dev flag such as `import.meta.env.DEV`.

## Inline

With `position="inline"` the toolbar sits in the normal document flow. It is controlled: pass the
current `state` and update it in `onChange`.

```tsx
import { useState } from 'react';
import { StateSimulator } from 'jarvis-react-ui';
import type { AppOrbState } from 'jarvis-react-ui';

export default function Inline() {
    const [state, setState] = useState<AppOrbState>('idle');

    return (
        <div className="flex flex-col items-center gap-3">
            <StateSimulator state={state} onChange={setState} position="inline" />
            <span className="text-[10px] text-text-muted">state = {state}</span>
        </div>
    );
}
```

The toolbar has one button per `AppOrbState`: `idle`, `listening`, `thinking`, `speaking`,
`follow_up` (labelled `FOLLOW UP`) and `working`.

## Drive the orb

Share one state between the simulator, the orb and the [StatusLabel](https://joeyash.github.io/jarvis_ui_lib/components/status-label.md) to
check every state in context. The active `working` button turns amber like the orb's working
overlay.

```tsx
import { useState } from 'react';
import { CssOrb, StateSimulator, StatusLabel } from 'jarvis-react-ui';
import type { AppOrbState } from 'jarvis-react-ui';

export default function DriveTheOrb() {
    const [state, setState] = useState<AppOrbState>('thinking');

    return (
        <div className="flex w-full flex-col items-center gap-3">
            <StateSimulator state={state} onChange={setState} position="inline" />
            <div className="relative h-[260px] w-full overflow-hidden">
                <CssOrb state={state} particles />
            </div>
            <StatusLabel state={state} />
        </div>
    );
}
```

## Fixed to the top

By default (`position="fixed-top"`) the toolbar is `position: fixed`, centred 60px below the top of
the viewport, above the HUD. Inside this demo frame it stays within the frame.

```tsx
import { useState } from 'react';
import { StateSimulator, StatusLabel } from 'jarvis-react-ui';
import type { AppOrbState } from 'jarvis-react-ui';

export default function FixedTop() {
    const [state, setState] = useState<AppOrbState>('listening');

    return (
        <>
            {/* Pinned 60px below the top of the viewport (here: of the demo frame). */}
            <StateSimulator state={state} onChange={setState} />
            <StatusLabel state={state} />
        </>
    );
}
```

## Sound

Hovering a state button plays `hover_button` and clicking it plays `click` through the nearest
`SfxProvider`. See [Sound effects](https://joeyash.github.io/jarvis_ui_lib/getting-started/sound.md).

## Accessibility

- Every state is a native `<button type="button">` whose text is its accessible name, so the
  toolbar works with Tab, Enter and Space.
- The button of the current state has `aria-pressed="true"`, all others `aria-pressed="false"`, so
  screen readers announce which state is selected, not only the color.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onChange` (required) | `(state: AppOrbState) => void` |  | Called with the state of the button that was clicked. |
| `state` (required) | `'idle' \| 'listening' \| 'thinking' \| 'speaking' \| 'follow_up' \| 'working'` |  | Currently selected orb state; its button is highlighted (amber for `working`) and marked `aria-pressed`. |
| `className` | `string` |  | Extra classes for the root `<div>` element (the toolbar). |
| `label` | `string` | `◈ ORB STATE` | Caption shown before the buttons. |
| `position` | `'fixed-top' \| 'inline'` | `'fixed-top'` | `fixed-top` pins the bar centred 60px below the top of the viewport; `inline` keeps it in the normal document flow. |

### Type `AppOrbState`

Full app-layer orb state — a superset of `OrbState` that includes
states handled above the base state machine.

Components and hooks should use `AppOrbState` for their props / return values.

```ts
type AppOrbState = OrbState | 'working';
```

### Type `OrbState`

States that drive the JARVIS orb visual and audio state machine.
Single source of truth — copied from src/types.ts.

```ts
type OrbState = 'idle' | 'listening' | 'thinking' | 'speaking' | 'follow_up';
```

# Tweaks

A floating development panel for adjusting the HUD theme live: accent hue, glow intensity and
five on/off flags. Pair it with `useTweakApply` to write the hue and glow into the design
tokens.

```ts
import { Tweaks } from 'jarvis-react-ui';
```

> **Warning: Development aid**
>
> Tweaks is meant for showcases, prototypes and design sessions. Do not ship it in a production
> UI; render it behind a dev flag such as `import.meta.env.DEV`. For a permanent theme, override
> the tokens in CSS instead (see [Theming](https://joeyash.github.io/jarvis_ui_lib/customization/theming.md)).

## Panel and useTweakApply

`Tweaks` is controlled: it shows `tweaks` and calls `onChange` with the complete next object.
`open` shows or hides it. The panel is `position: fixed` in the bottom-right corner (14px from the
right, 110px from the bottom); in this demo frame it stays within the frame.

`useTweakApply(tweaks)` sets the accent and glow variables on `:root`, so moving the hue slider or
picking a swatch recolors **this whole page**.

```tsx
import { useState } from 'react';
import { Button, Tweaks, TWEAKS_DEFAULTS, useTweakApply } from 'jarvis-react-ui';
import type { TweaksState } from 'jarvis-react-ui';

export default function Panel() {
    const [open, setOpen] = useState(true);
    const [tweaks, setTweaks] = useState<TweaksState>(TWEAKS_DEFAULTS);
    // Writes the accent + glow tokens to :root; removes them again on unmount.
    useTweakApply(tweaks);

    return (
        <div className="flex flex-col items-start gap-3 self-start">
            <Button variant={open ? 'primary' : 'secondary'} onClick={() => setOpen((v) => !v)}>
                {open ? 'Close tweaks' : 'Open tweaks'}
            </Button>
            <span className="text-[10px] text-text-muted">
                hue {tweaks.hue}° · glow {tweaks.glow}
            </span>
            <Tweaks open={open} tweaks={tweaks} onChange={setTweaks} />
        </div>
    );
}
```

> **Note: Automatic reset**
>
> When the component that calls `useTweakApply` unmounts, the hook removes every variable it set,
> so the stylesheet tokens apply again. Leaving this page therefore restores the default colors.

## Feature flags

`scan`, `grid`, `rings`, `particles` and `idleDim` are plain booleans that only live in your
`tweaks` state. **No library code reads them**: neither the panel nor `useTweakApply` turns on
scanlines, a grid, orb rings, particles or idle dimming by itself. Your app decides what each flag
means and passes it on, for example to the `rings` and `particles` props of `CssOrb`, or to whether
you render scanline and grid layers at all. This demo flips two of them with switches.

```tsx
import { useState } from 'react';
import { CssOrb, Switch, TWEAKS_DEFAULTS } from 'jarvis-react-ui';
import type { TweaksState } from 'jarvis-react-ui';

export default function FeatureFlags() {
    const [tweaks, setTweaks] = useState<TweaksState>(TWEAKS_DEFAULTS);

    return (
        <div className="flex w-full flex-col items-center gap-3">
            <div className="flex gap-4">
                <Switch
                    label="Rings"
                    checked={tweaks.rings}
                    onCheckedChange={(rings) => setTweaks({ ...tweaks, rings })}
                />
                <Switch
                    label="Particles"
                    checked={tweaks.particles}
                    onCheckedChange={(particles) => setTweaks({ ...tweaks, particles })}
                />
            </div>
            <div className="relative h-[260px] w-full overflow-hidden">
                <CssOrb state="idle" rings={tweaks.rings} particles={tweaks.particles} />
            </div>
        </div>
    );
}
```

## TWEAKS_DEFAULTS

The starting values. Use them as the initial state.

```tsx
import { Tweaks, TWEAKS_DEFAULTS, useTweakApply, type TweaksState } from 'jarvis-react-ui';

const [tweaks, setTweaks] = useState<TweaksState>(TWEAKS_DEFAULTS);
useTweakApply(tweaks);

<Tweaks open={open} tweaks={tweaks} onChange={setTweaks} />;
```

| Field       | Type      | Default | Description                                                |
| ----------- | --------- | ------- | ---------------------------------------------------------- |
| `hue`       | `number`  | `215`   | Accent hue in degrees (0–360); applied by `useTweakApply`. |
| `glow`      | `number`  | `74`    | Glow intensity (0–100); applied by `useTweakApply`.        |
| `scan`      | `boolean` | `true`  | Show scanlines. Read by your app.                          |
| `grid`      | `boolean` | `true`  | Show the grid background. Read by your app.                |
| `rings`     | `boolean` | `true`  | Show the orb rings. Read by your app.                      |
| `particles` | `boolean` | `true`  | Show the orb particles. Read by your app.                  |
| `idleDim`   | `boolean` | `true`  | Dim the HUD while idle. Read by your app.                  |

The hue swatches in the panel select 215, 28, 150, 280 and 0.

## useTweakApply

`useTweakApply(tweaks: TweaksState): void` runs an effect whenever `tweaks.hue` or `tweaks.glow`
changes and sets these inline styles on `document.documentElement`:

| Variable          | Value                                                            |
| ----------------- | ---------------------------------------------------------------- |
| `--tweak-hue`     | `hue`                                                            |
| `--accent`        | `oklch(0.72 0.14 hue)`                                           |
| `--accent-bright` | `oklch(0.82 0.16 hue)`                                           |
| `--accent-speak`  | `oklch(0.77 0.15 hue)`                                           |
| `--accent-dim`    | `oklch(0.52 0.10 hue)`                                           |
| `--glow`          | one accent glow whose blur and opacity grow with `glow`          |
| `--glow-strong`   | two stacked accent glows whose blur and opacity grow with `glow` |

Every component that uses these tokens, including Tailwind classes such as `text-accent`, follows
the new color immediately. Inline styles on `:root` win over the token stylesheet. When the calling
component unmounts, the hook removes all seven properties again, so the stylesheet values apply.
Call the hook in one place only; two mounted callers overwrite each other, and the first one to
unmount removes the variables for both. The flags are not touched by the hook.

## Sound

Hovering a hue swatch or a flag toggle plays `hover_button`, clicking it plays `click`. The two range
sliders are silent. See [Sound effects](https://joeyash.github.io/jarvis_ui_lib/getting-started/sound.md).

## Accessibility

- The hue and glow sliders are native `<input type="range">` elements with visible labels, so arrow
  keys adjust them.
- Each flag is a `<button>` with `aria-pressed` and an `aria-label` equal to its caption.
- Hue swatches are buttons named `Hue <degrees>`; the selected swatch has `aria-pressed="true"`.
- The slider ids are generated with `useId`, so the labels stay linked even with several panels on
  one page.

## API

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `onChange` (required) | `(next: TweaksState) => void` |  | Called with the complete next settings object whenever a control changes. |
| `open` (required) | `boolean` |  | Whether the panel is visible; when `false` it renders with `display: none`. |
| `tweaks` (required) | `TweaksState` |  | Current settings shown in the panel (controlled). |
| `className` | `string` |  | Extra classes for the root `<div>` element (the fixed panel). |

### Type `TweaksState`

Theme settings edited by the `Tweaks` panel.

| Field | Type | Default | Description |
| --- | --- | --- | --- |
| `glow` (required) | `number` |  | Glow intensity (0–100); `useTweakApply` scales `--glow` and `--glow-strong` with it. |
| `grid` (required) | `boolean` |  | Whether the grid background should be shown; read by your app. |
| `hue` (required) | `number` |  | Accent hue in degrees (0–360); `useTweakApply` turns it into the `--accent*` tokens. |
| `idleDim` (required) | `boolean` |  | Whether the HUD should dim while idle; read by your app. |
| `particles` (required) | `boolean` |  | Whether the orb particles should be shown; read by your app (e.g. `CssOrb` `particles`). |
| `rings` (required) | `boolean` |  | Whether the orb rings should be shown; read by your app (e.g. `CssOrb` `rings`). |
| `scan` (required) | `boolean` |  | Whether scanlines should be shown; read by your app, not applied by the library. |