@pienter/ui 0.3.0 → 0.7.1

package/CONVENTIONS.md

@@ -47,8 +47,7 @@ components/<category>/<module>/
 The categories are `action`, `display`, `feedback`, `form`, `layout`,
 `navigation`, and `overlay`. Cross-module implementation imports use these
 categorized paths. Package consumers use the explicit flat exports instead,
-for example `@pienter/ui/components/Button.vue` or
-`@pienter/ui/components/Button.astro`. Category paths, colocated CSS, and
+for example `@pienter/ui/components/Button.vue`. Category paths, colocated CSS, and
 private helpers are not public package entrypoints.
 
 ## Multi-component-per-directory exception
@@ -64,7 +63,6 @@ Current consumers:
 Rules:
 
 - The shared CSS file MUST be named after the shared visual concept (`avatar.css`, `select.css`)
-- All co-located components MUST be in the same Astro tier
 - Each component file has a separate flat public import (`@pienter/ui/components/Avatar.vue` and `@pienter/ui/components/AvatarStack.vue`)
 - Each component still has its own entry in the directory's `AUDIT.md`
 - New components SHOULD live in their own directory unless they meet the tightly-coupled-visual-sibling-family bar (i.e., this exception isn't a default — it's earned)
@@ -104,7 +102,7 @@ Variants and runtime states live on `data-*` attributes on the block element, ne
 | `data-animation`   | Continuous decorative animation on the block                                                                                                               | `spin` (Icon)                                                                         |
 | `data-tone`        | Semantic tone for non-variant components (Alert, Badge, Toast)                                                                                             | `brand`, `success`, `warning`, `danger`                                               |
 | `data-block`       | Block-level layout flag (boolean)                                                                                                                          | `'true'` or absent                                                                    |
-| `data-state`       | Runtime state controlled by code or controller                                                                                                             | `loading`, `open`, `closed`, `checked`, `indeterminate`                               |
+| `data-state`       | Runtime state controlled by code or a behavior composable                                                                                                  | `loading`, `open`, `closed`, `checked`, `indeterminate`                               |
 | `data-status`      | Derived semantic status for form primitives (validation outcome)                                                                                           | `error`, `success`                                                                    |
 | `data-layout`      | Form-primitive scaffold layout selector — lives on `.pui-field`; flips between stacked label-above (default) and compact inline control-left + label-right | `stacked` (default; attribute may be omitted), `inline`                               |
 | `data-orientation` | Layout direction for grouped controls (RadioGroup items, future SegmentedControl, etc.) — lives on the group container                                     | `vertical` (default for RadioGroup), `horizontal`                                     |
@@ -114,7 +112,7 @@ The example values listed for each attribute are non-exhaustive — components a
 **`data-state` vs `data-status`** — both attributes describe how a component
 "is right now," but they have different sources:
 
-- `data-state` is **runtime UI state** — owned by code or a controller, driven
+- `data-state` is **runtime UI state** — owned by code or a behavior composable, driven
   by interaction (`loading` while a request is in flight, `open`/`closed` for a
   disclosure, `checked`/`indeterminate` for a toggle). It usually changes in
   response to user input or async work.
@@ -186,9 +184,8 @@ A component that wraps a single native HTML element (`<button>`, `<input>`, `<a>
 - [ ] Loading state: emit `disabled` (or `aria-disabled` + `tabindex="-1"`
       for `<a>`) AND `aria-busy="true"` AND `data-state="loading"` AND a
       visually-rendered spinner element with `aria-hidden="true"`.
-- [ ] Forwards arbitrary attributes via `...rest` (Astro) / inheritAttrs
-      (Vue) so consumers can attach `id`, `name`, event listeners, ARIA
-      labels.
+- [ ] Forwards arbitrary attributes via `inheritAttrs` fallthrough so
+      consumers can attach `id`, `name`, event listeners, ARIA labels.
 
 **Worked example — Button**: see `packages/ui/components/action/button/`. Polymorphic `<button>`/`<a>` via `href`, variants/size/block/state on `data-*`, loading state via `aria-busy` + `data-state="loading"` + `<span class="pui-btn__spinner">` element.
 
@@ -260,8 +257,8 @@ role="alert">` with one `<li>` per error message, only when errors are
       etc. so the same selector pattern works across every form primitive.
       `data-status` is derived: if a `status` prop is set, use it; otherwise
       derive `error` from a non-empty errors array.
-- [ ] Forwards remaining attributes onto the control element (Astro: `...rest`,
-      Vue: `inheritAttrs` defaults), so consumers can attach `name`,
+- [ ] Forwards remaining attributes onto the control element via
+      `v-bind="$attrs"`, so consumers can attach `name`,
       `autocomplete`, `inputmode`, event listeners, ARIA labels, etc.
 
     **Declared props are stripped from `$attrs`** — when a Vue component
@@ -329,7 +326,7 @@ of where the file lives.
 ### Pure-markup with slots
 
 Locked during Phase 1 alongside Card (2026-05-03). A component that renders
-styled markup with **no behavior, no controller, no native form semantics**.
+styled markup with **no behavior, no composable wiring, no native form semantics**.
 Variants drive visual style via `data-variant` / `data-tone`; content flows
 in through slots (default and/or named). The component is essentially a
 named CSS chunk wrapped in a framework primitive so consumers don't have to
@@ -345,7 +342,7 @@ remember the wrapper class.
       see "Slot vs prop conventions" below.
 - [ ] Variants and tones expressed via `data-variant` or `data-tone` per the
       locked rules; no per-variant class names.
-- [ ] No JS — no controllers, no event listeners, no reactive state. If a
+- [ ] No JS — no behavior composables, no event listeners, no reactive state. If a
       pure-markup component grows behavior (loading, dismiss, expand), it
       graduates to one of the other archetypes and the audit entry is updated.
 - [ ] No ARIA roles **unless the component carries semantic meaning the
@@ -356,15 +353,14 @@ remember the wrapper class.
       consumer use **inside** the slot content (Card's `pui-card__title`,
       `pui-card__eyebrow`, etc.), document those classes in the audit entry
       as **public API**. Renaming or removing them is a breaking change.
-- [ ] Vue uses the default `inheritAttrs: true` (the wrapper IS the only
+- [ ] Uses the default `inheritAttrs: true` (the wrapper IS the only
       element) so consumer-supplied `id`, `class`, `aria-*`, and event
-      listeners land on the wrapper. Astro spreads `...rest` on the wrapper
-      to the same effect.
+      listeners land on the wrapper.
 
 **Worked example — Card**: see `packages/ui/components/layout/card/`. Renders a
 single `<div class="pui-card" data-variant>` with a default slot. Variants
 on `data-variant` (`bordered`, `brand`, `muted`); no ARIA role; no
-controller. Public child classes — `pui-card`, `pui-card__eyebrow`,
+behavior wiring. Public child classes — `pui-card`, `pui-card__eyebrow`,
 `pui-card__title`, `pui-card__body`, `pui-card__meta`, `pui-card__footer` — are
 applied by consumers to their own markup inside the slot.
 
@@ -408,71 +404,69 @@ pattern. Sidebar is the v1 reference; future Menubar / NavigationMenu
       items.
 - [ ] Recursion (when items can nest, e.g. Sidebar groups) is handled
       inside the component — the consumer always passes a single flat
-      `items` array, even when items are deep trees. In Vue this is
-      typically an internal recursive `<SidebarItemRender>` component
-      that is **not exported** (private to the parent file). In Astro
-      it is a recursive `.astro` component (see worked Sidebar example
-      below) — also private.
+      `items` array, even when items are deep trees. This is
+      typically an internal recursive `<SidebarMenuItem>` component
+      that is **not exported** (private to the parent module).
 - [ ] State that the consumer might want to control (collapsed/expanded
       shell, drawer open/closed, expanded group set) flows through
-      props + `v-model` / `update:*` events; runtime state is owned by
-      a controller (per the Stateful-component archetype).
+      props + `v-model` / `update:*` events; runtime side-effects are
+      owned by a behavior composable (per the Stateful-component
+      archetype).
 
 **Worked example — Sidebar**: see `packages/ui/components/navigation/sidebar/`.
-Hybrid: `:items` drives the menu (with the `link | group | section`
-discriminated union from `sidebar/types.ts`); `#brand` and `#footer`
+Hybrid: `:top-items` and `:bottom-items` drive the two nav regions (with
+the `link | group | section` discriminated union from
+`sidebar/types.ts`); `#brand` and `#bottom`
 slots cover decorative regions. Active-state derived from
 `:active-href` via the hierarchical-match algorithm (below). The
-recursive item rendering lives in a private `SidebarItemRender.vue`
-(Vue) and `SidebarItemRender.astro` (Astro). Runtime state — desktop
-collapse, mobile drawer, per-group expand — owned by `mountSidebar`
-in `controllers/sidebar.ts`.
+recursive item rendering lives in a private `SidebarMenuItem.vue`.
+Runtime state — desktop collapse, mobile drawer, per-group expand —
+follows the D13 layered split: shared primitives in
+`utils/navigation/sidebar.ts`, reactive orchestration inside
+`Sidebar.vue`.
 
 ### Form orchestration
 
 Locked during Phase 2 alongside Form (2026-05-03). Form is the **orchestrator**: it does not render a control of its own. Its job is to wire submit handling, run client-side validators, render error chrome (top-level summary + per-field), apply success state, and coordinate the submit busy lifecycle. The form-primitive wrappers (TextInput, Textarea, Switch, Checkbox, RadioGroup, Select, NumberField, DateInput) are the **fields**; Form orchestrates them.
 
-**Layered split** — three layers, locked per design D13:
+**Layered split** — two layers, locked per design D13:
 
-1. **Shared primitives** (used by both Vue and Astro):
+1. **Shared primitives** (framework-agnostic):
     - `utils/validation/rules.ts` — pure validators (`isRequired`, `isEmail`, `minLength`, …).
     - `utils/validation/form.ts:validateFormData(formData, validators)` — runs validators against `FormData`, returns `Record<string, string[]>`. Pure, framework-agnostic.
     - `utils/validation/form.ts:normalizeFieldErrors(map)` — normalizes the `string | string[]` per-field shape from `FormSubmitResponse` to `string[]`.
     - `utils/a11y/focus.ts:focusFirstInvalid(formEl)` — DOM-imperative focus helper.
     - `utils/a11y/live-region.ts:announce(text, priority)` — DOM-imperative announcement.
-2. **Astro form controller** — `controllers/form.ts:mountForm(el, config) → teardown`. Full imperative orchestration: intercept submit, run validators, render per-field + summary errors, set `aria-busy`, await `onSubmit`, map response to UI, focus first invalid + announce. Astro's only orchestration path.
-3. **Vue Form orchestration** — lives **inside `Form.vue`** using Vue reactive idioms (refs, watch effects, computed). Calls the shared primitives directly. Does **NOT** wrap `mountForm` — wrapping an imperative DOM controller from Vue fights Vue's data flow (controller mutates the DOM, Vue patches it back, race conditions ensue).
+2. **Form orchestration** — lives **inside `Form.vue`** using Vue reactive idioms (refs, watch effects, computed). Calls the shared primitives directly. Does **NOT** wrap an imperative DOM controller — that fights Vue's data flow (controller mutates the DOM, Vue patches it back, race conditions ensue).
 
-**Why two implementations**: forcing a single shared controller means either (a) Vue wraps imperative DOM (loses reactive benefits), or (b) primitives become so abstract they're not really doing the work. Layered split keeps each implementation idiomatic while sharing the expensive parts (validators, focus management, announcement) and the response contract.
+**Why the split**: pushing the orchestration into a shared controller means Vue wraps imperative DOM and loses its reactive benefits; pushing everything into the SFC buries the expensive parts (validators, focus management, announcement) where they can't be tested or reused. The layered split keeps the orchestration idiomatic while the primitives stay pure.
 
-**Consumer responsibility — Vue vs Astro**:
+**Consumer responsibility**:
 
-| Concern                     | Vue (`Form.vue`)                                                                                | Astro (`mountForm`)                                                                               |
-| --------------------------- | ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
-| Per-field error display     | Consumer wires `:errors` on each form-primitive child from `props.fieldErrors[name]`            | Controller writes per-field errors into the field's `pui-field__hint` element automatically       |
-| `aria-busy` during submit   | Consumer flips `:busy` prop on `<Form>` after async submit completes                            | Controller sets/removes `aria-busy` automatically                                                 |
-| Status message              | Consumer sets `:status-message` prop on `<Form>`                                                | Controller renders `statusMessage` from response automatically                                    |
-| Server `errors` (top-level) | Consumer sets `:errors` prop on `<Form>`                                                        | Controller renders `response.errors` automatically                                                |
-| Throw vs `{ ok: false }`    | Consumer's submit handler runs in parent; throwing is the consumer's exception-handling concern | Controller catches `onSubmit` throws and translates to `{ ok: false, errors: ['Submit failed'] }` |
+| Concern                     | Consumer responsibility (`Form.vue`)                                                            |
+| --------------------------- | ----------------------------------------------------------------------------------------------- |
+| Per-field error display     | Consumer wires `:errors` on each form-primitive child from `props.fieldErrors[name]`            |
+| `aria-busy` during submit   | Consumer flips `:busy` prop on `<Form>` after async submit completes                            |
+| Status message              | Consumer sets `:status-message` prop on `<Form>`                                                |
+| Server `errors` (top-level) | Consumer sets `:errors` prop on `<Form>`                                                        |
+| Throw vs `{ ok: false }`    | Consumer's submit handler runs in parent; throwing is the consumer's exception-handling concern |
 
 **Error display rules**:
 
-- Per-field errors land in the form-primitive's `pui-field__hint role="alert"` element, set `aria-invalid="true"` on the control, set `data-status="error"` on the wrapper. Vue: consumer wires `:errors` on each form-primitive child (typical Vue data flow). Astro: `mountForm` mutates the `pui-field` wrapper imperatively, marking the injected error list with `data-pui-form-errors="true"` so a future re-run can clear it without touching consumer-supplied static error markup.
+- Per-field errors land in the form-primitive's `pui-field__hint role="alert"` element, set `aria-invalid="true"` on the control, set `data-status="error"` on the wrapper. The consumer wires `:errors` on each form-primitive child (typical Vue data flow).
 - Top-level errors (`response.errors[]` or consumer-supplied `:errors` prop) land in `.pui-form__error-summary` at the top of the form, with `role="alert"` and `aria-live="assertive"`.
 - Success: `statusMessage` renders inside `.pui-form__status` with `aria-live="polite"`, and is also announced via the global ARIA live region by the shared `announce()` primitive.
 
 **Submit lifecycle**:
 
 1. `submit` event → `event.preventDefault()`. Read `FormData`.
-2. Run client-side validators. If any fail: render field errors, set `aria-invalid` on each invalid control, focus first invalid, announce error count assertively. Do NOT call `onSubmit`. (Vue emits `validation-error` for telemetry.)
-3. If validation passes: clear errors, set `aria-busy="true"` on form, disable submit button, call `await onSubmit(data)` (Vue: emit `submit`; Astro: await `config.onSubmit`).
+2. Run client-side validators. If any fail: render field errors, set `aria-invalid` on each invalid control, focus first invalid, announce error count assertively. Do NOT call `onSubmit`. (Form emits `validation-error` for telemetry.)
+3. If validation passes: clear errors, set `aria-busy="true"` on form, disable submit button, hand off to the consumer's submit handler (emit `submit` with the data).
 4. After `onSubmit` returns: clear `aria-busy`, re-enable submit. Map response — `ok: false` → render server `fieldErrors` + top-level `errors`, focus first invalid, announce; `ok: true` → render `statusMessage`, announce politely.
 
 **Disable propagation**: when Form's `busy` is `true`, child form-primitives do NOT auto-disable. The Form-level busy state controls the submit button only. Disabling other fields/buttons inside the form (e.g. a "Cancel" button) is the consumer's call — a Form-wide busy state shouldn't block dismiss affordances.
 
-**Astro consumer pattern (locked)**: `Form.astro` renders chrome only. The consumer mounts `mountForm` from a `<script>` block colocated with the form markup. This is intentional: `validators` (functions) and `onSubmit` (async function) cannot be passed as Astro props. The consumer-writes-the-mount-script pattern is verbose but explicit, and matches how real product surfaces will wire up server-driven validation + redirect handling.
-
-**Worked example — Form**: see `packages/ui/components/form/form/` and `packages/ui/utils/controllers/form.ts`. Vue uses reactive refs + watch effects; Astro uses `mountForm` from a consumer `<script>` block. Both consume the placeholder `FormSubmitResponse` shape and call the shared `focusFirstInvalid`, `announce`, and `validateFormData` primitives.
+**Worked example — Form**: see `packages/ui/components/form/form/`. Reactive refs + watch effects consume the placeholder `FormSubmitResponse` shape and call the shared `focusFirstInvalid`, `announce`, and `validateFormData` primitives.
 
 ### Active-href hierarchical-match algorithm
 
@@ -544,7 +538,7 @@ because the component places each in a fixed DOM position. Examples:
 - Modal's `#footer` (placed below the body, inside the dialog content,
   styled as the action bar)
 - Nav's `#actions` (placed at the trailing edge of the navbar)
-- Sidebar's `#brand` and `#footer` (header / footer regions of the layout
+- Sidebar's `#brand` and `#bottom` (header / foot regions of the layout
   shell, deferred to Sidebar)
 - AlertDialog's actions slot (deferred to Phase 4)
 
@@ -617,159 +611,202 @@ component.
 
 ---
 
-## Controller mount-on-element pattern
+## Choosing an orchestration pattern
+
+See ADR 0007 for the reasoning and the failure modes that produced this rule.
+
+Two patterns, and the choice is not a matter of taste. What differs is who
+owns the DOM.
+
+**A — Shared behavior composable** (`packages/ui/composables/`, below).
+One composable, called at setup time with the element ref; it wires its
+own lifecycle (`onMounted` / `onBeforeUnmount`). The composable owns the
+runtime side-effects; the component stays a thin trigger source.
+
+**B — Layered split** (D13, see _Form orchestration_ above). Shared _pure_
+primitives, and reactive orchestration inside the SFC that derives its
+answers from them — one source of truth for the answers.
+
+Reach for **B** when the component's runtime state is also _rendered_ state
+— attributes, classes, visibility, inline geometry that the template would
+otherwise want to bind. Under **A** those have two owners: the composable
+writes them imperatively and Vue patches them back. That race is not
+hypothetical; it is
+what D13 was written about, and re-litigating it cost Sidebar a string of
+bugs (a `focusin` handler silently rewriting every `tabindex`, `hidden`
+fighting `visibility`, a flyout's state attribute set from two directions).
+
+Stay with **A** when the composable owns things Vue never renders: focus
+traps, scroll locks, top-layer/`<dialog>` mechanics, `popover` wiring,
+event plumbing on `window` or `document`. A shared composable that never
+touches rendered state cannot race with the framework.
+
+Practical test: _would Vue want to `v-bind` this?_ If yes, it belongs in
+the template, and the component wants **B**.
+
+### Current assignments
+
+- **B (layered split)** — Form (D13, 2026-05-03), Sidebar (ADR 0007,
+  2026-08-27).
+- **A (shared composable)** — everything else listed below.
+
+The rest have not been assessed against this rule, let alone migrated.
+Several of them are legitimately **A** — the `<dialog>` and Popover-API
+families barely touch rendered state. Treat the list below as the current
+state of the codebase, not as a claim that each entry was chosen
+deliberately.
+
+---
+
+## Composable behavior pattern
 
-Locked during Phase 1 alongside Modal (2026-05-03). Stateful components (Modal,
-AlertDialog, Sheet, Toast, Popover, Tooltip, DropdownMenu, Combobox, Command,
-Accordion, Collapsible, plus per-input controllers — NumberField, TagsInput,
-InputOTP, Slider, Sidebar) are wired through a controller in
-`packages/ui/utils/controllers/`. The controller owns the runtime state
-machine; the framework (Vue or an Astro `<script>` block) acts as the trigger
-source.
+Locked during Phase 1 alongside Modal (2026-05-03) as the controller
+mount-on-element pattern; migrated to Vue composables in 2026-08. This is
+pattern **A** above. Stateful components (Modal, AlertDialog, Sheet,
+Popover, Tooltip, DropdownMenu, Combobox, Command, Accordion, Collapsible)
+are wired through a behavior composable in `packages/ui/composables/`. The
+composable owns the runtime side-effects; the Vue component acts as the
+trigger source.
 
-### Default signature — teardown-only
+`packages/ui/composables/` holds shared behavior composables — Vue code
+that owns DOM side-effects for more than one component. A single
+component's reactive orchestration is not a behavior composable and does
+not live there — Sidebar's lives inside `Sidebar.vue`.
 
-For controllers whose lifecycle is mount → teardown without runtime
-imperative methods (e.g., `controllers/form.ts:mountForm`,
-per-input mounts), the canonical signature is:
+### Default signature — void, self-cleaning
+
+Every behavior composable takes the element ref plus an options object at
+setup time, wires its listeners in `onMounted`, and removes them in
+`onBeforeUnmount`. There are no teardown functions to store and no
+control objects to null — Vue's lifecycle owns the cleanup. For behavior
+with no imperative methods (`useDisclosure`, `useMenu`), the canonical
+signature returns nothing:
 
 ```ts
-export function mount<Name>(element: HTMLElement, config?: <Config>): () => void
+export function use<Name>(
+    elRef: Ref<HTMLElement | null>,
+    options?: Use<Name>Options,
+): void;
 ```
 
-The returned function tears down all listeners, observers, and DOM mutations
-introduced by the controller. Astro components invoke from a `<script>`
-block; Vue components invoke from `onMounted` and call the teardown from
-`onBeforeUnmount`.
+Components call the composable directly in `<script setup>`; they never
+touch `onMounted` / `onBeforeUnmount` for it.
 
-### Stateful-component signature — control object
+### Stateful-component signature — handle
 
-For stateful components with imperative open/close (or show/hide / expand)
-methods — Modal, AlertDialog, Sheet, Toast, Popover, Tooltip, DropdownMenu,
-Combobox, Accordion, Collapsible — the controller returns a **control
-object** instead of a bare teardown function:
+For stateful components with imperative open/close (or show/hide)
+methods, the composable additionally returns a **handle**:
 
 ```ts
-interface DialogControl {
+export interface DialogHandle {
     open(): void;
     close(): void;
     isOpen(): boolean;
-    teardown(): void;
 }
 
-export function mountDialog(
-    element: HTMLElement,
-    config?: DialogConfig,
-): DialogControl;
+export function useDialog(
+    elRef: Ref<HTMLDialogElement | null>,
+    options?: UseDialogOptions,
+): DialogHandle;
 ```
 
-The control object collapses the dialog's state machine to a single source of
-truth. Frameworks call `control.open()` / `control.close()` and observe the
-controller-owned `data-state` attribute; they do not duplicate the state
-machine in reactive props. This avoids the dual-state-machine problem where
-Vue's `props.open` and a controller's internal state desync after a slow
-async transition.
-
-The framework's reactive prop is the **trigger source** — it tells the
-controller "I want to be open now"; the controller is the **state machine** —
-it owns the focus trap, scroll lock, portal placement, and the rendered
+(`usePopover` returns `{ show, hide, toggle, isOpen, reposition }`.)
+There is no `teardown()` on the handle — cleanup runs automatically in
+`onBeforeUnmount`, which closes the overlay first if it is still open so
+listeners and scroll locks are released.
+
+The handle collapses the dialog's runtime side-effects to a single source
+of truth. The DOM is the source of truth for whether the overlay is open
+(`el.open` for `<dialog>`, `:popover-open` for popovers — `isOpen()` reads
+it); the composable does not duplicate that state in reactive refs. This
+avoids the dual-state-machine problem where Vue's `props.open` and an
+internal state flag desync after a slow async transition.
+
+The component's reactive prop is the **trigger source** — the composable's
+controlled `open` option is a getter (`open: () => props.open`) that is
+applied on mount and watched thereafter (`true` opens, `false` closes,
+`undefined` is ignored). The composable is the **state machine** — it owns
+the focus handling, scroll lock, positioning, and the rendered
 `data-state`. The `onClose` callback closes the loop on user-initiated
-close (Escape, backdrop click): the controller invokes `onClose`, the
-framework reflects it back through its prop / `update:modelValue`, and the
-prop watcher then calls `control.close()` — single source of truth in the
-framework's reactive layer, single source of truth in the controller's
-imperative layer, no duplication.
-
-`teardown()` is mandatory on every control object — it must release
-listeners, focus traps, scroll locks, restore portaled DOM, and null all
-internal references. Calling `teardown()` while `isOpen()` is `true` MUST
-internally call `close()` first so resources don't leak.
+close (Escape, backdrop click, light-dismiss): the composable invokes
+`onClose` to report the intent, the component reflects it back through its
+prop / `update:modelValue`, and the watched `open` getter then performs
+the actual close — single source of truth in the component's reactive
+layer, single source of truth in the DOM, no duplication.
+
+Options that can change over the component's lifetime — `persistent`,
+`placement`, `offset`, `singleOpen` — accept `MaybeRefOrGetter` and are
+read reactively via `toValue()` at use time. `usePopover`'s `anchor` is a
+`MaybeRefOrGetter<HTMLElement | null>` resolved lazily on every
+reposition, so the trigger may appear after mount.
 
 ### Singleton-style exception
 
-When a controller manages a single global resource (e.g., the Toast queue
-with one global ARIA live region), the module MAY additionally export a
-module-level API (`toast.show()`, `toast.dismiss()`). Use sparingly and
+When a behavior module manages a single global resource (e.g., the Toast
+queue with one global ARIA live region), the module MAY additionally export
+a module-level API (`toast.show()`, `toast.dismiss()`). Use sparingly and
 document the exception here when added.
 
-### When to share a controller vs write a new one
+### When to share a composable vs write a new one
 
-Controllers are SHARED when component variants differ only in
+Composables are SHARED when component variants differ only in
 **configuration** — role, persistent flag, initial focus target, ARIA
-attributes set via `setAttribute`. Modal and AlertDialog (Phase 4) share
-`mountDialog` because the difference is `{ role: 'alertdialog', persistent:
-true, initialFocus: 'cancel' }`.
+attributes set via `setAttribute`. Modal and AlertDialog share
+`useDialog` because the difference is `{ role: 'alertdialog', persistent:
+() => true, initialFocus: 'cancel' }`.
 
-Controllers are SEPARATE when components differ in **geometry, focus rules,
+Composables are SEPARATE when components differ in **geometry, focus rules,
 or trigger semantics**:
 
-- Popover, Tooltip, DropdownMenu → their own `mountPopover` (anchor-positioned,
+- Popover, Tooltip, DropdownMenu → shared `usePopover` (anchor-positioned,
   no scroll lock, no focus trap unless a modal popover, click-outside
   dismisses by default)
-- Combobox → its own `mountCombobox` (input + listbox composition, typeahead,
-  ARIA combobox pattern)
-- Accordion + Collapsible → share a `mountDisclosure` (expand/collapse pair)
-- Sidebar drawer → `mountSidebar` (the panel is `<nav>`, not `<dialog>`,
-  so it can't share `mountDialog`; see "Use native APIs where applicable"
-  below)
-
-Sheet is NOT in this list — it shares `mountDialog` with Modal +
+- Accordion + Collapsible → share `useDisclosure` (expand/collapse pair)
+- DropdownMenu → additionally `useMenu` (menu keyboard navigation and
+  roving tabindex, composed alongside `usePopover`; each is independent
+  of the other and the component composes them)
+- Sidebar drawer → its own orchestration (the panel is `<nav>`, not
+  `<dialog>`, so it can't share `useDialog`; see "Use native APIs where
+  applicable" below). Not in `composables/` — see the D13 note below.
+
+Sheet is NOT in this list — it shares `useDialog` with Modal +
 AlertDialog. All three render `<dialog>` and only differ in CSS
-geometry (Sheet anchors to a side instead of centering). The controller
+geometry (Sheet anchors to a side instead of centering). The composable
 mechanics are identical.
 
+There is no `useCombobox` — Combobox uses `usePopover` for its listbox;
+the combobox-specific behavior (input + listbox composition, typeahead,
+the ARIA combobox pattern) lives inside the component.
+
 Listed mapping (locked):
 
-- `mountDialog` → Modal, AlertDialog, Sheet (all `<dialog>`-based; see "Use
-  native APIs where applicable" below — Sheet's slide-side geometry is a
-  CSS concern, the controller mechanics are identical)
-- `mountPopover` → Popover, Tooltip, DropdownMenu, HoverCard (all
-  Popover-API-based; deferred to Phase 4)
-- `mountCombobox` → Combobox, Command (search palette)
-- `mountDisclosure` → Accordion, Collapsible
-- `mountSidebar` → Sidebar (its own controller — desktop layout-shell
-  collapse, mobile drawer overlay, per-group expand, and roving-tabindex
-  keyboard nav are all Sidebar-specific geometry/focus-rule concerns; v1
-  owns its group expand/collapse inline and may compose into
-  `mountDisclosure` later)
-- `mountToast` → Toast (with module-level singleton API per the
-  singleton-exception rule)
-- `mountForm` → Form (Astro orchestration only; Vue uses reactive
-  idioms inside `Form.vue` and does not wrap the controller per D13).
-  Signature: `mountForm(formEl, { validators?, onSubmit?, onResult? })`
-  → teardown. Owns submit interception, client-side validation
-  kickoff, per-field + top-level error rendering, `aria-busy` lifecycle
-  management, `focusFirstInvalid` + `announce` calls, and the
-  `FormSubmitResponse` → UI mapping.
-- per-input controllers (each its own file, non-stateful
-  teardown-only signature per the canonical NumberField pattern):
-    - `mountNumberField` → NumberField
-      (`controllers/number-field.ts`). Signature:
-      `mountNumberField(wrapperEl, { onChange? })` → teardown.
-    - `mountTagsInput` → TagsInput (`controllers/tags-input.ts`).
-      Signature: `mountTagsInput(wrapperEl, { initialTags?,
-onChange?, maxTags?, separators? })` → teardown.
-    - `mountInputOTP` → InputOTP (`controllers/otp.ts`). Signature:
-      `mountInputOTP(wrapperEl, { pattern?, onChange? })` →
-      teardown.
-    - `mountSlider` → Slider (`controllers/slider.ts`). Signature:
-      `mountSlider(trackEl, { min?, max?, step?, initialValue?,
-disabled?, onChange? })` → teardown. Note: mounts on the
-      inner `.pui-slider` track element, not the outer `.pui-field`
-      scaffold (matching NumberField's mount-on-inner pattern).
-
-**Form primitives with NO controller** (markup-only with native
+- `useDialog` → Modal, AlertDialog, Sheet, Command (all `<dialog>`-based;
+  see "Use native APIs where applicable" below — Sheet's slide-side
+  geometry is a CSS concern, the composable mechanics are identical)
+- `usePopover` → Popover, Tooltip, DropdownMenu, Combobox listbox (all
+  Popover-API-based)
+- `useDisclosure` → Accordion, Collapsible
+- `useMenu` → DropdownMenu (layered on `usePopover`)
+- Sidebar → **layered split per D13**, like Form. `composables/` is
+  for shared behavior composables, and Sidebar's orchestration is reactive
+  bindings inside `Sidebar.vue`, deriving its answers from
+  `utils/navigation/sidebar.ts` (href match, group-key slug,
+  flyout geometry, submenu predicate). Desktop layout-shell collapse,
+  mobile drawer overlay, per-group expand and keyboard nav are all
+  Sidebar-specific geometry/focus-rule concerns.
+
+**Form primitives with NO behavior composable** (markup-only with native
 semantics): TextInput, Textarea (planned), Select (planned),
 **Switch**, **Checkbox**, **RadioGroup**. RadioGroup is the
 worked example of a grouped form primitive that does NOT need a
-controller — native `<input type="radio">` elements with a shared
+behavior composable — native `<input type="radio">` elements with a shared
 `name` provide arrow-key keyboard nav, single-selection, and
 Tab-focuses-selected for free; Radix's roving-tabindex
 implementation exists because Radix uses
 `<button role="radio">` rather than the native input. See the
 RadioGroup audit (`components/form/radio-group/AUDIT.md`) for the full rationale.
 
-**Press-button family with NO controller** (markup-only,
+**Press-button family with NO behavior composable** (markup-only,
 `<button aria-pressed>`-driven): **Toggle** (single press-button),
 **ToggleGroup** (multi-select press-button group), **Segmented**
 (single-select press-button group). Each native `<button>` is
@@ -785,14 +822,14 @@ independently tabbable" by design, mirroring how shadcn /
 ToggleGroup degrades to standard button focus when not wrapping
 Radix's primitive.
 
-**When two NON-`<dialog>` overlay controllers duplicate "modal mode"
+**When two NON-`<dialog>` overlays duplicate "modal mode"
 mechanics — extract**: this rule applies only to overlays that don't use
 the native `<dialog>` element. With `<dialog>`, the browser already
 provides the modal mechanics (focus trap, Escape, top-layer rendering),
-so `mountDialog` (Modal, AlertDialog, Sheet) is structurally a thin
+so `useDialog` (Modal, AlertDialog, Sheet, Command) is structurally a thin
 wrapper and there is no shared "modal mode" body to extract.
 
-Sidebar's drawer (`controllers/sidebar.ts`) implements its own
+Sidebar's drawer (`Sidebar.vue`) implements its own
 modal-overlay mechanics manually because the panel is a `<nav>`
 landmark rather than a `<dialog>` (see "Use native APIs where
 applicable" below): focus trap on the panel, ref-counted scroll lock
@@ -811,12 +848,12 @@ One consumer is implementation; two is duplication; three is a pattern.
 Modern HTML provides native overlay primitives that reduce hand-rolled
 focus traps, portals, and escape-key handling. Use them where they fit:
 
-| Overlay archetype                                          | Native API                                                                                       | Examples                                                                                                                                                                                                                                                                                                                            |
-| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Modal, alert dialog, sheet                                 | `<dialog>` + `showModal()` / `close()`                                                           | Modal, AlertDialog, Sheet (slide-side variants of the dialog primitive)                                                                                                                                                                                                                                                             |
-| Anchored popover, tooltip, dropdown menu, combobox listbox | Popover API (`popover` attribute + `showPopover()` / `hidePopover()`)                            | Popover, Tooltip, DropdownMenu, Combobox                                                                                                                                                                                                                                                                                            |
-| Navigation drawer, sidebar                                 | **Manual**                                                                                       | Sidebar drawer is `<nav>`, not `<dialog>` — keep manual `inert` / focus-trap mechanics. The semantic landmark is more important than the modal mechanics.                                                                                                                                                                           |
-| Toast                                                      | **Manual** — `<ol class="pui-toast-region">` with `aria-live="polite"` and `aria-atomic="false"` | Toasts are non-modal status notifications. The visual layer is a fixed-position `<ol>` (lazy-created by `controllers/toast.ts`); auto-dismiss + queue are owned by the singleton. The Popover API was considered and rejected: it requires a single element, but the toast region holds N siblings whose lifetimes are independent. |
+| Overlay archetype                                          | Native API                                                                                       | Examples                                                                                                                                                                                                                                                                                                |
+| ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Modal, alert dialog, sheet                                 | `<dialog>` + `showModal()` / `close()`                                                           | Modal, AlertDialog, Sheet (slide-side variants of the dialog primitive)                                                                                                                                                                                                                                 |
+| Anchored popover, tooltip, dropdown menu, combobox listbox | Popover API (`popover` attribute + `showPopover()` / `hidePopover()`)                            | Popover, Tooltip, DropdownMenu, Combobox                                                                                                                                                                                                                                                                |
+| Navigation drawer, sidebar                                 | **Manual**                                                                                       | Sidebar drawer is `<nav>`, not `<dialog>` — keep manual `inert` / focus-trap mechanics. The semantic landmark is more important than the modal mechanics.                                                                                                                                               |
+| Toast                                                      | **Manual** — `<ol class="pui-toast-region">` with `aria-live="polite"` and `aria-atomic="false"` | Toasts are non-modal status notifications. The visual layer is a fixed-position `<ol>`; auto-dismiss + queue are owned by whoever renders the region. The Popover API was considered and rejected: it requires a single element, but the toast region holds N siblings whose lifetimes are independent. |
 
 **What native APIs give us (free)**: top-layer rendering (escapes any
 ancestor stacking context / overflow), focus trap (`Tab` cycles within
@@ -833,34 +870,13 @@ persistent variants (suppress the `cancel` event with
 via `setAttribute`), our `data-state="open|closed"` reflection
 convention (so CSS selectors continue working consistently).
 
-The `mountDialog` / `mountPopover` / `mountSheet` controllers stay as
+The `useDialog` / `usePopover` composables stay as
 the public surface — they own the manual pieces above and standardize
-the controller archetype across components — but their internals lean
-on the native APIs rather than rebuilding them. `mountDialog` in
+the composable archetype across components — but their internals lean
+on the native APIs rather than rebuilding them. `useDialog` in
 particular is a thin wrapper over `<dialog>.showModal()` /
 `<dialog>.close()`.
 
-### Astro: hoisted vs inline script
-
-Two patterns for post-render JS in Astro components:
-
-**Hoisted module script** (`<script>` block at bottom of `.astro`, no
-`is:inline`): Astro hoists, dedupes, and bundles. Runs once per page
-load. Use this when many instances of the component can render per
-page (NumberField is the v1 example — its `data-pui-number-field`
-selector mounts the controller on every instance) — the dedupe
-wins. The script uses `document.querySelectorAll([data-…])` to find
-all instances and applies behavior to each.
-
-**Inline script** (`<script>` block in or co-located with markup,
-typically `is:inline`): runs verbatim in DOM order. Use this when
-the component is essentially singleton per page (Modal, Sidebar) and
-needs per-instance state via the `_<controllerName>` expando pattern.
-
-Both patterns ARE compatible with the `_<controllerName>` expando rule
-when stateful behavior is needed; the choice is about deduplication and
-script-payload economy.
-
 ### Stateful-component archetype
 
 Parallel to native-element-wrapper and form-primitive wrapper, stateful
@@ -868,36 +884,42 @@ components share a common authoring shape.
 
 **Authoring checklist for stateful components**:
 
-- [ ] Controller in `packages/ui/utils/controllers/<name>.ts` returns a
-      control object `{ open / close / isOpen / teardown }` (or the
-      equivalent imperative pair for non-open/close components, e.g.
-      Disclosure's `expand / collapse / isExpanded / teardown`).
-- [ ] Component template renders the wrapper element as the **mount point**
+- [ ] Behavior composable in `packages/ui/composables/use<Name>.ts` takes
+      `(elRef, options)` and returns a handle — `{ open / close / isOpen }`
+      for `useDialog`, `{ show / hide / toggle / isOpen / reposition }`
+      for `usePopover` — or `void` for wire-only behavior (`useDisclosure`,
+      `useMenu`).
+- [ ] Component template renders the wrapper element behind the ref
       with `data-state="closed"` (or equivalent neutral state) as the
-      static initial value. The controller flips `data-state` at runtime;
+      static initial value. The composable flips `data-state` at runtime;
       CSS targets `data-state` selectors only — no class-toggling for state.
-- [ ] Framework component captures a ref to the wrapper element and calls
-      `mount<Name>(el, config)` in `onMounted` (Vue) or in a `<script>`
-      block that runs after DOM is parsed (Astro). The control object is
-      stored on the framework instance (Vue: `let control` in setup; Astro:
-      `(el as any)._<name>` so consumer scripts can reach it).
-- [ ] Framework component watches its reactive `open` (or equivalent) prop
-      and forwards changes to the controller via `control.open()` /
-      `control.close()`. The framework prop is the trigger; the controller
-      owns runtime side-effects.
-- [ ] Framework component supplies an `onClose` (or equivalent
-      user-requested-state-change) callback to the controller. The callback
-      reflects the user intent back into framework state via emit /
-      `update:modelValue`; the framework's prop-watcher then calls
-      `control.close()`.
-- [ ] `onBeforeUnmount` (Vue) / before navigation (Astro) calls
-      `control.teardown()` so listeners, traps, scroll locks, and portaled
-      DOM are released even if `close()` was never called.
+- [ ] Component captures a ref to the wrapper element and calls
+      `use<Name>(elRef, options)` at setup time. The composable wires its
+      listeners in its own `onMounted` and cleans up in `onBeforeUnmount`
+      — the component writes no lifecycle hooks and stores no control
+      object.
+- [ ] Controlled open state flows through the `open` getter option
+      (`open: () => props.open`). The composable applies the initial value
+      on mount and watches for changes; `undefined` is ignored. The
+      component prop is the trigger; the composable owns runtime
+      side-effects.
+- [ ] Options that can change over the component's lifetime (`persistent`,
+      `placement`, `offset`, `singleOpen`) are passed as getters or refs
+      (`persistent: () => props.persistent`); the composable reads them
+      via `toValue()` at use time.
+- [ ] Component supplies an `onClose` (or equivalent
+      user-requested-state-change) callback. The callback
+      reflects the user intent back into component state via emit /
+      `update:modelValue`; the watched `open` getter then performs the
+      actual close.
+- [ ] Unmounting while open closes first — the composable's
+      `onBeforeUnmount` releases listeners, traps, and scroll locks even
+      if the component never closed explicitly.
 - [ ] **Native APIs first**. `<dialog>`-based overlays (Modal, AlertDialog,
-      Sheet) get top-layer rendering, focus trap, and Escape dismissal
-      from the browser. Popover-API-based overlays (Popover, Tooltip,
-      DropdownMenu, Combobox listbox) get top-layer + light dismiss.
-      The controller layers on body scroll lock, backdrop-click
+      Sheet, Command) get top-layer rendering, focus trap, and Escape
+      dismissal from the browser. Popover-API-based overlays (Popover,
+      Tooltip, DropdownMenu, Combobox listbox) get top-layer + light
+      dismiss. The composable layers on body scroll lock, backdrop-click
       dismissal, persistent suppression, `data-state` reflection, and
       any role override (`role="alertdialog"`). See "Use native APIs
       where applicable" below for the full table.
@@ -908,15 +930,16 @@ components share a common authoring shape.
       currently because `<dialog>`-based overlays escape stacking via
       the native top-layer and the Sidebar drawer stays inline. Vue's
       `<Teleport>` is intentionally NOT used should portaling be added —
-      both frameworks share one mechanism for one mental model.
+      the behavior layer owns DOM placement, one mechanism for one
+      mental model.
 - [ ] Components requiring body-scroll lock use `utils/dom/scroll-lock.ts`.
       The lock is reference-counted so nested overlays don't release each
       other prematurely.
-- [ ] Controllers managing manual focus traps (the non-`<dialog>` case)
-      use `utils/a11y/focus.ts:createFocusTrap`. They are also
+- [ ] Behavior code managing manual focus traps (the non-`<dialog>` case)
+      uses `utils/a11y/focus.ts:createFocusTrap`. It is also
       responsible for capturing the trigger before focus moves and
-      restoring focus to it on close. `<dialog>`-based controllers
-      delegate both to the browser; a backup focus restore runs only
+      restoring focus to it on close. `<dialog>`-based behavior
+      delegates both to the browser; a backup focus restore runs only
       when the browser fails to restore (rare — e.g. the trigger was
       removed from the DOM mid-open).
 
@@ -929,7 +952,7 @@ class="pui-modal">` element that is both the surface and the backdrop
   provides top-layer rendering, focus trap, Escape dismissal (via the
   `cancel` event), `[open]` reflection, and focus restoration to the
   trigger on close. AlertDialog (Phase 4) and Sheet (Phase 4) reuse
-  the same controller — only their CSS geometry differs.
+  the same composable — only their CSS geometry differs.
 - **Portal target**: not applicable. `<dialog>.showModal()` renders
   in the native top-layer, which already escapes any ancestor stacking
   context or `overflow: hidden`. There is no portal helper involved.
@@ -937,11 +960,11 @@ class="pui-modal">` element that is both the surface and the backdrop
   `padding-right` is increased by the scrollbar width to prevent layout
   shift. The lock is reference-counted across all open overlays.
   Browsers do NOT lock body scroll for `<dialog>` automatically, so the
-  controller still owns this.
-- **`data-state` lifecycle**: `closed` (static initial) → `open` (controller
-  flips on `open()`) → `closed` (controller flips on `close()`). The
+  composable still owns this.
+- **`data-state` lifecycle**: `closed` (static initial) → `open` (composable
+  flips on `open()`) → `closed` (composable flips on `close()`). The
   `[open]` attribute is set by the browser via `showModal()`/`close()`;
-  `data-state` is set by the controller in parallel so CSS selectors
+  `data-state` is set by the composable in parallel so CSS selectors
   consistent with the locked convention keep working. Animated
   enter/exit transitions drive off the `data-state` selector pairs in
   CSS; the `opening` / `closing` intermediate states are deferred to
@@ -949,7 +972,7 @@ class="pui-modal">` element that is both the surface and the backdrop
   out-of-scope on `@starting-style`).
 - **Initial focus**: `<dialog>.showModal()` auto-focuses the first
   focusable child (or the element with `[autofocus]`) by default. On
-  top of that, the controller's `initialFocus` config can override:
+  top of that, the composable's `initialFocus` option can override:
   `'cancel'` focuses the element marked `[data-dialog-cancel]`,
   `HTMLElement` focuses an explicit element, `'first'` and `null`
   defer to the browser. A `[data-dialog-initial-focus]` element
@@ -959,48 +982,41 @@ class="pui-modal">` element that is both the surface and the backdrop
   manual backup runs only when the browser fails to restore.
 - **Outside-click semantics**: clicks land on the `<dialog>` element
   itself when the user clicks the `::backdrop` (children clicks bubble
-  through with `target` = the inner content). The controller checks
+  through with `target` = the inner content). The composable checks
   `event.target === el` to detect a backdrop click. Persistent dialogs
   (AlertDialog, future) skip this dismissal entirely.
 - **Escape key**: when not persistent, Escape fires the native `cancel`
-  event whose default action is `el.close()`. The controller forwards
-  the close intent through `onClose` so the framework's reactive prop
+  event whose default action is `el.close()`. The composable forwards
+  the close intent through `onClose` so the component's reactive prop
   stays authoritative. Persistent dialogs call `event.preventDefault()`
   on the `cancel` event to suppress the default close.
-- **Astro `_<controllerName>` expando**: the control object is exposed on
-  the `<dialog>` element via a property named after the controller (not
-  the component): `_dialog` for `mountDialog` (used by Modal,
-  AlertDialog, and Sheet), `_popover` for `mountPopover`, etc.
-  Consumers reach the API via
-  `document.getElementById('<id>')._dialog.open()`. The TypeScript cast
-  `(el as any)._dialog` is the v1 pattern; a typed helper
-  `getController<T>(el, key)` may land in `utils/dom/` later.
 
 ### Worked example — Modal
 
 The full-fat reference. See `packages/ui/components/overlay/modal/` and
-`packages/ui/utils/controllers/dialog.ts` for the actual code.
+`packages/ui/composables/useDialog.ts` for the actual code.
 
 ```ts
-// packages/ui/utils/controllers/dialog.ts
-export interface DialogControl {
+// packages/ui/composables/useDialog.ts
+export interface DialogHandle {
     open(): void;
     close(): void;
     isOpen(): boolean;
-    teardown(): void;
 }
 
-export interface DialogConfig {
+export interface UseDialogOptions {
     role?: 'dialog' | 'alertdialog'; // default: 'dialog' (browser default for <dialog>)
-    persistent?: boolean; // default: false; suppresses cancel default + backdrop click
+    persistent?: MaybeRefOrGetter<boolean>; // default: false; suppresses cancel default + backdrop click
     initialFocus?: 'first' | 'cancel' | HTMLElement | null; // default: 'first' (defers to native showModal())
+    open?: () => boolean | undefined; // controlled state; applied on mount, watched after; undefined ignored
+    onBeforeOpen?: () => void; // runs just before the dialog opens, on every open path
     onClose?: () => void; // user-requested close (Escape or backdrop click)
 }
 
-export function mountDialog(
-    el: HTMLDialogElement,
-    config?: DialogConfig,
-): DialogControl;
+export function useDialog(
+    elRef: Ref<HTMLDialogElement | null>,
+    options?: UseDialogOptions,
+): DialogHandle;
 ```
 
 **Vue consumer** (full pattern):
@@ -1021,11 +1037,8 @@ export function mountDialog(
 </template>
 
 <script setup lang="ts">
-import { ref, watch, onMounted, onBeforeUnmount } from 'vue';
-import {
-    mountDialog,
-    type DialogControl,
-} from '@pienter/ui/utils/controllers/dialog.js';
+import { ref } from 'vue';
+import { useDialog } from '@pienter/ui/composables/useDialog';
 
 defineOptions({ inheritAttrs: false });
 
@@ -1037,78 +1050,23 @@ const props = defineProps<{
 const emit = defineEmits<{ 'update:open': [boolean]; close: [] }>();
 
 const rootRef = ref<HTMLDialogElement | null>(null);
-let control: DialogControl | null = null;
-
-onMounted(() => {
-    control = mountDialog(rootRef.value!, {
-        persistent: props.persistent,
-        onClose: () => {
-            emit('update:open', false);
-            emit('close');
-        },
-    });
-    if (props.open) control.open();
-});
 
-watch(
-    () => props.open,
-    (v) => (v ? control?.open() : control?.close()),
-);
-
-onBeforeUnmount(() => {
-    control?.teardown();
-    control = null;
+useDialog(rootRef, {
+    role: 'dialog',
+    persistent: () => props.persistent,
+    open: () => props.open,
+    onClose: () => {
+        emit('update:open', false);
+        emit('close');
+    },
 });
 </script>
 ```
 
-**Astro consumer** (open-by-default or trigger-driven via `_dialog`):
-
-```astro
----
-const { id, open, persistent, title } = Astro.props;
----
-<dialog
-  id={id}
-  class="pui-modal"
-  data-state="closed"
-  data-pui-modal
-  data-persistent={persistent ? 'true' : undefined}
-  data-open-initially={open ? 'true' : undefined}
-  aria-labelledby={`${id}-title`}
->
-  <h2 id={`${id}-title`}>{title}</h2>
-  <slot />
-</dialog>
-
-<script>
-  import { mountDialog } from '@pienter/ui/utils/controllers/dialog.js';
-  document.querySelectorAll<HTMLDialogElement>('dialog[data-pui-modal]').forEach((el) => {
-    if ((el as any)._dialog) return;
-    const control = mountDialog(el, {
-      persistent: el.dataset.persistent === 'true',
-    });
-    (el as any)._dialog = control;
-    if (el.dataset.openInitially === 'true') control.open();
-  });
-</script>
-```
-
-**Astro consumer page — opening from a trigger button**:
-
-```astro
-<button onclick="document.getElementById('demo-modal')._dialog.open()">
-  Open
-</button>
-<Modal id="demo-modal" title="Confirm" persistent={false}>
-  <p>Body text.</p>
-</Modal>
-```
-
-The `_dialog` consumer pattern is the v1 contract for Astro — each Modal
-exposes its control object as a property on the wrapper element so consumer
-scripts can reach it. A future iteration may add declarative
-`data-modal-trigger="<id>"` button wiring; deferred for v1.
+No `watch`, no `onMounted` / `onBeforeUnmount`, no stored control object —
+the composable owns its lifecycle. The `open` getter carries both the
+initial state and every subsequent change; `onClose` reports user intent
+back to the reactive layer.
 
 ### Vue API decisions
 
@@ -1144,14 +1102,10 @@ binding. Examples:
 <div role="dialog" aria-modal="true">…</div>
 ```
 
-```astro
-<ul role="list" aria-label="Breadcrumbs">…</ul>
-```
-
 This is the common case for `role`, `aria-modal`, `aria-label` (when the
 label is a literal string), and `aria-orientation`.
 
-### Reactive ARIA bindings (Vue) — `:aria-*`
+### Reactive ARIA bindings — `:aria-*`
 
 When the value depends on **props or runtime state**, use Vue's reactive
 binding syntax:
@@ -1173,26 +1127,6 @@ The pattern matches the **boolean-attr-only-when-truthy** rule above: emit
 so Vue drops the attribute entirely. Never emit the literal string
 `'false'`.
 
-### Astro ARIA — template expressions
-
-Astro doesn't have reactivity but its template-expression syntax handles
-the same conditional shape:
-
-```astro
-<input
-  aria-invalid={hasErrors ? 'true' : undefined}
-  aria-describedby={describedBy}
-/>
-
-<div aria-labelledby={`${id}-title`}>…</div>
-```
-
-The only difference from Vue is the syntax sigil (`{}` vs `:`). The
-`undefined`-drops-attribute behavior is identical. Consumer-supplied
-dynamic ARIA values land via the `...rest` spread on the appropriate
-element (the wrapper for pure-markup; the inner control for form
-primitives).
-
 ### Boolean ARIA values — strings, not literals
 
 Per the boolean-attr-only-when-truthy rule, emit `'true'` (the string)
@@ -1204,12 +1138,12 @@ state writes `[aria-busy='true']`, `[aria-invalid='true']`,
 **Disambiguation — native HTML booleans vs ARIA boolean strings**:
 native HTML boolean attributes (`disabled`, `readonly`, `required`,
 `checked`, `selected`) follow framework boolean-prop semantics — bind
-the boolean directly (`:disabled="x"` in Vue, `disabled={x}` in Astro);
-the framework renders the bare attribute when truthy and drops it when
-falsy. ARIA boolean attributes (`aria-busy`, `aria-invalid`,
-`aria-disabled`) take the _string_ `'true'` and the only-when-truthy
+the boolean directly (`:disabled="x"`); Vue renders the bare attribute
+when truthy and drops it when falsy. ARIA boolean attributes
+(`aria-busy`, `aria-invalid`, `aria-disabled`) take the _string_
+`'true'` and the only-when-truthy
 idiom (`x ? 'true' : undefined`). Do not pass a raw boolean to an
-`aria-*` binding — Astro will stringify `false` to the literal
+`aria-*` binding — Vue stringifies `false` to the literal
 `"false"`, which fails the rule. For `aria-expanded`, `aria-checked`,
 `aria-pressed`, and `aria-selected`, see Always-emit ARIA exceptions
 below — they require explicit `'true'`/`'false'`.
@@ -1239,28 +1173,28 @@ literally; do NOT omit when falsy:
   selected".
 
 For these four, the binding shape is `:aria-<name>="x ? 'true' :
-'false'"` (Vue) or `aria-<name>={x ? 'true' : 'false'}` (Astro). Native
+'false'"`. Native
 elements with intrinsic role semantics provide some of this for free
 (e.g. `<input type="checkbox">` carries implicit `checked` state) — but
 when the role is set explicitly (`role="switch"` on a checkbox-backed
 input), the matching ARIA attribute MUST also be set explicitly so AT
 reads the role-state pair consistently.
 
-### ARIA ownership — template vs controller
+### ARIA ownership — template vs composable
 
 For stateful components (Modal, AlertDialog, Sheet, Popover, Disclosure),
 some ARIA attributes are owned by the **template** (template-time data —
 heading IDs, label strings, role choice when fixed) and some by the
-**controller** (runtime state — `aria-modal` set during open, `data-state`
-mirrored to ARIA semantics where applicable). Each controller's audit
-entry documents which ARIA attributes it owns; everything else is the
-framework template's responsibility. For Modal:
+**composable** (runtime state — `aria-modal` set during open, `data-state`
+mirrored to ARIA semantics where applicable). Each component's audit
+entry documents which ARIA attributes its composable owns; everything else
+is the template's responsibility. For Modal:
 
 - Template: `aria-labelledby` (heading ID is template-time).
 - Browser: `role="dialog"` (the implicit role for `<dialog>`) and
   `aria-modal` (set implicitly when `showModal()` is called) — no
-  template or controller wiring needed.
-- Controller: `role` override only — `mountDialog` calls
+  template or composable wiring needed.
+- Composable: `role` override only — `useDialog` calls
   `setAttribute('role', 'alertdialog')` for AlertDialog. Modal v1
   doesn't override and inherits the browser default.
 
@@ -1296,28 +1230,6 @@ Every interactive component renders a consistent keyboard-focus ring:
 
 ---
 
-## Astro tier mapping
-
-Components ship Astro implementations only when listed in this tier. SPA-only interactive components are Vue-only; Astro consumers needing them render the Vue version as an Astro island via `client:visible`.
-
-| Tier                         | Components                                                                                                                                            | Astro?                                                |
-| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------- |
-| Static markup                | Card, Badge, Alert, Avatar, Avatar-stack, Breadcrumb, Empty, Icon, Skeleton, Spinner, Separator, Progress, Label                                      | Yes — pure `.astro`, no JS                            |
-| Form primitives              | Button, TextInput, Textarea, Form, Checkbox, RadioGroup, Switch, Select, NumberField, DateInput, TagsInput, InputOTP, Slider                          | Yes — JS via controllers where needed                 |
-| Marketing-needed interactive | Modal, AlertDialog, Toast                                                                                                                             | Yes — `controllers/dialog.ts`, `controllers/toast.ts` |
-| Layout                       | Navbar, Sidebar, Table                                                                                                                                | Yes — Table's sort ships as links, so still no JS     |
-| SPA-only interactive         | Tabs, Pagination, Segmented, Toggle (press), ToggleGroup, Popover, Tooltip, DropdownMenu, Combobox, Command, Sheet, Accordion, Collapsible, DataTable | **Vue-only**                                          |
-
-Table sort is deliberately not in the Vue-only row. Sorting a table is a
-navigation, not SPA state (ADR 0005), so the Astro tier renders each sortable
-header as an `<a>` pointing at the URL that column would produce next — same
-`aria-sort`, same chevron glyph, same asc → desc → unsorted cycle as the Vue
-tier's `<button>`, and no JavaScript. What stays Vue-only is `DataTable`, the
-data-driven wrapper: it renders rows from a reactive array and owns selection
-state, neither of which a static page has.
-
----
-
 ## shadcn / Radix commit pins
 
 _Pinned 2026-05-03. Update both together as a separate, intentional change._
@@ -1387,9 +1299,9 @@ follow the shape of an existing one.
 
 ## Form submit response contract
 
-_Placeholder shape — subject to change when ts-sdk publishes the canonical response shape. The symmetry requirement (same shape consumed by Vue `Form.vue` and Astro `controllers/form.ts:mountForm`) is locked; the shape itself is provisional and will be migrated together when ts-sdk lands._
+_Placeholder shape — subject to change when ts-sdk publishes the canonical response shape. The shape is provisional and will be migrated in one change when ts-sdk lands._
 
-Both the Vue `Form.vue` and the Astro `controllers/form.ts:mountForm` SHALL accept the same submit response shape, mapping server validation errors, success messages, and redirect signals through identical contracts. Drift between the two implementations is treated as a defect.
+`Form.vue` SHALL accept this submit response shape, mapping server validation errors, success messages, and redirect signals through one contract.
 
 ```ts
 // packages/ui/utils/validation/form.ts
@@ -1411,11 +1323,11 @@ export interface FormSubmitResponse {
 }
 ```
 
-**Mapping rules — both frameworks**:
+**Mapping rules**:
 
 - `ok: true` clears all errors, renders `statusMessage` in `.pui-form__status`, and announces it politely.
 - `ok: false` renders `errors` in `.pui-form__error-summary`, applies `fieldErrors` to the matching form-primitive wrappers (per-field error list inside `pui-field__hint role="alert"` + `aria-invalid="true"` on the control), focuses the first invalid field via `focusFirstInvalid`, and announces the error count assertively.
-- `redirect` is a passive value — orchestration does NOT navigate; consumers act on it inside their `onResult` / `@submit` callback.
+- `redirect` is a passive value — orchestration does NOT navigate; consumers act on it inside their `@submit` handler.
 
 **Field error normalization**: `fieldErrors[name]` MAY be a single string or an array of strings. Orchestration normalizes to `string[]` via the shared `normalizeFieldErrors` helper before applying to the DOM.
 
@@ -1497,3 +1409,48 @@ Pinned upstream SHAs used across the table:
 | toggle        | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/toggle.tsx          | 7865621397708917369251d67029ad920e390a38 | https://github.com/radix-ui/primitives/tree/22473d16404bfd446305db5b6c9308aece99fdec/packages/react/toggle/src                      | 22473d16404bfd446305db5b6c9308aece99fdec   | 2026-05-27   |
 | toggle-group  | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/toggle-group.tsx    | 7865621397708917369251d67029ad920e390a38 | https://github.com/radix-ui/primitives/tree/22473d16404bfd446305db5b6c9308aece99fdec/packages/react/toggle-group/src                | 22473d16404bfd446305db5b6c9308aece99fdec   | 2026-05-27   |
 | tooltip       | https://github.com/shadcn-ui/ui/blob/7865621397708917369251d67029ad920e390a38/apps/v4/registry/new-york-v4/ui/tooltip.tsx         | 7865621397708917369251d67029ad920e390a38 | https://github.com/radix-ui/primitives/tree/22473d16404bfd446305db5b6c9308aece99fdec/packages/react/tooltip/src                     | 22473d16404bfd446305db5b6c9308aece99fdec   | 2026-05-27   |
+
+## CMS page composition
+
+`Index`, `RecordForm`, and `RecordDetails` compose existing primitives. Consumers
+register routes and supply endpoint-specific data functions, rendering and actions.
+
+Index accepts `load(query, { signal })`, `columns` and `queryOptions`. It owns
+query state, rows, metadata, loading, failures and retry. Search is debounced;
+search/filter/sort/page-size changes reset page to 1. New requests and unmount
+abort earlier work; stale responses are ignored even when loaders ignore the signal.
+`sync-query` opts into Vue Router query decoding and history synchronization.
+Without it, state stays local. Index imports the optional `vue-router` peer, but
+requires an installed router instance only for URL synchronization.
+
+Index applies the existing default sort cycle; Table/DataTable still emit a column
+key as intent, per ADR 0005. A toolbar select shares that sort state and includes
+all allowed fields, including those without visible columns. Sortable columns
+must belong to the allowed sort vocabulary; labels may be overridden with
+`sortLabels`. Filter slots can update one key without replacing siblings. Action
+and selection slots receive loading state and an awaitable refresh callback.
+Structured backend query errors offer reset; other load failures offer retry.
+Use DataTable when the consumer needs controlled data
+and request state. Index's compact row spacing uses
+`--pui-table-cell-padding-block`, which Table otherwise defaults to `--space-xs`.
+
+RecordForm emits detached JSON snapshots, preserving every supplied property.
+Consumers construct an explicit writable object from backend records. Typed path
+segments identify nested fields and array indices; fields display issues for
+their path and descendants. The form summary retains unmatched issues.
+`--pui-record-form-columns` customizes the field grid, defaulting to one column.
+
+RecordForm's `fields` slot replaces its default RecordFields rendering for
+custom sidebar/tab layouts. RecordFields takes the same draft and renders a
+subset, with `--pui-record-fields-columns` as its grid seam. It never renders a
+form element. Callers expose the relevant tab when backend issues arrive.
+
+BlockEditor owns an ordered array of stable `id`/`type` blocks and emits updates
+for edits, addition, removal and reordering. Creation factories and slot content
+stay caller-owned. Optional `v-model:collapsed` lets pages reveal invalid blocks.
+Its colocated audit records pointer, keyboard, focus and cancellation behavior.
+
+The backend contract lives in `docs/cms/backend-contract.md` with a distributable
+JSON Schema at `utils/cms/schema.json`. It defines request/response data only;
+endpoint URLs, authentication, permissions and domain operations belong to the
+application.