@cascivo/mcp 0.2.0 → 0.3.3

package/dist/context/dropdown.md

@@ -0,0 +1,96 @@
+# Dropdown
+
+**Category:** overlay  
+**Description:** Menu of actions revealed from a trigger
+
+## When to use
+
+- Revealing a short menu of actions from a trigger button (row actions, "More" overflow, account menu)
+- Grouping related commands behind one affordance with optional icons and separators
+
+## When NOT to use
+
+- Selecting a persistent value for a form — use Select or Combobox
+- A global searchable command palette — use CommandMenu; right-click context actions — use ContextMenu
+
+## Anti-patterns
+
+### Dropdown items are role="menuitem" actions fired via onSelect — there is no selected-value semantics for assistive tech or forms
+
+**Bad:** `Using Dropdown to choose a form value and reading the selection as field state`  
+**Good:** `Use Select/Combobox which expose role="combobox" and a controlled value`  
+**Why:** Dropdown items are role="menuitem" actions fired via onSelect — there is no selected-value semantics for assistive tech or forms
+
+## Related components
+
+- **Select** (alternative): Use for choosing and persisting a single form value
+- **CommandMenu** (alternative): Use for a searchable global action palette
+- **Button** (pairs-with): The trigger is typically a Button passed via the trigger prop
+
+## Accessibility rationale
+
+The menu is role="menu" with role="menuitem" buttons and roving tabindex; the trigger gets aria-haspopup="menu" and aria-expanded via cloneElement; arrow/Home/End/Enter/Escape are handled and focus returns to the trigger on select or close, and popover="auto" provides light-dismiss synced back to state via the toggle event
+
+## Props
+
+| Name           | Type                                                                                            | Required | Default      | Description                                         |
+| -------------- | ----------------------------------------------------------------------------------------------- | -------- | ------------ | --------------------------------------------------- |
+| `trigger`      | `ReactElement`                                                                                  | Yes      | —            | The element that opens the dropdown when activated. |
+| `items`        | `{ label: string; value: string; icon?: ReactNode; disabled?: boolean; separator?: boolean }[]` | Yes      | —            | The items to render.                                |
+| `onSelect`     | `(value: string) => void`                                                                       | No       | —            | Called with the selected value.                     |
+| `placement`    | `'bottom-start' \| 'bottom-end'`                                                                | No       | bottom-start | Placement relative to the trigger.                  |
+| `open`         | `boolean`                                                                                       | No       | —            | Whether the component is open (controlled).         |
+| `onOpenChange` | `(open: boolean) => void`                                                                       | No       | —            | Called with the next open state when it changes.    |
+
+## Tokens
+
+- `--cascivo-color-surface-overlay`
+- `--cascivo-color-border`
+- `--cascivo-color-bg-subtle`
+- `--cascivo-radius-md`
+- `--cascivo-z-dropdown`
+
+## Examples
+
+### Basic
+
+```jsx
+<Dropdown
+  trigger={<Button>Actions</Button>}
+  items={[{ label: 'Edit', value: 'edit' }]}
+  onSelect={handle}
+/>
+```
+
+## Boundaries
+
+| Area                       | Level    | Note                                                                               |
+| -------------------------- | -------- | ---------------------------------------------------------------------------------- |
+| trigger element            | flexible | Any ReactElement works as the trigger; ref and aria props are merged in            |
+| controlled vs uncontrolled | flexible | Supports open + onOpenChange or fully internal state                               |
+| token names                | strict   | Menu styling resolves to semantic --cascivo-color-\* / --cascivo-z-dropdown tokens |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Dropdown component (overlay). Menu of actions revealed from a trigger
+
+Architecture constraints — follow exactly:
+- Signals only (useSignal/useComputed/useSignalEffect from @cascivo/core). Never useState/useEffect/useContext/useReducer.
+- Style only through --cascivo-* custom properties. No Tailwind, no inline styles, no CSS-in-JS.
+- Responsive via @container queries on the canonical scale (30rem/40rem/64rem/80rem). Do not use global viewport @media breakpoints.
+- Visual states (hover/focus/active/disabled) via CSS pseudo-classes, not JS.
+- CSS logical properties only (RTL-safe).
+
+Dropdown is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-surface-overlay, --cascivo-color-border, --cascivo-color-bg-subtle, --cascivo-radius-md, --cascivo-z-dropdown
+
+Accessibility: role "menu", WCAG 2.2-AA, keyboard: ArrowDown/ArrowUp/Home/End/Enter/Space/Escape. Keep it AA.
+
+Do not change (strict): token names — Menu styling resolves to semantic --cascivo-color-* / --cascivo-z-dropdown tokens
+Flexible: trigger element, controlled vs uncontrolled.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/editable.md

@@ -0,0 +1,101 @@
+# Editable
+
+**Category:** inputs  
+**Description:** Inline click-to-edit text field
+
+## When to use
+
+- Editing a single piece of text in place where the value is normally read-only — titles, names, labels
+- Keeping the page layout stable: the preview and the edit input occupy the same spot
+- Letting users opt into editing by clicking, without a separate edit mode or form
+
+## When NOT to use
+
+- A field that is always meant to be edited — use Input inside a Form instead
+- Multi-line or rich text — this is a single-line input only
+- Collecting several related values at once — use a Form with grouped fields
+
+## Anti-patterns
+
+### Inline edit hides the affordance behind a click; required form fields should be visibly editable from the start
+
+**Bad:** `<Editable value={email} onValueChange={save} /> as a primary form control`  
+**Good:** `<Input label="Email" value={email} onChange={...} />`  
+**Why:** Inline edit hides the affordance behind a click; required form fields should be visibly editable from the start
+
+## Related components
+
+- **Input** (alternative): Use Input when the field is always editable rather than click-to-reveal
+
+## Accessibility rationale
+
+The preview renders as a real <button> so it is keyboard-focusable and announces as an actionable control; while editing, Enter confirms and Escape cancels, and focus is moved into the input and its text selected so keyboard users can immediately type.
+
+## Props
+
+| Name            | Type                  | Required | Default | Description                                                        |
+| --------------- | --------------------- | -------- | ------- | ------------------------------------------------------------------ |
+| `value`         | `string`              | Yes      | —       | The controlled value.                                              |
+| `onValueChange` | `(v: string) => void` | Yes      | —       | Called with the new value when it changes.                         |
+| `placeholder`   | `string`              | No       | —       | Placeholder text shown when the field is empty.                    |
+| `disabled`      | `boolean`             | No       | false   | When true, disables the control and removes it from the tab order. |
+| `submitOnBlur`  | `boolean`             | No       | true    | When true, commits the edit when the field loses focus.            |
+| `onCancel`      | `() => void`          | No       | —       | Called when the edit is cancelled.                                 |
+
+## Tokens
+
+- `--cascivo-color-surface`
+- `--cascivo-color-border`
+- `--cascivo-color-accent`
+- `--cascivo-color-text`
+- `--cascivo-color-text-muted`
+- `--cascivo-color-bg-subtle`
+- `--cascivo-radius-sm`
+- `--cascivo-focus-ring`
+
+## Examples
+
+### Basic
+
+```jsx
+<Editable value="Click to edit" onValueChange={() => {}} />
+```
+
+### With placeholder
+
+```jsx
+<Editable value="" onValueChange={() => {}} placeholder="Enter text" />
+```
+
+## Boundaries
+
+| Area                    | Level    | Note                                                                                     |
+| ----------------------- | -------- | ---------------------------------------------------------------------------------------- |
+| token names             | strict   | Visual styling must resolve to the listed --cascivo-\* surface/border/accent/text tokens |
+| placeholder copy        | flexible | Free, within tone guidance                                                               |
+| submit-on-blur behavior | flexible | submitOnBlur toggles whether blurring confirms or cancels the edit                       |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Editable component (inputs). Inline click-to-edit text field
+
+Architecture constraints — follow exactly:
+- Signals only (useSignal/useComputed/useSignalEffect from @cascivo/core). Never useState/useEffect/useContext/useReducer.
+- Style only through --cascivo-* custom properties. No Tailwind, no inline styles, no CSS-in-JS.
+- Responsive via @container queries on the canonical scale (30rem/40rem/64rem/80rem). Do not use global viewport @media breakpoints.
+- Visual states (hover/focus/active/disabled) via CSS pseudo-classes, not JS.
+- CSS logical properties only (RTL-safe).
+
+Editable is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-surface, --cascivo-color-border, --cascivo-color-accent, --cascivo-color-text, --cascivo-color-text-muted, --cascivo-color-bg-subtle, --cascivo-radius-sm, --cascivo-focus-ring
+
+Accessibility: role "button", WCAG 2.2-AA, keyboard: Enter/Escape. Keep it AA.
+
+Do not change (strict): token names — Visual styling must resolve to the listed --cascivo-* surface/border/accent/text tokens
+Flexible: placeholder copy, submit-on-blur behavior.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/editor/code-editor.md

@@ -0,0 +1,146 @@
+# CodeEditor
+
+**Category:** inputs  
+**Description:** Lightweight code editor — a native textarea overlaid on a syntax-highlighted layer, with line numbers and Tab indent.
+
+## When to use
+
+- Editing code or config inline — JSON, snippets, web languages — with line numbers and syntax colors
+- A lightweight, themeable code field where a full IDE editor (Monaco/CodeMirror) would be overkill
+- Editing Markdown notes — find/replace, real undo/redo, save, and selection-preserving external sync
+- Editing long-form Markdown — generated docs, concatenated books, big notes — windowed (viewport-scoped) tokenization keeps scrolling/typing smooth well past ~5,000 lines
+
+## When NOT to use
+
+- You need IntelliSense/LSP, multi-cursor, folding, a minimap, or diff view — use a full editor framework
+- Plain prose or a single-line value — use Textarea or Input
+- Sustained editing of 100k+-line documents — use a full editor framework / dedicated worker pipeline (the windowed tokenizer keeps per-render work O(viewport), but a worker offload is intentionally out of scope)
+- Soft-wrap (wrap) on a very large document — rendering is O(n) under wrap; disable wrap above ~10k lines for sustained editing
+
+## Anti-patterns
+
+### The overlay technique keeps the bundle tiny and themes via the cascivo token system
+
+**Bad:** `Reaching for Monaco to show an editable snippet`  
+**Good:** `Use CodeEditor for the basic set (line numbers + highlighting) at a fraction of the weight`  
+**Why:** The overlay technique keeps the bundle tiny and themes via the cascivo token system
+
+## Related components
+
+- **Highlight** (pairs-with): The read-only renderer sharing the same tokenizer — for snippets and docs
+- **Textarea** (alternative): Use for free-form prose without syntax highlighting
+
+## Accessibility rationale
+
+The native <textarea> is the editing surface, so caret, selection, IME, undo, and the a11y tree come from the browser; the highlight layer and gutter are aria-hidden.
+
+## Props
+
+| Name              | Type                                                | Required | Default   | Description                                                                                    |
+| ----------------- | --------------------------------------------------- | -------- | --------- | ---------------------------------------------------------------------------------------------- |
+| `value`           | `string`                                            | No       | —         | Controlled value                                                                               |
+| `defaultValue`    | `string`                                            | No       | —         | Initial value for uncontrolled use                                                             |
+| `onValueChange`   | `(value: string) => void`                           | No       | —         | Called with the new text on every edit                                                         |
+| `language`        | `string`                                            | No       | plaintext | Grammar name (plaintext/json/javascript/typescript/css/html/markdown/bash)                     |
+| `lineNumbers`     | `boolean`                                           | No       | true      | Show the line-number gutter                                                                    |
+| `tabSize`         | `number`                                            | No       | 2         | Spaces per tab stop                                                                            |
+| `insertSpaces`    | `boolean`                                           | No       | true      | Insert spaces vs a literal tab on Tab                                                          |
+| `wrap`            | `boolean`                                           | No       | false     | Soft-wrap long lines instead of scrolling horizontally                                         |
+| `readOnly`        | `boolean`                                           | No       | false     | When true, the value is shown but cannot be edited.                                            |
+| `disabled`        | `boolean`                                           | No       | false     | When true, disables the control and removes it from the tab order.                             |
+| `placeholder`     | `string`                                            | No       | —         | Placeholder text shown when the field is empty.                                                |
+| `label`           | `string`                                            | No       | —         | Accessible label (defaults to the i18n "Code editor")                                          |
+| `onSave`          | `(value: string) => void`                           | No       | —         | Called on Mod-S; the browser save dialog is suppressed                                         |
+| `bracketMatching` | `boolean`                                           | No       | false     | Highlight the bracket matching the one adjacent to the caret                                   |
+| `theme`           | `EditorTheme`                                       | No       | —         | Per-instance --cascivo-editor-\* overrides; swapping it re-themes live                         |
+| `keymap`          | `KeyMap`                                            | No       | —         | Extra key bindings merged over the built-ins (user wins on a chord)                            |
+| `decorations`     | `Decoration[] \| ((value: string) => Decoration[])` | No       | —         | Extra offset-range → CSS class decorations                                                     |
+| `commands`        | `SlashCommand[]`                                    | No       | —         | Slash-command entries; typing "/" opens a filtered menu. Omit to disable.                      |
+| `ref`             | `Ref<CodeEditorHandle>`                             | No       | —         | Imperative handle: applyEdit / getSelection / focus / undo / redo / openFind / openCommandMenu |
+| `className`       | `string`                                            | No       | —         | Additional CSS class names merged onto the root element.                                       |
+
+## Tokens
+
+- `--cascivo-editor-bg`
+- `--cascivo-editor-fg`
+- `--cascivo-editor-gutter-bg`
+- `--cascivo-editor-gutter-fg`
+- `--cascivo-editor-gutter-active`
+- `--cascivo-editor-current-line`
+- `--cascivo-editor-selection`
+- `--cascivo-editor-border`
+- `--cascivo-editor-match`
+- `--cascivo-editor-match-current`
+- `--cascivo-editor-bracket`
+
+## Examples
+
+### Basic editor
+
+```jsx
+import { CodeEditor } from '@cascivo/editor'
+import '@cascivo/editor/styles.css'
+;<CodeEditor language="typescript" lineNumbers defaultValue={'const x = 1\n'} />
+```
+
+### Controlled
+
+```jsx
+<CodeEditor language="json" value={value} onValueChange={setValue} />
+```
+
+### Notes editing — find, save, brackets
+
+```jsx
+<CodeEditor
+  language="markdown"
+  value={doc}
+  onValueChange={setDoc}
+  onSave={save} // Mod-S
+  bracketMatching
+/> // Mod-F to search
+```
+
+### Slash commands
+
+Type "/" to open a filtered command menu; arrows + Enter insert.
+
+```jsx
+const commands = [
+  { id: 'fence', label: 'Code block', keywords: ['code'], insert: '\u0060\u0060\u0060\n\n\u0060\u0060\u0060' },
+  { id: 'todo', label: 'TODO', insert: '// TODO: ' },
+  { id: 'date', label: 'Date', run: (e) => e.applyEdit(e.getSelection(), new Date().toISOString()) },
+]
+
+<CodeEditor language="markdown" commands={commands} />
+```
+
+## Boundaries
+
+| Area            | Level    | Note                                                                                                                                                                                                                                      |
+| --------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| languages       | flexible | Ships a small grammar set; registerGrammar adds custom languages without bundle bloat                                                                                                                                                     |
+| large documents | flexible | Windowed tokenization (tokenizeRange + LineStateIndex) makes per-render work O(viewport) and per-edit work O(changed suffix); long Markdown edits well past ~5,000 lines. Worker offload / 100k+-line sustained editing stay out of scope |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo CodeEditor component (inputs). Lightweight code editor — a native textarea overlaid on a syntax-highlighted layer, with line numbers and Tab indent.
+
+Architecture constraints — follow exactly:
+- Signals only (useSignal/useComputed/useSignalEffect from @cascivo/core). Never useState/useEffect/useContext/useReducer.
+- Style only through --cascivo-* custom properties. No Tailwind, no inline styles, no CSS-in-JS.
+- Responsive via @container queries on the canonical scale (30rem/40rem/64rem/80rem). Do not use global viewport @media breakpoints.
+- Visual states (hover/focus/active/disabled) via CSS pseudo-classes, not JS.
+- CSS logical properties only (RTL-safe).
+
+CodeEditor is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-editor-bg, --cascivo-editor-fg, --cascivo-editor-gutter-bg, --cascivo-editor-gutter-fg, --cascivo-editor-gutter-active, --cascivo-editor-current-line, --cascivo-editor-selection, --cascivo-editor-border, --cascivo-editor-match, --cascivo-editor-match-current, --cascivo-editor-bracket
+
+Accessibility: role "textbox", WCAG 2.1-AA, keyboard: Tab (indent)/Shift+Tab (dedent)/Mod+Z / Mod+Shift+Z (undo / redo)/Mod+F (find)/Mod+Alt+F (replace)/Mod+S (save)// (open slash-command menu when commands are provided)/Up/Down + Enter/Tab (navigate + insert a command), Escape (dismiss)/Standard textarea editing. Keep it AA.
+Flexible: languages, large documents.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/editor/highlight.md

@@ -0,0 +1,74 @@
+# Highlight
+
+**Category:** display  
+**Description:** Read-only syntax-highlighted code block — the same owned tokenizer as CodeEditor, without the textarea.
+
+## When to use
+
+- Displaying non-editable code or config with syntax colors — docs, snippets, examples
+- A lightweight highlighter that themes via the cascivo token system
+
+## When NOT to use
+
+- The code must be editable — use CodeEditor
+- You need copy-to-clipboard chrome around a snippet — pair with a code-snippet surface
+
+## Related components
+
+- **CodeEditor** (pairs-with): The editable surface sharing the same tokenizer
+
+## Accessibility rationale
+
+Renders a read-only <pre><code>; the line-number gutter is aria-hidden and an optional label names the block.
+
+## Props
+
+| Name          | Type      | Required | Default   | Description                                                                |
+| ------------- | --------- | -------- | --------- | -------------------------------------------------------------------------- |
+| `value`       | `string`  | Yes      | —         | Code to render                                                             |
+| `language`    | `string`  | No       | plaintext | Grammar name (plaintext/json/javascript/typescript/css/html/markdown/bash) |
+| `lineNumbers` | `boolean` | No       | false     | Show the line-number gutter                                                |
+| `wrap`        | `boolean` | No       | false     | Soft-wrap long lines                                                       |
+| `tabSize`     | `number`  | No       | 2         | Spaces per tab stop                                                        |
+| `label`       | `string`  | No       | —         | Accessible label for the code block                                        |
+| `className`   | `string`  | No       | —         | Additional CSS class names merged onto the root element.                   |
+
+## Tokens
+
+- `--cascivo-editor-bg`
+- `--cascivo-editor-fg`
+- `--cascivo-editor-gutter-bg`
+- `--cascivo-editor-gutter-fg`
+- `--cascivo-editor-border`
+
+## Examples
+
+### Read-only snippet
+
+```jsx
+import { Highlight } from '@cascivo/editor'
+import '@cascivo/editor/styles.css'
+;<Highlight language="json" value={'{ "ok": true }'} />
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Highlight component (display). Read-only syntax-highlighted code block — the same owned tokenizer as CodeEditor, without the textarea.
+
+Architecture constraints — follow exactly:
+- Signals only (useSignal/useComputed/useSignalEffect from @cascivo/core). Never useState/useEffect/useContext/useReducer.
+- Style only through --cascivo-* custom properties. No Tailwind, no inline styles, no CSS-in-JS.
+- Responsive via @container queries on the canonical scale (30rem/40rem/64rem/80rem). Do not use global viewport @media breakpoints.
+- Visual states (hover/focus/active/disabled) via CSS pseudo-classes, not JS.
+- CSS logical properties only (RTL-safe).
+
+Highlight is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-editor-bg, --cascivo-editor-fg, --cascivo-editor-gutter-bg, --cascivo-editor-gutter-fg, --cascivo-editor-border
+
+Accessibility: role "group", WCAG 2.1-AA, keyboard: Scroll (no interactive controls). Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/empty-state.md

@@ -0,0 +1,101 @@
+# EmptyState
+
+**Category:** display  
+**Description:** Placeholder for views that have no data to display
+
+## When to use
+
+- Filling a view that has no data with guidance and a primary next step
+- Explaining why a list/table is empty (no results, nothing created yet)
+- Offering an action that resolves the empty condition (action prop)
+
+## When NOT to use
+
+- Content is still loading — use Skeleton or Spinner
+- An error occurred — use Alert to explain the failure
+
+## Anti-patterns
+
+### Conflating loading with empty tells the user there is no data when there may be
+
+**Bad:** `Showing an EmptyState while data is still fetching`  
+**Good:** `A Skeleton during load, then EmptyState only if the result is empty`  
+**Why:** Conflating loading with empty tells the user there is no data when there may be
+
+## Related components
+
+- **Skeleton** (alternative): Skeleton covers the loading phase before data resolves
+- **Alert** (alternative): Use Alert for error states rather than a generic empty state
+
+## Accessibility rationale
+
+Presentational by role; the title carries the meaning as text and the action is a real focusable control, so keyboard and screen-reader users can act on the next step
+
+## Props
+
+| Name          | Type           | Required | Default | Description                                           |
+| ------------- | -------------- | -------- | ------- | ----------------------------------------------------- |
+| `icon`        | `ReactNode`    | No       | —       | Icon element rendered in the component.               |
+| `title`       | `string`       | Yes      | —       | Title text for the component.                         |
+| `description` | `string`       | No       | —       | Supporting description text.                          |
+| `action`      | `ReactNode`    | No       | —       | Primary action shown in the component.                |
+| `size`        | `'md' \| 'lg'` | No       | md      | Visual size of the component (e.g. 'sm', 'md', 'lg'). |
+
+## Tokens
+
+- `--cascivo-color-text`
+- `--cascivo-color-text-subtle`
+- `--cascivo-color-text-muted`
+- `--cascivo-color-bg-subtle`
+- `--cascivo-radius-full`
+
+## Examples
+
+### Basic
+
+```jsx
+<EmptyState title="No results" description="Try adjusting your filters." />
+```
+
+### With action
+
+```jsx
+<EmptyState
+  icon="📄"
+  title="No documents yet"
+  description="Create your first document to get started."
+  action={<Button>New document</Button>}
+/>
+```
+
+## Boundaries
+
+| Area            | Level    | Note                                                                    |
+| --------------- | -------- | ----------------------------------------------------------------------- |
+| size and action | flexible | Action and icon are optional; size scales for full-page vs in-panel use |
+| token names     | strict   | Text and background colors must resolve to --cascivo-\* tokens          |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo EmptyState component (display). Placeholder for views that have no data to display
+
+Architecture constraints — follow exactly:
+- Signals only (useSignal/useComputed/useSignalEffect from @cascivo/core). Never useState/useEffect/useContext/useReducer.
+- Style only through --cascivo-* custom properties. No Tailwind, no inline styles, no CSS-in-JS.
+- Responsive via @container queries on the canonical scale (30rem/40rem/64rem/80rem). Do not use global viewport @media breakpoints.
+- Visual states (hover/focus/active/disabled) via CSS pseudo-classes, not JS.
+- CSS logical properties only (RTL-safe).
+
+EmptyState is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-text, --cascivo-color-text-subtle, --cascivo-color-text-muted, --cascivo-color-bg-subtle, --cascivo-radius-full
+
+Accessibility: role "none", WCAG 2.2-AA. Keep it AA.
+
+Do not change (strict): token names — Text and background colors must resolve to --cascivo-* tokens
+Flexible: size and action.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/fab.md

@@ -0,0 +1,128 @@
+# Fab
+
+**Category:** inputs  
+**Description:** Floating action button anchored to a screen corner, with an optional speed-dial of secondary actions
+
+## When to use
+
+- A single, high-emphasis primary action that floats above scrolling content (e.g. Compose, Add)
+- A small cluster of related create actions revealed from one corner via a speed-dial
+- Touch-first screens where the primary action should stay reachable at the thumb
+
+## When NOT to use
+
+- Ordinary form or toolbar buttons — use Button or IconButton in the layout flow
+- More than a handful of actions — use a Menu, Drawer, or full navigation
+- Primary navigation between top-level destinations — use Dock
+
+## Anti-patterns
+
+### A floating button competes with the in-flow submit and hides the action off the form
+
+**Bad:** `<Fab label="Save"><SaveIcon /></Fab> next to a form submit button`  
+**Good:** `<Button type="submit">Save</Button>`  
+**Why:** A floating button competes with the in-flow submit and hides the action off the form
+
+## Related components
+
+- **IconButton** (alternative): Use IconButton for an in-flow icon control; Fab floats and is high-emphasis
+- **Dock** (alternative): Use Dock for bottom navigation between destinations rather than a single action
+
+## Accessibility rationale
+
+The main button is icon-only and requires a `label` that becomes its aria-label. With a speed-dial it exposes aria-haspopup="menu", aria-expanded, and aria-controls; the dial is a role="menu" of role="menuitem" buttons under vertical roving focus (Arrow keys, Home/End, wrapping). Opening moves focus to the first action and closing (Escape, outside press, or selection via DismissableLayer) returns focus to the button.
+
+## Props
+
+| Name           | Type                             | Required | Default    | Description                                                                 |
+| -------------- | -------------------------------- | -------- | ---------- | --------------------------------------------------------------------------- |
+| `children`     | `React.ReactNode`                | Yes      | —          | The main icon                                                               |
+| `label`        | `string`                         | Yes      | —          | Accessible name for the button                                              |
+| `onClick`      | `() => void`                     | No       | —          | Called when the element is clicked.                                         |
+| `actions`      | `FabAction[]`                    | No       | —          | Speed-dial actions; each has a label, icon, onSelect, and optional disabled |
+| `position`     | `'bottom-end' \| 'bottom-start'` | No       | bottom-end | Position of the component.                                                  |
+| `open`         | `boolean`                        | No       | —          | Whether the component is open (controlled).                                 |
+| `defaultOpen`  | `boolean`                        | No       | —          | Whether the component is open on first render (uncontrolled).               |
+| `onOpenChange` | `(open: boolean) => void`        | No       | —          | Called with the next open state when it changes.                            |
+| `className`    | `string`                         | No       | —          | Additional CSS class names merged onto the root element.                    |
+
+## Tokens
+
+- `--cascivo-color-accent`
+- `--cascivo-color-accent-content`
+- `--cascivo-color-accent-hover`
+- `--cascivo-color-surface`
+- `--cascivo-color-border`
+- `--cascivo-radius-full`
+- `--cascivo-shadow-overlay`
+- `--cascivo-target-min-coarse`
+- `--cascivo-motion-enter`
+- `--cascivo-motion-exit`
+- `--cascivo-z-dropdown`
+
+## Examples
+
+### Single action
+
+```jsx
+<Fab label="Compose" onClick={compose}>
+  <PlusIcon />
+</Fab>
+```
+
+### Speed dial
+
+The main button toggles a menu of secondary actions.
+
+```jsx
+<Fab
+  label="Create"
+  actions={[
+    { label: 'New note', icon: <NoteIcon />, onSelect: newNote },
+    { label: 'New folder', icon: <FolderIcon />, onSelect: newFolder },
+  ]}
+>
+  <PlusIcon />
+</Fab>
+```
+
+### Start corner
+
+```jsx
+<Fab label="Help" position="bottom-start" onClick={openHelp}>
+  <HelpIcon />
+</Fab>
+```
+
+## Boundaries
+
+| Area       | Level    | Note                                                                          |
+| ---------- | -------- | ----------------------------------------------------------------------------- |
+| actions    | flexible | Omit for a single-action button, or provide a speed-dial of secondary actions |
+| position   | strict   | Anchored to bottom-end or bottom-start; honours safe-area insets              |
+| open state | flexible | Speed-dial is controlled (open/onOpenChange) or uncontrolled (defaultOpen)    |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Fab component (inputs). Floating action button anchored to a screen corner, with an optional speed-dial of secondary actions
+
+Architecture constraints — follow exactly:
+- Signals only (useSignal/useComputed/useSignalEffect from @cascivo/core). Never useState/useEffect/useContext/useReducer.
+- Style only through --cascivo-* custom properties. No Tailwind, no inline styles, no CSS-in-JS.
+- Responsive via @container queries on the canonical scale (30rem/40rem/64rem/80rem). Do not use global viewport @media breakpoints.
+- Visual states (hover/focus/active/disabled) via CSS pseudo-classes, not JS.
+- CSS logical properties only (RTL-safe).
+
+Fab is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-accent, --cascivo-color-accent-content, --cascivo-color-accent-hover, --cascivo-color-surface, --cascivo-color-border, --cascivo-radius-full, --cascivo-shadow-overlay, --cascivo-target-min-coarse, --cascivo-motion-enter, --cascivo-motion-exit, --cascivo-z-dropdown
+
+Accessibility: role "button", WCAG 2.2-AA, keyboard: Enter/Space/ArrowUp/ArrowDown/Home/End/Escape. Keep it AA.
+
+Do not change (strict): position — Anchored to bottom-end or bottom-start; honours safe-area insets
+Flexible: actions, open state.
+
+Do not invent props, tokens, or global viewport media queries.
+```