@hacky.software/opencode-todo-supervisor 0.0.0-stage → 0.3.2

package/src/markdown.test.ts

@@ -0,0 +1,135 @@
+// todo-supervisor — markdown mode unit tests (§5.8, aspect 14a).
+import { describe, expect, test } from "bun:test"
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs"
+import {
+  displayPath,
+  effectiveFiles,
+  MarkdownCache,
+  openMarkdownItems,
+  parseChecklist,
+  renderFileSection,
+  resolveMarkdownPath,
+  toggleMarkdownItem,
+} from "./markdown"
+
+describe("markdown parser (§5.8)", () => {
+  test("parses bullets, ordered lists, indentation and states with 1-based line numbers", () => {
+    const content = [
+      "# Title",
+      "- [ ] first",
+      "  * [x] nested done",
+      "1. [ ] ordered",
+      "3) [X] upper done",
+      "- [~] canceled",
+      "plain text",
+      "- not a checkbox",
+    ].join("\n")
+    const items = parseChecklist(content, "/p/TODO.md")
+    expect(items.map((entry) => [entry.line, entry.state, entry.text])).toEqual([
+      [2, "open", "first"],
+      [3, "completed", "nested done"],
+      [4, "open", "ordered"],
+      [5, "completed", "upper done"],
+      [6, "canceled", "canceled"],
+    ])
+    expect(items[1]!.indent).toBe("  ")
+  })
+
+  test("skips backtick and tilde fenced code blocks", () => {
+    const content = [
+      "- [ ] real",
+      "```md",
+      "- [ ] inside backticks",
+      "```",
+      "~~~",
+      "- [ ] inside tildes",
+      "~~~",
+      "- [x] after",
+    ].join("\n")
+    const items = parseChecklist(content, "/p/TODO.md")
+    expect(items.map((entry) => entry.text)).toEqual(["real", "after"])
+  })
+
+  test("handles CRLF line endings", () => {
+    const items = parseChecklist("- [ ] a\r\n- [~] b\r\n", "/p/TODO.md")
+    expect(items.map((entry) => entry.state)).toEqual(["open", "canceled"])
+  })
+})
+
+describe("markdown subscriptions (§5.8)", () => {
+  test("resolves and validates paths", () => {
+    expect(resolveMarkdownPath("/proj", "docs/TODO.md")).toBe("/proj/docs/TODO.md")
+    expect(resolveMarkdownPath("/proj", "/abs/PLAN.markdown")).toBe("/abs/PLAN.markdown")
+    expect(resolveMarkdownPath("/proj", "UPPER.MD")).toBe("/proj/UPPER.MD")
+    expect(() => resolveMarkdownPath("/proj", "notes.txt")).toThrow(/markdown/)
+    expect(() => resolveMarkdownPath("/proj", "   ")).toThrow()
+  })
+
+  test("merges config, stored files and removed shadows", () => {
+    const options = { markdownFiles: ["PLAN.md", "/abs/OTHER.md"] }
+    const subs = { files: ["/proj/docs/TODO.md", "/abs/OTHER.md"], removed: ["/proj/PLAN.md"] }
+    expect(effectiveFiles(options, "/proj", subs)).toEqual(["/abs/OTHER.md", "/proj/docs/TODO.md"])
+    expect(effectiveFiles(options, "/proj", undefined)).toEqual(["/abs/OTHER.md", "/proj/PLAN.md"])
+  })
+})
+
+describe("markdown cache + renderer", () => {
+  test("caches by mtime/size, invalidates, and reports missing files", () => {
+    const dir = "/tmp/opencode"
+    mkdirSync(dir, { recursive: true })
+    const file = `${dir}/md-cache-${process.pid}.md`
+    writeFileSync(file, "- [ ] one\n")
+    const cache = new MarkdownCache()
+    const first = cache.parse(file)
+    expect(first.exists).toBe(true)
+    expect(first.items.length).toBe(1)
+    expect(cache.parse(file)).toBe(first)
+    cache.invalidate(file)
+    expect(cache.parse(file)).not.toBe(first)
+    const missing = cache.parse(`${dir}/missing-${process.pid}.md`)
+    expect(missing.exists).toBe(false)
+    expect(missing.items).toEqual([])
+  })
+
+  test("toggles a checklist item in place, fence-aware and format-preserving", () => {
+    const dir = "/tmp/opencode"
+    mkdirSync(dir, { recursive: true })
+    const file = `${dir}/md-toggle-${process.pid}.md`
+    writeFileSync(
+      file,
+      ["# List", "  - [ ] nested item  ", "```md", "- [ ] fenced", "```", "1) [x] done\r"].join("\r\n"),
+    )
+    // open -> completed, indentation/bullet/trailing spaces preserved
+    expect(toggleMarkdownItem(file, 2)).toBe("completed")
+    expect(readFileSync(file, "utf8")).toContain("  - [x] nested item  ")
+    // completed -> open
+    expect(toggleMarkdownItem(file, 6)).toBe("open")
+    expect(readFileSync(file, "utf8")).toContain("1) [ ] done")
+    // CRLF line endings survive the rewrite
+    expect(readFileSync(file, "utf8").split("\n").length).toBe(6)
+    // a fenced look-alike is not an item
+    expect(() => toggleMarkdownItem(file, 4)).toThrow(/no checklist item/)
+    // a plain line is not an item either
+    expect(() => toggleMarkdownItem(file, 1)).toThrow(/no checklist item/)
+  })
+
+  test("renders path:line sections and open items", () => {
+    const path = "/proj/docs/TODO.md"
+    const parsed = {
+      path,
+      exists: true,
+      items: [
+        { path, line: 3, text: "do it", indent: "", state: "open" as const },
+        { path, line: 4, text: "done", indent: "", state: "completed" as const },
+      ],
+    }
+    const section = renderFileSection(parsed, "/proj")
+    expect(section).toContain("## docs/TODO.md (1 open of 2)")
+    expect(section).toContain("- [ ] do it  (docs/TODO.md:3)")
+    expect(section).toContain("- [x] done  (docs/TODO.md:4)")
+    expect(openMarkdownItems([parsed]).map((item) => item.text)).toEqual(["do it"])
+    expect(displayPath("/proj", path)).toBe("docs/TODO.md")
+    expect(displayPath("/proj", "/elsewhere/x.md")).toBe("/elsewhere/x.md")
+    expect(renderFileSection({ path: "/proj/gone.md", exists: false, items: [] }, "/proj")).toContain("missing")
+  })
+})

package/src/markdown.ts

@@ -0,0 +1,159 @@
+// todo-supervisor — markdown checklist mode (PLAN.md §5.8, aspect 14).
+//
+// Sessions may subscribe to any number of markdown files whose GFM checklist
+// items act as todos. This module owns: the fence-aware parser, path
+// resolution/validation, the effective-subscription merge, a per-file parse
+// cache and the shared renderer for `path:line` sections.
+import { readFileSync, renameSync, statSync, writeFileSync } from "node:fs"
+import { isAbsolute, relative, resolve as resolvePath } from "node:path"
+
+export type MarkdownState = "open" | "completed" | "canceled"
+
+export type MarkdownItem = {
+  path: string
+  /** 1-based line number for `path:line` references. */
+  line: number
+  text: string
+  indent: string
+  state: MarkdownState
+}
+
+export type ParsedFile = {
+  path: string
+  exists: boolean
+  error?: string
+  items: MarkdownItem[]
+}
+
+// GFM checkbox: any bullet or ordered marker, any indentation (§5.8). The trailing
+// `\r?` keeps a CRLF file whose last line has no final newline parseable.
+const ITEM_RE = /^(\s*)(?:[-*+]|\d+[.)])\s+\[( |x|X|~)\]\s+(.*?)\r?$/
+const FENCE_RE = /^\s*(`{3,}|~{3,})/
+
+/** Fence-aware checklist parse; code fences are skipped (§5.8). */
+export function parseChecklist(content: string, path: string): MarkdownItem[] {
+  const items: MarkdownItem[] = []
+  const lines = content.split(/\r?\n/)
+  let fence: string | undefined
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index]!
+    const fenceMatch = FENCE_RE.exec(line)
+    if (fenceMatch) {
+      const marker = fenceMatch[1]!
+      if (!fence) fence = marker[0]
+      else if (marker[0] === fence) fence = undefined
+      continue
+    }
+    if (fence) continue
+    const match = ITEM_RE.exec(line)
+    if (!match) continue
+    const [, indent, marker, text] = match
+    const state: MarkdownState =
+      marker === "x" || marker === "X" ? "completed" : marker === "~" ? "canceled" : "open"
+    items.push({ path, line: index + 1, text: text!.trim(), indent: indent!, state })
+  }
+  return items
+}
+
+/** `.md` / `.markdown` only; relative paths resolve against the location directory (§5.8). */
+export function resolveMarkdownPath(directory: string, raw: string): string {
+  const trimmed = raw.trim()
+  if (trimmed === "") throw new Error(`invalid input: "path" must be a non-empty string`)
+  const abs = isAbsolute(trimmed) ? resolvePath(trimmed) : resolvePath(directory, trimmed)
+  if (!/\.(md|markdown)$/i.test(abs)) {
+    throw new Error(`invalid input: "${raw}" is not a markdown file (.md or .markdown)`)
+  }
+  return abs
+}
+
+/** Effective set (§5.8): config `markdownFiles` ∪ stored `files`, minus `removed`. */
+export function effectiveFiles(
+  options: { readonly markdownFiles: readonly string[] },
+  directory: string,
+  subs: { readonly files: readonly string[]; readonly removed: readonly string[] } | undefined,
+): string[] {
+  const set = new Set<string>()
+  for (const raw of options.markdownFiles) {
+    set.add(isAbsolute(raw) ? resolvePath(raw) : resolvePath(directory, raw))
+  }
+  for (const path of subs?.files ?? []) set.add(path)
+  for (const path of subs?.removed ?? []) set.delete(path)
+  return [...set].sort()
+}
+
+/** Per-file parse cache keyed by mtime + size; `parse` is synchronous and cheap. */
+export class MarkdownCache {
+  private readonly cache = new Map<string, { mtimeMs: number; size: number; parsed: ParsedFile }>()
+
+  parse(path: string): ParsedFile {
+    try {
+      const stat = statSync(path)
+      const hit = this.cache.get(path)
+      if (hit && hit.mtimeMs === stat.mtimeMs && hit.size === stat.size) return hit.parsed
+      const parsed: ParsedFile = { path, exists: true, items: parseChecklist(readFileSync(path, "utf8"), path) }
+      this.cache.set(path, { mtimeMs: stat.mtimeMs, size: stat.size, parsed })
+      return parsed
+    } catch (err) {
+      const parsed: ParsedFile = { path, exists: false, error: String(err), items: [] }
+      this.cache.delete(path)
+      return parsed
+    }
+  }
+
+  invalidate(path?: string): void {
+    if (path === undefined) this.cache.clear()
+    else this.cache.delete(path)
+  }
+}
+
+/** Open markdown items across the given files. */
+export function openMarkdownItems(files: readonly ParsedFile[]): MarkdownItem[] {
+  return files.flatMap((file) => file.items.filter((item) => item.state === "open"))
+}
+
+/**
+ * Toggle one checklist item in place (§5.8 panel write-back). Only lines the
+ * fence-aware parser reports as items are eligible, and only the marker is
+ * rewritten — bullet, indentation, trailing text and the file's line endings are
+ * preserved. Writes via a temp file + rename so a crash cannot truncate the file.
+ * Callers invalidate the parse cache. Returns the new state.
+ */
+export function toggleMarkdownItem(path: string, line: number): MarkdownState {
+  const content = readFileSync(path, "utf8")
+  const item = parseChecklist(content, path).find((entry) => entry.line === line)
+  if (!item) throw new Error(`no checklist item at ${path}:${line} (fenced or missing?)`)
+  const next: MarkdownState = item.state === "completed" ? "open" : "completed"
+  const marker = next === "completed" ? "x" : next === "canceled" ? "~" : " "
+  const lines = content.split("\n")
+  const index = line - 1
+  const target = lines[index]
+  if (target === undefined) throw new Error(`no line ${line} in ${path}`)
+  const rewritten = target.replace(/\[( |x|X|~)\]/, `[${marker}]`)
+  if (rewritten === target) throw new Error(`could not rewrite the checklist marker at ${path}:${line}`)
+  lines[index] = rewritten
+  const tmp = `${path}.todo-supervisor.tmp`
+  writeFileSync(tmp, lines.join("\n"), "utf8")
+  renameSync(tmp, path)
+  return next
+}
+
+/** Path for display: relative to the location directory when inside it. */
+export function displayPath(directory: string, path: string): string {
+  const rel = relative(directory, path)
+  return rel === "" || rel.startsWith("..") ? path : rel
+}
+
+/** Shared `path:line` section renderer (§5.3 `todo_read`, §5.4 nudges). */
+export function renderFileSection(
+  file: ParsedFile,
+  directory: string,
+  options: { openOnly?: boolean } = {},
+): string {
+  const shown = displayPath(directory, file.path)
+  if (!file.exists) return `## ${shown} — missing (0 tasks)`
+  const open = file.items.filter((item) => item.state === "open").length
+  const marker = (state: MarkdownState) => (state === "completed" ? "[x]" : state === "canceled" ? "[~]" : "[ ]")
+  const shownItems = options.openOnly ? file.items.filter((item) => item.state === "open") : file.items
+  const rows = shownItems.map((item) => `- ${marker(item.state)} ${item.text}  (${shown}:${item.line})`)
+  return [`## ${shown} (${open} open of ${file.items.length})`, ...rows].join("\n")
+}

package/src/options.test.ts

@@ -0,0 +1,42 @@
+import { describe, expect, test } from "bun:test"
+import { DEFAULTS, parseOptions } from "./options"
+
+describe("parseOptions", () => {
+  test("uses defaults for absent input", () => {
+    expect(parseOptions(undefined)).toEqual(DEFAULTS)
+    expect(parseOptions(null)).toEqual(DEFAULTS)
+    expect(parseOptions({})).toEqual(DEFAULTS)
+  })
+
+  test("invalid values fall back to defaults", () => {
+    const options = parseOptions({
+      stallMinutes: "x",
+      settleMs: -5,
+      enabled: "yes",
+      scope: "nope",
+      markdownFiles: [1, 2],
+      minNudgeIntervalMs: Number.NaN,
+    })
+    expect(options).toEqual(DEFAULTS)
+  })
+
+  test("non-object input falls back to defaults", () => {
+    expect(parseOptions("nope")).toEqual(DEFAULTS)
+    expect(parseOptions([1, 2])).toEqual(DEFAULTS)
+  })
+
+  test("valid values are taken; unknown keys ignored", () => {
+    const options = parseOptions({
+      stallMinutes: 2,
+      scope: "all",
+      enabled: false,
+      markdownFiles: [" TODO.md ", "", "plans/x.md"],
+      unknown: true,
+    })
+    expect(options.stallMinutes).toBe(2)
+    expect(options.scope).toBe("all")
+    expect(options.enabled).toBe(false)
+    expect(options.markdownFiles).toEqual(["TODO.md", "plans/x.md"])
+    expect((options as Record<string, unknown>)["unknown"]).toBeUndefined()
+  })
+})

package/src/options.ts

@@ -0,0 +1,100 @@
+// todo-supervisor — options (PLAN.md §5.1, §5.7).
+//
+// Field-by-field type-checked parsing of `ctx.options`; invalid values fall
+// back to the default with a warning so a typo never breaks loading.
+import { log } from "./log"
+
+export type Options = {
+  enabled: boolean
+  settleMs: number
+  minNudgeIntervalMs: number
+  stallMinutes: number
+  maxNoProgressNudges: number
+  injectTodoContext: boolean
+  markdownFiles: string[]
+  scope: "project" | "all"
+  pauseOnInterrupt: boolean
+  debugEvents: boolean
+}
+
+export const DEFAULTS: Options = {
+  enabled: true,
+  settleMs: 5000,
+  minNudgeIntervalMs: 45000,
+  stallMinutes: 5,
+  maxNoProgressNudges: 5,
+  injectTodoContext: true,
+  markdownFiles: [],
+  scope: "project",
+  pauseOnInterrupt: true,
+  debugEvents: false,
+}
+
+function readNumber(
+  input: Record<string, unknown>,
+  key: keyof Options,
+  min: number,
+  apply: (value: number) => void,
+): void {
+  const raw = input[key]
+  if (raw === undefined) return
+  if (typeof raw === "number" && Number.isFinite(raw) && raw >= min) {
+    apply(raw)
+    return
+  }
+  log(`options: invalid "${key}" (${JSON.stringify(raw)}) — using default ${String(DEFAULTS[key])}`)
+}
+
+function readBoolean(
+  input: Record<string, unknown>,
+  key: keyof Options,
+  apply: (value: boolean) => void,
+): void {
+  const raw = input[key]
+  if (raw === undefined) return
+  if (typeof raw === "boolean") {
+    apply(raw)
+    return
+  }
+  log(`options: invalid "${key}" (${JSON.stringify(raw)}) — using default ${String(DEFAULTS[key])}`)
+}
+
+export function parseOptions(raw: unknown): Options {
+  const options: Options = { ...DEFAULTS, markdownFiles: [] }
+
+  if (raw === undefined || raw === null) return options
+  if (typeof raw !== "object" || Array.isArray(raw)) {
+    log(`options: expected an object, got ${Array.isArray(raw) ? "array" : typeof raw} — using defaults`)
+    return options
+  }
+
+  const input = raw as Record<string, unknown>
+
+  readNumber(input, "settleMs", 0, (v) => (options.settleMs = v))
+  readNumber(input, "minNudgeIntervalMs", 0, (v) => (options.minNudgeIntervalMs = v))
+  readNumber(input, "stallMinutes", 0, (v) => (options.stallMinutes = v))
+  readNumber(input, "maxNoProgressNudges", 0, (v) => (options.maxNoProgressNudges = v))
+
+  readBoolean(input, "enabled", (v) => (options.enabled = v))
+  readBoolean(input, "injectTodoContext", (v) => (options.injectTodoContext = v))
+  readBoolean(input, "pauseOnInterrupt", (v) => (options.pauseOnInterrupt = v))
+  readBoolean(input, "debugEvents", (v) => (options.debugEvents = v))
+
+  const scope = input["scope"]
+  if (scope !== undefined) {
+    if (scope === "project" || scope === "all") options.scope = scope
+    else log(`options: invalid "scope" (${JSON.stringify(scope)}) — using default "project"`)
+  }
+
+  const files = input["markdownFiles"]
+  if (files !== undefined) {
+    if (Array.isArray(files) && files.every((entry) => typeof entry === "string")) {
+      options.markdownFiles = (files as string[]).map((s) => s.trim()).filter((s) => s.length > 0)
+    } else {
+      log(`options: invalid "markdownFiles" — using default []`)
+    }
+  }
+
+  // Unknown keys are intentionally ignored (§5.7).
+  return options
+}

package/src/panel.test.ts

@@ -0,0 +1,193 @@
+// todo-supervisor — pure panel helper tests (aspect 12).
+import { describe, expect, test } from "bun:test"
+import {
+  buildRows,
+  clampCursor,
+  countOpen,
+  dialogWidth,
+  footerHints,
+  isSelectable,
+  moveCursor,
+  popoverBodyHeight,
+  progressBar,
+  quietLabel,
+  statusMark,
+  supervisorChip,
+  truncate,
+  visibleWindow,
+  type PanelSnapshot,
+} from "./panel"
+
+const snapshot = (): PanelSnapshot => ({
+  items: [
+    { content: "first task", status: "pending", priority: "high" },
+    { content: "second task", status: "in_progress" },
+    { content: "third task", status: "completed" },
+  ],
+  files: [
+    {
+      path: "/proj/docs/TODO.md",
+      exists: true,
+      items: [
+        { content: "file item one", status: "pending", line: 3 },
+        { content: "file item two", status: "completed", line: 4 },
+      ],
+    },
+    { path: "/proj/GONE.md", exists: false, items: [] },
+  ],
+  supervisor: { registered: true, status: "idle", quietMs: 12_000, terminal: true, nudges: 2 },
+})
+
+describe("panel formatting", () => {
+  test("status marks and open counts match todo_read", () => {
+    expect([statusMark("completed"), statusMark("in_progress"), statusMark("canceled"), statusMark("pending")]).toEqual([
+      "[x]",
+      "[~]",
+      "[~]",
+      "[ ]",
+    ])
+    expect(countOpen([{ status: "completed" }, { status: "pending" }, { status: "in_progress" }])).toBe(2)
+  })
+
+  test("progress bar fills by ratio and degrades safely", () => {
+    expect(progressBar(0, 8, 8)).toBe("░░░░░░░░")
+    expect(progressBar(4, 8, 8)).toBe("████░░░░")
+    expect(progressBar(8, 8, 8)).toBe("████████")
+    expect(progressBar(1, 3, 0)).toBe("")
+    expect(progressBar(0, 0, 4)).toBe("░░░░")
+  })
+
+  test("truncate collapses whitespace and ellipsises", () => {
+    expect(truncate("  a   b  ", 10)).toBe("a b")
+    expect(truncate("exact", 5)).toBe("exact")
+    expect(truncate("too long here", 6)).toBe("too l…")
+    expect(truncate("abc", 1)).toBe("…")
+    expect(truncate("abc", 0)).toBe("")
+  })
+
+  test("quiet labels and the supervisor chip describe state", () => {
+    expect(quietLabel(3_400)).toBe("3s")
+    expect(quietLabel(80_000)).toBe("1m20s")
+    expect(quietLabel(undefined)).toBe("—")
+
+    expect(supervisorChip(undefined)).toBe("not supervised")
+    expect(supervisorChip({ registered: false })).toBe("not supervised")
+    expect(supervisorChip({ registered: true, paused: true, pauseReason: "no-progress", nudges: 3 })).toBe(
+      "paused (no-progress) · nudges 3",
+    )
+    expect(
+      supervisorChip({ registered: true, runningTools: 1, runningShells: 2, quietMs: 4_000 }),
+    ).toBe("working: 1 tool · 2 shells · quiet 4s")
+    expect(supervisorChip({ registered: true, terminal: false, quietMs: 90_000 })).toBe(
+      "waiting for turn end · quiet 1m30s",
+    )
+    expect(supervisorChip({ registered: true, status: "idle", terminal: true, quietMs: 2_000, nudges: 1 })).toBe(
+      "idle · quiet 2s · nudges 1",
+    )
+  })
+})
+
+describe("panel rows", () => {
+  test("builds the session section, file sections and items", () => {
+    const rows = buildRows(snapshot())
+    expect(rows.map((row) => row.kind)).toEqual([
+      "section",
+      "item",
+      "item",
+      "item",
+      "file",
+      "item",
+      "item",
+      "file",
+    ])
+    const sessionHeader = rows[0]!
+    expect(sessionHeader.kind === "section" && sessionHeader.detail).toBe("2 open of 3")
+    const firstItem = rows[1]!
+    expect(firstItem.kind === "item" && firstItem.key).toBe("session:0")
+    expect(firstItem.kind === "item" && firstItem.priority).toBe("high")
+    const fileRow = rows[4]!
+    expect(fileRow.kind === "file" && fileRow.open).toBe(1)
+    expect(fileRow.kind === "file" && fileRow.exists).toBe(true)
+    const missing = rows[7]!
+    expect(missing.kind === "file" && missing.exists).toBe(false)
+  })
+
+  test("collapsed files hide their items; formatPath is applied", () => {
+    const rows = buildRows(snapshot(), { collapsed: new Set(["/proj/docs/TODO.md"]), formatPath: () => "docs/TODO.md" })
+    expect(rows.filter((row) => row.kind === "item" && row.source === "file").length).toBe(0)
+    const fileRow = rows.find((row) => row.kind === "file")!
+    expect(fileRow.kind === "file" && fileRow.label).toBe("docs/TODO.md")
+    expect(fileRow.kind === "file" && fileRow.collapsed).toBe(true)
+  })
+
+  test("filter hides non-matching items and whole sections", () => {
+    const rows = buildRows(snapshot(), { filter: "FILE ITEM ONE" })
+    expect(rows.filter((row) => row.kind === "item").map((row) => row.kind === "item" && row.content)).toEqual([
+      "file item one",
+    ])
+    expect(rows.some((row) => row.kind === "section")).toBe(false)
+    const none = buildRows(snapshot(), { filter: "zzz" })
+    expect(none.length).toBe(1)
+    expect(none[0]!.kind === "section" && none[0]!.label).toBe("no matches")
+  })
+
+  test("empty and all-done states", () => {
+    const empty = buildRows({ items: [], files: [] })
+    expect(empty[0]!.kind === "section" && empty[0]!.label).toBe("no todos")
+    const done = buildRows({ items: [{ content: "done", status: "completed" }], files: [] })
+    expect(done.some((row) => row.kind === "section" && row.key === "section:done")).toBe(true)
+    expect(done.some((row) => row.kind === "item")).toBe(true)
+  })
+})
+
+describe("panel cursor", () => {
+  test("clamp keeps a live key and falls back to the first selectable row", () => {
+    const rows = buildRows(snapshot())
+    expect(clampCursor(rows, "session:1")).toBe("session:1")
+    expect(clampCursor(rows, "gone")).toBe("session:0")
+    expect(clampCursor(rows, undefined)).toBe("session:0")
+    expect(clampCursor([], "x")).toBe(undefined)
+  })
+
+  test("movement skips section headers and clamps at both ends", () => {
+    const rows = buildRows(snapshot())
+    expect(isSelectable(rows[0]!)).toBe(false)
+    expect(moveCursor(rows, "session:0", 1)).toBe("session:1")
+    expect(moveCursor(rows, "session:2", 1)).toBe("file:/proj/docs/TODO.md")
+    expect(moveCursor(rows, "session:0", -1)).toBe("session:0")
+    expect(moveCursor(rows, "file:/proj/GONE.md", 1)).toBe("file:/proj/GONE.md")
+    expect(moveCursor([], "x", 1)).toBe(undefined)
+  })
+
+  test("the scroll window keeps the selected row visible", () => {
+    const rows = buildRows(snapshot())
+    expect(visibleWindow(rows, "session:0", 20)).toEqual({ start: 0, end: rows.length })
+    const window = visibleWindow(rows, "file:/proj/GONE.md", 3)
+    expect(window.end - window.start).toBe(3)
+    expect(window.start).toBe(rows.length - 3)
+  })
+
+  test("footer hints shrink with the terminal width", () => {
+    expect(footerHints(140).length).toBe(13)
+    expect(footerHints(90).length).toBe(8)
+    expect(footerHints(40)).toEqual(["↑↓", "space toggle", "n nudge", "/ filter", "? help", "esc"])
+  })
+
+  test("popover body height stays a popover on any terminal", () => {
+    expect(popoverBodyHeight(40)).toBe(16)
+    expect(popoverBodyHeight(24)).toBe(14)
+    expect(popoverBodyHeight(24, 1)).toBe(13)
+    expect(popoverBodyHeight(14)).toBe(4)
+    expect(popoverBodyHeight(50, 2)).toBe(16)
+  })
+
+  test("popover width follows the dialog size and clamps", () => {
+    expect(dialogWidth("medium", 200)).toBe(72)
+    expect(dialogWidth("large", 200)).toBe(140)
+    expect(dialogWidth("xlarge", 200)).toBe(140)
+    expect(dialogWidth("medium", 80)).toBe(56)
+    expect(dialogWidth("large", 80)).toBe(64)
+    expect(dialogWidth("xlarge", 80)).toBe(72)
+    expect(dialogWidth("xlarge", 20)).toBe(36)
+  })
+})