@kabmo-labs/kabmo 0.0.0-stage → 0.1.0

package/src/shared/lib/code/language.ts

@@ -0,0 +1,165 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Language detection for the highlighter: which Shiki grammar a path maps to,
+ * and whether a block of text looks like code at all.
+ *
+ * Both are pure string predicates over the input, with no highlighter state, so
+ * they live beside the tokenizer rather than inside it — the tokenizer needs a
+ * booted Shiki instance, these do not, and a caller that only wants to pick a
+ * language (a tool card deciding whether to render a code surface) does not
+ * have to pull one in.
+ */
+
+import { stripReadSelector } from '@/shared/lib/fs/paths';
+
+/**
+ * Map a path to a Shiki language id.
+ *
+ * `text` is the answer for a path that names no language: an extensionless
+ * file (`src/bin/run`), an internal URL (`xd://eval/browser`, `skill://diagnose`,
+ * `omp://`), a web URL, or no path at all. It was `javascript`, which is a
+ * claim, not a default — a device-docs read was badged `JAVASCRIPT` and its
+ * prose was tokenized as code. `text` is a Shiki SPECIAL language (always
+ * loaded, no grammar fetched) and `highlightCode`/`highlightLines` emit it
+ * escaped and uncoloured, which is what omp's own reader does for the same
+ * input (`getLanguageFromPath('xd://…')` is `undefined` there).
+ *
+ * The read-tool SELECTOR comes off first (`stripReadSelector`). A `read` may
+ * name its lines on the path itself (`Read.tsx:205-215:raw`), and reading the
+ * extension off the raw string gave `tsx:205-215:raw` — an unknown extension,
+ * so `text`, so an unhighlighted code surface. Only a `:N-M` suffix used to be
+ * stripped; `:raw`, `:img` and comma lists were not.
+ */
+export function getLanguageFromPath(filePath?: string): string {
+  if (!filePath) return 'text';
+  const clean = stripReadSelector(filePath);
+  const ext = clean.split('.').pop()?.toLowerCase();
+  switch (ext) {
+    case 'ts': return 'typescript';
+    case 'tsx': return 'tsx';
+    case 'js':
+    case 'mjs':
+    case 'cjs': return 'javascript';
+    case 'jsx': return 'jsx';
+    case 'json': return 'json';
+    case 'md':
+    case 'markdown': return 'markdown';
+    case 'css': return 'css';
+    case 'sh':
+    case 'bash':
+    case 'zsh': return 'bash';
+    case 'diff':
+    case 'patch': return 'diff';
+    case 'yaml':
+    case 'yml': return 'yaml';
+    case 'html': return 'html';
+    case 'svg':
+    case 'xml': return 'xml';
+    case 'py': return 'python';
+    case 'go': return 'go';
+    case 'rs': return 'rust';
+    case 'sql': return 'sql';
+    case 'toml': return 'toml';
+    case 'java': return 'java';
+    case 'c':
+    case 'h': return 'c';
+    case 'cpp':
+    case 'cc':
+    case 'hpp': return 'cpp';
+    case 'cs': return 'csharp';
+    case 'rb': return 'ruby';
+    case 'php': return 'php';
+    case 'kt':
+    case 'kts': return 'kotlin';
+    case 'swift': return 'swift';
+    case 'scala': return 'scala';
+    case 'lua': return 'lua';
+    case 'pl': return 'perl';
+    case 'dockerfile': return 'dockerfile';
+    case 'ini':
+    case 'cfg':
+    case 'conf': return 'ini';
+    case 'properties': return 'properties';
+    case 'env': return 'bash';
+    case 'zig': return 'zig';
+    case 'ex':
+    case 'exs': return 'elixir';
+    case 'dart': return 'dart';
+    case 'ml':
+    case 'mli': return 'ocaml';
+    case 'hs': return 'haskell';
+    case 'nix': return 'nix';
+    case 'tf':
+    case 'tfvars':
+    case 'hcl': return 'hcl';
+    case 'graphql':
+    case 'gql': return 'graphql';
+    case 'sol': return 'solidity';
+    case 'r': return 'r';
+    case 'jl': return 'julia';
+    case 'erl': return 'erlang';
+    case 'clj':
+    case 'cljs':
+    case 'cljc':
+    case 'edn': return 'clojure';
+    case 'scm':
+    case 'ss': return 'scheme';
+    case 'rkt': return 'racket';
+    case 'proto': return 'protobuf';
+    case 'makefile':
+    case 'mk': return 'makefile';
+    case 'ps1':
+    case 'psm1': return 'powershell';
+    case 'json5': return 'json5';
+    case 'less': return 'less';
+    case 'scss': return 'scss';
+    case 'sass': return 'sass';
+    case 'styl': return 'stylus';
+    case 'vue': return 'vue';
+    case 'svelte': return 'svelte';
+    case 'astro': return 'astro';
+    // `.m` is genuinely ambiguous (Objective-C vs MATLAB); map to Objective-C,
+    // the common editor default.
+    case 'mm':
+    case 'm': return 'objective-c';
+    case 'groovy':
+    case 'gvy':
+    case 'gradle': return 'groovy';
+    default: return 'text';
+  }
+}
+
+/**
+ * The patterns `isCodeLike` probes, at module scope.
+ *
+ * A regex *literal* inside the function body constructs a fresh `RegExp` on
+ * every call, and this runs per render from the notice, task-result and Bash
+ * cards. Compiled once here instead.
+ */
+const CODE_PATTERNS = [
+  /^(?:import|export)\s+.+from\s+['"][^'"]+['"]/m,
+  /^(?:const|let|var|function|class|interface|type|enum)\s+[A-Za-z0-9_$]+/m,
+  /(?:=>|\bconsole\.(?:log|error|warn)|return\s+|async\s+function)/,
+  /^\s*\d+:\s*(?:import|const|let|function|\/\/|\/\*|<|[A-Za-z])/m,
+  /^\s*\[[A-Za-z0-9_./-]+\.[a-zA-Z0-9]+\]\s*\n\d+:/m,
+] as const;
+
+/** Check if a string looks like code or structured programming text */
+export function isCodeLike(text: string): boolean {
+  if (!text || text.length < 5) return false;
+  const trimmed = text.trim();
+  if ((trimmed.startsWith('{') && trimmed.endsWith('}')) || (trimmed.startsWith('[') && trimmed.endsWith(']'))) {
+    try {
+      JSON.parse(trimmed);
+      return true;
+    } catch {
+      // not valid JSON
+    }
+  }
+
+  return CODE_PATTERNS.some((pattern) => pattern.test(trimmed));
+}

package/src/shared/lib/code/lazy-window.test.ts

@@ -0,0 +1,161 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import {
+  codeWindow,
+  clampWindow,
+  firstWindow,
+  measuredGeometry,
+  resolveWindow,
+  shouldWindow,
+  uniformGeometry,
+  windowSpace,
+  WHOLE_DOCUMENT_MAX_CHARS,
+  WHOLE_DOCUMENT_MAX_LINES,
+  WINDOW_OVERSCAN,
+  type LineGeometry,
+} from '@/shared/lib/code/lazy-window';
+
+const ROW = 18;
+
+/** `measuredGeometry` returns null for heights that do not fit the document. */
+function measured(heights: number[]): LineGeometry {
+  const geometry = measuredGeometry(heights, ROW, heights.length);
+  if (!geometry) throw new Error('heights should describe every line');
+  return geometry;
+}
+
+describe('shouldWindow', () => {
+  test('leaves a short document on the plain surface', () => {
+    expect(shouldWindow(120, 4_000)).toBe(false);
+  });
+
+  test('windows a document that is long in lines or in characters', () => {
+    expect(shouldWindow(WHOLE_DOCUMENT_MAX_LINES + 1, 10)).toBe(true);
+    expect(shouldWindow(10, WHOLE_DOCUMENT_MAX_CHARS + 1)).toBe(true);
+  });
+});
+
+describe('uniformGeometry', () => {
+  const geometry = uniformGeometry(ROW, 500);
+
+  test('spaces lines one row apart and totals the document', () => {
+    expect(geometry.offsetOf(0)).toBe(0);
+    expect(geometry.offsetOf(10)).toBe(10 * ROW);
+    expect(geometry.totalHeight).toBe(500 * ROW);
+  });
+
+  test('maps an offset back to the line covering it', () => {
+    expect(geometry.lineAt(0)).toBe(0);
+    expect(geometry.lineAt(ROW - 1)).toBe(0);
+    expect(geometry.lineAt(ROW)).toBe(1);
+    expect(geometry.lineAt(499 * ROW + 3)).toBe(499);
+  });
+
+  test('clamps an offset outside the document', () => {
+    expect(geometry.lineAt(-50)).toBe(0);
+    expect(geometry.lineAt(999_999)).toBe(499);
+    expect(geometry.offsetOf(500)).toBe(geometry.totalHeight);
+    expect(geometry.offsetOf(999)).toBe(geometry.totalHeight);
+  });
+});
+
+describe('measuredGeometry', () => {
+  // Every third line wraps over three rows; the rest are single rows.
+  const heights = Array.from({ length: 9 }, (_, index) => (index % 3 === 2 ? ROW * 3 : ROW));
+  const geometry = measured(heights);
+
+  test('builds offsets from the wrapped heights', () => {
+    expect(geometry.offsetOf(0)).toBe(0);
+    expect(geometry.offsetOf(1)).toBe(ROW);
+    expect(geometry.offsetOf(2)).toBe(2 * ROW);
+    // Line 2 spans three rows, so line 3 starts after all three.
+    expect(geometry.offsetOf(3)).toBe(5 * ROW);
+    expect(geometry.totalHeight).toBe(heights.reduce((sum, height) => sum + height, 0));
+  });
+
+  test('maps an offset inside a wrapped line to that line', () => {
+    expect(geometry.lineAt(2 * ROW)).toBe(2);
+    expect(geometry.lineAt(4 * ROW + 5)).toBe(2);
+    expect(geometry.lineAt(5 * ROW)).toBe(3);
+  });
+
+  test('refuses heights that do not describe every line', () => {
+    expect(measuredGeometry([ROW, ROW], ROW, 5)).toBeNull();
+    expect(measuredGeometry([], ROW, 0)).toBeNull();
+  });
+});
+
+describe('resolveWindow', () => {
+  const geometry = uniformGeometry(ROW, 1_000);
+
+  test('covers the viewport plus overscan on both sides', () => {
+    // Viewport rows 100..128 (the last row is half covered, so it is included).
+    const window = resolveWindow(geometry, 100 * ROW, 28 * ROW);
+    expect(window).toEqual({ start: 100 - WINDOW_OVERSCAN, end: 129 + WINDOW_OVERSCAN });
+  });
+
+  test('never runs past either end of the document', () => {
+    expect(resolveWindow(geometry, 0, ROW)).toEqual({ start: 0, end: 2 + WINDOW_OVERSCAN });
+    expect(resolveWindow(geometry, 999 * ROW, 40 * ROW).end).toBe(1_000);
+  });
+
+  test('keeps a zero-height band to at least the line under it', () => {
+    const window = resolveWindow(geometry, 400 * ROW, 0);
+    expect(window.start).toBeLessThanOrEqual(400);
+    expect(window.end).toBeGreaterThan(400);
+  });
+});
+
+describe('firstWindow', () => {
+  test('bounds the opening render of a long document', () => {
+    expect(firstWindow(20_000).start).toBe(0);
+    expect(firstWindow(20_000).end).toBeLessThan(20_000);
+  });
+
+  test('keeps a short document whole', () => {
+    expect(firstWindow(3)).toEqual({ start: 0, end: 3 });
+  });
+});
+
+describe('clampWindow', () => {
+  test('pulls a window left over from another document back inside it', () => {
+    expect(clampWindow({ start: 9_000, end: 9_500 }, 40)).toEqual({ start: 39, end: 40 });
+    expect(clampWindow({ start: -5, end: 10 }, 40)).toEqual({ start: 0, end: 10 });
+  });
+
+  test('never returns an empty range', () => {
+    expect(clampWindow({ start: 5, end: 5 }, 40).end).toBeGreaterThan(5);
+  });
+});
+
+describe('windowSpace', () => {
+  test('reserves exactly the height of the lines outside the window', () => {
+    const geometry = uniformGeometry(ROW, 100);
+    const space = windowSpace(geometry, { start: 10, end: 30 });
+    expect(space).toEqual({ top: 10 * ROW, bottom: 70 * ROW, breakAtEnd: false });
+    expect(space.top + space.bottom + (30 - 10) * ROW).toBe(geometry.totalHeight);
+  });
+
+  test('flags a window that reaches the last line', () => {
+    const geometry = uniformGeometry(ROW, 100);
+    expect(windowSpace(geometry, { start: 90, end: 100 }).breakAtEnd).toBe(true);
+  });
+});
+
+describe('codeWindow', () => {
+  test('clamps the range and spaces it in one step', () => {
+    const geometry = uniformGeometry(ROW, 50);
+    expect(codeWindow(geometry, { start: 0, end: 5_000 })).toEqual({
+      start: 0,
+      end: 50,
+      top: 0,
+      bottom: 0,
+      breakAtEnd: true,
+    });
+  });
+});

package/src/shared/lib/code/lazy-window.ts

@@ -0,0 +1,156 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Line geometry and windowing policy for the lazy editor surface.
+ *
+ * Shiki tokenization is linear in document size (≈0.14 ms per line), so a
+ * whole-file highlight costs ~0.8 s at 7 000 lines — and the editor pays it on
+ * every keystroke, on top of one gutter node and one wrapped-row measurement
+ * per line. A long document therefore renders only the lines the reader can
+ * actually see, and this module is the DOM-free half of that: px offsets per
+ * line, the viewport → line-range mapping, and the blank space the unrendered
+ * lines take up so the caret never leaves its row.
+ *
+ * The browser measurements this needs (row height, per-line wrapped heights)
+ * stay in the surface, which feeds them in as a `LineGeometry`.
+ */
+
+/** Documents at or below this size render whole — windowing them saves less than it costs. */
+export const WHOLE_DOCUMENT_MAX_LINES = 300;
+export const WHOLE_DOCUMENT_MAX_CHARS = 20_000;
+
+/** Lines kept beyond the viewport so a fast scroll cannot outrun the window. */
+export const WINDOW_OVERSCAN = 24;
+
+/** Lines rendered before the first measurement lands; the surface corrects this in a layout effect. */
+export const INITIAL_WINDOW_LINES = 200;
+
+/** Half-open line range `[start, end)`. */
+export interface LineWindow {
+  start: number;
+  end: number;
+}
+
+/** Blank space (px) the unrendered lines occupy above and below a window. */
+export interface WindowSpace {
+  top: number;
+  bottom: number;
+  /** The window reaches the document's last line, so it keeps the editor's trailing line break. */
+  breakAtEnd: boolean;
+}
+
+/** A windowed render request: the lines to draw plus the space the rest of the document takes. */
+export interface CodeWindow extends LineWindow, WindowSpace {}
+
+/** Per-line vertical layout of a document, in px. */
+export interface LineGeometry {
+  readonly lineCount: number;
+  /** Height (px) of a single visual row. */
+  readonly rowHeight: number;
+  /** Height (px) of every line together. */
+  readonly totalHeight: number;
+  /** Y offset (px) of the top edge of line `index`; `lineCount` is the document's end. */
+  offsetOf(index: number): number;
+  /** Index of the line covering `y`, clamped to the document. */
+  lineAt(y: number): number;
+}
+
+function clamp(value: number, min: number, max: number): number {
+  return value < min ? min : value > max ? max : value;
+}
+
+/** Whether a document is long enough that rendering all of it would be felt. */
+export function shouldWindow(lineCount: number, charCount: number): boolean {
+  return lineCount > WHOLE_DOCUMENT_MAX_LINES || charCount > WHOLE_DOCUMENT_MAX_CHARS;
+}
+
+/** Word wrap off: every line is exactly one row, so no measurement is involved. */
+export function uniformGeometry(rowHeight: number, lineCount: number): LineGeometry {
+  return {
+    lineCount,
+    rowHeight,
+    totalHeight: rowHeight * lineCount,
+    offsetOf: (index) => rowHeight * clamp(index, 0, lineCount),
+    lineAt: (y) => clamp(Math.floor(y / rowHeight), 0, Math.max(lineCount - 1, 0)),
+  };
+}
+
+/**
+ * Word wrap on: heights are the measured wrapped heights, one entry per line.
+ * Returns `null` when they do not describe every line, which leaves the caller
+ * on the whole-document path rather than spacing lines with a wrong geometry.
+ */
+export function measuredGeometry(heights: number[], rowHeight: number, lineCount: number): LineGeometry | null {
+  if (lineCount === 0 || heights.length !== lineCount) return null;
+  const offsets = new Float64Array(lineCount + 1);
+  for (let i = 0; i < lineCount; i++) offsets[i + 1] = offsets[i] + heights[i];
+  const total = offsets[lineCount];
+  return {
+    lineCount,
+    rowHeight,
+    totalHeight: total,
+    offsetOf: (index) => offsets[clamp(index, 0, lineCount)],
+    lineAt: (y) => {
+      if (y < 0) return 0;
+      if (total <= 0 || y >= total) return lineCount - 1;
+      // Last line whose top edge sits at or above `y`.
+      let low = 0;
+      let high = lineCount - 1;
+      while (low < high) {
+        const mid = (low + high + 1) >> 1;
+        if (offsets[mid] <= y) low = mid;
+        else high = mid - 1;
+      }
+      return low;
+    },
+  };
+}
+
+/** The lines a viewport band (`top`, `height`) covers, plus overscan on both sides. */
+export function resolveWindow(
+  geometry: LineGeometry,
+  top: number,
+  height: number,
+  overscan: number = WINDOW_OVERSCAN,
+): LineWindow {
+  const first = geometry.lineAt(top);
+  const last = geometry.lineAt(top + Math.max(height, 0));
+  return {
+    start: Math.max(0, first - overscan),
+    end: Math.min(geometry.lineCount, Math.max(last + 1, first + 1) + overscan),
+  };
+}
+
+/** What a freshly opened document renders before its viewport has been read. */
+export function firstWindow(lineCount: number): LineWindow {
+  return { start: 0, end: clamp(INITIAL_WINDOW_LINES, 1, Math.max(lineCount, 1)) };
+}
+
+/** Keep a window inside the document it belongs to (the state may predate a file switch). */
+export function clampWindow(window: LineWindow, lineCount: number): LineWindow {
+  const start = clamp(window.start, 0, Math.max(lineCount - 1, 0));
+  return { start, end: clamp(window.end, start + 1, Math.max(lineCount, 1)) };
+}
+
+export function sameWindow(a: LineWindow | null, b: LineWindow | null): boolean {
+  return a === b || (a !== null && b !== null && a.start === b.start && a.end === b.end);
+}
+
+/** Space the unrendered lines take around `window`, and whether it ends the document. */
+export function windowSpace(geometry: LineGeometry, window: LineWindow): WindowSpace {
+  const top = geometry.offsetOf(window.start);
+  return {
+    top,
+    bottom: Math.max(0, geometry.totalHeight - geometry.offsetOf(window.end)),
+    breakAtEnd: window.end >= geometry.lineCount,
+  };
+}
+
+/** Clamp a window to its document and resolve the space it leaves around itself. */
+export function codeWindow(geometry: LineGeometry, window: LineWindow): CodeWindow {
+  const clamped = clampWindow(window, geometry.lineCount);
+  return { ...clamped, ...windowSpace(geometry, clamped) };
+}

package/src/shared/lib/code/line-endings.test.ts

@@ -0,0 +1,38 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { detectLineEnding, toDiskText, toLf } from '@/shared/lib/code/line-endings';
+
+describe('line endings', () => {
+  test('the first terminator decides the style', () => {
+    expect(detectLineEnding('a\r\nb\n')).toBe('crlf');
+    expect(detectLineEnding('a\nb\r\n')).toBe('lf');
+  });
+
+  test('a file with no terminator, or one using lone CR, reads as lf', () => {
+    expect(detectLineEnding('single line')).toBe('lf');
+    expect(detectLineEnding('\rleading')).toBe('lf');
+    expect(detectLineEnding('a\rb\r')).toBe('lf');
+  });
+
+  test('the buffer form carries no CR', () => {
+    expect(toLf('a\r\nb\r\n')).toBe('a\nb\n');
+    expect(toLf('a\rb\r')).toBe('a\nb\n');
+    expect(toLf('a\nb\n')).toBe('a\nb\n');
+  });
+
+  test('writing back restores the detected ending', () => {
+    expect(toDiskText('a\nb\n', 'crlf')).toBe('a\r\nb\r\n');
+    expect(toDiskText('a\nb\n', 'lf')).toBe('a\nb\n');
+    // A mixed buffer still normalizes before it is re-encoded.
+    expect(toDiskText('a\r\nb\n', 'crlf')).toBe('a\r\nb\r\n');
+  });
+
+  test('an unedited CRLF round trip is byte-identical', () => {
+    const disk = 'const a = 1;\r\nconst b = 2;\r\n';
+    expect(toDiskText(toLf(disk), detectLineEnding(disk))).toBe(disk);
+  });
+});

package/src/shared/lib/code/line-endings.ts

@@ -0,0 +1,56 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Line-ending preservation for the file-editing surfaces.
+ *
+ * Two independent transports destroy the distinction, so the file's own ending
+ * has to be carried out of band rather than inferred from the buffer:
+ *
+ * - A `<textarea>` cannot hold a CRLF. The HTML spec defines its *API value* as
+ *   the raw value with every carriage return removed, so the instant a CRLF file
+ *   is placed in the editing surface the buffer is LF-only — verified in
+ *   Chromium: `textarea.value = 'a\r\nb'` reads back `'a\nb'`.
+ * - `multipart/form-data` normalizes the other way: every bare LF in a field
+ *   value becomes CRLF in transit (the HTML serializer on the way out, Bun's
+ *   parser agreeing on the way in). A save payload therefore cannot say "LF" no
+ *   matter what the buffer held.
+ *
+ * Saving the buffer as-is rewrote the whole file's line endings on a
+ * one-character edit — every line showed as changed in `git diff`. The ending is
+ * detected at read and travels as its own field; the server builds the bytes.
+ * An unedited save is then byte-identical and an edited save a one-line diff.
+ *
+ * Detection is by the FIRST terminator rather than a vote over all of them: a
+ * file is overwhelmingly uniform, and the first ending is the one the author's
+ * editor writes. A file with no terminator, or one using lone CR (classic Mac
+ * OS), reads as `lf`.
+ */
+
+export type LineEnding = 'lf' | 'crlf';
+
+/** The ending the file uses, judged by its first terminator. */
+export function detectLineEnding(text: string): LineEnding {
+  const index = text.indexOf('\n');
+  return index > 0 && text[index - 1] === '\r' ? 'crlf' : 'lf';
+}
+
+/**
+ * The buffer form: CRLF and lone CR collapsed to LF, matching what a textarea
+ * can actually hold. A string already free of CR is returned unchanged.
+ */
+export function toLf(text: string): string {
+  return text.includes('\r') ? text.replace(/\r\n?/g, '\n') : text;
+}
+
+/**
+ * The disk form: `text` normalized — whatever mix of endings it carries, and
+ * whether or not it came back through a transport that rewrote them — and then
+ * written with `ending`.
+ */
+export function toDiskText(text: string, ending: LineEnding): string {
+  const lf = toLf(text);
+  return ending === 'crlf' ? lf.replace(/\n/g, '\r\n') : lf;
+}

package/src/shared/lib/code/outline/document.ts

@@ -0,0 +1,56 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The shape of "the document the editor is holding", and the vocabulary for why
+ * it may have no outline.
+ *
+ * The type lives in `shared` because the empty-state wording does: the panel
+ * says "still reading", "could not read this" and "no symbols" with three
+ * different sentences, and that table must not be duplicated per surface. The
+ * STORE is client-only (`client/lib/editor-document.ts`) — nothing on the
+ * server has an editor.
+ *
+ * `diff` is its own state rather than a `not-a-document` with a note, because a
+ * diff tab HIDES the outline instead of explaining it: a reader comparing two
+ * versions of a file has no source document to outline, so a section that
+ * announced "diff tabs have no outline" was chrome occupying the panel floor for
+ * a question nobody asked.
+ */
+
+export type EditorDocumentState = 'idle' | 'loading' | 'ready' | 'error' | 'not-a-document' | 'diff';
+
+export interface EditorDocument {
+  /** Workspace-relative path of the file on screen, or null when nothing is open. */
+  path: string | null;
+  /** Display name, so a notice can name the file it is about. */
+  name: string | null;
+  /** The LIVE buffer — what the surface is drawing right now. */
+  content: string;
+  /** Shiki language id, as the editor resolved it from the name. */
+  language: string;
+  state: EditorDocumentState;
+  /** Why the tab has no outline to draw, when `state` is `not-a-document` or `error`. */
+  note: string | null;
+}
+
+const NOTICES: Record<EditorDocumentState, string> = {
+  idle: 'No file open in the editor.',
+  loading: 'Reading the file…',
+  error: 'Could not read this file.',
+  'not-a-document': 'This tab has no outline.',
+  diff: 'Diff tabs have no outline.',
+  ready: 'No symbols found.',
+};
+
+/**
+ * Why an outline has no rows, as one sentence.
+ *
+ * A caller's own `note` wins where it exists — it names the actual cause (the
+ * read failure's message, the viewer kind) rather than the state's category.
+ */
+export function outlineEmptyNotice(state: EditorDocumentState, note?: string | null): string {
+  return note ?? NOTICES[state];
+}