@adia-ai/web-components 0.4.7 → 0.4.8

package/README.md

@@ -175,6 +175,45 @@ Authoring rules (enforced by `ui-audit-coherence`):
 5. **Light DOM only.** No `::part()`, `::slotted()`, shadow roots. Use
    attribute selectors on children: `:scope > [slot="icon"]`.
 
+### `static template` is a closure — import what it references
+
+The `static template` property is a regular JavaScript closure (typically a tagged template literal — `() => html` followed by the template body). Any signal, variable, or function it references must be **lexically in scope** at the file where the class is defined. This is JavaScript scoping, not anything AdiaUI-specific — but it surprises authors coming from frameworks where templates magically receive props.
+
+```js
+// ❌ WRONG — ReferenceError at runtime: minL is not defined
+//   (no import; the template function can't see minL just because
+//    it's exported elsewhere in the monorepo)
+class MyPanel extends UIElement {
+  static template = () => html`<div>L: ${minL.value}</div>`;
+}
+
+// ✅ RIGHT — import the signal locally
+import { minL } from './state.js';
+
+class MyPanel extends UIElement {
+  static template = () => html`<div>L: ${minL.value}</div>`;
+}
+```
+
+The error surfaces in the browser console as `ReferenceError: minL is not defined` at first render — not at module load, not at `tsc --noEmit`. **The trace points at the template function body**, not at the missing import, which is the disorienting part.
+
+If your primitive needs external reactive state that varies per-instance, **expose it as a property** rather than reaching for module-scoped signals:
+
+```js
+// ✅ Best — per-instance reactive prop
+class MyPanel extends UIElement {
+  static properties = {
+    minL: { type: Number, default: 0 },
+  };
+  static template = el => html`<div>L: ${el.minL}</div>`;
+}
+
+// Consumer:
+<my-panel .minL=${minL}></my-panel>  // signal binds reactively per ADR-template-binding
+```
+
+The `el` parameter is the element instance — every signal-backed property is reactively read.
+
 Full authoring contract: [`docs/specs/component-token-contract.md`](../../docs/specs/component-token-contract.md).
 The `adia-ui-author` skill encodes the 20 non-negotiable rules.
 

package/components/accordion/accordion.a2ui.json

@@ -29,6 +29,9 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "container",
+    "composes": [
+      "icon-ui"
+    ],
     "events": {
       "change": {
         "description": "Fired when the set of open panels changes"

package/components/accordion/accordion.d.ts

@@ -5,13 +5,23 @@
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
  * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
- * run `npm run components`, then `npm run codegen:dts` to regenerate;
- * or hand-author this file fully if rich event types are needed.
+ * 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 '../../core/element.js';
 
+export type AccordionChangeEvent = CustomEvent<unknown>;
+
 export class UIAccordion extends UIElement {
   /** Allow multiple panels to be open simultaneously */
   multiple: boolean;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIAccordion, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'change', listener: (ev: AccordionChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/accordion/accordion.yaml

@@ -7,6 +7,10 @@ component: Accordion
 category: container
 version: 1
 description: Accordion container managing single/multiple open states.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - icon-ui
 props:
   multiple:
     description: Allow multiple panels to be open simultaneously

package/components/action-list/action-list.a2ui.json

@@ -24,6 +24,9 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "navigation",
+    "composes": [
+      "icon-ui"
+    ],
     "events": {
       "action": {
         "description": "Fired on action."

package/components/action-list/action-list.d.ts

@@ -5,11 +5,21 @@
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
  * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
- * run `npm run components`, then `npm run codegen:dts` to regenerate;
- * or hand-author this file fully if rich event types are needed.
+ * 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 '../../core/element.js';
 
+export type ActionListActionEvent = CustomEvent<unknown>;
+
 export class UIActionList extends UIElement {
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIActionList, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'action', listener: (ev: ActionListActionEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/action-list/action-list.yaml

@@ -8,6 +8,10 @@ category: navigation
 version: 1
 description: Inline list of command actions with keyboard navigation. Fires action event when an
   item is clicked or activated via keyboard.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - icon-ui
 props: {}
 events:
   action:

package/components/agent-artifact/agent-artifact.a2ui.json

@@ -49,6 +49,10 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "agent",
+    "composes": [
+      "icon-ui",
+      "badge-ui"
+    ],
     "events": {
       "artifact-toggle": {
         "description": "Fired on artifact-toggle."

package/components/agent-artifact/agent-artifact.d.ts

@@ -5,12 +5,15 @@
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
  * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
- * run `npm run components`, then `npm run codegen:dts` to regenerate;
- * or hand-author this file fully if rich event types are needed.
+ * 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 '../../core/element.js';
 
+export type AgentArtifactArtifactToggleEvent = CustomEvent<unknown>;
+
 export class UIAgentArtifact extends UIElement {
   /** Header title. */
   title: string;
@@ -22,4 +25,11 @@ export class UIAgentArtifact extends UIElement {
   kind: string;
   /** neutral | accent | warning | danger */
   tone: string;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIAgentArtifact, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'artifact-toggle', listener: (ev: AgentArtifactArtifactToggleEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/agent-artifact/agent-artifact.yaml

@@ -7,6 +7,11 @@ component: AgentArtifact
 category: agent
 version: 1
 description: Inline container for structured agent artifacts (A2UI, JSON, tickets).
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - icon-ui
+  - badge-ui
 props:
   kind:
     description: Badge label; value is normalized to uppercase before rendering.

package/components/agent-feedback-bar/agent-feedback-bar.a2ui.json

@@ -39,6 +39,9 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "agent",
+    "composes": [
+      "button-ui"
+    ],
     "events": {
       "feedback-rate": {
         "description": "Fired on feedback-rate."

package/components/agent-feedback-bar/agent-feedback-bar.d.ts

@@ -5,12 +5,16 @@
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
  * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
- * run `npm run components`, then `npm run codegen:dts` to regenerate;
- * or hand-author this file fully if rich event types are needed.
+ * 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 '../../core/element.js';
 
+export type AgentFeedbackBarFeedbackRateEvent = CustomEvent<unknown>;
+export type AgentFeedbackBarFeedbackSaveEvent = CustomEvent<unknown>;
+
 export class UIAgentFeedbackBar extends UIElement {
   /** Disable all actions. */
   disabled: boolean;
@@ -18,4 +22,12 @@ export class UIAgentFeedbackBar extends UIElement {
   saveIcon: string;
   /** Save button text; empty hides it. */
   saveLabel: string;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIAgentFeedbackBar, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'feedback-rate', listener: (ev: AgentFeedbackBarFeedbackRateEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'feedback-save', listener: (ev: AgentFeedbackBarFeedbackSaveEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/agent-feedback-bar/agent-feedback-bar.yaml

@@ -7,6 +7,10 @@ component: AgentFeedbackBar
 category: agent
 version: 1
 description: Thumbs + save row under an agent response.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - button-ui
 props:
   disabled:
     description: Disable all actions.

package/components/agent-questions/agent-questions.a2ui.json

@@ -44,6 +44,9 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "agent",
+    "composes": [
+      "button-ui"
+    ],
     "events": {
       "questions-answer": {
         "description": "Fired on questions-answer."

package/components/agent-questions/agent-questions.d.ts

@@ -5,12 +5,15 @@
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
  * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
- * run `npm run components`, then `npm run codegen:dts` to regenerate;
- * or hand-author this file fully if rich event types are needed.
+ * 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 '../../core/element.js';
 
+export type AgentQuestionsQuestionsAnswerEvent = CustomEvent<unknown>;
+
 export class UIAgentQuestions extends UIElement {
   /** Helper text. */
   helper: string;
@@ -20,4 +23,11 @@ export class UIAgentQuestions extends UIElement {
   question: string;
   /** Submit button label (multi mode). */
   submitLabel: string;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIAgentQuestions, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'questions-answer', listener: (ev: AgentQuestionsQuestionsAnswerEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/agent-questions/agent-questions.yaml

@@ -7,6 +7,10 @@ component: AgentQuestions
 category: agent
 version: 1
 description: Multi-choice clarifying-question cards.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - button-ui
 props:
   helper:
     description: Helper text.

package/components/agent-reasoning/agent-reasoning.a2ui.json

@@ -50,6 +50,10 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "agent",
+    "composes": [
+      "timeline-ui",
+      "timeline-item-ui"
+    ],
     "events": {
       "reasoning-finish": {
         "description": "Fired on reasoning-finish."

package/components/agent-reasoning/agent-reasoning.d.ts

@@ -5,12 +5,17 @@
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
  * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
- * run `npm run components`, then `npm run codegen:dts` to regenerate;
- * or hand-author this file fully if rich event types are needed.
+ * 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 '../../core/element.js';
 
+export type AgentReasoningReasoningFinishEvent = CustomEvent<unknown>;
+export type AgentReasoningReasoningStepToggleEvent = CustomEvent<unknown>;
+export type AgentReasoningReasoningToggleEvent = CustomEvent<unknown>;
+
 export class UIAgentReasoning extends UIElement {
   /** Start collapsed. */
   collapsed: boolean;
@@ -20,4 +25,13 @@ export class UIAgentReasoning extends UIElement {
   noAutocollapse: boolean;
   /** Drives the status icon — idle, active (spinner), done (check), error (warning). */
   status: 'idle' | 'active' | 'done' | 'error';
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIAgentReasoning, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'reasoning-finish', listener: (ev: AgentReasoningReasoningFinishEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'reasoning-step-toggle', listener: (ev: AgentReasoningReasoningStepToggleEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'reasoning-toggle', listener: (ev: AgentReasoningReasoningToggleEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/agent-reasoning/agent-reasoning.yaml

@@ -7,6 +7,11 @@ component: AgentReasoning
 category: agent
 version: 1
 description: Agent inner monologue + pipeline viewer with steps, thoughts, plans, and iterations.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - timeline-ui
+  - timeline-item-ui
 props:
   noAutocollapse:
     description: Disable auto-collapse after finish().

package/components/agent-suggestions/agent-suggestions.a2ui.json

@@ -39,6 +39,9 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "agent",
+    "composes": [
+      "button-ui"
+    ],
     "events": {
       "suggestion-select": {
         "description": "Fired on suggestion-select."

package/components/agent-suggestions/agent-suggestions.d.ts

@@ -5,12 +5,15 @@
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
  * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
- * run `npm run components`, then `npm run codegen:dts` to regenerate;
- * or hand-author this file fully if rich event types are needed.
+ * 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 '../../core/element.js';
 
+export type AgentSuggestionsSuggestionSelectEvent = CustomEvent<unknown>;
+
 export class UIAgentSuggestions extends UIElement {
   /** Disable all chips. */
   disabled: boolean;
@@ -18,4 +21,11 @@ export class UIAgentSuggestions extends UIElement {
   size: string;
   /** outline | ghost | subtle */
   variant: string;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIAgentSuggestions, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'suggestion-select', listener: (ev: AgentSuggestionsSuggestionSelectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/agent-suggestions/agent-suggestions.yaml

@@ -7,6 +7,10 @@ component: AgentSuggestions
 category: agent
 version: 1
 description: Row of follow-up suggestion chips.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - button-ui
 props:
   disabled:
     description: Disable all chips.

package/components/agent-trace/agent-trace.a2ui.json

@@ -34,6 +34,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "agent",
+    "composes": [],
     "events": {
       "trace-toggle": {
         "description": "Fired on trace-toggle."

package/components/agent-trace/agent-trace.d.ts

@@ -5,15 +5,25 @@
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
  * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
- * run `npm run components`, then `npm run codegen:dts` to regenerate;
- * or hand-author this file fully if rich event types are needed.
+ * 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 '../../core/element.js';
 
+export type AgentTraceTraceToggleEvent = CustomEvent<unknown>;
+
 export class UIAgentTrace extends UIElement {
   /** Hide the trace body. Default-visible disclosure (matches the agent-* family — agent-reasoning, agent-artifact). Set to opt out. */
   collapsed: boolean;
   /** Fallback summary label. */
   label: string;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIAgentTrace, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'trace-toggle', listener: (ev: AgentTraceTraceToggleEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/alert/alert.a2ui.json

@@ -68,6 +68,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "container",
+    "composes": [],
     "events": {
       "close": {
         "description": "Fired when the close button is clicked"

package/components/alert/alert.d.ts

@@ -5,12 +5,15 @@
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
  * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
- * run `npm run components`, then `npm run codegen:dts` to regenerate;
- * or hand-author this file fully if rich event types are needed.
+ * 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 '../../core/element.js';
 
+export type AlertCloseEvent = CustomEvent<unknown>;
+
 export class UIAlert extends UIElement {
   /** Bold headline rendered as the first line of the alert content. Pair with [description] for the canonical "banner" pattern (headline + body). When [title] or [description] is set, the [text] prop is ignored. */
   title: string;
@@ -26,4 +29,11 @@ export class UIAlert extends UIElement {
   text: string;
   /** Semantic color variant. */
   variant: 'default' | 'info' | 'success' | 'warning' | 'danger' | 'muted' | 'neutral';
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIAlert, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'close', listener: (ev: AlertCloseEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/aside/aside.a2ui.json

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

package/components/avatar/avatar.a2ui.json

@@ -69,6 +69,9 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "display",
+    "composes": [
+      "icon-ui"
+    ],
     "events": {},
     "examples": [
       {

package/components/avatar/avatar.d.ts

@@ -5,8 +5,9 @@
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
  * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
- * run `npm run components`, then `npm run codegen:dts` to regenerate;
- * or hand-author this file fully if rich event types are needed.
+ * 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 '../../core/element.js';

package/components/avatar/avatar.yaml

@@ -7,6 +7,10 @@ component: Avatar
 category: display
 version: 1
 description: Avatar with image → initials → empty fallback chain.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - icon-ui
 props:
   text:
     description: Display string (full name or initials). Initials derive from spaces — first letter of each word, max 2.

package/components/badge/badge.a2ui.json

@@ -78,6 +78,9 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "display",
+    "composes": [
+      "icon-ui"
+    ],
     "events": {},
     "examples": [
       {

package/components/badge/badge.d.ts

@@ -5,8 +5,9 @@
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
  * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
- * run `npm run components`, then `npm run codegen:dts` to regenerate;
- * or hand-author this file fully if rich event types are needed.
+ * 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 '../../core/element.js';

package/components/badge/badge.yaml

@@ -7,6 +7,10 @@ component: Badge
 category: display
 version: 1
 description: Inline pill-shaped badge/tag. Text rendered via CSS attr().
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - icon-ui
 props:
   icon:
     description: Optional leading icon (any registered name). Use icon="dot" for chart-legend /

package/components/block/block.a2ui.json

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

package/components/block/block.d.ts

@@ -5,8 +5,9 @@
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
  * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
- * run `npm run components`, then `npm run codegen:dts` to regenerate;
- * or hand-author this file fully if rich event types are needed.
+ * 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 '../../core/element.js';

package/components/breadcrumb/breadcrumb.a2ui.json

@@ -44,6 +44,11 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "navigation",
+    "composes": [
+      "menu-ui",
+      "button-ui",
+      "menu-item-ui"
+    ],
     "events": {},
     "examples": [
       {

package/components/breadcrumb/breadcrumb.d.ts

@@ -5,8 +5,9 @@
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
  * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
- * run `npm run components`, then `npm run codegen:dts` to regenerate;
- * or hand-author this file fully if rich event types are needed.
+ * 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 '../../core/element.js';

package/components/breadcrumb/breadcrumb.yaml

@@ -7,6 +7,12 @@ component: Breadcrumb
 category: navigation
 version: 1
 description: Breadcrumb trail with auto-inserted separators. Supports a leading icon (first child) and an overflow popover that collapses middle crumbs into a `…` menu.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - menu-ui
+  - button-ui
+  - menu-item-ui
 props:
   separator:
     description: Character or string rendered between breadcrumb items via CSS ::before.