@kitn.ai/ui 0.20.1 → 0.22.0

package/src/elements/composer.tsx

@@ -31,7 +31,7 @@ export function parseKaiTriggerItemElement(n: Element, char: string, kind: strin
 }
 
 interface Props extends Record<string, unknown> {
-  /** Controlled value — string or a full ComposerDoc (set as JS property). */
+  /** Controlled value: a string or a full ComposerDoc (set as JS property). */
   value?: string | ComposerDoc;
   /** Placeholder text shown when the composer is empty. */
   placeholder?: string;
@@ -43,9 +43,9 @@ interface Props extends Record<string, unknown> {
   maxHeight?: number | string;
   /** Whether pressing Enter (without Shift) submits. Default true. */
   submitOnEnter?: boolean;
-  /** Trigger definitions — set as a JS property. */
+  /** Trigger definitions. Set as a JS property. */
   triggers?: TriggerDef[];
-  /** Keyword highlight rules — set as a JS property. */
+  /** Keyword highlight rules. Set as a JS property. */
   highlights?: HighlightRule[];
   /** Default icon per entity kind (kind → image URL/data-URI) for items without
    *  their own `icon`. Overrides the built-in agent/plugin glyphs. JS property. */
@@ -67,7 +67,7 @@ interface Events {
   /** The active trigger was dismissed (Escape, space, or outside click). */
   'kai-trigger-close': Record<string, never>;
   /** The composer gained focus. `focus`/`blur` are NOT composed natively, so they
-   *  don't escape the shadow root — these re-expose them on the host. (For
+   *  don't escape the shadow root; these re-expose them on the host. (For
    *  `keydown`/`paste`/`focusin`/`focusout`, listen NATIVELY on `<kai-composer>`:
    *  they're composed and already cross the shadow boundary.) */
   'kai-focus': { originalEvent: FocusEvent };
@@ -100,7 +100,7 @@ defineWebComponent<Props, Events>('kai-composer', {
   let controller: ComposerController | undefined;
   expose({
     /** Focus the editable element. `focus`/`blur` are NOT composed natively, so a
-     *  host-level focus() can't reach the editable inside the shadow root — this is
+     *  host-level focus() can't reach the editable inside the shadow root. This is
      *  the only way to focus the composer programmatically. */
     focus: (options?: FocusOptions) => controller?.focus(options),
     /** Blur the editable element. */
@@ -108,9 +108,9 @@ defineWebComponent<Props, Events>('kai-composer', {
     /** Empty the composer to a blank doc (resets the internal value + history
      *  baseline; fires kai-value-change). */
     clear: () => controller?.clear(),
-    /** Submit the current content programmatically — same path as Enter (fires
-     *  kai-submit). Named `send`, not `submit`, to match the shared vocabulary and
-     *  avoid any submit collision. */
+    /** Submit the current content programmatically, on the same path as Enter
+     *  (fires kai-submit). Named `send`, not `submit`, to match the shared
+     *  vocabulary and avoid any submit collision. */
     send: () => controller?.send(),
     /** Insert an atomic entity pill (skill/agent/plugin) at the caret without
      *  typing a trigger (fires kai-entity-add). */

package/src/elements/confirm-card.tsx

@@ -6,13 +6,13 @@ interface Props extends Record<string, unknown> {
   /** The confirm definition (the CardEnvelope.data). Set as a JS PROPERTY:
    *  `el.data = { body, tone, actions:[…] }`. Import `ConfirmCardData` from
    *  `@kitn.ai/ui` for the full shape. */
-  data?: Record<string, unknown>;
+  data?: ConfirmCardData;
   /** Stable card id correlating every emitted CardEvent. Attribute: `card-id`. */
   cardId?: string;
   /** Heading rendered in the card chrome (= CardEnvelope.title). Attribute: `heading`. */
   heading?: string;
-  /** Focus the default action on mount (off by default — no focus-stealing).
-   *  Attribute: `autofocus`. */
+  /** Focus the default action on mount (off by default, so nothing steals
+   *  focus). Attribute: `autofocus`. */
   autofocus?: boolean;
   /** Set when the user resolved this card; renders the read-only view. Property:
    *  `el.resolution = { kind:'action', action:'…' }`. */
@@ -48,22 +48,22 @@ defineWebComponent<Props>(
     // `dismiss`/`reopen`).
     let controller: ConfirmController | undefined;
     expose({
-      /** Focus the default action button (or the first action if none is default) —
-       *  the same target `autofocus` focuses on mount, but on demand. */
+      /** Focus the default action button (or the first action if none is default).
+       *  The same target `autofocus` focuses on mount, but on demand. */
       focus: (options?: FocusOptions) => controller?.focus(options),
-      /** Activate an action by id — emits the `action` verb on kai-card and resolves
+      /** Activate an action by id: emits the `action` verb on kai-card and resolves
        *  the card (single-shot). With no id, invokes the default action. */
       confirm: (actionId?: string) => controller?.confirm(actionId),
-      /** Trigger the dismiss path — emits `dismiss` on kai-card and optimistically
+      /** Trigger the dismiss path: emits `dismiss` on kai-card and optimistically
        *  collapses the card to its re-openable stub. */
       dismiss: () => controller?.dismiss(),
-      /** Re-open a dismissed card from its stub — emits `reopen` on kai-card. */
+      /** Re-open a dismissed card from its stub: emits `reopen` on kai-card. */
       reopen: () => controller?.reopen(),
     });
 
     return (
       <ConfirmCard
-        data={props.data as ConfirmCardData | undefined}
+        data={props.data}
         cardId={props.cardId ?? (element.id || 'kai-confirm')}
         heading={props.heading}
         autofocus={flag('autofocus')}

package/src/elements/context-meter.tsx

@@ -16,27 +16,13 @@ import {
   DEFAULT_DANGER_THRESHOLD,
   type ContextSeverity,
 } from '../components/context';
-
-interface ContextUsage {
-  /** Tokens consumed so far in the context window (drives the meter fill). */
-  usedTokens: number;
-  /** The model's total context-window size in tokens. */
-  maxTokens: number;
-  /** Tokens attributed to the prompt/input, shown in the breakdown. */
-  inputTokens?: number;
-  /** Tokens attributed to the generated output, shown in the breakdown. */
-  outputTokens?: number;
-  /** Tokens attributed to reasoning/thinking, shown when present. */
-  reasoningTokens?: number;
-  /** Tokens served from prompt cache, shown when present. */
-  cacheTokens?: number;
-  /** Estimated cost in dollars for this usage, shown in the footer. */
-  estimatedCost?: number;
-}
+// Public shape of the `context` prop; lives in ./element-data-types so the ROOT
+// entry can re-export it (see that file's header).
+import type { KaiContextUsage } from './element-data-types';
 
 interface Props extends Record<string, unknown> {
   /** Token-usage data. Set as a JS property. */
-  context?: ContextUsage;
+  context?: KaiContextUsage;
   /**
    * Fraction (0–1) above which the meter turns yellow.
    * Defaults to `0.7` (70%).

package/src/elements/conversation-list.tsx

@@ -6,13 +6,18 @@ import { ConversationList, CollapsedRail, type ConversationListController } from
 import type { ConversationGroup, ConversationSummary, ConversationScope } from '../types';
 
 interface Props extends Record<string, unknown> {
-  /** Pre-bucketed conversation groups (e.g. "Today", "Yesterday"), each with its
-   *  own conversations. Use this when you want to control the grouping/headers
-   *  yourself; otherwise pass a flat `conversations` array. Set as a JS property. */
-  groups: ConversationGroup[];
-  /** A flat list of conversation summaries; the component buckets them by recency
-   *  for you. Ignored when `groups` is provided. Set as a JS property. */
-  conversations: ConversationSummary[];
+  /** The list's section headers (`{ id, name, sortOrder, createdAt }`), rendered
+   *  in array order. A group carries no conversations of its own; it is matched
+   *  against `conversations` by id, so the two props are complementary rather
+   *  than alternatives. Omit for an ungrouped list. Set as a JS property. */
+  groups?: ConversationGroup[];
+  /** Every conversation the list renders, flat. Each one is filed under the group
+   *  whose `id` equals its `groupId`; one with no `groupId`, or with a `groupId`
+   *  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. */
+  conversations?: ConversationSummary[];
   /** The id of the currently-open conversation, highlighted in the list. */
   activeId?: string;
   /** Controlled collapsed state. Set as a JS property (`el.collapsed = true`) to
@@ -115,7 +120,7 @@ defineWebComponent<Props, Events>('kai-conversations', {
     /** Clear the internal search query (resets the list filter) and fire
      *  kai-search with an empty string. */
     clear: () => controller?.clearSearch(),
-    /** Programmatically select a conversation by id — mirror of the
+    /** Programmatically select a conversation by id. The mirror of the
      *  kai-conversation-select event (a convenience over driving `activeId`). */
     select: (id: string) => dispatch('kai-conversation-select', { id }),
     /** Collapse the rail to its floating reopen button (fires `kai-collapse-toggle`). */
@@ -132,7 +137,7 @@ defineWebComponent<Props, Events>('kai-conversations', {
       fallback={<CollapsedRail onExpand={() => setCollapsedTo(false)} />}
     >
       <ConversationList
-        groups={props.groups}
+        groups={props.groups ?? []}
         conversations={allConversations()}
         activeId={props.activeId}
         onSelect={(id) => dispatch('kai-conversation-select', { id })}

package/src/elements/default-input.tsx

@@ -16,6 +16,32 @@ import {
 } from '../components/attachments';
 import { actionIcon } from '../ui/action-icons';
 import type { CustomAction } from './chat-types';
+// The LEAF module, deliberately not the `../wire` barrel: this needs the media
+// declaration, and importing the barrel would pull the whole stream adapter into
+// the elements bundle for a table of strings. Sharing the module itself (rather
+// than copying the list into the composer) is the entire point -- a second list
+// here is the drift this design exists to prevent.
+import { resolveMediaPolicy, type MediaTypeFilter } from '../wire/media-types';
+// Also a leaf, and imported for the same reason: when the browser cannot name a
+// file, the question "can this be sent?" is answered by decoding its bytes, and
+// this module is where that decode already lives. Asking IT rather than growing
+// a second decoder here is what keeps the composer's answer and the encoder's
+// answer the same answer, byte for byte, instead of two that agree today.
+import { classifyAttachment } from '../wire/files';
+
+/** One file the composer refused, as facts rather than as a message. The kit
+ *  says what happened; the application decides what the user reads. */
+export interface RejectedAttachment {
+  filename: string;
+  /** The browser's media type for the file, or `''` when it could not tell. An
+   *  empty one is not by itself why a file was rejected: an unnamed file is
+   *  decided by decoding its bytes, so `''` here means the decode is what said
+   *  no (binary), or that your `accept` left no text type for it to land in. */
+  mediaType: string;
+  /** `'filtered'` = this kit could have sent it, your `accept` excluded it.
+   *  `'unsupported'` = no API takes this as message content at all. */
+  reason: 'filtered' | 'unsupported';
+}
 
 export interface DefaultPromptInputProps {
   /** String = controlled text mirror; ComposerDoc = a seed that pre-populates pills. */
@@ -31,14 +57,27 @@ export interface DefaultPromptInputProps {
    *  `onAttachmentsChange` is provided (e.g. when a `+` menu already covers
    *  file-attach). Defaults to `true`. */
   attach?: boolean;
+  /** Which attachment media types the user may stage, in HTML `accept` syntax
+   *  (`'image/*,application/pdf'`). Omitted means no filter, exactly as before.
+   *
+   *  NARROWED BY WHAT THE ENCODERS CAN SEND: `'image/*'` here resolves to the
+   *  four image formats both APIs actually accept, not to every image type the
+   *  OS will offer. It is the same string, resolved by the same function against
+   *  the same declaration, as `toOpenAIMessages(msgs, { accept })` -- so a file
+   *  the picker allows is a file the wire can carry. */
+  accept?: MediaTypeFilter;
+  /** Files that were dropped because `accept` excluded them. Carries the facts
+   *  (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 Voice (Mic) button in the left toolbar; calls `onVoice`. */
   voice?: boolean;
   /** Send-button visibility. `'always'` (default) always shows it; `'auto'` shows
-   *  it only when there's text/attachments (an empty composer hides it — Enter
-   *  still submits). To hide it entirely (Enter-only), it's pure CSS:
-   *  `::part(send){display:none}` — no prop needed. Restyle via `::part(send)`.
+   *  it only when there's text/attachments (an empty composer hides it, though
+   *  Enter still submits). To hide it entirely (Enter-only), it's pure CSS:
+   *  `::part(send){display:none}`, no prop needed. Restyle via `::part(send)`.
    *  The Stop button (stoppable + loading) is unaffected. */
   submit?: 'always' | 'auto';
   onValueChange: (v: string) => void;
@@ -64,7 +103,23 @@ export interface DefaultPromptInputProps {
   onComposerChange?: (change: ComposerChange) => void;
 }
 
-function fileToAttachment(file: File): AttachmentData {
+/** The staged file as a `data:` URI.
+ *
+ *  NOT `URL.createObjectURL`. An object URL resolves only inside the tab that
+ *  minted it, so it renders a perfect thumbnail here and is meaningless to
+ *  anything downstream — `toOpenAIMessages` / `toAnthropicMessages` refuse it,
+ *  and before they refused it the attachment reached the model as nothing at
+ *  all. A data URI previews identically and is the one form both providers
+ *  actually take. */
+const readAsDataUrl = (file: File): Promise<string> =>
+  new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onload = () => resolve(String(reader.result));
+    reader.onerror = () => reject(reader.error ?? new Error(`Could not read ${file.name}`));
+    reader.readAsDataURL(file);
+  });
+
+async function fileToAttachment(file: File): Promise<AttachmentData> {
   const id =
     typeof crypto !== 'undefined' && crypto.randomUUID
       ? crypto.randomUUID()
@@ -74,7 +129,9 @@ function fileToAttachment(file: File): AttachmentData {
     type: 'file',
     filename: file.name,
     mediaType: file.type || undefined,
-    url: file.type.startsWith('image/') ? URL.createObjectURL(file) : undefined,
+    // EVERY file, not just images. A document used to get no `url` at all,
+    // which left it unencodable for exactly the same reason a blob: URL is.
+    url: await readAsDataUrl(file),
   };
 }
 
@@ -83,9 +140,67 @@ export function DefaultPromptInput(props: DefaultPromptInputProps) {
   const attachments = () => props.attachments ?? [];
   const canAttach = () => !!props.onAttachmentsChange;
 
-  const addFiles = (files: FileList | null) => {
+  // The SAME resolver the encoders call, on the same declaration. Recomputed
+  // reactively so a host that swaps `accept` at runtime moves the picker hint
+  // and the filter together.
+  const mediaPolicy = () => resolveMediaPolicy({ accept: props.accept });
+
+  const addFiles = async (files: FileList | null) => {
     if (!files?.length || !props.onAttachmentsChange) return;
-    props.onAttachmentsChange([...attachments(), ...Array.from(files).map(fileToAttachment)]);
+
+    // The `accept` ATTRIBUTE below is only a hint — every OS dialog offers an
+    // "All Files" escape, and it does not apply to drag-and-drop at all. So the
+    // filter that actually holds is this one, in JS, on the files as staged.
+    const policy = mediaPolicy();
+    const picked = Array.from(files);
+    // No `accept` means no filtering, which is what every existing consumer gets
+    // today. Opting in is what turns the picker into a guarantee.
+    const decisions = picked.map((file) =>
+      props.accept === undefined ? undefined : policy.decide(file.type),
+    );
+    // Read a file when its media type says yes, and ALSO when its media type
+    // says nothing at all: `undetermined` means the browser could not name it,
+    // and the only honest way to answer is to look at the bytes. Reading is the
+    // cost of that answer, so it is spent only on files that could still be
+    // staged — a file the filter already rejected is never read.
+    const needsBytes = (d: (typeof decisions)[number]): boolean =>
+      d === undefined || d.status === 'allowed' || d.status === 'undetermined';
+    // One parallel pass, index-aligned with `picked`, so the staged order is the
+    // PICK order rather than whichever file finished reading first.
+    const read = await Promise.all(
+      picked.map((file, i) => (needsBytes(decisions[i]) ? fileToAttachment(file) : undefined)),
+    );
+
+    const staged: AttachmentData[] = [];
+    const rejected: RejectedAttachment[] = [];
+    picked.forEach((file, i) => {
+      const decision = decisions[i];
+      const attachment = read[i];
+      if (decision === undefined || decision.status === 'allowed') {
+        if (attachment) staged.push(attachment);
+        return;
+      }
+      if (decision.status === 'undetermined') {
+        // The bytes are in hand now, so the encoder can answer for real. Its
+        // verdict IS the composer's verdict: staging anything it would refuse is
+        // the exact defect (#186) this whole design exists to prevent.
+        if (attachment && classifyAttachment(attachment, policy).status === 'encodable') {
+          staged.push(attachment);
+        } else {
+          // Not `filtered`: the kit could not encode this either, so pointing
+          // the developer at their own `accept` would send them the wrong way.
+          rejected.push({ filename: file.name, mediaType: file.type, reason: 'unsupported' });
+        }
+        return;
+      }
+      rejected.push({ filename: file.name, mediaType: file.type, reason: decision.status });
+    });
+
+    if (rejected.length > 0) props.onAttachmentsRejected?.(rejected);
+    if (staged.length === 0) return;
+    // Re-read `attachments()` AFTER the await — a second drop while these were
+    // being read would otherwise be overwritten by this call's stale snapshot.
+    props.onAttachmentsChange?.([...attachments(), ...staged]);
   };
   const removeAttachment = (id: string) =>
     props.onAttachmentsChange?.(attachments().filter((a) => a.id !== id));
@@ -156,8 +271,16 @@ export function DefaultPromptInput(props: DefaultPromptInputProps) {
                 type="file"
                 multiple
                 class="hidden"
+                // Derived from the same policy as the filter above, never spelled
+                // out again. `accept="image/*"` narrows to the image formats the
+                // wire can actually carry, so the OS dialog greys out the SVG
+                // that would otherwise 400 at request time.
+                accept={props.accept === undefined ? undefined : mediaPolicy().accept}
                 onChange={(e) => {
-                  addFiles(e.currentTarget.files);
+                  // Reading is async now, so this is deliberately not awaited.
+                  // `addFiles` captures the FileList synchronously, before its
+                  // first await, so clearing the input below cannot race it.
+                  void addFiles(e.currentTarget.files);
                   e.currentTarget.value = ''; // allow re-picking the same file
                 }}
               />

package/src/elements/define.tsx

@@ -96,6 +96,147 @@ function toAttr(name: string): string {
   return name.replace(/([A-Z])/g, '-$1').toLowerCase();
 }
 
+/**
+ * Every property name the built-in element prototype chain exposes as an ACCESSOR
+ * — `role`, `hidden`, `autofocus`, `dir`, `title`, `className`, … — i.e. the
+ * reflected IDL attributes plus the handful of read-only accessors. Methods
+ * (`focus`, `append`) are plain data properties and are deliberately not included:
+ * assigning over one shadows it on the instance but destroys nothing on the DOM.
+ *
+ * DERIVED, not listed. A hand-written list is a list someone has to remember to
+ * extend: the collision set is (this element's prop names) × (whatever the browser
+ * reflects), and both sides move — the kit adds props, and the platform keeps
+ * adding globals (`inert`, `popover`, `writingSuggestions` are all recent). Reading
+ * it off the live prototype chain means a prop that starts colliding tomorrow is
+ * protected the day it lands, in whichever engines have shipped the accessor,
+ * without a code change. It also self-limits: in an engine that has NOT shipped a
+ * given accessor (jsdom has no `autofocus`) the name is simply not a collision
+ * there, which is exactly right.
+ *
+ * Computed once — the chain does not change at runtime.
+ */
+let globalAccessorNames: Set<string> | undefined;
+export function reflectedGlobalPropNames(): Set<string> {
+  if (globalAccessorNames) return globalAccessorNames;
+  const names = new Set<string>();
+  let proto: object | null =
+    typeof HTMLElement === 'undefined' ? null : (HTMLElement.prototype as object);
+  while (proto && proto !== Object.prototype) {
+    for (const [name, descriptor] of Object.entries(Object.getOwnPropertyDescriptors(proto))) {
+      if (descriptor.get || descriptor.set) names.add(name);
+    }
+    proto = Object.getPrototypeOf(proto) as object | null;
+  }
+  globalAccessorNames = names;
+  return names;
+}
+
+/**
+ * Replace inherited reflected accessors with plain, non-reflecting per-instance
+ * stores on this element class's prototype. Setting the property then only STORES
+ * the value — component-register still reads it back to seed the styling prop, and
+ * later shadows this with its own (also non-reflecting) instance accessor — and it
+ * can never touch a host attribute.
+ */
+function installNonReflectingProps(proto: object, keys: readonly string[]): void {
+  for (const key of keys) {
+    const store = Symbol(`kai-prop:${key}`);
+    Object.defineProperty(proto, key, {
+      get(this: Record<symbol, unknown>) {
+        return this[store];
+      },
+      set(this: Record<symbol, unknown>, value: unknown) {
+        this[store] = value;
+      },
+      enumerable: true,
+      configurable: true,
+    });
+  }
+}
+
+/**
+ * Run `define` (solid-element's `customElement`, which calls
+ * `customElements.define` internally) with `keys` already shadowed on the element
+ * class — BEFORE the registry ever sees it.
+ *
+ * THE ORDER IS THE WHOLE POINT. `customElements.define()` synchronously upgrades
+ * every matching element the parser has already produced, and component-register's
+ * constructor runs `this[prop] = undefined` for every declared prop. If the
+ * non-reflecting accessor is installed AFTER the define call, that assignment lands
+ * on the NATIVE setter, which for a reflected IDL attribute means the author's
+ * markup is destroyed before a line of facade code runs — `undefined` coerces to
+ * `null`/`false` and the setter removes the attribute. Measured in chromium from
+ * parsed HTML (`node scripts/probe-upgrade-attribute-loss.mjs`):
+ *
+ *   <kai-message role="user">        → role attr gone, el.role "assistant",
+ *                                      the row renders as "Assistant message"
+ *   <kai-resizable-item hidden>      → hidden attr gone, el.hidden false, the
+ *                                      panel is slotted and RENDERS VISIBLE
+ *   <kai-confirm autofocus>          → autofocus attr gone, nothing focused
+ *
+ * Two of those are silent: `hidden` and `autofocus` are legitimate global
+ * attributes, so no a11y rule and no console warning fires — the value simply
+ * evaporates. Only `role` was loud enough to get noticed.
+ *
+ * WHY A TRANSIENT REGISTRY WRAP and not something tidier: the class does not exist
+ * until `register()` builds it, and `register()` defines it in the same statement.
+ * component-register can take a `BaseElement` (a prototype we control) or a
+ * `customElements`-alike (a registry we control) via its third argument — either
+ * would be cleaner — but solid-element's `customElement()` calls `register(tag,
+ * props)` with no options and forwards nothing, and `component-register` is not a
+ * declared dependency of this package, so reaching past solid-element to call
+ * `register` ourselves would ship an undeclared import to consumers. Intercepting
+ * the one `define` call is the smallest seam that exists.
+ *
+ * The wrap is synchronous, restored in a `finally`, delegates to whatever was
+ * installed (so a polyfilled or consumer-wrapped registry keeps working), acts only
+ * on OUR tag, and is re-entrancy safe: a facade that defines another element during
+ * its upgrade nests a second wrap and unwinds it in order.
+ */
+function defineWithNonReflectingProps<T>(
+  tag: string,
+  keys: readonly string[],
+  define: () => T,
+): { 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 };
+  const registry = customElements;
+  const hadOwnDefine = Object.prototype.hasOwnProperty.call(registry, 'define');
+  const inner = registry.define;
+  let handled = false;
+  let restore: (() => void) | undefined;
+  try {
+    registry.define = function (
+      this: CustomElementRegistry,
+      name: string,
+      constructor: CustomElementConstructor,
+      options?: ElementDefinitionOptions,
+    ) {
+      if (name === tag) {
+        installNonReflectingProps(constructor.prototype, keys);
+        handled = true;
+      }
+      return inner.call(this, name, constructor, options);
+    };
+    restore = () => {
+      if (hadOwnDefine) registry.define = inner;
+      else delete (registry as unknown as Record<string, unknown>).define;
+    };
+  } catch {
+    // A frozen registry (SES lockdown, a sealed polyfill, a hardened extension
+    // page): we cannot get ahead of define() there. Leave `handled` false so the
+    // caller installs on the returned class instead — the OLD, too-late timing, but
+    // registration itself still succeeds. Getting this wrong the other way would
+    // take all 80 elements down in that environment to fix three props in it.
+  }
+  try {
+    return { result: define(), handled };
+  } finally {
+    restore?.();
+  }
+}
+
 /** Underlying flag resolution; see `WebComponentContext.flag`. */
 function resolveFlag(element: HTMLElement, value: unknown, attribute: string): boolean {
   if (value === true) return true;
@@ -148,27 +289,33 @@ export function defineWebComponent<P extends Record<string, unknown>, E = Record
     }
   }
 
-  // Props that NAME a reflected global IDL accessor (today: only `role`, from
-  // ARIAMixin's Element.prototype.role). Unlike RESERVED (which throws), these are
-  // allowed as plain styling props, but they must NEVER reach the host as an
-  // attribute: kai-message uses role='user'|'assistant' to pick its layout, and
-  // those are not valid ARIA roles, so a reflected role="user" / role="assistant"
-  // fails axe's aria-roles rule. The native IDL setter reflects to an attribute
-  // whenever the property is set BEFORE connectedCallback (e.g. in a framework
-  // `ref`: `el.role = 'user'`), which is the window before component-register
-  // installs its own (non-reflecting) per-instance accessor in initializeProps. We
-  // shadow the native accessor on the element prototype with a plain non-reflecting
-  // one, so setting the property only STORES the value (component-register still
-  // reads it back for styling) and never touches a host attribute.
-  const NON_REFLECTING = ['role'];
+  // Every element gets a `theme` property/attribute. It drives a `.dark` class on
+  // an inner wrapper, which the injected kit CSS already styles — so dark mode
+  // works in standalone Shadow-DOM usage with no token duplication.
+  //
+  // The `as` annotation is load-bearing, not decoration: scripts/gen-element-api.mjs
+  // reads THIS object literal to learn which props every element gets for free, and
+  // takes each one's type and doc comment off the checker. Without it the inferred
+  // type is the literal `"auto"`. Add a universal prop here and it appears in
+  // element-meta.json, the generated .d.ts, custom-elements.json and llms-full.txt
+  // for all 79 elements, with no second list to update.
+  const defaults = {
+    /** Color mode (`auto` follows prefers-color-scheme). */
+    theme: 'auto' as 'light' | 'dark' | 'auto',
+    ...propDefaults,
+  };
 
-  // Every element gets a `theme` property/attribute: 'light' | 'dark' | 'auto'
-  // (default 'auto' = follow the OS `prefers-color-scheme`). It drives a `.dark`
-  // class on an inner wrapper, which the injected kit CSS already styles — so dark
-  // mode works in standalone Shadow-DOM usage with no token duplication.
-  const defaults = { theme: 'auto', ...propDefaults };
+  // Props that NAME a reflected global IDL accessor (today, across all 80 elements:
+  // `role` on kai-message, `hidden` on kai-resizable-item, `autofocus` on
+  // kai-confirm). Unlike RESERVED (which throws), these are legitimate domain props
+  // — `role` is the SPEAKER, `hidden` and `autofocus` mean what they say — and they
+  // stay usable, but the native accessor must not be the one that receives them.
+  // See defineWithNonReflectingProps for what the native setter does to the author's
+  // markup if it is, and why the shadowing has to be in place before the registry
+  // sees the class. RESERVED names never get here; they already threw above.
+  const shadowedProps = Object.keys(defaults).filter((key) => reflectedGlobalPropNames().has(key));
 
-  const Ctor = customElement(tag, defaults, (props: typeof defaults, options: { element: object }) => {
+  const renderFacade = (props: typeof defaults, options: { element: object }) => {
     const element = options.element as HTMLElement;
     let portalNode!: HTMLDivElement;
 
@@ -239,30 +386,18 @@ export function defineWebComponent<P extends Record<string, unknown>, E = Record
         </div>
       </>
     );
-  });
+  };
+
+  const { result: Ctor, handled } = defineWithNonReflectingProps(tag, shadowedProps, () =>
+    customElement(tag, defaults, renderFacade),
+  );
 
-  // Shadow any reflected native IDL accessor this element re-uses as a prop (see
-  // NON_REFLECTING) with a plain, non-reflecting store on the element prototype.
-  // This must live on the prototype (not the instance) so it is already in place
-  // when the value is set before connectedCallback, the window in which the native
-  // setter would otherwise reflect it to a host attribute. component-register reads
-  // the property back during initializeProps to seed the styling prop, and later
-  // shadows this with its own (also non-reflecting) per-instance accessor.
+  // Belt and braces for the one path the wrap cannot see: if `customElements.define`
+  // was never reached for this tag (a registry that defines lazily, or a future
+  // solid-element that stops calling it synchronously), install on the returned class
+  // instead. That is the OLD, too-late timing — it still protects every element
+  // constructed from here on, it just cannot rescue an already-upgraded one. Skipped
+  // in the normal case, where the accessors are already on this same prototype.
   const proto = (Ctor as unknown as { prototype?: object } | undefined)?.prototype;
-  if (proto) {
-    for (const key of NON_REFLECTING) {
-      if (!(key in defaults)) continue;
-      const store = Symbol(`kai-prop:${key}`);
-      Object.defineProperty(proto, key, {
-        get(this: Record<symbol, unknown>) {
-          return this[store];
-        },
-        set(this: Record<symbol, unknown>, value: unknown) {
-          this[store] = value;
-        },
-        enumerable: true,
-        configurable: true,
-      });
-    }
-  }
+  if (!handled && proto) installNonReflectingProps(proto, shadowedProps);
 }

package/src/elements/editable-label.tsx

@@ -3,7 +3,7 @@ import { defineWebComponent } from './define';
 import { EditableLabel } from '../ui/editable-label';
 
 interface Props extends Record<string, unknown> {
-  /** The label text — settable and reflected to the `value` attribute. Read
+  /** The label text. Settable and reflected to the `value` attribute. Read
    *  `el.value` for live state. */
   value?: string;
   /** Controlled edit state. `el.editing = true` opens the field; reflected to the
@@ -104,7 +104,22 @@ defineWebComponent<Props, Events>('kai-editable-label', {
     }
   };
 
-  expose({ edit: enter, commit, cancel });
+  expose({
+    /** Switch the label into its editing field, which autofocuses and selects the
+     *  current text. Same entry point as a user double-click, and a no-op while
+     *  `disabled`. Commit with `commit()` or by blurring, abandon with `cancel()`
+     *  or Escape. */
+    edit: enter,
+    /** Close the field and keep what was typed, exactly as blurring it does.
+     *  `kai-rename` fires only when the text actually changed, so committing an
+     *  untouched field is silent. A no-op while the field is closed. */
+    commit,
+    /** Abandon the edit, exactly as Escape does: the original text is restored,
+     *  the field closes and `kai-cancel` fires. `kai-rename` never fires, even if
+     *  the field was edited. Also works when `editing` was set programmatically
+     *  and the field has not rendered yet. */
+    cancel,
+  });
 
   return (
     <>