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

package/src/components/story-fixtures.ts

@@ -0,0 +1,90 @@
+/** Shared fixture data for the stories catalog: one plan session, one diff. */
+
+import type { Annotation, ReviewSession } from "@cueloop/schema";
+import { buildDisplay, marksByDisplay } from "../view-plan";
+import { diffRows } from "../view-diff";
+
+export const FIXTURE_PLAN = `# Migration Plan
+
+## Context
+
+The daemon persists sessions to disk atomically.
+
+## Steps
+
+- move the store
+- add recovery
+
+\`\`\`ts
+export function persist(session: Session): void {
+  // one JSON document per session
+  writeAtomically(pathFor(session.id), serialize(session));
+}
+\`\`\`
+`;
+
+export const FIXTURE_PATCH = `diff --git a/src/store.ts b/src/store.ts
+index 111..222 100644
+--- a/src/store.ts
++++ b/src/store.ts
+@@ -1,4 +1,4 @@
+ export class Store {
+-  private items = [];
++  private items = new Map();
+ }
+`;
+
+export const FIXTURE_ANNOTATIONS: Annotation[] = [
+  {
+    id: "a_story_1",
+    kind: "comment",
+    anchor: { quote: "persists sessions", prefix: "The daemon ", suffix: " to disk" },
+    body: "Which daemon owns this?",
+    createdAt: "2026-01-01T00:00:00Z",
+  },
+  {
+    id: "a_story_2",
+    kind: "suggestion",
+    anchor: { quote: "move the store", prefix: "", suffix: "" },
+    body: "move the store behind one interface",
+    createdAt: "2026-01-01T00:00:01Z",
+  },
+];
+
+export function fixturePlanSession(overrides: Partial<ReviewSession> = {}): ReviewSession {
+  return {
+    schemaVersion: "1",
+    id: "s_story_plan",
+    workspace: { repoRoot: "/repo", branch: "main" },
+    artifact: { type: "plan", content: FIXTURE_PLAN, meta: { title: "Migration Plan", agent: "agent/worker-3" } },
+    revisions: [{ revision: 1, content: FIXTURE_PLAN, submittedAt: "2026-01-01T00:00:00Z" }],
+    annotations: FIXTURE_ANNOTATIONS,
+    status: "pending",
+    ...overrides,
+  } as ReviewSession;
+}
+
+export function fixtureDiffSession(overrides: Partial<ReviewSession> = {}): ReviewSession {
+  return {
+    schemaVersion: "1",
+    id: "s_story_diff",
+    workspace: { repoRoot: "/repo", branch: "main" },
+    artifact: { type: "diff", content: FIXTURE_PATCH, meta: { title: "working tree", agent: "agent/worker-3" } },
+    revisions: [{ revision: 1, content: FIXTURE_PATCH, submittedAt: "2026-01-01T00:00:00Z" }],
+    annotations: [],
+    status: "pending",
+    ...overrides,
+  } as ReviewSession;
+}
+
+export function fixtureDisplay() {
+  return buildDisplay(FIXTURE_PLAN);
+}
+
+export function fixtureMarks() {
+  return marksByDisplay(FIXTURE_ANNOTATIONS, fixtureDisplay());
+}
+
+export function fixtureDiffRows() {
+  return diffRows(FIXTURE_PATCH);
+}

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

@@ -2,14 +2,15 @@ import { describe, expect, test } from "bun:test";
 import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { DEFAULT_KEYS, actionFor, loadConfig } from "./config";
+import { DEFAULT_KEYS, actionFor, loadConfig, persistReviewState, persistReviewWidth } from "./config";
+import { REVIEW_DEFAULT_WIDTH, REVIEW_MAX_WIDTH } from "./review-panel";
 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 +21,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 +40,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 +52,82 @@ 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 });
+    }
+  });
+
+  test("[ui] review panel defaults to an expanded rail at the default width", () => {
+    const config = loadConfig({ userConfigPath: "/nonexistent/config.toml" });
+    expect(config.ui.reviewState).toBe("expanded");
+    expect(config.ui.reviewWidth).toBe(REVIEW_DEFAULT_WIDTH);
+  });
+
+  test("[ui] parses review_width (clamped) and review_state", () => {
+    const dir = mkdtempSync(join(tmpdir(), "cueloop-cfg6-"));
+    const path = join(dir, "config.toml");
+    writeFileSync(path, `[ui]\nreview_width = 999\nreview_state = "compact"\n`);
+    try {
+      const config = loadConfig({ userConfigPath: path });
+      expect(config.ui.reviewWidth).toBe(REVIEW_MAX_WIDTH); // out-of-range width clamps
+      expect(config.ui.reviewState).toBe("compact");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("[ui] ignores an unknown review_state and a non-numeric width", () => {
+    const dir = mkdtempSync(join(tmpdir(), "cueloop-cfg7-"));
+    const path = join(dir, "config.toml");
+    writeFileSync(path, `[ui]\nreview_width = "wide"\nreview_state = "sideways"\n`);
+    try {
+      const config = loadConfig({ userConfigPath: path });
+      expect(config.ui.reviewWidth).toBe(REVIEW_DEFAULT_WIDTH);
+      expect(config.ui.reviewState).toBe("expanded");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("persistReviewWidth and persistReviewState round-trip through the config file", () => {
+    const dir = mkdtempSync(join(tmpdir(), "cueloop-cfg8-"));
+    const path = join(dir, "config.toml");
+    try {
+      persistReviewWidth(42, path);
+      persistReviewState("hidden", path);
+      const config = loadConfig({ userConfigPath: path });
+      expect(config.ui.reviewWidth).toBe(42);
+      expect(config.ui.reviewState).toBe("hidden");
+      // a second write replaces the key in place rather than appending a duplicate
+      persistReviewWidth(30, path);
+      expect(loadConfig({ userConfigPath: path }).ui.reviewWidth).toBe(30);
     } finally {
       rmSync(dir, { recursive: true, force: true });
     }
@@ -61,12 +136,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 +152,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 +171,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,14 +1,19 @@
 /**
- * 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 + the review-panel
+ * layout (review_width + review_state), [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";
+import { REVIEW_DEFAULT_WIDTH, clampWidth, type ReviewPanelMode } from "./review-panel";
 
 export interface KeymapConfig {
   [action: string]: string | string[];
@@ -18,9 +23,17 @@ 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.reviewState / ui.reviewWidth are CLIENT VIEW STATE: the review panel's
+   * collapse mode and expanded-rail width, persisted so they survive restarts.
+   */
+  ui: { autoClose: AutoClose; editor?: string; reviewState: ReviewPanelMode; reviewWidth: number };
   integrations: IntegrationsConfig;
 }
 
@@ -40,6 +53,10 @@ export const DEFAULT_KEYS: Record<string, string[]> = {
   delete_annotation: ["backspace"],
   submit: ["return", "enter"],
   quit: ["q"],
+  walk: ["w"],
+  review_cycle: ["b"],
+  review_wider: ["]"],
+  review_narrower: ["["],
 };
 
 function parseToml(text: string): Record<string, unknown> {
@@ -51,6 +68,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 +77,20 @@ 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; review_width?: unknown; review_state?: 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();
+  if (ui && typeof ui.review_width === "number" && Number.isFinite(ui.review_width)) {
+    out.ui.reviewWidth = clampWidth(ui.review_width);
+  }
+  if (ui && (ui.review_state === "expanded" || ui.review_state === "compact" || ui.review_state === "hidden")) {
+    out.ui.reviewState = ui.review_state;
+  }
   const theme = raw["theme"] as Partial<Record<keyof Theme, string>> | undefined;
   if (theme) {
     for (const [token, value] of Object.entries(theme)) {
@@ -70,29 +102,27 @@ 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", reviewState: "expanded", reviewWidth: REVIEW_DEFAULT_WIDTH },
     integrations: { obsidian: { ...OBSIDIAN_DEFAULTS } },
   };
-  const userPath =
-    opts.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]) {
+  const userPath = userConfigPathFrom(options.userConfigPath);
+  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 +141,48 @@ export function actionFor(keys: Record<string, string[]>, name: string, shift: b
   }
   return undefined;
 }
+
+function userConfigPathFrom(userConfigPath?: string): string {
+  return (
+    userConfigPath ??
+    process.env.CUELOOP_CONFIG ??
+    join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "cueloop", "config.toml")
+  );
+}
+
+/**
+ * Persist one `[ui]` key into the user config file. Line-level TOML surgery on
+ * the keys we own: replace the existing assignment, or drop it under an `[ui]`
+ * section (appending the section when absent) - a full TOML writer is not worth
+ * its weight here.
+ */
+function persistUiSetting(key: string, rendered: string, userConfigPath?: string): void {
+  const path = userConfigPathFrom(userConfigPath);
+  let text = "";
+  if (existsSync(path)) text = readFileSync(path, "utf8");
+  const assignment = new RegExp(`^(\\s*)${key}\\s*=.*$`, "m");
+  if (assignment.test(text)) {
+    text = text.replace(assignment, `$1${key} = ${rendered}`);
+  } else if (/^\[ui\]/m.test(text)) {
+    text = text.replace(/^\[ui\]\s*$/m, `[ui]\n${key} = ${rendered}`);
+  } else {
+    text = text.trimEnd() + (text.trim() ? "\n\n" : "") + `[ui]\n${key} = ${rendered}\n`;
+  }
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, text);
+}
+
+/** Persist the auto-close choice (`[ui] auto_close`) into the user config. */
+export function persistAutoClose(value: AutoClose, userConfigPath?: string): void {
+  persistUiSetting("auto_close", value === "off" ? '"off"' : String(value), userConfigPath);
+}
+
+/** Persist the expanded-rail width (`[ui] review_width`) into the user config. */
+export function persistReviewWidth(width: number, userConfigPath?: string): void {
+  persistUiSetting("review_width", String(clampWidth(width)), userConfigPath);
+}
+
+/** Persist the review-panel collapse mode (`[ui] review_state`) into the config. */
+export function persistReviewState(state: ReviewPanelMode, userConfigPath?: string): void {
+  persistUiSetting("review_state", `"${state}"`, userConfigPath);
+}