@adia-ai/web-components 0.8.40 → 0.8.42

package/custom-elements.json

@@ -137,7 +137,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Child of <action-list-ui>. One actionable row — icon + label, forwards activation to the parent action-list.",
+          "description": "Child of <action-list-ui>. One actionable row — icon + label + optional description, forwards activation to the parent action-list. Row contract converges on <menu-item-ui>: icon/text/description/value/variant/disabled props and icon/text/subtitle/trailing slot overrides (#1363 C5). (`subtitle` is a deprecated alias for `description` — ADR-0063, gh#1571.)",
           "name": "UIActionItem",
           "tagName": "action-item-ui",
           "superclass": {
@@ -159,6 +159,20 @@
               },
               "description": "Action label."
             },
+            {
+              "name": "subtitle",
+              "type": {
+                "text": "string"
+              },
+              "description": "DEPRECATED (ADR-0063, gh#1571) — use `description` instead. Same type/default/rendered position; kept working as a dual-read compat shim (one-time console.warn when it's the name that resolves). Removed in 0.9.0. (The `subtitle` SLOT below is a separate surface, deliberately left unrenamed in this pass — see its own description.)"
+            },
+            {
+              "name": "description",
+              "type": {
+                "text": "string"
+              },
+              "description": "Optional secondary description line rendered under the label. Canonical spelling (ADR-0063, gh#1571) replacing `subtitle` — converges action-item onto the same spelling <menu-item-ui> adopted under gh#1563."
+            },
             {
               "name": "value",
               "type": {
@@ -172,7 +186,7 @@
                 "text": "string"
               },
               "default": "default",
-              "description": "Visual variant (default | accent | danger)."
+              "description": "Visual variant (default | danger)."
             },
             {
               "name": "disabled",
@@ -187,6 +201,18 @@
             {
               "name": "icon",
               "description": "Override the [icon] glyph with a custom slotted element (custom icon-ui, image, avatar). Mutually exclusive with the [icon] attribute — slot child wins."
+            },
+            {
+              "name": "text",
+              "description": "Custom label content; falls through to [text] prop if not slotted."
+            },
+            {
+              "name": "subtitle",
+              "description": "Custom secondary-line content override; falls through to the [description] prop (or its deprecated [subtitle] alias — ADR-0063, gh#1571) if not slotted. The slot's own name is unchanged by that rename — this is a distinct, deliberately-unrenamed surface."
+            },
+            {
+              "name": "trailing",
+              "description": "Trailing element pinned to the far edge (shortcut hint, badge, caret). Supersedes the unnamed default slot this row previously used for trailing content — see MIGRATION GUIDE."
             }
           ]
         },
@@ -449,12 +475,6 @@
               "description": "Save button text; empty hides it."
             }
           ],
-          "slots": [
-            {
-              "name": "default",
-              "description": "Default slot — primary child content."
-            }
-          ],
           "events": [
             {
               "name": "feedback-rate",
@@ -603,12 +623,6 @@
               "description": "Drives the status icon — idle, active (spinner), done (check), error (warning)."
             }
           ],
-          "slots": [
-            {
-              "name": "default",
-              "description": "Default slot — NOT a step-authoring surface: the component rebuilds its body from the addStep()/addThought() pipeline and does not consume authored children (gh#938)."
-            }
-          ],
           "events": [
             {
               "name": "reasoning-finish",
@@ -673,7 +687,7 @@
                 "text": "string"
               },
               "default": "sm",
-              "description": "sm | md"
+              "description": "sm | md — forwarded to each chip's <button-ui size>."
             },
             {
               "name": "variant",
@@ -681,7 +695,7 @@
                 "text": "string"
               },
               "default": "outline",
-              "description": "outline | ghost | subtle"
+              "description": "outline | ghost — forwarded to each chip's <button-ui variant>."
             }
           ],
           "slots": [
@@ -742,12 +756,6 @@
               "description": "Hide the trace body. Default-visible disclosure (matches the agent-* family — agent-reasoning, agent-artifact). Set to opt out."
             }
           ],
-          "slots": [
-            {
-              "name": "default",
-              "description": "Default slot — primary child content."
-            }
-          ],
           "events": [
             {
               "name": "trace-toggle",
@@ -1092,20 +1100,6 @@
               },
               "description": "Image source URL. Falls back to initials on error."
             }
-          ],
-          "slots": [
-            {
-              "name": "icon",
-              "description": "Phosphor icon rendered inside the avatar circle (system-event avatars)"
-            },
-            {
-              "name": "img",
-              "description": "Avatar image element"
-            },
-            {
-              "name": "initials",
-              "description": "Initials text span"
-            }
           ]
         }
       ],
@@ -1455,10 +1449,6 @@
             }
           ],
           "slots": [
-            {
-              "name": "leading",
-              "description": "Icon container (start), sized to --content-height"
-            },
             {
               "name": "trailing",
               "description": "Icon container (end), sized to --content-height"
@@ -1598,7 +1588,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Date picker with trigger button and popover calendar grid. Form-associated input emitting ISO date string via change events; supports min/max and disabled-date masks. Use for single-date input in forms; for date ranges compose two pickers or use a dedicated range component.",
+          "description": "Date (and, per `[precision]`, date+time) picker with trigger button and popover panel. Form-associated input emitting an ISO date (or, when `precision` is `minute`/`second`, ISO datetime) string via change events; supports min/max and disabled-date masks. Use for single-date or single-datetime input in forms; for date ranges use <date-range-picker-ui> instead of composing two calendar-picker instances. gh#1372 (#1363 C3c) folded <datetime-picker-ui>'s surface into this widened `precision` axis — see the deprecated <datetime-picker-ui> alias.",
           "name": "UICalendarPicker",
           "tagName": "calendar-picker-ui",
           "superclass": {
@@ -1629,34 +1619,65 @@
               "default": "false",
               "description": "Disables interaction"
             },
+            {
+              "name": "readonly",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Blocks edits; the trigger stays keyboard-focusable for screen-reader inspection but the popover does not open."
+            },
             {
               "name": "format",
               "type": {
                 "text": "string"
               },
               "default": "short",
-              "description": "Display format for the selected date"
+              "description": "Display format for the trigger text. `short`, e.g. `Jan 1, 2026` (+ ` 14:30` when `precision` is minute/second); `long`, e.g. `January 1, 2026`; `iso`, the raw ISO string."
             },
             {
-              "name": "label",
+              "name": "max",
               "type": {
                 "text": "string"
               },
-              "description": "Label text displayed above the trigger"
+              "description": "Maximum selectable date (ISO `YYYY-MM-DD`), or datetime (ISO `YYYY-MM-DDTHH:mm[:ss]`) when `precision` is minute/second."
             },
             {
-              "name": "max",
+              "name": "min",
               "type": {
                 "text": "string"
               },
-              "description": "Maximum selectable date in ISO format (YYYY-MM-DD)"
+              "description": "Minimum selectable date (ISO `YYYY-MM-DD`), or datetime (ISO `YYYY-MM-DDTHH:mm[:ss]`) when `precision` is minute/second."
             },
             {
-              "name": "min",
+              "name": "precision",
+              "type": {
+                "text": "string"
+              },
+              "default": "date",
+              "description": "Mode axis (gh#1372,"
+            },
+            {
+              "name": "step",
+              "type": {
+                "text": "number"
+              },
+              "default": "60",
+              "description": "Per-Arrow-keypress increment in seconds for the time pane. Active only when `precision` is minute/second. 60 = minute precision (default), 900 = 15-minute, 1 = second precision."
+            },
+            {
+              "name": "hour-cycle",
+              "type": {
+                "text": "string"
+              },
+              "description": "Hour cycle for the time pane. Active only when `precision` is minute/second. Empty (default) derives from the document locale. `h12` forces a 12-hour cycle with an AM/PM (meridiem) segment; `h23` forces 24-hour cycle."
+            },
+            {
+              "name": "locale",
               "type": {
                 "text": "string"
               },
-              "description": "Minimum selectable date in ISO format (YYYY-MM-DD)"
+              "description": "BCP-47 locale tag used to derive hour-cycle when `hour-cycle` is empty. Active only when `precision` is minute/second. Falls back to `<html lang>` then to browser default."
             },
             {
               "name": "open",
@@ -1679,7 +1700,7 @@
               "type": {
                 "text": "string"
               },
-              "description": "Selected date (ISO string)"
+              "description": "Selected date (ISO string), or datetime (ISO `YYYY-MM-DDTHH:mm[:ss]`) when `precision` is minute/second."
             },
             {
               "name": "placement",
@@ -1692,16 +1713,16 @@
           ],
           "slots": [
             {
-              "name": "calendar",
-              "description": "Popover container for the month grid"
-            },
-            {
-              "name": "label",
-              "description": "Label element above the trigger"
+              "name": "popover",
+              "description": "Popover container for the calendar pane(s) (gh#1461; renamed from the yaml's prior `calendar` key, which matched no real slot=\"…\" attribute — render() stamps this element as slot=\"popover\")."
             },
             {
               "name": "trigger",
               "description": "Combobox button that opens the calendar popover"
+            },
+            {
+              "name": "footer",
+              "description": "Optional Apply/Cancel buttons for explicit-commit flows. Spans the pane(s) below the calendar (+ time, when `precision` is minute/second)."
             }
           ],
           "events": [
@@ -1710,7 +1731,35 @@
               "type": {
                 "text": "CustomEvent"
               },
-              "description": "Fired when a date is selected"
+              "description": "Fired when a value commits (date picked, or — when `precision` is minute/second — date picked + time edited, or Apply clicked in an explicit-commit footer)."
+            },
+            {
+              "name": "input",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "Fired during partial selection (date picked but time still pending, or vice versa — meaningful only when `precision` is minute/second)."
+            },
+            {
+              "name": "open",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "Popover opened (user clicked the trigger, pressed Enter/Space, or Apply/Cancel in a footer closed then reopened)."
+            },
+            {
+              "name": "close",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "Popover closed (without commit, or after commit)."
+            },
+            {
+              "name": "invalid",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "A constraint failed (out of range, or — when `precision` is minute/second — a parse error)."
             }
           ]
         }
@@ -1728,146 +1777,328 @@
     },
     {
       "kind": "javascript-module",
-      "path": "components/canvas/canvas.js",
+      "path": "components/calendar-picker/calendar-picker.test.js",
       "declarations": [
         {
           "kind": "class",
-          "description": "A2UI rendering surface — the canonical mount point that consumes a DocStore / A2UI document and renders the component tree from it. The runtime's <a2ui-root> typically wraps a canvas-ui internally for the preview pane in <editor-canvas>. Use for embedding live A2UI output inside a custom editor, playground, or preview surface; not for generic in-page canvases (use HTML <canvas> for drawing).",
-          "name": "UICanvas",
-          "tagName": "canvas-ui",
+          "description": "DEPRECATED (gh#1372, widened `precision` axis. `<datetime-picker-ui>` is now a thin `UICalendarPicker` subclass (see datetime-picker.class.js) rather than an independent implementation: `precision` defaults to `\"minute\"` (not `\"date\"`) and `placeholder` defaults to `\"Select date and time\"`; every other prop/event/token is inherited unchanged from <calendar-picker-ui>. Existing markup keeps working, but new markup should reach for `<calendar-picker-ui precision=\"minute\">` (or `precision=\"second\"`) directly. See <calendar-picker-ui> for the full contract.",
+          "name": "UIDatetimePicker",
+          "tagName": "datetime-picker-ui",
           "superclass": {
             "name": "UIElement",
             "module": "/core/element.js"
           },
           "attributes": [
             {
-              "name": "theme",
+              "name": "name",
               "type": {
                 "text": "string"
               },
-              "description": "Component property: theme."
-            }
-          ],
-          "slots": [
-            {
-              "name": "default",
-              "description": "Default slot — primary child content."
-            }
-          ],
-          "events": [
+              "description": "Form field name. The ISO 8601 datetime is submitted under this key when the picker is inside a `<form>`."
+            },
             {
-              "name": "canvas-interaction",
+              "name": "value",
               "type": {
-                "text": "CustomEvent"
+                "text": "string"
               },
-              "description": "Fired on canvas interactions (focus, blur, pointer events). Dispatched at canvas.js:50 + :167."
-            }
-          ]
-        }
-      ],
-      "exports": [
-        {
-          "kind": "custom-element-definition",
-          "name": "canvas-ui",
-          "declaration": {
-            "name": "UICanvas",
-            "module": "./components/canvas/canvas.js"
-          }
-        }
-      ]
-    },
-    {
-      "kind": "javascript-module",
-      "path": "components/card/card.js",
-      "declarations": [
-        {
-          "kind": "class",
-          "description": "Bordered container with header, body, and footer sections. The nested <header> activates a 3-column grid when",
-          "name": "UICard",
-          "tagName": "card-ui",
-          "superclass": {
-            "name": "UIElement",
-            "module": "/core/element.js"
-          },
-          "attributes": [
+              "description": "Current value as ISO 8601 datetime (\"YYYY-MM-DDTHH:mm\" or \"YYYY-MM-DDTHH:mm:ss\"). Empty when no value selected."
+            },
             {
-              "name": "padding",
+              "name": "min",
               "type": {
                 "text": "string"
               },
-              "default": "md",
-              "description": "Interior padding scale (overrides --card-padding). Accepts the named scale (none/xs/sm/md/lg/xl) or a numeric"
+              "description": "Earliest selectable ISO 8601 datetime (inclusive). Days before are disabled in the calendar pane; times before are rejected by the time pane on the same day."
             },
             {
-              "name": "draggable",
+              "name": "max",
               "type": {
-                "text": "boolean"
+                "text": "string"
               },
-              "default": "false",
-              "description": "Enables drag handle + cursor:grab. Wires the draggable trait; dispatches drag-end."
+              "description": "Latest selectable ISO 8601 datetime (inclusive). Days after are disabled in the calendar pane; times after are rejected by the time pane on the same day."
             },
             {
-              "name": "elevation",
+              "name": "step",
               "type": {
                 "text": "number"
               },
-              "default": "1",
-              "description": "Shadow depth 0-3"
+              "default": "60",
+              "description": "Per-Arrow-keypress increment in seconds for the time pane. 60 = minute precision (default), 900 = 15-minute, 1 = second precision."
             },
             {
-              "name": "raw",
+              "name": "precision",
               "type": {
-                "text": "boolean"
+                "text": "string"
               },
-              "default": "false",
-              "description": "Strips background, border, and shadow. Parent owns the surface. Content structure still applies."
+              "default": "minute",
+              "description": "Time-pane precision. `minute` (default HERE — `date` on the base `<calendar-picker-ui>`) emits `HH:mm`; `second` exposes the seconds segment and emits `HH:mm:ss`; `date` drops the time pane entirely (identical to the base class's own default)."
             },
             {
-              "name": "size",
+              "name": "hour-cycle",
               "type": {
                 "text": "string"
               },
-              "description": "Card scale. Controls inset, radius, gap, and font sizes. Default (empty) = md."
+              "description": "Hour cycle for the time pane. Empty (default) derives from the document locale. `h12` forces a 12-hour cycle with an AM/PM (meridiem) segment; `h23` forces 24-hour cycle."
             },
             {
-              "name": "variant",
+              "name": "disabled",
               "type": {
-                "text": "string"
+                "text": "boolean"
               },
-              "default": "default",
-              "description": "Visual style. `outlined` (alias `outline`) draws a border with no"
-            }
-          ],
-          "slots": [
+              "default": "false",
+              "description": "Block all interaction. Trigger remains rendered but does not open the popover."
+            },
             {
-              "name": "icon",
-              "description": "Leading icon for the card header — status, brand, or type marker. Placed in column 1 of the 3-column header grid when present; heading + description shift to column 2. Use `<icon-ui name=\"…\">`, `<avatar-ui>`, or any inline icon element as a DIRECT child of the `<header>` with slot=\"icon\" (not inside a wrapper — direct-child only, per the :has(> [slot=\"icon\"]) gate)."
+              "name": "readonly",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Block edits; allow keyboard navigation for screen-reader inspection."
             },
             {
-              "name": "heading",
-              "description": "Primary title — grid row 1 inside `<header>`, or the prominent metric value inside `<footer>` (trend-stat / KPI pattern). Also accepts bare `<h1>`–`<h6>` tags as direct children without slot=\"heading\". A slot=\"heading\" wrapper can contain inline badges or metadata alongside the title text."
+              "name": "required",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Required for validation when inside a `<form>`."
             },
             {
-              "name": "description",
-              "description": "Secondary metadata — grid row 2 beneath the heading inside `<header>`, or a period/caption line beneath a metric inside `<footer>` (e.g. \"Jan – Mar 2024\"). Also accepts bare `<p>` / `<small>` / body-variant `<text-ui>` as direct children without slot=\"description\". Triggers space-between layout in the footer when combined with slot=\"action\"."
+              "name": "open",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether the popover is currently open."
             },
             {
-              "name": "action",
-              "description": "Trailing control cluster inside `<header>` (icon-buttons, menu trigger, more-options) or the primary action cluster inside `<footer>` (e.g. Save, Confirm). Aligns to the flex-end edge in both contexts. Pair with slot=\"action-leading\" for dual-cluster footers."
+              "name": "placeholder",
+              "type": {
+                "text": "string"
+              },
+              "default": "Select date and time",
+              "description": "Text shown in the trigger when the value is empty. Defaults to \"Select date and time\" HERE (vs. \"Select date...\" on the base `<calendar-picker-ui>`)."
             },
             {
-              "name": "action-leading",
-              "description": "Leading control cluster — inline-start edge of the header or footer. In the header: back button, breadcrumb context, or workspace switcher, before the icon/heading column. In the footer: secondary action (e.g. Back) opposite the primary cluster."
+              "name": "format",
+              "type": {
+                "text": "string"
+              },
+              "default": "short",
+              "description": "Trigger button date format. `short`: `Jan 1, 2026 14:30`; `long`: `January 1, 2026 14:30`; `iso`: full ISO string."
             },
             {
-              "name": "media",
-              "description": "Full-bleed media region — placed before the first `<header>` or `<section>` as the card's hero image / video / illustration slot. Stretches edge-to-edge (negative margin equal to the card's inset); first-child `[slot=\"media\"]` gets zero border-radius on the top corners so it sits flush with the card border."
-            }
-          ]
-        }
-      ],
-      "exports": [
-        {
+              "name": "locale",
+              "type": {
+                "text": "string"
+              },
+              "description": "BCP-47 locale tag used to derive hour-cycle when `hour-cycle` is empty. Falls back to `<html lang>` then to browser default."
+            },
+            {
+              "name": "placement",
+              "type": {
+                "text": "string"
+              },
+              "default": "bottom",
+              "description": "Popover placement relative to the trigger. Default `bottom` centers the calendar+time panel under the trigger (ADR-0034 Rule 2 — ~600px panel >> trigger)."
+            }
+          ],
+          "slots": [
+            {
+              "name": "trigger",
+              "description": "Custom trigger replacement. When omitted, a default trigger is stamped (a plain clickable span, per the base `<calendar-picker-ui>` — NOT the old standalone datetime-picker's `<button-ui>` trigger; see the Consequences note below)."
+            },
+            {
+              "name": "footer",
+              "description": "Optional Apply / Cancel buttons for explicit-commit flows. Spans both panes below the calendar + time area."
+            }
+          ],
+          "events": [
+            {
+              "name": "change",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "Fired when the value commits (date picked + time edited, OR Apply clicked in explicit-commit mode)."
+            },
+            {
+              "name": "input",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "Fired during partial selection (date picked but time still pending, or vice versa)."
+            },
+            {
+              "name": "open",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "Popover opened (user clicked the trigger or pressed Enter / Space)."
+            },
+            {
+              "name": "close",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "Popover closed (without commit, or after commit)."
+            },
+            {
+              "name": "invalid",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "A constraint failed (out of range, parse error)."
+            }
+          ]
+        }
+      ],
+      "exports": [
+        {
+          "kind": "custom-element-definition",
+          "name": "datetime-picker-ui",
+          "declaration": {
+            "name": "UIDatetimePicker",
+            "module": "./components/calendar-picker/calendar-picker.test.js"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "components/canvas/canvas.js",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "A2UI rendering surface — the canonical mount point that consumes a DocStore / A2UI document and renders the component tree from it. The runtime's <a2ui-root> typically wraps a canvas-ui internally for the preview pane in <editor-canvas>. Use for embedding live A2UI output inside a custom editor, playground, or preview surface; not for generic in-page canvases (use HTML <canvas> for drawing).",
+          "name": "UICanvas",
+          "tagName": "canvas-ui",
+          "superclass": {
+            "name": "UIElement",
+            "module": "/core/element.js"
+          },
+          "attributes": [
+            {
+              "name": "theme",
+              "type": {
+                "text": "string"
+              },
+              "description": "Component property: theme."
+            }
+          ],
+          "events": [
+            {
+              "name": "canvas-interaction",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "Fired on canvas interactions (focus, blur, pointer events). Dispatched at canvas.js:50 + :167."
+            }
+          ]
+        }
+      ],
+      "exports": [
+        {
+          "kind": "custom-element-definition",
+          "name": "canvas-ui",
+          "declaration": {
+            "name": "UICanvas",
+            "module": "./components/canvas/canvas.js"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "components/card/card.js",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "Bordered container with header, body, and footer sections. The nested <header> activates a 3-column grid when",
+          "name": "UICard",
+          "tagName": "card-ui",
+          "superclass": {
+            "name": "UIElement",
+            "module": "/core/element.js"
+          },
+          "attributes": [
+            {
+              "name": "padding",
+              "type": {
+                "text": "string"
+              },
+              "description": "Interior padding scale — overrides --card-inset (the header/section/footer inset token) for the whole"
+            },
+            {
+              "name": "draggable",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Enables drag handle + cursor:grab. Wires the draggable trait; dispatches drag-end."
+            },
+            {
+              "name": "elevation",
+              "type": {
+                "text": "number"
+              },
+              "default": "1",
+              "description": "Shadow depth 0-3"
+            },
+            {
+              "name": "raw",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Strips background, border, and shadow. Parent owns the surface. Content structure still applies."
+            },
+            {
+              "name": "size",
+              "type": {
+                "text": "string"
+              },
+              "description": "Card scale. Controls inset, radius, gap, and font sizes. Default (empty) = md."
+            },
+            {
+              "name": "variant",
+              "type": {
+                "text": "string"
+              },
+              "default": "default",
+              "description": "Visual style. `outlined` (alias `outline`) draws a border with no"
+            }
+          ],
+          "slots": [
+            {
+              "name": "icon",
+              "description": "Leading icon for the card header — status, brand, or type marker. Placed in column 1 of the 3-column header grid when present; heading + description shift to column 2. Use `<icon-ui name=\"…\">`, `<avatar-ui>`, or any inline icon element as a DIRECT child of the `<header>` with slot=\"icon\" (not inside a wrapper — direct-child only, per the :has(> [slot=\"icon\"]) gate)."
+            },
+            {
+              "name": "heading",
+              "description": "Primary title — grid row 1 inside `<header>`, or the prominent metric value inside `<footer>` (trend-stat / KPI pattern). Also accepts bare `<h1>`–`<h6>` tags as direct children without slot=\"heading\". A slot=\"heading\" wrapper can contain inline badges or metadata alongside the title text."
+            },
+            {
+              "name": "description",
+              "description": "Secondary metadata — grid row 2 beneath the heading inside `<header>`, or a period/caption line beneath a metric inside `<footer>` (e.g. \"Jan – Mar 2024\"). Also accepts bare `<p>` / `<small>` / body-variant `<text-ui>` as direct children without slot=\"description\". Triggers space-between layout in the footer when combined with slot=\"action\"."
+            },
+            {
+              "name": "action",
+              "description": "Trailing control cluster inside `<header>` (icon-buttons, menu trigger, more-options) or the primary action cluster inside `<footer>` (e.g. Save, Confirm). Aligns to the flex-end edge in both contexts. Pair with slot=\"action-leading\" for dual-cluster footers."
+            },
+            {
+              "name": "action-leading",
+              "description": "Leading control cluster — inline-start edge of the header or footer. In the header: back button, breadcrumb context, or workspace switcher, before the icon/heading column. In the footer: secondary action (e.g. Back) opposite the primary cluster."
+            },
+            {
+              "name": "media",
+              "description": "Full-bleed media region — placed before the first `<header>` or `<section>` as the card's hero image / video / illustration slot. Stretches edge-to-edge (negative margin equal to the card's inset); first-child `[slot=\"media\"]` gets zero border-radius on the top corners so it sits flush with the card border."
+            }
+          ]
+        }
+      ],
+      "exports": [
+        {
           "kind": "custom-element-definition",
           "name": "card-ui",
           "declaration": {
@@ -1927,7 +2158,15 @@
                 "text": "boolean"
               },
               "default": "false",
-              "description": "When set, rows are non-interactive <span>s (no click, no toggle)."
+              "description": "DEPRECATED (ADR-0063, gh#1563) — use `interactive` instead. When set (and `interactive` is absent), rows are non-interactive <span>s (no click, no toggle). Kept working as a dual-read compat shim (one-time console.warn when it's the name that resolves). Removed in 0.9.0."
+            },
+            {
+              "name": "interactive",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "true",
+              "description": "Canonical opt-in spelling (ADR-0063, gh#1563) replacing `static`'s opt-out polarity. Rows are interactive <button>-role badges by default — this default stays `true` in 0.8.42 (deliberately NOT flipped yet; the 0.9.0 cut inverts it to `false` after a full consumer scan of every `<chart-legend-ui>` tag per the ADR)."
             },
             {
               "name": "on-toggle",
@@ -2009,7 +2248,15 @@
                 "text": "boolean"
               },
               "default": "false",
-              "description": "When true, suppress the overlaid average line"
+              "description": "DEPRECATED (ADR-0063, gh#1563) — use `noAverage` instead. Same meaning, same default; kept working as a dual-read compat shim (one- time console.warn when it's the name that resolves). Removed in 0.9.0."
+            },
+            {
+              "name": "no-average",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "When true, suppress the overlaid average line. Canonical spelling (ADR-0063, gh#1563) replacing `hideAverage`."
             },
             {
               "name": "hide-grid",
@@ -2017,7 +2264,15 @@
                 "text": "boolean"
               },
               "default": "false",
-              "description": "Hide gridlines"
+              "description": "DEPRECATED (ADR-0063, gh#1563) — use `noGrid` instead. Same meaning, same default; kept working as a dual-read compat shim (one-time console.warn when it's the name that resolves). Removed in 0.9.0."
+            },
+            {
+              "name": "no-grid",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Hide gridlines. Canonical spelling (ADR-0063, gh#1563) replacing `hideGrid`."
             },
             {
               "name": "hide-values",
@@ -2025,7 +2280,15 @@
                 "text": "boolean"
               },
               "default": "false",
-              "description": "Hide value labels"
+              "description": "DEPRECATED (ADR-0063, gh#1563) — use `noValues` instead. Same meaning, same default; kept working as a dual-read compat shim (one- time console.warn when it's the name that resolves). Removed in 0.9.0."
+            },
+            {
+              "name": "no-values",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Hide value labels. Canonical spelling (ADR-0063, gh#1563) replacing `hideValues`."
             },
             {
               "name": "corner-radius",
@@ -2107,7 +2370,7 @@
             },
             {
               "name": "empty",
-              "description": "Shown in place of the SVG when `.data` is empty or missing. Typically an `<empty-state-ui>` with icon + heading + description + optional action. Visibility is CSS-toggled via `[data-has-data]` on the host — authors don't need to manage it imperatively."
+              "description": "Shown in place of the SVG when `.data` is empty or missing. Typically an `<empty-state-ui>` with icon + heading + description + optional action. Visibility is CSS-toggled via `[has-data]` on the host — authors don't need to manage it imperatively."
             }
           ],
           "events": [
@@ -2377,16 +2640,6 @@
               "description": "Form value (submitted as 'on' when checked)"
             }
           ],
-          "slots": [
-            {
-              "name": "box",
-              "description": "Visual checkbox indicator"
-            },
-            {
-              "name": "label",
-              "description": "Label text beside the checkbox"
-            }
-          ],
           "events": [
             {
               "name": "change",
@@ -2632,13 +2885,13 @@
     },
     {
       "kind": "javascript-module",
-      "path": "components/color-input/color-input.js",
+      "path": "components/color-area/color-area.js",
       "declarations": [
         {
           "kind": "class",
-          "description": "Compact form-bearing color input — opens a popover-anchored `<color-picker-ui>` from an inline swatch button. §302 (v0.5.12, FEEDBACK-29 re-bucket from v0.6.0). Canonicalizes the USAGE.md §221f Option B recipe (popover + button + color-picker) into a single form-associated tag for inline form contexts (settings drawer \"source color\" field, swatch-row inline-edit, etc.).",
-          "name": "UIColorInput",
-          "tagName": "color-input-ui",
+          "description": "OKLCH-native color picker with 2D area and H/C/L sliders. Form-associated input emitting OKLCH color strings; canonical color authoring surface in the AdiaUI token system. Use for color input in design tools or theming UIs; for simple color swatches use <swatch-ui> or <color-input-ui> instead. Renamed from `<color-picker-ui>` (ADR-0063, gh#1563 — `-picker` is reserved for the outer trigger + popover composite shape; this is the inline substrate, mirroring <calendar-grid-ui>'s naming precedent). `<color-picker-ui>` is now a thin deprecated alias subclassing this component.",
+          "name": "UIColorArea",
+          "tagName": "color-area-ui",
           "superclass": {
             "name": "UIElement",
             "module": "/core/element.js"
@@ -2649,15 +2902,15 @@
               "type": {
                 "text": "string"
               },
-              "description": "Form field name."
+              "description": "Form field name"
             },
             {
-              "name": "value",
+              "name": "disabled",
               "type": {
-                "text": "string"
+                "text": "boolean"
               },
-              "default": "#3b82f6",
-              "description": "Current color as a string in the active [format]."
+              "default": "false",
+              "description": "Disables all interaction"
             },
             {
               "name": "format",
@@ -2665,10 +2918,132 @@
                 "text": "string"
               },
               "default": "hex",
-              "description": "Output format for the value property + event detail. Hex (`#rrggbb`) or OKLCH (`oklch(L C H)`)."
+              "description": "Output format for the value property"
             },
             {
-              "name": "disabled",
+              "name": "value",
+              "type": {
+                "text": "string"
+              },
+              "default": "#3b82f6",
+              "description": "Current color as hex string"
+            },
+            {
+              "name": "maxChroma",
+              "type": {
+                "text": "number"
+              },
+              "default": "Infinity",
+              "description": "Generation constraint (v0.4.9 §99h, FEEDBACK-02 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)."
+            },
+            {
+              "name": "maxL",
+              "type": {
+                "text": "number"
+              },
+              "default": "1",
+              "description": "Generation constraint — clamp OKLCH lightness to at most this value (0..1). Default 1 (no constraint)."
+            },
+            {
+              "name": "minL",
+              "type": {
+                "text": "number"
+              },
+              "default": "0",
+              "description": "Generation constraint — clamp OKLCH lightness to at least this value (0..1). Default 0 (no constraint)."
+            },
+            {
+              "name": "hueDriftMax",
+              "type": {
+                "text": "number"
+              },
+              "default": "NaN",
+              "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."
+            },
+            {
+              "name": "baseHue",
+              "type": {
+                "text": "number"
+              },
+              "default": "NaN",
+              "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."
+            }
+          ],
+          "events": [
+            {
+              "name": "change",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "Fired on every color change"
+            },
+            {
+              "name": "input",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "description": "Fired during continuous interaction (drag)"
+            },
+            {
+              "name": "constraint-clamp",
+              "type": {
+                "text": "CustomEvent"
+              },
+              "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."
+            }
+          ]
+        }
+      ],
+      "exports": [
+        {
+          "kind": "custom-element-definition",
+          "name": "color-area-ui",
+          "declaration": {
+            "name": "UIColorArea",
+            "module": "./components/color-area/color-area.js"
+          }
+        }
+      ]
+    },
+    {
+      "kind": "javascript-module",
+      "path": "components/color-input/color-input.js",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "Compact form-bearing color input — opens a popover-anchored `<color-area-ui>` from an inline swatch button. §302 (v0.5.12, FEEDBACK-29 re-bucket from v0.6.0). Canonicalizes the USAGE.md §221f Option B recipe (popover + button + color-area) into a single form-associated tag for inline form contexts (settings drawer \"source color\" field, swatch-row inline-edit, etc.). Composes `<color-area-ui>` (ADR-0063, gh#1563 — renamed from `<color-picker-ui>`, which is now a deprecated alias); `color-input-ui`'s own tag/name is unaffected.",
+          "name": "UIColorInput",
+          "tagName": "color-input-ui",
+          "superclass": {
+            "name": "UIElement",
+            "module": "/core/element.js"
+          },
+          "attributes": [
+            {
+              "name": "name",
+              "type": {
+                "text": "string"
+              },
+              "description": "Form field name."
+            },
+            {
+              "name": "value",
+              "type": {
+                "text": "string"
+              },
+              "default": "#3b82f6",
+              "description": "Current color as a string in the active [format]."
+            },
+            {
+              "name": "format",
+              "type": {
+                "text": "string"
+              },
+              "default": "hex",
+              "description": "Output format for the value property + event detail. Hex (`#rrggbb`) or OKLCH (`oklch(L C H)`)."
+            },
+            {
+              "name": "disabled",
               "type": {
                 "text": "boolean"
               },
@@ -2681,7 +3056,7 @@
                 "text": "string"
               },
               "default": "bottom",
-              "description": "Popover placement relative to the trigger. Default `bottom` centers the color-picker panel under the swatch button (ADR-0034 Rule 2 — panel wider than trigger)."
+              "description": "Popover placement relative to the trigger. Default `bottom` centers the color-area panel under the swatch button (ADR-0034 Rule 2 — panel wider than trigger)."
             },
             {
               "name": "open",
@@ -2697,7 +3072,7 @@
                 "text": "number"
               },
               "default": "Infinity",
-              "description": "Generation constraint forwarded to the inner `<color-picker-ui>` (v0.5.13 §-TBD, FB-33 §1). Clamp the OKLCH chroma channel to at most this value. Default Infinity (no constraint)."
+              "description": "Generation constraint forwarded to the inner `<color-area-ui>` (v0.5.13 §-TBD, FB-33 §1). Clamp the OKLCH chroma channel to at most this value. Default Infinity (no constraint)."
             },
             {
               "name": "maxL",
@@ -2767,7 +3142,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "OKLCH-native color picker with 2D area and H/C/L sliders. Form-associated input emitting OKLCH color strings; canonical color authoring surface in the AdiaUI token system. Use for color input in design tools or theming UIs; for simple color swatches use <swatch-ui> or <color-input-ui> instead.",
+          "description": "DEPRECATED (ADR-0063, gh#1563, gh#1377 B11) — `-picker` is reserved for the outer, trigger + popover, form-associated composite shape (`calendar-picker-ui` / `date-range-picker-ui` / `datetime-picker-ui` / `time-picker-ui`); `color-picker-ui` was the sole violator, playing `calendar-grid-ui`'s inline-substrate role under a `-picker` name. `<color-picker-ui>` is now a thin `UIColorArea` subclass (see color-picker.class.js) rather than an independent implementation — every prop/event/token is inherited unchanged from `<color-area-ui>`. Existing markup keeps working, but new markup should reach for `<color-area-ui>` directly. See `<color-area-ui>` for the full contract.",
           "name": "UIColorPicker",
           "tagName": "color-picker-ui",
           "superclass": {
@@ -3178,19 +3553,7 @@
           "slots": [
             {
               "name": "empty",
-              "description": "Empty state shown when no items match"
-            },
-            {
-              "name": "footer",
-              "description": "Keyboard hint bar"
-            },
-            {
-              "name": "input",
-              "description": "The auto-stamped search field — a contenteditable=\"plaintext-only\" span carrying role=\"combobox\" (per ADR-0025/ADR-0055; no native <input>). Internal only; not consumer-slottable."
-            },
-            {
-              "name": "list",
-              "description": "Container for command items and groups"
+              "description": "Empty state shown when no items match. Consumer-supplied [slot=\"empty\"] content is captured before the internal shell renders and re-inserted — a genuine light-DOM insertion point."
             }
           ],
           "events": [
@@ -3252,227 +3615,41 @@
               "description": "Programmatic open state. Set true to open at target center."
             },
             {
-              "name": "long-press-ms",
-              "type": {
-                "text": "number"
-              },
-              "default": "500",
-              "description": "Long-press duration (ms) on touch devices to open the menu."
-            }
-          ],
-          "slots": [
-            {
-              "name": "default",
-              "description": "Two-purpose slot: the wrapped target element (mode A — first non-menu-item-ui child) AND the menu-item-ui items. Items are promoted to the popover surface on open."
-            }
-          ],
-          "events": [
-            {
-              "name": "context-menu-open",
-              "type": {
-                "text": "CustomEvent"
-              },
-              "description": "Fired when the menu opens (right-click / long-press / keyboard)."
-            },
-            {
-              "name": "context-menu-close",
-              "type": {
-                "text": "CustomEvent"
-              },
-              "description": "Fired when the menu closes (item-select / outside-click / Escape)."
-            },
-            {
-              "name": "context-menu-select",
-              "type": {
-                "text": "CustomEvent"
-              },
-              "description": "Fired when an item is activated. Same shape as menu-ui's `action` event."
-            }
-          ]
-        }
-      ],
-      "exports": [
-        {
-          "kind": "custom-element-definition",
-          "name": "context-menu-ui",
-          "declaration": {
-            "name": "UIContextMenu",
-            "module": "./components/context-menu/context-menu.js"
-          }
-        }
-      ]
-    },
-    {
-      "kind": "javascript-module",
-      "path": "components/date-range-picker/date-range-picker.js",
-      "declarations": [
-        {
-          "kind": "class",
-          "description": "Compound form primitive for selecting a start + end date pair with optional named preset shortcuts (\"Today\", \"Last 7 days\", \"This month\", ...). Default presentation is a trigger button showing the formatted range; on activation a popover opens with two synchronized calendar panes + a preset side rail. Composes <calendar-grid-ui> twice; emits {from, to} ISO 8601 dates. Both panes are ONE selection surface: first click = start, second click = end, in either grid; a second click earlier than the start restarts the range there. Optional comparison-range mode emits a secondary range for analytics surfaces.",
-          "name": "UIDateRangePicker",
-          "tagName": "date-range-picker-ui",
-          "superclass": {
-            "name": "UIElement",
-            "module": "/core/element.js"
-          },
-          "attributes": [
-            {
-              "name": "name",
-              "type": {
-                "text": "string"
-              },
-              "description": "Form field name for form data submission. The selected range serializes as JSON `{\"from\":\"...\",\"to\":\"...\"}` under this key."
-            },
-            {
-              "name": "value",
-              "type": {
-                "text": "string"
-              },
-              "description": "Selected range as `{from, to}` ISO 8601 dates. Null when empty. Emitted on commit."
-            },
-            {
-              "name": "compare-value",
-              "type": {
-                "text": "string"
-              },
-              "description": "Comparison range when `[comparison]` is set. Same `{from, to}` shape as `value`."
-            },
-            {
-              "name": "comparison",
-              "type": {
-                "text": "boolean"
-              },
-              "default": "false",
-              "description": "Enable comparison-range mode. Renders a second preset cluster and emits a secondary range under `<name>-compare`."
-            },
-            {
-              "name": "min",
-              "type": {
-                "text": "string"
-              },
-              "description": "Earliest selectable ISO date (inclusive). Days before are disabled in both panes."
-            },
-            {
-              "name": "max",
-              "type": {
-                "text": "string"
-              },
-              "description": "Latest selectable ISO date (inclusive). Days after are disabled in both panes."
-            },
-            {
-              "name": "disabled",
-              "type": {
-                "text": "boolean"
-              },
-              "default": "false",
-              "description": "Block all interaction. Trigger remains rendered but does not open the popover."
-            },
-            {
-              "name": "readonly",
-              "type": {
-                "text": "boolean"
-              },
-              "default": "false",
-              "description": "Block edits; allow keyboard navigation for screen-reader inspection."
-            },
-            {
-              "name": "required",
-              "type": {
-                "text": "boolean"
-              },
-              "default": "false",
-              "description": "Required for validation when inside a `<form>`."
-            },
-            {
-              "name": "open",
-              "type": {
-                "text": "boolean"
-              },
-              "default": "false",
-              "description": "Whether the popover is currently open."
-            },
-            {
-              "name": "placeholder",
-              "type": {
-                "text": "string"
-              },
-              "default": "Select range",
-              "description": "Text shown in the trigger when the value is empty."
-            },
-            {
-              "name": "format",
-              "type": {
-                "text": "string"
-              },
-              "default": "short",
-              "description": "Trigger button date format. `short`: `Jan 1, 2026`; `long`: `January 1, 2026`; `iso`: `2026-01-01`."
-            },
-            {
-              "name": "no-presets",
-              "type": {
-                "text": "boolean"
-              },
-              "default": "false",
-              "description": "Hide the preset side rail."
-            },
-            {
-              "name": "placement",
+              "name": "long-press-ms",
               "type": {
-                "text": "string"
+                "text": "number"
               },
-              "default": "bottom",
-              "description": "Popover placement relative to the trigger. Default `bottom` centers the two-calendar panel under the trigger (ADR-0034 Rule 2 — ~800px panel >> trigger)."
+              "default": "500",
+              "description": "Long-press duration (ms) on touch devices to open the menu."
             }
           ],
           "slots": [
             {
-              "name": "trigger",
-              "description": "Custom trigger replacement. When omitted, a default `<button-ui>` is stamped."
-            },
-            {
-              "name": "presets",
-              "description": "Custom preset content replacing the default preset rail."
-            },
-            {
-              "name": "footer",
-              "description": "Optional footer area below the calendars (e.g., \"Apply\" / \"Cancel\" buttons for explicit-commit flows)."
+              "name": "default",
+              "description": "Two-purpose slot: the wrapped target element (mode A — first non-menu-item-ui child) AND the menu-item-ui items. Items are promoted to the popover surface on open."
             }
           ],
           "events": [
             {
-              "name": "change",
-              "type": {
-                "text": "CustomEvent"
-              },
-              "description": "Fired when the range commits (both `from` AND `to` selected, OR a preset clicked)."
-            },
-            {
-              "name": "input",
-              "type": {
-                "text": "CustomEvent"
-              },
-              "description": "Fired during selection — e.g. user clicked `from` but has not yet picked `to`."
-            },
-            {
-              "name": "open",
+              "name": "context-menu-open",
               "type": {
                 "text": "CustomEvent"
               },
-              "description": "Popover opened (user clicked the trigger or pressed Enter / Space)."
+              "description": "Fired when the menu opens (right-click / long-press / keyboard)."
             },
             {
-              "name": "close",
+              "name": "context-menu-close",
               "type": {
                 "text": "CustomEvent"
               },
-              "description": "Popover closed (without commit, or after commit)."
+              "description": "Fired when the menu closes (item-select / outside-click / Escape)."
             },
             {
-              "name": "invalid",
+              "name": "context-menu-select",
               "type": {
                 "text": "CustomEvent"
               },
-              "description": "A constraint failed (out of range, end < start)."
+              "description": "Fired when an item is activated. Same shape as menu-ui's `action` event."
             }
           ]
         }
@@ -3480,23 +3657,23 @@
       "exports": [
         {
           "kind": "custom-element-definition",
-          "name": "date-range-picker-ui",
+          "name": "context-menu-ui",
           "declaration": {
-            "name": "UIDateRangePicker",
-            "module": "./components/date-range-picker/date-range-picker.js"
+            "name": "UIContextMenu",
+            "module": "./components/context-menu/context-menu.js"
           }
         }
       ]
     },
     {
       "kind": "javascript-module",
-      "path": "components/datetime-picker/datetime-picker.js",
+      "path": "components/date-range-picker/date-range-picker.js",
       "declarations": [
         {
           "kind": "class",
-          "description": "Single-control date + time selection. Trigger button opens a popover with a `<calendar-picker-ui>` on the left + a `<time-picker-ui>` on the right; commit emits a full ISO 8601 datetime string (\"YYYY-MM-DDTHH:mm\" or with seconds). Composes the two underlying primitives — never wraps a native `<input type=\"datetime-local\">` (per ADR-0025). Form-associated under one `name`. SPEC-038.",
-          "name": "UIDatetimePicker",
-          "tagName": "datetime-picker-ui",
+          "description": "Compound form primitive for selecting a start + end date pair with optional named preset shortcuts (\"Today\", \"Last 7 days\", \"This month\", ...). Default presentation is a trigger button showing the formatted range; on activation a popover opens with two synchronized calendar panes + a preset side rail. Composes <calendar-grid-ui> twice; emits {from, to} ISO 8601 dates. Both panes are ONE selection surface: first click = start, second click = end, in either grid; a second click earlier than the start restarts the range there. Optional comparison-range mode emits a secondary range for analytics surfaces.",
+          "name": "UIDateRangePicker",
+          "tagName": "date-range-picker-ui",
           "superclass": {
             "name": "UIElement",
             "module": "/core/element.js"
@@ -3507,51 +3684,43 @@
               "type": {
                 "text": "string"
               },
-              "description": "Form field name. The ISO 8601 datetime is submitted under this key when the picker is inside a `<form>`."
+              "description": "Form field name for form data submission. The selected range serializes as JSON `{\"from\":\"...\",\"to\":\"...\"}` under this key."
             },
             {
               "name": "value",
               "type": {
                 "text": "string"
               },
-              "description": "Current value as ISO 8601 datetime (\"YYYY-MM-DDTHH:mm\" or \"YYYY-MM-DDTHH:mm:ss\"). Empty when no value selected."
-            },
-            {
-              "name": "min",
-              "type": {
-                "text": "string"
-              },
-              "description": "Earliest selectable ISO 8601 datetime (inclusive). Days before are disabled in the calendar pane; times before are rejected by the time pane on the same day."
+              "description": "Selected range as `{from, to}` ISO 8601 dates. Null when empty. Emitted on commit."
             },
             {
-              "name": "max",
+              "name": "compare-value",
               "type": {
                 "text": "string"
               },
-              "description": "Latest selectable ISO 8601 datetime (inclusive). Days after are disabled in the calendar pane; times after are rejected by the time pane on the same day."
+              "description": "Comparison range when `[comparison]` is set. Same `{from, to}` shape as `value`."
             },
             {
-              "name": "step",
+              "name": "comparison",
               "type": {
-                "text": "number"
+                "text": "boolean"
               },
-              "default": "60",
-              "description": "Per-Arrow-keypress increment in seconds for the time pane. 60 = minute precision (default), 900 = 15-minute, 1 = second precision."
+              "default": "false",
+              "description": "Enable comparison-range mode. Renders a second preset cluster and emits a secondary range under `<name>-compare`."
             },
             {
-              "name": "precision",
+              "name": "min",
               "type": {
                 "text": "string"
               },
-              "default": "minute",
-              "description": "Time-pane precision. `minute` (default) emits `HH:mm`; `second` exposes the seconds segment and emits `HH:mm:ss`."
+              "description": "Earliest selectable ISO date (inclusive). Days before are disabled in both panes."
             },
             {
-              "name": "hour-cycle",
+              "name": "max",
               "type": {
                 "text": "string"
               },
-              "description": "Hour cycle for the time pane. Empty (default) derives from the document locale. `h12` forces a 12-hour cycle with an AM/PM (meridiem) segment; `h23` forces 24-hour cycle."
+              "description": "Latest selectable ISO date (inclusive). Days after are disabled in both panes."
             },
             {
               "name": "disabled",
@@ -3590,7 +3759,7 @@
               "type": {
                 "text": "string"
               },
-              "default": "Select date and time",
+              "default": "Select range",
               "description": "Text shown in the trigger when the value is empty."
             },
             {
@@ -3599,14 +3768,15 @@
                 "text": "string"
               },
               "default": "short",
-              "description": "Trigger button date format. `short`: `Jan 1, 2026 14:30`; `long`: `January 1, 2026 14:30`; `iso`: full ISO string."
+              "description": "Trigger button date format. `short`: `Jan 1, 2026`; `long`: `January 1, 2026`; `iso`: `2026-01-01`."
             },
             {
-              "name": "locale",
+              "name": "no-presets",
               "type": {
-                "text": "string"
+                "text": "boolean"
               },
-              "description": "BCP-47 locale tag used to derive hour-cycle when `hour-cycle` is empty. Falls back to `<html lang>` then to browser default."
+              "default": "false",
+              "description": "Hide the preset side rail."
             },
             {
               "name": "placement",
@@ -3614,7 +3784,7 @@
                 "text": "string"
               },
               "default": "bottom",
-              "description": "Popover placement relative to the trigger. Default `bottom` centers the calendar+time panel under the trigger (ADR-0034 Rule 2 — ~600px panel >> trigger)."
+              "description": "Popover placement relative to the trigger. Default `bottom` centers the two-calendar panel under the trigger (ADR-0034 Rule 2 — ~800px panel >> trigger)."
             }
           ],
           "slots": [
@@ -3622,9 +3792,13 @@
               "name": "trigger",
               "description": "Custom trigger replacement. When omitted, a default `<button-ui>` is stamped."
             },
+            {
+              "name": "presets",
+              "description": "Custom preset content replacing the default preset rail."
+            },
             {
               "name": "footer",
-              "description": "Optional Apply / Cancel buttons for explicit-commit flows. Spans both panes below the calendar + time area."
+              "description": "Optional footer area below the calendars (e.g., \"Apply\" / \"Cancel\" buttons for explicit-commit flows)."
             }
           ],
           "events": [
@@ -3633,14 +3807,14 @@
               "type": {
                 "text": "CustomEvent"
               },
-              "description": "Fired when the value commits (date picked + time edited, OR Apply clicked in explicit-commit mode)."
+              "description": "Fired when the range commits (both `from` AND `to` selected, OR a preset clicked)."
             },
             {
               "name": "input",
               "type": {
                 "text": "CustomEvent"
               },
-              "description": "Fired during partial selection (date picked but time still pending, or vice versa)."
+              "description": "Fired during selection — e.g. user clicked `from` but has not yet picked `to`."
             },
             {
               "name": "open",
@@ -3661,7 +3835,7 @@
               "type": {
                 "text": "CustomEvent"
               },
-              "description": "A constraint failed (out of range, parse error)."
+              "description": "A constraint failed (out of range, end < start)."
             }
           ]
         }
@@ -3669,10 +3843,10 @@
       "exports": [
         {
           "kind": "custom-element-definition",
-          "name": "datetime-picker-ui",
+          "name": "date-range-picker-ui",
           "declaration": {
-            "name": "UIDatetimePicker",
-            "module": "./components/datetime-picker/datetime-picker.js"
+            "name": "UIDateRangePicker",
+            "module": "./components/date-range-picker/date-range-picker.js"
           }
         }
       ]
@@ -3779,7 +3953,7 @@
                 "text": "string"
               },
               "default": "start",
-              "description": "Alignment for inline layout. `start` (default): term and value pack to the term column edge. `between`: term left, value right-aligned with `text-align: end`. `stretch`: value fills the remaining track width (e.g. for a `<slider-ui>` / `<select-ui>` / `<color-picker-ui>` as `<dd>` that should span the full row). Sets `justify-self: stretch` and `width: 100%` on `dd` so block-level form controls inside reach the column edge rather than shrink-wrapping to content."
+              "description": "Alignment for inline layout. `start` (default): term and value pack to the term column edge. `between`: term left, value right-aligned with `text-align: end`. `stretch`: value fills the remaining track width (e.g. for a `<slider-ui>` / `<select-ui>` / `<color-area-ui>` as `<dd>` that should span the full row). Sets `justify-self: stretch` and `width: 100%` on `dd` so block-level form controls inside reach the column edge rather than shrink-wrapping to content."
             },
             {
               "name": "items",
@@ -3995,10 +4169,6 @@
             }
           ],
           "slots": [
-            {
-              "name": "backdrop",
-              "description": "Scrim overlay behind the drawer (stamped by the component)."
-            },
             {
               "name": "panel",
               "description": "Sliding panel container (stamped by the component)."
@@ -4143,42 +4313,6 @@
             {
               "name": "breadcrumb",
               "description": "Optional slot for a consumer-supplied <breadcrumb-ui> in the level header, for deep hierarchies. Not managed by drilldown-ui — the consumer wires jump clicks to `.path = [...]` itself."
-            },
-            {
-              "name": "header",
-              "description": "Auto-stamped level-header container (back affordance + breadcrumb + title/count). Structural — not consumer-overridable."
-            },
-            {
-              "name": "back",
-              "description": "Auto-stamped back-affordance <button> (chevron + parent-level label). Hidden at the root level."
-            },
-            {
-              "name": "title",
-              "description": "Auto-stamped title cluster (current-level label + item count) inside the header."
-            },
-            {
-              "name": "filter",
-              "description": "Auto-stamped filter-input row, shown only when `[filterable]` is set."
-            },
-            {
-              "name": "viewport",
-              "description": "Auto-stamped clipping container for the current level's panel (hosts the slide-transition overflow clip)."
-            },
-            {
-              "name": "dot",
-              "description": "Auto-stamped per-row leading color swatch, rendered when the row's data item declares a `dot` tone."
-            },
-            {
-              "name": "main",
-              "description": "Auto-stamped per-row content column (label + optional meta line)."
-            },
-            {
-              "name": "meta",
-              "description": "Auto-stamped per-row secondary meta line, rendered when the row's data item declares `meta`."
-            },
-            {
-              "name": "counts",
-              "description": "Auto-stamped per-row trailing count-chip cluster, rendered when the row's data item declares `counts`."
             }
           ],
           "events": [
@@ -4254,12 +4388,6 @@
               "default": "100%",
               "description": "Iframe width. Any CSS width value."
             }
-          ],
-          "slots": [
-            {
-              "name": "iframe",
-              "description": "Sandboxed <iframe> element (allow-scripts allow-same-origin)"
-            }
           ]
         }
       ],
@@ -4424,12 +4552,6 @@
               "description": "Label of an inline action button (the \"deep-link\" / \"undo\" pattern). Pair with `onAction` callback in `UIFeed.post()` — click invokes the callback then auto-dismisses. Empty string renders no action button."
             }
           ],
-          "slots": [
-            {
-              "name": "body",
-              "description": "Default content slot (also accepts the `text` / `heading` props)"
-            }
-          ],
           "events": [
             {
               "name": "close",
@@ -4553,7 +4675,7 @@
           "slots": [
             {
               "name": "default",
-              "description": "The form control — a WIDE control like input-ui, select-ui, textarea-ui, slider-ui, range-ui, calendar-picker-ui, color-picker-ui, upload-ui, otp-input-ui. Auto-id'd for the label's [for] binding. DO NOT wrap small self-labeling widgets here. check-ui, switch-ui, radio-ui, toggle-ui all carry their own [label] attribute that renders inline next to the control — wrapping them in field-ui produces broken layouts (settings-row `justify-self: end` rule pushes the control to the trailing edge, away from the label that field-ui stamps; the widget's own label then renders again on the right, creating a doubled / right-justified affordance). See anti_patterns below for the canonical alternatives."
+              "description": "The form control — a WIDE control like input-ui, select-ui, textarea-ui, slider-ui, range-ui, calendar-picker-ui, color-area-ui, upload-ui, otp-input-ui. Auto-id'd for the label's [for] binding. DO NOT wrap small self-labeling widgets here. check-ui, switch-ui, radio-ui, toggle-ui all carry their own [label] attribute that renders inline next to the control — wrapping them in field-ui produces broken layouts (settings-row `justify-self: end` rule pushes the control to the trailing edge, away from the label that field-ui stamps; the widget's own label then renders again on the right, creating a doubled / right-justified affordance). See anti_patterns below for the canonical alternatives."
             },
             {
               "name": "trailing",
@@ -5019,11 +5141,11 @@
               "description": "Size preset — e.g. 'full' fills the container width and height."
             },
             {
-              "name": "radius",
+              "name": "corner-radius",
               "type": {
                 "text": "string"
               },
-              "description": "Border radius token"
+              "description": "Border radius token. Renamed from `[radius]` (gh#1335) — a preset-enum can't share a name with the global Enum·preset `[radius]` attribute (`sharp`/`rounded`/`round`), whose vocabulary is unrelated (ADR-0053); mirrors chart-ui's own `[corner-radius]` fix (ADR-0054) and skeleton-ui's matching rename (image-ui composes skeleton-ui for its loading fallback)."
             },
             {
               "name": "src",
@@ -5042,8 +5164,12 @@
           ],
           "slots": [
             {
-              "name": "img",
-              "description": "Stamped <img> element"
+              "name": "image",
+              "description": "The <img> element. Adopt-or-stamp (gh#1461): an author-supplied [slot=\"image\"] child is adopted as-is; otherwise a lazy-loading <img> is created. Renamed from the yaml's prior `img` key, which matched neither this real attribute value nor any DOM element image-ui stamps."
+            },
+            {
+              "name": "skeleton",
+              "description": "Loading-state placeholder shown until the image loads or errors. Adopt-or-stamp: an author-supplied [slot=\"skeleton\"] child is adopted; otherwise a <skeleton-ui> is created."
             }
           ]
         }
@@ -5182,7 +5308,7 @@
               "type": {
                 "text": "string"
               },
-              "description": "Sets `aria-live` on the host for dynamic message updates. Empty = no live region (static annotation)."
+              "description": "Sets `aria-live` on the host for dynamic message updates. `off` = no live region (static annotation) — the A2UI v1.0 vocabulary (off | polite | assertive, SPEC REQ-013); empty string is the legacy alias for `off`, kept for existing consumers."
             }
           ],
           "slots": [
@@ -5235,7 +5361,7 @@
                 "text": "string"
               },
               "default": "text",
-              "description": "Input type. `password` wraps a native `<input>` for disc masking; `number` renders a contenteditable + stepper"
+              "description": "Input type. `password` wraps a native `<input>` for disc masking; `number` renders a contenteditable + stepper buttons (no native input). `text`/`email`/`tel`/`url` use plain contenteditable. input-ui does NOT implement date/time/color/search affordances — those HTML5 type values render as a plain contenteditable with no calendar, clock, swatch, or search affordance (first-pass-VALID against this enum historically, but functionally broken generation output). Use the owning primitive instead — CalendarPicker for date (+ month/week, no dedicated granularity primitive exists), DatetimePicker for datetime-local, TimePicker for time, ColorInput/ColorPicker for color, Search for search. See anti_patterns."
             },
             {
               "name": "required",
@@ -5951,6 +6077,14 @@
                 "text": "string"
               },
               "description": "Secondary line below the primary text. Subtle color."
+            },
+            {
+              "name": "selected",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether this row is the current selection. Managed by the parent <list-ui>[selectable] — don't set directly; the parent's [selectedKey] is the single source of truth (ADR-0056)."
             }
           ],
           "slots": [
@@ -5978,7 +6112,7 @@
         },
         {
           "kind": "class",
-          "description": "Styled flat list with optional row dividers and icons — each row is a <list-item-ui> child. Selectable mode via [selectable] + [selectedKey] / `select` event. Composes <icon-ui> for row leading glyphs. Distinct from <nav-ui> (sidebar navigation, route-aware), <tree-ui> (hierarchical with arbitrary nesting), and <table-ui> (tabular data with columns). Use list-ui for non-navigable, non-tabular vertical rows — comment lists, file lists, message streams outside chat-shell.",
+          "description": "Styled flat list with optional row dividers and icons — each row is a <list-item-ui> child. Selectable mode via [selectable] + [selectedKey] / `selection-change` event. Composes <icon-ui> for row leading glyphs. Distinct from <nav-ui> (sidebar navigation, route-aware), <tree-ui> (hierarchical with arbitrary nesting), and <table-ui> (tabular data with columns). Use list-ui for non-navigable, non-tabular vertical rows — comment lists, file lists, message streams outside chat-shell.",
           "name": "UIList",
           "tagName": "list-ui",
           "superclass": {
@@ -6015,7 +6149,7 @@
               "type": {
                 "text": "string"
               },
-              "description": "ID (or data-key) of the currently-selected child listitem."
+              "description": "ID (or data-key) of the currently-selected child listitem — drives each child's [selected] reflected prop (ADR-0056, #1363 B7). Kept as `selectedKey` rather than renamed to `value` (segmented/tabs/ select's parent-selection prop name): list rows are identified by DOM id/data-key, not an option value, and ADR-0056 itself governs only the child's own [selected] state surface, not this naming — a cross-family rename has no ratifying ADR (B5/B9-shaped follow-up)."
             },
             {
               "name": "spacing",
@@ -6023,7 +6157,7 @@
                 "text": "string"
               },
               "default": "md",
-              "description": "Item spacing"
+              "description": "Item spacing scale — `sm`/`lg` modulate the per-item inset; `md` (default) is the base inset."
             }
           ],
           "events": [
@@ -6180,7 +6314,7 @@
         },
         {
           "kind": "class",
-          "description": "Child of `<menu-ui>`. One actionable row inside a menu, with optional leading icon + label + subtitle + value.",
+          "description": "Child of `<menu-ui>`. One actionable row inside a menu, with optional leading icon + label + description + value. (`subtitle` is a deprecated alias for `description` — ADR-0063, gh#1563.)",
           "name": "UIMenuItem",
           "tagName": "menu-item-ui",
           "superclass": {
@@ -6207,7 +6341,14 @@
               "type": {
                 "text": "string"
               },
-              "description": "Optional secondary description line rendered under the label."
+              "description": "DEPRECATED (ADR-0063, gh#1563) — use `description` instead. Same type/default/rendered position; kept working as a dual-read compat shim (one-time console.warn when it's the name that resolves). Removed in 0.9.0. (The `subtitle` SLOT below is a separate surface, deliberately left unrenamed in this pass — see its own description.)"
+            },
+            {
+              "name": "description",
+              "type": {
+                "text": "string"
+              },
+              "description": "Optional secondary description line rendered under the label. Canonical spelling (ADR-0063, gh#1563) replacing `subtitle` — converges menu-item onto the ~20-component corpus majority that already names this concept `description`."
             },
             {
               "name": "value",
@@ -6244,7 +6385,7 @@
             },
             {
               "name": "subtitle",
-              "description": "Custom secondary-line content override; falls through to `[subtitle]` prop if not slotted."
+              "description": "Custom secondary-line content override; falls through to the `[description]` prop (or its deprecated `[subtitle]` alias — ADR-0063, gh#1563) if not slotted. The slot's own name is unchanged by that rename — this is a distinct, deliberately-unrenamed surface."
             },
             {
               "name": "trailing",
@@ -6288,12 +6429,12 @@
           },
           "attributes": [
             {
-              "name": "gap",
+              "name": "offset",
               "type": {
                 "text": "number"
               },
               "default": "4",
-              "description": "Gap in px"
+              "description": "Pixel offset between the anchor (trigger) and the menu popover. Renamed from `[gap]` (gh#1335) — a raw-px number can't share a name with the global Scale-grammar `[gap]` attribute (ADR-0053); matches popover-ui's own `[offset]` (same anchorPopover() helper)."
             },
             {
               "name": "open",
@@ -7161,8 +7302,8 @@
           ],
           "slots": [
             {
-              "name": "field",
-              "description": "Container for the digit input boxes and optional separator"
+              "name": "digit",
+              "description": "Each digit input box, one per [length] — the component's own real slot=\"digit\" attribute (gh#1461; renamed from the yaml's prior `field` key, which matched no DOM element otp-input-ui stamps). Rebuilt wholesale on every template-owned in current behavior, not an author-content insertion point; left under slots: here since reclassifying slots:/parts: is gh#1454's charter, not this ticket's."
             }
           ],
           "events": [
@@ -7409,6 +7550,13 @@
               "type": {
                 "text": "string"
               },
+              "description": "DEPRECATED (ADR-0063, gh#1563) — use `edge` instead. Same type/default/enum; kept working as a dual-read compat shim (one-time console.warn when it's the name that resolves). Removed in 0.9.0."
+            },
+            {
+              "name": "edge",
+              "type": {
+                "text": "string"
+              },
               "description": "'Opts a pane into horizontal-sibling chrome: suppresses the default"
             }
           ],
@@ -7581,12 +7729,12 @@
           },
           "attributes": [
             {
-              "name": "gap",
+              "name": "offset",
               "type": {
                 "text": "number"
               },
               "default": "4",
-              "description": "Pixel offset between the anchor and the popover"
+              "description": "Pixel offset between the anchor and the popover. Renamed from `[gap]` (gh#1335) — a raw-px number can't share a name with the global Scale-grammar `[gap]` attribute (ADR-0053)."
             },
             {
               "name": "match-width",
@@ -7628,7 +7776,7 @@
             },
             {
               "name": "content",
-              "description": "Popover body — any interactive content. Hoisted to the top-layer via :popover-open when shown. Positioned via the Popover API + CSS Anchor Positioning per [placement] / [gap]; no manual positioning required."
+              "description": "Popover body — any interactive content. Hoisted to the top-layer via :popover-open when shown. Positioned via the Popover API + CSS Anchor Positioning per [placement] / [offset]; no manual positioning required."
             }
           ]
         }
@@ -7715,7 +7863,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Inline labeled progress row with label, progress bar, and meta text. Used for storage",
+          "description": "DEPRECATED (gh#1363 C4) — absorbed into <progress-ui>: set `label` (and optional `meta`) directly on <progress-ui> instead, which activates the identical row layout in place. progress-row-ui keeps working (still composes <progress-ui> internally, unchanged behavior) for existing back-compat markup, but is no longer taught or generated for new work. Was: inline labeled progress row with label, progress bar, and meta text — storage quotas, capacity breakdowns, usage indicators.",
           "name": "UIProgressRow",
           "tagName": "progress-row-ui",
           "superclass": {
@@ -7783,7 +7931,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Progress indicator with bar (default) or spinner variant. Value < 0 marks indeterminate state showing animated activity instead of a fill. Use inside <progress-row-ui> for labeled task lists or standalone for global loading indicators; for percent-complete inline displays use <stat-ui> instead.",
+          "description": "Linear progress bar indicator. Value < 0 marks indeterminate state showing animated activity instead of a fill. Bar-only — for circular loading indicators use <spinner-ui> instead (the former `variant=\"spinner\"` render mode was retired; spinner-ui owns circular). Set `label` for a labeled task-list row (label + bar + optional `meta` text in one row, e.g. storage quotas, capacity breakdowns) — absorbed <progress-row-ui>'s row layout directly; that component is now a deprecated alias. Omit `label` for a standalone bar (global loading indicators); for percent-complete inline displays use <stat-ui> instead.",
           "name": "UIProgress",
           "tagName": "progress-ui",
           "superclass": {
@@ -7797,25 +7945,21 @@
                 "text": "number"
               },
               "default": "null",
-              "description": "Current progress. 0..max (or 0..1 when max omitted). null = indeterminate (legacy -1 accepted for back-compat)."
+              "description": "Current progress, 0-100 (clamped). null = indeterminate (legacy -1 accepted for back-compat)."
             },
             {
-              "name": "variant",
+              "name": "label",
               "type": {
                 "text": "string"
               },
-              "default": "bar",
-              "description": "Render mode — `bar` (default) or `spinner`. For fill color set"
-            }
-          ],
-          "slots": [
-            {
-              "name": "fill",
-              "description": "Bar fill element inside track"
+              "description": "Left-hand label text. Presence (non-empty) switches to the labeled row layout — label + bar + optional `meta` in one row; absent = plain bar. Sanctioned Mode Attribute (component-token-contract.md)."
             },
             {
-              "name": "track",
-              "description": "Bar track container"
+              "name": "meta",
+              "type": {
+                "text": "string"
+              },
+              "description": "Right-hand meta text shown in row layout (e.g. '32 GB', '4.2k / 10k'). No visible effect without `label`."
             }
           ]
         }
@@ -7953,10 +8097,6 @@
             {
               "name": "default",
               "description": "radio-ui children sharing one [name=] — exclusivity and arrow-key navigation are unchanged; they still resolve via closest('fieldset, [role=radiogroup]'), which now matches this host."
-            },
-            {
-              "name": "label",
-              "description": "Auto-minted label element (mounted by radio-group-ui from the [label] prop) — do not author this slot directly."
             }
           ]
         }
@@ -8054,16 +8194,6 @@
               "description": "Form value submitted when checked (defaults to 'on' if empty)"
             }
           ],
-          "slots": [
-            {
-              "name": "dot",
-              "description": "Radio dot indicator, sized via --dot-size"
-            },
-            {
-              "name": "label",
-              "description": "Label text container, rendered via CSS attr(label) on ::after"
-            }
-          ],
           "events": [
             {
               "name": "change",
@@ -8617,7 +8747,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Individual segment child of <segmented-ui> — carries the [value], [text], optional [icon], and [selected] state for one option in a horizontal segmented selector. Distinct from <tab-ui> (a view switcher's child) and <option> (native option for <select-ui>). Use segment-ui only as a direct child of <segmented-ui>; never standalone.",
+          "description": "Individual segment child of <segmented-ui> — carries the [value], [text], optional [icon], and [selected] state for one option in a horizontal segmented selector, single- or multi-select (<segmented-ui multiple>, gh#1369). Distinct from <tab-ui> (a view switcher's child) and <option> (native option for <select-ui>). Use segment-ui only as a direct child of <segmented-ui>; never standalone.",
           "name": "UISegment",
           "tagName": "segment-ui",
           "superclass": {
@@ -8682,7 +8812,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Single-select toggle group with an animated sliding indicator. Children must be segment-ui elements.",
+          "description": "Toggle group with an animated sliding indicator (single-select) or independently-toggleable segments (multi-select via [multiple]). Children must be segment-ui elements.",
           "name": "UISegmented",
           "tagName": "segmented-ui",
           "superclass": {
@@ -8695,7 +8825,15 @@
               "type": {
                 "text": "string"
               },
-              "description": "Value of the currently selected segment."
+              "description": "Value of the currently selected segment. Under [multiple], a comma-separated set of selected values (same encoding as select-ui[multiple])."
+            },
+            {
+              "name": "multiple",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Enables multi-select — value becomes a comma-separated set, the sliding indicator is suppressed (each selected segment carries its own background instead), and Space/Enter toggles a focused segment instead of arrow-move selecting it. Positive polarity, matching select-ui[multiple]. Absorbs the role of the deprecated <toggle-group-ui> + <toggle-option-ui> pair (gh#1369, #1363 C1). Unlike <toggle-group-ui single>, re-clicking an already-selected segment does NOT clear the selection — segmented-ui's single-select is standard radiogroup semantics (always exactly one selected once a value is set)."
             },
             {
               "name": "allow-empty",
@@ -8703,17 +8841,13 @@
                 "text": "boolean"
               },
               "default": "false",
-              "description": "Suppresses the connect-time self-select of the first enabled segment when value is falsy. Without it, an empty value silently selects the first segment; with it, a falsy value renders every segment unselected until a real value arrives — for path-bound consumers whose bound value can be a genuine empty state."
+              "description": "Suppresses the connect-time self-select of the first enabled segment when value is falsy. Without it, an empty value silently selects the first segment; with it, a falsy value renders every segment unselected until a real value arrives — for path-bound consumers whose bound value can be a genuine empty state. No effect under [multiple] — multi-select never self-selects (empty value already means \"nothing chosen\")."
             }
           ],
           "slots": [
             {
               "name": "default",
               "description": "Child segment-ui elements that form the toggle group. Children MUST be segment-ui — bare segment tags render text but are silently ignored for the sliding indicator and role/aria-checked state."
-            },
-            {
-              "name": "indicator",
-              "description": "Auto-created sliding indicator element prepended on first render."
             }
           ],
           "events": [
@@ -8895,7 +9029,6 @@
               "type": {
                 "text": "string"
               },
-              "default": "null",
               "description": "Multi-select only (gh#442). Replaces the chip trigger with one text line: a single selection shows its own label; N > 1 shows \"<summary-label> (N)\" — e.g. \"Organizations (2)\"; none shows the placeholder. Popover checkbox rows, Backspace-removes-last, the comma-separated form value, [select-all], and [clearable] are unchanged. Absent (default) = tag-ui chip trigger. Prefer this form for narrow triggers (filter bars) where wrapping chips would balloon the control."
             },
             {
@@ -8986,21 +9119,9 @@
             }
           ],
           "slots": [
-            {
-              "name": "label",
-              "description": "Label element above the trigger"
-            },
-            {
-              "name": "listbox",
-              "description": "Popover container for options (role=listbox)"
-            },
             {
               "name": "trigger",
-              "description": "Button that opens the listbox"
-            },
-            {
-              "name": "hint",
-              "description": "Override slot for hint markup richer than the plain [hint] attribute string (inline links, code spans). Renders beneath the trigger at body-subtle typography. Mutually exclusive with [hint]."
+              "description": "Button that opens the listbox. Stamped only if no consumer-authored [slot=\"trigger\"] is already present at first render (adopt-or-stamp) — a genuine light-DOM insertion point."
             }
           ],
           "events": [
@@ -9055,12 +9176,12 @@
               "description": "Height of the placeholder."
             },
             {
-              "name": "radius",
+              "name": "corner-radius",
               "type": {
                 "text": "string"
               },
               "default": "sm",
-              "description": "Border radius"
+              "description": "Border radius. Renamed from `[radius]` (gh#1335) — a preset-enum can't share a name with the global Enum·preset `[radius]` attribute (`sharp`/`rounded`/`round`), whose vocabulary is unrelated (ADR-0053); mirrors chart-ui's own `[corner-radius]` fix (ADR-0054)."
             },
             {
               "name": "static",
@@ -9648,21 +9769,21 @@
           "slots": [
             {
               "name": "label",
-              "description": "Custom label content; falls through to `[text]` prop if not slotted."
+              "description": "Custom label content; falls through to [text] prop if not slotted. Adopt-or-stamp guarded (gh#1462): render() only writes into the component-stamped fallback span — a consumer-authored `[slot=\"label\"]` child is adopted as source of truth and never overwritten."
             },
             {
               "name": "description",
-              "description": "Custom description content; falls through to `[description]` prop if not slotted."
+              "description": "Custom secondary-line content; falls through to [description] prop if not slotted. Same adopt-or-stamp guard as `label` (gh#1462)."
             },
             {
               "name": "icon",
-              "description": "Override the step-status glyph with a custom slotted element. By default the step renders a numeral / check / x indicator based on [status]; slot an `<icon-ui>` or image to customize."
+              "description": "Override the step-status glyph with a custom slotted element (custom icon-ui, image). Mutually exclusive with the [icon] attribute — a consumer-authored slot child wins and is never renamed or removed by render() (gh#1462 adopt-or-stamp guard)."
             }
           ]
         },
         {
           "kind": "class",
-          "description": "Wizard / process stepper — parent step index drives numbered children's complete/current/upcoming states automatically. Renders horizontally as a labeled step bar with connectors. Use for multi-step forms, onboarding, or pipelines; for read-only event history use <timeline-ui> instead. Add [interactive] to opt into click-to-navigate + roving- tabindex keyboard (arrow keys / Home / End) — the host still owns whether navigation is permitted: listen for the cancelable [step-request] event and call preventDefault() to veto a step before it lands, or set [disabled] on a stepper-item-ui to phase-gate it out of reach entirely.",
+          "description": "Wizard / process stepper — parent step index drives numbered children's complete/current/upcoming states automatically. Renders horizontally as a labeled step bar with connectors. Use for multi-step forms, onboarding, or pipelines; for read-only event history use <timeline-ui> instead. Add [interactive] to opt into click-to-navigate + roving-tabindex keyboard (arrow keys / Home / End) — the host still owns whether navigation is permitted: listen for the cancelable [step-request] event and call preventDefault() to veto a step before it lands, or set [disabled] on a stepper-item-ui to phase-gate it out of reach entirely.",
           "name": "UIStepper",
           "tagName": "stepper-ui",
           "superclass": {
@@ -10173,24 +10294,6 @@
               "description": "Form value (submitted as 'on' when checked)"
             }
           ],
-          "slots": [
-            {
-              "name": "hint",
-              "description": "Help text below the label"
-            },
-            {
-              "name": "label",
-              "description": "Label text beside the toggle"
-            },
-            {
-              "name": "thumb",
-              "description": "Sliding thumb indicator inside track"
-            },
-            {
-              "name": "track",
-              "description": "Toggle track container (holds thumb)"
-            }
-          ],
           "events": [
             {
               "name": "change",
@@ -10584,6 +10687,14 @@
               },
               "default": "false",
               "description": "Whether the tab is selectable."
+            },
+            {
+              "name": "selected",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Whether this tab's panel is the active one. Managed by the parent <tabs-ui> container — don't set directly; the parent's [value] is the single source of truth (ADR-0056)."
             }
           ]
         }
@@ -10640,10 +10751,6 @@
             {
               "name": "default",
               "description": "Child tab-ui elements that form the tab strip"
-            },
-            {
-              "name": "indicator",
-              "description": "Auto-created sliding indicator element (line variant only)"
             }
           ],
           "events": [
@@ -10834,7 +10941,7 @@
                 "text": "number"
               },
               "default": "1",
-              "description": "Minimum per-token character count after `transform` is applied."
+              "description": "Minimum per-token character count after `normalize` is applied."
             },
             {
               "name": "max-length",
@@ -10853,11 +10960,11 @@
               "description": "Reject duplicate tokens silently (no `invalid` event for accidental dups)."
             },
             {
-              "name": "transform",
+              "name": "normalize",
               "type": {
                 "text": "string"
               },
-              "description": "Normalize tokens on commit. `lowercase` lowercases, `trim` strips leading + trailing whitespace, `strip-spaces` removes all whitespace, `\"\"` (default) preserves the typed value."
+              "description": "Normalize tokens on commit, applied AFTER every candidate is already trimmed of leading/trailing whitespace (unconditional, independent of this attribute). `lowercase` lowercases, `trim` is then a no-op (the trim already happened), `strip-spaces` removes all remaining interior whitespace, `\"\"` (default) applies no further normalization beyond that unconditional trim — case and interior spacing are preserved verbatim. Renamed from `[transform]` (gh#1335) — this is a value-commit normalization step, a different concept from the global Enum·semantic `[transform]` (CSS text-transform display styling: uppercase/lowercase/capitalize/none), not merely a colliding vocabulary."
             },
             {
               "name": "suggestions",
@@ -11006,7 +11113,7 @@
               "type": {
                 "text": "string"
               },
-              "description": "Override text alignment. Note: text-ui defaults to display:inline, so this only takes effect when text-ui is block-like (wrapping or parent display:block/grid). Added v0.6.18 (FB-10)."
+              "description": "Override text alignment. Note: text-ui defaults to display:inline, so this only takes effect when text-ui is block-like (wrapping or parent display:block/grid). Added v0.6.18 (FB-10). Converged onto the global Enum·semantic `[text-align]` physical vocabulary (gh#1335) — `start`/`end` renamed to `left`/`right`; `justify` kept (a genuine physical alignment value, now also supported by the global grammar)."
             },
             {
               "name": "truncate",
@@ -11021,7 +11128,7 @@
               "type": {
                 "text": "string"
               },
-              "description": "Override the variant's font-weight. Maps to --a-weight / --a-weight-medium / --a-weight-semibold / --a-weight-bold. Permissive: unknown values are no-ops (variant weight wins). Added v0.6.18 (FB-10)."
+              "description": "Override the variant's font-weight. Maps to --a-weight / --a-weight-medium / --a-weight-semibold / --a-weight-bold. Permissive: unknown values are no-ops (variant weight wins). Added v0.6.18 (FB-10). `normal` (was `regular`, gh#1335 — converged onto the global Enum·semantic `[weight]` vocabulary's spelling)."
             },
             {
               "name": "textContent",
@@ -11192,7 +11299,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Foundation-providing wrapper — adopts the AdiaUI foundation (design tokens + resets + page-frame + every primitive's CSS) into the document from anywhere in the DOM, so a surface renders fully-styled WITHOUT a hand-wired <link rel=\"stylesheet\"> in <head>. Layout-transparent (display: contents): the element owns no box; children lay out as if it weren't there. Mechanism: it imports the constructable-stylesheet twin of web-components.min.css (byte-identical to the CDN bundle, emitted from the same build buffer) and adopts it once into document.adoptedStyleSheets, deduped — adoption fires at module load, before paint. Coexists with the render-blocking <link> path; both deliver the same bytes. Use a <link> (-> the CDN web-components.min.css) for multi-page / top-level surfaces (cacheable across navigations, zero flash); use <theme-provider> for SPA roots, embedded apps, and dynamic mounts where you do not control <head> (e.g. <embed-shell>, an A2UI surface, a micro-frontend). Theming: the base foundation is OS light/dark via light-dark() tokens. Two opt-in attributes adopt their layer on demand — theme=\"ocean|forest|slate|…\" applies a named preset (adopts the themes layer; matches the [theme] hook) and scale=\"verse|prose\" sets the compact / long-form typographic register (adopts the matching register layer; maps onto the [verse]/[prose] attribute). Each layer is fetched only when its attribute is set, so a bare provider stays lean. Opt-in infra: NOT in the all-in-one @adia-ai/web-components barrel (it carries the whole foundation); import @adia-ai/web-components/components/theme-provider explicitly. Distinct from <frame-ui> (a layout skeleton, owns no CSS delivery) and the page shells (chrome over the same foundation).",
+          "description": "Foundation-providing wrapper — adopts the AdiaUI foundation (design tokens + resets + page-frame + every primitive's CSS) into the document from anywhere in the DOM, so a surface renders fully-styled WITHOUT a hand-wired <link rel=\"stylesheet\"> in <head>. Layout-transparent (display: contents): the element owns no box; children lay out as if it weren't there. Mechanism: it imports the constructable-stylesheet twin of web-components.min.css (byte-identical to the CDN bundle, emitted from the same build buffer) and adopts it once into document.adoptedStyleSheets, deduped — adoption fires at module load, before paint. Coexists with the render-blocking <link> path; both deliver the same bytes. Use a <link> (-> the CDN web-components.min.css) for multi-page / top-level surfaces (cacheable across navigations, zero flash); use <theme-provider> for SPA roots, embedded apps, and dynamic mounts where you do not control <head> (e.g. <embed-shell>, an A2UI surface, a micro-frontend). Theming: the base foundation is OS light/dark via light-dark() tokens. Two opt-in attributes adopt their layer on demand — theme=\"ocean|forest|slate|…\" applies a named preset (adopts the themes layer; matches the [theme] hook) and scale=\"ui-sm|ui-md|ui-lg|content-sm|content-md|content-lg\" sets the sizing register (adopts the matching register layer). Deprecated aliases \"verse\" (→ ui-sm) and \"prose\" (→ content-md) still map onto the legacy [verse]/[prose] attributes; removed at v1.0. Each layer is fetched only when its attribute is set, so a bare provider stays lean. Opt-in infra: NOT in the all-in-one @adia-ai/web-components barrel (it carries the whole foundation); import @adia-ai/web-components/components/theme-provider explicitly. Distinct from <frame-ui> (a layout skeleton, owns no CSS delivery) and the page shells (chrome over the same foundation).",
           "name": "UIThemeProvider",
           "tagName": "theme-provider",
           "superclass": {
@@ -11442,7 +11549,7 @@
                 "text": "string"
               },
               "default": "idle",
-              "description": "Lifecycle state (idle | active | completed | error). Pairs with `spinner` on \"active\" for an in-progress step."
+              "description": "Lifecycle state (idle | active | completed | error) — the values timeline.css currently styles. Pairs with `spinner` on \"active\" for an in-progress step."
             },
             {
               "name": "spinner",
@@ -11454,13 +11561,21 @@
             }
           ],
           "slots": [
+            {
+              "name": "label",
+              "description": "Custom primary-line content; falls through to the [text] prop if not slotted. render() only writes into the component-stamped fallback span (gh#1462 adopt-or-stamp guard)."
+            },
+            {
+              "name": "time",
+              "description": "Custom timestamp/duration content; falls through to the [duration] or [time] prop if not slotted. render() only writes into the component-stamped fallback span (gh#1462 adopt-or-stamp guard)."
+            },
             {
               "name": "icon",
-              "description": "Override the [icon] glyph with a custom slotted element. Use for branded icons, avatars, or non-Phosphor sources. Mutually exclusive with the [icon] attribute."
+              "description": "Override the [icon] glyph with a custom slotted element (custom icon-ui, image, avatar). Mutually exclusive with the [icon] attribute — a consumer-authored slot child wins and is never renamed or removed by render() (gh#1462 adopt-or-stamp guard)."
             },
             {
               "name": "description",
-              "description": "Override slot for rich description markup (inline links, code spans, embedded badges). Renders beneath the primary text at body-subtle typography."
+              "description": "Custom secondary-line content; falls through to [description] prop if not slotted. render() only writes into the component-stamped fallback span (gh#1462 adopt-or-stamp guard)."
             }
           ]
         },
@@ -11666,7 +11781,7 @@
       "declarations": [
         {
           "kind": "class",
-          "description": "Multi-select button group (unlike <segmented-ui> which is single-select). Hosts <toggle-option-ui> children, each independently toggleable; emits change events with the active value set. Use for filter chips or feature flag clusters; for single-select option groups use <segmented-ui> instead.",
+          "description": "DEPRECATED (gh#1369) — use <segmented-ui multiple> + <segment-ui> instead. Multi-select button group (unlike <segmented-ui> which is single-select by default). Hosts <toggle-option-ui> children, each independently toggleable; emits change events with the active value set.",
           "name": "UIToggleGroup",
           "tagName": "toggle-group-ui",
           "superclass": {
@@ -11680,7 +11795,7 @@
                 "text": "boolean"
               },
               "default": "false",
-              "description": "When true, restrict to one active option (single-select)."
+              "description": "When true, restrict to one active option (single-select) — clicking the already-selected option again CLEARS it (empty value), unlike a native radiogroup. Migration (gh#1369): [single]=true maps to plain <segmented-ui> (no [multiple]) — note segmented-ui's single-select never clears on re-click, it's standard radiogroup semantics; the default (false, multi-select) maps to <segmented-ui multiple>."
             },
             {
               "name": "value",
@@ -11708,7 +11823,7 @@
         },
         {
           "kind": "class",
-          "description": "Child of `<toggle-group-ui>`. One toggleable option inside a single-select or multi-select group. Pressed state mirrors `value` against the parent's selection.",
+          "description": "DEPRECATED (gh#1369) — use `<segment-ui>` inside `<segmented-ui multiple>` instead. Child of `<toggle-group-ui>`. One toggleable option inside a single-select or multi-select group. Pressed state mirrors `value` against the parent's selection.",
           "name": "UIToggleOption",
           "tagName": "toggle-option-ui",
           "superclass": {
@@ -12396,6 +12511,14 @@
               "default": "false",
               "description": "Allows selecting multiple files"
             },
+            {
+              "name": "compact",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Icon-only trigger mode (sanctioned mode attribute, gh#1493) — collapses the dropzone to a compact icon button. The prompt text and visible label hide; [label] feeds the trigger's aria-label (\"Upload files\" when unset)."
+            },
             {
               "name": "value",
               "type": {