@kitn.ai/ui 0.25.1 → 0.26.0

package/src/elements/thinking-bar.tsx

@@ -25,10 +25,19 @@ defineWebComponent<Props, Events>('kai-thinking-bar', {
   text: 'Thinking',
   stoppable: false,
   stopLabel: 'Answer now',
-}, (props, { dispatch, flag }) => (
-  <ThinkingBar
-    text={props.text}
-    stopLabel={props.stopLabel}
-    onStop={flag('stoppable') ? () => dispatch('kai-stop') : undefined}
-  />
-));
+}, (props, { dispatch, flag, reflectFlag }) => {
+  // `stoppable` reflects, following kai-tool's `disabled` (its FIX1). Without it the
+  // remove direction is dead: `el.removeAttribute('stoppable')` parses to `undefined`,
+  // the prop was already `undefined` after a bare-attribute add, so no prop change
+  // fires and `flag()`'s non-reactive hasAttribute fallback is never re-read — the
+  // stop affordance stays rendered forever. reflectFlag's coercing read-back resolves
+  // every write through the same `flag()` policy, making both directions reactive.
+  reflectFlag('stoppable');
+  return (
+    <ThinkingBar
+      text={props.text}
+      stopLabel={props.stopLabel}
+      onStop={flag('stoppable') ? () => dispatch('kai-stop') : undefined}
+    />
+  );
+});

package/src/elements/toast.tsx

@@ -47,6 +47,9 @@ interface Events {
  * Stack-level defaults are also declarative: `<kai-toast-region appearance="card"
  * inverse>` makes every toast that doesn't set its own `appearance`/`inverse`
  * render as an inverted card. A per-toast value always wins.
+ *
+ * Your app chrome must stay below the toast layer; set `--kai-toast-z`
+ * (default 100) on the host to move the layer.
  */
 defineWebComponent<Props, Events>('kai-toast-region', {
   toasts: [],

package/src/elements/tool.tsx

@@ -1,4 +1,4 @@
-import { Show } from 'solid-js';
+import { createSignal, Show } from 'solid-js';
 import { defineWebComponent } from './define';
 import { Tool, type ToolPart } from '../components/tool';
 import { wireDisclosure } from './disclosure';
@@ -36,13 +36,34 @@ defineWebComponent<Props, Events>('kai-tool', {
   defaultOpen: undefined,
   disabled: undefined,
 }, (props, ctx) => {
-  const { flag } = ctx;
-  let api: CollapsibleController | undefined;
+  const { flag, reflectFlag } = ctx;
+
+  // A SIGNAL, not a `let`. This facade gates its whole subtree on `<Show when={props.tool}>`,
+  // and `tool` is an object prop, so the only sequence a consumer of the HTML spelling
+  // has is markup-then-assign: the element connects with no tool, renders nothing, and
+  // the Collapsible — and therefore the controller — arrives a tick later.
+  //
+  // With a plain `let`, wireDisclosure's effects ran once against `undefined` and never
+  // again, because the getter they were handed was not reactive and a bare `open`
+  // attribute never changes `props.open` to re-trigger them. Net result: `<kai-tool open>`
+  // silently stayed shut while `el.open` read back `true` — the property and the
+  // rendering disagreed. Making the controller reactive is the whole fix: the effects
+  // re-run the moment it lands. `Tool` already tracks its own copy this way internally.
+  // Pinned by the ordering rows in tests/elements/tool.test.tsx.
+  const [api, setApi] = createSignal<CollapsibleController>();
 
   // The standard disclosure surface: settable+reflecting `open`, kai-open-change,
   // show/hide/toggle, disabled-gating. See ./disclosure. This is the SOLE emitter
   // of kai-open-change — the Tool/Collapsible no longer wires its own.
-  wireDisclosure(ctx, () => api, () => props.open);
+  wireDisclosure(ctx, api, () => props.open);
+
+  // `disabled` reflects too, following kai-dock. Without it the prop is write-only in
+  // the read direction AND deaf in the write one: `el.setAttribute('disabled', '')`
+  // after mount is parsed by component-register to `undefined`, so the prop never
+  // changes and nothing re-renders. reflectFlag's coercing setter resolves that
+  // `undefined` back through the same `flag()` policy, which is what makes the plain
+  // HTML gesture work at runtime and not only at parse time (findings G-05).
+  reflectFlag('disabled');
 
   return (
     <Show when={props.tool}>
@@ -50,7 +71,7 @@ defineWebComponent<Props, Events>('kai-tool', {
         toolPart={props.tool!}
         defaultOpen={flag('defaultOpen')}
         disabled={flag('disabled')}
-        controllerRef={(a) => (api = a)}
+        controllerRef={(a) => setApi(a)}
       />
     </Show>
   );

package/src/elements/voice-input.tsx

@@ -39,6 +39,13 @@ interface Events {
    *  push-to-talk indicator) in sync with the mic. Fires on real transitions
    *  only (manual click and programmatic start()/stop()), never on mount. */
   'kai-recording-change': { recording: boolean };
+  /** A voice session failed, so no failure is ever silent. `detail.source` names
+   *  the failing side (`recognition` on `<kai-voice-input>`, `synthesis` on
+   *  `<kai-voice-output>`), `detail.error` carries the platform error code, the
+   *  thrown exception's name, or `no-result` when recognition ended with no error
+   *  and no text (the user said nothing), and `detail.message` is human-readable.
+   *  Deliberate cancellation does not fire. */
+  'kai-voice-error': { source: 'recognition'; error: string; message: string };
 }
 
 /**
@@ -47,8 +54,9 @@ interface Events {
  * `SpeechRecognition` (Chrome/Safari; no Firefox — and cloud-based in Chrome).
  * Set `el.transcribe` to route audio through your own async transcriber instead.
  * Where neither is available it records the blob and emits `kai-audio-captured`
- * with no text. Also emits `kai-transcription` (final text) and, with `interim`,
- * `kai-transcript-interim` (live partials).
+ * with no text. Also emits `kai-transcription` (final text), `kai-voice-error`
+ * (a failed or empty session) and, with `interim`, `kai-transcript-interim`
+ * (live partials).
  */
 defineWebComponent<Props, Events>('kai-voice-input', {
   transcribe: undefined,
@@ -85,6 +93,7 @@ defineWebComponent<Props, Events>('kai-voice-input', {
       onTranscription={(text) => dispatch('kai-transcription', { text })}
       onInterim={(text) => dispatch('kai-transcript-interim', { text })}
       onRecordingChange={(recording) => dispatch('kai-recording-change', { recording })}
+      onError={(detail) => dispatch('kai-voice-error', detail)}
       controllerRef={(c) => (controller = c)}
     />
   );

package/src/elements/voice-output.tsx

@@ -20,18 +20,30 @@ interface Props extends Record<string, unknown> {
 
 /** Events fired by `<kai-voice-output>`. */
 interface Events {
-  /** Playback started or stopped. Drive your own UI in sync. Fires on real transitions
-   *  only (manual click and programmatic speak()/stop()), never on mount. */
+  /** Playback started or stopped. Drive your own UI in sync. `speaking: true`
+   *  fires when audio actually starts (utterance.onstart natively; audio playback
+   *  beginning on the `synthesize` path), not when speak() is called; earlier
+   *  releases fired it optimistically inside speak() itself. Fires on real
+   *  transitions only (manual click and programmatic speak()/stop()), never on
+   *  mount. */
   'kai-speaking-change': { speaking: boolean };
   /** The model path (`synthesize`) resolved audio: the raw `Blob` before playback. */
   'kai-synthesized': { blob: Blob };
+  /** A voice session failed, so no failure is ever silent. `detail.source` names
+   *  the failing side (`recognition` on `<kai-voice-input>`, `synthesis` on
+   *  `<kai-voice-output>`), `detail.error` carries the platform error code, the
+   *  thrown exception's name, or `no-result` when recognition ended with no error
+   *  and no text (the user said nothing), and `detail.message` is human-readable.
+   *  Deliberate cancellation does not fire. */
+  'kai-voice-error': { source: 'synthesis'; error: string; message: string };
 }
 
 /**
  * `<kai-voice-output>` — a speaker button that reads `text` aloud. Native by
  * default (`speechSynthesis`); set `el.synthesize` to route through your TTS
  * model instead. The output sibling of `<kai-voice-input>`. Emits
- * `kai-speaking-change` and (model path) `kai-synthesized`.
+ * `kai-speaking-change`, `kai-voice-error` (a failed synthesis) and (model
+ * path) `kai-synthesized`.
  */
 defineWebComponent<Props, Events>('kai-voice-output', {
   text: '',
@@ -63,6 +75,7 @@ defineWebComponent<Props, Events>('kai-voice-output', {
       onSynthesize={props.synthesize ? (text) => props.synthesize!(text) : undefined}
       onSpeakingChange={(speaking) => dispatch('kai-speaking-change', { speaking })}
       onSynthesized={(blob) => dispatch('kai-synthesized', { blob })}
+      onError={(detail) => dispatch('kai-voice-error', detail)}
       controllerRef={(c) => (controller = c)}
     />
   );

package/src/index.ts

@@ -339,6 +339,8 @@ export type { VoiceInputProps, VoiceInputController } from './components/voice-i
 export { ConversationList } from './components/conversation-list';
 export type { ConversationListProps, ConversationListController } from './components/conversation-list';
 export { ConversationItem } from './components/conversation-item';
+export { SlottedConversationItem } from './components/conversation-item';
+export type { SlottedConversationItemProps } from './components/conversation-item';
 export type { ConversationItemProps } from './components/conversation-item';
 export { ModelSwitcher } from './components/model-switcher';
 export type { ModelSwitcherProps } from './components/model-switcher';

package/src/primitives/use-resize-observer.ts

@@ -10,3 +10,36 @@ export function observeContentHeight(el: Element, onHeight: (height: number) =>
   ro.observe(el);
   return () => ro.disconnect();
 }
+
+/** Observe an element's resizes but report the FULL rendered document height (not the
+ *  observed element's own content-box) — `document.body.scrollHeight`.
+ *
+ *  Used by the remote-card provider runtime to size the host iframe (D1, rung 5 IVP
+ *  task-10-report.md): `observeContentHeight` reports the ResizeObserver content-box of
+ *  the observed root, which drops that root's OWN padding/border and any ancestor
+ *  (e.g. `<body>`) padding above it — the host then clips the bottom of the card by
+ *  exactly those lost pixels. `scrollHeight` is the full padding-box height as actually
+ *  rendered, so it stays correct no matter which element in the ancestor chain carries
+ *  the padding/border, including if the provider page's own styles change later —
+ *  reading contentRect off one fixed element, or hand-summing computed padding/border
+ *  off a fixed list of ancestors, would both need updating every time that chain does.
+ *
+ *  Deliberately `document.body.scrollHeight`, NOT `document.documentElement.scrollHeight`
+ *  (N1, task-10-report.md "Fix-wave re-review"): the CSSOM View spec special-cases the
+ *  scrollHeight of the ROOT element to be `max(viewport scrolling area, viewport
+ *  height)` — and the host sets the iframe's viewport FROM this very measurement
+ *  (`host-embed.ts` `sizeIframe`), so `documentElement.scrollHeight` can only grow for
+ *  the life of the frame: once the iframe is tall, the root's own scrollHeight is
+ *  floored at that height even after the card's content shrinks. `<body>` carries no
+ *  such floor — its scrollHeight is a plain padding-box measurement of body's own
+ *  content, so it shrinks along with the card. */
+export function observeDocumentHeight(el: Element, onHeight: (height: number) => void): () => void {
+  let last = -1;
+  const ro = new ResizeObserver(() => {
+    const doc = el.ownerDocument;
+    const h = doc?.body?.scrollHeight ?? doc?.documentElement?.scrollHeight ?? el.getBoundingClientRect().height;
+    if (last < 0 || Math.abs(h - last) > THRESHOLD) { last = h; onHeight(h); }
+  });
+  ro.observe(el);
+  return () => ro.disconnect();
+}

package/src/primitives/use-speech-recognition.ts

@@ -51,6 +51,14 @@ export interface SpeechRecognitionStartOptions {
   lang?: string;
   /** Called with each interim (non-final) transcript when `interim` is enabled. */
   onInterim?: (text: string) => void;
+  /**
+   * Called when the recognition session hits a runtime error (`recognition.onerror`),
+   * with the platform's error code (`network`, `not-allowed`, `no-speech`, ...) and a
+   * human-readable message. The session still ends through `onend`, so `start()` still
+   * resolves (with whatever text was captured before the error). Without this callback
+   * a runtime failure is invisible: the `error` signal is state, not a notification.
+   */
+  onError?: (error: string, message: string) => void;
 }
 
 /**
@@ -102,7 +110,10 @@ export function useSpeechRecognition(options: UseSpeechRecognitionOptions = {})
       };
 
       recognition.onerror = (event) => {
-        setError(event.error ?? 'Speech recognition error');
+        const code = event.error ?? 'unknown';
+        const message = `Speech recognition error: ${code}`;
+        setError(message);
+        opts.onError?.(code, message);
       };
 
       recognition.onend = () => {

package/src/primitives/use-stick-to-bottom.ts

@@ -17,14 +17,42 @@ export function useStickToBottom() {
 
   function scrollToBottom(behavior: ScrollBehavior = 'smooth') {
     if (!containerEl) return;
-    containerEl.scrollTo({ top: containerEl.scrollHeight, behavior });
+    if (typeof containerEl.scrollTo === 'function') {
+      containerEl.scrollTo({ top: containerEl.scrollHeight, behavior });
+    } else {
+      containerEl.scrollTop = containerEl.scrollHeight;
+    }
     shouldStick = true;
     setIsAtBottom(true);
   }
 
+  let pendingFrame: number | undefined;
+
+  /**
+   * `cancelAnimationFrame`, captured at SETUP -- not called bare at cleanup.
+   *
+   * Cleanup is not guaranteed to run while the page that mounted this
+   * primitive is still standing: a host can tear its DOM globals down first
+   * (`component-register`'s `disconnectedCallback` defers a microtask; a
+   * test environment deletes the globals synchronously right after
+   * detaching). A bare `cancelAnimationFrame` there throws, surfacing as an
+   * unhandled rejection that fails a run in which every test passed --
+   * see tests/components/teardown-without-dom-globals.test.tsx, and the
+   * same pattern in create-tween.ts.
+   *
+   * Guarded because "setup" here is the component body, and a server render
+   * executes component bodies too; Node has neither global.
+   */
+  const cancelFrame = typeof cancelAnimationFrame === 'function'
+    ? cancelAnimationFrame.bind(globalThis)
+    : () => {};
+
   function onNewContent() {
     if (shouldStick) {
-      requestAnimationFrame(() => scrollToBottom('instant'));
+      pendingFrame = requestAnimationFrame(() => {
+        pendingFrame = undefined;
+        scrollToBottom('instant');
+      });
     }
   }
 
@@ -36,6 +64,10 @@ export function useStickToBottom() {
     onCleanup(() => {
       el.removeEventListener('scroll', checkIfAtBottom);
       observer.disconnect();
+      if (pendingFrame !== undefined) {
+        cancelFrame(pendingFrame);
+        pendingFrame = undefined;
+      }
     });
   }
 

package/src/primitives/use-text-stream.ts

@@ -5,6 +5,19 @@ export interface UseTextStreamOptions {
   speed?: number;
   characterChunkSize?: number;
   fadeDuration?: number;
+  segmentDelay?: number;
+}
+
+/** Default fade-in duration for a given speed (ms) — shared with ResponseStream. */
+export function defaultFadeDuration(speed: number): number {
+  const s = Math.min(100, Math.max(1, speed));
+  return Math.round(1000 / Math.sqrt(s));
+}
+
+/** Default per-segment stagger for a given speed (ms) — shared with ResponseStream. */
+export function defaultSegmentDelay(speed: number): number {
+  const s = Math.min(100, Math.max(1, speed));
+  return Math.max(1, Math.round(100 / Math.sqrt(s)));
 }
 
 export interface TextStreamSegment {
@@ -23,6 +36,7 @@ export function useTextStream(options: UseTextStreamOptions) {
   let fullText = '';
   let charIndex = 0;
   let intervalId: ReturnType<typeof setInterval> | undefined;
+  let completeTimeoutId: ReturnType<typeof setTimeout> | undefined;
   let isPaused = false;
   let asyncIterator: AsyncIterator<string> | undefined;
 
@@ -31,6 +45,10 @@ export function useTextStream(options: UseTextStreamOptions) {
       clearInterval(intervalId);
       intervalId = undefined;
     }
+    if (completeTimeoutId !== undefined) {
+      clearTimeout(completeTimeoutId);
+      completeTimeoutId = undefined;
+    }
   }
 
   function typewriterTick() {
@@ -76,8 +94,21 @@ export function useTextStream(options: UseTextStreamOptions) {
         const words = source.split(/(\s+)/).filter(Boolean);
         setSegments(words.map((text, index) => ({ text, index })));
         setDisplayedText(source);
-        // isComplete fires after animation has time to play
-        // (segments count * delay per segment from ResponseStream)
+        // Completion announces after the staggered animation has had time to
+        // play: segments * per-segment delay + one fade duration — the promise
+        // the comment here used to make with no code behind it (nothing on this
+        // path ever called setIsComplete(true), so kai-complete never fired for
+        // a fade-mode string). A timer, not a synchronous write: the consumer
+        // attaches its kai-complete listener a beat after mount, and a
+        // same-tick fire races past it.
+        const segDelay = typeof options.segmentDelay === 'number'
+          ? Math.max(0, options.segmentDelay)
+          : defaultSegmentDelay(speed);
+        const fadeDur = options.fadeDuration ?? defaultFadeDuration(speed);
+        completeTimeoutId = setTimeout(() => {
+          completeTimeoutId = undefined;
+          setIsComplete(true);
+        }, words.length * segDelay + fadeDur);
       }
     } else {
       if (options.mode === 'typewriter') {

package/src/remote/provider-runtime.ts

@@ -14,7 +14,7 @@ import { createPacker, isCardWireFrame, type WireMessage } from './wire';
 import { assertOrigin, redactFrame } from './origin';
 import { negotiateVersion } from './version';
 import { hasPollutionKey } from './validate';
-import { observeContentHeight } from '../primitives/use-resize-observer';
+import { observeDocumentHeight } from '../primitives/use-resize-observer';
 import { validateAgainstSchema, type JsonSchema } from '../primitives/card-validate';
 
 /** A provider-side renderer for one card `type`. Renamed (was CardRenderer) per H-K
@@ -105,10 +105,13 @@ export function createCardBridge(options: CreateCardBridgeOptions): CardBridge {
   }
 
   function startObserver(): void {
-    // Tear down any existing observer so observeContentHeight's internal `last` baseline
+    // Tear down any existing observer so observeDocumentHeight's internal `last` baseline
     // re-initializes to -1 and the newly-mounted card always emits its initial height.
+    // observeDocumentHeight (not observeContentHeight) so the reported height covers
+    // the FULL rendered document — root's own padding/border AND the provider page's
+    // body padding above it — not just root's ResizeObserver content-box (D1).
     stopObserver?.(); stopObserver = null;
-    stopObserver = observeContentHeight(root, (height) => {
+    stopObserver = observeDocumentHeight(root, (height) => {
       if (!currentId) return;
       cardHost.emit({ kind: 'resize', cardId: currentId, height });
     });

package/src/schemas/index.ts

@@ -279,6 +279,7 @@ export {
 } from './tool-defs';
 export type {
   AnthropicToolDef,
+  CardRequireRule,
   CardToolInput,
   CardToolOptions,
   CardToolSource,