@pmelab/gtd 23.2.0 → 24.1.0

package/src/steering/freeform.test.ts

@@ -0,0 +1,311 @@
+import { describe, expect, it } from "vitest"
+import { freeFormFormat } from "./freeform.js"
+import { BUILT_IN_MODE_NAMES, steeringFormatFor } from "./index.js"
+
+/** Applies edits back-to-front — a local copy of the file's own splice pattern, mirroring `qa.test.ts`/`review.test.ts`'s identical helper. */
+const applyEdits = (
+  content: string,
+  edits: readonly { range: unknown; newText: string }[],
+): string => {
+  const lines = content.split(/\r?\n/)
+  const toOffset = (position: { line: number; character: number }): number => {
+    let offset = 0
+    for (let i = 0; i < position.line; i += 1) offset += (lines[i]?.length ?? 0) + 1
+    return offset + position.character
+  }
+  const sorted = [...edits].sort((a, b) => {
+    const ra = a.range as { start: { line: number; character: number } }
+    const rb = b.range as { start: { line: number; character: number } }
+    return toOffset(rb.start) - toOffset(ra.start)
+  })
+  let result = content
+  for (const edit of sorted) {
+    const range = edit.range as {
+      start: { line: number; character: number }
+      end: { line: number; character: number }
+    }
+    const start = toOffset(range.start)
+    const end = toOffset(range.end)
+    result = result.slice(0, start) + edit.newText + result.slice(end)
+  }
+  return result
+}
+
+/**
+ * Applies edits with the SAME offset convention `applySteeringEdits`
+ * (`src/ui/Write.ts`) uses in production: lines split on a bare `"\n"`, so a
+ * CRLF line keeps its `\r` as part of the line's own length. `applyEdits`
+ * above (this file's pre-existing helper) instead splits on `/\r?\n/`, which
+ * strips `\r` and undercounts offsets in a CRLF document — fine for the
+ * LF-only fixtures every other test in this file uses, but it would silently
+ * corrupt the byte-exact CRLF assertions below. Not a normalizing helper:
+ * mismatched newText/range still round-trips to the WRONG bytes, exactly as
+ * production would.
+ */
+const applyEditsExact = (
+  content: string,
+  edits: readonly { range: unknown; newText: string }[],
+): string => {
+  const lines = content.split("\n")
+  const toOffset = (position: { line: number; character: number }): number => {
+    let offset = 0
+    for (let i = 0; i < position.line; i += 1) offset += (lines[i]?.length ?? 0) + 1
+    return offset + position.character
+  }
+  const sorted = [...edits].sort((a, b) => {
+    const ra = a.range as { start: { line: number; character: number } }
+    const rb = b.range as { start: { line: number; character: number } }
+    return toOffset(rb.start) - toOffset(ra.start)
+  })
+  let result = content
+  for (const edit of sorted) {
+    const range = edit.range as {
+      start: { line: number; character: number }
+      end: { line: number; character: number }
+    }
+    const start = toOffset(range.start)
+    const end = toOffset(range.end)
+    result = result.slice(0, start) + edit.newText + result.slice(end)
+  }
+  return result
+}
+
+describe("freeFormFormat — registry", () => {
+  it("is not registered: steeringFormatFor('freeform') returns undefined", () => {
+    expect(steeringFormatFor("freeform")).toBeUndefined()
+  })
+
+  it("is not among the built-in mode names", () => {
+    expect(BUILT_IN_MODE_NAMES).not.toContain("freeform")
+  })
+})
+
+describe("freeFormFormat.sample", () => {
+  it("validates clean", () => {
+    expect(freeFormFormat.validate(freeFormFormat.sample)).toEqual([])
+  })
+})
+
+describe("freeFormFormat.validate/outline/actions", () => {
+  it("validate always returns []", () => {
+    expect(freeFormFormat.validate("# Anything\n\nGoes.\n")).toEqual([])
+  })
+
+  it("outline is [] without threads", () => {
+    expect(freeFormFormat.outline("# Anything\n\nGoes.\n")).toEqual([])
+  })
+
+  it("actions are [] away from a thread", () => {
+    expect(
+      freeFormFormat.actions("Some prose.\n", {
+        start: { line: 0, character: 0 },
+        end: { line: 0, character: 0 },
+      }),
+    ).toEqual([])
+  })
+
+  it("has no pointerAt or documentLinks", () => {
+    expect(freeFormFormat.pointerAt).toBeUndefined()
+    expect(freeFormFormat.documentLinks).toBeUndefined()
+  })
+})
+
+describe("freeFormFormat.view", () => {
+  it("returns every top-level block, in document order, each with a {kind:'paragraph', line} anchor", () => {
+    const content = ["# Heading", "", "- one", "- two", "", "Paragraph.", ""].join("\n")
+    const view = freeFormFormat.view(content)
+    expect(view.nodes.map((n) => n.anchor)).toEqual([
+      { kind: "paragraph", line: 0 },
+      { kind: "paragraph", line: 2 },
+      { kind: "paragraph", line: 5 },
+    ])
+  })
+
+  it("a fenced ts code block's own text is the fence-stripped body, byte-identical to qa/review's own view", () => {
+    const content = ["```ts", "const x = 1", "```", ""].join("\n")
+    const view = freeFormFormat.view(content)
+    expect(view.nodes.map((n) => n.block?.text)).toEqual(["const x = 1"])
+  })
+
+  it("a two-line '>' quote's own text is marker-free, byte-identical to qa/review's own view", () => {
+    const content = ["> quoted line", "> more", ""].join("\n")
+    const view = freeFormFormat.view(content)
+    expect(view.nodes.map((n) => n.block?.text)).toEqual(["quoted line more"])
+  })
+})
+
+describe("freeFormFormat.apply — a block-start anchor now refuses", () => {
+  it("refuses anchor-not-found for a line matching a top-level block's own start line, on a non-empty document", () => {
+    const content = ["# Heading", "", "Paragraph one.", "", "Paragraph two.", ""].join("\n")
+    const result = freeFormFormat.apply(content, { kind: "paragraph", line: 2 }, { text: "x" })
+    expect(result).toEqual({ ok: false, reason: "anchor-not-found" })
+  })
+
+  it("refuses a heading's own start line the same way", () => {
+    const content = ["# Old heading", "", "Body.", ""].join("\n")
+    const result = freeFormFormat.apply(content, { kind: "paragraph", line: 0 }, { text: "# New" })
+    expect(result).toEqual({ ok: false, reason: "anchor-not-found" })
+  })
+})
+
+describe("freeFormFormat.apply — appending", () => {
+  it("a line at the document's last line appends text at the end, preceded by a blank line", () => {
+    const content = ["Paragraph one.", ""].join("\n")
+    const lastLine = content.split(/\r?\n/).length - 1
+    const result = freeFormFormat.apply(
+      content,
+      { kind: "paragraph", line: lastLine },
+      { text: "New content." },
+    )
+    expect(result.ok).toBe(true)
+    const applied = result.ok ? applyEdits(content, result.edits) : ""
+    expect(applied).toBe(["Paragraph one.", "", "New content.", ""].join("\n"))
+  })
+
+  it("a line well past the document's end also appends", () => {
+    const content = ["Paragraph one.", ""].join("\n")
+    const result = freeFormFormat.apply(
+      content,
+      { kind: "paragraph", line: 9999 },
+      { text: "New content." },
+    )
+    expect(result.ok).toBe(true)
+    const applied = result.ok ? applyEdits(content, result.edits) : ""
+    expect(applied).toBe(["Paragraph one.", "", "New content.", ""].join("\n"))
+  })
+
+  it("appending to an empty document produces just the new text", () => {
+    const result = freeFormFormat.apply("", { kind: "paragraph", line: 0 }, { text: "First line." })
+    expect(result.ok).toBe(true)
+    const applied = result.ok ? applyEdits("", result.edits) : ""
+    expect(applied).toBe("First line.\n")
+  })
+
+  it("the empty-document save path: Number.MAX_SAFE_INTEGER against '' reaches the append edit, reading no block's raw text", () => {
+    const result = freeFormFormat.apply(
+      "",
+      { kind: "paragraph", line: Number.MAX_SAFE_INTEGER },
+      { text: "x" },
+    )
+    expect(result.ok).toBe(true)
+    const applied = result.ok ? applyEdits("", result.edits) : ""
+    expect(applied).toBe("x\n")
+  })
+
+  it("an empty append (opts.text omitted, an append row submitted with nothing typed) leaves the document unchanged, not a bare trailing blank line", () => {
+    const content = ["Paragraph one.", ""].join("\n")
+    const lastLine = content.split(/\r?\n/).length - 1
+    const result = freeFormFormat.apply(content, { kind: "paragraph", line: lastLine }, {})
+    expect(result.ok).toBe(true)
+    const applied = result.ok ? applyEdits(content, result.edits) : ""
+    expect(applied).toBe(["Paragraph one.", ""].join("\n"))
+  })
+})
+
+describe("freeFormFormat.apply — no block at that line", () => {
+  it("refuses anchor-not-found for a line resolving to no block, not past the end", () => {
+    const content = ["Paragraph one.", "", "Paragraph two.", ""].join("\n")
+    const result = freeFormFormat.apply(content, { kind: "paragraph", line: 1 }, { text: "x" })
+    expect(result).toEqual({ ok: false, reason: "anchor-not-found" })
+  })
+})
+
+describe("freeFormFormat.apply — wrong anchor kind", () => {
+  it("refuses a non-paragraph anchor", () => {
+    const content = "Paragraph.\n"
+    const result = freeFormFormat.apply(content, { kind: "chunk", index: 0 }, { text: "x" })
+    expect(result).toEqual({ ok: false, reason: "anchor-not-found" })
+  })
+})
+
+describe("freeFormFormat.annotate", () => {
+  it("delegates to Footnotes.ts#footnoteAttachEdits: attaches a marker and a definition", () => {
+    const content = ["Paragraph one.", ""].join("\n")
+    const result = freeFormFormat.annotate(content, { kind: "paragraph", line: 0 }, "A note.")
+    expect(result.ok).toBe(true)
+    const applied = result.ok ? applyEdits(content, result.edits) : ""
+    expect(applied).toContain("Paragraph one.[^")
+    expect(applied).toContain("A note.")
+    expect(freeFormFormat.validate(applied)).toEqual([])
+  })
+
+  it("creates a thread, appends to an open one, replaces on a waiting one — each validates clean", () => {
+    const anchor = { kind: "paragraph" as const, line: 0 }
+    const attach = (content: string, text: string): string => {
+      const r = freeFormFormat.annotate(content, anchor, text)
+      if (!r.ok) throw new Error("refused")
+      return applyEdits(content, r.edits)
+    }
+    const created = attach("Paragraph one.\n", "first")
+    expect(created).toMatch(/\[\^na\w+\]:\n    - H: first\n/)
+    expect(freeFormFormat.validate(created)).toEqual([])
+    const replaced = attach(created, "second")
+    expect(replaced).toContain("- H: second")
+    expect(replaced).not.toContain("first")
+    const open = replaced.replace("- H: second", "- H: second\n    - A: why?")
+    const replied = attach(open, "because")
+    expect(replied).toContain("    - A: why?\n    - H: because")
+    expect(freeFormFormat.validate(replied)).toEqual([])
+  })
+
+  it("refuses a non-paragraph anchor", () => {
+    const result = freeFormFormat.annotate("x\n", { kind: "hunk", chunkIndex: 0, index: 0 }, "note")
+    expect(result).toEqual({ ok: false, reason: "anchor-not-found" })
+  })
+
+  it("refuses when the line isn't inside any real block", () => {
+    const content = ["Paragraph one.", "", "Paragraph two.", ""].join("\n")
+    const result = freeFormFormat.annotate(content, { kind: "paragraph", line: 1 }, "note")
+    expect(result).toEqual({ ok: false, reason: "anchor-not-found" })
+  })
+})
+
+describe("freeFormFormat.apply — CRLF documents preserve untouched bytes", () => {
+  it("a block-start anchor refuses on a CRLF document exactly as it does on LF", () => {
+    const content = ["# Heading", "", "Paragraph one.", "", "Paragraph two.", ""].join("\r\n")
+    const result = freeFormFormat.apply(
+      content,
+      { kind: "paragraph", line: 2 },
+      { text: "Edited." },
+    )
+    expect(result).toEqual({ ok: false, reason: "anchor-not-found" })
+  })
+
+  it("appending to a CRLF document uses CRLF for the new bytes too", () => {
+    const content = ["Paragraph one.", ""].join("\r\n")
+    const lastLine = content.split(/\r?\n/).length - 1
+    const result = freeFormFormat.apply(
+      content,
+      { kind: "paragraph", line: lastLine },
+      { text: "New content." },
+    )
+    expect(result.ok).toBe(true)
+    const applied = result.ok ? applyEditsExact(content, result.edits) : ""
+    expect(applied).toBe(["Paragraph one.", "", "New content.", ""].join("\r\n"))
+  })
+
+  it("pasting LF text into a CRLF document via append introduces no mixed endings", () => {
+    const content = ["# Heading", "", "Paragraph one.", ""].join("\r\n")
+    const lastLine = content.split(/\r?\n/).length - 1
+    const result = freeFormFormat.apply(
+      content,
+      { kind: "paragraph", line: lastLine },
+      { text: "Line one.\nLine two." },
+    )
+    expect(result.ok).toBe(true)
+    const applied = result.ok ? applyEditsExact(content, result.edits) : ""
+    expect(applied).toBe(
+      ["# Heading", "", "Paragraph one.", "", "Line one.", "Line two.", ""].join("\r\n"),
+    )
+    expect(applied.replace(/\r\n/g, "")).not.toContain("\n")
+  })
+})
+
+describe("freeFormFormat — thread outline", () => {
+  it("free-form lists threads at top level", () => {
+    const doc = "Text [^a].\n\n[^a]:\n    - H: hi\n    - A: yo\n"
+    expect(freeFormFormat.outline(doc).map((n) => [n.name, n.detail])).toEqual([
+      ["[^a]", "waiting on you"],
+    ])
+  })
+})

package/src/steering/freeform.ts

@@ -0,0 +1,148 @@
+import { blockNodesOf } from "./Blocks.js"
+import { eolOf } from "./Eol.js"
+import {
+  footnoteAttachEdits,
+  openThreadsOf,
+  threadFindings,
+  threadOutlineNodes,
+  threadReplyActions,
+  type FootnoteAnchor,
+} from "./Footnotes.js"
+import { blockNodeAt, parseMarkdown, toLspPosition } from "./MarkdownTree.js"
+import type {
+  SteeringAnnotateResult,
+  SteeringEdit,
+  SteeringFormat,
+  SteeringView,
+} from "./SteeringFormat.js"
+
+const FREE_FORM_SAMPLE = `Sample plan. Add a thing.
+
+## Notes
+
+Nothing here is validated — free-form has no structure to conform to.
+`
+
+/** Resolves a `paragraph` anchor: attaches at the end of `line`'s own text, the definition landing after that line's containing top-level block node. `undefined` when `line` isn't inside a real block — mirrors `qa.ts`/`review.ts`'s identical resolver. */
+const resolveParagraphAnchor = (
+  tree: ReturnType<typeof parseMarkdown>,
+  lines: readonly string[],
+  line: number,
+): FootnoteAnchor | undefined => {
+  const block = blockNodeAt(tree, line)
+  if (!block?.position) return undefined
+  return {
+    line,
+    endCharacter: (lines[line] ?? "").length,
+    blockEndLine: toLspPosition(block.position.end).line,
+    key: `paragraph:${line}`,
+  }
+}
+
+/** Free-form's `annotate`: only a `paragraph` anchor resolves here (it's the only kind `view` ever reports) — delegates the two-edit mechanics to `Footnotes.ts#footnoteAttachEdits`, exactly as both built-ins do. */
+const freeFormAnnotate: SteeringFormat["annotate"] = (
+  content,
+  anchor,
+  text,
+): SteeringAnnotateResult => {
+  if (anchor.kind !== "paragraph") return { ok: false, reason: "anchor-not-found" }
+  const tree = parseMarkdown(content)
+  const lines = content.split(/\r?\n/)
+  const resolved = resolveParagraphAnchor(tree, lines, anchor.line)
+  if (!resolved) return { ok: false, reason: "anchor-not-found" }
+  const result = footnoteAttachEdits(content, resolved, text)
+  if (!result.ok) return result
+  return { ok: true, edits: result.edits }
+}
+
+/**
+ * A single edit spanning the WHOLE document, replacing it with `newText` —
+ * free-form's `apply` reasons about the resulting document as a plain string
+ * (splice/join on lines) rather than surgical offset math, since there is no
+ * structure here to preserve beyond the blocks themselves. Its end position
+ * is computed from a plain `"\n"` split — matching `applySteeringEdits`'s own
+ * offset convention (a CRLF line keeps its `\r` as part of the line's own
+ * length) rather than `/\r?\n/`, which would strip it and undercount.
+ */
+const wholeDocumentEdit = (content: string, newText: string): SteeringEdit => {
+  const lines = content.split("\n")
+  return {
+    range: {
+      start: { line: 0, character: 0 },
+      end: { line: lines.length - 1, character: (lines[lines.length - 1] ?? "").length },
+    },
+    newText,
+  }
+}
+
+/**
+ * The append edit: `text` lands at the very end of the document, preceded by
+ * exactly one blank line — trailing whitespace on the existing document is
+ * trimmed first so this is idempotent regardless of how many blank lines
+ * already trail it. An empty `text` (an append row submitted with nothing
+ * typed) appends nothing rather than a bare trailing blank line.
+ */
+const appendEdit = (content: string, text: string): SteeringEdit => {
+  const eol = eolOf(content)
+  const trimmed = content.replace(/\s+$/, "")
+  const normalizedText = text.split(/\r?\n/).join(eol)
+  if (text.length === 0)
+    return wholeDocumentEdit(content, trimmed.length > 0 ? `${trimmed}${eol}` : "")
+  const newText =
+    trimmed.length > 0 ? `${trimmed}${eol}${eol}${normalizedText}${eol}` : `${normalizedText}${eol}`
+  return wholeDocumentEdit(content, newText)
+}
+
+/**
+ * Free-form's `apply`: only a `paragraph` anchor resolves (the only kind
+ * `view` ever reports), and it only ever APPENDS, at or past the document's
+ * last line. An `anchor.line` landing on a real top-level block's own start
+ * line — or anywhere else inside the document short of its last line —
+ * refuses `anchor-not-found`: per-block replace/delete were dropped with the
+ * phone's own per-block editing UI (this package), leaving append as the
+ * only write this format still performs.
+ */
+const freeFormApply: SteeringFormat["apply"] = (content, anchor, opts): SteeringAnnotateResult => {
+  if (anchor.kind !== "paragraph") return { ok: false, reason: "anchor-not-found" }
+  const text = opts.text ?? ""
+  const tree = parseMarkdown(content)
+  const lines = content.split(/\r?\n/)
+  const lastLineIndex = lines.length - 1
+  const isBlockStart = tree.children.some(
+    (node) =>
+      node.position !== undefined && toLspPosition(node.position.start).line === anchor.line,
+  )
+
+  if (isBlockStart) return { ok: false, reason: "anchor-not-found" }
+  if (anchor.line < lastLineIndex) return { ok: false, reason: "anchor-not-found" }
+  return { ok: true, edits: [appendEdit(content, text)] }
+}
+
+/** Free-form's `view`: every top-level block, in document order — no format-specific structure (no questions, no chunks) to project beyond the shared block walk. */
+const freeFormView = (content: string): SteeringView => {
+  const tree = parseMarkdown(content)
+  return { nodes: blockNodesOf(content, tree) }
+}
+
+/**
+ * The free-form `SteeringFormat`: no structure to validate, outline, or
+ * offer code actions over — a mode-less steering file has no schema to
+ * conform to, so `validate`/`outline`/`actions` are all constant `[]`, and
+ * there is nothing to jump to (`pointerAt`/`documentLinks` stay absent).
+ * Exported but deliberately NOT registered in `index.ts#REGISTRY` — this
+ * package's later tasks wire it in as the FALLBACK for an absent or
+ * unregistered `mode`, never a mode name of its own.
+ */
+export const freeFormFormat: SteeringFormat = {
+  sample: FREE_FORM_SAMPLE,
+  validate: threadFindings,
+  openThreads: openThreadsOf,
+  outline: (content) => threadOutlineNodes(content).map((t) => t.node),
+  actions: (content, range) => threadReplyActions(content, range.start),
+  view: freeFormView,
+  annotate: freeFormAnnotate,
+  apply: freeFormApply,
+  // Nothing here is a read-progress tick: free-form has no structure whose
+  // checkboxes mean anything to this engine.
+  clearTicks: (content) => content,
+}

package/src/steering/index.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from "vitest"
+import { BUILT_IN_MODE_NAMES, steeringFormatFor, unansweredQuestions, viewOf } from "./index.js"
+
+const qa = steeringFormatFor("qa")!
+const review = steeringFormatFor("review")!
+
+describe("steeringFormatFor / BUILT_IN_MODE_NAMES", () => {
+  it("resolves both built-in modes by name", () => {
+    expect(steeringFormatFor("qa")).toBeDefined()
+    expect(steeringFormatFor("review")).toBeDefined()
+  })
+
+  it("is undefined for a name that isn't a built-in mode", () => {
+    expect(steeringFormatFor("bogus")).toBeUndefined()
+  })
+
+  it("lists both built-in mode names, in registry order", () => {
+    expect(BUILT_IN_MODE_NAMES).toEqual(["qa", "review"])
+  })
+})
+
+describe("dispatch over a resolved format — cross-format safety", () => {
+  it("each registered format validates with its own rule, not a shared or wrong one", () => {
+    expect(qa.validate("")).toEqual([])
+    expect(review.validate("").length).toBeGreaterThan(0)
+  })
+
+  it("unansweredQuestions is qa-only — review always answers []", () => {
+    expect(unansweredQuestions(review, review.sample)).toEqual([])
+  })
+
+  it("clearTicks is format-parameterised — running review's clearTicks over qa-shaped content is a no-op", () => {
+    const qaShapedContent = [
+      "Plan.",
+      "",
+      "## Open Questions",
+      "",
+      "### Q?",
+      "",
+      "- [x] Option A",
+      "- [ ] Option B",
+      "",
+    ].join("\n")
+    expect(qa.clearTicks(qaShapedContent)).toBe(qaShapedContent)
+    expect(review.clearTicks(qaShapedContent)).toBe(qaShapedContent)
+  })
+})
+
+describe("viewOf", () => {
+  it("qa's view has no documentLinks (qa declares none) but does have an outline", () => {
+    const view = viewOf(qa, qa.sample)
+    expect(view.documentLinks).toEqual([])
+    expect(view.outline.length).toBeGreaterThan(0)
+  })
+
+  it("review's documentLinks carry the hunk pointer's own range, matching its outline's hunk-adjacent chunk range", () => {
+    const view = viewOf(review, review.sample)
+    expect(view.documentLinks.length).toBe(1)
+    expect(view.documentLinks[0]!.path).toBe("./sample.ts")
+    expect(view.documentLinks[0]!.line).toBe(0)
+  })
+})

package/src/steering/index.ts

@@ -0,0 +1,140 @@
+import type {
+  SteeringAction,
+  SteeringFormat,
+  SteeringLink,
+  SteeringOutlineNode,
+  SteeringPointer,
+} from "./SteeringFormat.js"
+import { qaDescriptor } from "./qa.js"
+import { reviewDescriptor } from "./review.js"
+export { reviewNotes, reviewRisks, type ReviewNote } from "./review.js"
+export { applySteeringEdits } from "./Edits.js"
+
+export type { InlineNode } from "./Inline.js"
+
+// The free-form format: the mode-less/unregistered-mode FALLBACK —
+// deliberately not a `REGISTRY` entry of its own, since it is never a mode a
+// `mode:` key names.
+import { freeFormFormat } from "./freeform.js"
+export { freeFormFormat }
+
+export type {
+  BlockListItem,
+  SteeringAction,
+  SteeringAnchor,
+  SteeringFinding,
+  SteeringFormat,
+  SteeringLink,
+  SteeringOutlineNode,
+  SteeringPointer,
+  SteeringView,
+  SteeringViewNode,
+  SteeringViewThread,
+} from "./SteeringFormat.js"
+
+/** The built-in registry: mode name → its format, in registry order. The single place `qa` and `review` are wired into names — everything else in this module dispatches over a resolved `SteeringFormat`, never a mode-name string. */
+const REGISTRY: ReadonlyMap<string, SteeringFormat> = new Map([
+  ["qa", qaDescriptor],
+  ["review", reviewDescriptor],
+])
+
+/** Every built-in format name, in registry order. */
+export const BUILT_IN_MODE_NAMES: readonly string[] = [...REGISTRY.keys()]
+
+// The two `qa` primitives the phone client itself needs: `src/web/screens/
+// Question.tsx` renders the free-text slot and derives answeredness in the
+// browser, against the SAME constant and predicate the server validates
+// with — a second copy there would drift silently.
+export { FREE_TEXT_PLACEHOLDER, isAnswered } from "./qa.js"
+
+// `ModeContradiction.ts`'s round-trip check re-parses a formatted sample's
+// footnotes to prove the formatter moved none of them — the one consumer
+// outside this package that needs the footnote parser itself, not a format.
+export {
+  parseFootnotes,
+  parseThreads,
+  parseThreadsWithFindings,
+  openThreadFindings,
+  FOOTNOTE_ACTION_TITLE,
+  THREAD_REPLY_ACTION_TITLE,
+} from "./Footnotes.js"
+
+// Test-observability only: the memo-hit counter is the one way "one parse per
+// document" is assertable from outside `MarkdownTree.ts` — timing is not.
+export { getParseCount } from "./MarkdownTree.js"
+
+// A flow's `sections()` is the one caller outside this package.
+export { headingSectionBodies, headingSections } from "./MarkdownTree.js"
+
+/** The built-in `SteeringFormat` registered under `mode`'s name, or `undefined` when it isn't a built-in mode at all. The one place a bare mode-name string is ever looked up — every consumer takes the RESOLVED value this returns, never a name, so "mode is required, never inferred from a file's basename" is a type, not a rule to remember. */
+export const steeringFormatFor = (mode: string): SteeringFormat | undefined => REGISTRY.get(mode)
+
+/**
+ * The ui boundary's own resolution: `mode`'s registered format, or
+ * `freeFormFormat` when `mode` is absent or names nothing in `REGISTRY` —
+ * never `undefined`. `resolveMode` (`SteeringMode.ts`) stays on
+ * `steeringFormatFor` alone, so a workflow naming a mode nothing defines
+ * still fails to compile; this fallback is deliberately reachable only from
+ * `src/ui/View.ts` and `src/ui/Write.ts`, where a mode-less/unknown-mode
+ * document must still render and accept a paragraph note, never refuse.
+ */
+export const steeringFormatOrFreeForm = (mode: string | undefined): SteeringFormat =>
+  (mode !== undefined ? REGISTRY.get(mode) : undefined) ?? freeFormFormat
+
+/**
+ * `qa`-only: every OPEN question in `content` not yet answered, as
+ * `{ question, headingLine }` pairs — enough for a refusal message ("which
+ * question", "where"). Semantically distinct from `validate`'s findings:
+ * a document can be perfectly well-formed (zero findings) while still having
+ * open questions nobody has answered, which is the whole point of the
+ * answer-completeness gate this feeds. Format-parameterised like everything
+ * else here: `review` (or any future format with no such concept) yields
+ * `[]` rather than this being a `qa`-specific function some caller has to
+ * know not to call on the wrong format.
+ */
+export const unansweredQuestions = (
+  format: SteeringFormat,
+  content: string,
+): readonly { readonly question: string; readonly headingLine: number }[] =>
+  format.unansweredQuestions?.(content) ?? []
+
+/**
+ * Every positional thing an editor (the LSP, in a later pass) needs for one
+ * document, off ONE `viewOf` call rather than four separate ones re-deriving
+ * ranges each time: `outline` and `documentLinks` are already fully resolved
+ * (each node/link carries its own range — see `SteeringOutlineNode`/
+ * `SteeringLink`), while `pointerAt`/`actionsAt` stay closures over `content`
+ * because they need a cursor position/selection range the caller supplies
+ * per request. `Lsp.ts` reads its ranges straight off `outline`/`documentLinks`.
+ */
+export interface SteeringEditorView {
+  readonly outline: readonly SteeringOutlineNode[]
+  readonly documentLinks: readonly SteeringLink[]
+  readonly pointerAt: (position: {
+    readonly line: number
+    readonly character: number
+  }) => SteeringPointer | undefined
+  readonly actionsAt: (range: {
+    readonly start: { readonly line: number; readonly character: number }
+    readonly end: { readonly line: number; readonly character: number }
+  }) => readonly SteeringAction[]
+}
+
+/** Builds `format`'s `SteeringEditorView` of `content` — see `SteeringEditorView`'s own doc for why this is one value, not several. Distinct from `SteeringView` (`SteeringFormat.ts`), which is the format's own node tree the phone client renders. */
+export const viewOf = (format: SteeringFormat, content: string): SteeringEditorView => ({
+  outline: format.outline(content),
+  documentLinks: format.documentLinks ? format.documentLinks(content) : [],
+  pointerAt: (position) => format.pointerAt?.(content, position),
+  actionsAt: (range) => format.actions(content, range),
+})
+
+/** Every OPEN thread — last entry is the agent's — as `{ name, line, firstMe }` (0-based line). `[]` for a format with no thread concept. */
+export const openThreads = (
+  format: SteeringFormat,
+  content: string,
+): readonly { readonly name: string; readonly line: number; readonly firstMe: string }[] =>
+  format.openThreads?.(content) ?? []
+
+// Line-comment `H:`/`A:` threads in changed code files: a flow's `codeThreads()`
+// and `gtd check --open-threads` are the callers outside this package.
+export { parseCodeThreads, stripCodeThreads } from "./CodeThreads.js"