@kitn.ai/ui 0.25.2 → 0.27.0

package/src/ui/select.tsx

@@ -0,0 +1,168 @@
+import { type JSX, For, Show, createEffect, splitProps } from 'solid-js';
+import { ChevronDown } from 'lucide-solid';
+import { cn } from '../utils/cn';
+import { FIELD_BASE, FIELD_INVALID } from './input';
+
+/** One choice in a {@link Select}. */
+export interface SelectOption<T = string> {
+  /** The value this row selects. Compared to the select's `value` by identity. */
+  value: T;
+  /** Visible text. Defaults to `String(value)`. Native `<option>`s hold text, not markup. */
+  label?: string;
+  /** Disable this option alone (the select's `disabled` disables the whole control). */
+  disabled?: boolean;
+}
+
+export interface SelectProps<T = string>
+  extends Omit<JSX.SelectHTMLAttributes<HTMLSelectElement>, 'value' | 'children'> {
+  /**
+   * The choices, in display order. Rendered in full: the kit never truncates,
+   * re-orders or de-duplicates a consumer's option list.
+   *
+   * Omit it and pass `children` instead when you need `<optgroup>`s or anything else
+   * a flat list cannot express.
+   */
+  options?: readonly SelectOption<T>[];
+  /**
+   * The selected value, matched against each option's `value` by IDENTITY (so a
+   * numeric enum selects on the number, not on its string form). Pass an array for a
+   * `multiple` select.
+   */
+  value?: T | readonly T[];
+  /**
+   * Text for a leading, disabled, empty-valued option — the "nothing chosen yet" row.
+   * Omitted means no such row is rendered at all; there is no default placeholder,
+   * because inventing one would put words in the consumer's UI.
+   */
+  placeholder?: string;
+  /** Force the invalid (destructive-border) state. Matches `Input`'s. */
+  invalid?: boolean;
+  /** Raw `<option>` / `<optgroup>` children, for lists `options` cannot express.
+   *  `value` still drives the selection when you use these: it is applied to the
+   *  rendered options rather than quietly doing nothing. */
+  children?: JSX.Element;
+  /** Extra classes for the positioning wrapper that holds the chevron. */
+  containerClass?: string;
+}
+
+/**
+ * A select. A REAL native `<select>` behind `appearance: none`, in a box consistent
+ * with {@link Input}, with the kit's own chevron drawn over it.
+ *
+ * **Native, not a listbox, and that is the design.** A hand-built popup can be made to
+ * look identical and cannot be made to behave identically: the native control brings
+ * the platform picker on mobile, type-ahead on desktop, form participation, and the
+ * OS's own accessibility tree. This kit's control audit found every one of its
+ * accessibility defects in a control that had replaced a native element.
+ *
+ * The trade is that the *dropdown list itself* stays OS chrome — it renders outside the
+ * page and no stylesheet reaches it. What the kit can do is make it follow the kit's
+ * light/dark mode rather than the OS's, which `color-scheme` on the element host
+ * already does (`src/elements/styles.css`). Styling the closed control and leaving the
+ * open list to the platform is the whole of the bargain.
+ *
+ * Everything not listed in `SelectProps` is forwarded to the `<select>`, so `id`,
+ * `name`, `required`, `disabled`, `multiple`, `size`, `aria-*`, any `data-*` hook and
+ * the DOM events behave exactly as they do on a plain select. No validation is
+ * applied: `required` reaches the native attribute and stops there.
+ *
+ * ```tsx
+ * <Select
+ *   options={[{ value: 'low' }, { value: 'high', label: 'High priority' }]}
+ *   value={sev()}
+ *   placeholder="Choose a severity…"
+ *   onChange={(e) => setSev(e.currentTarget.value)}
+ * />
+ * ```
+ */
+export function Select<T = string>(props: SelectProps<T>): JSX.Element {
+  const [local, rest] = splitProps(props, [
+    'class', 'containerClass', 'options', 'value', 'placeholder', 'invalid', 'children', 'ref',
+  ]);
+
+  // A `multiple` select is a scrolling list box, not a closed control: there is no
+  // collapsed state for a chevron to point at, and `appearance: none` on one buys
+  // nothing. So the custom chrome applies to the single-value shape only.
+  const isMulti = () => !!rest.multiple;
+
+  const isSelected = (v: T): boolean => {
+    const sel = local.value;
+    if (Array.isArray(sel)) return (sel as readonly T[]).includes(v);
+    return sel === v;
+  };
+
+  // Nothing chosen yet, for deciding whether the placeholder row is the selected one.
+  // Array-aware on purpose: an empty array means nothing is selected, and without this
+  // branch the browser would fall through to auto-selecting the first NON-disabled
+  // option — i.e. showing a real choice while the caller's state said none was made.
+  const isEmpty = (): boolean => {
+    const v = local.value;
+    if (Array.isArray(v)) return v.length === 0;
+    return v === undefined || v === null || (v as unknown) === '';
+  };
+
+  return (
+    <div class={cn('relative block w-full', local.containerClass)}>
+      <select
+        {...rest}
+        ref={(el) => {
+          // `ref` is split out and re-applied by hand because this component needs the
+          // element itself for the `children` path below. Solid always hands a component
+          // a ref FUNCTION (a variable ref compiles into one), so the typeof guard is for
+          // the hand-written object case only.
+          const forward = local.ref;
+          if (typeof forward === 'function') (forward as (el: HTMLSelectElement) => void)(el);
+
+          // `value` drives the `options` list declaratively (each `<option selected>`),
+          // which cannot reach options the CALLER rendered as `children`. Applying it
+          // imperatively for that path is the difference between "children are an
+          // escape hatch" and "`value` silently does nothing once you use one".
+          createEffect(() => {
+            if (local.children === undefined) return;
+            const v = local.value;
+            if (v === undefined || v === null) return;
+            if (Array.isArray(v)) {
+              const wanted = new Set((v as readonly unknown[]).map(String));
+              for (const o of el.options) o.selected = wanted.has(o.value);
+            } else {
+              el.value = String(v);
+            }
+          });
+        }}
+        class={cn(
+          FIELD_BASE,
+          // `peer` so the chevron beside it can dim with the control.
+          'peer',
+          // `pr-9` reserves the lane the chevron sits in, so a long option label never
+          // slides under it.
+          !isMulti() && 'cursor-pointer appearance-none pr-9',
+          local.invalid && FIELD_INVALID,
+          local.class,
+        )}
+      >
+        <Show when={local.placeholder !== undefined}>
+          <option value="" disabled selected={isEmpty()}>
+            {local.placeholder}
+          </option>
+        </Show>
+        <For each={local.options}>
+          {(opt) => (
+            <option value={String(opt.value)} disabled={opt.disabled} selected={isSelected(opt.value)}>
+              {opt.label ?? String(opt.value)}
+            </option>
+          )}
+        </For>
+        {local.children}
+      </select>
+      <Show when={!isMulti()}>
+        {/* `pointer-events-none` so the chevron is decoration and every click, including
+            one landing on the arrow, still opens the native picker. `aria-hidden`
+            because the select already announces itself as a combo box. */}
+        <ChevronDown
+          aria-hidden="true"
+          class="pointer-events-none absolute right-3 top-1/2 size-4 -translate-y-1/2 text-muted-foreground peer-disabled:opacity-50"
+        />
+      </Show>
+    </div>
+  );
+}

package/src/ui/slider.tsx

@@ -0,0 +1,178 @@
+import { type JSX, Show, splitProps, createSignal } from 'solid-js';
+import { cn } from '../utils/cn';
+
+export interface SliderProps
+  extends Omit<JSX.InputHTMLAttributes<HTMLInputElement>, 'type' | 'children' | 'min' | 'max' | 'step' | 'value'> {
+  /**
+   * Lowest selectable value. REQUIRED, and deliberately so.
+   *
+   * A range with no `min`/`max` is not a slider, it is a slider-shaped guess, and the
+   * guess belongs to whoever knows what the number means. `SliderWidget` reading a
+   * JSON-Schema field still defaults an absent `minimum` to 0 — that is the WIDGET's
+   * decision about a consumer-authored schema, and it stays there rather than being
+   * quietly adopted by every caller of this component.
+   */
+  min: number;
+  /** Highest selectable value. REQUIRED for the same reason as `min`. */
+  max: number;
+  /** Granularity. Omitted means the native default (1); `'any'` means continuous. */
+  step?: number | 'any';
+  /** The current value. Controlled — drive it from `onInput`. Omit for uncontrolled. */
+  value?: number;
+  /** Initial value when uncontrolled. */
+  defaultValue?: number;
+  /**
+   * Show the current value beside the track. Off by default.
+   *
+   * Two shapes, because one is not enough and three would be too many. `true` renders
+   * the raw number, which is what most sliders want. A FUNCTION renders whatever it
+   * returns, because plenty of sliders are not counting bare numbers: `60%`, `3 of 5`,
+   * `1m 30s`. A boolean alone cannot express those, and a formatter alone would make
+   * the common case read `valueLabel={(v) => v}`.
+   *
+   * The readout is `aria-hidden`. The input already reports the same number through
+   * `aria-valuenow` / `aria-valuetext`, so an exposed copy would be announced twice.
+   *
+   * NOTE ON STRUCTURE: with a readout the component renders a flex row around the
+   * input; without one it is still a bare `<input>` and nothing changes for existing
+   * callers. Toggling this at runtime therefore rebuilds the input element, which is
+   * fine for a control panel and not something a real app does mid-drag.
+   */
+  valueLabel?: boolean | ((value: number) => JSX.Element);
+}
+
+/**
+ * A slider. A REAL `<input type="range">` behind `appearance: none`, styled by the
+ * kit's `.kai-range` rule, never a `<div>` with a drag handler.
+ *
+ * The native control brings the whole keyboard contract (arrows, Home, End,
+ * PageUp/PageDown), pointer and touch dragging, form participation via `name`, and
+ * the `slider` role with a live value announcement — all of it for free and all of it
+ * correct. Every accessibility defect this kit's control audit found was in a control
+ * that had replaced the native element with something hand-rolled.
+ *
+ * What the component adds is the **filled track**. `.kai-range` paints the portion
+ * left of the thumb from a `--kai-range-fill` custom property, and until now every
+ * caller computed that percentage itself. It is arithmetic over `min`, `max` and the
+ * current value — three things this component already has — so no consumer should
+ * ever write it again.
+ *
+ * Everything not listed in `SliderProps` is forwarded to the input, so `id`, `name`,
+ * `disabled`, `required`, `aria-*` and any `data-*` hook behave exactly as they do on
+ * a plain `<input>`. No clamping and no validation is applied: a value outside
+ * `min`..`max` is the browser's business, not ours.
+ *
+ * ```tsx
+ * <Slider min={0} max={100} step={5} value={v()} onInput={(e) => setV(e.currentTarget.valueAsNumber)} />
+ * ```
+ */
+export function Slider(props: SliderProps): JSX.Element {
+  const [local, rest] = splitProps(props, [
+    'class', 'style', 'min', 'max', 'step', 'value', 'defaultValue', 'ref', 'valueLabel',
+  ]);
+
+  // The uncontrolled mirror. A slider's fill has to follow the thumb even when nobody
+  // is holding the value in a signal, so the component tracks the live value itself
+  // through a NATIVE `on:input` listener. That is `on:` and not `onInput` on purpose:
+  // `onInput` stays in `rest` and reaches the input untouched, so a caller's handler
+  // is neither wrapped nor swallowed, and the two listeners simply both run.
+  const [live, setLive] = createSignal<number | undefined>(props.defaultValue);
+
+  // HTML's own rule for a range with no value: the midpoint of the span. Restated here
+  // rather than left to the browser because the fill has to agree with the thumb on the
+  // very first paint, before any input event exists.
+  const current = () => local.value ?? live() ?? (local.min + local.max) / 2;
+
+  const fill = (): string => {
+    const lo = local.min;
+    const hi = local.max;
+    if (!(hi > lo)) return '0%';
+    // Clamp: a value outside the range is the caller's to fix, but a track painted
+    // 140% wide is a rendering artefact nobody asked for.
+    const pct = ((current() - lo) / (hi - lo)) * 100;
+    return `${Math.min(100, Math.max(0, pct))}%`;
+  };
+
+  // Merge rather than replace: `style` is a legitimate thing to pass a slider, and the
+  // fill is a custom property that has to survive alongside it. Solid accepts either a
+  // string or an object here, so both shapes are handled.
+  const style = (): string | JSX.CSSProperties => {
+    const s = local.style;
+    if (typeof s === 'string') return `${s.replace(/;\s*$/, '')};--kai-range-fill:${fill()}`;
+    return { ...(s ?? {}), '--kai-range-fill': fill() } as JSX.CSSProperties;
+  };
+
+  // CONTROLLED-MODE RECONCILIATION. A controlled `<input type="range">` in Solid can
+  // drift: the browser moves the thumb on a drag, and if the caller's `value` does not
+  // change in response, the bound expression is unchanged, so Solid never writes the
+  // DOM back. The thumb ends up somewhere the component's own state says it is not —
+  // and because the fill is derived from `value`, the two visibly DISAGREE. That is the
+  // exact symptom reported against the Storybook Playground: thumb slides, track does
+  // not. A pinned, writer-less `<Slider value={40} />` is a legitimate thing to render,
+  // and it should look pinned rather than half-moved.
+  //
+  // WHY A MICROTASK AND NOT THE HANDLER OR A BARE EFFECT. Both of those run too early
+  // and would break the ordinary controlled case. The `on:input` listener above is
+  // attached to the TARGET, so it runs before the caller's `onInput`, which Solid
+  // delegates at the document; snapping back there would hand the caller's handler a
+  // value we had already reset. A `createEffect` is flushed at the end of the update
+  // that `setLive` starts, which is still inside the target listener and therefore also
+  // before the delegated one. A microtask runs after the whole event turn: every input
+  // listener has run and any signal the caller set has propagated, so a value that
+  // still disagrees means the caller genuinely did not accept the edit.
+  let el: HTMLInputElement | undefined;
+  const reconcileControlled = () => {
+    const v = local.value;
+    // Uncontrolled: `live` is the truth and the DOM is already showing it.
+    if (v === undefined || el === undefined) return;
+    if (el.valueAsNumber !== v) el.value = String(v);
+  };
+
+  const readout = (): JSX.Element => {
+    const vl = local.valueLabel;
+    return typeof vl === 'function' ? vl(current()) : current();
+  };
+
+  const control = () => (
+    <input
+      {...rest}
+      type="range"
+      class={cn('kai-range', local.class)}
+      style={style()}
+      min={local.min}
+      max={local.max}
+      step={local.step}
+      value={local.value ?? live() ?? undefined}
+      ref={(node) => {
+        // `ref` is split out and re-applied by hand because this component needs the
+        // element for the reconciliation above. Solid always hands a component a ref
+        // FUNCTION (a variable ref compiles into one), so the typeof guard is for the
+        // hand-written object case only.
+        el = node;
+        const forward = local.ref;
+        if (typeof forward === 'function') (forward as (n: HTMLInputElement) => void)(node);
+      }}
+      on:input={(e) => {
+        setLive((e.currentTarget as HTMLInputElement).valueAsNumber);
+        queueMicrotask(reconcileControlled);
+      }}
+    />
+  );
+
+  return (
+    <Show when={local.valueLabel} fallback={control()}>
+      <div class="flex items-center gap-3">
+        {control()}
+        {/* aria-hidden: the input already announces this number. The readout is a
+            second copy for the eyes only, and exposing it would double the
+            announcement on every step of a drag. */}
+        <span
+          aria-hidden="true"
+          class="min-w-9 shrink-0 rounded-md bg-background px-2 py-1 text-center text-sm font-medium tabular-nums text-foreground shadow-sm"
+        >
+          {readout()}
+        </span>
+      </div>
+    </Show>
+  );
+}

package/src/ui/switch.tsx

@@ -1,7 +1,12 @@
-import { createSignal } from 'solid-js';
+import { type JSX, createSignal, splitProps } from 'solid-js';
 import { cn } from '../utils/cn';
 
-export interface SwitchProps {
+export interface SwitchProps
+  extends Omit<
+    JSX.ButtonHTMLAttributes<HTMLButtonElement>,
+    | 'type' | 'role' | 'aria-checked' | 'children' | 'ref'
+    | 'onChange' | 'onchange' | 'onClick' | 'onclick' | 'onKeyDown' | 'onkeydown'
+  > {
   /** Controlled checked state. When set, the component defers state to the
    *  parent; drive it from `onChange`. Omit for uncontrolled (internal) state. */
   checked?: boolean;
@@ -26,51 +31,74 @@ export interface SwitchProps {
 /**
  * A toggle switch (`role="switch"`). Controlled via `checked`, or uncontrolled
  * from `defaultChecked`. Keyboard-operable (Space/Enter) and theme-tokened.
+ *
+ * Anything not named in `SwitchProps` is forwarded to the inner button, so `id`,
+ * `aria-required` / `aria-invalid` / `aria-describedby` and any `data-*` hook land
+ * on the focusable element without a caller stamping them through a `ref`. The
+ * switch keeps ownership of `type`, `role`, `aria-checked` and the toggle handlers:
+ * those are the control, not decoration.
  */
 export function Switch(props: SwitchProps) {
-  const [internal, setInternal] = createSignal(props.defaultChecked ?? false);
-  const isControlled = () => props.checked !== undefined;
-  const isOn = () => (isControlled() ? !!props.checked : internal());
+  const [local, rest] = splitProps(props, [
+    'checked', 'defaultChecked', 'disabled', 'label', 'name', 'value', 'onChange', 'buttonRef', 'class',
+  ]);
+  const [internal, setInternal] = createSignal(local.defaultChecked ?? false);
+  const isControlled = () => local.checked !== undefined;
+  const isOn = () => (isControlled() ? !!local.checked : internal());
 
   const toggle = () => {
-    if (props.disabled) return;
+    if (local.disabled) return;
     const next = !isOn();
     if (!isControlled()) setInternal(next);
-    props.onChange?.(next);
+    local.onChange?.(next);
   };
 
   return (
     <>
-      {props.name != null && (
+      {local.name != null && (
         <input
           type="checkbox"
-          name={props.name}
-          value={props.value ?? 'on'}
+          name={local.name}
+          value={local.value ?? 'on'}
           checked={isOn()}
-          disabled={props.disabled}
+          disabled={local.disabled}
           aria-hidden="true"
           tabindex={-1}
           style={{ position: 'absolute', width: '1px', height: '1px', overflow: 'hidden', clip: 'rect(0 0 0 0)', 'white-space': 'nowrap' }}
           onChange={() => { /* driven by the button; keep the input in sync only */ }}
         />
       )}
+      {/* `{...rest}` comes FIRST so the attributes below win: a caller can add an
+          `id` or an `aria-describedby`, but cannot turn this into something that is
+          no longer a switch. */}
       <button
+        {...rest}
         type="button"
         role="switch"
-        ref={props.buttonRef}
+        ref={local.buttonRef}
         aria-checked={isOn()}
-        aria-label={props.label}
-        disabled={props.disabled}
+        aria-label={local.label}
+        disabled={local.disabled}
         onClick={toggle}
         onKeyDown={(e) => {
           if (e.key === ' ' || e.key === 'Enter') { e.preventDefault(); toggle(); }
         }}
         class={cn(
-          'relative inline-flex h-5 w-9 shrink-0 cursor-pointer items-center rounded-full transition-colors',
+          'relative inline-flex h-5 w-9 shrink-0 cursor-pointer items-center rounded-full border transition-colors',
           'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-background',
           'disabled:cursor-not-allowed disabled:opacity-50',
-          isOn() ? 'bg-primary' : 'bg-muted',
-          props.class,
+          // WCAG 2.1 SC 1.4.11: the track IS this control's visual boundary, so it
+          // needs 3:1 against the surface behind it. The OFF fill cannot carry that
+          // — `--color-muted` is a shared surface token (measured 1.10:1 light on
+          // `--color-background`) and darkening it to clear 3:1 would repaint every
+          // muted surface in the kit. So the boundary moves to a border on the
+          // control-edge token `--color-input`, which exists for exactly this and is
+          // already held to the 3:1 floor for radios, checkboxes and inputs
+          // (tests/primitives/control-contrast.test.ts). The ON track keeps its
+          // ~17:1 `--color-primary` fill and takes a transparent border purely so
+          // the two states stay the same size — the fill still paints under it.
+          isOn() ? 'border-transparent bg-primary' : 'border-input bg-muted',
+          local.class,
         )}
       >
         <span
@@ -79,7 +107,10 @@ export function Switch(props: SwitchProps) {
             // On the `primary` track use `primary-foreground` so the thumb stays
             // visible in both themes (in dark mode `primary` is light, where a
             // hard-coded white thumb vanished). Off-track stays white over `muted`.
-            isOn() ? 'translate-x-[1.125rem] bg-primary-foreground' : 'translate-x-0.5 bg-white',
+            // The track is `border-box` with a 1px border, so the thumb travels
+            // inside a 34px box: 2px in from each inner edge keeps both end
+            // positions 3px from the track's outer edge.
+            isOn() ? 'translate-x-4 bg-primary-foreground' : 'translate-x-0.5 bg-white',
           )}
         />
       </button>

package/src/utils/cn.ts

@@ -2,19 +2,25 @@ import { clsx, type ClassValue } from 'clsx';
 import { extendTailwindMerge } from 'tailwind-merge';
 
 // The kit defines custom font-size utilities via @theme tokens in theme.css:
-// text-caption / text-meta / text-body / text-title. tailwind-merge has no way
-// to know these are font sizes, so by default it buckets e.g. `text-body` with
-// text COLORS and drops a real color (`text-transparent`, `text-foreground`, …)
+// text-micro / text-caption / text-meta / text-compact / text-body / text-title.
+// tailwind-merge has no way to know these are font sizes, so by default it
+// buckets `text-body` with text COLORS and drops a real color
+// (`text-transparent`, `text-foreground`, …)
 // whenever both appear in the same cn() call — which silently broke TextShimmer
 // inside the web components (the element adds `text-body`, dropping
 // `text-transparent`, so the gradient stayed hidden behind opaque text).
 //
 // Register them in the `font-size` group so they conflict only with other font
-// sizes (text-xs/sm/base/lg/…) and never with text colors.
+// sizes (text-xs/sm/base/lg/…) and never with text colors. Since theme.css now
+// re-points Tailwind's own scale at the same tokens (text-xs ≡ text-meta,
+// text-sm ≡ text-body, text-base ≡ text-title), the semantic name and its
+// Tailwind alias are literally the same size — so they MUST land in one group
+// or `cn('text-sm', 'text-body')` would emit two classes for one declaration.
+// `text-lg` needs no entry: it is already a stock Tailwind font size.
 const twMerge = extendTailwindMerge({
   extend: {
     classGroups: {
-      'font-size': [{ text: ['caption', 'meta', 'body', 'title'] }],
+      'font-size': [{ text: ['micro', 'caption', 'meta', 'compact', 'body', 'title'] }],
     },
   },
 });

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,