@adia-ai/web-components 0.5.3 → 0.5.5

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/list/list-item.a2ui.json

@@ -0,0 +1,53 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/ListItem.json",
+  "title": "ListItem",
+  "description": "Child of <list-ui>. One list item with optional icon + text + description, plus arbitrary slotted content (cards, rows). Use inside <list-ui> only.",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "description": {
+      "description": "Secondary line below the primary text. Subtle color.",
+      "type": "string"
+    },
+    "component": {
+      "const": "ListItem"
+    },
+    "icon": {
+      "description": "Optional leading icon name (Phosphor).",
+      "type": "string"
+    },
+    "text": {
+      "description": "Primary text. Renders as semibold inline body.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "component"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [],
+    "category": "layout",
+    "composes": [],
+    "events": {},
+    "examples": [],
+    "keywords": [],
+    "name": "UIListItem",
+    "related": [],
+    "slots": {},
+    "states": [],
+    "synonyms": {},
+    "tag": "list-item-ui",
+    "tokens": {},
+    "traits": [],
+    "version": 1
+  }
+}

package/components/list/list-item.yaml

@@ -0,0 +1,29 @@
+# Edit this file; run `npm run build:components` to regenerate a2ui.json.
+#
+# §176 (v0.5.5): authored to close the §175 baseline-orphan class. The
+# component already existed as a sibling class in the parent's class.js
+# + was registered alongside the parent (e.g. UIList + UIListItem both
+# from list/class.js). The catalog just lacked its own entry. With the
+# §172 sibling-yaml scanner, this file gets picked up next to the parent
+# yaml.
+
+# Child component of <list-ui>. Surface only inside that parent.
+$schema: ../../../../scripts/schemas/component.yaml.schema.json
+name: UIListItem
+tag: list-item-ui
+component: ListItem
+category: layout
+version: 1
+description: |-
+  Child of <list-ui>. One list item with optional icon + text + description, plus arbitrary slotted content (cards, rows). Use inside <list-ui> only.
+
+props:
+  icon:
+    description: Optional leading icon name (Phosphor).
+    type: string
+  text:
+    description: Primary text. Renders as semibold inline body.
+    type: string
+  description:
+    description: Secondary line below the primary text. Subtle color.
+    type: string

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
@@ -36,8 +37,14 @@ export class UISelect extends UIFormElement {
     searchable:  { type: Boolean, default: false, reflect: true },
     freeText:    { type: Boolean, default: false, reflect: true, attribute: 'free-text' },
     divider:     { type: Boolean, default: false, reflect: true },
+    // §184 (v0.5.5, FEEDBACK-08 §7): optional caption beneath the
+    // trigger, wired to aria-describedby on the host.
+    hint:        { type: String,  default: '', reflect: true },
   };
 
+  // §184: per-instance hint id counter for aria-describedby wiring.
+  static #hintSeq = 0;
+
   static template = () => null;
 
   #options = [];
@@ -96,13 +103,21 @@ export class UISelect extends UIFormElement {
       const displayMarkup = this.searchable
         ? `<input slot="display" type="text" role="combobox" aria-autocomplete="list" autocomplete="off" placeholder="${escapeHTML(this.placeholder || '')}" value="${escapeHTML(this.#displayText() === this.placeholder ? '' : this.#displayText())}" />`
         : `<span slot="display">${escapeHTML(this.#displayText())}</span>`;
+      // §184 (v0.5.5, FEEDBACK-08 §7): optional hint slot beneath the
+      // trigger. Mirrors slider-ui's hint pattern + matches the
+      // schema-declared `hint` prop on switch-ui (which had the spec
+      // but not the rendering until this arc).
+      const hintId = this.hint ? `select-hint-${++UISelect.#hintSeq}` : '';
+      const hintMarkup = this.hint ? `<span slot="hint" id="${hintId}">${escapeHTML(this.hint)}</span>` : '';
       this.innerHTML = `
         <span slot="trigger">
           ${leading}
           ${displayMarkup}
           <icon-ui name="caret-up-down" slot="caret"></icon-ui>
         </span>
+        ${hintMarkup}
       `;
+      if (this.hint) this.setAttribute('aria-describedby', hintId);
 
       if (this.searchable) {
         // Detach from previous search input if any

package/components/select/select.a2ui.json

@@ -46,6 +46,11 @@
       "type": "boolean",
       "default": false
     },
+    "hint": {
+      "description": "§184 (v0.5.5, FEEDBACK-08 §7): small caption rendered beneath the select. Sets `aria-describedby` on the host so screen readers announce it as a description (distinct from `aria-label`, which comes from `label`). Does not conflict with the in-component `label`.",
+      "type": "string",
+      "default": ""
+    },
     "icon": {
       "description": "Leading icon name rendered inside the trigger",
       "type": "string",

package/components/select/select.css

@@ -308,3 +308,13 @@ select-ui[divider] [role="group"] + [role="group"] {
   margin-top: var(--a-space-1);
   padding-top: var(--a-space-1);
 }
+
+/* ── Hint (§184, v0.5.5, FEEDBACK-08 §7) ──
+   Caption beneath the trigger; wired to aria-describedby on the host. */
+select-ui > [slot="hint"] {
+  display: block;
+  margin-top: var(--select-hint-mt, var(--a-space-1));
+  font-size: var(--select-hint-size, var(--a-fine-size));
+  color: var(--select-hint-fg, var(--a-fg-muted));
+  line-height: var(--select-hint-lh, 1.4);
+}

package/components/select/select.yaml

@@ -67,6 +67,11 @@ props:
     description: Label text above the trigger
     type: string
     default: ""
+  hint:
+    description: |-
+      §184 (v0.5.5, FEEDBACK-08 §7): small caption rendered beneath the select. Sets `aria-describedby` on the host so screen readers announce it as a description (distinct from `aria-label`, which comes from `label`). Does not conflict with the in-component `label`.
+    type: string
+    default: ""
   maxlength:
     description: Maximum character length for validation
     type: number

package/components/slider/class.js

@@ -42,13 +42,31 @@ export class UISlider extends UIFormElement {
     step:   { type: Number,  default: 1,  reflect: true },
     label:  { type: String,  default: '', reflect: true },
     suffix: { type: String,  default: '', reflect: true },
+    // §184 (v0.5.5, FEEDBACK-08 §4): declarative debounce for the
+    // `input` event when driving expensive computation (palette regen,
+    // shader compile, large list reflow). When > 0, value updates +
+    // visual feedback are immediate but `input` event emission is
+    // debounced — only the FINAL value in the throttle window dispatches.
+    // `change` fires unthrottled on pointerup / track click / keyboard;
+    // any pending `input` flushes BEFORE `change` so consumers always
+    // see input→input→…→input→change ordering. throttle="0" (default)
+    // preserves the pre-§184 every-pointer-move-fires-input behavior.
+    throttle: { type: Number, default: 0, reflect: true },
   };
 
   static template = () => null;
 
+  // §184: per-instance hint id counter for aria-describedby wiring.
+  static #hintSeq = 0;
+
   #trackEl = null;
   #thumbEl = null;
   #dragging = false;
+  // §184 (v0.5.5, FEEDBACK-08 §4): debounce timer for the `input`
+  // event. When `throttle > 0`, #setValue stores a pending dispatch
+  // here + restarts the timer on every value change. Flushed before
+  // any `change` event so input always precedes change.
+  #inputTimer = null;
 
   get #pct() {
     const range = this.max - this.min;
@@ -69,6 +87,9 @@ export class UISlider extends UIFormElement {
     if (this.label) this.setAttribute('aria-label', this.label);
 
     if (!this.querySelector('[slot="track"]')) {
+      // §184 (v0.5.5, FEEDBACK-08 §7): hint slot stamped underneath
+      // the track when [hint] is set. Wired to aria-describedby below.
+      const hintId = this.hint ? `slider-hint-${++UISlider.#hintSeq}` : '';
       this.innerHTML = `
         <div slot="header">
           ${this.label ? `<span slot="label">${this.label}</span>` : ''}
@@ -81,7 +102,9 @@ export class UISlider extends UIFormElement {
           <div slot="fill"></div>
           <div slot="thumb" tabindex="0"></div>
         </div>
+        ${this.hint ? `<span slot="hint" id="${hintId}">${this.hint}</span>` : ''}
       `;
+      if (this.hint) this.setAttribute('aria-describedby', hintId);
     }
 
     this.#trackEl = this.querySelector('[slot="track"]');
@@ -148,9 +171,36 @@ export class UISlider extends UIFormElement {
   #setValue(v) {
     if (v === this.value) return;
     this.value = v;
+    // §184: when throttle > 0, debounce the `input` dispatch.
+    // The value update + UI is still immediate; only event emission is
+    // accumulated. Same value can dispatch input multiple times across
+    // pointer moves, but the throttle collapses them to one trailing
+    // emission at quiet+throttle ms.
+    const t = Number(this.throttle) || 0;
+    if (t > 0) {
+      if (this.#inputTimer != null) clearTimeout(this.#inputTimer);
+      this.#inputTimer = setTimeout(() => {
+        this.#inputTimer = null;
+        this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
+      }, t);
+      return;
+    }
     this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
   }
 
+  /**
+   * §184: flush any pending throttled `input` dispatch synchronously.
+   * Called before `change` so consumers see the trailing input event
+   * BEFORE the change commit. No-op when no timer is pending.
+   */
+  #flushInput() {
+    if (this.#inputTimer != null) {
+      clearTimeout(this.#inputTimer);
+      this.#inputTimer = null;
+      this.dispatchEvent(new CustomEvent('input', { bubbles: true, detail: { value: this.value } }));
+    }
+  }
+
   #onPointerDown = (e) => {
     if (this.disabled) return;
     e.preventDefault();
@@ -170,12 +220,14 @@ export class UISlider extends UIFormElement {
     this.#thumbEl.releasePointerCapture(e.pointerId);
     this.#thumbEl.removeEventListener('pointermove', this.#onPointerMove);
     this.#thumbEl.removeEventListener('pointerup', this.#onPointerUp);
+    this.#flushInput(); // §184: pending throttled input fires before change
     this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
   };
 
   #onTrackClick = (e) => {
     if (this.disabled || e.target === this.#thumbEl) return;
     this.#setValue(this.#valueFromX(e.clientX));
+    this.#flushInput(); // §184: ensure trailing input precedes change
     this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
   };
 
@@ -193,6 +245,7 @@ export class UISlider extends UIFormElement {
     }
     e.preventDefault();
     this.#setValue(this.#snap(v));
+    this.#flushInput(); // §184: trailing input fires before change
     this.dispatchEvent(new CustomEvent('change', { bubbles: true, detail: { value: this.value } }));
   };
 
@@ -203,6 +256,11 @@ export class UISlider extends UIFormElement {
     this.#thumbEl?.removeEventListener('pointermove', this.#onPointerMove);
     this.#thumbEl?.removeEventListener('pointerup', this.#onPointerUp);
     this.removeEventListener('keydown', this.#onKey);
+    // §184: drop any pending throttle timer (no flush — element is gone)
+    if (this.#inputTimer != null) {
+      clearTimeout(this.#inputTimer);
+      this.#inputTimer = null;
+    }
     this.#trackEl = null;
     this.#thumbEl = null;
   }

package/components/slider/slider.a2ui.json

@@ -31,6 +31,11 @@
       "type": "string",
       "default": ""
     },
+    "hint": {
+      "description": "§184 (v0.5.5, FEEDBACK-08 §7): small caption rendered beneath the slider track. Sets `aria-describedby` on the host so screen readers announce it as a description (distinct from `aria-label`, which comes from `label`). Does not conflict with the in-component `label`. Use for semantic clarifications a `<field-ui>` wrapper would be overkill for.",
+      "type": "string",
+      "default": ""
+    },
     "label": {
       "description": "Label text above the slider",
       "type": "string",
@@ -61,6 +66,11 @@
       "type": "string",
       "default": ""
     },
+    "throttle": {
+      "description": "§184 (v0.5.5, FEEDBACK-08 §4): when > 0, debounce the `input` event by this many milliseconds. Value updates + visual feedback remain immediate; only event dispatch accumulates. Pending input flushes BEFORE `change` so consumers always see input→…→input→change ordering. throttle=\"0\" (default) preserves the pre-§184 every-pointer-move-fires-input behavior. Common values: 50-100ms for palette regen / shader compile / large list reflow.",
+      "type": "number",
+      "default": 0
+    },
     "value": {
       "description": "Current slider value",
       "type": "number",