@djangocfg/ui-tools 2.1.415 → 2.1.417

package/src/tools/chat/composer/slash/state.ts

@@ -0,0 +1,168 @@
+/**
+ * Slash-command state machine — pure functions, no React.
+ *
+ * A small model for the composer's `/` surface: derive `SlashState` from
+ * the raw editor value, narrow the verb list by a filter, and produce
+ * the next editor value when a verb is picked.
+ *
+ * Triggering rule: a slash verb only counts when it is the first token
+ * of the buffer (`"/clear"` matches, `"hello /clear"` does not). The
+ * caret is irrelevant — the machine is buffer-shape driven, matching
+ * the Warp `slash_command_model.rs` design the cmdop port came from.
+ *
+ * Layering: this file imports types only — keep it React-free so it
+ * stays trivially unit-testable.
+ */
+import type { SlashCommand, SlashState } from './types';
+
+/** A `/verb` only counts when it is the very first token of the input. */
+const SLASH_RE = /^\/([a-zA-Z][\w-]*)?(?:[ \n]([\s\S]*))?$/;
+
+/**
+ * Derive the slash state from the raw editor value.
+ *
+ * - Buffer empty or not starting with `/` → `none`.
+ * - `/`, `/c`, `/cle` (no space yet) → `composing` with `filter`.
+ * - `/clear`, `/clear stuff` (verb followed by space) → `command` if
+ *   `verb` matches a known id, else `none`.
+ */
+export function parseSlashState(
+  value: string,
+  commands: readonly SlashCommand[],
+): SlashState {
+  if (!value.startsWith('/')) return { kind: 'none' };
+  const m = SLASH_RE.exec(value);
+  if (!m) return { kind: 'none' };
+  const verb = (m[1] ?? '').toLowerCase();
+  const rest = m[2];
+  // The buffer has advanced past the verb (a space/newline follows).
+  if (rest !== undefined) {
+    const command = commands.find((c) => c.id === verb);
+    if (!command) return { kind: 'none' };
+    return { kind: 'command', command, argument: rest };
+  }
+  // Still typing the verb — `/` alone or `/cle`.
+  return { kind: 'composing', filter: verb };
+}
+
+/**
+ * Narrow a verb list by the `composing` filter.
+ *
+ * Empty filter returns every command in input order. Otherwise the
+ * filter is matched (case-insensitive) against `id`, `token`, `label`
+ * and any `keywords`: prefix matches rank above substring matches.
+ */
+export function filterCommands(
+  commands: readonly SlashCommand[],
+  filter: string,
+): SlashCommand[] {
+  const q = filter.trim().toLowerCase();
+  if (q.length === 0) return [...commands];
+  const scored: { cmd: SlashCommand; score: number; idx: number }[] = [];
+  commands.forEach((cmd, idx) => {
+    const terms = [cmd.id, cmd.token, cmd.label, ...(cmd.keywords ?? [])];
+    let best = -1;
+    for (const term of terms) {
+      const t = term.toLowerCase();
+      if (t.startsWith(q) || t.startsWith(`/${q}`)) best = Math.max(best, 2);
+      else if (t.includes(q)) best = Math.max(best, 1);
+    }
+    if (best >= 0) scored.push({ cmd, score: best, idx });
+  });
+  scored.sort((a, b) => (b.score - a.score) || (a.idx - b.idx));
+  return scored.map((s) => s.cmd);
+}
+
+/**
+ * What should happen when the user picks a verb in the menu.
+ *
+ * - `execute` — the command explicitly opted in via `autoExecute: true`.
+ *   The host should call `command.onExecute?.()` and clear the editor
+ *   buffer. Use for action commands that produce no chat message.
+ * - `insert`  — default. The host should replace the leading `/partial`
+ *   with `text` (which is `<token> `) so the user can keep typing and
+ *   submit normally.
+ */
+export type SlashCommandAction =
+  | { kind: 'execute'; command: SlashCommand }
+  | { kind: 'insert'; command: SlashCommand; text: string };
+
+/**
+ * Decide whether a picked verb runs immediately or just inserts a token.
+ *
+ * Pure — does not touch the editor value. The React layer in
+ * `useSlashCommands` consumes this to branch between `onExecute`
+ * + clear-buffer and `applyCommand` + keep-buffer.
+ *
+ * Default is `insert`. Only `autoExecute === true` triggers `execute`
+ * — `argHint` is display-only and does NOT influence this decision.
+ */
+export function resolveCommandAction(
+  value: string,
+  command: SlashCommand,
+): SlashCommandAction {
+  const shouldAutoExecute = command.autoExecute === true;
+  if (shouldAutoExecute) return { kind: 'execute', command };
+  return { kind: 'insert', command, text: applyCommand(value, command) };
+}
+
+/**
+ * Find the `/verb` slice at the start of the buffer (if any). Returns
+ * the matched token + its end offset so an overlay-mirror highlighter
+ * can wrap the exact same characters the parser considers a slash verb.
+ *
+ * - `/`, `/cle` (still composing)         → returns the partial slice.
+ * - `/clear`, `/clear stuff` (resolved)   → returns the bare `/verb`.
+ * - `hello /clear` (slash not at start)   → returns `null`.
+ */
+export function extractSlashToken(
+  value: string,
+): { token: string; end: number } | null {
+  if (!value.startsWith('/')) return null;
+  const m = SLASH_RE.exec(value);
+  if (!m) return null;
+  const verb = m[1] ?? '';
+  const token = `/${verb}`;
+  return { token, end: token.length };
+}
+
+/**
+ * Whether the current buffer is a slash command that may be submitted.
+ *
+ * Returns `true` when the buffer is NOT a resolved slash command — the
+ * host decides on its own emptiness gates for plain messages. Returns
+ * `true` for resolved commands whose `argHint` is unset (the command is
+ * self-contained) and whose `autoExecute` is not `true`. Returns
+ * `false` when:
+ *
+ *  - the resolved command has `autoExecute: true` (action commands are
+ *    picked from the menu, not submitted as a text message),
+ *  - or the resolved command declares an `argHint` and the trimmed
+ *    argument is empty.
+ *
+ * Pure — no React, no DOM. The composer uses this to gate the Send
+ * button + Enter keypress so half-typed `/note` etc. cannot be
+ * submitted as a message.
+ */
+export function isSubmittableSlash(
+  value: string,
+  commands: readonly SlashCommand[],
+): boolean {
+  const state = parseSlashState(value, commands);
+  if (state.kind !== 'command') return true;
+  if (state.command.autoExecute === true) return false;
+  if (!state.command.argHint) return true;
+  return state.argument.trim().length > 0;
+}
+
+/**
+ * Apply a picked command to the editor value — replaces the leading
+ * `/partial` with `"<token> "` so the user can immediately type the
+ * argument. Any existing argument text is preserved.
+ */
+export function applyCommand(value: string, command: SlashCommand): string {
+  const m = SLASH_RE.exec(value);
+  const rest = m?.[2];
+  const tail = rest !== undefined && rest.length > 0 ? rest : '';
+  return `${command.token} ${tail}`;
+}

package/src/tools/chat/composer/slash/types.ts

@@ -0,0 +1,64 @@
+'use client';
+
+/**
+ * Slash-command types — public surface for the composer's `/` UI.
+ *
+ * Pure type module — no React, no DOM, no side effects. Safe to import
+ * from anywhere (including the pure state machine in `state.ts`).
+ */
+import type { ReactNode } from 'react';
+
+/** One slash verb the composer exposes in the dropdown. */
+export interface SlashCommand {
+  /** Stable id — verb without the leading slash (e.g. `"clear"`). */
+  id: string;
+  /** Display token incl. the slash (e.g. `"/clear"`). */
+  token: string;
+  /** Row label — short, action-style ("Clear conversation"). */
+  label: string;
+  /** Optional one-line description shown beneath the label. */
+  description?: string;
+  /**
+   * Display-only hint rendered next to the label in the menu (e.g.
+   * `<text>`, `<host>`). Does NOT affect selection behavior — use
+   * `autoExecute` to control whether picking runs immediately.
+   */
+  argHint?: string;
+  /** Optional row icon — host-supplied so this module ships zero icon deps. */
+  icon?: ReactNode;
+  /** Extra match terms beyond `id` (aliases used by `filterCommands`). */
+  keywords?: readonly string[];
+  /**
+   * Optional executor. When `autoExecute: true`, the composer invokes
+   * this on selection (with `''` as args) and clears the buffer. For
+   * insert-style commands (the default) hosts typically call this
+   * themselves on submit, with the user-typed arguments.
+   */
+  onExecute?: (args: string) => void | Promise<void>;
+  /**
+   * When true, picking this command runs `onExecute()` immediately and
+   * clears the composer buffer (no `/verb` is inserted). Default false —
+   * commands are inserted as `/verb ` with the cursor positioned for
+   * argument entry, and submitted by the user as a normal message.
+   *
+   * Set to `true` for action commands that should not produce a message
+   * (e.g. `/clear`, `/settings`, `/help`).
+   */
+  autoExecute?: boolean;
+}
+
+/**
+ * Three states of the slash machine — the editor either has no leading
+ * slash (`none`), is typing a verb (`composing`, menu open), or has
+ * resolved a known verb followed by free-text args (`command`).
+ */
+export type SlashState =
+  | { kind: 'none' }
+  | { kind: 'composing'; filter: string }
+  | { kind: 'command'; command: SlashCommand; argument: string };
+
+/** Per-composer slash config — currently just the verb list. */
+export interface SlashConfig {
+  /** The verbs available in this composer instance. */
+  commands: SlashCommand[];
+}

package/src/tools/chat/composer/slash/useSlashCommands.ts

@@ -0,0 +1,204 @@
+'use client';
+
+/**
+ * `useSlashCommands` — React glue over the pure slash machine.
+ *
+ * Given the live editor value, exposes:
+ *   - the current `SlashState`,
+ *   - the filtered verb list while composing,
+ *   - a `highlight` index + keyboard handler for the menu,
+ *   - `pick(cmd)` which either executes the verb (`autoExecute: true`)
+ *     or inserts `"<token> "` so the user can type arguments (default),
+ *   - `clear()` which strips the leading slash to close the menu.
+ *
+ * The hook owns no editor state — the host passes `value` in and
+ * applies the strings `pick` / `onKeyDown` hand back to its editor's
+ * setter. This keeps it usable from the chat composer (driven by
+ * `useChatComposer`) and from any plain `useState` driven input.
+ */
+import { useCallback, useMemo, useState, type KeyboardEvent } from 'react';
+
+import {
+  filterCommands,
+  isSubmittableSlash,
+  parseSlashState,
+  resolveCommandAction,
+} from './state';
+import type { SlashCommand, SlashState } from './types';
+
+export interface UseSlashCommandsOptions {
+  /** Live editor value (the full draft). */
+  value: string;
+  /** Verb set surfaced to the user. */
+  commands: readonly SlashCommand[];
+  /**
+   * Apply a new editor value. Called by `pick` (after an `insert`
+   * action), `clear` (Escape), and the auto-execute branch (clears
+   * the buffer after running the command).
+   */
+  onApply: (next: string) => void;
+}
+
+export interface UseSlashCommandsReturn {
+  /** Current machine state — `none | composing | command`. */
+  state: SlashState;
+  /** True while the dropdown should be visible (including empty-match state). */
+  isOpen: boolean;
+  /** Filtered verbs (empty list is possible when `isOpen` is true). */
+  matches: SlashCommand[];
+  /** Current filter string (the partial verb after the leading slash). */
+  query: string;
+  /** Index of the highlighted row in `matches`. */
+  highlight: number;
+  /** Set the highlight index (pointer-move sync). */
+  setHighlight: (i: number) => void;
+  /** The resolved verb once `state.kind === "command"`, else null. */
+  active: SlashCommand | null;
+  /**
+   * Whether the current buffer may be submitted as a chat message.
+   *
+   * Mirrors `isSubmittableSlash(value, commands)`. The composer ANDs
+   * this with `composer.canSubmit` to disable Send and turn Enter into
+   * a no-op while a slash command is missing its required argument or
+   * is an `autoExecute` action (which must be picked from the menu,
+   * not dispatched as a text message).
+   *
+   * When `commands` is empty (slash effectively disabled) this is
+   * always `true` — the gate is a no-op.
+   */
+  canSubmit: boolean;
+  /**
+   * Apply a verb. Commands with `autoExecute: true` invoke
+   * `command.onExecute?.('')` and clear the buffer. All other commands
+   * (the default) replace the leading `/partial` with `"<token> "` so
+   * the caret lands on the argument, and the user submits normally.
+   */
+  pick: (command: SlashCommand) => void;
+  /** Close the menu by dropping the leading slash. */
+  clear: () => void;
+  /**
+   * Keydown handler for the host editor. Consumes ↑/↓/Enter/Tab/Esc
+   * while the menu is open (calling `e.preventDefault()`); otherwise
+   * the event passes through untouched.
+   */
+  onKeyDown: (e: KeyboardEvent<HTMLElement>) => void;
+}
+
+export function useSlashCommands({
+  value,
+  commands,
+  onApply,
+}: UseSlashCommandsOptions): UseSlashCommandsReturn {
+  const [highlight, setHighlightState] = useState(0);
+
+  const state = useMemo(
+    () => parseSlashState(value, commands),
+    [value, commands],
+  );
+
+  const matches = useMemo(
+    () =>
+      state.kind === 'composing'
+        ? filterCommands(commands, state.filter)
+        : [],
+    [state, commands],
+  );
+
+  // Menu stays open for the whole `composing` state — even when the
+  // filter narrows to nothing, so we can render a "No commands match"
+  // line instead of silently closing on the user.
+  const isOpen = state.kind === 'composing';
+  const query = state.kind === 'composing' ? state.filter : '';
+  const active = state.kind === 'command' ? state.command : null;
+  // Empty `commands` means slash is effectively off — never block submit
+  // (the composer instantiates the hook unconditionally, see Composer.tsx).
+  const canSubmit = useMemo(
+    () => (commands.length === 0 ? true : isSubmittableSlash(value, commands)),
+    [value, commands],
+  );
+
+  // Clamp the highlight whenever the match list shrinks.
+  const safeHighlight =
+    matches.length > 0 ? Math.min(highlight, matches.length - 1) : 0;
+
+  const setHighlight = useCallback((i: number) => {
+    setHighlightState(i);
+  }, []);
+
+  const pick = useCallback(
+    (command: SlashCommand) => {
+      const action = resolveCommandAction(value, command);
+      if (action.kind === 'execute') {
+        // Fire-and-forget; the host owns error handling. Clear the
+        // buffer so the dropdown closes and the next draft starts fresh.
+        try {
+          void command.onExecute?.('');
+        } finally {
+          onApply('');
+        }
+      } else {
+        onApply(action.text);
+      }
+      setHighlightState(0);
+    },
+    [value, onApply],
+  );
+
+  const clear = useCallback(() => {
+    onApply(value.replace(/^\//, ''));
+    setHighlightState(0);
+  }, [value, onApply]);
+
+  const onKeyDown = useCallback(
+    (e: KeyboardEvent<HTMLElement>) => {
+      if (!isOpen) return;
+      switch (e.key) {
+        case 'ArrowDown':
+          if (matches.length === 0) return;
+          e.preventDefault();
+          setHighlightState((h) => (h + 1) % matches.length);
+          break;
+        case 'ArrowUp':
+          if (matches.length === 0) return;
+          e.preventDefault();
+          setHighlightState((h) => (h - 1 + matches.length) % matches.length);
+          break;
+        case 'Enter':
+        case 'Tab': {
+          // When there are no matches, swallow Enter so the composer
+          // doesn't submit a `/xyzzy` literal — but leave Tab to the
+          // browser so focus management still works.
+          if (matches.length === 0) {
+            if (e.key === 'Enter') e.preventDefault();
+            return;
+          }
+          e.preventDefault();
+          const sel = matches[safeHighlight];
+          if (sel) pick(sel);
+          break;
+        }
+        case 'Escape':
+          e.preventDefault();
+          clear();
+          break;
+        default:
+          break;
+      }
+    },
+    [isOpen, matches, safeHighlight, pick, clear],
+  );
+
+  return {
+    state,
+    isOpen,
+    matches,
+    query,
+    highlight: safeHighlight,
+    setHighlight,
+    active,
+    canSubmit,
+    pick,
+    clear,
+    onKeyDown,
+  };
+}

package/src/tools/chat/composer/types.ts

@@ -4,6 +4,7 @@ import type { ComponentType, ReactNode } from 'react';
 
 import type { UseChatComposerReturn } from '../hooks/useChatComposer';
 import type { ChatAttachment } from '../types';
+import type { SlashConfig } from './slash/types';
 
 /** Composer visual size — shared across the `<Composer>` API. */
 export type ComposerSize = 'sm' | 'md' | 'lg';
@@ -68,6 +69,13 @@ export interface ComposerSlots {
   inlineStart?: ReactNode;
   /** Raw nodes placed right of the textarea in the `inline` layout. */
   inlineEnd?: ReactNode;
+  /**
+   * Slash-command surface. When provided, the composer mounts an
+   * internal `<SlashMenu>` as a floating popover anchored above the
+   * input surface and routes ↑/↓/Enter/Tab/Esc to the slash hook
+   * while the menu is open. See `./slash/README.md`.
+   */
+  slashCommands?: SlashConfig;
 }
 
 // ── Tier B — full slot replacement ─────────────────────────────────────────

package/src/tools/chat/context/ChatProvider.tsx

@@ -8,9 +8,10 @@ import {
   useEffect,
   useMemo,
   useRef,
-  useState,
 } from 'react';
 
+import { getActiveComposer } from '@djangocfg/ui-tools/composer-registry';
+
 import type { ChatConfig, ChatLabels, ChatTransport } from '../types';
 import { DEFAULT_LABELS } from '../types';
 import type { BlockRegistry } from '../messages/blocks';
@@ -34,18 +35,12 @@ import type { ChatAudioConfig, UseChatAudioReturn } from '../core/audio/types';
  *  Consumed by `VoiceComposerSlot` for the focus / move-caret behaviour
  *  during live dictation.
  */
-export interface ComposerHandle {
-  focus: () => void;
-  /** Move the caret to the very end of the input. */
-  moveCursorToEnd?: () => void;
-  /** Read the current draft text. Needed by voice dictation to anchor
-   *  partial transcripts onto the user's already-typed prefix. */
-  getValue?: () => string;
-  /** Replace the current draft text. Voice dictation uses this to push
-   *  interim + final transcripts into the composer without owning a
-   *  controlled binding. */
-  setValue?: (value: string) => void;
-}
+// `ComposerHandle` lives in `@djangocfg/ui-tools/composer-registry` —
+// the cross-tool registry shared by chat (producer) and
+// speech-recognition (consumer). Re-export here so existing call sites
+// `import { ComposerHandle } from '@djangocfg/ui-tools/chat'` keep
+// working unchanged.
+export type { ComposerHandle } from '@djangocfg/ui-tools/composer-registry';
 
 export interface ChatContextValue extends UseChatReturn {
   layout: UseChatLayoutReturn;
@@ -56,13 +51,6 @@ export interface ChatContextValue extends UseChatReturn {
    * Components like ``AudioToggle`` use this to auto-hide when there
    * is nothing to mute. */
   hasAudio: boolean;
-  /** Composer registry. The built-in `<Composer>` calls
-   *  `registerComposer({ focus })` on mount; custom composers (e.g.
-   *  cmdop's MarkdownEditor wrapper) do the same via the
-   *  `useRegisterComposer` helper. Read it via `composer?.focus()` —
-   *  null until any composer has mounted. Plan64 follow-up. */
-  composer: ComposerHandle | null;
-  registerComposer: (handle: ComposerHandle | null) => void;
   /** Registry of `kind` → renderer for `message.blocks`. `null` when the
    *  host wired none — `<MessageBubble>` then uses `BUILTIN_BLOCK_REGISTRY`. */
   blockRegistry: BlockRegistry | null;
@@ -70,48 +58,6 @@ export interface ChatContextValue extends UseChatReturn {
 
 const Ctx = createContext<ChatContextValue | null>(null);
 
-// ─── Dual-bundle guard ────────────────────────────────────────────────────
-//
-// `@djangocfg/ui-tools` ships its root export through `dist/` (compiled) but
-// most subpaths resolve to raw `src/`. If a consumer mixes them — e.g.
-// `ChatRoot` from the root barrel and `VoiceComposerSlot` from
-// `@djangocfg/ui-tools/speech-recognition` — `createContext(...)` runs twice
-// and produces two distinct context instances. The Composer registers its
-// handle on one; `useChatContextOptional()` in the voice slot reads from the
-// other, sees `null`, and silently drops every transcript.
-//
-// We tag the global with our module identity. When more than one tag is
-// observed the consumer is told exactly what to do.
-type GuardSlot = { stamps: Set<symbol>; warned: boolean };
-const GLOBAL_KEY = '__djangocfg_chat_ctx_stamps__';
-const stamp = Symbol('djangocfg.chat.ctx');
-function markCtxLoad(): void {
-  if (typeof globalThis === 'undefined') return;
-  const g = globalThis as unknown as Record<string, GuardSlot | undefined>;
-  let slot = g[GLOBAL_KEY];
-  if (!slot) {
-    slot = { stamps: new Set(), warned: false };
-    g[GLOBAL_KEY] = slot;
-  }
-  slot.stamps.add(stamp);
-  if (slot.stamps.size > 1 && !slot.warned && process.env.NODE_ENV !== 'production') {
-    slot.warned = true;
-    // eslint-disable-next-line no-console
-    console.warn(
-      '[@djangocfg/ui-tools/chat] Two ChatProvider context instances detected — ' +
-        'this means `@djangocfg/ui-tools` was loaded twice (one bundle via the root ' +
-        '`.` export → `dist/`, another via a `./chat` / `./speech-recognition` subpath → `src/`). ' +
-        'Symptom: `useChatContextOptional()` returns `null` for descendants of `<ChatProvider>`, ' +
-        'so VoiceComposerSlot drops transcripts, useChatReset silently no-ops, etc. ' +
-        '\n\nFix: import every Chat surface from the SAME subpath. Recommended:\n' +
-        "  import { ChatRoot, ChatLauncher, useChatContextOptional, … } from '@djangocfg/ui-tools/chat';\n" +
-        "  import { VoiceComposerSlot } from '@djangocfg/ui-tools/speech-recognition';\n" +
-        '\n(See packages/ui-tools/src/tools/Chat/README.md → "Anti-patterns".)',
-    );
-  }
-}
-markCtxLoad();
-
 export interface ChatProviderProps {
   transport: ChatTransport;
   config?: ChatConfig;
@@ -240,26 +186,17 @@ export function ChatProvider({
     );
   }, [audio]);
 
-  // Composer registry — kept in state (not a ref) so consumers
-  // observing `ctx.composer` re-render when a composer mounts /
-  // unmounts. The setter is the API surface; pass it to the composer
-  // on mount and call with `null` on unmount.
-  const [composer, setComposer] = useState<ComposerHandle | null>(null);
-  const registerComposer = useCallback((handle: ComposerHandle | null) => {
-    setComposer(handle);
-  }, []);
-
   // Re-focus the composer on the streaming → idle edge. Lives here (not
   // in `ChatRoot`) so it works for *every* usage pattern — `ChatRoot`,
   // a hand-rolled `ChatProvider` + `Composer` layout, or headless — as
-  // long as a composer registered its handle.
-  const composerRef = useRef<ComposerHandle | null>(composer);
-  composerRef.current = composer;
+  // long as a composer registered its handle. The active handle lives
+  // in `@djangocfg/ui-tools/composer-registry` — a single cross-tool
+  // registry shared with `<VoiceComposerSlot>`.
   useStreamEndFocus({
     isStreaming: chat.isStreaming,
     enabled: autoFocusOnStreamEnd,
     delayMs: 0,
-    resolveTarget: () => composerRef.current,
+    resolveTarget: () => getActiveComposer(),
   });
 
   const value = useMemo<ChatContextValue>(
@@ -270,11 +207,9 @@ export function ChatProvider({
       labels,
       audio: audioApi,
       hasAudio,
-      composer,
-      registerComposer,
       blockRegistry: blockRegistry ?? null,
     }),
-    [chat, layout, config, labels, audioApi, hasAudio, composer, registerComposer, blockRegistry],
+    [chat, layout, config, labels, audioApi, hasAudio, blockRegistry],
   );
 
   return (

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

@@ -1,8 +1,13 @@
 'use client';
 
-import { type RefObject, useEffect, useRef } from 'react';
+import { type RefObject, useEffect } from 'react';
 
-import { useChatContextOptional, type ComposerHandle } from '../context';
+import {
+  attachComposer,
+  getActiveComposer,
+  type ComposerHandle,
+} from '@djangocfg/ui-tools/composer-registry';
+import { useChatContextOptional } from '../context';
 import { useStreamEndFocus, type Focusable } from './useStreamEndFocus';
 
 export type { Focusable } from './useStreamEndFocus';
@@ -63,18 +68,14 @@ 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 target resolution always sees
-  // the freshest registered handle.
-  const composerHandleRef = useRef<ComposerHandle | null>(null);
-  composerHandleRef.current = ctx?.composer ?? null;
-
   useStreamEndFocus({
     isStreaming,
     enabled,
     delayMs,
-    // Resolve in priority order: explicit ref > registered composer.
+    // Resolve in priority order: explicit ref > active composer
+    // (from the cross-tool registry).
     resolveTarget: () =>
-      (targetRef?.current as Focusable | null) ?? composerHandleRef.current,
+      (targetRef?.current as Focusable | null) ?? getActiveComposer(),
   });
 }
 
@@ -94,8 +95,6 @@ export function useAutoFocusOnStreamEnd(
  * No-op when called outside a `<ChatProvider>`.
  */
 export function useRegisterComposer(handle: ComposerHandle): void {
-  const ctx = useChatContextOptional();
-  const register = ctx?.registerComposer;
   const focus = handle.focus;
   const moveCursorToEnd = handle.moveCursorToEnd;
   // Forward `getValue/setValue` too — voice dictation reads/writes the
@@ -104,8 +103,6 @@ export function useRegisterComposer(handle: ComposerHandle): void {
   const getValue = handle.getValue;
   const setValue = handle.setValue;
   useEffect(() => {
-    if (!register) return;
-    register({ focus, moveCursorToEnd, getValue, setValue });
-    return () => register(null);
-  }, [register, focus, moveCursorToEnd, getValue, setValue]);
+    return attachComposer({ focus, moveCursorToEnd, getValue, setValue });
+  }, [focus, moveCursorToEnd, getValue, setValue]);
 }