@kitn.ai/ui 0.25.2 → 0.27.0

package/src/elements/composer.tsx

@@ -54,7 +54,10 @@ interface Props extends Record<string, unknown> {
 
 /** Events fired by `<kai-composer>`. */
 interface Events {
-  /** The user submitted the composer (Enter or programmatic submit). */
+  /** The user submitted the composer (Enter or programmatic submit). Note the
+   *  detail carries no `attachments`; `<kai-composer>` is the bare editing
+   *  surface: no send button, toolbar, or attachments. For a drop-in composer
+   *  row with all three, reach for `<kai-prompt-input>`, which is built on this. */
   'kai-submit': { doc: ComposerDoc; text: string; entities: EntityRef[] };
   /** The content changed (fires on every input event). */
   'kai-value-change': { doc: ComposerDoc; text: string; entities: EntityRef[] };
@@ -75,6 +78,14 @@ interface Events {
   'kai-blur': { originalEvent: FocusEvent };
 }
 
+/**
+ * `<kai-composer>` — the bare editing surface: rich text, entity pills,
+ * trigger menus, Enter-to-submit, and nothing else. No send button, no
+ * toolbar, no attachments — that division is deliberate. For a drop-in chat
+ * composer with a send button, toolbar, and attachment staging, reach for
+ * `<kai-prompt-input>`, which is built on this element. Keep `<kai-composer>`
+ * when you are composing the input row yourself and want to own those pieces.
+ */
 defineWebComponent<Props, Events>('kai-composer', {
   value: undefined,
   placeholder: undefined,

package/src/elements/conversation-item.tsx

@@ -0,0 +1,120 @@
+import { createSignal, onCleanup, onMount } from 'solid-js';
+import { defineWebComponent } from './define';
+import { readSlots, CONVERSATION_ITEM_SLOTS } from './slots';
+import { SlottedConversationItem } from '../components/conversation-item';
+import { isStandaloneConversationItem, readConversationItemId } from '../components/conversation-list';
+
+interface Props extends Record<string, unknown> {
+  /** The row's identity: the `conversation-id` attribute (host `id` is the
+   *  fallback). Inside `<kai-conversations>` it is handed to the container's
+   *  selection contract (`kai-conversation-select`); standalone it is the `id`
+   *  in this element's own `kai-select` detail. */
+  conversationId?: string;
+  /** Selected state. Reflected as `aria-current` on the row body and a
+   *  `data-active` styling hook on the row; inside a container the container
+   *  drives it from its `activeId`, standalone you set it yourself. */
+  active?: boolean;
+  /** Dense single-line row padding. */
+  compact?: boolean;
+}
+
+interface Events {
+  /** STANDALONE activation only: the row was activated (click, Enter or Space on its body) while the item is NOT a
+   *  direct child of `<kai-conversations>`. `id` is the row's identity: the
+   *  `conversation-id` attribute, else the host `id`. Inside a container this
+   *  never fires: activation surfaces once, as `kai-conversation-select` on the
+   *  container. */
+  'kai-select': { id: string };
+}
+
+/**
+ * `<kai-conversation-item>` — one composed row of a consumer-owned conversation
+ * loop. Two placements, one activation event each:
+ *
+ * SLOTTED into `<kai-conversations>`' light DOM (a direct child): the consumer
+ * owns the loop (framework-native `map`, `<For>`, `v-for`); the container
+ * detects these children, skips its data rendering, and runs the parent-item
+ * contract over them — selection state flowing container to item, roving
+ * tabindex, arrow-key traversal, and the accessible list/row relationship
+ * (list rows with button bodies and `aria-current` marking the active one;
+ * axe's nested-interactive and aria-required-children
+ * rules are why this is not listbox/option). Activation (click, Enter, Space)
+ * surfaces as `kai-conversation-select` on the container, and the item itself
+ * fires nothing — no double event.
+ *
+ * STANDALONE (anywhere else — a hand-composed rail, or wrapped in another
+ * element even inside a container, since the container manages only direct
+ * children): the row activates ITSELF.
+ * Its shadow body is a tabbable `role="button"`, and click / Enter / Space
+ * fire `kai-select` on this element with `{ id }` — non-bubbling, like every
+ * `kai-*` event, so listen on the item itself. What a standalone row does NOT
+ * have is the container's LIST story: roving tabindex across rows, arrow-key
+ * traversal, and the shared `role="list"` relationship — each standalone row
+ * is an ordinary tab stop, and a hand-composed rail brings its own list
+ * semantics (or slots the rows into `<kai-conversations>` and gets them for
+ * free).
+ *
+ * Slots: the default slot is the title; `leading`, `meta` and `menu` are the
+ * named regions. The `menu` slot takes your OWN popover (rename, fork, archive
+ * live there); the element provides only the region plus focus and ARIA
+ * plumbing, never a declarative actions prop, and a click inside it never
+ * selects the row — in either placement.
+ */
+defineWebComponent<Props, Events>('kai-conversation-item', {
+  conversationId: undefined,
+  active: undefined,
+  compact: undefined,
+}, (props, { element, flag, reflectFlag, dispatch }) => {
+  // Which named regions the consumer has filled; drives the conditional
+  // wrappers so an empty region leaves no stray box behind.
+  const [slots, setSlots] = createSignal<Record<string, boolean>>({});
+  // Standalone vs container-managed, decided at mount (an item is not
+  // reparented in practice; the activation handler re-checks at event time so
+  // a row moved INTO a container can never double-fire).
+  const [standalone, setStandalone] = createSignal(false);
+  onMount(() => {
+    const read = () => setSlots(readSlots(element, CONVERSATION_ITEM_SLOTS));
+    read();
+    const observer = new MutationObserver(read);
+    observer.observe(element, { childList: true, attributes: true, subtree: true });
+    onCleanup(() => observer.disconnect());
+
+    // The HOST is the row LISTITEM:
+    // it wraps the activation body AND the consumer's tabbable menu, so it must
+    // never be the activation control itself — axe nested-interactive bans
+    // focusable descendants of a control. The button role, aria-current and the
+    // tabindex live on the shadow BODY (`data-kai-item-body`): inside a
+    // container its controller stamps them; standalone the component renders
+    // them itself. An authored role wins.
+    if (!element.hasAttribute('role')) element.setAttribute('role', 'listitem');
+
+    setStandalone(isStandaloneConversationItem(element));
+  });
+
+  // Standalone activation → the per-item `kai-select` event. The re-check at
+  // event time keeps this dead the moment the item becomes a container's direct
+  // child, so the container's `kai-conversation-select` stays the only event.
+  const activate = () => {
+    if (!isStandaloneConversationItem(element)) return;
+    dispatch('kai-select', { id: readConversationItemId(element) });
+  };
+
+  // Property and attribute stay in agreement for `active`; the body's
+  // aria-current follows it reactively (nothing is written to the host).
+  reflectFlag('active');
+
+  return (
+    <SlottedConversationItem
+      conversationId={props.conversationId as string | undefined}
+      active={flag('active')}
+      compact={flag('compact')}
+      hostSemantics
+      onActivate={standalone() ? activate : undefined}
+      leading={slots().leading ? <slot name="leading" /> : undefined}
+      meta={slots().meta ? <slot name="meta" /> : undefined}
+      menu={slots().menu ? <slot name="menu" /> : undefined}
+    >
+      <slot />
+    </SlottedConversationItem>
+  );
+});

package/src/elements/conversation-list.tsx

@@ -1,9 +1,12 @@
-import { createSignal, onMount, onCleanup, Show } from 'solid-js';
+import { createSignal, createEffect, onMount, onCleanup, Show } from 'solid-js';
 import { defineWebComponent } from './define';
 import { createControllableSignal } from '../primitives/controllable';
 import { readSlots, CONVERSATIONS_SLOTS } from './slots';
-import { ConversationList, CollapsedRail, type ConversationListController } from '../components/conversation-list';
-import type { ConversationGroup, ConversationSummary, ConversationScope } from '../types';
+import {
+  ConversationList, CollapsedRail, createConversationItemsController,
+  type ConversationListController,
+} from '../components/conversation-list';
+import type { ConversationGroup, ConversationSummary } from '../types';
 
 interface Props extends Record<string, unknown> {
   /** The list's section headers (`{ id, name, sortOrder, createdAt }`), rendered
@@ -16,7 +19,11 @@ interface Props extends Record<string, unknown> {
    *  matching no entry in `groups`, falls into a trailing "Ungrouped" section, so
    *  nothing you pass in is ever dropped. There is no recency bucketing. Set as a
    *  JS property. Omit to supply them as `<kai-conversation>` light-DOM children
-   *  instead, or for the empty state. */
+   *  instead, or for the empty state. A search query that matches nothing shows a
+   *  visible "No conversations match your search" state, distinct from the
+   *  zero-conversations empty state. Slotted `<kai-conversation-item>` children
+   *  switch the list into item mode instead: your own rows win and this array is
+   *  not rendered. */
   conversations?: ConversationSummary[];
   /** The id of the currently-open conversation, highlighted in the list. */
   activeId?: string;
@@ -28,10 +35,14 @@ interface Props extends Record<string, unknown> {
   /** Initial collapsed state when uncontrolled (default false). Use the
    *  `default-collapsed` attribute to start collapsed in plain HTML. */
   defaultCollapsed?: boolean;
+  /** Dense single-line rows (a leading dot + title, no message count). */
+  compact?: boolean;
 }
 
 interface Events {
-  /** A conversation was selected. */
+  /** A conversation was selected. The selection event in BOTH modes: a
+   *  batteries data row, or an activated `<kai-conversation-item>` child
+   *  (click, Enter or Space). */
   'kai-conversation-select': { id: string };
   /** The "New chat" button was clicked. */
   'kai-new-chat': Record<string, never>;
@@ -50,19 +61,19 @@ interface Events {
  *   - `id`       → ConversationSummary.id
  *   - `group-id` → ConversationSummary.groupId (optional)
  *   - textContent → ConversationSummary.title
- *  Required fields not expressible as HTML attributes (`scope`, `messageCount`,
- *  `lastMessageAt`, `updatedAt`) receive safe defaults so the rendered list item
- *  is fully functional with just `id` + title text.
+ *  Fields not expressible as HTML attributes are NOT fabricated: the
+ *  optional `scope` and `lastMessageAt` stay absent, and the required
+ *  `messageCount`/`updatedAt` get honest defaults — zero messages, and an empty
+ *  `updatedAt` from which no trailing relative time is derived (the epoch it
+ *  used to fabricate rendered a bogus "many days ago" on every declarative row).
  */
 export function parseKaiConversationElement(n: Element): ConversationSummary {
   return {
     id: n.getAttribute('id') ?? '',
     title: n.textContent?.trim() ?? '',
     groupId: n.getAttribute('group-id') ?? undefined,
-    scope: { type: 'collection' } as ConversationScope,
     messageCount: 0,
-    lastMessageAt: new Date(0).toISOString(),
-    updatedAt: new Date(0).toISOString(),
+    updatedAt: '',
   };
 }
 
@@ -72,17 +83,34 @@ defineWebComponent<Props, Events>('kai-conversations', {
   activeId: undefined,
   collapsed: undefined,
   defaultCollapsed: undefined,
+  compact: undefined,
 }, (props, { dispatch, element, expose, flag }) => {
   // Read declarative <kai-conversation> children from light DOM.
   // Shadow DOM with no <slot> suppresses them visually — they're invisible data carriers.
   const [slottedConversations, setSlottedConversations] = createSignal<ConversationSummary[]>([]);
+  // Item mode: light-DOM <kai-conversation-item> children
+  // mean the CONSUMER owns the loop — the container skips its data rendering and
+  // runs the parent-item contract over the hosts instead.
+  const [itemHosts, setItemHosts] = createSignal<HTMLElement[]>([]);
   // Which composition slots (header/empty/footer) the consumer has filled.
   const [slots, setSlots] = createSignal<Record<string, boolean>>({});
   onMount(() => {
     const read = () => {
       const nodes = [...element.querySelectorAll('kai-conversation')];
       setSlottedConversations(nodes.map(parseKaiConversationElement));
+      // Reference-stable: a fresh array every observer tick would re-run the
+      // sync effect (whose writes the observer sees) in a feedback loop.
+      const hosts = [...element.querySelectorAll<HTMLElement>(':scope > kai-conversation-item')];
+      setItemHosts((prev) =>
+        prev.length === hosts.length && hosts.every((h, i) => h === prev[i]) ? prev : hosts,
+      );
       setSlots(readSlots(element, CONVERSATIONS_SLOTS));
+      // Re-sync on EVERY mutation, not only membership changes: an item host
+      // that upgrades after the first sync mutates its own attributes (the
+      // facade's mount), which lands here — and its shadow body needs stamping
+      // even though the hosts array is reference-stable. sync() writes
+      // on-change only, so this cannot feed the observer a loop.
+      if (hosts.length) itemsController.sync();
     };
     read();
     const observer = new MutationObserver(read);
@@ -90,9 +118,26 @@ defineWebComponent<Props, Events>('kai-conversations', {
     onCleanup(() => observer.disconnect());
   });
 
+  const itemMode = () => itemHosts().length > 0;
+
   // Prop conversations take precedence; slotted children are appended after.
   const allConversations = () => [...(props.conversations ?? []), ...slottedConversations()];
 
+  // The parent-item contract: selection flowing container→item, roving tabindex,
+  // ARIA list-row bookkeeping — pure DOM, host-agnostic (see the controller's JSDoc in
+  // components/conversation-list.tsx). Solid context cannot cross the element
+  // boundary, so the channel is DOM traversal by construction.
+  const itemsController = createConversationItemsController({
+    getItems: itemHosts,
+    getActiveId: () => props.activeId as string | undefined,
+    onSelect: (id) => dispatch('kai-conversation-select', { id }),
+  });
+  // Re-derive the bookkeeping whenever the children change (the MutationObserver
+  // and the shadow slot's slotchange both funnel into itemHosts) or activeId moves.
+  createEffect(() => {
+    if (itemMode()) itemsController.sync();
+  });
+
   // ── Rail collapse (controlled/uncontrolled, same pattern as kai-workspace) ──
   // `collapsed` (when set) wins; otherwise the element manages its own state,
   // seeded from `defaultCollapsed`. `setCollapsedTo` always writes the internal
@@ -143,8 +188,12 @@ defineWebComponent<Props, Events>('kai-conversations', {
         onSelect={(id) => dispatch('kai-conversation-select', { id })}
         onNewChat={() => dispatch('kai-new-chat')}
         onToggleSidebar={() => { dispatch('kai-toggle-sidebar'); setCollapsedTo(true); }}
+        compact={flag('compact')}
         onSearchChange={(query) => dispatch('kai-search', { query })}
         controllerRef={(c) => (controller = c)}
+        items={itemMode() ? <slot /> : undefined}
+        itemsKeyDown={itemsController.handleKeyDown}
+        itemsClick={itemsController.handleClick}
         header={slots().header ? <slot name="header" /> : undefined}
         footer={slots().footer ? <slot name="footer" /> : undefined}
         empty={slots().empty ? <slot name="empty" /> : undefined}

package/src/elements/default-input.tsx

@@ -70,8 +70,8 @@ export interface DefaultPromptInputProps {
    *  (name, media type, reason) and renders nothing itself: what the user should
    *  see is the application's call, not the kit's. */
   onAttachmentsRejected?: (rejected: RejectedAttachment[]) => void;
-  /** Show a Search (Globe) button in the left toolbar; calls `onSearch`. */
-  search?: boolean;
+  /** Show a web-search (Globe) button in the left toolbar; calls `onWebSearch`. */
+  webSearch?: boolean;
   /** Show a Voice (Mic) button in the left toolbar; calls `onVoice`. */
   voice?: boolean;
   /** Send-button visibility. `'always'` (default) always shows it; `'auto'` shows
@@ -84,7 +84,7 @@ export interface DefaultPromptInputProps {
   onSubmit: () => void;
   onSuggestionClick: (v: string) => void;
   onAttachmentsChange?: (attachments: AttachmentData[]) => void;
-  onSearch?: () => void;
+  onWebSearch?: () => void;
   onVoice?: () => void;
   /** When `true` and `loading` is also `true`, the send button is replaced by
    *  a Stop button that calls `onStop`. */
@@ -296,7 +296,7 @@ export function DefaultPromptInput(props: DefaultPromptInputProps) {
                 <Paperclip class="size-4" />
               </Button>
             </Show>
-            <Show when={props.search}>
+            <Show when={props.webSearch}>
               <Button
                 type="button"
                 variant="outline"
@@ -304,7 +304,7 @@ export function DefaultPromptInput(props: DefaultPromptInputProps) {
                 class="rounded-full gap-1"
                 aria-label="Search the web"
                 disabled={props.disabled}
-                onClick={() => props.onSearch?.()}
+                onClick={() => props.onWebSearch?.()}
               >
                 <Globe class="size-4" />
                 Search

package/src/elements/define-entry.ts

@@ -0,0 +1,12 @@
+/**
+ * @kitn.ai/ui/define — the facade seam, public.
+ *
+ * The construct engine's GENERATED projects (and any consumer who wants to wrap
+ * a pure-Solid interior as one self-registering element) import from here. Its
+ * own subpath rather than ./solid because define.tsx carries ELEMENT_CSS (the
+ * full compiled kit CSS) and solid-element — weight ./solid consumers must not
+ * pay. SSR-safe by construction: defineWebComponent no-ops without
+ * customElements (see define.tsx).
+ */
+export { defineWebComponent } from './define';
+export type { WebComponentContext } from './define';

package/src/elements/define.tsx

@@ -1,7 +1,8 @@
 import { customElement } from 'solid-element';
 import { ChatConfig } from '../primitives/chat-config';
 import { ELEMENT_CSS } from './css';
-import { createSignal, onCleanup, Show, type JSX } from 'solid-js';
+import { elementDiagnosticsWanted, installElementDiagnostics } from './element-diagnostics';
+import { createEffect, createSignal, onCleanup, Show, type JSX } from 'solid-js';
 
 /**
  * Shared constructable stylesheet, built once and adopted by every element's
@@ -78,6 +79,33 @@ export interface WebComponentContext<E = Record<string, unknown>> {
    * convention). Methods are attached when the facade renders (on element upgrade).
    */
   expose: (methods: Record<string, (...args: never[]) => unknown>) => void;
+  /**
+   * Reflect a boolean prop to its host attribute AND make that prop read back what
+   * was set. Use this instead of hand-rolling
+   * `createEffect(() => element.toggleAttribute('x', flag('x')))`.
+   *
+   * WHY IT IS ONE CALL AND NOT TWO. The reflection is what BREAKS the read-back, so
+   * the fix has to be attached to it or it gets forgotten — and it was, three times.
+   * `toggleAttribute(name, true)` sets the attribute to the EMPTY STRING;
+   * component-register's `attributeChangedCallback` then writes the prop back as
+   * `this[name] = parseAttributeValue("")`, and `parseAttributeValue` returns
+   * `undefined` for the empty string. So a reflected flag became write-only:
+   * `el.loading = true` left `el.loading === undefined` while `[loading]` was on the
+   * host. The element kept BEHAVING correctly, because `flag()` reads the attribute —
+   * which is precisely why nobody noticed until a consumer tried to read the property
+   * back (findings G-05).
+   *
+   * What this installs is an instance-level wrapper around the accessor
+   * component-register already created, coercing every incoming value through the
+   * same `flag()` policy (`resolveFlag`) — so the `undefined` write-back resolves to
+   * the attribute that caused it, and the property and the attribute can no longer
+   * disagree. It delegates to the underlying setter, so reactivity is untouched.
+   *
+   * `source` overrides where the ON/OFF value comes from, for an element whose truth
+   * is an internal controller rather than the prop (see `wireDisclosure`). Returning
+   * `undefined` from it means "not ready, leave the attribute alone".
+   */
+  reflectFlag: (name: string, source?: () => boolean | undefined) => void;
   /**
    * Whether the element should currently render its dark-mode look --
    * exactly the SAME resolved value that already drives the `.dark` class
@@ -197,10 +225,22 @@ function defineWithNonReflectingProps<T>(
   tag: string,
   keys: readonly string[],
   define: () => T,
+  /**
+   * Anything else that must be on the prototype BEFORE the registry sees the
+   * class. Today that is the element-layer diagnostics, and it needs this seam
+   * for a reason that is adjacent to the one above but not the same: `define()`
+   * SNAPSHOTS the lifecycle callbacks (`connectedCallback`,
+   * `attributeChangedCallback`, …) off the prototype into the custom-element
+   * definition, and the browser invokes the snapshot. A wrapper installed
+   * afterwards is present on the prototype, passes `hasOwnProperty`, and is
+   * never called. See `installElementDiagnostics`.
+   */
+  alsoPatch?: (proto: object) => void,
 ): { result: T; handled: boolean } {
-  // `handled` = nothing more for the caller to do. With no colliding props there is
-  // nothing to install at all, so that case is trivially handled.
-  if (keys.length === 0) return { result: define(), handled: true };
+  // `handled` = nothing more for the caller to do. With no colliding props and
+  // nothing else to patch there is nothing to install at all, so that case is
+  // trivially handled.
+  if (keys.length === 0 && !alsoPatch) return { result: define(), handled: true };
   const registry = customElements;
   const hadOwnDefine = Object.prototype.hasOwnProperty.call(registry, 'define');
   const inner = registry.define;
@@ -214,7 +254,8 @@ function defineWithNonReflectingProps<T>(
       options?: ElementDefinitionOptions,
     ) {
       if (name === tag) {
-        installNonReflectingProps(constructor.prototype, keys);
+        if (keys.length) installNonReflectingProps(constructor.prototype, keys);
+        alsoPatch?.(constructor.prototype);
         handled = true;
       }
       return inner.call(this, name, constructor, options);
@@ -237,6 +278,76 @@ function defineWithNonReflectingProps<T>(
   }
 }
 
+/**
+ * Marks a setter as one of ours, so the wrap is idempotent WITHOUT being permanent.
+ *
+ * The mark goes on the setter function rather than on the element, and that is the
+ * whole subtlety: component-register installs a FRESH instance accessor from
+ * `initializeProps` on every (re)connect after a release, which throws our wrapper
+ * away. An element-level "already done" flag would then skip re-wrapping and the
+ * property would quietly go write-only again on the second mount. An unmarked setter
+ * is by definition a new one, so it gets wrapped again.
+ */
+const FLAG_READ_BACK = Symbol('kai-flag-read-back');
+
+/**
+ * Wrap the instance accessor component-register created for `name` so every value
+ * written to it — a consumer's assignment, or the `undefined` write-back that
+ * `attributeChangedCallback` performs after a `toggleAttribute` — is resolved through
+ * the same policy `flag()` uses.
+ *
+ * TIMING. This must run from the facade body, i.e. during `connectedCallback` AFTER
+ * `initializeProps`, and that is not a detail: `initializeProps` harvests any value
+ * set on the element BEFORE upgrade (`value = element[key]`) and only then installs
+ * the accessor. Wrapping earlier (on the prototype, the way `installNonReflectingProps`
+ * does) would be shadowed by that accessor and would also sit in front of the harvest —
+ * the same class of defect `define-upgrade-ordering.test.tsx` pins for attributes.
+ */
+function installFlagReadBack(element: HTMLElement, name: string, attribute: string): void {
+  const inner = Object.getOwnPropertyDescriptor(element, name);
+  if (!inner?.get || !inner.set) {
+    // Reached only if `name` is not a declared prop of this element — a typo, or a
+    // facade reflecting something it never declared. Warn rather than no-op silently;
+    // a silent skip here would look exactly like a working read-back.
+    console.warn(
+      `reflectFlag("${name}"): no such declared prop on <${element.localName}> — ` +
+      `the attribute will still reflect, but the property will not read back.`,
+    );
+    return;
+  }
+  const { get, set } = inner;
+  if ((set as { [FLAG_READ_BACK]?: true })[FLAG_READ_BACK]) return;
+
+  const wrapped = function (this: HTMLElement, value: unknown) {
+    set.call(this, resolveFlag(this, value, attribute));
+  } as ((value: unknown) => void) & { [FLAG_READ_BACK]?: true };
+  wrapped[FLAG_READ_BACK] = true;
+
+  Object.defineProperty(element, name, {
+    get,
+    set: wrapped,
+    enumerable: inner.enumerable ?? true,
+    configurable: true,
+  });
+
+  // Seed, but ONLY upwards. The value sitting in the prop store right now may already
+  // be the broken one: `<el loading>` parses to `undefined` in `initializeProps`
+  // exactly as it does in the write-back, so without this the bare-attribute case
+  // would still read back `undefined` until something else wrote to the prop.
+  //
+  // WHY NOT SEED `false` TOO. Writing `false` over an `undefined` would look tidier
+  // and is wrong: for props declared with an `undefined` default, `undefined` MEANS
+  // "the consumer has not set this", and at least one caller depends on telling that
+  // apart from an explicit `false` — `wireDisclosure` seeds from `defaultOpen` only
+  // while `open` is unset, so a blanket `false` seed would clobber
+  // `<el default-open>` on every mount. Promoting only a present attribute to `true`
+  // fixes the read-back without inventing an opinion the author never expressed.
+  const current = get.call(element);
+  if (typeof current !== 'boolean' && resolveFlag(element, current, attribute)) {
+    wrapped.call(element, true);
+  }
+}
+
 /** Underlying flag resolution; see `WebComponentContext.flag`. */
 function resolveFlag(element: HTMLElement, value: unknown, attribute: string): boolean {
   if (value === true) return true;
@@ -329,6 +440,21 @@ export function defineWebComponent<P extends Record<string, unknown>, E = Record
     const flag = (name: string) =>
       resolveFlag(element, (props as Record<string, unknown>)[name], toAttr(name));
 
+    // Reflect a boolean prop to its attribute and keep the property readable. See
+    // WebComponentContext.reflectFlag for the defect this exists to close.
+    const reflectFlag: WebComponentContext<E>['reflectFlag'] = (name, source) => {
+      const attribute = toAttr(name);
+      installFlagReadBack(element, name, attribute);
+      createEffect(() => {
+        const on = source ? source() : flag(name);
+        // `undefined` means the caller's source is not ready yet (a controller a
+        // primitive has not handed up). Leave the author's attribute alone rather
+        // than writing a guessed OFF over it.
+        if (on === undefined) return;
+        element.toggleAttribute(attribute, on);
+      });
+    };
+
     // Attach imperative methods onto the host instance. See WebComponentContext.expose.
     // Uses defineProperty so a method can shadow an inherited getter-only accessor
     // (e.g. `focus`/`blur`) which a plain assignment would throw on. A method name
@@ -381,15 +507,39 @@ export function defineWebComponent<P extends Record<string, unknown>, E = Record
         <div classList={{ dark: isDark() }} style={{ display: 'contents', color: 'var(--color-foreground)' }}>
           <div ref={portalNode} />
           <ChatConfig portalMount={portalNode}>
-            {Facade(props as unknown as P, { element, dispatch, flag, expose, dark: isDark })}
+            {Facade(props as unknown as P, {
+              element,
+              dispatch,
+              flag,
+              reflectFlag,
+              expose,
+              dark: isDark,
+            })}
           </ChatConfig>
         </div>
       </>
     );
   };
 
-  const { result: Ctor, handled } = defineWithNonReflectingProps(tag, shadowedProps, () =>
-    customElement(tag, defaults, renderFacade),
+  // Element-layer diagnostics: report the three `kai-` contract violations that
+  // are otherwise silent (an array or object prop set as an HTML attribute, the
+  // same array reference handed back, a new array of the same item objects).
+  //
+  // HERE because this function is the single choke point — every kai-* element
+  // registers through it, which `elements/slots.test.ts` already enforces — so
+  // one call covers every element with no per-element work and no second list.
+  //
+  // Through the pre-define seam, not after the fact, because the registry
+  // snapshots lifecycle callbacks at definition time; see `alsoPatch` above.
+  // `elementDiagnosticsWanted` is asked first so a tag with no non-scalar prop
+  // (37 of the 80) does not even pay for the registry interception.
+  const wantsDiagnostics = elementDiagnosticsWanted(tag);
+
+  const { result: Ctor, handled } = defineWithNonReflectingProps(
+    tag,
+    shadowedProps,
+    () => customElement(tag, defaults, renderFacade),
+    wantsDiagnostics ? (proto) => installElementDiagnostics(tag, proto) : undefined,
   );
 
   // Belt and braces for the one path the wrap cannot see: if `customElements.define`
@@ -400,4 +550,14 @@ export function defineWebComponent<P extends Record<string, unknown>, E = Record
   // in the normal case, where the accessors are already on this same prototype.
   const proto = (Ctor as unknown as { prototype?: object } | undefined)?.prototype;
   if (!handled && proto) installNonReflectingProps(proto, shadowedProps);
+
+  // NOTE the diagnostics have no equivalent late fallback, and must not get one.
+  // The non-reflecting props still work when installed late (they only have to
+  // beat the NEXT constructor); the diagnostics do not, because the registry has
+  // already snapshotted the lifecycle callbacks it will invoke. Installing them
+  // here would produce a wrapper that is visibly present and never called —
+  // which is worse than not installing it, since it would read as coverage. So
+  // in the one environment the pre-define seam cannot reach (a frozen registry:
+  // SES lockdown, a sealed polyfill), element diagnostics are simply absent, and
+  // every other element behaviour is unaffected.
 }