@adia-ai/web-modules 0.7.10 → 0.7.12

package/runtime/a2ui-root/a2ui-root.d.ts

@@ -1,5 +1,5 @@
 /**
- * `<a2ui-root-ui>` — A2UI protocol surface. Connects to a stream source (SSE, WebSocket, JSONL, MCP) and renders A2UI messages as AdiaUI components via the `@adia-ai/a2ui-utils` renderer.
+ * `<a2ui-root>` — A2UI protocol surface. Connects to a stream source (SSE, WebSocket, JSONL, MCP) and renders A2UI messages as AdiaUI components via the `@adia-ai/a2ui-utils` renderer.
  *
  * @see https://ui-kit.exe.xyz/site/components/a2ui-root
  *

package/runtime/gen-root/gen-root.d.ts

@@ -1,5 +1,5 @@
 /**
- * `<gen-root-ui>` — Composition shell for chat + canvas generative UI. Manages layout modes
+ * `<gen-root>` — Composition shell for chat + canvas generative UI. Manages layout modes
 (chat-only / split / canvas-only) and delegates a unified API across
 child chat-ui, canvas-ui, and inspector-ui elements.
 

package/shell/admin-command/admin-command.d.ts

@@ -1,5 +1,5 @@
 /**
- * `<admin-command-ui>` — Module-tier command palette wrapper — wraps a native <dialog> and the
+ * `<admin-command>` — Module-tier command palette wrapper — wraps a native <dialog> and the
 inner <command-ui>. Owns the keyboard shortcut listener, focus
 management, and dismiss handlers. Reflects [open].
 

package/shell/admin-shell/admin-shell.d.ts

@@ -1,5 +1,5 @@
 /**
- * `<admin-shell-ui>` — Behavior-only application shell. Canonical authoring shape uses
+ * `<admin-shell>` — Behavior-only application shell. Canonical authoring shape uses
 cluster-namespaced bespoke children — <admin-topbar> at the top,
 <admin-sidebar slot="leading|trailing"> rails, <admin-content> for
 the main content region, <admin-command> for the Cmd+K palette, and

package/shell/admin-sidebar/admin-sidebar.d.ts

@@ -1,5 +1,5 @@
 /**
- * `<admin-sidebar-ui>` — Module-tier shell sidebar — owns resize, snap-to-collapsed, persistence,
+ * `<admin-sidebar>` — Module-tier shell sidebar — owns resize, snap-to-collapsed, persistence,
 and the [collapsed] reflected attribute. Sits inside <admin-shell> as
 slot="leading" or slot="trailing". Authors compose chrome bars + content
 inside via slot vocabulary.

package/shell/embed-shell/embed-shell.css

@@ -19,27 +19,9 @@ embed-shell {
   font-family: var(--a-font-family);
 }
 
-/* Opt-in resize affordance — resize needs overflow ≠ visible (satisfied above). */
-embed-shell[traits~="resizable"] {
-  resize: both;
-}
-/* The native ::-webkit-resizer is tiny + faint + half-hidden by the rounded
-   corner, so it reads as "not resizable". Draw a clear diagonal-grip cue inset
-   from the corner (clear of the radius); pointer-events:none keeps the native
-   resize working underneath it. */
-embed-shell[traits~="resizable"]::after {
-  content: "";
-  position: absolute;
-  inset-block-end: 4px;
-  inset-inline-end: 4px;
-  inline-size: 12px;
-  block-size: 12px;
-  pointer-events: none;
-  opacity: 0.6;
-  background:
-    linear-gradient(135deg, transparent 0 46%, var(--a-fg-subtle) 46% 62%, transparent 62%),
-    linear-gradient(135deg, transparent 0 72%, var(--a-fg-subtle) 72% 88%, transparent 88%);
-}
+/* Resize is opt-in via traits="resizable" — the real `resizable` trait owns it
+   entirely (invisible edge handles + a resize-end event). No grabber is drawn; the
+   resize cursor on edge-hover is the affordance. */
 
 /* primary app surface: borderless, fills the frame (or 50% when a panel opens),
    position:relative so it stays the containing block for its OWN sheets (and uses

package/shell/embed-shell/embed-shell.d.ts

@@ -1,5 +1,5 @@
 /**
- * `<embed-shell-ui>` — Embedded multi-surface shell — composes a primary [app] surface with secondary
+ * `<embed-shell>` — Embedded multi-surface shell — composes a primary [app] surface with secondary
 [panel="<name>"] surfaces the consumer provides, arranging them responsively.
 Peer of <admin-shell>. Content-agnostic: it orchestrates whatever [app] +
 [panel] children it is given (it owns layout, not content), so any embedded app

package/shell/embed-shell/embed-shell.js

@@ -25,25 +25,37 @@
  *
  * Layout lives in embed-shell.css: ≥760px the open panel is a 50/50 column; <760px
  * it's a cover sheet (translateY — identity at rest, so popovers inside still anchor).
+ *
+ * Extends UIElement (the shell base) so the declarative trait pattern works:
+ * `<embed-shell traits="resizable">` applies the real `resizable` trait (drag any
+ * edge to resize + a `resize-end` event), not a CSS stand-in. The trait is imported
+ * here so it's registered for declarative lookup.
  */
-class EmbedShell extends HTMLElement {
-  #wired = false;
+import { UIElement } from '../../../web-components/core/element.js';
+import '../../../web-components/traits/resizable/resizable.js'; // register `resizable` for traits="resizable"
+
+class EmbedShell extends UIElement {
+  static template = () => null; // behavior-only, light-DOM — keep the consumer's children
 
-  connectedCallback() {
-    if (this.#wired) return;
-    this.#wired = true;
-    this.addEventListener('click', (e) => {
-      const opener = e.target.closest?.('[opens]');
-      if (opener && this.contains(opener)) { this.toggle(opener.getAttribute('opens')); return; }
-      const closer = e.target.closest?.('[close]');
-      if (closer && this.contains(closer)) this.close();
-    });
-    this.addEventListener('embed:open', (e) => this.toggle(e.detail?.panel));
-    this.addEventListener('keydown', (e) => {
-      if (e.key === 'Escape' && this.panel) { e.stopPropagation(); this.close(); }
-    });
+  connected() {
+    this.addEventListener('click', this.#onClick);
+    this.addEventListener('embed:open', this.#onEmbedOpen);
+    this.addEventListener('keydown', this.#onKeydown);
   }
 
+  // Stable #field arrows — connect/reconnect re-adds are idempotent (the browser
+  // dedups identical listeners), satisfying the trait system's symmetric-lifecycle rule.
+  #onClick = (e) => {
+    const opener = e.target.closest?.('[opens]');
+    if (opener && this.contains(opener)) { this.toggle(opener.getAttribute('opens')); return; }
+    const closer = e.target.closest?.('[close]');
+    if (closer && this.contains(closer)) this.close();
+  };
+  #onEmbedOpen = (e) => this.toggle(e.detail?.panel);
+  #onKeydown = (e) => {
+    if (e.key === 'Escape' && this.panel) { e.stopPropagation(); this.close(); }
+  };
+
   /** the open panel's name, or '' */
   get panel() { return this.getAttribute('panel') || ''; }
 

package/shell/embed-shell/embed-shell.test.js

@@ -0,0 +1,127 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import './embed-shell.js'; // registers <embed-shell>
+
+// A minimal consumer shape: one [app] surface with two [opens] triggers, plus
+// two named [panel] surfaces (one carrying a [close] trigger). The shell owns
+// layout, not content — divs stand in for the real consumer surfaces.
+function mount() {
+  document.body.innerHTML = `
+    <embed-shell>
+      <div app>
+        <button id="open-chat" opens="chat">chat</button>
+        <button id="open-settings" opens="settings">settings</button>
+      </div>
+      <div panel="chat"><button id="close" close>x</button></div>
+      <div panel="settings"></div>
+    </embed-shell>`;
+  return document.body.querySelector('embed-shell');
+}
+
+beforeEach(() => {
+  document.body.innerHTML = '';
+});
+
+// ── open / close / toggle ─────────────────────────────────────────
+describe('embed-shell — open / close / toggle API', () => {
+  it('open(name) reflects [panel] on the shell + sets [active] on the matching surface', () => {
+    const shell = mount();
+    shell.open('chat');
+    expect(shell.getAttribute('panel')).toBe('chat');
+    expect(shell.querySelector('[panel="chat"]').hasAttribute('active')).toBe(true);
+    expect(shell.panel).toBe('chat');
+  });
+
+  it('open(name) switches the active panel — only one [active] at a time', () => {
+    const shell = mount();
+    shell.open('chat');
+    shell.open('settings');
+    expect(shell.getAttribute('panel')).toBe('settings');
+    expect(shell.querySelector('[panel="chat"]').hasAttribute('active')).toBe(false);
+    expect(shell.querySelector('[panel="settings"]').hasAttribute('active')).toBe(true);
+  });
+
+  it('open() with no matching [panel] is a no-op (consumer must provide the surface)', () => {
+    const shell = mount();
+    shell.open('nope');
+    expect(shell.hasAttribute('panel')).toBe(false);
+  });
+
+  it('open() ignores an empty name', () => {
+    const shell = mount();
+    shell.open('');
+    expect(shell.hasAttribute('panel')).toBe(false);
+  });
+
+  it('close() clears [panel] + [active]; .panel reads ""', () => {
+    const shell = mount();
+    shell.open('chat');
+    shell.close();
+    expect(shell.hasAttribute('panel')).toBe(false);
+    expect(shell.querySelector('[panel="chat"]').hasAttribute('active')).toBe(false);
+    expect(shell.panel).toBe('');
+  });
+
+  it('toggle() opens when closed, closes when the same panel is already open', () => {
+    const shell = mount();
+    shell.toggle('chat');
+    expect(shell.panel).toBe('chat');
+    shell.toggle('chat');
+    expect(shell.panel).toBe('');
+  });
+
+  it('emits embed:change with the new panel name on open, "" on close', () => {
+    const shell = mount();
+    const seen = [];
+    shell.addEventListener('embed:change', (e) => seen.push(e.detail.panel));
+    shell.open('chat');
+    shell.close();
+    expect(seen).toEqual(['chat', '']);
+  });
+});
+
+// ── delegated triggers + inbound events ───────────────────────────
+describe('embed-shell — delegated triggers + events', () => {
+  it('[opens] click toggles the named panel', () => {
+    const shell = mount();
+    shell.querySelector('#open-chat').click();
+    expect(shell.panel).toBe('chat');
+    shell.querySelector('#open-chat').click(); // same trigger toggles it back off
+    expect(shell.panel).toBe('');
+  });
+
+  it('[opens] switches directly between panels', () => {
+    const shell = mount();
+    shell.querySelector('#open-chat').click();
+    shell.querySelector('#open-settings').click();
+    expect(shell.panel).toBe('settings');
+  });
+
+  it('[close] click dismisses the open panel', () => {
+    const shell = mount();
+    shell.open('chat');
+    shell.querySelector('#close').click();
+    expect(shell.panel).toBe('');
+  });
+
+  it('embed:open event opens/toggles a panel', () => {
+    const shell = mount();
+    shell.querySelector('[app]').dispatchEvent(
+      new CustomEvent('embed:open', { detail: { panel: 'settings' }, bubbles: true }),
+    );
+    expect(shell.panel).toBe('settings');
+  });
+
+  it('Escape closes the open panel', () => {
+    const shell = mount();
+    shell.open('chat');
+    shell.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+    expect(shell.panel).toBe('');
+  });
+
+  it('Escape is a no-op when no panel is open', () => {
+    const shell = mount();
+    // Should not throw; panel stays closed.
+    shell.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+    expect(shell.panel).toBe('');
+  });
+});

package/simple/simple-shell/simple-shell.d.ts

@@ -1,5 +1,5 @@
 /**
- * `<simple-shell-ui>` — Module-tier minimal shell for marketing / landing / error pages.
+ * `<simple-shell>` — Module-tier minimal shell for marketing / landing / error pages.
 Behavior-only orchestrator with two reflected attributes — [centered]
 for vertical centering, [full-bleed] for dropping the max-width
 constraint.

package/theme/theme-panel/theme-panel.a2ui.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://adiaui.dev/a2ui/v0_9/components/ThemePanel.json",
   "title": "ThemePanel",
-  "description": "Module-tier appearance-preferences control surface. Owns the three knobs\nof the AdiaUI theming contract: [data-theme=<slug>] named themes,\n--a-density / --a-radius-k parametric overrides, and color-scheme\nlight/dark switching, plus optional localStorage persistence behind a\nsmall attribute API.\n\nDrops into any consumer's <popover-ui slot=\"content\"> (the canonical\ncomposition) or directly into a sidebar section. Eight named themes\nship by default; section visibility flips on/off via boolean attributes\n([parametric], [presets], [scheme-toggle]).\n\nPromoted from the duplicated <div id=\"theme-panel\"> block in site/ and\nplaygrounds/admin-shell/ — see docs/specs/theme-panel-module.md.\n",
+  "description": "Module-tier appearance-preferences control surface. Owns the three knobs\nof the AdiaUI theming contract: [theme=<slug>] named themes,\n--a-density / --a-radius-k parametric overrides, and color-scheme\nlight/dark switching, plus optional localStorage persistence behind a\nsmall attribute API.\n\nDrops into any consumer's <popover-ui slot=\"content\"> (the canonical\ncomposition) or directly into a sidebar section. Eight named themes\nship by default; section visibility flips on/off via boolean attributes\n([parametric], [presets], [scheme-toggle]).\n\nPromoted from the duplicated <div id=\"theme-panel\"> block in site/ and\nplaygrounds/admin-shell/ — see docs/specs/theme-panel-module.md.\n",
   "type": "object",
   "allOf": [
     {
@@ -52,7 +52,7 @@
       "default": false
     },
     "presets": {
-      "description": "Renders the compact / reset / spacious preset row. Each preset\napplies a (density, radius) pair; \"default\" also clears the\n[data-theme] attribute.\n",
+      "description": "Renders the compact / reset / spacious preset row. Each preset\napplies a (density, radius) pair; \"default\" also clears the\n[theme] attribute.\n",
       "type": "boolean",
       "default": false
     },
@@ -82,12 +82,12 @@
       "default": "adia-theme-"
     },
     "target": {
-      "description": "CSS selector for the element that receives [data-theme] and\n--a-density / --a-radius-k writes. Defaults to :root (the\n<html> element). Scoped targets are useful for preview-pane\ndemos.\n",
+      "description": "CSS selector for the element that receives [theme] and\n--a-density / --a-radius-k writes. Defaults to :root (the\n<html> element). Scoped targets are useful for preview-pane\ndemos.\n",
       "type": "string",
       "default": ":root"
     },
     "themes": {
-      "description": "Space-separated list of theme slugs to render as buttons. Author\nmay restrict ([themes=\"default ocean\"]) or extend. Tolerant —\nunknown slugs render a button; clicking applies [data-theme=slug]\nregardless of whether themes.css has a matching block.\n",
+      "description": "Space-separated list of theme slugs to render as buttons. Author\nmay restrict ([themes=\"default ocean\"]) or extend. Tolerant —\nunknown slugs render a button; clicking applies [theme=slug]\nregardless of whether themes.css has a matching block.\n",
       "type": "string",
       "default": "default ocean forest sunset lavender rose slate midnight"
     }

package/theme/theme-panel/theme-panel.d.ts

@@ -1,6 +1,6 @@
 /**
- * `<theme-panel-ui>` — Module-tier appearance-preferences control surface. Owns the three knobs
-of the AdiaUI theming contract: [data-theme=<slug>] named themes,
+ * `<theme-panel>` — Module-tier appearance-preferences control surface. Owns the three knobs
+of the AdiaUI theming contract: [theme=<slug>] named themes,
 --a-density / --a-radius-k parametric overrides, and color-scheme
 light/dark switching, plus optional localStorage persistence behind a
 small attribute API.
@@ -47,7 +47,7 @@ docs-shell preferences.
   persist: boolean;
   /** Renders the compact / reset / spacious preset row. Each preset
 applies a (density, radius) pair; "default" also clears the
-[data-theme] attribute.
+[theme] attribute.
  */
   presets: boolean;
   /** Renders a "Scale Context" row (verse / regular / prose) — a
@@ -61,7 +61,7 @@ matchMedia listener; user clicks on the scheme toggle promote to
 an explicit light or dark choice.
  */
   scheme: 'light' | 'dark' | 'auto';
-  /** CSS selector for the element that receives [data-theme] and
+  /** CSS selector for the element that receives [theme] and
 --a-density / --a-radius-k writes. Defaults to :root (the
 <html> element). Scoped targets are useful for preview-pane
 demos.
@@ -69,7 +69,7 @@ demos.
   target: string;
   /** Space-separated list of theme slugs to render as buttons. Author
 may restrict ([themes="default ocean"]) or extend. Tolerant —
-unknown slugs render a button; clicking applies [data-theme=slug]
+unknown slugs render a button; clicking applies [theme=slug]
 regardless of whether themes.css has a matching block.
  */
   themes: string;

package/theme/theme-panel/theme-panel.js

@@ -2,7 +2,7 @@
  * <theme-panel persist parametric presets scheme-toggle>
  *
  * Module-tier appearance-preferences control surface. Owns the three knobs
- * of the AdiaUI theming contract: [data-theme] named themes, --a-density /
+ * of the AdiaUI theming contract: [theme] named themes, --a-density /
  * --a-radius-k parametric overrides, and color-scheme light/dark switching,
  * plus optional localStorage persistence.
  *
@@ -103,13 +103,13 @@ class ThemePanel extends UIElement {
   }
 
   /**
-   * Clear all state on target — remove [data-theme], inline parametric
+   * Clear all state on target — remove [theme], inline parametric
    * overrides, color-scheme, and (if [persist]) localStorage keys.
    * Emits theme-change with source: 'reset'.
    */
   reset() {
     const target = this.#resolveTarget();
-    target.removeAttribute('data-theme');
+    target.removeAttribute('theme');
     target.style.removeProperty('--a-density');
     target.style.removeProperty('--a-radius-k');
     target.style.removeProperty('color-scheme');
@@ -340,10 +340,10 @@ class ThemePanel extends UIElement {
         localStorage.removeItem(`${this.storagePrefix}radius`);
       } catch {}
     }
-    // Apply the theme (which may write [data-theme] on target)
+    // Apply the theme (which may write [theme] on target)
     this.#apply({ theme: slug }, 'theme');
     // Then re-read computed values into sliders on next frame, so the
-    // theme's [data-theme] block has taken effect.
+    // theme's [theme] block has taken effect.
     const sync = () => {
       const cs = getComputedStyle(target);
       const density = parseFloat(cs.getPropertyValue('--a-density')) || 1;
@@ -364,9 +364,9 @@ class ThemePanel extends UIElement {
     const preset = PRESETS[name];
     if (!preset) return;
     if (preset.clearTheme) {
-      // "Reset" preset — clears [data-theme] too
+      // "Reset" preset — clears [theme] too
       const target = this.#resolveTarget();
-      target.removeAttribute('data-theme');
+      target.removeAttribute('theme');
       this.activeTheme = '';
       if (this.persist) {
         try { localStorage.removeItem(`${this.storagePrefix}theme`); } catch {}
@@ -384,10 +384,10 @@ class ThemePanel extends UIElement {
 
     if (partial.theme !== undefined) {
       if (partial.theme === '' || partial.theme === 'default') {
-        target.removeAttribute('data-theme');
+        target.removeAttribute('theme');
         this.activeTheme = '';
       } else {
-        target.setAttribute('data-theme', partial.theme);
+        target.setAttribute('theme', partial.theme);
         this.activeTheme = partial.theme;
       }
       if (this.persist) {
@@ -485,10 +485,10 @@ class ThemePanel extends UIElement {
 
     // Apply theme
     if (theme) {
-      target.setAttribute('data-theme', theme);
+      target.setAttribute('theme', theme);
       this.activeTheme = theme;
     } else {
-      this.activeTheme = target.getAttribute('data-theme') || '';
+      this.activeTheme = target.getAttribute('theme') || '';
     }
 
     // Apply scheme

package/theme/theme-panel/theme-panel.test.js

@@ -46,7 +46,7 @@ beforeEach(() => {
 
 afterEach(() => {
   // Always clean any html-level inline state so tests don't leak
-  document.documentElement.removeAttribute('data-theme');
+  document.documentElement.removeAttribute('theme');
   document.documentElement.style.removeProperty('--a-density');
   document.documentElement.style.removeProperty('--a-radius-k');
   document.documentElement.style.removeProperty('color-scheme');
@@ -96,24 +96,24 @@ describe('theme-panel', () => {
     expect(tp.querySelector('[part="scheme"] segmented-ui')).toBeTruthy();
   });
 
-  it('theme button click sets [data-theme] on the target (defaults to <html>)', async () => {
+  it('theme button click sets [theme] on the target (defaults to <html>)', async () => {
     const tp = mount('<theme-panel></theme-panel>');
     await tick();
     const oceanBtn = tp.querySelector('button-ui[data-theme-slug="ocean"]');
     oceanBtn.dispatchEvent(new Event('click', { bubbles: true }));
     await tick();
-    expect(document.documentElement.getAttribute('data-theme')).toBe('ocean');
+    expect(document.documentElement.getAttribute('theme')).toBe('ocean');
     expect(tp.getAttribute('active-theme')).toBe('ocean');
   });
 
-  it('theme button click for "default" clears [data-theme]', async () => {
-    document.documentElement.setAttribute('data-theme', 'ocean');
+  it('theme button click for "default" clears [theme]', async () => {
+    document.documentElement.setAttribute('theme', 'ocean');
     const tp = mount('<theme-panel></theme-panel>');
     await tick();
     const defaultBtn = tp.querySelector('button-ui[data-theme-slug="default"]');
     defaultBtn.dispatchEvent(new Event('click', { bubbles: true }));
     await tick();
-    expect(document.documentElement.hasAttribute('data-theme')).toBe(false);
+    expect(document.documentElement.hasAttribute('theme')).toBe(false);
     expect(tp.getAttribute('active-theme')).toBe('');
   });
 
@@ -166,14 +166,14 @@ describe('theme-panel', () => {
     expect(document.documentElement.style.getPropertyValue('--a-radius-k')).toBe('1.25');
   });
 
-  it('preset "default" (Reset) clears [data-theme]', async () => {
-    document.documentElement.setAttribute('data-theme', 'ocean');
+  it('preset "default" (Reset) clears [theme]', async () => {
+    document.documentElement.setAttribute('theme', 'ocean');
     const tp = mount('<theme-panel parametric presets></theme-panel>');
     await tick();
     const reset = tp.querySelector('button-ui[data-preset="default"]');
     reset.dispatchEvent(new Event('click', { bubbles: true }));
     await tick();
-    expect(document.documentElement.hasAttribute('data-theme')).toBe(false);
+    expect(document.documentElement.hasAttribute('theme')).toBe(false);
   });
 
   it('[persist] writes localStorage keys on theme click', async () => {
@@ -193,7 +193,7 @@ describe('theme-panel', () => {
   });
 
   it('reset() clears all state and emits source: "reset"', async () => {
-    document.documentElement.setAttribute('data-theme', 'ocean');
+    document.documentElement.setAttribute('theme', 'ocean');
     document.documentElement.style.setProperty('--a-density', '1.2');
     const tp = mount('<theme-panel parametric persist></theme-panel>');
     await tick();
@@ -201,7 +201,7 @@ describe('theme-panel', () => {
     tp.addEventListener('theme-change', onChange);
     tp.reset();
     await tick();
-    expect(document.documentElement.hasAttribute('data-theme')).toBe(false);
+    expect(document.documentElement.hasAttribute('theme')).toBe(false);
     expect(document.documentElement.style.getPropertyValue('--a-density')).toBe('');
     expect(onChange).toHaveBeenCalled();
     expect(onChange.mock.calls[0][0].detail.source).toBe('reset');
@@ -223,7 +223,7 @@ describe('theme-panel', () => {
     tp.addEventListener('theme-change', onChange);
     tp.apply({ theme: 'slate' });
     await tick();
-    expect(document.documentElement.getAttribute('data-theme')).toBe('slate');
+    expect(document.documentElement.getAttribute('theme')).toBe('slate');
     expect(onChange.mock.calls[0][0].detail.source).toBe('programmatic');
   });
 
@@ -251,8 +251,8 @@ describe('theme-panel', () => {
     await tick();
     tp.querySelector('button-ui[data-theme-slug="ocean"]').dispatchEvent(new Event('click', { bubbles: true }));
     await tick();
-    expect(preview.getAttribute('data-theme')).toBe('ocean');
-    expect(document.documentElement.getAttribute('data-theme')).toBeNull();
+    expect(preview.getAttribute('theme')).toBe('ocean');
+    expect(document.documentElement.getAttribute('theme')).toBeNull();
   });
 
   it('cleans up listeners on disconnect (no zombie listeners)', async () => {

package/theme/theme-panel/theme-panel.yaml

@@ -8,7 +8,7 @@ category: layout
 version: 1
 description: |
   Module-tier appearance-preferences control surface. Owns the three knobs
-  of the AdiaUI theming contract: [data-theme=<slug>] named themes,
+  of the AdiaUI theming contract: [theme=<slug>] named themes,
   --a-density / --a-radius-k parametric overrides, and color-scheme
   light/dark switching, plus optional localStorage persistence behind a
   small attribute API.
@@ -36,7 +36,7 @@ props:
     description: |
       Space-separated list of theme slugs to render as buttons. Author
       may restrict ([themes="default ocean"]) or extend. Tolerant —
-      unknown slugs render a button; clicking applies [data-theme=slug]
+      unknown slugs render a button; clicking applies [theme=slug]
       regardless of whether themes.css has a matching block.
     type: string
     default: "default ocean forest sunset lavender rose slate midnight"
@@ -54,7 +54,7 @@ props:
     description: |
       Renders the compact / reset / spacious preset row. Each preset
       applies a (density, radius) pair; "default" also clears the
-      [data-theme] attribute.
+      [theme] attribute.
     type: boolean
     default: false
     reflect: true
@@ -100,7 +100,7 @@ props:
 
   target:
     description: |
-      CSS selector for the element that receives [data-theme] and
+      CSS selector for the element that receives [theme] and
       --a-density / --a-radius-k writes. Defaults to :root (the
       <html> element). Scoped targets are useful for preview-pane
       demos.