@adia-ai/adia-ui-factory 0.2.3 → 0.8.0

package/references/migration.md

@@ -1,57 +1,131 @@
----
-name: migration
-load-when: migrating an adia-ui app — version upgrade, port-to-adia, or mode change
-load-size: ~2.5k tokens
-required-for: [adia-ui-migrate — all types]
----
+# Migration — types, history, sweep depth
 
-# Migration — types, history, discipline
-
-Consumer migrations. The framework MIGRATION GUIDE (in the framework repo) is the source of truth per version; this is the durable method + the shape of past breaks. Treat versions/examples as a snapshot.
+Consumer migrations: the durable method + the shape of past breaks. The framework MIGRATION
+GUIDE (`.claude/docs/MIGRATION GUIDE.md` in the framework repo — the space in the filename is
+intentional) is the per-version source of truth; its required shape is
+[`contracts/migration-guide-format.md`](contracts/migration-guide-format.md). Loaded by
+`adia-migrate` (all migration types). Versions and examples below are a snapshot, not a registry.
 
 ## Types
 
-- **version-upgrade** — bump `@adia-ai/*` X→Y (lockstep; all packages move together). PATCH cuts are drop-in; MINOR/MAJOR carry breaking items.
-- **port-to-adia** — an existing app (raw HTML, or legacy `@agent-ui-kit`) → adia-ui: a tag rename map (`aui-button`→`button-ui`, `<button>`→`<button-ui>`) + token namespace swap (`--n-*`→`--a-*`).
-- **mode-change** — SPA↔SSR: re-own routing (framework router vs `<router-ui>`), registration (top-level vs client-hook), and state (signals vs cookies). See `adia-ui-spa` / `adia-ui-ssr`.
-
-## The 5-step discipline
-
-1. **Read the guide** for the target version. Missing section → pause, ask, offer to draft it.
-2. **Audit** — `git grep -nlE '<pattern>'` each breaking item; cluster by component; count files/occurrences. Surface before sweeping.
-3. **Sweep** — mechanical per cluster:
+- **version-upgrade** — bump `@adia-ai/*` X→Y (lockstep; all packages move together). PATCH
+  cuts are drop-in; MINOR/MAJOR carry breaking items.
+- **port-to-adia** — an existing app (raw HTML, or legacy `@agent-ui-kit`) → adia-ui: a tag
+  rename map (`aui-button`→`button-ui`, `<button>`→`<button-ui>`) + token namespace swap
+  (`--n-*`→`--a-*`).
+- **mode-change** — SPA↔SSR: re-own routing (framework router vs `<router-ui>`), registration
+  (top-level vs client-hook), and state (signals vs cookies). `adia-host` carries both paths.
+
+## The 5-step sweep — depth
+
+1. **Read the guide** for the version span: index bullets → per-cut sections. Each breaking
+   item ships an old form, a new form, and a greppable pattern (the contract above). A missing
+   section, or an item without a pattern/verify command, is a producer defect — pause, report
+   upstream; don't improvise a breaking surface.
+2. **Audit** — `git grep -nE '<pattern>'` per item; cluster by component; report file +
+   occurrence counts and show the list before changing anything. Consumer code has edge cases
+   the canonical regexes don't anticipate (a `variant="danger"` on a non-button custom element
+   that shares the prefix).
+3. **Sweep** — mechanical per approved cluster:
 
    ```bash
    git grep -lE 'button-ui[^>]*variant="danger"' \
      | xargs perl -i -pe 's/(<button-ui[^>]*?)variant="danger"/$1color="danger"/g'
    ```
 
-   …or a shipped codemod. **Flag, don't auto-apply, judgment items** (below).
-
-4. **Verify** — `adia-lint` clean of `LEGACY-SHELL`/`NATIVE-PRIMITIVE`; build/render; then the **leftover-drift grep** across `.css`/`.js`/`.md`/`.json`; browser probe.
+   Judgment items (below) are flagged, never swept.
+4. **Verify** — `adia-lint` clean of `LEGACY-SHELL`/`NATIVE-PRIMITIVE`; the app's own build +
+   the browser gate ([`verification.md`](verification.md)); then the leftover-drift pass below.
 5. **Report** — per-axis counts, manual-review list, gate results, next actions.
 
-## Real breaking-change history (before → after)
+### Sweep anti-patterns (each shipped a real regression)
 
-- **v0.0.20 (10 items):** `<button-ui variant="danger">` → `variant="solid" color="danger"`; stage Booleans (`completed`/`active`) → `status="completed|active"` enum (timeline/stepper/pipeline); `<table-toolbar-ui>` opt-out Booleans **inverted** (`searchable="false"` → `no-search`; default flipped); `<chat-input-ui busy>` → `loading`; `variant="error"` alias removed → `danger`; event prefixes dropped (`chat-submit`→`submit`); `<field-ui error>` moved to the child input; `<agent-trace-ui open>` → `collapsed` (**semantic flip — default-visible now**); kebab prop keys → camelCase (JS only). Safari floor → 18.
-- **v0.0.29 — three-tier extraction:** `patterns/` moved `@adia-ai/web-components/patterns/*` → `@adia-ai/web-modules/{shell,chat,editor,runtime}/*`. Import-path rewrite + add the `web-modules` dep.
-- **v0.4.0 — legacy shell shapes retired (ADR-0024):** `<aside data-sidebar>`→`<admin-sidebar slot>`; `<dialog data-command>`→`<admin-command>`; `[data-chat-messages/input/empty]`→`<chat-thread>/<chat-composer>/<chat-empty>`; `[data-editor-body]/[data-canvas]`→`<editor-canvas>` + `<editor-sidebar>`. JS selectors move with them. (`adia-lint` `LEGACY-SHELL` flags the remnants.)
-- **v0.6.0/0.6.1:** `stat-ui.{js,css}`→`stat.{js,css}` (deep-import only); `<link-ui>` token rename `--link-color-*`→`--link-fg-*` (only if you override).
+- **One component per sweep.** `<(toast|alert|tag)-ui[^>]*variant="error"` looks efficient, but
+  perl/sed alternation captures don't substitute the matched alternative cleanly — loop
+  `for tag in toast alert tag` instead.
+- **HTML-attribute regexes don't cover JS property sites.** `<chat-input-ui busy>` and
+  `el.busy = true` are two audits — sweep `\.busy\s*=` separately, scoped to app code.
+- **`git grep -lE | xargs perl -i`, never `find … -exec perl`.** git grep excludes
+  `node_modules/`, `dist/`, `.git/`; a raw find doesn't.
 
-## Judgment items (flag for review — never auto-sweep)
-
-Semantic flips (`[open]`→`[collapsed]` inverts default visibility), Boolean opt-out inversions (default changes), attribution transfers (`field-ui error` → child input may not exist yet). Surface these with their call sites; let the author decide.
-
-## What the path-only sweep misses (leftover-drift categories)
+## Real breaking-change history (before → after)
 
-Bare-name mentions in prose docs (README/AGENTS/ROADMAP); skill-directory names; JSON metadata fields (highest impact — silent harvest miss on rebuild); inventory tables in cross-cutting docs. Use a pre/post grep diff:
+- **v0.0.20 (10 items):** `<button-ui variant="danger">` → `variant="solid" color="danger"`
+  (canonical form; the guide's mechanical sweep emits just `color="danger"`, leaning on `solid`
+  being the default variant); stage Booleans (`completed`/`active`) → `status="completed|active"`
+  enum (timeline/stepper/pipeline); `<table-toolbar-ui>` opt-out Booleans **inverted**
+  (`searchable="false"` → `no-search`; default flipped); `<chat-input-ui busy>` → `loading`;
+  `variant="error"` alias removed → `danger`; event prefixes dropped (`chat-submit`→`submit`,
+  `legend-toggle`→`toggle`, `slide-change`→`change`); `<field-ui error>` moved to the child
+  input; `<agent-trace-ui open>` → `collapsed` (**semantic flip — default-visible now**); kebab
+  prop keys → camelCase (JS only). Safari floor → 18.
+- **v0.0.29 — three-tier extraction:** `patterns/` moved `@adia-ai/web-components/patterns/*` →
+  `@adia-ai/web-modules/{shell,chat,editor,runtime}/*`. Import-path rewrite + add the
+  `web-modules` dep.
+- **v0.4.0 — legacy shell shapes retired (ADR-0024):** `<aside data-sidebar>`→`<admin-sidebar
+  slot>`; `<dialog data-command>`→`<admin-command>`; `[data-chat-messages/input/empty]`→
+  `<chat-thread>/<chat-composer>/<chat-empty>`; `[data-editor-body]/[data-canvas]`→
+  `<editor-canvas>` + `<editor-sidebar>`. JS selectors move with the markup. (`adia-lint`
+  `LEGACY-SHELL` flags the remnants.)
+- **v0.6.0/0.6.1:** `stat-ui.{js,css}`→`stat.{js,css}` (deep-import only); `<link-ui>` token
+  rename `--link-color-*`→`--link-fg-*` (only if you override).
+
+## Judgment items (flag with call sites — the author decides, never a sweep)
+
+- **Semantic flips** — `<agent-trace-ui open>`→`[collapsed]` is an inversion, not a rename:
+  `[open]` was default-hidden/opt-in, `[collapsed]` is default-visible/opt-out. Trace meant to
+  show? drop the attribute. Meant hidden? write `collapsed`.
+- **Boolean opt-out inversions** — `<table-toolbar-ui>`: the legacy Booleans defaulted to
+  `true`, so a bare `filterable` was a no-op; only an explicit `searchable="false"` carried
+  intent (→ `no-search`). A regex can't tell the two apart.
+- **Attribution transfers** — `<field-ui error="…">` moves the message to the child input,
+  which may not exist yet in the markup.
+- **JS-only key renames** — kebab property keys (`el['submit-label']`→`el.submitLabel`): the
+  HTML attribute form is unchanged, so attribute-only consumers need no change. Audit
+  programmatic access only.
+
+## Leftover drift — what the path-only sweep misses
+
+A vocabulary migration touches the markup but not the CSS selectors that style it, the JS
+comments that mention it, or the metadata that indexes it — different files, so a markup-only
+commit looks complete. Close with a pre/post grep diff:
 
 ```bash
 grep -rln 'OLD_NAME' . --include='*.md' --include='*.json' | sort > /tmp/pre.txt
 # … sweep …
-grep -rln 'OLD_NAME' . --include='*.md' --include='*.json' | sort > /tmp/post.txt && diff /tmp/pre.txt /tmp/post.txt
+grep -rln 'OLD_NAME' . --include='*.md' --include='*.json' | sort > /tmp/post.txt
+diff /tmp/pre.txt /tmp/post.txt   # anything left post-sweep is a stale ref to investigate
 ```
 
-## MCP aids
-
-`search_chunks` (the updated example for a changed component) · `check_anti_patterns` (a swept file is clean) · `convert_html` (map legacy/foreign markup → current components, for ports). There's no "list breaking changes" tool — the MIGRATION GUIDE is read by hand.
+Categories that have survived full-path sweeps:
+
+- **Bare-name prose mentions** in narrative docs and inventory tables (README, roadmap-style
+  indexes) — grep `\b<old-name>\b` over `*.md` / `*.yaml`, not just paths.
+- **Directories named after the renamed thing** (skill dirs, config dirs) — dir vs frontmatter
+  mismatch check:
+
+  ```bash
+  for skill in $(find . -name 'SKILL.md' -not -path '*/node_modules/*'); do
+    dir=$(basename $(dirname "$skill")); name=$(grep -m1 '^name:' "$skill" | sed 's/name: *//')
+    [ "$dir" != "$name" ] && echo "MISMATCH: $skill (dir=$dir, name=$name)"
+  done
+  ```
+
+- **JSON metadata at filename granularity** (highest impact — a stale `source`/`page` field is
+  a *silent* harvest miss on the next rebuild; no error is raised):
+
+  ```bash
+  for f in 'old-name.html' 'old-name.contents.html' 'old-name.contents.js'; do
+    grep -rn "$f" --include='*.json' | grep -v '/dist/' | grep -v '/node_modules/'
+  done
+  ```
+
+- **Refs to the directory itself, not the tag** — barrel JS exports, CSS `@import`s, HTML link
+  rels, sitemap/content paths name the old *dir*; a tag-rename sweep never touches them. Grep
+  the old directory name separately.
+- **Relative-import depth after `git mv`** — grep each moved file for `../` imports and fix the
+  depth; builds don't load them, so the breakage surfaces only in the browser. A doc move needs
+  a *different* rewrite per linking file's own depth — precompute per file.
+- **Hard-coded source lists in build scripts** — `SOURCES = […]` / include-dir arrays silently
+  drop renamed or new siblings while the build runs clean; diff output counts against the
+  pre-rename baseline after any rename.

package/references/project-shapes.md

@@ -1,13 +1,6 @@
----
-name: project-shapes
-load-when: classifying or laying out an adia-ui app's structure — picking the project shape, the four-axis layout, or page-trio vs page-DUO
-load-size: ~2.5k tokens
-required-for: [adia-ui-factory shape classifier, adia-ui-project (scaffold / add-surface / add-page)]
----
-
 # Project shapes & structure
 
-How real adia-ui apps are laid out (synthesized from the chat-ui apps). Three shapes over one four-axis layout, with a page-trio/DUO rule. The **structure rubric** at the bottom is the gate; `bin/adia-scaffold` mechanizes the layout.
+How real adia-ui apps are laid out (synthesized from the chat-ui apps). Three shapes over one four-axis layout, with a page-trio/DUO rule. The **structure rubric** at the bottom is the gate; `bin/adia-scaffold` mechanizes the layout. Loaded by `adia-orient` (shape classifier) and `adia-project` (layout / scaffold / inventory).
 
 ## The four-axis layout (all shapes)
 
@@ -56,7 +49,7 @@ Use for: a suite of related surfaces (a SaaS admin, a flow set, a demo gallery).
 
 ### Shared-foundation — sibling apps over a shared core
 
-Root-level `spec/plan/` for cross-app concerns; each app under `app/<name>/` with its own `spec/plan/src/`; a shared `app/shared/` (DataClient, loaders, mappers, tokens). The embed pattern lives here → becomes **`adia-embed-shell`**.
+Root-level `spec/plan/` for cross-app concerns; each app under `app/<name>/` with its own `spec/plan/src/`; a shared `app/shared/` (DataClient, loaders, mappers, tokens). The embed pattern lives here — the shell is **`<embed-shell>`** (ships in `@adia-ai/web-modules`, shell cluster); depth: [shell-embed.md](shell-embed.md).
 
 ```text
 app/
@@ -75,13 +68,18 @@ Use for: multiple embedded surfaces sharing data context, components, and an emb
 
 The `.html` shell fetches `.contents.html`, injects it, then dynamically imports `.contents.js` if present. **Rule:** add `.contents.js` only when there's behavior to wire — a DUO with a dead `.contents.js` and a trio missing its setup are both smells.
 
-## State & data — which pattern (depth: `adia-ui-data`)
+Two adjacent contracts:
+
+- `setup` must be `async function setup(host)` when its body contains top-level `await` — extracting inline page script into a non-async `.contents.js` controller turns that `await` into a parse-time SyntaxError.
+- CSS never takes the `.contents.` infix. HTML/JS get it because they're the dynamically-injected fragment + controller; CSS loads statically via `<link>` in the `.html` shell head and styles chrome + contents together, so its name follows scope (per-app / shared / per-component), not the page-form convention.
+
+## State & data — which pattern
 
-`signal()`/`effect()` (single-surface reactivity) · Service/Controller/Command (mutations + undo) · `DataClient.read(projection)` + pure mappers, with **`action_source` required on every `mutate`** (shared-foundation) · property-API (`el.columns = […]`, never post-connect `<option>` children) · declarative `data-*` (static flows). The data skill owns the choice; this is the map.
+The state/data pattern follows the shape, not taste — but the choice is owned by `adia-data`: see [data-and-hydration.md](data-and-hydration.md) for the shape → pattern map.
 
 ## Components
 
-One folder per tag, mirroring the framework: `components/<tag>/<tag>.{js,css}` (folder name = custom-element tag). Authoring discipline: `authoring-components.md`.
+One folder per tag, mirroring the framework: `components/<tag>/<tag>.{js,css}` (folder name = custom-element tag). Authoring discipline: [authoring-components.md](authoring-components.md).
 
 ## Structure rubric `[gate]`
 
@@ -93,4 +91,4 @@ A project is well-structured when (gate = all `[gate]` hold):
 - **Components foldered** `[gate]` — every custom element is `components/<tag>/<tag>.{js,css}`.
 - **No duplicated cross-surface code** `[review]` — shared logic lives in `app/shared/` (or `_shared/`), not copied per page.
 
-Verify target for a scaffold/edit: this rubric passes, and any new surface renders through `adia-ui-verify`.
+Verify target for a scaffold/edit: this rubric passes, and any new surface renders through `adia-verify`.

package/references/shell-admin.md

@@ -2,7 +2,7 @@
 name: shell-admin
 load-when: authoring or debugging an admin-shell app frame (sidebar + topbar + command palette + pages)
 load-size: ~2.5k tokens
-required-for: [adia-ui-shells — admin path]
+required-for: [adia-shells — admin path]
 ---
 
 # admin-shell — the app frame
@@ -49,7 +49,7 @@ Full SaaS/admin chrome from `@adia-ai/web-modules`. Register the **cluster barre
 
 ## SPA vs SSR
 
-SPA mounts the full markup. SSR keeps the shell + chrome fixed and swaps only the **page body** via the framework outlet — replace the inner page content with `{children}` / `<slot/>`; never mount `<router-ui>` (see `adia-ui-ssr`).
+SPA mounts the full markup. SSR keeps the shell + chrome fixed and swaps only the **page body** via the framework outlet — replace the inner page content with `{children}` / `<slot/>`; never mount `<router-ui>` (see `adia-host`).
 
 ## Gotchas (mechanized where noted)
 
@@ -61,5 +61,8 @@ SPA mounts the full markup. SSR keeps the shell + chrome fixed and swaps only th
 - **Multiple `<admin-page>` in one `<admin-scroll>`** → single-axis scroll breaks; one page per scroll.
 - **`@container (…)` instead of `@container page-content (…)`** → won't react to sidebar collapse.
 - **Legacy shapes** (`<aside data-sidebar>`, `<dialog data-command>`) — retired v0.4.0 (`adia-lint` `LEGACY-SHELL`).
+- **Sidebar nav is `<nav-ui>` + `<nav-item-ui>`**, never `<menu-ui>`/`<menu-item-ui>` — menu-ui is for Popover-API dropdowns, not persistent navigation.
+- **Full-height mount:** an intermediate wrapper (`<main id="app">`) between `body { height: 100dvh; display: flex }` and the shell needs `flex: 1; display: flex; min-height: 0` — without it the flex chain breaks and the shell collapses to content height.
+- **`header-ui` has no CSS of its own** — its icon/heading/description/action grid comes from the parent's `@scope` (`admin-page-header` provides it); bespoke chrome reusing the header-ui vocabulary must supply the grid + text ellipsis locally.
 
 Real usage: `apps/saas/app/admin-dashboard/`.

package/references/shell-chat.md

@@ -2,12 +2,12 @@
 name: shell-chat
 load-when: authoring a chat-shell LLM conversation surface
 load-size: ~1.5k tokens
-required-for: [adia-ui-shells — chat path]
+required-for: [adia-shells — chat path]
 ---
 
 # chat-shell — the conversation surface
 
-LLM chat chrome from `@adia-ai/web-modules`. Register: `import '@adia-ai/web-modules/chat'`. The **LLM client/proxy/security** lives in `adia-ui-llm` — this is the _surface_; that is the _wiring_.
+LLM chat chrome from `@adia-ai/web-modules`. Register: `import '@adia-ai/web-modules/chat'`. The **LLM client/proxy/security** lives in `adia-llm` — this is the _surface_; that is the _wiring_.
 
 ## Cluster roster
 
@@ -33,12 +33,14 @@ LLM chat chrome from `@adia-ai/web-modules`. Register: `import '@adia-ai/web-mod
 
 ## Wiring to the LLM
 
-Set `proxy-url` (or, dev-only, `apiKey`) and the shell **auto-sends on submit** via `streamChat` and renders the stream for you. Otherwise it just emits `submit` — you call your endpoint and drive the UI with `appendChunk`/`done`/`error`. **Security:** the production pattern is a same-origin smart proxy that holds the key server-side — never ship a provider key to the browser. Full client/proxy contract: `adia-ui-llm`.
+Set `proxy-url` (or, dev-only, `apiKey`) and the shell **auto-sends on submit** via `streamChat` and renders the stream for you. Otherwise it just emits `submit` — you call your endpoint and drive the UI with `appendChunk`/`done`/`error`. **Security:** the production pattern is a same-origin smart proxy that holds the key server-side — never ship a provider key to the browser. Full client/proxy contract: `adia-llm`.
 
 ## Gotchas
 
 - Import the **chat barrel**; piecemeal imports leave children unregistered.
+- `chat-input-ui` internally renders `textarea-ui` + `select-ui` (web-components primitives, invisible in your authored HTML) — the app must register those primitives too, or they stay undefined and collapse to 0px.
 - Legacy shapes (`[data-chat-messages]`, `[data-chat-input]`, `[data-chat-empty]`, `[data-chat-name]`) were retired v0.4.0 — use the bespoke tags (`adia-lint` `LEGACY-SHELL`).
 - SSR: register `<chat-shell>` client-side like any component; keep the key server-side.
+- **Reasoning/trace panels must surface their own reliability** — a bare status label (`Domain: data`) reads identically at 3% and 95% confidence; a label that hides the data needed to judge it is pragmatically deceptive. Show the confidence with the claim.
 
 Real usage: `apps/genui/app/factory-chat/`.

package/references/shell-editor.md

@@ -2,7 +2,7 @@
 name: shell-editor
 load-when: authoring an editor-shell — a design tool / canvas with resizable side panes
 load-size: ~1.2k tokens
-required-for: [adia-ui-shells — editor path]
+required-for: [adia-shells — editor path]
 ---
 
 # editor-shell — the canvas + panes

package/references/shell-embed.md

@@ -1,43 +1,57 @@
 ---
 name: shell-embed
-load-when: authoring an embedded adia-ui surface (a light-DOM element a host page sizes/centers), or anticipating the official adia-embed-shell
+load-when: authoring an embedded adia-ui surface — a `<embed-shell>` framing a primary app plus secondary panels a host page sizes/centers
 load-size: ~1.5k tokens
-required-for: [adia-ui-shells — embed path]
+required-for: [adia-shells — embed path]
 ---
 
-# adia-embed-shell — embedded surface _(FORTHCOMING)_
+# embed-shell — embedded multi-surface frame
 
-> **Status: emerging.** There is **no `<adia-embed-shell>` web-module shipped yet.** This is the official promotion-in-progress of the **embedded-app pattern** (the patient-labs / population-health surfaces). Build to the pattern below today; when the shell ships, re-bake this reference (paired with the pinned a2ui MCP snapshot) and the API firms up. Treat exact shapes here as **[PATTERN]** (verified from the embedded app), not **[SHELL-API]** (doesn't exist yet).
+Embedded chrome from `@adia-ai/web-modules` (shell cluster). Register: `import '@adia-ai/web-modules/shell'`. Peer of admin/editor/chat shells; light-DOM, content-agnostic — it orchestrates layout of whatever `[app]` + `[panel]` children it's given, never the content or data.
 
-An **embedded surface** is a self-contained light-DOM custom element that a _host page_ (an EHR, another SaaS) positions and sizes — adia-ui owns the surface, the host owns the frame.
+## Cluster roster
 
-## The pattern (today) **[PATTERN]**
+`<embed-shell>` (host coordinator) — the only tag. Its children are consumer-supplied: one `[app]` primary surface + any number of `[panel="<name>"]` secondary surfaces. Extends `UIElement`, so `traits="resizable"` applies the real `resizable` trait (drag any edge + a `resize-end` event), not a CSS stand-in.
 
-- **A self-booting container.** One custom element (`<my-surface>`); `connected()` guarded by a `#booted` flag (it re-fires on DOM moves); it fetches its data and renders its own subtree. No framework wrapper, no shadow DOM.
-- **The host sizes/centers it.** The placer page positions the element (absolute + `translate(-50%, -50%)`); the surface does **not** hardcode width/height (size-agnostic — the consumer owns extent).
-- **Panel layout:** pinned header/footer + scrollable body via flex + `min-block-size: 0` on the scroll region.
-- **Data via projection.** `DataClient.read({ type, params })` returns typed projections from pure mappers (`app/shared/corpus/mappers/`); the surface never calls a backend directly. **Every `mutate` carries `action_source`** (attribution is required; the client throws without it). Depth: `adia-ui-data`.
-- **Routing (in-DOM tabs):** a content-less `<router-ui>` whose URL you manage yourself with `history.replaceState()` to preserve the host's query params — do **not** set `router.routes` (that fetches + replaces). (This is the one place an embedded surface uses `<router-ui>`; it's a self-contained SPA island, not an SSR page — see the hybrid note in `adia-ui-data`.)
-- **Shared foundation.** Multiple embedded surfaces live under a `shared-foundation` project shape (`app/shared/` for DataClient/mappers/tokens) — see `project-shapes.md`.
+## Canonical skeleton
 
-## Authoring checklist (until the shell ships)
+```html
+<embed-shell>
+  <patient-labs app></patient-labs>                 <!-- the primary surface (exactly one) -->
+  <settings-panel panel="settings"></settings-panel><!-- a secondary surface (any number) -->
+  <chat-panel panel="chat"></chat-panel>
+  <!-- triggers anywhere inside, delegated: -->
+  <button-ui opens="chat">Chat</button-ui>          <!-- toggles the named panel -->
+  <button-ui close></button-ui>                      <!-- dismisses the open panel -->
+</embed-shell>
+```
 
-1. Scaffold a `shared-foundation` app; put the surface under `app/<surface>/src/`.
-2. Author the surface as a self-booting light-DOM container (`#booted` guard, render in `connected()`).
-3. Wire data through `DataClient`/mappers; attribute every mutation.
-4. Keep it size-agnostic; let the host place it.
-5. Verify in a host harness (renders, zero console errors, non-zero box) — `adia-ui-verify`.
+## Contract · state · events
 
-## Live worked example
+- **Children:** `[app]` = primary (one); `[panel="<name>"]` = secondaries. `[opens="<name>"]` toggles a panel; `[close]` dismisses the open one — both delegated off a click on any descendant.
+- **State (reflected, ADR-0023):** `embed-shell[panel="chat"]` = which panel is open (`''`/absent = none); the open panel carries `[active]` (the CSS show/slide hook).
+- **Events:** `embed:open` (in) `detail:{panel}` = request to open/toggle; `embed:change` (out) `detail:{panel}` = emitted after the open panel changes.
+- **Methods:** `.open(name)` · `.close()` · `.toggle(name)`; getter `.panel` (open name or `''`). Escape closes the open panel.
+- **Layout (embed-shell.css):** ≥760px the open panel is a 50/50 column beside the app; <760px it's a cover sheet (`translateY` — **identity at rest**, so popovers inside still anchor via CSS anchor-positioning; an offsetting `translate(-50%,-50%)` would break them).
 
-The canonical implementation of this pattern is `apps/embedded-app/` in the adia-ui monorepo — the patient-labs and population-health surfaces built to the shared-foundation shape. Use it as the reference when authoring a new embedded surface:
+## Authoring the surfaces inside it
 
-- `apps/embedded-app/app/patient-labs/` — patient-labs surface (full Live/Labs/History/Briefing tab set, DataClient projection wiring, ambient-pill footer)
-- `apps/embedded-app/app/population-health/` — population-health surface (coverage metrics, facility breakdown)
-- `apps/embedded-app/app/shared/` — DataClient, CorpusLoader, mappers, shared tokens
+The shell owns the frame; each `[app]`/`[panel]` surface is a self-booting light-DOM container you author to the embedded-surface pattern:
 
-If you have access to the monorepo, read `apps/embedded-app/` before authoring a new embedded surface — the shape is proven and annotated.
+- **Self-booting** — `connected()` guarded by a `#booted` flag (it re-fires on DOM moves), fetches its data, renders its own subtree. No shadow DOM.
+- **Size-agnostic** — the surface never hardcodes width/height; the shell (and the host page) own extent.
+- **Data via projection** — `DataClient.read({ type, params })` returns typed projections from pure mappers (`app/shared/corpus/mappers/`); the surface never calls a backend directly. **Every `mutate` carries `action_source`** — the client throws without it. Depth: [`data-and-hydration.md`](data-and-hydration.md).
+- **In-DOM tabs** — a content-less `<router-ui>` whose URL you manage with `history.replaceState()` to preserve the host's query params; do **not** set `router.routes` (that fetches + `innerHTML`-replaces).
+- **Shared foundation** — multiple embedded surfaces live under a `shared-foundation` project shape (`app/shared/` for DataClient/mappers/tokens); see [`project-shapes.md`](project-shapes.md).
 
-## When it ships
+## SPA vs SSR
 
-The official `adia-embed-shell` is expected to package this chrome (the panel layout, the host-placement contract, the embed bridge) as a web-module like the others. At that point: register via the cluster barrel, replace the hand-rolled container chrome with the shell, and keep the DataClient/projection + attribution wiring. Until then, the pattern above **is** the contract.
+The shell mounts the full markup in SPA. For SSR, register it client-side like any component and keep any data keys server-side; it's a self-contained SPA island, not an SSR page (see the hybrid note in [`data-and-hydration.md`](data-and-hydration.md)).
+
+## Gotchas
+
+- **Piecemeal import** → `EmbedShell` unregistered; `.open()`/`.toggle()` undefined and panels collapse. Import the **shell barrel**.
+- **A trigger `opens="x"` with no matching `[panel="x"]` child** → `.open()` no-ops silently.
+- **Wrapping `[app]`/`[panel]` children in a layout `<div>`** → breaks the `:scope > [panel]` direct-child selectors the shell and CSS use.
+
+Real usage: `apps/embedded-app/` — patient-labs and population-health surfaces built to the shared-foundation shape (`app/patient-labs/`, `app/population-health/`, shared `app/shared/`). Read it before authoring a new embedded surface.

package/references/shell-simple.md

@@ -2,12 +2,12 @@
 name: shell-simple
 load-when: authoring a simple-shell — marketing / error / landing / auth page (minimal centered chrome)
 load-size: ~0.8k tokens
-required-for: [adia-ui-shells — simple path]
+required-for: [adia-shells — simple path]
 ---
 
 # simple-shell — minimal centered chrome
 
-The lightest shell from `@adia-ai/web-modules` — for marketing, landing, error (404/500/maintenance), thank-you, and auth pages. Register: `import '@adia-ai/web-modules/shell'` (simple ships in the shell cluster). Behavior-only host + two CSS-only children.
+The lightest shell from `@adia-ai/web-modules` — for marketing, landing, error (404/500/maintenance), thank-you, and auth pages. Register: `import '@adia-ai/web-modules/simple'` (simple is its own cluster barrel — the `/shell` barrel does not register it). Behavior-only host + two CSS-only children.
 
 ## Cluster roster
 
@@ -34,5 +34,8 @@ The lightest shell from `@adia-ai/web-modules` — for marketing, landing, error
 
 - Controls inside are `*-ui` (`button-ui`, `link-ui`), not raw `<button>`/`<a>` (`adia-lint` `NATIVE-PRIMITIVE`).
 - For an error page, a page-DUO (no `.contents.js`) is usually right — see `project-shapes.md`.
+- **Where the message goes on a status page:** an `<alert-ui>` carries the full message when the user is a *passive* recipient (session expired, account locked); the header `text-ui` carries it when the user is *actively* confirming something they initiated — the alert then only supplements.
+- **Prose/marketing header:** the centered pattern is a `<col-ui>` inside `<header>` with kicker + display heading + deck — not ad-hoc heading stacks.
+- Reach for this canonical shell before hand-rolling centered chrome: a new auth/status/maintenance surface (centered card, brand mark, heading, content) composes `simple-shell` + `<card-ui raw>` — authoring a parallel bespoke shell is how a 117-line stylesheet earns a 33-line replacement.
 
 Real usage: `apps/errors/`, `apps/user-flow/` (auth).

package/references/spa-architecture.md

@@ -1,10 +1,10 @@
 # SPA architecture
 
-The client-rendered path (vanilla / Vite static host). The framework is SPA-native: the components register at load, the page is one document, and routing/state live in the browser. If you're inside Next/Nuxt/SvelteKit/Astro instead, you're on the **SSR** path — see [ssr-integration.md](ssr-integration.md); the two diverge sharply on routing, registration, and state.
+The client-rendered path: a static host, Vite or vanilla. The framework is SPA-native — components register at load, the page is one document, routing and state live in the browser. Inside Next/Nuxt/SvelteKit/Astro instead? That's the **SSR** path — [ssr-integration.md](ssr-integration.md); the two diverge sharply on registration, routing, and state.
 
 ## The host document
 
-One static `index.html` whose job is to load CSS in cascade order and register components once:
+One static `index.html` whose job is to load CSS in cascade order and register components once. npm-consumer paths, which is what `adia-scaffold spa` emits (pre-wired for Vite — `vite.config.js` + `package.json` included):
 
 ```html
 <!doctype html>
@@ -12,13 +12,12 @@ One static `index.html` whose job is to load CSS in cascade order and register c
 <head>
   <meta charset="utf-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1" />
-  <link rel="stylesheet" href="/packages/web-components/styles/host.css" />   <!-- foundation: tokens + resets + page frame -->
-  <link rel="stylesheet" href="/packages/web-components/styles/index.css" />  <!-- barrel: every component's CSS -->
-  <link rel="stylesheet" href="/packages/web-components/styles/verse.css" />  <!-- opt-in register (only if a surface uses [verse]) -->
-  <link rel="stylesheet" href="./index.css" />                               <!-- page framing: sizes + centers the surface -->
-  <link rel="stylesheet" href="./components/my-surface/my-surface.css" />    <!-- the surface's own chrome -->
-  <script type="module" src="/packages/web-components/index.js"></script>    <!-- registers EVERY primitive (incl. router-ui) -->
-  <script type="module" src="./components/my-surface/my-surface.js"></script>
+  <link rel="stylesheet" href="/node_modules/@adia-ai/web-components/styles/host.css" />   <!-- foundation: tokens + resets + page frame -->
+  <link rel="stylesheet" href="/node_modules/@adia-ai/web-components/styles/index.css" />  <!-- barrel: every component's CSS (link BOTH) -->
+  <link rel="stylesheet" href="/node_modules/@adia-ai/web-components/styles/verse.css" />  <!-- opt-in register (only if a surface uses [verse]) -->
+  <link rel="stylesheet" href="./index.css" />                              <!-- page framing: sizes + centers the surface -->
+  <link rel="stylesheet" href="./components/my-surface/my-surface.css" />   <!-- the surface's own chrome -->
+  <script type="module" src="./components/my-surface/my-surface.js"></script> <!-- its FIRST import is the registration barrel -->
 </head>
 <body>
   <my-surface verse></my-surface>
@@ -26,54 +25,33 @@ One static `index.html` whose job is to load CSS in cascade order and register c
 </html>
 ```
 
-> **Note — monorepo paths vs real npm consumer.** The `/packages/web-components/...` paths above only resolve inside the AdiaUI monorepo dev server. A real npm consumer has two options:
->
-> - **Vite (recommended):** `npm install @adia-ai/web-components`, add a `vite.config.js` (the `adia-scaffold spa` bin emits one), then replace the paths with `/node_modules/@adia-ai/web-components/styles/host.css` etc. — Vite serves node_modules at that prefix during dev and bundles them at build time. Bare `@adia-ai/*` specifiers in `.js` files resolve automatically.
-> - **Import-map / CDN (no bundler):** add an `<script type="importmap">` mapping `"@adia-ai/web-components"` to your CDN URL (e.g. `https://esm.sh/@adia-ai/web-components`), and adjust the CSS link hrefs to match.
->
-> The `adia-scaffold spa` output is pre-wired for the Vite path (`vite.config.js` + `package.json` included).
+Vite serves `/node_modules/...` hrefs during dev and bundles them at build; bare `@adia-ai/*` specifiers in `.js` files resolve automatically. Two alternatives:
 
-**Cascade order is load-bearing** (later wins): foundation → barrel → register → page → component. Invariants:
+- **Import-map / CDN (no bundler):** a `<script type="importmap">` mapping `"@adia-ai/web-components"` to a CDN URL (e.g. `https://esm.sh/@adia-ai/web-components`); adjust the CSS hrefs to match.
+- **Monorepo dev server (framework contributors only):** `/packages/web-components/styles/*.css` + `/packages/web-components/index.js` paths — not a consumer deployment mode.
 
-- Link **both** `host.css` and `styles/index.css`. Post-0.7.6 the barrel was split — `host.css` is foundation-only, so linking it alone renders primitives unstyled.
-- **One** registration script (`/packages/web-components/index.js`). Don't piecemeal-import primitives across the page.
-- Never hand-roll `:where(html,body){}` — the foundation owns the page frame; re-rolling it drifts from the system (the classic serif-leak bug).
-- A register has two halves: link `verse.css` **and** put `verse` on the surface. One without the other is a no-op.
-
-## Four-axis project structure
-
-```text
-my-app/
-├── spec/     design axis — BRIEF · ARCHITECTURE · SPEC · screen specs
-├── plan/     execution axis — ROADMAP · MILESTONES · PLAN
-├── skills/   procedural-knowledge axis — the app's own expert skill (optional)
-└── app/
-    ├── shared/   cross-surface source — DataClient, loaders, mappers, images
-    └── <surface>/src/
-        ├── index.html              the host shell (above)
-        ├── index.css               page framing
-        └── components/<tag>/<tag>.{js,css}
-```
+## Registration & cascade invariants
 
-Keep design (`spec/`), plan (`plan/`), and source (`app/`) on separate axes — the spec is the contract, the plan is the sequence, the app is the build.
+**Cascade order is load-bearing** (later wins): foundation → barrel → register → page → component.
 
-## The page-trio (and when it collapses)
+- Link **both** `host.css` and `styles/index.css`. The styles barrel is split: `host.css` carries only the foundation (tokens + resets + page frame), so linking it alone renders primitives unstyled.
+- CSS arrives via `<link>`, never via the JS import — Vite serves component CSS outside the module graph, so a JS-only side-effect import registers the element but leaves it unstyled.
+- **One registration script** — the side-effecting barrel `import '@adia-ai/web-components'`. Don't piecemeal-import primitives: composites render internal `*-ui` tags (e.g. `chat-input-ui` internally renders `textarea-ui` + `select-ui`) that stay unregistered and collapse to 0px unless the barrel ran.
+- Bespoke shell children need the **cluster barrel** (`@adia-ai/web-modules/shell`, `/chat`, `/editor`, `/simple`) — importing `admin-shell.js` alone registers only the host tag, not `admin-sidebar` / `admin-page` / the other children.
+- Never hand-roll `:where(html,body){}` — the foundation owns the page frame; re-rolling it drifts from the system (the classic serif-leak bug).
+- A `verse` register has two halves: link `verse.css` **and** put `verse` on the surface. One without the other is a no-op.
+- `themes.css` (named palettes) is **not** in the styles barrel — link it separately. `data-scheme` switches light/dark; `data-theme` picks the named palette.
+- Guards: `defineIfFree(tag, ctor)` (`core/register.js`) for defines; a `#booted` flag in `connected()` — the callback re-fires on DOM moves. And `customElements.whenDefined(name)` never rejects: a `Promise.all([...whenDefined])` boot gate hangs forever on one unimported tag — chrome renders (tag-keyed CSS), the page stays "empty", zero console errors.
 
-A standalone page is a triplet:
+## The surface container
 
-| File | Owns |
-| --- | --- |
-| `<page>.html` | static shell — meta, CSS/script links, a mount point |
-| `<page>.contents.html` | the markup, **fetched** and injected at runtime |
-| `<page>.contents.js` | `setup(root)` — wires behavior after the markup lands |
+An app surface is a self-booting custom element — it fetches its data and renders its own subtree in `connected()`:
 
 ```js
-const root = document.getElementById('demo-root');
-root.innerHTML = await (await fetch('./page.contents.html')).text();
-(await import('./page.contents.js')).default?.(root);   // setup(root)
+connected() { if (this.#booted) return; this.#booted = true; this.#load(); }
 ```
 
-In a real app the trio usually **collapses into the surface's own custom-element lifecycle** — the container fetches its data and renders its own subtree in `connected()`, so there's no separate `.contents.*` pair. Use the trio for playground/demo pages; use a self-booting container for app surfaces.
+Standalone demo/playground pages use the page-trio instead; the trio/DUO decision table, the four-axis layout, and the structure rubric live in [project-shapes.md](project-shapes.md) (owned by `adia-project`).
 
 ## Routing — content-less `<router-ui>`
 
@@ -91,33 +69,10 @@ my-surface router-ui[data-route-path="/live"] .live { display: flex; }
 
 A **content-mode** route (one carrying `content`) makes the router fetch and `innerHTML`-replace — which wipes stamped views, scroll, and focus. That's the wrong tool for in-DOM tabs. Never `innerHTML` a view on switch; show/hide.
 
-## Data-flow — `DataClient` → projection
-
-The UI never talks to a backend. It reads typed **projections** from a `DataClient`; a pure mapper is the swap seam between fixtures and a real API:
-
-```text
-DataClient.read({ type: 'LabRecommendationSet', params })   ← the only surface the UI sees
-   → runMapper(query, loader)                                ← pure (sources) => Projection; the v1-fixture ⇄ v2-API seam
-      → CorpusLoader.load*()                                 ← fetches the source data
-```
-
-- Components consume **projections only** — no backend calls, no re-deriving projections in the view, no per-view reshaping (the projection type _is_ the contract).
-- **Attribution is structural:** every `mutate` requires an `action_source`; the client throws without it.
-
-  ```js
-  await client.mutate({ type: 'order', payload }, { action_source: btn.dataset.action });
-  ```
-
-## State — single owner
-
-One owner per piece of state, no shadow copies:
-
-- the **route** owns which view is active,
-- the **component** owns selection sets / UI toggles,
-- the **DataClient** owns fetched data.
+## Data & state
 
-A control mutates the route; an observer or CSS reflects the route **into** the DOM — never the reverse. Mirror with a `MutationObserver` on `data-route-path`, not a second source of truth.
+Owned by `adia-data` — see [data-and-hydration.md](data-and-hydration.md) for the five data-flow patterns, the DataClient → projection pipeline, the attribution gate (`mutate` throws without an `action_source`), and single-owner state (the route owns the active view; a control mutates the route, an observer/CSS reflects it back — never a second source of truth).
 
 ## Exit gate
 
-A surface isn't done when it compiles — it's done when it passes the **browser gate** (zero console errors on load, non-zero bounding boxes, and you've _read_ the screenshot) plus the a11y and git checks. That gate is the `adia-ui-verify` skill. Re-baseline git at the start of every turn, stage explicit allowlists (never `git add -A` on a shared clone), and confirm the branch before committing.
+A surface isn't done when it compiles — it's done when it passes the **browser gate**: zero console errors on load, non-zero bounding boxes, and the screenshot actually read. That gate is the `adia-verify` skill.

package/references/ssr-integration.md

@@ -2,7 +2,7 @@
 
 Consuming adia-ui components **inside an SSR framework** (Next.js, Nuxt, SvelteKit, Astro, …). Same components, same UI, **wildly different architecture** from the SPA path — the framework owns routing, registration must be deferred to the client, and state can't live in component-lifetime signals.
 
-> **Honesty about sources.** The framework's `rendering-model` doc explicitly covers Next/Nuxt/SvelteKit/Astro — those patterns are marked **[D]** (documented) below. Frameworks it names in its routing table but doesn't give wiring for (Remix, Rails/Turbo, Django/HTMX, Phoenix) are marked **[G]** — the _rule_ (one route owner; client-only registration) holds, but the wiring is your framework's standard pattern, not something the kit ships. Don't present **[G]** patterns as kit-guaranteed.
+> **Honesty about sources.** The kit's own documentation explicitly covers Next/Nuxt/SvelteKit/Astro — those patterns are marked **[D]** (documented) below. Frameworks it names in its routing table but doesn't give wiring for (Remix, Rails/Turbo, Django/HTMX, Phoenix) are marked **[G]** — the _rule_ (one route owner; client-only registration) holds, but the wiring is your framework's standard pattern, not something the kit ships. Don't present **[G]** patterns as kit-guaranteed.
 
 ## Why SSR is different