@djangocfg/widget-chat 0.1.1

package/src/store/use-draft.ts

@@ -0,0 +1,168 @@
+/**
+ * The composer's draft.
+ *
+ * The paste handler is returned rather than attached to `document`: a global
+ * listener fires for every editable on the page, which is how a paste into an
+ * unrelated field started reaching the chat.
+ */
+
+import {
+  useCallback,
+  useMemo,
+  useRef,
+  useState,
+  type ClipboardEvent as ReactClipboardEvent,
+} from "react";
+
+import { emptyDraft, isEmpty, type Draft } from "../core/outbound";
+import { stripToolMarkers, type ToolPick } from "../core/tool-picks";
+import { addToolPicks, removeToolPick, toggleToolPick } from "../core/tool-picks-set";
+import { useCapabilities, useChatStore } from "./hooks";
+
+export interface DraftApi {
+  readonly draft: Draft;
+  readonly setText: (text: string) => void;
+  /** Aim this draft at a message, or `undefined` to answer nothing. */
+  readonly setReplyTo: (messageId: string | undefined) => void;
+  /** Stage a picked tool, or unstage it when already staged. */
+  readonly toggleTool: (pick: ToolPick) => void;
+  readonly removePickedTool: (id: string) => void;
+  readonly canSend: boolean;
+  readonly send: () => void;
+  /**
+   * Register something to end when the draft is sent; returns a disposer.
+   *
+   * Registration rather than a direct call: the voice session is built by
+   * `ComposerVoice` from a capability the host may not supply, and owning it
+   * here would mint a microphone for every composer.
+   *
+   * This is the seam every send door shares — the button, the form's submit,
+   * and Enter, which `field/input.tsx` handles itself. A hook on one leaves the
+   * others sending while the engine listens on.
+   */
+  readonly onSend: (listener: () => void) => () => void;
+  /**
+   * Wire to the composer's own `onPaste`. Returns true when it consumed the
+   * event, so a host can tell "we handled it" from "let the editor insert".
+   */
+  readonly handlePaste: (event: ClipboardEvent | ReactClipboardEvent) => boolean;
+}
+
+export function useDraft(): DraftApi {
+  const store = useChatStore();
+  const { tools } = useCapabilities();
+  const [draft, setDraft] = useState<Draft>(emptyDraft);
+
+  const setText = useCallback((text: string) => {
+    setDraft((current) => ({ ...current, text }));
+  }, []);
+
+  // One verb both ways: `undefined` clears. Two would let a surface set a
+  // target it has no matching way to drop.
+  const setReplyTo = useCallback((messageId: string | undefined) => {
+    setDraft((current) => {
+      if (messageId === undefined) {
+        const { replyTo: _dropped, ...rest } = current;
+        return rest;
+      }
+      return { ...current, replyTo: messageId };
+    });
+  }, []);
+
+  const toggleTool = useCallback((pick: ToolPick) => {
+    setDraft((current) => ({
+      ...current,
+      pickedTools: toggleToolPick(current.pickedTools ?? [], pick),
+    }));
+  }, []);
+
+  const removePickedTool = useCallback((id: string) => {
+    setDraft((current) => ({
+      ...current,
+      pickedTools: removeToolPick(current.pickedTools ?? [], id),
+    }));
+  }, []);
+
+  /**
+   * A paste that carried tool markers: the prose goes in, the tools become
+   * chips.
+   *
+   * The text is APPENDED rather than spliced at the caret. A marker describes
+   * the whole turn (`appendToolMarkers` puts it at the end for the same
+   * reason), and the pasted prose arrives as one block, so dropping it mid-word
+   * would rearrange a sentence the user did not edit.
+   */
+  const insertPastedTools = useCallback((text: string, picks: readonly ToolPick[]) => {
+    setDraft((current) => {
+      const body = current.text.trim();
+      const joined = text === "" ? body : body === "" ? text : `${body} ${text}`;
+      return {
+        ...current,
+        text: joined,
+        pickedTools: addToolPicks(current.pickedTools ?? [], picks),
+      };
+    });
+  }, []);
+
+  const handlePaste = useCallback(
+    (event: ClipboardEvent | ReactClipboardEvent): boolean => {
+      const data = "clipboardData" in event ? event.clipboardData : null;
+      if (data === null) return false;
+
+      // Tool markers are the only thing a paste is read for. Everything else is
+      // left to the browser, which inserts it as the text it is.
+      const marked = stripToolMarkers(data.getData("text/plain"));
+      const restored = marked.ids
+        .map((id) => tools?.entries.find((entry) => entry.id === id))
+        .filter((entry) => entry !== undefined)
+        .map((entry) => ({ id: entry.id, label: entry.name, icon: entry.icon }));
+      if (restored.length === 0) return false;
+
+      // Before the state update, and unconditionally on the path we consume: a
+      // contentEditable host (ProseMirror) inserts the text itself otherwise,
+      // and the user gets it twice.
+      event.preventDefault();
+      insertPastedTools(marked.text, restored);
+      return true;
+    },
+    [tools, insertPastedTools],
+  );
+
+  // A ref, not state: registering must not re-render the composer, and `send`
+  // must see the current set rather than the one its closure captured.
+  const sendListeners = useRef(new Set<() => void>());
+
+  const onSend = useCallback((listener: () => void) => {
+    sendListeners.current.add(listener);
+    return () => {
+      sendListeners.current.delete(listener);
+    };
+  }, []);
+
+  const send = useCallback(() => {
+    // Guarded here as well as at the button: Enter reaches this directly
+    // (`field/input.tsx`), so gating only `canSend` would send an empty draft.
+    if (isEmpty(draft)) return;
+    // Before the send and the clear, so a listener sees the draft it is ending
+    // against. No arguments and no return: a listener ends an engine, it does
+    // not mutate the draft.
+    for (const listener of sendListeners.current) listener();
+    void store.send(draft);
+    setDraft(emptyDraft);
+  }, [draft, store]);
+
+  return useMemo(
+    () => ({
+      draft,
+      setText,
+      setReplyTo,
+      toggleTool,
+      removePickedTool,
+      canSend: !isEmpty(draft),
+      send,
+      onSend,
+      handlePaste,
+    }),
+    [draft, setText, setReplyTo, toggleTool, removePickedTool, send, onSend, handlePaste],
+  );
+}

package/src/store/use-queue.ts

@@ -0,0 +1,61 @@
+import { useCallback, useMemo, useSyncExternalStore } from "react";
+
+import type { Draft } from "../core/outbound";
+import type { QueuedPrompt } from "../core/queue";
+import { useChatEvents, useChatStore } from "./hooks";
+
+/**
+ * React binding for the prompt queue.
+ *
+ * Thin, like `useMentions` and `useVoice`: the ordering and the empty rules live
+ * in `core/queue`, tested without a DOM. This subscribes.
+ */
+
+export interface UseQueueResult {
+  readonly items: readonly QueuedPrompt[];
+  readonly count: number;
+  readonly remove: (id: string) => void;
+  /** Replace a queued draft; editing it to empty removes the entry. */
+  readonly edit: (id: string, draft: Draft) => void;
+  /** Remove and return one queued draft, for editing it in the composer. */
+  readonly take: (id: string) => Draft | undefined;
+  /** Cut the current turn short and release this prompt now. */
+  readonly sendNow: (id: string) => void;
+}
+
+export function useQueue(): UseQueueResult {
+  const store = useChatStore();
+  // Announced from here rather than from the store: the store is clock-free
+  // pure core, and handing it the bus would give it a second way to notify
+  // beside `notify` — one that carries no snapshot and nothing can replay.
+  const events = useChatEvents();
+  const queue = useSyncExternalStore(
+    store.subscribe,
+    useCallback(() => store.getState().queue, [store]),
+  );
+
+  // Keyed on the store alone, never on the queue — the defect fixed in
+  // `use-mentions.ts`. A host putting `remove` in an effect's dependency array
+  // would otherwise re-run it on every enqueue, forever.
+  const actions = useMemo(
+    () => ({
+      remove: (id: string) => store.removeQueued(id),
+      edit: (id: string, draft: Draft) => store.editQueued(id, draft),
+      take: (id: string) => store.takeQueued(id),
+      sendNow: (id: string) => {
+        // Announced only when the prompt actually MOVED past a running turn.
+        // With nothing in flight `sendQueuedNow` just sends it, and reporting a
+        // promotion there would describe an interruption that never happened.
+        const wasStreaming = store.getState().inFlight !== null;
+        store.sendQueuedNow(id);
+        if (wasStreaming) events.emit("queue:promoted", { id });
+      },
+    }),
+    [store, events],
+  );
+
+  return useMemo(
+    () => ({ items: queue.items, count: queue.items.length, ...actions }),
+    [queue, actions],
+  );
+}

package/src/store/use-recall.ts

@@ -0,0 +1,264 @@
+import { useCallback, useRef, useState, type KeyboardEvent, type RefObject } from "react";
+
+import {
+  atFirstLine,
+  atLastLine,
+  bufferIsRecallOwned,
+  recallNext,
+  recallPrevious,
+  REST,
+  type RecallLadder,
+  type RecallState,
+} from "../core/recall";
+import type { Draft } from "../core/outbound";
+import { useChatEvents } from "./hooks";
+import { useQueue } from "./use-queue";
+
+/**
+ * ↑/↓ prompt recall, bound to the textarea.
+ *
+ * Deliberately thin, the same split `useMentions` makes: every rule lives in
+ * `core/recall` where it is tested in milliseconds without a DOM, and this file
+ * does three things a pure function cannot — read the caret out of the live
+ * node, write the buffer, and claim the key.
+ *
+ * ## Why the state is a ref and not `useState`
+ *
+ * Nothing here RENDERS from the ladder position. The only visible effect of a
+ * press is the text, which the composer store already owns, so state would buy a
+ * re-render per keystroke and nothing else. It also has to be readable
+ * synchronously inside the keydown handler: with `useState` the second of two
+ * fast presses would read the first press's stale value and walk the same rung
+ * twice.
+ */
+
+export interface UseRecallOptions {
+  /** Sent prompts, OLDEST first. The host owns storage — see below. */
+  readonly entries: readonly string[];
+  /** The live textarea, for the caret. Recall is refused while it is null. */
+  readonly input: RefObject<HTMLTextAreaElement | null>;
+  /**
+   * The composer's draft, passed in rather than read from its context.
+   *
+   * `store/` may not import `composer/` (`layers.test.ts`), and that boundary is
+   * right here for a reason beyond the gate: recall needs the TEXT, not the
+   * composer. Taking it as data keeps the hook usable by any surface that
+   * holds a draft.
+   */
+  readonly draft: Draft;
+  /** Writes the recalled entry into the buffer. */
+  readonly setText: (value: string) => void;
+}
+
+export interface UseRecallResult {
+  /**
+   * Feed this to `ComposerInput.onKeyDown`.
+   *
+   * Calls `preventDefault()` only when it actually navigates, so an arrow that
+   * should move the caret still does — that veto is the whole protocol.
+   */
+  readonly onKeyDown: (event: KeyboardEvent<HTMLTextAreaElement>) => void;
+  /**
+   * The prompt Tab would insert, or `null` when the ladder is at rest.
+   *
+   * The one piece of recall that RENDERS, and therefore the one piece held as
+   * state rather than in the ref below.
+   */
+  readonly preview: string | null;
+  /** Drop the ladder back to rest. Call after a send. */
+  readonly reset: () => void;
+}
+
+/**
+ * Where the ladder COMES FROM is the host's, and the two sources are not
+ * equivalent.
+ *
+ * A host may persist what was typed, or derive the ladder from the user turns
+ * already in the transcript. Deriving is cheaper and
+ * needs no storage, but it cannot recall a prompt that was sent and never
+ * landed, and it is empty until history loads — so an empty ladder there is a
+ * boundary, not a fault.
+ *
+ * Either way it stays off the wire: what you typed is a local editing
+ * convenience, not conversation state, and must not sync between devices or
+ * outlive the device it was typed on. This hook takes the ladder as data and
+ * owns neither choice.
+ */
+export function useRecall({ entries, input, draft, setText }: UseRecallOptions): UseRecallResult {
+  // Queued prompts are a rung of the same ladder: written but not answered, so
+  // nearer in time than anything sent. Read from the store rather than taken as
+  // an option — the queue is the package's own state and a host passing its own
+  // copy would be a second source of truth for it.
+  const { items, take } = useQueue();
+  const events = useChatEvents();
+  const state = useRef<RecallState>(REST);
+  // The ONE thing recall renders. State, unlike the position beside it: a
+  // preview that lived in a ref would move without repainting, which is the
+  // whole feature.
+  const [preview, setPreview] = useState<string | null>(null);
+  // The same value, readable SYNCHRONOUSLY. The handler decides whether Tab is
+  // recall's or the browser's, and a `useState` read there is one render stale
+  // — so the first Tab after an arrow would fall through and move focus out of
+  // the composer instead of inserting.
+  const walking = useRef<string | null>(null);
+  walking.current = preview;
+  // Which queued entry the preview came from, or null when the rung is a sent
+  // prompt. Read on Tab: a queued prompt is TAKEN and a sent one is copied, and
+  // the text alone cannot tell them apart — the same words may sit on both rungs.
+  const previewQueuedId = useRef<string | null>(null);
+
+  // Read through refs so the handler identity is stable: it goes onto
+  // `ComposerInput`, and a new function every render would defeat its
+  // `useCallback` for no benefit.
+  const latest = useRef({ entries, draft, items });
+  latest.current = { entries, draft, items };
+
+  /**
+   * Typing abandons the walk.
+   *
+   * A preview left hanging while the user writes something new invites a Tab
+   * that destroys it. Keyed on the draft becoming NON-EMPTY rather than on a
+   * keystroke, because that is the condition — recall only walks on an empty
+   * buffer, so any text at all means the user has started authoring.
+   *
+   * Derived during render rather than in an effect: an effect would paint one
+   * frame with a stale preview over text that is already there.
+   */
+  if (preview !== null && draft.text !== "") {
+    state.current = REST;
+    walking.current = null;
+    previewQueuedId.current = null;
+    setPreview(null);
+  }
+
+  const reset = useCallback(() => {
+    state.current = REST;
+    previewQueuedId.current = null;
+    setPreview(null);
+  }, []);
+
+  const onKeyDown = useCallback(
+    (event: KeyboardEvent<HTMLTextAreaElement>) => {
+      // Another handler already claimed it — an open mention menu owns the
+      // arrows while it is showing, and it renders over this same textarea.
+      if (event.defaultPrevented) return;
+
+      const node = input.current;
+
+      // Tab and Escape belong to recall ONLY while a preview is showing.
+      //
+      // The Tab guard is an accessibility rule, not a preference: a Tab that is
+      // always swallowed makes the composer a keyboard trap with no way out. So
+      // both keys fall through untouched at rest, and Tab keeps moving focus.
+      if (walking.current !== null) {
+        if (event.key === "Tab") {
+          event.preventDefault();
+          const text = walking.current;
+          const queuedId = previewQueuedId.current;
+          state.current = REST;
+          previewQueuedId.current = null;
+          setPreview(null);
+          // A queued prompt is TAKEN, a sent one copied. It has not been seen by
+          // anyone, so leaving the entry behind would send it twice: once from
+          // the queue and once as the edit the user is about to make. A sent
+          // turn already happened, and rewriting it is a separate, destructive
+          // operation that stays explicit.
+          // Through `latest`, like every other queue read in this handler: the
+          // callback is not re-created per keystroke, so a closed-over `items`
+          // would be whatever the queue held when it was built.
+          const taken =
+            queuedId === null
+              ? undefined
+              : latest.current.items.find((item) => item.id === queuedId);
+          if (queuedId !== null) take(queuedId);
+          setText(text);
+          // After BOTH steps, never between them. The queue's own edit path
+          // orders them the other way round on purpose, so this must stay a
+          // notification rather than the mechanism either path relies on.
+          if (queuedId !== null && taken !== undefined) {
+            events.emit("queue:taken", { id: queuedId, draft: taken.draft });
+          }
+          // Caret at the END: the user is about to edit or resend, and a caret
+          // at 0 puts every keystroke in front of what they just inserted.
+          // Deferred because React writes the value on the next commit.
+          queueMicrotask(() => node?.setSelectionRange(text.length, text.length));
+          return;
+        }
+        if (event.key === "Escape") {
+          // Nothing to restore: the draft was never written to. That is the
+          // point of the design — `stashedDraft` used to exist for this.
+          //
+          // The queued entry is left ALONE: Escape abandons the walk, and a
+          // prompt the user only looked at must stay in the queue.
+          event.preventDefault();
+          event.stopPropagation();
+          state.current = REST;
+          previewQueuedId.current = null;
+          setPreview(null);
+          return;
+        }
+      }
+
+      if (event.key !== "ArrowUp" && event.key !== "ArrowDown") return;
+      // A chord is the OS's or the host's: cmd+Up is "top of document" on macOS,
+      // and shift+Up extends a selection.
+      if (event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) return;
+
+      if (node === null) return;
+
+      const { entries: sent, draft: current, items: queued } = latest.current;
+      const caret = { start: node.selectionStart, end: node.selectionEnd };
+
+      // The cheapest and most absolute rule first: text the user typed is
+      // theirs, and no caret position makes an arrow navigate away from it.
+      //
+      // `lastRecalled` is passed as `null` DELIBERATELY, and the argument is
+      // now vestigial rather than merely unused: recall no longer writes to the
+      // buffer, so whatever is in it is always the user's. The rule that
+      // survives is the original half — a non-empty draft does not navigate —
+      // and passing a remembered value could only ever weaken it.
+      if (!bufferIsRecallOwned(current.text, null)) return;
+
+      const ladder: RecallLadder = {
+        sent,
+        queued: queued.map((item) => item.draft.text),
+      };
+      const up = event.key === "ArrowUp";
+      // The boundary decides whether this press is "move the caret within a
+      // multi-line draft" or "leave the buffer" — zsh's rule, not "is the
+      // composer empty".
+      if (up ? !atFirstLine(current.text, caret) : !atLastLine(current.text, caret)) return;
+
+      const move = up
+        ? recallPrevious(state.current, ladder, current.text)
+        : recallNext(state.current, ladder);
+
+      // Nothing to move to: leave the key alone rather than swallowing it, so
+      // ArrowUp in an empty composer with no history behaves like a textarea.
+      if (move.text === null) return;
+
+      event.preventDefault();
+      state.current = move.state;
+      // PREVIEW, never write. Walking must not touch the buffer: a full-buffer
+      // rewrite per press reflows the composer, so the line being read moves
+      // while it is read — and it makes "did recall eat what I was typing?"
+      // answerable by accident. Tab above is the only path into the draft.
+      //
+      // Landing back on the draft rung ends the walk: the ladder returns
+      // `stashedDraft`, which is the user's own text, and previewing that would
+      // offer to insert what is already there.
+      // The queue's LAST entry is the only queued rung — `core/recall` says so,
+      // and this must read the same end or Tab would take a different prompt
+      // than the one previewed.
+      const { items: queuedNow } = latest.current;
+      previewQueuedId.current =
+        move.state.position.kind === "queued"
+          ? (queuedNow[queuedNow.length - 1]?.id ?? null)
+          : null;
+      setPreview(move.state.position.kind === "draft" ? null : move.text);
+    },
+    [input, setText, take, events],
+  );
+
+  return { onKeyDown, preview, reset };
+}

package/src/store/use-reload-on-revision.ts

@@ -0,0 +1,67 @@
+import { useEffect, useRef } from "react";
+
+import { reloadDecision } from "../core/reload-decision";
+import { useTurn } from "./hooks";
+
+/**
+ * Re-read the room when something outside this tab changed it.
+ *
+ * The caller supplies a REVISION — a number that moves when the room moved —
+ * and a `reload` that re-fetches history. `reloadDecision` owns the rule; this
+ * owns the refs, because the decision needs values a render cannot hold: what
+ * revision was last acted on, and whether a change is owed.
+ *
+ * A number rather than the events themselves, because the package must not
+ * depend on the host's bus or its stores. What "the room moved" MEANS is the
+ * host's to decide — a server hint, a reconnect, a manual refresh — and all this
+ * needs is that the number changed.
+ *
+ * `room` is optional and identifies WHICH room the revision counts for. A host
+ * that mounts this hook once per room can omit it; one that keeps a single
+ * mount across rooms must pass it, or two rooms' counters are compared as if
+ * they were one room's.
+ */
+export function useReloadOnRevision(
+  revision: number,
+  reload: () => void,
+  room?: string,
+): void {
+  const { isStreaming } = useTurn();
+  // Seeded with the opening revision: a room has just read its history, so the
+  // first value is not a change.
+  const seen = useRef(revision);
+  const deferred = useRef(false);
+  // Which room `seen` describes. Revisions are per-room counters, so comparing
+  // one room's against another's is meaningless — and not merely noise: a room
+  // left at 3 followed by a fresh room reading 0 counts as a change and fires a
+  // reload over the history that room just fetched. That used to be impossible
+  // because the host remounted this hook per room; it is possible now, so the
+  // re-seed has to be explicit.
+  const seenRoom = useRef(room);
+  if (seenRoom.current !== room) {
+    seenRoom.current = room;
+    seen.current = revision;
+    deferred.current = false;
+  }
+  // Read through a ref so a caller may pass an inline arrow without re-arming
+  // the effect on every render.
+  const reloadRef = useRef(reload);
+  reloadRef.current = reload;
+
+  useEffect(() => {
+    const decision = reloadDecision({
+      revision,
+      seen: seen.current,
+      streaming: isStreaming,
+      deferred: deferred.current,
+    });
+    seen.current = revision;
+    if (decision === "ignore") return;
+    if (decision === "defer") {
+      deferred.current = true;
+      return;
+    }
+    deferred.current = false;
+    reloadRef.current();
+  }, [revision, isStreaming]);
+}

package/src/store/use-speech-language.ts

@@ -0,0 +1,84 @@
+import { useCallback, useMemo, useState } from "react";
+
+import { resolveLanguage } from "../core";
+
+/**
+ * Which language dictation listens for, and how it is remembered.
+ *
+ * Global, not per-conversation: a language is a property of the SPEAKER, not of
+ * the chat they are in. The archive stored it the same way.
+ */
+const STORAGE_KEY = "djc.chat.speech-language";
+
+export interface UseSpeechLanguageResult {
+  /** The BCP-47 tag in force. Never empty. */
+  readonly language: string;
+  /** Whether the user chose it, as opposed to it being resolved for them. */
+  readonly explicit: boolean;
+  readonly setLanguage: (tag: string) => void;
+  /** Forget the pick and go back to resolving. */
+  readonly clear: () => void;
+}
+
+export interface SpeechLanguageOptions {
+  /**
+   * The host UI's locale, as an ISO subtag.
+   *
+   * A TIE-BREAKER, never the source: it is consulted only when the browser also
+   * lists that language as spoken. Pinning speech to the app locale is a known
+   * regression — an English UI then cannot dictate Russian.
+   */
+  readonly uiLocale?: string | undefined;
+}
+
+function read(): string | undefined {
+  // Guarded: a package that assumes `localStorage` breaks in SSR and in a
+  // sandboxed iframe, both of which throw rather than returning null.
+  try {
+    return globalThis.localStorage?.getItem(STORAGE_KEY) ?? undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function write(tag: string | null): void {
+  try {
+    if (tag === null) globalThis.localStorage?.removeItem(STORAGE_KEY);
+    else globalThis.localStorage?.setItem(STORAGE_KEY, tag);
+  } catch {
+    // A pick that cannot be persisted still applies to this session. Failing
+    // the change because storage is unavailable would be worse than forgetting.
+  }
+}
+
+export function useSpeechLanguage(options: SpeechLanguageOptions = {}): UseSpeechLanguageResult {
+  const [picked, setPicked] = useState<string | undefined>(read);
+
+  const language = useMemo(
+    () =>
+      resolveLanguage({
+        picked,
+        uiLocale: options.uiLocale,
+        // Read here rather than in `resolveLanguage`, which stays pure so the
+        // priority order can be tested without faking globals.
+        browserLanguages: typeof navigator === "undefined" ? undefined : navigator.languages,
+        browserLanguage: typeof navigator === "undefined" ? undefined : navigator.language,
+      }),
+    [picked, options.uiLocale],
+  );
+
+  const setLanguage = useCallback((tag: string) => {
+    write(tag);
+    setPicked(tag);
+  }, []);
+
+  const clear = useCallback(() => {
+    write(null);
+    setPicked(undefined);
+  }, []);
+
+  return useMemo(
+    () => ({ language, explicit: picked !== undefined, setLanguage, clear }),
+    [language, picked, setLanguage, clear],
+  );
+}