@north-light/crouter 0.3.170 → 0.3.172

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

@@ -0,0 +1,902 @@
+import { relative, resolve } from 'node:path';
+import { CURSOR_MARKER } 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, YELLOW } from '../tui/ansi.js';
+import { ReviewDocumentError } from './comments-client.js';
+import { PAN_STEP, docSurface, maxHScroll, panBy, renderReviewDoc, renderReviewFrame, 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, initReviewState, moveActiveUnit, moveListIndex, openComposeEdit, openComposeNew, openHelp, openList, scrollBy, textBackspace, textDelete, textEnd, textHome, textInsert, textVerticalWrapped, textWordBackspace, textWordLeft, textWordRight, deleteAtListIndex, undoLast, } from './state.js';
+/** The reviewed document as a composed region: 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. */
+export class DocumentRegion {
+    absFile;
+    fileLabel;
+    kind;
+    source;
+    comments;
+    services;
+    unsubscribeComments;
+    ready;
+    cols = 0;
+    rows = 0;
+    focused = false;
+    closed = false;
+    spaceArmed = false;
+    state;
+    cache;
+    /** Every non-deleted comment the daemon currently projects, newest last. */
+    projection = [];
+    status = 'preparing';
+    /** Region-local error/summary state — never a host notice (D1). */
+    problem;
+    composeAnchorLost = false;
+    dirty;
+    /** Serializes base-hash transitions so B→C cannot overtake A→B. */
+    remapChain = Promise.resolve();
+    constructor(opts) {
+        this.absFile = opts.absFile;
+        this.fileLabel = labelFor(opts.cwd, opts.absFile);
+        this.kind = docSurface(opts.absFile);
+        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;
+    }
+    // ── SurfaceRegion ─────────────────────────────────────────────────────────
+    setViewport(cols, rows) {
+        const nextCols = Math.max(0, Math.floor(cols));
+        const nextRows = Math.max(0, Math.floor(rows));
+        if (nextCols === this.cols && nextRows === this.rows)
+            return;
+        this.cols = nextCols;
+        this.rows = nextRows;
+        this.reflow();
+    }
+    render() {
+        if (this.rows <= 0 || this.cols <= 0)
+            return [];
+        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;
+    }
+    handleInput(data) {
+        if (this.closed || 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 (this.spaceArmed) {
+            this.handleLeaderKey(key);
+            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);
+    }
+    handleWheel(direction, lines) {
+        const state = this.state;
+        if (this.closed || this.status !== 'ready' || state === undefined)
+            return false;
+        const doc = this.document(this.cols, state.sourceRevision);
+        const delta = (direction === 'up' ? -1 : 1) * Math.max(1, Math.floor(lines));
+        this.state = scrollBy(state, delta, this.bodyHeight(state), doc.lines.length);
+        this.repaint();
+        return true;
+    }
+    setFocused(value) {
+        if (this.focused === value)
+            return;
+        this.focused = value;
+        this.repaint();
+    }
+    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(' · ');
+    }
+    onDirty(fn) {
+        this.dirty = fn;
+    }
+    /** Releases this region's render cache and stops every projected repaint.
+     *  This region closes the source it was handed; that close stops its watcher. */
+    close() {
+        if (this.closed)
+            return;
+        // Stop the only source of new synchronous callbacks before closing the
+        // region to every already-in-flight asynchronous continuation.
+        this.source.close();
+        this.closed = true;
+        this.unsubscribeComments();
+        this.cache = undefined;
+        this.dirty = 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 region 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 region'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') {
+            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 docHash = this.source.current().sha256;
+            if (commit.editingId === null) {
+                void this.mutate(() => this.comments.create({
+                    line: commit.anchor.line,
+                    endLine: commit.anchor.endLine,
+                    text: commit.text,
+                    docHash,
+                }));
+                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(() => this.comments.edit({
+                id: editing.id,
+                text: commit.text,
+                ifRevision: editing.revision,
+            }));
+            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) } };
+    }
+    handleLeaderKey(key) {
+        const state = this.state;
+        this.spaceArmed = false;
+        if (state === undefined)
+            return;
+        const input = 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 === 'l') {
+            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') {
+            const snapshot = this.source.current();
+            if (snapshot.status === 'stale') {
+                this.problem = `approval refused while the source is ${snapshot.staleReason ?? 'unreadable'}`;
+            }
+            else {
+                this.services.submit();
+            }
+        }
+        this.repaint();
+    }
+    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 === 'leader') {
+            this.spaceArmed = true;
+            return true;
+        }
+        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 === 'leader') {
+            this.spaceArmed = true;
+            return true;
+        }
+        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.state = scrollBy(state, key.delta * bodyHeight, bodyHeight, doc.lines.length);
+        }
+        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 from the document belongs to the composed owner, which decides
+            // whether an unsent comment should hold the surface open.
+            return false;
+        }
+        else if (key.type === 'cancel') {
+            return false;
+        }
+        else {
+            return false;
+        }
+        this.repaint();
+        return true;
+    }
+    /** The reviewed file is the deliverable: the person's own editor writes it,
+     *  this region 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 composition owns cursor focus; its focused document region 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) {
+        if (state.mode === 'compose')
+            return markAtToken(lines, `${REVERSE} ${RESET}`);
+        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 region'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(`  ${DIM}j/k${RESET} move  ${DIM}enter/e${RESET} edit  ${DIM}d${RESET} delete  ${DIM}q/esc${RESET} close`);
+        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() {
+        if (this.closed)
+            return;
+        this.dirty?.();
+    }
+}
+// ── Pure helpers ─────────────────────────────────────────────────────────────
+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);
+}