@kitn.ai/ui 0.25.2 → 0.27.0

package/src/elements/pane-grid.tsx

@@ -0,0 +1,111 @@
+import { createSignal, onMount, onCleanup, Index } from 'solid-js';
+import { defineWebComponent } from './define';
+import { PaneGrid } from '../ui/pane-grid';
+
+interface Props extends Record<string, unknown> {
+  /** Minimum width of every pane, in px, before columns drop / the grid scrolls.
+   *  Defaults to `280`. Attribute: `min-pane-width`. */
+  minPaneWidth?: number;
+  /** Minimum height of every pane, in px, before the grid scrolls vertically.
+   *  Defaults to `200`. Attribute: `min-pane-height`. */
+  minPaneHeight?: number;
+  /** Column cap when the container is wide (default `3`). Attribute: `max-columns`. */
+  maxColumns?: number;
+  /** Gap between panes, any CSS length. Defaults to the kit gap
+   *  (`var(--kai-pane-grid-gap, 0.5rem)`). Attribute: `gap`. */
+  gap?: string;
+  /** When set to a valid child index, render ONLY that pane full-bleed: a simple
+   *  maximize hook the consumer drives (pair it with `<kai-pane>`'s `kai-maximize`
+   *  event). Clear it (or point out of range) for the full tiled grid.
+   *  Attribute: `maximized-index`. */
+  maximizedIndex?: number | null;
+}
+
+/** Attribute values arrive as strings; blank/invalid → undefined (the default). */
+function num(value: unknown): number | undefined {
+  if (value == null || value === '') return undefined;
+  const n = Number(value);
+  return Number.isFinite(n) ? n : undefined;
+}
+
+/**
+ * `<kai-pane-grid>` — an N-pane responsive tiling grid with a min-size + scroll
+ * floor. Each direct light child is one tile: the grid fills up to `max-columns`
+ * columns when wide, DROPS columns as the container narrows so panes never squish
+ * below `min-pane-width`, then SCROLLS once even one column can't fit. Rows keep
+ * at least `min-pane-height` the same way. The natural children are `<kai-pane>` /
+ * `<kai-pane-group>`, but any elements tile.
+ *
+ * ```html
+ * <kai-pane-grid max-columns="2" min-pane-width="320" style="height: 480px">
+ *   <kai-pane headline="Atlas">…</kai-pane>
+ *   <kai-pane headline="Otto">…</kai-pane>
+ *   <kai-pane headline="Nova">…</kai-pane>
+ * </kai-pane-grid>
+ * ```
+ *
+ * Maximize: set `maximized-index` to a child index to show only that pane
+ * full-bleed; clear it to restore. The grid never decides this itself — drive it
+ * from your own control (e.g. `<kai-pane>`'s `kai-maximize` event). Scalar
+ * attributes only; no events.
+ *
+ * Under the shadow root each pane child is projected through its own named slot
+ * (assigned automatically — an author-set `slot` attribute on a direct child is
+ * respected and left alone), so the light children become the grid tiles directly.
+ */
+defineWebComponent<Props>('kai-pane-grid', {
+  minPaneWidth: undefined,
+  minPaneHeight: undefined,
+  maxColumns: undefined,
+  gap: undefined,
+  maximizedIndex: undefined,
+}, (props, { element }) => {
+  // One named slot per direct light child, in child order. The slot names are
+  // written onto the children (`pane-<i>`), the same per-child-slot pattern
+  // <kai-resizable> uses (`p0`/`p1`/…): PaneGrid tiles its JSX children, and a
+  // single default <slot> would make ALL panes one tile. A child that already
+  // carries an author-set slot attribute outside our namespace is left alone
+  // (and therefore not tiled) — authoring escape hatch, same as unslotted text.
+  const [slotNames, setSlotNames] = createSignal<string[]>([]);
+
+  onMount(() => {
+    const read = () => {
+      const names: string[] = [];
+      let i = 0;
+      for (const child of Array.from(element.children)) {
+        const existing = child.getAttribute('slot');
+        if (existing !== null && !/^pane-\d+$/.test(existing)) continue; // author-owned
+        const name = `pane-${i++}`;
+        if (existing !== name) child.setAttribute('slot', name);
+        names.push(name);
+      }
+      // Structural equality: our own setAttribute('slot') writes re-fire the
+      // observer; an unchanged name list means an unchanged layout, so skip the
+      // re-render (mirrors <kai-resizable>'s itemsChanged guard).
+      if (names.length !== slotNames().length || names.some((n, j) => n !== slotNames()[j])) {
+        setSlotNames(names);
+      }
+    };
+    read();
+    const observer = new MutationObserver(read);
+    observer.observe(element, { childList: true });
+    onCleanup(() => observer.disconnect());
+  });
+
+  return (
+    <>
+      {/* A tiling grid fills its container — default the host to a stretching
+          block, same as <kai-resizable>. Give the element (or a parent) a height. */}
+      <style>{':host{display:block;height:100%;min-height:0;min-width:0}'}</style>
+      <PaneGrid
+        minPaneWidth={num(props.minPaneWidth)}
+        minPaneHeight={num(props.minPaneHeight)}
+        maxColumns={num(props.maxColumns)}
+        gap={props.gap as string | undefined}
+        maximizedIndex={num(props.maximizedIndex) ?? null}
+      >
+        <Index each={slotNames()}>{(name) => <slot name={name()} />}</Index>
+      </PaneGrid>
+    </>
+  );
+});

package/src/elements/prompt-dock.tsx

@@ -23,7 +23,8 @@ type SlotName = (typeof SLOT_NAMES)[number];
 
 /**
  * `<kai-prompt-dock>` — a recessed tray that frames a prompt input and can extend
- * with optional "lip" regions above and/or below it. The input is the raised card
+ * with optional "lip" regions above and/or below it. It sits in the page flow and
+ * launches nothing; the floating corner launcher is `<kai-dock>`. The input is the raised card
  * that floats on the tray; the lips sit in a slightly darker recessed band sharing
  * the tray's rounding, so the whole thing reads as one cohesive control.
  *

package/src/elements/prompt-input.tsx

@@ -27,9 +27,9 @@ interface Props extends Record<string, unknown> {
   /** What clicking a suggestion does: `'submit'` (default) sends it immediately
    *  as if typed and submitted; `'fill'` just places it in the input. */
   suggestionMode?: 'submit' | 'fill';
-  /** Show a Search (Globe) button in the left toolbar; clicking it fires a
-   *  `search` event. */
-  search?: boolean;
+  /** Show a web-search (Globe) button in the left toolbar; clicking it fires a
+   *  `kai-web-search` event. Attribute: `web-search`. */
+  webSearch?: boolean;
   /** Show a Voice (Mic) button in the left toolbar; clicking it fires a `voice`
    *  event. */
   voice?: boolean;
@@ -49,7 +49,11 @@ interface Props extends Record<string, unknown> {
   attach?: boolean;
   /** Attachments to seed the input with (so a consumer can pre-populate staged
    *  files without an upload). Set as a JS property; the element then manages its
-   *  own attachment state from there (add via the paperclip, remove per chip). */
+   *  own attachment state from there (add via the paperclip, remove per chip).
+   *  Each item's `url` must be a `data:` URI or an https URL, never
+   *  `URL.createObjectURL`: a `blob:` URL previews perfectly and is meaningless
+   *  outside this tab, so `toOpenAIMessages`/`toAnthropicMessages` refuse it.
+   *  (The built-in paperclip already stages files as `data:` URIs.) */
   attachments?: AttachmentData[];
   /** Rich entity triggers. Each `{ char, kind, items }` opens a caret-anchored menu
    *  that inserts an atomic pill. Convention: `/` → skills, `@` → agents (plugins
@@ -64,7 +68,9 @@ interface Props extends Record<string, unknown> {
 interface Events {
   /** The user submitted the prompt (Enter or send button). `value` is the
    *  flattened text (back-compat); `doc` is the structured document and
-   *  `entities` the inserted pills (skills/agents) for downstream expansion. */
+   *  `entities` the inserted pills (skills/agents) for downstream expansion.
+   *  `<kai-prompt-input>` is the batteries-included composer row (send button,
+   *  toolbar, attachment staging) built on `<kai-composer>`, the bare editor. */
   'kai-submit': { value: string; doc: ComposerDoc; entities: EntityRef[]; attachments: AttachmentData[] };
   /** The input changed (fires on every edit). Carries the flattened `value`
    *  plus the structured `doc` + `entities`. */
@@ -75,8 +81,8 @@ interface Events {
   'kai-attachments-change': { attachments: AttachmentData[] };
   /** A suggestion was clicked while `suggestion-mode="fill"`. */
   'kai-suggestion-click': { value: string };
-  /** The Search (Globe) toolbar button was clicked. */
-  'kai-search': Record<string, never>;
+  /** The web-search (Globe) toolbar button was clicked. */
+  'kai-web-search': Record<string, never>;
   /** The Voice (Mic) toolbar button was clicked. */
   'kai-voice': Record<string, never>;
   /** The Stop button was clicked while `stoppable` and `loading` are both true. */
@@ -93,7 +99,7 @@ defineWebComponent<Props, Events>('kai-prompt-input', {
   loading: false,
   suggestions: undefined,
   suggestionMode: 'submit',
-  search: false,
+  webSearch: false,
   voice: false,
   stoppable: false,
   submit: 'always',
@@ -215,7 +221,7 @@ defineWebComponent<Props, Events>('kai-prompt-input', {
       attach={flag('attach')}
       suggestions={props.suggestions}
       attachments={attachments()}
-      search={flag('search')}
+      webSearch={flag('webSearch')}
       voice={flag('voice')}
       toolbarActions={toolbarActions()}
       triggers={props.triggers}
@@ -225,7 +231,7 @@ defineWebComponent<Props, Events>('kai-prompt-input', {
       onSubmit={handleSubmit}
       onSuggestionClick={handleSuggestionClick}
       onAttachmentsChange={(a) => { setAttachments(a); dispatch('kai-attachments-change', { attachments: a }); }}
-      onSearch={() => dispatch('kai-search')}
+      onWebSearch={() => dispatch('kai-web-search')}
       onVoice={() => dispatch('kai-voice')}
       onStop={() => dispatch('kai-stop')}
       onAction={(id) => dispatch('kai-toolbar-action', { action: id })}

package/src/elements/radio-group.tsx

@@ -0,0 +1,129 @@
+import { createEffect, createSignal, untrack } from 'solid-js';
+import { defineWebComponent } from './define';
+import { RadioGroup } from '../ui/radio';
+// Public shape of the `options` prop; lives in ./element-data-types so the ROOT
+// entry can re-export it (see that file's header).
+import type { KaiRadioOption } from './element-data-types';
+
+interface Props extends Record<string, unknown> {
+  /** The choices, top to bottom. Set as a JS PROPERTY (array), never an attribute. */
+  options: KaiRadioOption[];
+  /** Controlled selected `value`. Settable and reflected to the `value` attribute.
+   *  `el.value = 'degraded'` drives it; choosing a row updates it and fires
+   *  `kai-change`. Read `el.value` for live state. */
+  value?: string;
+  /** Shared form-control name for every radio in the group. Defaults to a generated
+   *  id, so the group is exclusive and keyboard-navigable even when nothing is
+   *  submitted. */
+  name?: string;
+  /** Disable every row. Individual rows carry their own `disabled`. */
+  disabled?: boolean;
+  /** Accessible name for the group. */
+  label?: string;
+}
+
+/** Events fired by `<kai-radio-group>`. */
+interface Events {
+  /** A row was chosen. */
+  'kai-change': { value: string };
+}
+
+/**
+ * `<kai-radio-group>` — the kit's "pick exactly one" control: a bordered, divided
+ * list over real `<input type="radio">`s that share a `name`, so one tab stop, arrow
+ * keys, mutual exclusion and form participation are the browser's and not a
+ * reimplementation.
+ *
+ * Feed it `options` (a JS-property array of `{ value, label, description?, disabled? }`),
+ * drive/read the selection with the `value` property (settable + reflected to the
+ * `value` attribute, so `:host([value])` and `el.value` see live state), and listen
+ * for `kai-change`.
+ *
+ * Re-rendering follows the kit's reactivity contract: hand it a NEW array reference,
+ * and a new object for any option whose content changed — the rows are a
+ * reference-keyed list, so mutating an option in place changes nothing on screen.
+ *
+ * ```html
+ * <kai-radio-group value="degraded" label="Severity"></kai-radio-group>
+ * <script type="module">
+ *   import '@kitn.ai/ui/elements';
+ *   const group = document.querySelector('kai-radio-group');
+ *   group.options = [
+ *     { value: 'blocking', label: 'Blocking', description: 'Pages the on-call' },
+ *     { value: 'degraded', label: 'Degraded' },
+ *     { value: 'cosmetic', label: 'Cosmetic' },
+ *   ];
+ *   group.addEventListener('kai-change', (e) => console.log(e.detail.value));
+ *   group.value = 'cosmetic'; // drive it (no kai-change — the host already knows)
+ * </script>
+ * ```
+ */
+defineWebComponent<Props, Events>('kai-radio-group', {
+  options: [],
+  value: undefined,
+  name: undefined,
+  disabled: undefined,
+  label: undefined,
+}, (props, ctx) => {
+  const { element, dispatch, flag, expose } = ctx;
+
+  // Lift the selection into the facade and drive RadioGroup CONTROLLED so the host can
+  // read it (`el.value` / `:host([value])`) and set it after mount. Seed from the
+  // `value` property/attribute present on mount; nothing is auto-selected, because
+  // `options` normally arrives as a property AFTER upgrade (kai-segmented's structure).
+  const [value, setValue] = createSignal(
+    (props.value as string | undefined) ?? element.getAttribute('value') ?? '',
+  );
+
+  // Coerce anything arriving through the `value` setter (a JS assignment, or the
+  // attributeChangedCallback write-back) to a string, falling back to the live
+  // attribute when nullish so the reflect write-back equals the signal and the guards
+  // below absorb it — no attr⇄prop feedback loop.
+  const coerce = (v: unknown): string =>
+    v == null ? (element.getAttribute('value') ?? '') : String(v);
+
+  // Apply a new value and fire kai-change once (the user-choice path).
+  const apply = (next: string) => {
+    if (untrack(value) === next) return;
+    setValue(next);
+    dispatch('kai-change', { value: next });
+  };
+
+  Object.defineProperty(element, 'value', {
+    get: () => value(),
+    set: (v: unknown) => { const next = coerce(v); if (untrack(value) !== next) setValue(next); },
+    configurable: true,
+    enumerable: true,
+  });
+
+  // Reflect internal value → the `[value]` host attribute (for `:host([value])`).
+  createEffect(() => {
+    const v = value();
+    if (v) {
+      if (element.getAttribute('value') !== v) element.setAttribute('value', v);
+    } else if (element.hasAttribute('value')) {
+      element.removeAttribute('value');
+    }
+  });
+
+  expose({
+    /** Focus the group's tab stop. That is the selected radio, or the first row when
+     *  nothing is selected yet. */
+    focus: (options?: FocusOptions) => {
+      const root = element.shadowRoot;
+      const radios = [...(root?.querySelectorAll<HTMLInputElement>('input[type="radio"]') ?? [])];
+      (radios.find((r) => r.checked) ?? radios[0])?.focus(options);
+    },
+  });
+
+  return (
+    <RadioGroup
+      options={(props.options ?? []) as KaiRadioOption[]}
+      value={value()}
+      name={props.name as string | undefined}
+      disabled={flag('disabled')}
+      label={props.label as string | undefined}
+      onChange={(next) => apply(next)}
+    />
+  );
+});

package/src/elements/register-impl.ts

@@ -3,7 +3,10 @@
 // from ./register.ts so the elements entry is SSR-import-safe — see the comment
 // there. This file is hand-maintained (the generator gen-element-api.mjs SKIPs
 // register.ts AND this file); keep the component import list here in sync.
+import { installKaiDevtoolsHook } from '../diagnostics/hook';
+import { emitElementRegistry } from './element-diagnostics';
 import './conversation-list';
+import './conversation-item';
 import './prompt-input';
 import './chat';
 import './chat-workspace';
@@ -51,6 +54,11 @@ import './artifact';
 import './scroll-button';
 import './popover';
 import './switch';
+import './checkbox';
+import './checkbox-group';
+import './radio-group';
+import './slider';
+import './select';
 import './button';
 import './avatar';
 import './badge';
@@ -77,6 +85,10 @@ import './compare';
 import './composer';
 // W3 phase 2: cascading action menu from a JSON items-tree
 import './menu';
+// The same Dropdown surface with a consumer-owned body: you slot the rows
+// instead of handing over an items tree (the shape a framework consumer needs
+// when the rows are their own components).
+import './dropdown';
 // W4 phase 1: grouped filterable command/mention palette
 import './command';
 // Prompt dock + settings building blocks (graduated from SolidJS prototypes)
@@ -87,10 +99,50 @@ import './setting-item';
 // Multi-agent workspace primitives (graduated from SolidJS prototypes)
 import './pane';
 import './pane-group';
+import './pane-grid';
 import './agent-card';
 import './dialog';
+import './dock';
 // Input & search field family
 import './input';
 import './search';
 import './kbd';
 import './editable-label';
+
+// The devtools recorder hook, installed HERE because this file is already the
+// browser-only half of the elements entry (register.ts gates it behind a window
+// check and a dynamic import). So an app that registers the kai-* elements gets
+// the hook with no work, while an SSR import of the entry still touches no
+// global.
+//
+// At the BOTTOM, and it makes no difference: `import` declarations are hoisted,
+// so every element module above has already evaluated by the time any statement
+// in this file runs. Written here anyway so the order you read is the order that
+// happens. Nothing above emits a diagnostic event, so there is nothing to miss.
+//
+// Idempotent and near-free: with no activation signal it allocates no buffer,
+// makes no subscription, and leaves emission a guarded no-op. An app importing
+// the SolidJS components directly never runs this file and must call
+// `installKaiDevtoolsHook()` itself -- see the docblock in ../diagnostics/index.
+installKaiDevtoolsHook();
+
+// One registry snapshot, right after the hook installs and therefore after every
+// element above has registered (import declarations are hoisted, so they all ran
+// before this line).
+//
+// WHY HERE AND NOT INSIDE THE HOOK. The hook lives in ../diagnostics, which is
+// its own rollup bundle and must stay free of any element import -- pulling the
+// manifest in there would drag element bytes into a consumer who only parses
+// streams. The dependency goes elements -> diagnostics, never back.
+//
+// WHY EMIT AT ALL WHEN A PANEL IS USUALLY NOT THERE YET. On the recording branch
+// the hook has already subscribed by this point, so this snapshot lands in the
+// history buffer and a panel attaching seconds later still sees the state at
+// load -- which is the state that answers the hydration question. On the dormant
+// branch `emitElementRegistry()` short-circuits on the active check and costs a
+// symbol read.
+//
+// A panel attaching mid-session with no history gets no snapshot from here and
+// should ask for a fresh one: `emitElementRegistry()` is exported from
+// @kitn.ai/ui/elements for exactly that.
+emitElementRegistry();

package/src/elements/register.ts

@@ -38,6 +38,34 @@ export type { CodeHighlightingOptions } from '../primitives/highlighter';
 export { classifyTool } from '../components/tool-classify';
 export type { ToolKind } from '../components/tool-classify';
 
+// Element-layer diagnostics. `emitElementRegistry()` re-emits the which-elements-
+// are-defined snapshot on demand, for a panel that attached mid-session and so
+// missed the one register-impl emits at load. SSR-safe and a no-op with no
+// subscriber, so calling it unconditionally is fine.
+//
+// WHY THIS ONE PRODUCER IS PUBLIC while `@kitn.ai/ui/diagnostics` deliberately
+// keeps `emitWireDiagnostic`, `nextStreamId` and `setWirePayloadCapture`
+// internal. That rule exists because a consumer able to forge events or reset
+// the stream counter can make a panel lie about a stream that never happened,
+// and one able to flip payload capture can start recording an app's users'
+// conversations without the app deciding to. This function takes no arguments
+// and reports nothing but `customElements.get()` over the manifest: there is no
+// value to forge, no counter to move and no capture to arm. It can only tell the
+// truth about the registry, which is the one thing a late-attaching panel cannot
+// find out for itself.
+//
+// The event TYPES are re-exported here as well as from @kitn.ai/ui/diagnostics:
+// a consumer already importing the elements entry should not have to add a
+// second specifier to name the events it is handed.
+export { emitElementRegistry } from './element-diagnostics';
+export type {
+  ElementDiagnosticBase,
+  ElementDiagnosticEvent,
+  ElementRegistryEvent,
+  ElementViolationEvent,
+  ElementViolationKind,
+} from './diagnostic-events';
+
 // Imperative toast API — usable directly from the elements entry so consumers
 // who only import the web-components bundle still get `toast()`. The store is
 // SSR-safe (no DOM touched until the first toast is raised on the client).

package/src/elements/resizable.tsx

@@ -129,9 +129,16 @@ defineWebComponent<GroupProps, GroupEvents>('kai-resizable', {
         min: el.getAttribute('min') ?? undefined,
         max: el.getAttribute('max') ?? undefined,
         locked: el.hasAttribute('locked') && el.getAttribute('locked') !== 'false',
-        // Honour both the `hidden` boolean attribute and the IDL property — Solid
-        // (and direct `el.hidden = true`) set the property, which doesn't reflect
-        // to the attribute on a custom element.
+        // Honour both the `hidden` attribute and the property, because on THIS element
+        // they are two independent halves of the state and either can be the only one
+        // set. Not a fact about custom elements in general — a custom element that does
+        // not declare a `hidden` prop keeps the native reflecting accessor. It is a fact
+        // about this one: `<kai-resizable-item>` declares `hidden: false`, so
+        // component-register owns the property and nothing reflects. Measured:
+        // `el.hidden = true` writes no attribute, and after maximize writes the
+        // attribute `el.hidden` reads `undefined`. This union is what absorbs that, and
+        // it is why `hidden` is exempt from the reflectFlag migration rather than broken
+        // by it — see reflectItemConfig's doc below.
         hidden: el.hidden || (el.hasAttribute('hidden') && el.getAttribute('hidden') !== 'false'),
         collapsed,
       };
@@ -543,10 +550,22 @@ defineWebComponent<GroupProps, GroupEvents>('kai-resizable', {
  * *properties* — `el.size = "280px"` — but component-register only mirrors
  * attribute→property, never the reverse, so a property-set size never becomes an
  * attribute and the parent silently falls back to a flexible split. This is the
- * exact class of bug the `collapsed` reflection already fixed; extended here to
- * `size`/`min`/`max` (strings) and `locked` (boolean). `hidden` is deliberately
- * NOT reflected — native `el.hidden` reflects to the attribute on its own and the
- * parent honours the `hidden` property directly (and maximize drives `hidden`).
+ * exact class of bug the `collapsed` reflection already fixed; handled here for
+ * `size`/`min`/`max` (the STRINGS). The booleans — `collapsed` and `locked` — go
+ * through `reflectFlag` in the facade body instead, which reflects AND keeps the
+ * property readable; see WebComponentContext.reflectFlag.
+ *
+ * `hidden` is deliberately NOT reflected, and NOT because it is already fine — it is
+ * split exactly like the others, and measurably so: `el.hidden = true` leaves no
+ * attribute (a plain `<div>` gets one), and after maximize writes the attribute
+ * `el.hidden` reads `undefined`. Declaring `hidden: false` is what does it — it makes
+ * `hidden` a component-register prop, whose non-reflecting accessor shadows the native
+ * reflecting one. What makes the split HARMLESS here is that both readers take the
+ * union, `el.hidden || el.hasAttribute('hidden')`, so neither half can be missed.
+ * Routing it through `reflectFlag` would put a second writer on an attribute the
+ * maximize/restore path already owns, so it is a behaviour decision of its own rather
+ * than part of the read-back fix. See the exemption in
+ * tests/elements/reflected-boolean-coverage.test.ts.
  *
  * Durability (don't fight drags): the parent WRITES `size` back to the live percent
  * during a drag (`persistSizes` → `setAttribute('size', …)`), and that attribute
@@ -568,7 +587,6 @@ defineWebComponent<GroupProps, GroupEvents>('kai-resizable', {
 export function reflectItemConfig(
   element: HTMLElement,
   props: { readonly size?: string; readonly min?: string; readonly max?: string },
-  flag: (name: string) => boolean,
 ) {
   const norm = (v: unknown): string | null => (v == null || v === '' ? null : String(v));
   const reflectString = (name: 'size' | 'min' | 'max') => {
@@ -591,11 +609,11 @@ export function reflectItemConfig(
   reflectString('size');
   reflectString('min');
   reflectString('max');
-  // Boolean: mirror the `collapsed`/`loading` precedent — a bare `locked` attribute
-  // and the IDL property are both honoured via `flag`. The parent also writes
-  // `locked` during maximize/restore; because `flag` re-derives from that same
-  // attribute state, the reflection stays self-consistent (no fight).
-  createEffect(() => { element.toggleAttribute('locked', flag('locked')); });
+  // `locked` used to be reflected here too. It is a BOOLEAN, so it now goes through
+  // `reflectFlag` in the facade body next to `collapsed` — a boolean reflected with a
+  // bare `toggleAttribute` reads back `undefined` (see WebComponentContext.reflectFlag),
+  // and `reflectFlag` is only reachable from the facade's context. What is left here is
+  // the string props, which is this helper's real subject: the drag-durability guard.
 }
 
 interface ItemProps extends Record<string, unknown> {
@@ -633,23 +651,32 @@ defineWebComponent<ItemProps>('kai-resizable-item', {
   locked: false,
   hidden: false,
   collapsed: false,
-}, (props, { element, flag }) => {
+}, (props, { element, reflectFlag }) => {
   // Reflect the reactive `collapsed` prop to the `collapsed` ATTRIBUTE the parent
   // <kai-resizable> reads (and observes). This is what makes a bare JSX boolean
   // collapse the panel at INITIAL render from any framework: component-register
   // parses `<kai-resizable-item collapsed>` to `undefined` (not `true`), and a JSX
-  // boolean sets neither `hidden` nor the IDL property — so `flag('collapsed')`
-  // (which also honours the attribute) is the reliable source, and toggleAttribute
-  // mirrors it back so the parent's readItems()/MutationObserver lay it out. Same
-  // pattern as <kai-chat>'s `loading` reflection. We touch only `collapsed`, never
-  // `hidden`, so the back-compat hidden path and maximize (which drive `hidden`)
-  // are untouched.
-  createEffect(() => { element.toggleAttribute('collapsed', flag('collapsed')); });
-  // Reflect the other config props (`size`/`min`/`max`/`locked`) property→attribute
-  // for the SAME reason — a framework that sets them as DOM properties (React et al.)
-  // would otherwise be invisible to the parent. See reflectItemConfig for the
+  // boolean sets neither `hidden` nor the IDL property — so the flag resolution
+  // (which also honours the attribute) is the reliable source, and the attribute is
+  // mirrored back so the parent's readItems()/MutationObserver lay it out. Same
+  // pattern as <kai-chat>'s `loading` reflection, and now literally the same code:
+  // `reflectFlag` also makes `el.collapsed` READ BACK, which a hand-rolled
+  // toggleAttribute effect does not (WebComponentContext.reflectFlag).
+  //
+  // We touch only `collapsed` and `locked`, never `hidden`, so the back-compat hidden
+  // path and maximize (which drive `hidden`) are untouched — see the named exemption
+  // in tests/elements/reflected-boolean-coverage.test.ts for why `hidden` is a
+  // separate decision rather than an oversight.
+  reflectFlag('collapsed');
+  // `locked` is the parent's other boolean input; the parent also writes it during
+  // maximize/restore, and because the flag resolution re-derives from that same
+  // attribute state the reflection stays self-consistent (no fight).
+  reflectFlag('locked');
+  // Reflect the STRING config props (`size`/`min`/`max`) property→attribute for the
+  // SAME reason — a framework that sets them as DOM properties (React et al.) would
+  // otherwise be invisible to the parent. See reflectItemConfig for the
   // drag-durability guard on `size`.
-  reflectItemConfig(element, props, flag);
+  reflectItemConfig(element, props);
   return (
   <>
     {/* The item host fills the panel's single grid cell (the panel stretches it on