@djangocfg/widget-chat 0.1.1

package/src/composer/tray/command-progress.tsx

@@ -0,0 +1,116 @@
+import { useEffect, useRef, useState } from "react";
+import { Loader2 } from "lucide-react";
+import {
+  ComposerBanner,
+  ComposerBannerBody,
+  ComposerBannerDescription,
+  ComposerBannerIcon,
+  ComposerBannerTitle,
+} from "./banner";
+
+/**
+ * `<CommandProgress>` — "this session-control verb is still running".
+ *
+ * A control verb is not a turn: it opens no streaming message, so the
+ * transcript's pending row never appears for it and the composer shows nothing.
+ * The verb also takes real time — an engine walking a transcript is tens of
+ * seconds — which leaves a person who pressed Enter with an emptied field, no
+ * row in the conversation, and no evidence anything is happening. They press it
+ * again.
+ *
+ * Above the composer rather than in the transcript, and that follows the
+ * existing split rather than taste: `ComposerBanner` is where a notice about
+ * the SESSION goes, while the transcript's pending row belongs to a turn. A row
+ * in the transcript would also have to be removed again on completion, since
+ * the verb writes no message the row could resolve into.
+ *
+ * Copy is the HOST's, like every other banner here: which verbs exist comes
+ * from a generated catalogue this package does not read, and the sentence for
+ * one does not template across locales.
+ *
+ * The elapsed counter is the load-bearing half. A spinner alone says "busy" and
+ * says it identically at two seconds and at two minutes, which is exactly the
+ * ambiguity that makes a person retry; a climbing number says the wait is
+ * progressing rather than hung.
+ */
+export interface CommandProgressProps {
+  /**
+   * The verb in flight, or `null` when nothing is running. Null renders
+   * nothing, so this can be mounted unconditionally beside the other slots.
+   */
+  readonly verb: string | null;
+  /** What is happening, already localised — "Compacting the conversation…". */
+  readonly title: string;
+  /**
+   * Given whole seconds waited, the counter's text. Called only after the quiet
+   * threshold passes.
+   */
+  readonly elapsed: (seconds: number) => string;
+  /**
+   * How long to stay quiet before showing a number. A verb that finishes fast
+   * should leave no trace of a counter at all — a digit that appears and
+   * vanishes reads as a glitch.
+   */
+  readonly elapsedAfterMs?: number;
+}
+
+const DEFAULT_ELAPSED_AFTER_MS = 3_000;
+
+export function CommandProgress({
+  verb,
+  title,
+  elapsed,
+  elapsedAfterMs = DEFAULT_ELAPSED_AFTER_MS,
+}: CommandProgressProps) {
+  const seconds = useElapsedSeconds(verb, elapsedAfterMs);
+
+  if (verb === null) return null;
+
+  const counter = seconds === null ? null : elapsed(seconds);
+
+  return (
+    <ComposerBanner>
+      <ComposerBannerIcon tone="info">
+        <Loader2 className="size-4 animate-spin" aria-hidden />
+      </ComposerBannerIcon>
+      <ComposerBannerBody>
+        <ComposerBannerTitle>{title}</ComposerBannerTitle>
+        {counter === null ? null : (
+          <ComposerBannerDescription>
+            <span className="tabular-nums">{counter}</span>
+          </ComposerBannerDescription>
+        )}
+      </ComposerBannerBody>
+    </ComposerBanner>
+  );
+}
+
+/**
+ * Whole seconds since THIS verb started, or `null` under the threshold.
+ *
+ * Keyed on the verb rather than on mount: the banner stays mounted between two
+ * runs in the same room, so a mount-time start would report the age of the
+ * previous wait. Re-running the effect on the verb restarts the clock, and a
+ * `null` verb stops the interval rather than leaving it ticking behind an idle
+ * room.
+ */
+function useElapsedSeconds(verb: string | null, afterMs: number): number | null {
+  const startedAt = useRef(0);
+  const [seconds, setSeconds] = useState<number | null>(null);
+
+  useEffect(() => {
+    if (verb === null) {
+      setSeconds(null);
+      return;
+    }
+    startedAt.current = Date.now();
+    setSeconds(null);
+    const id = setInterval(() => {
+      const waited = Date.now() - startedAt.current;
+      setSeconds(waited < afterMs ? null : Math.floor(waited / 1_000));
+    }, 1_000);
+    return () => clearInterval(id);
+  }, [verb, afterMs]);
+
+  return seconds;
+}

package/src/composer/tray/picked-tools.tsx

@@ -0,0 +1,104 @@
+import { X } from "lucide-react";
+import { memo, useCallback, useRef, type ReactNode } from "react";
+
+import type { ToolPick } from "../../core/tool-picks";
+import { focusComposerField } from "../focus-field";
+import { useChatCopy } from "../../i18n";
+import { useComposer } from "../context";
+
+export interface ComposerPickedToolsProps {
+  /** Glyph for a pick's icon KEY. Absent, or unmapped, ⇒ a chip with no glyph. */
+  readonly icon?: (key: string) => ReactNode;
+  readonly className?: string;
+  readonly chipClassName?: string;
+}
+
+/**
+ * The tools staged on this draft, one chip each.
+ *
+ * Beside the `+` rather than inside the field: a pick has no position in the
+ * sentence, and a token spliced into the text would move as the user edits
+ * around it. Renders null when nothing is picked, so a host laying out the
+ * control row gets no empty box to undo.
+ */
+export function ComposerPickedTools({ icon, className, chipClassName }: ComposerPickedToolsProps) {
+  const { draft, removePickedTool } = useComposer();
+  const copy = useChatCopy().composer;
+  // A draft restored from storage predates this field; absent is "none picked".
+  const picked = draft.pickedTools ?? [];
+  if (picked.length === 0) return null;
+
+  return (
+    // Named, because a tool's label appears twice on screen — here and on its
+    // menu row — and without one neither a reader nor a test can say which.
+    <ul aria-label={copy.toolsPicked} className={className}>
+      {picked.map((pick) => (
+        <li key={pick.id}>
+          <PickedToolChip
+            pick={pick}
+            icon={icon}
+            onRemove={removePickedTool}
+            className={chipClassName}
+          />
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+export interface PickedToolChipProps {
+  readonly pick: ToolPick;
+  readonly icon?: (key: string) => ReactNode;
+  readonly onRemove: (id: string) => void;
+  readonly className?: string;
+}
+
+/** One chip. Memoized so typing does not re-render the staged row. */
+export const PickedToolChip = memo(function PickedToolChip({
+  pick,
+  icon,
+  onRemove,
+  className,
+}: PickedToolChipProps) {
+  const copy = useChatCopy().composer;
+  const removeRef = useRef<HTMLButtonElement>(null);
+  // The chip goes with the click, taking focus to `body` and dropping the next
+  // keystroke. Deferred for the reason the tool menu defers: this element
+  // unmounts in the same tick, and its blur would undo the focus.
+  const remove = useCallback(() => {
+    const form = removeRef.current?.closest("form");
+    onRemove(pick.id);
+    queueMicrotask(() => focusComposerField(form));
+  }, [onRemove, pick.id]);
+
+  return (
+    <span
+      /*
+        `h-7` matches the queue row exactly: both can be on screen at once, and
+        two heights read as two kinds of thing when they are the same kind —
+        something staged on this draft.
+      */
+      className={`inline-flex h-7 max-w-[12rem] items-center gap-1.5 ${className ?? ""}`}
+      // The id as data, so a host can style or find one pick without this
+      // package choosing a colour.
+      data-tool={pick.id}
+    >
+      {pick.icon === undefined ? null : icon?.(pick.icon)}
+      {/* `min-w-0` so the truncation resolves: a flex child refuses to shrink
+          past its content, which lets a long label widen the whole row. */}
+      <span className="min-w-0 truncate">{pick.label}</span>
+      <button
+        type="button"
+        /* `shrink-0` so the label truncates instead of this button vanishing —
+           a chip with no way to remove it is a dead end. Its reveal on hover
+           and focus lives in `styles/composer.css`, which owns the chip. */
+        className="shrink-0"
+        aria-label={copy.toolRemove}
+        ref={removeRef}
+        onClick={remove}
+      >
+        <X className="size-3" aria-hidden />
+      </button>
+    </span>
+  );
+});

package/src/composer/tray/queue.tsx

@@ -0,0 +1,202 @@
+import { ArrowUp, SkipForward, X } from "lucide-react";
+import { useState, type ReactNode } from "react";
+
+import type { QueuedPrompt } from "../../core/queue";
+import { plural, useChatCopy, useChatLanguage } from "../../i18n";
+import { useChatEvents, useQueue, useTurn } from "../../store";
+import { useReplaceText, type AskReplace } from "./use-replace-text";
+
+/**
+ * Rows kept on screen. Everything past this folds behind one line.
+ *
+ * Three, because the composer sits at the bottom of the transcript and each row
+ * eats it upward — enough to see a queue is forming, few enough that a long one
+ * does not become the screen.
+ */
+const INLINE_LIMIT = 3;
+
+export interface ComposerQueueProps {
+  /**
+   * Asked before a prompt cuts the running turn short.
+   *
+   * Injected for the same reason `useCopyAction` takes `write`: a dialog
+   * imported here would give this package a dialog implementation, and a second
+   * host no way to replace it. Absent ⇒ no confirmation and no control, because
+   * an unconfirmed interrupt is the one shape this must never ship.
+   *
+   * Resolving false must leave the queue untouched.
+   */
+  readonly confirmSendNow?: () => Promise<boolean>;
+  /**
+   * Asked before taking a prompt back into a composer that already holds text.
+   *
+   * Absent ⇒ the take replaces the draft outright. Editing still works; what is
+   * missing is the chance to keep both.
+   */
+  readonly askReplace?: AskReplace;
+  readonly className?: string;
+  /** The row list. Where a host puts the gap between rows. */
+  readonly listClassName?: string;
+  readonly itemClassName?: string;
+  /** Render one queued prompt. Absent ⇒ its text, truncated by the host's CSS. */
+  readonly renderItem?: (prompt: QueuedPrompt) => ReactNode;
+}
+
+/**
+ * Prompts waiting for the current turn to finish.
+ *
+ * **Absent when empty, shown in full when short.** The queue is not a feature to
+ * manage — it is a reassurance that nothing was lost, and that reassurance is
+ * only delivered if the user can SEE what was taken. One or two rows is the
+ * ordinary case and costs a click to open when collapsed, so they are open.
+ *
+ * Past `INLINE_LIMIT` the strip collapses to the summary line: the composer sits
+ * at the bottom of the transcript and an unbounded list grows upward into it,
+ * the same way an unbounded attachment tray once put 51 chips on screen.
+ */
+export function ComposerQueue({
+  confirmSendNow,
+  askReplace,
+  className,
+  listClassName,
+  itemClassName,
+  renderItem,
+}: ComposerQueueProps) {
+  const { items, count, remove, take, sendNow } = useQueue();
+  const events = useChatEvents();
+  const replace = useReplaceText(askReplace);
+  const { isStreaming } = useTurn();
+  const copy = useChatCopy().queue;
+  const language = useChatLanguage();
+  const [expanded, setExpanded] = useState(false);
+
+  // Absent, not empty-and-styled: a zero-height strip still occupies a gap in
+  // the composer's grid and still reads as a landmark.
+  if (count === 0) return null;
+
+  // The OVERFLOW collapses, never the whole strip.
+  //
+  // Hiding every row past the limit replaced the queue with a bare count — the
+  // fifth prompt took the first four off screen, and the reassurance the strip
+  // exists to give ("nothing was lost, here it is") went with them. The rows
+  // the user can see are the feature; only the tail beyond what fits is worth
+  // trading for a line.
+  const overflows = count > INLINE_LIMIT;
+  const visible = expanded ? items : items.slice(0, INLINE_LIMIT);
+  const hidden = count - visible.length;
+
+  // Idle needs no confirmation, so it needs no host dialog either. Only the
+  // interrupting path is gated on `confirmSendNow` — an unconfirmed interrupt
+  // is the one shape this must never ship.
+  //
+  // Shown when idle, not only while a turn runs. The queue drains itself when a
+  // turn ENDS on its own, but Stop refuses to drain deliberately — so after a
+  // Stop the prompt sat with no release control at all, which reads as the
+  // message having been swallowed. That is the state that most needs it.
+  const canSendNow = !isStreaming || confirmSendNow !== undefined;
+  // The label states what the click COSTS, so it follows the same condition the
+  // dialog does rather than being fixed at the interrupting wording.
+  const sendNowLabel = isStreaming ? copy.sendNow : copy.send;
+
+  const onSendNow = (id: string) => {
+    // Only a RUNNING turn is lost, so only that case is worth a dialog. With
+    // nothing in flight this sends immediately: asking "this will interrupt the
+    // current answer" when there is no current answer describes nothing.
+    if (!isStreaming) {
+      sendNow(id);
+      return;
+    }
+    // The answer is awaited before anything moves — promoting first and asking
+    // after would reorder the queue for a user who then declines.
+    void confirmSendNow?.().then((ok) => {
+      if (ok) sendNow(id);
+    });
+  };
+
+  /**
+   * Take a queued prompt back for editing.
+   *
+   * The write is attempted FIRST and the queue entry removed only if it landed:
+   * taking first would drop the prompt when the user cancels the replace. The
+   * text is read from `items` rather than from `take`, because `take` is the
+   * removal and must not run before the answer.
+   */
+  const onEdit = (id: string, text: string) => {
+    void replace(text).then((written) => {
+      if (!written) return;
+      const prompt = items.find((item) => item.id === id);
+      take(id);
+      // Announced only once BOTH steps landed. This path and recall's Tab order
+      // them in opposite directions on purpose, so an emit that a listener
+      // acted on would invert one of them and lose the prompt on cancel.
+      if (prompt !== undefined) events.emit("queue:taken", { id, draft: prompt.draft });
+    });
+  };
+
+  const more = plural(copy.more, hidden, language);
+
+  return (
+    <div className={className} data-slot="composer-queue">
+      <ul className={listClassName}>
+        {visible.map((prompt) => (
+            <li key={prompt.id} className={itemClassName}>
+              {/* The text itself is the edit affordance — no third icon. Taking
+                  a prompt back is what ↑ already does from the keyboard; this is
+                  the same act for any row, with the mouse. */}
+              <button
+                type="button"
+                data-action="edit"
+                title={copy.edit}
+                onClick={() => onEdit(prompt.id, prompt.draft.text)}
+              >
+                {renderItem?.(prompt) ?? <span>{prompt.draft.text}</span>}
+              </button>
+              {/* Icon-only: the label is a sentence and rendering it took the
+                  row from the prompt. It stays as the accessible name. */}
+              {canSendNow ? (
+                <button
+                  type="button"
+                  data-action="send-now"
+                  aria-label={sendNowLabel}
+                  title={sendNowLabel}
+                  onClick={() => onSendNow(prompt.id)}
+                >
+                  {/* Skip while a turn runs — it CUTS that turn, and a send
+                      arrow would hide the cost. With nothing to cut it is an
+                      ordinary send, and skip would name a turn that is over. */}
+                  {isStreaming ? (
+                    <SkipForward aria-hidden className="size-3.5" />
+                  ) : (
+                    <ArrowUp aria-hidden className="size-3.5" />
+                  )}
+                </button>
+              ) : null}
+              <button
+                type="button"
+                aria-label={copy.remove}
+                title={copy.remove}
+                onClick={() => remove(prompt.id)}
+              >
+                <X aria-hidden className="size-3.5" />
+              </button>
+            </li>
+        ))}
+      </ul>
+      {/* One toggle, two labels: `hidden` is 0 once expanded, so the same
+          control reads "3 more" and then "Show less". `type="button"` because
+          inside the composer's <form> a bare button submits — expanding the
+          queue would send the turn. */}
+      {overflows ? (
+        <button
+          type="button"
+          data-action="toggle-overflow"
+          aria-expanded={expanded}
+          onClick={() => setExpanded((value) => !value)}
+          className="w-full text-left"
+        >
+          {expanded ? copy.showLess : more}
+        </button>
+      ) : null}
+    </div>
+  );
+}

package/src/composer/tray/use-replace-text.ts

@@ -0,0 +1,58 @@
+import { useCallback } from "react";
+
+import { needsChoice } from "../../core/text-replace";
+import { useChatSurfaces } from "../../store";
+import { useComposer } from "../context";
+
+/**
+ * Asked when the field already holds something the write would destroy.
+ *
+ * Injected like `confirmSendNow`: a dialog imported here would give the package
+ * a dialog implementation and leave a second host no way to replace it.
+ *
+ * `true` ⇒ replace. A "no" costs nothing: the caller holds its own side of the
+ * move until this resolves, so declining leaves the field AND the source as
+ * they were.
+ */
+export type AskReplace = (incoming: string) => Promise<boolean>;
+
+/**
+ * Write text into the composer without silently destroying a draft.
+ *
+ * Resolves to whether the write happened, so a caller that also MOVES something
+ * — taking a queued prompt out of the queue — can hold its own side until the
+ * answer is in. The other order loses the prompt when the user cancels.
+ *
+ * Absent `ask` ⇒ replace outright. That is the honest default for a host with no
+ * dialog; refusing the write instead would read as a dead control.
+ */
+export function useReplaceText(ask?: AskReplace): (incoming: string) => Promise<boolean> {
+  const { draft, setText } = useComposer();
+  // The registry already knows which form is this chat's composer, and already
+  // retries on the next frame when it has not mounted. Locating the field here
+  // instead would be a second answer to the same question — the failure
+  // `surfaces.ts` was written to end.
+  const surfaces = useChatSurfaces();
+
+  return useCallback(
+    async (incoming: string) => {
+      if (incoming === "") return false;
+
+      const write = (text: string) => {
+        setText(text);
+        // Deferred: React writes the value on the next commit, so focusing now
+        // would put the caret against the OLD text and leave it mid-string.
+        queueMicrotask(() => surfaces?.focusComposer());
+      };
+
+      if (!needsChoice(draft.text, incoming) || ask === undefined) {
+        write(incoming);
+        return true;
+      }
+      if (!(await ask(incoming))) return false;
+      write(incoming);
+      return true;
+    },
+    [draft.text, setText, surfaces, ask],
+  );
+}

package/src/composer/use-draft-persistence.ts

@@ -0,0 +1,79 @@
+import { useEffect, useRef } from "react";
+
+import { draftStorageKey, draftWrite, mayPersist, restoredDraft } from "../core/draft-storage";
+import { useComposer } from "./context";
+
+/**
+ * Keep an unsent draft across a reload, per room.
+ *
+ * `sessionStorage`, not `localStorage`: a draft should survive an accidental
+ * reload, and should NOT still be waiting tomorrow in a room the user has left.
+ * Prompt recall makes the opposite trade, hence the different store.
+ *
+ * TEXT ONLY — a staged file is an object-URL pinned to this document, so a
+ * restored one is a chip that renders and cannot send. The ROOM is the
+ * caller's; this package has no notion of one (`use-reload-on-revision.ts`
+ * draws the same line).
+ *
+ * The rules live in `core/draft-storage.ts` so they can be tested without a
+ * DOM; this owns only the effects and refs.
+ */
+
+function read(key: string): string | null {
+  // Guarded: a sandboxed iframe and an SSR pass both THROW here rather than
+  // returning null, and a composer that cannot mount is worse than one that
+  // forgets.
+  try {
+    return globalThis.sessionStorage?.getItem(key) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function write(key: string, text: string): void {
+  const decision = draftWrite(text);
+  try {
+    if ("remove" in decision) globalThis.sessionStorage?.removeItem(key);
+    else globalThis.sessionStorage?.setItem(key, decision.value);
+  } catch {
+    // Quota, or storage denied. The draft still applies to this session; failing
+    // the keystroke because it cannot be saved would be the worse outcome.
+  }
+}
+
+/**
+ * Restore on mount, save on change.
+ *
+ * Clearing after a send needs no branch of its own: `send` resets the draft to
+ * `emptyDraft`, so the save path writes `""`, which removes the entry. Adding a
+ * send-specific hook here would give one behaviour two triggers.
+ *
+ * `room` changing means a different conversation: the effect restores that
+ * room's draft rather than carrying the current text into it.
+ */
+export function useDraftPersistence(room: string | undefined): void {
+  const { draft, setText } = useComposer();
+  // Which room's restore has completed. The save effect stays inert until it
+  // matches, so a restore is never overwritten by the emptiness preceding it.
+  const restored = useRef<string | null>(null);
+  // Read through a ref: seeding the restore effect with `setText` would re-arm
+  // it whenever the draft identity changes, re-restoring mid-typing.
+  const setTextRef = useRef(setText);
+  setTextRef.current = setText;
+
+  useEffect(() => {
+    // Absent room ⇒ the host wants no persistence. Guarded inside the effect,
+    // never by skipping the hook: a conditional call changes hook order the
+    // first time a host makes the room conditional.
+    if (room === undefined) return;
+    const stored = restoredDraft(read(draftStorageKey(room)));
+    restored.current = room;
+    if (stored !== null) setTextRef.current(stored);
+  }, [room]);
+
+  useEffect(() => {
+    if (room === undefined) return;
+    if (!mayPersist(restored.current, room)) return;
+    write(draftStorageKey(room), draft.text);
+  }, [room, draft.text]);
+}

package/src/content/index.ts

@@ -0,0 +1,16 @@
+// Markdown, code and math — the string-being-streamed layer.
+//
+// Separate from widgets/ because the input is a STRING ARRIVING TOKEN BY TOKEN,
+// not a finished data object. That difference is the whole problem: a
+// half-arrived fence must not throw, and a completed message must not re-parse
+// because a sibling changed.
+//
+// One component. The folder is small on purpose — the parser is `streamdown`,
+// adopted for exactly one property (it parses incomplete markdown) and pinned
+// by tests that would fail if it were swapped back. What lives here is the
+// CONFIGURATION of that parser, which is the part that is ours.
+//
+// May import: core, utils.
+
+export { Response, type ResponseProps } from "./response";
+export { renderMediaContent } from "./media-content";

package/src/content/media-content.tsx

@@ -0,0 +1,38 @@
+import type { ReactNode } from "react";
+
+import { LazyDiagram } from "@djangocfg/widget-media/diagram";
+import type { MediaBlock } from "../core";
+
+/**
+ * The renderer for the media kinds whose payload is TEXT, not a URL.
+ *
+ * `MediaWidget` has always routed `json`/`code`/`markdown`/`text`/`mermaid`
+ * through an optional `renderContent`, and nothing ever supplied one — so every
+ * one of them fell through to a `<pre>`, including the diagrams the `show_media`
+ * tool declares among its kinds. The callback was the seam; this is the thing
+ * that was missing from the other side of it.
+ *
+ * Only `mermaid` is answered here. The other four ARE plain text until this
+ * package has a reason to say otherwise, and the `<pre>` fallback is a correct
+ * rendering of them rather than a placeholder — returning null for those is what
+ * keeps the widget's own fallback in charge instead of duplicating it.
+ *
+ * Lives in `content/` because that is the layer that owns rendered content, and
+ * `widgets/` may import it. The diagram reaches the transcript through the
+ * layer whose job it is, not through a package a widget imported directly.
+ */
+export function renderMediaContent(block: MediaBlock): ReactNode {
+  if (block.kind !== "mermaid") return null;
+  // The wire calls this field `chart`; `readMediaBlock` normalises every
+  // textual kind onto `content`, so there is one name here for all of them.
+  const chart = block.content;
+  if (chart === undefined || chart.trim() === "") return null;
+  // Never streaming: a `show_media` block is dispatched once, whole. That is
+  // the caller-side half of the guard the renderer cannot answer from the
+  // source alone — the fenced rail, where the text really does arrive a token
+  // at a time, is guarded inside the streamdown plugin instead.
+  // Lazy: this file is reachable from the package ROOT through `data.tsx`, so
+  // an eager import would put the parser in every transcript's first paint —
+  // including the ones that never show a diagram.
+  return <LazyDiagram chart={chart} />;
+}