@adia-ai/web-modules 0.8.36 → 0.8.38

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog — @adia-ai/web-modules
 
+## [0.8.38] — 2026-08-15
+
+### Maintenance
+- **Lockstep version bump only.** No source changes in this package; bumped to maintain the lockstep version coherence enforced by `scripts/release/check-lockstep.mjs`. Substantive v0.8.38 work shipped in clean-world cut: five-family layout (ADR-0049), tiered-catalog contract phase 1 (ADR-0050), factory MCP server (ADR-0051), drilldown-ui, nav/view-transition/page fixes. See `packages/gen-ui/mcp/CHANGELOG.md#0838--2026-08-15` for details.
+- **`agent-admin/` touched in this release window** (2 file(s), e.g. `admin-settings/admin-settings.examples.html`) — carried by the entries above.
+- **`chat/` touched in this release window** (4 file(s), e.g. `chat/README.md`) — carried by the entries above.
+- **`dist/` bundles rebuilt** in this cut's window (2 file(s)) — regenerated from the source changes described above, not independent edits.
+
+## [0.8.37] — 2026-08-14
+
+### Fixed
+- **All 44 `escaped-root` packed-import violations resolved (gh#1191, gh#1186's biggest sibling).** Every relative specifier that walked out of this package's root (`../../../web-components/core/element.js` and its neighbors) now routes through `@adia-ai/web-components`'s own npm subpaths (`core/element`, `core/register`, `core/markdown`, `core/form`, `core/signals`, `components/code`, `components/agent-reasoning`, `components/canvas`, `components/chat-thread`, `components/inspector`). `shell/embed-shell/embed-shell.js`'s `resizable` trait registration is the one exception: `web-components`' `./traits/*` export only maps to a flat `./traits/*.js`, and the trait lives at `traits/resizable/resizable.js` — it now imports the `@adia-ai/web-components/traits` barrel instead, the same "consumers who use the trait library at all get declarative composition for free" pattern that module's own doc comment already describes.
+- **`billing/`, `dashboard/`, `feedback/`, `onboarding/`, `settings/` — 5 cluster barrels were never packed (gh#1191).** All five directories existed on disk (and were already listed in `sideEffects`) but `package.json`'s `files` field never shipped them, so `import '@adia-ai/web-modules'` 404'd on its own root barrel outside this repo. Added to `files`, plus matching `exports` subpaths (`./billing`, `./billing/*`, `./billing/*.css`, and the same for the other four) mirroring the existing `agent-admin`/`form` cluster shape. Fixing this surfaced 9 more `escaped-root` violations inside those clusters that the gate had never scanned — fixed alongside.
+
+### Added
+- **`npm run probe:packed-boot:web-modules`** proves the fix end-to-end: packs this package + its 5 first-party peers, installs the tarballs into a scratch dir outside the repo, and imports all 15 cluster barrels from that install. See root `CHANGELOG.md` `[Unreleased]` for the full description.
+
+### Maintenance
+- **`dist/` bundles rebuilt** in this cut's window (1 file(s)) — regenerated from the source changes described above, not independent edits.
+- **`editor/` touched in this release window** (11 file(s), e.g. `editor-canvas-empty/editor-canvas-empty.examples.html`) — carried by the entries above.
+- **`generative/` touched in this release window** (2 file(s), e.g. `generative/index.d.ts`) — carried by the entries above.
+- **`runtime/` touched in this release window** (2 file(s), e.g. `a2ui-root/a2ui-root.js`) — carried by the entries above.
+- **`simple/` touched in this release window** (1 file(s), e.g. `simple-shell/simple-shell.js`) — carried by the entries above.
+- **`theme/` touched in this release window** (2 file(s), e.g. `theme-panel/theme-panel.examples.html`) — carried by the entries above.
+
 ## [0.8.36] — 2026-08-13
 
 ### Maintenance

package/README.md

@@ -112,7 +112,7 @@ See the [CDN usage guide](https://ui-kit.exe.xyz/site/cdn-usage) for a full Code
 
 ### Using with AI agents
 
-When composing UI with an AI coding agent (Claude Code / Cursor / Windsurf / Claude Desktop), load the **`adia-ui-kit` skill** in the harness — it encodes the 95-primitive catalog, composition patterns for all shells (admin / chat / editor / simple), and the Plan-Execute-Verify discipline that renders the composed surface in a real demo to verify intent. Skill lives at [`.agents/skills/adia-compose/`](https://github.com/adiahealth/gen-ui-kit/tree/main/.agents/skills/adia-ui-kit) in the repo.
+When composing UI with an AI coding agent (Claude Code / Cursor / Windsurf / Claude Desktop), load the **`adia-ui-kit` skill** in the harness — it encodes the 95-primitive catalog, composition patterns for all shells (admin / chat / editor / simple), and the Plan-Execute-Verify discipline that renders the composed surface in a real demo to verify intent. Skill lives at [`.agents/skills/screen-composition/`](https://github.com/adiahealth/gen-ui-kit/tree/main/.agents/skills/adia-ui-kit) in the repo.
 
 `@adia-ai/web-components` is **always required** (modules compose primitives at runtime). Two additional peer dependencies are declared but **only needed for specific clusters**:
 
@@ -234,7 +234,7 @@ hunt for it:
 Future clusters on the strategic horizon: `data` (kanban, filters,
 table-toolbar), `agent` (agent-trace, reasoning panels).
 
-See [`adia-ui-authoring` skill, `references/shell-patterns.md`](../../.agents/skills/adia-author/references/shell-patterns.md) (absorbed `bespoke-shell-children`) for the canonical decomposition recipe used by all three families.
+See [`adia-ui-authoring` skill, `references/shell-patterns.md`](../../.agents/skills/primitive-authoring/references/shell-patterns.md) (absorbed `bespoke-shell-children`) for the canonical decomposition recipe used by all three families.
 
 ## Quick start
 
@@ -349,7 +349,7 @@ web-modules/
 └── index.js               barrel re-export of every cluster
 ```
 
-Each element directory carries its `.js`, `.css`, `.yaml`, and `.a2ui.json` files — same shape as `web-components/components/<x>/`. The yaml + a2ui.json contracts feed the gen-UI catalog at `packages/a2ui/corpus/catalog-a2ui_0_9.json`; the build script at `scripts/build/components.mjs` scans both `web-components/components/` and `web-modules/<cluster>/`.
+Each element directory carries its `.js`, `.css`, `.yaml`, and `.a2ui.json` files — same shape as `web-components/components/<x>/`. The yaml + a2ui.json contracts feed the gen-UI catalog at `packages/gen-ui/a2ui/corpus/catalog-a2ui_0_9.json`; the build script at `scripts/build/components.mjs` scans both `web-components/components/` and `web-modules/<cluster>/`.
 
 ## Behavior contract
 
@@ -358,7 +358,7 @@ All `<*-shell>` hosts are **behavior-only orchestrators** — they reflect state
 - **JS-bearing children** carry `connected()`/`disconnected()` lifecycle for interactive behavior (`admin-sidebar` resize, `admin-command` palette, `chat-thread` streaming scroll, `editor-canvas` zoom, etc.).
 - **CSS-only children** (no `.js` file — only `.yaml` + `.css` + `.a2ui.json`) declare slot intent for the host's styling system to attach against. Don't author a `.js` for these; the host handles their behavior via attribute selectors.
 
-The decomposition recipe (when to JS-bearing vs CSS-only, how to namespace state attributes, slot vocabulary conventions) is captured in the [`adia-ui-authoring` skill, `references/shell-patterns.md`](../../.agents/skills/adia-author/references/shell-patterns.md) (absorbed `bespoke-shell-children`).
+The decomposition recipe (when to JS-bearing vs CSS-only, how to namespace state attributes, slot vocabulary conventions) is captured in the [`adia-ui-authoring` skill, `references/shell-patterns.md`](../../.agents/skills/primitive-authoring/references/shell-patterns.md) (absorbed `bespoke-shell-children`).
 
 ## License
 

package/agent-admin/admin-roster/admin-roster.js

@@ -31,7 +31,7 @@
  * <button-ui> + <icon-ui> + <menu-item-ui> (menu.js) alongside this module.
  */
 
-import { UIElement, html } from '../../../web-components/core/element.js';
+import { UIElement, html } from '@adia-ai/web-components/core/element';
 import { exportPersona, importPersona } from '@adia-ai/persona';
 
 class UIAdminRoster extends UIElement {

package/agent-admin/admin-settings/admin-settings.js

@@ -30,7 +30,7 @@
  * <switch-ui>, <textarea-ui>, <text-ui>, <icon-ui>, <button-ui> alongside this module.
  */
 
-import { UIElement, html } from '../../../web-components/core/element.js';
+import { UIElement, html } from '@adia-ai/web-components/core/element';
 import { KNOWN_KINDS } from '@adia-ai/persona';
 import { entryStoreKey } from '../live-persona.js';
 

package/agent-admin/agent-admin/agent-admin.js

@@ -49,7 +49,7 @@
  * and <chat-shell> (+ its own bespoke children) alongside this module.
  */
 
-import { UIElement } from '../../../web-components/core/element.js';
+import { UIElement } from '@adia-ai/web-components/core/element';
 import { compilePersona, personaStore } from '@adia-ai/persona';
 import { createSession, composeSystem } from '@adia-ai/agent';
 import { createSurfaceRegistry, wireAgentEvents } from '../../chat/chat-surfaces/chat-surfaces.js';

package/billing/billing-overview/billing-overview.a2ui.json

@@ -0,0 +1,281 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/BillingOverview.json",
+  "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: .claude/docs/specs/implementation-ready/SPEC-004-billing-overview.md.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$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": "common_types.json#/$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
+  }
+}