@chromvoid/headless-ui 0.1.1 → 0.2.0

package/README.md

@@ -1,9 +1,140 @@
-The goal of this package is to provide a standalone headless foundation for a future UI kit,
-built on Reatom v1000 and WAI-ARIA APG behavior contracts.
+# @chromvoid/headless-ui
 
-The visual UI kit is intentionally out of scope for this package.
+`@chromvoid/headless-ui` is a standalone headless package for building accessible UI behavior
+without coupling that behavior to a visual layer.
 
-## Import contract
+It is the behavioral foundation for future ChromVoid UI kits and product interfaces:
+
+- reactive component models built on Reatom v1001
+- WAI-ARIA APG-aligned keyboard and accessibility contracts
+- explicit state transitions and event handling
+- framework-agnostic rendering ownership
+
+This package does **not** ship styled components, templates, CSS, icons, or product-specific
+layout decisions. It owns behavior and accessibility semantics. Your UI layer owns markup,
+styling, motion, and composition.
+
+## What This Package Is For
+
+Use this package when you want to build:
+
+- a design system or UI kit on top of stable headless behavior contracts
+- product-specific components without rewriting keyboard, focus, and ARIA logic
+- framework bindings that stay thin because the behavior already lives in the model
+- accessible widgets that remain portable outside the ChromVoid monorepo
+
+Use something else if you want:
+
+- ready-made visual components
+- a DOM renderer
+- a framework-specific component library
+- a package that hides Reatom from the public model shape
+
+## Mental Model
+
+Each component is a small behavior engine.
+
+1. Create a model with `createX(options)`.
+2. Read reactive `state` from Reatom atoms and computed values.
+3. Call `actions` in response to user intent.
+4. Apply `contracts.get*Props()` to your DOM or framework layer.
+
+In other words:
+
+- the package decides how a widget behaves
+- the package exposes what ARIA attributes and handlers are required
+- your app decides how the widget looks and where it is rendered
+
+That split is the core idea behind the repository.
+
+## How It Works
+
+The public API is intentionally repetitive across components:
+
+- `state`: reactive sources of truth
+- `actions`: the only supported mutation path
+- `contracts`: grouped prop getters for ARIA, ids, and event handlers
+
+Typical shape:
+
+```ts
+const model = createX(options)
+
+model.state
+model.actions
+model.contracts.getRootProps()
+```
+
+Example with a real component:
+
+```ts
+import {createButton} from '@chromvoid/headless-ui/button'
+
+const button = createButton({
+  idBase: 'save',
+  onPress: () => {
+    console.log('save')
+  },
+})
+
+const buttonProps = button.contracts.getButtonProps()
+
+button.state.isDisabled()
+button.actions.setLoading(true)
+
+buttonProps.role
+buttonProps.tabindex
+buttonProps.onClick
+buttonProps.onKeyDown
+buttonProps.onKeyUp
+```
+
+The same pattern scales from simple controls such as `button` and `checkbox` to larger widgets
+such as `listbox`, `combobox`, `treeview`, `grid`, or `treegrid`.
+
+## Design Philosophy
+
+This package is opinionated in a very specific way.
+
+- **Headless, not vague**: it avoids visual output, but it is strict about behavior, focus, and
+  accessibility semantics.
+- **Signal-first state**: public state stays reactive so UI layers can read it directly instead of
+  synchronizing snapshots by hand.
+- **Intent-first actions**: keyboard and pointer flows map to model actions, not scattered UI glue.
+- **Contract-first accessibility**: ARIA attributes, roles, ids, and linkage are part of the
+  public contract, not an afterthought.
+- **Thin adapters**: adapters exist to map models into renderers, not to contain business logic.
+- **Standalone by default**: the package must work outside this monorepo, with no hidden internal
+  imports or release-time coupling.
+- **DX over inertia in pre-v1**: while the package is still `<1.0`, ergonomics and API consistency
+  take priority over preserving temporary shapes.
+
+## Why The Repository Looks Like This
+
+This package is developed inside a monorepo for local integration speed, but it is treated as an
+independent public library.
+
+That leads to a few hard rules:
+
+- no imports from `@project/*`, `apps/*`, or other monorepo-only modules
+- package-local scripts, tests, specs, and release checks
+- explicit architecture docs and component specs
+- stable lean-import support through subpath exports
+
+This directory is a **development mirror**. The canonical release history and publishing flow live
+in a separate public git-shard repository.
+
+## Getting Started
+
+Install the package in a Node 20+ ESM environment:
+
+```sh
+npm install @chromvoid/headless-ui
+```
+
+Then pick the import style that matches your use case.
+
+## Import Contract
 
 The package ships from `dist/` and supports both a convenience root barrel and lean leaf imports.
 
@@ -13,7 +144,7 @@ Use the root barrel when convenience matters more than bundle shape:
 import {createButton, createTabs} from '@chromvoid/headless-ui'
 ```
 
-Use leaf subpaths in perf-sensitive code when you want an intentionally narrow dependency graph:
+Use leaf subpaths when you want a deliberately narrow dependency graph:
 
 ```ts
 import {createButton} from '@chromvoid/headless-ui/button'
@@ -21,17 +152,70 @@ import {CompositeNavigationOrientation} from '@chromvoid/headless-ui/interaction
 import {toggleSelection} from '@chromvoid/headless-ui/core/selection'
 ```
 
-The root barrel remains supported, but subpaths are the stable lean-import contract for applications and higher-level packages such as `@chromvoid/uikit`.
+The root barrel is supported, but leaf subpaths are the stable lean-import contract for
+applications and higher-level packages such as `@chromvoid/uikit`.
+
+## What Ships In The Package
+
+The package currently includes headless models for:
+
+- **Inputs and selection**: `button`, `checkbox`, `combobox`, `date-picker`, `input`, `listbox`,
+  `number`, `radio-group`, `select`, `slider`, `slider-multi-thumb`, `spinbutton`, `switch`,
+  `textarea`
+- **Feedback and content**: `alert`, `badge`, `callout`, `card`, `copy-button`, `meter`,
+  `progress`, `spinner`, `toast`
+- **Disclosure and overlays**: `accordion`, `alert-dialog`, `command-palette`, `context-menu`,
+  `dialog`, `disclosure`, `drawer`, `menu`, `menu-button`, `popover`, `tooltip`
+- **Navigation and structure**: `breadcrumb`, `landmarks`, `link`, `sidebar`, `tabs`, `toolbar`,
+  `treeview`, `window-splitter`
+- **Data and composite widgets**: `carousel`, `feed`, `grid`, `table`, `treegrid`
+
+Shared layers:
+
+- [`src/core/`](./src/core/): low-level state primitives such as selection and value-range logic
+- [`src/interactions/`](./src/interactions/): keyboard intents, typeahead, composite navigation,
+  overlay focus
+- [`src/a11y-contracts/`](./src/a11y-contracts/): typed ARIA and role contracts
+- [`src/adapters/`](./src/adapters/): thin adapter contracts for presentation-layer bindings
+
+## Repository Map
+
+```text
+src/
+  core/
+  interactions/
+  a11y-contracts/
+  adapters/
+  <component>/
+
+specs/
+  ADR-*.md
+  components/<component>.md
+  release/*
+  ops/*
+```
 
-Architecture decisions and delivery artifacts:
+Repository conventions:
 
-- `./specs/ADR-001-headless-architecture.md`
-- `./specs/IMPLEMENTATION-ROADMAP.md`
-- `./specs/ISSUE-BACKLOG.md`
-- `./specs/RELEASE-CANDIDATE.md`
-- `./specs/release/mvp-changelog.md`
+- every component lives in [`src/<component>/`](./src/)
+- every component has a colocated test file in `src/<component>/<component>.test.ts`
+- every component has a dedicated behavior spec in [`specs/components/<component>.md`](./specs/components/)
+- package boundaries are enforced so the code remains portable outside this monorepo
 
-## Package-local workflow
+## Quality And Release Discipline
+
+The repository treats behavior and accessibility as release contracts, not informal implementation
+details.
+
+That discipline is enforced through:
+
+- unit tests for transitions and invariants
+- shared APG regression coverage for cross-component accessibility guarantees
+- package export checks and bundle shape checks
+- standalone boundary checks to prevent accidental monorepo coupling
+- explicit SemVer and deprecation policy for public API evolution
+
+## Package-Local Workflow
 
 Run all package checks from the package root:
 
@@ -43,57 +227,13 @@ npm run build
 npm pack --dry-run
 ```
 
-## Implemented components
-
-- `listbox` (`src/listbox/`, `specs/components/listbox.md`)
-- `combobox` (`src/combobox/`, `specs/components/combobox.md`)
-- `menu` (`src/menu/`, `specs/components/menu.md`)
-- `tabs` (`src/tabs/`, `specs/components/tabs.md`)
-- `treeview` (`src/treeview/`, `specs/components/treeview.md`)
-- `alert` (`src/alert/`, `specs/components/alert.md`)
-- `breadcrumb` (`src/breadcrumb/`, `specs/components/breadcrumb.md`)
-- `landmarks` (`src/landmarks/`, `specs/components/landmarks.md`)
-- `meter` (`src/meter/`, `specs/components/meter.md`)
-- `link` (`src/link/`, `specs/components/link.md`)
-- `table` (`src/table/`, `specs/components/table.md`)
-- `button` (`src/button/`, `specs/components/button.md`)
-- `checkbox` (`src/checkbox/`, `specs/components/checkbox.md`)
-- `switch` (`src/switch/`, `specs/components/switch.md`)
-- `radio-group` (`src/radio-group/`, `specs/components/radio-group.md`)
-- `slider` (`src/slider/`, `specs/components/slider.md`)
-- `spinbutton` (`src/spinbutton/`, `specs/components/spinbutton.md`)
-- `slider-multi-thumb` (`src/slider-multi-thumb/`, `specs/components/slider-multi-thumb.md`)
-- `disclosure` (`src/disclosure/`, `specs/components/disclosure.md`)
-- `accordion` (`src/accordion/`, `specs/components/accordion.md`)
-- `dialog` (`src/dialog/`, `specs/components/dialog.md`)
-- `alert-dialog` (`src/alert-dialog/`, `specs/components/alert-dialog.md`)
-- `tooltip` (`src/tooltip/`, `specs/components/tooltip.md`)
-- `menu-button` (`src/menu-button/`, `specs/components/menu-button.md`)
-- `toolbar` (`src/toolbar/`, `specs/components/toolbar.md`)
-- `grid` (`src/grid/`, `specs/components/grid.md`)
-- `treegrid` (`src/treegrid/`, `specs/components/treegrid.md`)
-- `feed` (`src/feed/`, `specs/components/feed.md`)
-- `carousel` (`src/carousel/`, `specs/components/carousel.md`)
-- `window-splitter` (`src/window-splitter/`, `specs/components/window-splitter.md`)
-
-## MVP-next scaffolds (not finalized)
-
-- `popover` (`src/popover/`, `specs/components/popover.md`)
-- `select` (`src/select/`, `specs/components/select.md`)
-- `context-menu` (`src/context-menu/`, `specs/components/context-menu.md`)
-- `command-palette` (`src/command-palette/`, `specs/components/command-palette.md`)
-- `toast` (`src/toast/`, `specs/components/toast.md`)
-- `progress` (`src/progress/`, `specs/components/progress.md`)
-
-## Shared layers
-
-- `src/core/` - selection and value-range state primitives
-- `src/interactions/` - keyboard intents, typeahead, composite navigation, overlay focus
-- `src/a11y-contracts/` - typed aria/role contracts
-- `src/adapters/` - adapter contracts and integration coverage
-
-## Conventions
-
-- each component lives in a dedicated directory: `src/<component>/`
-- each component has a dedicated contract spec: `specs/components/<component>.md`
-- package must remain independent from monorepo-only imports (`@project/*`, `apps/*`)
+## Read Next
+
+If you are new to the repository, these documents explain the bigger picture:
+
+- [`./specs/ADR-001-headless-architecture.md`](./specs/ADR-001-headless-architecture.md)
+- [`./specs/ADR-003-public-api-versioning.md`](./specs/ADR-003-public-api-versioning.md)
+- [`./specs/ADR-004-focus-selection-policy.md`](./specs/ADR-004-focus-selection-policy.md)
+- [`./specs/IMPLEMENTATION-ROADMAP.md`](./specs/IMPLEMENTATION-ROADMAP.md)
+- [`./specs/ISSUE-BACKLOG.md`](./specs/ISSUE-BACKLOG.md)
+- [`./specs/RELEASE-CANDIDATE.md`](./specs/RELEASE-CANDIDATE.md)

package/dist/copy-button/index.d.ts

@@ -9,6 +9,8 @@ export interface CreateCopyButtonOptions {
     feedbackDuration?: number;
     isDisabled?: boolean;
     ariaLabel?: string;
+    successLabel?: string;
+    errorLabel?: string;
     onCopy?: (value: string) => void;
     onError?: (error: unknown) => void;
     clipboard?: ClipboardAdapter;

package/dist/copy-button/index.js

@@ -1,6 +1,8 @@
 import { action, atom, computed } from '@reatom/core';
 const clampDuration = (v) => Math.max(0, v);
 const isSpaceKey = (key) => key === ' ' || key === 'Spacebar';
+const DEFAULT_SUCCESS_LABEL = 'Copied';
+const DEFAULT_ERROR_LABEL = 'Copy failed';
 const STATUS_TO_ICON = {
     idle: 'copy',
     success: 'success',
@@ -8,6 +10,8 @@ const STATUS_TO_ICON = {
 };
 export function createCopyButton(options = {}) {
     const clipboard = options.clipboard ?? navigator.clipboard;
+    const successLabel = options.successLabel ?? DEFAULT_SUCCESS_LABEL;
+    const errorLabel = options.errorLabel ?? DEFAULT_ERROR_LABEL;
     const statusAtom = atom('idle', 'copyButton.status');
     const isDisabledAtom = atom(options.isDisabled ?? false, 'copyButton.isDisabled');
     const isCopyingAtom = atom(false, 'copyButton.isCopying');
@@ -103,10 +107,10 @@ export function createCopyButton(options = {}) {
                 ariaLabel = options.ariaLabel;
             }
             else if (status === 'success') {
-                ariaLabel = 'Copied';
+                ariaLabel = successLabel;
             }
             else {
-                ariaLabel = 'Copy failed';
+                ariaLabel = errorLabel;
             }
         }
         const props = {

package/dist/menu/index.js

@@ -471,7 +471,7 @@ export function createMenu(options) {
                 'aria-label': parentItem?.label,
             };
         },
-        getSubmenuItemProps(parentItemId, childId) {
+        getSubmenuItemProps(_parentItemId, childId) {
             const item = submenuItemById.get(childId);
             if (!item) {
                 throw new Error(`Unknown submenu item id: ${childId}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chromvoid/headless-ui",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Headless interaction and accessibility contracts for future UI kit",
   "keywords": [
     "a11y",
@@ -76,7 +76,7 @@
     "test:watch": "vitest --config ./vitest.config.ts --watch"
   },
   "dependencies": {
-    "@reatom/core": "^1000.15.0"
+    "@reatom/core": "^1001.0.0"
   },
   "devDependencies": {
     "@types/node": "^24.11.0",

package/specs/ADR-001-headless-architecture.md

@@ -6,7 +6,7 @@
 > **Authors**: Team ChromVoid
 > **Related Documents**:
 >
-> - [packages/headless/README.md](../README.md) - package goal
+> - [packages/headless-ui/README.md](../README.md) - package goal
 > - [WAI-ARIA APG patterns](https://www.w3.org/WAI/ARIA/apg/patterns/) - accessibility behavior patterns
 > - [WAI-ARIA APG keyboard interface](https://www.w3.org/WAI/ARIA/apg/practices/keyboard-interface/) - keyboard and focus rules
 > - [Reatom docs](https://www.reatom.dev/) - state management model
@@ -14,7 +14,7 @@
 > - [ADR-003-public-api-versioning](./ADR-003-public-api-versioning.md) - SemVer and deprecation policy
 > - [ADR-004-focus-selection-policy](./ADR-004-focus-selection-policy.md) - shared focus/selection policy
 >
-> **Note**: `packages/headless` in this monorepo is a development mirror.
+> **Note**: `packages/headless-ui` in this monorepo is a development mirror.
 > The canonical source, versioning, and publishing flow live in a separate public git-shard repository.
 
 ## Context
@@ -22,7 +22,7 @@
 We need a highly independent headless package for a future UI kit:
 
 - no visual layer;
-- Reatom v1000 as the state runtime;
+- Reatom v1001 as the state runtime;
 - behavior contracts aligned with WAI-ARIA APG.
 
 The package is developed in this monorepo for local integration speed,
@@ -56,7 +56,7 @@ If this package is treated as a regular internal monorepo module, we get:
 
 ### 1. Repository Model and Ownership
 
-1. `packages/headless` in this monorepo is a development mirror.
+1. `packages/headless-ui` in this monorepo is a development mirror.
 2. Canonical code history, tags, and releases are managed in a separate public git-shard repository.
 3. Publishing to package registries is done only from git-shard.
 
@@ -134,8 +134,8 @@ Example:
 
 ### 5. State Runtime Policy
 
-- **MUST**: Reatom v1000.
-- **MUST NOT**: `@statx/*` in headless core.
+- **MUST**: Reatom v1001.
+- **MUST NOT**: legacy state runtime in headless core.
 
 ### 6. Testing and Verification
 

package/specs/ADR-002-repo-release-model.md

@@ -10,7 +10,7 @@
 
 ## Context
 
-`packages/headless` is developed in the monorepo for local integration convenience.
+`packages/headless-ui` is developed in the monorepo for local integration convenience.
 The package must still be published as an independent public package from a separate git-shard repository.
 
 Without a clear model, mirror and shard will drift, and releases will become hard to reproduce.
@@ -42,7 +42,7 @@ We need a formal source-of-truth and release flow that answers:
 ### 1. Source of Truth
 
 1. Public git-shard repository is the single canonical source for `headless`.
-2. `packages/headless` in monorepo is mirror-only development workspace.
+2. `packages/headless-ui` in monorepo is mirror-only development workspace.
 
 ### 2. Release Ownership
 

package/specs/ISSUE-BACKLOG.md

@@ -18,11 +18,11 @@ Common labels:
 
 Applies to all issues unless overridden:
 
-1. Code/docs changed in `packages/headless` only.
+1. Code/docs changed in `packages/headless-ui` only.
 2. No forbidden imports (boundary check remains green).
 3. `npm run lint` passes.
 4. `npm run test` passes.
-5. Public exports are wired in `packages/headless/src/index.ts`.
+5. Public exports are wired in `packages/headless-ui/src/index.ts`.
 6. Component behavior stays aligned with corresponding `specs/components/<component>.md`.
 
 ## Backlog Baseline

package/specs/components/accordion.md

@@ -118,7 +118,7 @@ When config atoms change at runtime, the model enforces invariants:
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no @statx/\* in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/components/alert-dialog.md

@@ -60,7 +60,7 @@
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no @statx/\* in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/components/alert.md

@@ -53,7 +53,7 @@
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no @statx/\* in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/components/badge.md

@@ -206,7 +206,7 @@ This section defines what UIKit (`cv-badge`) binds to from the headless model.
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no `@statx/*` in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/components/breadcrumb.md

@@ -62,7 +62,7 @@
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no @statx/\* in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/components/button.md

@@ -103,7 +103,7 @@ UIKit (`cv-button`) binds to the headless contract as follows:
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no @statx/\* in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/components/callout.md

@@ -180,7 +180,7 @@ This section defines what UIKit (`cv-callout`) binds to from the headless model.
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no `@statx/*` in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/components/card.md

@@ -264,7 +264,7 @@ This section defines what UIKit (`cv-card`) binds to from the headless model.
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no `@statx/*` in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/components/carousel.md

@@ -127,7 +127,7 @@ UIKit adapters MUST bind to the headless model as follows:
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no @statx/\* in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/components/checkbox.md

@@ -147,7 +147,7 @@ When this contract changes in a breaking way, the change MUST be documented in t
 
 ### Parity matrix (Headless vs UIKit)
 
-This matrix is intentionally short and exists to prevent drift between `packages/headless/specs/components/checkbox.md` and `packages/uikit/specs/components/checkbox.md`.
+This matrix is intentionally short and exists to prevent drift between `packages/headless-ui/specs/components/checkbox.md` and `packages/uikit/specs/components/checkbox.md`.
 
 | Surface                      | Headless                                   | UIKit                                    |
 | ---------------------------- | ------------------------------------------ | ---------------------------------------- |
@@ -161,7 +161,7 @@ This matrix is intentionally short and exists to prevent drift between `packages
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no @statx/\* in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/components/combobox.md

@@ -405,7 +405,7 @@ UIKit adapter will:
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no @statx/\* in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/components/command-palette.md

@@ -79,7 +79,7 @@
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no @statx/\* in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/components/context-menu.md

@@ -544,7 +544,7 @@ All menu keyboard handling is no-op when the menu is closed.
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no @statx/\* in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/components/copy-button.md

@@ -17,6 +17,8 @@
 | `feedbackDuration` | `number`                                                  | `1500`                | Milliseconds to show success/error before reverting to idle (clamped >= 0)             |
 | `isDisabled`       | `boolean`                                                 | `false`               | Whether the button starts in a disabled state                                          |
 | `ariaLabel`        | `string \| undefined`                                     | `undefined`           | Accessible label for the button (e.g., `'Copy password'`)                              |
+| `successLabel`     | `string \| undefined`                                     | `'Copied'`            | Accessible/status label used after successful copy                                     |
+| `errorLabel`       | `string \| undefined`                                     | `'Copy failed'`       | Accessible/status label used after copy failure                                        |
 | `onCopy`           | `(value: string) => void \| undefined`                    | `undefined`           | Called on successful copy with the resolved value                                      |
 | `onError`          | `(error: unknown) => void \| undefined`                   | `undefined`           | Called when copy fails with the error                                                  |
 | `clipboard`        | `{ writeText(text: string): Promise<void> } \| undefined` | `navigator.clipboard` | Injectable clipboard adapter for testing and environments without native clipboard API |
@@ -80,8 +82,8 @@ type CopyButtonStatus = 'idle' | 'success' | 'error'
 **`aria-label` resolution:**
 
 - If `options.ariaLabel` is set and status is `'idle'`: returns `ariaLabel` as-is
-- If `options.ariaLabel` is set and status is `'success'`: returns `'Copied'`
-- If `options.ariaLabel` is set and status is `'error'`: returns `'Copy failed'`
+- If `options.ariaLabel` is set and status is `'success'`: returns `successLabel` or `'Copied'`
+- If `options.ariaLabel` is set and status is `'error'`: returns `errorLabel` or `'Copy failed'`
 - If `options.ariaLabel` is not set: `aria-label` is omitted (consumer provides labeling externally)
 
 #### `CopyStatusProps` shape
@@ -240,6 +242,8 @@ This section defines what UIKit (`cv-copy-button`) binds to from the headless mo
 | `feedback-duration` | `feedbackDuration` | Numeric attribute, defaults to `1500`                                                                |
 | `disabled`          | `isDisabled`       | Boolean attribute                                                                                    |
 | `aria-label`        | `ariaLabel`        | Labeling                                                                                             |
+| `success-label`     | `successLabel`     | Localized success feedback label supplied by adapters                                                |
+| `error-label`       | `errorLabel`       | Localized error feedback label supplied by adapters                                                  |
 
 ### UIKit-only concerns (NOT in headless)
 
@@ -278,7 +282,7 @@ This section defines what UIKit (`cv-copy-button`) binds to from the headless mo
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no `@statx/*` in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/components/dialog.md

@@ -287,7 +287,7 @@ UIKit adapters MUST bind to the headless model as follows:
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no `@statx/*` in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/components/disclosure.md

@@ -244,7 +244,7 @@ UIKit adapters MUST bind to the headless model as follows:
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no @statx/\* in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/components/drawer.md

@@ -339,7 +339,7 @@ UIKit adapters MUST bind to the headless model as follows:
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no `@statx/*` in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.
 - **Composition**: `createDrawer` wraps `createDialog`; no duplication of dialog internals.

package/specs/components/feed.md

@@ -251,7 +251,7 @@ UIKit adapters MUST bind to the headless model as follows:
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no @statx/\* in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/components/grid.md

@@ -173,7 +173,7 @@ UIKit (or any rendering adapter) must:
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom only; no @statx/\* in headless core.
+- **Runtime Policy**: Reatom only; no legacy state runtime 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.

package/specs/components/input.md

@@ -238,7 +238,7 @@ UIKit (`cv-input`) binds to the headless contract as follows:
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no @statx/\* in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/components/landmarks.md

@@ -125,7 +125,7 @@ UIKit adapters MUST bind to the headless model as follows:
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no `@statx/*` in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/components/link.md

@@ -121,7 +121,7 @@ UIKit (`cv-link`) binds to the headless contract as follows:
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no @statx/\* in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/components/listbox.md

@@ -340,7 +340,7 @@ UIKit adapter will:
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no @statx/\* in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/components/menu-button.md

@@ -64,7 +64,7 @@
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no @statx/\* in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/components/menu.md

@@ -609,7 +609,7 @@ UIKit adapter (`cv-menu`) will:
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no @statx/\* in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/components/meter.md

@@ -137,7 +137,7 @@ A default slot is supported in the UIKit layer for custom label content inside t
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no @statx/\* in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/components/number.md

@@ -375,7 +375,7 @@ UIKit reads `state.draftText()` and `state.value()` to determine what to display
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no @statx/\* in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime in headless core.
 - **Layering**: core -> interactions -> a11y-contracts -> adapters; adapters remain thin mappings. The number module sits in the interactions layer, composing the spinbutton core.
 - **Independence**: No imports from @project/_, apps/_, or other out-of-package modules. Only imports from `../spinbutton` (intra-package) and `@reatom/core`.
 - **Composition**: `createNumber` internally creates a `createSpinbutton` instance. It does NOT duplicate spinbutton logic.

package/specs/components/popover.md

@@ -238,7 +238,7 @@ UIKit adapters MUST bind to the headless model as follows:
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no `@statx/*` in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/components/progress.md

@@ -175,7 +175,7 @@ Note: `increment()` and `decrement()` are available for programmatic use but hav
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no `@statx/*` in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/components/radio-group.md

@@ -139,7 +139,7 @@ UIKit adapter (`cv-radio-group` + `cv-radio`) will:
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no @statx/\* in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/components/select.md

@@ -132,7 +132,7 @@ UIKit adapter will:
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no @statx/\* in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/components/sidebar.md

@@ -306,7 +306,7 @@ UIKit adapters MUST bind to the headless model as follows:
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no `@statx/*` in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.
 - **Composition**: `createSidebar` composes `createDialog` for mobile overlay mode; no duplication of dialog internals.

package/specs/components/slider-multi-thumb.md

@@ -66,7 +66,7 @@ It handles multi-value state, thumb collision/crossing prevention, and independe
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no @statx/\* in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/components/slider.md

@@ -72,7 +72,7 @@ It handles range constraints, step increments, and standard keyboard navigation
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no @statx/\* in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/components/spinbutton.md

@@ -128,7 +128,7 @@ Range semantics:
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no @statx/\* in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/components/spinner.md

@@ -118,7 +118,7 @@ This section defines what UIKit (`cv-spinner`) binds to from the headless model.
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no `@statx/*` in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/components/switch.md

@@ -162,7 +162,7 @@ UIKit adapter (`cv-switch`) will:
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no @statx/\* in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/components/table.md

@@ -388,7 +388,7 @@ UIKit adapter will:
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no @statx/\* in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/components/tabs.md

@@ -252,7 +252,7 @@ This section lists exactly what the UIKit adapter layer binds to.
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no @statx/\* in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/components/textarea.md

@@ -172,7 +172,7 @@ UIKit (`cv-textarea`) binds to the headless contract as follows:
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no @statx/\* in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime in headless core.
 - **Layering**: core/interactions/a11y-contracts/adapters boundaries preserved.
 - **Independence**: no monorepo app imports.
 - **Verification**: standalone headless tests via package command.

package/specs/components/toast.md

@@ -183,7 +183,7 @@ UIKit adapters MUST bind to the headless model as follows:
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no @statx/\* in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/components/toolbar.md

@@ -264,7 +264,7 @@ This section lists exactly what the UIKit adapter layer binds to.
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no @statx/\* in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/components/tooltip.md

@@ -240,7 +240,7 @@ Headless adapters (e.g., the UIKit `cv-tooltip` web component, React wrappers) M
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no @statx/\* in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/components/treegrid.md

@@ -266,7 +266,7 @@ Note: `getCellProps` includes an `onFocus` handler that must be wired to the cel
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no @statx/\* in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/components/treeview.md

@@ -78,7 +78,7 @@ In multiple-select mode (`selectionMode: 'multiple'`), focus and selection remai
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no @statx/\* in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/components/window-splitter.md

@@ -282,7 +282,7 @@ The UIKit adapter reads `snap` and `snapThreshold` from element attributes (or c
 
 ## ADR-001 Compliance
 
-- **Runtime Policy**: Reatom v1000 only; no `@statx/*` in headless core.
+- **Runtime Policy**: Reatom v1001 only; no legacy state runtime 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.

package/specs/ops/git-shard-sync.md

@@ -4,7 +4,7 @@
 
 This document defines the operational sync flow between:
 
-- monorepo mirror: `packages/headless`
+- monorepo mirror: `packages/headless-ui`
 - canonical public repository: git-shard
 
 It implements `HLS-001` and supports ADR-001/ADR-002.
@@ -22,7 +22,7 @@ Use this when changes were developed inside monorepo and must be promoted to can
 
 ### Preconditions
 
-1. changes are limited to `packages/headless/**`
+1. changes are limited to `packages/headless-ui/**`
 2. local checks pass:
    - `npm run lint`
    - `npm run test`
@@ -58,7 +58,7 @@ Use this after shard releases or direct shard-first development.
 
 1. create monorepo branch:
    - naming: `sync/shard-YYYYMMDD-<tag-or-topic>`
-2. copy/sync shard files into `packages/headless`
+2. copy/sync shard files into `packages/headless-ui`
 3. run mirror checks:
    - `npm run lint`
    - `npm run test`
@@ -100,7 +100,7 @@ If a critical bugfix is required:
 
 Before any sync merge:
 
-- [ ] scope limited to `packages/headless/**`
+- [ ] scope limited to `packages/headless-ui/**`
 - [ ] lint/test checks are green
 - [ ] no forbidden imports
 - [ ] source and destination references documented

package/specs/release/GAP-TO-GREEN-ISSUES.md

@@ -7,7 +7,7 @@ This file provides issue-ready tickets for the remaining work before stable rele
 ## How to Use
 
 - copy each issue into tracker as a standalone task
-- keep scope limited to `packages/headless/**` unless issue says otherwise
+- keep scope limited to `packages/headless-ui/**` unless issue says otherwise
 - require evidence links for CI runs and docs updates
 
 Common labels:
@@ -26,7 +26,7 @@ Common labels:
 - **Labels**: `headless`, `release`, `governance`, `ci`
 - **Scope**: add an automated gate that validates SemVer classification in release PR metadata
 - **Deliverables**:
-  - release-governance check script in `packages/headless/scripts/`
+  - release-governance check script in `packages/headless-ui/scripts/`
   - CI workflow job that runs the check for release PR context
 - **Acceptance Criteria**:
   - release PR without explicit SemVer classification fails CI
@@ -54,7 +54,7 @@ Common labels:
 - **Labels**: `headless`, `tests`, `a11y`
 - **Scope**: add component-level integration tests validating adapter-style bindings for keyboard/pointer flows
 - **Deliverables**:
-  - adapter integration tests under `packages/headless/src/adapters/`
+  - adapter integration tests under `packages/headless-ui/src/adapters/`
 - **Acceptance Criteria**:
   - tests validate `model -> bindings -> events -> state` flow
   - tests cover keyboard and pointer paths
@@ -67,8 +67,8 @@ Common labels:
 - **Labels**: `headless`, `docs`
 - **Scope**: align README and ADR-001 metadata with implemented state of package
 - **Deliverables**:
-  - `packages/headless/README.md` updated with all implemented components and structure
-  - `packages/headless/specs/ADR-001-headless-architecture.md` status/version update
+  - `packages/headless-ui/README.md` updated with all implemented components and structure
+  - `packages/headless-ui/specs/ADR-001-headless-architecture.md` status/version update
 - **Acceptance Criteria**:
   - README no longer describes listbox as the only current example
   - ADR-001 status reflects accepted architecture baseline
@@ -79,7 +79,7 @@ Common labels:
 - **Status**: Open
 - **Priority**: High
 - **Labels**: `headless`, `ci`, `release`
-- **Scope**: add root CI job that runs package-specific lint and tests for `packages/headless`
+- **Scope**: add root CI job that runs package-specific lint and tests for `packages/headless-ui`
 - **Deliverables**:
   - root workflow update with headless package job
 - **Acceptance Criteria**:

package/specs/release/mvp-changelog.md

@@ -26,8 +26,8 @@ Data and composite widgets (latest tranche):
 
 Full implemented surface at this point (30 patterns) is reflected in:
 
-- `packages/headless/src/index.ts`
-- `packages/headless/README.md`
+- `packages/headless-ui/src/index.ts`
+- `packages/headless-ui/README.md`
 
 ## Testing and APG Hardening
 

package/specs/release/release-rehearsal.md

@@ -15,7 +15,7 @@ It defines a deterministic dry-run sequence for shard release preparation and re
 
 ## Deterministic Command Sequence
 
-Run in `packages/headless`:
+Run in `packages/headless-ui`:
 
 1. `npm run lint`
 2. `npm run test`

package/specs/signals.md

@@ -136,7 +136,7 @@ If you use a signal-aware base element (for example an XLit-style base),
 this gives automatic dependency tracking.
 
 ```ts
-class ListboxView extends XLitElement {
+class ListboxView extends ReatomLitElement {
   model = createListbox()
 
   render() {