@adia-ai/web-components 0.5.3 → 0.5.4

package/components/calendar-picker/class.js

@@ -53,6 +53,7 @@ function sameDay(a, b) {
 }
 
 export class UICalendarPicker extends UIFormElement {
+  static labelDeprecated = false;  // §170 (v0.5.4): label is first-class per calendar-picker.yaml
   // §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

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

@@ -0,0 +1,158 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/ChatInput.json",
+  "title": "ChatInput",
+  "description": "Composable chat input bar — a self-contained chat-message composer\nthat stamps its OWN inner structure (textarea + model picker + send\nbutton) when authored as a bare `<chat-input-ui>` tag.\n\nIMPORTANT (closes the 2026-05-14 redundant-send-button class): the\ncomponent stamps a built-in send button (paper-plane-right icon,\nprimary variant). DO NOT add a separate Button sibling for \"send\" —\nthe user gets two send buttons. The submit event fires on Enter or\nsend-button click; `detail` is `{ text, model }`.\n\nInner stamped structure (default):\n  <chat-input-ui>\n    <textarea-ui placeholder=\"Type a message...\" rows=\"1\"></textarea-ui>\n    <div slot=\"toolbar\">\n      <select-ui slot=\"model\" placeholder=\"Model\">...</select-ui>\n      <button-ui icon=\"paper-plane-right\" variant=\"primary\" slot=\"send\"></button-ui>\n    </div>\n  </chat-input-ui>\n\nLayout:\n  ┌──────────────────────────────────┐\n  │  textarea (grows vertically)     │\n  ├──────────────────────────────────┤\n  │  [model ▾]           [⏎ send]   │  ← toolbar (model picker + built-in send)\n  └──────────────────────────────────┘\n\nComposite wrapper, not a form field itself. The inner textarea-ui\nis form-associated via UIFormElement and submits through the parent\nform. `chat-input-ui`'s `disabled` / `placeholder` props propagate\nto the inner textarea.\n\nFor module-tier composer surfaces (slot vocabulary for file attach,\nautocomplete, trailing/leading controls), wrap inside\n`<chat-composer>` — see ChatComposer for the module-tier shape.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "ChatInput"
+    },
+    "disabled": {
+      "description": "Disable the entire input. Textarea becomes contenteditable=false;\nsend button disabled.\n",
+      "type": "boolean",
+      "default": false
+    },
+    "loading": {
+      "description": "In-flight / streaming state. Send button disabled, submit events\nsuppressed, but textarea stays editable so the user can draft a\nfollow-up while the model is still responding.\n",
+      "type": "boolean",
+      "default": false
+    },
+    "model": {
+      "description": "Currently selected model value (reflected, two-way with inner\n`<select-ui slot=\"model\">`). Empty when no model picker is shown.\n",
+      "type": "string",
+      "default": ""
+    },
+    "models": {
+      "description": "JSON array of model options for the inner model picker —\n[{value, label}] or [{label, options: [...]}] groups. Empty array\nhides the model picker.\n",
+      "type": "array",
+      "default": []
+    },
+    "placeholder": {
+      "description": "Textarea placeholder. Defaults to \"Type a message...\".",
+      "type": "string",
+      "default": "Type a message..."
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [
+      {
+        "description": "Adding a separate Button(primary) sibling next to ChatInput for \"send\". The component stamps its own send button (paper-plane-right icon). Two send buttons render side-by-side, confusing users."
+      },
+      {
+        "description": "Stamping a Select next to ChatInput for model picker. The component has a built-in model picker driven by the `models` prop. Set `models=[{value, label}, ...]` instead of stamping a separate Select."
+      },
+      {
+        "description": "Wrapping ChatInput inside <field-ui label=\"...\"> for label association. ChatInput is a composite container, not a form field. For a labeled composer surface, use <chat-composer> + slot label markup."
+      }
+    ],
+    "category": "agent",
+    "composes": [],
+    "events": {
+      "submit": {
+        "description": "Fires when the user presses Enter (without Shift) in the textarea OR clicks the built-in send button. The composer suppresses submission while `[loading]` is set.",
+        "detail": {
+          "model": {
+            "description": "Currently selected model value (empty if no model picker).",
+            "type": "string"
+          },
+          "text": {
+            "description": "Submitted message text from the inner textarea.",
+            "type": "string"
+          }
+        }
+      }
+    },
+    "examples": [
+      {
+        "description": "Minimal chat input — placeholder, no model picker. Sits inside a chat shell footer.",
+        "a2ui": "[\n  {\"id\": \"root\", \"component\": \"ChatInput\", \"placeholder\": \"Ask me anything...\"}\n]",
+        "name": "basic-chat-input"
+      },
+      {
+        "description": "Chat input with model selection. The `models` prop drives the built-in model picker — DO NOT add a separate Select sibling.",
+        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"ChatInput\",\n    \"placeholder\": \"Type a message...\",\n    \"model\": \"claude-opus-4-7\",\n    \"models\": [\n      {\"value\": \"claude-opus-4-7\", \"label\": \"Claude Opus 4.7\"},\n      {\"value\": \"claude-haiku-4-5\", \"label\": \"Claude Haiku 4.5\"},\n      {\"value\": \"claude-sonnet-4-5\", \"label\": \"Claude Sonnet 4.5\"}\n    ]\n  }\n]",
+        "name": "chat-input-with-models"
+      },
+      {
+        "description": "Streaming response state. `[loading]` reflects on the host; send button disables; textarea stays editable so the user can draft a follow-up while the LLM is responding.",
+        "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"ChatInput\",\n    \"placeholder\": \"Drafting follow-up while streaming...\",\n    \"loading\": true\n  }\n]",
+        "name": "chat-input-loading-state"
+      },
+      {
+        "description": "Full chat shell — header + thread + ChatInput in the footer. Note: ChatInput is the sole footer child; no separate send button.",
+        "a2ui": "[\n  {\"id\": \"root\", \"component\": \"ChatShell\", \"children\": [\"header\", \"thread\", \"input\"]},\n  {\"id\": \"header\", \"component\": \"ChatHeader\", \"title\": \"Chat\"},\n  {\"id\": \"thread\", \"component\": \"ChatThread\"},\n  {\"id\": \"input\", \"component\": \"ChatInput\", \"placeholder\": \"Send a message...\"}\n]",
+        "name": "chat-shell-with-chat-input"
+      }
+    ],
+    "keywords": [
+      "chat-input",
+      "chat",
+      "message-input",
+      "composer",
+      "send-message",
+      "conversation",
+      "prompt",
+      "submit"
+    ],
+    "name": "UIChatInput",
+    "related": [
+      "ChatShell",
+      "ChatThread",
+      "ChatComposer",
+      "ChatHeader",
+      "TextArea",
+      "Input"
+    ],
+    "slots": {
+      "model": {
+        "description": "Override slot for the model picker. Most authors should NOT override this — set the `models` prop instead."
+      },
+      "send": {
+        "description": "Override slot for the send button only. The default stamped send button has `[icon=\"paper-plane-right\"] [variant=\"primary\"]`. Most authors should NOT override this — the built-in send button IS the send control. Adding a separate Button sibling for \"send\" duplicates this functionality."
+      },
+      "toolbar": {
+        "description": "Override slot for the entire toolbar row (model picker + send button). Most authors should NOT override this — the built-in toolbar handles model selection + send. Use this only when custom toolbar layout is required."
+      }
+    },
+    "states": [
+      {
+        "description": "Default, accepting input. Send button enabled when textarea has content.",
+        "name": "idle"
+      },
+      {
+        "description": "Input fully disabled (typically during initial form setup).",
+        "attribute": "disabled",
+        "name": "disabled"
+      },
+      {
+        "description": "LLM is responding. Send button disabled + submit events suppressed, but textarea stays editable for follow-up drafts.",
+        "attribute": "loading",
+        "name": "loading"
+      }
+    ],
+    "synonyms": {
+      "message-input": [
+        "conversation-input",
+        "prompt-input",
+        "send-bar"
+      ]
+    },
+    "tag": "chat-input-ui",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

package/components/chat-thread/chat-input.yaml

@@ -0,0 +1,251 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+#
+# §172 (v0.5.4): authored to close the chat-input redundant-send-button
+# regression diagnosed 2026-05-14. Pre-§172 the runtime registry declared
+# `ChatInput → chat-input-ui` but the component had no yaml/sidecar/catalog
+# entry — `<chat-input-ui>` lived as a sibling file inside `chat-thread/`
+# rather than its own folder. The build scanner only looked for canonical
+# `<name>/<name>.yaml`, so this component was invisible to the catalog +
+# system prompt + audit pipeline.
+#
+# Result: the LLM saw `ChatInput` in the type registry but had no schema
+# describing what the element stamps. When users asked for "chat interface
+# with chat-input", the LLM defensively added a sibling Button (primary
+# variant) for "send" — duplicating the built-in send button the
+# component already stamps. The user's ticket
+# (20260514045025-chatinput-training-data-unclea) flagged this.
+#
+# The scanner was extended in §172 to pick up sibling yamls in the same
+# component dir. This file now flows through the build to the v0.9 catalog,
+# the LLM system prompt's CORPUS CONTEXT block, and the audit-script family.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIChatInput
+tag: chat-input-ui
+component: ChatInput
+category: agent
+version: 1
+description: |
+  Composable chat input bar — a self-contained chat-message composer
+  that stamps its OWN inner structure (textarea + model picker + send
+  button) when authored as a bare `<chat-input-ui>` tag.
+
+  IMPORTANT (closes the 2026-05-14 redundant-send-button class): the
+  component stamps a built-in send button (paper-plane-right icon,
+  primary variant). DO NOT add a separate Button sibling for "send" —
+  the user gets two send buttons. The submit event fires on Enter or
+  send-button click; `detail` is `{ text, model }`.
+
+  Inner stamped structure (default):
+    <chat-input-ui>
+      <textarea-ui placeholder="Type a message..." rows="1"></textarea-ui>
+      <div slot="toolbar">
+        <select-ui slot="model" placeholder="Model">...</select-ui>
+        <button-ui icon="paper-plane-right" variant="primary" slot="send"></button-ui>
+      </div>
+    </chat-input-ui>
+
+  Layout:
+    ┌──────────────────────────────────┐
+    │  textarea (grows vertically)     │
+    ├──────────────────────────────────┤
+    │  [model ▾]           [⏎ send]   │  ← toolbar (model picker + built-in send)
+    └──────────────────────────────────┘
+
+  Composite wrapper, not a form field itself. The inner textarea-ui
+  is form-associated via UIFormElement and submits through the parent
+  form. `chat-input-ui`'s `disabled` / `placeholder` props propagate
+  to the inner textarea.
+
+  For module-tier composer surfaces (slot vocabulary for file attach,
+  autocomplete, trailing/leading controls), wrap inside
+  `<chat-composer>` — see ChatComposer for the module-tier shape.
+
+props:
+  disabled:
+    description: |
+      Disable the entire input. Textarea becomes contenteditable=false;
+      send button disabled.
+    type: boolean
+    default: false
+    reflect: true
+  loading:
+    description: |
+      In-flight / streaming state. Send button disabled, submit events
+      suppressed, but textarea stays editable so the user can draft a
+      follow-up while the model is still responding.
+    type: boolean
+    default: false
+    reflect: true
+  placeholder:
+    description: Textarea placeholder. Defaults to "Type a message...".
+    type: string
+    default: "Type a message..."
+    reflect: true
+  model:
+    description: |
+      Currently selected model value (reflected, two-way with inner
+      `<select-ui slot="model">`). Empty when no model picker is shown.
+    type: string
+    default: ""
+    reflect: true
+  models:
+    description: |
+      JSON array of model options for the inner model picker —
+      [{value, label}] or [{label, options: [...]}] groups. Empty array
+      hides the model picker.
+    type: array
+    default: []
+
+events:
+  submit:
+    description: >-
+      Fires when the user presses Enter (without Shift) in the textarea
+      OR clicks the built-in send button. The composer suppresses
+      submission while `[loading]` is set.
+    detail:
+      text:
+        type: string
+        description: Submitted message text from the inner textarea.
+      model:
+        type: string
+        description: Currently selected model value (empty if no model picker).
+
+slots:
+  toolbar:
+    description: >-
+      Override slot for the entire toolbar row (model picker + send
+      button). Most authors should NOT override this — the built-in
+      toolbar handles model selection + send. Use this only when
+      custom toolbar layout is required.
+  send:
+    description: >-
+      Override slot for the send button only. The default stamped send
+      button has `[icon="paper-plane-right"] [variant="primary"]`. Most
+      authors should NOT override this — the built-in send button IS
+      the send control. Adding a separate Button sibling for "send"
+      duplicates this functionality.
+  model:
+    description: >-
+      Override slot for the model picker. Most authors should NOT
+      override this — set the `models` prop instead.
+
+states:
+  - name: idle
+    description: Default, accepting input. Send button enabled when textarea has content.
+  - name: disabled
+    attribute: disabled
+    description: Input fully disabled (typically during initial form setup).
+  - name: loading
+    attribute: loading
+    description: >-
+      LLM is responding. Send button disabled + submit events suppressed,
+      but textarea stays editable for follow-up drafts.
+
+traits: []
+
+a2ui:
+  rules:
+    - >-
+      ChatInput is a self-contained composer — it stamps its own
+      textarea + model picker + send button. DO NOT add a separate
+      Button sibling for "send" inside the same parent. The user
+      gets two send buttons (one built-in, one redundant).
+    - >-
+      For chat interfaces emit ChatInput as the sole input
+      component inside the chat shell. The submit event fires on
+      Enter or send-button click; `detail` is `{ text, model }`.
+    - >-
+      To customize models, set the `models` prop with an array of
+      {value, label} option objects. Do not stamp a separate Select
+      next to ChatInput for model selection — the built-in model
+      picker handles it.
+
+anti_patterns:
+  - description: >-
+      Adding a separate Button(primary) sibling next to ChatInput for
+      "send". The component stamps its own send button (paper-plane-right
+      icon). Two send buttons render side-by-side, confusing users.
+  - description: >-
+      Stamping a Select next to ChatInput for model picker. The component
+      has a built-in model picker driven by the `models` prop. Set
+      `models=[{value, label}, ...]` instead of stamping a separate Select.
+  - description: >-
+      Wrapping ChatInput inside <field-ui label="..."> for label
+      association. ChatInput is a composite container, not a form
+      field. For a labeled composer surface, use <chat-composer> +
+      slot label markup.
+
+examples:
+  - name: basic-chat-input
+    description: >-
+      Minimal chat input — placeholder, no model picker. Sits inside
+      a chat shell footer.
+    a2ui: |-
+      [
+        {"id": "root", "component": "ChatInput", "placeholder": "Ask me anything..."}
+      ]
+  - name: chat-input-with-models
+    description: >-
+      Chat input with model selection. The `models` prop drives the
+      built-in model picker — DO NOT add a separate Select sibling.
+    a2ui: |-
+      [
+        {
+          "id": "root",
+          "component": "ChatInput",
+          "placeholder": "Type a message...",
+          "model": "claude-opus-4-7",
+          "models": [
+            {"value": "claude-opus-4-7", "label": "Claude Opus 4.7"},
+            {"value": "claude-haiku-4-5", "label": "Claude Haiku 4.5"},
+            {"value": "claude-sonnet-4-5", "label": "Claude Sonnet 4.5"}
+          ]
+        }
+      ]
+  - name: chat-input-loading-state
+    description: >-
+      Streaming response state. `[loading]` reflects on the host;
+      send button disables; textarea stays editable so the user can
+      draft a follow-up while the LLM is responding.
+    a2ui: |-
+      [
+        {
+          "id": "root",
+          "component": "ChatInput",
+          "placeholder": "Drafting follow-up while streaming...",
+          "loading": true
+        }
+      ]
+  - name: chat-shell-with-chat-input
+    description: >-
+      Full chat shell — header + thread + ChatInput in the footer.
+      Note: ChatInput is the sole footer child; no separate send
+      button.
+    a2ui: |-
+      [
+        {"id": "root", "component": "ChatShell", "children": ["header", "thread", "input"]},
+        {"id": "header", "component": "ChatHeader", "title": "Chat"},
+        {"id": "thread", "component": "ChatThread"},
+        {"id": "input", "component": "ChatInput", "placeholder": "Send a message..."}
+      ]
+
+keywords:
+  - chat-input
+  - chat
+  - message-input
+  - composer
+  - send-message
+  - conversation
+  - prompt
+  - submit
+
+synonyms:
+  message-input: [conversation-input, prompt-input, send-bar]
+
+related:
+  - ChatShell
+  - ChatThread
+  - ChatComposer
+  - ChatHeader
+  - TextArea
+  - Input

package/components/check/class.js

@@ -20,6 +20,7 @@ import { UIFormElement } from '../../core/form.js';
 import { html } from '../../core/element.js';
 
 export class UICheck extends UIFormElement {
+  static labelDeprecated = false;  // §170 (v0.5.4): label is first-class per check.yaml
   static properties = {
     ...UIFormElement.properties,
     checked:       { type: Boolean, default: false, reflect: true },

package/components/feed/feed-item.a2ui.json

@@ -0,0 +1,86 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/FeedItem.json",
+  "title": "FeedItem",
+  "description": "Atomic feed entry inside a `<feed-ui>` lane. Three dismiss policies are inferred from the prop shape — auto-fade (duration > 0 + no action), sticky-dismissible (duration null/0), action-required (duration null/0 + action; future phase). Posted via `UIFeed.post()` rather than authored directly.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "component": {
+      "const": "FeedItem"
+    },
+    "dismissible": {
+      "description": "Render an x close button (default true for sticky, false for auto-fade)",
+      "type": "boolean",
+      "default": false
+    },
+    "duration": {
+      "description": "Auto-fade timer in ms; null/0 = sticky (requires user input)",
+      "type": "number",
+      "default": 4000
+    },
+    "heading": {
+      "description": "Optional emphasis line above text",
+      "type": "string",
+      "default": ""
+    },
+    "icon": {
+      "description": "Optional leading icon name",
+      "type": "string",
+      "default": ""
+    },
+    "text": {
+      "description": "Body copy",
+      "type": "string",
+      "default": ""
+    },
+    "variant": {
+      "description": "Semantic variant",
+      "type": "string",
+      "enum": [
+        "default",
+        "info",
+        "success",
+        "warning",
+        "danger"
+      ],
+      "default": "default"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "feedback",
+    "composes": [],
+    "events": {
+      "close": {
+        "description": "Fired after the item finishes its exit animation"
+      }
+    },
+    "examples": [],
+    "keywords": [],
+    "name": "UIFeedItem",
+    "related": [],
+    "slots": {
+      "body": {
+        "description": "Default content slot (also accepts the `text` / `heading` props)"
+      }
+    },
+    "states": {},
+    "synonyms": {},
+    "tag": "feed-item-ui",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

package/components/radio/class.js

@@ -20,6 +20,7 @@ import { UIFormElement } from '../../core/form.js';
 import { html } from '../../core/element.js';
 
 export class UIRadio extends UIFormElement {
+  static labelDeprecated = false;  // §170 (v0.5.4): label is first-class per radio.yaml
   static properties = {
     ...UIFormElement.properties,
     checked:  { type: Boolean, default: false, reflect: true },

package/components/select/class.js

@@ -19,6 +19,7 @@ function escapeHTML(s) {
 }
 
 export class UISelect extends UIFormElement {
+  static labelDeprecated = false;  // §170 (v0.5.4): label is first-class per select.yaml
   // §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

package/components/switch/class.js

@@ -20,6 +20,7 @@ import { UIFormElement } from '../../core/form.js';
 import { html } from '../../core/element.js';
 
 export class UISwitch extends UIFormElement {
+  static labelDeprecated = false;  // §170 (v0.5.4): label is first-class per switch.yaml
   static properties = {
     ...UIFormElement.properties,
     checked:  { type: Boolean, default: false, reflect: true },

package/components/textarea/class.js

@@ -20,6 +20,7 @@
 import { UIFormElement } from '../../core/form.js';
 
 export class UITextarea extends UIFormElement {
+  static labelDeprecated = false;  // §170 (v0.5.4): label is first-class per textarea.yaml
   static properties = {
     ...UIFormElement.properties,
     placeholder: { type: String,  default: '', reflect: true },

package/components/upload/class.js

@@ -20,6 +20,7 @@
 import { UIFormElement } from '../../core/form.js';
 
 export class UIUpload extends UIFormElement {
+  static labelDeprecated = false;  // §170 (v0.5.4): label is first-class per upload.yaml
   static properties = {
     ...UIFormElement.properties,
     label:    { type: String,  default: '', reflect: true },

package/core/icons.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Icon registry — pluggable lookup map for `<icon-ui>` SVG resolution.
+ *
+ * Three consumer paths, picked by bundle-size budget:
+ *
+ *   1. **Zero-config** — import the main barrel; phosphor side-effect-loads
+ *      via `core/icons-phosphor.js`. Largest bundle (~9 000 chunks under
+ *      `vite build`). Best for prototypes.
+ *
+ *   2. **Opt-in phosphor with piecemeal component imports** — when you
+ *      `import '@adia-ai/web-components/components/button'` etc. you skip
+ *      the barrel's phosphor side-effect. Add it explicitly:
+ *        import '@adia-ai/web-components/core/icons-phosphor';
+ *
+ *   3. **Scoped registration (smallest bundle)** — install only the icons
+ *      you use via `installIconLoaders()` with a brace-list glob, OR
+ *      `installIconLoadersForRegistered()` to auto-discover from defined
+ *      primitives' `static requiredIcons`.
+ *
+ * Runtime exports mirror `core/icons.js`. `installIconLoadersForRegistered`
+ * shipped in v0.5.3 §154 (FEEDBACK-06 §4 + FEEDBACK-07 §4). `.d.ts`
+ * authored in v0.5.4 to close the missing-type-surface gap that blocked
+ * TypeScript consumers from importing the helper.
+ *
+ * @see ../USAGE.md (consumer guide)
+ * @see ./icons-phosphor.js (the zero-config side-effect path)
+ */
+
+/**
+ * Phosphor weight identifiers. `regular` is the default; the other five
+ * weights resolve to the corresponding `@phosphor-icons/core/assets/<weight>/`
+ * subtree when consumers install loaders for them.
+ */
+export const ICON_WEIGHTS: ReadonlyArray<'regular' | 'thin' | 'light' | 'bold' | 'fill' | 'duotone'>;
+
+/** A single phosphor weight identifier. */
+export type IconWeight = 'regular' | 'thin' | 'light' | 'bold' | 'fill' | 'duotone';
+
+/**
+ * Loader value in an icon-loader map. Either the SVG string itself (eager
+ * `import.meta.glob({ eager: true })` output) or a thunk that resolves to
+ * the SVG string (lazy / dynamic import).
+ */
+export type IconLoader = string | (() => string | Promise<string>);
+
+/**
+ * Per-path loader map for a single weight. Keys are typically the
+ * `/node_modules/@phosphor-icons/core/assets/<weight>/<filename>.svg` paths
+ * `import.meta.glob` produces — but any keys work (§140's filename-suffix
+ * fallback handles pnpm / yarn-berry / custom-Vite-root prefixes).
+ */
+export type IconLoaderMap = Record<string, IconLoader>;
+
+/**
+ * Per-weight loader maps. Pass to `installIconLoaders()` /
+ * `installIconLoadersForRegistered()`. Most consumers pass only `regular`;
+ * weight-overloaded usage (e.g. `<icon-ui name="star" weight="fill">`)
+ * needs the corresponding weight populated.
+ */
+export interface WeightModules {
+  regular?: IconLoaderMap;
+  thin?: IconLoaderMap;
+  light?: IconLoaderMap;
+  bold?: IconLoaderMap;
+  fill?: IconLoaderMap;
+  duotone?: IconLoaderMap;
+}
+
+/** Register a single icon by name. Bypasses loader-map lookup entirely. */
+export function registerIcon(name: string, svg: string, weight?: IconWeight): void;
+
+/** Register multiple icons at a single weight. Bypasses loader-map lookup. */
+export function registerIcons(icons: Record<string, string>, weight?: IconWeight): void;
+
+/**
+ * Get icon SVG by name + weight. Returns the cached SVG if present;
+ * otherwise triggers an async load (returning `''` immediately) + the
+ * registered `<icon-ui>` elements re-render once the load resolves.
+ */
+export function getIcon(name: string, weight?: IconWeight): string;
+
+/** Sync check — is `name` cached in the registry at this weight? */
+export function hasIcon(name: string, weight?: IconWeight): boolean;
+
+/** List all cached `weight:name` keys in the registry. */
+export function listIcons(): string[];
+
+/**
+ * Sync check — is `name` (or its `ICON_ALIASES` alias) a known icon at
+ * the given weight? Doesn't trigger loading. Used by primitives that
+ * accept either an icon name or a text label (`<input-ui prefix>`,
+ * `<input-ui suffix>`) to disambiguate.
+ */
+export function isIconName(name: string, weight?: IconWeight): boolean;
+
+/**
+ * Resolves once the icon registry is sync-checkable — i.e., after the
+ * first `installIconLoaders()` call. Primitives that branch on
+ * `isIconName` at connect time should await this to avoid the static-
+ * deploy race (the registry starts empty, fills async via manifest fetch).
+ */
+export const whenIconRegistryReady: Promise<void>;
+
+/**
+ * Install a per-weight loader map. Idempotent — subsequent calls replace
+ * the previous map. After install, re-stamps any existing
+ * `<icon-ui[name]>` elements so they re-render with the newly-loadable
+ * SVGs.
+ *
+ * @param modules per-weight maps; missing weights stay empty.
+ */
+export function installIconLoaders(modules: WeightModules): void;
+
+/**
+ * Auto-discover the icon set from defined primitives' `static
+ * requiredIcons` declarations, then install loaders.
+ *
+ * Each AdiaUI primitive that auto-stamps icons declares them via:
+ *
+ *     export class UISelect extends UIFormElement {
+ *       static requiredIcons = ['caret-up-down'];
+ *       // ...
+ *     }
+ *
+ * This helper aggregates the union across all currently-defined
+ * primitives (post-side-effect imports) and installs `modules` as the
+ * loader source. The returned list is the discovered set — useful for
+ * trimming a wide glob to only what's needed.
+ *
+ * Shipped v0.5.3 §154 (FEEDBACK-06 §4 + FEEDBACK-07 §4).
+ *
+ * @param modules - per-weight loader maps (typically `import.meta.glob`
+ *                  output for `@phosphor-icons/core/assets/<weight>/*.svg`)
+ * @returns the union of `static requiredIcons` across all defined primitives
+ */
+export function installIconLoadersForRegistered(
+  modules: IconLoaderMap | WeightModules
+): string[];
+
+export namespace installIconLoadersForRegistered {
+  /**
+   * Same-shape companion to `installIconLoadersForRegistered` but
+   * doesn't install. Returns the union of `static requiredIcons` across
+   * all currently-defined primitives — useful when you want to build a
+   * narrower glob from the discovered list.
+   */
+  function discover(): string[];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/web-components",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "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",