@spzxg/cli-ui 0.6.5 → 0.6.7

package/src/board/fileOps.ts

@@ -2,6 +2,8 @@
 // 看板、文件预览和给业务方的工作区接口（workspace.ts）共用。
 import { fileUrlFromBase, type BoardBackend } from "../core/client";
 import { extOf, fmtSize } from "./fileKind";
+import { syncFile } from "./fileSync";
+import { isOriginalDocument, isTaskUploadPath } from "../core/documentUpload";
 
 /** 只能先 fetch 成 blob 时（中枢太旧）：超过这么大的不在浏览器里拼下载。 */
 const BLOB_DOWNLOAD_MAX = 300 * 1024 * 1024;
@@ -9,7 +11,7 @@ const BLOB_DOWNLOAD_MAX = 300 * 1024 * 1024;
 export const MIME: Record<string, string> = {
   png: "image/png", jpg: "image/jpeg", jpeg: "image/jpeg", gif: "image/gif", webp: "image/webp", svg: "image/svg+xml",
   bmp: "image/bmp", ico: "image/x-icon", avif: "image/avif", pdf: "application/pdf", html: "text/html", htm: "text/html",
-  md: "text/markdown", txt: "text/plain", csv: "text/csv", json: "application/json", zip: "application/zip",
+  md: "text/markdown", markdown: "text/markdown", txt: "text/plain", csv: "text/csv", json: "application/json", zip: "application/zip",
   docx: "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
   xlsx: "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
   pptx: "application/vnd.openxmlformats-officedocument.presentationml.presentation",
@@ -70,7 +72,12 @@ function clickDownload(href: string, name: string) {
  * 只有中枢太旧时才 fetch 成 blob 再存（太大的拒绝，免得撑爆浏览器内存）。
  */
 export async function downloadFile(backend: BoardBackend, jobId: string, path: string, size?: number) {
-  const name = path.split("/").pop() || "file";
+  let name = path.split("/").pop() || "file";
+  if (backend.fileSync && (isOriginalDocument(path) || isTaskUploadPath(path))) {
+    const info = await backend.stat(jobId, path); if (info.type === "file" && info.name) name = info.name;
+    const result = await syncFile(backend.fileSync, jobId, path, { decode: false });
+    saveBlob(new Blob([result.bytes], { type: mimeOf(path) }), name); return;
+  }
   const url = await directFileUrl(backend, jobId, path, true);
   if (url) { clickDownload(url, name); return; }
   if (size !== undefined && size > BLOB_DOWNLOAD_MAX) throw new Error(`文件较大（${fmtSize(size)}），当前接入方式不能在浏览器里下载，请升级任务中心`);

package/src/board/fileScope.ts

@@ -0,0 +1,29 @@
+import type { BoardBackend } from "../core/client";
+
+type Scope = { paths: string[]; dirs: string[]; onDenied?: () => void };
+const scopes = new WeakMap<BoardBackend, Map<string, Map<object, Scope>>>();
+const listeners = new WeakMap<BoardBackend, Map<string, Set<() => void>>>();
+/** A preview/list owns its subscription. Unmounted/closed directories are not polled. */
+export function retainFileScope(backend: BoardBackend, jobId: string, scope: Scope): () => void {
+  let jobs = scopes.get(backend); if (!jobs) { jobs = new Map(); scopes.set(backend, jobs); }
+  let owners = jobs.get(jobId); if (!owners) { owners = new Map(); jobs.set(jobId, owners); }
+  const owner = {}; owners.set(owner, scope);
+  const notify = () => listeners.get(backend)?.get(jobId)?.forEach(fn => fn());
+  notify();
+  let active = true;
+  return () => { if (!active) return; active = false; owners!.delete(owner); if (!owners!.size && jobs!.get(jobId) === owners) jobs!.delete(jobId); notify(); };
+}
+export function readFileScope(backend: BoardBackend, jobId: string): Scope {
+  const active = [...(scopes.get(backend)?.get(jobId)?.values() ?? [])];
+  return { paths: [...new Set(active.flatMap(scope => scope.paths))].sort(), dirs: [...new Set(active.flatMap(scope => scope.dirs))].sort() };
+}
+export function denyFileScope(backend: BoardBackend, jobId: string) {
+  for (const scope of scopes.get(backend)?.get(jobId)?.values() ?? []) scope.onDenied?.();
+}
+export function onFileScope(backend: BoardBackend, jobId: string, listener: () => void) {
+  let jobs = listeners.get(backend); if (!jobs) { jobs = new Map(); listeners.set(backend, jobs); }
+  let set = jobs.get(jobId); if (!set) { set = new Set(); jobs.set(jobId, set); }
+  set.add(listener);
+  let active = true;
+  return () => { if (!active) return; active = false; set!.delete(listener); if (!set!.size && jobs!.get(jobId) === set) jobs!.delete(jobId); };
+}

package/src/board/fileSync.ts

@@ -0,0 +1,343 @@
+import { notifyCallback } from "../core/callbacks";
+import { FileSyncCache, fileSyncScopeKey, type FileSyncScope } from "./fileSyncCache";
+import { FileSyncProcessor } from "./fileSyncProcessor";
+import { createFileWorkQueue } from "./fileSyncQueue";
+
+export const FILE_SYNC_MAX = 100 * 1024 * 1024;
+export interface FileSyncManifest { protocol: 1; namespace: string; revision: string; size: number; hash: string; chunks: { id: string; size: number }[] }
+export interface FileSyncTransport {
+  /** null means 304 after the transport checked the authenticated namespace. */
+  manifest(jobId: string, path: string, options?: { signal?: AbortSignal; revision?: string }): Promise<FileSyncManifest | null>;
+  chunks(jobId: string, input: { path: string; revision: string; ids: string[] }, options?: { signal?: AbortSignal }): Promise<Uint8Array<ArrayBuffer>>;
+}
+export class FileSyncError extends Error {
+  constructor(message: string, readonly status: number, readonly code: string, readonly retryAfterMs?: number) { super(message); this.name = "FileSyncError"; }
+}
+export interface FileSyncProgress { phase: "manifest" | "chunks" | "verify"; loadedBytes: number; totalBytes: number; downloadedBytes: number; reusedBytes: number }
+export interface FileSyncOptions { signal?: AbortSignal; onProgress?: (progress: FileSyncProgress) => void; decode?: boolean; range?: { start?: number; maxBytes: number; tail?: boolean }; pendingTimeoutMs?: number; /** Require a manifest request started after this explicit refresh. */ fresh?: boolean; /** Remember only successfully viewed ranges, never downloads. */ preview?: boolean }
+export interface FilePreviewRefresh { changed: string[]; error?: Error }
+export interface SyncedFile {
+  readonly bytes: Uint8Array<ArrayBuffer>;
+  revision: string; namespace: string; hash: string; size: number; start: number; end: number; truncated: boolean;
+  text?: string; encoding?: string; downloadedBytes: number; reusedBytes: number; cacheMode: "persistent" | "session";
+}
+const hex = /^[a-f0-9]{64}$/;
+export function validateFileSyncManifest(value: unknown): FileSyncManifest {
+  const m = value as FileSyncManifest;
+  if (!m || m.protocol !== 1 || typeof m.namespace !== "string" || !m.namespace || m.namespace.length > 1024 || typeof m.revision !== "string" || typeof m.hash !== "string" || !hex.test(m.revision) || !hex.test(m.hash)
+    || !Number.isSafeInteger(m.size) || m.size < 0 || m.size > FILE_SYNC_MAX || !Array.isArray(m.chunks) || m.chunks.length > 10000) throw new FileSyncError("文件修订清单无效或超过100MiB", 502, "invalid_manifest");
+  let total = 0; const sizes = new Map<string, number>();
+  for (const chunk of m.chunks) {
+    if (!chunk || typeof chunk.id !== "string" || !hex.test(chunk.id) || !Number.isSafeInteger(chunk.size) || chunk.size <= 0 || chunk.size > 256 * 1024 || (sizes.has(chunk.id) && sizes.get(chunk.id) !== chunk.size)) throw new FileSyncError("文件分块清单无效", 502, "invalid_manifest");
+    total += chunk.size; sizes.set(chunk.id, chunk.size);
+  }
+  if (total !== m.size) throw new FileSyncError("文件分块长度与清单不一致", 502, "invalid_manifest");
+  return { protocol: 1, namespace: m.namespace, revision: m.revision, size: m.size, hash: m.hash, chunks: m.chunks.map(chunk => ({ id: chunk.id, size: chunk.size })) };
+}
+const aborted = () => new DOMException("文件同步已取消", "AbortError");
+const check = (signal: AbortSignal) => { if (signal.aborted) throw aborted(); };
+function untilCancelled<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T> {
+  if (!signal) return promise;
+  if (signal.aborted) return Promise.reject(aborted());
+  return new Promise((resolve, reject) => {
+    const cancel = () => { signal.removeEventListener("abort", cancel); reject(aborted()); };
+    signal.addEventListener("abort", cancel, { once: true });
+    promise.then(value => { signal.removeEventListener("abort", cancel); resolve(value); }, error => { signal.removeEventListener("abort", cancel); reject(error); });
+    if (signal.aborted) cancel();
+  });
+}
+const statusOf = (error: unknown) => error && typeof error === "object" && "status" in error ? Number(error.status) : 0;
+async function retryPending<T>(work: () => Promise<T>, signal: AbortSignal, timeoutMs = 180_000): Promise<T> {
+  const deadline = Date.now() + (Number.isFinite(timeoutMs) && timeoutMs >= 0 ? Math.min(timeoutMs, 180_000) : 180_000);
+  let pending = 0, failures = 0;
+  for (;;) {
+    check(signal);
+    try { return await work(); } catch (error) {
+      check(signal);
+      const status = statusOf(error), code = (error as FileSyncError)?.code;
+      const permanent = error instanceof Error && error.name === "AbortError"
+        || ["client_queue_full", "client_queue_timeout", "integrity", "invalid_manifest", "invalid_response", "response_too_large", "unsupported", "file_sync_unsupported"].includes(code);
+      const retryable = !status || status === 408 || status === 429 || status === 500 || status === 502 || status === 503 || status === 504;
+      if (permanent || (status !== 202 && (!retryable || ++failures > 3)) || Date.now() >= deadline) throw error;
+      const backoff = Math.min(8000, 500 * 2 ** (status === 202 ? pending++ : failures - 1));
+      const hint = Number((error as FileSyncError)?.retryAfterMs ?? (status === 202 ? 1000 : 0));
+      // Retry-After is a lower bound. Jitter spreads a burst without retrying before the server is ready.
+      const delay = Math.max(Number.isFinite(hint) && hint > 0 ? hint : 0, backoff) + Math.random() * Math.min(1000, backoff * .25);
+      if (delay > deadline - Date.now()) throw error;
+      await new Promise<void>((resolve, reject) => {
+        const cancel = () => { clearTimeout(timer); reject(aborted()); };
+        const timer = setTimeout(() => { signal.removeEventListener("abort", cancel); resolve(); }, delay);
+        signal.addEventListener("abort", cancel, { once: true });
+        if (signal.aborted) cancel();
+      });
+    }
+  }
+}
+type Shared<T> = { controller: AbortController; promise: Promise<T>; consumers: Set<object>; progress: Map<object, (value: FileSyncProgress) => void> };
+function lease<T>(map: Map<string, Shared<T>>, key: string, work: (signal: AbortSignal, notify: (value: FileSyncProgress) => void) => Promise<T>, signal?: AbortSignal, progress?: (value: FileSyncProgress) => void): Promise<T> {
+  if (signal?.aborted) return Promise.reject(aborted());
+  let entry = map.get(key);
+  if (!entry) {
+    const controller = new AbortController();
+    const created = { controller, consumers: new Set<object>(), progress: new Map<object, (value: FileSyncProgress) => void>(), promise: null! as Promise<T> };
+    created.promise = Promise.resolve().then(() => work(controller.signal, value => { for (const callback of [...created.progress.values()]) notifyCallback(callback, value); })).finally(() => { if (map.get(key) === created) map.delete(key); });
+    void created.promise.catch(() => undefined); map.set(key, created); entry = created;
+  }
+  const owned = entry, consumer = {}; owned.consumers.add(consumer); if (progress) owned.progress.set(consumer, progress);
+  return new Promise<T>((resolve, reject) => {
+    let active = true;
+    const release = () => { active = false; signal?.removeEventListener("abort", cancel); owned.consumers.delete(consumer); owned.progress.delete(consumer); };
+    const cancel = () => { if (!active) return; release(); reject(aborted()); if (!owned.consumers.size) { owned.controller.abort(); if (map.get(key) === owned) map.delete(key); } };
+    signal?.addEventListener("abort", cancel, { once: true });
+    owned.promise.then(value => { if (active) { release(); resolve(value); } }, error => { if (active) { release(); reject(error); } });
+    if (signal?.aborted) cancel();
+  });
+}
+
+/** Per-transport coordinator: every caller authorizes a manifest before any cached bytes are read. */
+export function createFileSynchronizer(transport: FileSyncTransport, cache = new FileSyncCache()) {
+  const last = new Map<string, FileSyncManifest>(), manifests = new Map<string, Shared<FileSyncManifest>>(), files = new Map<string, Shared<SyncedFile>>(), chunks = new Map<string, Shared<Uint8Array<ArrayBuffer>>>();
+  type Preview = { namespace: string; revision: string; range?: FileSyncOptions["range"]; stale?: boolean };
+  const previews = new Map<string, Preview>(), previewReads = new Map<string, object>(), previewListeners = new Map<string, Set<() => void>>();
+  const manifestQueue = createFileWorkQueue(3), chunkQueue = createFileWorkQueue(3);
+  const assemblyQueue = createFileWorkQueue(2), refreshQueue = createFileWorkQueue(1);
+  const retireNamespace = (namespace: string) => {
+    for (const entries of [files, chunks]) for (const [key, entry] of entries) if (JSON.parse(JSON.parse(key)[0])[0] === namespace) { entry.controller.abort(); entries.delete(key); }
+  };
+  const retireFile = (scope: FileSyncScope) => {
+    const identity = fileSyncScopeKey(scope);
+    for (const entries of [files, chunks]) for (const [key, entry] of entries) if (JSON.parse(key)[0] === identity) { entry.controller.abort(); entries.delete(key); }
+  };
+  type QueuedChunk = { identity: string; jobId: string; path: string; revision: string; id: string; size: number; signal: AbortSignal; timeout?: number; resolve: (bytes: Uint8Array<ArrayBuffer>) => void; reject: (error: unknown) => void };
+  let queued: QueuedChunk[] = [], flushTimer: ReturnType<typeof setTimeout> | undefined;
+  const flush = () => {
+    flushTimer = undefined; const pending = queued; queued = [];
+    while (pending.length) {
+      const first = pending.shift()!;
+      if (first.signal.aborted) { first.reject(aborted()); continue; }
+      const batch = [first]; let size = first.size;
+      for (let i = 0; i < pending.length;) {
+        const item = pending[i];
+        if (item.identity === first.identity && item.revision === first.revision && size + item.size <= 1024 * 1024) { pending.splice(i, 1); if (item.signal.aborted) item.reject(aborted()); else { batch.push(item); size += item.size; } } else i++;
+      }
+      const controller = new AbortController();
+      const cancel = () => { if (batch.every(item => item.signal.aborted)) controller.abort(); };
+      for (const item of batch) item.signal.addEventListener("abort", cancel);
+      void retryPending(() => chunkQueue.run(() => transport.chunks(first.jobId, { path: first.path, revision: first.revision, ids: batch.map(item => item.id) }, { signal: controller.signal }), controller.signal), controller.signal, first.timeout).then(bytes => {
+        if (bytes.length !== size) throw new FileSyncError("文件块批次长度错误", 502, "integrity");
+        let offset = 0; for (const item of batch) { const data = bytes.slice(offset, offset + item.size); offset += item.size; if (item.signal.aborted) item.reject(aborted()); else item.resolve(data); }
+      }).catch(error => { for (const item of batch) item.reject(error); }).finally(() => { for (const item of batch) item.signal.removeEventListener("abort", cancel); });
+    }
+  };
+  const fetchChunk = (item: Omit<QueuedChunk, "resolve" | "reject">) => new Promise<Uint8Array<ArrayBuffer>>((resolve, reject) => {
+    queued.push({ ...item, resolve, reject }); if (flushTimer === undefined) flushTimer = setTimeout(flush, 12);
+  });
+  const manifestFor = async (jobId: string, path: string, signal?: AbortSignal, timeout?: number, fresh = false) => {
+    const resource = JSON.stringify([jobId, path]);
+    // A round-end check must start after that event. Sharing an older in-flight
+    // check can miss the final edit indefinitely when there is no polling.
+    const earlier = fresh ? manifests.get(resource) : undefined;
+    if (earlier) await untilCancelled(earlier.promise.catch(() => undefined), signal);
+    return lease(manifests, resource, async inner => {
+      const previous = last.get(resource);
+      try {
+        const response = await retryPending(() => manifestQueue.run(() => transport.manifest(jobId, path, { signal: inner, revision: previous?.revision }), inner), inner, timeout); check(inner);
+        const manifest = response ? validateFileSyncManifest(response) : previous;
+        if (!manifest) throw new FileSyncError("没有可复用的授权修订清单", 502, "invalid_manifest");
+        last.delete(resource); last.set(resource, manifest); while (last.size > 40) last.delete(last.keys().next().value!);
+        return manifest;
+      } catch (error) {
+        const status = statusOf(error);
+        if ([401, 403, 404].includes(status)) {
+          last.delete(resource);
+          if (previous) {
+            if (status === 404) { const scope = { namespace: previous.namespace, taskId: jobId, path }; retireFile(scope); await cache.purgeFile(scope); }
+            else { retireNamespace(previous.namespace); await cache.purgeNamespace(previous.namespace); }
+          }
+        }
+        throw error;
+      }
+    }, signal);
+  };
+  const read = async (jobId: string, path: string, options: FileSyncOptions = {}, initialManifest?: FileSyncManifest): Promise<SyncedFile> => {
+    if (!path || path.length > 4096 || path.includes("\0")) throw new FileSyncError("文件路径无效", 400, "invalid_path");
+    if (options.range && (!Number.isSafeInteger(options.range.maxBytes) || options.range.maxBytes < 0 || !Number.isSafeInteger(options.range.start ?? 0) || (options.range.start ?? 0) < 0)) throw new FileSyncError("文件读取范围无效", 400, "invalid_range");
+    for (let attempt = 0; ; attempt++) {
+      notifyCallback(options.onProgress, { phase: "manifest", loadedBytes: 0, totalBytes: 0, downloadedBytes: 0, reusedBytes: 0 });
+      const manifest = attempt === 0 && initialManifest ? initialManifest : await manifestFor(jobId, path, options.signal, options.pendingTimeoutMs, options.fresh || attempt > 0);
+      const start = options.range?.tail ? Math.max(0, manifest.size - options.range.maxBytes) : Math.min(manifest.size, options.range?.start ?? 0);
+      const end = options.range ? Math.min(manifest.size, start + options.range.maxBytes) : manifest.size;
+      const scope: FileSyncScope = { namespace: manifest.namespace, taskId: jobId, path };
+      if (options.signal?.aborted) throw aborted();
+      await untilCancelled(cache.authorize(scope, manifest.revision), options.signal);
+      if (options.signal?.aborted) throw aborted();
+      const identity = fileSyncScopeKey(scope), key = JSON.stringify([identity, manifest.revision, start, end, options.decode !== false]);
+      try {
+        return await lease(files, key, (outerSignal, progress) => assemblyQueue.run(async () => {
+          const controller = new AbortController(), cancel = () => controller.abort();
+          outerSignal.addEventListener("abort", cancel, { once: true }); if (outerSignal.aborted) cancel();
+          const signal = controller.signal;
+          const processor = new FileSyncProcessor(signal);
+          let downloadedBytes = 0, reusedBytes = 0, loadedBytes = 0;
+          const report = (phase: FileSyncProgress["phase"]) => progress({ phase, loadedBytes, totalBytes: end - start, downloadedBytes, reusedBytes });
+          let offset = 0;
+          const selected = manifest.chunks.map(chunk => { const value = { ...chunk, offset }; offset += chunk.size; return value; }).filter(chunk => chunk.offset < end && chunk.offset + chunk.size > start);
+          const release = cache.retain(scope, new Set(selected.map(chunk => chunk.id)));
+          const coverStart = selected[0]?.offset ?? start, coverSize = selected.reduce((sum, chunk) => sum + chunk.size, 0);
+          const network = async (chunk: { id: string; size: number }) => {
+            const bytes = await lease(chunks, JSON.stringify([identity, manifest.revision, chunk.id]), inner => fetchChunk({ identity, jobId, path, revision: manifest.revision, id: chunk.id, size: chunk.size, signal: inner, timeout: options.pendingTimeoutMs }), signal);
+            check(signal); if (bytes.byteLength !== chunk.size) throw new FileSyncError("文件块长度错误", 502, "integrity");
+            const verified = await processor.verify(bytes.slice(), chunk.id); check(signal); downloadedBytes += verified.byteLength;
+            await cache.putBlock(scope, chunk.id, verified); check(signal); return verified;
+          };
+          const read = async (chunk: { id: string; size: number }) => {
+            const cached = await cache.getBlock(scope, chunk.id); check(signal);
+            if (cached?.byteLength === chunk.size) return { bytes: cached, cached: true };
+            if (cached) await cache.removeBlock(scope, chunk.id);
+            return { bytes: await network(chunk), cached: false };
+          };
+          const prefetched = new Map<number, ReturnType<typeof read>>();
+          const prefetch = (index: number) => { let bytes = 0; for (let i = index; i < Math.min(selected.length, index + 48); i++) { bytes += selected[i].size; if (bytes > 3 * 1024 * 1024) break; if (!prefetched.has(i)) { const promise = read(selected[i]); void promise.catch(() => undefined); prefetched.set(i, promise); } } };
+          try {
+            await processor.start(coverSize); prefetch(0);
+            for (let index = 0; index < selected.length; index++) {
+              check(signal); const chunk = selected[index]; const data = await prefetched.get(index)!; prefetched.delete(index);
+              try { await processor.append(data.bytes, chunk.id); if (data.cached) reusedBytes += chunk.size; }
+              catch (error) {
+                check(signal); if (!data.cached) throw error;
+                // Several prefetched positions may hold the same old corrupt
+                // block. Reuse a repair already committed by an earlier position.
+                const repaired = await cache.getBlock(scope, chunk.id); check(signal);
+                let reused = false;
+                if (repaired?.byteLength === chunk.size) try { await processor.append(repaired, chunk.id); reused = true; reusedBytes += chunk.size; } catch { check(signal); }
+                if (!reused) { await cache.removeBlock(scope, chunk.id); await processor.append(await network(chunk), chunk.id); }
+              }
+              loadedBytes = Math.min(end - start, chunk.offset + chunk.size - start); report("chunks"); prefetch(index + 1);
+            }
+            report("verify");
+            const complete = start === 0 && end === manifest.size;
+            const assembled = await processor.finish(complete ? manifest.hash : null, options.decode !== false, { start: start - coverStart, length: end - start, fromMiddle: start > 0 });
+            check(signal); const latest = last.get(JSON.stringify([jobId, path]));
+            if (complete && latest?.namespace === manifest.namespace && latest.revision === manifest.revision) await cache.putManifest(scope, manifest); check(signal);
+            return { ...assembled, namespace: manifest.namespace, revision: manifest.revision, hash: manifest.hash, size: manifest.size, start, end, truncated: !complete, downloadedBytes, reusedBytes, cacheMode: cache.mode };
+          } finally { controller.abort(); outerSignal.removeEventListener("abort", cancel); processor.dispose(); release(); }
+        }, outerSignal), options.signal, options.onProgress);
+      } catch (error) {
+        if (statusOf(error) !== 410 || attempt >= 2 || options.signal?.aborted) throw error;
+        last.delete(JSON.stringify([jobId, path]));
+      }
+    }
+  };
+  const sync = async (jobId: string, path: string, options: FileSyncOptions = {}): Promise<SyncedFile> => {
+    const resource = JSON.stringify([jobId, path]), token = {};
+    if (options.preview) previewReads.set(resource, token);
+    try {
+      const result = await read(jobId, path, options);
+      if (options.preview && previewReads.get(resource) === token && !options.signal?.aborted) {
+        const previous = previews.get(resource);
+        const range = options.range ? { start: options.range.start ?? 0, maxBytes: options.range.maxBytes, tail: !!options.range.tail } : undefined;
+        // A preview can finish behind a metadata baseline or a newer background refresh.
+        // Normal revision-only updates must not create a watch -> preview -> watch cycle.
+        const latest = last.get(resource), behindLatest = latest && (latest.namespace !== result.namespace || latest.revision !== result.revision);
+        const alreadyRefreshed = behindLatest && previous?.namespace === latest.namespace && previous.revision === latest.revision && JSON.stringify(previous.range) === JSON.stringify(range);
+        if (alreadyRefreshed) {
+          // Keep the latest verified revision, but request one corrective event
+          // because this caller is about to display an older snapshot.
+          previews.set(resource, { ...previous, stale: true });
+        } else {
+          previews.delete(resource); previews.set(resource, { namespace: result.namespace, revision: result.revision, range });
+          while (previews.size > 40) previews.delete(previews.keys().next().value!);
+        }
+        if (!previous || behindLatest || previous.namespace !== result.namespace || JSON.stringify(previous.range) !== JSON.stringify(range)) {
+          for (const callback of [...previewListeners.get(jobId) ?? []]) notifyCallback(callback, undefined);
+        }
+      }
+      return result;
+    } finally { if (previewReads.get(resource) === token) previewReads.delete(resource); }
+  };
+  const refreshPreviews = (jobId: string, paths: Iterable<string>, signal?: AbortSignal): Promise<FilePreviewRefresh> => {
+    const requested = [...new Set(paths)];
+    // Serialize background assembly across tasks as well: a chunk request limit alone does not
+    // prevent several 100MiB workers allocating full buffers at the same time.
+    const work = async (): Promise<FilePreviewRefresh> => {
+      const changed = new Set<string>(); let error: Error | undefined, hasRecoverableError = false, retryAfterMs = 0;
+      for (const path of requested) {
+        if (signal?.aborted) throw aborted();
+        const resource = JSON.stringify([jobId, path]), previous = previews.get(resource);
+        if (!previous) continue; // Restored/unread tabs are still demand-loaded on activation.
+        try {
+          const manifest = await manifestFor(jobId, path, signal, undefined, true);
+          if (manifest.namespace === previous.namespace && manifest.revision === previous.revision && !previous.stale) continue;
+          changed.add(path);
+          const result = await read(jobId, path, { signal, decode: false, range: previous.range }, manifest);
+          const latest = last.get(resource), current = previews.get(resource);
+          if (current?.namespace === previous.namespace && current.revision === previous.revision && JSON.stringify(current.range) === JSON.stringify(previous.range)
+            && latest?.namespace === result.namespace && latest.revision === result.revision) {
+            previews.set(resource, { ...current, namespace: result.namespace, revision: result.revision, stale: false });
+          }
+        } catch (failure) {
+          const status = statusOf(failure);
+          if (signal?.aborted || (failure instanceof Error && failure.name === "AbortError") || status === 401 || status === 403) throw failure;
+          if (status === 404) {
+            changed.add(path);
+            if (previews.get(resource) === previous) {
+              previews.delete(resource);
+              // Deletion may arrive from a chunk request after manifest authorization too.
+              const scope = { namespace: last.get(resource)?.namespace ?? previous.namespace, taskId: jobId, path };
+              last.delete(resource); retireFile(scope); await cache.purgeFile(scope);
+            }
+          } else {
+            const candidate = failure instanceof Error ? failure : new Error(String(failure));
+            const code = (failure as FileSyncError)?.code;
+            // Match event-driven workspace recovery: a permanent failure of one
+            // file must not hide a later file's recoverable failure.
+            const recoverable = !["invalid_manifest", "invalid_response", "integrity", "response_too_large", "client_queue_timeout"].includes(code)
+              && (!status || [408, 429, 500, 502, 503, 504].includes(status));
+            if (!error || (recoverable && !hasRecoverableError)) error = candidate;
+            if (recoverable) {
+              hasRecoverableError = true;
+              const hint = (failure as FileSyncError)?.retryAfterMs;
+              if (typeof hint === "number" && Number.isFinite(hint) && hint >= 0) retryAfterMs = Math.max(retryAfterMs, hint);
+            }
+          }
+        }
+      }
+      // Preserve the original errors: consumers may share them with other reads.
+      const combined = error && hasRecoverableError && retryAfterMs > 0 ? Object.assign(new Error(error.message), error, { name: error.name, retryAfterMs }) : error;
+      return { changed: [...changed], ...(combined ? { error: combined } : {}) };
+    };
+    return refreshQueue.run(work, signal);
+  };
+  const onPreviewScope = (jobId: string, callback: () => void) => {
+    let listeners = previewListeners.get(jobId); if (!listeners) { listeners = new Set(); previewListeners.set(jobId, listeners); }
+    listeners.add(callback);
+    return () => { listeners.delete(callback); if (!listeners.size) previewListeners.delete(jobId); };
+  };
+  return { sync, refreshPreviews, onPreviewScope, cache, clearNamespace: (namespace: string) => {
+    for (const entry of manifests.values()) entry.controller.abort(); manifests.clear();
+    retireNamespace(namespace);
+    for (const [key, manifest] of last) if (manifest.namespace === namespace) last.delete(key);
+    for (const [key, preview] of previews) if (preview.namespace === namespace) previews.delete(key);
+    return cache.purgeNamespace(namespace);
+  } };
+}
+const synchronizers = new WeakMap<FileSyncTransport, ReturnType<typeof createFileSynchronizer>>();
+function synchronizerFor(transport: FileSyncTransport) {
+  let sync = synchronizers.get(transport); if (!sync) { sync = createFileSynchronizer(transport); synchronizers.set(transport, sync); }
+  return sync;
+}
+export function syncFile(transport: FileSyncTransport, jobId: string, path: string, options: FileSyncOptions = {}) {
+  return synchronizerFor(transport).sync(jobId, path, options);
+}
+/** Refresh only ranges that were actually previewed, one file at a time. */
+export function refreshFilePreviews(transport: FileSyncTransport, jobId: string, paths: Iterable<string>, signal?: AbortSignal) {
+  return synchronizerFor(transport).refreshPreviews(jobId, paths, signal);
+}
+export function onFilePreviewScope(transport: FileSyncTransport, jobId: string, callback: () => void) {
+  return synchronizerFor(transport).onPreviewScope(jobId, callback);
+}
+/** Hosts can call this on an explicit account logout; a viewer unmount keeps reusable cache. */
+export function clearFileSyncNamespace(transport: FileSyncTransport, namespace: string) {
+  const synchronizer = synchronizers.get(transport);
+  return synchronizer ? synchronizer.clearNamespace(namespace) : new FileSyncCache().purgeNamespace(namespace);
+}