@djangocfg/ui-tools 2.1.407 → 2.1.409

package/src/tools/Chat/highlight/__tests__/resolveRef.test.ts

@@ -0,0 +1,55 @@
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it } from 'vitest';
+
+import { resolveRefs, type RefResolver } from '../resolveRef';
+import type { CSTRefId } from '../types';
+
+afterEach(() => {
+  document.body.innerHTML = '';
+});
+
+/** A tiny resolver backed by a plain map, for tests. */
+function makeResolver(map: Record<string, HTMLElement | null>): RefResolver {
+  return {
+    resolve: (ref: CSTRefId) => map[ref] ?? null,
+  };
+}
+
+describe('resolveRefs', () => {
+  it('returns nothing without a resolver', () => {
+    expect(resolveRefs(['@e1'], null)).toEqual([]);
+  });
+
+  it('resolves known refs to connected elements', () => {
+    const el = document.createElement('button');
+    document.body.appendChild(el);
+    const resolver = makeResolver({ '@e1': el });
+
+    const out = resolveRefs(['@e1'], resolver);
+    expect(out).toHaveLength(1);
+    expect(out[0].ref).toBe('@e1');
+    expect(out[0].element).toBe(el);
+  });
+
+  it('drops refs the resolver does not know', () => {
+    const resolver = makeResolver({});
+    expect(resolveRefs(['@e9'], resolver)).toEqual([]);
+  });
+
+  it('drops elements detached from the DOM', () => {
+    // Created but never appended — not connected.
+    const orphan = document.createElement('div');
+    const resolver = makeResolver({ '@e2': orphan });
+    expect(resolveRefs(['@e2'], resolver)).toEqual([]);
+  });
+
+  it('resolves a batch, keeping only the live ones', () => {
+    const live = document.createElement('a');
+    document.body.appendChild(live);
+    const orphan = document.createElement('a');
+    const resolver = makeResolver({ '@e1': live, '@e2': orphan, '@e3': null });
+
+    const out = resolveRefs(['@e1', '@e2', '@e3'], resolver);
+    expect(out.map((o) => o.ref)).toEqual(['@e1']);
+  });
+});

package/src/tools/Chat/highlight/index.ts

@@ -0,0 +1,21 @@
+'use client';
+
+/**
+ * Chat highlight — AI-driven `point` directives.
+ *
+ * When the assistant returns `point` directives, this module resolves
+ * the CST refs to live elements and draws a spotlight overlay over
+ * them (and optionally focuses one). Read-only: it never changes the
+ * user's data.
+ */
+
+export { HighlightOverlay, type HighlightOverlayProps } from './HighlightOverlay';
+export { SpotlightCanvas, type SpotlightCanvasProps } from './SpotlightCanvas';
+export { useHighlightTargets } from './useHighlightTargets';
+export { resolveRefs, type RefResolver } from './resolveRef';
+export type {
+  PointDirective,
+  HighlightTarget,
+  SpotlightRect,
+  CSTRefId,
+} from './types';

package/src/tools/Chat/highlight/resolveRef.ts

@@ -0,0 +1,42 @@
+/**
+ * Resolve a CST ref id to a live DOM element.
+ *
+ * The page-snapshot engine assigns each interactive element a ref
+ * (`@e4`) during capture and keeps a `ref → element` registry. When the
+ * AI returns a `point` directive citing a ref, the chat resolves it
+ * back through that registry.
+ *
+ * A ref that no longer resolves is "stale" — the element was removed or
+ * the user navigated away. Callers treat a null result as stale.
+ */
+
+import type { CSTRefId } from './types';
+
+/**
+ * Minimal shape of a snapshot ref registry — `resolve(ref)` returns the
+ * element or null. Structurally compatible with the page-snapshot
+ * engine's `RefRegistry` without importing it (keeps the highlight
+ * module decoupled from the capture engine internals).
+ */
+export interface RefResolver {
+  resolve(ref: CSTRefId): HTMLElement | null;
+}
+
+/**
+ * Resolve a batch of refs to elements, dropping the ones that no longer
+ * exist. Returns pairs so the caller keeps the ref↔element association.
+ */
+export function resolveRefs(
+  refs: CSTRefId[],
+  resolver: RefResolver | null,
+): Array<{ ref: CSTRefId; element: HTMLElement }> {
+  if (!resolver) return [];
+  const out: Array<{ ref: CSTRefId; element: HTMLElement }> = [];
+  for (const ref of refs) {
+    const element = resolver.resolve(ref);
+    if (element && element.isConnected) {
+      out.push({ ref, element });
+    }
+  }
+  return out;
+}

package/src/tools/Chat/highlight/types.ts

@@ -0,0 +1,49 @@
+/**
+ * Types for the AI-driven highlight overlay.
+ *
+ * The assistant points at the page by CST ref id; the chat resolves
+ * each ref to a live element and this overlay draws a spotlight on it.
+ */
+
+/** A CST ref id, e.g. "@e4". */
+export type CSTRefId = `@e${number}`;
+
+/** A `point` directive as received from the backend SSE stream. */
+export interface PointDirective {
+  type: 'point';
+  /** CST ref of the target element. */
+  ref: CSTRefId;
+  /** Draw the highlight overlay (default: true). */
+  highlight?: boolean;
+  /** Move focus into the element once visible (default: false). */
+  focus?: boolean;
+  /** Optional short caption shown beside the highlight. */
+  label?: string;
+}
+
+/**
+ * One resolved highlight target — a directive whose ref was found in
+ * the live DOM, paired with its element and measured rect.
+ */
+export interface HighlightTarget {
+  /** The resolved DOM element. */
+  element: HTMLElement;
+  /** Measured bounding rect (viewport coords). */
+  rect: DOMRect;
+  /** Caption to render beside the highlight. */
+  label?: string;
+  /** Whether to move focus into the element. */
+  focus: boolean;
+}
+
+/**
+ * A geometry-only target the SVG renderer consumes — decoupled from the
+ * DOM element so the renderer stays a pure presentational component.
+ */
+export interface SpotlightRect {
+  rect: DOMRect;
+  /** Extra px around the element. */
+  padding: number;
+  /** Corner radius. */
+  radius: number;
+}

package/src/tools/Chat/highlight/useHighlightTargets.ts

@@ -0,0 +1,128 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+import { resolveRefs, type RefResolver } from './resolveRef';
+import type { HighlightTarget, PointDirective } from './types';
+
+/** Is a rect fully inside the viewport. */
+function isOnScreen(rect: DOMRect): boolean {
+  return (
+    rect.top >= 0 &&
+    rect.left >= 0 &&
+    rect.bottom <= window.innerHeight &&
+    rect.right <= window.innerWidth
+  );
+}
+
+/**
+ * Resolve `point` directives into live, geometry-tracked highlight
+ * targets.
+ *
+ * - resolves each ref to a DOM element (drops stale ones);
+ * - measures rects and keeps them fresh on scroll / resize;
+ * - scrolls the first off-screen target into view;
+ * - moves focus into a target when the directive asked for it;
+ * - drops a target automatically if its element leaves the DOM.
+ *
+ * One effect owns the whole lifecycle — resolve, side-effects, and the
+ * geometry subscription — so there is no ordering ambiguity between
+ * separate effects.
+ */
+export function useHighlightTargets(
+  directives: PointDirective[],
+  resolver: RefResolver | null,
+): HighlightTarget[] {
+  const [targets, setTargets] = useState<HighlightTarget[]>([]);
+
+  useEffect(() => {
+    // Resolve every directive that wants a highlight to a live element.
+    const wanted = directives.filter((d) => d.highlight !== false);
+    const resolved = resolveRefs(
+      wanted.map((d) => d.ref),
+      resolver,
+    );
+    const pairs = resolved
+      .map(({ ref, element }) => {
+        const directive = wanted.find((d) => d.ref === ref);
+        return directive ? { element, directive } : null;
+      })
+      .filter(
+        (p): p is { element: HTMLElement; directive: PointDirective } =>
+          p !== null,
+      );
+
+    if (pairs.length === 0) {
+      setTargets([]);
+      return;
+    }
+
+    // Measure all targets — called now and on every scroll / resize.
+    const measure = () => {
+      const next: HighlightTarget[] = [];
+      for (const { element, directive } of pairs) {
+        if (!element.isConnected) continue; // element left the DOM
+        next.push({
+          element,
+          rect: element.getBoundingClientRect(),
+          label: directive.label,
+          focus: directive.focus ?? false,
+        });
+      }
+      setTargets(next);
+    };
+
+    let frame = 0;
+    const schedule = () => {
+      cancelAnimationFrame(frame);
+      frame = requestAnimationFrame(measure);
+    };
+
+    // Scroll the first target into view if it is off-screen.
+    const first = pairs[0].element;
+    const firstOffScreen = !isOnScreen(first.getBoundingClientRect());
+    if (firstOffScreen) {
+      first.scrollIntoView({ behavior: 'smooth', block: 'center' });
+    }
+
+    // Focus a target if requested — after any scroll settles.
+    const focusPair = pairs.find((p) => p.directive.focus);
+    let focusTimer = 0;
+    if (focusPair) {
+      const el = focusPair.element;
+      focusTimer = window.setTimeout(
+        () => {
+          if (!el.isConnected) return;
+          // Make a non-focusable element focusable so focus() lands.
+          const nativelyFocusable = [
+            'INPUT',
+            'TEXTAREA',
+            'SELECT',
+            'BUTTON',
+            'A',
+          ].includes(el.tagName);
+          if (el.tabIndex < 0 && !nativelyFocusable) el.tabIndex = -1;
+          el.focus({ preventScroll: true });
+        },
+        firstOffScreen ? 400 : 0,
+      );
+    }
+
+    // Initial measure + keep geometry fresh.
+    measure();
+    window.addEventListener('scroll', schedule, true);
+    window.addEventListener('resize', schedule);
+    const observer = new ResizeObserver(schedule);
+    for (const { element } of pairs) observer.observe(element);
+
+    return () => {
+      cancelAnimationFrame(frame);
+      window.clearTimeout(focusTimer);
+      window.removeEventListener('scroll', schedule, true);
+      window.removeEventListener('resize', schedule);
+      observer.disconnect();
+    };
+  }, [directives, resolver]);
+
+  return targets;
+}

package/src/tools/Chat/hooks/index.ts

@@ -6,11 +6,6 @@ export {
   type UseChatComposerOptions,
   type UseChatComposerReturn,
 } from './useChatComposer';
-export {
-  useChatScroll,
-  type UseChatScrollOptions,
-  type UseChatScrollReturn,
-} from './useChatScroll';
 export { useChatHistory, type UseChatHistoryOptions } from './useChatHistory';
 export {
   useChatLayout,

package/src/tools/Chat/hooks/useAutoFocusOnStreamEnd.ts

@@ -3,13 +3,9 @@
 import { type RefObject, useEffect, useRef } from 'react';
 
 import { useChatContextOptional, type ComposerHandle } from '../context';
+import { useStreamEndFocus, type Focusable } from './useStreamEndFocus';
 
-/** Anything with a `.focus()` method — covers HTMLElement, the
- *  composer's textareaRef from `useChatComposer`, and any custom
- *  imperative handle exposing the same shape. */
-export interface Focusable {
-  focus: () => void;
-}
+export type { Focusable } from './useStreamEndFocus';
 
 export interface UseAutoFocusOnStreamEndOptions {
   /** True while an assistant reply is streaming. The hook fires the
@@ -43,22 +39,21 @@ export interface UseAutoFocusOnStreamEndOptions {
  * streaming. Standard chat UX: the user types → sends → reads the
  * reply → starts typing again without reaching for the mouse.
  *
- * Default (zero-config) usage — works the moment a `<Composer>` is
- * mounted inside a `<ChatProvider>`:
- *
- *   useAutoFocusOnStreamEnd();
+ * **You usually do NOT need to call this.** `<ChatProvider>` runs the
+ * stream-end focus internally, so every chat — `ChatRoot`, a hand-rolled
+ * `ChatProvider` + `Composer` layout, or a headless setup with a
+ * registered composer — gets it for free. Disable it provider-wide with
+ * `<ChatProvider autoFocusOnStreamEnd={false}>`.
  *
- * Custom composer / advanced wiring:
+ * Call this hook directly only for advanced cases the provider can't
+ * cover:
  *
+ *   // focus something OTHER than the composer (an approve button):
  *   const ref = useRef<{ focus: () => void } | null>(null);
  *   useAutoFocusOnStreamEnd({ targetRef: ref });
  *
- * Driving stream state yourself:
- *
+ *   // drive stream state from your own store:
  *   useAutoFocusOnStreamEnd({ isStreaming: myExternalStreaming });
- *
- * Only the true → false transition fires focus — toggling `enabled`
- * mid-stream won't steal focus while the user is reading.
  */
 export function useAutoFocusOnStreamEnd(
   options: UseAutoFocusOnStreamEndOptions = {},
@@ -68,38 +63,19 @@ export function useAutoFocusOnStreamEnd(
   // Prefer the prop (caller knows best), fall back to context.
   const isStreaming = isStreamingProp ?? ctx?.isStreaming ?? false;
 
-  // Keep latest ctx-composer in a ref so the focus effect always
-  // sees the freshest registered handle without re-firing when
-  // composers re-mount.
+  // Keep latest ctx-composer in a ref so target resolution always sees
+  // the freshest registered handle.
   const composerHandleRef = useRef<ComposerHandle | null>(null);
   composerHandleRef.current = ctx?.composer ?? null;
 
-  const prevStreamingRef = useRef(isStreaming);
-
-  useEffect(() => {
-    const wasStreaming = prevStreamingRef.current;
-    prevStreamingRef.current = isStreaming;
-
-    if (!enabled) return;
-    if (!(wasStreaming && !isStreaming)) return;
-
-    const focusNow = () => {
-      // Resolve target in priority order: explicit ref > registered
-      // composer handle. Refs may carry an HTMLElement (raw DOM) or
-      // any object with `.focus()`; both are handled by the same
-      // call site below.
-      const explicit = targetRef?.current as Focusable | null;
-      const target: Focusable | null = explicit ?? composerHandleRef.current;
-      target?.focus();
-    };
-
-    if (delayMs > 0) {
-      const id = window.setTimeout(focusNow, delayMs);
-      return () => window.clearTimeout(id);
-    }
-    const raf = requestAnimationFrame(focusNow);
-    return () => cancelAnimationFrame(raf);
-  }, [isStreaming, enabled, delayMs, targetRef]);
+  useStreamEndFocus({
+    isStreaming,
+    enabled,
+    delayMs,
+    // Resolve in priority order: explicit ref > registered composer.
+    resolveTarget: () =>
+      (targetRef?.current as Focusable | null) ?? composerHandleRef.current,
+  });
 }
 
 /**
@@ -122,9 +98,14 @@ export function useRegisterComposer(handle: ComposerHandle): void {
   const register = ctx?.registerComposer;
   const focus = handle.focus;
   const moveCursorToEnd = handle.moveCursorToEnd;
+  // Forward `getValue/setValue` too — voice dictation reads/writes the
+  // draft through them, so dropping them silently broke dictation for
+  // custom composers (e.g. the TipTap MarkdownEditor wrapper).
+  const getValue = handle.getValue;
+  const setValue = handle.setValue;
   useEffect(() => {
     if (!register) return;
-    register({ focus, moveCursorToEnd });
+    register({ focus, moveCursorToEnd, getValue, setValue });
     return () => register(null);
-  }, [register, focus, moveCursorToEnd]);
+  }, [register, focus, moveCursorToEnd, getValue, setValue]);
 }

package/src/tools/Chat/hooks/useChat.ts

@@ -10,7 +10,7 @@ import type {
   ChatTransport,
   ChatToolCall,
 } from '../types';
-import { LIMITS } from '../config';
+import { LIMITS } from '../constants';
 import {
   type ChatState,
   initialState,
@@ -20,6 +20,7 @@ import {
 import { createId } from '../core/ids';
 import { getChatLogger } from '../core/logger';
 import { createTokenBuffer } from '../core/markdown';
+import { resolveSendMetadata } from '../core/metadata';
 
 export interface UseChatConfig {
   transport: ChatTransport;
@@ -47,6 +48,17 @@ export interface UseChatConfig {
    * sees plain text, while the bubble keeps the chip rendering. Plan64.
    */
   onBeforeSend?: (content: string) => string | Promise<string>;
+  /**
+   * Contribute extra transport metadata, computed fresh at send time.
+   * Invoked synchronously right before each `transport.stream/send`,
+   * and the result is merged over the static `metadata`. Returning
+   * `undefined` adds nothing.
+   *
+   * Use case: the page-context snapshot — captured per message
+   * (capture-on-submit) and carried as a separate `metadata` field,
+   * never mixed into the message content.
+   */
+  getDynamicMetadata?: () => Record<string, unknown> | undefined;
   /**
    * Enable verbose dev-mode logging (consola, namespace `chat:*`).
    * Defaults to `isDev` from `@djangocfg/ui-core/lib`. Pass `false` to silence
@@ -228,11 +240,16 @@ export function useChat(config: UseChatConfig): UseChatReturn {
       abortRef.current = ctrl;
       const assistantId = createId('a');
       streamingMsgIdRef.current = assistantId;
+      // The message id that subsequent events (chunks, tool calls, done)
+      // target. Starts as the freshly-created placeholder; on a
+      // `resume_start` it is repointed to the resumed assistant message
+      // so STREAM_DONE / TOOL_CALL_* don't land on a removed placeholder.
+      let targetId = assistantId;
 
       const iterator = transport.stream(sessionId, content, {
         signal: ctrl.signal,
         attachments,
-        metadata: config.metadata,
+        metadata: resolveSendMetadata(config.metadata, config.getDynamicMetadata),
       });
 
       // Peek at the first event — if it's `resume_start` we reuse the last assistant
@@ -264,6 +281,19 @@ export function useChat(config: UseChatConfig): UseChatReturn {
             // just-created empty placeholder and mark the last assistant msg streaming.
             dispatch({ type: 'STREAM_CANCEL_PLACEHOLDER', id: assistantId });
             dispatch({ type: 'STREAM_RESUME_EXISTING' });
+            // Repoint the event target at the resumed message. Without
+            // this, every subsequent chunk / tool call / message_end
+            // dispatches against the removed placeholder id and is lost
+            // — the resumed bubble would stream forever (isStreaming
+            // never cleared) and tool panels would never appear.
+            for (let i = stateRef.current.messages.length - 1; i >= 0; i -= 1) {
+              const m = stateRef.current.messages[i];
+              if (m.role === 'assistant' && m.isStreaming) {
+                targetId = m.id;
+                streamingMsgIdRef.current = m.id;
+                break;
+              }
+            }
           } else {
             peekedEvent = ev;
           }
@@ -279,10 +309,10 @@ export function useChat(config: UseChatConfig): UseChatReturn {
 
         // If transport never emitted message_end, finalize manually.
         if (stateRef.current.isStreaming) {
-          dispatch({ type: 'STREAM_DONE', id: assistantId });
+          dispatch({ type: 'STREAM_DONE', id: targetId });
         }
 
-        const finalMsg = stateRef.current.messages.find((m) => m.id === assistantId);
+        const finalMsg = stateRef.current.messages.find((m) => m.id === targetId);
         if (finalMsg) config.onMessageEnd?.(finalMsg);
         log.stream.success('done', {
           assistantId,
@@ -294,14 +324,14 @@ export function useChat(config: UseChatConfig): UseChatReturn {
         tokenBuffer.close();
         if (ctrl.signal.aborted) {
           const partial =
-            stateRef.current.messages.find((m) => m.id === assistantId)?.content ?? '';
-          dispatch({ type: 'STREAM_CANCELLED', id: assistantId, partialText: partial });
-          log.stream.warn('cancelled', { assistantId, partialChars: partial.length });
+            stateRef.current.messages.find((m) => m.id === targetId)?.content ?? '';
+          dispatch({ type: 'STREAM_CANCELLED', id: targetId, partialText: partial });
+          log.stream.warn('cancelled', { assistantId: targetId, partialChars: partial.length });
           return;
         }
         const e = err instanceof Error ? err : new Error(String(err));
         lastErrorRef.current = e;
-        dispatch({ type: 'STREAM_ERROR', id: assistantId, message: e.message });
+        dispatch({ type: 'STREAM_ERROR', id: targetId, message: e.message });
         config.onError?.(e);
         log.error.error('stream failed', { assistantId, message: e.message });
       } finally {
@@ -338,7 +368,7 @@ export function useChat(config: UseChatConfig): UseChatReturn {
             };
             dispatch({
               type: 'TOOL_CALL_START',
-              messageId: assistantId,
+              messageId: targetId,
               toolCall,
             });
             log.tools.info('call_start', { toolId: ev.toolId, name: ev.name });
@@ -347,7 +377,7 @@ export function useChat(config: UseChatConfig): UseChatReturn {
           case 'tool_call_delta':
             dispatch({
               type: 'TOOL_CALL_DELTA',
-              messageId: assistantId,
+              messageId: targetId,
               toolId: ev.toolId,
               delta: ev.delta,
             });
@@ -355,7 +385,7 @@ export function useChat(config: UseChatConfig): UseChatReturn {
           case 'tool_call_end':
             dispatch({
               type: 'TOOL_CALL_END',
-              messageId: assistantId,
+              messageId: targetId,
               toolId: ev.toolId,
               output: ev.output,
               status: ev.status,
@@ -366,7 +396,7 @@ export function useChat(config: UseChatConfig): UseChatReturn {
             tokenBuffer.flush();
             dispatch({
               type: 'STREAM_DONE',
-              id: assistantId,
+              id: targetId,
               tokensIn: ev.tokensIn,
               tokensOut: ev.tokensOut,
               sources: ev.sources,
@@ -381,7 +411,7 @@ export function useChat(config: UseChatConfig): UseChatReturn {
             tokenBuffer.flush();
             dispatch({
               type: 'STREAM_ERROR',
-              id: assistantId,
+              id: targetId,
               message: ev.message,
             });
             log.error.error('stream event error', { code: ev.code, message: ev.message });
@@ -402,7 +432,7 @@ export function useChat(config: UseChatConfig): UseChatReturn {
         const reply = await transport.send(sessionId, content, {
           signal: ctrl.signal,
           attachments,
-          metadata: config.metadata,
+          metadata: resolveSendMetadata(config.metadata, config.getDynamicMetadata),
         });
         const placeholderId = createId('a');
         dispatch({ type: 'STREAM_START', id: placeholderId });
@@ -411,6 +441,9 @@ export function useChat(config: UseChatConfig): UseChatReturn {
         dispatch({ type: 'STREAM_DONE', id: placeholderId });
         config.onMessageEnd?.(reply);
       } catch (err) {
+        // A user-initiated cancel (cancelStream / newSession) aborts the
+        // controller — that's not an error, so don't raise the banner.
+        if (ctrl.signal.aborted) return;
         const e = err instanceof Error ? err : new Error(String(err));
         lastErrorRef.current = e;
         dispatch({ type: 'STREAM_ERROR', message: e.message });

package/src/tools/Chat/hooks/useChatComposer.ts

@@ -12,8 +12,8 @@ import {
 } from 'react';
 
 import type { ChatAttachment } from '../types';
-import { LIMITS } from '../config';
-import { sanitizeDraft } from '../utils/sanitizeDraft';
+import { LIMITS } from '../constants';
+import { sanitizeDraft } from '../utils';
 
 export interface UseChatComposerOptions {
   onSubmit: (content: string, attachments: ChatAttachment[]) => void | Promise<void>;

package/src/tools/Chat/hooks/useChatLayout.ts

@@ -4,7 +4,7 @@ import { useCallback, useEffect, useMemo, useState } from 'react';
 
 import { useLocalStorage, useMediaQuery } from '@djangocfg/ui-core/hooks';
 
-import { CSS_VARS, DEFAULT_SIDEBAR, STORAGE_KEYS } from '../config';
+import { CSS_VARS, DEFAULT_SIDEBAR, STORAGE_KEYS } from '../constants';
 import type { ChatDisplayMode } from '../types';
 
 export interface UseChatLayoutConfig {

package/src/tools/Chat/hooks/useStreamEndFocus.ts

@@ -0,0 +1,54 @@
+'use client';
+
+import { useEffect, useRef } from 'react';
+
+/** Anything with a `.focus()` method. */
+export interface Focusable {
+  focus: () => void;
+}
+
+/**
+ * Core stream-end focus effect — context-free on purpose so it can run
+ * *inside* `ChatProvider` without an import cycle (`context` →
+ * `hooks/useAutoFocusOnStreamEnd` → `context`).
+ *
+ * Fires `resolveTarget().focus()` on the streaming true → false edge.
+ * Both `ChatProvider` and the public `useAutoFocusOnStreamEnd` hook
+ * delegate here.
+ */
+export function useStreamEndFocus(params: {
+  isStreaming: boolean;
+  enabled: boolean;
+  delayMs: number;
+  /** Resolves the focus target lazily, at fire time — so it always
+   *  sees the freshest registered composer handle. */
+  resolveTarget: () => Focusable | null;
+}): void {
+  const { isStreaming, enabled, delayMs, resolveTarget } = params;
+
+  // Keep the resolver in a ref so the effect doesn't re-fire when the
+  // caller passes a fresh closure each render.
+  const resolveRef = useRef(resolveTarget);
+  resolveRef.current = resolveTarget;
+
+  const prevStreamingRef = useRef(isStreaming);
+
+  useEffect(() => {
+    const wasStreaming = prevStreamingRef.current;
+    prevStreamingRef.current = isStreaming;
+
+    if (!enabled) return;
+    // Only the true → false transition fires focus — toggling `enabled`
+    // mid-stream won't steal focus while the user is reading.
+    if (!(wasStreaming && !isStreaming)) return;
+
+    const focusNow = () => resolveRef.current()?.focus();
+
+    if (delayMs > 0) {
+      const id = window.setTimeout(focusNow, delayMs);
+      return () => window.clearTimeout(id);
+    }
+    const raf = requestAnimationFrame(focusNow);
+    return () => cancelAnimationFrame(raf);
+  }, [isStreaming, enabled, delayMs]);
+}