@djangocfg/widget-chat 0.1.1

package/src/primitives/use-select-all-transcript.ts

@@ -0,0 +1,111 @@
+import { useEffect } from "react";
+
+/**
+ * ⌘A selects the whole conversation instead of the whole page.
+ *
+ * The browser default selects the document, which here means the rail, the
+ * status bar and the composer alongside the turns — so the copy that follows is
+ * unusable and the user trims it by hand.
+ *
+ * Scoped to the TRANSCRIPT, and only when the caret is not in an editable:
+ * inside the composer ⌘A means "select my draft", which is the more specific
+ * intent and must win. `useHotkey`'s default policy would take it, because a
+ * modifier combo defaults to firing in inputs — hence the explicit `inInput`
+ * at the call site.
+ *
+ * The selection is built over the transcript's message NODES rather than the
+ * scroller, so the gaps between turns stay out of it. Those gaps are
+ * `select-none` on purpose (see `../ui/message.tsx`): including
+ * them fuses two speakers into one block on copy, which is exactly what this
+ * feature exists to avoid.
+ *
+ * It selects what is LOADED, which is the transcript the user is looking at.
+ * Fetching older turns first would make a keystroke perform a network read with
+ * no way to show progress.
+ *
+ * Nothing is written to the clipboard: ⌘A selects, and the ⌘C that follows is
+ * the user's own gesture.
+ */
+export function selectTranscript(root: HTMLElement | null): boolean {
+  if (!root) return false;
+  const items = root.querySelectorAll("[data-chat-item]");
+  const first = items[0];
+  const last = items[items.length - 1];
+  if (!first || !last) return false;
+
+  const selection = window.getSelection();
+  if (!selection) return false;
+
+  const range = document.createRange();
+  range.setStartBefore(first);
+  range.setEndAfter(last);
+  selection.removeAllRanges();
+  selection.addRange(range);
+  return true;
+}
+
+/** True while the caret sits somewhere the user is typing. */
+export function isEditableTarget(node: EventTarget | null): boolean {
+  return (
+    node instanceof HTMLElement &&
+    (node.isContentEditable ||
+      node instanceof HTMLInputElement ||
+      node instanceof HTMLTextAreaElement)
+  );
+}
+
+/**
+ * Is this the keystroke, and is it ours to take?
+ *
+ * Split out so the decision is testable without a DOM: it reads only the
+ * modifier flags and whether the target is editable, and every way this
+ * feature can misbehave — eating the composer's ⌘A, firing on ⌘⇧A — is
+ * decided here.
+ */
+export function claimsSelectAll(event: {
+  readonly key: string;
+  readonly metaKey: boolean;
+  readonly ctrlKey: boolean;
+  readonly altKey: boolean;
+  readonly shiftKey: boolean;
+  readonly editableTarget: boolean;
+}): boolean {
+  if (event.key !== "a" || !(event.metaKey || event.ctrlKey)) return false;
+  // ⌘⌥A and ⌘⇧A are other commands, not a louder select-all.
+  if (event.altKey || event.shiftKey) return false;
+  // The composer's own ⌘A is the more specific intent and wins.
+  return !event.editableTarget;
+}
+
+/**
+ * Bind ⌘A to {@link selectTranscript} for as long as the surface is mounted.
+ *
+ * A plain listener rather than `useHotkey`: this must inspect the EVENT TARGET
+ * to leave the composer alone, and it must call `preventDefault` only when it
+ * actually took the selection — a conditional both of which the wrapper's
+ * declarative policy decides up front, before the target is known.
+ */
+export function useSelectAllTranscript(
+  surface: () => HTMLElement | null,
+  enabled = true,
+): void {
+  useEffect(() => {
+    if (!enabled) return;
+    const onKeyDown = (event: KeyboardEvent) => {
+      const claim = claimsSelectAll({
+        key: event.key,
+        metaKey: event.metaKey,
+        ctrlKey: event.ctrlKey,
+        altKey: event.altKey,
+        shiftKey: event.shiftKey,
+        editableTarget: isEditableTarget(event.target),
+      });
+      if (!claim) return;
+      // Only claim the key once the selection succeeded, so a surface with no
+      // transcript still gets the browser's own select-all.
+      if (selectTranscript(surface())) event.preventDefault();
+    };
+    document.addEventListener("keydown", onKeyDown);
+    return () => document.removeEventListener("keydown", onKeyDown);
+  }, [surface, enabled]);
+}

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

@@ -0,0 +1,83 @@
+/**
+ * Following the bottom, delegated to `use-stick-to-bottom`.
+ *
+ * This was ours, twice, and both versions had the same class of defect: an
+ * INSTANT write to `scrollTop` on every growth. A hard fling landing on the
+ * bottom edge then visibly shook — measured at 5–12 direction reversals with an
+ * 8–23px swing — because the write, the engine's own settle and the resulting
+ * scroll event chase each other inside one frame. Neither a tolerance around
+ * the target nor rounding the box's fractional height fixed it; a write-trap
+ * proved the hook was not even the one writing during the shake.
+ *
+ * The library answers it structurally rather than by tuning: it animates toward
+ * the bottom with a damped spring, so there is no single frame that jumps, and
+ * it remembers the position it last wrote (`ignoreScrollToTop`) so its own echo
+ * is never mistaken for the reader scrolling. It also suspends following while
+ * a text selection is in progress, which no amount of gesture-watching here
+ * would have covered.
+ *
+ * What stays ours is the SHAPE of the return value: `Transcript` consumes
+ * `{ ref, onScroll, isPinned, scrollToBottom }`, and keeping that means the
+ * primitive did not have to learn about a second element.
+ */
+
+import { useCallback, type UIEvent } from "react";
+import { useStickToBottom as useLibraryStickToBottom } from "use-stick-to-bottom";
+
+export interface StickToBottom {
+  /** The SCROLLER. */
+  readonly ref: (node: HTMLDivElement | null) => void;
+  /** The element wrapping the rows, which is what actually changes height. */
+  readonly contentRef: (node: HTMLDivElement | null) => void;
+  readonly onScroll: (event: UIEvent<HTMLDivElement>) => void;
+  /** False while the user is reading history — render a "jump to latest" control. */
+  readonly isPinned: boolean;
+  readonly scrollToBottom: () => void;
+}
+
+/**
+ * @param revision unused, and kept only so callers need not change. The library
+ *   watches the content element with a ResizeObserver, which sees streamed text
+ *   grow a row as readily as it sees a row appear — the count was always a
+ *   proxy for exactly that.
+ */
+export function useStickToBottom(_revision: number): StickToBottom {
+  const instance = useLibraryStickToBottom({
+    // Growth is ANIMATED. `instant` here is what produced the shake: it lands
+    // the view on the target in one frame, so the engine's own settle reads as
+    // a bounce rather than as part of a motion.
+    resize: "smooth",
+    // Arrival is INSTANT, and the asymmetry is the point. Opening a room is not
+    // motion the reader is following — there is nothing on screen yet to track —
+    // so animating it scrolls a transcript they never asked to watch, every
+    // single time they switch. The bottom is simply where the room starts.
+    initial: "instant",
+  });
+
+  const { scrollRef, contentRef, isAtBottom, scrollToBottom } = instance;
+
+  const ref = useCallback(
+    (node: HTMLDivElement | null) => {
+      scrollRef(node);
+    },
+    [scrollRef],
+  );
+
+  const content = useCallback(
+    (node: HTMLDivElement | null) => {
+      contentRef(node);
+    },
+    [contentRef],
+  );
+
+  // The library listens on the element itself, so nothing has to happen here.
+  // Kept because `Transcript` passes it to the scroller and a missing handler
+  // would be a silent behaviour change rather than a type error.
+  const onScroll = useCallback(() => {}, []);
+
+  const jump = useCallback(() => {
+    void scrollToBottom();
+  }, [scrollToBottom]);
+
+  return { ref, contentRef: content, onScroll, isPinned: isAtBottom, scrollToBottom: jump };
+}

package/src/primitives/use-turn-activity.ts

@@ -0,0 +1,25 @@
+import { useTurn } from "../store";
+
+/**
+ * `waiting` — sent, nothing back yet. `working` — text is arriving.
+ * `null` — no turn in flight, so nothing to mark.
+ */
+export type TurnActivity = "waiting" | "working" | null;
+
+/**
+ * The live turn's activity, in one place.
+ *
+ * Derived from `useTurn`, never stored: the two flags it reads are themselves
+ * derived from the transcript, and a third copy could disagree with both about
+ * whether an answer has started.
+ *
+ * It exists so the trailing indicator has ONE owner. The alternative — each
+ * message row deciding from its own `status` — puts the answer in as many places
+ * as there are messages, and every settled row then answers "yes, I finished",
+ * which is how a marker ends up stacked once per reply on a single screen.
+ */
+export function useTurnActivity(): TurnActivity {
+  const { isStreaming, isPending } = useTurn();
+  if (!isStreaming) return null;
+  return isPending ? "waiting" : "working";
+}

package/src/store/context.ts

@@ -0,0 +1,28 @@
+/**
+ * The single context.
+ *
+ * Capabilities ride here rather than being threaded as props, which is what
+ * lets `<Chat>` stay at seven props while a composer three levels down still
+ * knows which features exist. One context, not one per feature: a context per
+ * capability would put the count back on the same growth curve the props were
+ * on.
+ */
+
+import { createContext } from "react";
+
+import type { ChatCapabilities } from "../core/capabilities";
+import type { ChatEvents } from "../core/events";
+import type { ChatStore } from "./store";
+
+export interface ChatContextValue {
+  readonly store: ChatStore;
+  readonly capabilities: ChatCapabilities;
+  /**
+   * Announcements, as opposed to state. The store answers "what is true now";
+   * this says "this just happened" — which a subscriber cannot reconstruct from
+   * a snapshot, because two identical states can be reached by different acts.
+   */
+  readonly events: ChatEvents;
+}
+
+export const ChatContext = createContext<ChatContextValue | null>(null);

package/src/store/hooks.ts

@@ -0,0 +1,215 @@
+/**
+ * React bindings for the store.
+ *
+ * The split is deliberate and is the whole performance story: the transcript
+ * subscribes to `useMessageIds()` and each row to `useMessage(id)`, so a token
+ * arriving in the last message re-renders one row rather than the list. MUI X
+ * settled on the same pair, and a single `useMessages()` returning the array
+ * cannot be optimised into it afterwards — every consumer would have to change.
+ */
+
+import { useCallback, useContext, useMemo, useSyncExternalStore } from "react";
+
+import type { ChatCapabilities } from "../core/capabilities";
+import type { ChatEvents } from "../core/events";
+import type { ChatMessage } from "../core/parts";
+import { ChatContext, type ChatContextValue } from "./context";
+import type { ChatState, ChatStore } from "./store";
+
+/**
+ * Has the in-flight reply produced anything a reader can SEE yet?
+ *
+ * Two thresholds were tried and both were too early, each by one step:
+ *
+ *   - `streamingId !== null` flips on `message-start`, which opens an EMPTY
+ *     message;
+ *   - a non-empty `parts` array flips on `text-start`, which appends a part
+ *     whose text is `""`.
+ *
+ * Both leave a measurable silent gap where the indicator is gone and the reply
+ * has not appeared — the exact state it exists to prevent. So the question is
+ * asked of the CONTENT: a text or reasoning part counts once it has characters,
+ * and any other part counts as soon as it exists, because a tool call renders
+ * its own header immediately.
+ *
+ * Returns a boolean rather than the message: `useSyncExternalStore` compares by
+ * reference, and a selector minting an object per call re-renders forever.
+ */
+function hasRenderedPart(state: ChatState): boolean {
+  const id = state.transcript.streamingId;
+  if (id === null) return false;
+  const parts = state.transcript.byId[id]?.parts ?? [];
+  return parts.some((part) =>
+    part.type === "text" || part.type === "reasoning" ? part.text !== "" : true,
+  );
+}
+
+function useChatContext(): ChatContextValue {
+  const value = useContext(ChatContext);
+  if (value === null) {
+    throw new Error("chat hooks must be used inside <ChatProvider>");
+  }
+  return value;
+}
+
+export function useChatStore(): ChatStore {
+  return useChatContext().store;
+}
+
+/**
+ * What this chat can do.
+ *
+ * A component asks for the capability it needs and renders nothing when it is
+ * absent — that check IS the feature flag. There is no second boolean that can
+ * disagree with it.
+ */
+export function useCapabilities(): ChatCapabilities {
+  return useChatContext().capabilities;
+}
+
+/**
+ * The chat's event bus.
+ *
+ * Announcements, not state: subscribe in an effect, never read during render.
+ * What is TRUE comes from the store — a component that mirrors an event into
+ * its own state has made a second owner of a fact the store already holds.
+ *
+ * The identity is stable for the life of the provider, so an effect may depend
+ * on it without re-subscribing.
+ */
+export function useChatEvents(): ChatEvents {
+  return useChatContext().events;
+}
+
+/**
+ * Message ids in order.
+ *
+ * The identity of the array matters: `useSyncExternalStore` compares by
+ * reference, so returning a fresh array per call would re-render the transcript
+ * on every token. The reducer keeps `ids` stable unless a message is added, so
+ * reading it directly is both correct and cheap.
+ */
+export function useMessageIds(): readonly string[] {
+  const store = useChatStore();
+  return useSyncExternalStore(
+    store.subscribe,
+    useCallback(() => store.getState().transcript.ids, [store]),
+  );
+}
+
+/**
+ * Whether the host's history fetch has answered.
+ *
+ * `false` with an empty transcript is LOADING, not empty — the distinction the
+ * empty state needs and cannot make from the message list alone.
+ */
+export function useHistoryLoaded(): boolean {
+  const store = useChatStore();
+  return useSyncExternalStore(
+    store.subscribe,
+    useCallback(() => store.getState().historyLoaded, [store]),
+  );
+}
+
+/** One message, re-rendering only when that message changes. */
+export function useMessage(id: string): ChatMessage | undefined {
+  const store = useChatStore();
+  const subscribe = useCallback(
+    (listener: () => void) => store.subscribeMessage(id, listener),
+    [store, id],
+  );
+  return useSyncExternalStore(
+    subscribe,
+    useCallback(() => store.getState().transcript.byId[id], [store, id]),
+  );
+}
+
+/**
+ * When the row BEFORE `id` was created, or `undefined` when it is the first.
+ *
+ * A number, not the message: a row needs its neighbour only to tell whether the
+ * calendar day changed, and subscribing to the whole message would re-render it
+ * on every token arriving in the row above.
+ *
+ * Read from the list rather than passed down, so the day heading survives the
+ * memo boundary that keeps a streaming transcript cheap.
+ */
+export function usePreviousMessageTime(id: string): number | undefined {
+  const store = useChatStore();
+  return useSyncExternalStore(
+    store.subscribe,
+    useCallback(() => {
+      const { ids, byId } = store.getState().transcript;
+      const index = ids.indexOf(id);
+      if (index <= 0) return undefined;
+      return byId[ids[index - 1] as string]?.createdAt;
+    }, [store, id]),
+  );
+}
+
+/**
+ * Whether the row BEFORE `id` was spoken by the same author.
+ *
+ * A BOOLEAN, not the message, for the reason `usePreviousMessageTime` returns a
+ * number: a row needs its neighbour only to decide whether to repeat the name,
+ * and subscribing to the whole message would re-render it on every token
+ * arriving in the row above — the one cost the id/message split exists to avoid.
+ *
+ * False for the first row, and false whenever either side has no author: a
+ * system-authored line and a turn of yours both BREAK a run, so the next speaker
+ * is named again rather than reading as the previous one still talking.
+ */
+export function usePreviousAuthorMatches(id: string): boolean {
+  const store = useChatStore();
+  return useSyncExternalStore(
+    store.subscribe,
+    useCallback(() => {
+      const { ids, byId } = store.getState().transcript;
+      const index = ids.indexOf(id);
+      if (index <= 0) return false;
+      const mine = byId[id]?.authorId;
+      const before = byId[ids[index - 1] as string]?.authorId;
+      return mine !== undefined && mine === before;
+    }, [store, id]),
+  );
+}
+
+export interface TurnState {
+  readonly isStreaming: boolean;
+  /**
+   * A turn is in flight and has produced NOTHING yet.
+   *
+   * Derived, never stored: a turn is in flight and the reply holds no part yet.
+   * A stored flag would be a second source of truth that can disagree with the
+   * transcript about whether the answer has started.
+   *
+   * The threshold is the first PART, not the opening of the message — see
+   * `hasRenderedPart`.
+   *
+   * The gap it names is the common case here, not an edge one — an agent may
+   * read files or start a subagent for many seconds before its first token, and
+   * during that time the transcript is otherwise silent.
+   */
+  readonly isPending: boolean;
+  readonly stop: () => void;
+}
+
+export function useTurn(): TurnState {
+  const store = useChatStore();
+  const inFlight = useSyncExternalStore(
+    store.subscribe,
+    useCallback(() => store.getState().inFlight, [store]),
+  );
+  const rendered = useSyncExternalStore(
+    store.subscribe,
+    useCallback(() => hasRenderedPart(store.getState()), [store]),
+  );
+  return useMemo(
+    () => ({
+      isStreaming: inFlight !== null,
+      isPending: inFlight !== null && !rendered,
+      stop: store.stop,
+    }),
+    [inFlight, rendered, store.stop],
+  );
+}

package/src/store/index.ts

@@ -0,0 +1,31 @@
+export { createChatStore } from "./store";
+export type { ChatState, ChatStore, StoreOptions } from "./store";
+export { ChatContext } from "./context";
+export type { ChatContextValue } from "./context";
+export { ChatProvider } from "./provider";
+export type { ChatProviderProps } from "./provider";
+export { ChatSurfacesContext, useChatSurfaces, useSurfacesRegistry } from "./surfaces";
+export { useReloadOnRevision } from "./use-reload-on-revision";
+export type { ChatSurfaces } from "./surfaces";
+export {
+  useCapabilities,
+  useChatEvents,
+  useChatStore,
+  useHistoryLoaded,
+  useMessage,
+  useMessageIds,
+  usePreviousMessageTime,
+  usePreviousAuthorMatches,
+  useTurn,
+} from "./hooks";
+export type { TurnState } from "./hooks";
+export { useDraft } from "./use-draft";
+export type { DraftApi } from "./use-draft";
+export { useQueue } from "./use-queue";
+export type { UseQueueResult } from "./use-queue";
+export { useVoice } from "./use-voice";
+export type { UseVoiceResult } from "./use-voice";
+export { useSpeechLanguage } from "./use-speech-language";
+export type { UseSpeechLanguageResult, SpeechLanguageOptions } from "./use-speech-language";
+export { useRecall } from "./use-recall";
+export type { UseRecallOptions, UseRecallResult } from "./use-recall";

package/src/store/provider.tsx

@@ -0,0 +1,97 @@
+import { useMemo, useRef, type ReactNode } from "react";
+
+import type { ChatAdapter } from "../core/adapter";
+import type { ChatCapabilities } from "../core/capabilities";
+import { createChatEvents, type ChatEvents } from "../core/events";
+import { ChatContext } from "./context";
+import { createChatStore, type ChatStore } from "./store";
+import { ChatSurfacesContext, useSurfacesRegistry } from "./surfaces";
+
+export interface ChatProviderProps {
+  readonly adapter: ChatAdapter;
+  readonly capabilities?: ChatCapabilities;
+  /**
+   * Bring your own store to seed history or drive it from outside. Omit and one
+   * is created — the common path needs no lifecycle awareness at all.
+   */
+  readonly store?: ChatStore;
+  readonly children: ReactNode;
+}
+
+const noCapabilities: ChatCapabilities = {};
+
+/**
+ * The escape hatch, and the seam every primitive resolves through.
+ *
+ * `<Chat>` renders this internally, so a host that outgrows the packaged layout
+ * drops to primitives without losing state wiring — the thing that usually
+ * forces a fork of the whole component.
+ */
+export function ChatProvider({
+  adapter,
+  capabilities = noCapabilities,
+  store,
+  children,
+}: ChatProviderProps) {
+  // The store is created ONCE and never re-created from a prop change.
+  //
+  // A `useMemo` keyed on [adapter, capabilities, store] reads as harmless and
+  // is not: `capabilities` is an object literal at every realistic call site
+  // (`<ChatProvider capabilities={{ think: … }}>`), so it is a new
+  // reference on every parent render, and a new store means an EMPTY
+  // transcript. The conversation would vanish mid-turn, with no error and
+  // nothing in the stack pointing here.
+  //
+  // A ref, not a memo: `useMemo` is a performance hint React may discard and
+  // recompute at will, so it is not a place to put something whose identity is
+  // load-bearing. This is the documented distinction, not a style preference.
+  //
+  // `crypto.randomUUID` and `Date.now` are injected here, at the edge, so the
+  // core stays clock-free and testable. This is the only place they appear.
+
+  // The LIVE adapter, re-read on every send rather than captured once. A host
+  // re-binds its adapter when the room changes (one transport per room), so a
+  // store holding the first one addresses the room that was
+  // open at mount: the start screen's first message landed in the previous
+  // conversation instead of creating one. Re-creating the store for it is the
+  // wrong fix — that is the defect the paragraph above guards against.
+  const liveAdapter = useRef(adapter);
+  liveAdapter.current = adapter;
+
+  const ownStore = useRef<ChatStore | null>(null);
+  if (ownStore.current === null && store === undefined) {
+    ownStore.current = createChatStore({
+      // Indirection, not the prop: the store keeps this object for its lifetime,
+      // so reading the ref at call time is what lets the adapter change under a
+      // transcript that must survive the change.
+      adapter: { sendMessage: (request) => liveAdapter.current.sendMessage(request) },
+      makeId: () => crypto.randomUUID(),
+      now: () => Date.now(),
+    });
+  }
+
+  // Per chat, and by ref for the same reason as the store: a listener that
+  // outlived a re-created bus would hold a subscription nothing ever emits to —
+  // silent, and indistinguishable from an event that simply did not happen.
+  const events = useRef<ChatEvents | null>(null);
+  events.current ??= createChatEvents();
+
+  // A caller that SWAPS its store prop means it: that is the one identity we
+  // must follow. Everything else is stable across renders.
+  const active = store ?? ownStore.current;
+  const value = useMemo(
+    () => ({ store: active as ChatStore, capabilities, events: events.current as ChatEvents }),
+    [active, capabilities],
+  );
+
+  // Where the surfaces are, for a host that must put the caret back or scope a
+  // selection. Provided here because it spans BOTH — the composer and the
+  // transcript — and a host asking is usually outside either.
+  const surfaces = useSurfacesRegistry();
+
+  return (
+    <ChatContext.Provider value={value}>
+      <ChatSurfacesContext.Provider value={surfaces}>{children}</ChatSurfacesContext.Provider>
+    </ChatContext.Provider>
+  );
+}