@adia-ai/web-modules 0.8.24 → 0.8.26

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog — @adia-ai/web-modules
 
+## [0.8.26] — 2026-08-05
+
+### Added
+- **`chat-surfaces` (WCH-4, gh#599)** — the L3 surface-host registry: `createSurfaceRegistry` (per-surfaceId hosts with persistent bubble identity across turns; protocol-level close with a visible non-removable annotation) + `wireAgentEvents` (folds an `AgentEvent` stream into chat-shell's external-drive API with a code-owned progress-label table). Transport-blind; the renderer is dependency-injected.
+- **`agent-admin` composite family (WCH-5, gh#600)** — `admin-roster-ui` (exactly-one-active persona roster, import/export), `admin-settings-ui` (settings over one bound store, KNOWN_KINDS display grouping, zero per-kind logic), `agent-admin-ui` (roster + settings + chat; the store-swap law: a genuine store-reference change resets conversation/surfaces/session, a same-store reconnect resets nothing; live-apply by fresh read). Peer-depends on `@adia-ai/persona` + `@adia-ai/agent` (exact-pinned).
+
+### Fixed
+- **theme-panel sliders trust applied state** (gh#578, PR #609) — theme clicks no longer round-trip `getComputedStyle` (which showed the theme's baked shape values); the one legitimate initial read is isolated in `#readInitialShape` with its rationale.
+
+### Maintenance
+- **`dist/` bundles rebuilt** in this cut's window (1 file(s)) — regenerated from the source changes described above, not independent edits.
+
+## [0.8.25] — 2026-07-31
+
+### Fixed
+- **`theme-panel[scheme-toggle]` gains a System option** (operator report). The segmented control only offered Light/Dark, so a user who picked either couldn't return to OS-following `auto` from the UI — and the control silently collapsed "System, currently resolving light" to just "Light", hiding that auto was even active. Added a System segment; every sync point (initial resolve, live `prefers-color-scheme` changes, reset, programmatic `.apply()`) now reflects the RAW scheme intent (`auto`/`light`/`dark`) on the segment, not the resolved paint — System stays selected across an OS theme flip.
+- **theme-panel's scoped-target demo used a stale pre-ADR-0035 token** (`--a-radius-2`, doesn't exist post the v0.6.48 foundation reorg) — its preview pane's border-radius was permanently invalid-at-computed-value, always rendering 0px regardless of the radius slider. Root-target (default) parametric radius was never broken — verified via a real mouse drag (value 1→2, a live button's radius 9.3px→14px, correctly clamped). The scoped-target demo itself was also asserting a capability the framework didn't have at the time: `[parametric]` density/radius only reactively recomputed for `target=":root"` (gh#570 — the derived tokens were declared once on `:root`, so a scoped-target override never triggered their re-derivation). **gh#570 is fixed in this same release** (see `@adia-ai/web-components`'s `theme-panel[parametric]` entry above) via a `data-parametric-scope` marker that re-derives the chain for a scoped target too — the demo's scoped instance keeps `[parametric]` and now works correctly. `[theme]`/`color-scheme` scoping to a non-root target was unaffected throughout and continues to work.
+
+### Maintenance
+- **`billing/` touched in this release window** (6 file(s), e.g. `billing-overview/billing-overview.examples.html`) — carried by the entries above.
+- **`dashboard/` touched in this release window** (2 file(s), e.g. `dashboard-layout/dashboard-layout.examples.html`) — carried by the entries above.
+- **`dist/` bundles rebuilt** in this cut's window (1 file(s)) — regenerated from the source changes described above, not independent edits.
+- **`feedback/` touched in this release window** (1 file(s), e.g. `confirm-dialog/confirm-dialog.examples.html`) — carried by the entries above.
+- **`form/` touched in this release window** (1 file(s), e.g. `form-popover/form-popover.examples.html`) — carried by the entries above.
+- **`onboarding/` touched in this release window** (1 file(s), e.g. `onboarding-checklist/onboarding-checklist.examples.html`) — carried by the entries above.
+- **`settings/` touched in this release window** (2 file(s), e.g. `integrations-page/integrations-page.examples.html`) — carried by the entries above.
+
 ## [0.8.24] — 2026-07-30
 
 ### Maintenance

package/agent-admin/admin-roster/admin-roster.a2ui.json

@@ -0,0 +1,171 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://adiaui.dev/a2ui/v0_9/components/AdminRoster.json",
+  "title": "AdminRoster",
+  "description": "L4 persona roster (CHAT-HARNESS.md §Components row L4, gh#600 / WCH-5) —\none row per persona with exactly-one-active menu semantics\n(`role=\"menu\"` of `role=\"menuitemradio\"` rows, `aria-checked` mirroring\n`[active-id]`). Clicking a row fires `persona-change` with the clicked\npersona's id; clicking the already-active row is a no-op. Import/export\nbuttons ride `@adia-ai/persona`'s persona-file functions verbatim —\nexport downloads the active persona as JSON, import reads a chosen file\nand re-emits the minted persona as `persona-import` for the host to\nappend and persist.\n\nLives in `packages/web-modules/agent-admin/` alongside\n`<admin-settings-ui>` and `<agent-admin-ui>` — the L4 admin composite\nfamily over `@adia-ai/persona`'s L2 store contract.\n",
+  "type": "object",
+  "allOf": [
+    {
+      "$ref": "common_types.json#/$defs/ComponentCommon"
+    },
+    {
+      "$ref": "common_types.json#/$defs/CatalogComponentCommon"
+    }
+  ],
+  "properties": {
+    "active-id": {
+      "description": "The currently-active persona's id. Reflects so a host can deep-link;\ndrives `aria-checked` + the visible check glyph on the matching row.\n",
+      "$ref": "common_types.json#/$defs/DynamicString"
+    },
+    "component": {
+      "const": "AdminRoster"
+    },
+    "personas": {
+      "description": "Array of `{ id, label, category? }` persona summaries. Empty array\nrenders \"No personas yet.\"\n",
+      "$ref": "common_types.json#/$defs/DynamicStringList"
+    }
+  },
+  "required": [
+    "component",
+    "personas"
+  ],
+  "unevaluatedProperties": false,
+  "x-adiaui": {
+    "anti_patterns": [
+      {
+        "fix": "{\"component\": \"AdminRoster\", \"personas\": [{\"id\": \"a\", \"label\": \"A\"}]}\n",
+        "why": "Rows are generated from the `personas` prop — slotted children are ignored.",
+        "wrong": "{\"component\": \"AdminRoster\", \"personas\": [{\"id\": \"a\", \"label\": \"A\"}], \"children\": [\n  {\"component\": \"Button\", \"text\": \"Switch\"}\n]}\n"
+      }
+    ],
+    "category": "container",
+    "composes": [
+      "button-ui",
+      "icon-ui"
+    ],
+    "events": {
+      "persona-change": {
+        "description": "A non-active row was clicked.",
+        "detail": {
+          "personaId": {
+            "description": "The id of the persona the user switched to.",
+            "type": "string"
+          }
+        }
+      },
+      "persona-import": {
+        "description": "A persona file was chosen and parsed successfully.",
+        "detail": {
+          "persona": {
+            "description": "The minted persona (fresh, collision-safe id) from `importPersona`.",
+            "type": "object"
+          }
+        }
+      },
+      "persona-import-error": {
+        "description": "A chosen file failed to parse or validate as a persona file.",
+        "detail": {
+          "error": {
+            "description": "The error message from `importPersona`.",
+            "type": "string"
+          }
+        }
+      }
+    },
+    "examples": [
+      {
+        "description": "Roster with one active persona.",
+        "a2ui": "[{\"id\": \"roster\", \"component\": \"AdminRoster\",\n  \"active-id\": \"support\",\n  \"personas\": [\n    {\"id\": \"support\", \"label\": \"Support agent\", \"category\": \"Customer\"},\n    {\"id\": \"writer\", \"label\": \"Writer\", \"category\": \"Content\"}\n  ]}]\n",
+        "name": "two-personas"
+      },
+      {
+        "description": "No personas yet.",
+        "a2ui": "[{\"id\": \"roster\", \"component\": \"AdminRoster\", \"personas\": []}]\n",
+        "name": "empty"
+      }
+    ],
+    "keywords": [
+      "admin",
+      "persona",
+      "roster",
+      "agent",
+      "switch",
+      "menu"
+    ],
+    "name": "UIAdminRoster",
+    "related": [
+      "AdminSettings",
+      "AgentAdmin",
+      "Menu"
+    ],
+    "slots": {},
+    "states": [
+      {
+        "description": "Default; renders the persona list.",
+        "name": "idle"
+      },
+      {
+        "description": "`personas` is an empty array.",
+        "name": "empty"
+      }
+    ],
+    "status": "stable",
+    "synonyms": {
+      "persona": [
+        "agent",
+        "config",
+        "profile"
+      ],
+      "roster": [
+        "list",
+        "personas",
+        "agents"
+      ]
+    },
+    "tag": "admin-roster-ui",
+    "tokens": {
+      "--admin-roster-active-bg": {
+        "description": "Active/hover row background.",
+        "default": "var(--a-bg-muted)"
+      },
+      "--admin-roster-active-fg": {
+        "description": "Active row foreground.",
+        "default": "var(--a-fg-strong)"
+      },
+      "--admin-roster-bg": {
+        "description": "Panel background.",
+        "default": "var(--a-bg)"
+      },
+      "--admin-roster-fg": {
+        "description": "Primary foreground.",
+        "default": "var(--a-fg)"
+      },
+      "--admin-roster-fg-muted": {
+        "description": "Secondary foreground (category text, empty state).",
+        "default": "var(--a-fg-muted)"
+      },
+      "--admin-roster-gap": {
+        "description": "Vertical gap between header / menu / toolbar.",
+        "default": "var(--a-space-3)"
+      },
+      "--admin-roster-px": {
+        "description": "Horizontal padding.",
+        "default": "var(--a-space-4)"
+      },
+      "--admin-roster-py": {
+        "description": "Vertical padding.",
+        "default": "var(--a-space-4)"
+      },
+      "--admin-roster-row-gap": {
+        "description": "Gap between rows.",
+        "default": "var(--a-space-1)"
+      },
+      "--admin-roster-row-radius": {
+        "description": "Row border radius.",
+        "default": "var(--a-radius-md)"
+      }
+    },
+    "traits": [],
+    "version": 1
+  }
+}

package/agent-admin/admin-roster/admin-roster.css

@@ -0,0 +1,112 @@
+/* ═══════════════════════════════════════════════════════════════
+   admin-roster-ui — Module CSS
+
+   Two-block @scope:
+     Block 1 — TOKENS  (:where(:scope))
+     Block 2 — BASE    (:scope + descendant rules)
+
+   Tokens consumed (substrate):
+     --a-bg, --a-fg, --a-fg-muted, --a-fg-strong, --a-border-subtle,
+     --a-bg-muted, --a-radius-md, --a-space-1..6, --a-ui-sm, --a-text-lg,
+     --a-weight-medium, --a-accent, --a-accent-contrast
+   ═══════════════════════════════════════════════════════════════ */
+
+@scope (admin-roster-ui) {
+
+  :where(:scope) {
+    --admin-roster-bg:            var(--a-bg);
+    --admin-roster-fg:            var(--a-fg);
+    --admin-roster-fg-muted:      var(--a-fg-muted);
+    --admin-roster-px:            var(--a-space-4);
+    --admin-roster-py:            var(--a-space-4);
+    --admin-roster-gap:           var(--a-space-3);
+    --admin-roster-row-gap:       var(--a-space-1);
+    --admin-roster-row-radius:    var(--a-radius-md);
+    --admin-roster-active-bg:     var(--a-bg-muted);
+    --admin-roster-active-fg:     var(--a-fg-strong);
+  }
+
+  :scope {
+    box-sizing: border-box;
+    display: grid;
+    gap: var(--admin-roster-gap);
+    padding: var(--admin-roster-py) var(--admin-roster-px);
+    background: var(--admin-roster-bg);
+    color: var(--admin-roster-fg);
+    min-width: 0;
+  }
+
+  :scope > [data-part="header"] > [data-part="title"] {
+    margin: 0;
+    font-size: var(--a-ui-sm);
+    font-weight: var(--a-weight-medium);
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+    color: var(--admin-roster-fg-muted);
+  }
+
+  :scope [data-part="menu"] {
+    display: grid;
+    gap: var(--admin-roster-row-gap);
+  }
+
+  :scope [data-part="row"] {
+    box-sizing: border-box;
+    display: flex;
+    align-items: center;
+    gap: var(--a-space-2);
+    width: 100%;
+    padding: var(--a-space-2) var(--a-space-3);
+    border: 1px solid transparent;
+    border-radius: var(--admin-roster-row-radius);
+    background: transparent;
+    color: var(--admin-roster-fg);
+    font: inherit;
+    text-align: left;
+    cursor: pointer;
+  }
+
+  :scope [data-part="row"]:hover {
+    background: var(--admin-roster-active-bg);
+  }
+
+  :scope [data-part="row"][data-active="true"] {
+    background: var(--admin-roster-active-bg);
+    color: var(--admin-roster-active-fg);
+    font-weight: var(--a-weight-medium);
+  }
+
+  :scope [data-part="row-label"] {
+    flex: 1 1 auto;
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  :scope [data-part="row-category"] {
+    flex: 0 0 auto;
+    font-size: var(--a-ui-sm);
+    color: var(--admin-roster-fg-muted);
+  }
+
+  :scope [data-part="row-check"] {
+    flex: 0 0 auto;
+    visibility: hidden;
+  }
+
+  :scope [data-part="row"][data-active="true"] [data-part="row-check"] {
+    visibility: visible;
+  }
+
+  :scope [data-part="empty"] {
+    padding: var(--a-space-4);
+    color: var(--admin-roster-fg-muted);
+    text-align: center;
+  }
+
+  :scope [data-part="toolbar"] {
+    display: flex;
+    gap: var(--a-space-2);
+  }
+}

package/agent-admin/admin-roster/admin-roster.d.ts

@@ -0,0 +1,44 @@
+/**
+ * `<admin-roster-ui>` — L4 persona roster (CHAT-HARNESS.md §Components row
+ * L4, gh#600 / WCH-5).
+ *
+ * Hand-authored alongside `<name>.yaml`; regenerate when the props /
+ * events shape changes.
+ */
+
+import { UIElement } from '../../../web-components/core/element.js';
+
+export interface AdminRosterPersonaSummary {
+  id: string;
+  label: string;
+  category?: string;
+}
+
+export interface AdminRosterPersonaChangeDetail {
+  personaId: string;
+}
+export type AdminRosterPersonaChangeEvent = CustomEvent<AdminRosterPersonaChangeDetail>;
+
+export interface AdminRosterPersonaImportDetail {
+  persona: import('@adia-ai/persona').Persona;
+}
+export type AdminRosterPersonaImportEvent = CustomEvent<AdminRosterPersonaImportDetail>;
+
+export interface AdminRosterPersonaImportErrorDetail {
+  error: string;
+}
+export type AdminRosterPersonaImportErrorEvent = CustomEvent<AdminRosterPersonaImportErrorDetail>;
+
+export class UIAdminRoster extends UIElement {
+  personas: AdminRosterPersonaSummary[];
+  'active-id': string;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIAdminRoster, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'persona-change', listener: (ev: AdminRosterPersonaChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'persona-import', listener: (ev: AdminRosterPersonaImportEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'persona-import-error', listener: (ev: AdminRosterPersonaImportErrorEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

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

@@ -0,0 +1,202 @@
+/**
+ * <admin-roster-ui> — L4 persona roster (CHAT-HARNESS.md §Components row L4,
+ * gh#600 / WCH-5).
+ *
+ *   <admin-roster-ui id="roster"></admin-roster-ui>
+ *   <script>
+ *     const roster = document.querySelector('#roster');
+ *     roster.personas = [
+ *       { id: 'support', label: 'Support agent', category: 'Customer' },
+ *       { id: 'writer',  label: 'Writer',        category: 'Content'  },
+ *     ];
+ *     roster['active-id'] = 'support';
+ *     roster.addEventListener('persona-change', (e) => { ... e.detail.personaId });
+ *   </script>
+ *
+ * One row per persona, exactly-one-active menu semantics: WAI-ARIA
+ * `role="menu"` of `role="menuitemradio"` rows, `aria-checked` mirrors
+ * `[active-id]`. Clicking the already-active row is a no-op (radio
+ * semantics — a radio group never fires a change back to its own value).
+ *
+ * Import/export rides `@adia-ai/persona`'s persona-file functions
+ * verbatim — this composite never re-implements the file format. Export
+ * downloads a `.json` via a throwaway object URL; import reads a chosen
+ * file through `input[type=file]`, calls `importPersona` (which always
+ * MINTS a new persona — never overwrites an existing one, even on an id
+ * collision) and re-emits it upward as `persona-import` so a host can
+ * append it to its own persona list and persist it.
+ *
+ * Per ADR-0027 — composites that programmatically create primitives in
+ * render() do NOT auto-import those primitives; a consumer imports
+ * <button-ui> + <icon-ui> alongside this module.
+ */
+
+import { UIElement, html } from '../../../web-components/core/element.js';
+import { exportPersona, importPersona } from '@adia-ai/persona';
+
+class UIAdminRoster extends UIElement {
+  static properties = {
+    personas: { type: Array, default: [] },
+    'active-id': { type: String, default: '', reflect: true },
+  };
+
+  static template = (host) => host._renderTemplate();
+
+  #headerId = `admin-roster-h-${Math.random().toString(36).slice(2, 8)}`;
+  #fileInput = null;
+
+  attributeChangedCallback(name, oldVal, newVal) {
+    if (name === 'personas') {
+      if (newVal == null) {
+        this.personas = [];
+      } else {
+        try {
+          const parsed = JSON.parse(newVal);
+          this.personas = Array.isArray(parsed) ? parsed : [];
+        } catch {
+          this.personas = [];
+        }
+      }
+      return;
+    }
+    super.attributeChangedCallback(name, oldVal, newVal);
+  }
+
+  connected() {
+    this.setAttribute('role', 'region');
+    this.setAttribute('aria-labelledby', this.#headerId);
+    if (this.hasAttribute('personas') && !Array.isArray(this.personas)) {
+      try { this.personas = JSON.parse(this.getAttribute('personas')); }
+      catch { this.personas = []; }
+    }
+    this.addEventListener('click', this.#onClick);
+    this.addEventListener('change', this.#onImportFileChange);
+  }
+
+  disconnected() {
+    this.removeEventListener('click', this.#onClick);
+    this.removeEventListener('change', this.#onImportFileChange);
+  }
+
+  _renderTemplate() {
+    const list = Array.isArray(this.personas) ? this.personas : [];
+    const activeId = this['active-id'] || '';
+    return html`
+      <header data-part="header">
+        <h2 data-part="title" id=${this.#headerId}>Personas</h2>
+      </header>
+      <div data-part="menu" role="menu" aria-label="Personas">
+        ${list.length === 0 ? this.#renderEmpty() : list.map((p) => this.#renderRow(p, activeId))}
+      </div>
+      <div data-part="toolbar">
+        <button-ui data-action="export" text="Export" icon="download-simple" variant="ghost" size="sm"
+          .disabled=${!activeId}></button-ui>
+        <button-ui data-action="import" text="Import" icon="upload-simple" variant="ghost" size="sm"></button-ui>
+      </div>
+    `;
+  }
+
+  #renderRow(persona, activeId) {
+    const isActive = persona.id === activeId;
+    return html`
+      <button
+        type="button"
+        data-part="row"
+        data-persona-id=${persona.id}
+        role="menuitemradio"
+        aria-checked=${String(isActive)}
+        data-active=${isActive}
+      >
+        <span data-part="row-label">${persona.label ?? persona.id}</span>
+        ${persona.category ? html`<span data-part="row-category">${persona.category}</span>` : null}
+        <icon-ui data-part="row-check" name="check" aria-hidden="true"></icon-ui>
+      </button>
+    `;
+  }
+
+  #renderEmpty() {
+    return html`<div data-part="empty" role="status">No personas yet.</div>`;
+  }
+
+  // ── event delegation ────────────────────────────────────────────
+
+  #onClick = (e) => {
+    const row = e.target.closest?.('[data-part="row"]');
+    if (row && this.contains(row)) {
+      const personaId = row.getAttribute('data-persona-id');
+      if (personaId && personaId !== this['active-id']) {
+        this['active-id'] = personaId;
+        this.dispatchEvent(new CustomEvent('persona-change', {
+          bubbles: true,
+          detail: { personaId },
+        }));
+      }
+      return;
+    }
+
+    const exportBtn = e.target.closest?.('[data-action="export"]');
+    if (exportBtn && this.contains(exportBtn)) {
+      this.#exportActive();
+      return;
+    }
+
+    const importBtn = e.target.closest?.('[data-action="import"]');
+    if (importBtn && this.contains(importBtn)) {
+      this.#triggerImport();
+    }
+  };
+
+  #exportActive() {
+    const activeId = this['active-id'];
+    const persona = (Array.isArray(this.personas) ? this.personas : []).find((p) => p.id === activeId);
+    if (!persona) return;
+    const json = exportPersona(persona);
+    const blob = new Blob([json], { type: 'application/json' });
+    const url = URL.createObjectURL(blob);
+    const a = this.ownerDocument.createElement('a');
+    a.href = url;
+    a.download = `${persona.id}.persona.json`;
+    a.click();
+    URL.revokeObjectURL(url);
+  }
+
+  #triggerImport() {
+    if (!this.#fileInput) {
+      this.#fileInput = this.ownerDocument.createElement('input');
+      this.#fileInput.type = 'file';
+      this.#fileInput.accept = 'application/json';
+      this.#fileInput.setAttribute('data-part', 'import-file');
+      this.#fileInput.style.display = 'none';
+      this.appendChild(this.#fileInput);
+    }
+    this.#fileInput.value = '';
+    this.#fileInput.click();
+  }
+
+  #onImportFileChange = async (e) => {
+    const input = e.target;
+    if (!input || input !== this.#fileInput) return;
+    const file = input.files?.[0];
+    if (!file) return;
+    try {
+      const text = await file.text();
+      const existingIds = (Array.isArray(this.personas) ? this.personas : []).map((p) => p.id);
+      const persona = importPersona(text, existingIds);
+      this.dispatchEvent(new CustomEvent('persona-import', {
+        bubbles: true,
+        detail: { persona },
+      }));
+    } catch (err) {
+      this.dispatchEvent(new CustomEvent('persona-import-error', {
+        bubbles: true,
+        detail: { error: err instanceof Error ? err.message : String(err) },
+      }));
+    }
+  };
+}
+
+if (!customElements.get('admin-roster-ui')) {
+  customElements.define('admin-roster-ui', UIAdminRoster);
+}
+
+export { UIAdminRoster };