@cascivo/mcp 0.2.0 → 0.3.3

package/dist/context/layout/split-view.md

@@ -0,0 +1,71 @@
+# SplitView
+
+**Category:** layout  
+**Description:** Resizable two-pane split layout with keyboard and pointer drag support.
+
+## When to use
+
+- Two side-by-side panes the user can resize via pointer or keyboard
+- Master/detail, editor/preview, or list/content layouts
+
+## When NOT to use
+
+- Static two-column content — use Columns
+- A full app frame with persistent navigation — use AppShell or SidebarApp
+
+## Related components
+
+- **Columns** (alternative): Use for static, non-resizable two-column content
+
+## Accessibility rationale
+
+Exposes a keyboard-operable separator with role="separator" and aria-valuenow for the split ratio.
+
+## Props
+
+| Name           | Type        | Required | Default | Description                  |
+| -------------- | ----------- | -------- | ------- | ---------------------------- |
+| `start`        | `ReactNode` | Yes      | —       | Left pane content            |
+| `end`          | `ReactNode` | Yes      | —       | Right pane content           |
+| `defaultRatio` | `number`    | No       | —       | Initial split ratio (0–1)    |
+| `min`          | `number`    | No       | —       | Minimum ratio for start pane |
+| `max`          | `number`    | No       | —       | Maximum ratio for start pane |
+| `aria-label`   | `string`    | No       | —       | Label for the separator      |
+
+## Tokens
+
+- `--cascivo-color-border`
+- `--cascivo-color-accent`
+- `--cascivo-duration-150`
+
+## Examples
+
+### Basic
+
+Two-pane split with draggable divider
+
+```jsx
+<SplitView start={<FileTree />} end={<Editor />} />
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo SplitView component (layout). Resizable two-pane split layout with keyboard and pointer drag support.
+
+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).
+
+SplitView is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-border, --cascivo-color-accent, --cascivo-duration-150
+
+Accessibility: role "separator", WCAG 2.1-AA, keyboard: ArrowLeft/ArrowRight. Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/layout/stack.md

@@ -0,0 +1,93 @@
+# Stack
+
+**Category:** layout  
+**Description:** Flex layout primitive for vertical or horizontal stacking with gap control.
+
+## When to use
+
+- Arranging children vertically or horizontally with a consistent gap
+- The default primitive for spacing a small set of elements in one direction
+
+## When NOT to use
+
+- Two-dimensional layouts — use Grid
+- Responsive auto-wrapping card collections — use AutoGrid
+- A visual card-pile / overlapping avatars — that is the DIFFERENT `Stack` in @cascivo/react (an `offset` prop), not this flex layout primitive.
+
+## Anti-patterns
+
+### The published `Stack` export is a card-pile that overlaps children; this gap-based flex Stack is copy-paste-only despite sharing the name.
+
+**Bad:** `Expecting import { Stack } from '@cascivo/react' to gap items`  
+**Good:** `Copy this layout Stack in with `npx cascivo add stack`, then import it from your local layouts`  
+**Why:** The published `Stack` export is a card-pile that overlaps children; this gap-based flex Stack is copy-paste-only despite sharing the name.
+
+## Related components
+
+- **Stack (card-pile)** (alternative): The `@cascivo/react` `Stack` overlaps children with an offset (card-pile) — a different component that shares this name. Pick by behaviour: gap layout here, visual overlap there.
+- **Grid** (alternative): Use for two-dimensional row-and-column layouts
+- **Columns** (alternative): Use for equal-width multi-column content
+
+## Accessibility rationale
+
+Pure layout primitive with no semantic role; does not affect the accessibility tree.
+
+## Props
+
+| Name        | Type                                  | Required | Default | Description        |
+| ----------- | ------------------------------------- | -------- | ------- | ------------------ |
+| `direction` | `'vertical' \| 'horizontal'`          | No       | —       | Flex direction     |
+| `gap`       | `1\|2\|3\|4\|5\|6\|8\|10\|12`         | No       | —       | Spacing token step |
+| `align`     | `'start'\|'center'\|'end'\|'stretch'` | No       | —       | align-items        |
+| `justify`   | `'start'\|'center'\|'end'\|'between'` | No       | —       | justify-content    |
+| `wrap`      | `boolean`                             | No       | —       | Allow wrapping     |
+
+## Tokens
+
+- `--cascivo-space-*`
+
+## Examples
+
+### Vertical
+
+Default vertical stack
+
+```jsx
+<Stack gap={4}>
+  <div>A</div>
+  <div>B</div>
+</Stack>
+```
+
+### Horizontal
+
+Row layout
+
+```jsx
+<Stack direction="horizontal" gap={2}>
+  <div>A</div>
+  <div>B</div>
+</Stack>
+```
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Stack component (layout). Flex layout primitive for vertical or horizontal stacking with gap control.
+
+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).
+
+Stack is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-space-*
+
+Accessibility: role "generic", WCAG 2.1-AA. Keep it AA.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/link.md

@@ -0,0 +1,112 @@
+# Link
+
+**Category:** navigation  
+**Description:** Styled anchor for navigation, standalone or inline within prose
+
+## When to use
+
+- Navigating to another page, view, or resource via a real href
+- Inline cross-references within prose (variant="inline")
+- Linking to an external destination with a clear new-tab indicator (external)
+
+## When NOT to use
+
+- Triggering an action or mutation with no destination — use Button
+- Submitting a form — use a submit Button
+
+## Anti-patterns
+
+### Links are for navigation; actions belong to buttons so keyboard and assistive tech behave correctly
+
+**Bad:** `<Link onClick={doThing}> with no href`  
+**Good:** `<Button onClick={doThing}>`  
+**Why:** Links are for navigation; actions belong to buttons so keyboard and assistive tech behave correctly
+
+## Related components
+
+- **Button** (alternative): Button is for actions; Link is for navigation
+
+## Accessibility rationale
+
+Renders a native <a> so role, Enter activation, and focus come from the platform; external links add rel="noreferrer" and a visual indicator so users know a new tab will open
+
+## Props
+
+| Name       | Type                       | Required | Default    | Description                                                                  |
+| ---------- | -------------------------- | -------- | ---------- | ---------------------------------------------------------------------------- |
+| `variant`  | `'standalone' \| 'inline'` | No       | standalone | Selects the visual style variant.                                            |
+| `size`     | `'sm' \| 'md' \| 'lg'`     | No       | md         | Visual size of the component (e.g. 'sm', 'md', 'lg').                        |
+| `external` | `boolean`                  | No       | false      | When true, treats the link as external (opens in a new tab with rel safety). |
+| `href`     | `string`                   | No       | —          | The destination URL.                                                         |
+
+## Tokens
+
+- `--cascivo-color-accent`
+- `--cascivo-color-accent-hover`
+- `--cascivo-color-accent-active`
+- `--cascivo-radius-sm`
+- `--cascivo-focus-ring`
+
+## Examples
+
+### Standalone
+
+```jsx
+<Link href="/docs">View documentation</Link>
+```
+
+### Inline
+
+Inline links inherit the surrounding font size and stay underlined.
+
+```jsx
+<p>
+  Read the{' '}
+  <Link variant="inline" href="/guide">
+    guide
+  </Link>{' '}
+  first.
+</p>
+```
+
+### External
+
+Opens in a new tab with rel="noreferrer" and a visual indicator.
+
+```jsx
+<Link external href="https://example.com">
+  Example
+</Link>
+```
+
+## Boundaries
+
+| Area        | Level    | Note                                                             |
+| ----------- | -------- | ---------------------------------------------------------------- |
+| variant     | flexible | standalone vs inline depending on whether the link sits in prose |
+| token names | strict   | Accent colors and focus ring 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 Link component (navigation). Styled anchor for navigation, standalone or inline within prose
+
+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).
+
+Link is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-accent, --cascivo-color-accent-hover, --cascivo-color-accent-active, --cascivo-radius-sm, --cascivo-focus-ring
+
+Accessibility: role "link", WCAG 2.2-AA, keyboard: Enter. Keep it AA.
+
+Do not change (strict): token names — Accent colors and focus ring must resolve to --cascivo-* tokens
+Flexible: variant.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/list.md

@@ -0,0 +1,109 @@
+# List
+
+**Category:** display  
+**Description:** Styled unordered or ordered list with ListItem
+
+## When to use
+
+- Presenting a set of related items as a bulleted or numbered list
+- Conveying sequence with an ordered list (as="ol")
+- Keeping list semantics while hiding visual markers (marker="none")
+
+## When NOT to use
+
+- Tabular data with multiple columns — use DataTable
+- Interactive navigation items — use SideNav or a menu
+
+## Anti-patterns
+
+### Real list markup lets screen readers announce item count and position
+
+**Bad:** `A stack of <Text> rows used as a visual list`  
+**Good:** `<List><ListItem>…</ListItem></List>`  
+**Why:** Real list markup lets screen readers announce item count and position
+
+## Related components
+
+- **Text** (contains): ListItem content is typically body Text
+
+## Accessibility rationale
+
+Renders native <ul>/<ol> with <li> children so assistive tech announces the list and its length; marker="none" hides bullets visually without removing list semantics
+
+## Props
+
+| Name     | Type                            | Required | Default                               | Description                                        |
+| -------- | ------------------------------- | -------- | ------------------------------------- | -------------------------------------------------- |
+| `as`     | `'ul' \| 'ol'`                  | No       | ul                                    | The HTML element to render as.                     |
+| `marker` | `'disc' \| 'decimal' \| 'none'` | No       | derived from as (ul→disc, ol→decimal) | List marker style ('disc' \| 'decimal' \| 'none'). |
+
+## Tokens
+
+- `--cascivo-font-sans`
+- `--cascivo-leading-normal`
+- `--cascivo-color-text`
+- `--cascivo-text-base`
+- `--cascivo-space-1`
+- `--cascivo-space-6`
+
+## Examples
+
+### Unordered
+
+```jsx
+<List>
+  <ListItem>Tokens</ListItem>
+  <ListItem>Themes</ListItem>
+</List>
+```
+
+### Ordered
+
+```jsx
+<List as="ol">
+  <ListItem>Init</ListItem>
+  <ListItem>Add</ListItem>
+</List>
+```
+
+### Unmarked
+
+Keeps list semantics without visual markers
+
+```jsx
+<List marker="none">
+  <ListItem>Clean row</ListItem>
+</List>
+```
+
+## Boundaries
+
+| Area        | Level    | Note                                                       |
+| ----------- | -------- | ---------------------------------------------------------- |
+| marker      | flexible | disc/decimal/none chosen to match content and visual needs |
+| token names | strict   | Spacing and text color 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 List component (display). Styled unordered or ordered list with ListItem
+
+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).
+
+List is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-font-sans, --cascivo-leading-normal, --cascivo-color-text, --cascivo-text-base, --cascivo-space-1, --cascivo-space-6
+
+Accessibility: role "list", WCAG 2.2-AA. Keep it AA.
+
+Do not change (strict): token names — Spacing and text color must resolve to --cascivo-* tokens
+Flexible: marker.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/log-viewer.md

@@ -0,0 +1,124 @@
+# LogViewer
+
+**Category:** display  
+**Description:** Virtualized monospace console for high-frequency log and stream output
+
+## When to use
+
+- Rendering continuous, high-volume log or stream output (build/deploy logs, server output)
+- Showing thousands of lines without mounting a DOM node per line
+- Auto-following live output while letting the user scroll back to inspect history
+
+## When NOT to use
+
+- A short, static block of code or output — use a <pre> or Code block
+- Tabular data with columns — use DataTable
+- A rich interactive terminal with cursor addressing — out of scope (line-oriented only)
+
+## Anti-patterns
+
+### The slice pattern reallocates the whole array per line (O(n)) and renders per line; the stream buffer is O(1) and renders once per frame
+
+**Bad:** `logsSignal.value = [...logsSignal.value.slice(1), line]`  
+**Good:** `const logs = useStreamBuffer({ capacity: 1000 }); logs.append(line)`  
+**Why:** The slice pattern reallocates the whole array per line (O(n)) and renders per line; the stream buffer is O(1) and renders once per frame
+
+## Related components
+
+- **createStreamBuffer** (pairs-with): Provides the bounded, O(1) signal LogViewer renders
+- **DataTable** (alternative): DataTable virtualizes tabular rows; LogViewer virtualizes monospace lines
+
+## Accessibility rationale
+
+The scroll region is role="log" with aria-live="polite" so assistive tech announces new output without stealing focus; the container is keyboard-scrollable and a visually-hidden live status reports the line count; color is paired with level semantics, never the sole encoding
+
+## Props
+
+| Name             | Type                                                       | Required | Default | Description                                                     |
+| ---------------- | ---------------------------------------------------------- | -------- | ------- | --------------------------------------------------------------- |
+| `lines`          | `ReadonlySignal<readonly LogLine[]> \| readonly LogLine[]` | Yes      | —       | The log lines to display (a signal or array).                   |
+| `rowHeight`      | `number`                                                   | No       | 20      | Height of each row in pixels, used for virtualization.          |
+| `overscan`       | `number`                                                   | No       | 8       | Number of extra rows rendered above and below the viewport.     |
+| `follow`         | `boolean`                                                  | No       | —       | Whether the view auto-scrolls to follow new lines (controlled). |
+| `onFollowChange` | `(follow: boolean) => void`                                | No       | —       | Called with the new follow state when it changes.               |
+| `ansi`           | `boolean`                                                  | No       | false   | When true, parses ANSI color escape codes into colored spans.   |
+| `search`         | `string`                                                   | No       | —       | Query used to filter and highlight matching lines.              |
+| `maxHeight`      | `string`                                                   | No       | '24rem' | Maximum height of the scroll viewport (CSS length).             |
+| `labels`         | `LogViewerLabels`                                          | No       | —       | Overrides for the component’s user-visible strings (i18n).      |
+
+## Tokens
+
+- `--cascivo-font-mono`
+- `--cascivo-color-text`
+- `--cascivo-color-text-muted`
+- `--cascivo-color-surface`
+- `--cascivo-color-surface-raised`
+- `--cascivo-color-border`
+- `--cascivo-color-error`
+- `--cascivo-color-warning`
+- `--cascivo-color-success`
+- `--cascivo-color-info`
+- `--cascivo-color-accent`
+- `--cascivo-target-min-coarse`
+
+## Examples
+
+### Streaming build log
+
+Backed by createStreamBuffer; auto-follows the tail
+
+```jsx
+const logs = useStreamBuffer<LogLine>({ capacity: 1000 })
+// socket.onmessage = (e) => logs.append({ id: seq++, text: e.data })
+<LogViewer lines={logs.signal} />
+```
+
+### Static log with levels
+
+```jsx
+<LogViewer
+  lines={[
+    { id: 1, text: 'Build started', level: 'info' },
+    { id: 2, text: 'Type error', level: 'error' },
+  ]}
+/>
+```
+
+### ANSI colored output
+
+```jsx
+<LogViewer ansi lines={ansiLines} maxHeight="32rem" />
+```
+
+## Boundaries
+
+| Area        | Level    | Note                                                                               |
+| ----------- | -------- | ---------------------------------------------------------------------------------- |
+| data source | flexible | Accepts a live signal or a plain array                                             |
+| rowHeight   | strict   | Virtualization assumes a fixed row height; variable-height lines are not supported |
+| coloring    | flexible | Per-line level or ANSI SGR-16 escapes                                              |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo LogViewer component (display). Virtualized monospace console for high-frequency log and stream output
+
+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).
+
+LogViewer is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-font-mono, --cascivo-color-text, --cascivo-color-text-muted, --cascivo-color-surface, --cascivo-color-surface-raised, --cascivo-color-border, --cascivo-color-error, --cascivo-color-warning, --cascivo-color-success, --cascivo-color-info, --cascivo-color-accent, --cascivo-target-min-coarse
+
+Accessibility: role "log", WCAG 2.2-AA, keyboard: Tab/ArrowUp/ArrowDown/PageUp/PageDown. Keep it AA.
+
+Do not change (strict): rowHeight — Virtualization assumes a fixed row height; variable-height lines are not supported
+Flexible: data source, coloring.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/menu-button.md

@@ -0,0 +1,137 @@
+# MenuButton
+
+**Category:** navigation  
+**Description:** A button that opens an anchored action menu of one-shot commands
+
+## When to use
+
+- Exposing a small set of one-shot actions behind a single labeled button
+- Toolbar or header overflow actions where each item runs a command on activation
+- Action lists that need ArrowUp/ArrowDown roving focus and Enter/Space activation
+
+## When NOT to use
+
+- Choosing and persisting a value from options — use Select
+- Right-click contextual actions on a target element — use ContextMenu
+- A single action with no list — use a plain Button
+- Rich interactive content (forms, pickers) rather than a list of commands — use Popover
+
+## Anti-patterns
+
+### role="menuitem" items do not model a selected value and dismiss the menu when activated, so they cannot represent persistent choices
+
+**Bad:** `Rendering checkbox or radio state inside MenuButton items and treating selection as a chosen value`  
+**Good:** `Use Select or MultiSelect for value selection; MenuButton items are one-shot actions that close the menu on activation`  
+**Why:** role="menuitem" items do not model a selected value and dismiss the menu when activated, so they cannot represent persistent choices
+
+### A trigger with no accessible name is unusable for screen-reader and voice-control users
+
+**Bad:** `Leaving the trigger label empty with no visible text and no labels.open override`  
+**Good:** `Provide visible label text, or pass labels.open / rely on the built-in i18n accessible name`  
+**Why:** A trigger with no accessible name is unusable for screen-reader and voice-control users
+
+## Related components
+
+- **Menu** (alternative): Use Menu for fully composable trigger + item children; MenuButton is the prop-driven convenience form
+- **ContextMenu** (alternative): Use ContextMenu when actions are triggered by right-click on a target rather than a button
+- **Select** (alternative): Use Select when the user is picking a value instead of firing an action
+- **Button** (contains): The trigger is a styled button that opens the menu
+
+## Accessibility rationale
+
+The trigger is a real <button> exposing aria-haspopup="menu", aria-expanded reflecting open state, and aria-controls pointing at the role="menu" panel. ArrowDown/Enter/Space open the menu and move focus to the first enabled item, ArrowUp opens and focuses the last item, ArrowUp/ArrowDown rove focus between items with wrap-around, disabled items are aria-disabled and skipped by roving focus, Escape closes and restores focus to the trigger, and Tab closes without trapping focus. DismissableLayer provides outside-pointer and Escape dismissal, and high-contrast plus reduced-motion preferences are honored in CSS.
+
+## Props
+
+| Name       | Type                                  | Required | Default     | Description                                             |
+| ---------- | ------------------------------------- | -------- | ----------- | ------------------------------------------------------- |
+| `label`    | `ReactNode`                           | Yes      | —           | Trigger button content                                  |
+| `items`    | `MenuButtonItem[]`                    | Yes      | —           | Action items: { id, label, onSelect?, disabled? }       |
+| `variant`  | `'primary' \| 'secondary' \| 'ghost'` | No       | 'secondary' | Trigger visual variant                                  |
+| `size`     | `'sm' \| 'md' \| 'lg'`                | No       | 'md'        | Trigger size                                            |
+| `disabled` | `boolean`                             | No       | false       | Disables the trigger                                    |
+| `align`    | `'start' \| 'end'`                    | No       | 'start'     | Aligns the menu to the start or end edge of the trigger |
+| `labels`   | `{ open?: string }`                   | No       | —           | Override the trigger accessible name                    |
+
+## Tokens
+
+- `--cascivo-color-primary`
+- `--cascivo-color-primary-fg`
+- `--cascivo-color-primary-hover`
+- `--cascivo-color-surface`
+- `--cascivo-color-border`
+- `--cascivo-color-text`
+- `--cascivo-color-bg-subtle`
+- `--cascivo-radius-control`
+- `--cascivo-radius-overlay`
+- `--cascivo-radius-item`
+- `--cascivo-shadow-md`
+- `--cascivo-focus-ring`
+- `--cascivo-motion-enter`
+- `--cascivo-z-dropdown`
+
+## Examples
+
+### Basic action menu
+
+A secondary button that opens a list of actions
+
+```jsx
+<MenuButton
+  label="Actions"
+  items={[
+    { id: 'edit', label: 'Edit', onSelect: () => edit() },
+    { id: 'duplicate', label: 'Duplicate', onSelect: () => duplicate() },
+    { id: 'delete', label: 'Delete', onSelect: () => remove(), disabled: !canDelete },
+  ]}
+/>
+```
+
+### End-aligned, primary
+
+Aligns the menu to the trigger end edge
+
+```jsx
+<MenuButton
+  label="Create"
+  variant="primary"
+  align="end"
+  items={[
+    { id: 'doc', label: 'New document', onSelect: createDoc },
+    { id: 'folder', label: 'New folder', onSelect: createFolder },
+  ]}
+/>
+```
+
+## Boundaries
+
+| Area               | Level    | Note                                                                     |
+| ------------------ | -------- | ------------------------------------------------------------------------ |
+| token names        | strict   | Trigger and menu styling must resolve to the listed --cascivo-\* tokens  |
+| item content       | flexible | Each item label accepts arbitrary ReactNode; onSelect defines the action |
+| trigger appearance | flexible | variant and size choose among the standard button looks and dimensions   |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo MenuButton component (navigation). A button that opens an anchored action menu of one-shot commands
+
+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).
+
+MenuButton is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-primary, --cascivo-color-primary-fg, --cascivo-color-primary-hover, --cascivo-color-surface, --cascivo-color-border, --cascivo-color-text, --cascivo-color-bg-subtle, --cascivo-radius-control, --cascivo-radius-overlay, --cascivo-radius-item, --cascivo-shadow-md, --cascivo-focus-ring, --cascivo-motion-enter, --cascivo-z-dropdown
+
+Accessibility: role "menu", WCAG 2.2-AA, keyboard: ArrowDown/ArrowUp/Enter/Space/Escape/Tab. Keep it AA.
+
+Do not change (strict): token names — Trigger and menu styling must resolve to the listed --cascivo-* tokens
+Flexible: item content, trigger appearance.
+
+Do not invent props, tokens, or global viewport media queries.
+```