@chromvoid/headless-ui 0.1.0

package/specs/components/tabs.md

@@ -0,0 +1,265 @@
+# Tabs Component Contract
+
+## Purpose
+
+`Tabs` provides a headless APG-aligned tablist/tab/tabpanel model.
+
+It handles active tab focus, selected tab activation,
+orientation-aware keyboard navigation, and panel linkage contracts.
+
+## Component Files
+
+- `src/tabs/index.ts` - model and public `createTabs` API
+- `src/tabs/tabs.test.ts` - unit behavior tests
+
+## Public API
+
+- `createTabs(options): TabsModel`
+- `state` (signal-backed): `activeTabId()`, `selectedTabId()`
+- `actions`:
+  - `setActive`, `select`
+  - `moveNext`, `movePrev`, `moveFirst`, `moveLast`
+  - `handleKeyDown`
+- `contracts`:
+  - `getTabListProps()`
+  - `getTabProps(id)`
+  - `getPanelProps(id)`
+
+## Options (`CreateTabsOptions`)
+
+| Option                 | Type                         | Default                              | Description                                                                                    |
+| ---------------------- | ---------------------------- | ------------------------------------ | ---------------------------------------------------------------------------------------------- |
+| `tabs`                 | `readonly TabItem[]`         | required                             | Tab definitions. Each `TabItem` has `id: string` and optional `disabled?: boolean`.            |
+| `idBase`               | `string`                     | `'tabs'`                             | Prefix for generated DOM ids (`{idBase}-tablist`, `{idBase}-tab-{id}`, `{idBase}-panel-{id}`). |
+| `ariaLabel`            | `string \| undefined`        | `undefined`                          | Optional `aria-label` for the tablist element.                                                 |
+| `orientation`          | `'horizontal' \| 'vertical'` | `'horizontal'`                       | Determines keyboard navigation axis and `aria-orientation` value.                              |
+| `activationMode`       | `'automatic' \| 'manual'`    | `'automatic'`                        | Whether navigation also selects (`automatic`) or only Enter/Space selects (`manual`).          |
+| `initialActiveTabId`   | `string \| null`             | falls back to `initialSelectedTabId` | Initial roving-focus tab. Normalized to first enabled tab if invalid or disabled.              |
+| `initialSelectedTabId` | `string \| null`             | first enabled tab                    | Initial selected tab. Normalized to first enabled tab if invalid or disabled.                  |
+
+### Initial State Resolution
+
+1. `initialSelectedTabId` is resolved: if the candidate is a valid enabled tab id, use it; otherwise fall back to the first enabled tab id, or `null` if no enabled tabs exist.
+2. `initialActiveTabId` is resolved: if provided, apply the same validation; if not provided, default to the resolved `initialSelectedTabId`.
+3. If `selectedTabId` resolves to `null` but `activeTabId` is non-null, `selectedTabId` is set to `activeTabId`.
+
+## Reactive State Contract
+
+Headless Tabs exposes state as reactive signal-backed getters.
+
+### State Surface
+
+- `state.activeTabId(): string | null`
+  - Current roving-focus tab id.
+  - Changes on directional navigation, `setActive`, and `select`.
+- `state.selectedTabId(): string | null`
+  - Current selected/visible panel tab id.
+  - Changes on `select`, on `setActive` in `automatic` mode, and on navigation in `automatic` mode.
+
+### Reactivity Guarantees
+
+- `state` values are read via getter calls (`Atom<string | null>`) and are suitable as reactive dependencies in adapters.
+- Any state change MUST be observable synchronously by adapters after action execution.
+- Adapters MUST treat `state` as source of truth; DOM flags are derived outputs.
+
+## Actions
+
+### `setActive(id: string | null)`
+
+- If `id` is `null`, sets `activeTabId` to `null`.
+- If `id` is a valid enabled tab, sets `activeTabId` to `id`.
+- In `automatic` mode, also updates `selectedTabId` to match `activeTabId`.
+- If `id` is disabled or unknown, no state change.
+
+### `select(id: string)`
+
+- If `id` is a valid enabled tab, sets both `activeTabId` and `selectedTabId` to `id`.
+- If `id` is disabled or unknown, no state change.
+
+### `moveNext()` / `movePrev()`
+
+- Moves `activeTabId` to the next/previous enabled tab in circular (wrapping) order.
+- If no enabled tabs exist, sets `activeTabId` to `null`.
+- If `activeTabId` is currently `null` or invalid, resets to the first enabled tab.
+- In `automatic` mode, also updates `selectedTabId`.
+
+### `moveFirst()` / `moveLast()`
+
+- Sets `activeTabId` to the first/last enabled tab, or `null` if none exist.
+- In `automatic` mode, also updates `selectedTabId`.
+
+### `handleKeyDown(event)`
+
+- Accepts `Pick<KeyboardEvent, 'key' | 'shiftKey' | 'ctrlKey' | 'metaKey' | 'altKey'>`.
+- Maps keys through `mapListboxKeyboardIntent` with `orientation`, `selectionMode: 'single'`, `rangeSelectionEnabled: false`.
+- Intent mapping:
+  - `NAV_NEXT` -> `moveNext()`
+  - `NAV_PREV` -> `movePrev()`
+  - `NAV_FIRST` -> `moveFirst()`
+  - `NAV_LAST` -> `moveLast()`
+  - `ACTIVATE` / `TOGGLE_SELECTION` -> `select(activeTabId)` (if `activeTabId` is non-null)
+- Unrecognized keys produce no state change.
+
+## Transitions Table
+
+| Event / Action                               | `activeTabId`                       | `selectedTabId`                                             |
+| -------------------------------------------- | ----------------------------------- | ----------------------------------------------------------- |
+| `setActive(id)` where id is enabled          | set to `id`                         | set to `id` if `automatic`; unchanged if `manual`           |
+| `setActive(null)`                            | set to `null`                       | unchanged                                                   |
+| `setActive(id)` where id is disabled/unknown | unchanged                           | unchanged                                                   |
+| `select(id)` where id is enabled             | set to `id`                         | set to `id`                                                 |
+| `select(id)` where id is disabled/unknown    | unchanged                           | unchanged                                                   |
+| `moveNext()` / `movePrev()`                  | next/prev enabled (wrapping)        | follows `activeTabId` if `automatic`; unchanged if `manual` |
+| `moveFirst()` / `moveLast()`                 | first/last enabled                  | follows `activeTabId` if `automatic`; unchanged if `manual` |
+| `handleKeyDown` (arrow key)                  | delegates to `moveNext`/`movePrev`  | per activation mode                                         |
+| `handleKeyDown` (Home/End)                   | delegates to `moveFirst`/`moveLast` | per activation mode                                         |
+| `handleKeyDown` (Enter/Space)                | unchanged                           | set to `activeTabId` (via `select`)                         |
+| `handleKeyDown` (unrecognized key)           | unchanged                           | unchanged                                                   |
+
+## Contracts
+
+Contracts return ready-to-spread ARIA attribute maps.
+
+### `getTabListProps(): TabListProps`
+
+```ts
+interface TabListProps {
+  id: string // '{idBase}-tablist'
+  role: 'tablist'
+  'aria-orientation': 'horizontal' | 'vertical'
+  'aria-label'?: string // from options.ariaLabel
+}
+```
+
+### `getTabProps(id: string): TabProps`
+
+Throws `Error` if `id` is not a known tab.
+
+```ts
+interface TabProps {
+  id: string // '{idBase}-tab-{id}'
+  role: 'tab'
+  tabindex: '0' | '-1' // '0' if active, '-1' otherwise
+  'aria-selected': 'true' | 'false' // 'true' if selected
+  'aria-controls': string // '{idBase}-panel-{id}'
+  'aria-disabled'?: 'true' // present only when tab is disabled
+  'data-active': 'true' | 'false' // matches activeTabId
+  'data-selected': 'true' | 'false' // matches selectedTabId
+}
+```
+
+### `getPanelProps(id: string): TabPanelProps`
+
+Throws `Error` if `id` is not a known tab.
+
+```ts
+interface TabPanelProps {
+  id: string // '{idBase}-panel-{id}'
+  role: 'tabpanel'
+  tabindex: '0' | '-1' // '0' if selected, '-1' otherwise
+  'aria-labelledby': string // '{idBase}-tab-{id}'
+  hidden: boolean // true if not selected
+}
+```
+
+## APG and A11y Contract
+
+- tablist role: `tablist`
+- tab role: `tab`
+- panel role: `tabpanel`
+- tablist exposes `aria-orientation`
+- tablist optionally exposes `aria-label`
+- each tab exposes `aria-controls` pointing to its panel id
+- each panel exposes `aria-labelledby` pointing to its tab id
+- roving tabindex: active tab has `tabindex="0"`, all others `tabindex="-1"`
+- selected tab has `aria-selected="true"`, all others `aria-selected="false"`
+- disabled tabs expose `aria-disabled="true"`
+
+## Activation Modes
+
+- `automatic`:
+  - moving active tab (via navigation or `setActive`) also updates selected tab
+- `manual`:
+  - active tab changes on navigation and `setActive`
+  - selected tab changes only on `select` or activation keys (`Enter` / `Space`)
+
+## Keyboard Contract
+
+- Orientation-aware navigation: `ArrowRight`/`ArrowLeft` for horizontal, `ArrowDown`/`ArrowUp` for vertical
+- `Home`/`End` for first/last tab
+- Activation via `Enter` or `Space`
+- Disabled tabs are skipped by navigation and cannot be selected
+- Navigation wraps circularly (last -> first, first -> last)
+
+## Invariants
+
+1. `activeTabId` is `null` or an enabled tab id.
+2. `selectedTabId` is `null` or an enabled tab id.
+3. Selected panel visibility derives only from `selectedTabId`.
+4. State transitions never select or activate disabled tabs.
+5. Navigation wraps circularly through enabled tabs only.
+6. `getTabProps` and `getPanelProps` throw for unknown tab ids.
+7. When all tabs are disabled, both `activeTabId` and `selectedTabId` are `null` and all actions are no-ops.
+
+## Adapter Expectations
+
+This section lists exactly what the UIKit adapter layer binds to.
+
+### Signals Read
+
+| Signal                  | UIKit Usage                                                                                                                                      |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `state.activeTabId()`   | Determines roving tabindex; drives `data-active` attribute on tab elements; used for focus management.                                           |
+| `state.selectedTabId()` | Determines `aria-selected` on tabs; drives panel visibility (`hidden`); drives `data-selected` attribute; used for active indicator positioning. |
+
+### Actions Called
+
+| Action                       | UIKit Trigger                                                    |
+| ---------------------------- | ---------------------------------------------------------------- |
+| `setActive(id)`              | Tab receives focus (e.g., pointer click on a tab).               |
+| `select(id)`                 | Tab is clicked or tapped (pointer activation).                   |
+| `handleKeyDown(event)`       | `keydown` event on the tablist or individual tab.                |
+| `moveNext()` / `movePrev()`  | Not called directly by UIKit; delegated through `handleKeyDown`. |
+| `moveFirst()` / `moveLast()` | Not called directly by UIKit; delegated through `handleKeyDown`. |
+
+### Contracts Spread
+
+| Contract            | UIKit Target                               |
+| ------------------- | ------------------------------------------ |
+| `getTabListProps()` | Spread onto the tablist container element. |
+| `getTabProps(id)`   | Spread onto each tab trigger element.      |
+| `getPanelProps(id)` | Spread onto each tab panel element.        |
+
+### UIKit-Only Concerns (Not in Headless)
+
+- **Active indicator animation**: Positioned and animated at the UIKit layer using `selectedTabId` to determine which tab to highlight.
+- **Closable tabs**: Close button rendering and close orchestration are UIKit concerns. Headless handles selection fallback implicitly through model rebuild with an updated tab list (without the closed tab).
+- **`input` / `change` events**: Custom DOM events dispatched by the UIKit wrapper, not part of the headless model.
+
+## Minimum Test Matrix
+
+- automatic activation behavior
+- manual activation behavior
+- Home/End behavior
+- disabled-tab skip and rejection behavior
+- vertical orientation behavior
+- aria linkage integrity (`aria-controls`, `aria-labelledby`)
+- initial state resolution (invalid/disabled initial ids)
+- all-disabled edge case (null-safe behavior)
+- wrapping navigation
+- unsupported key no-op behavior
+- `setActive` auto-activation in automatic mode
+
+## ADR-001 Compliance
+
+- **Runtime Policy**: Reatom v1000 only; no @statx/\* in headless core.
+- **Layering**: core -> interactions -> a11y-contracts -> adapters; adapters remain thin mappings.
+- **Independence**: No imports from @project/_, apps/_, or other out-of-package modules.
+- **Verification**: Mandatory adapter integration tests and standalone package test execution.
+
+## Out of Scope (Current)
+
+- dynamic tab insertion/removal orchestration
+- lazy panel mount orchestration
+
+**Note on closable tabs**: Close orchestration (close button, remove animation, user confirmation) is a UIKit-layer concern. Headless handles selection fallback implicitly through model rebuild with an updated tab list (i.e., the adapter recreates the model without the closed tab, and initial state resolution picks the appropriate fallback).

package/specs/components/textarea.md

@@ -0,0 +1,185 @@
+# Textarea Component Contract
+
+## Purpose
+
+`Textarea` is a headless contract for a native multi-line text field. It manages value, disabled/readonly/required semantics, placeholder, geometry (`rows`, `cols`), length constraints, resize mode, and focus tracking. It provides ready-to-spread ARIA and native attribute maps for the underlying `<textarea>` element.
+
+## Component Files
+
+- `src/textarea/index.ts` - model and public `createTextarea` API
+- `src/textarea/textarea.test.ts` - unit behavior tests
+
+## Public API
+
+- `createTextarea(options)`
+  - `options`:
+    - `idBase?`: `string` - base for generated IDs (default: `"textarea"`)
+    - `value?`: `string` - initial value (default: `""`)
+    - `disabled?`: `boolean` - initial disabled state (default: `false`)
+    - `readonly?`: `boolean` - initial readonly state (default: `false`)
+    - `required?`: `boolean` - initial required state (default: `false`)
+    - `placeholder?`: `string` - initial placeholder text (default: `""`)
+    - `rows?`: `number` - visible text rows (default: `4`)
+    - `cols?`: `number` - visible text columns (default: `20`)
+    - `minLength?`: `number` - minimum text length, omitted when unset
+    - `maxLength?`: `number` - maximum text length, omitted when unset
+    - `resize?`: `TextareaResize` - resize mode (default: `"vertical"`)
+    - `onInput?`: `(value: string) => void` - callback on user input (`handleInput`)
+- **Types**:
+  - `TextareaResize = "none" | "vertical"`
+- `state` (signal-backed):
+  - `value()`: `string` - current value
+  - `disabled()`: `boolean` - whether field is disabled
+  - `readonly()`: `boolean` - whether field is readonly
+  - `required()`: `boolean` - whether field is required
+  - `placeholder()`: `string` - placeholder text
+  - `rows()`: `number` - visible text rows
+  - `cols()`: `number` - visible text columns
+  - `minLength()`: `number | undefined` - min length constraint
+  - `maxLength()`: `number | undefined` - max length constraint
+  - `resize()`: `TextareaResize` - resize mode
+  - `focused()`: `boolean` - focus state
+  - `filled()`: `boolean` - **derived**: `value.length > 0`
+- `actions`:
+  - `setValue(value: string)`: updates value programmatically
+  - `setDisabled(disabled: boolean)`: updates disabled state
+  - `setReadonly(readonly: boolean)`: updates readonly state
+  - `setRequired(required: boolean)`: updates required state
+  - `setPlaceholder(placeholder: string)`: updates placeholder
+  - `setRows(rows: number | undefined)`: updates row count when valid positive integer
+  - `setCols(cols: number | undefined)`: updates col count when valid positive integer
+  - `setMinLength(minLength: number | undefined)`: updates minimum length constraint
+  - `setMaxLength(maxLength: number | undefined)`: updates maximum length constraint
+  - `setResize(resize: TextareaResize)`: updates resize mode
+  - `setFocused(focused: boolean)`: updates focus state
+  - `handleInput(value: string)`: processes user input; no-op when disabled/readonly; invokes `onInput`
+- `contracts`:
+  - `getTextareaProps()`: returns complete attribute map for native `<textarea>`
+
+## APG and A11y Contract
+
+### Native `<textarea>` element
+
+- `id`: `"{idBase}-textarea"`
+- `aria-disabled`: `"true"` when disabled, otherwise omitted
+- `aria-readonly`: `"true"` when readonly, otherwise omitted
+- `aria-required`: `"true"` when required, otherwise omitted
+- `disabled`: `true` when disabled (native form behavior)
+- `readonly`: `true` when readonly (focusable, non-editable)
+- `required`: `true` when required (native constraint validation)
+- `placeholder`: current placeholder value, omitted when empty
+- `tabindex`: `"0"` when interactive, `"-1"` when disabled
+- `rows`: current rows value
+- `cols`: current cols value
+- `minlength`: `minLength` when set
+- `maxlength`: `maxLength` when set
+
+Note: role is not set explicitly. Native `<textarea>` semantics are used.
+
+## Behavior Contract
+
+### Value management
+
+- `setValue(v)` always updates `state.value` (programmatic/controlled path).
+- `handleInput(v)` updates `state.value` only when interactive and invokes `onInput(v)`.
+
+### Disabled and readonly
+
+- A disabled or readonly textarea ignores `handleInput(v)`.
+- Disabled uses `tabindex="-1"`; readonly remains `tabindex="0"`.
+
+### Geometry and constraints
+
+- `rows` and `cols` accept positive finite integers only.
+- `minLength` and `maxLength` accept non-negative finite integers or `undefined`.
+- `resize` is constrained to `"none" | "vertical"`.
+
+### Focus management
+
+- `setFocused(true)` / `setFocused(false)` reflects native focus/blur.
+
+## Transitions Table
+
+| Event / Action      | Guard                                    | Effect                       | Next State        |
+| ------------------- | ---------------------------------------- | ---------------------------- | ----------------- | --- | --------- |
+| `handleInput(v)`    | `!disabled && !readonly`                 | set value, call `onInput(v)` | `value = v`       |
+| `handleInput(v)`    | `disabled                                |                              | readonly`         | --  | no change |
+| `setValue(v)`       | --                                       | set value                    | `value = v`       |
+| `setDisabled(d)`    | --                                       | set disabled                 | `disabled = d`    |
+| `setReadonly(r)`    | --                                       | set readonly                 | `readonly = r`    |
+| `setRequired(r)`    | --                                       | set required                 | `required = r`    |
+| `setPlaceholder(p)` | --                                       | set placeholder              | `placeholder = p` |
+| `setRows(n)`        | `n` is positive integer                  | set rows                     | `rows = n`        |
+| `setRows(n)`        | invalid `n`                              | --                           | no change         |
+| `setCols(n)`        | `n` is positive integer                  | set cols                     | `cols = n`        |
+| `setCols(n)`        | invalid `n`                              | --                           | no change         |
+| `setMinLength(n)`   | `n` is non-negative integer or undefined | set minLength                | `minLength = n`   |
+| `setMaxLength(n)`   | `n` is non-negative integer or undefined | set maxLength                | `maxLength = n`   |
+| `setResize(mode)`   | --                                       | set resize                   | `resize = mode`   |
+| `setFocused(f)`     | --                                       | set focused                  | `focused = f`     |
+
+## Adapter Expectations
+
+UIKit (`cv-textarea`) binds to the headless contract as follows:
+
+- **Signals read**:
+  - `state.value()` - value reflection to DOM
+  - `state.disabled()` - host `[disabled]` reflection
+  - `state.readonly()` - host `[readonly]` reflection
+  - `state.required()` - host `[required]` reflection
+  - `state.focused()` - host `[focused]` reflection
+  - `state.filled()` - host `[filled]` reflection
+  - `state.resize()` - host `[resize]` reflection
+- **Actions called**:
+  - `setValue`, `setDisabled`, `setReadonly`, `setRequired`, `setPlaceholder`, `setRows`, `setCols`, `setMinLength`, `setMaxLength`, `setResize`
+  - `setFocused` on native focus/blur
+  - `handleInput` on native input
+- **Contracts spread**:
+  - `contracts.getTextareaProps()` - spread onto native `<textarea>`
+- **Events dispatched by UIKit**:
+  - `cv-input` on user input
+  - `cv-change` on blur commit when value changed since focus
+  - `cv-focus` / `cv-blur` on focus transitions
+
+## Invariants
+
+1. `filled` is `true` iff `value.length > 0`.
+2. `handleInput` is a no-op when `disabled` or `readonly`.
+3. `setValue` remains available while `disabled`/`readonly` (programmatic updates).
+4. `tabindex` is `"-1"` when disabled, `"0"` otherwise.
+5. `aria-disabled` is `"true"` only when disabled.
+6. `aria-readonly` is `"true"` only when readonly.
+7. `aria-required` is `"true"` only when required.
+8. `rows` and `cols` are always positive integers.
+9. `minLength` and `maxLength` are undefined or non-negative integers.
+10. `resize` is always `"none"` or `"vertical"`.
+
+## Minimum Test Matrix
+
+- initial defaults for all state values
+- `handleInput(v)` updates value and calls `onInput`
+- `handleInput(v)` no-op for disabled
+- `handleInput(v)` no-op for readonly
+- `setValue(v)` updates while disabled
+- `setValue(v)` updates while readonly
+- `filled` derives from value emptiness
+- `setRows` and `setCols` accept valid positive integers
+- `setRows` and `setCols` ignore invalid numbers
+- `setMinLength` / `setMaxLength` set and clear constraints
+- `getTextareaProps()` returns proper ARIA and native attributes
+- `getTextareaProps()` omits role
+- `setFocused` updates focus state
+
+## ADR-001 Compliance
+
+- **Runtime Policy**: Reatom v1000 only; no @statx/\* in headless core.
+- **Layering**: core/interactions/a11y-contracts/adapters boundaries preserved.
+- **Independence**: no monorepo app imports.
+- **Verification**: standalone headless tests via package command.
+
+## Out of Scope (Current)
+
+- auto-growing textarea height based on content
+- validation message state and error modeling
+- rich text / markdown semantics
+- custom keyboard shortcuts beyond native textarea behavior

package/specs/components/toast.md

@@ -0,0 +1,198 @@
+# Toast Component Contract
+
+## Purpose
+
+`Toast` provides a headless notification queue model with dismiss, auto-dismiss, and pause/resume timing behavior. Composite architecture: `cv-toast-region` (container) + `cv-toast` (per-item).
+
+## Component Files
+
+- `src/toast/index.ts` - model and public `createToast` API
+- `src/toast/toast.test.ts` - unit behavior tests
+
+## Public API
+
+- `createToast(options)`
+- `state` (signal-backed):
+  - `items()` - full toast queue
+  - `visibleItems()` - top `maxVisible` slice
+  - `isPaused()` - pause state for timers
+- `actions`:
+  - `push(item)` - enqueue toast and return generated id
+  - `dismiss(id)`
+  - `clear()`
+  - `pause()`
+  - `resume()`
+- `contracts`:
+  - `getRegionProps()`
+  - `getToastProps(id)`
+  - `getDismissButtonProps(id)`
+
+## CreateToastOptions
+
+| Option              | Type                      | Default    | Description                                   |
+| ------------------- | ------------------------- | ---------- | --------------------------------------------- |
+| `idBase`            | `string`                  | `'toast'`  | Base id prefix for all generated ids          |
+| `initialItems`      | `readonly ToastItem[]`    | `[]`       | Pre-populated toast items                     |
+| `maxVisible`        | `number`                  | `3`        | Maximum number of toasts shown (clamped >= 1) |
+| `defaultDurationMs` | `number`                  | `5000`     | Default auto-dismiss duration (clamped >= 0)  |
+| `ariaLive`          | `'polite' \| 'assertive'` | `'polite'` | `aria-live` value for the region              |
+
+## State Signal Surface
+
+| Signal         | Type                    | Derived? | Description                            |
+| -------------- | ----------------------- | -------- | -------------------------------------- |
+| `items`        | `Atom<ToastItem[]>`     | No       | Full toast queue, newest-first         |
+| `visibleItems` | `Computed<ToastItem[]>` | Yes      | `items().slice(0, maxVisible)`         |
+| `isPaused`     | `Atom<boolean>`         | No       | Whether auto-dismiss timers are paused |
+
+## APG and A11y Contract
+
+- region role: `region`
+- region attributes:
+  - `aria-live` (`polite` or `assertive`)
+  - `aria-atomic="false"`
+- toast item role:
+  - `status` for `info`/`success`
+  - `alert` for `warning`/`error`
+- dismiss button role: `button`
+
+## Keyboard Contract
+
+- model-level keyboard behavior is intentionally minimal
+- keyboard bindings for dismiss shortcuts are adapter-level
+- dismiss action is exposed through dismiss-button contract handlers
+
+## Behavior Contract
+
+- pushing a toast prepends it to queue (`newest-first`).
+- queue visibility is constrained by `maxVisible`.
+- auto-dismiss timers are tracked per toast id.
+- pause computes and stores remaining durations; resume continues from remaining time.
+- no auto-dismiss is scheduled when duration is `<= 0`.
+
+## Contract Prop Shapes
+
+### `getRegionProps()`
+
+```ts
+{
+  id: string                          // '{idBase}-region'
+  role: 'region'
+  'aria-live': 'polite' | 'assertive' // from options.ariaLive
+  'aria-atomic': 'false'
+}
+```
+
+### `getToastProps(id)`
+
+```ts
+{
+  id: string                          // '{idBase}-item-{id}'
+  role: 'status' | 'alert'           // 'status' for info/success, 'alert' for warning/error
+  'data-level': ToastLevel            // 'info' | 'success' | 'warning' | 'error'
+}
+```
+
+### `getDismissButtonProps(id)`
+
+```ts
+{
+  id: string                          // '{idBase}-dismiss-{id}'
+  role: 'button'
+  tabindex: '0'
+  'aria-label': 'Dismiss notification'
+  onClick: () => void                 // calls dismiss(id)
+}
+```
+
+## Transitions Table
+
+| Event / Action             | Current State            | Next State / Effect                                                                    |
+| -------------------------- | ------------------------ | -------------------------------------------------------------------------------------- |
+| `push(item)`               | any                      | New toast prepended to `items`; auto-dismiss timer scheduled; returns generated id     |
+| `push(item)` (paused)      | `isPaused = true`        | New toast prepended to `items`; remaining duration stored but no timer started         |
+| `dismiss(id)`              | toast exists in `items`  | Toast removed from `items`; timer and tracking data cleared                            |
+| `clear()`                  | any                      | All items removed; all timers and tracking data cleared                                |
+| `pause()`                  | `isPaused = false`       | `isPaused = true`; all running timers stopped; remaining durations computed and stored |
+| `pause()`                  | `isPaused = true`        | no-op                                                                                  |
+| `resume()`                 | `isPaused = true`        | `isPaused = false`; auto-dismiss timers rescheduled from remaining durations           |
+| `resume()`                 | `isPaused = false`       | no-op                                                                                  |
+| timer fires (auto-dismiss) | toast exists, timer done | `dismiss(id)` called; toast removed from queue                                         |
+
+### Derived state reactions
+
+| State Change    | `visibleItems`                               |
+| --------------- | -------------------------------------------- |
+| `items` changes | Recomputed as `items().slice(0, maxVisible)` |
+
+## Invariants
+
+1. `visibleItems` always equals `items().slice(0, maxVisible)`.
+2. `clear` removes all queue items and all timer tracking data.
+3. No auto-dismiss is scheduled when duration is `<= 0`.
+4. Role mapping is level-dependent: `role="status"` for `info`/`success`, `role="alert"` for `warning`/`error`.
+5. `getToastProps(id)` throws if the toast id is not found in `items`.
+6. `pause()` is idempotent when already paused; `resume()` is idempotent when not paused.
+7. Remaining duration after pause/resume must preserve elapsed time accurately.
+
+## Adapter Expectations
+
+UIKit adapters MUST bind to the headless model as follows:
+
+**Signals read (reactive, drive re-renders):**
+
+- `state.items()` — full toast queue for iteration
+- `state.visibleItems()` — sliced queue for rendering visible toasts
+- `state.isPaused()` — whether auto-dismiss timers are paused (for hover pause behavior)
+
+**Actions called (event handlers, never mutate state directly):**
+
+- `actions.push(item)` — enqueue a new toast notification
+- `actions.dismiss(id)` — dismiss a specific toast
+- `actions.clear()` — dismiss all toasts
+- `actions.pause()` — pause auto-dismiss timers (e.g., on mouse enter region)
+- `actions.resume()` — resume auto-dismiss timers (e.g., on mouse leave region)
+
+**Contracts spread (attribute maps applied directly to DOM elements):**
+
+- `contracts.getRegionProps()` — spread onto the `cv-toast-region` container element
+- `contracts.getToastProps(id)` — spread onto each `cv-toast` item element (returns `role: 'status' | 'alert'` based on toast level)
+- `contracts.getDismissButtonProps(id)` — spread onto the dismiss button inside each toast (includes `onClick` handler)
+
+**UIKit-only concerns (NOT in headless):**
+
+- Positioning and stacking layout (`position` attribute on `cv-toast-region`)
+- Entry/exit animations and transitions
+- Icon slot rendering per severity level
+- Closable attribute controlling dismiss button visibility
+- Lifecycle events (`cv-dismiss`, etc.)
+- Mouse enter/leave region handlers that call `pause()`/`resume()`
+
+## Minimum Test Matrix
+
+- push/dismiss queue operations
+- auto-dismiss timing behavior
+- pause/resume preserving remaining duration
+- max-visible slicing behavior
+- role mapping for different toast levels (`status` for info/success, `alert` for warning/error)
+- `getRegionProps` returns correct `aria-live` and `role`
+- `getDismissButtonProps` onClick calls dismiss
+- `getToastProps` throws for unknown id
+- clear removes all items and tracking
+- push while paused stores duration without starting timer
+
+## ADR-001 Compliance
+
+- **Runtime Policy**: Reatom v1000 only; no @statx/\* in headless core.
+- **Layering**: core -> interactions -> a11y-contracts -> adapters; adapters remain thin mappings.
+- **Independence**: No imports from @project/_, apps/_, or other out-of-package modules.
+- **Verification**: Mandatory adapter integration tests and standalone package test execution.
+
+## Out of Scope (Current)
+
+- animation and transition orchestration
+- swipe/gesture dismissal
+- viewport positioning and stacking rules
+- cross-tab or persistent notification history
+- progress bar or loading variant
+- title field (message-only content)