@adia-ai/a2ui-corpus 0.6.34 → 0.6.36

package/catalog-a2ui_0_9.json

@@ -2024,6 +2024,16 @@
           "type": "string",
           "default": ""
         },
+        "amount": {
+          "description": "Dunning mode only — the unpaid amount as a decimal major-unit number (`24.50`, not minor units like `2450`). Formatted via `Intl.NumberFormat` using [currency] and [lang]. Ignored when [pattern] is not `dunning`.",
+          "type": "number",
+          "default": 0
+        },
+        "cardLast4": {
+          "description": "Dunning mode only — last 4 digits of the declined card. Rendered as \"ending 4242\". Ignored when [pattern] is not `dunning`. Attribute spelling: `card-last4`.",
+          "type": "string",
+          "default": ""
+        },
         "closable": {
           "description": "Whether a close button is displayed. Alias [dismissible] is also accepted (same semantics, different spelling — the corpus and many libraries use both; both map to the same state).",
           "type": "boolean",
@@ -2032,16 +2042,47 @@
         "component": {
           "const": "Alert"
         },
+        "currency": {
+          "description": "Dunning mode only — ISO 4217 currency code driving the `Intl.NumberFormat` style=\"currency\" rendering. Defaults to `USD`.",
+          "type": "string",
+          "default": "USD"
+        },
         "dismissible": {
           "description": "Public alias for [closable] — same semantics. Both attributes render the close button. Use whichever spelling matches your authoring style.",
           "type": "boolean",
           "default": false
         },
+        "dueAt": {
+          "description": "Dunning mode only — ISO 8601 due / failed-at timestamp. Formatted via `Intl.DateTimeFormat`. Ignored when [pattern] is not `dunning`. Attribute spelling: `due-at`.",
+          "type": "string",
+          "default": ""
+        },
         "icon": {
           "description": "Icon identifier displayed before the message content",
           "type": "string",
           "default": ""
         },
+        "pattern": {
+          "description": "Domain pattern mode. Default is empty (standard alert). Setting `pattern=\"dunning\"` switches to billing dunning render mode — stamps a formatted amount + due-date + decline-reason from props and re-dispatches descendant `[data-dunning-action]` button clicks as a unified `dunning-action` event. Spec: SPEC-006.",
+          "type": "string",
+          "enum": [
+            "",
+            "dunning"
+          ],
+          "default": ""
+        },
+        "reason": {
+          "description": "Dunning mode only — decline reason. Drives the leading icon (declined → `x-circle`, expired → `clock`, insufficient → `wallet`, network → `wifi-slash`). One of: `declined`, `expired`, `insufficient`, `network`, or empty.",
+          "type": "string",
+          "enum": [
+            "",
+            "declined",
+            "expired",
+            "insufficient",
+            "network"
+          ],
+          "default": ""
+        },
         "text": {
           "description": "Single-line alert message. For two-line \"headline + body\" alerts, use [title] + [description] instead. For rich content (links, formatting), use the [slot=\"content\"] slot.",
           "type": "string",
@@ -2067,12 +2108,26 @@
       ],
       "unevaluatedProperties": false,
       "x-adiaui": {
-        "anti_patterns": [],
+        "anti_patterns": [
+          {
+            "fix": "<alert-ui pattern=\"dunning\" variant=\"danger\">",
+            "why": "Dunning is always a failure surface; info mis-signals severity.",
+            "wrong": "<alert-ui pattern=\"dunning\" variant=\"info\">"
+          },
+          {
+            "fix": "<alert-ui pattern=\"dunning\" amount=\"24.50\" currency=\"USD\" due-at=\"2026-05-20\">",
+            "why": "Amount baked into title defeats Intl formatting + telemetry.",
+            "wrong": "<alert-ui pattern=\"dunning\" title=\"Payment failed $24.50\">"
+          }
+        ],
         "category": "container",
         "composes": [],
         "events": {
           "close": {
             "description": "Fired when the close button is clicked"
+          },
+          "dunning-action": {
+            "description": "Dunning pattern only — fired when a descendant button with `[data-dunning-action]` is clicked. Detail shape `{ action, amount, currency, dueAt }`; the action string is the value of the `data-dunning-action` attribute (typically `\"update\"` or `\"retry\"`)."
           }
         },
         "examples": [
@@ -2085,6 +2140,11 @@
             "description": "Card with error alert and a retry button for error state display.",
             "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Card\",\n    \"children\": [\n      \"sec\",\n      \"ftr\"\n    ]\n  },\n  {\n    \"id\": \"sec\",\n    \"component\": \"Section\",\n    \"children\": [\n      \"alert\"\n    ]\n  },\n  {\n    \"id\": \"alert\",\n    \"component\": \"Alert\",\n    \"variant\": \"error\",\n    \"title\": \"Something went wrong\",\n    \"description\": \"We encountered an error while loading the data. Please try again.\"\n  },\n  {\n    \"id\": \"ftr\",\n    \"component\": \"Footer\",\n    \"children\": [\n      \"retry\"\n    ]\n  },\n  {\n    \"id\": \"retry\",\n    \"component\": \"Button\",\n    \"text\": \"Retry\",\n    \"icon\": \"refresh\",\n    \"variant\": \"primary\"\n  }\n]",
             "name": "error-state"
+          },
+          {
+            "description": "Billing dunning banner — declined card with retry + update-card actions (SPEC-006).",
+            "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Alert\",\n    \"pattern\": \"dunning\",\n    \"variant\": \"danger\",\n    \"amount\": 24.5,\n    \"currency\": \"USD\",\n    \"dueAt\": \"2026-05-20T00:00:00Z\",\n    \"cardLast4\": \"4242\",\n    \"reason\": \"declined\",\n    \"children\": [\"btn-update\", \"btn-retry\"]\n  },\n  {\n    \"id\": \"btn-update\",\n    \"component\": \"Button\",\n    \"text\": \"Update payment method\",\n    \"variant\": \"primary\",\n    \"slot\": \"actions\"\n  },\n  {\n    \"id\": \"btn-retry\",\n    \"component\": \"Button\",\n    \"text\": \"Retry charge\",\n    \"variant\": \"outline\",\n    \"slot\": \"actions\"\n  }\n]",
+            "name": "dunning-payment-failed"
           }
         ],
         "keywords": [
@@ -2113,6 +2173,9 @@
           "action": {
             "description": "Optional trailing action button (e.g. \"Refresh\", \"Status page\"). Right-aligned in the flex layout. See system-banners pattern for examples."
           },
+          "actions": {
+            "description": "Dunning pattern only — action button stack (typically two `<button-ui>` with `data-dunning-action=\"update\"` and `data-dunning-action=\"retry\"`). Sits below the formatted message in the col layout when `pattern=\"dunning\"`."
+          },
           "close": {
             "description": "Close button. Stamped automatically when `closable` is set; the stamped element is `<button-ui slot=\"close\" icon=\"x\" variant=\"ghost\" size=\"sm\">`. Override by passing a custom `slot=\"close\"` button."
           },
@@ -2886,6 +2949,285 @@
         "version": 1
       }
     },
+    "BillingOverview": {
+      "title": "BillingOverview",
+      "description": "Module-tier billing dashboard that stitches the seven Wave A+B\nbilling primitives into the canonical \"all-billing-on-one-page\"\nsurface — current plan + status header, a KPI strip (monthly\nspend · seats · next invoice), an optional dunning banner when the\naccount is past-due, a plan-picker section for in-app plan changes,\na payment-method-list section, and an invoice-history section.\n\nData-driven via the `account` property — an aggregate snapshot of\nthe customer's billing state ({plan, status, billingCycle,\ncurrentSpend, seats, nextInvoiceDate, paymentMethods[],\ninvoices[], dunning?}). The composite stamps a fixed five-region\nskeleton once on first connect — header · kpis · dunning ·\nplan-picker · payment-methods · invoice-history — then mutates\nper-region nodes via id-keyed in-place diff on every property\nchange. Children primitives (plan-picker, payment-method-list,\ninvoice-history, alert-ui) are stamped as composed tags; this\ncomposite owns the orchestration, not the row chrome.\n\nHigher-level account-action event surfaces consumer-actionable\nintents from descendant primitives. Children carrying\n[data-account-action=\"X\"] or descendant events\n(`plan-action`, `payment-action`, `invoice-action`, `dunning-action`)\nare normalised into a single `account-action` event with\n`detail.action` ∈ {change-plan, add-payment-method, pay-now,\ndownload-invoice, update-card, retry, custom}. The composite\ndoes NOT mutate the data source; consumers wire `account-action`\nagainst their billing backend.\n\nDisplay surface. Extends UIElement, not UIFormElement — child\nprimitives are individually form-bearing (plan-picker,\npayment-method-list) while the host is not.\n\nSpec: docs/specs/implementation-ready/SPEC-004-billing-overview.md.\n",
+      "type": "object",
+      "allOf": [
+        {
+          "$ref": "#/$defs/ComponentCommon"
+        },
+        {
+          "$ref": "#/$defs/CatalogComponentCommon"
+        }
+      ],
+      "properties": {
+        "account": {
+          "description": "Aggregate billing snapshot — source of truth for the whole\ndashboard. Shape:\n  {plan: {id, name, price, cycle, currency, status},\n   status: \"active\" | \"trialing\" | \"past_due\" | \"canceled\" | \"paused\",\n   billingCycle: \"month\" | \"year\",\n   currentSpend: number,\n   seats: {used: number, total: number},\n   nextInvoiceDate: ISO 8601 date string,\n   paymentMethods: [...],          // forwarded to payment-method-list\n   invoices: [...],                // forwarded to invoice-history\n   plans?: [...],                  // forwarded to plan-picker; omitted when planSection is \"hidden\"\n   dunning?: {amount, currency, dueAt, cardLast4?, reason?}}\nNull + no `data-stream-src` renders the empty state.\n",
+          "type": "object",
+          "default": null
+        },
+        "component": {
+          "const": "BillingOverview"
+        },
+        "currency": {
+          "description": "Default ISO 4217 currency for all amount formatting. Overridable\nper-record (plan.currency, invoice.currency, etc.).\n",
+          "type": "string",
+          "default": "USD"
+        },
+        "data-stream-src": {
+          "description": "Optional endpoint returning the full account snapshot. On\nsuccessful load, `account` is replaced and a `load` event fires;\non failure an `error` event fires.\n",
+          "type": "string",
+          "default": ""
+        },
+        "loading": {
+          "description": "Renders skeleton placeholders in the header + KPI strip while\ndata is fetching. Sets aria-busy on the host. Forwarded to\nchild composites that accept [loading] (plan-picker,\npayment-method-list, invoice-history).\n",
+          "$ref": "#/$defs/DynamicBoolean"
+        },
+        "locale": {
+          "description": "Locale for Intl.NumberFormat (currency) and Intl.DateTimeFormat\n(dates). Defaults to document.documentElement.lang (or \"en-US\"\nwhen absent).\n",
+          "type": "string",
+          "default": ""
+        },
+        "variant": {
+          "description": "Layout variant. `full` shows every section. `compact` collapses\nthe plan-picker section and renders only the KPI strip + payment\nmethods + invoice history (the canonical \"settings billing\"\nshape). `enterprise` hides plan-picker entirely (no self-serve\nplan changes) and keeps the rest.\n",
+          "type": "string",
+          "enum": [
+            "full",
+            "compact",
+            "enterprise"
+          ],
+          "default": "full"
+        }
+      },
+      "required": [
+        "component",
+        "account"
+      ],
+      "unevaluatedProperties": false,
+      "x-adiaui": {
+        "anti_patterns": [
+          {
+            "fix": "{\"component\": \"BillingOverview\", \"account\":\n  {\"plan\": {\"id\":\"p_pro\",\"name\":\"Pro\",\"price\":48,\"cycle\":\"month\",\"currency\":\"USD\",\"status\":\"active\"},\n   \"status\": \"active\",\n   \"billingCycle\": \"month\",\n   \"currentSpend\": 48,\n   \"seats\": {\"used\": 4, \"total\": 10},\n   \"nextInvoiceDate\": \"2026-06-01\",\n   \"paymentMethods\": [...],\n   \"invoices\": [...]}}\n",
+            "why": "Missing the required `account` prop. The composite renders the\nempty state. A dashboard without data has nothing to show.\n",
+            "wrong": "{\"component\": \"BillingOverview\"}\n"
+          },
+          {
+            "fix": "Render the BillingOverview composite on its own route\n(typically `/settings/billing` or `/billing`).\n",
+            "why": "The dashboard is a route, not a modal. Modal traps focus + clips\ncontent; the composite is designed for the full /billing page.\n",
+            "wrong": "{\"component\": \"Modal\", \"children\":\n  [{\"component\": \"BillingOverview\", \"account\": {...}}]}\n"
+          },
+          {
+            "fix": "Provide a dunning object alongside the past_due status:\n<billing-overview-ui account='{\"status\":\"past_due\",\"dunning\":{\"amount\":48,\"currency\":\"USD\",\"dueAt\":\"2026-05-20\"}}'></billing-overview-ui>\n",
+            "why": "Past-due status without an `account.dunning` payload. The\ncomposite cannot render the dunning banner (it needs amount +\ndue-at + currency to format the alert message).\n",
+            "wrong": "<billing-overview-ui account='{\"status\":\"past_due\"}'></billing-overview-ui>\n"
+          },
+          {
+            "fix": "Either pass `account.plans` OR set `variant=\"compact\"` to hide\nthe plan-picker section entirely.\n",
+            "why": "`variant=full` requires `account.plans` so the plan-picker\nsection has rows to render. Without plans, the section renders\nits own empty-state and looks broken.\n",
+            "wrong": "<billing-overview-ui variant=\"full\" account='{\"plan\":{...},\"status\":\"active\"}'></billing-overview-ui>\n"
+          }
+        ],
+        "category": "container",
+        "composes": [
+          "card-ui",
+          "stat-ui",
+          "tag-ui",
+          "text-ui",
+          "alert-ui",
+          "plan-picker-ui",
+          "payment-method-list-ui",
+          "invoice-history-ui",
+          "button-ui",
+          "icon-ui"
+        ],
+        "events": {
+          "account-action": {
+            "description": "Unified account-action event — normalises every actionable\nintent from descendant primitives into a single bubbling event.\nHandler can act on `detail.action` without subscribing to four\ndifferent child event names. Bubbles.\n",
+            "detail": {
+              "action": {
+                "description": "One of \"change-plan\" | \"add-payment-method\" | \"pay-now\" |\n\"download-invoice\" | \"update-card\" | \"retry\" | \"select-plan\"\n| \"remove-payment-method\" | \"set-default-payment-method\" |\nor any consumer-defined value carried on a descendant\n[data-account-action] attribute.\n",
+                "type": "string"
+              },
+              "payload": {
+                "description": "Forwarded detail from the originating event (e.g. the\ninvoice record, the plan id, the dunning amount). Shape\nvaries by source.\n",
+                "type": "object"
+              },
+              "source": {
+                "description": "The originating primitive — \"plan-picker\" | \"payment-method-list\"\n| \"invoice-history\" | \"alert-dunning\" | \"header\" | \"custom\".\n",
+                "type": "string"
+              }
+            }
+          },
+          "error": {
+            "description": "Fired when a `data-stream-src` fetch fails. Bubbles.\n",
+            "detail": {
+              "reason": {
+                "description": "One of `fetch-failed`.",
+                "type": "string"
+              }
+            }
+          },
+          "load": {
+            "description": "Fired when `data-stream-src` finishes a successful fetch and\n`account` is populated. Bubbles.\n",
+            "detail": {
+              "account": {
+                "description": "The loaded account snapshot.",
+                "type": "object"
+              }
+            }
+          }
+        },
+        "examples": [
+          {
+            "description": "Active Pro plan with 4 saved cards + 3 invoices.",
+            "a2ui": "[\n  {\n    \"id\": \"bo-pro\",\n    \"component\": \"BillingOverview\",\n    \"variant\": \"full\",\n    \"currency\": \"USD\",\n    \"account\": {\n      \"plan\": {\n        \"id\": \"p_pro\",\n        \"name\": \"Pro\",\n        \"price\": 48,\n        \"cycle\": \"month\",\n        \"currency\": \"USD\",\n        \"status\": \"active\"\n      },\n      \"status\": \"active\",\n      \"billingCycle\": \"month\",\n      \"currentSpend\": 48,\n      \"seats\": {\"used\": 4, \"total\": 10},\n      \"nextInvoiceDate\": \"2026-06-01\",\n      \"plans\": [],\n      \"paymentMethods\": [],\n      \"invoices\": []\n    }\n  }\n]\n",
+            "name": "active-pro-account"
+          },
+          {
+            "description": "Past-due account with dunning banner above plan section.",
+            "a2ui": "[\n  {\n    \"id\": \"bo-past-due\",\n    \"component\": \"BillingOverview\",\n    \"variant\": \"full\",\n    \"currency\": \"USD\",\n    \"account\": {\n      \"plan\": {\n        \"id\": \"p_pro\",\n        \"name\": \"Pro\",\n        \"price\": 48,\n        \"cycle\": \"month\",\n        \"currency\": \"USD\",\n        \"status\": \"past_due\"\n      },\n      \"status\": \"past_due\",\n      \"billingCycle\": \"month\",\n      \"currentSpend\": 48,\n      \"seats\": {\"used\": 4, \"total\": 10},\n      \"nextInvoiceDate\": \"2026-05-20\",\n      \"dunning\": {\n        \"amount\": 48,\n        \"currency\": \"USD\",\n        \"dueAt\": \"2026-05-20\",\n        \"cardLast4\": \"4242\",\n        \"reason\": \"declined\"\n      },\n      \"plans\": [],\n      \"paymentMethods\": [],\n      \"invoices\": []\n    }\n  }\n]\n",
+            "name": "past-due-account"
+          }
+        ],
+        "keywords": [
+          "billing",
+          "overview",
+          "dashboard",
+          "account",
+          "subscription",
+          "plan",
+          "invoice",
+          "payment-method",
+          "usage",
+          "dunning",
+          "past-due"
+        ],
+        "name": "UIBillingOverview",
+        "related": [
+          "PlanPicker",
+          "PaymentMethodList",
+          "InvoiceHistory",
+          "InvoiceDetail",
+          "PaymentMethodForm",
+          "Alert",
+          "Stat"
+        ],
+        "slots": {
+          "after-invoice-history": {
+            "description": "Optional content slotted below the invoice-history section\n(e.g. tax-document download row, billing-contact form).\n"
+          },
+          "before-plan-picker": {
+            "description": "Optional content slotted above the plan-picker section (e.g. a\npromo banner, an annual-savings callout).\n"
+          },
+          "empty": {
+            "description": "Custom empty-state content when there's no account snapshot\nAND no data-stream-src. Falls back to a default empty-state\nmessage.\n"
+          },
+          "header-actions": {
+            "description": "Optional action row in the dashboard header (top-right). Used\nfor consumer-authored \"Contact sales\", \"Cancel subscription\",\netc. The composite NEVER stamps a default toolbar.\n"
+          }
+        },
+        "states": [
+          {
+            "description": "Default — account rendered, ready for interaction.",
+            "name": "idle"
+          },
+          {
+            "description": "A `data-stream-src` fetch is in flight or [loading] is set.",
+            "attribute": "loading",
+            "name": "loading"
+          },
+          {
+            "description": "No account snapshot + no data-stream-src.",
+            "attribute": "empty",
+            "name": "empty"
+          },
+          {
+            "description": "Account is past-due (computed from `account.status === \"past_due\"`).\nStamps the dunning banner if `account.dunning` is present.\n",
+            "attribute": "past-due",
+            "name": "past-due"
+          },
+          {
+            "description": "Account is trialing (computed from `account.status === \"trialing\"`).\n",
+            "attribute": "trial",
+            "name": "trial"
+          },
+          {
+            "description": "Last `data-stream-src` fetch failed.",
+            "attribute": "error",
+            "name": "error"
+          }
+        ],
+        "status": "experimental",
+        "synonyms": {
+          "account": [
+            "subscription",
+            "membership"
+          ],
+          "billing": [
+            "subscription",
+            "account-billing"
+          ],
+          "overview": [
+            "dashboard",
+            "summary"
+          ]
+        },
+        "tag": "billing-overview-ui",
+        "tokens": {
+          "--billing-overview-bg": {
+            "description": "Host page background. Defaults to transparent.",
+            "default": "transparent"
+          },
+          "--billing-overview-gap": {
+            "description": "Vertical gap between dashboard sections.",
+            "default": "var(--a-space-5)"
+          },
+          "--billing-overview-header-gap": {
+            "description": "Gap between the plan title block and the status badge cluster.",
+            "default": "var(--a-space-3)"
+          },
+          "--billing-overview-kpi-columns": {
+            "description": "Grid column template for the KPI strip. Falls back to a 3-column\nauto-fit when narrowed below 40rem (container query).\n",
+            "default": "repeat(3, minmax(0, 1fr))"
+          },
+          "--billing-overview-kpi-gap": {
+            "description": "Gap between KPI stat cards.",
+            "default": "var(--a-space-3)"
+          },
+          "--billing-overview-meta-fg": {
+            "description": "Foreground color for secondary metadata in the header.",
+            "default": "var(--a-fg-muted)"
+          },
+          "--billing-overview-px": {
+            "description": "Horizontal padding around dashboard content.",
+            "default": "var(--a-space-5)"
+          },
+          "--billing-overview-py": {
+            "description": "Vertical padding around dashboard content.",
+            "default": "var(--a-space-5)"
+          },
+          "--billing-overview-section-heading-fg": {
+            "description": "Foreground color for section heading labels.",
+            "default": "var(--a-fg)"
+          },
+          "--billing-overview-section-heading-size": {
+            "description": "Font size for section heading labels.",
+            "default": "var(--a-text-base, 1rem)"
+          },
+          "--billing-overview-section-heading-weight": {
+            "description": "Font weight for section heading labels.",
+            "default": "var(--a-weight-semibold, 600)"
+          },
+          "--billing-overview-section-radius": {
+            "description": "Section card corner radius.",
+            "default": "var(--a-radius-lg)"
+          }
+        },
+        "traits": [],
+        "version": 1
+      }
+    },
     "Block": {
       "title": "Block",
       "description": "Generic padded / margined content wrapper. Applies a configurable\npadding + margin scale via [padding] / [margin] attribute props,\nmapping to the canonical spacing tokens. Use as a lightweight\nspacing wrapper when <section-ui> would imply chrome the parent\ncontainer doesn't own. Not a layout primitive (no flex / grid) —\nfor layout use <col-ui> / <row-ui> / <stack-ui> / <grid-ui>.\n",
@@ -3378,6 +3720,16 @@
           "type": "string",
           "default": ""
         },
+        "rangeEnd": {
+          "description": "End of a date range (ISO YYYY-MM-DD). See `rangeStart` for the full contract.",
+          "type": "string",
+          "default": ""
+        },
+        "rangeStart": {
+          "description": "Start of a date range (ISO YYYY-MM-DD). When both rangeStart and rangeEnd are set + ordered, day cells strictly between the endpoints get `[data-in-range]` stamped for visual continuity. Used by `<date-range-picker-ui>` which pushes the same from/to onto both calendar panes. Endpoints themselves render via the `value` prop's `[data-selected]` state.",
+          "type": "string",
+          "default": ""
+        },
         "readonly": {
           "description": "Blocks selection but allows month navigation.",
           "type": "boolean",
@@ -4519,7 +4871,7 @@
         ],
         "slots": {
           "default": {
-            "description": "Default — primary input child (typically <chat-input-ui> or <input-ui submit-on-enter>)."
+            "description": "Default — primary input child (typically <chat-input-ui>; <input-ui> also works — both emit a `submit` event on Enter without Shift)."
           },
           "attach": {
             "description": "Future — attachment trigger button (paperclip icon to upload)."
@@ -4763,7 +5115,7 @@
         "composes": [],
         "events": {
           "submit": {
-            "description": "Fires when the user presses Enter (without Shift) in the textarea OR clicks the built-in send button. The composer suppresses submission while `[loading]` is set.",
+            "description": "Fires when the user presses Enter (without Shift) in the textarea OR clicks the built-in send button. Unconditional — there is no [submit-on-enter] opt-in or opt-out attribute; Enter→submit is delegated from the inner <textarea-ui> which always emits a `submit` event on Enter without Shift. The composer suppresses submission while `[loading]` is set.",
             "detail": {
               "model": {
                 "description": "Currently selected model value (empty if no model picker).",
@@ -4988,7 +5340,7 @@
         ],
         "slots": {
           "default": {
-            "description": "Bespoke children compose here in document order — typically <chat-thread> (with optional <chat-empty> inside) for the message surface, then <chat-composer> wrapping a <chat-input-ui submit-on-enter> for the input. Optional <chat-header>, <chat-sidebar slot=\"leading|trailing\">, <chat-status>."
+            "description": "Bespoke children compose here in document order — typically <chat-thread> (with optional <chat-empty> inside) for the message surface, then <chat-composer> wrapping a <chat-input-ui> for the input. Optional <chat-header>, <chat-sidebar slot=\"leading|trailing\">, <chat-status>."
           }
         },
         "states": [
@@ -6954,9 +7306,9 @@
         "version": 1
       }
     },
-    "DateRangePicker": {
-      "title": "DateRangePicker",
-      "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-picker-ui> twice; emits {from, to} ISO 8601 dates. Optional comparison-range mode emits a secondary range for analytics surfaces.",
+    "DashboardLayout": {
+      "title": "DashboardLayout",
+      "description": "Module-tier dashboard-body composite. Crystallizes the recurring\n\"toolbar + KPI grid + chart area + table\" dashboard layout into a\nsingle primitive with four named regions (toolbar / kpis / charts /\ntable) plus an optional aside column. Each region is filled by\nconsumer-supplied <card-ui>s; the composite owns band sizing,\nresponsive breakpoints, and a [density] knob that propagates to\nevery descendant primitive via the parametric --a-density cascade.\n\nSits inside an <admin-page-body>; replaces the hand-rolled\n<col-ui gap=\"4\"> + nested <grid-ui> + <card-ui> chains every\nanalytics consumer reinvents today. Per ADR-0033 (Light-DOM\nsubstrate) — slot= attributes are decorative metadata; CSS rules\nmatch `:scope > [slot=\"X\"]` to position bands in DOM order.\n\nSpec: docs/specs/implementation-ready/SPEC-018-dashboard-layout.md.\n",
       "type": "object",
       "allOf": [
         {
@@ -6967,64 +7319,316 @@
         }
       ],
       "properties": {
-        "required": {
-          "description": "Required for validation when inside a `<form>`.",
-          "type": "boolean",
-          "default": false
-        },
-        "compareValue": {
-          "description": "Comparison range when `[comparison]` is set. Same `{from, to}` shape as `value`.",
-          "$ref": "#/$defs/DynamicString"
-        },
-        "comparison": {
-          "description": "Enable comparison-range mode. Renders a second preset cluster and emits a secondary range under `<name>-compare`.",
-          "type": "boolean",
-          "default": false
+        "chart-split": {
+          "description": "Chart-band column split. Empty string = single full-width chart;\n`2` = two equal columns; `2:1` / `3:2` / `3:1` = asymmetric\nratios. Collapses to single column at narrow widths (≤48em).\n",
+          "type": "string",
+          "enum": [
+            "",
+            "2",
+            "2:1",
+            "3:2",
+            "3:1"
+          ],
+          "default": ""
         },
         "component": {
-          "const": "DateRangePicker"
-        },
-        "disabled": {
-          "description": "Block all interaction. Trigger remains rendered but does not open the popover.",
-          "type": "boolean",
-          "default": false
+          "const": "DashboardLayout"
         },
-        "format": {
-          "description": "Trigger button date format. `short`: `Jan 1, 2026`; `long`: `January 1, 2026`; `iso`: `2026-01-01`.",
+        "density": {
+          "description": "Spacing scale — propagates --a-density to descendant primitives\nvia CSS custom-property cascade. Empty string inherits whatever\ndensity is in effect on an ancestor (the default — respects an\napp-level density theme). `compact` / `comfortable` / `spacious`\nexplicitly override.\n",
           "type": "string",
           "enum": [
-            "short",
-            "long",
-            "iso"
+            "",
+            "comfortable",
+            "compact",
+            "spacious"
           ],
-          "default": "short"
-        },
-        "max": {
-          "description": "Latest selectable ISO date (inclusive). Days after are disabled in both panes.",
-          "type": "string",
           "default": ""
         },
-        "min": {
-          "description": "Earliest selectable ISO date (inclusive). Days before are disabled in both panes.",
+        "gap": {
+          "description": "Override band-to-band vertical gap. Empty string = the\ndensity-modulated default (--a-space-4 at comfortable). Numeric\n`1`..`6` selects the corresponding --a-space-N step.\n",
           "type": "string",
           "default": ""
         },
-        "name": {
-          "description": "Form field name for form data submission. The selected range serializes as JSON `{\"from\":\"...\",\"to\":\"...\"}` under this key.",
+        "kpi-columns": {
+          "description": "Target column count for the KPI band at desktop width. Range 2-6;\nout-of-range values fall back to 4. Container-query collapse\nreduces this at narrower widths (≤48em → 2; ≤32em → 1).\n",
           "type": "string",
-          "default": ""
-        },
-        "noPresets": {
-          "description": "Hide the preset side rail.",
-          "type": "boolean",
-          "default": false
+          "enum": [
+            "2",
+            "3",
+            "4",
+            "5",
+            "6"
+          ],
+          "default": "4"
         },
-        "open": {
-          "description": "Whether the popover is currently open.",
+        "loading": {
+          "description": "Marks the composite as data-loading. Sets aria-busy=true on the\nhost and dims slotted children to 60% opacity with pointer-events\nsuppressed. Skeletons inside slotted cards continue to render\nnormally; the dim is on top of them.\n",
           "type": "boolean",
           "default": false
-        },
-        "placeholder": {
+        }
+      },
+      "required": [
+        "component"
+      ],
+      "unevaluatedProperties": false,
+      "x-adiaui": {
+        "anti_patterns": [
+          {
+            "description": "Child without a [slot] attribute. Lands in the implicit default\nregion and breaks the band layout. Every direct child MUST\ndeclare its slot — toolbar / kpis / charts / table / aside.\n",
+            "right": "<dashboard-layout-ui>\n  <card-ui slot=\"kpis\">...</card-ui>\n</dashboard-layout-ui>\n",
+            "rule": "Every direct child of dashboard-layout-ui declares its slot.\n",
+            "wrong": "<dashboard-layout-ui>\n  <card-ui><!-- no slot -->...</card-ui>\n</dashboard-layout-ui>\n"
+          },
+          {
+            "description": "Nested DashboardLayout. Two density containers fight over the\n--a-density cascade. The inner one re-creates a 2-column layout\ninside a charts band, which is incoherent.\n",
+            "right": "<tabs-ui>\n  <tab-panel-ui><dashboard-layout-ui>...</dashboard-layout-ui></tab-panel-ui>\n  <tab-panel-ui><dashboard-layout-ui>...</dashboard-layout-ui></tab-panel-ui>\n</tabs-ui>\n",
+            "rule": "For nested dashboards, use sibling DashboardLayouts switched by\nTabs — not DashboardLayout inside DashboardLayout.\n",
+            "wrong": "<dashboard-layout-ui>\n  <dashboard-layout-ui slot=\"charts\">...</dashboard-layout-ui>\n</dashboard-layout-ui>\n"
+          },
+          {
+            "description": "kpi-columns out of range. Eight cards in a row is too narrow\nto be legible at typical container widths; the container-query\ncollapse (≤48em → 2 cols, ≤32em → 1 col) won't help when N is\nalready that large at desktop.\n",
+            "right": "<dashboard-layout-ui kpi-columns=\"4\">...</dashboard-layout-ui>\n",
+            "rule": "kpi-columns ∈ {2,3,4,5,6}. Split into 2 rows of 4 by composing\n2 DashboardLayouts vertically if 8 cards are truly necessary.\n",
+            "wrong": "<dashboard-layout-ui kpi-columns=\"8\">...</dashboard-layout-ui>\n"
+          }
+        ],
+        "category": "layout",
+        "composes": [
+          "card-ui",
+          "grid-ui",
+          "row-ui",
+          "stat-ui",
+          "chart-ui",
+          "table-ui"
+        ],
+        "events": {
+          "density-change": {
+            "description": "Fired when [density] changes (programmatic or via setDensity()).\nBubbles; detail.density carries the new value.\n",
+            "detail": {
+              "density": {
+                "description": "The new density value (comfortable / compact / spacious).",
+                "type": "string"
+              }
+            }
+          },
+          "region-empty": {
+            "description": "Fired when a slot transitions from having content to being empty\n(consumer-driven removal of the last child for that slot).\nUseful for parent-level adjust-layout logic.\n",
+            "detail": {
+              "region": {
+                "description": "The slot name that became empty (toolbar / kpis / charts / table / aside).",
+                "type": "string"
+              }
+            }
+          }
+        },
+        "examples": [
+          {
+            "description": "KPI-strip + 2:1 chart split + table band inside an admin page.\n",
+            "a2ui": "[\n  {\n    \"id\": \"dash-1\",\n    \"component\": \"DashboardLayout\",\n    \"density\": \"\",\n    \"kpiColumns\": \"4\",\n    \"chartSplit\": \"2:1\",\n    \"children\": [\"dash-toolbar\", \"dash-kpis\", \"dash-charts\", \"dash-table\"]\n  },\n  {\n    \"id\": \"dash-toolbar\",\n    \"component\": \"Row\",\n    \"slot\": \"toolbar\"\n  },\n  {\n    \"id\": \"dash-kpis\",\n    \"component\": \"Group\",\n    \"slot\": \"kpis\"\n  },\n  {\n    \"id\": \"dash-charts\",\n    \"component\": \"Group\",\n    \"slot\": \"charts\"\n  },\n  {\n    \"id\": \"dash-table\",\n    \"component\": \"Card\",\n    \"slot\": \"table\"\n  }\n]\n",
+            "name": "canonical-analytics-dashboard"
+          },
+          {
+            "description": "Six-KPI dashboard at compact density (power-user view).\n",
+            "a2ui": "[\n  {\n    \"id\": \"dash-2\",\n    \"component\": \"DashboardLayout\",\n    \"density\": \"compact\",\n    \"kpiColumns\": \"6\"\n  }\n]\n",
+            "name": "compact-six-kpi"
+          },
+          {
+            "description": "Dashboard with a sticky aside column carrying a live activity feed.\n",
+            "a2ui": "[\n  {\n    \"id\": \"dash-3\",\n    \"component\": \"DashboardLayout\",\n    \"chartSplit\": \"2\",\n    \"children\": [\"d3-aside\"]\n  },\n  {\n    \"id\": \"d3-aside\",\n    \"component\": \"Card\",\n    \"slot\": \"aside\"\n  }\n]\n",
+            "name": "with-aside-feed"
+          }
+        ],
+        "keywords": [
+          "dashboard",
+          "dashboard-layout",
+          "analytics",
+          "kpi-grid",
+          "chart-area",
+          "dashboard-body",
+          "admin-dashboard",
+          "reporting",
+          "metrics-page",
+          "layout-container"
+        ],
+        "name": "UIDashboardLayout",
+        "related": [
+          "AdminPageBody",
+          "AdminPage",
+          "Card",
+          "Grid",
+          "Stat",
+          "Chart",
+          "Table",
+          "DateRangeSelector"
+        ],
+        "slots": {
+          "aside": {
+            "description": "Optional right-side panel (e.g., live activity feed). When set,\npromotes the host to a 2-column grid with the aside as a sticky\nright column on desktop. Collapses when empty.\n"
+          },
+          "charts": {
+            "description": "Chart band — wrapper containing 1-3 <card-ui> with <chart-ui>.\n[chart-split] drives the grid columns. Collapses when empty.\n"
+          },
+          "kpis": {
+            "description": "KPI band — typically a wrapper element containing N <card-ui>\ninstances each with one <stat-ui>. The composite drives the\ngrid template via [kpi-columns]. Collapses when empty.\n"
+          },
+          "table": {
+            "description": "Table band — typically a single <card-ui slot=\"table\"> containing\n<table-ui> and optional <pagination-ui> in the footer. Full-bleed\nacross the main column. Collapses when empty.\n"
+          },
+          "toolbar": {
+            "description": "Top band — filter chips, segmented date range, global controls.\nTypically a single <row-ui> or <date-range-selector-ui> (SPEC-019).\nCollapses when empty (no row reserved).\n"
+          }
+        },
+        "states": [
+          {
+            "description": "Default; all regions interactive.",
+            "name": "idle"
+          },
+          {
+            "description": "Data fetch in progress; aria-busy=true; content dimmed.",
+            "attribute": "loading",
+            "name": "loading"
+          },
+          {
+            "description": "Compact-density variant; tighter band gaps + density cascade.",
+            "attribute": "density",
+            "name": "compact"
+          },
+          {
+            "description": "Spacious-density variant; looser band gaps + density cascade.",
+            "attribute": "density",
+            "name": "spacious"
+          }
+        ],
+        "status": "experimental",
+        "synonyms": {
+          "charts": [
+            "chart-area",
+            "viz",
+            "graphs"
+          ],
+          "dashboard": [
+            "analytics",
+            "report",
+            "overview",
+            "metrics"
+          ],
+          "kpi": [
+            "metric",
+            "stat",
+            "measure"
+          ],
+          "layout": [
+            "container",
+            "grid",
+            "frame",
+            "shell"
+          ],
+          "tags": [
+            "DashboardLayout",
+            "Dashboard",
+            "AnalyticsDashboard",
+            "MetricsDashboard"
+          ]
+        },
+        "tag": "dashboard-layout-ui",
+        "tokens": {
+          "--dashboard-layout-aside-width": {
+            "description": "Aside column width when [slot=\"aside\"] is present.",
+            "default": "20em"
+          },
+          "--dashboard-layout-chart-gap": {
+            "description": "Inter-card gap inside the chart band.",
+            "default": "var(--a-space-4)"
+          },
+          "--dashboard-layout-gap": {
+            "description": "Band-to-band vertical gap.",
+            "default": "var(--a-space-4)"
+          },
+          "--dashboard-layout-kpi-gap": {
+            "description": "Inter-card gap inside the KPI band.",
+            "default": "var(--a-space-2)"
+          },
+          "--dashboard-layout-padding": {
+            "description": "Outer padding around the composite.",
+            "default": "0"
+          }
+        },
+        "traits": [],
+        "version": 1
+      }
+    },
+    "DateRangePicker": {
+      "title": "DateRangePicker",
+      "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-picker-ui> twice; emits {from, to} ISO 8601 dates. Optional comparison-range mode emits a secondary range for analytics surfaces.",
+      "type": "object",
+      "allOf": [
+        {
+          "$ref": "#/$defs/ComponentCommon"
+        },
+        {
+          "$ref": "#/$defs/CatalogComponentCommon"
+        }
+      ],
+      "properties": {
+        "required": {
+          "description": "Required for validation when inside a `<form>`.",
+          "type": "boolean",
+          "default": false
+        },
+        "compareValue": {
+          "description": "Comparison range when `[comparison]` is set. Same `{from, to}` shape as `value`.",
+          "$ref": "#/$defs/DynamicString"
+        },
+        "comparison": {
+          "description": "Enable comparison-range mode. Renders a second preset cluster and emits a secondary range under `<name>-compare`.",
+          "type": "boolean",
+          "default": false
+        },
+        "component": {
+          "const": "DateRangePicker"
+        },
+        "disabled": {
+          "description": "Block all interaction. Trigger remains rendered but does not open the popover.",
+          "type": "boolean",
+          "default": false
+        },
+        "format": {
+          "description": "Trigger button date format. `short`: `Jan 1, 2026`; `long`: `January 1, 2026`; `iso`: `2026-01-01`.",
+          "type": "string",
+          "enum": [
+            "short",
+            "long",
+            "iso"
+          ],
+          "default": "short"
+        },
+        "max": {
+          "description": "Latest selectable ISO date (inclusive). Days after are disabled in both panes.",
+          "type": "string",
+          "default": ""
+        },
+        "min": {
+          "description": "Earliest selectable ISO date (inclusive). Days before are disabled in both panes.",
+          "type": "string",
+          "default": ""
+        },
+        "name": {
+          "description": "Form field name for form data submission. The selected range serializes as JSON `{\"from\":\"...\",\"to\":\"...\"}` under this key.",
+          "type": "string",
+          "default": ""
+        },
+        "noPresets": {
+          "description": "Hide the preset side rail.",
+          "type": "boolean",
+          "default": false
+        },
+        "open": {
+          "description": "Whether the popover is currently open.",
+          "type": "boolean",
+          "default": false
+        },
+        "placeholder": {
           "description": "Text shown in the trigger when the value is empty.",
           "type": "string",
           "default": "Select range"
@@ -8724,6 +9328,11 @@
           "type": "boolean",
           "default": false
         },
+        "collapsible": {
+          "description": "Reflected CSS-state marker — declares this sidebar's collapse\naffordance is exposed to authors (matching the <admin-sidebar>\nconvention). The .toggle() / .collapse() / .expand() public API\nis always callable; [collapsible] is the attribute consumers\nkey CSS rules off (e.g. showing a toggle button when present).\nSet on the canonical demos in editor-sidebar.examples.html.\n",
+          "type": "boolean",
+          "default": false
+        },
         "component": {
           "const": "EditorSidebar"
         },
@@ -10664,9 +11273,9 @@
         "version": 1
       }
     },
-    "Input": {
-      "title": "Input",
-      "description": "Text input field with contenteditable surface. Supports prefix/suffix icons, label, form participation, and a `type=\"number\"` mode that renders [+]/[-] stepper buttons, numeric input filtering, and ARIA spinbutton semantics — no native `<input type=\"number\">` under the hood. Password type uses a native `<input>` (only path that still wraps native, for `-webkit-text-security` disc masking).",
+    "InlineMessage": {
+      "title": "InlineMessage",
+      "description": "In-flow message glyph + text used in form-field rows for validation\nfeedback, hint copy, and inline confirmations. Distinguished from\n<alert-ui> (banner / surface-bearing notice) by carrying no surface\nfill, no border, no padding box — severity is foreground color +\nicon only. Variants map to severity (info / success / warning /\ndanger). Nests inside <field-ui>, <col-ui>, <row-ui> without\nbreaking field rhythm. Non-interactive annotation only.\n",
       "type": "object",
       "allOf": [
         {
@@ -10677,88 +11286,229 @@
         }
       ],
       "properties": {
-        "type": {
-          "description": "Input type. `password` wraps a native `<input>` for disc masking; `number` renders a contenteditable + stepper buttons (no native input). All other types use plain contenteditable.",
-          "type": "string",
-          "enum": [
-            "text",
-            "email",
-            "password",
-            "number",
-            "tel",
-            "url",
-            "search",
-            "date",
-            "datetime-local",
-            "time",
-            "month",
-            "week",
-            "color"
-          ],
-          "default": "text"
-        },
-        "required": {
-          "description": "Marks the field as required for form validation. Sets aria-required.",
-          "type": "boolean",
-          "default": false
-        },
-        "autocomplete": {
-          "description": "Browser autofill behavior per HTML autocomplete spec. Routed via setAttribute to the host element. Common values: off, on, cc-number, cc-exp, cc-csc, cc-name, email, username, current-password, new-password, one-time-code, given-name, family-name, street-address, postal-code.",
-          "type": "string",
-          "default": ""
-        },
         "component": {
-          "const": "Input"
-        },
-        "disabled": {
-          "description": "Disables interaction, removes contenteditable, and dims the control",
-          "type": "boolean",
-          "default": false
+          "const": "InlineMessage"
         },
-        "error": {
-          "description": "Validation error message. Set automatically by constraint validation or manually via setInvalid().",
-          "type": "string",
-          "default": ""
+        "icon": {
+          "description": "Phosphor glyph override; each [variant] ships a sensible default (info / check-circle / warning / x-circle).",
+          "$ref": "#/$defs/DynamicString"
         },
-        "inputmode": {
-          "description": "Mobile keyboard hint per HTML inputmode spec. Routed via setAttribute to the host element. Values: text, decimal, numeric, tel, search, email, url.",
+        "live": {
+          "description": "Sets `aria-live` on the host for dynamic message updates. Empty = no live region (static annotation).",
           "type": "string",
           "enum": [
-            "text",
-            "decimal",
-            "numeric",
-            "tel",
-            "search",
-            "email",
-            "url",
-            "none"
+            "",
+            "polite",
+            "assertive"
           ],
-          "default": null
-        },
-        "label": {
-          "description": "Inline label rendered as a leading caption inside the input chrome, between any prefix and the value. Wires aria-labelledby on the editable surface. For stacked label / hint / error compositions, wrap with field-ui.",
-          "type": "string",
-          "default": ""
-        },
-        "locale": {
-          "description": "BCP-47 locale tag for `type=\"number\"`, e.g. `de-DE`, `fr-FR`, `en-IN`. When set, the input accepts both `.` AND the locale's decimal separator (e.g. `,` in de-DE), uses `Intl.NumberFormat` for display, and groups thousands on blur (e.g. en-US `1,234,567.89`, de-DE `1.234.567,89`). On focus, the input reverts to ungrouped form for easy editing. `.value` always stores the ungrouped, locale-decimal form so `Number(#toCanonical(v))` round-trips. Default empty = en-US-equivalent path (no behavior change).",
-          "type": "string",
           "default": ""
         },
-        "max": {
-          "description": "Maximum numeric value. Applies when `type=\"number\"`. Clamps + drives aria-valuemax + the [+] button's disabled state.",
-          "type": "number",
-          "default": null
-        },
-        "maxlength": {
-          "description": "Maximum character length for validation",
-          "type": "number",
-          "default": null
+        "text": {
+          "description": "Single-line message text. Default-slot content wins when present.",
+          "$ref": "#/$defs/DynamicString"
         },
-        "min": {
-          "description": "Minimum numeric value. Applies when `type=\"number\"`. Clamps + drives aria-valuemin + the [-] button's disabled state.",
-          "type": "number",
-          "default": null
+        "variant": {
+          "description": "Semantic severity tone — drives icon + foreground color. Default carries no leading icon (pure hint copy).",
+          "$ref": "#/$defs/DynamicString"
+        }
+      },
+      "required": [
+        "component"
+      ],
+      "unevaluatedProperties": false,
+      "x-adiaui": {
+        "anti_patterns": [],
+        "category": "feedback",
+        "composes": [
+          "icon-ui"
+        ],
+        "events": {},
+        "examples": [
+          {
+            "description": "Email field with a danger inline-message under the input.",
+            "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Field\",\n    \"label\": \"Email\",\n    \"children\": [\n      \"input\",\n      \"msg\"\n    ]\n  },\n  {\n    \"id\": \"input\",\n    \"component\": \"Input\",\n    \"type\": \"email\"\n  },\n  {\n    \"id\": \"msg\",\n    \"component\": \"InlineMessage\",\n    \"variant\": \"danger\",\n    \"text\": \"Email address is required\"\n  }\n]",
+            "name": "field-validation"
+          },
+          {
+            "description": "Password field with a muted hint (default variant, no icon).",
+            "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Field\",\n    \"label\": \"Password\",\n    \"children\": [\n      \"input\",\n      \"hint\"\n    ]\n  },\n  {\n    \"id\": \"input\",\n    \"component\": \"Input\",\n    \"type\": \"password\"\n  },\n  {\n    \"id\": \"hint\",\n    \"component\": \"InlineMessage\",\n    \"text\": \"At least 8 characters\"\n  }\n]",
+            "name": "password-hint"
+          },
+          {
+            "description": "Username field with a polite live-region success confirmation.",
+            "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Field\",\n    \"label\": \"Username\",\n    \"children\": [\n      \"input\",\n      \"msg\"\n    ]\n  },\n  {\n    \"id\": \"input\",\n    \"component\": \"Input\"\n  },\n  {\n    \"id\": \"msg\",\n    \"component\": \"InlineMessage\",\n    \"variant\": \"success\",\n    \"live\": \"polite\",\n    \"text\": \"Username is available\"\n  }\n]",
+            "name": "username-success"
+          }
+        ],
+        "keywords": [
+          "inline",
+          "message",
+          "hint",
+          "helper",
+          "validation",
+          "error",
+          "field-error",
+          "helper-text",
+          "error-text",
+          "form-feedback",
+          "status",
+          "notice"
+        ],
+        "name": "UIInlineMessage",
+        "related": [
+          "alert",
+          "field",
+          "input",
+          "text"
+        ],
+        "slots": {
+          "default": {
+            "description": "Message body — text or inline DOM (e.g. <link-ui>, <kbd-ui>). Wins over the [text] attribute when present. Stays inline so the message reads as one annotation line under the field."
+          },
+          "leading": {
+            "description": "Leading icon slot. Stamped automatically from [icon] or the variant's default glyph. Consumer-provided <icon-ui slot=\"leading\"> is preserved across [variant] changes (never overwritten)."
+          }
+        },
+        "states": [
+          {
+            "description": "Default, ready for screen-reader pickup.",
+            "name": "idle"
+          }
+        ],
+        "status": "stable",
+        "synonyms": {
+          "error": [
+            "error",
+            "alert",
+            "validation"
+          ],
+          "helper": [
+            "hint",
+            "help",
+            "tooltip"
+          ],
+          "hint": [
+            "hint",
+            "tooltip",
+            "help"
+          ],
+          "message": [
+            "alert",
+            "notification",
+            "hint"
+          ],
+          "notice": [
+            "alert",
+            "banner",
+            "hint"
+          ],
+          "validation": [
+            "validation",
+            "error",
+            "alert"
+          ]
+        },
+        "tag": "inline-message-ui",
+        "tokens": {},
+        "traits": [],
+        "version": 1
+      }
+    },
+    "Input": {
+      "title": "Input",
+      "description": "Text input field with contenteditable surface. Supports prefix/suffix icons, label, form participation, and a `type=\"number\"` mode that renders [+]/[-] stepper buttons, numeric input filtering, and ARIA spinbutton semantics — no native `<input type=\"number\">` under the hood. Password type uses a native `<input>` (only path that still wraps native, for `-webkit-text-security` disc masking).",
+      "type": "object",
+      "allOf": [
+        {
+          "$ref": "#/$defs/ComponentCommon"
+        },
+        {
+          "$ref": "#/$defs/CatalogComponentCommon"
+        }
+      ],
+      "properties": {
+        "type": {
+          "description": "Input type. `password` wraps a native `<input>` for disc masking; `number` renders a contenteditable + stepper buttons (no native input). All other types use plain contenteditable.",
+          "type": "string",
+          "enum": [
+            "text",
+            "email",
+            "password",
+            "number",
+            "tel",
+            "url",
+            "search",
+            "date",
+            "datetime-local",
+            "time",
+            "month",
+            "week",
+            "color"
+          ],
+          "default": "text"
+        },
+        "required": {
+          "description": "Marks the field as required for form validation. Sets aria-required.",
+          "type": "boolean",
+          "default": false
+        },
+        "autocomplete": {
+          "description": "Browser autofill behavior per HTML autocomplete spec. Routed via setAttribute to the host element. Common values: off, on, cc-number, cc-exp, cc-csc, cc-name, email, username, current-password, new-password, one-time-code, given-name, family-name, street-address, postal-code.",
+          "type": "string",
+          "default": ""
+        },
+        "component": {
+          "const": "Input"
+        },
+        "disabled": {
+          "description": "Disables interaction, removes contenteditable, and dims the control",
+          "type": "boolean",
+          "default": false
+        },
+        "error": {
+          "description": "Validation error message. Set automatically by constraint validation or manually via setInvalid().",
+          "type": "string",
+          "default": ""
+        },
+        "inputmode": {
+          "description": "Mobile keyboard hint per HTML inputmode spec. Routed via setAttribute to the host element. Values: text, decimal, numeric, tel, search, email, url.",
+          "type": "string",
+          "enum": [
+            "text",
+            "decimal",
+            "numeric",
+            "tel",
+            "search",
+            "email",
+            "url",
+            "none"
+          ],
+          "default": null
+        },
+        "label": {
+          "description": "Inline label rendered as a leading caption inside the input chrome, between any prefix and the value. Wires aria-labelledby on the editable surface. For stacked label / hint / error compositions, wrap with field-ui.",
+          "type": "string",
+          "default": ""
+        },
+        "locale": {
+          "description": "BCP-47 locale tag for `type=\"number\"`, e.g. `de-DE`, `fr-FR`, `en-IN`. When set, the input accepts both `.` AND the locale's decimal separator (e.g. `,` in de-DE), uses `Intl.NumberFormat` for display, and groups thousands on blur (e.g. en-US `1,234,567.89`, de-DE `1.234.567,89`). On focus, the input reverts to ungrouped form for easy editing. `.value` always stores the ungrouped, locale-decimal form so `Number(#toCanonical(v))` round-trips. Default empty = en-US-equivalent path (no behavior change).",
+          "type": "string",
+          "default": ""
+        },
+        "max": {
+          "description": "Maximum numeric value. Applies when `type=\"number\"`. Clamps + drives aria-valuemax + the [+] button's disabled state.",
+          "type": "number",
+          "default": null
+        },
+        "maxlength": {
+          "description": "Maximum character length for validation",
+          "type": "number",
+          "default": null
+        },
+        "min": {
+          "description": "Minimum numeric value. Applies when `type=\"number\"`. Clamps + drives aria-valuemin + the [-] button's disabled state.",
+          "type": "number",
+          "default": null
         },
         "minlength": {
           "description": "Minimum character length for validation",
@@ -11358,9 +12108,9 @@
         "version": 1
       }
     },
-    "Kbd": {
-      "title": "Kbd",
-      "description": "Keyboard key cap. Purely decorative, content from innerHTML — typically a single key or short chord like \"⌘K\" or \"Ctrl+Shift+P\". Use inline in menu items, tooltips, command hints, and shortcut documentation.",
+    "IntegrationsPage": {
+      "title": "IntegrationsPage",
+      "description": "Module-tier Settings page composite — a searchable, category-grouped\ngrid of <integration-card-ui> tiles (SPEC-062). Owns the\n`integrations` array, the search-filter state, the category /\nstatus grouping, the responsive grid breakpoints, and the empty-state\ncopy. Card-level events (`connect` / `configure` / `disconnect` /\n`retry`) bubble up unchanged with `provider` in detail; the page also\nemits `search` (debounced) and a top-bar `filter-change` when the\nuser picks a status chip.\n\nLives in `packages/web-modules/settings/integrations-page/` per the\nthree-tier architecture — composes multiple primitives, holds layout\nresponsibility, consumed by the settings shell. Replaces the\nhand-rolled `settings/integrations` HTML template per consumer.\n\nSpec: docs/specs/implementation-ready/SPEC-063-integrations-page.md\n",
       "type": "object",
       "allOf": [
         {
@@ -11372,91 +12122,950 @@
       ],
       "properties": {
         "component": {
-          "const": "Kbd"
+          "const": "IntegrationsPage"
         },
-        "size": {
-          "description": "Sizing scale (compact tier — sm / md only).",
+        "group-by": {
+          "description": "How to bucket cards into sections. `category` groups by the per-item\n`category` key; `status` groups by connection state; `none` renders\na single ungrouped grid.\n",
           "type": "string",
           "enum": [
-            "sm",
-            "md"
+            "category",
+            "status",
+            "none"
           ],
-          "default": ""
+          "default": "category"
+        },
+        "integrations": {
+          "description": "Array of integration descriptors — each item conforms to the\nSPEC-062 <integration-card-ui> prop shape:\n`{ provider, name, logo?, description?, status, category?,\nerror-message? }`. Empty array renders the empty-state slot.\n",
+          "$ref": "#/$defs/DynamicStringList"
+        },
+        "loading": {
+          "description": "Renders a skeleton grid (6 tiles) instead of cards. Driven by the\nconsumer while the integrations payload is in flight.\n",
+          "$ref": "#/$defs/DynamicBoolean"
+        },
+        "search-placeholder": {
+          "description": "Placeholder copy for the built-in search input. Defaults to\n\"Search integrations\".\n",
+          "type": "string",
+          "default": "Search integrations"
+        },
+        "status-filter": {
+          "description": "Optional status filter — restricts the visible cards to one status.\n`all` (default) shows everything; the rest restrict to that status\nbucket. Reflects so consumers can deep-link.\n",
+          "$ref": "#/$defs/DynamicString"
         }
       },
       "required": [
-        "component"
+        "component",
+        "integrations"
       ],
       "unevaluatedProperties": false,
       "x-adiaui": {
-        "anti_patterns": [],
-        "category": "display",
-        "composes": [],
-        "events": {},
-        "examples": [
+        "anti_patterns": [
           {
-            "description": "Card displaying a grid of keyboard shortcut rows with key badges and descriptions.",
-            "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Card\",\n    \"children\": [\n      \"hdr\",\n      \"sec\"\n    ]\n  },\n  {\n    \"id\": \"hdr\",\n    \"component\": \"Header\",\n    \"children\": [\n      \"title\"\n    ]\n  },\n  {\n    \"id\": \"title\",\n    \"component\": \"Text\",\n    \"slot\": \"heading\",\n    \"textContent\": \"Keyboard Shortcuts\"\n  },\n  {\n    \"id\": \"sec\",\n    \"component\": \"Section\",\n    \"children\": [\n      \"grid\"\n    ]\n  },\n  {\n    \"id\": \"grid\",\n    \"component\": \"Grid\",\n    \"columns\": 1,\n    \"gap\": \"2\",\n    \"children\": [\n      \"r1\",\n      \"r2\",\n      \"r3\",\n      \"r4\",\n      \"r5\",\n      \"r6\"\n    ]\n  },\n  {\n    \"id\": \"r1\",\n    \"component\": \"Row\",\n    \"children\": [\n      \"k1\",\n      \"d1\"\n    ]\n  },\n  {\n    \"id\": \"k1\",\n    \"component\": \"Kbd\",\n    \"text\": \"Ctrl+K\"\n  },\n  {\n    \"id\": \"d1\",\n    \"component\": \"Text\",\n    \"textContent\": \"Open command palette\"\n  },\n  {\n    \"id\": \"r2\",\n    \"component\": \"Row\",\n    \"children\": [\n      \"k2\",\n      \"d2\"\n    ]\n  },\n  {\n    \"id\": \"k2\",\n    \"component\": \"Kbd\",\n    \"text\": \"Ctrl+S\"\n  },\n  {\n    \"id\": \"d2\",\n    \"component\": \"Text\",\n    \"textContent\": \"Save current file\"\n  },\n  {\n    \"id\": \"r3\",\n    \"component\": \"Row\",\n    \"children\": [\n      \"k3\",\n      \"d3\"\n    ]\n  },\n  {\n    \"id\": \"k3\",\n    \"component\": \"Kbd\",\n    \"text\": \"Ctrl+Z\"\n  },\n  {\n    \"id\": \"d3\",\n    \"component\": \"Text\",\n    \"textContent\": \"Undo last action\"\n  },\n  {\n    \"id\": \"r4\",\n    \"component\": \"Row\",\n    \"children\": [\n      \"k4\",\n      \"d4\"\n    ]\n  },\n  {\n    \"id\": \"k4\",\n    \"component\": \"Kbd\",\n    \"text\": \"Ctrl+Shift+P\"\n  },\n  {\n    \"id\": \"d4\",\n    \"component\": \"Text\",\n    \"textContent\": \"Toggle preview\"\n  },\n  {\n    \"id\": \"r5\",\n    \"component\": \"Row\",\n    \"children\": [\n      \"k5\",\n      \"d5\"\n    ]\n  },\n  {\n    \"id\": \"k5\",\n    \"component\": \"Kbd\",\n    \"text\": \"Ctrl+N\"\n  },\n  {\n    \"id\": \"d5\",\n    \"component\": \"Text\",\n    \"textContent\": \"Create new document\"\n  },\n  {\n    \"id\": \"r6\",\n    \"component\": \"Row\",\n    \"children\": [\n      \"k6\",\n      \"d6\"\n    ]\n  },\n  {\n    \"id\": \"k6\",\n    \"component\": \"Kbd\",\n    \"text\": \"Esc\"\n  },\n  {\n    \"id\": \"d6\",\n    \"component\": \"Text\",\n    \"textContent\": \"Close dialog\"\n  }\n]",
-            "name": "kbd-shortcuts"
-          }
-        ],
-        "keywords": [
-          "kbd",
-          "command",
-          "shortcut",
-          "hotkey",
-          "keyboard",
-          "keybinding"
-        ],
-        "name": "UIKbd",
-        "related": [
-          "grid"
-        ],
-        "slots": {
-          "default": {
-            "description": "Key label text"
-          }
-        },
-        "states": [
+            "fix": "{\"component\": \"IntegrationsPage\", \"integrations\": [\n  {\"provider\": \"slack\", \"name\": \"Slack\", \"status\": \"available\"}\n]}\n",
+            "why": "Slotted cards are ignored — the page generates cards from the\n`integrations` prop. The page renders empty.\n",
+            "wrong": "{\"component\": \"IntegrationsPage\", \"children\": [\n  {\"component\": \"IntegrationCard\", \"provider\": \"slack\", \"name\": \"Slack\"}\n]}\n"
+          },
           {
-            "description": "Default, ready for interaction.",
-            "name": "idle"
+            "fix": "{\"component\": \"IntegrationsPage\", \"integrations\": [\n  {\"provider\": \"slack\", \"name\": \"Slack\", \"status\": \"available\"}\n]}\n",
+            "why": "Re-implements the page composite with primitives. Loses search,\ngrouping, and empty-state semantics.\n",
+            "wrong": "{\"component\": \"Page\", \"children\": [\n  {\"component\": \"Grid\", \"children\": [\n    {\"component\": \"IntegrationCard\", \"provider\": \"slack\", \"name\": \"Slack\"}\n  ]}\n]}\n"
           }
         ],
-        "status": "stable",
-        "synonyms": {
-          "command": [
-            "command",
-            "palette",
-            "kbd",
-            "shortcut"
-          ],
-          "hotkey": [
-            "kbd",
-            "shortcut",
-            "command"
-          ],
-          "keybinding": [
-            "kbd",
-            "shortcut",
-            "command"
-          ],
-          "keyboard": [
-            "kbd",
-            "shortcut",
-            "command"
-          ],
-          "shortcut": [
-            "kbd",
-            "shortcut",
-            "command"
-          ],
-          "tags": [
-            "Keyboard"
-          ]
-        },
-        "tag": "kbd-ui",
-        "tokens": {},
+        "category": "container",
+        "composes": [
+          "integration-card-ui",
+          "grid-ui",
+          "search-ui",
+          "segmented-ui",
+          "segment-ui",
+          "text-ui"
+        ],
+        "events": {
+          "configure": {
+            "description": "Bubbled from a child <integration-card-ui> while `status=\"connected\"`.",
+            "detail": {
+              "provider": {
+                "description": "The provider key of the card that fired.",
+                "type": "string"
+              }
+            }
+          },
+          "connect": {
+            "description": "Bubbled from a child <integration-card-ui> when its primary button is pressed while `status=\"available\"`.",
+            "detail": {
+              "provider": {
+                "description": "The provider key of the card that fired.",
+                "type": "string"
+              }
+            }
+          },
+          "disconnect": {
+            "description": "Bubbled from a child card's overflow menu disconnect item.",
+            "detail": {
+              "provider": {
+                "description": "The provider key of the card that fired.",
+                "type": "string"
+              }
+            }
+          },
+          "filter-change": {
+            "description": "User clicked a status filter chip in the top bar.",
+            "detail": {
+              "status": {
+                "description": "The newly-selected status filter (`all` resets).",
+                "type": "string"
+              }
+            }
+          },
+          "retry": {
+            "description": "Bubbled from a child <integration-card-ui> while `status=\"error\"`.",
+            "detail": {
+              "provider": {
+                "description": "The provider key of the card that fired.",
+                "type": "string"
+              }
+            }
+          },
+          "search": {
+            "description": "Debounced search input change.",
+            "detail": {
+              "query": {
+                "description": "The current search query (lower-cased, trimmed).",
+                "type": "string"
+              }
+            }
+          }
+        },
+        "examples": [
+          {
+            "description": "Full integrations page grouped by category (default).",
+            "a2ui": "[\n  {\n    \"id\": \"page\",\n    \"component\": \"IntegrationsPage\",\n    \"group-by\": \"category\",\n    \"integrations\": [\n      {\"provider\": \"slack\",  \"name\": \"Slack\",  \"logo\": \"/integrations/slack.svg\",\n       \"description\": \"Notifications and replies in channels.\",\n       \"status\": \"connected\", \"category\": \"Communication\"},\n      {\"provider\": \"github\", \"name\": \"GitHub\", \"logo\": \"/integrations/github.svg\",\n       \"description\": \"Sync issues and pull requests.\",\n       \"status\": \"available\", \"category\": \"Developer Tools\"},\n      {\"provider\": \"stripe\", \"name\": \"Stripe\", \"logo\": \"/integrations/stripe.svg\",\n       \"description\": \"Charge customers and reconcile invoices.\",\n       \"status\": \"error\", \"category\": \"Payments\",\n       \"error-message\": \"Token expired — re-authenticate.\"}\n    ]\n  }\n]\n",
+            "name": "category-grouped"
+          },
+          {
+            "description": "Loading state — 6 skeleton tiles, no cards.",
+            "a2ui": "[{\"id\": \"page\", \"component\": \"IntegrationsPage\", \"loading\": true}]\n",
+            "name": "loading-skeleton"
+          },
+          {
+            "description": "Empty state — no integrations available.",
+            "a2ui": "[{\"id\": \"page\", \"component\": \"IntegrationsPage\", \"integrations\": []}]\n",
+            "name": "empty-data"
+          }
+        ],
+        "keywords": [
+          "integrations",
+          "integration",
+          "settings",
+          "settings-page",
+          "connections",
+          "third-party",
+          "oauth",
+          "providers",
+          "app-directory",
+          "marketplace"
+        ],
+        "name": "UIIntegrationsPage",
+        "related": [
+          "IntegrationCard",
+          "Grid",
+          "Search",
+          "Segmented",
+          "Page"
+        ],
+        "slots": {
+          "empty": {
+            "description": "Optional override for the empty-state copy. When supplied, replaces\nthe built-in \"No integrations match\" / \"No integrations available\"\nmessages.\n"
+          },
+          "header": {
+            "description": "Optional page header (kicker / title / subtitle). Overrides the\ndefault rendering — when supplied the composite stamps no\nbuilt-in heading.\n"
+          }
+        },
+        "states": [
+          {
+            "description": "Default; renders all groups matching the current filter.",
+            "name": "idle"
+          },
+          {
+            "description": "Skeleton grid; cards hidden.",
+            "attribute": "loading",
+            "name": "loading"
+          },
+          {
+            "description": "Search query yields zero cards.",
+            "attribute": "data-empty-search",
+            "name": "empty-search"
+          },
+          {
+            "description": "`integrations` array is empty.",
+            "attribute": "data-empty-data",
+            "name": "empty-data"
+          }
+        ],
+        "status": "stable",
+        "synonyms": {
+          "integrations": [
+            "integration",
+            "connections",
+            "apps",
+            "providers"
+          ],
+          "marketplace": [
+            "integrations",
+            "app-directory",
+            "apps"
+          ],
+          "oauth": [
+            "integration",
+            "connection",
+            "auth"
+          ],
+          "settings": [
+            "settings",
+            "account",
+            "admin"
+          ]
+        },
+        "tag": "integrations-page-ui",
+        "tokens": {
+          "--integrations-page-bg": {
+            "description": "Page background. Defaults to `var(--a-bg)`.",
+            "default": "var(--a-bg)"
+          },
+          "--integrations-page-card-gap": {
+            "description": "Gap inside the grid between cards.",
+            "default": "var(--a-space-4)"
+          },
+          "--integrations-page-fg": {
+            "description": "Primary foreground. Defaults to `var(--a-fg)`.",
+            "default": "var(--a-fg)"
+          },
+          "--integrations-page-fg-muted": {
+            "description": "Secondary foreground for empty-state copy + section meta.",
+            "default": "var(--a-fg-muted)"
+          },
+          "--integrations-page-gap": {
+            "description": "Vertical gap between toolbar / sections / empty-state.",
+            "default": "var(--a-space-5)"
+          },
+          "--integrations-page-grid-min": {
+            "description": "Minimum card width for the auto-fill grid track.",
+            "default": "var(--a-space-12)"
+          },
+          "--integrations-page-px": {
+            "description": "Horizontal padding around the page.",
+            "default": "var(--a-space-5)"
+          },
+          "--integrations-page-py": {
+            "description": "Vertical padding around the page.",
+            "default": "var(--a-space-5)"
+          },
+          "--integrations-page-section-gap": {
+            "description": "Vertical gap between sibling category sections.",
+            "default": "var(--a-space-6)"
+          },
+          "--integrations-page-section-heading-fg": {
+            "description": "Section heading color.",
+            "default": "var(--a-fg-strong)"
+          },
+          "--integrations-page-section-heading-size": {
+            "description": "Section heading font size.",
+            "default": "var(--a-ui-sm)"
+          },
+          "--integrations-page-section-heading-weight": {
+            "description": "Section heading font weight.",
+            "default": "var(--a-weight-medium)"
+          }
+        },
+        "traits": [],
+        "version": 1
+      }
+    },
+    "InvoiceDetail": {
+      "title": "InvoiceDetail",
+      "description": "Module-tier page composite that renders a single invoice — header\n(number + status badge + dates), line-items table, totals block,\ncustomer + remit-to blocks, and a slot-driven action toolbar.\nThe canonical invoice layout shared by billing-enabled products\nso totals math, status-badge color mapping, and action-toolbar\norder do not drift across surfaces.\n\nData-driven via the `invoice` property OR a `data-stream-src`\nendpoint. The composite stamps a six-region skeleton once on\nfirst connect — header · meta · parties · lines · totals ·\nfooter — then mutates per-region nodes via id-keyed in-place\ndiff on every property change. The status badge color maps\nfrom `invoice.status` (paid → success, past-due → warning,\nvoid → muted, open/draft → default). Action buttons are\nconsumer-slotted into `header-actions` per spec OD-002 (always\nslot, never stamp a default toolbar).\n\nPrint-friendly: an internal `@media print` branch hides the\naction toolbar + zeroes the page padding. The composite is a\ndisplay surface — extends UIElement, not UIFormElement.\n\nSpec: docs/specs/implementation-ready/SPEC-007-invoice-detail-page.md.\n",
+      "type": "object",
+      "allOf": [
+        {
+          "$ref": "#/$defs/ComponentCommon"
+        },
+        {
+          "$ref": "#/$defs/CatalogComponentCommon"
+        }
+      ],
+      "properties": {
+        "component": {
+          "const": "InvoiceDetail"
+        },
+        "currency": {
+          "description": "ISO 4217 currency code for amount formatting via\nIntl.NumberFormat. Overridable per-record via invoice.currency.\n",
+          "type": "string",
+          "default": "USD"
+        },
+        "data-stream-src": {
+          "description": "Optional endpoint returning the invoice record (universal\ndata-stream-* trait). On successful load, `invoice` is\nreplaced and a `load` event fires; on failure an `error`\nevent fires.\n",
+          "type": "string",
+          "default": ""
+        },
+        "density": {
+          "description": "Line-items table row density. `compact` for tightly-packed\ninvoices with many line items; `standard` for typical invoices.\nForwarded to the embedded <table-ui density>.\n",
+          "type": "string",
+          "enum": [
+            "compact",
+            "standard"
+          ],
+          "default": "standard"
+        },
+        "invoice": {
+          "description": "The invoice record. Source of truth for the rendered page.\nShape: {number, status, issuedAt, dueAt, customer:{name,email},\nremitTo?:{name,address?}, lines:[{description,qty,unitAmount,\namount}], subtotal, tax, discount?, total, currency,\nnotes?:string}. Null + no data-stream-src renders the empty\nstate.\n",
+          "type": "object",
+          "default": null
+        },
+        "loading": {
+          "description": "Renders skeleton placeholders for header + line-items + totals\nwhile a data-stream-src fetch is in flight. Sets aria-busy\non the host. Data updates suppressed while [loading] is set.\n",
+          "$ref": "#/$defs/DynamicBoolean"
+        },
+        "locale": {
+          "description": "Locale for Intl.NumberFormat (amounts) and Intl.DateTimeFormat\n(issued/due). Defaults to document.documentElement.lang (or\n\"en-US\" when absent).\n",
+          "type": "string",
+          "default": ""
+        },
+        "printable": {
+          "description": "Includes the @media print branch — hides the action toolbar\nand zeroes page padding so the printed output is invoice-only.\nSet [printable] to false on screens where the invoice is\nembedded inside a larger surface and printing should not be\na first-class action.\n",
+          "type": "boolean",
+          "default": true
+        },
+        "status": {
+          "description": "Mirrors invoice.status. Drives the status badge `variant`\nmapping (paid → success, past-due → warning, void → muted,\nopen/draft → default). When set independently of `invoice`,\nthe host status reflection wins for CSS — useful when the\nhost wraps an invoice without a status field.\n",
+          "$ref": "#/$defs/DynamicString"
+        }
+      },
+      "required": [
+        "component",
+        "invoice"
+      ],
+      "unevaluatedProperties": false,
+      "x-adiaui": {
+        "anti_patterns": [
+          {
+            "fix": "{\"component\": \"InvoiceDetail\", \"invoice\":\n  {\"lines\": [...], \"subtotal\": 24, \"total\": 24.5, \"currency\": \"USD\"}}\n",
+            "why": "Line items belong on `invoice.lines`, not the host. Without\nthe wrapping `invoice` object, totals + currency are unwired\nand the composite renders the empty state.\n",
+            "wrong": "{\"component\": \"InvoiceDetail\", \"lines\": [...]}\n"
+          },
+          {
+            "fix": "Open the invoice via <a href=\"/invoices/INV-001234\"> route\nnavigation; render the InvoiceDetail composite on that route.\n",
+            "why": "Invoices are routes, not modals. Modal traps focus + clips\non long content; the composite is designed for full-page\nlayout.\n",
+            "wrong": "{\"component\": \"Modal\", \"children\":\n  [{\"component\": \"InvoiceDetail\", \"invoice\": {...}}]}\n"
+          },
+          {
+            "fix": "<invoice-detail-ui status=\"paid\"></invoice-detail-ui>\n",
+            "why": "`settled` is not in the status enum. Unknown statuses fall\nback to the default badge variant; the consumer surface\nloses the semantic color mapping.\n",
+            "wrong": "<invoice-detail-ui status=\"settled\"></invoice-detail-ui>\n"
+          }
+        ],
+        "category": "container",
+        "composes": [
+          "card-ui",
+          "table-ui",
+          "stat-ui",
+          "tag-ui",
+          "button-ui",
+          "text-ui",
+          "icon-ui",
+          "empty-state-ui"
+        ],
+        "events": {
+          "error": {
+            "description": "Fired when a data-stream-src fetch fails OR when the host is\nasked to print but window.print is unavailable. Bubbles.\n",
+            "detail": {
+              "reason": {
+                "description": "One of `fetch-failed`, `print-unavailable`.",
+                "type": "string"
+              }
+            }
+          },
+          "invoice-action": {
+            "description": "Fired when a header-action button carrying\n[data-invoice-action] is activated. Consumers wire this to\ndownload / send / pay / void flows. Bubbles.\n",
+            "detail": {
+              "action": {
+                "description": "The data-invoice-action value (download, send, pay, etc.).",
+                "type": "string"
+              },
+              "invoiceNumber": {
+                "description": "invoice.number at the time of activation.",
+                "type": "string"
+              }
+            }
+          },
+          "line-item-click": {
+            "description": "Fired when a line-item row is clicked. Bubbles.\n",
+            "detail": {
+              "index": {
+                "description": "0-based row index within invoice.lines.",
+                "type": "integer"
+              },
+              "lineItem": {
+                "description": "The clicked invoice.lines[index] record.",
+                "type": "object"
+              }
+            }
+          },
+          "load": {
+            "description": "Fired when a data-stream-src fetch resolves and the invoice\nrecord is populated. Bubbles.\n",
+            "detail": {
+              "invoiceNumber": {
+                "description": "The loaded invoice.number.",
+                "type": "string"
+              }
+            }
+          }
+        },
+        "examples": [
+          {
+            "description": "A paid invoice with two line items + slotted actions.",
+            "a2ui": "[\n  {\n    \"id\": \"inv-paid\",\n    \"component\": \"InvoiceDetail\",\n    \"status\": \"paid\",\n    \"currency\": \"USD\",\n    \"invoice\": {\n      \"number\": \"INV-001234\",\n      \"status\": \"paid\",\n      \"issuedAt\": \"2026-05-01\",\n      \"dueAt\": \"2026-05-15\",\n      \"customer\": {\"name\": \"Acme Co.\", \"email\": \"billing@acme.test\"},\n      \"lines\": [\n        {\"description\": \"Pro plan — May\", \"qty\": 1, \"unitAmount\": 24.00, \"amount\": 24.00},\n        {\"description\": \"Add-on — Audit log retention\", \"qty\": 1, \"unitAmount\": 0.50, \"amount\": 0.50}\n      ],\n      \"subtotal\": 24.50,\n      \"tax\": 0,\n      \"total\": 24.50,\n      \"currency\": \"USD\"\n    },\n    \"children\": [\"btn-download\"]\n  },\n  {\"id\": \"btn-download\", \"component\": \"Button\",\n   \"text\": \"Download\", \"slot\": \"header-actions\"}\n]\n",
+            "name": "paid-invoice"
+          },
+          {
+            "description": "Open invoice awaiting payment + Pay CTA.",
+            "a2ui": "[\n  {\n    \"id\": \"inv-open\",\n    \"component\": \"InvoiceDetail\",\n    \"status\": \"open\",\n    \"currency\": \"USD\",\n    \"invoice\": {\n      \"number\": \"INV-001235\",\n      \"status\": \"open\",\n      \"issuedAt\": \"2026-05-10\",\n      \"dueAt\": \"2026-05-24\",\n      \"customer\": {\"name\": \"Globex Corp.\", \"email\": \"ap@globex.test\"},\n      \"lines\": [\n        {\"description\": \"Team seats × 5\", \"qty\": 5, \"unitAmount\": 10.00, \"amount\": 50.00}\n      ],\n      \"subtotal\": 50.00,\n      \"tax\": 5.00,\n      \"total\": 55.00,\n      \"currency\": \"USD\"\n    },\n    \"children\": [\"btn-pay-open\"]\n  },\n  {\"id\": \"btn-pay-open\", \"component\": \"Button\",\n   \"text\": \"Pay $55\", \"variant\": \"primary\",\n   \"slot\": \"header-actions\"}\n]\n",
+            "name": "open-invoice"
+          }
+        ],
+        "keywords": [
+          "invoice",
+          "invoice-detail",
+          "billing",
+          "receipt",
+          "bill",
+          "statement",
+          "payment",
+          "line-items",
+          "charges",
+          "totals",
+          "paid",
+          "past-due",
+          "void"
+        ],
+        "name": "UIInvoiceDetail",
+        "related": [
+          "Card",
+          "Table",
+          "Stat",
+          "Tag",
+          "Button",
+          "EmptyState",
+          "PlanPicker"
+        ],
+        "slots": {
+          "customer-block": {
+            "description": "Override the default customer block. When unset, the composite\nrenders a default block from invoice.customer.\n"
+          },
+          "footer": {
+            "description": "Optional content below the totals — payment instructions,\nterms, fine print.\n"
+          },
+          "header-actions": {
+            "description": "Action toolbar slotted into the top-right of the invoice\nheader — Download, Send, Pay, etc. Consumer-owned per\nSPEC-007 OD-002 (the composite NEVER stamps a default\ntoolbar; action sets vary too much across products).\nButtons carrying [data-invoice-action] dispatch the host's\n`invoice-action` event on activation.\n"
+          },
+          "remit-to-block": {
+            "description": "Override the default remit-to block. When unset, the composite\nrenders a default block from invoice.remitTo if present.\n"
+          }
+        },
+        "states": [
+          {
+            "description": "Default — invoice rendered, ready for interaction.",
+            "name": "idle"
+          },
+          {
+            "description": "A data-stream-src fetch is in flight.",
+            "attribute": "loading",
+            "name": "loading"
+          },
+          {
+            "description": "No invoice + no data-stream-src.",
+            "attribute": "empty",
+            "name": "empty"
+          },
+          {
+            "description": "Last data-stream-src fetch failed.",
+            "attribute": "error",
+            "name": "error"
+          }
+        ],
+        "status": "experimental",
+        "synonyms": {
+          "invoice": [
+            "bill",
+            "receipt",
+            "statement"
+          ],
+          "line-items": [
+            "charges",
+            "entries"
+          ],
+          "payment": [
+            "charge",
+            "billing"
+          ]
+        },
+        "tag": "invoice-detail-ui",
+        "tokens": {
+          "--invoice-detail-amount-fg": {
+            "description": "Color for monetary amounts in the totals stack.",
+            "default": "var(--a-fg)"
+          },
+          "--invoice-detail-bg": {
+            "description": "Host page background. Defaults to transparent.",
+            "default": "transparent"
+          },
+          "--invoice-detail-line-amount-align": {
+            "description": "Text-align for the rightmost amount column in the lines table.\n`end` for typical right-aligned numerics.\n",
+            "default": "end"
+          },
+          "--invoice-detail-meta-fg": {
+            "description": "Color for the secondary header metadata (issued / due).",
+            "default": "var(--a-fg-muted)"
+          },
+          "--invoice-detail-page-padding": {
+            "description": "Inset around the invoice content area.",
+            "default": "var(--a-space-5)"
+          },
+          "--invoice-detail-section-gap": {
+            "description": "Vertical gap between header, parties, lines, totals.",
+            "default": "var(--a-space-5)"
+          },
+          "--invoice-detail-status-badge-radius": {
+            "description": "Status badge corner radius.",
+            "default": "var(--a-radius-md)"
+          },
+          "--invoice-detail-total-size": {
+            "description": "Font size for the grand total line.",
+            "default": "var(--a-text-2xl, 1.5rem)"
+          },
+          "--invoice-detail-total-weight": {
+            "description": "Font weight for the grand total line.",
+            "default": "var(--a-weight-bold, 700)"
+          },
+          "--invoice-detail-totals-width": {
+            "description": "Width of the right-aligned totals stack. Clamps to 100% on\nnarrow viewports.\n",
+            "default": "min(360px, 100%)"
+          }
+        },
+        "traits": [],
+        "version": 1
+      }
+    },
+    "InvoiceHistory": {
+      "title": "InvoiceHistory",
+      "description": "Canonical billing-list composite — a pre-configured <table-ui> with\ninvoice-shaped columns (number, issued, due, amount, status, actions),\nstatus-badge cell renderer (paid/open/past-due/void/draft → semantic\nbadge variant), currency cell renderer, optional search + filter\nchips via <table-toolbar-ui>, and a row-click that navigates to the\ninvoice detail page.\n\nWraps <table-ui> with billing-shaped columns + cell renderers + a\nCSV-export toolbar. Consumer passes invoices[]; the composite owns\ncolumn shape, status-to-badge mapping, currency formatting, date\nformatting, and navigation. Sibling to SPEC-007 (invoice detail).\n\nEach invoice record: {id, number, status, issuedAt, dueAt, amount,\ncurrency}. status MUST be one of \"draft\" | \"open\" | \"paid\" |\n\"past-due\" | \"void\"; unknown values fall back to a neutral badge.\n\nSpec: docs/specs/implementation-ready/SPEC-008-invoice-history-table.md.\n",
+      "type": "object",
+      "allOf": [
+        {
+          "$ref": "#/$defs/ComponentCommon"
+        },
+        {
+          "$ref": "#/$defs/CatalogComponentCommon"
+        }
+      ],
+      "properties": {
+        "component": {
+          "const": "InvoiceHistory"
+        },
+        "currency": {
+          "description": "Default ISO 4217 currency code for amount formatting. Overridable\nper-row via invoices[].currency.\n",
+          "type": "string",
+          "default": "USD"
+        },
+        "data-stream-src": {
+          "description": "Optional endpoint returning the `invoices` array (universal\ndata-stream-* trait). On successful load, `invoices` is replaced\nand a `load` event fires; on failure an `error` event fires.\n",
+          "type": "string",
+          "default": ""
+        },
+        "density": {
+          "description": "Row density, forwarded to <table-ui>. `compact` for dense lists,\n`standard` for default rows, `comfortable` for spacious rows.\n",
+          "type": "string",
+          "enum": [
+            "compact",
+            "standard",
+            "comfortable"
+          ],
+          "default": "standard"
+        },
+        "exportable": {
+          "description": "When set, the default toolbar carries an \"Export CSV\" button.\nConsumers overriding the toolbar via slot=\"toolbar\" can omit\nthis and stamp their own export affordance.\n",
+          "type": "boolean",
+          "default": true
+        },
+        "filter": {
+          "description": "Active status filter — narrows visible rows to a single status\nbucket. Empty string = show all. Mirrors the toolbar chip-group\nselection state.\n",
+          "$ref": "#/$defs/DynamicString"
+        },
+        "hrefPattern": {
+          "description": "URL template for row-click navigation. The literal `{number}` is\nreplaced with the invoice's number on click. Defaults to\n`/invoices/{number}`.\n",
+          "type": "string",
+          "default": "/invoices/{number}"
+        },
+        "invoices": {
+          "description": "Array of invoice records. Source of truth for the rendered rows.\nShape per record: {id, number, status, issuedAt, dueAt, amount,\ncurrency?}. status must be one of \"draft\" | \"open\" | \"paid\" |\n\"past-due\" | \"void\". Empty array renders the empty-state.\n",
+          "$ref": "#/$defs/DynamicStringList"
+        },
+        "loading": {
+          "description": "Forwarded to <table-ui> — renders skeleton rows instead of data\nwhile a fetch is in flight.\n",
+          "$ref": "#/$defs/DynamicBoolean"
+        },
+        "locale": {
+          "description": "Locale for Intl.NumberFormat (amount) and Intl.DateTimeFormat\n(issuedAt / dueAt). Defaults to document.documentElement.lang\n(or \"en-US\" when absent).\n",
+          "type": "string",
+          "default": ""
+        },
+        "paginate": {
+          "description": "Rows per page, forwarded to <table-ui>. 0 = show all rows.\n",
+          "type": "number",
+          "default": 25
+        },
+        "selectable": {
+          "description": "When set, enables row selection via a leading checkbox column on\nthe underlying <table-ui> (bulk-action surface).\n",
+          "type": "boolean",
+          "default": false
+        }
+      },
+      "required": [
+        "component",
+        "invoices"
+      ],
+      "unevaluatedProperties": false,
+      "x-adiaui": {
+        "anti_patterns": [
+          {
+            "fix": "<invoice-history-ui .invoices=\"${rows}\"></invoice-history-ui>\n",
+            "why": "Hand-rolled billing list. Reinvents the canonical composite,\ndrifts on status-badge mapping, currency formatting, and\ndate format.\n",
+            "wrong": "<table-ui sortable>\n  <col-def key=\"number\" label=\"Invoice\"></col-def>\n  <col-def key=\"status\" label=\"Status\"></col-def>\n</table-ui>\n"
+          },
+          {
+            "fix": "<invoice-history-ui .invoices=\"${rows}\"></invoice-history-ui>\n",
+            "why": "Columns are owned by the composite. Custom columns belong on a\ndifferent <table-ui> composition.\n",
+            "wrong": "<invoice-history-ui .columns=\"${customColumns}\"\n                    .invoices=\"${rows}\"></invoice-history-ui>\n"
+          }
+        ],
+        "category": "display",
+        "composes": [
+          "table-ui",
+          "table-toolbar-ui",
+          "badge-ui",
+          "button-ui",
+          "empty-state-ui",
+          "pagination-ui"
+        ],
+        "events": {
+          "error": {
+            "description": "Fired when a `data-stream-src` fetch fails. Bubbles.\n",
+            "detail": {
+              "reason": {
+                "description": "One of `fetch-failed`.",
+                "type": "string"
+              }
+            }
+          },
+          "invoice-export": {
+            "description": "Fired when the default \"Export CSV\" toolbar button is pressed.\nDetail carries the generated blob; consumers may preventDefault\nto suppress the default download. Bubbles.\n",
+            "detail": {
+              "blob": {
+                "description": "The generated text/csv Blob.",
+                "type": "object"
+              },
+              "rowCount": {
+                "description": "Number of rows in the export.",
+                "type": "integer"
+              }
+            }
+          },
+          "invoice-filter-change": {
+            "description": "Fired when the status filter changes via the toolbar chip group.\nBubbles.\n",
+            "detail": {
+              "filter": {
+                "description": "New status filter value (empty string = all).",
+                "type": "string",
+                "enum": [
+                  "",
+                  "draft",
+                  "open",
+                  "paid",
+                  "past-due",
+                  "void"
+                ]
+              },
+              "previous": {
+                "description": "Previous filter value.",
+                "type": "string"
+              }
+            }
+          },
+          "invoice-row-click": {
+            "description": "Fired when an invoice row is activated (mouse click or keyboard\nEnter / Space). Listener can preventDefault() to suppress the\ndefault `window.location.assign(href)` navigation. Bubbles.\n",
+            "detail": {
+              "href": {
+                "description": "Resolved navigation URL.",
+                "type": "string"
+              },
+              "invoice": {
+                "description": "The invoice record under the clicked row.",
+                "type": "object"
+              }
+            }
+          },
+          "invoice-selection-change": {
+            "description": "Fired when row selection changes (only when `selectable` is set).\nBubbles.\n",
+            "detail": {
+              "selected": {
+                "description": "Array of selected invoice records.",
+                "type": "array"
+              }
+            }
+          },
+          "load": {
+            "description": "Fired when `data-stream-src` finishes a successful fetch and\n`invoices` is populated. Bubbles.\n",
+            "detail": {
+              "count": {
+                "description": "Number of invoices loaded.",
+                "type": "integer"
+              }
+            }
+          }
+        },
+        "examples": [
+          {
+            "description": "6-column billing list with status badges, currency formatting, and pagination.",
+            "a2ui": "[\n  {\n    \"id\": \"inv-hist-1\",\n    \"component\": \"InvoiceHistory\",\n    \"currency\": \"USD\",\n    \"paginate\": 25,\n    \"invoices\": [\n      {\"id\":\"i1\",\"number\":\"INV-001234\",\"status\":\"paid\",\"issuedAt\":\"2026-05-01\",\"dueAt\":\"2026-05-15\",\"amount\":24.50},\n      {\"id\":\"i2\",\"number\":\"INV-001235\",\"status\":\"open\",\"issuedAt\":\"2026-05-08\",\"dueAt\":\"2026-05-22\",\"amount\":24.50},\n      {\"id\":\"i3\",\"number\":\"INV-001236\",\"status\":\"past-due\",\"issuedAt\":\"2026-04-15\",\"dueAt\":\"2026-04-29\",\"amount\":24.50}\n    ]\n  }\n]\n",
+            "name": "canonical"
+          },
+          {
+            "description": "Server-streamed invoices via data-stream-src.",
+            "a2ui": "[\n  {\n    \"id\": \"inv-hist-stream\",\n    \"component\": \"InvoiceHistory\",\n    \"data-stream-src\": \"/api/invoices\",\n    \"currency\": \"USD\",\n    \"paginate\": 50\n  }\n]\n",
+            "name": "streamed"
+          }
+        ],
+        "keywords": [
+          "invoice",
+          "invoices",
+          "billing",
+          "invoice-history",
+          "invoice-list",
+          "payments-history",
+          "receipt",
+          "receipts",
+          "statement",
+          "statements",
+          "subscription",
+          "charges",
+          "past-due",
+          "paid",
+          "billing-list",
+          "billing-table",
+          "download-invoice",
+          "export-invoices"
+        ],
+        "name": "InvoiceHistory",
+        "related": [
+          "Table",
+          "TableToolbar",
+          "Badge",
+          "Button",
+          "EmptyState",
+          "Pagination"
+        ],
+        "slots": {
+          "empty": {
+            "description": "Custom empty-state content when `invoices` is empty. Falls back\nto a default <empty-state-ui icon=\"receipt\"> when omitted.\n"
+          },
+          "toolbar": {
+            "description": "Optional pre-table action toolbar — overrides the default\n<table-toolbar-ui> + export button stamp. Use when the host\nsurface needs custom actions (e.g. \"New invoice\", \"Reconcile\").\n"
+          }
+        },
+        "states": [
+          {
+            "description": "Default — rows rendered, ready for interaction.",
+            "name": "idle"
+          },
+          {
+            "description": "A `data-stream-src` fetch is in flight.",
+            "attribute": "loading",
+            "name": "loading"
+          },
+          {
+            "description": "No invoices to render (computed from invoices.length).",
+            "attribute": "empty",
+            "name": "empty"
+          },
+          {
+            "description": "Last `data-stream-src` fetch failed.",
+            "attribute": "error",
+            "name": "error"
+          }
+        ],
+        "status": "experimental",
+        "synonyms": {
+          "billing": [
+            "invoice",
+            "payment",
+            "subscription"
+          ],
+          "history": [
+            "log",
+            "audit",
+            "record",
+            "timeline"
+          ],
+          "invoice": [
+            "bill",
+            "statement",
+            "receipt"
+          ],
+          "receipts": [
+            "invoices",
+            "billing"
+          ],
+          "statement": [
+            "invoice",
+            "bill"
+          ]
+        },
+        "tag": "invoice-history-ui",
+        "tokens": {
+          "--invoice-history-amount-fg": {
+            "description": "Amount cell foreground.",
+            "default": "var(--a-fg-strong, var(--a-fg))"
+          },
+          "--invoice-history-amount-font": {
+            "description": "Font family for tabular amounts; defaults to the mono stack.",
+            "default": "var(--a-font-mono)"
+          },
+          "--invoice-history-bg": {
+            "description": "Host background. Defaults to transparent.",
+            "default": "transparent"
+          },
+          "--invoice-history-date-fg": {
+            "description": "Secondary metadata (issued / due dates) foreground.",
+            "default": "var(--a-fg-muted)"
+          },
+          "--invoice-history-filter-gap": {
+            "description": "Gap between status-filter chips.",
+            "default": "var(--a-space-2)"
+          },
+          "--invoice-history-gap": {
+            "description": "Vertical gap between toolbar / table / pagination regions.",
+            "default": "var(--a-space-3)"
+          },
+          "--invoice-history-row-min-height": {
+            "description": "Forwarded as `--table-row-h` to <table-ui>; row minimum height.",
+            "default": "var(--table-row-h, 3rem)"
+          },
+          "--invoice-history-toolbar-gap": {
+            "description": "Gap between toolbar clusters (title · filter chips · export).",
+            "default": "var(--a-space-3)"
+          }
+        },
+        "traits": [],
+        "version": 1
+      }
+    },
+    "Kbd": {
+      "title": "Kbd",
+      "description": "Keyboard key cap. Purely decorative, content from innerHTML — typically a single key or short chord like \"⌘K\" or \"Ctrl+Shift+P\". Use inline in menu items, tooltips, command hints, and shortcut documentation.",
+      "type": "object",
+      "allOf": [
+        {
+          "$ref": "#/$defs/ComponentCommon"
+        },
+        {
+          "$ref": "#/$defs/CatalogComponentCommon"
+        }
+      ],
+      "properties": {
+        "component": {
+          "const": "Kbd"
+        },
+        "size": {
+          "description": "Sizing scale (compact tier — sm / md only).",
+          "type": "string",
+          "enum": [
+            "sm",
+            "md"
+          ],
+          "default": ""
+        }
+      },
+      "required": [
+        "component"
+      ],
+      "unevaluatedProperties": false,
+      "x-adiaui": {
+        "anti_patterns": [],
+        "category": "display",
+        "composes": [],
+        "events": {},
+        "examples": [
+          {
+            "description": "Card displaying a grid of keyboard shortcut rows with key badges and descriptions.",
+            "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Card\",\n    \"children\": [\n      \"hdr\",\n      \"sec\"\n    ]\n  },\n  {\n    \"id\": \"hdr\",\n    \"component\": \"Header\",\n    \"children\": [\n      \"title\"\n    ]\n  },\n  {\n    \"id\": \"title\",\n    \"component\": \"Text\",\n    \"slot\": \"heading\",\n    \"textContent\": \"Keyboard Shortcuts\"\n  },\n  {\n    \"id\": \"sec\",\n    \"component\": \"Section\",\n    \"children\": [\n      \"grid\"\n    ]\n  },\n  {\n    \"id\": \"grid\",\n    \"component\": \"Grid\",\n    \"columns\": 1,\n    \"gap\": \"2\",\n    \"children\": [\n      \"r1\",\n      \"r2\",\n      \"r3\",\n      \"r4\",\n      \"r5\",\n      \"r6\"\n    ]\n  },\n  {\n    \"id\": \"r1\",\n    \"component\": \"Row\",\n    \"children\": [\n      \"k1\",\n      \"d1\"\n    ]\n  },\n  {\n    \"id\": \"k1\",\n    \"component\": \"Kbd\",\n    \"text\": \"Ctrl+K\"\n  },\n  {\n    \"id\": \"d1\",\n    \"component\": \"Text\",\n    \"textContent\": \"Open command palette\"\n  },\n  {\n    \"id\": \"r2\",\n    \"component\": \"Row\",\n    \"children\": [\n      \"k2\",\n      \"d2\"\n    ]\n  },\n  {\n    \"id\": \"k2\",\n    \"component\": \"Kbd\",\n    \"text\": \"Ctrl+S\"\n  },\n  {\n    \"id\": \"d2\",\n    \"component\": \"Text\",\n    \"textContent\": \"Save current file\"\n  },\n  {\n    \"id\": \"r3\",\n    \"component\": \"Row\",\n    \"children\": [\n      \"k3\",\n      \"d3\"\n    ]\n  },\n  {\n    \"id\": \"k3\",\n    \"component\": \"Kbd\",\n    \"text\": \"Ctrl+Z\"\n  },\n  {\n    \"id\": \"d3\",\n    \"component\": \"Text\",\n    \"textContent\": \"Undo last action\"\n  },\n  {\n    \"id\": \"r4\",\n    \"component\": \"Row\",\n    \"children\": [\n      \"k4\",\n      \"d4\"\n    ]\n  },\n  {\n    \"id\": \"k4\",\n    \"component\": \"Kbd\",\n    \"text\": \"Ctrl+Shift+P\"\n  },\n  {\n    \"id\": \"d4\",\n    \"component\": \"Text\",\n    \"textContent\": \"Toggle preview\"\n  },\n  {\n    \"id\": \"r5\",\n    \"component\": \"Row\",\n    \"children\": [\n      \"k5\",\n      \"d5\"\n    ]\n  },\n  {\n    \"id\": \"k5\",\n    \"component\": \"Kbd\",\n    \"text\": \"Ctrl+N\"\n  },\n  {\n    \"id\": \"d5\",\n    \"component\": \"Text\",\n    \"textContent\": \"Create new document\"\n  },\n  {\n    \"id\": \"r6\",\n    \"component\": \"Row\",\n    \"children\": [\n      \"k6\",\n      \"d6\"\n    ]\n  },\n  {\n    \"id\": \"k6\",\n    \"component\": \"Kbd\",\n    \"text\": \"Esc\"\n  },\n  {\n    \"id\": \"d6\",\n    \"component\": \"Text\",\n    \"textContent\": \"Close dialog\"\n  }\n]",
+            "name": "kbd-shortcuts"
+          }
+        ],
+        "keywords": [
+          "kbd",
+          "command",
+          "shortcut",
+          "hotkey",
+          "keyboard",
+          "keybinding"
+        ],
+        "name": "UIKbd",
+        "related": [
+          "grid"
+        ],
+        "slots": {
+          "default": {
+            "description": "Key label text"
+          }
+        },
+        "states": [
+          {
+            "description": "Default, ready for interaction.",
+            "name": "idle"
+          }
+        ],
+        "status": "stable",
+        "synonyms": {
+          "command": [
+            "command",
+            "palette",
+            "kbd",
+            "shortcut"
+          ],
+          "hotkey": [
+            "kbd",
+            "shortcut",
+            "command"
+          ],
+          "keybinding": [
+            "kbd",
+            "shortcut",
+            "command"
+          ],
+          "keyboard": [
+            "kbd",
+            "shortcut",
+            "command"
+          ],
+          "shortcut": [
+            "kbd",
+            "shortcut",
+            "command"
+          ],
+          "tags": [
+            "Keyboard"
+          ]
+        },
+        "tag": "kbd-ui",
+        "tokens": {},
         "traits": [],
         "version": 1
       }
@@ -12111,6 +13720,180 @@
         "version": 1
       }
     },
+    "LoadingOverlay": {
+      "title": "LoadingOverlay",
+      "description": "Container-scoped busy overlay. Covers a positioned parent region with a centered spinner (auto-stamped) or slotted indicator (skeleton-ui, progress-ui, custom) while async work is in flight. Wires aria-busy onto the parent on connect; applies a [delay] grace window to avoid flash on fast loads. For viewport-scoped / route loaders use a dedicated route-loader pattern; for submit-button busy use <button-ui loading>.",
+      "type": "object",
+      "allOf": [
+        {
+          "$ref": "#/$defs/ComponentCommon"
+        },
+        {
+          "$ref": "#/$defs/CatalogComponentCommon"
+        }
+      ],
+      "properties": {
+        "active": {
+          "description": "When set, overlay is visible and the parent container is marked aria-busy. Toggle from consumer code; default hidden.",
+          "$ref": "#/$defs/DynamicBoolean"
+        },
+        "component": {
+          "const": "LoadingOverlay"
+        },
+        "delay": {
+          "description": "Suppress the overlay until this many ms elapse. Prevents flash on fast loads. Default 200ms.",
+          "$ref": "#/$defs/DynamicNumber"
+        },
+        "label": {
+          "description": "Accessible operation name used by the host aria-label and forwarded to the auto-stamped spinner.",
+          "$ref": "#/$defs/DynamicString"
+        },
+        "variant": {
+          "description": "Backdrop treatment — default (muted scrim), transparent (no backdrop fill — useful with full-area skeleton indicators), blur (light scrim with backdrop-filter blur).",
+          "$ref": "#/$defs/DynamicString"
+        }
+      },
+      "required": [
+        "component"
+      ],
+      "unevaluatedProperties": false,
+      "x-adiaui": {
+        "anti_patterns": [
+          {
+            "fix": "{\"component\": \"Card\", \"children\": [\n  {\"component\": \"LoadingOverlay\", \"active\": true},\n  {\"component\": \"Table\", \"data-stream-src\": \"...\"}\n]}\n",
+            "why": "LoadingOverlay is container-scoped. Attaching it directly to Page\ncovers the entire viewport but lacks the route-loader's wiring\n(skeleton routing, route-level animation). Use the route loader.\n",
+            "wrong": "{\"component\": \"Page\", \"children\": [\n  {\"component\": \"LoadingOverlay\", \"active\": true}\n]}\n"
+          },
+          {
+            "fix": "{\"component\": \"Modal\", \"open\": true, \"loading\": true}\n",
+            "why": "Modal owns its own busy state and focus trap; nesting a\nLoadingOverlay introduces two competing inert toggles.\n",
+            "wrong": "{\"component\": \"Modal\", \"open\": true, \"children\": [\n  {\"component\": \"LoadingOverlay\", \"active\": true}\n]}\n"
+          },
+          {
+            "fix": "{\"component\": \"Form\", \"children\": [\n  {\"component\": \"Button\", \"text\": \"Submitting\", \"type\": \"submit\", \"loading\": true, \"disabled\": true}\n]}\n",
+            "why": "A form-submit affordance belongs on the button itself, not as an\noverlay over the entire form region. Use Button[loading].\n",
+            "wrong": "{\"component\": \"Form\", \"children\": [\n  {\"component\": \"Button\", \"text\": \"Submit\", \"type\": \"submit\"},\n  {\"component\": \"LoadingOverlay\", \"active\": true}\n]}\n"
+          }
+        ],
+        "category": "feedback",
+        "composes": [],
+        "events": {},
+        "examples": [
+          {
+            "description": "Card containing a table that loads on mount; the overlay covers the card's body while data streams.",
+            "a2ui": "[\n  {\n    \"id\": \"card\",\n    \"component\": \"Card\",\n    \"children\": [\"sec\"]\n  },\n  {\n    \"id\": \"sec\",\n    \"component\": \"Section\",\n    \"children\": [\"overlay\", \"table\"]\n  },\n  {\n    \"id\": \"overlay\",\n    \"component\": \"LoadingOverlay\",\n    \"active\": true,\n    \"label\": \"Loading orders…\"\n  },\n  {\n    \"id\": \"table\",\n    \"component\": \"Table\",\n    \"data-stream-src\": \"/api/orders\"\n  }\n]",
+            "name": "card-with-loading-table"
+          },
+          {
+            "description": "Skeleton-shaped placeholder overlay using the transparent variant — slot a stack of <Skeleton> rows.",
+            "a2ui": "[\n  {\n    \"id\": \"ov\",\n    \"component\": \"LoadingOverlay\",\n    \"active\": true,\n    \"variant\": \"transparent\",\n    \"label\": \"Loading content…\",\n    \"children\": [\"sk-stack\"]\n  },\n  {\n    \"id\": \"sk-stack\",\n    \"component\": \"Column\",\n    \"gap\": \"2\",\n    \"children\": [\"sk1\", \"sk2\", \"sk3\"]\n  },\n  {\n    \"id\": \"sk1\",\n    \"component\": \"Skeleton\",\n    \"width\": \"100%\",\n    \"height\": \"1rem\"\n  },\n  {\n    \"id\": \"sk2\",\n    \"component\": \"Skeleton\",\n    \"width\": \"80%\",\n    \"height\": \"1rem\"\n  },\n  {\n    \"id\": \"sk3\",\n    \"component\": \"Skeleton\",\n    \"width\": \"60%\",\n    \"height\": \"1rem\"\n  }\n]",
+            "name": "skeleton-overlay"
+          },
+          {
+            "description": "Overlay with the default 200ms grace window. If the underlying load resolves in less than 200ms, the overlay never paints.",
+            "a2ui": "[\n  {\n    \"id\": \"ov\",\n    \"component\": \"LoadingOverlay\",\n    \"active\": true,\n    \"delay\": 200,\n    \"label\": \"Loading\"\n  }\n]",
+            "name": "fast-load-no-flash"
+          }
+        ],
+        "keywords": [
+          "loading",
+          "overlay",
+          "busy",
+          "spinner",
+          "skeleton",
+          "placeholder",
+          "feedback",
+          "progress",
+          "indicator",
+          "wait"
+        ],
+        "name": "UILoadingOverlay",
+        "related": [
+          "Spinner",
+          "Skeleton",
+          "Progress",
+          "Card",
+          "Table",
+          "Modal"
+        ],
+        "slots": {
+          "default": {
+            "description": "Busy indicator content — <spinner-ui>, <skeleton-ui>, <progress-ui>, or custom. If empty, a centered <spinner-ui size=\"lg\"> is auto-stamped."
+          }
+        },
+        "states": [
+          {
+            "description": "Default, hidden. Parent interactive.",
+            "name": "idle"
+          },
+          {
+            "description": "Overlay visible; parent has aria-busy=\"true\".",
+            "attribute": "active",
+            "name": "active"
+          }
+        ],
+        "status": "stable",
+        "synonyms": {
+          "busy": [
+            "loading",
+            "overlay",
+            "busy",
+            "spinner"
+          ],
+          "loader": [
+            "loading",
+            "overlay",
+            "spinner"
+          ],
+          "loading": [
+            "loading",
+            "overlay",
+            "busy",
+            "spinner",
+            "skeleton"
+          ],
+          "overlay": [
+            "loading",
+            "overlay",
+            "busy"
+          ],
+          "spinner": [
+            "loading",
+            "overlay",
+            "spinner"
+          ]
+        },
+        "tag": "loading-overlay-ui",
+        "tokens": {
+          "--loading-overlay-bg": {
+            "description": "Backdrop fill color. Default uses the generic neutral scrim token.",
+            "default": "var(--a-scrim-default)"
+          },
+          "--loading-overlay-duration": {
+            "description": "Fade in / fade out duration.",
+            "default": "var(--a-duration)"
+          },
+          "--loading-overlay-easing": {
+            "description": "Fade easing curve.",
+            "default": "var(--a-easing-out)"
+          },
+          "--loading-overlay-gap": {
+            "description": "Vertical gap between the indicator and any sibling content (e.g. label, skeleton stack).",
+            "default": "var(--a-space-3)"
+          },
+          "--loading-overlay-radius": {
+            "description": "Backdrop corner radius. Matches the parent surface by default.",
+            "default": "var(--a-radius-md)"
+          },
+          "--loading-overlay-z": {
+            "description": "Stacking order. Sits above sibling content, below modal-ui (which uses ::backdrop on top-layer dialog).",
+            "default": "50"
+          }
+        },
+        "traits": [],
+        "version": 1
+      }
+    },
     "Menu": {
       "title": "Menu",
       "description": "Dropdown action menu with roving focus and keyboard navigation. Uses Popover API.",
@@ -12202,6 +13985,9 @@
         "slots": {
           "default": {
             "description": "Menu items with role=\"menuitem\" and optional <hr> dividers"
+          },
+          "trigger": {
+            "description": "Required. Focusable element that opens the menu when activated. Exactly one child must have slot=\"trigger\" — typically <button-ui>, but any focusable element works. Without it the menu cannot open via keyboard or pointer. Lives in light DOM; the items are hoisted to a top-layer popover on open."
           }
         },
         "states": [
@@ -13103,13 +14889,256 @@
             "bezier-wire"
           ]
         },
-        "tag": "noodles-ui",
+        "tag": "noodles-ui",
+        "tokens": {
+          "--noodles-duration": {
+            "description": "Transition duration for noodle animations"
+          },
+          "--noodles-easing": {
+            "description": "Easing function for noodle animations"
+          }
+        },
+        "traits": [],
+        "version": 1
+      }
+    },
+    "NotificationPreferences": {
+      "title": "NotificationPreferences",
+      "description": "Page-level Settings composite: a matrix of notification types (rows)\n× delivery channels (columns: in-app, email, SMS) with a binary\n<check-ui> in each cell and an optional <switch-ui> column-header\nmaster toggle for bulk-flipping a channel across every row.\n\nForm-bearing — the composite extends UIFormElement and serializes its\ncurrent preferences shape as JSON on `value`. Per first-principle #2\n(\"save is the consumer's job\"), the composite does NOT mutate the\npassed-in `preferences` array; it emits a typed `change` event per\ncell toggle and a `bulk-toggle` event per column-header switch, and\nexposes the staged JSON via the form value so a host <form> submit\ncarries it through ElementInternals.\n\nChannels are columns; types are rows (the smaller-set / larger-set\ninvariant — channels are 3-5 in the wild, types are 10-50). Layout\nrenders as a semantic ARIA grid (`role=\"table\"`/`row`/`cell`/\n`rowheader`/`columnheader`) — NOT native `<table>` (per the HTML\nparser strip rule, table-content tags would foster-parent out of a\ncustom-element subtree).\n\nSpec: docs/specs/implementation-ready/SPEC-064-notification-preferences.md.\n",
+      "type": "object",
+      "allOf": [
+        {
+          "$ref": "#/$defs/ComponentCommon"
+        },
+        {
+          "$ref": "#/$defs/CatalogComponentCommon"
+        }
+      ],
+      "properties": {
+        "channelEnabled": {
+          "description": "Map of channel-key → master-toggle boolean for the column-header\n<switch-ui>. When omitted, master toggles default to `true` for\nevery channel. Independent of cell values — toggling the master\noff does NOT auto-update the cells; the host receives a\n`bulk-toggle` event and updates `preferences` itself.\n",
+          "type": "object",
+          "default": {}
+        },
+        "channels": {
+          "description": "Column definitions — one record per delivery channel. Each\ncarries a stable `key`, a `label` (the column header), and an\noptional `icon` name (Phosphor — defaults to no icon when\nabsent). Example: [{key:\"in-app\", label:\"In-app\", icon:\"chat-circle\"},\n{key:\"email\", label:\"Email\", icon:\"envelope\"}]. Empty array\nrenders nothing (the matrix needs at least one column).\n",
+          "$ref": "#/$defs/DynamicStringList"
+        },
+        "component": {
+          "const": "NotificationPreferences"
+        },
+        "disabled": {
+          "description": "All cells + master toggles become non-interactive.",
+          "type": "boolean",
+          "default": false
+        },
+        "group-by": {
+          "description": "Row-grouping mode. `none` (default) renders all rows in one\nblock. `group` renders one section per unique `preferences[].group`\nvalue with a header row above each section.\n",
+          "type": "string",
+          "enum": [
+            "none",
+            "group"
+          ],
+          "default": "none"
+        },
+        "loading": {
+          "description": "Renders a skeleton matrix overlay. Cells become non-interactive\nand dim while loading.\n",
+          "type": "boolean",
+          "default": false
+        },
+        "preferences": {
+          "description": "Matrix data — one row per notification type. Each record carries\na stable `key`, a `label`, optional `description` (rendered under\nthe label), optional `group` (when `group-by=\"group\"`), and a\n`channels` map keyed by channel key with boolean values.\nExample: {key:\"mentions\", label:\"Mentions\", channels:{\"in-app\":true,\nemail:false, sms:false}}. Empty array renders the empty state.\n",
+          "$ref": "#/$defs/DynamicStringList"
+        }
+      },
+      "required": [
+        "component",
+        "preferences",
+        "channels"
+      ],
+      "unevaluatedProperties": false,
+      "x-adiaui": {
+        "anti_patterns": [
+          {
+            "fix": "<notification-preferences-ui id=\"prefs\"></notification-preferences-ui>\n<script>\n  document.querySelector('#prefs').channels = [\n    {key:'email', label:'Email'}\n  ];\n  document.querySelector('#prefs').preferences = [\n    {key:'mentions', label:'Mentions', channels:{email:true}},\n    {key:'replies',  label:'Replies',  channels:{email:false}}\n  ];\n</script>\n",
+            "why": "Cells are generated from the `preferences` matrix. Slotted\nswitches are ignored and the host renders empty.\n",
+            "wrong": "<notification-preferences-ui>\n  <switch-ui label=\"Email mentions\"></switch-ui>\n  <switch-ui label=\"Email replies\"></switch-ui>\n</notification-preferences-ui>\n"
+          },
+          {
+            "fix": "<notification-preferences-ui id=\"prefs\"></notification-preferences-ui>\n<script>/* set channels + preferences here */</script>\n",
+            "why": "Re-implements the matrix in raw HTML — loses the typed\n`change` / `bulk-toggle` event contract, the column-master\nswitch, the group-by support, and the consistent token-driven\nvisual treatment. Worse, table-content tags inside a custom\nelement subtree are foster-parented out of the DOM by the HTML\nparser — they silently vanish.\n",
+            "wrong": "<table>\n  <thead><tr><th></th><th>Email</th></tr></thead>\n  <tbody>\n    <tr><th>Mentions</th><td><check-ui></check-ui></td></tr>\n  </tbody>\n</table>\n"
+          }
+        ],
+        "category": "container",
+        "composes": [
+          "check-ui",
+          "switch-ui",
+          "icon-ui",
+          "text-ui",
+          "empty-state-ui"
+        ],
+        "events": {
+          "bulk-toggle": {
+            "description": "Fired when the user toggles a column-header <switch-ui>.\nBubbles. Mirrors `change` shape but for the column master —\nhost applies the bulk change to its own `preferences` data.\n",
+            "detail": {
+              "channel": {
+                "description": "The `key` of the channel column whose master flipped.",
+                "type": "string"
+              },
+              "enabled": {
+                "description": "The new desired master state.",
+                "type": "boolean"
+              }
+            }
+          },
+          "change": {
+            "description": "Fired when the user toggles a cell <check-ui>. Bubbles. The\ncomposite emits this with the previous state — the host must\napply the new state to its own data and re-pass `preferences`\nfor the cell to visually update.\n",
+            "detail": {
+              "channel": {
+                "description": "The `key` of the channel column whose cell flipped.",
+                "type": "string"
+              },
+              "enabled": {
+                "description": "The new desired state (true = opted in).",
+                "type": "boolean"
+              },
+              "row": {
+                "description": "The `key` of the notification type whose cell flipped.",
+                "type": "string"
+              }
+            }
+          }
+        },
+        "examples": [
+          {
+            "description": "Three channels (in-app / email / SMS) × four notification types.",
+            "a2ui": "[\n  {\n    \"id\": \"np-default\",\n    \"component\": \"NotificationPreferences\",\n    \"name\": \"notifications\",\n    \"channels\": [\n      {\"key\": \"in-app\", \"label\": \"In-app\", \"icon\": \"chat-circle\"},\n      {\"key\": \"email\",  \"label\": \"Email\",  \"icon\": \"envelope\"},\n      {\"key\": \"sms\",    \"label\": \"SMS\",    \"icon\": \"device-mobile\"}\n    ],\n    \"preferences\": [\n      {\"key\": \"mentions\", \"label\": \"Mentions\",\n       \"channels\": {\"in-app\": true, \"email\": true,  \"sms\": false}},\n      {\"key\": \"comments\", \"label\": \"Comments\",\n       \"channels\": {\"in-app\": true, \"email\": false, \"sms\": false}},\n      {\"key\": \"releases\", \"label\": \"Releases\",\n       \"channels\": {\"in-app\": false,\"email\": true,  \"sms\": false}},\n      {\"key\": \"security\", \"label\": \"Security alerts\",\n       \"channels\": {\"in-app\": true, \"email\": true,  \"sms\": true}}\n    ]\n  }\n]\n",
+            "name": "default"
+          },
+          {
+            "description": "Same matrix grouped by category via group-by=\"group\".",
+            "a2ui": "[\n  {\n    \"id\": \"np-grouped\",\n    \"component\": \"NotificationPreferences\",\n    \"name\": \"notifications\",\n    \"groupBy\": \"group\",\n    \"channels\": [\n      {\"key\": \"in-app\", \"label\": \"In-app\"},\n      {\"key\": \"email\",  \"label\": \"Email\"}\n    ],\n    \"preferences\": [\n      {\"key\": \"mentions\", \"label\": \"Mentions\", \"group\": \"Activity\",\n       \"channels\": {\"in-app\": true, \"email\": true}},\n      {\"key\": \"comments\", \"label\": \"Comments\", \"group\": \"Activity\",\n       \"channels\": {\"in-app\": true, \"email\": false}},\n      {\"key\": \"digest\",   \"label\": \"Weekly digest\", \"group\": \"Summaries\",\n       \"channels\": {\"in-app\": false, \"email\": true}}\n    ]\n  }\n]\n",
+            "name": "grouped"
+          }
+        ],
+        "keywords": [
+          "notification-preferences",
+          "notifications",
+          "preferences",
+          "opt-in",
+          "opt-out",
+          "alerts",
+          "channels",
+          "in-app",
+          "email",
+          "sms",
+          "subscriptions",
+          "notification-settings"
+        ],
+        "name": "UINotificationPreferences",
+        "related": [
+          "Check",
+          "Switch",
+          "Table",
+          "EmptyState",
+          "Icon",
+          "Text"
+        ],
+        "slots": {
+          "empty": {
+            "description": "Custom empty-state copy shown when `preferences` is empty. Falls\nback to a default <empty-state-ui> when not provided.\n"
+          },
+          "footer": {
+            "description": "Optional content below the matrix — e.g. a global Save Changes\nbutton row or fine-print disclaimer. Falls back to nothing.\n"
+          },
+          "header": {
+            "description": "Optional content above the matrix — e.g. a page title, intro\ncopy, or per-page save row. Falls back to nothing when empty.\n"
+          }
+        },
+        "states": [
+          {
+            "description": "Default — matrix rendered, ready for interaction.",
+            "name": "idle"
+          },
+          {
+            "description": "Skeleton overlay while data loads.",
+            "attribute": "loading",
+            "name": "loading"
+          },
+          {
+            "description": "All toggles non-interactive.",
+            "attribute": "disabled",
+            "name": "disabled"
+          },
+          {
+            "description": "No notification types configured.",
+            "attribute": "empty",
+            "name": "empty"
+          }
+        ],
+        "status": "stable",
+        "synonyms": {
+          "channels": [
+            "delivery",
+            "destinations"
+          ],
+          "notifications": [
+            "alerts",
+            "messages",
+            "updates"
+          ],
+          "preferences": [
+            "settings",
+            "opt-ins",
+            "subscriptions"
+          ]
+        },
+        "tag": "notification-preferences-ui",
         "tokens": {
-          "--noodles-duration": {
-            "description": "Transition duration for noodle animations"
+          "--notification-preferences-bg": {
+            "description": "Host background.",
+            "default": "var(--a-bg)"
           },
-          "--noodles-easing": {
-            "description": "Easing function for noodle animations"
+          "--notification-preferences-border": {
+            "description": "Row separator color.",
+            "default": "var(--a-border-subtle)"
+          },
+          "--notification-preferences-channel-width": {
+            "description": "Minimum column width for each channel cell.",
+            "default": "var(--a-space-9)"
+          },
+          "--notification-preferences-group-fg": {
+            "description": "Group-heading label color.",
+            "default": "var(--a-fg-muted)"
+          },
+          "--notification-preferences-px": {
+            "description": "Host horizontal padding.",
+            "default": "var(--a-space-5)"
+          },
+          "--notification-preferences-py": {
+            "description": "Host vertical padding.",
+            "default": "var(--a-space-5)"
+          },
+          "--notification-preferences-radius": {
+            "description": "Outer matrix container radius.",
+            "default": "var(--a-radius-md)"
+          },
+          "--notification-preferences-row-bg": {
+            "description": "Even-row zebra background.",
+            "default": "var(--a-bg-muted)"
+          },
+          "--notification-preferences-row-label-min": {
+            "description": "Minimum row-label column width.",
+            "default": "12rem"
+          },
+          "--notification-preferences-row-px": {
+            "description": "Per-cell horizontal padding.",
+            "default": "var(--a-space-3)"
+          },
+          "--notification-preferences-row-py": {
+            "description": "Per-row vertical padding.",
+            "default": "var(--a-space-3)"
           }
         },
         "traits": [],
@@ -13917,85 +15946,499 @@
       ],
       "unevaluatedProperties": false,
       "x-adiaui": {
-        "anti_patterns": [],
-        "category": "navigation",
-        "composes": [],
+        "anti_patterns": [],
+        "category": "navigation",
+        "composes": [],
+        "events": {
+          "page-change": {
+            "description": "Fired when a page button is clicked. detail contains { page }.",
+            "detail": {
+              "page": {
+                "description": "New page number.",
+                "type": "number"
+              }
+            }
+          }
+        },
+        "examples": [
+          {
+            "description": "Card with header containing title and search input, table component, and pagination footer.",
+            "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Card\",\n    \"size\": \"lg\",\n    \"children\": [\n      \"hdr\",\n      \"sec\",\n      \"ftr\"\n    ]\n  },\n  {\n    \"id\": \"hdr\",\n    \"component\": \"Header\",\n    \"children\": [\n      \"title-row\"\n    ]\n  },\n  {\n    \"id\": \"title-row\",\n    \"component\": \"Row\",\n    \"children\": [\n      \"title\",\n      \"search\"\n    ],\n    \"gap\": \"4\"\n  },\n  {\n    \"id\": \"title\",\n    \"component\": \"Text\",\n    \"slot\": \"heading\",\n    \"textContent\": \"Data Table\",\n    \"variant\": \"section\"\n  },\n  {\n    \"id\": \"search\",\n    \"component\": \"Input\",\n    \"placeholder\": \"Search...\",\n    \"type\": \"search\",\n    \"name\": \"search\"\n  },\n  {\n    \"id\": \"sec\",\n    \"component\": \"Section\",\n    \"children\": [\n      \"tbl\"\n    ]\n  },\n  {\n    \"id\": \"tbl\",\n    \"component\": \"Table\",\n    \"sortable\": true\n  },\n  {\n    \"id\": \"ftr\",\n    \"component\": \"Footer\",\n    \"children\": [\n      \"pager\"\n    ]\n  },\n  {\n    \"id\": \"pager\",\n    \"component\": \"Pagination\",\n    \"total\": 10,\n    \"page\": 1\n  }\n]",
+            "name": "data-table-view"
+          },
+          {
+            "description": "Row with centered pagination component for navigating paged content.",
+            "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Row\",\n    \"justify\": \"center\",\n    \"children\": [\n      \"pager\"\n    ]\n  },\n  {\n    \"id\": \"pager\",\n    \"component\": \"Pagination\",\n    \"total\": 10,\n    \"page\": 1\n  }\n]",
+            "name": "pagination-nav"
+          }
+        ],
+        "keywords": [
+          "pagination",
+          "navigation",
+          "back",
+          "paginate",
+          "paging"
+        ],
+        "name": "UIPagination",
+        "related": [
+          "input",
+          "table"
+        ],
+        "slots": {},
+        "states": [
+          {
+            "description": "Default, ready for interaction.",
+            "name": "idle"
+          }
+        ],
+        "status": "stable",
+        "synonyms": {
+          "back": [
+            "breadcrumb",
+            "nav",
+            "pagination"
+          ],
+          "navigation": [
+            "nav",
+            "sidebar",
+            "breadcrumb",
+            "tabs",
+            "menu",
+            "pagination"
+          ],
+          "paginate": [
+            "pagination",
+            "nav",
+            "table"
+          ],
+          "paging": [
+            "pagination",
+            "nav"
+          ]
+        },
+        "tag": "pagination-ui",
+        "tokens": {},
+        "traits": [],
+        "version": 1
+      }
+    },
+    "Pane": {
+      "title": "Pane",
+      "description": "Collapsible, resizable content panel — drag-resize handle on the\ninner edge when [side=\"leading\"] / [side=\"trailing\"], [resizable]\nopt-in. Used standalone for resizable two-pane layouts, or wrapped\nby <editor-sidebar> / <admin-sidebar> which DELEGATE drag to the\ninner pane-ui rather than reimplementing it. See pane.yaml's\na2ui.rules for the full composition contract.\n",
+      "type": "object",
+      "allOf": [
+        {
+          "$ref": "#/$defs/ComponentCommon"
+        },
+        {
+          "$ref": "#/$defs/CatalogComponentCommon"
+        }
+      ],
+      "properties": {
+        "collapsed": {
+          "description": "Component property: collapsed.",
+          "type": "boolean",
+          "default": false
+        },
+        "component": {
+          "const": "Pane"
+        },
+        "maxWidth": {
+          "description": "Component property: maxWidth.",
+          "type": "number",
+          "default": 9999
+        },
+        "minWidth": {
+          "description": "Component property: minWidth.",
+          "type": "number",
+          "default": 200
+        },
+        "resizable": {
+          "description": "Component property: resizable.",
+          "type": "boolean",
+          "default": false
+        },
+        "side": {
+          "description": "Opts a pane into horizontal-sibling chrome: suppresses the default\nfour-sided border and moves the resize grabber to the inner edge\n(right edge for `leading`, left edge for `trailing`). Also flips the\nresize-drag direction so `trailing` panes grow when dragged leftward.\nUnset keeps the pane-intrinsic chrome (full border, right-edge\ngrabber when resizable).\n",
+          "type": "string",
+          "enum": [
+            "",
+            "leading",
+            "trailing"
+          ],
+          "default": ""
+        }
+      },
+      "required": [
+        "component"
+      ],
+      "unevaluatedProperties": false,
+      "x-adiaui": {
+        "anti_patterns": [],
+        "category": "layout",
+        "composes": [
+          "icon-ui"
+        ],
+        "events": {
+          "toggle": {
+            "description": "Fired when the pane's collapsed state flips (via button press, keyboard, or programmatic toggle()). Bubbles."
+          }
+        },
+        "examples": [
+          {
+            "description": "Split pane with TextArea for editing markdown on the left and a preview card on the right.",
+            "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Row\",\n    \"children\": [\n      \"left\",\n      \"right\"\n    ]\n  },\n  {\n    \"id\": \"left\",\n    \"component\": \"Pane\",\n    \"resizable\": true,\n    \"width\": \"50%\",\n    \"children\": [\n      \"editor-card\"\n    ]\n  },\n  {\n    \"id\": \"editor-card\",\n    \"component\": \"Card\",\n    \"children\": [\n      \"ed-hdr\",\n      \"ed-sec\"\n    ]\n  },\n  {\n    \"id\": \"ed-hdr\",\n    \"component\": \"Header\",\n    \"children\": [\n      \"ed-title\"\n    ]\n  },\n  {\n    \"id\": \"ed-title\",\n    \"component\": \"Text\",\n    \"slot\": \"heading\",\n    \"textContent\": \"Editor\"\n  },\n  {\n    \"id\": \"ed-sec\",\n    \"component\": \"Section\",\n    \"children\": [\n      \"textarea\"\n    ]\n  },\n  {\n    \"id\": \"textarea\",\n    \"component\": \"TextArea\",\n    \"placeholder\": \"Write your markdown here...\",\n    \"rows\": 20\n  },\n  {\n    \"id\": \"right\",\n    \"component\": \"Pane\",\n    \"resizable\": true,\n    \"width\": \"50%\",\n    \"children\": [\n      \"preview-card\"\n    ]\n  },\n  {\n    \"id\": \"preview-card\",\n    \"component\": \"Card\",\n    \"children\": [\n      \"pv-hdr\",\n      \"pv-sec\"\n    ]\n  },\n  {\n    \"id\": \"pv-hdr\",\n    \"component\": \"Header\",\n    \"children\": [\n      \"pv-title\"\n    ]\n  },\n  {\n    \"id\": \"pv-title\",\n    \"component\": \"Text\",\n    \"slot\": \"heading\",\n    \"textContent\": \"Preview\"\n  },\n  {\n    \"id\": \"pv-sec\",\n    \"component\": \"Section\",\n    \"children\": [\n      \"preview-text\"\n    ]\n  },\n  {\n    \"id\": \"preview-text\",\n    \"component\": \"Text\",\n    \"variant\": \"body\",\n    \"textContent\": \"Rendered markdown will appear here...\"\n  }\n]",
+            "name": "markdown-editor"
+          },
+          {
+            "description": "Row with two resizable Pane components for left/right panel layout.",
+            "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Row\",\n    \"children\": [\n      \"left\",\n      \"right\"\n    ]\n  },\n  {\n    \"id\": \"left\",\n    \"component\": \"Pane\",\n    \"resizable\": true,\n    \"width\": \"50%\",\n    \"children\": [\n      \"ltxt\"\n    ]\n  },\n  {\n    \"id\": \"ltxt\",\n    \"component\": \"Text\",\n    \"variant\": \"body\",\n    \"textContent\": \"Left panel content\"\n  },\n  {\n    \"id\": \"right\",\n    \"component\": \"Pane\",\n    \"resizable\": true,\n    \"width\": \"50%\",\n    \"children\": [\n      \"rtxt\"\n    ]\n  },\n  {\n    \"id\": \"rtxt\",\n    \"component\": \"Text\",\n    \"variant\": \"body\",\n    \"textContent\": \"Right panel content\"\n  }\n]",
+            "name": "split-pane"
+          }
+        ],
+        "keywords": [
+          "pane"
+        ],
+        "name": "UIPane",
+        "related": [
+          "text-area"
+        ],
+        "slots": {
+          "header": {
+            "description": "Auto-created header element with label text and toggle arrow"
+          }
+        },
+        "states": [
+          {
+            "description": "Default, ready for interaction.",
+            "name": "idle"
+          }
+        ],
+        "status": "stable",
+        "synonyms": {
+          "tags": [
+            "split-pane",
+            "side-panel",
+            "resizable-panel",
+            "detail-pane",
+            "list-pane",
+            "context-pane",
+            "Panel",
+            "Pane"
+          ]
+        },
+        "tag": "pane-ui",
+        "tokens": {},
+        "traits": [],
+        "version": 1
+      }
+    },
+    "PaymentMethodForm": {
+      "title": "PaymentMethodForm",
+      "description": "Form-participating composite for capturing a payment method —\ncard number, expiry, CVC, name on card, billing address (optional),\nand country. The form chrome + structured validation + a single\nnormalized emit event; it does NOT integrate with Stripe Elements\nor a tokenization SDK directly (consumer responsibility).\n\nEach sub-field is a <field-ui> wrapper around an <input-ui> (or\n<select-ui> for country). Card number is Luhn-validated; expiry is\nparsed as MM/YY with month + year bounds; CVC is 3-4 digits.\nBrand detection (visa / mastercard / amex / discover) runs against\na small regex map and surfaces via the `change` event detail.\n\nForm value is a JSON-encoded payload of normalized field values\nserialized through ElementInternals under [name] (default\n\"paymentMethod\"). On submit, the host fires\n`submit-payment-method` with a flat detail\n`{ token, last4, brand, expMonth, expYear, name, country }`.\n`token` is a synthetic local-mode token (sha-like opaque string);\nconsumers integrating with a real processor handle tokenization\nin their own submit listener using `last4` / `brand` / etc.\n\nSpec: docs/specs/implementation-ready/SPEC-009-payment-method-form.md.\n",
+      "type": "object",
+      "allOf": [
+        {
+          "$ref": "#/$defs/ComponentCommon"
+        },
+        {
+          "$ref": "#/$defs/CatalogComponentCommon"
+        }
+      ],
+      "properties": {
+        "required": {
+          "description": "Form-validation gate. When set, an empty composite fails\ncheckValidity() with \"Payment method required.\".\n",
+          "type": "boolean",
+          "default": false
+        },
+        "autofocus": {
+          "description": "When set, the first sub-field (Name on card) receives focus on\nfirst connect. Convention parity with native form elements.\n",
+          "type": "boolean",
+          "default": false
+        },
+        "component": {
+          "const": "PaymentMethodForm"
+        },
+        "countries": {
+          "description": "Allowed billing countries, ISO 3166-1 alpha-2 codes. Drives\nthe <select-ui> dropdown's options. Empty array uses a\ndefault short list (US, CA, GB, DE, FR, AU).\n",
+          "$ref": "#/$defs/DynamicStringList"
+        },
+        "default-country": {
+          "description": "Default selected country (ISO 3166-1 alpha-2). Falls back to\nthe first entry in `countries` (or \"US\" when empty).\n",
+          "type": "string",
+          "default": "US"
+        },
+        "disabled": {
+          "description": "Forwarded to every sub-control. Pointer-events:none on the\ncomposite host as a belt-and-suspenders.\n",
+          "$ref": "#/$defs/DynamicBoolean"
+        },
+        "error": {
+          "description": "Externally-set error message (e.g. server-rejected card). When\nnon-empty, the composite renders an <alert-ui variant=\"danger\">\nat the top of the form and sets aria-invalid=true on the host.\n",
+          "$ref": "#/$defs/DynamicString"
+        },
+        "name": {
+          "description": "Form field name. The composite's serialized form value lives\nunder this key in any wrapping <form>. Defaults to\n\"paymentMethod\".\n",
+          "type": "string",
+          "default": "paymentMethod"
+        },
+        "prefill": {
+          "description": "JSON-encoded prefill payload `{last4, brand, expMonth, expYear,\nname, country}`. When set, the summary row renders with the\nsaved-card chrome and the rest of the form is hidden behind an\n\"Edit card\" button. Useful for \"update saved payment method\"\nflows.\n",
+          "type": "string",
+          "default": ""
+        },
+        "require-billing-address": {
+          "description": "When set, renders the billing-address sub-fields (address line\n1, optional line 2, postal code). When unset, only postal code\n+ country are collected for the address-verification check.\n",
+          "type": "boolean",
+          "default": false
+        },
+        "value": {
+          "description": "Resolved payment-method token. Read-only externally — the\ncomposite writes it after a successful tokenize() call. Setting\nthis to a non-empty string is treated as \"prefilled from a\nsaved payment method\" and renders the form in\nread-only-summary mode (last4 + brand + expiry shown).\n",
+          "$ref": "#/$defs/DynamicString"
+        }
+      },
+      "required": [
+        "component"
+      ],
+      "unevaluatedProperties": false,
+      "x-adiaui": {
+        "anti_patterns": [
+          {
+            "fix": "<payment-method-form-ui name=\"paymentMethod\" required></payment-method-form-ui>\n",
+            "why": "Raw card digits in `value`. The composite's value is the\ntokenized output, never the input. Raw digits leak through\nreflection back to the attribute and end up in DOM snapshots /\nbrowser history / analytics.\n",
+            "wrong": "<payment-method-form-ui value=\"4242 4242 4242 4242\"></payment-method-form-ui>\n"
+          },
+          {
+            "fix": "<payment-method-form-ui aria-label=\"Card details\"></payment-method-form-ui>\n",
+            "why": "PaymentMethodForm IS itself a labeled field group; nesting in\nField duplicates the label and breaks the internal grid\nlayout. Field's auto-id stamping confuses the composite's\nfirst-focusable lookup.\n",
+            "wrong": "<field-ui label=\"Card details\">\n  <payment-method-form-ui></payment-method-form-ui>\n</field-ui>\n"
+          },
+          {
+            "fix": "<form>\n  <payment-method-form-ui id=\"pm\"></payment-method-form-ui>\n  <button-ui type=\"submit\" text=\"Save\"></button-ui>\n</form>\n<script>\n  form.addEventListener('submit', async (e) => {\n    e.preventDefault();\n    const detail = await pm.tokenize();\n    // Hand `detail.last4` / `detail.brand` to your processor SDK\n    // to mint a real token; POST the resulting token to /charge.\n  });\n</script>\n",
+            "why": "Posting the form's serialized token directly to /charge skips\ntokenization — the synthetic local-mode token is opaque but\nNOT a real payment token. A real processor must mint the\ntoken before the charge call.\n",
+            "wrong": "<form>\n  <payment-method-form-ui></payment-method-form-ui>\n  <button-ui type=\"submit\" text=\"Save\"></button-ui>\n</form>\n<script>\n  form.addEventListener('submit', (e) => fetch('/charge', { body: new FormData(form) }));\n</script>\n"
+          }
+        ],
+        "category": "input",
+        "composes": [
+          "field-ui",
+          "input-ui",
+          "select-ui",
+          "alert-ui",
+          "icon-ui",
+          "button-ui"
+        ],
         "events": {
-          "page-change": {
-            "description": "Fired when a page button is clicked. detail contains { page }.",
+          "change": {
+            "description": "Fired on every sub-field input. Detail carries a snapshot of\nthe current form validity + detected card brand. Bubbles.\n",
             "detail": {
-              "page": {
-                "description": "New page number.",
-                "type": "number"
+              "brand": {
+                "description": "Detected brand (`visa` / `mastercard` / `amex` / `discover` / `unknown`).",
+                "type": "string"
+              },
+              "valid": {
+                "description": "Whether the form currently passes all constraints.",
+                "type": "boolean"
+              }
+            }
+          },
+          "payment-method-error": {
+            "description": "Fired when tokenize() fails — either constraint validation\nsurfaced one or more field errors, or a Luhn / expiry / CVC\ncheck failed. Bubbles.\n",
+            "detail": {
+              "code": {
+                "description": "Error code — one of `validation-failed`, `card-invalid`, `expired`, `cvc-invalid`.",
+                "type": "string"
+              },
+              "field": {
+                "description": "Field name that surfaced the error (`cardNumber` / `expiry` / `cvc` / `name` / `postalCode` / `country` / null).",
+                "type": "string"
+              },
+              "message": {
+                "description": "Human-readable error message.",
+                "type": "string"
+              }
+            }
+          },
+          "submit-payment-method": {
+            "description": "Fired when tokenize() resolves — either via an outer <form>\nsubmission or an explicit tokenize() call. Detail carries the\nnormalized payload that downstream code POSTs to the billing\nservice. Bubbles.\n",
+            "detail": {
+              "brand": {
+                "description": "Detected brand — `visa`, `mastercard`, `amex`, `discover`, or `unknown`.",
+                "type": "string"
+              },
+              "country": {
+                "description": "ISO 3166-1 alpha-2 billing country.",
+                "type": "string"
+              },
+              "expMonth": {
+                "description": "Expiry month (1-12).",
+                "type": "integer"
+              },
+              "expYear": {
+                "description": "Expiry year (4-digit).",
+                "type": "integer"
+              },
+              "last4": {
+                "description": "Last 4 digits of the card number.",
+                "type": "string"
+              },
+              "name": {
+                "description": "Name on card.",
+                "type": "string"
+              },
+              "token": {
+                "description": "Synthetic local-mode token (sha-like opaque string).",
+                "type": "string"
               }
             }
           }
         },
         "examples": [
           {
-            "description": "Card with header containing title and search input, table component, and pagination footer.",
-            "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Card\",\n    \"size\": \"lg\",\n    \"children\": [\n      \"hdr\",\n      \"sec\",\n      \"ftr\"\n    ]\n  },\n  {\n    \"id\": \"hdr\",\n    \"component\": \"Header\",\n    \"children\": [\n      \"title-row\"\n    ]\n  },\n  {\n    \"id\": \"title-row\",\n    \"component\": \"Row\",\n    \"children\": [\n      \"title\",\n      \"search\"\n    ],\n    \"gap\": \"4\"\n  },\n  {\n    \"id\": \"title\",\n    \"component\": \"Text\",\n    \"slot\": \"heading\",\n    \"textContent\": \"Data Table\",\n    \"variant\": \"section\"\n  },\n  {\n    \"id\": \"search\",\n    \"component\": \"Input\",\n    \"placeholder\": \"Search...\",\n    \"type\": \"search\",\n    \"name\": \"search\"\n  },\n  {\n    \"id\": \"sec\",\n    \"component\": \"Section\",\n    \"children\": [\n      \"tbl\"\n    ]\n  },\n  {\n    \"id\": \"tbl\",\n    \"component\": \"Table\",\n    \"sortable\": true\n  },\n  {\n    \"id\": \"ftr\",\n    \"component\": \"Footer\",\n    \"children\": [\n      \"pager\"\n    ]\n  },\n  {\n    \"id\": \"pager\",\n    \"component\": \"Pagination\",\n    \"total\": 10,\n    \"page\": 1\n  }\n]",
-            "name": "data-table-view"
+            "description": "Empty form, all sub-fields visible, required.",
+            "a2ui": "[\n  {\n    \"id\": \"pm-1\",\n    \"component\": \"PaymentMethodForm\",\n    \"name\": \"paymentMethod\",\n    \"required\": true\n  }\n]\n",
+            "name": "default"
           },
           {
-            "description": "Row with centered pagination component for navigating paged content.",
-            "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Row\",\n    \"justify\": \"center\",\n    \"children\": [\n      \"pager\"\n    ]\n  },\n  {\n    \"id\": \"pager\",\n    \"component\": \"Pagination\",\n    \"total\": 10,\n    \"page\": 1\n  }\n]",
-            "name": "pagination-nav"
+            "description": "Edit-saved-card flow — summary row renders with the saved\ncard; \"Edit card\" CTA reveals the full form.\n",
+            "a2ui": "[\n  {\n    \"id\": \"pm-2\",\n    \"component\": \"PaymentMethodForm\",\n    \"name\": \"paymentMethod\",\n    \"prefill\": \"{\\\"last4\\\":\\\"4242\\\",\\\"brand\\\":\\\"visa\\\",\\\"expMonth\\\":12,\\\"expYear\\\":2027,\\\"name\\\":\\\"Pat Doe\\\",\\\"country\\\":\\\"US\\\"}\"\n  }\n]\n",
+            "name": "prefilled-saved-card"
+          },
+          {
+            "description": "Full form including billing address lines + postal + country.\n",
+            "a2ui": "[\n  {\n    \"id\": \"pm-3\",\n    \"component\": \"PaymentMethodForm\",\n    \"name\": \"paymentMethod\",\n    \"requireBillingAddress\": true,\n    \"countries\": [\"US\", \"CA\", \"GB\", \"DE\"]\n  }\n]\n",
+            "name": "with-billing-address"
           }
         ],
         "keywords": [
-          "pagination",
-          "navigation",
-          "back",
-          "paginate",
-          "paging"
-        ],
-        "name": "UIPagination",
+          "payment-method",
+          "card",
+          "billing",
+          "checkout",
+          "card-capture",
+          "payment",
+          "credit-card",
+          "debit-card",
+          "save-payment-method",
+          "update-payment-method",
+          "add-card"
+        ],
+        "name": "UIPaymentMethodForm",
         "related": [
-          "input",
-          "table"
+          "Form",
+          "Field",
+          "Input",
+          "Select",
+          "Alert",
+          "PlanPicker",
+          "Button"
         ],
-        "slots": {},
+        "slots": {
+          "legal": {
+            "description": "Optional content rendered below the form fields — typically a\nterms-of-storage acknowledgement string with link(s).\n"
+          }
+        },
         "states": [
           {
-            "description": "Default, ready for interaction.",
+            "description": "Default; ready for input.",
             "name": "idle"
+          },
+          {
+            "description": "tokenize() in flight.",
+            "attribute": "tokenizing",
+            "name": "tokenizing"
+          },
+          {
+            "description": "A field-level or host-level error is present.",
+            "attribute": "error",
+            "name": "error"
+          },
+          {
+            "description": "A saved payment method is displayed; form is hidden.",
+            "attribute": "prefilled",
+            "name": "prefilled"
+          },
+          {
+            "description": "All sub-fields non-interactive.",
+            "attribute": "disabled",
+            "name": "disabled"
           }
         ],
-        "status": "stable",
+        "status": "experimental",
         "synonyms": {
-          "back": [
-            "breadcrumb",
-            "nav",
-            "pagination"
-          ],
-          "navigation": [
-            "nav",
-            "sidebar",
-            "breadcrumb",
-            "tabs",
-            "menu",
-            "pagination"
+          "billing": [
+            "billing-info",
+            "payment-method",
+            "card"
           ],
-          "paginate": [
-            "pagination",
-            "nav",
-            "table"
+          "card": [
+            "payment-card",
+            "credit-card",
+            "debit-card"
           ],
-          "paging": [
-            "pagination",
-            "nav"
+          "payment-method": [
+            "card",
+            "card-on-file",
+            "billing"
           ]
         },
-        "tag": "pagination-ui",
-        "tokens": {},
+        "tag": "payment-method-form-ui",
+        "tokens": {
+          "--payment-method-form-alert-mb": {
+            "description": "Margin-block-end on the host-level error alert.",
+            "default": "var(--a-space-3)"
+          },
+          "--payment-method-form-brand-icon-size": {
+            "description": "Inline brand-badge icon size in the card-number suffix.",
+            "default": "1.25em"
+          },
+          "--payment-method-form-disabled-opacity": {
+            "description": "Opacity applied to the host when [disabled].",
+            "default": "var(--a-opacity-disabled, 0.5)"
+          },
+          "--payment-method-form-gap": {
+            "description": "Gap between rows of the form grid.",
+            "default": "var(--a-space-3)"
+          },
+          "--payment-method-form-grid-template": {
+            "description": "Grid-template-areas for the field layout. Defaults to a\n4-row template — name spans both columns, card number spans\nboth, expiry + cvc share row 3, country + postal share row 4.\nAddress rows append when `require-billing-address` is set.\n",
+            "default": "\"name name\" \"card card\" \"expiry cvc\" \"country postal\""
+          },
+          "--payment-method-form-legal-fg": {
+            "description": "Foreground color of the slotted legal copy.",
+            "default": "var(--a-fg-muted)"
+          },
+          "--payment-method-form-legal-size": {
+            "description": "Font size of the slotted legal copy.",
+            "default": "var(--a-text-xs, 0.75rem)"
+          },
+          "--payment-method-form-summary-bg": {
+            "description": "Background of the saved-card summary row.",
+            "default": "var(--a-bg-muted)"
+          },
+          "--payment-method-form-summary-border": {
+            "description": "Border on the saved-card summary row.",
+            "default": "1px solid var(--a-border)"
+          },
+          "--payment-method-form-summary-px": {
+            "description": "Horizontal padding inside the saved-card summary row.",
+            "default": "var(--a-space-4)"
+          },
+          "--payment-method-form-summary-py": {
+            "description": "Vertical padding inside the saved-card summary row.",
+            "default": "var(--a-space-3)"
+          },
+          "--payment-method-form-summary-radius": {
+            "description": "Corner radius on the saved-card summary row.",
+            "default": "var(--a-radius-md)"
+          }
+        },
         "traits": [],
         "version": 1
       }
     },
-    "Pane": {
-      "title": "Pane",
-      "description": "Collapsible, resizable content panel — drag-resize handle on the\ninner edge when [side=\"leading\"] / [side=\"trailing\"], [resizable]\nopt-in. Used standalone for resizable two-pane layouts, or wrapped\nby <editor-sidebar> / <admin-sidebar> which DELEGATE drag to the\ninner pane-ui rather than reimplementing it. See pane.yaml's\na2ui.rules for the full composition contract.\n",
+    "PaymentMethodList": {
+      "title": "PaymentMethodList",
+      "description": "Compound billing primitive that renders the user's saved payment\nmethods (cards, bank accounts, wallets) as a vertical list with one\nrow designated as the default. Each row shows a brand mark, the\nlast-4 / account identifier, an optional expiry, and per-row actions\n(set-default / edit / remove). A trailing \"Add payment method\" CTA\nemits `add` so consumers can route the consumer flow.\n\nDefault is a strict 1-of-N radiogroup — exactly one row carries the\ndefault state when the list is non-empty. The primitive does NOT\nmutate the data source; all changes flow as events (`change`,\n`add`, `remove`, `select`) and the consumer applies the side\neffect against their billing API.\n\nSpec: docs/specs/implementation-ready/SPEC-010-payment-method-list.md.\n",
       "type": "object",
       "allOf": [
         {
@@ -14006,38 +16449,46 @@
         }
       ],
       "properties": {
-        "collapsed": {
-          "description": "Component property: collapsed.",
+        "add-icon": {
+          "description": "Phosphor icon name for the add CTA.",
+          "type": "string",
+          "default": "plus"
+        },
+        "add-label": {
+          "description": "Label for the trailing add CTA.",
+          "type": "string",
+          "default": "Add payment method"
+        },
+        "component": {
+          "const": "PaymentMethodList"
+        },
+        "disabled": {
+          "description": "Block all interaction; rows remain visible.",
           "type": "boolean",
           "default": false
         },
-        "component": {
-          "const": "Pane"
+        "methods": {
+          "description": "Array of saved payment-method records. Source of truth for the\nrendered rows. Shape per record:\n{id, brand, last4?, expiry?, holder?, type, default?, status?}.\nEmpty array renders the empty-state.\n",
+          "$ref": "#/$defs/DynamicStringList"
         },
-        "maxWidth": {
-          "description": "Component property: maxWidth.",
-          "type": "number",
-          "default": 9999
+        "name": {
+          "description": "Form field name for the default-method id. Serialized via\nElementInternals; mirrors UIFormElement conventions.\n",
+          "type": "string",
+          "default": ""
         },
-        "minWidth": {
-          "description": "Component property: minWidth.",
-          "type": "number",
-          "default": 200
+        "no-add": {
+          "description": "Hide the trailing \"Add payment method\" CTA (read-only flow,\ncheckout drawer, etc.).\n",
+          "type": "boolean",
+          "default": false
         },
-        "resizable": {
-          "description": "Component property: resizable.",
+        "no-remove": {
+          "description": "Hide per-row remove buttons.",
           "type": "boolean",
           "default": false
         },
-        "side": {
-          "description": "Opts a pane into horizontal-sibling chrome: suppresses the default\nfour-sided border and moves the resize grabber to the inner edge\n(right edge for `leading`, left edge for `trailing`). Also flips the\nresize-drag direction so `trailing` panes grow when dragged leftward.\nUnset keeps the pane-intrinsic chrome (full border, right-edge\ngrabber when resizable).\n",
-          "type": "string",
-          "enum": [
-            "",
-            "leading",
-            "trailing"
-          ],
-          "default": ""
+        "value": {
+          "description": "Id of the row currently marked default (the form value). When\nboth `value` and `methods[].default` are set, `value` wins and\nthe primitive emits `change` to reconcile.\n",
+          "$ref": "#/$defs/DynamicString"
         }
       },
       "required": [
@@ -14045,62 +16496,224 @@
       ],
       "unevaluatedProperties": false,
       "x-adiaui": {
-        "anti_patterns": [],
-        "category": "layout",
+        "anti_patterns": [
+          {
+            "fix": "<payment-method-list-ui methods='[\n  {\"id\":\"pm_1\",\"default\":true},\n  {\"id\":\"pm_2\"}\n]'></payment-method-list-ui>\n",
+            "why": "Two rows marked default. The primitive clears all but the first\nand emits a corrective `change` event; this is wasted round-trips.\nSource of truth should mark exactly one row.\n",
+            "wrong": "<payment-method-list-ui methods='[\n  {\"id\":\"pm_1\",\"default\":true},\n  {\"id\":\"pm_2\",\"default\":true}\n]'></payment-method-list-ui>\n"
+          },
+          {
+            "fix": "<payment-method-list-ui methods=\"...\"></payment-method-list-ui>\n",
+            "why": "Reinvents 1-of-N default semantics. Drops radiogroup a11y.\nRe-derives the brand-icon dictionary per consumer.\n",
+            "wrong": "A <col-ui> of bespoke <card-ui> rows with manual radio markup\nand a per-row \"make default\" button.\n"
+          },
+          {
+            "fix": "<payment-method-list-ui methods='[{\"id\":\"pm_1\",\"brand\":\"discover\",\"type\":\"card\"}]'>\n</payment-method-list-ui>\n",
+            "why": "\"discover-it\" is a card product, not a brand from the enumerated\nset. The primitive renders the generic credit-card fallback.\n",
+            "wrong": "<payment-method-list-ui methods='[{\"id\":\"pm_1\",\"brand\":\"discover-it\",\"type\":\"card\"}]'>\n</payment-method-list-ui>\n"
+          }
+        ],
+        "category": "input",
         "composes": [
-          "icon-ui"
+          "card-ui",
+          "button-ui",
+          "icon-ui",
+          "tag-ui",
+          "text-ui",
+          "empty-state-ui"
         ],
         "events": {
-          "toggle": {
-            "description": "Fired when the pane's collapsed state flips (via button press, keyboard, or programmatic toggle()). Bubbles."
+          "add": {
+            "description": "Fired when the user activates the trailing add CTA. Consumer\nroutes to its add-method flow (drawer / modal / page). Bubbles.\n"
+          },
+          "change": {
+            "description": "Fired when the default method changes — via row activation or\nprogrammatic value set. Bubbles.\n",
+            "detail": {
+              "method": {
+                "description": "The full method record now marked default.",
+                "type": "object"
+              },
+              "previous": {
+                "description": "Id of the previous default (empty string when none).",
+                "type": "string"
+              },
+              "value": {
+                "description": "Id of the new default.",
+                "type": "string"
+              }
+            }
+          },
+          "remove": {
+            "description": "Fired when the user activates a row's remove affordance. Consumer\nremoves the method on its end and writes back via `.remove(id)`\nor by mutating `methods`. Bubbles.\n",
+            "detail": {
+              "id": {
+                "description": "Method id targeted for removal.",
+                "type": "string"
+              },
+              "method": {
+                "description": "The full method record.",
+                "type": "object"
+              }
+            }
+          },
+          "select": {
+            "description": "Fired when the user activates a row without changing the default\n(e.g. an \"Edit\" action). Bubbles.\n",
+            "detail": {
+              "id": {
+                "description": "Method id.",
+                "type": "string"
+              },
+              "method": {
+                "description": "The full method record.",
+                "type": "object"
+              }
+            }
           }
         },
         "examples": [
           {
-            "description": "Split pane with TextArea for editing markdown on the left and a preview card on the right.",
-            "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Row\",\n    \"children\": [\n      \"left\",\n      \"right\"\n    ]\n  },\n  {\n    \"id\": \"left\",\n    \"component\": \"Pane\",\n    \"resizable\": true,\n    \"width\": \"50%\",\n    \"children\": [\n      \"editor-card\"\n    ]\n  },\n  {\n    \"id\": \"editor-card\",\n    \"component\": \"Card\",\n    \"children\": [\n      \"ed-hdr\",\n      \"ed-sec\"\n    ]\n  },\n  {\n    \"id\": \"ed-hdr\",\n    \"component\": \"Header\",\n    \"children\": [\n      \"ed-title\"\n    ]\n  },\n  {\n    \"id\": \"ed-title\",\n    \"component\": \"Text\",\n    \"slot\": \"heading\",\n    \"textContent\": \"Editor\"\n  },\n  {\n    \"id\": \"ed-sec\",\n    \"component\": \"Section\",\n    \"children\": [\n      \"textarea\"\n    ]\n  },\n  {\n    \"id\": \"textarea\",\n    \"component\": \"TextArea\",\n    \"placeholder\": \"Write your markdown here...\",\n    \"rows\": 20\n  },\n  {\n    \"id\": \"right\",\n    \"component\": \"Pane\",\n    \"resizable\": true,\n    \"width\": \"50%\",\n    \"children\": [\n      \"preview-card\"\n    ]\n  },\n  {\n    \"id\": \"preview-card\",\n    \"component\": \"Card\",\n    \"children\": [\n      \"pv-hdr\",\n      \"pv-sec\"\n    ]\n  },\n  {\n    \"id\": \"pv-hdr\",\n    \"component\": \"Header\",\n    \"children\": [\n      \"pv-title\"\n    ]\n  },\n  {\n    \"id\": \"pv-title\",\n    \"component\": \"Text\",\n    \"slot\": \"heading\",\n    \"textContent\": \"Preview\"\n  },\n  {\n    \"id\": \"pv-sec\",\n    \"component\": \"Section\",\n    \"children\": [\n      \"preview-text\"\n    ]\n  },\n  {\n    \"id\": \"preview-text\",\n    \"component\": \"Text\",\n    \"variant\": \"body\",\n    \"textContent\": \"Rendered markdown will appear here...\"\n  }\n]",
-            "name": "markdown-editor"
+            "description": "Saved payment methods in a billing settings panel.",
+            "a2ui": "[\n  {\n    \"id\": \"pml-settings\",\n    \"component\": \"PaymentMethodList\",\n    \"name\": \"default-method\",\n    \"value\": \"pm_1\",\n    \"methods\": [\n      {\"id\":\"pm_1\",\"brand\":\"visa\",\"last4\":\"4242\",\"expiry\":\"2027-05-01\",\"holder\":\"Ada Lovelace\",\"type\":\"card\",\"default\":true},\n      {\"id\":\"pm_2\",\"brand\":\"mastercard\",\"last4\":\"0009\",\"expiry\":\"2026-06-01\",\"holder\":\"Ada Lovelace\",\"type\":\"card\"},\n      {\"id\":\"pm_3\",\"brand\":\"ach\",\"last4\":\"6789\",\"holder\":\"Chase ••6789\",\"type\":\"bank\"}\n    ]\n  }\n]\n",
+            "name": "settings-list"
           },
           {
-            "description": "Row with two resizable Pane components for left/right panel layout.",
-            "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Row\",\n    \"children\": [\n      \"left\",\n      \"right\"\n    ]\n  },\n  {\n    \"id\": \"left\",\n    \"component\": \"Pane\",\n    \"resizable\": true,\n    \"width\": \"50%\",\n    \"children\": [\n      \"ltxt\"\n    ]\n  },\n  {\n    \"id\": \"ltxt\",\n    \"component\": \"Text\",\n    \"variant\": \"body\",\n    \"textContent\": \"Left panel content\"\n  },\n  {\n    \"id\": \"right\",\n    \"component\": \"Pane\",\n    \"resizable\": true,\n    \"width\": \"50%\",\n    \"children\": [\n      \"rtxt\"\n    ]\n  },\n  {\n    \"id\": \"rtxt\",\n    \"component\": \"Text\",\n    \"variant\": \"body\",\n    \"textContent\": \"Right panel content\"\n  }\n]",
-            "name": "split-pane"
+            "description": "Checkout-drawer picker — no add CTA; read-only-ish.",
+            "a2ui": "[\n  {\n    \"id\": \"pml-checkout\",\n    \"component\": \"PaymentMethodList\",\n    \"name\": \"checkout-method\",\n    \"noAdd\": true,\n    \"methods\": [\n      {\"id\":\"pm_1\",\"brand\":\"visa\",\"last4\":\"4242\",\"expiry\":\"2027-05-01\",\"type\":\"card\",\"default\":true},\n      {\"id\":\"pm_2\",\"brand\":\"mastercard\",\"last4\":\"0009\",\"expiry\":\"2026-06-01\",\"type\":\"card\"}\n    ]\n  }\n]\n",
+            "name": "checkout-drawer"
           }
         ],
         "keywords": [
-          "pane"
-        ],
-        "name": "UIPane",
+          "payment-method",
+          "payment-methods",
+          "saved-cards",
+          "billing",
+          "cards",
+          "payment-card",
+          "credit-card",
+          "default-card",
+          "wallet",
+          "bank-account",
+          "ach",
+          "method-list"
+        ],
+        "name": "PaymentMethodList",
         "related": [
-          "text-area"
+          "PlanPicker",
+          "Card",
+          "Button",
+          "Tag",
+          "Icon",
+          "EmptyState"
         ],
         "slots": {
-          "header": {
-            "description": "Auto-created header element with label text and toggle arrow"
+          "add": {
+            "description": "Custom add-CTA replacement. When absent the primitive stamps a\ndefault `<button-ui variant=\"outline\" icon=\"plus\">`. Hidden\nentirely when `[no-add]` is set.\n"
+          },
+          "empty": {
+            "description": "Custom empty-state shown when `methods` is empty. Falls back to a\ndefault <empty-state-ui icon=\"credit-card\"> when omitted.\n"
           }
         },
         "states": [
           {
-            "description": "Default, ready for interaction.",
+            "description": "Default — rows rendered, ready for interaction.",
             "name": "idle"
+          },
+          {
+            "description": "No methods to render.",
+            "attribute": "empty",
+            "name": "empty"
+          },
+          {
+            "description": "All rows non-interactive.",
+            "attribute": "disabled",
+            "name": "disabled"
           }
         ],
-        "status": "stable",
+        "status": "experimental",
         "synonyms": {
-          "tags": [
-            "split-pane",
-            "side-panel",
-            "resizable-panel",
-            "detail-pane",
-            "list-pane",
-            "context-pane",
-            "Panel",
-            "Pane"
+          "card": [
+            "credit-card",
+            "debit-card",
+            "payment-method"
+          ],
+          "payment": [
+            "billing",
+            "charge"
+          ],
+          "saved": [
+            "stored"
           ]
         },
-        "tag": "pane-ui",
-        "tokens": {},
-        "traits": [],
+        "tag": "payment-method-list-ui",
+        "tokens": {
+          "--payment-method-list-add-justify": {
+            "description": "Justification of the trailing add CTA row.",
+            "default": "flex-start"
+          },
+          "--payment-method-list-bg": {
+            "description": "Host background. Defaults to transparent.",
+            "default": "transparent"
+          },
+          "--payment-method-list-brand-frame": {
+            "description": "Brand-mark frame background.",
+            "default": "var(--a-bg-strong)"
+          },
+          "--payment-method-list-brand-radius": {
+            "description": "Brand-mark frame radius.",
+            "default": "var(--a-radius-md)"
+          },
+          "--payment-method-list-brand-size": {
+            "description": "Brand-mark frame size.",
+            "default": "2.5rem"
+          },
+          "--payment-method-list-disabled-opacity": {
+            "description": "Opacity applied when the host is disabled.",
+            "default": 0.5
+          },
+          "--payment-method-list-gap": {
+            "description": "Gap between rows.",
+            "default": "var(--a-space-2)"
+          },
+          "--payment-method-list-row-bg": {
+            "description": "Default row background.",
+            "default": "var(--a-bg)"
+          },
+          "--payment-method-list-row-bg-default": {
+            "description": "Background tint applied to the default row.",
+            "default": "var(--a-accent-muted)"
+          },
+          "--payment-method-list-row-bg-hover": {
+            "description": "Row hover background.",
+            "default": "var(--a-bg-muted)"
+          },
+          "--payment-method-list-row-border": {
+            "description": "Row border.",
+            "default": "1px solid var(--a-border-subtle)"
+          },
+          "--payment-method-list-row-border-default": {
+            "description": "Border on the default row.",
+            "default": "1px solid var(--a-accent)"
+          },
+          "--payment-method-list-row-gap": {
+            "description": "Gap between brand mark, meta, and actions cells.",
+            "default": "var(--a-space-3)"
+          },
+          "--payment-method-list-row-px": {
+            "description": "Row horizontal padding.",
+            "default": "var(--a-space-4)"
+          },
+          "--payment-method-list-row-py": {
+            "description": "Row vertical padding.",
+            "default": "var(--a-space-3)"
+          },
+          "--payment-method-list-row-radius": {
+            "description": "Row corner radius.",
+            "default": "var(--a-radius-lg)"
+          }
+        },
+        "traits": [
+          "focusable"
+        ],
         "version": 1
       }
     },
@@ -14184,23 +16797,370 @@
             "description": "Default slot — primary child content."
           }
         },
-        "states": [
-          {
-            "description": "Default, ready for interaction.",
-            "name": "idle"
-          }
+        "states": [
+          {
+            "description": "Default, ready for interaction.",
+            "name": "idle"
+          }
+        ],
+        "status": "stable",
+        "synonyms": {
+          "tags": [
+            "job-status",
+            "deploy-status",
+            "pipeline-indicator"
+          ]
+        },
+        "tag": "pipeline-status-ui",
+        "tokens": {},
+        "traits": [],
+        "version": 1
+      }
+    },
+    "PlanPicker": {
+      "title": "PlanPicker",
+      "description": "A form-participating chooser of one of N billing plans. The canonical\nplan-card grid used by both in-app upgrade modals and marketing\npricing pages (SPEC-012 composes this primitive as its core), so\nbenefit copy, pricing strings, recommendation highlighting, and the\nbilling-cycle toggle never drift between surfaces.\n\nEach plan record carries a stable id, name, optional tagline + icon,\na per-cycle price object, a feature list, and optional flags\n(recommended, rank, disabled). One plan may carry recommended:true\n(accent border + tinted bg + shadow); a host-level `current` id\nmarks the user's current plan (muted bg, \"Current plan\" tag, no\nChoose CTA, contextual \"Upgrade\"/\"Downgrade\" labels on siblings).\n\nLayout is grid by default (marketing surfaces) and `layout=\"list\"`\nfor in-app settings panels. The optional `cycle-toggle` boolean\nrenders an internal <segmented-ui> that swaps prices between\nmonthly and annual cycles in place across every card.\n\nSpec: docs/specs/implementation-ready/SPEC-011-plan-picker-in-app-upgrade.md.\n",
+      "type": "object",
+      "allOf": [
+        {
+          "$ref": "#/$defs/ComponentCommon"
+        },
+        {
+          "$ref": "#/$defs/CatalogComponentCommon"
+        }
+      ],
+      "properties": {
+        "component": {
+          "const": "PlanPicker"
+        },
+        "currency": {
+          "description": "Default ISO 4217 currency code for price rendering. Overridable\nper-price via plans[].prices[cycle].currency.\n",
+          "type": "string",
+          "default": "USD"
+        },
+        "current": {
+          "description": "Id of the user's CURRENT plan. When set, that card renders with\na muted background, a \"Current plan\" <tag-ui>, and either no CTA\nor a \"Manage\" CTA. Other plans receive contextual upgrade /\ndowngrade CTA labels derived from rank. Unknown ids fail\nsilently (no anchor row).\n",
+          "$ref": "#/$defs/DynamicString"
+        },
+        "cycle": {
+          "description": "Active billing cycle. Drives which `plans[].prices[cycle]` value\nrenders across every card simultaneously. Toggle via the in-host\n`cycle-toggle` (when set) or programmatically via setCycle().\n",
+          "$ref": "#/$defs/DynamicString"
+        },
+        "cycle-toggle": {
+          "description": "When set, the primitive renders an internal <segmented-ui> with\nMonthly / Annual options above the plan grid. When unset, the\nconsumer drives [cycle] externally (e.g. from a parent toolbar).\n",
+          "type": "boolean",
+          "default": false
+        },
+        "data-stream-src": {
+          "description": "Optional endpoint returning the `plans` array (universal\ndata-stream-* trait). On successful load, `plans` is replaced\nand a `load` event fires; on failure an `error` event fires.\n",
+          "type": "string",
+          "default": ""
+        },
+        "disabled": {
+          "description": "Block all interaction across the picker.",
+          "type": "boolean",
+          "default": false
+        },
+        "layout": {
+          "description": "Card layout. `grid` (auto-fit columns, minimum 16rem) for\nmarketing surfaces. `list` (single column rows) for in-app\nsettings panels.\n",
+          "type": "string",
+          "enum": [
+            "grid",
+            "list"
+          ],
+          "default": "grid"
+        },
+        "locale": {
+          "description": "Locale for Intl.NumberFormat (price) and cycle labels. Defaults\nto document.documentElement.lang (or \"en-US\" when absent).\n",
+          "type": "string",
+          "default": ""
+        },
+        "name": {
+          "description": "Form field name for the selected plan id. Mirrors UIFormElement\nconventions; serialized via ElementInternals.\n",
+          "type": "string",
+          "default": ""
+        },
+        "plans": {
+          "description": "Array of plan records. Source of truth for the rendered cards.\nShape per record: {id, name, tagline?, prices: {monthly: {amount,\ncurrency?, unit?, note?}, annual?: {...}}, features?: string[],\ncta?: string, recommended?: boolean, rank?: number, icon?: string,\ndisabled?: boolean}. Empty array renders the empty-state.\n",
+          "$ref": "#/$defs/DynamicStringList"
+        },
+        "value": {
+          "description": "Currently selected plan id (form value). Read-write — both the\nform submission key and the [checked] gate on the matching\n<option-card-ui>.\n",
+          "$ref": "#/$defs/DynamicString"
+        }
+      },
+      "required": [
+        "component",
+        "plans"
+      ],
+      "unevaluatedProperties": false,
+      "x-adiaui": {
+        "anti_patterns": [
+          {
+            "fix": "<plan-picker-ui plans='[\n  {\"id\":\"p1\",\"name\":\"Free\",\"prices\":{\"monthly\":{\"amount\":0}}},\n  {\"id\":\"p2\",\"name\":\"Pro\",\"prices\":{\"monthly\":{\"amount\":20}}}\n]'></plan-picker-ui>\n",
+            "why": "`price` is a top-level shortcut not in the schema. Prices are\nkeyed by cycle (monthly / annual). Without a cycle key, the\ncycle toggle has nothing to switch and annual pricing is\ninvisible to consumers.\n",
+            "wrong": "<plan-picker-ui plans='[\n  {\"id\":\"p1\",\"name\":\"Free\",\"price\":0},\n  {\"id\":\"p2\",\"name\":\"Pro\",\"price\":20}\n]'></plan-picker-ui>\n"
+          },
+          {
+            "fix": "<plan-picker-ui plans='[\n  {\"id\":\"t\",\"name\":\"Team\",\"prices\":{\"monthly\":{\"amount\":10}}},\n  {\"id\":\"p\",\"name\":\"Pro\",\"recommended\":true,\"prices\":{\"monthly\":{\"amount\":20}}}\n]'></plan-picker-ui>\n",
+            "why": "Two recommended plans cancel each other visually — there is no\n\"the\" recommendation. Pick one.\n",
+            "wrong": "<plan-picker-ui plans='[\n  {\"id\":\"t\",\"name\":\"Team\",\"recommended\":true,\"prices\":{\"monthly\":{\"amount\":10}}},\n  {\"id\":\"p\",\"name\":\"Pro\",\"recommended\":true,\"prices\":{\"monthly\":{\"amount\":20}}}\n]'></plan-picker-ui>\n"
+          },
+          {
+            "fix": "<plan-picker-ui plans=\"...\" cycle-toggle></plan-picker-ui>\n",
+            "why": "Reinvents the radiogroup keyboard model and the cycle-toggle\nsemantics; pricing strings drift between this surface and the\nmarketing pricing page that uses the canonical primitive.\n",
+            "wrong": "A <col-ui> of bespoke <card-ui> plan cards with manual radio\nmarkup and a per-plan cycle pill.\n"
+          }
+        ],
+        "category": "input",
+        "composes": [
+          "option-card-ui",
+          "segmented-ui",
+          "segment-ui",
+          "button-ui",
+          "icon-ui",
+          "text-ui",
+          "tag-ui",
+          "empty-state-ui"
+        ],
+        "events": {
+          "change": {
+            "description": "Fired when the selected plan id changes — either via user click\nor programmatic value set. Bubbles.\n",
+            "detail": {
+              "cycle": {
+                "description": "Active billing cycle.",
+                "type": "string"
+              },
+              "previous": {
+                "description": "Previous plan id (empty string when none).",
+                "type": "string"
+              },
+              "value": {
+                "description": "New plan id.",
+                "type": "string"
+              }
+            }
+          },
+          "cycle-change": {
+            "description": "Fired when the active billing cycle changes (cycle-toggle\nclick or programmatic setCycle). Bubbles.\n",
+            "detail": {
+              "cycle": {
+                "description": "New cycle.",
+                "type": "string",
+                "enum": [
+                  "monthly",
+                  "annual"
+                ]
+              },
+              "previous": {
+                "description": "Previous cycle.",
+                "type": "string"
+              }
+            }
+          },
+          "error": {
+            "description": "Fired when a `data-stream-src` fetch fails OR when a user tries\nto select a `disabled: true` plan. Bubbles.\n",
+            "detail": {
+              "reason": {
+                "description": "One of `fetch-failed`, `plan-disabled`.",
+                "type": "string"
+              }
+            }
+          },
+          "load": {
+            "description": "Fired when `data-stream-src` finishes a successful fetch and\n`plans` is populated. Bubbles.\n",
+            "detail": {
+              "count": {
+                "description": "Number of plans loaded.",
+                "type": "integer"
+              }
+            }
+          },
+          "select": {
+            "description": "Fired when the user activates a plan's CTA button — the\ncommitting action that consumers wire to a checkout / upgrade\nflow. Distinct from `change` (selection without commit). Bubbles.\n",
+            "detail": {
+              "cycle": {
+                "description": "Active billing cycle at commit.",
+                "type": "string"
+              },
+              "value": {
+                "description": "Plan id being committed.",
+                "type": "string"
+              }
+            }
+          }
+        },
+        "examples": [
+          {
+            "description": "In-app upgrade modal with three plans + annual default + cycle toggle.",
+            "a2ui": "[\n  {\n    \"id\": \"pp-upgrade\",\n    \"component\": \"PlanPicker\",\n    \"name\": \"plan\",\n    \"current\": \"plan_team\",\n    \"cycle\": \"annual\",\n    \"cycleToggle\": true,\n    \"plans\": [\n      {\"id\":\"plan_free\",\"name\":\"Free\",\"prices\":{\"monthly\":{\"amount\":0}},\"features\":[\"3 projects\",\"Community support\"],\"rank\":1},\n      {\"id\":\"plan_team\",\"name\":\"Team\",\"prices\":{\"monthly\":{\"amount\":10,\"unit\":\"seat\"},\"annual\":{\"amount\":8,\"unit\":\"seat\",\"note\":\"billed annually\"}},\"features\":[\"Unlimited projects\",\"Email support\"],\"rank\":2},\n      {\"id\":\"plan_pro\",\"name\":\"Pro\",\"prices\":{\"monthly\":{\"amount\":25,\"unit\":\"seat\"},\"annual\":{\"amount\":20,\"unit\":\"seat\",\"note\":\"billed annually\"}},\"features\":[\"Everything in Team\",\"Priority support\"],\"recommended\":true,\"rank\":3}\n    ]\n  }\n]\n",
+            "name": "in-app-upgrade"
+          },
+          {
+            "description": "Settings-page plan picker — single-column list inside a card.",
+            "a2ui": "[\n  {\n    \"id\": \"pp-settings\",\n    \"component\": \"PlanPicker\",\n    \"name\": \"plan\",\n    \"current\": \"plan_team\",\n    \"layout\": \"list\",\n    \"plans\": [\n      {\"id\":\"plan_team\",\"name\":\"Team\",\"prices\":{\"monthly\":{\"amount\":10,\"unit\":\"seat\"}},\"features\":[\"Unlimited projects\"],\"rank\":2},\n      {\"id\":\"plan_pro\",\"name\":\"Pro\",\"prices\":{\"monthly\":{\"amount\":25,\"unit\":\"seat\"}},\"features\":[\"Everything in Team\",\"Priority support\"],\"recommended\":true,\"rank\":3}\n    ]\n  }\n]\n",
+            "name": "settings-list"
+          }
+        ],
+        "keywords": [
+          "plan-picker",
+          "plans",
+          "pricing",
+          "upgrade",
+          "billing",
+          "tier",
+          "tiers",
+          "subscription",
+          "subscribe",
+          "paywall",
+          "choose-plan",
+          "select-plan",
+          "plan-selection"
+        ],
+        "name": "PlanPicker",
+        "related": [
+          "OptionCard",
+          "Segmented",
+          "Segment",
+          "Tag",
+          "Button",
+          "Card",
+          "EmptyState",
+          "Skeleton"
+        ],
+        "slots": {
+          "empty": {
+            "description": "Custom empty-state shown when `plans` is empty. Falls back to a\ndefault <empty-state-ui> when not provided.\n"
+          },
+          "footer": {
+            "description": "Optional content below the plan grid (compare-plans link, FAQ,\nfine print).\n"
+          },
+          "header": {
+            "description": "Optional content above the plan grid (e.g. a <header> with a\ntitle and a custom cycle toggle). When absent and\n`cycle-toggle` is set, the primitive stamps its own toggle.\n"
+          }
+        },
+        "states": [
+          {
+            "description": "Default — plans rendered, ready for interaction.",
+            "name": "idle"
+          },
+          {
+            "description": "A `data-stream-src` fetch is in flight.",
+            "attribute": "loading",
+            "name": "loading"
+          },
+          {
+            "description": "No plans to render.",
+            "attribute": "empty",
+            "name": "empty"
+          },
+          {
+            "description": "Last `data-stream-src` fetch failed.",
+            "attribute": "error",
+            "name": "error"
+          },
+          {
+            "description": "All cards non-interactive.",
+            "attribute": "disabled",
+            "name": "disabled"
+          }
+        ],
+        "status": "experimental",
+        "synonyms": {
+          "plan": [
+            "tier",
+            "subscription",
+            "package"
+          ],
+          "pricing": [
+            "plan",
+            "price",
+            "tier"
+          ],
+          "upgrade": [
+            "plan-change",
+            "subscribe",
+            "choose-plan"
+          ]
+        },
+        "tag": "plan-picker-ui",
+        "tokens": {
+          "--plan-picker-bg": {
+            "description": "Host background. Defaults to transparent.",
+            "default": "transparent"
+          },
+          "--plan-picker-card-bg": {
+            "description": "Card background (cascades to option-card --option-card-bg).",
+            "default": "var(--a-bg)"
+          },
+          "--plan-picker-card-bg-current": {
+            "description": "Current-plan card background.",
+            "default": "var(--a-bg-muted)"
+          },
+          "--plan-picker-card-bg-recommended": {
+            "description": "Recommended-card background.",
+            "default": "var(--a-accent-muted)"
+          },
+          "--plan-picker-card-border": {
+            "description": "Default card border.",
+            "default": "1px solid var(--a-border)"
+          },
+          "--plan-picker-card-border-recommended": {
+            "description": "Recommended-card accent border.",
+            "default": "2px solid var(--a-accent)"
+          },
+          "--plan-picker-card-px": {
+            "description": "Card horizontal padding.",
+            "default": "var(--a-space-5)"
+          },
+          "--plan-picker-card-py": {
+            "description": "Card vertical padding.",
+            "default": "var(--a-space-5)"
+          },
+          "--plan-picker-card-radius": {
+            "description": "Card corner radius.",
+            "default": "var(--a-radius-lg)"
+          },
+          "--plan-picker-card-shadow-recommended": {
+            "description": "Shadow elevation on the recommended card.",
+            "default": "var(--a-shadow-md)"
+          },
+          "--plan-picker-cycle-fg": {
+            "description": "Per-unit / cycle suffix color (e.g. \"/month\").",
+            "default": "var(--a-fg-muted)"
+          },
+          "--plan-picker-feature-icon-fg": {
+            "description": "Feature-row check icon color.",
+            "default": "var(--a-accent)"
+          },
+          "--plan-picker-features-gap": {
+            "description": "Gap between feature list rows.",
+            "default": "var(--a-space-2)"
+          },
+          "--plan-picker-grid-gap": {
+            "description": "Gap between plan cards in grid layout.",
+            "default": "var(--a-space-4)"
+          },
+          "--plan-picker-grid-min": {
+            "description": "Minimum column width in auto-fit grid.",
+            "default": "16rem"
+          },
+          "--plan-picker-price-fg": {
+            "description": "Price color.",
+            "default": "var(--a-fg-strong, var(--a-fg))"
+          },
+          "--plan-picker-price-size": {
+            "description": "Price font size.",
+            "default": "var(--a-text-3xl, 1.875rem)"
+          },
+          "--plan-picker-toggle-justify": {
+            "description": "Justification of the internal cycle toggle row. `center` for\nmarketing layouts; `start` for in-app settings panels.\n",
+            "default": "center"
+          }
+        },
+        "traits": [
+          "focusable"
         ],
-        "status": "stable",
-        "synonyms": {
-          "tags": [
-            "job-status",
-            "deploy-status",
-            "pipeline-indicator"
-          ]
-        },
-        "tag": "pipeline-status-ui",
-        "tokens": {},
-        "traits": [],
         "version": 1
       }
     },
@@ -14295,7 +17255,14 @@
           "button",
           "divider"
         ],
-        "slots": {},
+        "slots": {
+          "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."
+          },
+          "trigger": {
+            "description": "Focusable element that opens the popover when activated. Typically <button-ui>, but any focusable element works (button, a link with href). MUST be focusable for keyboard accessibility — bare <span> or <div> children will not respond to keyboard activation. Positioned at the anchor point per [placement]."
+          }
+        },
         "states": [
           {
             "description": "Default, ready for interaction.",
@@ -15891,7 +18858,7 @@
     },
     "Select": {
       "title": "Select",
-      "description": "Single-select dropdown primitive — the canonical AdiaUI select\ncontrol. Form-bearing via UIFormElement: [name], [value],\n[required], [disabled], fires `change`. Options via native\n<option> / <optgroup> children, programmatic `.options` array, or\nJSON [data-options] (hydrated by <editor-shell>'s wireSelects).\nUse for single-select with > 4 options; for ≤ 4 options use\n<segmented-ui> or <radio-ui>. Multi-select via [multiple searchable].\n",
+      "description": "Single- and multi-select dropdown primitive — the canonical AdiaUI\nselect control. Form-bearing via UIFormElement: [name], [value],\n[required], [disabled], fires `change`. Options via native\n<option> / <optgroup> children, programmatic `.options` array, or\nJSON [data-options] (hydrated by <editor-shell>'s wireSelects).\nUse for single-select with > 4 options; for ≤ 4 options use\n<segmented-ui> or <radio-ui>. Multi-select via [multiple]: trigger\nrenders <tag-ui> chips per selection, popover shows checkbox-style\noption list, Backspace removes the last chip, [select-all] adds\nbulk controls, [max-chips] caps the visible chip count with a\n\"+N more\" pill. Form value stays a comma-separated string under\n[name] for native <form> compatibility (parse with .split(',')).\n",
       "type": "object",
       "allOf": [
         {
@@ -15912,6 +18879,11 @@
           "type": "string",
           "default": ""
         },
+        "clearable": {
+          "description": "Multi-select only. Adds a clear-all `x` affordance to the trigger\nwhen at least one chip is present. Click empties value and fires\n`change`.\n",
+          "type": "boolean",
+          "default": false
+        },
         "component": {
           "const": "Select"
         },
@@ -15950,18 +18922,33 @@
           "type": "string",
           "default": ""
         },
+        "max": {
+          "description": "Multi-select only. Maximum allowed selections. Toggling past the\ncap is suppressed; the `invalid` event fires with reason=\"max\".\n`0` (default) = unlimited.\n",
+          "type": "number",
+          "default": 0
+        },
+        "max-chips": {
+          "description": "Multi-select only. Caps the number of chips visible in the\ntrigger. When `value.length > max-chips`, the first N chips\nrender plus a \"+M more\" pill that opens the popover on click.\n`0` (default) = unlimited.\n",
+          "type": "number",
+          "default": 0
+        },
         "maxlength": {
           "description": "Maximum character length for validation",
           "type": "number",
           "default": null
         },
+        "min": {
+          "description": "Multi-select only. Minimum required selections. Below this floor\nthe host's form validity goes invalid (valueMissing) and the\n`invalid` event fires.\n",
+          "type": "number",
+          "default": 0
+        },
         "minlength": {
           "description": "Minimum character length for validation",
           "type": "number",
           "default": null
         },
         "multiple": {
-          "description": "Enables multi-select (comma-separated values)",
+          "description": "Enables multi-select. Trigger renders <tag-ui> chips per selection\n(not comma-separated text); popover renders checkbox-style option\nrows where clicks toggle without closing; Backspace from the\ntrigger removes the last chip. Form value remains comma-separated\nunder [name] for native <form> compatibility.\n",
           "type": "boolean",
           "default": false
         },
@@ -16000,6 +18987,11 @@
           "type": "boolean",
           "default": false
         },
+        "select-all": {
+          "description": "Multi-select only. Renders a \"Select all\" / \"Clear\" control row\nabove the option list. Click selects every non-disabled option;\nwhen already all selected, click clears.\n",
+          "type": "boolean",
+          "default": false
+        },
         "size": {
           "description": "Sizing scale via universal `[size]` attribute system (packages/web-components/styles/tokens.css). Matches Input's sizing tokens so a Select rendered alongside an Input feels coherent in a form row.",
           "type": "string",
@@ -16035,11 +19027,15 @@
         "anti_patterns": [],
         "category": "input",
         "composes": [
-          "icon-ui"
+          "icon-ui",
+          "tag-ui"
         ],
         "events": {
           "change": {
             "description": "Fired when selected value changes"
+          },
+          "invalid": {
+            "description": "Multi-select only. Fired when a toggle is suppressed by [min] or\n[max] constraints. detail = { value, reason: 'min' | 'max' }.\n"
           }
         },
         "examples": [
@@ -16048,6 +19044,11 @@
             "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Card\",\n    \"children\": [\n      \"hdr\",\n      \"photo-sec\",\n      \"settings-sec\",\n      \"ftr\"\n    ]\n  },\n  {\n    \"id\": \"hdr\",\n    \"component\": \"Header\",\n    \"children\": [\n      \"hdr-title\",\n      \"hdr-desc\"\n    ]\n  },\n  {\n    \"id\": \"hdr-title\",\n    \"component\": \"Text\",\n    \"slot\": \"heading\",\n    \"textContent\": \"Bleed Design Settings\",\n    \"variant\": \"section\"\n  },\n  {\n    \"id\": \"hdr-desc\",\n    \"component\": \"Text\",\n    \"slot\": \"description\",\n    \"textContent\": \"Configure bleed margins, upload artwork, and preview before approval.\",\n    \"variant\": \"body\"\n  },\n  {\n    \"id\": \"photo-sec\",\n    \"component\": \"Section\",\n    \"children\": [\n      \"photo-col\"\n    ]\n  },\n  {\n    \"id\": \"photo-col\",\n    \"component\": \"Column\",\n    \"children\": [\n      \"photo-label\",\n      \"photo-img\",\n      \"photo-btn\"\n    ],\n    \"gap\": \"3\"\n  },\n  {\n    \"id\": \"photo-label\",\n    \"component\": \"Text\",\n    \"textContent\": \"Artwork Upload\",\n    \"variant\": \"label\"\n  },\n  {\n    \"id\": \"photo-img\",\n    \"component\": \"Image\",\n    \"src\": \"https://picsum.photos/400/200\",\n    \"aspect\": \"2/1\"\n  },\n  {\n    \"id\": \"photo-btn\",\n    \"component\": \"Button\",\n    \"text\": \"Upload Photo\",\n    \"variant\": \"secondary\"\n  },\n  {\n    \"id\": \"settings-sec\",\n    \"component\": \"Section\",\n    \"children\": [\n      \"settings-col\"\n    ]\n  },\n  {\n    \"id\": \"settings-col\",\n    \"component\": \"Column\",\n    \"children\": [\n      \"bleed-mode\",\n      \"bleed-margin\",\n      \"bleed-unit\",\n      \"approved\"\n    ],\n    \"gap\": \"4\"\n  },\n  {\n    \"id\": \"bleed-mode\",\n    \"component\": \"Select\",\n    \"label\": \"Bleed Mode\",\n    \"name\": \"bleed-mode\",\n    \"placeholder\": \"Select mode...\"\n  },\n  {\n    \"id\": \"bleed-margin\",\n    \"component\": \"Input\",\n    \"label\": \"Bleed Margin\",\n    \"name\": \"bleed-margin\",\n    \"type\": \"number\",\n    \"placeholder\": \"e.g. 3\"\n  },\n  {\n    \"id\": \"bleed-unit\",\n    \"component\": \"Select\",\n    \"label\": \"Unit\",\n    \"name\": \"bleed-unit\",\n    \"placeholder\": \"mm\"\n  },\n  {\n    \"id\": \"approved\",\n    \"component\": \"CheckBox\",\n    \"label\": \"Approved for production\",\n    \"name\": \"approved\"\n  },\n  {\n    \"id\": \"ftr\",\n    \"component\": \"Footer\",\n    \"children\": [\n      \"preview-btn\",\n      \"apply-btn\"\n    ]\n  },\n  {\n    \"id\": \"preview-btn\",\n    \"component\": \"Button\",\n    \"text\": \"Preview\",\n    \"variant\": \"secondary\"\n  },\n  {\n    \"id\": \"apply-btn\",\n    \"component\": \"Button\",\n    \"text\": \"Apply\",\n    \"variant\": \"primary\"\n  }\n]",
             "name": "bleed-design-settings"
           },
+          {
+            "description": "Multi-select with chip trigger + checkbox option list (SPEC-040).",
+            "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Card\",\n    \"children\": [\"sec\"]\n  },\n  {\n    \"id\": \"sec\",\n    \"component\": \"Section\",\n    \"children\": [\"col\"]\n  },\n  {\n    \"id\": \"col\",\n    \"component\": \"Column\",\n    \"children\": [\"tags\"],\n    \"gap\": \"3\"\n  },\n  {\n    \"id\": \"tags\",\n    \"component\": \"Select\",\n    \"multiple\": true,\n    \"selectAll\": true,\n    \"label\": \"Tags\",\n    \"name\": \"tags\",\n    \"placeholder\": \"Pick tags...\",\n    \"value\": \"urgent,backend\"\n  }\n]",
+            "name": "multi-select-tags"
+          },
           {
             "description": "Simple account creation form with text fields, select, and action buttons.",
             "a2ui": "[\n  {\n    \"id\": \"root\",\n    \"component\": \"Card\",\n    \"children\": [\n      \"hdr\",\n      \"sec\",\n      \"ftr\"\n    ]\n  },\n  {\n    \"id\": \"hdr\",\n    \"component\": \"Header\",\n    \"children\": [\n      \"title\",\n      \"desc\"\n    ]\n  },\n  {\n    \"id\": \"title\",\n    \"component\": \"Text\",\n    \"slot\": \"heading\",\n    \"textContent\": \"Create Account\",\n    \"variant\": \"section\"\n  },\n  {\n    \"id\": \"desc\",\n    \"component\": \"Text\",\n    \"slot\": \"description\",\n    \"variant\": \"caption\",\n    \"textContent\": \"Fill in your details\"\n  },\n  {\n    \"id\": \"sec\",\n    \"component\": \"Section\",\n    \"children\": [\n      \"form\"\n    ]\n  },\n  {\n    \"id\": \"form\",\n    \"component\": \"Column\",\n    \"children\": [\n      \"name\",\n      \"email\",\n      \"role\"\n    ],\n    \"gap\": \"4\"\n  },\n  {\n    \"id\": \"name\",\n    \"component\": \"Input\",\n    \"label\": \"Full Name\",\n    \"placeholder\": \"Kim Granlund\",\n    \"name\": \"name\",\n    \"required\": true\n  },\n  {\n    \"id\": \"email\",\n    \"component\": \"Input\",\n    \"label\": \"Email\",\n    \"type\": \"email\",\n    \"placeholder\": \"kim@adia.health\",\n    \"name\": \"email\",\n    \"required\": true\n  },\n  {\n    \"id\": \"role\",\n    \"component\": \"Select\",\n    \"label\": \"Role\",\n    \"placeholder\": \"Choose role...\",\n    \"name\": \"role\"\n  },\n  {\n    \"id\": \"ftr\",\n    \"component\": \"Footer\",\n    \"children\": [\n      \"cancel\",\n      \"submit\"\n    ]\n  },\n  {\n    \"id\": \"cancel\",\n    \"component\": \"Button\",\n    \"text\": \"Cancel\",\n    \"variant\": \"ghost\"\n  },\n  {\n    \"id\": \"submit\",\n    \"component\": \"Button\",\n    \"text\": \"Create\",\n    \"variant\": \"primary\"\n  }\n]",
@@ -16058,7 +19059,13 @@
           "select",
           "dropdown",
           "combobox",
-          "autocomplete"
+          "autocomplete",
+          "multi-select",
+          "multiple",
+          "chips",
+          "tokens",
+          "tags",
+          "picker"
         ],
         "name": "UISelect",
         "related": [
@@ -16111,6 +19118,20 @@
             "menu",
             "select",
             "form"
+          ],
+          "multi-select": [
+            "multiselect",
+            "multi-pick",
+            "chips",
+            "tokens",
+            "tags",
+            "multiple"
+          ],
+          "multiple": [
+            "multi-select",
+            "multiselect",
+            "chips",
+            "select-many"
           ]
         },
         "tag": "select-ui",
@@ -16684,12 +19705,13 @@
           "default": "current"
         },
         "variant": {
-          "description": "Visual flavor — arc (rotating quarter-circle), ring (full ring with one colored segment), dots (three bouncing dots).",
+          "description": "Visual flavor — `arc` (rotating quarter-circle, the default glyph spinner), `ring` (full ring with one colored segment rotating around it), `dots` (three bouncing dots — animated in a left-to-right wave), `knight` (horizontal \"knight-rider\" bar — a sliding thumb that bounces back-and-forth across a track; widest variant, reads as a determinate-looking bar but is indeterminate by intent).",
           "type": "string",
           "enum": [
             "arc",
             "ring",
-            "dots"
+            "dots",
+            "knight"
           ],
           "default": "arc"
         }
@@ -19169,6 +22191,15 @@
           "description": "Tag label. Renderer routes this to the `text` attribute, rendered via CSS attr(text) on ::after.",
           "$ref": "#/$defs/DynamicString"
         },
+        "tone": {
+          "description": "Fill style — orthogonal to [variant]. Default (`solid`) for family\nvariants is a saturated bg with on-strong (near-white) text — the\nchip IS the state. Opt-out via `tone=\"muted\"` for a tinted bg with\nscheme-paired text (matches <badge-ui>'s default look) when the\nchip is metadata in a dense list rather than a status stamp. The\n`default` variant stays quiet chrome regardless of tone unless\n`tone=\"solid\"` is set explicitly (high-contrast neutral inverse).\n",
+          "type": "string",
+          "enum": [
+            "solid",
+            "muted"
+          ],
+          "default": "solid"
+        },
         "variant": {
           "description": "Semantic variant — `default | info | success | warning | danger`.",
           "type": "string",
@@ -19286,6 +22317,341 @@
         "version": 1
       }
     },
+    "TagsInput": {
+      "title": "TagsInput",
+      "description": "Free-form token input — type a value, press Enter (or the configured\ndelimiter) to commit it as a chip; Backspace from the empty inline\ninput removes the last chip. Distinct from <select-ui multiple>\n(SPEC-040), which is constrained to a fixed option list — tags-input\nis for OPEN sets (labels, email recipients, keyword inputs). Per\nADR-0025 the inline editor is a contenteditable surface (NO native\n`<input>` wrap). Form-bearing via UIFormElement + ElementInternals:\nthe form value is a JSON-serialized string array under `[name]`.\nEach rendered chip is a `<tag-ui removable>`; the `remove` event\ndelegates back to the host. Optional autocompletion: when\n`.suggestions` is non-empty, a popover renders below the field and\nthe host announces as a combobox per WAI-APG.\n",
+      "type": "object",
+      "allOf": [
+        {
+          "$ref": "#/$defs/ComponentCommon"
+        },
+        {
+          "$ref": "#/$defs/CatalogComponentCommon"
+        }
+      ],
+      "properties": {
+        "required": {
+          "description": "Required for form validation. Empty array fails `:invalid`.",
+          "type": "boolean",
+          "default": false
+        },
+        "component": {
+          "const": "TagsInput"
+        },
+        "delimiter": {
+          "description": "Inline character that commits the typed value as a chip. The\nsentinel `enter` disables in-line commit — only the Enter key\n(or programmatic `addToken`) commits. Default is `,`.",
+          "type": "string",
+          "default": ","
+        },
+        "disabled": {
+          "description": "Block all interaction; dim the field.",
+          "type": "boolean",
+          "default": false
+        },
+        "max": {
+          "description": "Maximum number of tokens. `0` (default) means unlimited.",
+          "type": "number",
+          "default": 0
+        },
+        "maxLength": {
+          "description": "Maximum per-token character count. `0` (default) means unlimited.",
+          "type": "number",
+          "default": 0
+        },
+        "min": {
+          "description": "Minimum required tokens for form validity.",
+          "type": "number",
+          "default": 0
+        },
+        "minLength": {
+          "description": "Minimum per-token character count after `transform` is applied.",
+          "type": "number",
+          "default": 1
+        },
+        "name": {
+          "description": "Form field name. Serializes the token list as JSON under this key.",
+          "type": "string",
+          "default": ""
+        },
+        "pasteSplit": {
+          "description": "Regex character-class fragment matched against pasted text to\nsplit it into multiple tokens. Default `,\\n` splits on commas\nand newlines. Use `\"\"` to disable paste-splitting entirely.",
+          "type": "string",
+          "default": ",\n"
+        },
+        "placeholder": {
+          "description": "Placeholder text for the inline input when no chips are committed.",
+          "type": "string",
+          "default": "Add tag…"
+        },
+        "readonly": {
+          "description": "Block edits; allow inspection (chips render without remove buttons).",
+          "type": "boolean",
+          "default": false
+        },
+        "size": {
+          "description": "Sizing scale via universal `[size]` attribute system. Matches\nInput + Combobox sizing tokens so a TagsInput rendered alongside\neither feels coherent in a form row.",
+          "type": "string",
+          "enum": [
+            "sm",
+            "md",
+            "lg"
+          ],
+          "default": "md"
+        },
+        "suggestions": {
+          "description": "Optional autocomplete strings rendered in a popover below the\nfield. Suggestions are hints, not gates — the typed value still\nwins on commit. JS property only (array reflection skipped).",
+          "$ref": "#/$defs/DynamicStringList"
+        },
+        "transform": {
+          "description": "Normalize tokens on commit. `lowercase` lowercases, `trim` strips\nleading + trailing whitespace, `strip-spaces` removes all\nwhitespace, `\"\"` (default) preserves the typed value.",
+          "type": "string",
+          "enum": [
+            "",
+            "lowercase",
+            "trim",
+            "strip-spaces"
+          ],
+          "default": ""
+        },
+        "unique": {
+          "description": "Reject duplicate tokens silently (no `invalid` event for accidental dups).",
+          "type": "boolean",
+          "default": true
+        },
+        "validateFn": {
+          "description": "Per-token validator. Sync `(value, index) => boolean` rejects\nfalse synchronously; async `(value, index) => Promise<boolean>`\nflips the host into `[validating]` while pending. JS property\nonly — not serializable in A2UI JSON; wire post-mount.",
+          "type": "object",
+          "default": null
+        },
+        "value": {
+          "description": "Current token list (string array). Setting `.value = ['a','b']`\nreplaces the rendered chips. Reflection skipped — array values\ndo not round-trip through attribute strings.",
+          "$ref": "#/$defs/DynamicStringList"
+        }
+      },
+      "required": [
+        "component"
+      ],
+      "unevaluatedProperties": false,
+      "x-adiaui": {
+        "anti_patterns": [
+          {
+            "fix": "{\"component\": \"Select\", \"multiple\": true, \"options\": [{\"id\": \"a\", \"label\": \"A\"}]}\n",
+            "why": "TagsInput does NOT accept `options`. It is the OPEN-set primitive — any\ntyped string is valid. For closed option lists, use the multi-select\nprimitive with `multiple: true`.\n",
+            "wrong": "{\"component\": \"TagsInput\", \"options\": [{\"id\": \"a\", \"label\": \"A\"}]}\n"
+          },
+          {
+            "fix": "{\"component\": \"TagsInput\", \"value\": [\"bug\", \"high-priority\"]}\n",
+            "why": "Comma-separated string is invalid for `value`. The contract requires\na string array.\n",
+            "wrong": "{\"component\": \"TagsInput\", \"value\": \"bug,high-priority\"}\n"
+          },
+          {
+            "fix": "{\"component\": \"TagsInput\", \"value\": [\"Tag 1\"]}\n",
+            "why": "Chips are rendered automatically from `value`. Slotting Tag children\ndecouples the rendered DOM from the form value and breaks Backspace\nremoval + the `change` event payload.\n",
+            "wrong": "{\"component\": \"TagsInput\", \"children\": [\n  {\"component\": \"Tag\", \"text\": \"Tag 1\"}\n]}\n"
+          }
+        ],
+        "category": "input",
+        "composes": [
+          "tag-ui",
+          "icon-ui"
+        ],
+        "events": {
+          "change": {
+            "description": "Fired after `value` changes (token added or removed).",
+            "detail": {
+              "added": {
+                "description": "Tokens added by this change (`[]` when only removals occurred).",
+                "type": "array"
+              },
+              "removed": {
+                "description": "Tokens removed by this change (`[]` when only additions occurred).",
+                "type": "array"
+              },
+              "value": {
+                "description": "Current token list (string array).",
+                "type": "array"
+              }
+            }
+          },
+          "commit": {
+            "description": "Fired immediately before a token is committed. Call\n`event.preventDefault()` to reject the candidate token.",
+            "detail": {
+              "accepted": {
+                "description": "True unless the consumer calls `preventDefault()`.",
+                "type": "boolean"
+              },
+              "value": {
+                "description": "Candidate token text (post-transform).",
+                "type": "string"
+              }
+            }
+          },
+          "input": {
+            "description": "Fired on each keystroke in the inline input (pre-commit).",
+            "detail": {
+              "query": {
+                "description": "Current typed text in the inline input.",
+                "type": "string"
+              }
+            }
+          },
+          "invalid": {
+            "description": "Fired when a candidate token is rejected. Reasons cover all\nbuilt-in validators and the user-supplied `validateFn`.",
+            "detail": {
+              "reason": {
+                "description": "One of `duplicate` / `too-short` / `too-long` / `validator` / `max`.",
+                "type": "string"
+              },
+              "value": {
+                "description": "Rejected token text.",
+                "type": "string"
+              }
+            }
+          }
+        },
+        "examples": [
+          {
+            "description": "Label input with lowercase normalization + max 10 tags + 2 pre-committed values.",
+            "a2ui": "[\n  {\"id\": \"root\", \"component\": \"Card\", \"children\": [\"sec\"]},\n  {\"id\": \"sec\", \"component\": \"Section\", \"children\": [\"field\"]},\n  {\n    \"id\": \"field\",\n    \"component\": \"Field\",\n    \"label\": \"Labels\",\n    \"children\": [\"tags\"]\n  },\n  {\n    \"id\": \"tags\",\n    \"component\": \"TagsInput\",\n    \"name\": \"labels\",\n    \"placeholder\": \"Add a label, press Enter\",\n    \"transform\": \"lowercase\",\n    \"max\": 10,\n    \"value\": [\"bug\", \"high-priority\"]\n  }\n]",
+            "name": "canonical-labels"
+          },
+          {
+            "description": "Recipient picker with Enter-only commit (commas are legal in display names).",
+            "a2ui": "[\n  {\n    \"id\": \"to\",\n    \"component\": \"TagsInput\",\n    \"name\": \"to\",\n    \"placeholder\": \"Email…\",\n    \"delimiter\": \"enter\",\n    \"transform\": \"trim\"\n  }\n]",
+            "name": "email-recipients"
+          }
+        ],
+        "keywords": [
+          "tags-input",
+          "tag-input",
+          "token-input",
+          "chips-input",
+          "chip-input",
+          "labels",
+          "recipients",
+          "keywords",
+          "tags",
+          "email-input",
+          "multi-value-input"
+        ],
+        "name": "UITagsInput",
+        "related": [
+          "tag",
+          "select",
+          "combobox",
+          "field",
+          "input"
+        ],
+        "slots": {
+          "chip": {
+            "description": "Custom chip template — receives `{value, index}` per token.\nWhen absent, each token renders as a default\n`<tag-ui removable text=\"<value>\">`."
+          }
+        },
+        "states": [
+          {
+            "description": "No tokens; no typed text.",
+            "name": "idle"
+          },
+          {
+            "description": "One or more tokens committed.",
+            "attribute": "populated",
+            "name": "populated"
+          },
+          {
+            "description": "User is typing into the inline input.",
+            "attribute": "editing",
+            "name": "editing"
+          },
+          {
+            "description": "Suggestion popover is open.",
+            "attribute": "suggesting",
+            "name": "suggesting"
+          },
+          {
+            "description": "Async `validateFn` is in flight.",
+            "attribute": "validating",
+            "name": "validating"
+          },
+          {
+            "description": "Non-interactive; dimmed.",
+            "attribute": "disabled",
+            "name": "disabled"
+          },
+          {
+            "description": "Read-only; chips render without remove affordance.",
+            "attribute": "readonly",
+            "name": "readonly"
+          }
+        ],
+        "status": "experimental",
+        "synonyms": {
+          "chips-input": [
+            "tags-input",
+            "chip-input",
+            "token-input"
+          ],
+          "labels": [
+            "tags",
+            "tag-input",
+            "labels-input"
+          ],
+          "recipients": [
+            "email-input",
+            "tags-input",
+            "to-field"
+          ],
+          "tags-input": [
+            "tag-input",
+            "chip-input",
+            "token-input",
+            "tokenizer"
+          ],
+          "token-input": [
+            "tags-input",
+            "chip-input",
+            "tokenizer"
+          ]
+        },
+        "tag": "tags-input-ui",
+        "tokens": {
+          "--tags-input-bg": {
+            "description": "Host background color."
+          },
+          "--tags-input-border": {
+            "description": "Host border color (idle)."
+          },
+          "--tags-input-border-hover": {
+            "description": "Host border color on hover."
+          },
+          "--tags-input-chip-bg-invalid": {
+            "description": "Chip background color when a chip is marked invalid (validator rejection echo)."
+          },
+          "--tags-input-fg": {
+            "description": "Host foreground (typed-text color)."
+          },
+          "--tags-input-focus-ring": {
+            "description": "Focus-ring box-shadow when the host is focus-within."
+          },
+          "--tags-input-gap": {
+            "description": "Gap between chips and the inline input."
+          },
+          "--tags-input-placeholder-fg": {
+            "description": "Placeholder color for the empty inline input."
+          },
+          "--tags-input-px": {
+            "description": "Horizontal padding inside the chip-cluster wrapper."
+          },
+          "--tags-input-py": {
+            "description": "Vertical padding inside the chip-cluster wrapper."
+          },
+          "--tags-input-radius": {
+            "description": "Host border radius."
+          }
+        },
+        "traits": [],
+        "version": 1
+      }
+    },
     "Text": {
       "title": "Text",
       "description": "Typography wrapper that applies role tokens. Supports truncation and line clamping.",
@@ -19457,7 +22823,7 @@
     },
     "Textarea": {
       "title": "Textarea",
-      "description": "Multi-line text input primitive — the host IS the contenteditable\nsurface (per ADR-0025, no native <textarea> wrapped underneath).\nForm-bearing via UIFormElement: [name], [value], [required],\n[disabled], [readonly], fires `change` on blur and `input` per\nkeystroke. Enter inserts a newline — does NOT fire `submit` (for\nEnter-to-send composers use <chat-input-ui submit-on-enter> inside\n<chat-composer>). Wrap in <field-ui label=\"…\"> for the canonical\nlabeled stack.\n",
+      "description": "Multi-line text input primitive — the host IS the contenteditable\nsurface (per ADR-0025, no native <textarea> wrapped underneath).\nForm-bearing via UIFormElement: [name], [value], [required],\n[disabled], [readonly], fires `change` on blur and `input` per\nkeystroke. Enter (without Shift) dispatches a bubbling `submit`\nevent — Shift+Enter inserts a newline. This is unconditional;\nthere is no opt-in/opt-out attribute. For Enter-to-send composers\nuse <chat-input-ui> inside <chat-composer>. Wrap in <field-ui\nlabel=\"…\"> for the canonical labeled stack.\n",
       "type": "object",
       "allOf": [
         {