@khorsheed/dsh-file-preview 0.4.1 → 0.4.2

package/lib/index.js

@@ -265,6 +265,48 @@ var BashWriteCollector = class {
 	captured(sessionId) {
 		return this.#captured.get(sessionId);
 	}
+	/**
+	* Rebuild one session's captures from its own event snapshot — the
+	* snapshot-driven twin of the live feed's replay, for a caller that holds
+	* the session's events rather than a composition's event feed. The same
+	* extraction, expansion, and stat-verification pipeline runs in event
+	* order, every verification awaited, so the result mirrors what the live
+	* feed would have captured from the same events. Nothing is stored in the
+	* live registry: pending candidates and verified captures are local to the
+	* call.
+	* @param cwd - the session's cwd for relative write targets, or undefined.
+	* @param events - the session's events in ascending seq order.
+	* @returns the verified captures (undefined when none survived, mirroring
+	*   `captured`).
+	*/
+	async replaySnapshot(cwd, events) {
+		const pending = /* @__PURE__ */ new Map();
+		const captured = /* @__PURE__ */ new Map();
+		for (const event of events) {
+			if (event.type === "tool/call") {
+				if (event.data.name !== "bash") continue;
+				const command = parseArguments(event.data.arguments).command;
+				if (typeof command !== "string" || command.length === 0) continue;
+				const candidates = extractWriteTargets(command).map((token) => expandShellPath(token, this.#env, this.#home, cwd)).filter((path) => path !== null);
+				if (candidates.length === 0) continue;
+				pending.set(String(event.data.callId), {
+					turn: event.data.turn,
+					step: event.data.step,
+					seq: event.seq,
+					candidates
+				});
+				continue;
+			}
+			if (event.type === "tool/result") {
+				const callId = String(event.data.message?.source?.callId ?? "");
+				const write = pending.get(callId);
+				if (write === void 0) continue;
+				pending.delete(callId);
+				await this.#verifyInto(captured, write);
+			}
+		}
+		return captured.size === 0 ? void 0 : captured;
+	}
 	/** Rebuild one session's registry from its own history (host restart). */
 	#replay(session) {
 		this.#pending.set(session.id, /* @__PURE__ */ new Map());
@@ -301,6 +343,11 @@ var BashWriteCollector = class {
 	/** stat-verify the pending candidates and store the survivors. */
 	async #verify(session, pending) {
 		const captured = this.#captured.get(session.id) ?? /* @__PURE__ */ new Map();
+		await this.#verifyInto(captured, pending);
+		if (captured.size > 0) this.#captured.set(session.id, captured);
+	}
+	/** stat-verify the pending candidates into the given capture map. */
+	async #verifyInto(captured, pending) {
 		for (const candidate of pending.candidates) {
 			if (captured.size >= this.#maxFiles || captured.has(candidate)) continue;
 			let ok = false;
@@ -316,7 +363,6 @@ var BashWriteCollector = class {
 				seq: pending.seq
 			});
 		}
-		if (captured.size > 0) this.#captured.set(session.id, captured);
 	}
 };
 //#endregion
@@ -725,6 +771,494 @@ async function openExternalNative(path, appId, signal, internals = {}) {
 	], signal, "visible");
 }
 //#endregion
+//#region lib/types/read-surface.js
+/**
+* The read core and the read-surface factory. The `filePreview` Remote face
+* resolves its `agent` parameter through the host's unified lookup — a lookup
+* that can wake an offline session — so a trusted server-side caller that
+* already holds an authorized session source (its events, its cwd anchor, an
+* fs face) must not reach the data through that wire. This module is the seam:
+* the Remote methods and {@link createFilePreviewReadSurface} run the SAME
+* core functions, so the surface's answers are byte-identical to the Remote
+* face's for the same session by construction.
+*
+* Authorization lives entirely with the caller: the surface reads whatever the
+* injected event reader, anchor, and fs face reach, and performs no admission
+* check of its own. The surface never constructs, resolves, or wakes a session
+* runtime object — it derives everything from the injected source plus pure
+* folds, keeps at most watermark-keyed caches scoped to the returned instance
+* ({@link FilePreviewReadSurface.dispose} drops them), and starts no
+* background work.
+*
+* @module @khorsheed/dsh-file-preview
+*/
+/** Extensions treated as binary without reading (their text decode is meaningless). */
+const BINARY_EXTENSIONS = /* @__PURE__ */ new Set([
+	".pdf",
+	".zip",
+	".gz",
+	".tar",
+	".7z",
+	".zstd",
+	".br",
+	".woff",
+	".woff2",
+	".ttf",
+	".otf",
+	".eot",
+	".wasm",
+	".node",
+	".dylib",
+	".so",
+	".dll",
+	".exe",
+	".kext",
+	".class",
+	".jar",
+	".pyc",
+	".sqlite",
+	".db",
+	".DS_Store",
+	".a",
+	".o"
+]);
+/** Image extensions served to the browser through an image address. */
+const IMAGE_EXTENSIONS = /* @__PURE__ */ new Set([
+	".png",
+	".jpg",
+	".jpeg",
+	".gif",
+	".webp",
+	".avif",
+	".bmp",
+	".ico",
+	".svg"
+]);
+/** MIME type per image extension for a byte read's Content-Type answer. */
+const IMAGE_MIME = {
+	".png": "image/png",
+	".jpg": "image/jpeg",
+	".jpeg": "image/jpeg",
+	".gif": "image/gif",
+	".webp": "image/webp",
+	".avif": "image/avif",
+	".bmp": "image/bmp",
+	".ico": "image/x-icon",
+	".svg": "image/svg+xml"
+};
+/** HTML extensions served through the sandboxed render channel. */
+const HTML_EXTENSIONS = /* @__PURE__ */ new Set([".html", ".htm"]);
+/** NUL bytes in decoded text mark a file as binary despite a successful decode. */
+function hasNulByte(content) {
+	return content.slice(0, 4096).includes("\0");
+}
+/** Shared non-fatal UTF-8 decoder for the bounded byte-window read: invalid
+* sequences become U+FFFD (a cut multi-byte character at the window edge
+* included) instead of failing the read. */
+const utf8Decoder = new TextDecoder();
+/** Detect a binary file from its display path extension. */
+function isBinaryPath(path) {
+	const dot = path.lastIndexOf(".");
+	return dot >= 0 && BINARY_EXTENSIONS.has(path.slice(dot).toLowerCase());
+}
+/** Detect an image from its display path extension. */
+function isImagePath(path) {
+	const dot = path.lastIndexOf(".");
+	return dot >= 0 && IMAGE_EXTENSIONS.has(path.slice(dot).toLowerCase());
+}
+/** Detect an HTML document from its display path extension. */
+function isHtmlPath(path) {
+	const dot = path.lastIndexOf(".");
+	return dot >= 0 && HTML_EXTENSIONS.has(path.slice(dot).toLowerCase());
+}
+/** Best-effort scripted-HTML detection: any `<script>` tag, inline event
+*  handler (`on*="…"`), or `javascript:` URL marks the document as scripted.
+*  Only a hint for default-mode selection and warning — never a trust
+*  decision; the sandbox and the Tier1 CSP are the real boundary. The scan
+*  runs on the read content as delivered (a truncated read may miss markers
+*  in the tail; acceptable for a hint). */
+function isScriptedHtml(content) {
+	return /<\s*script[\s>]/i.test(content) || /\son[a-z]+\s*=/i.test(content) || /javascript:/i.test(content);
+}
+/** Stable error text for a failed read, without leaking backend internals. */
+function readErrorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+/** The fold cache watermark: seq of the last event (`-1` for an empty log). */
+function eventsWatermark(events) {
+	return events.length === 0 ? -1 : events[events.length - 1].seq;
+}
+/** The resolve options for one anchored probe, built field-by-field so an
+*  absent anchor or signal never materializes as an explicit `undefined`
+*  (exactOptionalPropertyTypes). */
+function resolveOptions(cwd, signal) {
+	const options = {};
+	if (cwd !== void 0) options.cwd = cwd;
+	if (signal !== void 0) options.signal = signal;
+	return options;
+}
+/**
+* Resolve the recorded display paths against the anchor and keep only those
+* that currently exist as a regular file. The products surfaces fold the
+* session log (which is history, not disk state): a path the log wrote may
+* have been cleaned up since, and such a path is not a product to list.
+* Existence is checked fresh on every call (never cached), so a deletion that
+* lands after a fold is visible on the next fetch. Unresolvable/unstat-able
+* paths are treated as absent.
+* @param fs - the fs face the probes run through.
+* @param cwd - the anchor relative paths resolve against, or undefined.
+* @param paths - the display paths to probe.
+* @returns the subset that resolves to an existing regular file.
+*/
+async function retainExistingFiles(fs, cwd, paths) {
+	if (paths.length === 0) return /* @__PURE__ */ new Set();
+	const existing = /* @__PURE__ */ new Set();
+	for (const path of paths) {
+		if (existing.has(path)) continue;
+		try {
+			const target = await fs.resolve(path, resolveOptions(cwd, void 0));
+			if ((await fs.stat(target))?.type === "file") existing.add(path);
+		} catch {}
+	}
+	return existing;
+}
+/**
+* The `list` core: the log fold plus any bash-written files the collector
+* verified, merged so a captured path the fold already knows keeps its
+* log-derived entry, then filtered to paths that still exist on disk. This is
+* the exact body the Remote `list` runs.
+* @param core - the fs face, the path anchor, and the entry cap.
+* @param events - the session's events in ascending seq order.
+* @param captured - the collector's verified bash writes, when capture is on.
+* @returns existing first-seen files capped by `maxFiles`, with the log watermark.
+*/
+async function listFilePreview(core, events, captured) {
+	const folded = foldFilePreview(events, core.maxFiles);
+	let entries = folded.entries;
+	if (captured !== void 0 && captured.size > 0) {
+		const seen = new Set(entries.map((entry) => entry.path));
+		const extra = [];
+		for (const [path, write] of captured) {
+			if (seen.has(path) || entries.length + extra.length >= core.maxFiles) continue;
+			extra.push({
+				path,
+				op: "write",
+				seq: write.seq,
+				turn: write.turn,
+				step: write.step,
+				diffs: []
+			});
+		}
+		entries = [...entries, ...extra];
+	}
+	const existing = await retainExistingFiles(core.fs, core.cwd, entries.map((entry) => entry.path));
+	return {
+		entries: entries.filter((entry) => existing.has(entry.path)),
+		asOfSeq: folded.asOfSeq,
+		truncated: folded.truncated || entries.length >= core.maxFiles
+	};
+}
+/**
+* The `turnFiles` core: merge the per-turn fold with the collector's captured
+* writes by their own turn, then filter every group to paths that still exist
+* on disk (fresh per call — the fold cache is by log watermark, existence
+* moves independently). A path touched in two turns appears in BOTH turn
+* groups. This is the exact body the Remote `turnFiles` runs; the caller owns
+* the by-turn fold (and any cache of it) so the watermark discipline sits
+* next to the caller's own cache.
+* @param core - the fs face and the path anchor (`maxFiles` goes unread here).
+* @param asOfSeq - the watermark of the scanned log ({@link eventsWatermark}).
+* @param byTurn - the per-turn fold over the same events.
+* @param captured - the collector's verified bash writes, when capture is on.
+* @returns existing per-turn file groups plus the scanned watermark.
+*/
+async function turnFilesFilePreview(core, asOfSeq, byTurn, captured) {
+	const turns = [];
+	const turnNumbers = new Set(byTurn.keys());
+	if (captured !== void 0) for (const write of captured.values()) turnNumbers.add(write.turn);
+	for (const turn of [...turnNumbers].sort((a, b) => a - b)) {
+		const files = [];
+		const map = byTurn.get(turn);
+		if (map !== void 0) files.push(...map.values());
+		if (captured !== void 0) for (const [path, write] of captured) {
+			if (write.turn !== turn || files.some((file) => file.path === path)) continue;
+			files.push({
+				path,
+				seq: write.seq,
+				step: write.step
+			});
+		}
+		if (files.length === 0) continue;
+		turns.push({
+			turn,
+			files: files.sort((a, b) => a.seq - b.seq)
+		});
+	}
+	const existing = await retainExistingFiles(core.fs, core.cwd, turns.flatMap((group) => group.files.map((file) => file.path)));
+	return {
+		turns: turns.map((group) => ({
+			turn: group.turn,
+			files: group.files.filter((file) => existing.has(file.path))
+		})).filter((group) => group.files.length > 0),
+		asOfSeq
+	};
+}
+/**
+* The `read` core: resolve the recorded display path against the anchor and
+* serve current text content, capped per kind. The text read is a bounded
+* byte window (`readByteRange` of cap + 1 bytes), so an oversized file costs
+* the cap, never its full size; a known oversized stat still short-circuits
+* to `too-large` before any bytes move. This is the exact body the Remote
+* `read` runs.
+* @param core - the fs face, the path anchor, the caps, and the image issuer.
+* @param path - the display path recorded by the write/edit tool call.
+* @param signal - cooperative cancellation from the calling request.
+* @returns the classified read; `text` carries content, `image` carries the
+*   issued URL, other kinds carry the size or a human-readable reason.
+*/
+async function readFilePreview(core, path, signal) {
+	if (typeof path !== "string" || path.length === 0) return {
+		path,
+		kind: "error",
+		message: "file preview requires a non-empty path"
+	};
+	let target;
+	try {
+		target = await core.fs.resolve(path, resolveOptions(core.cwd, signal));
+	} catch (error) {
+		return {
+			path,
+			kind: "error",
+			message: readErrorMessage(error)
+		};
+	}
+	let info;
+	try {
+		info = await core.fs.stat(target, signal);
+	} catch (error) {
+		return {
+			path,
+			kind: "error",
+			message: readErrorMessage(error)
+		};
+	}
+	if (info === void 0 || info.type !== "file") return {
+		path,
+		kind: "missing"
+	};
+	const html = isHtmlPath(path);
+	const cap = html ? core.htmlMaxReadBytes : core.maxReadBytes;
+	if (info.size !== void 0 && info.size > cap) return {
+		path,
+		kind: "too-large",
+		size: info.size
+	};
+	if (isImagePath(path)) {
+		const url = core.imageUrl?.(path);
+		if (url !== void 0) return {
+			path,
+			kind: "image",
+			url,
+			...info.size === void 0 ? {} : { size: info.size }
+		};
+		return {
+			path,
+			kind: "binary",
+			...info.size === void 0 ? {} : { size: info.size }
+		};
+	}
+	if (isBinaryPath(path)) return {
+		path,
+		kind: "binary",
+		...info.size === void 0 ? {} : { size: info.size }
+	};
+	try {
+		const bytes = await core.fs.readByteRange(target, {
+			offset: 0,
+			length: cap + 1
+		}, signal);
+		const truncated = bytes.length > cap;
+		const content = utf8Decoder.decode(truncated ? bytes.subarray(0, cap) : bytes);
+		if (hasNulByte(content)) return {
+			path,
+			kind: "binary",
+			...info.size === void 0 ? {} : { size: info.size }
+		};
+		return {
+			path,
+			kind: "text",
+			content,
+			truncated,
+			...html && isScriptedHtml(content) ? { htmlScripted: true } : {},
+			...info.size === void 0 ? {} : { size: info.size }
+		};
+	} catch (error) {
+		return {
+			path,
+			kind: "error",
+			message: readErrorMessage(error)
+		};
+	}
+}
+/**
+* The authorized image byte read: the same resolution, anchor, containment,
+* and caps as {@link readFilePreview}, returning the bytes themselves instead
+* of an address — the consuming side serves them through its own
+* authenticated channel. The failure taxonomy mirrors `read` (`missing`,
+* `too-large`, `error`) plus `not-image` for a path without an image
+* extension.
+* @param core - the fs face, the path anchor, and the byte cap.
+* @param path - the display path recorded by the session.
+* @param signal - cooperative cancellation from the calling request.
+* @returns the bytes and MIME type, or the classified failure.
+*/
+async function readFilePreviewImageBytes(core, path, signal) {
+	if (typeof path !== "string" || path.length === 0) return {
+		path,
+		ok: false,
+		reason: "error",
+		message: "file preview requires a non-empty path"
+	};
+	if (!isImagePath(path)) return {
+		path,
+		ok: false,
+		reason: "not-image"
+	};
+	let target;
+	try {
+		target = await core.fs.resolve(path, resolveOptions(core.cwd, signal));
+	} catch (error) {
+		return {
+			path,
+			ok: false,
+			reason: "error",
+			message: readErrorMessage(error)
+		};
+	}
+	let info;
+	try {
+		info = await core.fs.stat(target, signal);
+	} catch (error) {
+		return {
+			path,
+			ok: false,
+			reason: "error",
+			message: readErrorMessage(error)
+		};
+	}
+	if (info === void 0 || info.type !== "file") return {
+		path,
+		ok: false,
+		reason: "missing"
+	};
+	if (info.size !== void 0 && info.size > core.maxReadBytes) return {
+		path,
+		ok: false,
+		reason: "too-large",
+		size: info.size
+	};
+	try {
+		const bytes = await core.fs.readBytes(target, signal, core.maxReadBytes);
+		const dot = path.lastIndexOf(".");
+		return {
+			path,
+			ok: true,
+			mime: IMAGE_MIME[path.slice(dot).toLowerCase()] ?? "application/octet-stream",
+			bytes,
+			...info.size === void 0 ? {} : { size: info.size }
+		};
+	} catch (error) {
+		return {
+			path,
+			ok: false,
+			reason: "error",
+			message: readErrorMessage(error)
+		};
+	}
+}
+/**
+* Build a read-only file-preview surface over an externally-authorized
+* session source. The surface runs the same core functions the Remote methods
+* run, so for the same session its answers are byte-identical to the Remote
+* face's — the bash-write merge included, rebuilt from the same events
+* through the same collector pipeline. The factory itself holds no state: the
+* caches live in the returned instance and die with {@link FilePreviewReadSurface.dispose}.
+* @param source - the caller-authorized events, anchor, fs face, and issuer.
+* @returns the read surface.
+*/
+function createFilePreviewReadSurface(source) {
+	const resolved = {
+		maxReadBytes: source.maxReadBytes ?? 524288,
+		htmlMaxReadBytes: source.htmlMaxReadBytes ?? 4194304,
+		maxFiles: source.maxFiles ?? 500
+	};
+	const cwd = source.cwd;
+	const collector = source.captureBashWrites === false ? void 0 : new BashWriteCollector({
+		fs: source.fs,
+		maxFiles: resolved.maxFiles
+	});
+	/** Derived caches keyed by the log watermark; `dispose` drops both. */
+	let turnCache;
+	let captureCache;
+	/** The verified bash-write captures for the current watermark (replayed on change). */
+	const capturedAt = async (events, asOfSeq) => {
+		if (collector === void 0) return void 0;
+		if (captureCache !== void 0 && captureCache.asOfSeq === asOfSeq) return captureCache.captured;
+		const captured = await collector.replaySnapshot(cwd, events);
+		captureCache = {
+			asOfSeq,
+			captured
+		};
+		return captured;
+	};
+	return {
+		list: async () => {
+			const events = source.events();
+			const captured = await capturedAt(events, eventsWatermark(events));
+			return listFilePreview({
+				fs: source.fs,
+				cwd,
+				maxFiles: resolved.maxFiles
+			}, events, captured);
+		},
+		turnFiles: async () => {
+			const events = source.events();
+			const asOfSeq = eventsWatermark(events);
+			let byTurn;
+			if (turnCache !== void 0 && turnCache.asOfSeq === asOfSeq) byTurn = turnCache.byTurn;
+			else {
+				byTurn = foldFilePreviewByTurn(events);
+				turnCache = {
+					asOfSeq,
+					byTurn
+				};
+			}
+			const captured = await capturedAt(events, asOfSeq);
+			return turnFilesFilePreview({
+				fs: source.fs,
+				cwd,
+				maxFiles: resolved.maxFiles
+			}, asOfSeq, byTurn, captured);
+		},
+		read: (path, signal) => readFilePreview({
+			fs: source.fs,
+			cwd,
+			maxReadBytes: resolved.maxReadBytes,
+			htmlMaxReadBytes: resolved.htmlMaxReadBytes,
+			imageUrl: source.imageUrl
+		}, path, signal),
+		readImageBytes: (path, signal) => readFilePreviewImageBytes({
+			fs: source.fs,
+			cwd,
+			maxReadBytes: resolved.maxReadBytes
+		}, path, signal),
+		dispose: () => {
+			turnCache = void 0;
+			captureCache = void 0;
+		}
+	};
+}
+//#endregion
 //#region lib/types/reveal.js
 /**
 * Cross-platform native "show in folder, selecting the file" dispatch used by
@@ -842,98 +1376,6 @@ var __esDecorate = function(ctor, descriptorIn, decorators, contextIn, initializ
 	if (target) Object.defineProperty(target, contextIn.name, descriptor);
 	done = true;
 };
-/** Extensions treated as binary without reading (their text decode is meaningless). */
-const BINARY_EXTENSIONS = /* @__PURE__ */ new Set([
-	".pdf",
-	".zip",
-	".gz",
-	".tar",
-	".7z",
-	".zstd",
-	".br",
-	".woff",
-	".woff2",
-	".ttf",
-	".otf",
-	".eot",
-	".wasm",
-	".node",
-	".dylib",
-	".so",
-	".dll",
-	".exe",
-	".kext",
-	".class",
-	".jar",
-	".pyc",
-	".sqlite",
-	".db",
-	".DS_Store",
-	".a",
-	".o"
-]);
-/** Image extensions served to the browser through the image route. */
-const IMAGE_EXTENSIONS = /* @__PURE__ */ new Set([
-	".png",
-	".jpg",
-	".jpeg",
-	".gif",
-	".webp",
-	".avif",
-	".bmp",
-	".ico",
-	".svg"
-]);
-/** MIME type per image extension for the image route's Content-Type header. */
-const IMAGE_MIME = {
-	".png": "image/png",
-	".jpg": "image/jpeg",
-	".jpeg": "image/jpeg",
-	".gif": "image/gif",
-	".webp": "image/webp",
-	".avif": "image/avif",
-	".bmp": "image/bmp",
-	".ico": "image/x-icon",
-	".svg": "image/svg+xml"
-};
-/** NUL bytes in decoded text mark a file as binary despite a successful decode. */
-function hasNulByte(content) {
-	return content.slice(0, 4096).includes("\0");
-}
-/** Shared non-fatal UTF-8 decoder for the bounded byte-window read: invalid
-* sequences become U+FFFD (a cut multi-byte character at the window edge
-* included) instead of failing the read. */
-const utf8Decoder = new TextDecoder();
-/** Detect a binary file from its display path extension. */
-function isBinaryPath(path) {
-	const dot = path.lastIndexOf(".");
-	return dot >= 0 && BINARY_EXTENSIONS.has(path.slice(dot).toLowerCase());
-}
-/** Detect an image from its display path extension. */
-function isImagePath(path) {
-	const dot = path.lastIndexOf(".");
-	return dot >= 0 && IMAGE_EXTENSIONS.has(path.slice(dot).toLowerCase());
-}
-/** HTML extensions served through the sandboxed render channel. */
-const HTML_EXTENSIONS = /* @__PURE__ */ new Set([".html", ".htm"]);
-/** Detect an HTML document from its display path extension. */
-function isHtmlPath(path) {
-	const dot = path.lastIndexOf(".");
-	return dot >= 0 && HTML_EXTENSIONS.has(path.slice(dot).toLowerCase());
-}
-/** Best-effort scripted-HTML detection: any `<script>` tag, inline event
-*  handler (`on*="…"`), or `javascript:` URL marks the document as scripted.
-*  Only a hint for default-mode selection and warning — never a trust
-*  decision; the sandbox and the Tier1 CSP are the real boundary. The scan
-*  runs on the read content as delivered (a truncated read may miss markers
-*  in the tail; acceptable for a hint). */
-function isScriptedHtml(content) {
-	return /<\s*script[\s>]/i.test(content) || /\son[a-z]+\s*=/i.test(content) || /javascript:/i.test(content);
-}
-/** Stable error text for a failed read, without leaking backend internals. */
-function readErrorMessage(error) {
-	return error instanceof Error ? error.message : String(error);
-}
 /**
 * The `filePreview` Remote service: session-scoped read-only file inspection
 * for web surfaces. `list` is a fold over the session log, then filtered to the
@@ -1044,10 +1486,9 @@ let FilePreviewService = (() => {
 		/** URL prefix the image route answers under. */
 		static IMAGE_ROUTE = "/file-preview-image";
 		resolved = __runInitializers(this, _instanceExtraInitializers);
-		/** Whether a web server is present to host the image route; image reads
-		* answer `binary` without it (the headless face has no browser to serve). */
-		imageRoute;
-		/** The agents service when present (image route only; null headless). */
+		/** The agents service while the image route is registered; undefined
+		* otherwise (headless faces, or before `webServer`/`agents` arrive), and
+		* image reads then answer `binary` (no browser to serve). */
 		agents;
 		/** Native reveal runner; a constructor seam for deterministic tests. */
 		revealNative;
@@ -1059,7 +1500,8 @@ let FilePreviewService = (() => {
 		turnCache = /* @__PURE__ */ new Map();
 		/**
 		* @param ctx - owning Cordis Context carrying `fs`; `webServer` and `agents`
-		*   are optional (the image route needs them, headless faces lack both).
+		*   are optional (the image route registers whenever both are up, headless
+		*   faces lack both).
 		* @param config - optional deployment tuning; defaults cap reads and lists,
 		*   and enable the bash-write collector.
 		* @param deps - test seam for the native reveal dispatch.
@@ -1081,19 +1523,27 @@ let FilePreviewService = (() => {
 				});
 				ctx.effect(() => this.collector.attach(ctx), "file-preview: bash-write capture");
 			} else this.collector = void 0;
-			const webServer = ctx.get("webServer");
-			this.agents = ctx.get("agents");
-			this.imageRoute = webServer !== void 0 && this.agents !== void 0;
-			if (this.imageRoute && webServer !== void 0) ctx.effect(() => webServer.register({
-				kind: "prefix",
-				path: FilePreviewService.IMAGE_ROUTE,
-				/* v8 ignore next 2 -- the handler body is the request path; the
-				unit tests drive serveImage directly, the real server reaches it
-				through this registration */
-				handler: (req, res) => {
-					this.serveImage(req, res);
-				}
-			}), "file-preview: image route");
+			ctx.inject(["webServer", "agents"], (routeCtx) => {
+				const webServer = routeCtx.get("webServer");
+				const agents = routeCtx.get("agents");
+				routeCtx.effect(() => {
+					const unregister = webServer.register({
+						kind: "prefix",
+						path: FilePreviewService.IMAGE_ROUTE,
+						/* v8 ignore next 2 -- the handler body is the request path; the
+						unit tests drive serveImage directly, the real server reaches it
+						through this registration */
+						handler: (req, res) => {
+							this.serveImage(req, res);
+						}
+					});
+					this.agents = agents;
+					return () => {
+						this.agents = void 0;
+						unregister();
+					};
+				}, "file-preview: image route");
+			});
 		}
 		/** Zero-session availability handshake for browser companions. */
 		capabilities() {
@@ -1173,30 +1623,6 @@ let FilePreviewService = (() => {
 			});
 			res.end(Buffer.from(bytes));
 		}
-		/** Resolve the session's recorded display paths against its cwd and keep only
-		*  those that currently exist as a regular file. The products surfaces fold
-		*  the session log (which is history, not disk state): a path the log wrote
-		*  may have been cleaned up since (a temp script the turn deleted), and such
-		*  a path is not a product to list. Existence is checked fresh on every call
-		*  (never cached), so a deletion that lands after a fold is visible on the
-		*  next fetch. Unresolvable/unstat-able paths are treated as absent.
-		* @param agent - owning live agent; its session cwd anchors relative paths.
-		* @param paths - the display paths to probe.
-		* @returns the subset that resolves to an existing regular file.
-		*/
-		async retainExisting(agent, paths) {
-			if (paths.length === 0) return /* @__PURE__ */ new Set();
-			const cwd = agent.session.header.cwd;
-			const existing = /* @__PURE__ */ new Set();
-			for (const path of paths) {
-				if (existing.has(path)) continue;
-				try {
-					const target = await this.fs.resolve(path, cwd === void 0 ? {} : { cwd });
-					if ((await this.fs.stat(target))?.type === "file") existing.add(path);
-				} catch {}
-			}
-			return existing;
-		}
 		/**
 		* List the files one session wrote or edited: the log fold plus any
 		* bash-written files the collector verified (the S2 seam), merged so a
@@ -1207,31 +1633,11 @@ let FilePreviewService = (() => {
 		* @returns existing first-seen files capped by `maxFiles`, with the log watermark.
 		*/
 		async list(agent) {
-			const folded = foldFilePreview(agent.session.snapshotEvents(), this.resolved.maxFiles);
-			const captured = this.collector?.captured(agent.session.id);
-			let entries = folded.entries;
-			if (captured !== void 0 && captured.size > 0) {
-				const seen = new Set(entries.map((entry) => entry.path));
-				const extra = [];
-				for (const [path, write] of captured) {
-					if (seen.has(path) || entries.length + extra.length >= this.resolved.maxFiles) continue;
-					extra.push({
-						path,
-						op: "write",
-						seq: write.seq,
-						turn: write.turn,
-						step: write.step,
-						diffs: []
-					});
-				}
-				entries = [...entries, ...extra];
-			}
-			const existing = await this.retainExisting(agent, entries.map((entry) => entry.path));
-			return {
-				entries: entries.filter((entry) => existing.has(entry.path)),
-				asOfSeq: folded.asOfSeq,
-				truncated: folded.truncated || entries.length >= this.resolved.maxFiles
-			};
+			return listFilePreview({
+				fs: this.fs,
+				cwd: agent.session.header?.cwd,
+				maxFiles: this.resolved.maxFiles
+			}, agent.session.snapshotEvents(), this.collector?.captured(agent.session.id));
 		}
 		/**
 		* Every turn's file mutations for the turn-tail card — the single source of
@@ -1251,7 +1657,7 @@ let FilePreviewService = (() => {
 		async turnFiles(agent) {
 			const session = agent.session;
 			const events = session.snapshotEvents();
-			const asOfSeq = events.length === 0 ? -1 : events[events.length - 1].seq;
+			const asOfSeq = eventsWatermark(events);
 			const cached = this.turnCache.get(session.id);
 			let byTurn;
 			if (cached === void 0 || cached.asOfSeq !== asOfSeq) {
@@ -1261,36 +1667,11 @@ let FilePreviewService = (() => {
 					byTurn
 				});
 			} else byTurn = cached.byTurn;
-			const captured = this.collector?.captured(session.id);
-			const turns = [];
-			const turnNumbers = new Set(byTurn.keys());
-			if (captured !== void 0) for (const write of captured.values()) turnNumbers.add(write.turn);
-			for (const turn of [...turnNumbers].sort((a, b) => a - b)) {
-				const files = [];
-				const map = byTurn.get(turn);
-				if (map !== void 0) files.push(...map.values());
-				if (captured !== void 0) for (const [path, write] of captured) {
-					if (write.turn !== turn || files.some((file) => file.path === path)) continue;
-					files.push({
-						path,
-						seq: write.seq,
-						step: write.step
-					});
-				}
-				if (files.length === 0) continue;
-				turns.push({
-					turn,
-					files: files.sort((a, b) => a.seq - b.seq)
-				});
-			}
-			const existing = await this.retainExisting(agent, turns.flatMap((group) => group.files.map((file) => file.path)));
-			return {
-				turns: turns.map((group) => ({
-					turn: group.turn,
-					files: group.files.filter((file) => existing.has(file.path))
-				})).filter((group) => group.files.length > 0),
-				asOfSeq
-			};
+			return turnFilesFilePreview({
+				fs: this.fs,
+				cwd: session.header?.cwd,
+				maxFiles: this.resolved.maxFiles
+			}, asOfSeq, byTurn, this.collector?.captured(session.id));
 		}
 		/**
 		* Read the current content of one recorded file, resolved against the
@@ -1305,94 +1686,14 @@ let FilePreviewService = (() => {
 		*   browser URL, other kinds carry the size or a human-readable reason.
 		*/
 		async read(agent, path, signal) {
-			if (typeof path !== "string" || path.length === 0) return {
-				path,
-				kind: "error",
-				message: "file preview requires a non-empty path"
-			};
-			const cwd = agent.session.header.cwd;
-			let target;
-			try {
-				target = await this.fs.resolve(path, cwd === void 0 ? { signal } : {
-					cwd,
-					signal
-				});
-			} catch (error) {
-				return {
-					path,
-					kind: "error",
-					message: readErrorMessage(error)
-				};
-			}
-			let info;
-			try {
-				info = await this.fs.stat(target, signal);
-			} catch (error) {
-				return {
-					path,
-					kind: "error",
-					message: readErrorMessage(error)
-				};
-			}
-			if (info === void 0 || info.type !== "file") return {
-				path,
-				kind: "missing"
-			};
-			const html = isHtmlPath(path);
-			const cap = html ? this.resolved.htmlMaxReadBytes : this.resolved.maxReadBytes;
-			if (info.size !== void 0 && info.size > cap) return {
-				path,
-				kind: "too-large",
-				size: info.size
-			};
-			if (isImagePath(path)) {
-				if (this.imageRoute) {
-					const encoded = encodeURIComponent(path);
-					return {
-						path,
-						kind: "image",
-						url: `${FilePreviewService.IMAGE_ROUTE}/${agent.session.id}/${encoded}`,
-						...info.size === void 0 ? {} : { size: info.size }
-					};
-				}
-				return {
-					path,
-					kind: "binary",
-					...info.size === void 0 ? {} : { size: info.size }
-				};
-			}
-			if (isBinaryPath(path)) return {
-				path,
-				kind: "binary",
-				...info.size === void 0 ? {} : { size: info.size }
-			};
-			try {
-				const bytes = await this.fs.readByteRange(target, {
-					offset: 0,
-					length: cap + 1
-				}, signal);
-				const truncated = bytes.length > cap;
-				const content = utf8Decoder.decode(truncated ? bytes.subarray(0, cap) : bytes);
-				if (hasNulByte(content)) return {
-					path,
-					kind: "binary",
-					...info.size === void 0 ? {} : { size: info.size }
-				};
-				return {
-					path,
-					kind: "text",
-					content,
-					truncated,
-					...html && isScriptedHtml(content) ? { htmlScripted: true } : {},
-					...info.size === void 0 ? {} : { size: info.size }
-				};
-			} catch (error) {
-				return {
-					path,
-					kind: "error",
-					message: readErrorMessage(error)
-				};
-			}
+			const session = agent.session;
+			return readFilePreview({
+				fs: this.fs,
+				cwd: session.header.cwd,
+				maxReadBytes: this.resolved.maxReadBytes,
+				htmlMaxReadBytes: this.resolved.htmlMaxReadBytes,
+				imageUrl: this.agents !== void 0 ? (display) => `${FilePreviewService.IMAGE_ROUTE}/${session.id}/${encodeURIComponent(display)}` : void 0
+			}, path, signal);
 		}
 		/**
 		* Reveal one recorded file in the host file manager — open its folder and
@@ -1505,4 +1806,4 @@ let FilePreviewService = (() => {
 	};
 })();
 //#endregion
-export { FilePreviewService, FilePreviewService as default };
+export { FilePreviewService, FilePreviewService as default, createFilePreviewReadSurface };