@cueloop/client 0.1.0-alpha.2 → 0.1.0-alpha.20

package/src/components/story.ts

@@ -0,0 +1,66 @@
+/**
+ * The story contract. Every component file in components/ ships a
+ * colocated *.stories.tsx that exports `meta` plus named Story objects.
+ * The catalog IS the regression suite: stories.test.tsx walks every story,
+ * snapshots its char frame, and asserts declared colors against the styled
+ * spans; the `bun run stories` TUI renders the same objects interactively.
+ */
+
+import type React from "react";
+
+export interface StoryMeta {
+  /** Catalog path, e.g. "primitives/Card". */
+  title: string;
+}
+
+export interface Story {
+  render: () => React.ReactNode;
+  /**
+   * Colors (hex tokens) that must appear among the rendered frame's styled
+   * spans - the color regression net for color-bearing stories.
+   */
+  expectedColors?: string[];
+  /** Virtual terminal size; defaults to 80x24. */
+  size?: { width: number; height: number };
+}
+
+export interface LoadedStory {
+  moduleTitle: string;
+  storyName: string;
+  story: Story;
+}
+
+export function isStory(value: unknown): value is Story {
+  return typeof value === "object" && value !== null && typeof (value as Story).render === "function";
+}
+
+/** Import every *.stories.tsx next to the components and flatten the exports. */
+export async function loadStories(): Promise<LoadedStory[]> {
+  const glob = new Bun.Glob("**/*.stories.tsx");
+  const files = [...glob.scanSync({ cwd: import.meta.dir })].sort();
+  const loaded: LoadedStory[] = [];
+  for (const file of files) {
+    const moduleExports = (await import(`${import.meta.dir}/${file}`)) as Record<string, unknown>;
+    const meta = moduleExports["meta"] as StoryMeta | undefined;
+    const moduleTitle = meta?.title ?? file.replace(/\.stories\.tsx$/, "");
+    for (const [exportName, exported] of Object.entries(moduleExports)) {
+      if (exportName === "meta" || !isStory(exported)) continue;
+      loaded.push({ moduleTitle, storyName: exportName, story: exported });
+    }
+  }
+  return loaded;
+}
+
+/** Component files that must carry stories: every .tsx that is not a story/test. */
+export function componentFilesMissingStories(): string[] {
+  const componentGlob = new Bun.Glob("**/*.tsx");
+  const files = [...componentGlob.scanSync({ cwd: import.meta.dir })];
+  const missing: string[] = [];
+  for (const file of files) {
+    if (file.endsWith(".stories.tsx") || file.endsWith(".test.tsx")) continue;
+    if (file === "stories-app.tsx") continue;
+    const storiesSibling = file.replace(/\.tsx$/, ".stories.tsx");
+    if (!files.includes(storiesSibling)) missing.push(file);
+  }
+  return missing;
+}

package/src/components/syntax-highlight.ts

@@ -0,0 +1,57 @@
+/**
+ * Code highlighting tokens: the theme's named tokens projected onto
+ * tree-sitter capture names for the native code renderable. One SyntaxStyle
+ * per theme object, cached, so every code block on screen shares a handle.
+ * Unknown languages simply render unstyled - highlighting is an enhancement,
+ * never a blocker.
+ */
+
+import { SyntaxStyle, infoStringToFiletype } from "@opentui/core";
+import type { Theme } from "../theme";
+
+/** Markdown fence info -> tree-sitter filetype, with the aliases we accept. */
+export function filetypeFor(language?: string): string | undefined {
+  const info = (language ?? "").toLowerCase();
+  if (!info) return undefined;
+  const aliases: Record<string, string> = {
+    ts: "typescript",
+    js: "javascript",
+    py: "python",
+    rb: "ruby",
+    rs: "rust",
+    sh: "bash",
+    shell: "bash",
+    zsh: "bash",
+    yml: "yaml",
+  };
+  return infoStringToFiletype(aliases[info] ?? info) ?? aliases[info] ?? info;
+}
+
+const syntaxStyleCache = new WeakMap<Theme, SyntaxStyle>();
+
+export function syntaxStyleFor(theme: Theme): SyntaxStyle {
+  const cached = syntaxStyleCache.get(theme);
+  if (cached) return cached;
+  const style = SyntaxStyle.fromStyles({
+    default: { fg: theme.textMuted },
+    comment: { fg: theme.textDim, italic: true },
+    string: { fg: theme.green },
+    number: { fg: theme.blue },
+    constant: { fg: theme.blue },
+    boolean: { fg: theme.blue },
+    keyword: { fg: theme.accent },
+    operator: { fg: theme.textDim },
+    punctuation: { fg: theme.textDim },
+    function: { fg: theme.text },
+    method: { fg: theme.text },
+    type: { fg: theme.blue },
+    constructor: { fg: theme.blue },
+    variable: { fg: theme.textMuted },
+    property: { fg: theme.textMuted },
+    parameter: { fg: theme.textMuted },
+    tag: { fg: theme.accent },
+    attribute: { fg: theme.blue },
+  });
+  syntaxStyleCache.set(theme, style);
+  return style;
+}

package/src/components/theme-context.stories.tsx

@@ -0,0 +1,41 @@
+import React from "react";
+import { DARK, type Theme } from "../theme";
+import type { Story, StoryMeta } from "./story";
+import { ThemeProvider } from "./theme-context";
+import { Card } from "./primitives/Card";
+
+export const meta: StoryMeta = { title: "theme-context" };
+
+/** A high-contrast variant to prove tokens flow through the provider. */
+const HIGH_CONTRAST: Theme = { ...DARK, accent: "#00ffff", elevated: "#000000", border: "#ffffff" };
+
+export const ContextDefault: Story = {
+  render: () => (
+    <Card title=" default dark theme " contentRows={1}>
+      <text>no provider needed</text>
+    </Card>
+  ),
+  expectedColors: [DARK.elevated],
+};
+
+export const ProviderSwap: Story = {
+  render: () => (
+    <ThemeProvider theme={HIGH_CONTRAST}>
+      <Card title=" provider theme " contentRows={1} borderColor={HIGH_CONTRAST.accent}>
+        <text>tokens come from the provider</text>
+      </Card>
+    </ThemeProvider>
+  ),
+  expectedColors: ["#00ffff", "#000000"],
+};
+
+export const PropOverride: Story = {
+  render: () => (
+    <ThemeProvider theme={DARK}>
+      <Card title=" prop-overridden theme " contentRows={1} theme={HIGH_CONTRAST} borderColor={HIGH_CONTRAST.accent}>
+        <text>the theme prop beats the context</text>
+      </Card>
+    </ThemeProvider>
+  ),
+  expectedColors: ["#00ffff"],
+};

package/src/components/theme-context.tsx

@@ -0,0 +1,30 @@
+/**
+ * Provider theming for the component system. The context default is the
+ * built-in dark theme, so embedding a component (or rendering a story) needs
+ * no provider at all. One ThemeProvider swap switches the live theme; every
+ * component also accepts an optional `theme` prop that overrides the context
+ * for explicit control. Components consume named tokens only - a hardcoded
+ * color inside components/ is a review rejection.
+ */
+
+import React, { createContext, useContext } from "react";
+import { DARK, type Theme } from "../theme";
+
+const ThemeContext = createContext<Theme>(DARK);
+
+export function ThemeProvider({ theme, children }: { theme: Theme; children: React.ReactNode }): React.ReactNode {
+  return <ThemeContext.Provider value={theme}>{children}</ThemeContext.Provider>;
+}
+
+export function useTheme(): Theme {
+  return useContext(ThemeContext);
+}
+
+/**
+ * Token resolution for a component: the explicit `theme` prop wins over the
+ * provider context, which defaults to the built-in dark theme.
+ */
+export function useComponentTheme(override?: Theme): Theme {
+  const contextTheme = useContext(ThemeContext);
+  return override ?? contextTheme;
+}

package/src/components/truncate-text.ts

@@ -0,0 +1,6 @@
+/** Truncate text to one line of at most maxLength characters, ellipsis-terminated. */
+
+export function truncateToSingleLine(value: string, maxLength: number): string {
+  const oneLine = value.replace(/\n/g, " ");
+  return oneLine.length > maxLength ? oneLine.slice(0, maxLength - 1) + "…" : oneLine;
+}

package/src/config.test.ts

@@ -7,9 +7,9 @@ import { DARK } from "./theme";
 
 describe("loadConfig", () => {
   test("defaults when no file exists", () => {
-    const c = loadConfig({ userConfigPath: "/nonexistent/config.toml" });
-    expect(c.keys["comment"]).toEqual(["c"]);
-    expect(c.theme.accent).toBe(DARK.accent);
+    const config = loadConfig({ userConfigPath: "/nonexistent/config.toml" });
+    expect(config.keys["comment"]).toEqual(["c"]);
+    expect(config.theme.accent).toBe(DARK.accent);
   });
 
   test("user config rebinds actions and overrides theme tokens", () => {
@@ -20,12 +20,12 @@ describe("loadConfig", () => {
       `[keys]\ncomment = "a"\nsubmit = ["return", "S"]\n\n[theme]\naccent = "#ff0000"\n`,
     );
     try {
-      const c = loadConfig({ userConfigPath: path });
-      expect(c.keys["comment"]).toEqual(["a"]);
-      expect(c.keys["submit"]).toEqual(["return", "S"]);
-      expect(c.keys["cut"]).toEqual(["x"]); // untouched defaults survive
-      expect(c.theme.accent).toBe("#ff0000");
-      expect(c.theme.green).toBe(DARK.green);
+      const config = loadConfig({ userConfigPath: path });
+      expect(config.keys["comment"]).toEqual(["a"]);
+      expect(config.keys["submit"]).toEqual(["return", "S"]);
+      expect(config.keys["cut"]).toEqual(["x"]); // untouched defaults survive
+      expect(config.theme.accent).toBe("#ff0000");
+      expect(config.theme.green).toBe(DARK.green);
     } finally {
       rmSync(dir, { recursive: true, force: true });
     }
@@ -39,8 +39,8 @@ describe("loadConfig", () => {
     Bun.spawnSync(["mkdir", "-p", join(repoRoot, ".cueloop")]);
     writeFileSync(join(repoRoot, ".cueloop", "config.toml"), `[keys]\ncomment = "z"\n`);
     try {
-      const c = loadConfig({ userConfigPath: user, repoRoot });
-      expect(c.keys["comment"]).toEqual(["z"]);
+      const config = loadConfig({ userConfigPath: user, repoRoot });
+      expect(config.keys["comment"]).toEqual(["z"]);
     } finally {
       rmSync(dir, { recursive: true, force: true });
     }
@@ -51,8 +51,33 @@ describe("loadConfig", () => {
     const path = join(dir, "config.toml");
     writeFileSync(path, "not [valid toml");
     try {
-      const c = loadConfig({ userConfigPath: path });
-      expect(c.keys["comment"]).toEqual(["c"]);
+      const config = loadConfig({ userConfigPath: path });
+      expect(config.keys["comment"]).toEqual(["c"]);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("[ui] parses auto_close and the editor override", () => {
+    const dir = mkdtempSync(join(tmpdir(), "cueloop-cfg4-"));
+    const path = join(dir, "config.toml");
+    writeFileSync(path, `[ui]\nauto_close = 3\neditor = "code --wait"\n`);
+    try {
+      const config = loadConfig({ userConfigPath: path });
+      expect(config.ui.autoClose).toBe(3);
+      expect(config.ui.editor).toBe("code --wait");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("[ui] editor defaults to undefined and ignores a blank value", () => {
+    const dir = mkdtempSync(join(tmpdir(), "cueloop-cfg5-"));
+    const path = join(dir, "config.toml");
+    writeFileSync(path, `[ui]\neditor = "   "\n`);
+    try {
+      expect(loadConfig({ userConfigPath: "/nonexistent/config.toml" }).ui.editor).toBeUndefined();
+      expect(loadConfig({ userConfigPath: path }).ui.editor).toBeUndefined();
     } finally {
       rmSync(dir, { recursive: true, force: true });
     }
@@ -61,12 +86,12 @@ describe("loadConfig", () => {
 
 describe("integrations.obsidian config", () => {
   test("defaults when the section is absent", () => {
-    const c = loadConfig({ userConfigPath: "/nonexistent/config.toml" });
-    expect(c.integrations.obsidian.vault).toBeUndefined();
-    expect(c.integrations.obsidian.folder).toBe("cueloop");
-    expect(c.integrations.obsidian.filenameFormat).toBe("{YYYY}-{MM}-{DD} - {title}");
-    expect(c.integrations.obsidian.separator).toBe("space");
-    expect(c.integrations.obsidian.exportOn).toBe("manual");
+    const config = loadConfig({ userConfigPath: "/nonexistent/config.toml" });
+    expect(config.integrations.obsidian.vault).toBeUndefined();
+    expect(config.integrations.obsidian.folder).toBe("cueloop");
+    expect(config.integrations.obsidian.filenameFormat).toBe("{YYYY}-{MM}-{DD} - {title}");
+    expect(config.integrations.obsidian.separator).toBe("space");
+    expect(config.integrations.obsidian.exportOn).toBe("manual");
   });
 
   test("user config sets the section; invalid enum values are ignored", () => {
@@ -77,12 +102,12 @@ describe("integrations.obsidian config", () => {
       `[integrations.obsidian]\nvault = "/notes/vault"\nfolder = "plans"\nexportOn = "approve"\nseparator = "comma"\n`,
     );
     try {
-      const c = loadConfig({ userConfigPath: path });
-      expect(c.integrations.obsidian.vault).toBe("/notes/vault");
-      expect(c.integrations.obsidian.folder).toBe("plans");
-      expect(c.integrations.obsidian.exportOn).toBe("approve");
-      expect(c.integrations.obsidian.separator).toBe("space"); // invalid value falls back
-      expect(c.keys["comment"]).toEqual(["c"]); // other sections untouched
+      const config = loadConfig({ userConfigPath: path });
+      expect(config.integrations.obsidian.vault).toBe("/notes/vault");
+      expect(config.integrations.obsidian.folder).toBe("plans");
+      expect(config.integrations.obsidian.exportOn).toBe("approve");
+      expect(config.integrations.obsidian.separator).toBe("space"); // invalid value falls back
+      expect(config.keys["comment"]).toEqual(["c"]); // other sections untouched
     } finally {
       rmSync(dir, { recursive: true, force: true });
     }
@@ -96,10 +121,10 @@ describe("integrations.obsidian config", () => {
     Bun.spawnSync(["mkdir", "-p", join(repoRoot, ".cueloop")]);
     writeFileSync(join(repoRoot, ".cueloop", "config.toml"), `[integrations.obsidian]\nfolder = "repo-plans"\n`);
     try {
-      const c = loadConfig({ userConfigPath: user, repoRoot });
-      expect(c.integrations.obsidian.vault).toBe("/user/vault"); // user layer survives
-      expect(c.integrations.obsidian.exportOn).toBe("resolve");
-      expect(c.integrations.obsidian.folder).toBe("repo-plans"); // repo layer wins
+      const config = loadConfig({ userConfigPath: user, repoRoot });
+      expect(config.integrations.obsidian.vault).toBe("/user/vault"); // user layer survives
+      expect(config.integrations.obsidian.exportOn).toBe("resolve");
+      expect(config.integrations.obsidian.folder).toBe("repo-plans"); // repo layer wins
     } finally {
       rmSync(dir, { recursive: true, force: true });
     }

package/src/config.ts

@@ -1,13 +1,16 @@
 /**
- * Layered TOML config (#20): built-in defaults → user config → trusted repo
+ * Layered TOML config: built-in defaults → user config → trusted repo
  * config → env. Sections: [keys] action = "combo" (every action rebindable),
- * [theme] per-token overrides, [integrations.obsidian] notes-vault export.
+ * [theme] per-token overrides, [ui] auto_close + editor, [integrations.obsidian]
+ * notes-vault export.
  */
 
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { OBSIDIAN_DEFAULTS, type ObsidianConfig } from "@cueloop/integration-obsidian";
+import { writeFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
 import { DARK, type Theme } from "./theme";
 
 export interface KeymapConfig {
@@ -18,9 +21,13 @@ export interface IntegrationsConfig {
   obsidian: ObsidianConfig;
 }
 
+/** Post-submit behavior: "off" prompts, 0 closes instantly, N counts down. */
+export type AutoClose = "off" | number;
+
 export interface CueloopConfig {
   keys: Record<string, string[]>;
   theme: Theme;
+  ui: { autoClose: AutoClose; editor?: string };
   integrations: IntegrationsConfig;
 }
 
@@ -40,6 +47,7 @@ export const DEFAULT_KEYS: Record<string, string[]> = {
   delete_annotation: ["backspace"],
   submit: ["return", "enter"],
   quit: ["q"],
+  walk: ["w"],
 };
 
 function parseToml(text: string): Record<string, unknown> {
@@ -51,6 +59,7 @@ function layer(base: CueloopConfig, raw: Record<string, unknown>): CueloopConfig
   const out: CueloopConfig = {
     keys: { ...base.keys },
     theme: { ...base.theme },
+    ui: { ...base.ui },
     integrations: { obsidian: { ...base.integrations.obsidian } },
   };
   const keys = raw["keys"] as KeymapConfig | undefined;
@@ -59,6 +68,12 @@ function layer(base: CueloopConfig, raw: Record<string, unknown>): CueloopConfig
       out.keys[action] = Array.isArray(combo) ? combo : [combo];
     }
   }
+  const ui = raw["ui"] as { auto_close?: unknown; editor?: unknown } | undefined;
+  if (ui && ui.auto_close !== undefined) {
+    if (ui.auto_close === "off") out.ui.autoClose = "off";
+    else if (typeof ui.auto_close === "number" && ui.auto_close >= 0) out.ui.autoClose = ui.auto_close;
+  }
+  if (ui && typeof ui.editor === "string" && ui.editor.trim()) out.ui.editor = ui.editor.trim();
   const theme = raw["theme"] as Partial<Record<keyof Theme, string>> | undefined;
   if (theme) {
     for (const [token, value] of Object.entries(theme)) {
@@ -70,29 +85,30 @@ function layer(base: CueloopConfig, raw: Record<string, unknown>): CueloopConfig
   const integrations = raw["integrations"] as Record<string, unknown> | undefined;
   const obsidian = integrations?.["obsidian"] as Record<string, unknown> | undefined;
   if (obsidian) {
-    const o = out.integrations.obsidian;
-    if (typeof obsidian["vault"] === "string") o.vault = obsidian["vault"];
-    if (typeof obsidian["folder"] === "string") o.folder = obsidian["folder"];
-    if (typeof obsidian["filenameFormat"] === "string") o.filenameFormat = obsidian["filenameFormat"];
-    const sep = obsidian["separator"];
-    if (sep === "space" || sep === "dash" || sep === "underscore") o.separator = sep;
-    const on = obsidian["exportOn"];
-    if (on === "approve" || on === "resolve" || on === "manual") o.exportOn = on;
+    const obsidianConfig = out.integrations.obsidian;
+    if (typeof obsidian["vault"] === "string") obsidianConfig.vault = obsidian["vault"];
+    if (typeof obsidian["folder"] === "string") obsidianConfig.folder = obsidian["folder"];
+    if (typeof obsidian["filenameFormat"] === "string") obsidianConfig.filenameFormat = obsidian["filenameFormat"];
+    const separator = obsidian["separator"];
+    if (separator === "space" || separator === "dash" || separator === "underscore") obsidianConfig.separator = separator;
+    const exportOn = obsidian["exportOn"];
+    if (exportOn === "approve" || exportOn === "resolve" || exportOn === "manual") obsidianConfig.exportOn = exportOn;
   }
   return out;
 }
 
-export function loadConfig(opts: { repoRoot?: string; userConfigPath?: string } = {}): CueloopConfig {
+export function loadConfig(options: { repoRoot?: string; userConfigPath?: string } = {}): CueloopConfig {
   let config: CueloopConfig = {
     keys: { ...DEFAULT_KEYS },
     theme: { ...DARK },
+    ui: { autoClose: "off" },
     integrations: { obsidian: { ...OBSIDIAN_DEFAULTS } },
   };
   const userPath =
-    opts.userConfigPath ??
+    options.userConfigPath ??
     process.env.CUELOOP_CONFIG ??
     join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "cueloop", "config.toml");
-  for (const path of [userPath, opts.repoRoot ? join(opts.repoRoot, ".cueloop", "config.toml") : undefined]) {
+  for (const path of [userPath, options.repoRoot ? join(options.repoRoot, ".cueloop", "config.toml") : undefined]) {
     if (!path || !existsSync(path)) continue;
     try {
       config = layer(config, parseToml(readFileSync(path, "utf8")));
@@ -111,3 +127,27 @@ export function actionFor(keys: Record<string, string[]>, name: string, shift: b
   }
   return undefined;
 }
+
+/**
+ * Persist the auto-close choice into the user config file. Line-level TOML
+ * surgery on the one key we own: replace an existing `auto_close`, or append
+ * an `[ui]` section - a full TOML writer is not worth its weight here.
+ */
+export function persistAutoClose(value: AutoClose, userConfigPath?: string): void {
+  const path =
+    userConfigPath ??
+    process.env.CUELOOP_CONFIG ??
+    join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "cueloop", "config.toml");
+  const rendered = value === "off" ? '"off"' : String(value);
+  let text = "";
+  if (existsSync(path)) text = readFileSync(path, "utf8");
+  if (/^\s*auto_close\s*=/m.test(text)) {
+    text = text.replace(/^(\s*)auto_close\s*=.*$/m, `$1auto_close = ${rendered}`);
+  } else if (/^\[ui\]/m.test(text)) {
+    text = text.replace(/^\[ui\]\s*$/m, `[ui]\nauto_close = ${rendered}`);
+  } else {
+    text = text.trimEnd() + (text.trim() ? "\n\n" : "") + `[ui]\nauto_close = ${rendered}\n`;
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, text);
+}

package/src/editor.test.ts

@@ -0,0 +1,110 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { editInEditor, resolveEditor, resolveEditorCommand } from "./editor";
+
+describe("resolveEditor", () => {
+  test("a clean environment falls back to nano so editing always works", () => {
+    expect(resolveEditor(undefined, {})).toBe("nano");
+  });
+
+  test("the environment chain wins in order: CUELOOP_EDITOR, VISUAL, EDITOR", () => {
+    expect(resolveEditor(undefined, { EDITOR: "vim", VISUAL: "code", CUELOOP_EDITOR: "hx" })).toBe("hx");
+    expect(resolveEditor(undefined, { EDITOR: "vim", VISUAL: "code" })).toBe("code");
+    expect(resolveEditor(undefined, { EDITOR: "vim" })).toBe("vim");
+  });
+
+  test("the [ui] editor config overrides the environment", () => {
+    expect(resolveEditor("code --wait", { EDITOR: "vim" })).toBe("code --wait");
+  });
+});
+
+describe("resolveEditorCommand", () => {
+  test("a known GUI editor gets its wait flag appended and is trusted to wait", () => {
+    expect(resolveEditorCommand("code")).toEqual({ argv: ["code", "--wait"], waits: true });
+    expect(resolveEditorCommand("subl")).toEqual({ argv: ["subl", "--new-window", "--wait"], waits: true });
+  });
+
+  test("an existing wait flag is not duplicated", () => {
+    expect(resolveEditorCommand("code --wait").argv).toEqual(["code", "--wait"]);
+  });
+
+  test("a terminal editor is left alone and trusted to hold the tty", () => {
+    expect(resolveEditorCommand("vim")).toEqual({ argv: ["vim"], waits: true });
+  });
+
+  test("an unknown editor is neither flagged nor trusted to wait", () => {
+    expect(resolveEditorCommand("my-editor")).toEqual({ argv: ["my-editor"], waits: false });
+  });
+});
+
+describe("editInEditor", () => {
+  let dir: string;
+  beforeEach(() => {
+    dir = mkdtempSync(join(tmpdir(), "cueloop-edit-test-"));
+  });
+  afterEach(() => {
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  /** A runnable editor stub with a chosen base name and body. */
+  function stubEditor(name: string, body: string): string {
+    const script = join(dir, name);
+    writeFileSync(script, `#!/bin/sh\n${body}\n`);
+    chmodSync(script, 0o755);
+    return script;
+  }
+
+  const instant = (): (() => number) => {
+    let value = 0;
+    return () => (value += 5);
+  };
+
+  test("an editor that changes the file reports the new content", () => {
+    const result = editInEditor("old", "plan.md", { editor: stubEditor("writer.sh", `printf 'new' > "$1"`) });
+    expect(result).toEqual({ content: "new", changed: true });
+  });
+
+  test("a fast, unchanged return opens the gate; confirming re-reads the saved file", () => {
+    let askedLabel = "";
+    const result = editInEditor("keep", "plan.md", {
+      editor: stubEditor("gui-like.sh", "exit 0"),
+      now: instant(),
+      confirmSaved: (label, path) => {
+        askedLabel = label;
+        writeFileSync(path, "saved in the GUI");
+        return true;
+      },
+    });
+    expect(askedLabel).toContain("gui-like.sh");
+    expect(result).toEqual({ content: "saved in the GUI", changed: true });
+  });
+
+  test("declining the gate keeps the original content", () => {
+    const result = editInEditor("keep", "plan.md", {
+      editor: stubEditor("gui-like.sh", "exit 0"),
+      now: instant(),
+      confirmSaved: () => false,
+    });
+    expect(result).toEqual({ content: "keep", changed: false });
+  });
+
+  test("a terminal editor that makes no change never opens the gate", () => {
+    let asked = false;
+    const result = editInEditor("keep", "plan.md", {
+      editor: stubEditor("vi", "exit 0"),
+      now: instant(),
+      confirmSaved: () => {
+        asked = true;
+        return true;
+      },
+    });
+    expect(asked).toBeFalse();
+    expect(result).toEqual({ content: "keep", changed: false });
+  });
+
+  test("a nonzero editor exit throws", () => {
+    expect(() => editInEditor("x", "plan.md", { editor: stubEditor("fail.sh", "exit 3") })).toThrow("editor exited 3");
+  });
+});