@chromvoid/headless-ui 0.1.0

package/specs/RELEASE-CANDIDATE.md

@@ -0,0 +1,30 @@
+# Headless Release Candidate Evidence
+
+## APG coverage summary
+
+- Component specs in `specs/components/*.md`: 30
+- Implemented component modules in `src/<component>/index.ts`: 30
+- Component tests in `src/<component>/*.test.ts`: 30
+- Shared APG harness: `src/testing/apg-contract-harness.ts`
+- Cross-component APG regression suite: `src/testing/apg-contracts.regression.test.ts`
+
+Coverage focus for the newest tranche (HLS-131..HLS-134):
+
+- `treegrid`: role/aria hierarchy metadata and keyboard transitions
+- `feed`: role/aria stream metadata and paging keyboard contract
+- `carousel`: role/aria-live semantics, control linkage, and rotation pause rules
+- `window-splitter`: separator aria-value contract and orientation-aware keyboard resizing
+
+## Release-ready checklist
+
+- [x] `src/index.ts` exports include all implemented components
+- [x] `README.md` implemented components list matches package surface
+- [x] LSP diagnostics clean for changed source and test files
+- [x] Package lint gates pass (`lint:types`, `lint:oxlint`, `lint:format`, `lint:boundaries`)
+- [x] Package test gate passes (`vitest`)
+- [x] APG contract helper and regression suite added
+
+## Verification commands
+
+- `npm run lint`
+- `npm run test`

package/specs/components/accordion.md

@@ -0,0 +1,130 @@
+# Accordion Component Contract
+
+## Purpose
+
+`Accordion` is a headless APG-aligned contract for a set of vertically stacked sections that can be expanded or collapsed to reveal or hide content. It manages expansion state, keyboard navigation between headers, and accessibility attributes.
+
+## Component Files
+
+- `src/accordion/index.ts` - model and public `createAccordion` API
+- `src/accordion/accordion.test.ts` - unit behavior tests
+
+## Public API
+
+- `createAccordion(options)`
+  - `options`:
+    - `sections`: `AccordionSection[]` — `{id: string, disabled?: boolean}`
+    - `idBase?`: string
+    - `allowMultiple?`: boolean (default: `false`)
+    - `allowZeroExpanded?`: boolean (default: `true`)
+    - `initialExpandedIds?`: string[]
+    - `ariaLabel?`: string
+    - `headingLevel?`: number (default: `3`, clamped 1–6)
+- `state` (signal-backed):
+  - `expandedIds()` — set of currently expanded section IDs
+  - `focusedId()` — ID of the section header currently holding focus
+  - `value()` — first expanded section ID, or `null` (computed)
+  - `expandedValues()` — array of expanded section IDs (computed)
+  - `sections()` — current sections list (reactive)
+  - `allowMultiple()` — current allow-multiple setting (reactive)
+  - `allowZeroExpanded()` — current allow-zero-expanded setting (reactive)
+  - `headingLevel()` — current heading level 1–6 (reactive)
+  - `ariaLabel()` — current aria-label (reactive)
+- `actions`:
+  - `toggle(id)` — expands or collapses a section
+  - `expand(id)` — expands a section
+  - `collapse(id)` — collapses a section
+  - `setFocused(id)` — sets roving focus to a section
+  - `moveNext()` — moves focus to the next header
+  - `movePrev()` — moves focus to the previous header
+  - `moveFirst()` — moves focus to the first header
+  - `moveLast()` — moves focus to the last header
+  - `handleKeyDown(event)` — processes keyboard navigation and activation
+  - `setSections(sections)` — replaces sections list; enforces expanded invariants
+  - `setAllowMultiple(value)` — updates allow-multiple; clamps expanded to first if switching to single
+  - `setAllowZeroExpanded(value)` — updates allow-zero-expanded; expands first if none expanded
+  - `setHeadingLevel(level)` — updates heading level (clamped 1–6)
+  - `setAriaLabel(label)` — updates aria-label
+  - `setExpandedIds(ids)` — programmatically sets expanded sections; respects constraints
+- `contracts`:
+  - `getRootProps()`
+  - `getHeaderProps(id)`
+  - `getTriggerProps(id)`
+  - `getPanelProps(id)`
+
+## APG and A11y Contract
+
+- root role: none (usually a `div` or `dl`)
+- header role: none (usually a heading level `h1-h6`)
+- trigger role: `button`
+- panel role: `region`
+- required attributes:
+  - trigger: `aria-expanded`, `aria-controls`, `id`, `aria-disabled`
+  - panel: `aria-labelledby`, `id`, `role="region"`
+- focus management:
+  - triggers are in the page tab sequence
+  - focus moves between triggers using arrow keys (optional but recommended for large accordions)
+
+## Behavior Contract
+
+- **Single/Multiple Expansion**:
+  - if `allowMultiple` is `false`, expanding one section collapses others
+  - if `allowMultiple` is `true`, multiple sections can be expanded simultaneously
+- **Collapsible**:
+  - if `allowZeroExpanded` is `false`, at least one section must remain expanded; clicking an expanded trigger does nothing if it's the only one expanded
+- **Keyboard Navigation**:
+  - `Enter` or `Space`: toggles the expanded state of the panel associated with the focused trigger
+  - `ArrowDown`: moves focus to the next trigger; wraps if configured
+  - `ArrowUp`: moves focus to the previous trigger; wraps if configured
+  - `Home`: moves focus to the first trigger
+  - `End`: moves focus to the last trigger
+
+## Reactive Config Invariants
+
+When config atoms change at runtime, the model enforces invariants:
+
+- `setAllowMultiple(false)` — if multiple sections are expanded, clamps to the first expanded section
+- `setAllowZeroExpanded(false)` — if no sections are expanded, expands the first enabled section
+- `setSections(...)` — removes expanded IDs that no longer exist in the new sections list; enforces `allowMultiple` and `allowZeroExpanded` constraints after pruning
+- `setExpandedIds(...)` — filters out unknown section IDs; clamps to first if `allowMultiple` is false; expands first enabled if `allowZeroExpanded` is false and result is empty
+
+## Invariants
+
+- a disabled section cannot be expanded or collapsed via user interaction
+- `expandedIds` must always respect the `allowMultiple` and `allowZeroExpanded` constraints
+- `aria-controls` on the trigger must match the `id` of the panel
+- `aria-labelledby` on the panel must match the `id` of the trigger
+
+## Minimum Test Matrix
+
+- initialize with specific sections expanded
+- toggle expansion on `Enter`/`Space`
+- respect `allowMultiple: false` (auto-collapse others)
+- respect `allowZeroExpanded: false` (prevent collapsing last expanded)
+- navigate between triggers using `ArrowDown`/`ArrowUp`/`Home`/`End`
+- skip disabled sections during keyboard navigation
+- verify `aria-expanded` and `aria-controls` linkage
+- verify `aria-labelledby` linkage
+- computed `value()` reflects first expanded ID
+- computed `expandedValues()` reflects all expanded IDs
+- `setSections` removes stale expanded IDs
+- `setSections` respects `allowZeroExpanded` after pruning
+- `setAllowMultiple(false)` clamps to first expanded
+- `setAllowZeroExpanded(false)` expands first when none expanded
+- `setHeadingLevel` clamps to 1–6
+- `setAriaLabel` updates `getRootProps()` aria-label
+- `setExpandedIds` respects `allowMultiple` and `allowZeroExpanded`
+- `setExpandedIds` ignores unknown section IDs
+
+## 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)
+
+- nested accordions (recursive state management)
+- animation/transition state (handled by visual layer)
+- drag-and-drop reordering

package/specs/components/alert-dialog.md

@@ -0,0 +1,72 @@
+# Alert Dialog Component Contract
+
+## Purpose
+
+`AlertDialog` is a specialized modal dialog for critical confirmations or alerts that require immediate user attention. It differs from a standard dialog by its role and focus behavior, specifically prioritizing the least destructive action.
+
+## Component Files
+
+- `src/alert-dialog/index.ts` - model and public `createAlertDialog` API
+- `src/alert-dialog/alert-dialog.test.ts` - unit behavior tests
+
+## Public API
+
+- `createAlertDialog(options)`
+- `state` (signal-backed):
+  - `isOpen()`
+- `actions`:
+  - `open`, `close`
+  - `handleKeyDown`
+- `contracts`:
+  - `getDialogProps()`
+  - `getOverlayProps()`
+  - `getTitleProps()`
+  - `getDescriptionProps()`
+  - `getCancelButtonProps()`
+  - `getActionButtonProps()`
+
+## APG and A11y Contract
+
+- content role: `alertdialog`
+- required attributes:
+  - content: `aria-modal="true"`, `aria-labelledby`, `aria-describedby`
+- focus management:
+  - initial focus MUST be on the least destructive element (e.g., "Cancel" button)
+  - focus trap within the dialog while open
+  - focus restore to the trigger on close
+
+## Behavior Contract
+
+- `Escape` key closes the dialog (if appropriate for the context)
+- focus management: specifically prioritizes the "Cancel" or "No" action to prevent accidental destructive actions
+- scroll lock on the body when open
+- focus trap: `Tab` and `Shift+Tab` cycle through focusable elements inside the dialog
+
+## Invariants
+
+- `isOpen` is a boolean
+- `aria-describedby` is mandatory for `alertdialog` to ensure the alert message is announced
+- focus is always trapped while open
+- initial focus is placed on the cancel/least-destructive action by default
+
+## Minimum Test Matrix
+
+- open/close state transitions
+- initial focus on the "Cancel" button by default
+- focus trap behavior (Tab/Shift+Tab wrapping)
+- focus restore on close
+- `Escape` key dismissal
+- mandatory `aria-describedby` presence check
+
+## 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)
+
+- non-modal alerts (use `alert` component)
+- complex multi-step confirmation flows
+- custom focus trap logic (uses shared dialog primitive)

package/specs/components/alert.md

@@ -0,0 +1,65 @@
+# Alert Component Contract
+
+## Purpose
+
+`Alert` is a headless contract for passive live region announcements. It is used to communicate important and usually time-sensitive information without interrupting the user's flow.
+
+## Component Files
+
+- `src/alert/index.ts` - model and public `createAlert` API
+- `src/alert/alert.test.ts` - unit behavior tests
+
+## Public API
+
+- `createAlert(options)`
+- `state` (signal-backed):
+  - `isVisible()`
+  - `message()`
+- `actions`:
+  - `show(message)`, `hide`
+- `contracts`:
+  - `getAlertProps()`
+
+## APG and A11y Contract
+
+- role: `alert`
+- required attributes:
+  - `aria-live="assertive"`
+  - `aria-atomic="true"`
+- behavior:
+  - assistive technologies should announce the content immediately when it changes
+  - does not take focus
+
+## Behavior Contract
+
+- `show`: updates `message` and sets `isVisible` to `true`
+- `hide`: sets `isVisible` to `false`
+- passive: does not manage focus or keyboard interactions
+- automatic dismissal: can be configured via `duration` option
+
+## Invariants
+
+- `isVisible` is a boolean
+- `role="alert"` is always present on the root element
+- `aria-live` is set to `assertive` by default to ensure immediate announcement
+
+## Minimum Test Matrix
+
+- visibility state transitions
+- message update reactivity
+- correct ARIA attributes (`role`, `aria-live`, `aria-atomic`)
+- verification that it does not interfere with focus
+- auto-dismiss timer verification (if enabled)
+
+## 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)
+
+- interactive alerts (use `alert-dialog`)
+- multiple concurrent alerts (handled by consumer or higher-level toast manager)
+- rich content within alerts

package/specs/components/badge.md

@@ -0,0 +1,220 @@
+# Badge Component Contract
+
+## Purpose
+
+`Badge` is a headless contract for a non-interactive status indicator that displays short labels, counts, or colored dots. It provides ARIA semantics for live-region announcements when badge content changes dynamically, and decorative hiding when the badge is purely visual.
+
+## Component Files
+
+- `src/badge/index.ts` - model and public `createBadge` API
+- `src/badge/badge.test.ts` - unit behavior tests
+
+## Options (`CreateBadgeOptions`)
+
+| Option         | Type                  | Default     | Description                                                                    |
+| -------------- | --------------------- | ----------- | ------------------------------------------------------------------------------ |
+| `variant`      | `BadgeVariant`        | `'neutral'` | Visual variant: `'primary' \| 'success' \| 'neutral' \| 'warning' \| 'danger'` |
+| `size`         | `BadgeSize`           | `'medium'`  | Display size: `'small' \| 'medium' \| 'large'`                                 |
+| `dot`          | `boolean`             | `false`     | Dot mode: hides textual content, shows a colored circle indicator              |
+| `pulse`        | `boolean`             | `false`     | Whether the badge should animate to draw attention                             |
+| `pill`         | `boolean`             | `false`     | Whether to apply a pill (fully rounded) shape modifier                         |
+| `isDynamic`    | `boolean`             | `false`     | Whether content changes at runtime (enables live-region semantics)             |
+| `isDecorative` | `boolean`             | `false`     | Whether the badge is purely decorative (hides from assistive technology)       |
+| `ariaLabel`    | `string \| undefined` | `undefined` | Accessible label override; useful in dot mode where visible text is absent     |
+
+## Type Definitions
+
+```ts
+type BadgeVariant = 'primary' | 'success' | 'neutral' | 'warning' | 'danger'
+type BadgeSize = 'small' | 'medium' | 'large'
+```
+
+## Public API
+
+### `createBadge(options?: CreateBadgeOptions): BadgeModel`
+
+### State (signal-backed)
+
+| Signal           | Type                 | Description                                              |
+| ---------------- | -------------------- | -------------------------------------------------------- |
+| `variant()`      | `Atom<BadgeVariant>` | Current visual variant                                   |
+| `size()`         | `Atom<BadgeSize>`    | Current display size                                     |
+| `dot()`          | `Atom<boolean>`      | Whether dot mode is active                               |
+| `pulse()`        | `Atom<boolean>`      | Whether pulse animation is active                        |
+| `pill()`         | `Atom<boolean>`      | Whether pill shape modifier is active                    |
+| `isDynamic()`    | `Atom<boolean>`      | Whether the badge is a live region                       |
+| `isDecorative()` | `Atom<boolean>`      | Whether the badge is decorative-only                     |
+| `isEmpty()`      | `Computed<boolean>`  | Derived: `true` when `dot` is `true` (content is hidden) |
+
+### Actions
+
+| Action          | Signature                       | Description                   |
+| --------------- | ------------------------------- | ----------------------------- |
+| `setVariant`    | `(value: BadgeVariant) => void` | Updates the visual variant    |
+| `setSize`       | `(value: BadgeSize) => void`    | Updates the display size      |
+| `setDot`        | `(value: boolean) => void`      | Toggles dot mode              |
+| `setPulse`      | `(value: boolean) => void`      | Toggles pulse animation       |
+| `setPill`       | `(value: boolean) => void`      | Toggles pill shape modifier   |
+| `setDynamic`    | `(value: boolean) => void`      | Toggles live-region semantics |
+| `setDecorative` | `(value: boolean) => void`      | Toggles decorative mode       |
+
+### Contracts
+
+| Contract          | Return type  | Description                                              |
+| ----------------- | ------------ | -------------------------------------------------------- |
+| `getBadgeProps()` | `BadgeProps` | Ready-to-spread ARIA attribute map for the badge element |
+
+#### `BadgeProps` Shape
+
+The returned object depends on the current state:
+
+**When `isDecorative` is `true`:**
+
+```ts
+{
+  role: 'presentation'
+  'aria-hidden': 'true'
+}
+```
+
+**When `isDynamic` is `true` (and not decorative):**
+
+```ts
+{
+  role: 'status'
+  'aria-live': 'polite'
+  'aria-atomic': 'true'
+  'aria-label'?: string   // from options.ariaLabel (recommended for dot mode)
+}
+```
+
+**Default (static, non-decorative):**
+
+```ts
+{
+  'aria-label'?: string   // from options.ariaLabel (recommended for dot mode)
+}
+```
+
+## APG and A11y Contract
+
+- **Dynamic badge** (content changes at runtime):
+  - `role="status"` — implicit live region with polite politeness
+  - `aria-live="polite"` — explicit for broader assistive technology support
+  - `aria-atomic="true"` — announce the entire badge content on change
+- **Decorative badge** (purely visual, no semantic meaning):
+  - `role="presentation"` — removes semantic meaning
+  - `aria-hidden="true"` — hidden from assistive technology
+- **Static badge** (content does not change after render):
+  - No role or live-region attributes needed; content is read inline
+- **Dot mode**:
+  - When `dot` is `true`, visible text content is hidden; `aria-label` should be provided for accessible meaning
+- **Non-interactive**: no keyboard interaction, no `tabindex`, no focus management
+
+## Keyboard Contract
+
+Badge is not keyboard-interactive. No keyboard handling is needed.
+
+## Behavior Contract
+
+- All state properties are set programmatically; there are no user-driven interactions.
+- `isEmpty` is derived from `dot`: when dot mode is active, the badge has no visible text content.
+- `variant` accepts only the five defined values; invalid values should be ignored or defaulted to `'neutral'`.
+- `size` accepts only the three defined values; invalid values should be ignored or defaulted to `'medium'`.
+- `isDecorative` takes precedence over `isDynamic`: a decorative badge never becomes a live region regardless of `isDynamic` state.
+
+## Transitions Table
+
+| Trigger                    | Precondition  | State Change                    | Contract Effect                                                                       |
+| -------------------------- | ------------- | ------------------------------- | ------------------------------------------------------------------------------------- |
+| `actions.setVariant(v)`    | valid variant | `variant` = v                   | no ARIA change                                                                        |
+| `actions.setSize(v)`       | valid size    | `size` = v                      | no ARIA change                                                                        |
+| `actions.setDot(v)`        | any           | `dot` = v; `isEmpty` recomputes | no ARIA change; UIKit hides/shows content                                             |
+| `actions.setPulse(v)`      | any           | `pulse` = v                     | no ARIA change                                                                        |
+| `actions.setPill(v)`       | any           | `pill` = v                      | no ARIA change                                                                        |
+| `actions.setDynamic(v)`    | any           | `isDynamic` = v                 | `getBadgeProps()` adds/removes `role="status"`, `aria-live`, `aria-atomic`            |
+| `actions.setDecorative(v)` | any           | `isDecorative` = v              | `getBadgeProps()` switches to `role="presentation"` + `aria-hidden="true"` or reverts |
+
+## Invariants
+
+- `isDecorative` takes precedence: when `true`, `getBadgeProps()` always returns `{ role: 'presentation', 'aria-hidden': 'true' }` regardless of `isDynamic`.
+- `isEmpty` must be `true` if and only if `dot` is `true`.
+- `variant` must always be one of `'primary' | 'success' | 'neutral' | 'warning' | 'danger'`.
+- `size` must always be one of `'small' | 'medium' | 'large'`.
+- Badge must never produce `tabindex`, keyboard event handlers, or focus-related attributes.
+- When `isDynamic` is `true` and `isDecorative` is `false`, `role` must be `'status'` and `aria-live` must be `'polite'`.
+
+## Adapter Expectations
+
+This section defines what UIKit (`cv-badge`) binds to from the headless model.
+
+### Signals read by adapter
+
+| Signal            | UIKit usage                                                            |
+| ----------------- | ---------------------------------------------------------------------- |
+| `state.variant()` | Maps to `variant` host attribute and CSS class for color theming       |
+| `state.size()`    | Maps to `size` host attribute and CSS class for dimension styling      |
+| `state.dot()`     | Sets `dot` attribute on host; conditionally hides default slot content |
+| `state.pulse()`   | Sets `pulse` attribute on host; toggles CSS pulse animation            |
+| `state.pill()`    | Sets `pill` attribute on host; applies fully rounded border radius     |
+| `state.isEmpty()` | Used to conditionally suppress content rendering in dot mode           |
+
+### Actions called by adapter
+
+| Action                     | UIKit trigger                                                    |
+| -------------------------- | ---------------------------------------------------------------- |
+| `actions.setVariant(v)`    | When `variant` attribute/property changes on the host element    |
+| `actions.setSize(v)`       | When `size` attribute/property changes on the host element       |
+| `actions.setDot(v)`        | When `dot` attribute/property changes on the host element        |
+| `actions.setPulse(v)`      | When `pulse` attribute/property changes on the host element      |
+| `actions.setPill(v)`       | When `pill` attribute/property changes on the host element       |
+| `actions.setDynamic(v)`    | When `dynamic` attribute/property changes on the host element    |
+| `actions.setDecorative(v)` | When `decorative` attribute/property changes on the host element |
+
+### Contracts spread by adapter
+
+| Contract          | Target element                     | Notes                                                                                                        |
+| ----------------- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `getBadgeProps()` | Root badge element (`part="base"`) | Spread as attributes; provides `role`, `aria-live`, `aria-atomic`, `aria-hidden`, `aria-label` as applicable |
+
+### Options passed through from UIKit attributes
+
+| UIKit attribute | Headless option | Notes                                              |
+| --------------- | --------------- | -------------------------------------------------- |
+| `variant`       | `variant`       | String enum, defaults to `'neutral'`               |
+| `size`          | `size`          | String enum, defaults to `'medium'`                |
+| `dot`           | `dot`           | Boolean attribute                                  |
+| `pulse`         | `pulse`         | Boolean attribute                                  |
+| `pill`          | `pill`          | Boolean attribute                                  |
+| `dynamic`       | `isDynamic`     | Boolean attribute; enables live-region semantics   |
+| `decorative`    | `isDecorative`  | Boolean attribute; hides from assistive technology |
+| `aria-label`    | `ariaLabel`     | Labeling; recommended when `dot` is `true`         |
+
+## Minimum Test Matrix
+
+- default state: `variant='neutral'`, `size='medium'`, all booleans `false`
+- `getBadgeProps()` returns no role/live-region attrs for static non-decorative badge
+- `getBadgeProps()` returns `role="status"`, `aria-live="polite"`, `aria-atomic="true"` when `isDynamic` is `true`
+- `getBadgeProps()` returns `role="presentation"`, `aria-hidden="true"` when `isDecorative` is `true`
+- `isDecorative` takes precedence over `isDynamic` in contract output
+- `isEmpty` is `true` when `dot` is `true`, `false` otherwise
+- `setVariant` updates variant signal; invalid values rejected
+- `setSize` updates size signal; invalid values rejected
+- `setDot(true)` makes `isEmpty` compute to `true`
+- `aria-label` is included in props when provided
+- badge never produces `tabindex` or keyboard handler attributes
+
+## 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)
+
+- notification count management or capping (consumer responsibility)
+- positioning relative to parent element (layout/CSS concern)
+- removable/dismissible badges (would require interactive contract)
+- animation orchestration for pulse (handled by visual layer)
+- badge groups or stacking

package/specs/components/breadcrumb.md

@@ -0,0 +1,74 @@
+# Breadcrumb Component Contract
+
+## Purpose
+
+`Breadcrumb` is a headless APG-aligned contract for a navigation landmark that helps users understand their current location within a hierarchical structure. It ensures the correct navigation role and identifies the current page within the sequence.
+
+## Component Files
+
+- `src/breadcrumb/index.ts` - model and public `createBreadcrumb` API
+- `src/breadcrumb/breadcrumb.test.ts` - unit behavior tests
+
+## Public API
+
+- `createBreadcrumb(options)`
+  - `options`:
+    - `items`: array of breadcrumb items `{ id, label, href, isCurrent? }`
+- `state` (signal-backed):
+  - `items()` - list of breadcrumb items with `id`, `label`, `href`, and `isCurrent`
+- `actions`: none (primarily a structural/navigational component)
+- `contracts`:
+  - `getRootProps()` - returns props for the `<nav>` element
+  - `getListProps()` - returns props for the list element (`<ol>` or `<ul>`)
+  - `getItemProps(id)` - returns props for the list item element (`<li>`)
+  - `getLinkProps(id)` - returns props for the link element (`<a>`)
+  - `getSeparatorProps(id)` - returns props for the separator element (usually `aria-hidden="true"`)
+
+## APG and A11y Contract
+
+- root role: `nav`
+- list role: none (usually `ol` or `ul`)
+- item role: none (usually `li`)
+- link role: `link`
+- required attributes:
+  - root: `aria-label="Breadcrumb"` (or localized equivalent)
+  - current link: `aria-current="page"`
+- focus management:
+  - links are in the page tab sequence
+  - the current page link may or may not be focusable depending on implementation, but must have `aria-current="page"`
+
+## Behavior Contract
+
+- **Structural Integrity**:
+  - the component provides the necessary ARIA attributes to identify the navigation landmark and the current page
+- **Current Page**:
+  - exactly one item (usually the last one) should have `isCurrent: true`
+  - the `getLinkProps` for the current item must include `aria-current="page"`
+
+## Invariants
+
+- the root element must be a `<nav>` or have `role="navigation"`
+- `aria-label` (or `aria-labelledby`) is required on the root to distinguish it from other navigation landmarks
+- only the current page link should have `aria-current="page"`
+
+## Minimum Test Matrix
+
+- render a list of breadcrumb items
+- verify `aria-label="Breadcrumb"` on the root
+- verify `aria-current="page"` on the current item link
+- verify other items do not have `aria-current`
+- verify correct `href` mapping for links
+- verify separators are `aria-hidden="true"`
+
+## 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)
+
+- collapsible breadcrumbs (overflow management)
+- dropdown menus within breadcrumbs
+- dynamic path updates (handled by routing integration)