@adia-ai/web-modules 0.4.6 → 0.4.8

package/editor/editor-sidebar/editor-sidebar.d.ts

@@ -0,0 +1,53 @@
+/**
+ * `<editor-sidebar-ui>` — Module-tier editor-cluster sidebar — wraps <pane-ui resizable>
+(the primitive that owns drag) and adds [collapsed] reflected
+state, localStorage persistence (adia-editor-sidebar-{name}),
+and .toggle() / .collapse() / .expand() public API.
+
+Sits inside <editor-shell> as slot="leading" (navigator pane) or
+slot="trailing" (inspector pane). Mirrors the cluster-namespace
+shape from <admin-sidebar> and <chat-sidebar>, but DELEGATES to
+<pane-ui> for resize rather than reimplementing it (per
+bespoke-shell-children skill §When NOT to promote — pane primitive
+already owns this concern).
+
+This is the FIRST bespoke shell child that delegates rather than
+duplicates a primitive's behavior. Pattern is: cluster-namespace +
+state-as-attribute + persistence at the bespoke tier; physical
+drag at the primitive tier.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/editor-sidebar
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../../web-components/core/element.js';
+
+export interface EditorSidebarSidebarToggleEventDetail {
+  expanded: string;
+  name: string;
+}
+
+export type EditorSidebarSidebarToggleEvent = CustomEvent<EditorSidebarSidebarToggleEventDetail>;
+
+export class UIEditorSidebar extends UIElement {
+  /** Reflected — set when inner <pane-ui> width is at or below 96px snap threshold. */
+  collapsed: boolean;
+  /** Reflected — set during an active pointer-drag of the pane's
+resize handle. Used to disable transitions and visual treatments
+that would feel laggy during drag.
+ */
+  resizing: boolean;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIEditorSidebar, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'sidebar-toggle', listener: (ev: EditorSidebarSidebarToggleEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/editor/editor-statusbar/editor-statusbar.a2ui.json

@@ -24,6 +24,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [],
     "events": {},
     "examples": [],
     "keywords": [

package/editor/editor-toolbar/editor-toolbar.a2ui.json

@@ -29,6 +29,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [],
     "events": {
       "toolbar-action": {
         "description": "Bubbles when a child element with [data-toolbar-action] is clicked. Detail carries the action name from the clicked element's attribute.",

package/editor/editor-toolbar/editor-toolbar.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `<editor-toolbar-ui>` — Module-tier editor toolbar — replaces legacy <header> chrome bar
+inside <editor-shell> per ADR-0023. Owns the [full-screen] reflected
+attribute (set when host enters focus mode), click-bubble for
+[data-toolbar-action] buttons, and slot vocabulary routing.
+
+Sits at the top of <editor-shell>. Authors compose actions + status
+via slot vocabulary. The host (<editor-shell>) reads either
+<editor-toolbar> or <header> via :is() selector for backwards compat.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/editor-toolbar
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../../web-components/core/element.js';
+
+export interface EditorToolbarToolbarActionEventDetail {
+  name: string;
+}
+
+export type EditorToolbarToolbarActionEvent = CustomEvent<EditorToolbarToolbarActionEventDetail>;
+
+export class UIEditorToolbar extends UIElement {
+  /** Reflected — set when editor is in distraction-free / focus mode. */
+  fullScreen: boolean;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIEditorToolbar, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'toolbar-action', listener: (ev: EditorToolbarToolbarActionEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adia-ai/web-modules",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "description": "AdiaUI composite custom elements — shell, chat, editor, runtime clusters built from @adia-ai/web-components primitives. Subpath exports per cluster.",
   "type": "module",
   "exports": {

package/runtime/a2ui-root/a2ui-root.a2ui.json

@@ -60,6 +60,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "container",
+    "composes": [],
     "events": {
       "a2ui-action": {
         "description": "Fired when a child element with [data-action] is clicked. detail: { name, sourceComponentId, context }"

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

@@ -0,0 +1,47 @@
+/**
+ * `<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.
+ *
+ * @see https://ui-kit.exe.xyz/site/components/a2ui-root
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../../web-components/core/element.js';
+
+export type A2UIRootA2uiActionEvent = CustomEvent<unknown>;
+export type A2UIRootA2uiClosedEvent = CustomEvent<unknown>;
+export type A2UIRootA2uiConnectedEvent = CustomEvent<unknown>;
+export type A2UIRootA2uiErrorEvent = CustomEvent<unknown>;
+export type A2UIRootA2uiMessageEvent = CustomEvent<unknown>;
+export type A2UIRootDocReplacedEvent = CustomEvent<unknown>;
+
+export class UIA2UIRoot extends UIElement {
+  /** True while the stream is connected and receiving messages. */
+  active: boolean;
+  /** Batch renderer updates via requestAnimationFrame for large fan-in. */
+  batch: boolean;
+  /** Author-driven mode — set to an array of A2UI messages and the renderer resets + replays them. No network/transport involvement. Setting to a new array triggers a full re-render. Use this for editors, previews, tests, and any static-doc authoring loop. When both `src` and `doc` are set, `doc` wins (the stream is not opened). Pass as a JS property; not reflected to an attribute. */
+  doc: unknown[];
+  /** True while the stream is connecting. */
+  loading: boolean;
+  /** Stream source URL (endpoint for SSE/WebSocket, file path for JSONL, tool-call target for MCP). */
+  src: string;
+  /** Stream transport to use. */
+  transport: 'sse' | 'ws' | 'websocket' | 'jsonl' | 'mcp';
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIA2UIRoot, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'a2ui-action', listener: (ev: A2UIRootA2uiActionEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'a2ui-closed', listener: (ev: A2UIRootA2uiClosedEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'a2ui-connected', listener: (ev: A2UIRootA2uiConnectedEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'a2ui-error', listener: (ev: A2UIRootA2uiErrorEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'a2ui-message', listener: (ev: A2UIRootA2uiMessageEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'doc-replaced', listener: (ev: A2UIRootDocReplacedEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/runtime/gen-root/gen-root.a2ui.json

@@ -39,6 +39,11 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [
+      "chat-thread-ui",
+      "canvas-ui",
+      "inspector-ui"
+    ],
     "events": {},
     "examples": [],
     "keywords": [

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

@@ -0,0 +1,23 @@
+/**
+ * `<gen-root-ui>` — 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.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/gen-root
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../../web-components/core/element.js';
+
+export class UIGenRoot extends UIElement {
+  /** Show the inspector pane (for debugging generated A2UI). */
+  inspector: boolean;
+  /** Layout mode — chat-only, 50/50 split, or canvas-only. */
+  mode: 'chat' | 'split' | 'canvas';
+}

package/runtime/gen-root/gen-root.yaml

@@ -9,6 +9,12 @@ description: |
   (chat-only / split / canvas-only) and delegates a unified API across
   child chat-ui, canvas-ui, and inspector-ui elements.
 
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - chat-thread-ui
+  - canvas-ui
+  - inspector-ui
 props:
   mode:
     type: string

package/shell/admin-command/admin-command.a2ui.json

@@ -44,6 +44,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "interaction",
+    "composes": [],
     "events": {
       "command-select": {
         "description": "Forwarded from the inner <command-ui> when an option is chosen. Detail mirrors the inner event's detail.",

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

@@ -0,0 +1,50 @@
+/**
+ * `<admin-command-ui>` — 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].
+
+Sits inside <admin-shell> as a direct child. The host wires
+[data-command-trigger] elements to <admin-command>.show() via lookup.
+
+This is the bespoke web-component replacement for the legacy
+<dialog data-command> shape. <admin-shell> still recognizes the
+legacy shape via :is() selector. New code should prefer <admin-command>.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/admin-command
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../../web-components/core/element.js';
+
+export interface AdminCommandCommandSelectEventDetail {
+  value: string;
+}
+
+export type AdminCommandCommandSelectEvent = CustomEvent<AdminCommandCommandSelectEventDetail>;
+
+export class UIAdminCommand extends UIElement {
+  /** Reflected — set while the dialog is showing. Synced with both
+programmatic .show()/.hide() and native dialog close events
+(esc key, backdrop click).
+ */
+  open: boolean;
+  /** Keyboard shortcut binding. "cmd+k" responds only on Mac
+(metaKey); "ctrl+k" responds only when ctrlKey; "both" (default)
+responds to either, which is the canonical AdiaUI behavior for
+cross-platform Cmd+K affordance.
+ */
+  shortcut: 'both' | 'cmd+k' | 'ctrl+k';
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIAdminCommand, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'command-select', listener: (ev: AdminCommandCommandSelectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/shell/admin-content/admin-content.a2ui.json

@@ -24,6 +24,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [],
     "events": {},
     "examples": [],
     "keywords": [

package/shell/admin-page/admin-page.a2ui.json

@@ -24,6 +24,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [],
     "events": {},
     "examples": [],
     "keywords": [

package/shell/admin-page-body/admin-page-body.a2ui.json

@@ -24,6 +24,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [],
     "events": {},
     "examples": [],
     "keywords": [

package/shell/admin-page-header/admin-page-header.a2ui.json

@@ -24,6 +24,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [],
     "events": {},
     "examples": [],
     "keywords": [

package/shell/admin-scroll/admin-scroll.a2ui.json

@@ -24,6 +24,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [],
     "events": {},
     "examples": [],
     "keywords": [

package/shell/admin-shell/admin-shell.a2ui.json

@@ -34,6 +34,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [],
     "events": {
       "command-select": {
         "description": "Forwarded from the command palette when an option is chosen.",

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

@@ -0,0 +1,49 @@
+/**
+ * `<admin-shell-ui>` — Behavior-only application shell. Wires sidebar toggles, resize handles,
+a Cmd+K command palette, and a ResizeObserver that drives responsive
+sidebar collapse. Author supplies the DOM (aside[data-sidebar], main,
+dialog[data-command]); admin-shell binds the interactions.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/admin-shell
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../../web-components/core/element.js';
+
+export interface AppShellCommandSelectEventDetail {
+  value: string;
+}
+
+export type AppShellCommandSelectEvent = CustomEvent<AppShellCommandSelectEventDetail>;
+export interface AppShellSidebarResizeEventDetail {
+  sidebar: string;
+  width: string;
+}
+
+export type AppShellSidebarResizeEvent = CustomEvent<AppShellSidebarResizeEventDetail>;
+export interface AppShellSidebarToggleEventDetail {
+  expanded: string;
+  sidebar: string;
+}
+
+export type AppShellSidebarToggleEvent = CustomEvent<AppShellSidebarToggleEventDetail>;
+
+export class UIAppShell extends UIElement {
+  /** Layout variant — default is bordered surface; rounded softens edges; borderless removes the outer chrome. */
+  mode: '' | 'rounded' | 'borderless';
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIAppShell, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'command-select', listener: (ev: AppShellCommandSelectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'sidebar-resize', listener: (ev: AppShellSidebarResizeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'sidebar-toggle', listener: (ev: AppShellSidebarToggleEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/shell/admin-sidebar/admin-sidebar.a2ui.json

@@ -54,6 +54,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [],
     "events": {
       "sidebar-resize": {
         "description": "Bubbles when an active pointer-drag releases.",

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

@@ -0,0 +1,68 @@
+/**
+ * `<admin-sidebar-ui>` — 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.
+
+This is the bespoke web-component replacement for the legacy
+<aside data-sidebar> shape. <admin-shell> still recognizes the legacy
+shape via :is() selector for backwards compat. New code should prefer
+<admin-sidebar>.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/admin-sidebar
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../../web-components/core/element.js';
+
+export interface AdminSidebarSidebarResizeEventDetail {
+  name: string;
+  width: string;
+}
+
+export type AdminSidebarSidebarResizeEvent = CustomEvent<AdminSidebarSidebarResizeEventDetail>;
+export interface AdminSidebarSidebarToggleEventDetail {
+  expanded: string;
+  name: string;
+}
+
+export type AdminSidebarSidebarToggleEvent = CustomEvent<AdminSidebarSidebarToggleEventDetail>;
+
+export class UIAdminSidebar extends UIElement {
+  /** Reflected — set when the sidebar's measured width is at or below
+96px. Consumers query this to style "collapsed mode" without
+duplicating threshold math.
+ */
+  collapsed: boolean;
+  /** Opts in to programmatic collapse — toggle button wiring + the
+.toggle() / .collapse() / .expand() public methods.
+ */
+  collapsible: boolean;
+  /** Identifier for localStorage namespacing. Defaults to slot value
+("leading" or "trailing"). Override when running multiple sidebars
+with the same slot.
+ */
+  name: string;
+  /** Opts in to drag-to-resize behavior. Author supplies a child
+[data-resize] element as the drag handle.
+ */
+  resizable: boolean;
+  /** Reflected — set during an active pointer-drag on the resize handle.
+Useful for suppressing transitions while dragging.
+ */
+  resizing: boolean;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIAdminSidebar, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'sidebar-resize', listener: (ev: AdminSidebarSidebarResizeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'sidebar-toggle', listener: (ev: AdminSidebarSidebarToggleEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/shell/admin-statusbar/admin-statusbar.a2ui.json

@@ -24,6 +24,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [],
     "events": {},
     "examples": [],
     "keywords": [

package/shell/admin-topbar/admin-topbar.a2ui.json

@@ -24,6 +24,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [],
     "events": {},
     "examples": [],
     "keywords": [

package/simple/simple-content/simple-content.a2ui.json

@@ -24,6 +24,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "shells",
+    "composes": [],
     "events": {},
     "examples": [],
     "keywords": [

package/simple/simple-hero/simple-hero.a2ui.json

@@ -24,6 +24,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "shells",
+    "composes": [],
     "events": {},
     "examples": [],
     "keywords": [

package/simple/simple-shell/simple-shell.a2ui.json

@@ -34,6 +34,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "shells",
+    "composes": [],
     "events": {},
     "examples": [],
     "keywords": [

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

@@ -0,0 +1,29 @@
+/**
+ * `<simple-shell-ui>` — 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.
+
+The 4th cluster in the bespoke shell family per ADR-0023, designed
+deliberately small (1 host + 2 CSS-only children) to demonstrate
+the pattern works without ceremony for thin clusters.
+
+Use cases: marketing splashes, error pages (404 / 500 / maintenance),
+thank-you pages, single-card flows (sign-in, password reset).
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/simple-shell
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../../web-components/core/element.js';
+
+export class UISimpleShell extends UIElement {
+  /** Reflected — vertically centers content in viewport. */
+  centered: boolean;
+}

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

@@ -89,6 +89,15 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [
+      "segmented-ui",
+      "segment-ui",
+      "text-ui",
+      "button-ui",
+      "divider-ui",
+      "field-ui",
+      "slider-ui"
+    ],
     "events": {
       "theme-change": {
         "description": "Bubbles when any user-visible state changes (theme click, slider\ninput, preset click, scheme flip, reset). One event per change.\nNo event on auto-rehydrate-from-storage at boot.\n",

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

@@ -0,0 +1,77 @@
+/**
+ * `<theme-panel-ui>` — Module-tier appearance-preferences control surface. Owns the three knobs
+of the AdiaUI theming contract: [data-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.
+
+Drops into any consumer's <popover-ui slot="content"> (the canonical
+composition) or directly into a sidebar section. Eight named themes
+ship by default; section visibility flips on/off via boolean attributes
+([parametric], [presets], [scheme-toggle]).
+
+Promoted from the duplicated <div id="theme-panel"> block in site/ and
+playgrounds/admin-shell/ — see docs/specs/theme-panel-module.md.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/theme-panel
+ *
+ * Type declarations generated by scripts/build/dts-codegen.mjs from
+ * the component's `.a2ui.json` sidecar. Edit the source `.yaml`,
+ * run `npm run build:components`, then `npm run codegen:dts` to
+ * regenerate; or hand-author this file fully if rich event types are
+ * needed beyond what the yaml `events:` block can express.
+ */
+
+import { UIElement } from '../../../web-components/core/element.js';
+
+export interface ThemePanelThemeChangeEventDetail {
+  theme: string;
+  density: string;
+  radius: string;
+  scheme: string;
+  source: string;
+}
+
+export type ThemePanelThemeChangeEvent = CustomEvent<ThemePanelThemeChangeEventDetail>;
+
+export class UIThemePanel extends UIElement {
+  /** Renders the density + radius slider block. Sliders bind to
+--a-density and --a-radius-k on the target element.
+ */
+  parametric: boolean;
+  /** Persists selections to localStorage. Defaults to ephemeral so
+playgrounds and embedded demos do not silently mutate a user's
+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.
+ */
+  presets: boolean;
+  /** Initial color-scheme. "auto" follows prefers-color-scheme via a
+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
+--a-density / --a-radius-k writes. Defaults to :root (the
+<html> element). Scoped targets are useful for preview-pane
+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]
+regardless of whether themes.css has a matching block.
+ */
+  themes: string;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIThemePanel, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'theme-change', listener: (ev: ThemePanelThemeChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}