@cueloop/client 0.1.0-alpha.76 → 0.1.0-alpha.78

package/src/diff-intraline.ts

@@ -36,16 +36,16 @@ function stripTrailingNewline(text: string): string {
   return text.replace(/\n$/, "");
 }
 
-/**
- * Char-precise intra-line runs for modified diff rows. Within a change block - a
- * run of deletions immediately followed by additions - lines are aligned to their
- * real counterpart (see alignedPairs) and each matched pair is word-diffed so the
- * removed/added words are marked changed. Rows with no counterpart (pure add, pure
- * delete, or an unmatched line in a shifted block) are omitted, so the caller
- * renders those as a single run. Each row's runs concatenate back to that row's text.
- */
-export function intralineRunsByRow(rows: DiffRow[]): Map<number, IntralineRun[]> {
-  const runsByRow = new Map<number, IntralineRun[]>();
+/** A change block: a run of deletion rows immediately followed by addition rows. */
+interface IntralineBlock {
+  deletionStart: number;
+  additionStart: number;
+  end: number;
+}
+
+/** The change blocks in row order, found in one cheap pass (no word diff yet). */
+function intralineBlocks(rows: DiffRow[]): IntralineBlock[] {
+  const blocks: IntralineBlock[] = [];
   let index = 0;
 
   while (index < rows.length) {
@@ -59,22 +59,91 @@ export function intralineRunsByRow(rows: DiffRow[]): Map<number, IntralineRun[]>
     const additionStart = index;
 
     while (index < rows.length && rows[index]!.kind === "add") index++;
-    const deletionTexts = rows
-      .slice(deletionStart, additionStart)
-      .map((row) => stripTrailingNewline(row.text));
-    const additionTexts = rows
-      .slice(additionStart, index)
-      .map((row) => stripTrailingNewline(row.text));
-
-    for (const [deletionOffset, additionOffset] of alignedPairs(deletionTexts, additionTexts)) {
-      const changes = wordLevelChanges(
-        deletionTexts[deletionOffset]!,
-        additionTexts[additionOffset]!,
-      );
-
-      runsByRow.set(deletionStart + deletionOffset, sideRuns(changes, "removed"));
-      runsByRow.set(additionStart + additionOffset, sideRuns(changes, "added"));
-    }
+    blocks.push({ deletionStart, additionStart, end: index });
+  }
+
+  return blocks;
+}
+
+/** Word-diff one change block into [rowIndex, runs] pairs; unmatched rows get no entry. */
+function blockRunEntries(rows: DiffRow[], block: IntralineBlock): Array<[number, IntralineRun[]]> {
+  const deletionTexts = rows
+    .slice(block.deletionStart, block.additionStart)
+    .map((row) => stripTrailingNewline(row.text));
+  const additionTexts = rows
+    .slice(block.additionStart, block.end)
+    .map((row) => stripTrailingNewline(row.text));
+  const entries: Array<[number, IntralineRun[]]> = [];
+
+  for (const [deletionOffset, additionOffset] of alignedPairs(deletionTexts, additionTexts)) {
+    const changes = wordLevelChanges(
+      deletionTexts[deletionOffset]!,
+      additionTexts[additionOffset]!,
+    );
+
+    entries.push([block.deletionStart + deletionOffset, sideRuns(changes, "removed")]);
+    entries.push([block.additionStart + additionOffset, sideRuns(changes, "added")]);
+  }
+
+  return entries;
+}
+
+/** The change block whose rows cover `rowIndex`, by binary search over the ordered blocks. */
+function blockContaining(blocks: IntralineBlock[], rowIndex: number): number | undefined {
+  let low = 0;
+  let high = blocks.length - 1;
+
+  while (low <= high) {
+    const mid = (low + high) >> 1;
+    const block = blocks[mid]!;
+
+    if (rowIndex < block.deletionStart) high = mid - 1;
+    else if (rowIndex >= block.end) low = mid + 1;
+    else return mid;
+  }
+
+  return undefined;
+}
+
+/** A row's intra-line runs, resolved on demand. */
+export interface IntralineResolver {
+  runsForRow(rowIndex: number): IntralineRun[] | undefined;
+}
+
+/**
+ * Char-precise intra-line runs for modified diff rows, computed lazily. The change blocks are found
+ * up front in one cheap pass; a block is word-diffed only when a row inside it is first asked for,
+ * so a virtualized diff pays for the rows on screen, not for the whole file. Within a change block -
+ * deletions immediately followed by additions - lines align to their real counterpart (alignedPairs)
+ * and each matched pair is word-diffed; unmatched rows get no runs, so the caller renders those whole.
+ */
+export function createIntralineResolver(rows: DiffRow[]): IntralineResolver {
+  const blocks = intralineBlocks(rows);
+  const computed = new Set<number>();
+  const runsByRow = new Map<number, IntralineRun[]>();
+
+  return {
+    runsForRow(rowIndex) {
+      const blockIndex = blockContaining(blocks, rowIndex);
+
+      if (blockIndex === undefined) return undefined;
+      if (!computed.has(blockIndex)) {
+        computed.add(blockIndex);
+        for (const [row, runs] of blockRunEntries(rows, blocks[blockIndex]!))
+          runsByRow.set(row, runs);
+      }
+
+      return runsByRow.get(rowIndex);
+    },
+  };
+}
+
+/** Every modified row's intra-line runs, eagerly. Prefer createIntralineResolver on a hot path. */
+export function intralineRunsByRow(rows: DiffRow[]): Map<number, IntralineRun[]> {
+  const runsByRow = new Map<number, IntralineRun[]>();
+
+  for (const block of intralineBlocks(rows)) {
+    for (const [row, runs] of blockRunEntries(rows, block)) runsByRow.set(row, runs);
   }
 
   return runsByRow;

package/src/github-identity.test.ts

@@ -0,0 +1,58 @@
+import { afterEach, expect, test } from "bun:test";
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { resolveGithubIdentity } from "./github-identity";
+
+const originalBinary = process.env.CUELOOP_GH;
+const tempDirectories: string[] = [];
+
+afterEach(() => {
+  if (originalBinary === undefined) delete process.env.CUELOOP_GH;
+  else process.env.CUELOOP_GH = originalBinary;
+  for (const directory of tempDirectories.splice(0)) {
+    rmSync(directory, { recursive: true, force: true });
+  }
+});
+
+function stubGithubCli(script: string): string {
+  const directory = mkdtempSync(join(tmpdir(), "gh-stub-"));
+
+  tempDirectories.push(directory);
+  const path = join(directory, "gh");
+
+  writeFileSync(path, `#!/bin/sh\n${script}\n`);
+  chmodSync(path, 0o755);
+
+  return path;
+}
+
+test("reads the GitHub login and name from gh", async () => {
+  process.env.CUELOOP_GH = stubGithubCli(`printf '{"login":"markus","name":"Markus M"}'`);
+
+  expect(await resolveGithubIdentity()).toEqual({ login: "markus", name: "Markus M" });
+});
+
+test("drops a null name to undefined", async () => {
+  process.env.CUELOOP_GH = stubGithubCli(`printf '{"login":"markus","name":null}'`);
+
+  expect(await resolveGithubIdentity()).toEqual({ login: "markus" });
+});
+
+test("falls back to null when gh exits non-zero (logged out)", async () => {
+  process.env.CUELOOP_GH = stubGithubCli(`exit 1`);
+
+  expect(await resolveGithubIdentity()).toBeNull();
+});
+
+test("falls back to null when gh is not installed", async () => {
+  process.env.CUELOOP_GH = join(tmpdir(), "cueloop-absent-gh-binary");
+
+  expect(await resolveGithubIdentity()).toBeNull();
+});
+
+test("falls back to null when gh prints an unexpected shape", async () => {
+  process.env.CUELOOP_GH = stubGithubCli(`printf 'not json'`);
+
+  expect(await resolveGithubIdentity()).toBeNull();
+});

package/src/github-identity.ts

@@ -0,0 +1,41 @@
+/** The signed-in GitHub identity from the local gh tool, or null when gh cannot answer. */
+
+import * as v from "valibot";
+
+export interface GithubIdentity {
+  login: string;
+  name?: string;
+}
+
+const GithubUserSchema = v.object({
+  login: v.string(),
+  name: v.nullish(v.string()),
+});
+
+/** The gh binary is injectable so tests stub it without a real GitHub login. */
+function githubCliBinary(): string {
+  return process.env.CUELOOP_GH || "gh";
+}
+
+/** Read the authenticated GitHub login and name, or null when gh cannot answer. */
+export async function resolveGithubIdentity(): Promise<GithubIdentity | null> {
+  try {
+    const githubProcess = Bun.spawn(
+      [githubCliBinary(), "api", "user", "--jq", "{login: .login, name: .name}"],
+      { stdout: "pipe", stderr: "ignore" },
+    );
+    const [output, exitCode] = await Promise.all([
+      new Response(githubProcess.stdout).text(),
+      githubProcess.exited,
+    ]);
+
+    if (exitCode !== 0) return null;
+    const parsed = v.safeParse(GithubUserSchema, JSON.parse(output));
+
+    if (!parsed.success) return null;
+
+    return { login: parsed.output.login, name: parsed.output.name ?? undefined };
+  } catch {
+    return null;
+  }
+}

package/src/intent-dispatch.test.ts

@@ -108,6 +108,7 @@ function baseController(): ReviewController {
     walkLeave: mock(),
     submit: mock(),
     share: mock(),
+    setShareAccess: mock(),
     treeRows: mock(() => []),
     goToEntry: mock(),
     branch: mock(),
@@ -143,6 +144,7 @@ function makeDeps(overrides: Partial<IntentDispatchDeps> = {}): IntentDispatchDe
     quickActions: [],
     renameAuthor: mock(),
     renameThread: mock(),
+    setLocalIdentityName: mock(),
     liveInput: { current: "" },
     setCursor: mock(),
     setInboxCursor: mock(),
@@ -383,7 +385,7 @@ describe("openSubmit", () => {
 });
 
 describe("share", () => {
-  test("dispatches to the controller's share", () => {
+  test("opens the public/private choice overlay instead of publishing directly", () => {
     // Arrange
     const deps = makeDeps();
     const dispatch = createIntentDispatch(deps);
@@ -392,7 +394,8 @@ describe("share", () => {
     dispatch({ type: "share" });
 
     // Assert
-    expect(deps.controller.share).toHaveBeenCalled();
+    expect(deps.setMode).toHaveBeenCalledWith({ type: "shareChoice", index: 0 });
+    expect(deps.controller.share).not.toHaveBeenCalled();
   });
 });
 
@@ -547,6 +550,18 @@ describe("rename author", () => {
     expect(deps.renameAuthor).toHaveBeenCalledWith("SHA256:x", "Alex");
     expect(deps.setMode).toHaveBeenCalledWith({ type: "normal" });
   });
+
+  test("confirmDialog in renameSelf mode sets the trimmed local identity name and closes", () => {
+    // Arrange
+    const deps = makeDeps({ mode: { type: "renameSelf", text: "  Robin  " } });
+
+    // Act
+    createIntentDispatch(deps)({ type: "confirmDialog" });
+
+    // Assert
+    expect(deps.setLocalIdentityName).toHaveBeenCalledWith("Robin");
+    expect(deps.setMode).toHaveBeenCalledWith({ type: "normal" });
+  });
 });
 
 describe("collaborator self-name", () => {

package/src/intent-dispatch.ts

@@ -39,6 +39,8 @@ export type Mode =
   | { type: "rename"; authorId: string; text: string }
   | { type: "renameThread"; sessionId: string; text: string }
   | { type: "nameSelf"; text: string }
+  | { type: "renameSelf"; text: string }
+  | { type: "shareChoice"; index: number }
   | { type: "treePrompt"; ask: TreeAsk; entryId?: string; text: string };
 
 /** What a tree prompt asks for: a branch name, a checkpoint name, or the summary a move back leaves. */
@@ -98,6 +100,8 @@ export interface IntentDispatchDeps {
   renameAuthor: (id: string, name: string) => void;
   /** Rename a thread's title through the daemon. */
   renameThread: (id: string, title: string) => void;
+  /** Set the local reviewer's typed display name and persist it (App-owned). */
+  setLocalIdentityName: (name: string) => void;
 
   liveInput: MutableRefObject<string>;
 
@@ -238,6 +242,7 @@ function handleConfirmDialog(
   else if (mode.type === "rename") deps.renameAuthor(mode.authorId, mode.text.trim());
   else if (mode.type === "renameThread") deps.renameThread(mode.sessionId, mode.text.trim());
   else if (mode.type === "nameSelf") controller.setSelfName(mode.text.trim());
+  else if (mode.type === "renameSelf") deps.setLocalIdentityName(mode.text.trim());
   else if (mode.type === "treePrompt") confirmTreePrompt(mode, deps);
   deps.setMode({ type: "normal" });
 }
@@ -381,8 +386,9 @@ function handleOpenSubmit(_intent: IntentOfType<"openSubmit">, deps: IntentDispa
   deps.setMode({ type: "submit", verdict: defaultVerdict(session), summary: "" });
 }
 
+// share opens the public/private choice overlay; the App owns the choice keys and publishes on pick
 function handleShare(_intent: IntentOfType<"share">, deps: IntentDispatchDeps): void {
-  deps.controller.share();
+  deps.setMode({ type: "shareChoice", index: 0 });
 }
 
 function handleCut(_intent: IntentOfType<"cut">, deps: IntentDispatchDeps): void {

package/src/keymap.test.ts

@@ -59,8 +59,8 @@ describe("submit overlay", () => {
   const keyState = state({ overlay: "submit" });
   const table: [string, Intent[]][] = [
     ["escape", [{ type: "closeOverlay" }]],
-    ["return", [{ type: "submitVerdict" }]],
-    ["enter", [{ type: "submitVerdict" }]],
+    ["return", []],
+    ["enter", []],
     ["left", [{ type: "cycleVerdict", direction: -1 }]],
     ["right", [{ type: "cycleVerdict", direction: 1 }]],
     ["j", []],

package/src/keymap.ts

@@ -87,6 +87,7 @@ export interface KeyState {
     | "submit"
     | "confirm"
     | "prompt"
+    | "shareChoice"
     | "spanActions"
     | "completion-prompt"
     | "completion-counting";
@@ -192,7 +193,6 @@ function submitOverlayGrammar(state: KeyState, key: KeyInput): Intent[] {
   const name = key.name;
 
   if (name === "escape") return [{ type: "closeOverlay" }];
-  if (name === "return" || name === "enter") return [{ type: "submitVerdict" }];
   if (name === "left" || name === "right") {
     return [{ type: "cycleVerdict", direction: name === "left" ? -1 : 1 }];
   }

package/src/pasted-image.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, test } from "bun:test";
+import { imagePlaceholder, looksLikeBinaryPaste } from "./pasted-image";
+
+function bytesOf(...values: number[]): Uint8Array {
+  return Uint8Array.from(values);
+}
+
+describe("looksLikeBinaryPaste", () => {
+  test("plain text pastes stay text", () => {
+    expect(looksLikeBinaryPaste(new TextEncoder().encode("just a normal comment"))).toBe(false);
+  });
+
+  test("multi-line text with tabs and newlines stays text", () => {
+    expect(
+      looksLikeBinaryPaste(new TextEncoder().encode("line one\n\tline two\r\nline three")),
+    ).toBe(false);
+  });
+
+  test("unicode text stays text", () => {
+    expect(looksLikeBinaryPaste(new TextEncoder().encode("café — naïve — 日本語 — 🎉"))).toBe(
+      false,
+    );
+  });
+
+  test("a PNG signature is binary", () => {
+    expect(looksLikeBinaryPaste(bytesOf(0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a))).toBe(
+      true,
+    );
+  });
+
+  test("a JPEG signature is binary", () => {
+    expect(looksLikeBinaryPaste(bytesOf(0xff, 0xd8, 0xff, 0xe0, 0x00, 0x10))).toBe(true);
+  });
+
+  test("a GIF signature is binary", () => {
+    expect(looksLikeBinaryPaste(new TextEncoder().encode("GIF89a\x01\x02"))).toBe(true);
+  });
+
+  test("a WEBP signature is binary", () => {
+    expect(
+      looksLikeBinaryPaste(bytesOf(0x52, 0x49, 0x46, 0x46, 1, 2, 3, 4, 0x57, 0x45, 0x42, 0x50)),
+    ).toBe(true);
+  });
+
+  test("a NUL byte marks binary", () => {
+    expect(looksLikeBinaryPaste(bytesOf(0x68, 0x69, 0x00, 0x74, 0x68, 0x65, 0x72, 0x65))).toBe(
+      true,
+    );
+  });
+
+  test("a burst of control bytes marks binary", () => {
+    expect(looksLikeBinaryPaste(bytesOf(0x01, 0x02, 0x03, 0x04, 0x05, 0x06, 0x07, 0x08))).toBe(
+      true,
+    );
+  });
+
+  test("an empty paste is not binary", () => {
+    expect(looksLikeBinaryPaste(new Uint8Array())).toBe(false);
+  });
+});
+
+describe("imagePlaceholder", () => {
+  test("numbers each pasted image", () => {
+    expect(imagePlaceholder(1)).toBe("[Image #1]");
+    expect(imagePlaceholder(2)).toBe("[Image #2]");
+  });
+});

package/src/pasted-image.ts

@@ -0,0 +1,60 @@
+/** Detects an image or other binary paste so a composer shows an [Image #n] placeholder instead of dumping raw bytes into the draft. */
+
+const IMAGE_MAGIC_SIGNATURES: number[][] = [
+  [0x89, 0x50, 0x4e, 0x47], // PNG
+  [0xff, 0xd8, 0xff], // JPEG
+  [0x47, 0x49, 0x46, 0x38], // GIF87a / GIF89a
+];
+
+const CONTROL_RATIO_THRESHOLD = 0.15;
+const PASTE_DECODER = new TextDecoder("utf-8", { fatal: false });
+
+function hasImageMagic(bytes: Uint8Array): boolean {
+  for (const signature of IMAGE_MAGIC_SIGNATURES) {
+    if (signature.every((byte, index) => bytes[index] === byte)) return true;
+  }
+
+  const isRiffWebp =
+    bytes.length >= 12 &&
+    bytes[0] === 0x52 && // R
+    bytes[1] === 0x49 && // I
+    bytes[2] === 0x46 && // F
+    bytes[3] === 0x46 && // F
+    bytes[8] === 0x57 && // W
+    bytes[9] === 0x45 && // E
+    bytes[10] === 0x42 && // B
+    bytes[11] === 0x50; // P
+
+  return isRiffWebp;
+}
+
+function isControlCodePoint(codePoint: number): boolean {
+  if (codePoint === 0x09 || codePoint === 0x0a || codePoint === 0x0d) return false;
+
+  return codePoint < 0x20 || codePoint === 0x7f;
+}
+
+/** True when a paste is an image or other non-text binary payload and should collapse to a placeholder. */
+export function looksLikeBinaryPaste(bytes: Uint8Array): boolean {
+  if (bytes.length === 0) return false;
+  if (hasImageMagic(bytes)) return true;
+
+  const decoded = PASTE_DECODER.decode(bytes);
+  let controlCount = 0;
+  let total = 0;
+
+  for (const character of decoded) {
+    total += 1;
+    const codePoint = character.codePointAt(0) ?? 0;
+
+    if (codePoint === 0 || codePoint === 0xfffd) return true;
+    if (isControlCodePoint(codePoint)) controlCount += 1;
+  }
+
+  return total > 0 && controlCount / total > CONTROL_RATIO_THRESHOLD;
+}
+
+/** The draft placeholder for the nth image pasted into a composer: [Image #1], [Image #2], … */
+export function imagePlaceholder(index: number): string {
+  return `[Image #${index}]`;
+}

package/src/run.ts

@@ -4,6 +4,7 @@ import React from "react";
 import { createCliRenderer } from "@opentui/core";
 import { createRoot } from "@opentui/react";
 import { App } from "./App";
+import type { Appearance } from "./theme-presets";
 import { loadConfig } from "./config";
 import { perfMark } from "./perf/perf-timings";
 import { reportPerfMarks } from "./perf/perf-report";
@@ -38,12 +39,6 @@ export async function runClient(options: RunClientOptions): Promise<number> {
     renderer.useMouse = false;
     renderer.useMouse = true;
   });
-  // block first paint on the theme query only briefly, so an answering terminal paints its real theme
-  // with no flash while a non-answering one falls back to dark within the budget
-  const appearance =
-    (await renderer.waitForThemeMode(THEME_QUERY_TIMEOUT_MS).catch(() => null)) ?? "dark";
-  perfMark("themeQuery");
-
   return new Promise<number>((resolve) => {
     let exited = false;
     const shutdown = (code: number): void => {
@@ -61,19 +56,36 @@ export async function runClient(options: RunClientOptions): Promise<number> {
     process.once("SIGHUP", () => shutdown(0));
     process.once("SIGTERM", () => shutdown(0));
 
-    createRoot(renderer).render(
-      React.createElement(App, {
-        home: options.home,
-        sessionId: options.sessionId,
-        appearance,
-        layout,
-        onExit: shutdown,
-        onReady: () => {
-          perfMark("firstFrame");
-          reportPerfMarks("startup");
-        },
-      }),
-    );
+    const root = createRoot(renderer);
+    const renderApp = (appearance: Appearance): void => {
+      root.render(
+        React.createElement(App, {
+          home: options.home,
+          sessionId: options.sessionId,
+          appearance,
+          layout,
+          onExit: shutdown,
+          onReady: () => {
+            perfMark("firstFrame");
+            reportPerfMarks("startup");
+          },
+        }),
+      );
+    };
+
+    // Paint immediately with the default appearance; the OSC theme query resolves off the
+    // first-paint path and upgrades the theme in place when the terminal answers, so launch
+    // never blocks on it. A non-answering terminal simply stays dark.
+    renderApp("dark");
     perfMark("render");
+
+    void renderer
+      .waitForThemeMode(THEME_QUERY_TIMEOUT_MS)
+      .then((mode) => {
+        perfMark("themeQuery");
+        // the query can answer after a fast quit; never render onto a destroyed renderer
+        if (!exited && mode && mode !== "dark") renderApp(mode);
+      })
+      .catch(() => {});
   });
 }

package/src/serve.ts

@@ -1,6 +1,6 @@
 /**
  * SSH-served TUI: `cueloop serve` lets teammates join a
- * review session over plain ssh. Every SSH connection renders <App> in
+ * thread over plain ssh. Every SSH connection renders <App> in
  * observer mode (readOnly) against the same local daemon; the one writable
  * controller stays the local owner's own `cueloop` TUI.
  *

package/src/share.ts

@@ -1,5 +1,5 @@
 /**
- * Publish a review session as a share: pack it, stream it to the gateway's
+ * Publish a thread as a share: pack it, stream it to the gateway's
  * `share` user over SSH, and copy the returned `ssh p_…@host` line to the
  * clipboard. The planner holds no key, so all this side does is upload; the
  * gateway seals and stores. Used by both `cueloop share` and the in-TUI
@@ -12,7 +12,13 @@ import {
   SHARE_UPLOAD_USER,
   packSessionBlob,
 } from "@cueloop/daemon/share-blob";
-import { removalEntries, viewFollowing, type Annotation, type Thread } from "@cueloop/schema";
+import {
+  removalEntries,
+  viewFollowing,
+  type Annotation,
+  type ShareAccess,
+  type Thread,
+} from "@cueloop/schema";
 import { ThreadRecordSchema } from "@cueloop/daemon/validate";
 import type { SharedMerge } from "@cueloop/daemon/client";
 import * as v from "valibot";
@@ -102,11 +108,13 @@ export function mergeFromShare(remote: Thread): SharedMerge {
 export async function pushShare(
   shareId: string,
   annotations: Array<Omit<Annotation, "createdAt">>,
+  access?: ShareAccess,
   target: ShareTarget = {},
 ): Promise<void> {
+  const payload = access ? { shareId, annotations, access } : { shareId, annotations };
   const { stderr, code } = await runShareSsh(
     "cueloop-push",
-    Buffer.from(JSON.stringify({ shareId, annotations })),
+    Buffer.from(JSON.stringify(payload)),
     target,
   );
 

package/src/slash-palette.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import {
   activeSlashToken,
+  insertSlashItem,
   isStandaloneSlashQuery,
   scoreMatch,
   slashFilter,
@@ -84,3 +85,19 @@ describe("isStandaloneSlashQuery", () => {
     expect(isStandaloneSlashQuery("just prose")).toBe(false);
   });
 });
+
+describe("insertSlashItem", () => {
+  test("replaces the active slash token with the reference and lands the caret after it", () => {
+    const result = insertSlashItem("look at /rev", 12, "review");
+
+    expect(result.text).toBe("look at /review ");
+    expect(result.caret).toBe("look at /review ".length);
+  });
+
+  test("keeps text after the caret intact", () => {
+    const result = insertSlashItem("/pl tail", 3, "plan");
+
+    expect(result.text).toBe("/plan  tail");
+    expect(result.caret).toBe("/plan ".length);
+  });
+});

package/src/slash-palette.ts

@@ -86,6 +86,17 @@ export function isStandaloneSlashQuery(text: string): boolean {
   return /^\/\S*$/.test(text.trim());
 }
 
+export function insertSlashItem(text: string, caret: number, itemName: string) {
+  const token = activeSlashToken(text, caret) ?? "";
+  const cut = caret - token.length;
+  const insertion = `/${itemName} `;
+
+  return {
+    text: text.slice(0, cut) + insertion + text.slice(caret),
+    caret: cut + insertion.length,
+  };
+}
+
 /**
  * The character ranges of every completed "/name" in the draft that names a real
  * action or skill, so a surface can paint the references. A half-typed "/na" is

package/src/thread-controller.curate.test.ts

@@ -109,6 +109,7 @@ function fakeClient(initial: Thread, sink: WorkingCopySink): SessionClient {
 
       return session;
     }),
+    sessionSetAccess: unimplemented("sessionSetAccess"),
     sessionNavigate: unimplemented("sessionNavigate"),
     sessionBranch: unimplemented("sessionBranch"),
     sessionSwitch: unimplemented("sessionSwitch"),