@kitn.ai/ui 0.27.0 → 0.29.0

package/src/elements/diagnostic-events.ts

@@ -1,114 +0,0 @@
-// The ELEMENT-layer diagnostic events: what the `kai-*` custom elements SAW a
-// consumer do to them.
-//
-// The wire events answer "did the data arrive". These answer the other half —
-// "the data is right and the UI still is not updating" — which is a different
-// failure with a different cause and, until now, no evidence at all. All three
-// causes are documented in root CLAUDE.md's `kai-` contract section, and every
-// one of them is silent by construction:
-//
-//   1. An array or object prop set as an HTML ATTRIBUTE. `component-register`
-//      parses attributes with a `JSON.parse` whose `catch` returns the raw
-//      string, so `el.setAttribute('messages', arr)` assigns the literal text
-//      `"[object Object],[object Object]"` to the property and pushes THAT into
-//      the Solid signal. Nothing throws, nothing logs, nothing renders.
-//   2. The SAME array reference handed back. solid-element creates one signal
-//      per prop and sets it with `set(() => v)`; Solid's default equality is
-//      `===`, so re-assigning the identical reference notifies nothing.
-//   3. A NEW array whose items are all the previous item objects. The array
-//      notifies, but the lists render through reference-keyed `<For>`s, so no
-//      row is re-invoked and nothing on screen changes.
-//
-// ZERO IMPORTS, DELIBERATELY. These are type declarations only, so this file is
-// erased at build. That is what lets `wire/diagnostics.ts` name them in its
-// union without `wire/` acquiring a runtime dependency on `elements/` — which
-// would be a real layering inversion, and would drag the element bundle into
-// every consumer that only parses streams.
-//
-// METADATA ONLY, by the same rule the wire events follow: if a value comes from
-// the model, the end user, or the app's data it is PAYLOAD; if it describes the
-// shape, size, timing or identity of that value it is METADATA. A tag name, a
-// prop name, a kind, a count and a length are all identity or shape. A prop's
-// VALUE never appears in any field below — `valuePreview` is a shape
-// description built from a closed vocabulary, never the text itself. Pinned by
-// `element-diagnostics-payload.test.ts`, which plants a sentinel inside every
-// prop value it sets and asserts it never reaches a serialized event.
-
-/** The envelope, structurally identical to `WireDiagnosticBase`. Restated here
- *  rather than imported so this file keeps its zero-import property; the two are
- *  kept in step by `element-diagnostics.test.ts`, which asserts every emitted
- *  element event carries a `type` and a numeric `t`. */
-export interface ElementDiagnosticBase {
-  type: string;
-  /** `Date.now()` at emission. */
-  t: number;
-}
-
-/** Which contract was broken. A closed vocabulary, so a panel keys its own
- *  explanation off the kind and never needs prose from the kit. */
-export type ElementViolationKind =
-  /** A non-scalar prop received a value through the ATTRIBUTE channel. The
-   *  attribute cannot carry an array or an object, so the property now holds a
-   *  string and the element renders nothing. */
-  | 'array-prop-as-attribute'
-  /** A list prop was set to the array reference it already held. Solid compares
-   *  with `===`, so this notified nothing — a no-op write. */
-  | 'same-array-reference'
-  /** A list prop received a NEW array of the SAME length whose every item is
-   *  reference-identical to the previous array's. The array notified, but every
-   *  row's identity is unchanged, so a reference-keyed `<For>` re-invokes none
-   *  of them. The classic "I mutated the item and copied the array" case.
-   *
-   *  NOTE what this deliberately does NOT claim: the kit cannot know an item
-   *  "changed" without comparing its CONTENT, and content is payload. So this
-   *  reports the structurally knowable fact — an update that cannot render —
-   *  and leaves the question of whether the consumer meant anything by it to
-   *  the consumer, who is the only one who can answer it. */
-  | 'mutated-in-place';
-
-/** A consumer broke one of the three `kai-` contract rules on a live element. */
-export interface ElementViolationEvent extends ElementDiagnosticBase {
-  type: 'element.violation';
-  kind: ElementViolationKind;
-  /** The custom-element tag, e.g. `kai-chat`. */
-  tag: string;
-  /** The camelCase prop name, e.g. `messages`. */
-  prop: string;
-  /**
-   * SHAPE of the offending value, never its content. `array-prop-as-attribute`
-   * only. A closed vocabulary:
-   *
-   *   `[object Object]`      one object stringified into the attribute
-   *   `[object Object] x N`  an array of N objects stringified — the common case
-   *   `json:number`          the attribute held valid JSON, but a scalar
-   *   `json:boolean`         "
-   *   `json:null`            "
-   *   `string(len=N)`        anything else: the LENGTH of the text, never the text
-   *   `empty-attribute`      a bare attribute on a prop that needs a value
-   */
-  valuePreview?: string;
-  /** Element count of the array involved. `same-array-reference` and
-   *  `mutated-in-place` only. A length is shape, not content. */
-  length?: number;
-}
-
-/** Which `kai-*` elements are DEFINED in this realm right now.
- *
- *  The question behind it is hydration: an SSR page whose markup contains
- *  `<kai-chat>` but whose element bundle never loaded shows empty boxes and no
- *  error, because an undefined custom element is a valid, inert HTMLElement.
- *  The SSR starters already answer this by hand for a hard-coded handful
- *  (`HydrationBadge.tsx`); this is the same answer over the whole manifest. */
-export interface ElementRegistryEvent extends ElementDiagnosticBase {
-  type: 'element.registry';
-  /** Tags `customElements.get()` resolved. */
-  defined: string[];
-  /** Tags in the manifest that are NOT defined in this realm. Named for what it
-   *  is rather than `undefined`, which is a miserable key to read in a panel. */
-  notDefined: string[];
-  /** `defined.length + notDefined.length`. Present so a panel can show "62 of
-   *  79" without trusting itself to add up two arrays it may have truncated. */
-  total: number;
-}
-
-export type ElementDiagnosticEvent = ElementViolationEvent | ElementRegistryEvent;

package/src/elements/dialog.tsx

@@ -1,145 +0,0 @@
-import { createSignal, onCleanup, onMount } from 'solid-js';
-import { defineWebComponent } from './define';
-import { Dialog, type DialogController } from '../ui/dialog';
-import { wireDisclosure } from './disclosure';
-
-interface Props extends Record<string, unknown> {
-  /** Drive/observe open state (Shoelace-style: settable + reflected to the `open`
-   *  attribute; the element still self-manages on Escape/backdrop). Set
-   *  `el.open = true`, or `<kai-dialog open>`; listen for `kai-open-change`. */
-  open?: boolean;
-  /** Initial open state on mount (uncontrolled seed). */
-  defaultOpen?: boolean;
-  /**
-   * Accessible name for the modal, used when no `header` slot is projected:
-   * `<kai-dialog label="Delete workspace">`. A projected `header` WINS over this
-   * (it becomes `aria-labelledby`), because ARIA resolves `aria-labelledby` ahead
-   * of `aria-label` and the visible heading is the name both a sighted and a
-   * screen-reader user can be talked through. Defaults to `Dialog` so a modal is
-   * never nameless.
-   */
-  label?: string;
-}
-
-/**
- * The fallback accessible name.
- *
- * DELIBERATELY GENERIC, and a decision rather than a placeholder. A modal with no
- * name at all fails WCAG and axe's `aria-dialog-name`; "Dialog, dialog" is merely
- * redundant, and between the two the redundant one is strictly better — it is also
- * what Shoelace and WebAwesome ship. The kit cannot know what a given modal is about,
- * so inventing something specific here would be a worse default than saying nothing
- * extra. Consumers name it properly with `label` or by projecting a `header`.
- */
-const DEFAULT_LABEL = 'Dialog';
-
-/**
- * The consumer's label, or the fallback — with "no label" meaning every way a
- * consumer can arrive at one.
- *
- * The declared default is a SEED, not a floor: component-register writes the prop
- * back as `null` when the attribute is removed and does NOT restore the declared
- * value, so `props.label` is legitimately `null`/`undefined` at runtime. An empty or
- * whitespace-only string is the same situation wearing a name — `aria-label=""` is a
- * `role="dialog"` with no accessible name, i.e. the exact defect this exists to
- * prevent, reached through the attribute that was supposed to prevent it. Each of
- * those routes is a row in tests/elements/dialog.test.tsx, because a mutation run
- * showed the plain `??` was uncovered.
- */
-function resolveLabel(label: unknown): string {
-  return typeof label === 'string' && label.trim() !== '' ? label : DEFAULT_LABEL;
-}
-
-/** Events fired by `<kai-dialog>`. */
-interface Events {
-  /** The dialog opened or closed (Escape, backdrop click, a driven `open`, or a method). */
-  'kai-open-change': { open: boolean };
-}
-
-/**
- * `<kai-dialog>` — a centered modal: a dimmed backdrop over the page with a
- * centered panel of arbitrary content. It is the real primitive behind the kind
- * of modal that settings panels and broadcast composers reach for.
- *
- * **How to use** — slot the body, and optionally a `header` and `footer`:
- * ```html
- * <kai-dialog open>
- *   <h2 slot="header">Broadcast a message</h2>
- *   <textarea placeholder="What's on your mind?"></textarea>
- *   <div slot="footer">
- *     <button onclick="this.closest('kai-dialog').hide()">Cancel</button>
- *     <button>Send</button>
- *   </div>
- * </kai-dialog>
- * ```
- *
- * The default slot is the body; `header`/`footer` are optional regions with
- * dividers. The backdrop dims the page; clicking it (or pressing Escape) closes
- * the dialog. Focus moves into the panel on open and is restored on close, and a
- * basic Tab focus trap keeps keyboard focus inside while open.
- *
- * The dialog is always named: a projected `header` becomes its `aria-labelledby`,
- * and otherwise `label` becomes its `aria-label` (defaulting to `Dialog`). The
- * header wins when both are present, since ARIA ranks `aria-labelledby` first.
- *
- * Open state is the standard disclosure surface: settable+reflecting `open`,
- * `kai-open-change`, and `show()`/`hide()`/`toggle()`; seed with `default-open`.
- * It also exposes `focus()` to move focus to the panel. Parts: `backdrop` ·
- * `panel` · `header` · `body` · `footer`.
- */
-defineWebComponent<Props, Events>('kai-dialog', {
-  open: undefined,
-  defaultOpen: undefined,
-  label: DEFAULT_LABEL,
-}, (props, ctx) => {
-  const { flag, element, expose } = ctx;
-  let api: DialogController | undefined;
-  let panel: HTMLElement | undefined;
-
-  // The standard disclosure surface: settable+reflecting `open`, kai-open-change,
-  // show/hide/toggle. See ./disclosure. The SOLE emitter of kai-open-change — the
-  // primitive's onOpenChange is intentionally NOT wired here to avoid a double
-  // dispatch.
-  wireDisclosure(ctx, () => api, () => props.open);
-
-  // Only render the header/footer chrome (border + padding) when the consumer has
-  // actually projected content for that slot — otherwise an empty bordered region
-  // would show. Tracked off the host's light-DOM children.
-  const [hasHeader, setHasHeader] = createSignal(false);
-  const [hasFooter, setHasFooter] = createSignal(false);
-  const recompute = () => {
-    setHasHeader(!!element.querySelector(':scope > [slot="header"]'));
-    setHasFooter(!!element.querySelector(':scope > [slot="footer"]'));
-  };
-  onMount(() => {
-    recompute();
-    if (typeof MutationObserver === 'function') {
-      const obs = new MutationObserver(recompute);
-      obs.observe(element, { childList: true });
-      onCleanup(() => obs.disconnect());
-    }
-  });
-
-  // focus() shadows the host's native focus so it targets the dialog panel inside
-  // the shadow root (the WebAwesome/Shoelace convention).
-  expose({
-    /** Move focus to the dialog panel (no-op while closed). */
-    focus: (options?: FocusOptions) => panel?.focus(options),
-  });
-
-  return (
-    <Dialog
-      defaultOpen={flag('defaultOpen')}
-      // The primitive already ranks these correctly — it emits `aria-labelledby` when
-      // a header is present and `aria-label` only when one is not — so the facade just
-      // has to HAND the name over, which is the wiring that was missing.
-      aria-label={resolveLabel(props.label)}
-      header={hasHeader() ? <slot name="header" /> : undefined}
-      footer={hasFooter() ? <slot name="footer" /> : undefined}
-      controllerRef={(a) => (api = a)}
-      panelRef={(el) => (panel = el)}
-    >
-      <slot />
-    </Dialog>
-  );
-});

package/src/elements/disclosure.ts

@@ -1,95 +0,0 @@
-import { createEffect, untrack, type Accessor } from 'solid-js';
-import type { WebComponentContext } from './define';
-
-/** The open controller a primitive hands up via `controllerRef` so a facade can
- *  drive + observe its open/closed state. */
-export interface OpenController {
-  open: Accessor<boolean>;
-  setOpen: (v: boolean) => void;
-}
-
-/**
- * Wire the standard Shoelace/WebAwesome-style overlay surface onto an internal
- * open controller — the kit's convention for every open/close element (hover-card,
- * tooltip, popover, menu, model-switcher, scope-picker, collapsibles, …). NOT
- * React-controlled: the element keeps self-managing; this layers the host-facing
- * conveniences on top.
- *
- * Given the primitive's `{ open, setOpen }` controller, it provides:
- *  - **`open` reflects** to the host `[open]` attribute (for `:host([open])` CSS),
- *    and is **settable** — `el.open = true` / `<el open>` drives it;
- *  - **`kai-open-change` `{ open }`** fires once per change (a guarded reflect
- *    avoids the attribute⇄prop feedback loop);
- *  - **`show()` / `hide()` / `toggle()`** instance methods, gated by `disabled`.
- *
- * The facade still:
- *  - declares the `open` / `defaultOpen` / `disabled` props (defaults `undefined`),
- *  - seeds the primitive from `defaultOpen` (e.g. via the primitive's own prop),
- *  - includes `'kai-open-change': { open: boolean }` in its `Events` map.
- *
- * @param ctx      the facade's WebComponentContext (its Events must include kai-open-change).
- * @param getApi   returns the open controller once the primitive has handed it up (may be undefined early).
- * @param openProp reads the raw reactive `open` prop (e.g. `() => props.open`) — used to tell
- *                 "consumer explicitly set open" from "unset" so a `defaultOpen` seed isn't clobbered.
- */
-export function wireDisclosure<E extends { 'kai-open-change': { open: boolean } }>(
-  ctx: WebComponentContext<E>,
-  getApi: () => OpenController | undefined,
-  openProp: () => unknown,
-): void {
-  const { element, dispatch, flag, reflectFlag, expose } = ctx;
-  let prev: boolean | undefined;
-
-  // External `open` prop/attr → drive internal state. Only when the consumer has
-  // EXPLICITLY set it (so a defaultOpen seed survives mount); the equality guard
-  // keeps the reflect below from looping back through the prop.
-  //
-  // THIS RUNS FIRST, AND THE ORDER IS THE FIX FOR A REAL DEFECT. It used to run
-  // second, after the outward reflection — which on the very first pass read a
-  // controller still in its default CLOSED state and called
-  // `toggleAttribute('open', false)`, DELETING the author's attribute before anything
-  // had read it. This effect then saw no attribute and a prop that
-  // component-register had parsed to `undefined`, concluded nothing was asked for,
-  // and left the element shut. Net result: `<kai-reasoning open>` — the plain HTML
-  // spelling the `open` prop's own doc advertises — never opened; only `default-open`
-  // did. Reading intent IN before reflecting state OUT is what makes the author's
-  // attribute survive long enough to mean something.
-  createEffect(() => {
-    const api = getApi();
-    if (!api) return;
-    const explicit = openProp() !== undefined || element.hasAttribute('open');
-    if (!explicit) return;
-    const desired = flag('open');
-    if (desired !== untrack(api.open)) api.setOpen(desired);
-  });
-
-  // Reflect internal open → the `[open]` host attribute.
-  //
-  // Through `reflectFlag`, whose SOURCE is the controller rather than the prop — this
-  // element's truth is its internal open signal, not `props.open`. It also installs
-  // the read-back accessor, which this wiring needed and did not have: `el.open = true`
-  // used to leave `el.open === undefined`, exactly as `kai-chat`'s `loading` did
-  // (findings G-05). Returning `undefined` before the primitive has handed its
-  // controller up leaves the author's `<el open>` attribute alone.
-  reflectFlag('open', () => getApi()?.open());
-
-  // kai-open-change, fired once per change. Separate from the reflection above
-  // because it is a notification, not a reflection; both run in the same batch, so
-  // splitting them changes nothing observable about the ordering.
-  createEffect(() => {
-    const api = getApi();
-    if (!api) return;
-    const o = api.open();
-    if (prev !== undefined && prev !== o) dispatch('kai-open-change', { open: o } as E['kai-open-change']);
-    prev = o;
-  });
-
-  expose({
-    /** Open it programmatically (no-op while disabled). */
-    show: () => { if (!flag('disabled')) getApi()?.setOpen(true); },
-    /** Close it programmatically. */
-    hide: () => getApi()?.setOpen(false),
-    /** Flip the open state (closes while disabled). */
-    toggle: () => { const api = getApi(); if (api) api.setOpen(flag('disabled') ? false : !api.open()); },
-  });
-}

package/src/elements/dock.tsx

@@ -1,215 +0,0 @@
-import { untrack } from 'solid-js';
-import { defineWebComponent } from './define';
-import {
-  Dock, DockCloseGlyph, DockLauncherGlyph,
-  type DockController, type DockFocusOnOpen, type DockPosition,
-} from '../ui/dock';
-import { wireDisclosure } from './disclosure';
-
-interface Props extends Record<string, unknown> {
-  /** Drive/observe open state (Shoelace-style: settable + reflected to the `open`
-   *  attribute; the element still self-manages on the launcher and Escape). Set
-   *  `el.open = true`, or `<kai-dock open>`; listen for `kai-open-change`. */
-  open?: boolean;
-  /** Initial open state on mount (uncontrolled seed). */
-  defaultOpen?: boolean;
-  /** Which corner the dock sits in. Logical, so `-end` follows the writing direction
-   *  and an RTL page docks on the left. Attribute: `position`. */
-  position?: DockPosition;
-  /** The widget's NAME. Derives the panel's accessible name and both launcher names
-   *  (`Open ${label}` / `Close ${label}`). Defaults to `Chat`. */
-  label?: string;
-  /** i18n override for the launcher's name while closed (default `Open ${label}`). */
-  openLabel?: string;
-  /** i18n override for the launcher's name while open (default `Close ${label}`). */
-  closeLabel?: string;
-  /** Show the unread dot. YOURS: it renders only while closed, and the dock never
-   *  writes it back. Clear it in your `kai-open-change` handler. */
-  unread?: boolean;
-  /** Disable the launcher; `show()` and `toggle()` are gated on it. */
-  disabled?: boolean;
-  /** Suppress the dock's own built-in mobile close X. Set this when your slotted
-   *  panel content supplies its own close affordance (e.g. a `<kai-chat
-   *  slot="header-end">` close button), otherwise the two stack. TRADEOFF: the
-   *  mobile panel reserves a padding band above its content so the built-in X
-   *  never paints over slotted content; that band stays reserved unless you set
-   *  this true, so only set it once your own control is actually in place.
-   *  Attribute: `hide-close`. */
-  hideClose?: boolean;
-  /** Where focus lands on open: `content` (default, the first element you slotted),
-   *  `panel`, or `none`. Attribute: `focus-on-open`. */
-  focusOnOpen?: DockFocusOnOpen;
-}
-
-/** Events fired by `<kai-dock>`. */
-interface Events {
-  /** The dock opened or closed (the launcher, Escape, a driven `open`, or a method). */
-  'kai-open-change': { open: boolean };
-}
-
-/**
- * `<kai-dock>` — the corner launcher: a floating button pinned to a corner of the
- * viewport, and a panel above it holding whatever you slot in. This is the "chat
- * bubble in the bottom-right" affordance. (Not to be confused with
- * `<kai-prompt-dock>`, which is a recessed tray that frames a prompt INPUT and does
- * not float, launch or open anything.)
- *
- * **How to use** — slot the surface, and let the dock own the button:
- * ```html
- * <kai-dock label="Aurora support">
- *   <kai-chat slot="panel" chat-title="Aurora Support"></kai-chat>
- * </kai-dock>
- * ```
- *
- * The panel is content-agnostic: a `<kai-chat>`, a form, your own element. The dock
- * never reads or types it. `slot="launcher"` / `slot="launcher-open"` swap the icon
- * INSIDE the built-in button — the button itself is never slotted away, because the
- * dock owns `aria-expanded`, `aria-controls`, the toggle wiring and the focus return,
- * and a replaced button would take all four with it.
- *
- * Open state is the standard disclosure surface: settable+reflecting `open`,
- * `kai-open-change`, and `show()`/`hide()`/`toggle()`; seed with `default-open`. It
- * also exposes `focus()` — the panel while open, the launcher while closed.
- *
- * Neither `default-open` nor `open` moves focus at mount. A widget docked on someone
- * else's page does not get to steal focus on load, which is the one place this
- * element differs from `<kai-dialog>`, where a modal opened at mount takes focus on
- * purpose. Opening it later does move focus, per `focus-on-open`.
- *
- * Closed does not mean gone: the panel keeps its layout box (`visibility: hidden` +
- * `inert`), so a thread inside it never re-measures from zero and a reply that lands
- * while closed is really there. `unread` is yours to set and yours to clear; the dot
- * just stops rendering while open.
- *
- * Escape closes only while the dock holds focus, and is never swallowed — a widget
- * docked on someone else's page does not get to eat their Escape. There is no focus
- * trap; the page stays usable, which is the point of "docked".
- *
- * Geometry is CSS custom properties, not props: `--kai-dock-width` ·
- * `--kai-dock-height` · `--kai-dock-inset` · `--kai-dock-gap` · `--kai-dock-radius` ·
- * `--kai-dock-z` · `--kai-dock-launcher-size`. Narrow viewports go full-bleed by
- * default. Parts: `launcher` · `panel` · `badge`.
- *
- * Put it as a body-level child: a `transform` / `filter` / `contain` ancestor makes
- * `position: fixed` resolve against that ancestor instead of the viewport.
- *
- * **Migrating a hand-rolled widget onto this element changes two behaviours**, both
- * deliberately, so check them rather than assuming a drop-in:
- *
- * 1. **Escape is scoped to the dock.** Hand-rolled versions of this widget typically
- *    listen on `document` and close on any Escape anywhere on the page. This one
- *    closes only while the dock holds focus, and never stops the event. If your app
- *    relied on Escape-anywhere, that is now the host page's key again.
- * 2. **The panel keeps its layout box while closed.** It is hidden with
- *    `visibility` + `inert`, not `display: none`, and is never unmounted, so whatever
- *    you slot in KEEPS RENDERING in the background: a stream still folds in, timers
- *    still run, and heights stay measured. That is what makes `unread` honest and
- *    what stops a reopened thread re-measuring from zero, but it does mean a panel
- *    that was free while `display: none` no longer is.
- */
-defineWebComponent<Props, Events>('kai-dock', {
-  open: undefined,
-  defaultOpen: undefined,
-  position: 'bottom-end',
-  label: 'Chat',
-  openLabel: undefined,
-  closeLabel: undefined,
-  unread: undefined,
-  disabled: undefined,
-  hideClose: undefined,
-  focusOnOpen: 'content',
-}, (props, ctx) => {
-  const { flag, element, expose, reflectFlag } = ctx;
-  let api: DockController | undefined;
-  let panel: HTMLElement | undefined;
-  let launcher: HTMLButtonElement | undefined;
-
-  // The standard disclosure surface: settable+reflecting `open`, kai-open-change,
-  // show/hide/toggle. See ./disclosure — and note it is the SOLE emitter of the
-  // event, so the primitive's onOpenChange is deliberately not wired here.
-  wireDisclosure(ctx, () => api, () => props.open);
-
-  // The other three booleans get the same read-back treatment, for the same reason:
-  // `<kai-dock unread>` parses to `undefined`, so without this the property would
-  // contradict the attribute that set it (findings G-05). Reflecting `unread` syncs
-  // the ATTRIBUTE to the prop and never changes the VALUE — the dock still never
-  // decides that a message has been read.
-  reflectFlag('unread');
-  reflectFlag('disabled');
-  reflectFlag('defaultOpen');
-  reflectFlag('hideClose');
-
-  // Seed the primitive from EITHER spelling, read once at upgrade.
-  //
-  // `open` is folded in here rather than left to wireDisclosure's effect on purpose.
-  // That effect runs a tick after mount, so `<kai-dock open>` would mount closed and
-  // then transition — which the primitive's focus effect would correctly read as a
-  // real open and steal focus with, on page load, on someone else's page. Seeding
-  // makes mount a non-event for both spellings; wireDisclosure's effect then finds
-  // the value already correct and its equality guard makes it a no-op.
-  //
-  // UNTRACKED, and that is not defensive noise — it is the fix for a real defect this
-  // element shipped for about ten minutes. A facade body runs inside the tracking
-  // scope that inserts it, so a bare `flag('open')` here subscribes the WHOLE FACADE
-  // to `open`: every toggle re-ran it, which re-created the `<Dock>`, its panel div
-  // and its controller. The visible symptoms were far away from the cause — focus
-  // never moved (each fresh focus effect was re-seeded with the current state, so it
-  // saw no transition) and `kai-open-change` never fired (wireDisclosure had latched
-  // the first, discarded controller). Reading a prop at the top level of a facade is
-  // the general trap; `untrack` is how you say "seed", and it is what makes this a
-  // seed rather than a subscription.
-  const seed = untrack(() => flag('open') || flag('defaultOpen'));
-
-  expose({
-    /** Move focus to the panel while open, or to the launcher while closed. */
-    focus: (options?: FocusOptions) =>
-      (api?.open() ? panel : launcher)?.focus(options),
-  });
-
-  // The `content` focus target: the first element assigned to the panel. Read off the
-  // live slots rather than off `element.children`, so it is the ASSIGNMENT that
-  // decides — a child whose `slot` attribute changes moves with it, and a comment or
-  // whitespace text node is not mistaken for content.
-  const contentTarget = () => {
-    const slots = panel?.querySelectorAll('slot');
-    for (const slot of Array.from(slots ?? [])) {
-      const first = (slot as HTMLSlotElement).assignedElements()[0];
-      if (first instanceof HTMLElement) return first;
-    }
-    return undefined;
-  };
-
-  return (
-    <Dock
-      defaultOpen={seed}
-      position={props.position as DockPosition}
-      label={props.label as string}
-      openLabel={props.openLabel as string | undefined}
-      closeLabel={props.closeLabel as string | undefined}
-      unread={flag('unread')}
-      disabled={flag('disabled')}
-      hideClose={flag('hideClose')}
-      focusOnOpen={props.focusOnOpen as DockFocusOnOpen}
-      contentTarget={contentTarget}
-      controllerRef={(a) => (api = a)}
-      panelRef={(el) => (panel = el)}
-      launcherRef={(el) => (launcher = el)}
-      // NATIVE SLOT FALLBACK does the whole icon chain, with no occupancy tracking and
-      // no MutationObserver: an unfilled slot renders its fallback content, and a slot
-      // nested in another slot's fallback still receives its own assignment. So
-      // `launcher-open` wins while open; failing that the consumer's `launcher` glyph
-      // STAYS rather than morphing into a built-in ✕ that clashes with their art;
-      // failing that the built-in ✕. Both defaults are the primitive's own, imported
-      // rather than re-drawn here.
-      launcher={<slot name="launcher"><DockLauncherGlyph /></slot>}
-      launcherOpen={(
-        <slot name="launcher-open">
-          <slot name="launcher"><DockCloseGlyph /></slot>
-        </slot>
-      )}
-    >
-      <slot name="panel" />
-      <slot />
-    </Dock>
-  );
-});