ompchamber 2.0.2 → 3.1.0

package/src/shared/lib/code/editor/keymap.ts

@@ -0,0 +1,151 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The code editor's keymap, as data.
+ *
+ * One table is the whole truth about an editor shortcut: what it does, which
+ * chords reach it on each platform, and what the palette calls it. The
+ * textarea's handler, the find bar's buttons, the tooltips and the command
+ * palette all read this table, so a shortcut cannot be listed in the palette
+ * and unbound in the editor.
+ *
+ * VS Code's defaults are followed wherever this editor has an equivalent. Where
+ * it has none — folding, go-to-definition, the `⌘K` prefix chords — the command
+ * is absent rather than bound to something that would surprise.
+ */
+
+import type { KeyBinding, KeyStroke } from '@/shared/lib/ui/key-binding';
+
+export type EditorCommand =
+  | 'find'
+  | 'replace'
+  | 'nextMatch'
+  | 'previousMatch'
+  | 'replaceOne'
+  | 'replaceAll'
+  | 'toggleCaseSensitive'
+  | 'toggleWholeWord'
+  | 'toggleRegex'
+  | 'toggleWordWrap'
+  | 'selectNextOccurrence'
+  | 'selectAllOccurrences'
+  | 'insertCursorBelow'
+  | 'moveLineUp'
+  | 'moveLineDown'
+  | 'copyLineUp'
+  | 'copyLineDown'
+  | 'deleteLine'
+  | 'toggleComment'
+  | 'insertLineBelow'
+  | 'insertLineAbove'
+  | 'indent'
+  | 'outdent'
+  | 'undo'
+  | 'redo'
+  | 'lineStart'
+  | 'lineEnd'
+  | 'documentStart'
+  | 'documentEnd'
+  | 'selectToLineStart'
+  | 'selectToLineEnd'
+  | 'selectToDocumentStart'
+  | 'selectToDocumentEnd'
+  | 'selectWord'
+  | 'selectLine'
+  | 'escape';
+
+/**
+ * The editor keymap.
+ *
+ * Every entry carries both platforms even when the chords are identical,
+ * because the label is DERIVED from the stroke rather than written twice — a
+ * hand-written "Ctrl+F" beside a binding that listens for ⌘F is exactly the
+ * drift this table exists to prevent.
+ */
+export const EDITOR_KEY_BINDINGS: readonly KeyBinding<EditorCommand>[] = [
+  { command: 'find', label: 'Find', mac: { code: 'KeyF', meta: true }, other: { code: 'KeyF', ctrl: true } },
+  { command: 'replace', label: 'Replace', mac: { code: 'KeyF', meta: true, alt: true }, other: { code: 'KeyH', ctrl: true } },
+  { command: 'nextMatch', label: 'Next match', mac: { code: 'F3' }, other: { code: 'F3' } },
+  { command: 'previousMatch', label: 'Previous match', mac: { code: 'F3', shift: true }, other: { code: 'F3', shift: true } },
+  { command: 'replaceOne', label: 'Replace current match', mac: { code: 'Digit1', meta: true, shift: true }, other: { code: 'Digit1', ctrl: true, shift: true } },
+  { command: 'replaceAll', label: 'Replace all matches', mac: { code: 'Enter', meta: true, alt: true }, other: { code: 'Enter', ctrl: true, alt: true } },
+  { command: 'toggleCaseSensitive', label: 'Match case', mac: { code: 'KeyC', meta: true, alt: true }, other: { code: 'KeyC', alt: true } },
+  { command: 'toggleWholeWord', label: 'Match whole word', mac: { code: 'KeyW', meta: true, alt: true }, other: { code: 'KeyW', alt: true } },
+  { command: 'toggleRegex', label: 'Use regular expression', mac: { code: 'KeyR', meta: true, alt: true }, other: { code: 'KeyR', alt: true } },
+  { command: 'toggleWordWrap', label: 'Toggle word wrap', mac: { code: 'KeyZ', alt: true }, other: { code: 'KeyZ', alt: true } },
+
+  { command: 'selectNextOccurrence', label: 'Add selection to next find match', mac: { code: 'KeyD', meta: true }, other: { code: 'KeyD', ctrl: true } },
+  { command: 'selectAllOccurrences', label: 'Select all occurrences of current selection', mac: { code: 'KeyL', meta: true, shift: true }, other: { code: 'KeyL', ctrl: true, shift: true } },
+  { command: 'insertCursorBelow', label: 'Insert cursor below', mac: { code: 'KeyD', meta: true, shift: true }, other: { code: 'KeyD', ctrl: true, shift: true } },
+
+  { command: 'moveLineUp', label: 'Move line up', mac: { code: 'ArrowUp', alt: true }, other: { code: 'ArrowUp', alt: true } },
+  { command: 'moveLineDown', label: 'Move line down', mac: { code: 'ArrowDown', alt: true }, other: { code: 'ArrowDown', alt: true } },
+  { command: 'copyLineUp', label: 'Copy line up', mac: { code: 'ArrowUp', meta: true, alt: true, shift: true }, other: { code: 'ArrowUp', ctrl: true, alt: true, shift: true } },
+  { command: 'copyLineDown', label: 'Copy line down', mac: { code: 'ArrowDown', meta: true, alt: true, shift: true }, other: { code: 'ArrowDown', ctrl: true, alt: true, shift: true } },
+  // `⇧⌘K` on macOS; VS Code's Windows/Linux chord is the two-stroke `Ctrl+K Ctrl+K`,
+  // which a single-stroke table cannot express, so the mac chord is used there too.
+  { command: 'deleteLine', label: 'Delete line', mac: { code: 'KeyK', meta: true, shift: true }, other: { code: 'KeyK', ctrl: true, shift: true } },
+  // `Slash` is a physical key: on a US layout that is `/`, elsewhere it is
+  // wherever the user's own layout puts it.
+  { command: 'toggleComment', label: 'Toggle line comment', mac: { code: 'Slash', meta: true }, other: { code: 'Slash', ctrl: true } },
+
+  { command: 'insertLineBelow', label: 'Insert line below', mac: { code: 'Enter', meta: true }, other: { code: 'Enter', ctrl: true } },
+  { command: 'insertLineAbove', label: 'Insert line above', mac: { code: 'Enter', meta: true, shift: true }, other: { code: 'Enter', ctrl: true, shift: true } },
+
+  { command: 'indent', label: 'Indent line', mac: { code: 'BracketRight', meta: true }, other: { code: 'BracketRight', ctrl: true } },
+  { command: 'outdent', label: 'Outdent line', mac: { code: 'BracketLeft', meta: true }, other: { code: 'BracketLeft', ctrl: true } },
+
+  { command: 'undo', label: 'Undo', mac: { code: 'KeyZ', meta: true }, other: { code: 'KeyZ', ctrl: true } },
+  {
+    command: 'redo',
+    label: 'Redo',
+    mac: { code: 'KeyZ', meta: true, shift: true },
+    other: { code: 'KeyZ', ctrl: true, shift: true },
+    windows: { code: 'KeyY', ctrl: true },
+  },
+
+  { command: 'lineStart', label: 'Go to line start', mac: { code: 'ArrowLeft', meta: true }, other: { code: 'Home' } },
+  { command: 'lineEnd', label: 'Go to line end', mac: { code: 'ArrowRight', meta: true }, other: { code: 'End' } },
+  { command: 'documentStart', label: 'Go to file start', mac: { code: 'ArrowUp', meta: true }, other: { code: 'ArrowUp', ctrl: true } },
+  { command: 'documentEnd', label: 'Go to file end', mac: { code: 'ArrowDown', meta: true }, other: { code: 'ArrowDown', ctrl: true } },
+  { command: 'selectToLineStart', label: 'Select to line start', mac: { code: 'ArrowLeft', meta: true, shift: true }, other: { code: 'ArrowLeft', ctrl: true, shift: true } },
+  { command: 'selectToLineEnd', label: 'Select to line end', mac: { code: 'ArrowRight', meta: true, shift: true }, other: { code: 'ArrowRight', ctrl: true, shift: true } },
+  { command: 'selectToDocumentStart', label: 'Select to file start', mac: { code: 'ArrowUp', meta: true, shift: true }, other: { code: 'ArrowUp', ctrl: true, shift: true } },
+  { command: 'selectToDocumentEnd', label: 'Select to file end', mac: { code: 'ArrowDown', meta: true, shift: true }, other: { code: 'ArrowDown', ctrl: true, shift: true } },
+];
+
+/**
+ * Commands the FIND BAR handles: the editor panel dispatches these to the find
+ * hook rather than running them against the buffer itself.
+ */
+export const FIND_BAR_COMMANDS: readonly EditorCommand[] = [
+  'find',
+  'replace',
+  'nextMatch',
+  'previousMatch',
+  'replaceOne',
+  'replaceAll',
+  'toggleCaseSensitive',
+  'toggleWholeWord',
+  'toggleRegex',
+  'toggleWordWrap',
+];
+
+/** Membership test for a call site that has a command and wants a yes/no. */
+const FIND_BAR_SET: Record<string, true> = Object.fromEntries(FIND_BAR_COMMANDS.map((command) => [command, true]));
+
+export function isFindBarCommand(command: EditorCommand): boolean {
+  return FIND_BAR_SET[command] === true;
+}
+
+/** The chord for a command on the current platform. */
+export function editorStrokeFor(command: EditorCommand, isMac: boolean, isWindows: boolean): KeyStroke | null {
+  const binding = EDITOR_KEY_BINDINGS.find((entry) => entry.command === command);
+  if (!binding) return null;
+  if (isMac) return binding.mac;
+  if (binding.windows && isWindows) return binding.windows;
+  return binding.other;
+}

package/src/shared/lib/code/editor/layers.test.ts

@@ -0,0 +1,77 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The two-layer alignment contract.
+ *
+ * The transparent `<textarea>` sits exactly on top of the highlighted `<pre>`,
+ * so any typographic property that differs between them puts the caret on a
+ * different row than the glyphs. These assertions pin the two things that
+ * matter: both layers inherit their typography (a second copy of the font stack
+ * is what makes them drift), and the `<pre>` reserves the unrendered lines as
+ * padding while the textarea keeps the plain inset.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { layerStyle, layerStyles } from '@/shared/lib/code/editor/layers';
+
+describe('layerStyle', () => {
+  test('inherits every typographic property rather than restating it', () => {
+    const style = layerStyle();
+
+    for (const property of ['fontFamily', 'fontSize', 'lineHeight', 'letterSpacing', 'tabSize'] as const) {
+      expect(style[property]).toBe('inherit');
+    }
+  });
+
+  test('breaks words the same way the gutter measured them', () => {
+    // The measurement mirror copies these from the editor's computed style; a
+    // layer that broke differently would put the numbers on the wrong rows.
+    const style = layerStyle();
+
+    expect(style.whiteSpace).toBe('pre-wrap');
+    expect(style.overflowWrap).toBe('break-word');
+    expect(style.wordBreak).toBe('keep-all');
+  });
+
+  test('takes its box from the caller, not from the UA', () => {
+    const style = layerStyle();
+
+    expect(style.boxSizing).toBe('inherit');
+    expect(style.display).toBe('inherit');
+    expect(style.margin).toBe(0);
+    expect(style.border).toBe(0);
+  });
+});
+
+describe('layerStyles', () => {
+  test('both layers carry the caller’s padding', () => {
+    const { pre, textarea } = layerStyles(16, null);
+
+    expect(textarea.paddingTop).toBe(16);
+    expect(textarea.paddingLeft).toBe(16);
+    expect(pre.paddingTop).toBe(16);
+    expect(pre.paddingBottom).toBe(16);
+  });
+
+  test('the pre reserves the unrendered lines as padding', () => {
+    // Windowing is the whole trick: the textarea holds the document, the pre
+    // holds a slice of it, and the space of everything else is this padding.
+    const { pre, textarea } = layerStyles(8, { start: 100, end: 120, top: 900, bottom: 200, breakAtEnd: false });
+
+    expect(pre.paddingTop).toBe(908);
+    expect(pre.paddingBottom).toBe(208);
+    expect(textarea.paddingTop).toBe(8);
+    expect(textarea.paddingBottom).toBe(8);
+  });
+
+  test('a window without space leaves the plain inset', () => {
+    const { pre } = layerStyles(4, { start: 0, end: 10, top: 0, bottom: 0, breakAtEnd: true });
+
+    expect(pre.paddingTop).toBe(4);
+    expect(pre.paddingBottom).toBe(4);
+  });
+});

package/src/shared/lib/code/editor/layers.ts

@@ -0,0 +1,67 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The inline styles that keep the editor's two layers in register.
+ *
+ * The transparent `<textarea>` (which owns the caret, the selection and every
+ * keystroke) sits exactly on top of the `<pre>` (which paints the glyphs), so
+ * both must lay text out identically: `layerStyles` is the shared half —
+ * every typographic property inherits rather than being restated, because a
+ * second copy of the font stack is what makes the two drift.
+ *
+ * The `<pre>` additionally carries the space of the lines the window is not
+ * rendering, as padding, which is the whole trick behind the lazy surface: the
+ * textarea still holds every line, so the caret lands where the reader expects
+ * without the highlighter ever tokenizing the rest of the document.
+ */
+
+import type { CSSProperties } from 'preact';
+import type { CodeWindow } from '@/shared/lib/code/lazy-window';
+
+/** The shared typography, inherited from the caller's own class. */
+export function layerStyle(): CSSProperties {
+  return {
+    margin: 0,
+    border: 0,
+    background: 'none',
+    boxSizing: 'inherit',
+    display: 'inherit',
+    fontFamily: 'inherit',
+    fontSize: 'inherit',
+    fontStyle: 'inherit',
+    fontVariantLigatures: 'inherit',
+    fontWeight: 'inherit',
+    letterSpacing: 'inherit',
+    lineHeight: 'inherit',
+    tabSize: 'inherit',
+    textIndent: 'inherit',
+    textRendering: 'inherit',
+    textTransform: 'inherit',
+    whiteSpace: 'pre-wrap',
+    wordBreak: 'keep-all',
+    overflowWrap: 'break-word',
+  };
+}
+
+/** The plain inset both layers take; `padding` is the editor's own padding. */
+function contentStyle(padding: number): CSSProperties {
+  return { paddingTop: padding, paddingRight: padding, paddingBottom: padding, paddingLeft: padding };
+}
+
+/** Both layers' styles for one render: the shared typography plus each one's box. */
+export function layerStyles(padding: number, virtual: CodeWindow | null | undefined) {
+  const content = contentStyle(padding);
+  return {
+    /** Textarea: the full document, so its padding is the plain inset. */
+    textarea: content,
+    /** `<pre>`: the window, with the unrendered lines reserved as padding. */
+    pre: {
+      ...content,
+      paddingTop: padding + (virtual?.top ?? 0),
+      paddingBottom: padding + (virtual?.bottom ?? 0),
+    },
+  };
+}

package/src/shared/lib/code/editor/line-edits.test.ts

@@ -0,0 +1,131 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The line commands: move, duplicate, delete, insert, and the caret's line
+ * edges.
+ *
+ * The cases that matter are the document's edges — the first and last line have
+ * no neighbour to swap with, a last line with no trailing newline still needs its
+ * own separator, and a line deleted rather than blanked. Each of those was a
+ * visible bug in the naive concatenation.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { deleteLines, duplicateLines, insertLine, lineEdges, moveLines } from '@/shared/lib/code/editor/line-edits';
+
+describe('moveLines', () => {
+  test('moves the block up and carries the selection with it', () => {
+    const result = moveLines('one\ntwo\nthree', { start: 4, end: 8 }, -1);
+
+    expect(result.value).toBe('two\none\nthree');
+    expect([result.selectionStart, result.selectionEnd]).toEqual([0, 4]);
+  });
+
+  test('moves the block down', () => {
+    const result = moveLines('one\ntwo\nthree', { start: 4, end: 8 }, 1);
+
+    expect(result.value).toBe('one\nthree\ntwo');
+    expect([result.selectionStart, result.selectionEnd]).toEqual([10, 14]);
+  });
+
+  test('a block already at the edge does not move', () => {
+    const first = moveLines('one\ntwo', { start: 0, end: 4 }, -1);
+    expect(first.value).toBe('one\ntwo');
+    expect(first.selectionStart).toBe(0);
+
+    const last = moveLines('one\ntwo', { start: 4, end: 7 }, 1);
+    expect(last.value).toBe('one\ntwo');
+  });
+
+  test('moving several lines keeps them together', () => {
+    const result = moveLines('a\nb\nc\nd', { start: 2, end: 6 }, 1);
+
+    expect(result.value).toBe('a\nd\nb\nc');
+  });
+});
+
+describe('duplicateLines', () => {
+  test('copies the line below and leaves the original selected', () => {
+    const result = duplicateLines('one\ntwo', { start: 0, end: 4 }, 1);
+
+    expect(result.value).toBe('one\none\ntwo');
+    expect([result.selectionStart, result.selectionEnd]).toEqual([0, 4]);
+  });
+
+  test('copies above and selects the copy', () => {
+    const result = duplicateLines('one\ntwo', { start: 4, end: 7 }, -1);
+
+    expect(result.value).toBe('one\ntwo\ntwo');
+    expect([result.selectionStart, result.selectionEnd]).toEqual([8, 11]);
+  });
+
+  test('a last line with no trailing newline still gets its own line', () => {
+    const result = duplicateLines('one\ntwo', { start: 4, end: 7 }, 1);
+
+    expect(result.value).toBe('one\ntwo\ntwo');
+  });
+});
+
+describe('deleteLines', () => {
+  test('removes the line rather than blanking it', () => {
+    const result = deleteLines('one\ntwo\nthree', { start: 4, end: 8 });
+
+    expect(result.value).toBe('one\nthree');
+    expect(result.selectionStart).toBe(4);
+  });
+
+  test('deleting the last line leaves the caret at the buffer end', () => {
+    const result = deleteLines('one\ntwo', { start: 4, end: 7 });
+
+    expect(result.value).toBe('one\n');
+    expect(result.selectionStart).toBe(4);
+  });
+
+  test('deleting a multi-line block removes all of it', () => {
+    const result = deleteLines('a\nb\nc\nd', { start: 2, end: 6 });
+
+    expect(result.value).toBe('a\nd');
+  });
+});
+
+describe('insertLine', () => {
+  test('opens a line below, keeping the indentation', () => {
+    const result = insertLine('  one\ntwo', 5, 'below');
+
+    expect(result.value).toBe('  one\n  \ntwo');
+    expect(result.selectionStart).toBe(8);
+  });
+
+  test('opens a line above, keeping the indentation', () => {
+    const result = insertLine('  one\ntwo', 5, 'above');
+
+    expect(result.value).toBe('  \n  one\ntwo');
+    expect(result.selectionStart).toBe(2);
+  });
+
+  test('on the buffer’s last line without a trailing newline the line is appended', () => {
+    const result = insertLine('  one', 5, 'below');
+
+    // No trailing newline: the new line simply follows, indented, and the caret
+    // lands after that indent. Writing a second newline (what this used to do)
+    // left a blank line under the caret.
+    expect(result.value).toBe('  one\n  ');
+    expect(result.selectionStart).toBe(8);
+  });
+});
+
+describe('lineEdges', () => {
+  test('reports the start of the line and the end of its content', () => {
+    // The trailing newline is not part of the line's content, so ⌘→ stops
+    // before it rather than on the next line.
+    expect(lineEdges('one\ntwo\n', 5)).toEqual({ start: 4, end: 7 });
+  });
+
+  test('the last line has no newline to exclude', () => {
+    expect(lineEdges('one\ntwo', 5)).toEqual({ start: 4, end: 7 });
+  });
+});

package/src/shared/lib/code/editor/line-edits.ts

@@ -0,0 +1,159 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The editor's line commands: move, duplicate, delete, insert a line, and the
+ * caret's line edges.
+ *
+ * Split from `editor-commands` (which owns the multi-selection and comment
+ * concerns) because the two families have nothing in common beyond both being
+ * pure string arithmetic — and because the repository caps a file at 350 lines.
+ */
+
+import { lineIndexAt, lineRangeAt, lineRangesInSelection, lineStartOffset, type TextRange } from '@/shared/lib/code/editor/lines';
+
+/** The block of lines a selection touches, as ONE range. */
+function selectionBlock(text: string, selection: TextRange): TextRange {
+  const lines = lineRangesInSelection(text, selection);
+  return { start: lines[0].start, end: lines[lines.length - 1].end };
+}
+
+/**
+ * Move the selected lines up (`-1`) or down (`1`).
+ *
+ * The two groups are swapped as a REGION rather than as two concatenations:
+ * the neighbour may be the document's last line with no trailing newline, so
+ * the separator between the swapped halves has to be re-emitted from the
+ * region's own shape. Getting that wrong turns `one\ntwo\nthree` into
+ * `one\nthreetwo` — which is what the naive `body + neighbour` swap produced.
+ *
+ * The selection travels with its lines, so a repeated ⌥↑ keeps moving the same
+ * block. At the document's first/last line there is no neighbour and the buffer
+ * is returned unchanged.
+ */
+export function moveLines(
+  text: string,
+  selection: TextRange,
+  direction: -1 | 1,
+): { value: string; selectionStart: number; selectionEnd: number } {
+  const block = selectionBlock(text, selection);
+  const blockText = text.slice(block.start, block.end);
+  const neighbour = direction === -1 ? lineRangeAt(text, block.start - 1) : lineRangeAt(text, block.end);
+  if (direction === -1 && block.start === 0) {
+    return { value: text, selectionStart: selection.start, selectionEnd: selection.end };
+  }
+  if (direction === 1 && block.end >= text.length) {
+    return { value: text, selectionStart: selection.start, selectionEnd: selection.end };
+  }
+
+  const neighbourText = text.slice(neighbour.start, neighbour.end);
+  // Both groups are whole lines, so each carries at most one trailing newline.
+  const blockBody = blockText.replace(/\n$/, '');
+  const neighbourBody = neighbourText.replace(/\n$/, '');
+  const regionEndsWithNewline = text.slice(Math.min(block.start, neighbour.start), Math.max(block.end, neighbour.end)).endsWith('\n');
+
+  const ordered = direction === -1
+    ? `${blockBody}\n${neighbourBody}`
+    : `${neighbourBody}\n${blockBody}`;
+  const region = ordered + (regionEndsWithNewline ? '\n' : '');
+  const regionStart = Math.min(block.start, neighbour.start);
+  const regionEnd = Math.max(block.end, neighbour.end);
+
+  // The block's own first line moves by exactly the neighbour's length plus the
+  // separator that now precedes it.
+  const shift = neighbourBody.length + 1;
+  const delta = direction === -1 ? -shift : shift;
+  return {
+    value: text.slice(0, regionStart) + region + text.slice(regionEnd),
+    selectionStart: selection.start + delta,
+    selectionEnd: selection.end + delta,
+  };
+}
+
+/** Copy the selected lines below (`1`) or above (`-1`); the copy stays selected. */
+export function duplicateLines(
+  text: string,
+  selection: TextRange,
+  direction: -1 | 1,
+): { value: string; selectionStart: number; selectionEnd: number } {
+  const block = selectionBlock(text, selection);
+  const body = text.slice(block.start, block.end);
+  // A block that reaches the end of a document with no trailing newline needs
+  // one, or the copy would land on the same line it came from.
+  const separator = body.endsWith('\n') ? '' : '\n';
+
+  if (direction === 1) {
+    const inserted = separator + body;
+    return {
+      value: text.slice(0, block.end) + inserted + text.slice(block.end),
+      selectionStart: selection.start,
+      selectionEnd: selection.end,
+    };
+  }
+  const inserted = body + separator;
+  return {
+    value: text.slice(0, block.start) + inserted + text.slice(block.start),
+    selectionStart: selection.start + inserted.length,
+    selectionEnd: selection.end + inserted.length,
+  };
+}
+
+/**
+ * Delete the selected lines, newline included — so the line is gone rather than
+ * blanked. The caret lands at the start of the line that took its place, or at
+ * the end of the buffer when the last line was deleted.
+ */
+export function deleteLines(
+  text: string,
+  selection: TextRange,
+): { value: string; selectionStart: number; selectionEnd: number } {
+  const block = selectionBlock(text, selection);
+  const value = text.slice(0, block.start) + text.slice(block.end);
+  const caret = Math.min(block.start, value.length);
+  return { value, selectionStart: caret, selectionEnd: caret };
+}
+
+/**
+ * Open a new line above or below the caret's line, keeping that line's
+ * indentation. ⌘⏎ is "below" and ⌘⇧⏎ is "above", like VS Code.
+ */
+export function insertLine(
+  text: string,
+  offset: number,
+  where: 'above' | 'below',
+): { value: string; selectionStart: number; selectionEnd: number } {
+  const line = lineRangeAt(text, offset);
+  const lineText = text.slice(line.start, line.end).replace(/\n$/, '');
+  const indent = lineText.match(/^\s*/)?.[0] ?? '';
+
+  if (where === 'above') {
+    const caret = line.start + indent.length;
+    return {
+      value: `${text.slice(0, line.start)}${indent}\n${text.slice(line.start)}`,
+      selectionStart: caret,
+      selectionEnd: caret,
+    };
+  }
+
+  // Below a line that already ends in a newline the new line is inserted
+  // BEFORE that successor; below the document's last line the newline has to be
+  // written first. Emitting both unconditionally left a blank line behind
+  // (measured: `a\nb` + ⌘⏎ became `a\nb\n\n`).
+  const lineEndsWithNewline = text[line.end - 1] === '\n';
+  const inserted = lineEndsWithNewline ? `${indent}\n` : `\n${indent}`;
+  const caret = line.end + inserted.length - (lineEndsWithNewline ? 1 : 0);
+  return {
+    value: text.slice(0, line.end) + inserted + text.slice(line.end),
+    selectionStart: caret,
+    selectionEnd: caret,
+  };
+}
+
+/** The offset at the start of the caret's line, and at the end of it (⌘← / ⌘→). */
+export function lineEdges(text: string, offset: number): { start: number; end: number } {
+  const line = lineRangeAt(text, offset);
+  const start = lineStartOffset(text, lineIndexAt(text, offset));
+  return { start, end: Math.max(start, line.end - (text[line.end - 1] === '\n' ? 1 : 0)) };
+}

package/src/shared/lib/code/editor/lines.test.ts

@@ -0,0 +1,81 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Line arithmetic, which every line command and the gutter depend on agreeing
+ * about. The interesting cases are the two the arithmetic gets wrong by
+ * accident: a caret on the empty line a trailing newline opens, and a selection
+ * that ends exactly at a line start (which does not touch that line).
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  countLines,
+  lineIndexAt,
+  lineRangeAt,
+  lineRangesInSelection,
+  lineStartOffset,
+} from '@/shared/lib/code/editor/lines';
+
+describe('lineIndexAt and lineStartOffset', () => {
+  test('are inverses for every line start', () => {
+    const text = 'one\ntwo\n\nfour';
+    // Line starts in `text`: 0, 4, 8 (the empty line) and 9.
+    for (const offset of [0, 4, 8, 9]) {
+      expect(lineStartOffset(text, lineIndexAt(text, offset))).toBe(offset);
+    }
+    expect(lineIndexAt(text, 13)).toBe(3);
+  });
+
+  test('clamp an offset past the end to the last line', () => {
+    expect(lineIndexAt('one\ntwo', 999)).toBe(1);
+    expect(lineStartOffset('one\ntwo', 99)).toBe(7);
+  });
+
+  test('count a trailing newline as opening one more, empty line', () => {
+    expect(countLines('one\ntwo')).toBe(2);
+    expect(countLines('one\ntwo\n')).toBe(3);
+    expect(countLines('')).toBe(1);
+  });
+});
+
+describe('lineRangeAt', () => {
+  test('includes the trailing newline, so the range can delete or move the line', () => {
+    expect(lineRangeAt('one\ntwo\nthree', 5)).toEqual({ start: 4, end: 8 });
+  });
+
+  test('the last line has no newline to include', () => {
+    expect(lineRangeAt('one\ntwo', 5)).toEqual({ start: 4, end: 7 });
+  });
+
+  test('a caret on the empty line a trailing newline opens yields an empty range there', () => {
+    // `a\n` has an empty second line at offset 2; the honest reading of that
+    // position is "no characters of its own", not the previous line.
+    expect(lineRangeAt('a\n', 2)).toEqual({ start: 2, end: 2 });
+  });
+});
+
+describe('lineRangesInSelection', () => {
+  test('covers every line the selection touches', () => {
+    const text = 'one\ntwo\nthree';
+    expect(lineRangesInSelection(text, { start: 4, end: 7 })).toEqual([{ start: 4, end: 8 }]);
+    expect(lineRangesInSelection(text, { start: 0, end: 7 })).toEqual([
+      { start: 0, end: 4 },
+      { start: 4, end: 8 },
+    ]);
+  });
+
+  test('a selection ending exactly at a line start does not touch that line', () => {
+    // The rule VS Code applies, and the one that keeps a whole-line selection
+    // from splitting off an empty trailing entry.
+    const text = 'one\ntwo';
+    expect(lineRangesInSelection(text, { start: 0, end: 4 })).toEqual([{ start: 0, end: 4 }]);
+  });
+
+  test('an empty selection still names the line the caret is on', () => {
+    expect(lineRangesInSelection('one\ntwo', { start: 5, end: 5 })).toEqual([{ start: 4, end: 7 }]);
+  });
+});