gentle-pi 3.7.0 → 4.1.0

package/tests/vim-normal-engine.test.ts

@@ -0,0 +1,101 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { VimNormalEngine } from "../lib/vim-normal-engine.ts";
+
+function run(text: string, cursor: { line: number; col: number }, keys: string) {
+  const engine = new VimNormalEngine();
+  let position = cursor;
+  let insert: string | undefined;
+  for (const key of keys.split(" ")) {
+    const result = engine.input(key, text, position);
+    position = result.cursor;
+    if (result.insert !== undefined) insert = result.insert;
+  }
+  return { position, insert };
+}
+
+test("horizontal motions count graphemes, not UTF-16 units; clamp at line edges", () => {
+  assert.deepEqual(run("a👩‍💻é\nz", { line: 0, col: 0 }, "3l").position, { line: 0, col: 7 });
+  assert.deepEqual(run("a👩‍💻é\nz", { line: 0, col: 7 }, "2h").position, { line: 0, col: 1 });
+  assert.deepEqual(run("a\nb", { line: 0, col: 1 }, "l").position, { line: 0, col: 1 });
+  assert.deepEqual(run("a b", { line: 0, col: 0 }, "Space").position, { line: 0, col: 1 });
+});
+
+test("vertical motions keep preferred grapheme column across short lines without history", () => {
+  assert.deepEqual(run("a👩‍💻z\nx\na👩‍💻z", { line: 0, col: 6 }, "j j").position, { line: 2, col: 6 });
+  assert.deepEqual(run("one\ntwo", { line: 0, col: 0 }, "k").position, { line: 0, col: 0 });
+});
+
+test("word, line and document motions work across newlines and Unicode", () => {
+  assert.deepEqual(run("  雪 blue\n fin", { line: 0, col: 0 }, "w").position, { line: 0, col: 2 });
+  assert.deepEqual(run("  雪 blue\n fin", { line: 0, col: 2 }, "w").position, { line: 0, col: 4 });
+  assert.deepEqual(run("abc de\nfin", { line: 0, col: 0 }, "e").position, { line: 0, col: 2 });
+  assert.deepEqual(run("abc de\nfin", { line: 0, col: 4 }, "b").position, { line: 0, col: 0 });
+  assert.deepEqual(run("  abc\n fin", { line: 1, col: 2 }, "0").position, { line: 1, col: 0 });
+  assert.deepEqual(run("  abc\n fin", { line: 1, col: 0 }, "^").position, { line: 1, col: 1 });
+  assert.deepEqual(run("  abc\n fin", { line: 0, col: 0 }, "$ G").position, { line: 1, col: 0 });
+  assert.deepEqual(run("a\nb\nc", { line: 2, col: 1 }, "g g").position, { line: 0, col: 0 });
+  assert.deepEqual(run("a\nb\nc", { line: 0, col: 0 }, "2G").position, { line: 1, col: 0 });
+  assert.deepEqual(run("a\nb\nc", { line: 0, col: 0 }, "2g g").position, { line: 1, col: 0 });
+});
+
+test("pending count and gg survive a non-command shortcut probe", () => {
+  const engine = new VimNormalEngine();
+  const text = "a\nb\nc";
+  assert.deepEqual(engine.input("g", text, { line: 2, col: 0 }).cursor, { line: 2, col: 0 });
+  assert.deepEqual(engine.input("g", text, { line: 2, col: 0 }).cursor, { line: 0, col: 0 });
+  engine.input("2", text, { line: 0, col: 0 });
+  assert.deepEqual(engine.input("j", text, { line: 0, col: 0 }).cursor, { line: 2, col: 0 });
+});
+
+test("first non-whitespace is a grapheme boundary when whitespace precedes a combining mark", () => {
+  assert.deepEqual(run(" \u0301a", { line: 0, col: 0 }, "^").position, { line: 0, col: 2 });
+  assert.deepEqual(run(" \u0301a", { line: 0, col: 0 }, "I"), { position: { line: 0, col: 2 }, insert: "" });
+});
+
+test("horizontal motions skip registered paste markers atomically", () => {
+  const engine = new VimNormalEngine();
+  const text = "a[paste #1 1001 chars]b";
+  const end = text.indexOf("b");
+  const positions = [[0, 1, end, text.length]];
+  assert.deepEqual(engine.input("h", text, { line: 0, col: end }, positions).cursor, { line: 0, col: 1 });
+  assert.deepEqual(engine.input("l", text, { line: 0, col: 1 }, positions).cursor, { line: 0, col: end });
+});
+
+test("counted f/F/t/T find within the current line on grapheme boundaries", () => {
+  assert.deepEqual(run("a👩‍💻x👩‍💻x\n👩‍💻x", { line: 0, col: 0 }, "2 f 👩‍💻").position, { line: 0, col: 7 });
+  assert.deepEqual(run("a👩‍💻x👩‍💻x", { line: 0, col: 0 }, "2 t 👩‍💻").position, { line: 0, col: 6 });
+  assert.deepEqual(run("a👩‍💻x👩‍💻x", { line: 0, col: 13 }, "2 F 👩‍💻").position, { line: 0, col: 1 });
+  assert.deepEqual(run("a👩‍💻x👩‍💻x", { line: 0, col: 13 }, "2 T 👩‍💻").position, { line: 0, col: 6 });
+});
+
+test(";/, repeat last successful find with counts, reverse direction, and no-match safety", () => {
+  assert.deepEqual(run("axaxax", { line: 0, col: 0 }, "t x ;").position, { line: 0, col: 2 });
+  assert.deepEqual(run("axaxax", { line: 0, col: 0 }, "f x 2 ; ,").position, { line: 0, col: 3 });
+  assert.deepEqual(run("ax\nx", { line: 0, col: 0 }, "f x ;").position, { line: 0, col: 1 });
+  assert.deepEqual(run("a👩‍💻b", { line: 0, col: 0 }, "f z ;").position, { line: 0, col: 0 });
+  assert.deepEqual(run("ax", { line: 0, col: 0 }, "; ,").position, { line: 0, col: 0 });
+});
+
+test("pending find consumes numeric target, resets on cancellation and respects atomic paste", () => {
+  const engine = new VimNormalEngine();
+  const text = "a1[paste #1 1001 chars]b";
+  const end = text.indexOf("b");
+  const stops = [[0, 1, 2, end, text.length]];
+  assert.deepEqual(engine.input("f", text, { line: 0, col: 0 }, stops).cursor, { line: 0, col: 0 });
+  assert.deepEqual(engine.input("1", text, { line: 0, col: 0 }, stops).cursor, { line: 0, col: 1 });
+  engine.input("f", text, { line: 0, col: 1 }, stops);
+  engine.reset();
+  assert.deepEqual(engine.input(";", text, { line: 0, col: 1 }, stops).cursor, { line: 0, col: 1 });
+  const markerText = "a[paste #1 1001 chars]b";
+  assert.deepEqual(engine.input("f", markerText, { line: 0, col: 0 }, [[0, 1, markerText.length - 1, markerText.length]]).cursor, { line: 0, col: 0 });
+  assert.deepEqual(engine.input("#", markerText, { line: 0, col: 0 }, [[0, 1, markerText.length - 1, markerText.length]]).cursor, { line: 0, col: 0 });
+});
+
+test("insert/open commands return exact insertion and cursor destination", () => {
+  assert.deepEqual(run("  ab", { line: 0, col: 2 }, "I"), { position: { line: 0, col: 2 }, insert: "" });
+  assert.deepEqual(run("  ab", { line: 0, col: 2 }, "A"), { position: { line: 0, col: 4 }, insert: "" });
+  assert.deepEqual(run("ab", { line: 0, col: 0 }, "a"), { position: { line: 0, col: 1 }, insert: "" });
+  assert.deepEqual(run("ab\ncd", { line: 0, col: 0 }, "o"), { position: { line: 0, col: 2 }, insert: "\n" });
+  assert.deepEqual(run("ab\ncd", { line: 1, col: 1 }, "O"), { position: { line: 1, col: 0 }, insert: "\n" });
+});

package/tests/vim-operator-engine.test.ts

@@ -0,0 +1,215 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { VimOperatorEngine } from "../lib/vim-operator-engine.ts";
+
+function run(text: string, col: number, keys: string[], bounds?: number[][]) {
+  const engine = new VimOperatorEngine();
+  let cursor = { line: 0, col };
+  let edit;
+  for (const key of keys) {
+    const result = engine.input(key, text, cursor, bounds);
+    if (result?.edit) {
+      edit = result.edit;
+      const offset = (p: typeof cursor) => text.split("\n").slice(0, p.line).reduce((n, line) => n + line.length + 1, 0) + p.col;
+      text = text.slice(0, offset(edit.start)) + edit.text + text.slice(offset(edit.end));
+      cursor = edit.cursor;
+    }
+  }
+  return { text, cursor, edit, engine };
+}
+
+test("visual ranges delete or change linewise and shift only selected lines", () => {
+  const engine = new VimOperatorEngine();
+  const range = { start: { line: 1, col: 0 }, end: { line: 2, col: 5 }, linewise: true };
+  assert.deepEqual(engine.visualEdit("d", "one\ntwo\nthree", range).edit, {
+    start: { line: 0, col: 3 }, end: { line: 2, col: 5 }, text: "", cursor: { line: 0, col: 0 },
+  });
+  assert.equal(engine.visualEdit("c", "one\ntwo\nthree", range).edit?.insert, true);
+  assert.equal(engine.visualEdit(">", "one\ntwo\nthree", range).edit?.text, "  two\n  three");
+  assert.equal(engine.visualEdit("<", "one\ntwo\nthree", range).edit, undefined);
+});
+
+test("visual shifts dedent tabs and empty visual ranges cannot overwrite the register", () => {
+  const engine = new VimOperatorEngine();
+  const line = { start: { line: 0, col: 0 }, end: { line: 0, col: 4 }, linewise: true };
+  assert.equal(engine.visualEdit("<", "\tfoo", line).edit?.text, "foo");
+  engine.visualRegister("saved", false);
+  engine.visualRegister("", false);
+  assert.equal(engine.input("P", "abc", { line: 0, col: 0 })?.edit?.text, "saved");
+});
+
+test("operator motions and doubled line operators honor counts and multiline Unicode", () => {
+  assert.equal(run("👩‍💻 hi\nnext", 0, ["d", "w"]).text, "hi\nnext");
+  assert.equal(run("one\ntwo\nthree", 0, ["2", "d", "d"]).text, "three");
+  assert.equal(run("one\ntwo", 0, ["c", "c"]).text, "\ntwo");
+  assert.equal(run("one\ntwo", 0, ["y", "y", "p"]).text, "one\none\ntwo");
+  assert.equal(run("abcb", 0, ["d", "f", "c"]).text, "b");
+});
+
+test("linewise yank records a complete line and pastes at line boundaries", () => {
+  for (const paste of ["p", "P"]) {
+    const engine = new VimOperatorEngine();
+    const cursor = { line: 1, col: 0 };
+    assert.deepEqual(engine.input("y", "one\ntwo", cursor), { handled: true });
+    assert.deepEqual(engine.input("y", "one\ntwo", cursor), { handled: true });
+    const result = engine.input(paste, "one\ntwo", cursor);
+    assert.ok(result?.edit);
+    const { start, end, text } = result.edit;
+    const source = "one\ntwo";
+    const offset = (p: typeof cursor) => source.split("\n").slice(0, p.line).reduce((n, line) => n + line.length + 1, 0) + p.col;
+    assert.equal(source.slice(0, offset(start)) + text + source.slice(offset(end)), "one\ntwo\ntwo");
+    assert.deepEqual(result.edit.cursor, { line: paste === "P" ? 1 : 2, col: 0 });
+  }
+});
+
+test("change line keeps one empty line and enters insert on the changed line", () => {
+  for (const [source, line, expected] of [["one", 0, ""], ["one\ntwo", 1, "one\n"]] as const) {
+    const engine = new VimOperatorEngine();
+    const cursor = { line, col: 0 };
+    engine.input("c", source, cursor);
+    const result = engine.input("c", source, cursor);
+    assert.ok(result?.edit?.insert);
+    const offset = (p: { line: number; col: number }) => source.split("\n").slice(0, p.line).reduce((n, value) => n + value.length + 1, 0) + p.col;
+    const edit = result.edit;
+    assert.equal(source.slice(0, offset(edit.start)) + edit.text + source.slice(offset(edit.end)), expected);
+    assert.deepEqual(edit.cursor, { line, col: 0 });
+  }
+});
+
+test("linewise change and delete preserve surrounding lines and last-line cursor", () => {
+  assert.equal(run("one\ntwo\nthree", 0, ["c", "c"]).text, "\ntwo\nthree");
+  const middle = new VimOperatorEngine();
+  const at = { line: 1, col: 0 };
+  middle.input("c", "one\ntwo\nthree", at);
+  const edit = middle.input("c", "one\ntwo\nthree", at)?.edit;
+  assert.deepEqual(edit?.cursor, at);
+  assert.equal(edit?.text, "\n");
+  const last = new VimOperatorEngine();
+  last.input("d", "one\ntwo", at);
+  assert.deepEqual(last.input("d", "one\ntwo", at)?.edit?.cursor, { line: 0, col: 0 });
+  assert.equal(run("one", 0, ["d", "d"]).text, "");
+});
+
+test("S on an empty prompt still requests INSERT", () => {
+  assert.equal(new VimOperatorEngine().input("S", "", { line: 0, col: 0 })?.edit?.insert, true);
+});
+
+test("text objects include punctuation and WORD whitespace with quote/bracket nesting", () => {
+  assert.equal(run("alpha beta", 2, ["d", "i", "w"]).text, " beta");
+  assert.equal(run("alpha beta", 2, ["d", "a", "w"]).text, "beta");
+  assert.equal(run("a.b rest", 2, ["d", "i", "W"]).text, " rest");
+  assert.equal(run('x "a👩‍💻b" y', 4, ["d", "i", '"']).text, 'x "" y');
+  assert.equal(run("a (b [cd]) z", 7, ["d", "a", "["]).text, "a (b ) z");
+});
+
+test("x/s/S and character paste use grapheme boundaries and undo-safe single edit", () => {
+  assert.equal(run("👩‍💻é", 0, ["x"]).text, "é");
+  assert.equal(run("👩‍💻é", 0, ["s"]).edit?.insert, true);
+  assert.equal(run("abc", 0, ["x", "P"]).text, "abc");
+  assert.equal(run("abc", 0, ["x", "p"]).text, "bac");
+  assert.equal(run("one\ntwo", 0, ["S"]).text, "\ntwo");
+});
+
+test("shift operator accepts motion ranges, counts, Unicode and keeps the register", () => {
+  const engine = new VimOperatorEngine();
+  const at = { line: 0, col: 0 };
+  engine.visualRegister("saved", false);
+  engine.input(">", "é one\n  two\nthree", at);
+  const edit = engine.input("w", "é one\n  two\nthree", at)?.edit;
+  assert.equal(edit?.text, "  é one");
+  assert.equal(engine.input("P", "abc", at)?.edit?.text, "saved");
+  assert.equal(run("a\n b\n c\nd", 0, ["2", ">", "j"]).text, "  a\n   b\n   c\nd");
+  assert.equal(run("a\n b\n c", 0, [">", "2", "j"]).text, "  a\n   b\n   c");
+  assert.equal(run("  a\n\tb", 0, ["<", "j"]).text, "a\nb");
+  assert.equal(run("  a\n  b", 0, ["<", "w"]).text, "a\n  b");
+  assert.equal(run("  a\n  b", 0, ["<", "k"]).text, "  a\n  b");
+  assert.equal(run("a\nb\nc", 0, [">", "G"]).text, "  a\n  b\n  c");
+  assert.equal(run("a\nb\nc", 0, [">", "2", "G"]).text, "  a\n  b\nc");
+  const repeat = new VimOperatorEngine();
+  repeat.input(">", "a\nb", at);
+  repeat.remember(repeat.input("j", "a\nb", at)!);
+  assert.equal(repeat.repeatAt("é\nz", at)?.edit?.text, "  é\n  z");
+  assert.equal(run("a\nb\nc", 0, [">", "g", "g"]).text, "a\nb\nc");
+  assert.equal(run("a\nb\nc", 0, [">", "f", "b"]).text, "a\nb\nc");
+});
+
+test("motion shift excludes a next-line column-zero endpoint but keeps inclusive line motions", () => {
+  assert.equal(run("a\nb", 0, [">", "w"]).text, "  a\nb");
+  assert.equal(run("  a\n  b", 0, ["<", "w"]).text, "a\n  b");
+  assert.equal(run("é\nb\nc", 0, [">", "2", "w"]).text, "  é\n  b\nc");
+  assert.equal(run("a\nb", 0, [">", "j"]).text, "  a\n  b");
+});
+
+test("dedent with no indentation leaves undo and repeat history on the previous x", () => {
+  const engine = new VimOperatorEngine();
+  const cursor = { line: 0, col: 0 };
+  const x = engine.input("x", "abc", cursor)!;
+  engine.remember(x);
+  assert.equal(engine.input("<", "bc", cursor)?.edit, undefined);
+  const dedent = engine.input("<", "bc", cursor)!;
+  assert.equal(dedent.edit, undefined);
+  engine.remember(dedent);
+  assert.deepEqual(engine.repeatAt("bc", cursor)?.edit?.end, { line: 0, col: 1 });
+  const visual = { start: cursor, end: { line: 0, col: 2 }, linewise: true };
+  assert.equal(engine.visualEdit("<", "bc", visual).edit, undefined);
+});
+
+test("join and shift linewise commands honor counts and Unicode without clipping", () => {
+  assert.equal(run("  👩‍💻 one  \n  é two\nthird", 0, ["J"]).text, "  👩‍💻 one é two\nthird");
+  assert.equal(run("a\nb\nc", 0, ["3", "J"]).text, "a b c");
+  assert.equal(run("  one\n\ttwo", 0, [">", ">", "<", "<"]).text, "  one\n\ttwo");
+  assert.equal(run("one\ntwo\nthree", 0, ["2", ">", ">"]).text, "  one\n  two\nthree");
+});
+
+test("repeat re-evaluates a completed counted operator at a new cursor, never a motion or yank", () => {
+  const engine = new VimOperatorEngine();
+  const at = { line: 0, col: 0 };
+  for (const key of ["2", "d", "w"]) {
+    const result = engine.input(key, "one two three four", at);
+    if (result?.edit) engine.remember(result);
+  }
+  assert.equal(engine.repeatAt("alpha beta gamma delta", at)?.edit?.text, "");
+  assert.deepEqual(engine.repeatAt("alpha beta gamma delta", at)?.edit?.end, { line: 0, col: 11 });
+  engine.input("y", "alpha beta", at); engine.input("w", "alpha beta", at);
+  assert.deepEqual(engine.repeatAt("red blue green", at)?.edit?.end, { line: 0, col: 9 });
+  engine.cancel();
+  assert.deepEqual(engine.repeatAt("red blue green", at)?.edit?.end, { line: 0, col: 9 });
+});
+
+test("repeat of x, p, join and shift uses bounded semantics; empty or failed edits are not recorded", () => {
+  const engine = new VimOperatorEngine();
+  const at = { line: 0, col: 0 };
+  assert.equal(engine.repeatAt("abc", at), undefined);
+  const noop = engine.input("x", "", at);
+  assert.equal(noop?.edit, undefined);
+  engine.remember(noop!);
+  assert.equal(engine.repeatAt("abc", at), undefined);
+  const x = engine.input("x", "👩‍💻ab", at)!;
+  engine.remember(x);
+  assert.deepEqual(engine.repeatAt("éz", at)?.edit?.end, { line: 0, col: 1 });
+  engine.input("y", "hi\nthere", at); engine.input("y", "hi\nthere", at);
+  const paste = engine.input("p", "a\nb", at)!;
+  engine.remember(paste);
+  assert.equal(engine.repeatAt("é\nz", at)?.edit?.text, "hi\n");
+  const join = engine.input("J", "a\nb\nc", at)!;
+  engine.remember(join);
+  assert.equal(engine.repeatAt("é\nz", at)?.edit?.text, "é z");
+  engine.input(">", "a\nb", at);
+  engine.remember(engine.input(">", "a\nb", at)!);
+  assert.equal(engine.repeatAt("é\nz", at)?.edit?.text, "  é");
+});
+
+test("cancel and failed motions never overwrite register or mutate paste markers", () => {
+  const engine = new VimOperatorEngine();
+  const pos = { line: 0, col: 0 };
+  assert.deepEqual(engine.input("d", "abc", pos), { handled: true });
+  assert.equal(engine.cancel(), true);
+  assert.equal(engine.input("w", "abc", pos), null);
+  assert.deepEqual(engine.input("p", "abc", pos), { handled: true });
+  const text = "a[paste #1 1001 chars]b";
+  const end = text.indexOf("b");
+  const markerStart = { line: 0, col: 1 };
+  assert.deepEqual(engine.input("d", text, markerStart, [[0, 1, end, text.length]]), { handled: true });
+  assert.deepEqual(engine.input("w", text, markerStart, [[0, 1, end, text.length]]), { handled: true });
+  assert.deepEqual(engine.input("p", text, pos), { handled: true });
+});

package/tests/vim-policy.test.ts

@@ -0,0 +1,19 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import test from "node:test";
+import { resolveVimPolicy, writeVimPolicy } from "../lib/vim-policy.ts";
+
+test("vim preference defaults off, persists strictly, and fails closed on malformed input", () => {
+	const home = mkdtempSync(join(tmpdir(), "gentle-vim-"));
+	const options = { gentlePiConfigHome: home };
+	assert.equal(resolveVimPolicy(options).policy, "off");
+	assert.equal(resolveVimPolicy(options).source, "default");
+	writeVimPolicy("on", options);
+	assert.equal(resolveVimPolicy(options).policy, "on");
+	assert.equal(JSON.parse(readFileSync(join(home, "vim.json"), "utf8")).schema, "gentle-pi.vim/v1");
+	writeFileSync(join(home, "vim.json"), '{"schema":"gentle-pi.vim/v1","policy":"on","extra":true}');
+	assert.equal(resolveVimPolicy(options).policy, "off");
+	assert.equal(resolveVimPolicy(options).malformed, true);
+});

package/tests/vim-visual-engine.test.ts

@@ -0,0 +1,52 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { VimVisualEngine } from "../lib/vim-visual-engine.ts";
+
+const bounds = (text: string) => text.split("\n").map((line) => [...new Intl.Segmenter(undefined, { granularity: "grapheme" }).segment(line)].map((unit) => unit.index).concat(line.length));
+
+test("character selection includes the moving grapheme, crosses newlines, and swaps its anchor", () => {
+  const engine = new VimVisualEngine();
+  const text = "a👩‍💻\néx";
+  const stops = bounds(text);
+  engine.start("char", { line: 0, col: 1 });
+  assert.deepEqual(engine.range(text, { line: 0, col: 1 }, stops), { start: { line: 0, col: 1 }, end: { line: 0, col: 6 }, linewise: false });
+  assert.deepEqual(engine.range(text, { line: 1, col: 0 }, stops), { start: { line: 0, col: 1 }, end: { line: 1, col: 1 }, linewise: false });
+  assert.deepEqual(engine.swap({ line: 1, col: 0 }), { line: 0, col: 1 });
+  assert.deepEqual(engine.range(text, { line: 0, col: 1 }, stops), { start: { line: 0, col: 1 }, end: { line: 1, col: 1 }, linewise: false });
+  engine.cancel();
+  assert.equal(engine.range(text, { line: 0, col: 0 }, stops), undefined);
+});
+
+test("visual objects resolve word, WORD, quotes and nested brackets across graphemes and lines", () => {
+  const engine = new VimVisualEngine();
+  const text = 'a👩‍💻b rest\n(é [two]) "hi"';
+  const stops = bounds(text);
+  engine.start("char", { line: 0, col: 1 });
+  assert.deepEqual(engine.object(text, { line: 0, col: 1 }, stops, "i", "w"), {
+    start: { line: 0, col: 1 }, end: { line: 0, col: 6 }, linewise: false,
+  });
+  assert.deepEqual(engine.object(text, { line: 0, col: 1 }, stops, "a", "W")?.end, { line: 0, col: 8 });
+  assert.deepEqual(engine.object(text, { line: 1, col: 5 }, stops, "i", "("), {
+    start: { line: 1, col: 1 }, end: { line: 1, col: 8 }, linewise: false,
+  });
+  assert.deepEqual(engine.object(text, { line: 1, col: 11 }, stops, "a", '"'), {
+    start: { line: 1, col: 10 }, end: { line: 1, col: 14 }, linewise: false,
+  });
+  assert.equal(engine.object(text, { line: 1, col: 0 }, stops, "i", '"'), undefined);
+  assert.equal(engine.object(text, { line: 0, col: 0 }, stops, "i", "["), undefined);
+  assert.equal(engine.object("(one\ntwo)", { line: 1, col: 1 }, bounds("(one\ntwo)"), "i", "(")?.end.line, 1);
+  const across = "(one\nnext\n)";
+  assert.deepEqual(engine.object(across, { line: 0, col: 1 }, bounds(across), "i", "("), {
+    start: { line: 0, col: 1 }, end: { line: 2, col: 0 }, linewise: false,
+  });
+  engine.start("char", { line: 0, col: 1 });
+  assert.deepEqual(engine.range(across, { line: 1, col: 4 }, bounds(across))?.end, { line: 2, col: 0 });
+});
+
+test("line selection includes complete lines even at the final line without a newline", () => {
+  const engine = new VimVisualEngine();
+  engine.start("line", { line: 1, col: 1 });
+  assert.deepEqual(engine.range("one\ntwo\nthree", { line: 2, col: 2 }, bounds("one\ntwo\nthree")), {
+    start: { line: 1, col: 0 }, end: { line: 2, col: 5 }, linewise: true,
+  });
+});

package/tests/visual-customization-policy.test.ts

@@ -0,0 +1,139 @@
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+import { DEFAULT_VISUAL_SETTINGS, DENSITY, HEADER_PLACEMENT, parseVisualSettingsFile, resolveVisualSettings, STATUS_PLACEMENT, VISUAL_SECTION_KEYS, writeVisualSettings, VISUAL_SCHEMA } from "../lib/visual-customization-policy.ts";
+
+test("missing settings use responsive defaults and return independent copies", () => {
+	const home = mkdtempSync(join(tmpdir(), "visual-policy-"));
+	try {
+		const resolved = resolveVisualSettings({ gentlePiConfigHome: home });
+		assert.deepEqual(resolved.settings, DEFAULT_VISUAL_SETTINGS);
+		assert.equal(DEFAULT_VISUAL_SETTINGS.statusPlacement, "auto");
+		assert.equal(DEFAULT_VISUAL_SETTINGS.headerPlacement, "top");
+		assert.equal(DEFAULT_VISUAL_SETTINGS.density, "comfortable");
+		assert.deepEqual(DEFAULT_VISUAL_SETTINGS.visibility, { changes: true, rdd: true, agents: true, todo: true, usageCost: true, modelDetails: true, contextWarning: true });
+		resolved.settings.visibility.agents = false;
+		assert.equal(DEFAULT_VISUAL_SETTINGS.visibility.agents, true);
+		assert.equal(resolveVisualSettings({ gentlePiConfigHome: home }).settings.visibility.agents, true);
+	} finally { rmSync(home, { recursive: true, force: true }); }
+});
+
+test("strict versioned parsing rejects malformed and partial settings", () => {
+	const valid = { schema: VISUAL_SCHEMA, ...DEFAULT_VISUAL_SETTINGS };
+	assert.deepEqual(parseVisualSettingsFile(JSON.stringify(valid)), DEFAULT_VISUAL_SETTINGS);
+	for (const value of ["{", "null", "[]", JSON.stringify({ ...valid, schema: "future" }), JSON.stringify({ ...valid, density: "dense" }), JSON.stringify({ ...valid, visibility: { ...valid.visibility, todo: "yes" } }), JSON.stringify({ ...valid, extra: 1 }), JSON.stringify({ ...valid, visibility: { changes: true } })]) {
+		assert.equal(parseVisualSettingsFile(value), undefined);
+	}
+});
+
+test("Sections rows follow one ordered key list that covers every visibility key", () => {
+	assert.deepEqual(VISUAL_SECTION_KEYS, ["changes", "rdd", "agents", "todo", "usageCost", "modelDetails", "contextWarning"]);
+	assert.deepEqual([...VISUAL_SECTION_KEYS].sort(), Object.keys(DEFAULT_VISUAL_SETTINGS.visibility).sort());
+});
+
+test("settings saved before the rdd section existed load as valid with rdd shown", () => {
+	const legacy = { schema: VISUAL_SCHEMA, ...DEFAULT_VISUAL_SETTINGS, visibility: { changes: false, agents: true, todo: false, usageCost: true, modelDetails: false } };
+	const expected = { ...DEFAULT_VISUAL_SETTINGS, visibility: { changes: false, rdd: true, agents: true, todo: false, usageCost: true, modelDetails: false, contextWarning: true } };
+	assert.deepEqual(parseVisualSettingsFile(JSON.stringify(legacy)), expected);
+	assert.deepEqual(parseVisualSettingsFile(JSON.stringify({ ...legacy, visibility: { ...expected.visibility, rdd: false } })), { ...expected, visibility: { ...expected.visibility, rdd: false } });
+	for (const visibility of [{ ...legacy.visibility, extra: true }, { ...legacy.visibility, rdd: "no" }, { ...legacy.visibility, todo: "yes" }, { agents: true, todo: true, usageCost: true, modelDetails: true, rdd: true }]) {
+		assert.equal(parseVisualSettingsFile(JSON.stringify({ ...legacy, visibility })), undefined);
+	}
+	const home = mkdtempSync(join(tmpdir(), "visual-policy-"));
+	try {
+		writeFileSync(join(home, "visual-customization.json"), JSON.stringify(legacy));
+		const resolved = resolveVisualSettings({ gentlePiConfigHome: home });
+		assert.equal(resolved.malformed, false);
+		assert.deepEqual(resolved.settings, expected);
+		const { rdd: _rdd, ...legacyVisibility } = expected.visibility;
+		assert.throws(() => writeVisualSettings({ ...expected, visibility: legacyVisibility } as typeof expected), /Invalid visual settings/);
+	} finally { rmSync(home, { recursive: true, force: true }); }
+});
+
+test("settings saved before contextWarning existed load it shown and preserve rdd", () => {
+	// Both historical shapes: the earliest pre-rdd visibility and the previous-current shape that
+	// already had rdd but not contextWarning. Only the missing added keys default to shown.
+	const shared = { schema: VISUAL_SCHEMA, ...DEFAULT_VISUAL_SETTINGS };
+	const preRdd = { ...shared, visibility: { changes: false, agents: true, todo: false, usageCost: true, modelDetails: false } };
+	assert.deepEqual(parseVisualSettingsFile(JSON.stringify(preRdd)), { ...DEFAULT_VISUAL_SETTINGS,
+		visibility: { changes: false, rdd: true, agents: true, todo: false, usageCost: true, modelDetails: false, contextWarning: true } });
+	const preContext = { ...shared, visibility: { changes: false, rdd: false, agents: true, todo: false, usageCost: true, modelDetails: false } };
+	assert.deepEqual(parseVisualSettingsFile(JSON.stringify(preContext)), { ...DEFAULT_VISUAL_SETTINGS,
+		visibility: { changes: false, rdd: false, agents: true, todo: false, usageCost: true, modelDetails: false, contextWarning: true } });
+	const withoutRdd = { ...shared, visibility: { changes: true, agents: true, todo: true, usageCost: true, modelDetails: true, contextWarning: false } };
+	assert.deepEqual(parseVisualSettingsFile(JSON.stringify(withoutRdd)), { ...DEFAULT_VISUAL_SETTINGS,
+		visibility: { changes: true, rdd: true, agents: true, todo: true, usageCost: true, modelDetails: true, contextWarning: false } });
+});
+
+test("a present non-boolean added key in a partial legacy shape is rejected before default fill", () => {
+	// Missing added keys default to shown, but a key that is present must already be a
+	// boolean: `null` (or any other value) must not be silently coerced by the fill.
+	const base = { changes: true, agents: true, todo: true, usageCost: true, modelDetails: true };
+	for (const visibility of [{ ...base, rdd: null }, { ...base, contextWarning: null }]) {
+		assert.equal(parseVisualSettingsFile(JSON.stringify({ schema: VISUAL_SCHEMA, ...DEFAULT_VISUAL_SETTINGS, visibility })), undefined,
+			`${JSON.stringify(visibility)} must stay invalid`);
+	}
+	const previousCurrent = structuredClone(DEFAULT_VISUAL_SETTINGS) as unknown as { visibility: Record<string, unknown> };
+	delete previousCurrent.visibility.contextWarning;
+	previousCurrent.visibility.rdd = null;
+	assert.equal(parseVisualSettingsFile(JSON.stringify({ schema: VISUAL_SCHEMA, ...previousCurrent })), undefined);
+});
+
+test("an unreadable settings path is a read error, not malformed content", () => {
+	const home = mkdtempSync(join(tmpdir(), "visual-policy-"));
+	try {
+		mkdirSync(join(home, "visual-customization.json"));
+		const result = resolveVisualSettings({ gentlePiConfigHome: home });
+		assert.equal(result.malformed, false);
+		assert.equal(result.readError, true);
+		assert.equal(result.source, "global_file");
+		assert.deepEqual(result.settings, DEFAULT_VISUAL_SETTINGS);
+	} finally { rmSync(home, { recursive: true, force: true }); }
+});
+
+test("failed rename preserves the destination and removes the temporary file", () => {
+	const home = mkdtempSync(join(tmpdir(), "visual-policy-"));
+	try {
+		const destination = join(home, "visual-customization.json");
+		mkdirSync(destination);
+		assert.throws(() => writeVisualSettings(DEFAULT_VISUAL_SETTINGS, { gentlePiConfigHome: home }));
+		assert.deepEqual(readdirSync(home), ["visual-customization.json"]);
+		assert.equal(statSync(destination).isDirectory(), true);
+	} finally { rmSync(home, { recursive: true, force: true }); }
+});
+
+test("each placement and density value survives a versioned write and read", () => {
+	const home = mkdtempSync(join(tmpdir(), "visual-policy-"));
+	try {
+		for (const statusPlacement of Object.values(STATUS_PLACEMENT)) {
+			for (const headerPlacement of Object.values(HEADER_PLACEMENT)) {
+				for (const density of Object.values(DENSITY)) {
+					const settings = { ...DEFAULT_VISUAL_SETTINGS, statusPlacement, headerPlacement, density };
+					writeVisualSettings(settings, { gentlePiConfigHome: home });
+					assert.deepEqual(resolveVisualSettings({ gentlePiConfigHome: home }).settings, settings);
+				}
+			}
+		}
+	} finally { rmSync(home, { recursive: true, force: true }); }
+});
+
+test("atomic write round trips and invalid existing files fall back without overwriting", () => {
+	const home = mkdtempSync(join(tmpdir(), "visual-policy-"));
+	try {
+		const settings = { ...DEFAULT_VISUAL_SETTINGS, statusPlacement: "hidden" as const, headerPlacement: "below-input" as const, density: "minimal" as const, visibility: { ...DEFAULT_VISUAL_SETTINGS.visibility, agents: false } };
+		const path = writeVisualSettings(settings, { gentlePiConfigHome: home });
+		assert.equal(path, join(home, "visual-customization.json"));
+		if (process.platform !== "win32") assert.equal(statSync(path).mode & 0o777, 0o600);
+		assert.deepEqual(resolveVisualSettings({ gentlePiConfigHome: home }).settings, settings);
+		assert.deepEqual(JSON.parse(readFileSync(path, "utf8")), { schema: VISUAL_SCHEMA, ...settings });
+		const validFile = readFileSync(path, "utf8");
+		assert.throws(() => writeVisualSettings({ ...settings, density: "bad" as typeof settings.density }, { gentlePiConfigHome: home }));
+		assert.equal(readFileSync(path, "utf8"), validFile);
+		writeFileSync(path, "broken");
+		assert.deepEqual(resolveVisualSettings({ gentlePiConfigHome: home }).settings, DEFAULT_VISUAL_SETTINGS);
+		assert.equal(resolveVisualSettings({ gentlePiConfigHome: home }).malformed, true);
+		assert.equal(readFileSync(path, "utf8"), "broken");
+	} finally { rmSync(home, { recursive: true, force: true }); }
+});