@adia-ai/web-components 0.5.2 → 0.5.3

package/USAGE.md

@@ -134,6 +134,33 @@ const tpl3 = html`<slider-ui .value=${minL.value * 100} min="0" max="100"></slid
 
 The `.prop=` syntax sets the JS property (not the attribute). The `attr=` syntax sets an attribute. Both round-trip through the signal-backed setter, so either works for reactive updates from your side.
 
+### Template attribute bindings — full / property / no-partial (§152, v0.5.3)
+
+The `html\`` template literal supports three attribute-binding modes:
+
+| Syntax | Behavior |
+|---|---|
+| `attr="${value}"` (or just `attr=${value}`) | **Full attribute replacement.** The entire attribute value is the placeholder. The string `value` becomes the attribute value via `setAttribute()`. Works for any string-typed attribute. |
+| `.prop=${value}` (leading dot) | **Property assignment.** Sets `element.prop = value` directly (bypasses attributes). Preferred for objects, functions, arrays, signals — anything that doesn't serialize to a string. |
+| `attr="prefix-${value}-suffix"` | **NOT SUPPORTED.** Partial interpolation is not implemented — the attribute-part contract is whole-value-only. The framework will `console.warn` at scan time. Compute the full attribute value as a single expression and interpolate the whole. |
+
+Example of the partial-interpolation pitfall and its fix:
+
+```js
+// ❌ NOT SUPPORTED — partial attribute interpolation
+// Will console.warn at scan time + the `{{p:0}}` placeholder text reaches the DOM as literal.
+html`<div style="background:${bgCss}; color:${labelColor}">…</div>`;
+
+// ✅ Compute the full attribute as one expression
+const swatchStyle = `background:${bgCss}; color:${labelColor};`;
+html`<div style="${swatchStyle}">…</div>`;
+
+// ✅ Or use property binding with an object (CSSStyleDeclaration-like)
+html`<div .style=${{ background: bgCss, color: labelColor }}>…</div>`;
+```
+
+**Why the constraint exists**: the engine pre-processes static-string chunks to insert placeholder markers (`{{p:N}}` for attribute positions, `<!--p:N-->` for content positions). At scan time, the post-substitution attribute value must match `^\{\{p:N\}\}$` for the placeholder-to-part mapping to register. Sub-string placeholders break this contract. The runtime guard (added v0.5.3 §152) makes the failure mode explicit instead of silent.
+
 ### Using React, Lit, Vue, Svelte, etc.
 
 When the binding system isn't AdiaUI's `html` tag, the rule generalizes:
@@ -186,6 +213,21 @@ html`<slider-ui .value=${(v) => v * 100} />`
 
 The rule: **inside `.prop=${…}`, anything that reads `.value` directly is a snapshot. Wrap in `() => …` to get reactivity.**
 
+**Dev-mode guard (v0.5.3 §153 / FEEDBACK-07 §3):** primitives that read their value synchronously (e.g. `<slider-ui>`) emit a `console.warn` when their `.value` is assigned a function — this catches the case where the function wasn't wrapped by the template engine (e.g. assigned imperatively `sliderEl.value = fn`, or returned by a framework binding that doesn't recognize the AdiaUI reactivity contract). The warn names the two correct patterns:
+
+```
+[slider-ui] .value received a function. Did you mean:
+  .value=${fn()}            ← call the function to get the current value
+  .value=${signal.value}     ← read the signal's current value
+Functions are not auto-invoked at render time; the slider reads
+.value synchronously. See USAGE.md "Reactive binding" for the
+parent-template-re-read pattern that works across frameworks.
+```
+
+If you see this warn in dev console, either:
+1. You're using AdiaUI's `html\``: ensure the function reads at least one signal value (otherwise the function isn't reactive, just expensive). Pattern A above with `() => signal.value * 100` is correct.
+2. You're using a different framework (React/Lit/Vue): the binding system isn't AdiaUI's `html` engine, so functions don't auto-wrap. Use Pattern B from the parent-template-re-read recipe — read the signal in the parent's render, pass the extracted value imperatively or via your framework's binding.
+
 For more complex derived values, `computed()` gives you a named reactive holder you can pass directly or read in templates:
 
 ```js

package/components/accordion/accordion.a2ui.json

@@ -33,8 +33,14 @@
       "icon-ui"
     ],
     "events": {
-      "change": {
-        "description": "Fired when the set of open panels changes"
+      "toggle": {
+        "description": "Fired when the accordion panel opens or closes (single-pane accordion-ui dispatch — multi-pane group emits the same event per child).",
+        "detail": {
+          "open": {
+            "description": "New open state of the panel.",
+            "type": "boolean"
+          }
+        }
       }
     },
     "examples": [

package/components/accordion/accordion.d.ts

@@ -12,7 +12,12 @@
 
 import { UIElement } from '../../core/element.js';
 
-export type AccordionChangeEvent = CustomEvent<unknown>;
+export interface AccordionToggleEventDetail {
+  /** New open state of the panel. */
+  open: boolean;
+}
+
+export type AccordionToggleEvent = CustomEvent<AccordionToggleEventDetail>;
 
 export class UIAccordion extends UIElement {
   /** Allow multiple panels to be open simultaneously */
@@ -23,5 +28,5 @@ export class UIAccordion extends UIElement {
     listener: (this: UIAccordion, ev: HTMLElementEventMap[K]) => unknown,
     options?: boolean | AddEventListenerOptions,
   ): void;
-  addEventListener(type: 'change', listener: (ev: AccordionChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'toggle', listener: (ev: AccordionToggleEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/accordion/accordion.yaml

@@ -17,8 +17,12 @@ props:
     type: boolean
     default: false
 events:
-  change:
-    description: Fired when the set of open panels changes
+  toggle:
+    description: Fired when the accordion panel opens or closes (single-pane accordion-ui dispatch — multi-pane group emits the same event per child).
+    detail:
+      open:
+        type: boolean
+        description: New open state of the panel.
 slots:
   default:
     description: pane-ui children
@@ -27,6 +31,8 @@ states:
     description: Default, ready for interaction.
 traits: []
 tokens: {}
+requiredIcons:
+  - caret-down
 a2ui:
   rules: []
 anti_patterns: []

package/components/accordion/class.js

@@ -30,6 +30,12 @@ import { UIElement } from '../../core/element.js';
 // ── Accordion Container ────────────────────────────────────────
 
 export class UIAccordion extends UIElement {
+  // §154 (v0.5.3): Phosphor icons this primitive auto-stamps (without
+  // consumer markup). Aggregated by installIconLoadersForRegistered()
+  // across all defined elements. Audited by check-required-icons.mjs
+  // (slot 11). Per FEEDBACK-06 §4 + FEEDBACK-07 §4.
+  static requiredIcons = ['caret-down'];
+
   static properties = {
     multiple: { type: Boolean, default: false, reflect: true },
   };

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

@@ -47,6 +47,8 @@ states:
     description: Default, ready for interaction.
 traits: []
 tokens: {}
+requiredIcons:
+  - check
 a2ui:
   rules: []
 anti_patterns: []

package/components/agent-questions/class.js

@@ -50,6 +50,12 @@ function escapeAttr(s) {
 }
 
 export class UIAgentQuestions extends UIElement {
+  // §154 (v0.5.3): Phosphor icons this primitive auto-stamps (without
+  // consumer markup). Aggregated by installIconLoadersForRegistered()
+  // across all defined elements. Audited by check-required-icons.mjs
+  // (slot 11). Per FEEDBACK-06 §4 + FEEDBACK-07 §4.
+  static requiredIcons = ['check'];
+
   static properties = {
     multi:       { type: Boolean, default: false, reflect: true },
     question:    { type: String,  default: '',    reflect: true },

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

@@ -62,6 +62,11 @@ states:
     description: Default, ready for interaction.
 traits: []
 tokens: {}
+requiredIcons:
+  - check-circle
+  - circle
+  - warning
+  - warning-circle
 a2ui:
   rules: []
 anti_patterns: []

package/components/agent-reasoning/class.js

@@ -77,6 +77,12 @@ function formatDuration(ms) {
 }
 
 export class UIAgentReasoning extends UIElement {
+  // §154 (v0.5.3): Phosphor icons this primitive auto-stamps (without
+  // consumer markup). Aggregated by installIconLoadersForRegistered()
+  // across all defined elements. Audited by check-required-icons.mjs
+  // (slot 11). Per FEEDBACK-06 §4 + FEEDBACK-07 §4.
+  static requiredIcons = ['check-circle', 'circle', 'warning', 'warning-circle'];
+
   static properties = {
     collapsed:       { type: Boolean, default: false,    reflect: true },
     noAutocollapse:  { type: Boolean, default: false,    reflect: true, attribute: 'no-autocollapse' },

package/components/agent-trace/agent-trace.js

@@ -37,6 +37,12 @@
 import { UIElement } from '../../core/element.js';
 
 class UIAgentTrace extends UIElement {
+  // §154 (v0.5.3): Phosphor icons this primitive auto-stamps (without
+  // consumer markup). Aggregated by installIconLoadersForRegistered()
+  // across all defined elements. Audited by check-required-icons.mjs
+  // (slot 11). Per FEEDBACK-06 §4 + FEEDBACK-07 §4.
+  static requiredIcons = ['caret-right', 'circle-fill'];
+
   static properties = {
     // agent-* family is default-visible disclosure (see component-token-contract.md
     // §"Toggle state naming"). Use `collapsed` to hide; bare element shows.

package/components/agent-trace/agent-trace.yaml

@@ -32,6 +32,9 @@ states:
     description: Default, ready for interaction.
 traits: []
 tokens: {}
+requiredIcons:
+  - caret-right
+  - circle-fill
 a2ui:
   rules: []
 anti_patterns: []

package/components/calendar-picker/calendar-picker.yaml

@@ -71,6 +71,10 @@ states:
   attribute: disabled
 traits: []
 tokens: {}
+requiredIcons:
+  - calendar
+  - caret-left
+  - caret-right
 a2ui:
   rules: []
 anti_patterns: []

package/components/calendar-picker/class.js

@@ -53,6 +53,12 @@ function sameDay(a, b) {
 }
 
 export class UICalendarPicker extends UIFormElement {
+  // §154 (v0.5.3): Phosphor icons this primitive auto-stamps (without
+  // consumer markup). Aggregated by installIconLoadersForRegistered()
+  // across all defined elements. Audited by check-required-icons.mjs
+  // (slot 11). Per FEEDBACK-06 §4 + FEEDBACK-07 §4.
+  static requiredIcons = ['calendar', 'caret-left', 'caret-right'];
+
   static properties = {
     ...UIFormElement.properties,
     label:       { type: String,  default: '', reflect: true },

package/components/canvas/canvas.a2ui.json

@@ -32,16 +32,7 @@
     "composes": [],
     "events": {
       "canvas-interaction": {
-        "description": "Fired on canvas-interaction."
-      },
-      "change": {
-        "description": "Fired when the value changes (on blur for inputs, on selection for pickers)."
-      },
-      "click": {
-        "description": "Fired on pointer click."
-      },
-      "input": {
-        "description": "Fired on each input change during typing."
+        "description": "Fired on canvas interactions (focus, blur, pointer events). Dispatched at canvas.js:50 + :167."
       }
     },
     "examples": [

package/components/canvas/canvas.d.ts

@@ -13,9 +13,6 @@
 import { UIElement } from '../../core/element.js';
 
 export type CanvasInteractionEvent = CustomEvent<unknown>;
-export type CanvasChangeEvent = CustomEvent<unknown>;
-export type CanvasClickEvent = CustomEvent<unknown>;
-export type CanvasInputEvent = CustomEvent<unknown>;
 
 export class UICanvas extends UIElement {
   /** Component property: theme. */
@@ -27,7 +24,4 @@ export class UICanvas extends UIElement {
     options?: boolean | AddEventListenerOptions,
   ): void;
   addEventListener(type: 'canvas-interaction', listener: (ev: CanvasInteractionEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
-  addEventListener(type: 'change', listener: (ev: CanvasChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
-  addEventListener(type: 'click', listener: (ev: CanvasClickEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
-  addEventListener(type: 'input', listener: (ev: CanvasInputEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/canvas/canvas.yaml

@@ -24,13 +24,7 @@ props:
     default: ''
 events:
   canvas-interaction:
-    description: Fired on canvas-interaction.
-  change:
-    description: Fired when the value changes (on blur for inputs, on selection for pickers).
-  click:
-    description: Fired on pointer click.
-  input:
-    description: Fired on each input change during typing.
+    description: Fired on canvas interactions (focus, blur, pointer events). Dispatched at canvas.js:50 + :167.
 slots:
   default:
     description: Default slot — primary child content.

package/components/card/card.a2ui.json

@@ -76,11 +76,7 @@
     "anti_patterns": [],
     "category": "container",
     "composes": [],
-    "events": {
-      "drag-end": {
-        "description": "Fired when a drag completes."
-      }
-    },
+    "events": {},
     "examples": [
       {
         "description": "Chat interface with message bubbles containing avatar and text pairs, plus an input footer.",

package/components/card/card.d.ts

@@ -12,8 +12,6 @@
 
 import { UIElement } from '../../core/element.js';
 
-export type CardDragEndEvent = CustomEvent<unknown>;
-
 export class UICard extends UIElement {
   /** Enables drag handle + cursor:grab. Wires the draggable trait; dispatches drag-end. */
   draggable: boolean;
@@ -27,11 +25,4 @@ export class UICard extends UIElement {
   size: 'sm' | 'md' | 'lg';
   /** Visual style. `outline` is an alias for `outlined`; `flat` removes shadow; `soft`/`primary` apply tinted surfaces. */
   variant: 'default' | 'outlined' | 'outline' | 'filled' | 'ghost' | 'flat' | 'soft' | 'primary';
-
-  addEventListener<K extends keyof HTMLElementEventMap>(
-    type: K,
-    listener: (this: UICard, ev: HTMLElementEventMap[K]) => unknown,
-    options?: boolean | AddEventListenerOptions,
-  ): void;
-  addEventListener(type: 'drag-end', listener: (ev: CardDragEndEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/card/card.yaml

@@ -56,9 +56,7 @@ props:
     - flat
     - soft
     - primary
-events:
-  drag-end:
-    description: Fired when a drag completes.
+events: {}
 slots: {}
 states:
 - name: idle

package/components/color-picker/class.js

@@ -123,6 +123,12 @@ function gamutMapChroma(L, C, H) {
 // ── Component ────────────────────────────────────────────
 
 export class UIColorPicker extends UIFormElement {
+  // §154 (v0.5.3): Phosphor icons this primitive auto-stamps (without
+  // consumer markup). Aggregated by installIconLoadersForRegistered()
+  // across all defined elements. Audited by check-required-icons.mjs
+  // (slot 11). Per FEEDBACK-06 §4 + FEEDBACK-07 §4.
+  static requiredIcons = ['copy'];
+
   static properties = {
     ...UIFormElement.properties,
     value:    { type: String,  default: '#3b82f6', reflect: true },

package/components/color-picker/color-picker.yaml

@@ -95,6 +95,8 @@ states:
     attribute: disabled
 traits: []
 tokens: {}
+requiredIcons:
+  - copy
 a2ui:
   rules: []
 anti_patterns: []

package/components/command/class.js

@@ -34,6 +34,12 @@ import { UIElement } from '../../core/element.js';
  *   dismiss — Escape pressed
  */
 export class UICommand extends UIElement {
+  // §154 (v0.5.3): Phosphor icons this primitive auto-stamps (without
+  // consumer markup). Aggregated by installIconLoadersForRegistered()
+  // across all defined elements. Audited by check-required-icons.mjs
+  // (slot 11). Per FEEDBACK-06 §4 + FEEDBACK-07 §4.
+  static requiredIcons = ['magnifying-glass'];
+
   static properties = {
     placeholder: { type: String, default: 'Type a command...', reflect: true },
     open:        { type: Boolean, default: false, reflect: true },

package/components/command/command.yaml

@@ -41,6 +41,8 @@ states:
   description: Default, ready for interaction.
 traits: []
 tokens: {}
+requiredIcons:
+  - magnifying-glass
 a2ui:
   rules: []
 anti_patterns: []

package/components/drawer/class.js

@@ -50,6 +50,13 @@ export class UIDrawer extends UIElement {
   #previousFocus = null;
   #closeTimer = null;
   #dialogRef = null;
+  // §156 (v0.5.3): track the reason the drawer closed so the dispatched
+  // `close` CustomEvent carries `detail.reason`. Set at each entry point
+  // (escape → 'escape', backdrop → 'backdrop', close-button → 'close-button',
+  // any other path defaults to 'programmatic'). Reset to 'programmatic'
+  // after dispatch so a subsequent .open=false from consumer code
+  // doesn't carry a stale reason. Per FEEDBACK-06 §2.
+  #closeReason = 'programmatic';
 
   static properties = {
     text:      { type: String,  default: '', reflect: true },
@@ -95,11 +102,15 @@ export class UIDrawer extends UIElement {
   }
 
   #onPress = (e) => {
-    if (e.target.closest('[slot="close"]')) this.open = false;
+    if (e.target.closest('[slot="close"]')) {
+      this.#closeReason = 'close-button';
+      this.open = false;
+    }
   };
 
   #onDialogCancel = (e) => {
     e.preventDefault();
+    this.#closeReason = 'escape';
     if (!this.permanent) this.open = false;
   };
 
@@ -107,11 +118,22 @@ export class UIDrawer extends UIElement {
     this.open = false;
     this.#previousFocus?.focus();
     this.#previousFocus = null;
-    this.dispatchEvent(new Event('close', { bubbles: true }));
+    // §156 (v0.5.3): emit a CustomEvent with typed detail.reason. Capture
+    // and reset #closeReason so a subsequent programmatic close doesn't
+    // inherit the prior reason. Per FEEDBACK-06 §2.
+    const reason = this.#closeReason;
+    this.#closeReason = 'programmatic';
+    this.dispatchEvent(new CustomEvent('close', {
+      detail: { reason },
+      bubbles: true,
+    }));
   };
 
   #onDialogClick = (e) => {
-    if (e.target === this.#dialogRef && !this.permanent) this.open = false;
+    if (e.target === this.#dialogRef && !this.permanent) {
+      this.#closeReason = 'backdrop';
+      this.open = false;
+    }
   };
 
   connected() {

package/components/drawer/drawer.a2ui.json

@@ -63,7 +63,19 @@
     "composes": [],
     "events": {
       "close": {
-        "description": "Fired when the drawer is dismissed via close button or backdrop click"
+        "description": "Fired when the drawer closes via any path (close button, backdrop, Escape key, or programmatic `.open = false`). The `detail.reason` field distinguishes which.",
+        "detail": {
+          "reason": {
+            "description": "`'escape'` (Escape key) / `'backdrop'` (backdrop click) / `'close-button'` ([slot=\"close\"] button click) / `'programmatic'` (consumer set `.open = false` from JS). Defaults to `'programmatic'` when no event-driven path captured a reason. Added v0.5.3 §156 per FEEDBACK-06 §2.",
+            "type": "string",
+            "enum": [
+              "escape",
+              "backdrop",
+              "close-button",
+              "programmatic"
+            ]
+          }
+        }
       }
     },
     "examples": [

package/components/drawer/drawer.d.ts

@@ -12,7 +12,12 @@
 
 import { UIElement } from '../../core/element.js';
 
-export type DrawerCloseEvent = CustomEvent<unknown>;
+export interface DrawerCloseEventDetail {
+  /** `'escape'` (Escape key) / `'backdrop'` (backdrop click) / `'close-button'` ([slot="close"] button click) / `'programmatic'` (consumer set `.open = false` from JS). Defaults to `'programmatic'` when no event-driven path captured a reason. Added v0.5.3 §156 per FEEDBACK-06 §2. */
+  reason: 'escape' | 'backdrop' | 'close-button' | 'programmatic';
+}
+
+export type DrawerCloseEvent = CustomEvent<DrawerCloseEventDetail>;
 
 export class UIDrawer extends UIElement {
   /** Controls visibility. When false, backdrop and panel are removed from DOM. */

package/components/drawer/drawer.yaml

@@ -49,7 +49,17 @@ props:
     default: ""
 events:
   close:
-    description: Fired when the drawer is dismissed via close button or backdrop click
+    description: Fired when the drawer closes via any path (close button, backdrop, Escape key, or programmatic `.open = false`). The `detail.reason` field distinguishes which.
+    detail:
+      reason:
+        type: string
+        enum: [escape, backdrop, close-button, programmatic]
+        description: >-
+          `'escape'` (Escape key) / `'backdrop'` (backdrop click) /
+          `'close-button'` ([slot="close"] button click) /
+          `'programmatic'` (consumer set `.open = false` from JS).
+          Defaults to `'programmatic'` when no event-driven path
+          captured a reason. Added v0.5.3 §156 per FEEDBACK-06 §2.
 slots:
   backdrop:
     description: Scrim overlay behind the drawer (stamped by the component).

package/components/pane/class.js

@@ -47,6 +47,12 @@
 import { UIElement } from '../../core/element.js';
 
 export class UIPane extends UIElement {
+  // §154 (v0.5.3): Phosphor icons this primitive auto-stamps (without
+  // consumer markup). Aggregated by installIconLoadersForRegistered()
+  // across all defined elements. Audited by check-required-icons.mjs
+  // (slot 11). Per FEEDBACK-06 §4 + FEEDBACK-07 §4.
+  static requiredIcons = ['caret-right'];
+
   static properties = {
     collapsed:  { type: Boolean, default: false, reflect: true },
     resizable:  { type: Boolean, default: false, reflect: true },

package/components/pane/pane.yaml

@@ -60,6 +60,8 @@ states:
   description: Default, ready for interaction.
 traits: []
 tokens: {}
+requiredIcons:
+  - caret-right
 a2ui:
   rules: []
 anti_patterns: []

package/components/row/row.a2ui.json

@@ -55,11 +55,7 @@
     "anti_patterns": [],
     "category": "layout",
     "composes": [],
-    "events": {
-      "drag-end": {
-        "description": "Fired when a drag completes."
-      }
-    },
+    "events": {},
     "examples": [
       {
         "description": "Chat interface with message bubbles containing avatar and text pairs, plus an input footer.",

package/components/row/row.d.ts

@@ -12,8 +12,6 @@
 
 import { UIElement } from '../../core/element.js';
 
-export type RowDragEndEvent = CustomEvent<unknown>;
-
 export class UIRow extends UIElement {
   /** Align items */
   align: string;
@@ -27,11 +25,4 @@ export class UIRow extends UIElement {
   justify: string;
   /** Enable flex wrap */
   wrap: boolean;
-
-  addEventListener<K extends keyof HTMLElementEventMap>(
-    type: K,
-    listener: (this: UIRow, ev: HTMLElementEventMap[K]) => unknown,
-    options?: boolean | AddEventListenerOptions,
-  ): void;
-  addEventListener(type: 'drag-end', listener: (ev: RowDragEndEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/row/row.yaml

@@ -36,9 +36,7 @@ props:
     description: Enable flex wrap
     type: boolean
     default: false
-events:
-  drag-end:
-    description: "Fired when a drag completes."
+events: {}
 slots:
   default:
     description: "Default slot — primary child content."

package/components/select/class.js

@@ -19,6 +19,12 @@ function escapeHTML(s) {
 }
 
 export class UISelect extends UIFormElement {
+  // §154 (v0.5.3): Phosphor icons this primitive auto-stamps (without
+  // consumer markup). Aggregated by installIconLoadersForRegistered()
+  // across all defined elements. Audited by check-required-icons.mjs
+  // (slot 11). Per FEEDBACK-06 §4 + FEEDBACK-07 §4.
+  static requiredIcons = ['caret-up-down'];
+
   static properties = {
     ...UIFormElement.properties,
     placeholder: { type: String,  default: 'Select...', reflect: true },

package/components/select/select.yaml

@@ -127,6 +127,8 @@ states:
     attribute: disabled
 traits: []
 tokens: {}
+requiredIcons:
+  - caret-up-down
 a2ui:
   rules: []
 anti_patterns: []

package/components/slider/class.js

@@ -95,6 +95,31 @@ export class UISlider extends UIFormElement {
   render() {
     if (!this.#trackEl) return;
 
+    // §153 (v0.5.3): function-typed `.value` runtime guard. Per FEEDBACK-07
+    // §3, consumers sometimes pass `() => signal.value * 100` expecting
+    // auto-subscribe; AdiaUI's reactive system (template.js `isFn` branch)
+    // does wrap functions in effects + call them per dep change, but the
+    // result of `v()` must be a number for `#pct` / `#format` to work.
+    // When the function returns non-number (e.g. doesn't read a signal,
+    // returns object/string) OR when consumers bypass the template engine
+    // (manual `sliderEl.value = someFunction`), `this.value` ends up as
+    // the function itself — `#pct` does NaN math, thumb stays at 0%,
+    // silent fail. Warn loudly + skip render so the bug class is
+    // diagnosable in dev. See USAGE.md "Reactive binding" for the
+    // documented patterns.
+    if (typeof this.value === 'function') {
+      // eslint-disable-next-line no-console
+      console.warn(
+        '[slider-ui] .value received a function. Did you mean:\n' +
+        '  .value=${fn()}            ← call the function to get the current value\n' +
+        '  .value=${signal.value}     ← read the signal\'s current value\n' +
+        'Functions are not auto-invoked at render time; the slider reads\n' +
+        '.value synchronously. See USAGE.md "Reactive binding" for the\n' +
+        'parent-template-re-read pattern that works across frameworks.'
+      );
+      return;
+    }
+
     const pct = this.#pct;
     const fill = this.querySelector('[slot="fill"]');
     if (fill) fill.style.width = `${pct}%`;

package/components/table/class.js

@@ -91,6 +91,12 @@ function csvEscape(val) {
 // ── Component ────────────────────────────────────────────────────────────────
 
 export class UITable extends UIElement {
+  // §154 (v0.5.3): Phosphor icons this primitive auto-stamps (without
+  // consumer markup). Aggregated by installIconLoadersForRegistered()
+  // across all defined elements. Audited by check-required-icons.mjs
+  // (slot 11). Per FEEDBACK-06 §4 + FEEDBACK-07 §4.
+  static requiredIcons = ['caret-right', 'caret-up-down', 'table'];
+
   static properties = {
     sortable:   { type: Boolean, default: false, reflect: true },
     selectable: { type: Boolean, default: false, reflect: true },

package/components/table/table.a2ui.json

@@ -143,6 +143,19 @@
           }
         }
       },
+      "row-collapse": {
+        "description": "Fired when an already-expanded row's chevron is activated (collapses the row). Mirror of row-expand.",
+        "detail": {
+          "index": {
+            "description": "Row index in the underlying data array.",
+            "type": "number"
+          },
+          "row": {
+            "description": "Row data object.",
+            "type": "object"
+          }
+        }
+      },
       "row-expand": {
         "description": "Fired when an expandable row's chevron is activated. detail.index is the row position; detail.row is the row data.",
         "detail": {

package/components/table/table.d.ts

@@ -44,6 +44,14 @@ export interface TableResizeEventDetail {
 }
 
 export type TableResizeEvent = CustomEvent<TableResizeEventDetail>;
+export interface TableRowCollapseEventDetail {
+  /** Row index in the underlying data array. */
+  index: number;
+  /** Row data object. */
+  row: Record<string, unknown>;
+}
+
+export type TableRowCollapseEvent = CustomEvent<TableRowCollapseEventDetail>;
 export interface TableRowExpandEventDetail {
   /** Row index in the underlying data array. */
   index: number;
@@ -102,6 +110,7 @@ export class UITable extends UIElement {
   addEventListener(type: 'filter-change', listener: (ev: TableFilterChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'page', listener: (ev: TablePageEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'resize', listener: (ev: TableResizeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'row-collapse', listener: (ev: TableRowCollapseEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'row-expand', listener: (ev: TableRowExpandEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'select', listener: (ev: TableSelectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'sort', listener: (ev: TableSortEvent) => unknown, options?: boolean | AddEventListenerOptions): void;

package/components/table/table.yaml

@@ -108,6 +108,15 @@ events:
       width:
         type: number
         description: New column width in pixels.
+  row-collapse:
+    description: Fired when an already-expanded row's chevron is activated (collapses the row). Mirror of row-expand.
+    detail:
+      index:
+        type: number
+        description: Row index in the underlying data array.
+      row:
+        type: object
+        description: Row data object.
   row-expand:
     description: Fired when an expandable row's chevron is activated. detail.index is the row position; detail.row is the row data.
     detail:
@@ -187,6 +196,10 @@ tokens:
     description: Sort arrow color
   --table-transition:
     description: Transition timing
+requiredIcons:
+  - caret-right
+  - caret-up-down
+  - table
 a2ui:
   rules: []
 anti_patterns: []

package/components/tag/class.js

@@ -27,6 +27,12 @@
 import { UIElement } from '../../core/element.js';
 
 export class UITag extends UIElement {
+  // §154 (v0.5.3): Phosphor icons this primitive auto-stamps (without
+  // consumer markup). Aggregated by installIconLoadersForRegistered()
+  // across all defined elements. Audited by check-required-icons.mjs
+  // (slot 11). Per FEEDBACK-06 §4 + FEEDBACK-07 §4.
+  static requiredIcons = ['x'];
+
   static properties = {
     text:      { type: String,  default: '', reflect: true },
     textContent: { type: String, default: '' },

package/components/tag/tag.yaml

@@ -61,6 +61,8 @@ states:
     attribute: disabled
 traits: []
 tokens: {}
+requiredIcons:
+  - x
 a2ui:
   rules: []
 anti_patterns: []

package/components/tree/class.js

@@ -35,6 +35,12 @@
 import { UIElement } from '../../core/element.js';
 
 export class UITree extends UIElement {
+  // §154 (v0.5.3): Phosphor icons this primitive auto-stamps (without
+  // consumer markup). Aggregated by installIconLoadersForRegistered()
+  // across all defined elements. Audited by check-required-icons.mjs
+  // (slot 11). Per FEEDBACK-06 §4 + FEEDBACK-07 §4.
+  static requiredIcons = ['caret-right'];
+
   static template = () => null;
 
   connected() {

package/components/tree/tree.yaml

@@ -66,6 +66,8 @@ tokens:
     description: Inline-end padding of each row
   --tree-row-radius:
     description: Border radius of each row
+requiredIcons:
+  - caret-right
 a2ui:
   rules: []
 anti_patterns: []

package/core/icons.js

@@ -140,6 +140,104 @@ export function installIconLoaders(modules) {
   resolveRegistryReady();
 }
 
+/**
+ * Aggregate `static requiredIcons` declarations from all currently-defined
+ * `customElements`, install loaders for the union, and return the list of
+ * discovered icon names. Replaces the trial-and-error icon-glob authoring
+ * loop FEEDBACK-06 §4 + FEEDBACK-07 §4 reported.
+ *
+ * Each AdiaUI primitive that auto-stamps icons declares them via:
+ *
+ *   export class UISelect extends UIFormElement {
+ *     static requiredIcons = ['caret-up-down'];
+ *     // ...
+ *   }
+ *
+ * Consumer usage:
+ *
+ *   import '@adia-ai/web-components';  // side-effect — defines all primitives
+ *   import { installIconLoadersForRegistered } from '@adia-ai/web-components/core/icons';
+ *
+ *   // Build the Phosphor loader map from your bundler (Vite, Webpack, etc.).
+ *   const modules = import.meta.glob('/node_modules/@phosphor-icons/core/assets/regular/*.svg', { query: '?raw' });
+ *
+ *   // Aggregate requiredIcons across all defined primitives + install.
+ *   const discovered = installIconLoadersForRegistered(modules);
+ *
+ * Or, to limit the icon set to ONLY what's needed (smaller bundle):
+ *
+ *   const discovered = installIconLoadersForRegistered.discover();
+ *   // discovered: ['caret-up-down', 'x', 'caret-right', ...]
+ *   // Now build a narrower glob from this list.
+ *
+ * Added v0.5.3 §154 per FEEDBACK-06 §4 + FEEDBACK-07 §4.
+ *
+ * @param {Record<string, () => Promise<string>>} modules - Phosphor loader map
+ * @returns {string[]} The union of all primitives' `requiredIcons`
+ */
+export function installIconLoadersForRegistered(modules) {
+  const discovered = discoverRequiredIcons();
+  installIconLoaders(modules);
+  return discovered;
+}
+
+/**
+ * Walk customElements and collect the union of `static requiredIcons` across
+ * all defined primitives. Useful for building a Vite glob brace-list that
+ * matches exactly what the registered primitives need.
+ *
+ * Returns an empty array if `customElements` is unavailable (Node SSR)
+ * or if no defined primitive exposes `requiredIcons`.
+ */
+function discoverRequiredIcons() {
+  const union = new Set();
+  if (typeof customElements === 'undefined') return [];
+  // customElements has no Object.entries-style iterator in the standard API.
+  // We need to track which tag names have been defined. The AdiaUI convention:
+  // every primitive's tag ends in `-ui` (or `-n` per yaml `tag:` pattern). We
+  // walk a known list of tag names — passed via opt-in. For SSR safety the
+  // consumer can also pass `tags` explicitly:
+  // discoverRequiredIcons(['select-ui', 'tag-ui', ...]).
+  //
+  // For browser usage with the default barrel import, the consumer's
+  // `import '@adia-ai/web-components'` defines all 93+ primitives at the
+  // global custom-element registry; we walk the DOM-known tag names by
+  // checking customElements.get() on the AdiaUI prefix convention.
+  //
+  // Strategy: query all defined tags by walking the document's primitive
+  // surface OR accept an explicit tag list. The simpler API: iterate over
+  // a known whitelist of tag names. We embed the whitelist for known
+  // auto-stamping primitives.
+  const KNOWN_AUTO_STAMPING_TAGS = [
+    'accordion-ui',
+    'agent-questions-ui',
+    'agent-reasoning-ui',
+    'agent-trace-ui',
+    'calendar-picker-ui',
+    'color-picker-ui',
+    'command-ui',
+    'pane-ui',
+    'select-ui',
+    'table-ui',
+    'tag-ui',
+    'tree-ui',
+  ];
+  for (const tag of KNOWN_AUTO_STAMPING_TAGS) {
+    const ctor = customElements.get(tag);
+    if (ctor && Array.isArray(ctor.requiredIcons)) {
+      for (const name of ctor.requiredIcons) union.add(name);
+    }
+  }
+  return [...union];
+}
+
+/**
+ * Public discovery — same shape as installIconLoadersForRegistered but
+ * doesn't install. Returns the union of `static requiredIcons` across
+ * all currently-defined auto-stamping AdiaUI primitives.
+ */
+installIconLoadersForRegistered.discover = discoverRequiredIcons;
+
 /* Track which (name, weight) pairs we've already warned about so the
    console stays readable even when a missing icon is used many times on
    a page (e.g. a broken Phosphor name in a list row repeated 50×). */
@@ -168,17 +266,62 @@ function filenameFor(name, weight) {
   return `${name}-${weight}.svg`;
 }
 
+/* Resolve a loader by name + weight, tolerant of path-prefix variation.
+ *
+ * Two-step lookup, fast-path first:
+ *
+ *   1. **Fast path**: try the canonical `/node_modules/@phosphor-icons/core/
+ *      assets/<weight>/<filename>` key directly. This is what `icons-phosphor.js`
+ *      installs when Vite's project root sits above an npm-style node_modules,
+ *      and what the chat-ui dev convention assumes.
+ *
+ *   2. **Suffix fallback**: if the fast path misses, scan `modules` keys for
+ *      one ending with `/<filename>`. Handles:
+ *        - pnpm: `/node_modules/.pnpm/@phosphor-icons+core@.../node_modules/.../assets/...`
+ *        - yarn berry / PnP: virtual paths like `/.yarn/cache/...`
+ *        - custom Vite root: `/packages/my-app/node_modules/...`
+ *        - brace-list globs with absolute paths
+ *        - manually-built loader maps with arbitrary keys
+ *
+ * The fast path stays O(1); the fallback is O(N) over the weight's module
+ * map but only runs once per (name, weight) miss (results aren't cached, but
+ * misses fall through to a registry hit via `loadIcon`'s `registry.set`).
+ *
+ * Same two-step shape applies to the `-fill` back-compat name suffix.
+ *
+ * Fix history: pre-§140 the function was fast-path-only. FEEDBACK-06 from
+ * color-app reported `installIconLoaders` → `warnMissingIcon` firing for
+ * `caret-right` / `x` / `caret-up-down` even though the consumer had installed
+ * a loader map. Root cause: color-app's `modules` keys didn't match the
+ * canonical `/node_modules/...` prefix (different package-manager or Vite
+ * root). The suffix fallback closes that gap without changing the public API.
+ */
 function resolveLoader(name, weight = DEFAULT_WEIGHT) {
   const modules = weightModules[weight];
   if (!modules) return null;
-  const key = `/node_modules/@phosphor-icons/core/assets/${weight}/${filenameFor(name, weight)}`;
-  if (modules[key]) return modules[key];
+  const filename = filenameFor(name, weight);
+
+  // 1. Fast path — canonical phosphor npm-style path.
+  const fastKey = `/node_modules/@phosphor-icons/core/assets/${weight}/${filename}`;
+  if (modules[fastKey]) return modules[fastKey];
+
+  // 2. Suffix fallback — match any key ending with the filename.
+  const suffix = `/${filename}`;
+  for (const key in modules) {
+    if (key.endsWith(suffix)) return modules[key];
+  }
 
   // Back-compat: allow the caller to put the -fill suffix directly in the
-  // name (e.g. `name="circle-fill"`) without specifying weight.
+  // name (e.g. `name="circle-fill"`) without specifying weight. Two-step
+  // lookup applies here too.
   if (weight === DEFAULT_WEIGHT && name.endsWith('-fill')) {
-    const fillKey = `/node_modules/@phosphor-icons/core/assets/fill/${name}.svg`;
-    if (weightModules.fill[fillKey]) return weightModules.fill[fillKey];
+    const fillFilename = `${name}.svg`;
+    const fillFastKey = `/node_modules/@phosphor-icons/core/assets/fill/${fillFilename}`;
+    if (weightModules.fill[fillFastKey]) return weightModules.fill[fillFastKey];
+    const fillSuffix = `/${fillFilename}`;
+    for (const key in weightModules.fill) {
+      if (key.endsWith(fillSuffix)) return weightModules.fill[key];
+    }
   }
   return null;
 }

package/core/icons.test.js

@@ -0,0 +1,187 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import {
+  installIconLoaders,
+  registerIcon,
+  hasIcon,
+  isIconName,
+  getIcon,
+  listIcons,
+} from './icons.js';
+
+// Tests for `installIconLoaders` + `resolveLoader` + the §140 suffix-
+// fallback fix for FEEDBACK-06 (color-app's `installIconLoaders` →
+// `warnMissingIcon` failures on `caret-right` / `x` / `caret-up-down`
+// when the consumer's `modules` keys didn't match the canonical
+// `/node_modules/@phosphor-icons/core/assets/<weight>/<name>.svg` path.
+//
+// `isIconName` is the SYNC probe — it calls `resolveLoader` without
+// triggering an async load. That's what we need to assert the fallback
+// logic finds the loader regardless of path shape.
+
+const CARET_RIGHT_SVG = '<svg data-icon="caret-right"/>';
+const X_SVG = '<svg data-icon="x"/>';
+const CARET_UP_DOWN_SVG = '<svg data-icon="caret-up-down"/>';
+
+describe('installIconLoaders + resolveLoader (§140 suffix fallback)', () => {
+  beforeEach(() => {
+    // Reset to a known state. Note: the registry Map itself is module-
+    // singleton + doesn't reset between tests, so we keep test SVG
+    // contents distinct from any real phosphor names just in case.
+    installIconLoaders({ regular: {}, thin: {}, light: {}, bold: {}, fill: {}, duotone: {} });
+  });
+
+  it('resolves by canonical phosphor path (fast path)', () => {
+    installIconLoaders({
+      regular: {
+        '/node_modules/@phosphor-icons/core/assets/regular/caret-right.svg': CARET_RIGHT_SVG,
+        '/node_modules/@phosphor-icons/core/assets/regular/x.svg': X_SVG,
+      },
+    });
+
+    expect(isIconName('caret-right')).toBe(true);
+    expect(isIconName('x')).toBe(true);
+  });
+
+  it('resolves by filename suffix when key has a pnpm-style prefix', () => {
+    // pnpm hoists phosphor inside `.pnpm/<pkg>@<ver>/node_modules/...`
+    installIconLoaders({
+      regular: {
+        '/node_modules/.pnpm/@phosphor-icons+core@2.1.1/node_modules/@phosphor-icons/core/assets/regular/caret-right.svg':
+          CARET_RIGHT_SVG,
+      },
+    });
+
+    expect(isIconName('caret-right')).toBe(true);
+  });
+
+  it('resolves by filename suffix when key is a custom Vite-root absolute path', () => {
+    // Custom Vite root puts node_modules at a deeper location.
+    installIconLoaders({
+      regular: {
+        '/packages/my-app/node_modules/@phosphor-icons/core/assets/regular/caret-up-down.svg':
+          CARET_UP_DOWN_SVG,
+      },
+    });
+
+    expect(isIconName('caret-up-down')).toBe(true);
+  });
+
+  it('resolves by filename suffix for an arbitrary manually-built loader map', () => {
+    // Manual loader maps may have any keys at all — only the filename matters.
+    installIconLoaders({
+      regular: {
+        '/anywhere/at/all/caret-right.svg': CARET_RIGHT_SVG,
+        '/another/path/entirely/x.svg': X_SVG,
+      },
+    });
+
+    expect(isIconName('caret-right')).toBe(true);
+    expect(isIconName('x')).toBe(true);
+  });
+
+  it('returns false on miss across both paths', () => {
+    installIconLoaders({
+      regular: {
+        '/node_modules/@phosphor-icons/core/assets/regular/caret-right.svg': CARET_RIGHT_SVG,
+      },
+    });
+
+    expect(isIconName('not-a-real-icon-name')).toBe(false);
+  });
+
+  it('resolves `-fill` back-compat suffix in name via fast path', () => {
+    const STAR_FILL_SVG = '<svg data-icon="star-fill"/>';
+    installIconLoaders({
+      regular: {},
+      fill: {
+        '/node_modules/@phosphor-icons/core/assets/fill/star-fill.svg': STAR_FILL_SVG,
+      },
+    });
+
+    // `name="star-fill"` with default weight=regular falls back to fill weight.
+    expect(isIconName('star-fill')).toBe(true);
+  });
+
+  it('resolves `-fill` back-compat suffix in name via suffix fallback', () => {
+    const STAR_FILL_SVG = '<svg data-icon="star-fill"/>';
+    installIconLoaders({
+      regular: {},
+      fill: {
+        '/anywhere/star-fill.svg': STAR_FILL_SVG,
+      },
+    });
+
+    expect(isIconName('star-fill')).toBe(true);
+  });
+
+  it('resolves non-regular weights (bold, fill, etc.) via suffix fallback', () => {
+    const HEART_BOLD_SVG = '<svg data-icon="heart-bold"/>';
+    installIconLoaders({
+      regular: {},
+      bold: {
+        '/anywhere/heart-bold.svg': HEART_BOLD_SVG,
+      },
+    });
+
+    expect(isIconName('heart', 'bold')).toBe(true);
+  });
+
+  it('isIconName returns true via alias resolution + suffix fallback', () => {
+    // `send` → `paper-plane-right` in ICON_ALIASES. Suffix fallback should
+    // still match the aliased filename.
+    const PAPER_PLANE_SVG = '<svg data-icon="paper-plane-right"/>';
+    installIconLoaders({
+      regular: {
+        '/anywhere/paper-plane-right.svg': PAPER_PLANE_SVG,
+      },
+    });
+
+    expect(isIconName('send')).toBe(true);
+  });
+
+  it('end-to-end via DOM re-stamp: installIconLoaders auto-loads existing <icon-ui[name]>', async () => {
+    // The §140 fix's primary symptom: `installIconLoaders` walks existing
+    // `<icon-ui[name]>` elements + calls `loadIcon` for each. Without the
+    // suffix fallback, `loadIcon` → `resolveLoader` returns null →
+    // `warnMissingIcon` fires. With the fix, the load completes.
+    const PAW_SVG = '<svg data-icon="paw"/>';
+
+    // Plant an `<icon-ui[name="paw"]>` element. We don't need it to
+    // actually upgrade; we just need `querySelectorAll('icon-ui[name]')`
+    // to find it.
+    const el = document.createElement('icon-ui');
+    el.setAttribute('name', 'paw');
+    document.body.appendChild(el);
+
+    // Install a loader map with a pnpm-style path (suffix fallback exercise).
+    installIconLoaders({
+      regular: {
+        '/some/non-canonical/prefix/paw.svg': PAW_SVG,
+      },
+    });
+
+    // `loadIcon` runs sync (loader is a string, not a function), so the
+    // registry is written by the time `installIconLoaders` returns.
+    expect(hasIcon('paw')).toBe(true);
+
+    document.body.removeChild(el);
+  });
+});
+
+describe('registerIcon / hasIcon — unchanged by §140', () => {
+  it('registerIcon adds an icon by name without needing a loader map', () => {
+    const CUSTOM_SVG = '<svg data-icon="custom-§140-marker"/>';
+    registerIcon('my-§140-custom-icon', CUSTOM_SVG);
+
+    expect(hasIcon('my-§140-custom-icon')).toBe(true);
+    expect(getIcon('my-§140-custom-icon')).toBe(CUSTOM_SVG);
+  });
+
+  it('listIcons returns registered names', () => {
+    registerIcon('§140-listIcons-marker-one', '<svg/>');
+    registerIcon('§140-listIcons-marker-two', '<svg/>');
+
+    expect(listIcons().some((k) => k.includes('§140-listIcons-marker-one'))).toBe(true);
+    expect(listIcons().some((k) => k.includes('§140-listIcons-marker-two'))).toBe(true);
+  });
+});

package/core/template.js

@@ -31,15 +31,48 @@ export function css(strings, ...values) {
 
 const templateCache = new WeakMap();
 
+// §155 (v0.5.3): walks the accumulated static-string chunk to decide
+// whether each ${…} placeholder is in tag-position (substitute {{p:N}})
+// or content-position (substitute <!--p:N-->). The walker tracks `<`,
+// `>`, `'`, `"` for that decision.
+//
+// FEEDBACK-06 §1 P0: HTML comments must be treated as opaque. An
+// apostrophe inside `<!-- foo's bar -->` previously put `q = 1`
+// (single-quoted-string state); the `-->` closer was then treated as
+// string content; all subsequent `<` / `>` chars were masked. Result:
+// every placeholder after the comment got mis-classified, producing
+// `<segmented-ui .value=<!--p:10--> …>` (which the DOM parser eats),
+// `scan()` finds no part registered, and `update()` falls through
+// `isFn` branch — invoking the consumer's arrow handler with no
+// arguments → "Cannot read properties of undefined (reading 'detail')"
+// crash at mount with a stack trace pointing at user code.
+//
+// Fix: skip HTML comments wholesale before the quote/tag walker runs.
+// Comments cannot open a tag and cannot contain real string delimiters
+// as far as the live HTML parser is concerned. Unterminated comments
+// fall through to `last = 0` (content-position) which is the safe
+// default.
 function inTag(m) {
-  let q = 0, last = 0;
-  for (let i = 0; i < m.length; i++) {
+  let q = 0, last = 0, i = 0;
+  while (i < m.length) {
+    if (q === 0 &&
+        m.charCodeAt(i)     === 60 /* < */ &&
+        m.charCodeAt(i + 1) === 33 /* ! */ &&
+        m.charCodeAt(i + 2) === 45 /* - */ &&
+        m.charCodeAt(i + 3) === 45 /* - */) {
+      const end = m.indexOf('-->', i + 4);
+      if (end === -1) { last = 0; break; }
+      i = end + 3;
+      last = 0;
+      continue;
+    }
     const c = m.charCodeAt(i);
     if (q) { if (c === (q === 1 ? 39 : 34)) q = 0; }
     else if (c === 39) q = 1;
     else if (c === 34) q = 2;
     else if (c === 60) last = 1;
     else if (c === 62) last = 0;
+    i++;
   }
   return last === 1;
 }
@@ -93,7 +126,30 @@ function scan(fragment, count) {
     } else if (n.nodeType === 1) {
       for (const attr of [...n.attributes]) {
         const m = attr.value.match(/^\{\{p:(\d+)\}\}$/);
-        if (!m) continue;
+        if (!m) {
+          // §152 (v0.5.3): partial-attribute interpolation runtime guard.
+          // The attribute-part contract is whole-value-only (one placeholder
+          // per attribute, full replacement). Partial like `style="bg:${a};
+          // color:${b}"` produces post-concat `bg:{{p:0}}; color:{{p:1}}`
+          // which fails the ^…$ regex above. Without this guard the literal
+          // {{p:N}} text reaches the DOM as the attribute's static value —
+          // silent-garbage class. Warn loudly so consumers don't ship the
+          // bug. Hot template paths fire many times, so warn (not throw):
+          // a thrown error would crash render; warn surfaces the bug class.
+          if (attr.value.includes('{{p:')) {
+            // eslint-disable-next-line no-console
+            console.warn(
+              `[template] Partial attribute interpolation is not supported.\n` +
+              `  Element: <${n.tagName.toLowerCase()}>\n` +
+              `  Attribute: ${attr.name}="${attr.value.slice(0, 80)}${attr.value.length > 80 ? '…' : ''}"\n` +
+              `  Use one of:\n` +
+              `    ${attr.name}="\${expression}"      ← full replacement (whole attr is the placeholder)\n` +
+              `    .${attr.name}=\${expression}        ← property assignment (preferred for objects/functions)\n` +
+              `  Compute the full attr value as a single expression and interpolate the whole.`
+            );
+          }
+          continue;
+        }
         const i = +m[1], name = attr.name;
         if (name[0] === '@') {
           n.removeAttribute(name);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/web-components",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "AdiaUI web components — vanilla custom elements. A2UI runtime (renderer, registry, streams, wiring) lives in @adia-ai/a2ui-runtime.",
   "type": "module",
   "types": "./index.d.ts",
@@ -58,7 +58,21 @@
     "./core/icons-phosphor.js"
   ],
   "dependencies": {
-    "@adia-ai/a2ui-runtime": "^0.5.0"
+    "@adia-ai/a2ui-runtime": "^0.5.0",
+    "@codemirror/commands": "^6.10.3",
+    "@codemirror/language": "^6.12.3",
+    "@codemirror/lint": "^6.9.5",
+    "@codemirror/state": "^6.6.0",
+    "@codemirror/view": "^6.41.1",
+    "@lezer/highlight": "^1.2.3"
+  },
+  "optionalDependencies": {
+    "@codemirror/lang-css": "^6.3.1",
+    "@codemirror/lang-html": "^6.4.11",
+    "@codemirror/lang-javascript": "^6.2.5",
+    "@codemirror/lang-json": "^6.0.2",
+    "@codemirror/lang-markdown": "^6.5.0",
+    "@codemirror/lang-yaml": "^6.1.3"
   },
   "publishConfig": {
     "access": "public",