@kitn.ai/ui 0.25.2 → 0.26.0

package/src/ui/dropdown.tsx

@@ -37,6 +37,63 @@ const useDropdown = () => {
 // a parent's querySelectorAll scoped to its own menu never reaches sub items.
 const ITEM_SELECTOR = '[role="menuitem"]:not([aria-disabled="true"]), [role="menuitemcheckbox"]:not([aria-disabled="true"]), [role="menuitemradio"]:not([aria-disabled="true"])';
 
+/**
+ * The roving-focus set, in FLAT-TREE order.
+ *
+ * ★ NOT `querySelectorAll`, and the difference is the whole point: a `<slot>` in the
+ * shadow tree contains NONE of the light-DOM nodes it projects, so a plain query
+ * returns zero items for any facade whose rows are SLOTTED (`<kai-dropdown>`) and
+ * ArrowUp/Down, Home/End and typeahead all reach nothing. The items-tree facades
+ * (`kai-menu`, `kai-model-switcher`, `kai-scope-picker`) render their rows INTO the
+ * shadow tree, so both spellings agree for them — which is exactly why this went
+ * unnoticed until a slotted menu body existed.
+ *
+ * Same class as `hasFocusableChild` in ./hover-card.tsx, which asks the boolean
+ * version of this question. This one needs the ORDER as well, so it walks the tree
+ * and splices each slot's assigned elements in AT THE SLOT'S POSITION rather than
+ * appending them; a menu may mix rendered and slotted rows. `flatten: true` follows
+ * a slot assigned to another slot.
+ *
+ * Scope is unchanged: submenu content is portaled to a SIBLING node, so a parent's
+ * walk still never reaches sub items.
+ */
+function menuItems(root: HTMLElement | undefined): HTMLElement[] {
+  if (!root) return [];
+  const out: HTMLElement[] = [];
+  const collect = (el: Element): void => {
+    if (el.matches(ITEM_SELECTOR)) out.push(el as HTMLElement);
+    for (const child of Array.from(el.children)) visit(child);
+  };
+  const visit = (el: Element): void => {
+    if (el.localName === 'slot') {
+      for (const assigned of (el as HTMLSlotElement).assignedElements({ flatten: true })) collect(assigned);
+      return;
+    }
+    collect(el);
+  };
+  for (const child of Array.from(root.children)) visit(child);
+  return out;
+}
+
+/** The first roving-focus item, in flat-tree order. Replaces
+ *  `querySelector(ITEM_SELECTOR)` for the reason `menuItems` replaces the `All`. */
+const firstMenuItem = (root: HTMLElement | undefined): HTMLElement | undefined => menuItems(root)[0];
+
+/**
+ * The focused item, resolved across BOTH trees.
+ *
+ * Inside a Shadow DOM `document.activeElement` returns the HOST rather than the
+ * focused menu item, so the menu's own root node is asked first. But a SLOTTED row
+ * lives in the LIGHT DOM: focus is then outside the shadow tree, that root reports
+ * null, and the document's answer is the real one. Asking only the shadow root would
+ * leave `currentIndex()` at -1 for every slotted row, so ArrowDown would restart at
+ * the top instead of advancing.
+ */
+function activeMenuItem(root: HTMLElement | undefined): Element | null {
+  const tree = root?.getRootNode() as Document | ShadowRoot | undefined;
+  return (tree?.activeElement ?? document.activeElement) as Element | null;
+}
+
 /** Imperative open controller, handed to a parent (e.g. the kai-menu facade) via
  *  `controllerRef` so it can drive/observe the Dropdown's open state. */
 export interface DropdownController { open: Accessor<boolean>; setOpen: (v: boolean) => void; }
@@ -103,8 +160,8 @@ export function Dropdown(props: DropdownProps) {
       // attempt focus now and re-assert in the menu ref's microtask so it lands
       // once the node exists. Skip disabled items (roving-focus contract).
       if (opts?.viaKeyboard) {
-        queueMicrotask(() => menu()?.querySelector<HTMLElement>(ITEM_SELECTOR)?.focus());
-        menu()?.querySelector<HTMLElement>(ITEM_SELECTOR)?.focus();
+        queueMicrotask(() => firstMenuItem(menu())?.focus());
+        firstMenuItem(menu())?.focus();
       }
     } else if (opts?.returnFocus !== false) {
       // Closing via keyboard/select: return focus to the trigger. The menu
@@ -179,23 +236,14 @@ export function DropdownContent(props: DropdownContentProps) {
     refs: () => [ctx.trigger(), ctx.menu(), ...ctx.subMenus()],
   });
 
-  const items = () => Array.from(ctx.menu()?.querySelectorAll<HTMLElement>(ITEM_SELECTOR) ?? []);
+  const items = () => menuItems(ctx.menu());
   const focusIndex = (i: number) => {
     const list = items();
     if (!list.length) return;
     const idx = ((i % list.length) + list.length) % list.length;
     list[idx].focus();
   };
-  // Resolve the focused item via the menu's own root node. Inside a Shadow DOM
-  // (every kitn-* element), `document.activeElement` returns the host element,
-  // not the focused menu item, which would break ArrowUp/Down roving focus.
-  // `getRootNode().activeElement` correctly returns the active node within the
-  // same tree (ShadowRoot or Document).
-  const activeItem = () => {
-    const root = ctx.menu()?.getRootNode() as Document | ShadowRoot | undefined;
-    return (root?.activeElement ?? document.activeElement) as Element | null;
-  };
-  const currentIndex = () => items().findIndex((el) => el === activeItem());
+  const currentIndex = () => items().findIndex((el) => el === activeMenuItem(ctx.menu()));
 
   const onKeyDown = (e: KeyboardEvent) => {
     const list = items();
@@ -226,7 +274,7 @@ export function DropdownContent(props: DropdownContentProps) {
             // synchronously; this ref-time microtask re-asserts focus once the
             // menu node exists. Skip disabled items.
             if (ctx.openedViaKeyboard()) {
-              queueMicrotask(() => el.querySelector<HTMLElement>(ITEM_SELECTOR)?.focus());
+              queueMicrotask(() => firstMenuItem(el)?.focus());
             }
           }}
           id={ctx.menuId}
@@ -424,8 +472,8 @@ export function DropdownSub(props: DropdownSubProps) {
     setOpenSig(v);
     if (v) {
       if (opts?.viaKeyboard) {
-        queueMicrotask(() => menu()?.querySelector<HTMLElement>(ITEM_SELECTOR)?.focus());
-        menu()?.querySelector<HTMLElement>(ITEM_SELECTOR)?.focus();
+        queueMicrotask(() => firstMenuItem(menu())?.focus());
+        firstMenuItem(menu())?.focus();
       }
     } else if (opts?.returnFocus !== false) {
       const el = trigger();
@@ -516,18 +564,14 @@ export function DropdownSubContent(props: DropdownSubContentProps) {
   // useDismiss here would double-fire Escape because document listeners run
   // after stopPropagation on the element, not on the document.
 
-  const items = () => Array.from(sub.menu()?.querySelectorAll<HTMLElement>(ITEM_SELECTOR) ?? []);
+  const items = () => menuItems(sub.menu());
   const focusIndex = (i: number) => {
     const list = items();
     if (!list.length) return;
     const idx = ((i % list.length) + list.length) % list.length;
     list[idx].focus();
   };
-  const activeItem = () => {
-    const root = sub.menu()?.getRootNode() as Document | ShadowRoot | undefined;
-    return (root?.activeElement ?? document.activeElement) as Element | null;
-  };
-  const currentIndex = () => items().findIndex((el) => el === activeItem());
+  const currentIndex = () => items().findIndex((el) => el === activeMenuItem(sub.menu()));
 
   const onKeyDown = (e: KeyboardEvent) => {
     const list = items();
@@ -559,7 +603,7 @@ export function DropdownSubContent(props: DropdownSubContentProps) {
             const unregister = parent.registerSubMenu(el);
             onCleanup(unregister);
             if (sub.openedViaKeyboard()) {
-              queueMicrotask(() => el.querySelector<HTMLElement>(ITEM_SELECTOR)?.focus());
+              queueMicrotask(() => firstMenuItem(el)?.focus());
             }
           }}
           id={sub.menuId}

package/src/ui/hover-card.tsx

@@ -1,5 +1,5 @@
 import {
-  createContext, useContext, createSignal, Show, splitProps, onCleanup,
+  createContext, useContext, createSignal, createUniqueId, Show, splitProps, onCleanup,
   type JSX, type Accessor,
 } from 'solid-js';
 import { Portal } from 'solid-js/web';
@@ -17,6 +17,12 @@ interface HoverCardCtx {
   setContent: (el: HTMLElement) => void;
   trigger: Accessor<HTMLElement | undefined>;
   content: Accessor<HTMLElement | undefined>;
+  /** Ties a focused trigger to the card it reveals. Without it a keyboard tab
+   *  stop announces nothing, which is a focus stop that wastes the user's time. */
+  contentId: string;
+  /** Whether this card refuses to open. Read by the TRIGGER, not just by
+   *  `enter()`: a card that cannot open must not be in the tab order either. */
+  disabled: Accessor<boolean>;
 }
 const Ctx = createContext<HoverCardCtx>();
 const useHoverCard = () => {
@@ -45,6 +51,7 @@ export function HoverCardRoot(props: HoverCardRootProps) {
   const [open, setOpen] = createSignal(props.defaultOpen ?? false);
   const [trigger, setTrigger] = createSignal<HTMLElement>();
   const [content, setContent] = createSignal<HTMLElement>();
+  const contentId = createUniqueId();
   let timer: number | undefined;
   props.controllerRef?.({ open, setOpen });
 
@@ -73,25 +80,167 @@ export function HoverCardRoot(props: HoverCardRootProps) {
       open, enter, leave, close,
       setTrigger, setContent,
       trigger, content,
+      contentId,
+      disabled: () => props.disabled ?? false,
     }}>
       {props.children}
     </Ctx.Provider>
   );
 }
 
-export interface HoverCardTriggerProps { children: JSX.Element; class?: string; }
+export interface HoverCardTriggerProps {
+  children: JSX.Element;
+  class?: string;
+  /**
+   * Whether the trigger is its own tab stop. Omit for the automatic behaviour,
+   * which is right for every case in this repo: the trigger takes focus only
+   * when nothing inside it already can.
+   *
+   * Pass `false` to keep a trigger out of the tab order entirely, or `true` to
+   * force a stop. Both are escape hatches — reach for them when the automatic
+   * answer is wrong, not to restate it.
+   */
+  focusable?: boolean;
+}
+
+/** Anything the platform puts in the tab order by default, plus anything a
+ *  consumer opted in with `tabindex`. `tabindex="-1"` is deliberately excluded:
+ *  it is programmatically focusable but the Tab key skips it, so a trigger
+ *  containing only such an element still needs a stop of its own. */
+const FOCUSABLE_CHILD =
+  'a[href],button,input,select,textarea,summary,[contenteditable=""],[contenteditable="true"],[tabindex]:not([tabindex^="-"])';
+
+/** Does this subtree already offer the keyboard a way in? Slotted content is
+ *  checked through `assignedElements()`, because a `<slot>` in the shadow tree
+ *  contains none of the light-DOM nodes it projects — the `kai-hover-card`
+ *  facade wraps a bare `<slot />`, so without this branch every use of that
+ *  element would be told its children are inert.
+ *
+ *  ★ WHEN this runs is as load-bearing as what it asks. At ref time the facade's
+ *  trigger contains `<slot></slot>` with NOTHING assigned yet, so a single call
+ *  from the ref answers "inert" for a slot that is about to receive a focusable
+ *  `<a>` — and the trigger stamps a second tab stop on top of the child's. That
+ *  is the very regression the `assignedElements()` branch was added to prevent,
+ *  reintroduced by timing rather than by logic. Measured with a real Tab key:
+ *  4 stops across a 3-widget fixture. So the caller re-runs this on
+ *  `slotchange`; see `HoverCardTrigger`. */
+const hasFocusableChild = (root: HTMLElement): boolean => {
+  if (root.querySelector(FOCUSABLE_CHILD)) return true;
+  return Array.from(root.querySelectorAll('slot')).some((slot) =>
+    (slot as HTMLSlotElement).assignedElements().some(
+      (el) => el.matches(FOCUSABLE_CHILD) || el.querySelector(FOCUSABLE_CHILD),
+    ),
+  );
+};
 
+/**
+ * ★ THE TRIGGER IS A TAB STOP WHEN, AND ONLY WHEN, ITS CHILDREN ARE NOT.
+ *
+ * `onFocusIn`/`onFocusOut` were here from the start and the focus-open path was
+ * plainly intended, but the span never set `tabindex`, so the Tab key could not
+ * land on it and neither handler could fire on a keyboard. It went unnoticed for
+ * as long as it did because `focusin` BUBBLES and every consumer at the time put
+ * something focusable inside the trigger — `source.tsx` an `<a>`, `context.tsx`
+ * a `<Button>` — so the card opened via the child and the span's own inertness
+ * never showed. The first trigger with inert children (an attachment tile: a
+ * div, an img, an svg) had no tab stop anywhere in it.
+ *
+ * Hence delegation rather than an unconditional `tabindex`: adding one always
+ * would give every existing consumer TWO stops for one card, which is a worse
+ * bug than the one being fixed. The check runs in the ref AND again on every
+ * `slotchange`, because slot assignment happens after the ref and a one-shot
+ * check calls a not-yet-filled `<slot>` inert (see `hasFocusableChild`).
+ *
+ * ★ THE FOCUS LISTENERS ARE NATIVE, NOT SOLID'S DELEGATED `onFocusIn`. Solid
+ * delegates a fixed set of events from the document and retargets them into
+ * component trees; inside these shadow roots that path runs for a PROGRAMMATIC
+ * `.focus()` and, in the deeper trees, not for a real Tab. Measured: tabbing to
+ * an attachment tile in a mounted `<kai-chat>` left the card shut and
+ * `aria-describedby` null while `.focus()` on the same element opened it — so
+ * every keyboard user got a tab stop that announced nothing and showed nothing,
+ * which is worse than no stop at all. `addEventListener` in the ref does not
+ * care how focus arrived. Anything in this kit relying on delegated focus
+ * events inside a shadow root is suspect for the same reason.
+ *
+ * `aria-describedby` is what makes the stop worth arriving at: the card is
+ * DESCRIPTIVE, not an action, so the trigger gets no `role="button"` — that
+ * would promise an activation that does not exist — and instead points at the
+ * content it reveals so a screen reader reads it out.
+ */
 export function HoverCardTrigger(props: HoverCardTriggerProps) {
   const ctx = useHoverCard();
+  const [detectedInert, setDetectedInert] = createSignal(false);
+  // `&& !disabled` last, and it beats an explicit `focusable` — a disabled card
+  // early-returns out of `enter()`, so a stop here could never open anything.
+  // Landing on it would announce nothing and reveal nothing, which is the dead
+  // stop the note above argues against; forcing one is not an escape hatch
+  // anybody should get.
+  const isFocusable = () => (props.focusable ?? detectedInert()) && !ctx.disabled();
+
   return (
     <As
       as="span"
-      class={cn('inline-block', props.class)}
-      ref={ctx.setTrigger}
+      class={cn(
+        'inline-block',
+        // A tab stop nobody can SEE is barely an improvement on no tab stop —
+        // WCAG 2.4.7. Only when this element is the stop; a delegating trigger
+        // must not draw a ring around its child's own focus state.
+        //
+        // AN OUTLINE, NOT A RING, and both halves of that were measured rather
+        // than assumed:
+        //
+        //  1. ★ A TAILWIND v4 UTILITY THAT ROUTES THROUGH `@property` IS INERT
+        //     INSIDE THESE SHADOW ROOTS, and that is a trap far wider than this
+        //     line. v4 gives `--tw-*` custom properties their defaults with
+        //     `@property`, and an `@property` rule delivered through a shadow
+        //     root's `adoptedStyleSheets` never registers — so the var resolves
+        //     to nothing, the declaration is invalid, and the property falls
+        //     back to its initial value. Measured in Chrome, twice:
+        //     `ring-2 ring-offset-1` set `--tw-ring-shadow` correctly and
+        //     computed `box-shadow: none`; `inset-ring-2` did the same; and
+        //     `outline-2` alone computed `outline-style: none` while width,
+        //     colour and offset all landed, because only the style goes
+        //     through `var(--tw-outline-style)`. Hence the literal
+        //     `[outline-style:solid]` — the one part that cannot be a var.
+        //  2. The offset is NEGATIVE so the outline lands inside the border
+        //     box. A trigger that fills its container (`block size-full` inside
+        //     the attachment tile's `overflow-hidden rounded-lg`) would
+        //     otherwise have its focus indicator painted straight into the
+        //     clip, and a trigger cannot know whether its container clips.
+        isFocusable() &&
+          'rounded-sm focus-visible:[outline-style:solid] focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-ring',
+        props.class,
+      )}
+      ref={(el: HTMLElement) => {
+        ctx.setTrigger(el);
+
+        // Native listeners, deliberately — see the note above. `focusin` /
+        // `focusout` rather than `focus` / `blur` because these have to fire
+        // for a focusable CHILD too, and only the -in/-out pair bubbles.
+        const enter = () => ctx.enter();
+        const leave = () => ctx.leave();
+        el.addEventListener('focusin', enter);
+        el.addEventListener('focusout', leave);
+        onCleanup(() => {
+          el.removeEventListener('focusin', enter);
+          el.removeEventListener('focusout', leave);
+        });
+
+        // Ask now for the direct-children case, and again whenever a slot is
+        // filled or emptied. Both are needed: `slotchange` never fires for a
+        // trigger with no slot in it, and the ref-time answer is wrong for one
+        // that has.
+        const evaluate = () => setDetectedInert(!hasFocusableChild(el));
+        evaluate();
+        for (const slot of Array.from(el.querySelectorAll('slot'))) {
+          slot.addEventListener('slotchange', evaluate);
+          onCleanup(() => slot.removeEventListener('slotchange', evaluate));
+        }
+      }}
+      tabIndex={isFocusable() ? 0 : undefined}
+      aria-describedby={isFocusable() && ctx.open() ? ctx.contentId : undefined}
       onPointerEnter={ctx.enter}
       onPointerLeave={ctx.leave}
-      onFocusIn={ctx.enter}
-      onFocusOut={ctx.leave}
     >
       {props.children}
     </As>
@@ -166,6 +315,7 @@ export function HoverCardContent(props: HoverCardContentProps) {
         >
           {/* Inner card: all visual + animation classes and the presence state. */}
           <div
+            id={ctx.contentId}
             data-expanded={presence.state() === 'open' ? '' : undefined}
             data-closed={presence.state() === 'closed' ? '' : undefined}
             class={cn(

package/src/ui/input.tsx

@@ -69,7 +69,21 @@ export function Input(props: InputProps): JSX.Element {
   const hasHint = () => !!local.error || !!local.hint;
   const hasAffix = () => local.leading != null || local.trailing != null;
 
-  const inputEl = (cls: string, part: string): JSX.Element => (
+  // The class arrives as an ACCESSOR, not a string, and this is load-bearing.
+  //
+  // Solid evaluates a `<Show>` `fallback` inside the Show's own memo. When the
+  // class was computed at the call site — `inputEl(cn(FIELD_BASE, …,
+  // isInvalid() && INVALID, local.class), …)` — those reads happened in that
+  // memo, so any of them changing re-ran the memo and BUILT A NEW `<input>`
+  // NODE: focus, caret and IME composition state all died with the old one. A
+  // consumer whose `invalid` is derived from the value (`kai-form` did exactly
+  // that) lost focus after every character.
+  //
+  // Passing a function moves every reactive read inside the element, where
+  // Solid compiles it into a nested effect that sets the attribute on the
+  // EXISTING node. Same reason the affix branch was always fine: it inserts the
+  // input through a function. Pinned by `tests/ui/input-node-identity.test.tsx`.
+  const inputEl = (cls: () => string, part: string): JSX.Element => (
     <input
       {...rest}
       id={id}
@@ -77,7 +91,7 @@ export function Input(props: InputProps): JSX.Element {
       disabled={local.disabled}
       aria-invalid={isInvalid() ? 'true' : undefined}
       aria-describedby={hasHint() ? hintId : undefined}
-      class={cn(SEARCH_RESET, cls)}
+      class={cn(SEARCH_RESET, cls())}
       onInput={(e) => local.onValueInput?.(e.currentTarget.value)}
       onBlur={(e) => {
         const handler = local.onBlur;
@@ -87,6 +101,17 @@ export function Input(props: InputProps): JSX.Element {
     />
   );
 
+  const fieldClass = () =>
+    cn(FIELD_BASE, local.size === 'sm' && SIZE_SM, isInvalid() && INVALID, local.class);
+
+  // Created on first use and then REUSED, so toggling an affix on or off does
+  // not discard a focused input either. The lazy cache also keeps the unused
+  // branch's node (and its effects) from being built at all.
+  let plainNode: JSX.Element;
+  const plainInput = () => (plainNode ??= inputEl(fieldClass, 'field input'));
+  let rowNode: JSX.Element;
+  const rowInput = () => (rowNode ??= inputEl(() => ROW_INPUT, 'input'));
+
   return (
     <div class="flex w-full flex-col gap-1.5">
       <Show when={local.label}>
@@ -95,13 +120,7 @@ export function Input(props: InputProps): JSX.Element {
         </label>
       </Show>
 
-      <Show
-        when={hasAffix()}
-        fallback={inputEl(
-          cn(FIELD_BASE, local.size === 'sm' && SIZE_SM, isInvalid() && INVALID, local.class),
-          'field input',
-        )}
-      >
+      <Show when={hasAffix()} fallback={plainInput()}>
         <div
           part="field"
           class={cn(
@@ -115,7 +134,7 @@ export function Input(props: InputProps): JSX.Element {
           <Show when={local.leading}>
             <span class="flex shrink-0 items-center text-muted-foreground">{local.leading}</span>
           </Show>
-          {inputEl(ROW_INPUT, 'input')}
+          {rowInput()}
           <Show when={local.trailing}>
             <span class="flex shrink-0 items-center text-muted-foreground">{local.trailing}</span>
           </Show>

package/src/ui/resizable.tsx

@@ -509,6 +509,17 @@ function ResizableHandle(props: ResizableHandleProps) {
       style={{
         cursor: isStatic() ? 'default' : isHoriz() ? 'col-resize' : 'row-resize',
         [isHoriz() ? 'width' : 'height']: '8px',
+        // The panels on either side are given explicit `flex-shrink: 0` (see
+        // `applyDelta`/`resetPanelToDefault`/`ResizablePanel.sizeStyle`) so THEY
+        // never yield space back to the handle. Without an equally explicit
+        // shrink here the handle keeps the flexbox default (`flex-shrink: 1`),
+        // so the moment its neighbors' sizes sum to (or exceed) the container's
+        // main axis — e.g. two percentage sizes that add to 100% after a
+        // maximize/restore round trip — flexbox has nowhere else to reclaim the
+        // 8px shortfall from and squeezes the handle itself to a computed width
+        // of 0. That makes the divider invisible AND undraggable (no hit area)
+        // until reload. Pin it to never shrink, matching its neighbors.
+        'flex-shrink': '0',
         'background': showStripHighlight() ? 'var(--color-muted-foreground, #98989f)' : 'transparent',
         'opacity': showStripHighlight() ? '0.3' : '1',
       }}

package/src/wire/chunk.ts

@@ -42,6 +42,21 @@ export interface ModelUsage {
 
 export interface ModelStreamChunk {
   text?: string;
+  /**
+   * The model id the RESPONSE stated, verbatim; REPORT, NEVER INFER.
+   *
+   * Read from the response rather than the request, which is what makes it work
+   * at all when the app builds its own fetch and the kit never sees what was
+   * asked for. Providers commonly resolve an alias (ask for `gpt-4o`, get
+   * `gpt-4o-2024-08-06`); through a gateway the value is the gateway's own id.
+   * Both are reasons to pass the string through untouched.
+   *
+   * It is NOT guaranteed. A proxy can strip or rewrite it and a custom endpoint
+   * may omit it, so a consumer renders it as ABSENT when it is absent. Filling
+   * the gap with the requested id would lie in exactly the requested-vs-served
+   * mismatch this field exists to catch.
+   */
+  model?: string;
   /**
    * Reasoning delta. `''` is MEANINGFUL, not a no-op: a redacted block has no
    * readable text but still carries a payload that must round-trip, and a format
@@ -170,6 +185,38 @@ export interface ModelTurn {
 export interface ConsumeOptions {
   /** Label for the reasoning disclosure. Defaults to 'Thinking'. */
   reasoningLabel?: string;
+  /**
+   * Correlates diagnostics and namespaces reasoning parts for this consume call;
+   * assigned automatically when absent.
+   *
+   * Supply one only to tie a read to an id you already hold. Two reads into the
+   * SAME sink must not share a value: the id is what keeps a second round's
+   * block 0 from merging into the first round's reasoning part.
+   */
+  streamId?: string;
+  /**
+   * The app's own grouping of several reads into ONE logical turn, carried onto
+   * every diagnostic event this read emits.
+   *
+   * THE KIT REPORTS WHAT THE APP DECLARES AND GROUPS NOTHING ON ITS OWN. A chat
+   * app running a tool loop, or fanning out to sub-agents, makes several model
+   * calls that belong to one turn; the kit sees one Response at a time and has
+   * no way to know which ones those are. So it does not guess:
+   *
+   *   readOpenAIStream(res, sink, { traceId: 'turn-42', label: 'planner' })
+   *
+   * Absent when not supplied -- the key is not present on the events at all,
+   * rather than present and undefined. Purely diagnostic: nothing in the parse
+   * branches on it and it never reaches a provider.
+   */
+  traceId?: string;
+  /** The app's name for THIS read inside its trace (`'planner'`,
+   *  `'executor'`, `'retry-2'`). Carried onto every diagnostic event, and
+   *  absent when not supplied. Never derived from the format or the model.
+   *
+   *  Not to be confused with `reasoningLabel`, which is UI copy for the
+   *  reasoning disclosure; this one is never rendered to an end user. */
+  label?: string;
   /** Fires once per tool call the moment its arguments parse cleanly. This is
    *  the hook a host's tool loop waits on. There is deliberately no
    *  per-fragment callback: `ToolPart.rawInput` is written on every fragment,