@adia-ai/web-components 0.4.7 → 0.4.9

package/components/canvas/canvas.yaml

@@ -5,6 +5,18 @@ component: Canvas
 category: agent
 version: 1
 description: A2UI rendering surface.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+# <canvas-ui> composes only cross-package primitives (a2ui-root + theme-ui);
+# they're declared in cross_package_composes: below per v0.4.9 §92 G1.
+composes: []
+cross_package_composes:
+  - tag: a2ui-root
+    from: '@adia-ai/web-modules/runtime'
+    note: Hosts A2UI rendering. Required whenever canvas mounts content.
+  - tag: theme-ui
+    from: '@adia-ai/web-modules/theme'
+    note: Optional — only read when [theme-wrapper] is set.
 props:
   theme:
     description: 'Component property: theme.'

package/components/card/card.a2ui.json

@@ -75,6 +75,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "container",
+    "composes": [],
     "events": {
       "drag-end": {
         "description": "Fired when a drag completes."

package/components/card/card.d.ts

@@ -5,12 +5,15 @@
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
  * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
- * run `npm run components`, then `npm run codegen:dts` to regenerate;
- * or hand-author this file fully if rich event types are needed.
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
  */
 
 import { UIElement } from '../../core/element.js';
 
+export type CardDragEndEvent = CustomEvent<unknown>;
+
 export class UICard extends UIElement {
   /** Enables drag handle + cursor:grab. Wires the draggable trait; dispatches drag-end. */
   draggable: boolean;
@@ -24,4 +27,11 @@ 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/chart/chart.a2ui.json

@@ -133,6 +133,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "agent",
+    "composes": [],
     "events": {
       "chart-hover": {
         "description": "Fires when the pointer enters a datum (bar / dot / slice). Detail includes {label, value, pct, series, slot, pointerX, pointerY}. Only re-fires when the hovered datum changes — moving inside the same datum is quiet."
@@ -142,6 +143,9 @@
       },
       "chart-select": {
         "description": "Fires on click of a datum with the same detail shape as chart-hover."
+      },
+      "legend-update": {
+        "description": "Fires when the chart's internal legend payload regenerates (datum\nlabel/value re-aggregate). Signal-only — no detail payload.\nUsed by chart-legend-ui to mirror state when wired via [for].\n"
       }
     },
     "examples": [

package/components/chart/chart.d.ts

@@ -5,12 +5,18 @@
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
  * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
- * run `npm run components`, then `npm run codegen:dts` to regenerate;
- * or hand-author this file fully if rich event types are needed.
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
  */
 
 import { UIElement } from '../../core/element.js';
 
+export type ChartHoverEvent = CustomEvent<unknown>;
+export type ChartLeaveEvent = CustomEvent<unknown>;
+export type ChartSelectEvent = CustomEvent<unknown>;
+export type ChartLegendUpdateEvent = CustomEvent<unknown>;
+
 export class UIChart extends UIElement {
   /** Chart type. All 18 enum values have dedicated render paths in chart.js. */
   type: 'bar' | 'line' | 'pie' | 'donut' | 'radar' | 'sparkline' | 'segments' | 'area' | 'scatter' | 'radial-bar' | 'gauge' | 'stacked-bar' | 'grouped-bar' | 'multi-line' | 'funnel' | 'treemap' | 'sankey' | 'composed';
@@ -38,4 +44,14 @@ export class UIChart extends UIElement {
   x: string;
   /** Y-axis key(s), comma-separated for multi-series */
   y: string;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIChart, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'chart-hover', listener: (ev: ChartHoverEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'chart-leave', listener: (ev: ChartLeaveEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'chart-select', listener: (ev: ChartSelectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'legend-update', listener: (ev: ChartLegendUpdateEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/chart/chart.yaml

@@ -132,6 +132,11 @@ events:
     description: Fires when the pointer leaves the plot area or a previously-hovered datum with no new one entering.
   chart-select:
     description: Fires on click of a datum with the same detail shape as chart-hover.
+  legend-update:
+    description: |
+      Fires when the chart's internal legend payload regenerates (datum
+      label/value re-aggregate). Signal-only — no detail payload.
+      Used by chart-legend-ui to mirror state when wired via [for].
 slots:
   canvas:
     description: Chart rendering area

package/components/chart-legend/chart-legend.a2ui.json

@@ -70,9 +70,27 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "agent",
+    "composes": [
+      "badge-ui",
+      "swatch-ui"
+    ],
     "events": {
       "toggle": {
-        "description": "Fires on row click (non-static). Detail: {key, active, mode}. `active` is the new state (true=visible). Consumers (or chart-ui via [for]) wire this to series visibility."
+        "description": "Fires on row click (non-static). Detail: {key, active, mode}. `active` is the new state (true=visible). Consumers (or chart-ui via [for]) wire this to series visibility.",
+        "detail": {
+          "active": {
+            "description": "New visibility state (true = visible).",
+            "type": "boolean"
+          },
+          "key": {
+            "description": "Series key identifier.",
+            "type": "string"
+          },
+          "mode": {
+            "description": "Visibility mode (default \"hide\").",
+            "type": "string"
+          }
+        }
       }
     },
     "examples": [

package/components/chart-legend/chart-legend.d.ts

@@ -5,12 +5,24 @@
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
  * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
- * run `npm run components`, then `npm run codegen:dts` to regenerate;
- * or hand-author this file fully if rich event types are needed.
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
  */
 
 import { UIElement } from '../../core/element.js';
 
+export interface ChartLegendToggleEventDetail {
+  /** New visibility state (true = visible). */
+  active: boolean;
+  /** Series key identifier. */
+  key: string;
+  /** Visibility mode (default "hide"). */
+  mode: string;
+}
+
+export type ChartLegendToggleEvent = CustomEvent<ChartLegendToggleEventDetail>;
+
 export class UIChartLegend extends UIElement {
   /** JSON array of {key, label, slot?, pct?} legend items. Takes precedence over [for] when both are provided. */
   items: string;
@@ -24,4 +36,11 @@ export class UIChartLegend extends UIElement {
   shape: 'dot' | 'square' | 'line' | 'dashed';
   /** When set, rows are non-interactive <span>s (no click, no toggle). */
   static: boolean;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIChartLegend, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'toggle', listener: (ev: ChartLegendToggleEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/chart-legend/chart-legend.yaml

@@ -9,6 +9,11 @@ description: >-
   badge-ui chips (swatch + label) that are keyboard-focusable and
   click-toggleable. Composes with chart-ui via [for] id-ref (auto-mirror) or
   via explicit [items] JSON.
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - badge-ui
+  - swatch-ui
 props:
   for:
     description: id-ref of a chart-ui / heatmap-ui to mirror series from.
@@ -63,6 +68,16 @@ events:
       Fires on row click (non-static). Detail: {key, active, mode}. `active` is
       the new state (true=visible). Consumers (or chart-ui via [for]) wire
       this to series visibility.
+    detail:
+      key:
+        type: string
+        description: Series key identifier.
+      active:
+        type: boolean
+        description: New visibility state (true = visible).
+      mode:
+        type: string
+        description: Visibility mode (default "hide").
 slots:
   default:
     description: >-

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

@@ -29,9 +29,20 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "agent",
+    "composes": [],
     "events": {
       "submit": {
-        "description": "Fired when the user submits a chat message via Enter or send button. Detail: { text, model }."
+        "description": "Fired when the user submits a chat message via Enter or send button. Detail: { text, model }.",
+        "detail": {
+          "model": {
+            "description": "Selected model identifier.",
+            "type": "string"
+          },
+          "text": {
+            "description": "Submitted message text.",
+            "type": "string"
+          }
+        }
       }
     },
     "examples": [

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

@@ -5,13 +5,30 @@
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
  * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
- * run `npm run components`, then `npm run codegen:dts` to regenerate;
- * or hand-author this file fully if rich event types are needed.
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
  */
 
 import { UIElement } from '../../core/element.js';
 
+export interface ChatThreadSubmitEventDetail {
+  /** Selected model identifier. */
+  model: string;
+  /** Submitted message text. */
+  text: string;
+}
+
+export type ChatThreadSubmitEvent = CustomEvent<ChatThreadSubmitEventDetail>;
+
 export class UIChatThread extends UIElement {
   /** Component property: streaming. */
   streaming: boolean;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIChatThread, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'submit', listener: (ev: ChatThreadSubmitEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

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

@@ -15,6 +15,13 @@ props:
 events:
   submit:
     description: "Fired when the user submits a chat message via Enter or send button. Detail: { text, model }."
+    detail:
+      text:
+        type: string
+        description: Submitted message text.
+      model:
+        type: string
+        description: Selected model identifier.
 slots:
   default:
     description: "Default slot — primary child content."

package/components/check/check.a2ui.json

@@ -71,6 +71,7 @@
       }
     ],
     "category": "layout",
+    "composes": [],
     "events": {
       "change": {
         "description": "Fired when checked state changes"

package/components/code/code.a2ui.json

@@ -83,21 +83,51 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "display",
+    "composes": [],
     "events": {
       "change": {
-        "description": "Fired on blur if the buffer changed since focus (editable mode); detail.value is the final buffer"
-      },
-      "copy": {
-        "description": "Fired when text is copied to clipboard"
+        "description": "Fired on blur if the buffer changed since focus (editable mode); detail.value is the final buffer.",
+        "detail": {
+          "value": {
+            "description": "Editor contents at blur.",
+            "type": "string"
+          }
+        }
       },
       "input": {
-        "description": "Fired on every doc change (editable mode); detail.value is the current buffer"
+        "description": "Fired on every doc change (editable mode); detail.value is the current buffer.",
+        "detail": {
+          "value": {
+            "description": "Current editor contents.",
+            "type": "string"
+          }
+        }
       },
       "language-load-error": {
-        "description": "Fired when the language pack or CodeMirror bundle fails to load; detail.phase is 'core' or 'language'"
+        "description": "Fired when CodeMirror's dynamic language-mode or core bundle fails to load.\ndetail.phase is \"core\" (fatal — component falls back to static pre+code) or\n\"language\" (recoverable — editor mounts in plain-text mode).\n",
+        "detail": {
+          "error": {
+            "description": "The underlying load failure.",
+            "type": "object"
+          },
+          "language": {
+            "description": "Present when phase is \"language\" — the language slug that failed.",
+            "type": "string"
+          },
+          "phase": {
+            "description": "Either \"core\" or \"language\".",
+            "type": "string"
+          }
+        }
       },
       "save": {
-        "description": "Fired on Mod+S keybind (editable mode); detail.value is the current buffer. Cancelable."
+        "description": "Fired on Mod+S keybind (editable mode); detail.value is the current buffer. Cancelable — call event.preventDefault() to suppress the host page's save handling.",
+        "detail": {
+          "value": {
+            "description": "Editor contents at the moment of save.",
+            "type": "string"
+          }
+        }
       }
     },
     "examples": [

package/components/code/code.d.ts

@@ -12,6 +12,34 @@ export interface CodeChangeEventDetail {
 export type CodeChangeEvent = CustomEvent<CodeChangeEventDetail>;
 export type CodeInputEvent = CustomEvent<CodeChangeEventDetail>;
 
+/**
+ * Detail payload for the `save` event — fired when the user invokes the
+ * CodeMirror save keybinding (Cmd/Ctrl+S). The event is `cancelable: true`;
+ * call `event.preventDefault()` to suppress the host page's save handling.
+ */
+export interface CodeSaveEventDetail {
+  /** Current editor contents at the moment of save. */
+  value: string;
+}
+export type CodeSaveEvent = CustomEvent<CodeSaveEventDetail>;
+
+/**
+ * Detail payload for the `language-load-error` event — fired when
+ * CodeMirror's dynamic language-mode import fails. `phase: "core"`
+ * indicates the CodeMirror core bundle itself failed (rare, fatal —
+ * the component falls back to a static `<pre><code>`). `phase: "language"`
+ * indicates the requested language extension failed (recoverable —
+ * editor still mounts in plain-text mode).
+ */
+export interface CodeLanguageLoadErrorEventDetail {
+  phase: 'core' | 'language';
+  /** Present when `phase === 'language'`; the language slug that failed. */
+  language?: string;
+  /** The underlying load failure. */
+  error: unknown;
+}
+export type CodeLanguageLoadErrorEvent = CustomEvent<CodeLanguageLoadErrorEventDetail>;
+
 export class UICode extends UIFormElement {
   /** CodeMirror language slug — `javascript` / `typescript` / `html` / `css` / `json` / `markdown` / `python` etc. */
   language: string;
@@ -36,4 +64,6 @@ export class UICode extends UIFormElement {
   ): void;
   addEventListener(type: 'change', listener: (ev: CodeChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'input', listener: (ev: CodeInputEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'save', listener: (ev: CodeSaveEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'language-load-error', listener: (ev: CodeLanguageLoadErrorEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/code/code.yaml

@@ -58,16 +58,39 @@ props:
     type: boolean
     default: false
 events:
-  copy:
-    description: Fired when text is copied to clipboard
   input:
-    description: Fired on every doc change (editable mode); detail.value is the current buffer
+    description: Fired on every doc change (editable mode); detail.value is the current buffer.
+    detail:
+      value:
+        type: string
+        description: Current editor contents.
   change:
-    description: Fired on blur if the buffer changed since focus (editable mode); detail.value is the final buffer
+    description: Fired on blur if the buffer changed since focus (editable mode); detail.value is the final buffer.
+    detail:
+      value:
+        type: string
+        description: Editor contents at blur.
   save:
-    description: Fired on Mod+S keybind (editable mode); detail.value is the current buffer. Cancelable.
+    description: Fired on Mod+S keybind (editable mode); detail.value is the current buffer. Cancelable — call event.preventDefault() to suppress the host page's save handling.
+    detail:
+      value:
+        type: string
+        description: Editor contents at the moment of save.
   language-load-error:
-    description: Fired when the language pack or CodeMirror bundle fails to load; detail.phase is 'core' or 'language'
+    description: |
+      Fired when CodeMirror's dynamic language-mode or core bundle fails to load.
+      detail.phase is "core" (fatal — component falls back to static pre+code) or
+      "language" (recoverable — editor mounts in plain-text mode).
+    detail:
+      phase:
+        type: string
+        description: Either "core" or "language".
+      language:
+        type: string
+        description: Present when phase is "language" — the language slug that failed.
+      error:
+        type: object
+        description: The underlying load failure.
 slots:
   default:
     description: Raw text fallback when the text property is not set

package/components/col/col.a2ui.json

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

package/components/col/col.d.ts

@@ -5,8 +5,9 @@
  *
  * Type declarations generated by scripts/build/dts-codegen.mjs from
  * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
- * run `npm run components`, then `npm run codegen:dts` to regenerate;
- * or hand-author this file fully if rich event types are needed.
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
  */
 
 import { UIElement } from '../../core/element.js';

package/components/color-picker/class.js

@@ -128,9 +128,27 @@ export class UIColorPicker extends UIFormElement {
     value:    { type: String,  default: '#3b82f6', reflect: true },
     format:   { type: String,  default: 'hex',     reflect: true },
     disabled: { type: Boolean, default: false,      reflect: true },
+    /**
+     * v0.4.9 §99h — generation-constraint props (FEEDBACK-02 #7).
+     * When set, the picker clamps OKLCH channels to the consumer's
+     * declared bounds before committing. Out-of-bound mutations
+     * round-trip to the nearest in-bound equivalent + fire a
+     * `constraint-clamp` event with `{ axis, requested, clamped, reason }`
+     * so the consumer can surface UX feedback (toast, validity warning,
+     * scope-drift indicator). Default values disable the constraint.
+     */
+    maxChroma:    { type: Number, default: Infinity, reflect: true, attribute: 'max-chroma' },
+    maxL:         { type: Number, default: 1,        reflect: true, attribute: 'max-l' },
+    minL:         { type: Number, default: 0,        reflect: true, attribute: 'min-l' },
+    /** Maximum allowed hue deviation in degrees from the picker's `baseHue`. NaN = no constraint. */
+    hueDriftMax:  { type: Number, default: NaN, reflect: true, attribute: 'hue-drift-max' },
+    /** Reference hue (degrees) for [hue-drift-max]. NaN = use the value parsed at first commit. */
+    baseHue:      { type: Number, default: NaN, reflect: true, attribute: 'base-hue' },
   };
 
   #L = 0.6; #C = 0.15; #H = 230;
+  /** Cached reference hue for hue-drift constraint. Set on first commit if [base-hue] isn't authored. */
+  #resolvedBaseHue = NaN;
   #bound = false;
   #dragging = null; // 'area' | 'hue' | null
   #internalUpdate = false;
@@ -400,9 +418,45 @@ export class UIColorPicker extends UIFormElement {
     }
   }
 
-  // ── Commit: update value + fire events ──
+  // ── Commit: clamp to consumer constraints + gamut-map + update value + fire events ──
 
   #commit(eventType) {
+    // Apply consumer-declared constraints BEFORE gamut mapping. Each constraint
+    // axis records a `constraint-clamp` event-payload entry when it actually
+    // moved a value; we dispatch one event per commit so the consumer can
+    // surface a single UX response (toast / validity warning / etc.).
+    const clamps = [];
+    if (this.#L > this.maxL) {
+      clamps.push({ axis: 'l', requested: this.#L, clamped: this.maxL, reason: 'max-l' });
+      this.#L = this.maxL;
+    }
+    if (this.#L < this.minL) {
+      clamps.push({ axis: 'l', requested: this.#L, clamped: this.minL, reason: 'min-l' });
+      this.#L = this.minL;
+    }
+    if (this.#C > this.maxChroma) {
+      clamps.push({ axis: 'c', requested: this.#C, clamped: this.maxChroma, reason: 'max-chroma' });
+      this.#C = this.maxChroma;
+    }
+    if (Number.isFinite(this.hueDriftMax)) {
+      const base = Number.isFinite(this.baseHue)
+        ? this.baseHue
+        : (Number.isFinite(this.#resolvedBaseHue) ? this.#resolvedBaseHue : this.#H);
+      if (!Number.isFinite(this.#resolvedBaseHue)) this.#resolvedBaseHue = base;
+      // Hue is circular — find the signed shortest-path drift in [-180, 180].
+      let drift = ((this.#H - base + 540) % 360) - 180;
+      const limit = this.hueDriftMax;
+      if (drift > limit) {
+        const requestedH = this.#H;
+        this.#H = (base + limit + 360) % 360;
+        clamps.push({ axis: 'h', requested: requestedH, clamped: this.#H, reason: 'hue-drift-max' });
+      } else if (drift < -limit) {
+        const requestedH = this.#H;
+        this.#H = (base - limit + 360) % 360;
+        clamps.push({ axis: 'h', requested: requestedH, clamped: this.#H, reason: 'hue-drift-max' });
+      }
+    }
+
     const clampedC = gamutMapChroma(this.#L, this.#C, this.#H);
     const hexVal = oklchToHex(this.#L, clampedC, this.#H);
     const oklchStr = this.#oklchStr();
@@ -411,6 +465,10 @@ export class UIColorPicker extends UIFormElement {
     this.value = this.format === 'oklch' ? oklchStr : hexVal;
     this.syncValue();
 
+    if (clamps.length) {
+      this.dispatchEvent(new CustomEvent('constraint-clamp', { bubbles: true, detail: { clamps } }));
+    }
+
     const detail = { value: this.value, l: this.#L, c: this.#C, h: this.#H, hex: hexVal, oklch: oklchStr };
     this.dispatchEvent(new CustomEvent(eventType, { bubbles: true, detail }));
   }

package/components/color-picker/color-picker.a2ui.json

@@ -13,6 +13,11 @@
     }
   ],
   "properties": {
+    "baseHue": {
+      "description": "Reference hue (degrees) for the [hue-drift-max] constraint. Default\nNaN — falls back to the picker's hue at first commit so the consumer\ncan pre-seed the picker and constrain drift from that initial value.\n",
+      "type": "number",
+      "default": "NaN"
+    },
     "component": {
       "const": "ColorPicker"
     },
@@ -30,6 +35,26 @@
       ],
       "default": "hex"
     },
+    "hueDriftMax": {
+      "description": "Generation constraint — maximum allowed signed-shortest-path hue\ndeviation (degrees) from [base-hue] (or the first-committed hue\nif [base-hue] is unset). Default NaN (no constraint). Wrap-aware\nso a drift of 350 degrees resolves as -10.\n",
+      "type": "number",
+      "default": "NaN"
+    },
+    "maxChroma": {
+      "description": "Generation constraint (v0.4.9 §99h, FEEDBACK-02 #7) — clamp the\nOKLCH chroma channel to at most this value before commit. Out-of-\nbound mutations round-trip to the nearest in-bound equivalent +\nfire `constraint-clamp`. Default Infinity (no constraint).\n",
+      "type": "number",
+      "default": "Infinity"
+    },
+    "maxL": {
+      "description": "Generation constraint — clamp OKLCH lightness to at most this value (0..1). Default 1 (no constraint).",
+      "type": "number",
+      "default": 1
+    },
+    "minL": {
+      "description": "Generation constraint — clamp OKLCH lightness to at least this value (0..1). Default 0 (no constraint).",
+      "type": "number",
+      "default": 0
+    },
     "name": {
       "description": "Form field name",
       "type": "string",
@@ -48,10 +73,22 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "input",
+    "composes": [
+      "slider-ui"
+    ],
     "events": {
       "change": {
         "description": "Fired on every color change"
       },
+      "constraint-clamp": {
+        "description": "Fired immediately before `change` / `input` when one or more\nconsumer-declared constraints (max-chroma / max-l / min-l /\nhue-drift-max) clamped a channel away from the user-requested\nvalue. detail.clamps is an array of axis-specific clamp records.\n",
+        "detail": {
+          "clamps": {
+            "description": "Array of `{ axis, requested, clamped, reason }` objects. axis is\none of \"l\" / \"c\" / \"h\". reason names the triggering constraint\nprop. Empty arrays are never emitted.\n",
+            "type": "array"
+          }
+        }
+      },
       "input": {
         "description": "Fired during continuous interaction (drag)"
       }