dsh-diff-approval 0.36.1 → 0.37.0

package/lib/index.js

@@ -2503,7 +2503,7 @@ var CommentAsker = class {
 		const comment = this.comments.get(commentId);
 		if (comment === void 0 || !inScope(comment.sessionId)) return { outcome: "missing" };
 		const controller = this.ctx.get("sessionController");
-		if (typeof controller?.prompt !== "function") {
+		if (typeof controller?.prompt !== "function" && typeof controller?.resolveAgent !== "function") {
 			this.ctx.logger.warn("diff-approval: no sessionController.prompt in this host, so a comment cannot be asked");
 			return { outcome: "no-agent" };
 		}
@@ -2514,6 +2514,22 @@ var CommentAsker = class {
 		this.watch(sessionId);
 		const requestId = randomUUID();
 		this.comments.recordAsk(sessionId, commentId, requestId, void 0, text);
+		const source = {
+			kind: "diff-comment",
+			rpcId: requestId,
+			commentId,
+			path: comment.path,
+			startLine: comment.anchor.startLine,
+			endLine: comment.anchor.endLine
+		};
+		if (await this.deliverAsCard(sessionId, prompt, source)) return {
+			outcome: "asked",
+			requestId
+		};
+		if (typeof controller.prompt !== "function") return {
+			outcome: "no-agent",
+			requestId
+		};
 		try {
 			await controller.prompt({
 				requestId,
@@ -2539,6 +2555,53 @@ var CommentAsker = class {
 		}
 	}
 	/**
+	* Deliver one comment through the host's WAKE-UP seam, so the shell draws it as a trigger card.
+	*
+	* The seam is the one the host's own reminders use: resolve the live agent, publish a user message on
+	* it, then flush. The message's `source` is what the shell's closed switch turns into a card, and this
+	* plugin's client retitles its own source on the rendered DOM (an unknown kind falls back to a generic
+	* title). A host without the seam — or any failure asking for it — answers false, and the caller falls
+	* back to an ordinary prompt rather than losing the question.
+	*
+	* @param sessionId - the session whose live agent wakes.
+	* @param prompt - the prompt text to deliver verbatim.
+	* @param source - the comment's source marker, carried onto the message.
+	* @returns whether the message was published on the live agent.
+	*/
+	async deliverAsCard(sessionId, prompt, source) {
+		const controller = this.ctx.get("sessionController");
+		if (typeof controller?.resolveAgent !== "function") return false;
+		let resolved;
+		try {
+			resolved = await controller.resolveAgent(sessionId);
+		} catch {
+			return false;
+		}
+		if (resolved === void 0 || resolved.error !== void 0 || resolved.agent === void 0) return false;
+		const agent = resolved.agent;
+		if (typeof agent.followup !== "function") return false;
+		try {
+			agent.followup({
+				id: randomUUID(),
+				role: "user",
+				content: [{
+					type: "text",
+					text: prompt
+				}],
+				source
+			});
+		} catch {
+			return false;
+		}
+		const sessions = this.ctx.get("sessions");
+		if (typeof sessions?.flush === "function" && agent.session !== void 0) try {
+			if (!await sessions.flush(agent.session)) this.ctx.logger.warn("diff-approval: the host did not persist the comment delivery");
+		} catch (error) {
+			this.ctx.logger.warn(`diff-approval: flushing the comment delivery failed: ${rejectionText(error)}`);
+		}
+		return true;
+	}
+	/**
 	* One scope's questions, grouped by THE TRANSCRIPT each was submitted into.
 	*
 	* A lineage's threads may hold questions asked from several seats, and an answer lives in the
@@ -6548,8 +6611,17 @@ function apply(ctx, config) {
 					ok: true,
 					value: { outcome: "missing" }
 				};
-				const accepted = contentRangeOf(entry.newText, blockTarget.block.newStart, blockTarget.block.newEnd);
-				const updatedOld = replaceContentLines(entry.oldText, blockTarget.block.oldStart, blockTarget.block.oldEnd, accepted);
+				const chars = charSpansOf(blockTarget.block);
+				let updatedOld;
+				if (chars === void 0 || !charSpansStayOnOneLine(entry.oldText, entry.newText, chars)) {
+					const accepted = contentRangeOf(entry.newText, blockTarget.block.newStart, blockTarget.block.newEnd);
+					updatedOld = replaceContentLines(entry.oldText, blockTarget.block.oldStart, blockTarget.block.oldEnd, accepted);
+				} else {
+					const accepted = entry.newText.slice(chars.new.start, chars.new.end);
+					const spliced = spliceChars(entry.oldText, chars.old.start, chars.old.end, accepted);
+					if (spliced === void 0) return rpcError("block character span does not fit the file");
+					updatedOld = spliced;
+				}
 				store.update(blockTarget.id, { oldText: updatedOld });
 				const afterEntry = {
 					...entry,
@@ -6602,9 +6674,18 @@ function apply(ctx, config) {
 					ok: true,
 					value: { outcome: "missing" }
 				};
-				const restored = contentRangeOf(entry.oldText, blockTarget.block.oldStart, blockTarget.block.oldEnd);
-				const updatedNew = replaceContentLines(entry.newText, blockTarget.block.newStart, blockTarget.block.newEnd, restored);
-				const content = reencodeEol(updatedNew, detectEol(entry.newText));
+				const revertChars = charSpansOf(blockTarget.block);
+				let revertedText;
+				if (revertChars === void 0 || !charSpansStayOnOneLine(entry.oldText, entry.newText, revertChars)) {
+					const restored = contentRangeOf(entry.oldText, blockTarget.block.oldStart, blockTarget.block.oldEnd);
+					revertedText = replaceContentLines(entry.newText, blockTarget.block.newStart, blockTarget.block.newEnd, restored);
+				} else {
+					const restored = entry.oldText.slice(revertChars.old.start, revertChars.old.end);
+					const spliced = spliceChars(entry.newText, revertChars.new.start, revertChars.new.end, restored);
+					if (spliced === void 0) return rpcError("block character span does not fit the file");
+					revertedText = spliced;
+				}
+				const content = reencodeEol(revertedText, detectEol(entry.newText));
 				store.update(blockTarget.id, { newText: content });
 				const afterEntry = {
 					...entry,
@@ -6639,7 +6720,7 @@ function apply(ctx, config) {
 				}
 				if (undo !== void 0) pushUndo(blockTarget.sessionId, undo.before, undo.after);
 				persistSession();
-				const fullyResolved = contentEqual(updatedNew, entry.oldText);
+				const fullyResolved = contentEqual(revertedText, entry.oldText);
 				if (fullyResolved && blockTarget.removeWhenResolved === true) {
 					const resolvedDrop = droppingComments({
 						id: entry.id,
@@ -7233,6 +7314,8 @@ function blockTargetOf(payload) {
 		newStart,
 		newEnd
 	].every((value) => typeof value === "number" && Number.isFinite(value))) return void 0;
+	const oldChars = charSpanOf(block.oldChars);
+	const newChars = charSpanOf(block.newChars);
 	const removeWhenResolved = payload.removeWhenResolved;
 	return {
 		...target,
@@ -7240,11 +7323,78 @@ function blockTargetOf(payload) {
 			oldStart,
 			oldEnd,
 			newStart,
-			newEnd
+			newEnd,
+			...oldChars !== void 0 && newChars !== void 0 ? {
+				oldChars,
+				newChars
+			} : {}
 		},
 		removeWhenResolved: typeof removeWhenResolved === "boolean" ? removeWhenResolved : void 0
 	};
 }
+/** Narrow one wire character span: two finite, non-negative, ordered offsets. */
+function charSpanOf(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return void 0;
+	const { start, end } = value;
+	if (typeof start !== "number" || typeof end !== "number") return void 0;
+	if (!Number.isInteger(start) || !Number.isInteger(end)) return void 0;
+	if (start < 0 || end < start) return void 0;
+	return {
+		start,
+		end
+	};
+}
+/**
+* The pair of character spans a block names, when it names both.
+*
+* A block carries either both spans (a preview's sub-line change) or neither (every line-based caller); one
+* without the other is meaningless and is treated as absent.
+*
+* @param block - the incoming block range.
+* @returns the two spans, or undefined for a line-based block.
+*/
+function charSpansOf(block) {
+	if (block.oldChars === void 0 || block.newChars === void 0) return void 0;
+	return {
+		old: block.oldChars,
+		new: block.newChars
+	};
+}
+/**
+* Whether character spans really stay inside ONE line on both sides.
+*
+* A character-level keep/revert is only safe within a line. A caller can (and an older renderer did) send a
+* span that crosses a newline — splicing that accepted text into the middle of a line corrupts the baseline,
+* duplicating or swallowing lines and making the block impossible to keep afterwards. Such a span falls back
+* to its line range, which the block always carries.
+*
+* @param oldText - the entry's baseline.
+* @param newText - the entry's current content.
+* @param spans - the character spans to check.
+* @returns true when both spanned slices are single-line (or empty).
+*/
+function charSpansStayOnOneLine(oldText, newText, spans) {
+	const oldSlice = oldText.slice(spans.old.start, spans.old.end);
+	const newSlice = newText.slice(spans.new.start, spans.new.end);
+	return !oldSlice.includes("\n") && !newSlice.includes("\n");
+}
+/**
+* Replace `[start, end)` of `text` with `insert`, refusing a span that does not fit.
+*
+* The character-level counterpart of `replaceContentLines` (which works in whole lines): a Markdown preview
+* block can be smaller than a line — a changed table cell beside an unchanged one — and keeping or reverting
+* just that change must not touch its neighbours on the same line.
+*
+* @param text - the file the span indexes.
+* @param start - first character to replace, 0-based.
+* @param end - offset just past the last character to replace.
+* @param insert - what takes its place.
+* @returns the new text, or undefined when the span is out of range.
+*/
+function spliceChars(text, start, end, insert) {
+	if (start > end || end > text.length) return void 0;
+	return text.slice(0, start) + insert + text.slice(end);
+}
 /** Narrow a wire payload to one keep/revert target. */
 function targetOf(payload) {
 	const sessionId = sessionOf(payload);

package/lib/types/client/comment-card-seat.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The session-scoped seat that publishes the shown conversation to the comment-card bridge.
+ *
+ * It renders nothing: the shell hands every session-scope slot component `sessionId` and `useChat`, and
+ * the published snapshot is what lets the DOM side join a rendered trigger card's node key back to the
+ * comment it delivered. Both props are read defensively, so a shell that hands only one of them still
+ * leaves the other facts intact.
+ *
+ * @module dsh-diff-approval/client/comment-card-seat
+ */
+import type { ReactNode } from 'react';
+/** Props the shell injects into a session-scoped seat. */
+export interface CommentCardSeatProps {
+    /** The session this seat's page is showing. */
+    sessionId?: unknown;
+    /** The chat snapshot selector, when this shell merges it onto session-scope slots. */
+    useChat?: unknown;
+}
+/**
+ * Publish the shown conversation's snapshot for the comment-card titles.
+ * @param props - the shell-injected session id and chat hook.
+ * @returns null; this seat is invisible by design.
+ */
+export declare function CommentCardSeat(props: CommentCardSeatProps): ReactNode;

package/lib/types/client/comment-card.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Title the shell's trigger card for a COMMENT delivered from the review panel.
+ *
+ * A comment asked of an idle agent is delivered through the host's wake-up seam (see
+ * `src/comment-ask.ts`), so the shell draws that turn's wake message as its own `turn-trigger` card —
+ * the same card a scheduled reminder or a shortcut gets. The card's title comes from a CLOSED switch
+ * over `source.kind` inside the shell, and a kind it does not know falls back to the generic "execution
+ * requested"; there is no seam to teach it a new kind without taking over the renderer for EVERY wake
+ * source. So the title is corrected here, in the DOM, joined through the node key the shell already
+ * puts on the card.
+ *
+ * Only cards whose source kind is this plugin's own (`diff-comment`) are touched: a reminder, a goal
+ * or another plugin's delivery keeps exactly the title it had.
+ *
+ * @module dsh-diff-approval/client/comment-card
+ */
+/** One delivered comment, as the chat snapshot exposes it. */
+export interface CommentCardMeta {
+    /** The reviewed file, as the comment recorded it. */
+    path: string;
+    /** First new-file line of the comment's anchor. */
+    startLine: number;
+    /** Last new-file line of the comment's anchor. */
+    endLine: number;
+}
+/**
+ * Build the node key → comment map from one chat snapshot.
+ * @param snapshot - the chat snapshot handed to the seat.
+ * @returns the delivered comments, by the node key the shell puts on their card.
+ */
+export declare function buildCommentCards(snapshot: unknown): Map<string, CommentCardMeta>;
+/**
+ * Publish the shown conversation's delivered comments.
+ * @param snapshot - the chat snapshot as the seat received it.
+ */
+export declare function publishCommentCards(snapshot: unknown): void;
+/** Forget the published comments (the seat unmounted). */
+export declare function withdrawCommentCards(): void;
+/** Subscribe a non-React reader to publishes. */
+export declare function subscribeCommentCards(listener: () => void): () => void;
+/** The comment a delivered card came from, or undefined for every other wake source. */
+export declare function publishedCommentCard(nodeKey: string): CommentCardMeta | undefined;
+/**
+ * The label a card's title carries: the file's base name and the comment's lines.
+ * @param meta - the delivered comment.
+ * @returns `README.md:40`, or `README.md:40-42` for a multi-line anchor.
+ */
+export declare function commentCardLabel(meta: CommentCardMeta): string;
+/** The translator this decoration needs (the plugin's own namespace). */
+export type CommentCardTranslate = (key: 'commentCard.title') => string;
+/**
+ * Title every rendered trigger card that belongs to one of our delivered comments.
+ *
+ * Separate from {@link attachCommentCardTitles} so the DOM pass is a plain, testable call.
+ * @param t - translator for the plugin's namespace.
+ */
+export declare function titleCommentCards(t: CommentCardTranslate): void;
+/**
+ * Title delivered comments' cards, and keep them titled as the chat re-renders.
+ *
+ * Returns early without a `document`, like every DOM bridge in this plugin: the published bundle is
+ * exercised in headless harnesses where those globals do not exist, and a decoration must never be the
+ * reason a plugin fails to load.
+ * @param options - the plugin's translator.
+ * @returns a disposer that stops observing (the cards unmount with the view).
+ */
+export declare function attachCommentCardTitles(options: {
+    t: CommentCardTranslate;
+}): () => void;

package/lib/types/client/locales.d.ts

@@ -57,6 +57,11 @@ export declare const zh: {
     'panel.diffLineHeightDesc': string;
     'panel.mdPreview': string;
     'panel.mdPreviewDesc': string;
+    'panel.mdStructure': string;
+    'panel.mdStructureDesc': string;
+    'panel.sourceDiff': string;
+    'panel.invisibleContent': string;
+    'commentCard.title': string;
     'panel.codeFont': string;
     'panel.codeFontDesc': string;
     'panel.mdMaxWidth': string;
@@ -327,6 +332,11 @@ export declare const en: {
     'panel.diffLineHeightDesc': string;
     'panel.mdPreview': string;
     'panel.mdPreviewDesc': string;
+    'panel.mdStructure': string;
+    'panel.mdStructureDesc': string;
+    'panel.sourceDiff': string;
+    'panel.invisibleContent': string;
+    'commentCard.title': string;
     'panel.codeFont': string;
     'panel.codeFontDesc': string;
     'panel.mdMaxWidth': string;

package/lib/types/client/markdown-preview.d.ts

@@ -1,20 +1,201 @@
 /** Self-contained Markdown preview-diff renderer.
  *
- *  Renders the whole-file text diff at the Markdown level: the source diff is
- *  computed first, then each added/removed/context run is rendered through
- *  `marked` and presented single-column (merged, like the unified source diff)
- *  or double-column (before | after). Every rendered block carries its run's
- *  add/remove/context status so it can be tinted with the diff colors.
+ *  Two styles, chosen by the caller:
+ *
+ *  - `blocks` (the original): the source diff is cut into contiguous add/del/context runs and each run is
+ *    parsed as a document of its own, then wrapped in a `<div>`. Simple, and wrong for any structure that
+ *    spans a run boundary — a reworded list item becomes four lists, a changed table row falls out of the
+ *    table and renders as text, a changed fenced line stops being code.
+ *  - `structure` (the default): the whole document is rendered ONCE, exactly as the author wrote it, and
+ *    the diff is mapped onto the elements that came from the changed lines. Nothing is re-parsed, no
+ *    wrapper is inserted, so the document keeps its own layout. A deletion and the addition that replaces
+ *    it are shown TOGETHER inside the same element (`~~old~~ new`), and a deleted element with no
+ *    counterpart is emitted as a struck ghost beside its sibling — inside the same list, table or column.
+ *
+ *  Both styles emit the same contract the panel's anchoring already reads: `data-md-block` / `data-md-kind` on
+ *  every element that carries a difference BLOCK (what the toolbar numbers, frames and keeps), `data-md-unit`
+ *  on every element that carries a character-level change inside one (what is highlighted), plus `mdAdd` /
+ *  `mdDel` for the tint and `mdWordAdd` / `mdWordDel` for the changed characters inside one element.
+ */
+/** How the preview expresses the diff. See the module comment. */
+export type MarkdownPreviewStyle = 'structure' | 'blocks';
+/** An inclusive span of 0-based source lines. */
+interface LineSpan {
+    start: number;
+    end: number;
+}
+/**
+ * One character-level change the preview HIGHLIGHTS.
+ *
+ * The source view's blocks are lines, but a rendered document puts several changes on one line: a table row
+ * holds a reworded cell AND a retargeted link, and each is a separate run to highlight. The preview cuts each
+ * line block into these units for the drawn marks. What the reader COUNTS and keeps, though, is a BLOCK
+ * (`PreviewBlock`): one pure-addition hunk, one table row, or one invisible change — which may hold several
+ * units (see `previewBlocks`).
+ */
+export interface PreviewUnit {
+    /** Index in the preview's own unit numbering: the `data-md-unit` value (its block is `data-md-block`). */
+    index: number;
+    /** The source-line block this unit was cut from. */
+    lineBlock: number;
+    /** The line block's own 1-based inclusive line ranges, carried along for the source view. */
+    oldLines: {
+        start: number;
+        end: number;
+    };
+    newLines: {
+        start: number;
+        end: number;
+    };
+    /** The change's absolute character span per side, `[start, end)`; `start === end` is an insertion. */
+    oldChars: {
+        start: number;
+        end: number;
+    };
+    newChars: {
+        start: number;
+        end: number;
+    };
+    /** The changed source itself on each side, for matching the runs that were drawn. */
+    oldText: string;
+    newText: string;
+}
+/**
+ * Cut the file's change blocks into the preview's units.
+ *
+ * A line block is worked through LINE BY LINE: its changed old lines and changed new lines are paired in
+ * order (the k-th removed line with the k-th added one, the same reading the side-by-side view uses), and each
+ * pair is diffed again character by character — every run of changed characters becomes a unit, and runs a
+ * few characters apart on that line are folded into one so a reworded sentence stays one change rather than
+ * three. A changed line with no counterpart is a pure deletion or addition and is one unit itself over its
+ * whole line.
+ *
+ * Working per line is what keeps a deleted paragraph from being swallowed by the retargeted link above it: a
+ * character diff run over a whole multi-line block would fold the newline into the change and report the link
+ * and the paragraph as one unit, and a unit is a hover target and a Keep/Revert action.
+ *
+ * @param oldText - the file's tracked baseline.
+ * @param newText - the file's current content.
+ * @returns the units, in document order.
  */
+/** localStorage key that picks the preview's diff pipeline: `1` = tree-first, `0` = legacy line-hunk path. */
+export declare const TREE_DIFF_SETTING = "diff-approval:tree-diff";
+/** The pipeline the preview uses when nothing is stored: the tree-first path. */
+export declare const TREE_DIFF_DEFAULT = true;
+/**
+ * Whether the tree-first diff is active.
+ *
+ * The browser default is the TREE path (`TREE_DIFF_DEFAULT`); `localStorage` can force either pipeline (1/0).
+ * Inside the unit-test environment the default is the LEGACY path instead, so the old behavior's regression
+ * specs keep asserting the old behavior; the tree path's own specs opt in explicitly. End-to-end tests run the
+ * real browser default and a dedicated e2e spec pins the tree path there.
+ */
+export declare function treeDiffEnabled(): boolean;
+export declare function previewUnits(oldText: string, newText: string): PreviewUnit[];
+/** A change the rendering cannot show: the toolbar lists it as source, with its own line numbers. */
+export interface PreviewInvisibleDiff {
+    /** The removed source line(s), 1-based inclusive. */
+    oldLines?: {
+        start: number;
+        end: number;
+    };
+    /** The added source line(s), 1-based inclusive. */
+    newLines?: {
+        start: number;
+        end: number;
+    };
+    /** The removed source itself. */
+    oldText?: string;
+    /** The added source itself. */
+    newText?: string;
+    /** The grammar the source is highlighted with: YAML for front matter, Markdown otherwise. */
+    grammar: 'markdown' | 'yaml';
+}
+/**
+ * One DIFFERENCE BLOCK: what the preview numbers, navigates, frames, and keeps or reverts.
+ *
+ * A block is NOT the same thing as a unit. A unit is a character-level change inside one line — the thing the
+ * preview highlights — while a block is the thing the reader counts and acts on. One block can hold several
+ * units (a changed table row's cells, a whole added paragraph's lines) or none at all (a whole new row, a
+ * deletion the rendering only reports as source). The rules:
+ *
+ *  - a pure addition or pure deletion hunk (a new paragraph, a new list, a new table, the whole of a new
+ *    file) is ONE block, however many units its lines were cut into;
+ *  - a mixed hunk (an edit) numbers one block per unit, except a table row, which is one block for the row;
+ *    a table row with no counterpart in the other version is one block too, tinted as a row;
+ *  - a change that renders nothing (front matter, an HTML comment, a link definition) is a block of its own;
+ *    inside a merged pure block it joins that block instead (its source is listed in the block's tabs).
+ */
+export interface PreviewBlock {
+    /** Document order: the preview's `data-md-block` value and the toolbar's number. */
+    index: number;
+    /** The source-line hunk this block came from. */
+    lineBlock: number;
+    /**
+     * The highlighted units that belong to this block. A whole-row block still lists its one whole-line unit
+     * (the unit→block map needs it), but the renderer draws the ROW rather than that unit's characters.
+     */
+    units: PreviewUnit[];
+    /** Keep/revert range on the old side, 1-based; an absent side is empty (`oldStart > oldEnd`). */
+    oldStart: number;
+    oldEnd: number;
+    /** Keep/revert range on the new side, 1-based; an absent side is empty (`newStart > newEnd`). */
+    newStart: number;
+    newEnd: number;
+    /** The character span used when this block is exactly one unit and has no invisible part. */
+    oldChars?: {
+        start: number;
+        end: number;
+    };
+    newChars?: {
+        start: number;
+        end: number;
+    };
+    /** The lines that actually changed (0-based, inclusive), for drawing the block: no insertion widening. */
+    oldChanged?: LineSpan;
+    newChanged?: LineSpan;
+    /** Whether a whole pure-addition/deletion hunk was merged into this block. */
+    merged: boolean;
+    /** A table row with no counterpart on the other side: tint the row, not its cells. */
+    wholeRow?: 'add' | 'del';
+    /** Changes inside this block that the rendering cannot show, in source order. */
+    invisible: PreviewInvisibleDiff[];
+}
+/**
+ * The preview's DIFFERENCE BLOCKS: the unit the reader counts, navigates, frames and keeps/reverts.
+ *
+ * @param oldText - the file's tracked baseline.
+ * @param newText - the file's current content.
+ * @returns the blocks, in document order.
+ */
+export declare function previewBlocks(oldText: string, newText: string): PreviewBlock[];
 /**
  * Render the Markdown preview as sanitized HTML.
  * @param oldText - the file's tracked baseline (rendered as "before").
- * @param newText - the file's current content (rendered as "after").
- * @param mode - 'single' merges add/remove/context (unified-like); 'double'
- *   shows the before and after renderings aligned row by row, each change block
- *   tinted (deleted on the before side, added on the after side). Comparable
- *   edits get word-level highlights on the changed words.
- * @returns sanitized HTML for the preview body. Local images keep their src so
- *   a later pass can resolve them to data URIs (see the preview image resolver).
- */
-export declare function renderMarkdownPreview(oldText: string, newText: string, mode: 'single' | 'double'): string;
+ * @param newText - the file's current content.
+ * @param mode - 'single' merges both sides into one reading of the document; 'double' shows the before and
+ *   after renderings as two whole documents.
+ * @param style - 'structure' (default) renders each document once and maps the diff onto its elements;
+ *   'blocks' is the original fragment-per-run renderer, kept behind the setting.
+ * @param labels - user-facing words the rendered markup must carry (none by default; the tests render bare).
+ * @returns sanitized HTML for the preview body. Local images keep their src so a later pass can resolve
+ *   them to data URIs (see the preview image resolver).
+ */
+export declare function renderMarkdownPreview(oldText: string, newText: string, mode: 'single' | 'double', style?: MarkdownPreviewStyle, labels?: {
+    readonly invisible?: string;
+}): string;
+/** The tree path's units, adapted to the panel's `PreviewUnit` shape. */
+export declare function treePreviewUnits(oldText: string, newText: string): PreviewUnit[];
+/** The tree path's blocks, adapted to the panel's `PreviewBlock` shape. */
+export declare function treePreviewBlocks(oldText: string, newText: string): PreviewBlock[];
+/** The paragraph-level blocks, adapted to the panel's `PreviewBlock` shape. */
+export declare function flowPreviewBlocks(oldText: string, newText: string): PreviewBlock[];
+/** Render the paragraph-level single column: old above new, tinted rows grouped into hunk blocks. */
+export declare function renderFlowMerged(oldText: string, newText: string): string;
+/**
+ * The same flow model, rendered as TWO aligned columns: old left, new right. Every difference block is one grid
+ * row whose two cells are the red (old) and green (new) halves of the change, so a matched block's colour reads
+ * as one continuous band across the gutter. Unchanged rows are context grid rows (same content on both sides).
+ */
+export declare function renderFlowDouble(oldText: string, newText: string): string;
+export {};

package/lib/types/client/markdown-tree-blocks.d.ts

@@ -0,0 +1,90 @@
+import { type MarkdownTreeNode } from './markdown-tree-match.ts';
+/** One character-level change: what the preview highlights. Mirrors `PreviewUnit` in markdown-preview.ts. */
+export interface TreePreviewUnit {
+    index: number;
+    /** Kept for source-view compatibility; the tree path has no line hunks, so this is the block's index. */
+    lineBlock: number;
+    oldLines: {
+        start: number;
+        end: number;
+    };
+    newLines: {
+        start: number;
+        end: number;
+    };
+    oldChars: {
+        start: number;
+        end: number;
+    };
+    newChars: {
+        start: number;
+        end: number;
+    };
+    oldText: string;
+    newText: string;
+}
+/** A change the rendering cannot show: mirrors `PreviewInvisibleDiff` in markdown-preview.ts. */
+export interface TreePreviewInvisibleDiff {
+    oldLines?: {
+        start: number;
+        end: number;
+    };
+    newLines?: {
+        start: number;
+        end: number;
+    };
+    oldText?: string;
+    newText?: string;
+    grammar: 'markdown' | 'yaml';
+}
+/** One difference block: mirrors `PreviewBlock` in markdown-preview.ts, plus the tree nodes it came from. */
+export interface TreePreviewBlock {
+    index: number;
+    lineBlock: number;
+    units: TreePreviewUnit[];
+    oldStart: number;
+    oldEnd: number;
+    newStart: number;
+    newEnd: number;
+    oldChars?: {
+        start: number;
+        end: number;
+    };
+    newChars?: {
+        start: number;
+        end: number;
+    };
+    merged: boolean;
+    wholeRow?: 'add' | 'del';
+    invisible: TreePreviewInvisibleDiff[];
+    /** The block's own kind, for the renderer and tests (`paragraph`, `list_item`, `table_row`, `code`, …). */
+    kind: string;
+    /** A `table_cell` block's column: which cell of its row it covers. */
+    cellColumn?: number;
+    /**
+     * For an INLINE-CHILD block (a text run, a changed link/strong/image inside a paragraph/cell/item): the
+     * container pair whose rendered element hosts the change. The block never owns the container element
+     * itself, so blocks cannot nest inside each other.
+     */
+    inlineContainer?: {
+        old?: MarkdownTreeNode;
+        new?: MarkdownTreeNode;
+    };
+    /** The old-side nodes this block covers (empty for a pure addition). */
+    oldNodes: MarkdownTreeNode[];
+    /** The new-side nodes this block covers (empty for a pure deletion). */
+    newNodes: MarkdownTreeNode[];
+}
+/** The tree path's whole model: units in reading order, and blocks in document order. */
+export interface TreePreviewModel {
+    blocks: TreePreviewBlock[];
+    units: TreePreviewUnit[];
+}
+/**
+ * Compute the tree path's preview model for one document pair.
+ *
+ * @param oldText - the baseline.
+ * @param newText - the current content.
+ * @returns the blocks (document order) and their units, with 1-based line ranges for keep/revert.
+ */
+export declare function treePreviewModel(oldText: string, newText: string): TreePreviewModel;