@djangocfg/widget-chat 0.1.1

package/src/core/outbound.ts

@@ -0,0 +1,86 @@
+/**
+ * The outbound payload has ONE owner, and it is this file.
+ *
+ * Everything a turn sends passes through `buildOutbound`. A caller that
+ * assembles text itself is the bug, not a shortcut.
+ */
+
+import type { ChatMessage, MessagePart } from "./parts";
+import { appendToolMarkers, type ToolPick } from "./tool-picks";
+
+export interface Draft {
+  readonly text: string;
+  /**
+   * Tools picked from the menu, in the order they were picked.
+   *
+   * They reach the model as markers appended by `buildOutbound`, and the
+   * transcript not at all — the sent bubble shows what the user wrote.
+   *
+   * Optional because `Draft` crosses the package boundary: a host's own draft,
+   * or one restored from storage written before this field existed, carries no
+   * list, and absent must mean "picked nothing" rather than a send-path crash.
+   */
+  readonly pickedTools?: readonly ToolPick[];
+  /**
+   * The message this draft answers, by the host's own id.
+   *
+   * State the draft genuinely owns, unlike an addressee: addressing is written
+   * in the text, while "which message" has nowhere else to live and rides the
+   * send as its own field.
+   */
+  readonly replyTo?: string;
+}
+
+export const emptyDraft: Draft = { text: "", pickedTools: [] };
+
+/** Nothing to send. */
+export function isEmpty(draft: Draft): boolean {
+  // A picked tool alone IS sendable: choosing one from the menu is a request,
+  // and refusing to send it would leave the pick visible with no way to act
+  // on it.
+  return draft.text.trim() === "" && (draft.pickedTools?.length ?? 0) === 0;
+}
+
+export interface Outbound {
+  /** What the model receives: the typed text, with tool markers appended. */
+  readonly text: string;
+  /** What the transcript shows: the user's own words. */
+  readonly message: ChatMessage;
+}
+
+/**
+ * Build both renderings of one turn at once.
+ *
+ * They are deliberately different and deliberately built together: the model
+ * receives the tool markers, the transcript shows only what the user wrote.
+ * Deriving one from the other later is how they drift — and a drift here means
+ * the transcript lies about what was sent.
+ */
+export function buildOutbound(draft: Draft, id: string, createdAt: number): Outbound {
+  const parts: MessagePart[] = [];
+  if (draft.text.trim() !== "") {
+    parts.push({ type: "text", id: `${id}:text`, text: draft.text });
+  }
+  return {
+    // Markers land on the MODEL's rendering alone. In `parts` the sent bubble
+    // would carry a link the user never typed, where they expect their own
+    // words.
+    text: appendToolMarkers(draft.text, draft.pickedTools),
+    message: {
+      id,
+      role: "user",
+      parts,
+      status: { state: "complete" },
+      createdAt,
+      // Spread, so the field is ABSENT rather than "" when nothing is answered:
+      // the quote keys on `undefined`, and an empty id would send it looking up
+      // a message that cannot exist.
+      //
+      // The bubble the sender sees is built here, not read back from the wire.
+      // Dropping it would leave the sender with no quote while every other
+      // reader — who loads the turn from storage, which does persist it — sees
+      // one, so the same message would render two ways.
+      ...(draft.replyTo ? { replyTo: draft.replyTo } : {}),
+    },
+  };
+}

package/src/core/parts.ts

@@ -0,0 +1,169 @@
+/**
+ * Message parts — the extension seam of this package.
+ *
+ * A new capability adds a PART TYPE here, never a prop to `<Chat>`. That is the
+ * only shape whose API cost stays flat as the product grows: the predecessor
+ * grew a prop per feature and reached 83, at which point no one could enumerate
+ * the configurations it claimed to support (`@rules/architecture.md`).
+ *
+ * Shape follows the Vercel AI SDK's `message.parts` (a discriminated union keyed
+ * on `type`, tool parts keyed by name) because the whole ecosystem converged on
+ * it. We copy the SHAPE, not the package — its majors broke the API twice.
+ */
+
+/**
+ * Stable identity for a streamed part.
+ *
+ * Two consumers need it and neither can improvise one: the reducer routes
+ * deltas by it, and React keys rows by it. An array index cannot serve — `reset`
+ * empties the parts array mid-turn, so index 0 legitimately becomes a different
+ * part and React reconciles the old DOM into it.
+ */
+export interface PartIdentity {
+  readonly id: string;
+}
+
+/** Plain assistant or user prose. Markdown is a rendering concern, not a type. */
+export interface TextPart extends PartIdentity {
+  readonly type: "text";
+  readonly text: string;
+}
+
+/**
+ * Model thinking. Separate from `text` because it collapses by default and is
+ * never part of the copyable answer.
+ */
+export interface ReasoningPart extends PartIdentity {
+  readonly type: "reasoning";
+  readonly text: string;
+  /**
+   * Still thinking. The block shows a live label while true and a settled
+   * summary once false.
+   *
+   * Needed because a thought is sealed by the NEXT part opening, not by a
+   * chunk of its own — without this the transcript cannot tell a thought still
+   * arriving from one that finished, and both would render identically.
+   */
+  readonly streaming?: boolean;
+  /**
+   * Measured wall time, when the engine measured it. Absent is ordinary — a
+   * driven CLI engine reports no duration — so the block must read without it.
+   */
+  readonly elapsedMs?: number;
+  /**
+   * Reasoning tokens spent, when the engine reports them.
+   *
+   * The only true thing left to show when a provider ships the thinking block
+   * with its words stripped: `text` is "" and this is not. A block keyed on
+   * text alone renders nothing on the engine most likely to be running.
+   */
+  readonly tokens?: number;
+}
+
+/**
+ * Tool-call lifecycle. Four states, and the transition carries the payload —
+ * so a renderer can never read `output` before it exists.
+ *
+ * Modelled as a union rather than a `status` field plus optional `input`/
+ * `output`: the predecessor's `ToolCall` had `status` alongside optional
+ * `output`, which let "success with no output" and "still running" become the
+ * same value at the type level.
+ */
+export type ToolState =
+  /** Arguments are still streaming in; `input` is a partial JSON string. */
+  | { readonly state: "input-streaming"; readonly inputText: string }
+  /** Arguments complete, execution not finished. */
+  | { readonly state: "input-available"; readonly input: unknown }
+  | { readonly state: "output-available"; readonly input: unknown; readonly output: unknown }
+  | { readonly state: "output-error"; readonly input: unknown; readonly error: string };
+
+/**
+ * One tool invocation.
+ *
+ * `messages` is present from day one deliberately, ahead of any renderer for it:
+ * a tool that spawns a subagent carries that subagent's whole conversation, and
+ * assistant-ui showed this is the shape that works (nested read-only thread,
+ * parent tool renderers inherited inward). Retrofitting a nested thread onto a
+ * flat transcript later is a rewrite of every selector; reserving the field now
+ * costs one line.
+ */
+export interface ToolPart extends PartIdentity {
+  readonly type: "tool";
+  /** `id` IS the tool-call id — the wire's `toolCallId` maps onto it directly.
+   *  A second field holding the same value is a second source of truth. */
+  readonly toolName: string;
+  readonly toolState: ToolState;
+  /** Subagent transcript, when this tool ran one. Absent for an ordinary tool. */
+  readonly messages?: readonly ChatMessage[];
+}
+
+/**
+ * Product-specific typed content the agent authored (map, chart, image card…).
+ * `data` stays `unknown`: the renderer registry validates per kind, so an
+ * unknown or malformed kind degrades to a fallback instead of widening this
+ * union every time the agent learns a new block.
+ */
+export interface DataPart extends PartIdentity {
+  readonly type: "data";
+  readonly kind: string;
+  readonly data: unknown;
+}
+
+export type MessagePart = TextPart | ReasoningPart | ToolPart | DataPart;
+
+export type MessageRole = "user" | "assistant" | "system";
+
+/**
+ * Terminal state of an assistant turn.
+ *
+ * `interrupted` and `failed` are distinct because the RECOVERY differs: an
+ * interrupted turn may still have been persisted by the server and reconciles on
+ * reconnect, while a failed one is a verdict the server already recorded. The
+ * predecessor learned this the expensive way — a failure rendered as an ordinary
+ * reply looks like the agent said it, which is worse than silence.
+ */
+export type MessageStatus =
+  | { readonly state: "streaming" }
+  | { readonly state: "complete" }
+  | { readonly state: "interrupted" }
+  | { readonly state: "failed"; readonly message: string };
+
+export interface ChatMessage {
+  readonly id: string;
+  readonly role: MessageRole;
+  readonly parts: readonly MessagePart[];
+  readonly status: MessageStatus;
+  /** Wall-clock creation, millis. Ordering uses array position, never this. */
+  readonly createdAt: number;
+  /**
+   * WHO spoke this turn, as the host's own opaque reference — never a name.
+   *
+   * The package neither resolves nor renders it: a host with several speakers
+   * in one room passes a header slot that turns this into a line, and a host
+   * with one correspondent passes nothing. Absent on every turn the host does
+   * not attribute, which is the ordinary case.
+   */
+  readonly authorId?: string;
+  /**
+   * The message this one answers, as the host's own id.
+   *
+   * Rendered only where the host supplies a quote resolver — the package holds
+   * no transcript index and will not search one. Absent is the ordinary case.
+   */
+  readonly replyTo?: string;
+}
+
+/** Narrowing helpers — cheaper than repeating the discriminant at every call site. */
+export const isTextPart = (p: MessagePart): p is TextPart => p.type === "text";
+export const isToolPart = (p: MessagePart): p is ToolPart => p.type === "tool";
+
+/** A tool part that ran a subagent, i.e. one a nested thread can render. */
+export function subagentMessages(part: ToolPart): readonly ChatMessage[] | undefined {
+  return part.messages !== undefined && part.messages.length > 0 ? part.messages : undefined;
+}
+
+/** True once the tool produced something a renderer can show. */
+export function toolHasResult(part: ToolPart): boolean {
+  const s = part.toolState.state;
+  return s === "output-available" || s === "output-error";
+}

package/src/core/queue/index.ts

@@ -0,0 +1,15 @@
+// Prompts written while the agent is working.
+//
+// `store.send` used to open with `if (state.inFlight !== null) return;` — a
+// second turn was discarded in silence. Our agents run for minutes, so that was
+// exactly the moment a user most often had something to add.
+
+export {
+  dequeue,
+  editQueued,
+  emptyQueue,
+  enqueue,
+  promoteQueued,
+  removeQueued,
+} from "./queue";
+export type { QueuedPrompt, QueueState } from "./queue";

package/src/core/queue/queue.ts

@@ -0,0 +1,100 @@
+import { isEmpty, type Draft } from "../outbound";
+
+/**
+ * Prompts written while the agent is working.
+ *
+ * ## Why this exists
+ *
+ * `store.send` opened with `if (state.inFlight !== null) return;` — a second
+ * turn was DISCARDED, silently. Our agents run for minutes, so the moment a user
+ * most often has something to add is exactly the moment the composer threw it
+ * away. Nothing reported it: no error, no toast, the text simply vanished from
+ * the field.
+ *
+ * ## Draft objects, never strings
+ *
+ * A queued entry is a whole `Draft`. A queue of strings would drop the picked
+ * tools a turn carries beside its text. `core/outbound` already owns what a
+ * sendable turn is; this holds those.
+ *
+ * ## No settings
+ *
+ * Whether to queue is not a preference. Enter while streaming queues, always.
+ * A toggle here would be a question with no good default, asked of someone who
+ * is mid-sentence.
+ */
+
+export interface QueuedPrompt {
+  readonly id: string;
+  readonly draft: Draft;
+}
+
+export interface QueueState {
+  readonly items: readonly QueuedPrompt[];
+}
+
+export const emptyQueue: QueueState = { items: [] };
+
+/**
+ * Append, unless the draft is empty.
+ *
+ * Empty is rejected here rather than at the call site so every entry point —
+ * keyboard, button, a host calling directly — obeys one rule. Queueing nothing
+ * would put a row in the strip that sends nothing when it drains.
+ */
+export function enqueue(state: QueueState, draft: Draft, id: string): QueueState {
+  if (isEmpty(draft)) return state;
+  return { items: [...state.items, { id, draft }] };
+}
+
+/**
+ * Take the next prompt, or null.
+ *
+ * Returns the REMAINDER alongside it rather than mutating: the caller sends the
+ * draft and stores the rest, so a send that throws cannot leave the queue in a
+ * state where the prompt is both gone and unsent.
+ */
+export function dequeue(state: QueueState): {
+  readonly next: QueuedPrompt | null;
+  readonly rest: QueueState;
+} {
+  const [next, ...rest] = state.items;
+  if (next === undefined) return { next: null, rest: state };
+  return { next, rest: { items: rest } };
+}
+
+export function removeQueued(state: QueueState, id: string): QueueState {
+  return { items: state.items.filter((item) => item.id !== id) };
+}
+
+/**
+ * Move one prompt to the head, keeping the rest in order.
+ *
+ * "Send now" names a ROW, and the drain always takes the head — so without this
+ * the button beside the third prompt would release the first. Promotion rather
+ * than a send-this-one path because one code owner for "what goes next" is what
+ * keeps the forced release and the natural one from drifting apart.
+ *
+ * An unknown id returns the state unchanged rather than throwing: the row can be
+ * removed by another click between render and dispatch, and a queue that throws
+ * on a stale id would take the composer down for a race the user cannot see.
+ */
+export function promoteQueued(state: QueueState, id: string): QueueState {
+  const chosen = state.items.find((item) => item.id === id);
+  if (chosen === undefined) return state;
+  return { items: [chosen, ...state.items.filter((item) => item.id !== id)] };
+}
+
+/**
+ * Replace a queued draft — the edit affordance.
+ *
+ * An edit to empty REMOVES the entry. The alternative is a row the user has
+ * emptied on purpose that still occupies the strip and still sends nothing, and
+ * "delete it yourself" is an extra action for something already expressed.
+ */
+export function editQueued(state: QueueState, id: string, draft: Draft): QueueState {
+  if (isEmpty(draft)) return removeQueued(state, id);
+  return {
+    items: state.items.map((item) => (item.id === id ? { ...item, draft } : item)),
+  };
+}

package/src/core/recall/boundary.ts

@@ -0,0 +1,77 @@
+/**
+ * When does an arrow key walk the prompt ladder, and when does it move the
+ * caret?
+ *
+ * Pure — a function of the buffer, the caret and what recall last wrote — so the
+ * whole interaction is testable without an editor. The surface is meant to be
+ * swappable (textarea → Tiptap) without retesting the rules.
+ *
+ * ## The rule, and where it comes from
+ *
+ * Recall used to require a COMPLETELY empty composer. That made ArrowUp a dead
+ * key in any multi-line draft and left the down direction nowhere to go. The
+ * shells settled this decades ago with a boundary test, and zsh's
+ * `up-line-or-beginning-search` is the cheapest correct form: it asks whether
+ * the text LEFT OF THE CARET contains a newline rather than computing a row
+ * index. That is `atFirstLine`.
+ *
+ * ## The soft-wrap limit, stated rather than discovered
+ *
+ * One long line that WRAPS across three visual rows is ONE logical line here, so
+ * ArrowUp navigates instead of moving up a visual row. Doing better needs
+ * `coordsAtPos` pixel geometry and a live DOM, which this seam does not have —
+ * and a second editor-specific path is a worse trade than a named limit.
+ *
+ * Not hypothetical: it is the live complaint against Claude Code
+ * (anthropics/claude-code#63670), whose docs promise a visual-row rule its
+ * shipped build does not implement. We promise the logical-line rule and
+ * implement exactly that, and the story says so.
+ */
+
+/**
+ * Caret position within the composer buffer.
+ *
+ * A collapsed caret has `start === end`. A selection never navigates.
+ */
+export interface ComposerCaret {
+  readonly start: number;
+  readonly end: number;
+}
+
+/**
+ * True when nothing in the buffer sits above the caret — the top of the ladder.
+ *
+ * A selection is never a boundary: Up with text selected means "extend or
+ * collapse", and hijacking it destroys a selection the user is building.
+ * DevTools takes the same position.
+ */
+export function atFirstLine(value: string, caret: ComposerCaret | null): boolean {
+  if (value === "") return true;
+  if (caret === null || caret.start !== caret.end) return false;
+  return !value.slice(0, caret.start).includes("\n");
+}
+
+/** True when nothing in the buffer sits below the caret — the bottom rung. */
+export function atLastLine(value: string, caret: ComposerCaret | null): boolean {
+  if (value === "") return true;
+  if (caret === null || caret.start !== caret.end) return false;
+  return !value.slice(caret.end).includes("\n");
+}
+
+/**
+ * May an arrow press navigate at all, whatever the caret says?
+ *
+ * Only while the buffer is still recall's own: empty, or byte-identical to what
+ * recall last wrote. The moment the user types a character the buffer is theirs
+ * and arrows only move the caret.
+ *
+ * Taken from Codex's gate, and it has a second consequence worth naming: a
+ * non-empty buffer never navigates, so there is no buffer for a prefix filter to
+ * read. zsh/fish-style prefix search and this rule are mutually exclusive by
+ * construction — prefix search is off the table until something like `Ctrl+R`
+ * is wired instead.
+ */
+export function bufferIsRecallOwned(value: string, lastRecalled: string | null): boolean {
+  if (value === "") return true;
+  return lastRecalled !== null && value === lastRecalled;
+}

package/src/core/recall/from-transcript.ts

@@ -0,0 +1,47 @@
+/**
+ * The `sent` rungs of the recall ladder, read out of a room's transcript.
+ *
+ * `ladder.ts` WALKS the ladder; this builds the one array it walks. Split
+ * because the walk is about keystrokes and this is about the room: they change
+ * for unrelated reasons and neither needs the other to be tested.
+ *
+ * Derived from the transcript, never cached locally. The server is the SSoT for
+ * "what did I send here", so the ladder matches what is on screen and works from
+ * any browser or device — where a local copy is blind, and where it would also
+ * outlive the room it belongs to.
+ *
+ * A localStorage cache did exist, to cover the moment before history arrives. It
+ * went with the composer that consumed it: the surviving surface seeds from the
+ * transcript it has already loaded, so the cache only ever had a wrong answer to
+ * offer.
+ */
+
+/** Entries kept per room. Long enough to reach yesterday's prompt, short enough
+ *  that the whole ladder stays walkable. */
+const HISTORY_LIMIT = 50;
+
+/** A single oversized paste must not evict the entire ladder. */
+const MAX_ENTRY_LENGTH = 8_000;
+
+/** The slice of a chat message the ladder cares about. */
+interface LadderSource {
+  role: string;
+  content: string;
+}
+
+/**
+ * The room's user-authored prompts, oldest first.
+ *
+ * Immediate repeats collapse so a double-send does not burn two ArrowUp steps.
+ */
+export function ladderFromMessages(messages: readonly LadderSource[]): string[] {
+  const out: string[] = [];
+  for (const m of messages) {
+    if (m.role !== "user") continue;
+    const text = m.content.trim();
+    if (!text || text.length > MAX_ENTRY_LENGTH) continue;
+    if (out[out.length - 1] === text) continue;
+    out.push(text);
+  }
+  return out.slice(-HISTORY_LIMIT);
+}

package/src/core/recall/index.ts

@@ -0,0 +1,23 @@
+// ↑/↓ prompt recall: the boundary rules and the ladder they walk.
+//
+// Pure by design — the surface is meant to be swappable without retesting any
+// of this. May import: nothing.
+
+export {
+  atFirstLine,
+  atLastLine,
+  bufferIsRecallOwned,
+  type ComposerCaret,
+} from "./boundary";
+export {
+  REST,
+  recallNext,
+  recallPrevious,
+  type RecallLadder,
+  type RecallMove,
+  type RecallPosition,
+  type RecallState,
+} from "./ladder";
+// Where the `sent` rungs come FROM. `ladder.ts` walks the ladder; this builds
+// the one array it walks, out of the transcript rather than a local cache.
+export { ladderFromMessages } from "./from-transcript";