@kitn.ai/ui 0.25.1 → 0.26.0

package/src/elements/conversation-item.tsx

@@ -0,0 +1,80 @@
+import { createSignal, onCleanup, onMount } from 'solid-js';
+import { defineWebComponent } from './define';
+import { readSlots, CONVERSATION_ITEM_SLOTS } from './slots';
+import { SlottedConversationItem } from '../components/conversation-item';
+
+interface Props extends Record<string, unknown> {
+  /** The row's identity, handed to the container's selection contract. In the
+   *  element this is the `conversation-id` attribute (host `id` is the fallback). */
+  conversationId?: string;
+  /** Selected state. Reflected as `aria-current` on the row body and a
+   *  `data-active` styling hook on the row; the container drives it from its
+   *  `activeId`. */
+  active?: boolean;
+  /** Dense single-line row padding. */
+  compact?: boolean;
+}
+
+/**
+ * `<kai-conversation-item>` — one composed row of a consumer-owned conversation
+ * loop, slotted into `<kai-conversations>`' light DOM. 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, and the
+ * accessible list/row relationship (list rows with button bodies and
+ * `aria-current` marking the active one; ratified 2026-08-20 — axe's
+ * nested-interactive and aria-required-children rules are why this is not
+ * listbox/option).
+ *
+ * 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.
+ *
+ * The item is presentational on its own: activation (click, Enter, Space)
+ * surfaces as `kai-conversation-select` on the surrounding `<kai-conversations>`,
+ * never as an event of this element.
+ */
+defineWebComponent<Props>('kai-conversation-item', {
+  conversationId: undefined,
+  active: undefined,
+  compact: undefined,
+}, (props, { element, flag, reflectFlag }) => {
+  // 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>>({});
+  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 (sibling restructure, ratified 2026-08-20):
+    // 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
+    // roving tabindex live on the shadow BODY (`data-kai-item-body`), which the
+    // container's controller targets. An authored role wins.
+    if (!element.hasAttribute('role')) element.setAttribute('role', 'listitem');
+  });
+
+  // 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
+      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 (F-10): 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 (spec 2026-08-20 § 2a): 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.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.
 }

package/src/elements/diagnostic-events.ts

@@ -0,0 +1,114 @@
+// 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;