@cascivo/mcp 0.2.0 → 0.3.4

package/dist/context/notification.md

@@ -0,0 +1,116 @@
+# Notification
+
+**Category:** feedback  
+**Description:** Inline, actionable notification banner that surfaces a titled message with an optional recovery action
+
+## When to use
+
+- Surfacing a prominent, often actionable message in the page flow (sync result, failed upload, available update)
+- Pairing a status message with one or more recovery actions via the actions slot
+- Communicating outcomes that should persist until the user reads or acts on them
+
+## When NOT to use
+
+- Transient, auto-dismissing feedback that floats above the layout — use Toast
+- A terse single-line action status next to a control — use InlineLoading
+- Blocking the user for a required decision — use Modal or AlertDialog
+
+## Anti-patterns
+
+### Notification is an in-flow banner; faking toast behavior duplicates Toast and breaks layout expectations
+
+**Bad:** `Stacking Notifications in a fixed corner viewport on a timer to fake toasts`  
+**Good:** `<Toast> for ephemeral, floating, auto-dismissing feedback`  
+**Why:** Notification is an in-flow banner; faking toast behavior duplicates Toast and breaks layout expectations
+
+## Related components
+
+- **Toast** (alternative): Toast floats and auto-dismisses; Notification stays inline in the document flow
+- **Alert** (alternative): Alert is a lighter inline message; Notification leans into a leading variant icon and an actions slot
+
+## Accessibility rationale
+
+role="alert" for warning and error so assistive tech announces them assertively, role="status" for info and success; the variant icon is decorative (aria-hidden) and color is always paired with the icon and title, and the dismiss control is a labeled button
+
+## Props
+
+| Name          | Type                                          | Required | Default | Description                                                |
+| ------------- | --------------------------------------------- | -------- | ------- | ---------------------------------------------------------- |
+| `title`       | `ReactNode`                                   | Yes      | —       | Title text for the component.                              |
+| `description` | `ReactNode`                                   | No       | —       | Supporting description text.                               |
+| `variant`     | `'info' \| 'success' \| 'warning' \| 'error'` | No       | info    | Selects the visual style variant.                          |
+| `dismissible` | `boolean`                                     | No       | false   | When true, shows a control to dismiss the component.       |
+| `onDismiss`   | `() => void`                                  | No       | —       | Called when the component is dismissed.                    |
+| `actions`     | `ReactNode`                                   | No       | —       | Action elements shown in the notification.                 |
+| `icon`        | `ReactNode`                                   | No       | —       | Icon element rendered in the component.                    |
+| `labels`      | `{ dismiss?: string }`                        | No       | —       | Overrides for the component’s user-visible strings (i18n). |
+
+## Tokens
+
+- `--cascivo-color-info`
+- `--cascivo-color-success`
+- `--cascivo-color-warning`
+- `--cascivo-color-destructive`
+- `--cascivo-color-border`
+- `--cascivo-color-surface`
+- `--cascivo-radius-surface`
+- `--cascivo-motion-enter`
+- `--cascivo-motion-exit`
+
+## Examples
+
+### Info
+
+```jsx
+<Notification variant="info" title="Sync complete" description="Your files are up to date." />
+```
+
+### Dismissible
+
+```jsx
+<Notification variant="success" title="Saved" dismissible onDismiss={handleDismiss} />
+```
+
+### Actionable
+
+```jsx
+<Notification
+  variant="error"
+  title="Upload failed"
+  description="The connection dropped."
+  actions={<Button onClick={retry}>Retry</Button>}
+/>
+```
+
+## Boundaries
+
+| Area         | Level    | Note                                                                           |
+| ------------ | -------- | ------------------------------------------------------------------------------ |
+| icon         | flexible | A variant-appropriate icon is supplied by default; override with the icon prop |
+| actions      | flexible | Any ReactNode (typically Buttons) can fill the actions slot                    |
+| role mapping | strict   | warning/error must use role="alert"; info/success use role="status"            |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo Notification component (feedback). Inline, actionable notification banner that surfaces a titled message with an optional recovery action
+
+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).
+
+Notification is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-info, --cascivo-color-success, --cascivo-color-warning, --cascivo-color-destructive, --cascivo-color-border, --cascivo-color-surface, --cascivo-radius-surface, --cascivo-motion-enter, --cascivo-motion-exit
+
+Accessibility: role "alert", WCAG 2.2-AA. Keep it AA.
+
+Do not change (strict): role mapping — warning/error must use role="alert"; info/success use role="status"
+Flexible: icon, actions.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/number-input.md

@@ -0,0 +1,117 @@
+# NumberInput
+
+**Category:** inputs  
+**Description:** Numeric input with stepper buttons, clamping, precision, and locale formatting
+
+## When to use
+
+- Collecting a bounded numeric value where increment/decrement by a known step is natural (quantity, opacity, count)
+- Numeric entry that needs clamping to min/max, fixed precision, or locale-aware display formatting (e.g. currency)
+- Inputs where keyboard ArrowUp/ArrowDown stepping speeds up adjustment
+
+## When NOT to use
+
+- Free-form or non-numeric text — use Input
+- Choosing along a continuous range where the exact number matters less than the relative position — use Slider
+- Phone numbers, PINs, or codes that are digit strings rather than quantities — use Input or OtpInput
+
+## Anti-patterns
+
+### NumberInput adds stepper buttons, clamping, precision rounding, and Intl formatting that a raw number input does not, and reports a parsed number | null rather than a string
+
+**Bad:** `<Input type="number" onChange={...} />`  
+**Good:** `<NumberInput min={0} max={99} step={1} onChange={...} />`  
+**Why:** NumberInput adds stepper buttons, clamping, precision rounding, and Intl formatting that a raw number input does not, and reports a parsed number | null rather than a string
+
+## Related components
+
+- **Input** (alternative): Use for unbounded or non-numeric text entry
+- **Slider** (alternative): Use when approximate position on a range matters more than an exact typed number
+
+## Accessibility rationale
+
+Exposes role="spinbutton" with aria-valuenow/min/max so assistive tech announces the current value and bounds; stepper buttons are taken out of the tab order (tabIndex=-1) and labeled, keeping keyboard focus on the field while ArrowUp/ArrowDown drive stepping.
+
+## Props
+
+| Name             | Type                              | Required | Default   | Description                                                             |
+| ---------------- | --------------------------------- | -------- | --------- | ----------------------------------------------------------------------- |
+| `value`          | `number \| null`                  | No       | —         | The controlled value.                                                   |
+| `defaultValue`   | `number`                          | No       | —         | The initial value when uncontrolled.                                    |
+| `onChange`       | `(value: number \| null) => void` | No       | —         | Fired on commit (blur, Enter, stepping); null when empty or unparseable |
+| `min`            | `number`                          | No       | —         | Minimum allowed value.                                                  |
+| `max`            | `number`                          | No       | —         | Maximum allowed value.                                                  |
+| `step`           | `number`                          | No       | 1         | Increment between allowed values.                                       |
+| `precision`      | `number`                          | No       | —         | Decimal places applied on commit                                        |
+| `formatOptions`  | `Intl.NumberFormatOptions`        | No       | —         | Display formatting applied on blur; raw editable string while focused   |
+| `label`          | `string`                          | No       | —         | Text label for the control.                                             |
+| `hint`           | `string`                          | No       | —         | Supplementary hint text shown with the control.                         |
+| `error`          | `string`                          | No       | —         | Error message shown when the value is invalid.                          |
+| `size`           | `'sm' \| 'md' \| 'lg'`            | No       | md        | Visual size of the component (e.g. 'sm', 'md', 'lg').                   |
+| `disabled`       | `boolean`                         | No       | false     | When true, disables the control and removes it from the tab order.      |
+| `incrementLabel` | `string`                          | No       | Increment | Accessible label for the increment button.                              |
+| `decrementLabel` | `string`                          | No       | Decrement | Accessible label for the decrement button.                              |
+
+## Tokens
+
+- `--cascivo-color-surface`
+- `--cascivo-color-border`
+- `--cascivo-color-accent`
+- `--cascivo-color-destructive`
+- `--cascivo-color-bg-subtle`
+- `--cascivo-color-text-subtle`
+- `--cascivo-radius-input`
+- `--cascivo-focus-ring`
+
+## Examples
+
+### Basic
+
+```jsx
+<NumberInput label="Quantity" defaultValue={1} min={0} max={99} />
+```
+
+### Currency
+
+```jsx
+<NumberInput label="Price" precision={2} formatOptions={{ style: 'currency', currency: 'USD' }} />
+```
+
+### Stepped
+
+```jsx
+<NumberInput label="Opacity" min={0} max={1} step={0.1} />
+```
+
+## Boundaries
+
+| Area                  | Level    | Note                                                                           |
+| --------------------- | -------- | ------------------------------------------------------------------------------ |
+| token names           | strict   | Visual props must resolve to the listed --cascivo-\* semantic tokens           |
+| formatting and bounds | flexible | min, max, step, precision, and formatOptions are free to suit the value domain |
+| stepper labels        | flexible | incrementLabel/decrementLabel override the i18n defaults                       |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo NumberInput component (inputs). Numeric input with stepper buttons, clamping, precision, and locale formatting
+
+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).
+
+NumberInput 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-destructive, --cascivo-color-bg-subtle, --cascivo-color-text-subtle, --cascivo-radius-input, --cascivo-focus-ring
+
+Accessibility: role "spinbutton", WCAG 2.2-AA, keyboard: ArrowUp/ArrowDown/Enter/Tab. Keep it AA.
+
+Do not change (strict): token names — Visual props must resolve to the listed --cascivo-* semantic tokens
+Flexible: formatting and bounds, stepper labels.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/otp-input.md

@@ -0,0 +1,98 @@
+# OtpInput
+
+**Category:** inputs  
+**Description:** Segmented one-time code input
+
+## When to use
+
+- Entering a fixed-length one-time code (2FA, SMS verification, email confirmation) split across per-character slots
+- Codes that benefit from auto-advance between slots and pasting the full code at once
+- Numeric or alphanumeric short codes of a known length
+
+## When NOT to use
+
+- Variable-length or free-form text — use Input
+- Secret credentials that should be masked — use PasswordInput
+- Long codes where per-character boxes add no value over a single field — use Input
+
+## Anti-patterns
+
+### OtpInput gives per-digit slots with auto-advance, backspace-to-previous, full-code paste handling, and autoComplete="one-time-code" that a single Input does not
+
+**Bad:** `<Input maxLength={6} placeholder="Enter code" />`  
+**Good:** `<OtpInput length={6} value={code} onValueChange={setCode} />`  
+**Why:** OtpInput gives per-digit slots with auto-advance, backspace-to-previous, full-code paste handling, and autoComplete="one-time-code" that a single Input does not
+
+## Related components
+
+- **Input** (alternative): Use for variable-length or non-code text entry
+- **PasswordInput** (alternative): Use when the entered value is a secret that must be masked
+
+## Accessibility rationale
+
+Wraps the slots in role="group" with a localized aria-label and labels each slot with its position so screen readers announce which digit is being entered; the first slot carries autoComplete="one-time-code" so platform SMS autofill can populate the code.
+
+## Props
+
+| Name            | Type                          | Required | Default | Description                                                        |
+| --------------- | ----------------------------- | -------- | ------- | ------------------------------------------------------------------ |
+| `length`        | `number`                      | No       | 6       | Number of input cells.                                             |
+| `value`         | `string`                      | Yes      | —       | The controlled value.                                              |
+| `onValueChange` | `(v: string) => void`         | Yes      | —       | Called with the new value when it changes.                         |
+| `disabled`      | `boolean`                     | No       | false   | When true, disables the control and removes it from the tab order. |
+| `type`          | `'numeric' \| 'alphanumeric'` | No       | numeric | Accepted characters ('numeric' \| 'alphanumeric').                 |
+
+## Tokens
+
+- `--cascivo-color-surface`
+- `--cascivo-color-border`
+- `--cascivo-color-accent`
+- `--cascivo-color-bg-subtle`
+- `--cascivo-radius-input`
+- `--cascivo-focus-ring`
+
+## Examples
+
+### Basic
+
+```jsx
+<OtpInput value="" onValueChange={() => {}} />
+```
+
+### 4-digit
+
+```jsx
+<OtpInput length={4} value="" onValueChange={() => {}} />
+```
+
+## Boundaries
+
+| Area            | Level    | Note                                                                          |
+| --------------- | -------- | ----------------------------------------------------------------------------- |
+| token names     | strict   | Slot styling must resolve to the listed --cascivo-\* tokens                   |
+| length and type | flexible | length and numeric/alphanumeric type are free to match the issued code format |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo OtpInput component (inputs). Segmented one-time code input
+
+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).
+
+OtpInput 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-bg-subtle, --cascivo-radius-input, --cascivo-focus-ring
+
+Accessibility: role "group", WCAG 2.2-AA, keyboard: ArrowLeft/ArrowRight/Backspace. Keep it AA.
+
+Do not change (strict): token names — Slot styling must resolve to the listed --cascivo-* tokens
+Flexible: length and type.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/overflow-menu.md

@@ -0,0 +1,107 @@
+# OverflowMenu
+
+**Category:** overlay  
+**Description:** Kebab icon button revealing a menu of row-level actions
+
+## When to use
+
+- Collapsing secondary row-level or item-level actions behind a kebab trigger in dense layouts like tables and lists
+- Offering a small set of actions where a destructive option needs visual distinction
+
+## When NOT to use
+
+- A primary action that should always be visible — use Button
+- Selecting a single value from a set rather than triggering actions — use Select or Dropdown
+- New code — this component is deprecated in favor of Menu
+
+## Anti-patterns
+
+### A kebab menu keeps dense rows scannable; surfacing every action inline competes for attention and breaks alignment
+
+**Bad:** `Rendering every row action as a visible Button in a crowded table`  
+**Good:** `<OverflowMenu items={[{ label: "Edit", value: "edit" }, { label: "Delete", value: "delete", destructive: true }]} onSelect={handle} />`  
+**Why:** A kebab menu keeps dense rows scannable; surfacing every action inline competes for attention and breaks alignment
+
+## Related components
+
+- **Menu** (alternative): Preferred replacement; OverflowMenu is deprecated and delegates to Dropdown internally
+- **Dropdown** (contains): OverflowMenu is a kebab-triggered wrapper around Dropdown
+- **Button** (alternative): Use for a single always-visible action instead of hiding it in a menu
+
+## Accessibility rationale
+
+The kebab trigger carries a localized aria-label since it has no visible text, and the revealed list uses Dropdown's menu semantics so arrow keys, Home/End, Enter/Space, and Escape work without custom handling.
+
+## Props
+
+| Name        | Type                                                                                              | Required | Default      | Description                                                        |
+| ----------- | ------------------------------------------------------------------------------------------------- | -------- | ------------ | ------------------------------------------------------------------ |
+| `items`     | `{ label: string; value: string; icon?: ReactNode; disabled?: boolean; destructive?: boolean }[]` | Yes      | —            | The items to render.                                               |
+| `onSelect`  | `(value: string) => void`                                                                         | No       | —            | Called with the selected value.                                    |
+| `placement` | `'bottom-start' \| 'bottom-end'`                                                                  | No       | bottom-end   | Placement relative to the trigger.                                 |
+| `ariaLabel` | `string`                                                                                          | No       | More actions | Accessible label for the component.                                |
+| `size`      | `'sm' \| 'md'`                                                                                    | No       | md           | Visual size of the component (e.g. 'sm', 'md', 'lg').              |
+| `disabled`  | `boolean`                                                                                         | No       | false        | When true, disables the control and removes it from the tab order. |
+| `className` | `string`                                                                                          | No       | —            | Additional CSS class names merged onto the root element.           |
+
+## Tokens
+
+- `--cascivo-color-text`
+- `--cascivo-color-text-muted`
+- `--cascivo-color-bg-subtle`
+- `--cascivo-color-destructive`
+- `--cascivo-color-destructive-subtle`
+- `--cascivo-radius-button`
+- `--cascivo-focus-ring`
+
+## Examples
+
+### Row actions
+
+```jsx
+<OverflowMenu
+  items={[
+    { label: 'Edit', value: 'edit' },
+    { label: 'Delete', value: 'delete', destructive: true },
+  ]}
+  onSelect={handle}
+/>
+```
+
+### Small, start-aligned
+
+```jsx
+<OverflowMenu size="sm" placement="bottom-start" items={items} />
+```
+
+## Boundaries
+
+| Area                | Level    | Note                                                                    |
+| ------------------- | -------- | ----------------------------------------------------------------------- |
+| token names         | strict   | Trigger and item styling must resolve to the listed --cascivo-\* tokens |
+| item set and labels | flexible | items, ariaLabel, and placement are free to suit the context            |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo OverflowMenu component (overlay). Kebab icon button revealing a menu of row-level 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).
+
+OverflowMenu is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-text, --cascivo-color-text-muted, --cascivo-color-bg-subtle, --cascivo-color-destructive, --cascivo-color-destructive-subtle, --cascivo-radius-button, --cascivo-focus-ring
+
+Accessibility: role "menu", WCAG 2.2-AA, keyboard: ArrowDown/ArrowUp/Home/End/Enter/Space/Escape. Keep it AA.
+
+Do not change (strict): token names — Trigger and item styling must resolve to the listed --cascivo-* tokens
+Flexible: item set and labels.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/pagination.md

@@ -0,0 +1,123 @@
+# Pagination
+
+**Category:** navigation  
+**Description:** Controls for navigating paged data sets, with page size selection
+
+## When to use
+
+- Navigating between pages of a paged dataset
+- Letting the user change how many items appear per page (onPageSizeChange)
+- Pairing with a table or list that loads data in chunks
+
+## When NOT to use
+
+- Navigating a content hierarchy — use Breadcrumb
+- Infinite scroll experiences where pages are not exposed
+
+## Anti-patterns
+
+### Pagination semantics imply sequential pages of one dataset, not arbitrary navigation
+
+**Bad:** `Using Pagination to navigate between unrelated app sections`  
+**Good:** `<Tabs> or nav links for section switching`  
+**Why:** Pagination semantics imply sequential pages of one dataset, not arbitrary navigation
+
+## Related components
+
+- **DataTable** (pairs-with): DataTable embeds Pagination for its rows
+- **Breadcrumb** (alternative): Breadcrumb is for hierarchy, Pagination for sequential pages
+
+## Accessibility rationale
+
+Wrapped in <nav> with an accessible label; page controls are real buttons with current-page state exposed, and all visible/assistive strings are overridable via labels for i18n
+
+## Props
+
+| Name               | Type                     | Required | Default           | Description                                                     |
+| ------------------ | ------------------------ | -------- | ----------------- | --------------------------------------------------------------- |
+| `page`             | `number`                 | Yes      | —                 | Current page (1-based)                                          |
+| `pageSize`         | `number`                 | Yes      | —                 | Items per page                                                  |
+| `totalItems`       | `number`                 | Yes      | —                 | Total number of items                                           |
+| `onPageChange`     | `(page: number) => void` | Yes      | —                 | Called with the new page number when it changes.                |
+| `onPageSizeChange` | `(size: number) => void` | No       | —                 | Called with the new page size when it changes.                  |
+| `pageSizeOptions`  | `number[]`               | No       | [10, 25, 50, 100] | Options for the page size select                                |
+| `labels`           | `PaginationLabels`       | No       | —                 | Overridable English strings for all visible and accessible text |
+| `className`        | `string`                 | No       | —                 | Additional CSS class names merged onto the root element.        |
+
+## Tokens
+
+- `--cascivo-color-text`
+- `--cascivo-color-text-muted`
+- `--cascivo-color-surface`
+- `--cascivo-color-border`
+- `--cascivo-color-border-strong`
+- `--cascivo-color-bg-subtle`
+- `--cascivo-color-accent`
+- `--cascivo-color-accent-subtle`
+- `--cascivo-radius-input`
+- `--cascivo-radius-button`
+- `--cascivo-focus-ring`
+
+## Examples
+
+### Basic
+
+```jsx
+<Pagination page={1} pageSize={25} totalItems={103} onPageChange={setPage} />
+```
+
+### With page size select
+
+```jsx
+<Pagination
+  page={page}
+  pageSize={size}
+  totalItems={103}
+  onPageChange={setPage}
+  onPageSizeChange={setSize}
+/>
+```
+
+### Custom labels
+
+```jsx
+<Pagination
+  page={1}
+  pageSize={10}
+  totalItems={42}
+  onPageChange={setPage}
+  labels={{ previous: 'Zurück', next: 'Weiter' }}
+/>
+```
+
+## Boundaries
+
+| Area              | Level    | Note                                                              |
+| ----------------- | -------- | ----------------------------------------------------------------- |
+| page size options | flexible | pageSizeOptions and the size select are optional                  |
+| token names       | strict   | Surfaces, borders, and accent 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 Pagination component (navigation). Controls for navigating paged data sets, with page size selection
+
+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).
+
+Pagination is strictly bound to these tokens — use only these, do not invent token names:
+  --cascivo-color-text, --cascivo-color-text-muted, --cascivo-color-surface, --cascivo-color-border, --cascivo-color-border-strong, --cascivo-color-bg-subtle, --cascivo-color-accent, --cascivo-color-accent-subtle, --cascivo-radius-input, --cascivo-radius-button, --cascivo-focus-ring
+
+Accessibility: role "navigation", WCAG 2.2-AA, keyboard: Tab/Enter/Space/ArrowUp/ArrowDown. Keep it AA.
+
+Do not change (strict): token names — Surfaces, borders, and accent must resolve to --cascivo-* tokens
+Flexible: page size options.
+
+Do not invent props, tokens, or global viewport media queries.
+```

package/dist/context/password-input.md

@@ -0,0 +1,100 @@
+# PasswordInput
+
+**Category:** inputs  
+**Description:** Password input with reveal toggle and optional strength meter
+
+## When to use
+
+- Collecting a secret credential that should be masked by default with an opt-in reveal toggle
+- Password creation flows that benefit from inline strength feedback
+
+## When NOT to use
+
+- Non-secret text — use Input
+- A fixed-length one-time verification code — use OtpInput
+
+## Anti-patterns
+
+### PasswordInput adds an accessible reveal/hide toggle and an optional strength meter on top of the masked field, which a raw password input lacks
+
+**Bad:** `<Input type="password" />`  
+**Good:** `<PasswordInput showStrengthMeter />`  
+**Why:** PasswordInput adds an accessible reveal/hide toggle and an optional strength meter on top of the masked field, which a raw password input lacks
+
+## Related components
+
+- **Input** (alternative): Use for non-secret text that never needs masking
+- **OtpInput** (alternative): Use for fixed-length one-time codes rather than passwords
+
+## Accessibility rationale
+
+The reveal control is a real <button> whose aria-label switches between reveal/hide so screen-reader users know the current masking state; toggling swaps the input type between password and text so the platform handles masking natively.
+
+## Props
+
+| Name                | Type                                               | Required | Default | Description                                                        |
+| ------------------- | -------------------------------------------------- | -------- | ------- | ------------------------------------------------------------------ |
+| `showStrengthMeter` | `boolean`                                          | No       | false   | When true, shows a password-strength meter.                        |
+| `size`              | `'sm' \| 'md' \| 'lg'`                             | No       | md      | Visual size of the component (e.g. 'sm', 'md', 'lg').              |
+| `labels`            | `PasswordInputLabels`                              | No       | —       | Overrides for the component’s user-visible strings (i18n).         |
+| `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.                    |
+| `value`             | `string`                                           | No       | —       | The controlled value.                                              |
+| `onChange`          | `(e: React.ChangeEvent<HTMLInputElement>) => void` | No       | —       | Called when the value changes.                                     |
+
+## Tokens
+
+- `--cascivo-color-surface`
+- `--cascivo-color-border`
+- `--cascivo-color-accent`
+- `--cascivo-color-destructive`
+- `--cascivo-color-warning`
+- `--cascivo-color-success`
+- `--cascivo-radius-input`
+- `--cascivo-focus-ring`
+
+## Examples
+
+### Basic
+
+```jsx
+<PasswordInput placeholder="Enter password" />
+```
+
+### With strength meter
+
+```jsx
+<PasswordInput showStrengthMeter placeholder="Create password" />
+```
+
+## Boundaries
+
+| Area        | Level    | Note                                                                                     |
+| ----------- | -------- | ---------------------------------------------------------------------------------------- |
+| token names | strict   | Field, toggle, and strength-meter styling must resolve to the listed --cascivo-\* tokens |
+| labels      | flexible | reveal, hide, and strengthLabel can be overridden via the labels prop                    |
+
+## AI context prompt
+
+Copy this into an LLM context bar before editing this component:
+
+```text
+I am modifying the cascivo PasswordInput component (inputs). Password input with reveal toggle and optional strength meter
+
+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).
+
+PasswordInput 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-destructive, --cascivo-color-warning, --cascivo-color-success, --cascivo-radius-input, --cascivo-focus-ring
+
+Accessibility: role "textbox", WCAG 2.2-AA, keyboard: Tab/Shift+Tab. Keep it AA.
+
+Do not change (strict): token names — Field, toggle, and strength-meter styling must resolve to the listed --cascivo-* tokens
+Flexible: labels.
+
+Do not invent props, tokens, or global viewport media queries.
+```