@djangocfg/widget-chat 0.1.1

package/src/store/store.ts

@@ -0,0 +1,394 @@
+/**
+ * The store: transcript state plus the turn lifecycle.
+ *
+ * Hand-rolled on `useSyncExternalStore` rather than pulled from zustand — the
+ * whole surface is five methods and a subscription, and the package's point is
+ * to be dependency-light enough that a consumer can read it end to end. The
+ * core reducer already owns every state transition; this only owns WHEN they
+ * run and WHO is told.
+ *
+ * Per-message subscription is the load-bearing part. A transcript that
+ * re-renders every row on every token is the difference between a chat that
+ * feels instant and one that stutters at fifty messages, and it cannot be
+ * retrofitted — it decides the shape of the selectors.
+ */
+
+import type { ChatAdapter } from "../core/adapter";
+import type { StreamChunk } from "../core/chunks";
+import type { ChatMessage, MessageStatus } from "../core/parts";
+import { buildOutbound, isEmpty, type Draft } from "../core/outbound";
+import {
+  dequeue,
+  editQueued,
+  emptyQueue,
+  enqueue,
+  promoteQueued,
+  removeQueued,
+  type QueueState,
+} from "../core/queue";
+import {
+  appendUserMessage,
+  emptyTranscript,
+  reduce,
+  selectMessages,
+  type TranscriptState,
+} from "../core/transcript";
+import { messageOf } from "../utils";
+import { createSubscribers, type Listener } from "./subscribers";
+
+export interface ChatState {
+  readonly transcript: TranscriptState;
+  /** Prompts written while a turn was in flight, oldest first. */
+  readonly queue: QueueState;
+  /** Non-null while a turn is in flight; aborting it is the only way to stop. */
+  readonly inFlight: AbortController | null;
+  /**
+   * Whether the host's history fetch has answered.
+   *
+   * Starts `false`: a store with no messages and no answer yet is LOADING, and
+   * defaulting the other way is what let the empty state paint during a fetch.
+   * A host that never seeds history calls `setHistoryLoaded(true)` once.
+   */
+  readonly historyLoaded: boolean;
+}
+
+
+export interface ChatStore {
+  getState(): ChatState;
+  subscribe(listener: Listener): () => void;
+  /** Notified only when THIS message changes — the reason rows do not re-render. */
+  subscribeMessage(id: string, listener: Listener): () => void;
+  send(draft: Draft): Promise<void>;
+  /** Queue explicitly. `send` already queues when a turn is in flight. */
+  enqueue(draft: Draft): void;
+  removeQueued(id: string): void;
+  /** Replace a queued draft; editing it to empty removes the entry. */
+  editQueued(id: string, draft: Draft): void;
+  /**
+   * Take a queued prompt back out for editing — the ArrowUp affordance.
+   *
+   * REMOVES it, unlike recalling a sent prompt, which copies. A sent turn
+   * already happened and rewriting it is a different, explicit operation; a
+   * queued prompt has not been seen by anyone, so leaving a copy behind would
+   * send it twice — once as the entry still in the queue and once as the edit.
+   *
+   * Returns the draft so the caller can put it in the buffer, or `undefined` for
+   * an unknown id.
+   */
+  takeQueued(id: string): Draft | undefined;
+  /**
+   * Cut the current turn short and release ONE queued prompt immediately.
+   *
+   * Named by row, because the button sits beside a row and the drain always
+   * takes the head — so this promotes first. See `promoteQueued`.
+   *
+   * The prompt is not sent here. `stop()` aborts, and the turn's own `finally`
+   * releases the head; one owner for "what goes next" is what stops a forced
+   * release and a natural one from drifting. That block normally refuses to
+   * drain after an abort — deliberately, so Stop cannot start something — and
+   * this is the one intent that overrides it.
+   */
+  sendQueuedNow(id: string): void;
+  stop(): void;
+  /**
+   * Abandon what belongs to the room being left: aborts the in-flight turn and
+   * drops the queue. A turn and a queued prompt belong to the room they were
+   * written in, so carrying either across a switch streams a reply into a
+   * conversation that never asked for it. NOT the transcript — the caller
+   * reseeds immediately. `stop()` is not a substitute: it leaves the queue,
+   * which then drains into the wrong room.
+   */
+  leaveRoom(): void;
+  /** Seed from history. Replaces the transcript wholesale; not a merge. */
+  load(messages: readonly ChatMessage[]): void;
+  /**
+   * Whether the host's history fetch has answered.
+   *
+   * An empty transcript means two different things — a room with no messages,
+   * and a room whose messages are still in flight — and only the host knows
+   * which. Without this the empty state showed for the duration of every cold
+   * fetch: measured ~100ms on a room that then rendered 90 replies.
+   */
+  setHistoryLoaded(loaded: boolean): void;
+}
+
+export interface StoreOptions {
+  readonly adapter: ChatAdapter;
+  /** Injected so tests stay deterministic and history replay keeps real stamps. */
+  readonly makeId: () => string;
+  readonly now: () => number;
+}
+
+export function createChatStore(options: StoreOptions): ChatStore {
+  let state: ChatState = {
+    transcript: emptyTranscript,
+    queue: emptyQueue,
+    inFlight: null,
+    historyLoaded: false,
+  };
+  /**
+   * Set by `sendQueuedNow` so the abort it triggers still drains.
+   *
+   * NOT part of `ChatState`: it lives only between an abort and the `finally`
+   * that reads it, nothing renders from it, and putting it in the state would
+   * wake every subscriber for a flag none of them can see.
+   *
+   * Cleared where it is read, so an ordinary Stop that follows can never inherit
+   * a release the user did not ask for.
+   */
+  let releaseAfterAbort = false;
+  const { notify, subscribe, subscribeMessage } = createSubscribers();
+
+  function apply(next: ChatState, changed: Iterable<string>): void {
+    state = next;
+    notify(changed);
+  }
+
+  function applyChunk(chunk: StreamChunk): void {
+    const before = state.transcript;
+    const transcript = reduce(before, chunk);
+    if (transcript === before) return;
+
+    // Only the streaming message can change, so that is the only row to wake.
+    // Waking all of them here is precisely the stutter this store exists to
+    // avoid, and it would go unnoticed until the transcript got long.
+    const touched = transcript.streamingId ?? before.streamingId;
+    apply({ ...state, transcript }, touched === null ? [] : [touched]);
+  }
+
+  /**
+   * End a turn that failed, whether or not the assistant ever opened a message.
+   *
+   * The subtle case this exists for: `sendMessage()` rejecting BEFORE any
+   * `message-start`. Routing that through the reducer would be a no-op — there
+   * is no message to mark — so a connection refused, a 500, or a bad auth token
+   * left the transcript looking as if nothing had been sent. Silent failure is
+   * the worst outcome of the three; a visible failed turn is the point.
+   */
+  function fail(status: MessageStatus, userMessageId: string): void {
+    const streaming = state.transcript.streamingId;
+    if (streaming !== null) {
+      const message = state.transcript.byId[streaming];
+      if (message !== undefined) {
+        apply(
+          {
+            ...state,
+            transcript: {
+              ...state.transcript,
+              byId: { ...state.transcript.byId, [streaming]: { ...message, status } },
+              streamingId: null,
+            },
+          },
+          [streaming],
+        );
+        return;
+      }
+    }
+
+    // No assistant message exists, so the user's own turn carries the verdict.
+    const user = state.transcript.byId[userMessageId];
+    if (user === undefined) return;
+    apply(
+      {
+        ...state,
+        transcript: {
+          ...state.transcript,
+          byId: { ...state.transcript.byId, [userMessageId]: { ...user, status } },
+        },
+      },
+      [userMessageId],
+    );
+  }
+
+  const store: ChatStore = {
+    getState: () => state,
+
+    subscribe,
+    subscribeMessage,
+
+    setHistoryLoaded(loaded) {
+      if (state.historyLoaded === loaded) return;
+      apply({ ...state, historyLoaded: loaded }, []);
+    },
+
+    load(messages) {
+      const byId: Record<string, ChatMessage> = {};
+      for (const message of messages) byId[message.id] = message;
+      apply(
+        {
+          ...state,
+          transcript: { ids: messages.map((m) => m.id), byId, streamingId: null },
+        },
+        messages.map((m) => m.id),
+      );
+    },
+
+    stop() {
+      state.inFlight?.abort();
+    },
+
+    leaveRoom() {
+      // Both effects are synchronous and independent: `abort()` only signals,
+      // and the turn's `finally` runs a microtask later, by which time the queue
+      // is already empty. The drain is refused there anyway — `releaseAfterAbort`
+      // stays false, so leaving a room can never SEND one of its queued prompts.
+      if (state.queue !== emptyQueue) apply({ ...state, queue: emptyQueue }, []);
+      state.inFlight?.abort();
+    },
+
+    async send(draft) {
+      // Guarded here rather than in the composer so that every entry point —
+      // keyboard, button, a host calling `send` directly — obeys it.
+      if (isEmpty(draft)) return;
+
+      // One turn at a time: two streams into one message cannot be untangled,
+      // because no chunk carries enough identity to say which it belongs to.
+      //
+      // But a turn already in flight now QUEUES rather than returning. The bare
+      // `return` here discarded the prompt in silence — no error, no toast, the
+      // text simply gone — at exactly the moment our minutes-long agents make a
+      // user most likely to add something. The queue drains itself in `finally`.
+      if (state.inFlight !== null) {
+        apply({ ...state, queue: enqueue(state.queue, draft, options.makeId()) }, []);
+        return;
+      }
+
+      const outbound = buildOutbound(draft, options.makeId(), options.now());
+      const controller = new AbortController();
+
+      // Captured BEFORE the user's message is appended. `history` means prior
+      // turns; including the turn whose text rides beside it makes an adapter
+      // that concatenates the two send the message twice.
+      const history = selectMessages(state.transcript);
+
+      // The user's turn is authored, not streamed — it goes in whole. The
+      // assistant's message is opened later by the adapter's `message-start`,
+      // because only the adapter knows its id.
+      apply(
+        {
+          ...state,
+          transcript: appendUserMessage(state.transcript, outbound.message),
+          inFlight: controller,
+        },
+        [outbound.message.id],
+      );
+
+      try {
+        const stream = await options.adapter.sendMessage({
+          text: outbound.text,
+          history,
+          ...(draft.replyTo ? { replyTo: draft.replyTo } : {}),
+          signal: controller.signal,
+        });
+        const reader = stream.getReader();
+        // The loop races each read against the abort signal rather than
+        // checking it between reads. A transport that ignores the signal parks
+        // in `read()` forever, and a between-reads check never runs again — so
+        // Stop would look dead precisely on the stalled turn it exists for.
+        for (;;) {
+          const next = await Promise.race([reader.read(), aborted(controller.signal)]);
+          if (next === ABORTED) {
+            void reader.cancel().catch(() => undefined);
+            break;
+          }
+          if (next.done) break;
+          applyChunk(next.value);
+        }
+        // A stream that ends without a terminal frame is an interruption, not a
+        // completion: the reply may still have been persisted server-side, so
+        // the host reconciles rather than showing a permanent error. Routed
+        // through `fail` so a stream that closed before `message-start` is
+        // still visible rather than silently doing nothing.
+        if (state.transcript.streamingId !== null || controller.signal.aborted) {
+          fail({ state: "interrupted" }, outbound.message.id);
+        }
+      } catch (error) {
+        fail(
+          controller.signal.aborted
+            ? { state: "interrupted" }
+            : { state: "failed", message: messageOf(error) },
+          outbound.message.id,
+        );
+      } finally {
+        apply({ ...state, inFlight: null }, []);
+
+        // Drain the next queued prompt — unattended, because a queue that
+        // needed a "go" button would be a to-do list, not a queue.
+        //
+        // NOT after an abort. The user pressed Stop; sending the next prompt
+        // would make Stop start something, which is the opposite of what the
+        // control says. Their queue survives for when they choose to continue.
+        // Read and cleared together: a forced release is spent by the abort it
+        // was set for, so a later plain Stop cannot inherit it.
+        const forced = releaseAfterAbort;
+        releaseAfterAbort = false;
+
+        if (!controller.signal.aborted || forced) {
+          const { next, rest } = dequeue(state.queue);
+          if (next !== null) {
+            apply({ ...state, queue: rest }, []);
+            // `store.send`, never `this.send`: every consumer destructures
+            // (`const { send } = useChatStore()`), and a `this` that arrives
+            // undefined would throw here — inside a `finally`, where it would
+            // mask whatever the turn was actually doing.
+            //
+            // `void`: this send owns its own errors, and awaiting it would chain
+            // every queued turn onto the first one's promise, so an abort deep in
+            // the chain would settle a caller that is long gone.
+            void store.send(next.draft);
+          }
+        }
+      }
+    },
+
+    enqueue(draft) {
+      if (isEmpty(draft)) return;
+      apply({ ...state, queue: enqueue(state.queue, draft, options.makeId()) }, []);
+    },
+
+    removeQueued(id) {
+      apply({ ...state, queue: removeQueued(state.queue, id) }, []);
+    },
+
+    editQueued(id, draft) {
+      apply({ ...state, queue: editQueued(state.queue, id, draft) }, []);
+    },
+
+    takeQueued(id) {
+      const chosen = state.queue.items.find((item) => item.id === id);
+      if (chosen === undefined) return undefined;
+      apply({ ...state, queue: removeQueued(state.queue, id) }, []);
+      return chosen.draft;
+    },
+
+    sendQueuedNow(id) {
+      // Nothing in flight: the queue is not waiting on anything, so there is no
+      // turn to cut short and the abort path would do nothing at all. Release it
+      // directly instead of leaving the button dead.
+      if (state.inFlight === null) {
+        const taken = store.takeQueued(id);
+        if (taken !== undefined) void store.send(taken);
+        return;
+      }
+      // Promote BEFORE aborting: the drain takes the head, and the abort's
+      // `finally` can run as soon as the signal fires.
+      const promoted = promoteQueued(state.queue, id);
+      if (promoted === state.queue) return;
+      apply({ ...state, queue: promoted }, []);
+      releaseAfterAbort = true;
+      state.inFlight.abort();
+    },
+  };
+
+  return store;
+}
+
+/** Sentinel for "the signal won the race", distinguishable from a read result. */
+const ABORTED = Symbol("aborted");
+
+function aborted(signal: AbortSignal): Promise<typeof ABORTED> {
+  if (signal.aborted) return Promise.resolve(ABORTED);
+  return new Promise((resolve) => {
+    signal.addEventListener("abort", () => resolve(ABORTED), { once: true });
+  });
+}

package/src/store/subscribers.ts

@@ -0,0 +1,55 @@
+export type Listener = () => void;
+
+/**
+ * Who gets told, and how narrowly.
+ *
+ * Split out of `store.ts` because it is the one part that touches no state at
+ * all: it holds two sets of callbacks and decides which of them to wake. The
+ * store owns WHEN a transition happens; this owns WHO hears about it.
+ *
+ * Per-message subscription is the load-bearing part, not an optimisation. A
+ * transcript that re-renders every row on every token is the difference between
+ * a chat that feels instant and one that stutters at fifty messages — and it
+ * cannot be retrofitted, because it decides the shape of the selectors.
+ */
+export interface Subscribers {
+  /** Wake the whole-store listeners, plus the rows named in `changed`. */
+  readonly notify: (changed: Iterable<string>) => void;
+  /** Subscribe to any change. Returns the unsubscribe. */
+  readonly subscribe: (listener: Listener) => () => void;
+  /** Subscribe to ONE message's changes. Returns the unsubscribe. */
+  readonly subscribeMessage: (id: string, listener: Listener) => () => void;
+}
+
+export function createSubscribers(): Subscribers {
+  const listeners = new Set<Listener>();
+  const perMessage = new Map<string, Set<Listener>>();
+
+  return {
+    notify(changed) {
+      for (const listener of listeners) listener();
+      for (const id of changed) {
+        const set = perMessage.get(id);
+        if (set === undefined) continue;
+        for (const listener of set) listener();
+      }
+    },
+
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+
+    subscribeMessage(id, listener) {
+      const set = perMessage.get(id) ?? new Set<Listener>();
+      set.add(listener);
+      perMessage.set(id, set);
+      return () => {
+        set.delete(listener);
+        // Dropped when the last listener for that id leaves, so a long session
+        // does not accumulate an empty Set per message ever rendered.
+        if (set.size === 0) perMessage.delete(id);
+      };
+    },
+  };
+}

package/src/store/surfaces.ts

@@ -0,0 +1,174 @@
+import { createContext, useCallback, useContext, useRef } from "react";
+
+/**
+ * Where the chat's two surfaces are in the DOM.
+ *
+ * Separate from the draft context on purpose: that one answers "what has been
+ * typed", this one "where is it being typed". A host needs the second to put
+ * the caret back after a modal closes, and to scope ⌘A to the conversation.
+ *
+ * Registration, not a ref prop. Threading refs out would put a prop on
+ * `Composer` and `Transcript` for one host's benefit, and both are deliberately
+ * narrow. The surfaces know where they are; this is how they say so.
+ *
+ * THE ALTERNATIVE THIS REPLACES, and why it had to go: the host resolved
+ * both by `document.querySelector` — the transcript by the class
+ * `.chat-surface`, the field by `textarea[aria-label="…"]` built from a
+ * TRANSLATED string. So renaming a layout class or retranslating "Message"
+ * silently broke focus, in one locale, with every test green.
+ */
+export interface ChatSurfaces {
+  /** Put the caret in the composer, at the end of the draft. */
+  focusComposer(): void;
+  /** The scrolling transcript, for a selection scoped to the conversation. */
+  transcriptNode(): HTMLElement | null;
+  /**
+   * Append a mention to the draft and put the caret after it.
+   *
+   * Published by the composer: the draft lives in its state, so a transcript
+   * calling `useDraft` would write into one nothing sends.
+   * False when no composer published a handler — omit the affordance then.
+   */
+  mention(token: string): boolean;
+  /**
+   * Aim the draft at a message, or `undefined` to clear it.
+   *
+   * Separate from `mention`: quoting and addressing are different acts, and the
+   * contact card mentions without answering anything. False when no composer is
+   * listening.
+   */
+  replyTo(messageId: string | undefined): boolean;
+  /**
+   * Scroll a message into view and mark it briefly, so the eye can find it.
+   *
+   * False when the transcript has not mounted or the message is not in the
+   * loaded page — history is paged, so that is an ordinary answer and a caller
+   * can fall back (fetch, or say so) instead of scrolling nowhere.
+   */
+  revealMessage(messageId: string): boolean;
+  /** Called by the surfaces themselves. Not for hosts. */
+  registerComposer(node: HTMLFormElement | null): void;
+  registerTranscript(node: HTMLElement | null): void;
+  registerMention(handler: ((token: string) => void) | null): void;
+  registerReplyTo(handler: ((messageId: string | undefined) => void) | null): void;
+}
+
+export const ChatSurfacesContext = createContext<ChatSurfaces | null>(null);
+
+/**
+ * The two surfaces, once they exist.
+ *
+ * Returns null outside a provider rather than throwing: a host asking where the
+ * composer is before one has mounted is the normal opening state, not an error.
+ */
+export function useChatSurfaces(): ChatSurfaces | null {
+  return useContext(ChatSurfacesContext);
+}
+
+/** Builds the registry the provider hands down. Called once, at the root. */
+export function useSurfacesRegistry(): ChatSurfaces {
+  const composer = useRef<HTMLFormElement | null>(null);
+  const transcript = useRef<HTMLElement | null>(null);
+  const mentionHandler = useRef<((token: string) => void) | null>(null);
+  const replyToHandler = useRef<((messageId: string | undefined) => void) | null>(null);
+
+  // Caret at the END: focus returning to a written draft means "keep typing",
+  // and position zero would type into the front of it.
+  const caretToEnd = useCallback(() => {
+    const field = composer.current?.querySelector("textarea");
+    if (!field) return false;
+    field.focus();
+    const end = field.value.length;
+    field.setSelectionRange(end, end);
+    return true;
+  }, []);
+
+  const focusComposer = useCallback(() => {
+    // Retried on the next frame when the composer is not mounted YET, which is
+    // the normal case rather than an error: the common caller is a modal
+    // handing the caret back as it closes, and the composer it is handing back
+    // to only re-appears on the render that follows.
+    if (!caretToEnd()) requestAnimationFrame(caretToEnd);
+  }, [caretToEnd]);
+
+  const transcriptNode = useCallback(() => transcript.current, []);
+
+  const registerComposer = useCallback((node: HTMLFormElement | null) => {
+    composer.current = node;
+  }, []);
+
+  const registerTranscript = useCallback((node: HTMLElement | null) => {
+    transcript.current = node;
+  }, []);
+
+  const registerMention = useCallback((handler: ((token: string) => void) | null) => {
+    mentionHandler.current = handler;
+  }, []);
+
+  const mention = useCallback(
+    (token: string) => {
+      if (mentionHandler.current === null) return false;
+      mentionHandler.current(token);
+      // Next frame, or `value.length` measures the draft before the append.
+      // Caret, never a selection: a mention is added in order to keep typing.
+      requestAnimationFrame(caretToEnd);
+      return true;
+    },
+    [caretToEnd],
+  );
+
+  const revealMessage = useCallback((messageId: string) => {
+    const root = transcript.current;
+    if (root === null) return false;
+    const target = root.querySelector<HTMLElement>(
+      `[data-message-id="${CSS.escape(messageId)}"]`,
+    );
+    if (target === null) return false;
+    target.scrollIntoView({ block: "center", behavior: "smooth" });
+    // A scroll alone lands the reader mid-transcript with nothing saying which
+    // row was meant. The class is removed on the way out so a second jump to the
+    // same row flashes again.
+    target.classList.remove("chat-revealed");
+    void target.offsetWidth;
+    target.classList.add("chat-revealed");
+    return true;
+  }, []);
+
+  const registerReplyTo = useCallback(
+    (handler: ((messageId: string | undefined) => void) | null) => {
+      replyToHandler.current = handler;
+    },
+    [],
+  );
+
+  const replyTo = useCallback(
+    (messageId: string | undefined) => {
+      if (replyToHandler.current === null) return false;
+      replyToHandler.current(messageId);
+      // Focus only when AIMING: clearing is a dismissal, and stealing the caret
+      // back would fight a reader who just put it somewhere else.
+      if (messageId !== undefined) requestAnimationFrame(caretToEnd);
+      return true;
+    },
+    [caretToEnd],
+  );
+
+  // A ref rather than a memo: the identity is load-bearing (a host may hold
+  // `focusComposer` in a dependency array), and `useMemo` is a hint React may
+  // discard. The callbacks above are already stable, so this never restages.
+  const api = useRef<ChatSurfaces | null>(null);
+  if (api.current === null) {
+    api.current = {
+      focusComposer,
+      transcriptNode,
+      mention,
+      replyTo,
+      revealMessage,
+      registerComposer,
+      registerTranscript,
+      registerMention,
+      registerReplyTo,
+    };
+  }
+  return api.current;
+}