@adia-ai/web-modules 0.4.7 → 0.4.8

package/CHANGELOG.md

@@ -11,6 +11,32 @@ Built from `@adia-ai/web-components` primitives.
 
 _No pending changes._
 
+## [0.4.8] - 2026-05-12
+
+### Added — TypeScript declarations for all web-modules (FEEDBACK-02 #1, v0.4.8)
+
+Closes consumer-friction item #1 from FEEDBACK-adia-packages-02. Hand-codegen'd `.d.ts` declarations now ship for every web-module across all clusters:
+
+- **chat** (6): `chat-composer`, `chat-shell`, `chat-sidebar`, `chat-thread` + supporting types.
+- **editor** (5): `editor-canvas`, `editor-shell`, `editor-sidebar`, `editor-toolbar` + supporting types.
+- **runtime** (2): `a2ui-root`, `gen-root`.
+- **admin shell** (10): admin-command, admin-content, admin-page, admin-page-{body,header}, admin-scroll, admin-shell, admin-sidebar, admin-statusbar, admin-topbar.
+- **simple** + **theme** clusters: companion `.d.ts` files for the remaining modules.
+
+TypeScript consumers now get typed `document.querySelector('admin-shell')` returns `AdminShell`, typed reflected properties, typed methods (`.toggle()`, `.collapse()`, etc.), and typed custom events. `HTMLElementTagNameMap` augmentation in the package barrel makes the tag-name lookups type-aware. Mirrors the `@adia-ai/web-components@0.4.7` §74 codegen pattern.
+
+### Added — `composes:` field on YAMLs + `.a2ui.json` regen (ADR-0027 wiring, v0.4.8)
+
+Each web-module YAML now declares a `composes:` field listing the `@adia-ai/web-components` primitives it instantiates internally. ADR-0027 (cross-primitive composition imports are consumer's responsibility) becomes mechanically auditable — the `composes:` linter ships in this release and runs as part of `npm run components`. `.a2ui.json` sidecars regenerated to surface the `composes:` data through the v0.9 catalog.
+
+`chat-shell.yaml` + `gen-root.yaml` documented the LLM-pipeline wiring expectations alongside the composes declarations.
+
+### Documentation — lexical-scope authoring guide
+
+`README.md` § Module authoring updated with the `composes:` field semantics + lexical-scope rationale (why composes-declared imports must live at the consumer page, not transitively pulled by the module). Aligns with §66's `adaptV09Component()` catalog reader work.
+
+See root [CHANGELOG.md `[Unreleased]`](../../CHANGELOG.md) for the cross-cutting arc narrative.
+
 ## [0.4.7] - 2026-05-12
 
 ### Changed — `chat/chat-thread.yaml` populates `synonyms.tags` (§72)

package/chat/chat-composer/chat-composer.a2ui.json

@@ -29,6 +29,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "input",
+    "composes": [],
     "events": {
       "composer-submit": {
         "description": "Bubbles when the inner input fires its 'submit' event. Detail mirrors the inner event's detail (typically text + model).",

package/chat/chat-composer/chat-composer.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `<chat-composer-ui>` — Module-tier chat composer wrapper — replaces legacy <chat-input-ui
+data-chat-input> direct child of <chat-shell> per ADR-0023.
+Forwards submit events as 'composer-submit', propagates [disabled]
+to the inner input, provides slot vocabulary for future composer
+surfaces (file attach, autocomplete, model picker).
+
+Sits inside <chat-shell> as the input region (typically inside or
+alongside the footer). Authors place an inner <chat-input-ui>
+(or input-ui / textarea-ui) as the primary input.
+
+Backwards compat — <chat-shell> still recognizes the legacy
+<chat-input-ui data-chat-input> shape via :is() selector. New
+code should prefer <chat-composer>.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/chat-composer
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../../web-components/core/element.js';
+
+export interface ChatComposerComposerSubmitEventDetail {
+  model: string;
+  text: string;
+}
+
+export type ChatComposerComposerSubmitEvent = CustomEvent<ChatComposerComposerSubmitEventDetail>;
+
+export class UIChatComposer extends UIElement {
+  /** Reflected — set by the host while streaming, or by application
+code. Propagated to the inner input element automatically.
+ */
+  disabled: boolean;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIChatComposer, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'composer-submit', listener: (ev: ChatComposerComposerSubmitEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/chat/chat-empty/chat-empty.a2ui.json

@@ -24,6 +24,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "feedback",
+    "composes": [],
     "events": {},
     "examples": [],
     "keywords": [

package/chat/chat-header/chat-header.a2ui.json

@@ -24,6 +24,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [],
     "events": {},
     "examples": [],
     "keywords": [

package/chat/chat-shell/chat-shell.a2ui.json

@@ -54,6 +54,9 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "container",
+    "composes": [
+      "code-ui"
+    ],
     "events": {
       "abort": {
         "description": "Fired when the user aborts an in-flight request."

package/chat/chat-shell/chat-shell.d.ts

@@ -0,0 +1,86 @@
+/**
+ * `<chat-shell-ui>` — Behavior-only chat orchestrator (LLM-streaming module). Author supplies the
+DOM structure via [data-chat-messages], [data-chat-input], [data-chat-empty],
+[data-chat-status] elements; chat-shell wires message streaming, markdown
+rendering, code-block upgrades, and an LLM integration path via proxy-url
+(or via external submit).
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/chat-shell
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../../web-components/core/element.js';
+
+export type ChatShellAbortEvent = CustomEvent<unknown>;
+export interface ChatShellChunkEventDetail {
+  snapshot: string;
+  text: string;
+}
+
+export type ChatShellChunkEvent = CustomEvent<ChatShellChunkEventDetail>;
+export type ChatShellClearEvent = CustomEvent<unknown>;
+export interface ChatShellDoneEventDetail {
+  stopReason: string;
+  text: string;
+  usage: string;
+}
+
+export type ChatShellDoneEvent = CustomEvent<ChatShellDoneEventDetail>;
+export interface ChatShellErrorEventDetail {
+  error: string;
+}
+
+export type ChatShellErrorEvent = CustomEvent<ChatShellErrorEventDetail>;
+export interface ChatShellMessageEventDetail {
+  content: string;
+  id: string;
+  role: string;
+}
+
+export type ChatShellMessageEvent = CustomEvent<ChatShellMessageEventDetail>;
+export interface ChatShellSubmitEventDetail {
+  model: string;
+  text: string;
+}
+
+export type ChatShellSubmitEvent = CustomEvent<ChatShellSubmitEventDetail>;
+export interface ChatShellThinkingEventDetail {
+  text: string;
+}
+
+export type ChatShellThinkingEvent = CustomEvent<ChatShellThinkingEventDetail>;
+
+export class UIChatShell extends UIElement {
+  /** Model identifier. */
+  model: string;
+  /** LLM provider name (anthropic | openai | google | stub). */
+  provider: string;
+  /** API proxy endpoint for LLM calls; enables self-contained chat without external wiring. */
+  proxyUrl: string;
+  /** Active streaming indicator; toggled while a response is being received. */
+  streaming: boolean;
+  /** System prompt prepended to conversations. */
+  system: string;
+  /** Enable Anthropic extended-thinking mode. */
+  thinking: boolean;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIChatShell, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'abort', listener: (ev: ChatShellAbortEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'chunk', listener: (ev: ChatShellChunkEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'clear', listener: (ev: ChatShellClearEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'done', listener: (ev: ChatShellDoneEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'error', listener: (ev: ChatShellErrorEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'message', listener: (ev: ChatShellMessageEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'submit', listener: (ev: ChatShellSubmitEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'thinking', listener: (ev: ChatShellThinkingEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/chat/chat-shell/chat-shell.yaml

@@ -11,6 +11,10 @@ description: |
   rendering, code-block upgrades, and an LLM integration path via proxy-url
   (or via external submit).
 
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - code-ui
 props:
   streaming:
     type: boolean

package/chat/chat-sidebar/chat-sidebar.a2ui.json

@@ -54,6 +54,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [],
     "events": {
       "sidebar-resize": {
         "description": "Bubbles when an active pointer-drag releases.",

package/chat/chat-sidebar/chat-sidebar.d.ts

@@ -0,0 +1,70 @@
+/**
+ * `<chat-sidebar-ui>` — Module-tier chat-cluster sidebar — owns resize, snap-to-collapsed,
+persistence, and the [collapsed] reflected attribute. Sits inside
+<chat-shell> as slot="leading" (conversation history rail) or
+slot="trailing" (artifacts/citations panel). Mirrors the admin-sidebar
+shape — same 4 concerns, cluster-namespaced for the chat family.
+
+This is the chat-cluster equivalent of <admin-sidebar> per ADR-0023.
+<chat-shell> doesn't currently have a legacy sidebar shape (chat is
+typically a single-pane experience), so <chat-sidebar> is purely
+forward-looking — for chat apps that want conversation-history or
+inspector rails.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/chat-sidebar
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../../web-components/core/element.js';
+
+export interface ChatSidebarSidebarResizeEventDetail {
+  name: string;
+  width: string;
+}
+
+export type ChatSidebarSidebarResizeEvent = CustomEvent<ChatSidebarSidebarResizeEventDetail>;
+export interface ChatSidebarSidebarToggleEventDetail {
+  expanded: string;
+  name: string;
+}
+
+export type ChatSidebarSidebarToggleEvent = CustomEvent<ChatSidebarSidebarToggleEventDetail>;
+
+export class UIChatSidebar extends UIElement {
+  /** Reflected — set when the sidebar's measured width is at or below
+96px. Consumers query this to style "collapsed mode" without
+duplicating threshold math.
+ */
+  collapsed: boolean;
+  /** Opts in to programmatic collapse — toggle button wiring + the
+.toggle() / .collapse() / .expand() public methods.
+ */
+  collapsible: boolean;
+  /** Identifier for localStorage namespacing. Defaults to slot value
+("leading" or "trailing"). Override when running multiple sidebars
+with the same slot.
+ */
+  name: string;
+  /** Opts in to drag-to-resize behavior. Author supplies a child
+[data-resize] element as the drag handle.
+ */
+  resizable: boolean;
+  /** Reflected — set during an active pointer-drag on the resize handle.
+Useful for suppressing transitions while dragging.
+ */
+  resizing: boolean;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIChatSidebar, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'sidebar-resize', listener: (ev: ChatSidebarSidebarResizeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'sidebar-toggle', listener: (ev: ChatSidebarSidebarToggleEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/chat/chat-status/chat-status.a2ui.json

@@ -24,6 +24,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "feedback",
+    "composes": [],
     "events": {},
     "examples": [],
     "keywords": [

package/chat/chat-thread/chat-thread.a2ui.json

@@ -34,6 +34,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "container",
+    "composes": [],
     "events": {},
     "examples": [],
     "keywords": [

package/chat/chat-thread/chat-thread.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `<chat-thread-ui>` — Module-tier chat message thread container — replaces legacy
+<section data-chat-messages> per ADR-0023. Owns scroll-to-bottom
+on new message (with user-scroll-up suspension), [streaming] and
+[empty] reflected attributes, and a stable target for the host's
+message rendering pipeline.
+
+Sits inside <chat-shell> as the central scroll surface. Authors
+compose <chat-empty> as an optional first child for the empty
+state; message children are appended dynamically by the host.
+
+Backwards compat — <chat-shell> still recognizes the legacy
+<section data-chat-messages> shape via :is() selector. New code
+should prefer <chat-thread>.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/chat-thread
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../../web-components/core/element.js';
+
+export class UIChatThread extends UIElement {
+  /** Reflected — set when zero message children. Drives the
+<chat-empty> visibility via CSS — no JS toggling needed.
+ */
+  empty: boolean;
+  /** Reflected — set by the host while an LLM response is streaming.
+Consumers can style streaming-mode (e.g. cursor blink) via
+:has(chat-thread[streaming]) or attribute selectors.
+ */
+  streaming: boolean;
+}

package/editor/editor-canvas/editor-canvas.a2ui.json

@@ -34,6 +34,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "container",
+    "composes": [],
     "events": {},
     "examples": [],
     "keywords": [

package/editor/editor-canvas/editor-canvas.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `<editor-canvas-ui>` — Module-tier editor canvas surface — replaces legacy <div data-canvas>
+inside <editor-shell> per ADR-0023. Owns scroll/zoom container
+semantics, [empty] and [focused] reflected attributes, and a stable
+target for the host's content rendering pipeline.
+
+Sits as the central content region inside <editor-shell>, between
+the optional <editor-sidebar slot="leading"> and <editor-sidebar
+slot="trailing">. Authors compose <editor-canvas-empty> as an
+optional first child for the empty state; canvas content children
+(artboards, document body, etc.) are appended either statically or
+dynamically by the host.
+
+Backwards compat — <editor-shell> still recognizes the legacy
+<div data-canvas> shape via :is() selector. New code should prefer
+<editor-canvas>.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/editor-canvas
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../../web-components/core/element.js';
+
+export class UIEditorCanvas extends UIElement {
+  /** Reflected — set when zero non-<editor-canvas-empty> children.
+Drives the <editor-canvas-empty> visibility via parent CSS —
+no JS toggling needed.
+ */
+  empty: boolean;
+  /** Reflected — set when canvas claims focus ownership (programmatic
+.focus() call or toolbar full-screen toggle).
+ */
+  focused: boolean;
+}

package/editor/editor-canvas-empty/editor-canvas-empty.a2ui.json

@@ -24,6 +24,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "feedback",
+    "composes": [],
     "events": {},
     "examples": [],
     "keywords": [

package/editor/editor-shell/editor-shell.a2ui.json

@@ -24,6 +24,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "container",
+    "composes": [],
     "events": {},
     "examples": [],
     "keywords": [

package/editor/editor-shell/editor-shell.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `<editor-shell-ui>` — Behavior-only editor shell module for design-tool layouts. Author
+provides the structural DOM — header (topbar), [data-editor-body] with
+pane-ui children ([data-left], [data-right]), [data-canvas] for the
+central surface, and a footer (statusbar). editor-shell wires
+select-ui[data-options] for JSON-parsed option lists.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/editor-shell
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../../web-components/core/element.js';
+
+export class UIEditorShell extends UIElement {
+}

package/editor/editor-sidebar/editor-sidebar.a2ui.json

@@ -34,6 +34,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [],
     "events": {
       "sidebar-toggle": {
         "description": "Bubbles when .toggle() / .collapse() / .expand() is called.",

package/editor/editor-sidebar/editor-sidebar.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `<editor-sidebar-ui>` — Module-tier editor-cluster sidebar — wraps <pane-ui resizable>
+(the primitive that owns drag) and adds [collapsed] reflected
+state, localStorage persistence (adia-editor-sidebar-{name}),
+and .toggle() / .collapse() / .expand() public API.
+
+Sits inside <editor-shell> as slot="leading" (navigator pane) or
+slot="trailing" (inspector pane). Mirrors the cluster-namespace
+shape from <admin-sidebar> and <chat-sidebar>, but DELEGATES to
+<pane-ui> for resize rather than reimplementing it (per
+bespoke-shell-children skill §When NOT to promote — pane primitive
+already owns this concern).
+
+This is the FIRST bespoke shell child that delegates rather than
+duplicates a primitive's behavior. Pattern is: cluster-namespace +
+state-as-attribute + persistence at the bespoke tier; physical
+drag at the primitive tier.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/editor-sidebar
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../../web-components/core/element.js';
+
+export interface EditorSidebarSidebarToggleEventDetail {
+  expanded: string;
+  name: string;
+}
+
+export type EditorSidebarSidebarToggleEvent = CustomEvent<EditorSidebarSidebarToggleEventDetail>;
+
+export class UIEditorSidebar extends UIElement {
+  /** Reflected — set when inner <pane-ui> width is at or below 96px snap threshold. */
+  collapsed: boolean;
+  /** Reflected — set during an active pointer-drag of the pane's
+resize handle. Used to disable transitions and visual treatments
+that would feel laggy during drag.
+ */
+  resizing: boolean;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIEditorSidebar, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'sidebar-toggle', listener: (ev: EditorSidebarSidebarToggleEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/editor/editor-statusbar/editor-statusbar.a2ui.json

@@ -24,6 +24,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [],
     "events": {},
     "examples": [],
     "keywords": [

package/editor/editor-toolbar/editor-toolbar.a2ui.json

@@ -29,6 +29,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [],
     "events": {
       "toolbar-action": {
         "description": "Bubbles when a child element with [data-toolbar-action] is clicked. Detail carries the action name from the clicked element's attribute.",

package/editor/editor-toolbar/editor-toolbar.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `<editor-toolbar-ui>` — Module-tier editor toolbar — replaces legacy <header> chrome bar
+inside <editor-shell> per ADR-0023. Owns the [full-screen] reflected
+attribute (set when host enters focus mode), click-bubble for
+[data-toolbar-action] buttons, and slot vocabulary routing.
+
+Sits at the top of <editor-shell>. Authors compose actions + status
+via slot vocabulary. The host (<editor-shell>) reads either
+<editor-toolbar> or <header> via :is() selector for backwards compat.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/editor-toolbar
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../../web-components/core/element.js';
+
+export interface EditorToolbarToolbarActionEventDetail {
+  name: string;
+}
+
+export type EditorToolbarToolbarActionEvent = CustomEvent<EditorToolbarToolbarActionEventDetail>;
+
+export class UIEditorToolbar extends UIElement {
+  /** Reflected — set when editor is in distraction-free / focus mode. */
+  fullScreen: boolean;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIEditorToolbar, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'toolbar-action', listener: (ev: EditorToolbarToolbarActionEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/web-modules",
-  "version": "0.4.7",
+  "version": "0.4.8",
   "description": "AdiaUI composite custom elements — shell, chat, editor, runtime clusters built from @adia-ai/web-components primitives. Subpath exports per cluster.",
   "type": "module",
   "exports": {

package/runtime/a2ui-root/a2ui-root.a2ui.json

@@ -60,6 +60,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "container",
+    "composes": [],
     "events": {
       "a2ui-action": {
         "description": "Fired when a child element with [data-action] is clicked. detail: { name, sourceComponentId, context }"

package/runtime/a2ui-root/a2ui-root.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `<a2ui-root-ui>` — A2UI protocol surface. Connects to a stream source (SSE, WebSocket, JSONL, MCP) and renders A2UI messages as AdiaUI components via the `@adia-ai/a2ui-utils` renderer.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/a2ui-root
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../../web-components/core/element.js';
+
+export type A2UIRootA2uiActionEvent = CustomEvent<unknown>;
+export type A2UIRootA2uiClosedEvent = CustomEvent<unknown>;
+export type A2UIRootA2uiConnectedEvent = CustomEvent<unknown>;
+export type A2UIRootA2uiErrorEvent = CustomEvent<unknown>;
+export type A2UIRootA2uiMessageEvent = CustomEvent<unknown>;
+export type A2UIRootDocReplacedEvent = CustomEvent<unknown>;
+
+export class UIA2UIRoot extends UIElement {
+  /** True while the stream is connected and receiving messages. */
+  active: boolean;
+  /** Batch renderer updates via requestAnimationFrame for large fan-in. */
+  batch: boolean;
+  /** Author-driven mode — set to an array of A2UI messages and the renderer resets + replays them. No network/transport involvement. Setting to a new array triggers a full re-render. Use this for editors, previews, tests, and any static-doc authoring loop. When both `src` and `doc` are set, `doc` wins (the stream is not opened). Pass as a JS property; not reflected to an attribute. */
+  doc: unknown[];
+  /** True while the stream is connecting. */
+  loading: boolean;
+  /** Stream source URL (endpoint for SSE/WebSocket, file path for JSONL, tool-call target for MCP). */
+  src: string;
+  /** Stream transport to use. */
+  transport: 'sse' | 'ws' | 'websocket' | 'jsonl' | 'mcp';
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIA2UIRoot, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'a2ui-action', listener: (ev: A2UIRootA2uiActionEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'a2ui-closed', listener: (ev: A2UIRootA2uiClosedEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'a2ui-connected', listener: (ev: A2UIRootA2uiConnectedEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'a2ui-error', listener: (ev: A2UIRootA2uiErrorEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'a2ui-message', listener: (ev: A2UIRootA2uiMessageEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'doc-replaced', listener: (ev: A2UIRootDocReplacedEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/runtime/gen-root/gen-root.a2ui.json

@@ -39,6 +39,11 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [
+      "chat-thread-ui",
+      "canvas-ui",
+      "inspector-ui"
+    ],
     "events": {},
     "examples": [],
     "keywords": [

package/runtime/gen-root/gen-root.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `<gen-root-ui>` — Composition shell for chat + canvas generative UI. Manages layout modes
+(chat-only / split / canvas-only) and delegates a unified API across
+child chat-ui, canvas-ui, and inspector-ui elements.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/gen-root
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../../web-components/core/element.js';
+
+export class UIGenRoot extends UIElement {
+  /** Show the inspector pane (for debugging generated A2UI). */
+  inspector: boolean;
+  /** Layout mode — chat-only, 50/50 split, or canvas-only. */
+  mode: 'chat' | 'split' | 'canvas';
+}

package/runtime/gen-root/gen-root.yaml

@@ -9,6 +9,12 @@ description: |
   (chat-only / split / canvas-only) and delegates a unified API across
   child chat-ui, canvas-ui, and inspector-ui elements.
 
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - chat-thread-ui
+  - canvas-ui
+  - inspector-ui
 props:
   mode:
     type: string

package/shell/admin-command/admin-command.a2ui.json

@@ -44,6 +44,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "interaction",
+    "composes": [],
     "events": {
       "command-select": {
         "description": "Forwarded from the inner <command-ui> when an option is chosen. Detail mirrors the inner event's detail.",

package/shell/admin-command/admin-command.d.ts

@@ -0,0 +1,50 @@
+/**
+ * `<admin-command-ui>` — Module-tier command palette wrapper — wraps a native <dialog> and the
+inner <command-ui>. Owns the keyboard shortcut listener, focus
+management, and dismiss handlers. Reflects [open].
+
+Sits inside <admin-shell> as a direct child. The host wires
+[data-command-trigger] elements to <admin-command>.show() via lookup.
+
+This is the bespoke web-component replacement for the legacy
+<dialog data-command> shape. <admin-shell> still recognizes the
+legacy shape via :is() selector. New code should prefer <admin-command>.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/admin-command
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../../web-components/core/element.js';
+
+export interface AdminCommandCommandSelectEventDetail {
+  value: string;
+}
+
+export type AdminCommandCommandSelectEvent = CustomEvent<AdminCommandCommandSelectEventDetail>;
+
+export class UIAdminCommand extends UIElement {
+  /** Reflected — set while the dialog is showing. Synced with both
+programmatic .show()/.hide() and native dialog close events
+(esc key, backdrop click).
+ */
+  open: boolean;
+  /** Keyboard shortcut binding. "cmd+k" responds only on Mac
+(metaKey); "ctrl+k" responds only when ctrlKey; "both" (default)
+responds to either, which is the canonical AdiaUI behavior for
+cross-platform Cmd+K affordance.
+ */
+  shortcut: 'both' | 'cmd+k' | 'ctrl+k';
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIAdminCommand, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'command-select', listener: (ev: AdminCommandCommandSelectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/shell/admin-content/admin-content.a2ui.json

@@ -24,6 +24,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [],
     "events": {},
     "examples": [],
     "keywords": [

package/shell/admin-page/admin-page.a2ui.json

@@ -24,6 +24,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [],
     "events": {},
     "examples": [],
     "keywords": [

package/shell/admin-page-body/admin-page-body.a2ui.json

@@ -24,6 +24,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [],
     "events": {},
     "examples": [],
     "keywords": [

package/shell/admin-page-header/admin-page-header.a2ui.json

@@ -24,6 +24,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [],
     "events": {},
     "examples": [],
     "keywords": [

package/shell/admin-scroll/admin-scroll.a2ui.json

@@ -24,6 +24,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [],
     "events": {},
     "examples": [],
     "keywords": [

package/shell/admin-shell/admin-shell.a2ui.json

@@ -34,6 +34,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [],
     "events": {
       "command-select": {
         "description": "Forwarded from the command palette when an option is chosen.",

package/shell/admin-shell/admin-shell.d.ts

@@ -0,0 +1,49 @@
+/**
+ * `<admin-shell-ui>` — Behavior-only application shell. Wires sidebar toggles, resize handles,
+a Cmd+K command palette, and a ResizeObserver that drives responsive
+sidebar collapse. Author supplies the DOM (aside[data-sidebar], main,
+dialog[data-command]); admin-shell binds the interactions.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/admin-shell
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../../web-components/core/element.js';
+
+export interface AppShellCommandSelectEventDetail {
+  value: string;
+}
+
+export type AppShellCommandSelectEvent = CustomEvent<AppShellCommandSelectEventDetail>;
+export interface AppShellSidebarResizeEventDetail {
+  sidebar: string;
+  width: string;
+}
+
+export type AppShellSidebarResizeEvent = CustomEvent<AppShellSidebarResizeEventDetail>;
+export interface AppShellSidebarToggleEventDetail {
+  expanded: string;
+  sidebar: string;
+}
+
+export type AppShellSidebarToggleEvent = CustomEvent<AppShellSidebarToggleEventDetail>;
+
+export class UIAppShell extends UIElement {
+  /** Layout variant — default is bordered surface; rounded softens edges; borderless removes the outer chrome. */
+  mode: '' | 'rounded' | 'borderless';
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIAppShell, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'command-select', listener: (ev: AppShellCommandSelectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'sidebar-resize', listener: (ev: AppShellSidebarResizeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'sidebar-toggle', listener: (ev: AppShellSidebarToggleEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/shell/admin-sidebar/admin-sidebar.a2ui.json

@@ -54,6 +54,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [],
     "events": {
       "sidebar-resize": {
         "description": "Bubbles when an active pointer-drag releases.",

package/shell/admin-sidebar/admin-sidebar.d.ts

@@ -0,0 +1,68 @@
+/**
+ * `<admin-sidebar-ui>` — Module-tier shell sidebar — owns resize, snap-to-collapsed, persistence,
+and the [collapsed] reflected attribute. Sits inside <admin-shell> as
+slot="leading" or slot="trailing". Authors compose chrome bars + content
+inside via slot vocabulary.
+
+This is the bespoke web-component replacement for the legacy
+<aside data-sidebar> shape. <admin-shell> still recognizes the legacy
+shape via :is() selector for backwards compat. New code should prefer
+<admin-sidebar>.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/admin-sidebar
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../../web-components/core/element.js';
+
+export interface AdminSidebarSidebarResizeEventDetail {
+  name: string;
+  width: string;
+}
+
+export type AdminSidebarSidebarResizeEvent = CustomEvent<AdminSidebarSidebarResizeEventDetail>;
+export interface AdminSidebarSidebarToggleEventDetail {
+  expanded: string;
+  name: string;
+}
+
+export type AdminSidebarSidebarToggleEvent = CustomEvent<AdminSidebarSidebarToggleEventDetail>;
+
+export class UIAdminSidebar extends UIElement {
+  /** Reflected — set when the sidebar's measured width is at or below
+96px. Consumers query this to style "collapsed mode" without
+duplicating threshold math.
+ */
+  collapsed: boolean;
+  /** Opts in to programmatic collapse — toggle button wiring + the
+.toggle() / .collapse() / .expand() public methods.
+ */
+  collapsible: boolean;
+  /** Identifier for localStorage namespacing. Defaults to slot value
+("leading" or "trailing"). Override when running multiple sidebars
+with the same slot.
+ */
+  name: string;
+  /** Opts in to drag-to-resize behavior. Author supplies a child
+[data-resize] element as the drag handle.
+ */
+  resizable: boolean;
+  /** Reflected — set during an active pointer-drag on the resize handle.
+Useful for suppressing transitions while dragging.
+ */
+  resizing: boolean;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIAdminSidebar, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'sidebar-resize', listener: (ev: AdminSidebarSidebarResizeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'sidebar-toggle', listener: (ev: AdminSidebarSidebarToggleEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/shell/admin-statusbar/admin-statusbar.a2ui.json

@@ -24,6 +24,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [],
     "events": {},
     "examples": [],
     "keywords": [

package/shell/admin-topbar/admin-topbar.a2ui.json

@@ -24,6 +24,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [],
     "events": {},
     "examples": [],
     "keywords": [

package/simple/simple-content/simple-content.a2ui.json

@@ -24,6 +24,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "shells",
+    "composes": [],
     "events": {},
     "examples": [],
     "keywords": [

package/simple/simple-hero/simple-hero.a2ui.json

@@ -24,6 +24,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "shells",
+    "composes": [],
     "events": {},
     "examples": [],
     "keywords": [

package/simple/simple-shell/simple-shell.a2ui.json

@@ -34,6 +34,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "shells",
+    "composes": [],
     "events": {},
     "examples": [],
     "keywords": [

package/simple/simple-shell/simple-shell.d.ts

@@ -0,0 +1,29 @@
+/**
+ * `<simple-shell-ui>` — Module-tier minimal shell for marketing / landing / error pages.
+Behavior-only orchestrator with two reflected attributes — [centered]
+for vertical centering, [full-bleed] for dropping the max-width
+constraint.
+
+The 4th cluster in the bespoke shell family per ADR-0023, designed
+deliberately small (1 host + 2 CSS-only children) to demonstrate
+the pattern works without ceremony for thin clusters.
+
+Use cases: marketing splashes, error pages (404 / 500 / maintenance),
+thank-you pages, single-card flows (sign-in, password reset).
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/simple-shell
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../../web-components/core/element.js';
+
+export class UISimpleShell extends UIElement {
+  /** Reflected — vertically centers content in viewport. */
+  centered: boolean;
+}

package/theme/theme-panel/theme-panel.a2ui.json

@@ -89,6 +89,15 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [
+      "segmented-ui",
+      "segment-ui",
+      "text-ui",
+      "button-ui",
+      "divider-ui",
+      "field-ui",
+      "slider-ui"
+    ],
     "events": {
       "theme-change": {
         "description": "Bubbles when any user-visible state changes (theme click, slider\ninput, preset click, scheme flip, reset). One event per change.\nNo event on auto-rehydrate-from-storage at boot.\n",

package/theme/theme-panel/theme-panel.d.ts

@@ -0,0 +1,77 @@
+/**
+ * `<theme-panel-ui>` — Module-tier appearance-preferences control surface. Owns the three knobs
+of the AdiaUI theming contract: [data-theme=<slug>] named themes,
+--a-density / --a-radius-k parametric overrides, and color-scheme
+light/dark switching, plus optional localStorage persistence behind a
+small attribute API.
+
+Drops into any consumer's <popover-ui slot="content"> (the canonical
+composition) or directly into a sidebar section. Eight named themes
+ship by default; section visibility flips on/off via boolean attributes
+([parametric], [presets], [scheme-toggle]).
+
+Promoted from the duplicated <div id="theme-panel"> block in site/ and
+playgrounds/admin-shell/ — see docs/specs/theme-panel-module.md.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/theme-panel
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../../web-components/core/element.js';
+
+export interface ThemePanelThemeChangeEventDetail {
+  theme: string;
+  density: string;
+  radius: string;
+  scheme: string;
+  source: string;
+}
+
+export type ThemePanelThemeChangeEvent = CustomEvent<ThemePanelThemeChangeEventDetail>;
+
+export class UIThemePanel extends UIElement {
+  /** Renders the density + radius slider block. Sliders bind to
+--a-density and --a-radius-k on the target element.
+ */
+  parametric: boolean;
+  /** Persists selections to localStorage. Defaults to ephemeral so
+playgrounds and embedded demos do not silently mutate a user's
+docs-shell preferences.
+ */
+  persist: boolean;
+  /** Renders the compact / reset / spacious preset row. Each preset
+applies a (density, radius) pair; "default" also clears the
+[data-theme] attribute.
+ */
+  presets: boolean;
+  /** Initial color-scheme. "auto" follows prefers-color-scheme via a
+matchMedia listener; user clicks on the scheme toggle promote to
+an explicit light or dark choice.
+ */
+  scheme: 'light' | 'dark' | 'auto';
+  /** CSS selector for the element that receives [data-theme] and
+--a-density / --a-radius-k writes. Defaults to :root (the
+<html> element). Scoped targets are useful for preview-pane
+demos.
+ */
+  target: string;
+  /** Space-separated list of theme slugs to render as buttons. Author
+may restrict ([themes="default ocean"]) or extend. Tolerant —
+unknown slugs render a button; clicking applies [data-theme=slug]
+regardless of whether themes.css has a matching block.
+ */
+  themes: string;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIThemePanel, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'theme-change', listener: (ev: ThemePanelThemeChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/theme/theme-panel/theme-panel.html

@@ -23,6 +23,7 @@
   <link rel="stylesheet" href="../../../web-components/components/code/code.css">
   <link rel="stylesheet" href="../../../web-components/components/tag/tag.css">
 
+  <link rel="stylesheet" href="../segment/segment.css">
   <!-- Module CSS -->
   <link rel="stylesheet" href="./theme-panel.css">
 
@@ -38,6 +39,7 @@
   <script type="module" src="../../../web-components/components/code/code.js"></script>
   <script type="module" src="../../../web-components/components/tag/tag.js"></script>
 
+  <script type="module" src="../segment/segment.js"></script>
   <!-- Module JS -->
   <script type="module" src="./theme-panel.js"></script>
 

package/theme/theme-panel/theme-panel.yaml

@@ -20,6 +20,16 @@ description: |
   Promoted from the duplicated <div id="theme-panel"> block in site/ and
   playgrounds/admin-shell/ — see docs/specs/theme-panel-module.md.
 
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - segmented-ui
+  - segment-ui
+  - text-ui
+  - button-ui
+  - divider-ui
+  - field-ui
+  - slider-ui
 props:
   themes:
     description: |