@runtypelabs/persona 4.8.0 → 4.10.0

package/src/utils/composer-document.test.ts

@@ -0,0 +1,280 @@
+import { describe, it, expect } from "vitest";
+import {
+  emptyDocument,
+  documentFromTextarea,
+  toDisplayText,
+  toLogicalText,
+  logicalLength,
+  mentionBlocksInOrder,
+  insertMention,
+  removeMention,
+  spliceDocument,
+  documentToMessageFields,
+  MENTION_PLACEHOLDER,
+  type ComposerDocument
+} from "./composer-document";
+import { parseMentionTrigger } from "./mention-trigger";
+import type { AgentWidgetContextMentionRef } from "../types";
+
+const appRef: AgentWidgetContextMentionRef = {
+  sourceId: "files",
+  itemId: "app",
+  label: "App.tsx"
+};
+const utilRef: AgentWidgetContextMentionRef = {
+  sourceId: "files",
+  itemId: "util",
+  label: "util.ts"
+};
+
+/** Build a document quickly and normalize via a no-op insert-free path. */
+function docOf(...blocks: ComposerDocument["blocks"]): ComposerDocument {
+  return { blocks };
+}
+
+describe("composer-document projections", () => {
+  it("emptyDocument is a single empty text block", () => {
+    expect(emptyDocument()).toEqual({ blocks: [{ kind: "text", value: "" }] });
+    expect(toLogicalText(emptyDocument())).toBe("");
+  });
+
+  it("documentFromTextarea wraps the value as one text block", () => {
+    expect(documentFromTextarea("hi there")).toEqual({
+      blocks: [{ kind: "text", value: "hi there" }]
+    });
+  });
+
+  it("projects text/display/logical distinctly around a token", () => {
+    const doc = docOf(
+      { kind: "text", value: "Check " },
+      { kind: "mention", id: "m1", ref: appRef },
+      { kind: "text", value: " for errors" }
+    );
+    expect(toDisplayText(doc)).toBe("Check @App.tsx for errors");
+    expect(toLogicalText(doc)).toBe("Check  for errors");
+    expect(logicalLength(doc)).toBe("Check  for errors".length);
+  });
+});
+
+describe("insertMention", () => {
+  it("replaces the @query range with a token and returns the trailing caret", () => {
+    // Start with "Check @App for errors"; caret after "@App" (index 10).
+    const start = documentFromTextarea("Check @App for errors");
+    const match = parseMentionTrigger(toLogicalText(start), 10);
+    expect(match).toEqual({ triggerIndex: 6, query: "App" });
+
+    const { doc, caret } = insertMention(
+      start,
+      { start: match!.triggerIndex, end: 10 },
+      appRef,
+      "m1"
+    );
+    // The pre-existing space separates; no second one is inserted.
+    expect(toDisplayText(doc)).toBe("Check @App.tsx for errors");
+    // caret hops the existing separator, landing after ` `.
+    expect(caret).toBe(8);
+    expect(toLogicalText(doc)[caret - 2]).toBe("");
+    expect(toLogicalText(doc)[caret - 1]).toBe(" ");
+  });
+
+  it("inserts at the very end of the document with a separating space", () => {
+    const start = documentFromTextarea("Look at @ap");
+    const { doc, caret } = insertMention(start, { start: 8, end: 11 }, appRef, "m1");
+    expect(toDisplayText(doc)).toBe("Look at @App.tsx ");
+    const mentions = mentionBlocksInOrder(doc);
+    expect(mentions).toHaveLength(1);
+    expect(mentions[0].ref).toEqual(appRef);
+    // Caret after the inserted space: typing or a fresh `@` chains directly.
+    expect(caret).toBe(toLogicalText(doc).length);
+  });
+
+  it("chains: a fresh trigger typed right after completion parses immediately", () => {
+    const start = documentFromTextarea("@ap");
+    const { doc, caret } = insertMention(start, { start: 0, end: 3 }, appRef, "m1");
+    // The auto-space satisfies the parser's preceding-whitespace requirement,
+    // so `@` chains without a manual spacebar press.
+    const typed = { blocks: [...doc.blocks, { kind: "text" as const, value: "@u" }] };
+    const logical = toLogicalText(typed);
+    expect(parseMentionTrigger(logical, logical.length)).toEqual({
+      triggerIndex: caret,
+      query: "u",
+    });
+  });
+
+  it("keeps a text slot between two adjacent inserted tokens (no adjacency)", () => {
+    let doc = documentFromTextarea("@a");
+    ({ doc } = insertMention(doc, { start: 0, end: 2 }, appRef, "m1"));
+    // Now type another trigger right after the token and select.
+    const logical = toLogicalText(doc); // ""
+    doc = { blocks: [...doc.blocks, { kind: "text", value: "@u" }] };
+    ({ doc } = insertMention(
+      doc,
+      { start: logical.length, end: logical.length + 2 },
+      utilRef,
+      "m2"
+    ));
+    // Two mentions, never directly adjacent (a text block separates them).
+    for (let i = 0; i < doc.blocks.length - 1; i++) {
+      const a = doc.blocks[i];
+      const b = doc.blocks[i + 1];
+      expect(a.kind === "mention" && b.kind === "mention").toBe(false);
+    }
+    expect(mentionBlocksInOrder(doc).map((m) => m.id)).toEqual(["m1", "m2"]);
+  });
+});
+
+describe("removeMention", () => {
+  it("drops a token and merges the surrounding text", () => {
+    const doc = docOf(
+      { kind: "text", value: "Check " },
+      { kind: "mention", id: "m1", ref: appRef },
+      { kind: "text", value: " now" }
+    );
+    const { doc: next, caret } = removeMention(doc, "m1");
+    expect(toDisplayText(next)).toBe("Check  now");
+    // A single merged text block remains.
+    expect(next.blocks).toEqual([{ kind: "text", value: "Check  now" }]);
+    // Caret lands where the token used to be.
+    expect(caret).toBe("Check ".length);
+  });
+
+  it("is a no-op for an unknown id", () => {
+    const doc = documentFromTextarea("nothing here");
+    const { doc: next } = removeMention(doc, "missing");
+    expect(next).toBe(doc);
+  });
+});
+
+describe("MENTION_PLACEHOLDER", () => {
+  it("is the U+FFFC object-replacement char, single-sourced from mention-trigger", () => {
+    expect(MENTION_PLACEHOLDER).toBe("");
+    expect(toLogicalText(
+      docOf(
+        { kind: "text", value: "a" },
+        { kind: "mention", id: "m1", ref: appRef }
+      )
+    )).toBe(`a${MENTION_PLACEHOLDER}`);
+  });
+});
+
+describe("spliceDocument", () => {
+  const withToken = (): ComposerDocument =>
+    docOf(
+      { kind: "text", value: "a " },
+      { kind: "mention", id: "m1", ref: appRef },
+      { kind: "text", value: " b" }
+    );
+
+  it("replaces a range OUTSIDE a token, preserving the token", () => {
+    // logical "a  b" (0='a' 1=' ' 2= 3=' ' 4='b'); replace the leading "a ".
+    const { doc, caret } = spliceDocument(withToken(), 0, 2, "X");
+    expect(toDisplayText(doc)).toBe("X@App.tsx b");
+    expect(mentionBlocksInOrder(doc)).toHaveLength(1);
+    expect(caret).toBe(1);
+  });
+
+  it("drops a token when the replaced range spans it (multi-block selection)", () => {
+    const { doc } = spliceDocument(withToken(), 1, 4, "");
+    expect(toDisplayText(doc)).toBe("ab");
+    expect(mentionBlocksInOrder(doc)).toHaveLength(0);
+  });
+
+  it("orders and clamps start/end defensively", () => {
+    // Reversed args → treated as [1, 4).
+    const reversed = spliceDocument(withToken(), 4, 1, "-");
+    expect(toDisplayText(reversed.doc)).toBe("a-b");
+    expect(reversed.caret).toBe(2);
+    // Out-of-range args → clamped to the whole document.
+    const whole = spliceDocument(withToken(), -5, 99, "Z");
+    expect(toDisplayText(whole.doc)).toBe("Z");
+    expect(whole.caret).toBe(1);
+  });
+});
+
+describe("parseMentionTrigger over logical text", () => {
+  it("does not report a query spanning an existing token", () => {
+    // "@a" typed, then token, then "b": logical "@ab". No active trigger at end.
+    const doc = docOf(
+      { kind: "text", value: "@a" },
+      { kind: "mention", id: "m1", ref: appRef },
+      { kind: "text", value: "b" }
+    );
+    const logical = toLogicalText(doc);
+    expect(logical).toBe("@ab");
+    expect(parseMentionTrigger(logical, logical.length)).toBeNull();
+  });
+
+  it("activates a fresh @ typed after a token", () => {
+    const doc = docOf(
+      { kind: "mention", id: "m1", ref: appRef },
+      { kind: "text", value: " @fo" }
+    );
+    const logical = toLogicalText(doc); // " @fo"
+    const match = parseMentionTrigger(logical, logical.length);
+    expect(match).toEqual({ triggerIndex: 2, query: "fo" });
+  });
+});
+
+describe("duplicate mentions", () => {
+  it("allows the same ref twice with distinct ids", () => {
+    let doc = documentFromTextarea("@a and @a");
+    ({ doc } = insertMention(doc, { start: 0, end: 2 }, appRef, "m1"));
+    const logical = toLogicalText(doc); // " and @a"
+    ({ doc } = insertMention(
+      doc,
+      { start: logical.indexOf("@"), end: logical.length },
+      appRef,
+      "m2"
+    ));
+    const mentions = mentionBlocksInOrder(doc);
+    expect(mentions.map((m) => m.id)).toEqual(["m1", "m2"]);
+    expect(mentions.every((m) => m.ref === appRef)).toBe(true);
+  });
+});
+
+describe("documentToMessageFields", () => {
+  it("emits content, contextMentions, and contentSegments in document order", () => {
+    const doc = docOf(
+      { kind: "text", value: "Check " },
+      { kind: "mention", id: "m1", ref: appRef },
+      { kind: "text", value: " for errors" }
+    );
+    const fields = documentToMessageFields(doc);
+    expect(fields.content).toBe("Check @App.tsx for errors");
+    expect(fields.contextMentions).toEqual([appRef]);
+    expect(fields.contentSegments).toEqual([
+      { kind: "text", text: "Check " },
+      { kind: "mention", ref: appRef },
+      { kind: "text", text: " for errors" }
+    ]);
+  });
+
+  it("preserves order and duplicates across multiple tokens", () => {
+    const doc = docOf(
+      { kind: "mention", id: "m1", ref: appRef },
+      { kind: "text", value: " vs " },
+      { kind: "mention", id: "m2", ref: utilRef }
+    );
+    const fields = documentToMessageFields(doc);
+    expect(fields.contextMentions).toEqual([appRef, utilRef]);
+    expect(fields.contentSegments).toEqual([
+      { kind: "mention", ref: appRef },
+      { kind: "text", text: " vs " },
+      { kind: "mention", ref: utilRef }
+    ]);
+  });
+
+  it("drops empty text runs from contentSegments", () => {
+    // A leading empty text block (structural) must not leak into the transcript.
+    const doc = docOf(
+      { kind: "text", value: "" },
+      { kind: "mention", id: "m1", ref: appRef },
+      { kind: "text", value: "" }
+    );
+    const fields = documentToMessageFields(doc);
+    expect(fields.contentSegments).toEqual([
+      { kind: "mention", ref: appRef }
+    ]);
+    expect(fields.content).toBe("@App.tsx");
+  });
+});

package/src/utils/composer-document.ts

@@ -0,0 +1,293 @@
+/**
+ * Pure, DOM-free document model for the inline-mention composer
+ * (`contextMentions.display: "inline"`).
+ *
+ * The canonical composer state is a flat, ordered list of blocks — text runs and
+ * atomic mention tokens — rather than a single string with range markers. Blocks
+ * make insert/remove, duplicate detection, and history round-trip explicit
+ * without parsing HTML. The DOM adapter (`composer-contenteditable.ts`) renders a
+ * document to a contenteditable surface and re-parses it back on input; this
+ * module owns everything that does not touch the DOM, so it is unit-testable in
+ * the Node env exactly like `mention-trigger.ts` and `composer-history.ts`.
+ *
+ * Two text projections exist, each for a distinct purpose:
+ *  - `toDisplayText` — text + `@label` per mention (the human-readable, sent
+ *                      bubble / model-visible prose).
+ *  - `toLogicalText` — text + `` (OBJECT REPLACEMENT CHAR) per mention. An
+ *                      INTERNAL index space only — never shown to the user, never
+ *                      sent to the model — that lets the existing
+ *                      `parseMentionTrigger` run over `(logicalText, caret)` with
+ *                      tokens standing in as single, query-terminating chars.
+ */
+
+import { MENTION_PLACEHOLDER } from "./mention-trigger";
+import type {
+  AgentWidgetContentSegment,
+  AgentWidgetContextMentionRef
+} from "../types";
+
+// Single-sourced from the dependency-free trigger module (see its definition for
+// why it lives there); re-exported here so existing importers keep working.
+export { MENTION_PLACEHOLDER };
+
+/** Stable id for one inline mention instance (DOM `data-mention-id`, history key). */
+export type ComposerMentionId = string;
+
+/** One block in the composer document. Order is significant. */
+export type ComposerBlock =
+  | { kind: "text"; value: string }
+  | {
+      kind: "mention";
+      id: ComposerMentionId;
+      ref: AgentWidgetContextMentionRef;
+    };
+
+/** Canonical inline-composer state. */
+export type ComposerDocument = {
+  blocks: ComposerBlock[];
+};
+
+/** A logical-coordinate range `[start, end)` into `toLogicalText(doc)`. */
+export type LogicalRange = { start: number; end: number };
+
+/** Prefix shown before a mention's label in display/model-visible prose. */
+const MENTION_DISPLAY_PREFIX = "@";
+
+/** Logical length of a single block (`` counts as one char). */
+function blockLength(block: ComposerBlock): number {
+  return block.kind === "text" ? block.value.length : 1;
+}
+
+/**
+ * Enforce the structural invariant that keeps caret placement stable: the
+ * document begins and ends with a text block and no two mention blocks are
+ * adjacent (an empty text block always separates them). Adjacent text runs are
+ * merged. This never changes any projection's output (empty text contributes the
+ * empty string) — it only guarantees a caret slot exists on every side of a token.
+ */
+function normalizeBlocks(blocks: ComposerBlock[]): ComposerBlock[] {
+  const out: ComposerBlock[] = [];
+  const pushText = (value: string): void => {
+    const last = out[out.length - 1];
+    if (last && last.kind === "text") last.value += value;
+    else out.push({ kind: "text", value });
+  };
+
+  // Ensure a leading text slot.
+  if (blocks.length === 0 || blocks[0].kind !== "text") {
+    out.push({ kind: "text", value: "" });
+  }
+
+  for (const block of blocks) {
+    if (block.kind === "text") {
+      pushText(block.value);
+      continue;
+    }
+    // Guarantee a text block precedes this mention (it does by construction, but
+    // stay defensive), then always trail one so the next block — text or another
+    // mention — keeps the alternation.
+    const last = out[out.length - 1];
+    if (!last || last.kind !== "text") out.push({ kind: "text", value: "" });
+    out.push({ kind: "mention", id: block.id, ref: block.ref });
+    out.push({ kind: "text", value: "" });
+  }
+
+  const last = out[out.length - 1];
+  if (!last || last.kind !== "text") out.push({ kind: "text", value: "" });
+  return out;
+}
+
+/** `{ blocks: [{ kind: "text", value: "" }] }`. */
+export function emptyDocument(): ComposerDocument {
+  return { blocks: [{ kind: "text", value: "" }] };
+}
+
+/** Chip-mode shim: wrap a raw textarea value as a single text block. */
+export function documentFromTextarea(value: string): ComposerDocument {
+  return { blocks: [{ kind: "text", value }] };
+}
+
+/** Text blocks + `@label` per mention — human-readable / model-visible prose. */
+export function toDisplayText(doc: ComposerDocument): string {
+  return doc.blocks
+    .map((b) =>
+      b.kind === "text" ? b.value : `${MENTION_DISPLAY_PREFIX}${b.ref.label}`
+    )
+    .join("");
+}
+
+/**
+ * Text blocks + `` per mention — the internal caret/trigger index space for
+ * reusing `parseMentionTrigger`. Never shown to the user, never sent to the model.
+ */
+export function toLogicalText(doc: ComposerDocument): string {
+  return doc.blocks
+    .map((b) => (b.kind === "text" ? b.value : MENTION_PLACEHOLDER))
+    .join("");
+}
+
+/** Total logical length of the document. */
+export function logicalLength(doc: ComposerDocument): number {
+  return doc.blocks.reduce((sum, b) => sum + blockLength(b), 0);
+}
+
+/** Mention blocks in document order (source of submit `contextMentions`). */
+export function mentionBlocksInOrder(
+  doc: ComposerDocument
+): Array<{ id: ComposerMentionId; ref: AgentWidgetContextMentionRef }> {
+  const out: Array<{ id: ComposerMentionId; ref: AgentWidgetContextMentionRef }> =
+    [];
+  for (const b of doc.blocks) {
+    if (b.kind === "mention") out.push({ id: b.id, ref: b.ref });
+  }
+  return out;
+}
+
+/**
+ * Split `blocks` at a single logical offset, returning the blocks fully to the
+ * left of `cut` and the blocks fully to the right (text blocks that straddle the
+ * cut are sliced). Mention blocks (one logical char) never straddle in practice;
+ * a defensive cut inside one keeps the whole token on the right.
+ */
+function splitBlocksAt(
+  blocks: ComposerBlock[],
+  cut: number
+): { left: ComposerBlock[]; right: ComposerBlock[] } {
+  const left: ComposerBlock[] = [];
+  const right: ComposerBlock[] = [];
+  let offset = 0;
+  for (const block of blocks) {
+    const len = blockLength(block);
+    const end = offset + len;
+    if (end <= cut) {
+      left.push(block);
+    } else if (offset >= cut) {
+      right.push(block);
+    } else if (block.kind === "text") {
+      const at = cut - offset;
+      if (at > 0) left.push({ kind: "text", value: block.value.slice(0, at) });
+      if (at < len) right.push({ kind: "text", value: block.value.slice(at) });
+    } else {
+      right.push(block);
+    }
+    offset = end;
+  }
+  return { left, right };
+}
+
+/**
+ * Replace the logical range `[range.start, range.end)` (the active `@query`,
+ * trigger char through caret) with an atomic mention block for `ref`, keyed by
+ * the caller-supplied `id`. A separating space follows the token (Slack-style)
+ * unless the next char already is one, so typing and `@`-chaining continue
+ * without a manual spacebar press; the returned caret sits after that space.
+ * The caller owns id creation so this stays pure.
+ */
+export function insertMention(
+  doc: ComposerDocument,
+  range: LogicalRange,
+  ref: AgentWidgetContextMentionRef,
+  id: ComposerMentionId
+): { doc: ComposerDocument; caret: number } {
+  const before = splitBlocksAt(doc.blocks, range.start).left;
+  const after = splitBlocksAt(doc.blocks, range.end).right;
+  const next = after[0];
+  const nextChar = next?.kind === "text" ? next.value.charAt(0) : "";
+  // A following newline already separates; keep the caret on the token's line.
+  const needsSpace = nextChar !== " " && nextChar !== "\t" && nextChar !== "\n";
+  const blocks = normalizeBlocks([
+    ...before,
+    { kind: "mention", id, ref },
+    ...(needsSpace ? [{ kind: "text", value: " " } as const] : []),
+    ...after
+  ]);
+  // `before` spans exactly logical `[0, range.start)`; the token adds one char,
+  // and the caret hops the separator (inserted or pre-existing space/tab).
+  const caret = range.start + 1 + (nextChar === "\n" ? 0 : 1);
+  return { doc: { blocks }, caret };
+}
+
+/**
+ * Drop the mention block with `id` and merge the surrounding text. Returns the
+ * new document and the caret offset where the token used to be. No-op (same doc)
+ * when the id is absent — the caret then points at end of document.
+ */
+export function removeMention(
+  doc: ComposerDocument,
+  id: ComposerMentionId
+): { doc: ComposerDocument; caret: number } {
+  let caret = 0;
+  let offset = 0;
+  let found = false;
+  for (const block of doc.blocks) {
+    if (block.kind === "mention" && block.id === id) {
+      caret = offset;
+      found = true;
+    }
+    offset += blockLength(block);
+  }
+  if (!found) return { doc, caret: offset };
+  const blocks = normalizeBlocks(
+    doc.blocks.filter((b) => !(b.kind === "mention" && b.id === id))
+  );
+  return { doc: { blocks }, caret };
+}
+
+/**
+ * Replace the logical range `[start, end)` with plain `text`, preserving every
+ * mention token that lies OUTSIDE the range and dropping any that fall inside it.
+ * Returns the new document and the caret offset just after the inserted text.
+ *
+ * This is the general logical-range edit the DOM adapter needs whenever a native
+ * edit can't be trusted to keep tokens atomic — paste over a selection, and
+ * slash-command completion that rewrites a `/query` span while other tokens sit
+ * elsewhere in the line. `start`/`end` are clamped and ordered defensively.
+ */
+export function spliceDocument(
+  doc: ComposerDocument,
+  start: number,
+  end: number,
+  text: string
+): { doc: ComposerDocument; caret: number } {
+  const total = logicalLength(doc);
+  const lo = Math.max(0, Math.min(start, end, total));
+  const hi = Math.min(total, Math.max(start, end, 0));
+  const before = splitBlocksAt(doc.blocks, lo).left;
+  const after = splitBlocksAt(doc.blocks, hi).right;
+  const blocks = normalizeBlocks([
+    ...before,
+    { kind: "text", value: text },
+    ...after
+  ]);
+  return { doc: { blocks }, caret: lo + text.length };
+}
+
+/**
+ * Produce the display/transcript fields a sent inline-mode message carries.
+ * `content` is the human-readable prose (`@label` tokens inline); `contextMentions`
+ * are the refs in document order; `contentSegments` is the full block list with
+ * empty text runs dropped for a clean transcript. The model-visible channel
+ * (`llmContent`/`contentParts`) is assembled separately by the manager bundle and
+ * `session.applyMentionBundle` — this function does not touch it.
+ */
+export function documentToMessageFields(doc: ComposerDocument): {
+  content: string;
+  contextMentions: AgentWidgetContextMentionRef[];
+  contentSegments: AgentWidgetContentSegment[];
+} {
+  const contentSegments: AgentWidgetContentSegment[] = [];
+  for (const block of doc.blocks) {
+    if (block.kind === "text") {
+      if (block.value.length > 0) {
+        contentSegments.push({ kind: "text", text: block.value });
+      }
+    } else {
+      contentSegments.push({ kind: "mention", ref: block.ref });
+    }
+  }
+  return {
+    content: toDisplayText(doc),
+    contextMentions: mentionBlocksInOrder(doc).map((m) => m.ref),
+    contentSegments
+  };
+}

package/src/utils/composer-history.test.ts

@@ -2,16 +2,17 @@ import { describe, it, expect } from "vitest";
 import {
   navigateComposerHistory,
   INITIAL_HISTORY_STATE,
-  type ComposerHistoryState
+  type ComposerHistoryState,
+  type ComposerHistoryInput
 } from "./composer-history";
 
 const history = ["first", "second", "third"]; // oldest -> newest
 
 const up = (
   state: ComposerHistoryState,
-  overrides: Partial<Parameters<typeof navigateComposerHistory>[0]> = {}
+  overrides: Partial<ComposerHistoryInput<string>> = {}
 ) =>
-  navigateComposerHistory({
+  navigateComposerHistory<string>({
     direction: "up",
     history,
     currentValue: "",
@@ -22,9 +23,9 @@ const up = (
 
 const down = (
   state: ComposerHistoryState,
-  overrides: Partial<Parameters<typeof navigateComposerHistory>[0]> = {}
+  overrides: Partial<ComposerHistoryInput<string>> = {}
 ) =>
-  navigateComposerHistory({
+  navigateComposerHistory<string>({
     direction: "down",
     history,
     currentValue: "",
@@ -93,7 +94,7 @@ describe("navigateComposerHistory", () => {
     const result = down(state);
     expect(result.handled).toBe(true);
     expect(result.value).toBe("saved draft");
-    expect(result.state).toEqual(INITIAL_HISTORY_STATE);
+    expect(result.state.index).toBe(-1); // not navigating
   });
 
   it("Down does nothing when not navigating history", () => {
@@ -123,6 +124,33 @@ describe("navigateComposerHistory", () => {
 
     const d1 = down(state); // back past newest -> restore draft
     expect(d1.value).toBe(draft);
-    expect(d1.state).toEqual(INITIAL_HISTORY_STATE);
+    expect(d1.state.index).toBe(-1);
+  });
+
+  it("is generic over the entry type (documents, not just strings)", () => {
+    // Inline mode recalls ComposerDocument-shaped entries; the machine only
+    // indexes and swaps, so any entry type round-trips.
+    type Doc = { blocks: string[] };
+    const docs: Doc[] = [{ blocks: ["a"] }, { blocks: ["b"] }];
+    const draft: Doc = { blocks: ["draft"] };
+    const u = navigateComposerHistory<Doc>({
+      direction: "up",
+      history: docs,
+      currentValue: draft,
+      atStart: true,
+      state: { index: -1, draft }
+    });
+    expect(u.value).toEqual({ blocks: ["b"] }); // newest
+    expect(u.state).toEqual({ index: 1, draft });
+
+    const d = navigateComposerHistory<Doc>({
+      direction: "down",
+      history: docs,
+      currentValue: draft,
+      atStart: true,
+      state: u.state
+    });
+    expect(d.value).toEqual(draft); // restored draft
+    expect(d.state.index).toBe(-1);
   });
 });