@adia-ai/web-modules 0.4.7 → 0.4.9

package/CHANGELOG.md

@@ -11,6 +11,91 @@ Built from `@adia-ai/web-components` primitives.
 
 _No pending changes._
 
+## [0.4.9] - 2026-05-13
+
+### Added — `<editor-sidebar>` `[persist]` attribute (§91c, FEEDBACK-04 #6)
+
+Closes FEEDBACK-04 claim #6 discoverability gap. `<editor-sidebar>` has persisted pane width to `localStorage` since the module shipped, keyed by `[name]` (with `[slot]` fallback). The consumer's mental model expected `[persist="dts-layout"]` — that attribute name better describes what the surface does. v0.4.9 adds `[persist]` as the preferred attribute:
+
+```html
+<!-- Preferred (v0.4.9+) -->
+<editor-sidebar slot="leading" collapsible persist="dts-layout">
+  <pane-ui resizable>...</pane-ui>
+</editor-sidebar>
+
+<!-- Back-compat (v0.4.x) — still works -->
+<editor-sidebar slot="leading" collapsible name="dts-layout">
+  <pane-ui resizable>...</pane-ui>
+</editor-sidebar>
+```
+
+Both map to the same `localStorage["adia-editor-sidebar-dts-layout"]` namespace. Precedence is `[persist]` > `[name]` > `[slot]` — if both `[persist]` and `[name]` are set, `[persist]` wins (more descriptive attribute beats the legacy alias). The `sidebar-toggle` event's `detail.name` reflects the chosen key.
+
+`[name]` is now documented as deprecated; not scheduled for removal in v0.5.x.
+
+**Migration:**
+
+```diff
+- <editor-sidebar collapsible name="dts-layout">
++ <editor-sidebar collapsible persist="dts-layout">
+```
+
+### Added — `isFocusInInput()` utility on `@adia-ai/web-modules/editor` (§90, FEEDBACK-04 P2 #5)
+
+`FEEDBACK-04--adia-ui--2026-05-13.md` item #5: consumer building global keyboard shortcuts for an editor app hit the TypeScript ergonomics gap on `document.activeElement.isContentEditable` (the `Element` type doesn't have `isContentEditable`; only `HTMLElement` does). Every consumer reimplements the cast boilerplate.
+
+Ships `isFocusInInput()` as a small helper:
+
+```ts
+import { isFocusInInput } from '@adia-ai/web-modules/editor';
+
+document.addEventListener('keydown', (e) => {
+  if (isFocusInInput()) return;  // user is typing — don't fire shortcut
+  if (e.key === '/') openCommandPalette();
+});
+```
+
+Returns `true` when focus is inside `<input>` / `<textarea>` / any `contenteditable` host / or an AdiaUI text-input primitive (`<input-ui>`, `<textarea-ui>`, `<otp-input-ui>`, `<search-ui>`). The AdiaUI tag-name checks catch focus that lands on the host element (not just the inner native input).
+
+**Files:**
+- NEW `packages/web-modules/editor/utils.js` — implementation
+- NEW `packages/web-modules/editor/utils.d.ts` — types
+- NEW `packages/web-modules/editor/index.d.ts` — barrel re-export of the editor module types incl. `isFocusInInput`
+- `packages/web-modules/editor/index.js` — re-export
+- `packages/web-modules/package.json` — `./editor` exports gains `types` conditional; new explicit `./editor/utils` entry for direct subpath import
+
+Two reachable import paths:
+- `import { isFocusInInput } from '@adia-ai/web-modules/editor';` (via barrel)
+- `import { isFocusInInput } from '@adia-ai/web-modules/editor/utils';` (direct subpath)
+
+Both carry types via the new `types` conditionals.
+
+## [0.4.8] - 2026-05-12
+
+### Added — TypeScript declarations for all web-modules (FEEDBACK-02 #1, v0.4.8)
+
+Closes consumer-friction item #1 from FEEDBACK-adia-packages-02. Hand-codegen'd `.d.ts` declarations now ship for every web-module across all clusters:
+
+- **chat** (6): `chat-composer`, `chat-shell`, `chat-sidebar`, `chat-thread` + supporting types.
+- **editor** (5): `editor-canvas`, `editor-shell`, `editor-sidebar`, `editor-toolbar` + supporting types.
+- **runtime** (2): `a2ui-root`, `gen-root`.
+- **admin shell** (10): admin-command, admin-content, admin-page, admin-page-{body,header}, admin-scroll, admin-shell, admin-sidebar, admin-statusbar, admin-topbar.
+- **simple** + **theme** clusters: companion `.d.ts` files for the remaining modules.
+
+TypeScript consumers now get typed `document.querySelector('admin-shell')` returns `AdminShell`, typed reflected properties, typed methods (`.toggle()`, `.collapse()`, etc.), and typed custom events. `HTMLElementTagNameMap` augmentation in the package barrel makes the tag-name lookups type-aware. Mirrors the `@adia-ai/web-components@0.4.7` §74 codegen pattern.
+
+### Added — `composes:` field on YAMLs + `.a2ui.json` regen (ADR-0027 wiring, v0.4.8)
+
+Each web-module YAML now declares a `composes:` field listing the `@adia-ai/web-components` primitives it instantiates internally. ADR-0027 (cross-primitive composition imports are consumer's responsibility) becomes mechanically auditable — the `composes:` linter ships in this release and runs as part of `npm run components`. `.a2ui.json` sidecars regenerated to surface the `composes:` data through the v0.9 catalog.
+
+`chat-shell.yaml` + `gen-root.yaml` documented the LLM-pipeline wiring expectations alongside the composes declarations.
+
+### Documentation — lexical-scope authoring guide
+
+`README.md` § Module authoring updated with the `composes:` field semantics + lexical-scope rationale (why composes-declared imports must live at the consumer page, not transitively pulled by the module). Aligns with §66's `adaptV09Component()` catalog reader work.
+
+See root [CHANGELOG.md `[Unreleased]`](../../CHANGELOG.md) for the cross-cutting arc narrative.
+
 ## [0.4.7] - 2026-05-12
 
 ### Changed — `chat/chat-thread.yaml` populates `synonyms.tags` (§72)

package/chat/chat-composer/chat-composer.a2ui.json

@@ -29,6 +29,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "input",
+    "composes": [],
     "events": {
       "composer-submit": {
         "description": "Bubbles when the inner input fires its 'submit' event. Detail mirrors the inner event's detail (typically text + model).",

package/chat/chat-composer/chat-composer.d.ts

@@ -0,0 +1,47 @@
+/**
+ * `<chat-composer-ui>` — Module-tier chat composer wrapper — replaces legacy <chat-input-ui
+data-chat-input> direct child of <chat-shell> per ADR-0023.
+Forwards submit events as 'composer-submit', propagates [disabled]
+to the inner input, provides slot vocabulary for future composer
+surfaces (file attach, autocomplete, model picker).
+
+Sits inside <chat-shell> as the input region (typically inside or
+alongside the footer). Authors place an inner <chat-input-ui>
+(or input-ui / textarea-ui) as the primary input.
+
+Backwards compat — <chat-shell> still recognizes the legacy
+<chat-input-ui data-chat-input> shape via :is() selector. New
+code should prefer <chat-composer>.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/chat-composer
+ *
+ * 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 ChatComposerComposerSubmitEventDetail {
+  model: string;
+  text: string;
+}
+
+export type ChatComposerComposerSubmitEvent = CustomEvent<ChatComposerComposerSubmitEventDetail>;
+
+export class UIChatComposer extends UIElement {
+  /** Reflected — set by the host while streaming, or by application
+code. Propagated to the inner input element automatically.
+ */
+  disabled: boolean;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIChatComposer, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'composer-submit', listener: (ev: ChatComposerComposerSubmitEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/chat/chat-empty/chat-empty.a2ui.json

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

package/chat/chat-header/chat-header.a2ui.json

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

package/chat/chat-shell/chat-shell.a2ui.json

@@ -54,6 +54,9 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "container",
+    "composes": [
+      "code-ui"
+    ],
     "events": {
       "abort": {
         "description": "Fired when the user aborts an in-flight request."

package/chat/chat-shell/chat-shell.d.ts

@@ -0,0 +1,86 @@
+/**
+ * `<chat-shell-ui>` — Behavior-only chat orchestrator (LLM-streaming module). Author supplies the
+DOM structure via [data-chat-messages], [data-chat-input], [data-chat-empty],
+[data-chat-status] elements; chat-shell wires message streaming, markdown
+rendering, code-block upgrades, and an LLM integration path via proxy-url
+(or via external submit).
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/chat-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 type ChatShellAbortEvent = CustomEvent<unknown>;
+export interface ChatShellChunkEventDetail {
+  snapshot: string;
+  text: string;
+}
+
+export type ChatShellChunkEvent = CustomEvent<ChatShellChunkEventDetail>;
+export type ChatShellClearEvent = CustomEvent<unknown>;
+export interface ChatShellDoneEventDetail {
+  stopReason: string;
+  text: string;
+  usage: string;
+}
+
+export type ChatShellDoneEvent = CustomEvent<ChatShellDoneEventDetail>;
+export interface ChatShellErrorEventDetail {
+  error: string;
+}
+
+export type ChatShellErrorEvent = CustomEvent<ChatShellErrorEventDetail>;
+export interface ChatShellMessageEventDetail {
+  content: string;
+  id: string;
+  role: string;
+}
+
+export type ChatShellMessageEvent = CustomEvent<ChatShellMessageEventDetail>;
+export interface ChatShellSubmitEventDetail {
+  model: string;
+  text: string;
+}
+
+export type ChatShellSubmitEvent = CustomEvent<ChatShellSubmitEventDetail>;
+export interface ChatShellThinkingEventDetail {
+  text: string;
+}
+
+export type ChatShellThinkingEvent = CustomEvent<ChatShellThinkingEventDetail>;
+
+export class UIChatShell extends UIElement {
+  /** Model identifier. */
+  model: string;
+  /** LLM provider name (anthropic | openai | google | stub). */
+  provider: string;
+  /** API proxy endpoint for LLM calls; enables self-contained chat without external wiring. */
+  proxyUrl: string;
+  /** Active streaming indicator; toggled while a response is being received. */
+  streaming: boolean;
+  /** System prompt prepended to conversations. */
+  system: string;
+  /** Enable Anthropic extended-thinking mode. */
+  thinking: boolean;
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UIChatShell, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'abort', listener: (ev: ChatShellAbortEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'chunk', listener: (ev: ChatShellChunkEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'clear', listener: (ev: ChatShellClearEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'done', listener: (ev: ChatShellDoneEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'error', listener: (ev: ChatShellErrorEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'message', listener: (ev: ChatShellMessageEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'submit', listener: (ev: ChatShellSubmitEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'thinking', listener: (ev: ChatShellThinkingEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/chat/chat-shell/chat-shell.yaml

@@ -11,6 +11,10 @@ description: |
   rendering, code-block upgrades, and an LLM integration path via proxy-url
   (or via external submit).
 
+# Per ADR-0027 — primitives that programmatically create other primitives
+# do NOT auto-import them. Consumer (or demo shell) must explicitly import.
+composes:
+  - code-ui
 props:
   streaming:
     type: boolean

package/chat/chat-sidebar/chat-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/chat/chat-sidebar/chat-sidebar.d.ts

@@ -0,0 +1,70 @@
+/**
+ * `<chat-sidebar-ui>` — Module-tier chat-cluster sidebar — owns resize, snap-to-collapsed,
+persistence, and the [collapsed] reflected attribute. Sits inside
+<chat-shell> as slot="leading" (conversation history rail) or
+slot="trailing" (artifacts/citations panel). Mirrors the admin-sidebar
+shape — same 4 concerns, cluster-namespaced for the chat family.
+
+This is the chat-cluster equivalent of <admin-sidebar> per ADR-0023.
+<chat-shell> doesn't currently have a legacy sidebar shape (chat is
+typically a single-pane experience), so <chat-sidebar> is purely
+forward-looking — for chat apps that want conversation-history or
+inspector rails.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/chat-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 ChatSidebarSidebarResizeEventDetail {
+  name: string;
+  width: string;
+}
+
+export type ChatSidebarSidebarResizeEvent = CustomEvent<ChatSidebarSidebarResizeEventDetail>;
+export interface ChatSidebarSidebarToggleEventDetail {
+  expanded: string;
+  name: string;
+}
+
+export type ChatSidebarSidebarToggleEvent = CustomEvent<ChatSidebarSidebarToggleEventDetail>;
+
+export class UIChatSidebar 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: UIChatSidebar, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'sidebar-resize', listener: (ev: ChatSidebarSidebarResizeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'sidebar-toggle', listener: (ev: ChatSidebarSidebarToggleEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+}

package/chat/chat-status/chat-status.a2ui.json

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

package/chat/chat-thread/chat-thread.a2ui.json

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

package/chat/chat-thread/chat-thread.d.ts

@@ -0,0 +1,38 @@
+/**
+ * `<chat-thread-ui>` — Module-tier chat message thread container — replaces legacy
+<section data-chat-messages> per ADR-0023. Owns scroll-to-bottom
+on new message (with user-scroll-up suspension), [streaming] and
+[empty] reflected attributes, and a stable target for the host's
+message rendering pipeline.
+
+Sits inside <chat-shell> as the central scroll surface. Authors
+compose <chat-empty> as an optional first child for the empty
+state; message children are appended dynamically by the host.
+
+Backwards compat — <chat-shell> still recognizes the legacy
+<section data-chat-messages> shape via :is() selector. New code
+should prefer <chat-thread>.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/chat-thread
+ *
+ * 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 UIChatThread extends UIElement {
+  /** Reflected — set when zero message children. Drives the
+<chat-empty> visibility via CSS — no JS toggling needed.
+ */
+  empty: boolean;
+  /** Reflected — set by the host while an LLM response is streaming.
+Consumers can style streaming-mode (e.g. cursor blink) via
+:has(chat-thread[streaming]) or attribute selectors.
+ */
+  streaming: boolean;
+}

package/editor/editor-canvas/editor-canvas.a2ui.json

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

package/editor/editor-canvas/editor-canvas.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `<editor-canvas-ui>` — Module-tier editor canvas surface — replaces legacy <div data-canvas>
+inside <editor-shell> per ADR-0023. Owns scroll/zoom container
+semantics, [empty] and [focused] reflected attributes, and a stable
+target for the host's content rendering pipeline.
+
+Sits as the central content region inside <editor-shell>, between
+the optional <editor-sidebar slot="leading"> and <editor-sidebar
+slot="trailing">. Authors compose <editor-canvas-empty> as an
+optional first child for the empty state; canvas content children
+(artboards, document body, etc.) are appended either statically or
+dynamically by the host.
+
+Backwards compat — <editor-shell> still recognizes the legacy
+<div data-canvas> shape via :is() selector. New code should prefer
+<editor-canvas>.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/editor-canvas
+ *
+ * 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 UIEditorCanvas extends UIElement {
+  /** Reflected — set when zero non-<editor-canvas-empty> children.
+Drives the <editor-canvas-empty> visibility via parent CSS —
+no JS toggling needed.
+ */
+  empty: boolean;
+  /** Reflected — set when canvas claims focus ownership (programmatic
+.focus() call or toolbar full-screen toggle).
+ */
+  focused: boolean;
+}

package/editor/editor-canvas-empty/editor-canvas-empty.a2ui.json

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

package/editor/editor-shell/editor-shell.a2ui.json

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

package/editor/editor-shell/editor-shell.d.ts

@@ -0,0 +1,21 @@
+/**
+ * `<editor-shell-ui>` — Behavior-only editor shell module for design-tool layouts. Author
+provides the structural DOM — header (topbar), [data-editor-body] with
+pane-ui children ([data-left], [data-right]), [data-canvas] for the
+central surface, and a footer (statusbar). editor-shell wires
+select-ui[data-options] for JSON-parsed option lists.
+
+ *
+ * @see https://ui-kit.exe.xyz/site/components/editor-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 UIEditorShell extends UIElement {
+}

package/editor/editor-sidebar/editor-sidebar.a2ui.json

@@ -21,6 +21,16 @@
     "component": {
       "const": "EditorSidebar"
     },
+    "name": {
+      "description": "Alias for [persist]; kept for v0.4.x back-compat. Deprecated —\nnew code should use [persist]. If both are set, [persist] wins.\n",
+      "type": "string",
+      "default": ""
+    },
+    "persist": {
+      "description": "localStorage key suffix. When set, the sidebar persists its pane\nwidth across reloads under `adia-editor-sidebar-{persist}`.\nPreferred over the [name] alias kept for v0.4.x back-compat.\nDefaults to [name] then [slot] if neither set.\n",
+      "type": "string",
+      "default": ""
+    },
     "resizing": {
       "description": "Reflected — set during an active pointer-drag of the pane's\nresize handle. Used to disable transitions and visual treatments\nthat would feel laggy during drag.\n",
       "type": "boolean",
@@ -34,6 +44,7 @@
   "x-adiaui": {
     "anti_patterns": [],
     "category": "layout",
+    "composes": [],
     "events": {
       "sidebar-toggle": {
         "description": "Bubbles when .toggle() / .collapse() / .expand() is called.",

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

@@ -0,0 +1,63 @@
+/**
+ * `<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;
+  /** Alias for [persist]; kept for v0.4.x back-compat. Deprecated —
+new code should use [persist]. If both are set, [persist] wins.
+ */
+  name: string;
+  /** localStorage key suffix. When set, the sidebar persists its pane
+width across reloads under `adia-editor-sidebar-{persist}`.
+Preferred over the [name] alias kept for v0.4.x back-compat.
+Defaults to [name] then [slot] if neither set.
+ */
+  persist: string;
+  /** 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-sidebar/editor-sidebar.js

@@ -25,8 +25,11 @@
  *   [slot="leading"|"trailing"]  — required, drives localStorage
  *                                  namespacing
  *   [collapsible]                — opts in to programmatic collapse
- *   [name="<id>"]                — optional override for the
- *                                  localStorage key (defaults to slot)
+ *   [persist="<id>"]             — optional override for the localStorage
+ *                                  key (defaults to slot). Preferred over
+ *                                  [name]; if both set, [persist] wins.
+ *   [name="<id>"]                — alias for [persist]; kept for v0.4.x
+ *                                  back-compat. Deprecated; prefer [persist].
  *
  * Reflected attributes:
  *   [collapsed]  — set when inner pane width ≤ SNAP_THRESHOLD
@@ -69,10 +72,14 @@ class EditorSidebar extends UIElement {
     this.#pane = this.querySelector('pane-ui');
     if (!this.#pane) return;
 
-    // Resolve storage key
+    // Resolve storage key. Source of truth is [persist], with [name] as an
+    // alias kept for back-compat — both map to the same `${STORAGE_PREFIX}${key}`
+    // localStorage namespace. If both are set, [persist] wins (more descriptive
+    // attribute should beat the legacy alias). Final fallback is [slot] so an
+    // un-named sidebar still namespaces itself per-position.
     const slot = this.getAttribute('slot') || 'leading';
-    const name = this.getAttribute('name') || slot;
-    this.#storageKey = `${STORAGE_PREFIX}${name}`;
+    const key = this.getAttribute('persist') || this.getAttribute('name') || slot;
+    this.#storageKey = `${STORAGE_PREFIX}${key}`;
 
     // Restore persisted width
     this.#restoreWidth();
@@ -169,7 +176,7 @@ class EditorSidebar extends UIElement {
 
   #emitToggle() {
     const slot = this.getAttribute('slot') || 'leading';
-    const name = this.getAttribute('name') || slot;
+    const name = this.getAttribute('persist') || this.getAttribute('name') || slot;
     this.dispatchEvent(new CustomEvent('sidebar-toggle', {
       bubbles: true,
       detail: { name, expanded: !this.collapsed },

package/editor/editor-sidebar/editor-sidebar.yaml

@@ -37,6 +37,20 @@ props:
     type: boolean
     default: false
     reflect: true
+  persist:
+    description: |
+      localStorage key suffix. When set, the sidebar persists its pane
+      width across reloads under `adia-editor-sidebar-{persist}`.
+      Preferred over the [name] alias kept for v0.4.x back-compat.
+      Defaults to [name] then [slot] if neither set.
+    type: string
+    default: ""
+  name:
+    description: |
+      Alias for [persist]; kept for v0.4.x back-compat. Deprecated —
+      new code should use [persist]. If both are set, [persist] wins.
+    type: string
+    default: ""
 
 events:
   sidebar-toggle: