dsh-diff-approval 0.19.3 → 0.20.0

package/lib/index.js

@@ -138,6 +138,18 @@ var PendingDiffStore = class {
 		return true;
 	}
 	/**
+	* Admit one entry into the list without the change guard {@link fold} applies.
+	* A listed entry may carry no diff at all: a path the user added by hand has
+	* no local change until one appears, and a fully-resolved file has already
+	* folded its diff away. This is the guard-free put {@link restore} performs,
+	* named for its other caller.
+	* @param entry - the entry to insert or replace by path.
+	* @returns whether the store changed.
+	*/
+	insert(entry) {
+		return this.restore(entry);
+	}
+	/**
 	* Merge persisted entries into the store, one per path after folding. A live
 	* entry wins over a persisted one only when its time is newer (folders are
 	* applied in capture order, so a later persisted capture is strictly newer).
@@ -820,6 +832,50 @@ function writeOutcomeOf(value) {
 function errorMessage(error) {
 	return error instanceof Error ? error.message : String(error);
 }
+/** Directories one browse level hides: VCS/build noise a review list never wants.
+*  The path box can still reach them by typing the path outright. */
+const BROWSE_HIDDEN_NAMES = /* @__PURE__ */ new Set([".git", "node_modules"]);
+/** Cap on one browse level's children: the panel renders a list, not a dump of a
+*  huge directory, and it reports `truncated` rather than silently cutting. */
+const BROWSE_ENTRY_CAP = 500;
+/** Cap on the files one no-change walk reads: ticking the box on a directory
+*  asks for "everything under here", which must not mean reading a whole tree
+*  (every file's text) inside one call. */
+const ADD_UNCHANGED_CAP = 300;
+/**
+* One absolute path as a workspace-relative path with `/` separators, or
+* `undefined` when it lies outside the root. `''` is the root itself.
+* @param root - the workspace root.
+* @param absolute - the path to express relative to it.
+* @returns the relative path, or undefined when outside.
+*/
+function workspaceRelativeOf(root, absolute) {
+	const rel = relative(resolve(root), resolve(absolute));
+	if (rel === "") return "";
+	if (isAbsolute(rel)) return void 0;
+	const parts = rel.split(/[\\/]/);
+	if (parts[0] === "..") return void 0;
+	return parts.join("/");
+}
+/**
+* Resolve one caller-supplied path against the workspace root. A relative path
+* is taken as workspace-relative; an absolute one must still land inside.
+* @param root - the workspace root.
+* @param input - the caller's path (absolute or workspace-relative).
+* @returns the absolute path, or undefined when it escapes the workspace.
+*/
+function resolveInsideWorkspace(root, input) {
+	const absolute = isAbsolute(input) ? resolve(input) : resolve(root, input);
+	return workspaceRelativeOf(root, absolute) === void 0 ? void 0 : absolute;
+}
+/** The workspace-relative parent of a relative directory path (`''` at the root). */
+/** Fold one path for comparison: absolute, `/`-separated, case-folded on Windows.
+*  Entries are keyed by the path spelling their capture carried (a tool's display
+*  path or a scan's absolute one), so an equality test has to normalize first. */
+function pathIdentity(absolute) {
+	const unified = resolve(absolute).split(/[\\/]/).join("/");
+	return process.platform === "win32" ? unified.toLowerCase() : unified;
+}
 /** Narrow a tool-execution-shaped value to its name, call id, and agent. */
 function actorOf(value) {
 	if (typeof value !== "object" || value === null) return void 0;
@@ -1103,6 +1159,138 @@ function apply(ctx, config) {
 		};
 	}
 	/**
+	* Fold a batch of entries into one session's list as a single undoable action.
+	* Nothing touches the files, so the batch is undone by restoring each affected
+	* path's pre-fold entry (or removing it when the path was not listed), which is
+	* what the import and the hand-add path both want.
+	* @param sessionId - the session whose list gains the entries.
+	* @param entries - the entries to fold, in capture order.
+	* @param admitNoDiff - also admit entries that carry no diff at all (the
+	*        guard-free insert), which is how a hand-added clean path is listed.
+	* @returns how many entries landed; 0 leaves the store, persistence, and the
+	*          undo queue untouched.
+	*/
+	async function foldBatch(sessionId, entries, admitNoDiff = false) {
+		await ensureLoaded();
+		const before = new Map(store.list(sessionId).map((entry) => [entry.path, entry]));
+		let folded = 0;
+		const changedPaths = [];
+		for (const entry of entries) if (entry.oldText === entry.newText ? admitNoDiff && store.insert(entry) : store.fold(entry)) {
+			folded += 1;
+			changedPaths.push(entry.path);
+		}
+		if (folded === 0) return 0;
+		persistSession(true);
+		const after = new Map(store.list(sessionId).map((entry) => [entry.path, entry]));
+		const batchBefore = [];
+		const batchAfter = [];
+		for (const path of changedPaths) {
+			const final = after.get(path);
+			if (final === void 0) continue;
+			const pre = before.get(path);
+			batchAfter.push({
+				id: final.id,
+				path,
+				entry: final,
+				fileText: void 0
+			});
+			batchBefore.push({
+				id: final.id,
+				path,
+				entry: pre,
+				fileText: void 0
+			});
+		}
+		if (batchBefore.length > 0) pushUndo(sessionId, {
+			id: batchBefore[0].id,
+			path: batchBefore[0].path,
+			entry: void 0,
+			fileText: void 0,
+			batch: batchBefore
+		}, {
+			id: batchAfter[0].id,
+			path: batchAfter[0].path,
+			entry: void 0,
+			fileText: void 0,
+			batch: batchAfter
+		});
+		return folded;
+	}
+	/**
+	* One path's text, or `undefined` when it is absent or not readable as text
+	* (a binary, an unreadable permission). An empty file reads as `''`, which is
+	* a value: a listed entry may carry no content at all.
+	* @param absolute - the path to read.
+	* @param signal - caller lifetime.
+	* @returns the text, or undefined.
+	*/
+	async function readTextOrNone(absolute, signal) {
+		try {
+			return await ctx.fs.readText(await ctx.fs.resolve(absolute, { signal }), signal);
+		} catch {
+			return;
+		}
+	}
+	/**
+	* Every regular file under one directory, with its text. Breadth-first in the
+	* backend's name order, hiding the browse's noise names, skipping whatever is
+	* not readable as text, and stopping at {@link ADD_UNCHANGED_CAP} files so
+	* "include paths with no change" cannot read an unbounded tree in one call.
+	* Symlinked directories are followed once, so a cycle ends rather than loops.
+	* @param root - the resolved directory target to walk.
+	* @param rootAbsolute - that directory's absolute path.
+	* @param signal - caller lifetime.
+	* @returns the files found and whether the cap cut the walk short.
+	*/
+	async function collectFilesUnder(root, rootAbsolute, signal) {
+		const files = [];
+		const visited = /* @__PURE__ */ new Set();
+		if (typeof root.targetKey === "string" && root.targetKey !== "") visited.add(root.targetKey);
+		const queue = [{
+			absolute: rootAbsolute,
+			target: root
+		}];
+		while (queue.length > 0) {
+			const current = queue.shift();
+			if (current === void 0) break;
+			let children;
+			try {
+				children = await ctx.fs.listDir(current.target, signal);
+			} catch {
+				continue;
+			}
+			for (const child of children) {
+				if (BROWSE_HIDDEN_NAMES.has(child.name)) continue;
+				const absolute = resolve(current.absolute, child.name);
+				if (child.type === "directory") {
+					const key = child.target.targetKey;
+					if (typeof key === "string" && key !== "") {
+						if (visited.has(key)) continue;
+						visited.add(key);
+					}
+					queue.push({
+						absolute,
+						target: child.target
+					});
+					continue;
+				}
+				if (child.type !== "file") continue;
+				if (files.length >= ADD_UNCHANGED_CAP) return {
+					files,
+					truncated: true
+				};
+				files.push({
+					path: absolute,
+					content: await readTextOrNone(absolute, signal)
+				});
+			}
+		}
+		return {
+			files,
+			truncated: false
+		};
+	}
+	/**
 	* The workspace whose session account holds `sessionId`. Web sessions are
 	* attached to a workspace at creation, so an unowned session is the
 	* memory-only edge (its entries never persist).
@@ -1690,66 +1878,19 @@ function apply(ctx, config) {
 				} catch (error) {
 					return rpcError(`import failed: ${errorMessage(error)}`);
 				}
-				await ensureLoaded();
-				const before = new Map(store.list(sessionId).map((entry) => [entry.path, entry]));
-				let imported = 0;
-				const changedPaths = [];
-				for (const change of changes) {
-					const entry = {
-						id: change.path,
-						sessionId,
-						path: change.path,
-						kind: change.kind,
-						oldText: change.oldText,
-						newText: change.newText,
-						updatedAt: Date.now(),
-						sessionIds: [sessionId]
-					};
-					if (store.fold(entry)) {
-						imported += 1;
-						changedPaths.push(change.path);
-					}
-				}
-				if (imported > 0) {
-					persistSession();
-					const after = new Map(store.list(sessionId).map((entry) => [entry.path, entry]));
-					const batchBefore = [];
-					const batchAfter = [];
-					for (const path of changedPaths) {
-						const final = after.get(path);
-						if (final === void 0) continue;
-						const pre = before.get(path);
-						batchAfter.push({
-							id: final.id,
-							path,
-							entry: final,
-							fileText: void 0
-						});
-						batchBefore.push({
-							id: final.id,
-							path,
-							entry: pre,
-							fileText: void 0
-						});
-					}
-					if (batchBefore.length > 0) pushUndo(sessionId, {
-						id: batchBefore[0].id,
-						path: batchBefore[0].path,
-						entry: void 0,
-						fileText: void 0,
-						batch: batchBefore
-					}, {
-						id: batchAfter[0].id,
-						path: batchAfter[0].path,
-						entry: void 0,
-						fileText: void 0,
-						batch: batchAfter
-					});
-				}
 				return {
 					ok: true,
 					value: {
-						imported,
+						imported: await foldBatch(sessionId, changes.map((change) => ({
+							id: change.path,
+							sessionId,
+							path: change.path,
+							kind: change.kind,
+							oldText: change.oldText,
+							newText: change.newText,
+							updatedAt: Date.now(),
+							sessionIds: [sessionId]
+						}))),
 						detected: true
 					}
 				};
@@ -1787,8 +1928,7 @@ function apply(ctx, config) {
 				} catch (error) {
 					return rpcError(`refresh failed: ${errorMessage(error)}`);
 				}
-				const folded = (value) => process.platform === "win32" ? resolve(value).toLowerCase() : resolve(value);
-				const change = changes.find((candidate) => folded(candidate.path) === folded(entry.path));
+				const change = changes.find((candidate) => pathIdentity(candidate.path) === pathIdentity(entry.path));
 				if (change === void 0) return {
 					ok: true,
 					value: { outcome: "no-change" }
@@ -1822,6 +1962,175 @@ function apply(ctx, config) {
 					value: { outcome: "refreshed" }
 				};
 			}
+			case "list-path": {
+				const sessionId = sessionOf(payload);
+				if (sessionId === void 0) return rpcError("sessionId must be a non-empty string");
+				const workspace = workspaceOf(sessionId);
+				if (workspace === void 0) return rpcError("browse unavailable: the session has no workspace");
+				const requested = pathFieldOf(payload) ?? "";
+				const absolute = resolveInsideWorkspace(workspace.path, requested);
+				if (absolute === void 0) return rpcError("browse failed: the path is outside the workspace");
+				let children;
+				try {
+					const target = await ctx.fs.resolve(absolute, { signal });
+					const info = await ctx.fs.stat(target, signal);
+					if (info === void 0 || info.type !== "directory") return rpcError("browse failed: not a directory");
+					children = await ctx.fs.listDir(target, signal);
+				} catch (error) {
+					return rpcError(`browse failed: ${errorMessage(error)}`);
+				}
+				const entries = [];
+				for (const child of children) {
+					if (BROWSE_HIDDEN_NAMES.has(child.name)) continue;
+					const childAbsolute = resolve(absolute, child.name);
+					if (workspaceRelativeOf(workspace.path, childAbsolute) === void 0) continue;
+					entries.push({
+						name: child.name,
+						type: child.type === "directory" ? "directory" : child.type === "file" ? "file" : "other",
+						path: childAbsolute,
+						size: child.type === "file" ? child.size : void 0
+					});
+				}
+				entries.sort((left, right) => {
+					const rank = (value) => value.type === "directory" ? 0 : 1;
+					const byKind = rank(left) - rank(right);
+					return byKind !== 0 ? byKind : left.name.localeCompare(right.name, void 0, {
+						numeric: true,
+						sensitivity: "base"
+					});
+				});
+				const truncated = entries.length > BROWSE_ENTRY_CAP;
+				return {
+					ok: true,
+					value: {
+						path: absolute,
+						entries: truncated ? entries.slice(0, BROWSE_ENTRY_CAP) : entries,
+						truncated
+					}
+				};
+			}
+			case "add-path": {
+				const target = addTargetOf(payload);
+				if (target === void 0) return rpcError("sessionId and path must be non-empty strings");
+				const workspace = workspaceOf(target.sessionId);
+				if (workspace === void 0) return rpcError("add unavailable: the session has no workspace");
+				const absolute = resolveInsideWorkspace(workspace.path, target.path);
+				if (absolute === void 0) return {
+					ok: true,
+					value: {
+						outcome: "outside",
+						added: 0,
+						duplicates: 0
+					}
+				};
+				await ensureLoaded();
+				let info;
+				try {
+					const target = await ctx.fs.resolve(absolute, { signal });
+					info = await ctx.fs.stat(target, signal);
+				} catch (error) {
+					return rpcError(`add failed: ${errorMessage(error)}`);
+				}
+				if (info === void 0 || info.type === "other") return {
+					ok: true,
+					value: {
+						outcome: "missing",
+						added: 0,
+						duplicates: 0
+					}
+				};
+				const isDirectory = info.type === "directory";
+				const root = detectVcsRoot(workspace.path);
+				if (root === void 0) return {
+					ok: true,
+					value: {
+						outcome: "no-vcs",
+						added: 0,
+						duplicates: 0
+					}
+				};
+				const shell = ctx.get("shell");
+				if (shell === void 0) return rpcError("add unavailable: the deployment has no shell executor");
+				let changes;
+				try {
+					changes = await listVcsChanges({
+						kind: root.kind,
+						root: root.root,
+						workspaceRoot: workspace.path,
+						includeUntracked: true,
+						scope: absolute,
+						shell,
+						readText: (path) => readFile(path, "utf8").catch(() => void 0),
+						signal
+					});
+				} catch (error) {
+					return {
+						ok: true,
+						value: {
+							outcome: "failed",
+							added: 0,
+							duplicates: 0,
+							message: errorMessage(error)
+						}
+					};
+				}
+				const now = Date.now();
+				const candidates = changes.map((change) => ({
+					id: change.path,
+					sessionId: target.sessionId,
+					path: change.path,
+					kind: change.kind,
+					oldText: change.oldText,
+					newText: change.newText,
+					updatedAt: now,
+					sessionIds: [target.sessionId]
+				}));
+				let truncated = false;
+				if (target.includeUnchanged) {
+					const scanned = new Set(candidates.map((entry) => pathIdentity(entry.path)));
+					const found = isDirectory ? await collectFilesUnder(await ctx.fs.resolve(absolute, { signal }), absolute, signal) : {
+						files: [{
+							path: absolute,
+							content: await readTextOrNone(absolute, signal)
+						}],
+						truncated: false
+					};
+					truncated = found.truncated;
+					for (const file of found.files) {
+						if (file.content === void 0) continue;
+						if (scanned.has(pathIdentity(file.path))) continue;
+						scanned.add(pathIdentity(file.path));
+						candidates.push({
+							id: file.path,
+							sessionId: target.sessionId,
+							path: file.path,
+							kind: "edit",
+							oldText: file.content,
+							newText: file.content,
+							updatedAt: now,
+							sessionIds: [target.sessionId]
+						});
+					}
+				}
+				const listed = new Set(store.list(target.sessionId).map((entry) => pathIdentity(entry.path)));
+				const fresh = candidates.filter((entry) => !listed.has(pathIdentity(entry.path)));
+				const duplicates = candidates.length - fresh.length;
+				const added = await foldBatch(target.sessionId, fresh, true);
+				const outcome = added > 0 ? "added" : duplicates > 0 ? "duplicate" : isDirectory ? "empty" : "unchanged";
+				return {
+					ok: true,
+					value: truncated ? {
+						outcome,
+						added,
+						duplicates,
+						truncated
+					} : {
+						outcome,
+						added,
+						duplicates
+					}
+				};
+			}
 			case "open": {
 				const target = openTargetOf(payload);
 				if (target === void 0) return rpcError("sessionId, id, and action must be valid");
@@ -1980,6 +2289,24 @@ function previewImageTargetOf(payload) {
 		path
 	};
 }
+/** One payload's optional `path` field; absent (or not a string) is undefined. */
+function pathFieldOf(payload) {
+	if (typeof payload !== "object" || payload === null || Array.isArray(payload)) return void 0;
+	const path = payload.path;
+	return typeof path === "string" ? path : void 0;
+}
+/** Narrow a wire payload to one hand-added path. */
+function addTargetOf(payload) {
+	const sessionId = sessionOf(payload);
+	if (sessionId === void 0) return void 0;
+	const path = pathFieldOf(payload)?.trim();
+	if (path === void 0 || path === "") return void 0;
+	return {
+		sessionId,
+		path,
+		includeUnchanged: payload.includeUnchanged === true
+	};
+}
 /** Narrow a wire payload to one open target: the keep/revert pair plus the action. */
 function openTargetOf(payload) {
 	const target = targetOf(payload);

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

@@ -0,0 +1,43 @@
+/**
+ * The add-path dialog: pick one path in a lazily-loaded workspace tree — or type
+ * it outright — then press Add. Nothing is added by pointing at it: the path and
+ * the no-change box are prepared first, and the host judges them once the button
+ * is pressed.
+ *
+ * The path box is the single source of truth for the selection: a tree row is
+ * highlighted while its path is the box's text, and editing the text by hand
+ * simply leaves no row highlighted.
+ *
+ * The dialog is a modal inside the panel: it owns Escape while it is on screen
+ * (the panel's own chords stand down, see `pathPickerOpen`).
+ * @module dsh-diff-approval/client/PathPicker
+ */
+import type { ReactElement } from 'react';
+import type { DiffApprovalAddValue, DiffApprovalBrowseEntry } from '../types.ts';
+import type { Translator } from './locales.ts';
+/** Whether this panel's add-path dialog is on screen. The panel's global chords
+ *  consult this so the modal owns the keyboard while it is open. */
+export declare function pathPickerOpen(): boolean;
+/** Full props of the add-path dialog. */
+export interface PathPickerProps {
+    /** The session's workspace root (absolute), for the tree's top row. */
+    rootPath?: string | undefined;
+    /** List one workspace directory level (absolute path; undefined is the root). */
+    onBrowse: (path?: string) => Promise<{
+        path: string;
+        entries: DiffApprovalBrowseEntry[];
+        truncated: boolean;
+    }>;
+    /** Add the chosen path; resolves to what the host's scan did. */
+    onAdd: (path: string, includeUnchanged: boolean) => Promise<DiffApprovalAddValue>;
+    /** Transient banner for an outcome the dialog does not stay open for. */
+    onToast: (text: string) => void;
+    onClose: () => void;
+    t: Translator;
+}
+/**
+ * The add-path dialog.
+ * @param props - the workspace root, the host calls, and the close/toast sinks.
+ * @returns the modal (rendered only while open by its parent).
+ */
+export declare function PathPicker({ rootPath, onBrowse, onAdd, onToast, onClose, t }: PathPickerProps): ReactElement;

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

@@ -3,10 +3,11 @@ import type { SessionId } from '@deepseek-ai/dsh-client-connection/client';
 import type { InjectFace, PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots';
 import type { DiffApprovalBlockRange, PendingFileDiff } from '../types.ts';
 import type { PendingPanelFace } from './slots.ts';
-import type { DiffApprovalKey } from './locales.ts';
+import type { Translator } from './locales.ts';
 import { computeWholeFileDiff } from './whole-file-diff.ts';
-import type { IntraRun } from './whole-file-diff.ts';
-import { highlightLines } from './highlight.ts';
+import type { ChangeBlock, IntraRun } from './whole-file-diff.ts';
+import type { HighlightSides } from './highlight.ts';
+import type { VisibleLines } from './windowed-highlight.ts';
 /** Normalize a path for comparison: forward slashes, no trailing slash. */
 export declare function normalizeDiffPath(p: string): string;
 /** Whether a produced-file chip path and a pending file path refer to the same
@@ -23,8 +24,6 @@ export declare const SIDEBAR_AUTO_COLLAPSE_PX = 1024;
 export declare function wrapInto(text: string, widthPx: number, measure: (t: string) => number, tabPx: number): string[];
 /** Full panel props composed by the sidebar footer-action slot. */
 export type PendingPanelProps = PropsRuntime<'sidebar.footer.action'> & InjectFace<PendingPanelFace> & PropsLocale<'diff-approval'>;
-/** Locale translator used by the panel and its rows. */
-type Translator = (key: DiffApprovalKey, params?: Record<string, unknown>) => string;
 /**
  * Open the DSH settings dialog and switch to this plugin's section. The
  * settings shell keeps its open state and the active section id as
@@ -43,16 +42,6 @@ interface RowModel {
     /** Intra-line runs keyed by row index, present only for annotated del/add rows. */
     intra: Map<number, IntraRun[]>;
 }
-/** One file's deferred syntax-highlight runs, one entry per side. */
-interface HighlightRuns {
-    oldRuns: ReturnType<typeof highlightLines>;
-    newRuns: ReturnType<typeof highlightLines>;
-}
-/** One contiguous run of changed rows, treated as a single modification. */
-interface ChangeBlock {
-    start: number;
-    end: number;
-}
 /** One selected line range in row indices, normalized low-to-high. */
 interface RowRange {
     start: number;
@@ -76,7 +65,7 @@ export interface SplitDiffHandle {
 export declare const SplitDiff: import("react").ForwardRefExoticComponent<{
     file: PendingFileDiff;
     model: RowModel;
-    runs: HighlightRuns | undefined;
+    runs: HighlightSides | undefined;
     langWrap: boolean;
     tabWidthSpaces: number;
     busy: boolean;
@@ -87,6 +76,9 @@ export declare const SplitDiff: import("react").ForwardRefExoticComponent<{
     onBlockRevert: (sessionId: SessionId, id: string, block: DiffApprovalBlockRange) => Promise<void>;
     /** Notify the parent to toast a block-wrap boundary / single-block (Ctrl+Up/Down). */
     onWrapToast: (text: string) => void;
+    /** Report which source lines this view is showing, so the parent's windowed
+     *  highlighter follows this view's own scroller (it has its own virtual window). */
+    onVisibleLines: (visible: VisibleLines) => void;
 } & import("react").RefAttributes<SplitDiffHandle>>;
 /**
  * Reconstruct the plain text of the current selection so auto-wrap's visual
@@ -97,5 +89,5 @@ export declare const SplitDiff: import("react").ForwardRefExoticComponent<{
  */
 export declare function selectedPlainText(): string | undefined;
 /** Render the pending-edit review panel and its unified footer action. */
-export declare function PendingPanel({ wide, useSessions, usePending, onRefresh, onKeep, onRevert, onBlockKeep, onBlockRevert, onOpen, onPreviewImage, onPasteReference, onUndo, onRedo, onImportVcs, onRefreshVcs, onKeepAll, onRevertAll, onAckRedoCleared, collapseSidebar, t, }: PendingPanelProps): import("react").JSX.Element;
+export declare function PendingPanel({ wide, useSessions, usePending, onRefresh, onKeep, onRevert, onBlockKeep, onBlockRevert, onOpen, onPreviewImage, onPasteReference, onUndo, onRedo, onImportVcs, onRefreshVcs, onBrowse, onAddPath, onKeepAll, onRevertAll, onAckRedoCleared, collapseSidebar, t, }: PendingPanelProps): import("react").JSX.Element;
 export {};

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

@@ -10,11 +10,42 @@
  * @module dsh-diff-approval/client/highlight
  */
 import type { CSSProperties } from 'react';
+import type { HighlighterCore } from 'shiki/core';
 /** One highlighted run of a line: literal text plus a color style. */
 export interface HighlightSpan {
     text: string;
     style: CSSProperties;
 }
+/** One file's highlight runs, one entry per side and line (index = line - 1). A
+ *  hole means that line has not been highlighted — the viewer renders it plain,
+ *  which is the honest state of a windowed highlighter: only what has been looked
+ *  at is tokenized. */
+export interface HighlightSides {
+    oldRuns: HighlightSpan[][];
+    newRuns: HighlightSpan[][];
+}
+/** A saved grammar state: resuming from one continues tokenization *exactly*
+ *  where it stopped, instead of assuming the window's first line starts the file.
+ *  Opaque to callers — only `highlightWindow` produces and consumes it, and
+ *  `undefined` means "no saved state" (the file's first line is top-level). */
+export type HighlightState = Parameters<HighlighterCore['codeToTokens']>[1]['grammarState'];
+/** One highlighted window: the requested lines' runs and the grammar state after
+ *  the last of them, for an exact continuation by the next window. */
+export interface HighlightWindow {
+    runs: HighlightSpan[][];
+    state: HighlightState;
+}
+/** Options for {@link highlightWindow}. */
+export interface HighlightWindowOptions {
+    /** Lines of preceding context to run the grammar over without returning them,
+     *  so a window starting inside a multi-line construct (a block comment, a
+     *  template literal, a fenced code block) still colours correctly. Ignored when
+     *  `state` is given: that one is exact. */
+    context?: number;
+    /** An exact state saved at this window's first line (a previous window's
+     *  `state`). */
+    state?: HighlightState;
+}
 /**
  * Primary grammar ids offered in the viewer's language selector, in picker
  * order (alphabetical). Kept explicit instead of deriving from `LANGS`: some
@@ -28,13 +59,25 @@ export declare const HIGHLIGHT_LANGS: string[];
 /** Conventional display name for a grammar id, falling back to the id itself. */
 export declare function languageDisplayName(id: string): string;
 /**
- * Tokenize `code` into per-line highlighted runs when `lang` names a
- * registered grammar; `undefined` means the caller renders its plain fallback.
- * Each run's color is a `--shiki-*` custom property, keeping token colors on
- * the harness theme's sheets. The trailing newline shiki appends as a final
- * empty line is dropped so the run count matches the caller's own line array.
- * @param code - the source text.
+ * Tokenize the lines `[from, to)` into per-line highlighted runs when `lang`
+ * names a registered grammar; `undefined` means the caller renders its plain
+ * fallback. Each run's color is a `--shiki-*` custom property, keeping token
+ * colors on the harness theme's sheets. The trailing newline shiki appends as a
+ * final empty line is dropped so the run count matches the caller's own array.
+ *
+ * This is the viewer's only entry point, and it is deliberately windowed: the
+ * code view renders a virtual window of rows, so highlighting a whole file to
+ * show one screenful is almost all waste (measured on a 3818-line file: ~945 ms
+ * for both sides whole-file against ~8 ms for one window). A window is continued
+ * *exactly* from a previous one's `state`, or approximately from `context` lines
+ * when no state is known yet — which is what lets a jump straight to the middle
+ * of a file colour correctly without tokenizing anything above it.
+ * @param lines - the side's lines, indexed from 0 as the caller's line numbers are.
  * @param lang - the Shiki grammar id, or `undefined` for plain text.
- * @returns one entry per source line (each an array of runs), or `undefined` when unhighlightable.
+ * @param from - the first line index to highlight (inclusive, clamped).
+ * @param to - one past the last line index to highlight (clamped).
+ * @param options - the grammar state to resume from and/or context lines for the grammar.
+ * @returns the window's runs and its end state, or `undefined` when the language
+ *   is unknown, the range is empty, or the window's own text is too large.
  */
-export declare function highlightLines(code: string, lang: string | undefined): HighlightSpan[][] | undefined;
+export declare function highlightWindow(lines: readonly string[], lang: string | undefined, from: number, to: number, options?: HighlightWindowOptions): HighlightWindow | undefined;