@north-light/api 0.3.579 → 0.3.587

package/dist/clients/inbox/review/document-surface.js

@@ -0,0 +1,1268 @@
+import { relative, resolve } from 'node:path';
+import { CURSOR_MARKER, Key, matchesKey } from '@earendil-works/pi-tui';
+import { documentLines } from '../../../core/document-lines.js';
+import { codeRenderedDoc } from '../../../core/termrender/code-doc.js';
+import { deriveAnchorUnits, remapUnitIndex, unitIndexForLine, unitRangeForSpan } from './anchors.js';
+import { centerHorizontal, clipLine, CYAN, DIM, RESET, REVERSE, sanitize, truncate, visibleWidth, YELLOW } from '../tui/ansi.js';
+import { ReviewDocumentError } from './comments-client.js';
+import { closeCompanionPane, companionPaneLive, openCompanionPane, openForkPane } from './companion-pane.js';
+import { PAN_STEP, docSurface, maxHScroll, panBy, renderReviewDoc, renderReviewFrame, listHintBar, renderWidthForCols, reservedRows, } from './frame.js';
+import { matchReviewKey, reviewKeyText } from './keys.js';
+import { renderInputBuffer } from '../tui/render.js';
+import { openReviewedFileInEditor } from './nvim.js';
+import { buildLineMap, remapRange } from './remap.js';
+import { cleanPastedText, closeCompose, closeHelp, closeList, commitCompose, ensureAnchorVisible, halfPageRows, initReviewState, moveActiveUnit, moveListIndex, moveViewRows, openComposeEdit, openComposeNew, openHelp, openList, scrollBy, textBackspace, textDelete, textEnd, textHome, textInsert, textVerticalWrapped, textWordBackspace, textWordLeft, textWordRight, deleteAtListIndex, undoLast, } from './state.js';
+/** The widest the document is ever rendered, however wide the pane is. */
+const DOC_MAX_COLS = 126;
+/** How many places a half-page move is painted at: three midpoints, then the
+ *  destination. A move of fewer rows than this uses one step per row. */
+const SCROLL_STEPS = 4;
+/** Milliseconds between painted steps. pi-tui paints at most every 16ms, so a
+ *  shorter gap would drop steps instead of showing them. */
+const SCROLL_STEP_MS = 24;
+/** The one mounted review surface: existing review rendering and navigation
+ *  over a live file, with comments projected from the daemon and ranges
+ *  remapped by this terminal as the file changes, plus a status row naming the
+ *  companion pane the conversation lives in. */
+export class ReviewDocumentSurface {
+    absFile;
+    fileLabel;
+    companionNodeId;
+    companionCwd;
+    callerPane;
+    kind;
+    source;
+    comments;
+    services;
+    unsubscribeComments;
+    ready;
+    cols = 0;
+    /** Rows the host assigned this surface; the document frame renders one
+     *  fewer, because the last line is this surface's status row. */
+    hostRows = 0;
+    /** The `hostRows` the current state was last reflowed against. A height
+     *  change matters as much as a width one: `reflow` is what re-runs
+     *  `ensureAnchorVisible` against the new body height, so a pane shrink
+     *  cannot strand the active anchor below the visible body. */
+    flowedRows = -1;
+    _focused = false;
+    closed = false;
+    escapeConfirmArmed = false;
+    cancelArmed = false;
+    submitArmed = false;
+    tornDown = false;
+    /** The disposition {@link teardown} stated, kept only while there was no
+     *  handle to close: the mount that follows disposes every standing notice,
+     *  so {@link setHandle} states it again once the surface is gone. */
+    tornDownNotice;
+    handle;
+    /** The companion pane this surface is bound to, and how it came to be.
+     *  `paneOrigin` is status-row copy only: teardown reads `paneId`. */
+    paneId;
+    paneOrigin;
+    /** Fork columns this surface opened, oldest first. The newest live one is
+     *  what the next fork splits against, so columns accumulate rightward. */
+    forkPanes = [];
+    /** Row increments of a half-page move still to be painted, and the timer
+     *  walking them. A fresh press settles whatever is in flight before starting
+     *  its own move, so a held key cannot pile up overlapping animations. */
+    scrollSteps = [];
+    scrollTimer;
+    state;
+    cache;
+    /** Every non-deleted comment the daemon currently projects, newest last. */
+    projection = [];
+    status = 'preparing';
+    /** This surface's own error/summary state — never a host notice (D1). */
+    problem;
+    composeAnchorLost = false;
+    /** Serializes base-hash transitions so B→C cannot overtake A→B. */
+    remapChain = Promise.resolve();
+    constructor(opts) {
+        this.absFile = opts.review.file;
+        this.fileLabel = labelFor(opts.review.cwd, opts.review.file);
+        this.companionNodeId = opts.review.companionNodeId;
+        this.companionCwd = opts.review.cwd;
+        this.callerPane = opts.callerPane;
+        this.kind = docSurface(opts.review.file);
+        this.source = opts.source;
+        this.comments = opts.comments;
+        this.services = opts.services;
+        this.source.onChange((next, previous) => {
+            this.onSourceChanged(next, previous);
+        });
+        this.unsubscribeComments = this.comments.onChanged(() => {
+            void this.refreshProjection();
+        });
+        this.ready = this.align().catch((error) => {
+            if (this.closed)
+                return;
+            this.status = 'refused';
+            this.problem = describe(error);
+            this.repaint();
+        });
+    }
+    /** Resolves once the daemon coordinate base has been aligned to the file on
+     *  disk. The owner may await it so the first painted frame already carries
+     *  current ranges; painting earlier shows only a preparing line, never a
+     *  comment at a coordinate the daemon has not accepted. */
+    open() {
+        return this.ready;
+    }
+    hasUnsentCompose() {
+        const state = this.state;
+        return state?.mode === 'compose' && state.compose !== null && state.compose.buffer.length > 0;
+    }
+    // ── SurfaceComponent ──────────────────────────────────────────────────────
+    get focused() {
+        return this._focused;
+    }
+    set focused(value) {
+        if (this._focused === value)
+            return;
+        this._focused = value;
+        this.repaint();
+    }
+    setRows(rows) {
+        this.hostRows = Math.max(0, Math.floor(rows));
+    }
+    /** Exactly the rows the host assigned: the document frame, then this
+     *  surface's status row. The document is capped at {@link DOC_MAX_COLS} and
+     *  every line is padded out to the full pane width. */
+    render(width) {
+        const frameWidth = Math.max(0, Math.floor(width));
+        if (this.hostRows <= 0)
+            return [];
+        const cols = Math.min(frameWidth, DOC_MAX_COLS);
+        if (cols !== this.cols || this.hostRows !== this.flowedRows) {
+            this.cols = cols;
+            this.flowedRows = this.hostRows;
+            this.reflow();
+        }
+        const body = this.rows <= 0 || this.cols <= 0 ? [] : this.renderDocument();
+        return [...exactRows(body, this.rows, frameWidth), this.statusRow(frameWidth)];
+    }
+    /** Rows the document frame itself owns. */
+    get rows() {
+        return Math.max(0, this.hostRows - 1);
+    }
+    renderDocument() {
+        if (this.status !== 'ready' || this.state === undefined)
+            return this.renderPlaceholder();
+        const doc = this.document(this.cols, this.state.sourceRevision);
+        const lines = renderReviewFrame(this.state, this.fileLabel, doc, this.cols, this.rows, {
+            lineNumbers: this.kind.doc === 'code',
+            ...(this.footerLine() === undefined ? {} : { notice: this.footerLine() }),
+        });
+        const grouped = this.state.mode === 'list' && this.state.comments.some((comment) => comment.anchorStatus === 'detached')
+            ? this.renderGroupedList(lines)
+            : lines;
+        const rendered = this.state.mode === 'compose' && this.composeAnchorLost
+            ? this.statedComposeAnchor(grouped)
+            : grouped;
+        return this.focused ? this.markCursorLocation(rendered, this.state) : rendered;
+    }
+    /** The surface consumes every chunk: nothing typed into a mounted review may
+     *  reach the transcript beneath it. Esc is the one key this surface answers
+     *  itself — it closes the review unless an unsent comment holds it open. */
+    handleInput(data) {
+        if (this.closed)
+            return;
+        // An armed cancel is answered before every other ladder, and disarms on
+        // any key: only a second `x` cancels, and anything else is the ordinary
+        // keypress it would have been. `escapeConfirmArmed` is left alone.
+        if (this.cancelArmed) {
+            this.cancelArmed = false;
+            const key = matchReviewKey(data);
+            if (key !== null && reviewKeyText(key) === 'x') {
+                this.services.cancel();
+                return;
+            }
+        }
+        // Submitting ends the review the same way, so it asks once too.
+        if (this.submitArmed) {
+            this.submitArmed = false;
+            const key = matchReviewKey(data);
+            if (key !== null && reviewKeyText(key) === 's') {
+                this.submit();
+                return;
+            }
+        }
+        if (matchesKey(data, Key.escape)) {
+            if (this.escapeConfirmArmed) {
+                this.escapeConfirmArmed = false;
+                if (this.consume(data))
+                    return;
+                this.services.requestClose();
+                return;
+            }
+            if (this.hasUnsentCompose()) {
+                this.escapeConfirmArmed = true;
+                this.services.notice('unsent comment — press esc again to discard');
+                this.repaint();
+                return;
+            }
+            // Compose mode owns Esc when its buffer is empty; view mode leaves it
+            // unconsumed so this surface can close.
+            if (this.consume(data))
+                return;
+            this.services.requestClose();
+            return;
+        }
+        if (this.escapeConfirmArmed)
+            this.escapeConfirmArmed = false;
+        this.consume(data);
+    }
+    /** True when the document's own modes took the chunk. */
+    consume(data) {
+        if (this.status !== 'ready')
+            return false;
+        const state = this.state;
+        if (state === undefined)
+            return false;
+        const key = matchReviewKey(data);
+        if (key === null)
+            return false;
+        if (state.mode === 'compose') {
+            this.handleComposeKey(key);
+            this.repaint();
+            return true;
+        }
+        if (state.mode === 'list') {
+            const consumed = this.handleListKey(key);
+            this.repaint();
+            return consumed;
+        }
+        if (state.mode === 'help') {
+            if (key.type === 'help' || (key.type === 'cancel' && key.text === undefined)) {
+                this.state = closeHelp(state);
+                this.repaint();
+                return true;
+            }
+            if (key.type === 'cancel') {
+                this.state = closeHelp(state);
+                this.repaint();
+                return true;
+            }
+            return false;
+        }
+        return this.handleViewKey(key);
+    }
+    /** A mounted review consumes every notch, ready or not: the transcript
+     *  beneath it must never scroll while the document stands over it. */
+    handleWheel(direction, lines) {
+        if (this.closed)
+            return false;
+        const state = this.state;
+        if (this.status !== 'ready' || state === undefined)
+            return true;
+        this.settleScrollAnimation();
+        const current = this.state ?? state;
+        const doc = this.document(this.cols, current.sourceRevision);
+        const delta = (direction === 'up' ? -1 : 1) * Math.max(1, Math.floor(lines));
+        this.state = scrollBy(current, delta, this.bodyHeight(current), doc.lines.length);
+        this.repaint();
+        return true;
+    }
+    /** A half-page move of the view and the selection together, painted at three
+     *  midpoints before its destination so the document slides rather than jumps.
+     *  Whatever is still in flight lands first, keeping every press exact. */
+    startScrollAnimation(rows) {
+        this.settleScrollAnimation();
+        const steps = splitScrollSteps(rows);
+        const first = steps.shift();
+        if (first === undefined)
+            return;
+        this.applyScrollRows(first);
+        this.scrollSteps = steps;
+        this.scheduleScrollStep();
+    }
+    scheduleScrollStep() {
+        if (this.scrollSteps.length === 0)
+            return;
+        this.scrollTimer = setTimeout(() => {
+            this.scrollTimer = undefined;
+            const rows = this.scrollSteps.shift();
+            if (rows === undefined || this.closed)
+                return;
+            this.applyScrollRows(rows);
+            this.repaint();
+            this.scheduleScrollStep();
+        }, SCROLL_STEP_MS);
+    }
+    /** Land every step still to be painted on the state at once. */
+    settleScrollAnimation() {
+        this.stopScrollAnimation();
+        const pending = this.scrollSteps;
+        this.scrollSteps = [];
+        for (const rows of pending)
+            this.applyScrollRows(rows);
+    }
+    stopScrollAnimation() {
+        if (this.scrollTimer === undefined)
+            return;
+        clearTimeout(this.scrollTimer);
+        this.scrollTimer = undefined;
+    }
+    applyScrollRows(rows) {
+        const state = this.state;
+        if (this.status !== 'ready' || state === undefined)
+            return;
+        const doc = this.document(this.cols, state.sourceRevision);
+        this.state = moveViewRows(state, rows, this.bodyHeight(state), doc.lines.length);
+    }
+    /** Repaints are scheduled by the host; this surface never draws directly. */
+    invalidate() {
+        if (!this.closed)
+            this.handle?.invalidate();
+    }
+    /** The mounted handle is this surface's repaint and close channel, and the
+     *  host's close is what releases the document's resources. */
+    setHandle(handle) {
+        if (this.handle !== undefined)
+            return;
+        this.handle = handle;
+        handle.onClose(() => this.close());
+        // A teardown that landed before the mount had no handle to close, so the
+        // fresh one is closed the moment it arrives: a review settled elsewhere
+        // never stands mounted. Its disposition is stated after the close, which
+        // is what disposes the notice the earlier teardown raised.
+        if (this.tornDown) {
+            handle.close();
+            const notice = this.tornDownNotice;
+            this.tornDownNotice = undefined;
+            if (notice !== undefined)
+                this.services.notice(notice.text, notice.opts);
+        }
+    }
+    /** The status row's left segment: this document's state in one line. */
+    summary() {
+        if (this.status === 'refused')
+            return `${this.fileLabel} — unavailable`;
+        if (this.status === 'preparing')
+            return `${this.fileLabel} — preparing`;
+        const open = this.projection.filter((comment) => comment.status === 'open').length;
+        const detached = this.projection.filter((comment) => comment.anchorStatus === 'detached').length;
+        const parts = [this.fileLabel, `${open} open`];
+        if (detached > 0)
+            parts.push(`${detached} detached`);
+        if (this.source.current().status === 'stale')
+            parts.push(`stale (${this.source.current().staleReason ?? 'unreadable'})`);
+        return parts.join(' · ');
+    }
+    /** The status row's right segment: where the companion conversation is. */
+    companionSegment() {
+        const companion = this.paneOrigin === undefined ? 'companion none' : `companion ${this.paneOrigin}`;
+        const forks = this.forkPanes.length;
+        return forks === 0 ? companion : `${companion} · ${forks} fork${forks === 1 ? '' : 's'}`;
+    }
+    statusRow(width) {
+        if (width <= 0)
+            return '';
+        const right = clipLine(this.companionSegment(), width);
+        const left = clipLine(this.summary(), Math.max(0, width - visibleWidth(right) - 1));
+        const gap = Math.max(0, width - visibleWidth(left) - visibleWidth(right));
+        return `${DIM}${left}${' '.repeat(gap)}${right}${RESET}`;
+    }
+    // ── Companion pane ────────────────────────────────────────────────
+    /** Bind the conversation's pane, opening one only when this surface holds no
+     *  live pane already and there is no live companion viewer to adopt. A second
+     *  call therefore keeps the bound pane, whatever state its viewer is in. */
+    openCompanion() {
+        if (this.closed || this.tornDown)
+            return;
+        // Adoption can only see a pane once its viewer has tagged it, so through
+        // the whole revive-and-connect window the recorded pane is the only thing
+        // that keeps this idempotent: without it a retry splits a second pane and
+        // orphans the first. A pane that has since died falls through and reopens.
+        if (this.paneId !== undefined && companionPaneLive(this.paneId))
+            return;
+        const result = openCompanionPane({
+            companionNodeId: this.companionNodeId,
+            cwd: this.companionCwd,
+            callerPane: this.callerPane,
+        });
+        if (result.ok) {
+            this.paneId = result.paneId;
+            this.paneOrigin = result.origin;
+            this.repaint();
+            return;
+        }
+        if (result.reason === 'split_refused') {
+            this.services.notice('tmux refused the companion split — press a to retry');
+            return;
+        }
+        // Without tmux the person still has a way to reach the conversation, and
+        // that instruction has to outlive an auto-clearing notice.
+        this.services.notice(`The review companion needs tmux — run: crtr surface attach to ${this.companionNodeId}`, { sticky: true });
+    }
+    // ── Fork columns ──────────────────────────────────────────────
+    /** The pane a new fork column splits from: the newest live fork, else the
+     *  companion, else this viewer. */
+    rightmostReviewPane() {
+        for (let index = this.forkPanes.length - 1; index >= 0; index -= 1) {
+            const candidate = this.forkPanes[index];
+            if (companionPaneLive(candidate.paneId))
+                return candidate.paneId;
+        }
+        if (this.paneId !== undefined && companionPaneLive(this.paneId))
+            return this.paneId;
+        return this.callerPane;
+    }
+    /** Hand one comment to its own fork of the companion and place its column.
+     *  The comment is already saved by the time this runs, so every failure here
+     *  is stated as a notice rather than failing the comment. */
+    async forkComment(commentId) {
+        if (this.closed || this.tornDown)
+            return;
+        let fork;
+        try {
+            fork = await this.comments.fork(commentId);
+        }
+        catch (error) {
+            this.services.notice(`the comment was saved, but its fork could not start — ${describe(error)}`);
+            return;
+        }
+        if (this.closed || this.tornDown)
+            return;
+        const opened = openForkPane({
+            nodeId: fork.nodeId,
+            cwd: fork.cwd,
+            splitFrom: this.rightmostReviewPane(),
+        });
+        if (opened.ok) {
+            this.forkPanes.push({ paneId: opened.paneId, nodeId: fork.nodeId });
+            this.repaint();
+            return;
+        }
+        // The fork is already working on the comment; only its column is missing.
+        this.services.notice(opened.reason === 'no_room'
+            ? `no room for another fork column — the fork is running: crtr surface attach to ${fork.nodeId}`
+            : `the fork is running, but tmux gave it no column — run: crtr surface attach to ${fork.nodeId}`, { sticky: true });
+    }
+    /** The one path out of a review that has reached a terminal state — approved,
+     *  canceled here, or decided elsewhere. The pane goes with the review, never
+     *  with Esc: closing the document leaves the conversation standing so the
+     *  review can be re-opened over it. Idempotent. The disposition is stated
+     *  only after the close, because the host's restoring close disposes every
+     *  notice raised over the closing surface — a notice raised first would die
+     *  with the surface and the disposition would never paint. */
+    teardown(notice, opts) {
+        if (this.tornDown)
+            return;
+        this.tornDown = true;
+        for (const fork of this.forkPanes)
+            closeCompanionPane(fork.paneId, fork.nodeId);
+        this.forkPanes = [];
+        if (this.paneId !== undefined)
+            closeCompanionPane(this.paneId, this.companionNodeId);
+        this.paneId = undefined;
+        this.paneOrigin = undefined;
+        if (this.handle === undefined)
+            this.tornDownNotice = { text: notice, ...(opts === undefined ? {} : { opts }) };
+        this.handle?.close();
+        this.services.notice(notice, opts);
+    }
+    /** Releases this surface's render cache and stops every projected repaint.
+     *  This surface closes the source it was handed; that close stops its watcher.
+     *  The companion pane deliberately survives: only {@link teardown} closes it. */
+    close() {
+        if (this.closed)
+            return;
+        // Stop the only source of new synchronous callbacks before closing the
+        // surface to every already-in-flight asynchronous continuation.
+        this.source.close();
+        this.closed = true;
+        this.stopScrollAnimation();
+        this.scrollSteps = [];
+        this.unsubscribeComments();
+        this.cache = undefined;
+    }
+    // ── Open-time base alignment ──────────────────────────────────────────────
+    /** Bring the daemon's comment coordinates onto the bytes now on disk, then
+     *  build the first state from what the daemon accepted. The zero-comment case
+     *  still submits its batch: the base digest itself is what advances, and a
+     *  later create against current bytes is rejected until it does. */
+    async align() {
+        // Each pass re-reads the daemon base AND the file, because a write landing
+        // during an await would otherwise leave the base aligned to bytes that are
+        // already gone. A pass whose source moved under it is discarded and retried
+        // against the settled file rather than committed at a hash nobody holds.
+        for (;;) {
+            const base = await this.comments.anchorBase();
+            if (this.closed)
+                return;
+            if (resolve(base.file) !== resolve(this.absFile)) {
+                throw new Error(`review document mismatch — the daemon's canonical file is ${base.file}, not ${this.absFile}`);
+            }
+            const snapshot = this.source.current();
+            if (snapshot.status === 'stale') {
+                throw new Error(`the reviewed file cannot be read (${snapshot.staleReason ?? 'unreadable'})`);
+            }
+            if (base.docHash !== snapshot.sha256) {
+                const listed = await this.comments.list();
+                if (this.closed)
+                    return;
+                if (this.movedSince(snapshot))
+                    continue;
+                const map = buildLineMap(documentLines(base.text), snapshot.lines);
+                await this.comments.remapRanges({
+                    fromDocHash: base.docHash,
+                    toDocHash: snapshot.sha256,
+                    entries: batchEntries(nonDeleted(listed), map),
+                });
+                if (this.closed)
+                    return;
+            }
+            const comments = await this.comments.list();
+            if (this.closed)
+                return;
+            if (this.movedSince(snapshot))
+                continue;
+            this.projection = nonDeleted(comments);
+            this.status = 'ready';
+            this.buildState(snapshot);
+            this.repaint();
+            return;
+        }
+    }
+    movedSince(snapshot) {
+        const current = this.source.current();
+        return current.status === 'live' && current.sha256 !== snapshot.sha256;
+    }
+    /** Re-derive this surface from the daemon's own coordinate base. The only
+     *  honest recovery once a batch is rejected: the local map that produced it
+     *  is no longer a true description of what the daemon holds. */
+    async realign() {
+        if (this.closed)
+            return;
+        try {
+            await this.align();
+        }
+        catch (error) {
+            if (this.closed)
+                return;
+            this.status = 'refused';
+            this.problem = describe(error);
+            this.repaint();
+        }
+    }
+    buildState(snapshot) {
+        const doc = this.document(this.cols, snapshot.revision);
+        this.state = initReviewState(snapshot.lines, deriveAnchorUnits(doc), orderedForDisplay(this.projection), snapshot.revision);
+        this.state = ensureAnchorVisible(this.state, doc, this.bodyHeight(this.state));
+    }
+    // ── Live source ───────────────────────────────────────────────────────────
+    onSourceChanged(next, previous) {
+        if (this.closed || this.status !== 'ready')
+            return;
+        const state = this.state;
+        if (state === undefined)
+            return;
+        if (next.status === 'stale') {
+            this.problem = undefined;
+            this.repaint();
+            return;
+        }
+        if (next.text === previous.text) {
+            this.problem = undefined;
+            this.repaint();
+            return;
+        }
+        // Order is load-bearing: every coordinate is remapped through ONE map built
+        // from the outgoing text, before any unit is re-derived from the new render.
+        const map = buildLineMap(previous.lines, next.lines);
+        const commentRanges = new Map();
+        for (const comment of this.projection) {
+            commentRanges.set(comment.id, comment.anchorStatus === 'detached'
+                ? { range: comment.originalRange ?? { line: comment.line, endLine: comment.endLine }, detached: true }
+                : mapRange(map, { line: comment.line, endLine: comment.endLine }));
+        }
+        // A lost compose anchor stays lost: remapping its old numbers against
+        // whatever now occupies them would silently re-point the buffer at
+        // unrelated text. Only cancelling or opening a new compose clears it.
+        const composeAnchor = state.compose === null || this.composeAnchorLost
+            ? undefined
+            : mapRange(map, state.compose.anchor);
+        const activeRange = mapRange(map, unitRange(state, state.activeUnit));
+        const selectionRange = state.selectionAnchor === null
+            ? undefined
+            : mapRange(map, unitRange(state, state.selectionAnchor));
+        const topLine = mapLine(map, this.topVisibleSourceLine(state), previous.lines.length);
+        const doc = this.document(this.cols, next.revision);
+        const { units, rowUnits } = deriveAnchorUnits(doc);
+        const active = unitRangeForSpan(units, activeRange.range.line, activeRange.range.endLine).hi;
+        const selection = selectionRange === undefined
+            ? null
+            : unitRangeForSpan(units, selectionRange.range.line, selectionRange.range.endLine).lo;
+        const comments = this.projection.map((comment) => {
+            const mapped = commentRanges.get(comment.id);
+            if (mapped === undefined)
+                return comment;
+            return applyMappedRange(comment, mapped);
+        });
+        this.projection = comments;
+        const detached = {};
+        for (const comment of comments) {
+            if (comment.anchorStatus === 'detached') {
+                detached[comment.id] = comment.originalRange ?? { line: comment.line, endLine: comment.endLine };
+            }
+        }
+        this.composeAnchorLost = this.composeAnchorLost || composeAnchor?.detached === true;
+        const compose = state.compose === null || composeAnchor === undefined
+            ? state.compose
+            : { ...state.compose, anchor: composeAnchor.range };
+        let nextState = {
+            ...state,
+            sourceLines: next.lines,
+            units,
+            rowUnits,
+            comments: orderedForDisplay(comments),
+            sourceRevision: next.revision,
+            detached,
+            activeUnit: active,
+            selectionAnchor: selection,
+            compose,
+            listIndex: Math.max(0, Math.min(state.listIndex, comments.length - 1)),
+            scroll: units[unitIndexForLine(units, topLine)]?.firstRow ?? 0,
+        };
+        nextState = ensureAnchorVisible(nextState, doc, this.bodyHeight(nextState));
+        this.state = nextState;
+        this.problem = this.composeAnchorLost ? 'the commented lines were removed — this comment has no anchor' : undefined;
+        this.repaint();
+        this.remapChain = this.remapChain.then(() => this.submitBatch(previous.sha256, next.sha256, commentRanges), () => this.submitBatch(previous.sha256, next.sha256, commentRanges));
+    }
+    /** One transaction covering every non-deleted comment. A rejection is stated
+     *  in this surface's own footer and the projection is re-read from the
+     *  authority, which is the only thing that can still be true afterwards. */
+    async submitBatch(fromDocHash, toDocHash, ranges) {
+        if (this.closed)
+            return;
+        const entries = [...ranges].map(([id, mapped]) => mapped.detached
+            ? { id, detached: true }
+            : { id, anchor: mapped.range });
+        try {
+            await this.comments.remapRanges({ fromDocHash, toDocHash, entries });
+            if (this.closed)
+                return;
+            await this.refreshProjection();
+        }
+        catch (error) {
+            if (this.closed)
+                return;
+            this.problem = `comment ranges were rejected — ${describe(error)}`;
+            this.repaint();
+            await this.realign();
+        }
+    }
+    // ── Daemon-projected comments ─────────────────────────────────────────────
+    async refreshProjection() {
+        if (this.closed || this.status === 'refused')
+            return;
+        try {
+            const comments = nonDeleted(await this.comments.list());
+            if (this.closed)
+                return;
+            this.projection = comments;
+            const state = this.state;
+            if (state !== undefined) {
+                const ordered = orderedForDisplay(comments);
+                this.state = {
+                    ...state,
+                    comments: ordered,
+                    detached: Object.fromEntries(ordered.flatMap((comment) => comment.anchorStatus === 'detached'
+                        ? [[comment.id, comment.originalRange ?? { line: comment.line, endLine: comment.endLine }]]
+                        : [])),
+                    listIndex: Math.max(0, Math.min(state.listIndex, ordered.length - 1)),
+                };
+            }
+            this.repaint();
+        }
+        catch (error) {
+            if (this.closed)
+                return;
+            this.problem = `comments could not be read — ${describe(error)}`;
+            this.repaint();
+        }
+    }
+    async mutate(operation) {
+        if (this.closed)
+            return;
+        try {
+            await operation();
+            if (this.closed)
+                return;
+            this.problem = undefined;
+        }
+        catch (error) {
+            if (this.closed)
+                return;
+            this.problem = error instanceof ReviewDocumentError
+                ? `${error.code.replace(/_/g, ' ')} — the document moved under this comment`
+                : describe(error);
+            this.repaint();
+        }
+        await this.refreshProjection();
+    }
+    // ── Keys ──────────────────────────────────────────────────────────────────
+    handleComposeKey(key) {
+        const state = this.state;
+        const compose = state?.compose;
+        if (state === undefined || compose === null || compose === undefined)
+            return;
+        if (key.type === 'cancel' && key.text === undefined) {
+            this.composeAnchorLost = false;
+            this.state = closeCompose(state);
+            return;
+        }
+        if (key.type === 'confirm' || key.type === 'confirmFork') {
+            if (this.composeAnchorLost) {
+                this.problem = 'comment not saved — its anchored lines were removed';
+                return;
+            }
+            const committed = commitCompose(state);
+            this.composeAnchorLost = false;
+            this.state = committed.state;
+            const commit = committed.commit;
+            if (commit === null)
+                return;
+            const forking = key.type === 'confirmFork';
+            const docHash = this.source.current().sha256;
+            if (commit.editingId === null) {
+                void this.mutate(async () => {
+                    const commentId = await this.comments.create({
+                        line: commit.anchor.line,
+                        endLine: commit.anchor.endLine,
+                        text: commit.text,
+                        docHash,
+                    });
+                    if (forking)
+                        await this.forkComment(commentId);
+                });
+                return;
+            }
+            const editing = this.projection.find((comment) => comment.id === commit.editingId);
+            if (editing === undefined) {
+                this.problem = 'that comment no longer exists';
+                return;
+            }
+            void this.mutate(async () => {
+                await this.comments.edit({
+                    id: editing.id,
+                    text: commit.text,
+                    ifRevision: editing.revision,
+                });
+                if (forking)
+                    await this.forkComment(editing.id);
+            });
+            return;
+        }
+        if (key.type === 'composeNewline') {
+            this.state = { ...state, compose: { ...compose, ...textInsert(compose.buffer, compose.cursor, '\n') } };
+            return;
+        }
+        if (key.type === 'composeWordBackspace') {
+            this.state = { ...state, compose: { ...compose, ...textWordBackspace(compose.buffer, compose.cursor) } };
+            return;
+        }
+        if (key.type === 'composeBackspace') {
+            this.state = { ...state, compose: { ...compose, ...textBackspace(compose.buffer, compose.cursor) } };
+            return;
+        }
+        if (key.type === 'composeDelete') {
+            this.state = { ...state, compose: { ...compose, ...textDelete(compose.buffer, compose.cursor) } };
+            return;
+        }
+        if (key.type === 'composeMove') {
+            const cursor = key.direction === 'wordLeft'
+                ? textWordLeft(compose.buffer, compose.cursor)
+                : textWordRight(compose.buffer, compose.cursor);
+            this.state = { ...state, compose: { ...compose, cursor } };
+            return;
+        }
+        if (key.type === 'arrow' && key.direction === 'left') {
+            this.state = { ...state, compose: { ...compose, cursor: Math.max(0, compose.cursor - 1) } };
+            return;
+        }
+        if (key.type === 'arrow' && key.direction === 'right') {
+            this.state = {
+                ...state,
+                compose: { ...compose, cursor: Math.min([...compose.buffer].length, compose.cursor + 1) },
+            };
+            return;
+        }
+        if (key.type === 'composeHome') {
+            this.state = { ...state, compose: { ...compose, cursor: textHome(compose.buffer, compose.cursor) } };
+            return;
+        }
+        if (key.type === 'composeEnd') {
+            this.state = { ...state, compose: { ...compose, cursor: textEnd(compose.buffer, compose.cursor) } };
+            return;
+        }
+        if (key.type === 'arrow' && (key.direction === 'up' || key.direction === 'down')) {
+            const delta = key.direction === 'up' ? -1 : 1;
+            this.state = {
+                ...state,
+                compose: {
+                    ...compose,
+                    cursor: textVerticalWrapped(compose.buffer, compose.cursor, delta, this.composeWidth()),
+                },
+            };
+            return;
+        }
+        const text = reviewKeyText(key);
+        if (text === undefined)
+            return;
+        if (key.type === 'paste') {
+            const clean = cleanPastedText(text);
+            if (clean.length === 0)
+                return;
+            this.state = { ...state, compose: { ...compose, ...textInsert(compose.buffer, compose.cursor, clean) } };
+            return;
+        }
+        this.state = { ...state, compose: { ...compose, ...textInsert(compose.buffer, compose.cursor, text) } };
+    }
+    /** The document's single-key commands, shared by view mode. Returns false
+     *  for a key that is not one of them. Space was once a prefix for these; it
+     *  is now ignored, so a remembered `space c` still lands on `c`. */
+    handleCommandKey(key) {
+        const state = this.state;
+        if (state === undefined)
+            return false;
+        const input = key.type === 'confirm' ? 'c' : reviewKeyText(key);
+        if (input === 'c') {
+            const opened = openComposeNew(state);
+            this.composeAnchorLost = false;
+            this.state = ensureAnchorVisible(opened, this.document(this.cols, opened.sourceRevision), this.bodyHeight(opened));
+        }
+        else if (input === 'C') {
+            this.state = openList(state);
+        }
+        else if (input === 'U') {
+            const undone = undoLast(state);
+            if (undone.id !== null) {
+                const id = undone.id;
+                void this.mutate(() => this.comments.remove(id));
+            }
+        }
+        else if (input === 'e') {
+            this.editInEditor();
+        }
+        else if (input === 's') {
+            this.armSubmit();
+        }
+        else if (input === 'a') {
+            this.openCompanion();
+        }
+        else if (input === 'x') {
+            this.armCancel();
+        }
+        else if (input === ' ') {
+            // Ignored: see above.
+        }
+        else {
+            return false;
+        }
+        this.repaint();
+        return true;
+    }
+    submit() {
+        const snapshot = this.source.current();
+        if (snapshot.status === 'stale') {
+            this.problem = `approval refused while the source is ${snapshot.staleReason ?? 'unreadable'}`;
+            this.repaint();
+            return;
+        }
+        this.services.submit();
+    }
+    /** Submitting ends the review, so it asks once. The armed state is answered
+     *  in {@link handleInput}, ahead of every mode's ladder. */
+    armSubmit() {
+        this.submitArmed = true;
+        this.services.notice('submit and approve this review? press s again to confirm');
+    }
+    /** Cancelling discards the whole review, so it asks once. The armed state is
+     *  answered in {@link handleInput}, ahead of every mode's ladder. */
+    armCancel() {
+        this.cancelArmed = true;
+        this.services.notice('cancel this review? press x again to confirm');
+    }
+    handleListKey(key) {
+        const state = this.state;
+        if (state === undefined)
+            return false;
+        if (key.type === 'cancel') {
+            this.state = closeList(state);
+            return true;
+        }
+        if ((key.type === 'moveUnit' && key.text === 'j') || (key.type === 'arrow' && key.direction === 'down')) {
+            this.state = moveListIndex(state, 1);
+            return true;
+        }
+        if ((key.type === 'moveUnit' && key.text === 'k') || (key.type === 'arrow' && key.direction === 'up')) {
+            this.state = moveListIndex(state, -1);
+            return true;
+        }
+        if (key.type === 'listEdit' || key.type === 'confirm') {
+            if (state.comments.length > 0) {
+                const opened = openComposeEdit(state, state.listIndex);
+                this.composeAnchorLost = false;
+                this.state = ensureAnchorVisible(opened, this.document(this.cols, opened.sourceRevision), this.bodyHeight(opened));
+            }
+            return true;
+        }
+        if (key.type === 'scrollPage' && key.text === 'd' && state.comments.length > 0) {
+            const deleted = deleteAtListIndex(state);
+            if (deleted.id !== null) {
+                const id = deleted.id;
+                void this.mutate(() => this.comments.remove(id));
+            }
+            return true;
+        }
+        if (key.type === 'printable' && key.text === 'c') {
+            this.state = closeList(state);
+            return this.handleCommandKey(key);
+        }
+        return false;
+    }
+    handleViewKey(key) {
+        const state = this.state;
+        if (state === undefined)
+            return false;
+        const doc = this.document(this.cols, state.sourceRevision);
+        const bodyHeight = this.bodyHeight(state);
+        if (key.type === 'moveUnit' || (key.type === 'arrow' && (key.direction === 'up' || key.direction === 'down'))) {
+            const delta = key.type === 'moveUnit' ? key.delta : key.direction === 'down' ? 1 : -1;
+            this.state = ensureAnchorVisible(moveActiveUnit(state, delta, false), doc, bodyHeight);
+        }
+        else if (key.type === 'extendUnit') {
+            this.state = ensureAnchorVisible(moveActiveUnit(state, key.delta, true), doc, bodyHeight);
+        }
+        else if (key.type === 'scrollPage') {
+            this.startScrollAnimation(key.delta * halfPageRows(bodyHeight));
+        }
+        else if ((key.type === 'pan' || (key.type === 'arrow' && (key.direction === 'left' || key.direction === 'right')))
+            && maxHScroll(state, doc, this.cols, this.rows, this.gutterWidth()) > 0) {
+            const delta = key.type === 'pan' ? key.delta : key.direction === 'right' ? 1 : -1;
+            this.state = panBy(state, delta * PAN_STEP, doc, this.cols, this.rows, this.gutterWidth());
+        }
+        else if (key.type === 'help') {
+            this.state = openHelp(state);
+        }
+        else if (key.type === 'cancel' && key.text === undefined) {
+            // Esc in view mode belongs to this surface's own ladder, which decides
+            // whether an unsent comment should hold the review open.
+            return false;
+        }
+        else if (key.type === 'cancel') {
+            return false;
+        }
+        else {
+            return this.handleCommandKey(key);
+        }
+        this.repaint();
+        return true;
+    }
+    /** The reviewed file is the deliverable: the person's own editor writes it,
+     *  this surface never does. The source is re-read the moment the editor exits
+     *  rather than waiting for the watcher's coalescing window. */
+    editInEditor() {
+        const state = this.state;
+        if (state === undefined)
+            return;
+        const line = state.units[state.activeUnit]?.start ?? 1;
+        const resume = this.services.suspendForChild();
+        try {
+            const outcome = openReviewedFileInEditor(this.absFile, line);
+            if (outcome.error !== undefined)
+                this.problem = `editor failed — ${outcome.error}`;
+        }
+        finally {
+            resume();
+        }
+        this.source.refreshNow();
+    }
+    // ── Geometry and rendering ────────────────────────────────────────────────
+    /** The host owns cursor focus; a focused surface contributes exactly one
+     * whole marker at the same visual location the document already calls
+     * active. There is deliberately no synthetic fallback row: a marker is
+     * only valid when it belongs to a rendered anchor or the compose/list cursor. */
+    markCursorLocation(lines, state) {
+        // The compose caret is reverse video painted over the character it sits on,
+        // so its start sequence is the cell the hardware cursor belongs in.
+        if (state.mode === 'compose')
+            return markAtToken(lines, REVERSE);
+        if (state.mode === 'list') {
+            const markedListCursor = markAtToken(lines, `${CYAN}▸${RESET}`);
+            if (markedListCursor !== lines)
+                return markedListCursor;
+        }
+        const row = this.activeAnchorFrameRow(state);
+        return row === undefined ? lines : markAtToken(lines, `${CYAN}▌${RESET}`, row);
+    }
+    /** The frame paints source rows after its three-line header. Scroll indicators
+     * replace their source rows, so they are never cursor targets. */
+    activeAnchorFrameRow(state) {
+        const bodyHeight = Math.max(1, this.rows - reservedRows(state, this.cols));
+        const total = state.rowUnits.length;
+        const scroll = Math.max(0, Math.min(state.scroll, Math.max(0, total - bodyHeight)));
+        for (let bodyRow = 0; bodyRow < bodyHeight; bodyRow++) {
+            const sourceRow = scroll + bodyRow;
+            const replacedByIndicator = (bodyRow === 0 && scroll > 0)
+                || (bodyRow === bodyHeight - 1 && sourceRow < total - 1);
+            if (!replacedByIndicator && state.rowUnits[sourceRow] === state.activeUnit)
+                return 3 + bodyRow;
+        }
+        return undefined;
+    }
+    reflow() {
+        const state = this.state;
+        if (state === undefined || this.cols <= 0)
+            return;
+        const previousActive = state.units[state.activeUnit];
+        const previousSelection = state.selectionAnchor === null ? undefined : state.units[state.selectionAnchor];
+        const doc = this.document(this.cols, state.sourceRevision);
+        const { units, rowUnits } = deriveAnchorUnits(doc);
+        const reflowed = {
+            ...state,
+            units,
+            rowUnits,
+            activeUnit: previousActive === undefined ? 0 : remapUnitIndex(units, previousActive),
+            selectionAnchor: previousSelection === undefined ? null : remapUnitIndex(units, previousSelection),
+        };
+        this.state = ensureAnchorVisible(reflowed, doc, this.bodyHeight(reflowed));
+    }
+    document(width, sourceRevision) {
+        const cached = this.cache;
+        if (cached !== undefined && cached.width === width && cached.sourceRevision === sourceRevision)
+            return cached.doc;
+        const text = this.source.current().text;
+        const doc = this.kind.doc === 'code'
+            ? codeRenderedDoc(text, this.kind.language ?? 'text', renderWidthForCols(width))
+            : renderReviewDoc(text, width);
+        this.cache = { width, sourceRevision, doc };
+        return doc;
+    }
+    bodyHeight(state) {
+        const groupedListRows = state.mode === 'list' && state.comments.some((comment) => comment.anchorStatus === 'detached')
+            ? 1 + (state.comments.some((comment) => comment.anchorStatus !== 'detached') ? 1 : 0)
+            : 0;
+        return Math.max(1, this.rows - reservedRows(state, this.cols) - groupedListRows);
+    }
+    composeWidth() {
+        return Math.max(10, Math.min(Math.max(20, this.cols - 4), 120) - 2);
+    }
+    gutterWidth() {
+        return this.kind.doc === 'code' ? String(this.source.current().lines.length).length : 0;
+    }
+    /** The document frame's own footer line: its error, then its stale verdict. */
+    footerLine() {
+        if (this.problem !== undefined)
+            return this.problem;
+        const snapshot = this.source.current();
+        if (snapshot.status === 'stale') {
+            return `source ${snapshot.staleReason ?? 'unreadable'} — showing the last good read; approval is refused`;
+        }
+        return undefined;
+    }
+    renderPlaceholder() {
+        const message = this.status === 'refused'
+            ? `Review unavailable — ${this.problem ?? 'the document could not be prepared'}`
+            : `Preparing ${this.fileLabel}…`;
+        const lines = ['', `  ${message}`];
+        while (lines.length < this.rows)
+            lines.push('');
+        return lines.slice(0, this.rows).map((line) => clipLine(line, this.cols));
+    }
+    /** `frame.ts` renders the ordinary list. Detached anchors need stronger
+     *  treatment: their own leading group plus the original range and snippet,
+     *  because no document marker can lead a person back to them. */
+    renderGroupedList(base) {
+        const state = this.state;
+        const maxW = Math.min(Math.max(20, this.cols - 4), 120);
+        const detached = state.comments.filter((comment) => comment.anchorStatus === 'detached');
+        const anchored = state.comments.filter((comment) => comment.anchorStatus !== 'detached');
+        const panel = [`  ${YELLOW}Detached${RESET}`];
+        for (const comment of detached)
+            panel.push(this.commentListRow(comment, state.comments.indexOf(comment), maxW, true));
+        if (anchored.length > 0) {
+            panel.push(`  ${DIM}Comments${RESET}`);
+            for (const comment of anchored)
+                panel.push(this.commentListRow(comment, state.comments.indexOf(comment), maxW, false));
+        }
+        panel.push('');
+        panel.push(listHintBar(maxW));
+        const available = Math.max(0, this.rows - 3);
+        const visible = panel.slice(0, available);
+        const start = Math.max(3, this.rows - visible.length);
+        const out = [...base];
+        const centered = centerHorizontal(visible, this.cols, Math.min(this.cols, maxW + 2));
+        for (let i = 0; i < centered.length; i++)
+            out[start + i] = clipLine(centered[i] ?? '', this.cols);
+        return out.slice(0, this.rows);
+    }
+    /** The compose header states a lost anchor where the person is already
+     *  looking, leaving the footer's compose keys intact. */
+    statedComposeAnchor(lines) {
+        const state = this.state;
+        if (state?.compose == null)
+            return lines;
+        const maxW = Math.min(Math.max(20, this.cols - 4), 120);
+        const bufferRows = renderInputBuffer(state.compose.buffer, state.compose.cursor, Math.max(10, maxW - 2)).length;
+        const header = this.rows - (bufferRows + 3);
+        if (header < 0 || header >= lines.length)
+            return lines;
+        const out = [...lines];
+        out[header] = clipLine(centerHorizontal([`  ${YELLOW}Comment anchor removed by an edit — esc, then re-anchor:${RESET}`], this.cols, Math.min(this.cols, maxW + 2))[0] ?? '', this.cols);
+        return out;
+    }
+    commentListRow(comment, index, maxW, detached) {
+        const range = detached
+            ? comment.originalRange ?? { line: comment.line, endLine: comment.endLine }
+            : { line: comment.line, endLine: comment.endLine };
+        const loc = range.line === range.endLine ? `L${range.line}` : `L${range.line}-${range.endLine}`;
+        const cursor = index === this.state.listIndex ? `${CYAN}▸${RESET}` : ' ';
+        const snippet = detached ? `“${sanitize(comment.lineText).replace(/\s+/g, ' ').trim()}” · ` : '';
+        const text = `${snippet}${sanitize(comment.comment).replace(/\s+/g, ' ').trim()}`;
+        return `  ${cursor} ${DIM}[${loc}]${RESET} ${truncate(text, Math.max(10, maxW - 14))}`;
+    }
+    topVisibleSourceLine(state) {
+        const unit = state.rowUnits[state.scroll];
+        if (unit !== null && unit !== undefined)
+            return state.units[unit]?.start ?? 1;
+        for (let row = state.scroll; row < state.rowUnits.length; row++) {
+            const candidate = state.rowUnits[row];
+            if (candidate !== null && candidate !== undefined)
+                return state.units[candidate]?.start ?? 1;
+        }
+        return 1;
+    }
+    repaint() {
+        this.invalidate();
+    }
+}
+// ── Pure helpers ─────────────────────────────────────────────────────────────
+/** Split a row move into increments summing exactly to it — one per painted
+ *  step, and one per row when the move is shorter than the step count (a jump
+ *  of a single row is painted once, not animated). */
+function splitScrollSteps(rows) {
+    const magnitude = Math.abs(rows);
+    if (magnitude === 0)
+        return [];
+    const direction = Math.sign(rows);
+    const count = Math.min(SCROLL_STEPS, magnitude);
+    const steps = [];
+    let painted = 0;
+    for (let i = 1; i <= count; i++) {
+        const reached = Math.round((magnitude * i) / count);
+        steps.push((reached - painted) * direction);
+        painted = reached;
+    }
+    return steps;
+}
+/** Exactly `rows` lines, each exactly `width` cells. */
+function exactRows(lines, rows, width) {
+    const frame = lines.slice(0, rows).map((line) => padTo(line, width));
+    while (frame.length < rows)
+        frame.push(' '.repeat(width));
+    return frame;
+}
+/** `string-width` correctly ignores ANSI but cannot know pi-tui's private
+ *  cursor marker is zero-width, so the marker is measured out of the line. */
+function padTo(line, width) {
+    const bare = line.split(CURSOR_MARKER).join('');
+    const cells = visibleWidth(bare);
+    if (cells > width) {
+        const clipped = clipLine(bare, width);
+        return clipped + ' '.repeat(Math.max(0, width - visibleWidth(clipped)));
+    }
+    return line + ' '.repeat(width - cells);
+}
+function labelFor(cwd, absFile) {
+    const rel = relative(cwd, absFile);
+    return rel === '' || rel.startsWith('..') ? absFile : rel;
+}
+function nonDeleted(comments) {
+    return comments.filter((comment) => comment.status !== 'deleted');
+}
+/** Detached comments lead the list: they no longer point anywhere in the
+ *  document, so they are only reachable there. */
+function orderedForDisplay(comments) {
+    const detached = comments.filter((comment) => comment.anchorStatus === 'detached');
+    const anchored = comments.filter((comment) => comment.anchorStatus !== 'detached');
+    return [...detached, ...anchored];
+}
+function unitRange(state, index) {
+    const unit = state.units[index];
+    if (unit === undefined)
+        return { line: 1, endLine: 1 };
+    return { line: unit.start, endLine: unit.end };
+}
+/** `remap.ts` speaks 0-based lines with an exclusive end; comment anchors are
+ *  1-based and inclusive. This is the only place the two meet. */
+function mapRange(map, range) {
+    const result = remapRange(map, { line: range.line - 1, endLine: range.endLine });
+    if (result.kind === 'detached')
+        return { range, detached: true };
+    return { range: { line: result.line + 1, endLine: Math.max(result.line + 1, result.endLine) }, detached: false };
+}
+function mapLine(map, line, oldLineCount) {
+    const old = line - 1;
+    const exact = map.get(old);
+    if (exact !== undefined)
+        return exact + 1;
+    // A deleted top row has no range to remap. Preserve locality by choosing the
+    // nearest surviving source row, preferring the following row on a tie.
+    for (let distance = 1; distance < oldLineCount; distance++) {
+        const after = map.get(old + distance);
+        if (after !== undefined)
+            return after + 1;
+        const before = map.get(old - distance);
+        if (before !== undefined)
+            return before + 1;
+    }
+    return 1;
+}
+function applyMappedRange(comment, mapped) {
+    if (mapped.detached) {
+        return {
+            ...comment,
+            anchorStatus: 'detached',
+            originalRange: comment.originalRange ?? { line: comment.line, endLine: comment.endLine },
+        };
+    }
+    if (comment.anchorStatus === 'detached')
+        return comment;
+    const shifted = mapped.range.line !== comment.line || mapped.range.endLine !== comment.endLine;
+    return {
+        ...comment,
+        line: mapped.range.line,
+        endLine: mapped.range.endLine,
+        anchorStatus: shifted ? 'shifted' : comment.anchorStatus,
+    };
+}
+function batchEntries(comments, map) {
+    return comments.map((comment) => {
+        if (comment.anchorStatus === 'detached')
+            return { id: comment.id, detached: true };
+        const mapped = mapRange(map, { line: comment.line, endLine: comment.endLine });
+        return mapped.detached
+            ? { id: comment.id, detached: true }
+            : { id: comment.id, anchor: mapped.range };
+    });
+}
+function markAtToken(lines, token, row) {
+    const index = row ?? lines.findIndex((line) => line.includes(token));
+    const line = lines[index];
+    if (line === undefined)
+        return lines;
+    const at = line.indexOf(token);
+    if (at === -1)
+        return lines;
+    const marked = [...lines];
+    marked[index] = `${line.slice(0, at)}${CURSOR_MARKER}${line.slice(at)}`;
+    return marked;
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}