@adia-ai/web-components 0.4.8 → 0.5.0

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

@@ -12,7 +12,12 @@
 
 import { UIElement } from '../../core/element.js';
 
-export type AgentTraceTraceToggleEvent = CustomEvent<unknown>;
+export interface AgentTraceTraceToggleEventDetail {
+  /** Whether the trace is now collapsed. */
+  collapsed: boolean;
+}
+
+export type AgentTraceTraceToggleEvent = CustomEvent<AgentTraceTraceToggleEventDetail>;
 
 export class UIAgentTrace extends UIElement {
   /** Hide the trace body. Default-visible disclosure (matches the agent-* family — agent-reasoning, agent-artifact). Set to opt out. */

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

@@ -20,6 +20,10 @@ props:
 events:
   trace-toggle:
     description: "Fired on trace-toggle."
+    detail:
+      collapsed:
+        type: boolean
+        description: Whether the trace is now collapsed.
 slots:
   default:
     description: "Default slot — primary child content."

package/components/canvas/canvas.yaml

@@ -7,14 +7,16 @@ 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.
-# NOTE: <canvas-ui> mounts <a2ui-root> (web-modules/runtime) and optionally
-# <theme-ui> (web-modules/theme). These are CROSS-PACKAGE compositions that
-# the current composes: field can't express as same-package siblings. Cross-
-# package composition tracking is queued for v0.4.9; for now consumers
-# loading <canvas-ui> with a2ui-root rendering must import:
-#   @adia-ai/web-modules/runtime/a2ui-root
-#   @adia-ai/web-modules/theme/theme  (only if [theme-wrapper] is used)
+# <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/chart/chart.a2ui.json

@@ -143,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

@@ -15,6 +15,7 @@ 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. */
@@ -52,4 +53,5 @@ export class UIChart extends UIElement {
   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

@@ -76,7 +76,21 @@
     ],
     "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

@@ -12,7 +12,16 @@
 
 import { UIElement } from '../../core/element.js';
 
-export type ChartLegendToggleEvent = CustomEvent<unknown>;
+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. */

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

@@ -68,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

@@ -32,7 +32,17 @@
     "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

@@ -12,7 +12,14 @@
 
 import { UIElement } from '../../core/element.js';
 
-export type ChatThreadSubmitEvent = CustomEvent<unknown>;
+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. */

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

@@ -86,19 +86,48 @@
     "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/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",
@@ -55,6 +80,15 @@
       "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)"
       }

package/components/color-picker/color-picker.d.ts

@@ -1,30 +1,92 @@
 /**
- * `<color-picker-ui>` — Color picker with hex / rgb / hsl / oklch formats.
+ * `<color-picker-ui>` — OKLCH-native color picker with 2D area + H/C/L sliders.
+ *
+ * Form-associated (extends UIFormElement). The `[format]` attribute controls
+ * whether `value` is read/written as a `#rrggbb` hex string or an `oklch(L C H)`
+ * string, but the event detail always carries BOTH forms plus the parsed
+ * OKLCH channel scalars — consumers don't need to parse the string.
  *
  * @see https://ui-kit.exe.xyz/site/components/color-picker
  */
 
 import { UIFormElement } from '../../core/form.js';
 
-export type ColorFormat = 'hex' | 'rgb' | 'hsl' | 'oklch';
+/**
+ * Output format selected by the `[format]` attribute. Drives the shape of
+ * `value` (and the matching `detail.value` field). Both `hex` and `oklch`
+ * forms are always present on the event detail regardless of `[format]`.
+ */
+export type ColorFormat = 'hex' | 'oklch';
 
+/**
+ * Detail payload for both `change` (commit) and `input` (continuous drag)
+ * events. Carries parsed channel scalars + both string forms — `value`
+ * mirrors the picker's current `[format]`, while `hex` and `oklch` are
+ * always populated parallel views.
+ */
 export interface ColorPickerChangeEventDetail {
+  /** Format-respecting string. Equals `hex` when `[format="hex"]`; equals `oklch` when `[format="oklch"]`. */
   value: string;
-  format: ColorFormat;
+  /** OKLCH lightness (0–1). */
+  l: number;
+  /** OKLCH chroma (0–~0.4). */
+  c: number;
+  /** OKLCH hue (0–360, degrees). */
+  h: number;
+  /** Hex string (`#rrggbb`). Gamut-mapped to sRGB. */
+  hex: string;
+  /** OKLCH string (`oklch(L C H)`, fixed precision). */
+  oklch: string;
 }
 export type ColorPickerChangeEvent = CustomEvent<ColorPickerChangeEventDetail>;
 export type ColorPickerInputEvent = CustomEvent<ColorPickerChangeEventDetail>;
 
-export interface ColorPickerFormatChangeEventDetail {
-  format: ColorFormat;
+/**
+ * Axis-specific clamp record. Fires when a consumer-declared constraint
+ * (max-chroma / max-l / min-l / hue-drift-max) clamped a user-requested
+ * channel value to its in-bound equivalent.
+ */
+export interface ColorPickerClampRecord {
+  /** OKLCH axis that was clamped. */
+  axis: 'l' | 'c' | 'h';
+  /** Channel value the user requested before the clamp. */
+  requested: number;
+  /** Channel value the picker actually committed after the clamp. */
+  clamped: number;
+  /** Constraint prop that triggered the clamp. */
+  reason: 'max-l' | 'min-l' | 'max-chroma' | 'hue-drift-max';
+}
+
+/**
+ * Detail payload for the `constraint-clamp` event — fired immediately
+ * before the corresponding `change` / `input` when one or more axes
+ * were clamped to fit the consumer's declared constraints. `clamps`
+ * is never empty.
+ */
+export interface ColorPickerConstraintClampEventDetail {
+  clamps: ColorPickerClampRecord[];
 }
-export type ColorPickerFormatChangeEvent = CustomEvent<ColorPickerFormatChangeEventDetail>;
+export type ColorPickerConstraintClampEvent = CustomEvent<ColorPickerConstraintClampEventDetail>;
 
 export class UIColorPicker extends UIFormElement {
+  /** Form field name. */
+  name: string;
+  /** Disables all interaction. */
+  disabled: boolean;
   /** Current color as a string in the active `format`. */
   value: string;
-  /** Output format. */
+  /** Output format — drives the shape of `value`. Detail always carries both `hex` and `oklch`. */
   format: ColorFormat;
+  /** Clamp the OKLCH chroma channel to at most this value. `Infinity` = unconstrained. */
+  maxChroma: number;
+  /** Clamp the OKLCH lightness channel to at most this value (0..1). `1` = unconstrained. */
+  maxL: number;
+  /** Clamp the OKLCH lightness channel to at least this value (0..1). `0` = unconstrained. */
+  minL: number;
+  /** Maximum allowed signed-shortest-path hue drift in degrees from `baseHue`. `NaN` = unconstrained. */
+  hueDriftMax: number;
+  /** Reference hue (degrees) for the `hueDriftMax` constraint. `NaN` = use the picker's hue at first commit. */
+  baseHue: number;
 
   addEventListener<K extends keyof HTMLElementEventMap>(
     type: K,
@@ -33,5 +95,5 @@ export class UIColorPicker extends UIFormElement {
   ): void;
   addEventListener(type: 'change', listener: (ev: ColorPickerChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'input', listener: (ev: ColorPickerInputEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
-  addEventListener(type: 'format-change', listener: (ev: ColorPickerFormatChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'constraint-clamp', listener: (ev: ColorPickerConstraintClampEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

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

@@ -32,11 +32,60 @@ props:
     description: Current color as hex string
     type: string
     default: "#3b82f6"
+  maxChroma:
+    description: |
+      Generation constraint (v0.4.9 §99h, FEEDBACK-02 #7) — clamp the
+      OKLCH chroma channel to at most this value before commit. Out-of-
+      bound mutations round-trip to the nearest in-bound equivalent +
+      fire `constraint-clamp`. Default Infinity (no constraint).
+    type: number
+    default: Infinity
+    reflect: true
+  maxL:
+    description: Generation constraint — clamp OKLCH lightness to at most this value (0..1). Default 1 (no constraint).
+    type: number
+    default: 1
+    reflect: true
+  minL:
+    description: Generation constraint — clamp OKLCH lightness to at least this value (0..1). Default 0 (no constraint).
+    type: number
+    default: 0
+    reflect: true
+  hueDriftMax:
+    description: |
+      Generation constraint — maximum allowed signed-shortest-path hue
+      deviation (degrees) from [base-hue] (or the first-committed hue
+      if [base-hue] is unset). Default NaN (no constraint). Wrap-aware
+      so a drift of 350 degrees resolves as -10.
+    type: number
+    default: NaN
+    reflect: true
+  baseHue:
+    description: |
+      Reference hue (degrees) for the [hue-drift-max] constraint. Default
+      NaN — falls back to the picker's hue at first commit so the consumer
+      can pre-seed the picker and constrain drift from that initial value.
+    type: number
+    default: NaN
+    reflect: true
 events:
   change:
     description: Fired on every color change
   input:
     description: Fired during continuous interaction (drag)
+  constraint-clamp:
+    description: |
+      Fired immediately before `change` / `input` when one or more
+      consumer-declared constraints (max-chroma / max-l / min-l /
+      hue-drift-max) clamped a channel away from the user-requested
+      value. detail.clamps is an array of axis-specific clamp records.
+    detail:
+      clamps:
+        type: array
+        description: |
+          Array of `{ axis, requested, clamped, reason }` objects. axis is
+          one of "l" / "c" / "h". reason names the triggering constraint
+          prop. Empty arrays are never emitted.
 slots: {}
 states:
   - name: idle