@spzxg/cli-ui 0.6.5 → 0.6.7

package/src/board/fileWatch.ts

@@ -1,88 +1,195 @@
-import { CenterError, type BoardBackend } from '../core/client';
+import { type BoardBackend } from '../core/client';
 import { notifyCallback } from '../core/callbacks';
 import type { FileEntry, WorkspaceChangeEvent, WorkspaceFileBatch, WorkspaceFileChange, WorkspaceWatchStatus } from '../core/types';
-import { listFolder } from './folderDownload';
-export interface WorkspaceWatchOptions { intervalMs?:number; onStatus?:(status:WorkspaceWatchStatus)=>void }
+import { denyFileScope, onFileScope, readFileScope, retainFileScope } from './fileScope';
+import { onFilePreviewScope, refreshFilePreviews } from './fileSync';
+import { createFileWorkQueue } from './fileSyncQueue';
+export interface WorkspaceWatchOptions { /** @deprecated Retained for compatibility; checks are event-driven, never periodic. */ intervalMs?:number; paths?:readonly string[]; dirs?:readonly string[]; onStatus?:(status:WorkspaceWatchStatus)=>void }
 type Listener={change:(event:WorkspaceChangeEvent)=>void;status?:WorkspaceWatchOptions['onStatus']};
-type Entry={listeners:Set<Listener>;stop:()=>void;retry?:()=>void;status:WorkspaceWatchStatus};
+export interface WorkspaceRefreshOptions { manual?:boolean }
+type Entry={listeners:Set<Listener>;stop:()=>void;retry:(manual?:boolean)=>void;status:WorkspaceWatchStatus};
 export function cloneWorkspaceChange(event:WorkspaceChangeEvent):WorkspaceChangeEvent {return {...event,changes:event.changes.map(change=>({...change,file:change.file?{...change.file}:undefined,previous:change.previous?{...change.previous}:undefined}))};}
 const registries=new WeakMap<BoardBackend,Map<string,Entry>>();
-const MAX_TRACKED_FILES=100000;
-/** Internal: a new lease in an aggregating store can retry a terminal stream. */
-export function retryWorkspaceFiles(backend:BoardBackend,jobId:string):void {registries.get(backend)?.get(jobId)?.retry?.();}
-/** One transport per backend/workspace; independent of the active directory or file tab. */
+const metadataQueues=new WeakMap<BoardBackend,ReturnType<typeof createFileWorkQueue>>();
+function metadataQueue(backend:BoardBackend){
+ let queue=metadataQueues.get(backend);if(!queue){queue=createFileWorkQueue(4,128);metadataQueues.set(backend,queue);}return queue;
+}
+export function retryWorkspaceFiles(backend:BoardBackend,jobId:string,options:WorkspaceRefreshOptions={}):void {registries.get(backend)?.get(jobId)?.retry(options.manual);}
+const fingerprint=(file:FileEntry)=>`${file.type}:${file.size}:${file.mtime}:${file.changeToken??''}`;
+const validFile=(file:FileEntry)=>!!file&&typeof file.path==='string'&&typeof file.name==='string'&&['file','dir'].includes(file.type)&&Number.isFinite(file.size)&&Number.isFinite(file.mtime);
+const invalidResponse=(message:string)=>Object.assign(new Error(message),{status:502,code:'invalid_response'});
+/** Shared event-driven HTTP checks. No recurring file timer or file event connection. */
 export function subscribeWorkspaceFiles(backend:BoardBackend,jobId:string,listener:(event:WorkspaceChangeEvent)=>void,options:WorkspaceWatchOptions={}):()=>void {
- let entries=registries.get(backend);if(!entries){entries=new Map();registries.set(backend,entries);}
- let entry=entries.get(jobId);const subscription={change:listener,status:options.onStatus};
+ const releaseOwnedScope=options.paths?.length||options.dirs?.length?retainFileScope(backend,jobId,{paths:[...options.paths??[]],dirs:[...options.dirs??[]]}):()=>{};
+ let jobs=registries.get(backend);if(!jobs){jobs=new Map();registries.set(backend,jobs);}
+ let entry=jobs.get(jobId);
  if(!entry){
-  const mode=backend.watchFiles?'events':'poll',coverage=mode==='events'?'workspace':'listed-files';
-  entry={listeners:new Set(),stop:()=>{},status:{type:'files_watch',jobId,state:'connecting',mode,coverage,complete:false}};entries.set(jobId,entry);
-  const owned=entry;let alive=true,baseline:Map<string,FileEntry>|null=null,limited=false,blocked=false,stopTransport:(()=>void)|null=null;
-  let timer:ReturnType<typeof setTimeout>|undefined,controller:AbortController|null=null,attempt=0,generation=0;
-  const status=(state:WorkspaceWatchStatus['state'],complete=false,error?:string)=>{
-   if(!alive)return;owned.status={type:'files_watch',jobId,state,mode,coverage,complete:mode==='events'&&complete&&!limited,...(error?{error}:{})};
-   for(const item of [...owned.listeners])notifyCallback(item.status,{...owned.status});
-  };
-  const publish=(changes:WorkspaceFileChange[],batch:WorkspaceFileBatch,resync=false)=>{
+  // Keep the public transport value for compatibility; it denotes bounded HTTP, not a timer.
+  const statusBase={type:'files_watch' as const,jobId,mode:'poll' as const,coverage:'listed-files' as const,complete:false};
+  entry={listeners:new Set(),stop:()=>{},retry:()=>{},status:{...statusBase,state:'connecting'}};jobs.set(jobId,entry);
+  const owned=entry;
+  let alive=true,controller:AbortController|null=null,timer:ReturnType<typeof setTimeout>|undefined,failed=0,generation=0,dirty=false;
+  let scopeKey=JSON.stringify(readFileScope(backend,jobId));
+  const retryDelays=[1000,2000,4000];
+  let serverNotBefore=0,retryAt=0,exhaustedUntil=0;
+  const requests=metadataQueue(backend);
+  let baseline=new Map<string,FileEntry>(),directories=new Map<string,string|null>(),cursors=new Map<string,string>();
+  let known=new Set<string>();
+  type ScanState={baseline:Map<string,FileEntry>;known:Set<string>};
+  const status=(state:WorkspaceWatchStatus['state'],error?:string)=>{owned.status={...statusBase,state,...(error?{error}:{})};for(const item of [...owned.listeners])notifyCallback(item.status,{...owned.status});};
+  const publish=(changes:WorkspaceFileChange[],revision?:string)=>{
    if(!alive||!changes.length)return;
-   const event:WorkspaceChangeEvent={type:'files_changed',jobId,mode,coverage,complete:mode==='events'&&batch.complete&&!limited,changes,revision:batch.revision,...(resync?{resync:true}:{})};
+   const event:WorkspaceChangeEvent={type:'files_changed',jobId,mode:'poll',coverage:'listed-files',complete:false,changes,revision};
    for(const item of [...owned.listeners])notifyCallback(item.change,cloneWorkspaceChange(event));
   };
-  const accept=(batch:WorkspaceFileBatch)=>{
-   if(!alive)return;
-   if(batch.type==='resync'){if(batch.reason==='workspace_unavailable'&&baseline===null)baseline=new Map();status('reconnecting',false,batch.reason);return;}
-   if(batch.type==='snapshot'){
-    const next=new Map<string,FileEntry>();let overflow=false;const changes:WorkspaceFileChange[]=[];
-    for(const file of batch.files)if(file.type==='file'){if(next.has(file.path)||next.size<MAX_TRACKED_FILES)next.set(file.path,{...file});else overflow=true;}
-    if(baseline){
-     for(const [path,file] of next){const previous=baseline.get(path);if(!previous)changes.push({kind:'created',path,file});else if(previous.mtime!==file.mtime||previous.size!==file.size||previous.changeToken!==file.changeToken)changes.push({kind:'modified',path,file,previous});}
-     if(batch.complete&&!overflow)for(const [path,previous] of baseline)if(!next.has(path))changes.push({kind:'deleted',path,previous});
+  const snapshot=(files:FileEntry[],paths:string[],state:ScanState):WorkspaceFileChange[]=>{
+   if(!Array.isArray(files)||!files.every(validFile))throw invalidResponse('文件变化响应不完整，请重试');
+   const current=new Map(files.map(file=>[file.path,file])),changes:WorkspaceFileChange[]=[];
+   for(const path of paths){
+    const file=current.get(path),previous=state.baseline.get(path);
+    if(state.known.has(path)){
+     if(file&&!previous)changes.push({kind:'created',path,file});
+     else if(!file&&previous)changes.push({kind:'deleted',path,previous});
+     else if(file&&previous&&fingerprint(file)!==fingerprint(previous))changes.push({kind:'modified',path,file,previous});
     }
-    // Once tracking overflows, only a complete, bounded snapshot restores
-    // completeness. Partial snapshots never prove that missing files vanished.
-    if(batch.complete){baseline=next;limited=overflow;}
-    else{baseline??=new Map();for(const [path,file] of next){if(baseline.has(path)||baseline.size<MAX_TRACKED_FILES)baseline.set(path,file);else overflow=true;}limited||=overflow;}
-    publish(changes,batch,true);
-   }else{
-    baseline??=new Map();for(const change of batch.changes){if(change.kind==='deleted')baseline.delete(change.path);else if(change.file){if(baseline.has(change.path)||baseline.size<MAX_TRACKED_FILES)baseline.set(change.path,{...change.file});else limited=true;}}
-    // Native change events are authoritative even when size/mtime are unchanged.
-    publish(batch.changes,batch);
+    state.known.add(path);if(file)state.baseline.set(path,{...file});else state.baseline.delete(path);
    }
-   attempt=0;status('ready',batch.complete);
+   return changes;
   };
-  const interval=Math.max(1000,options.intervalMs??15000);
+  const accept=(batch:WorkspaceFileBatch,paths:string[],state:ScanState)=>{
+   if(batch.type==='resync')return [];
+   if(batch.type==='snapshot')return snapshot(batch.files,paths,state);
+   if(batch.type!=='changes'||!Array.isArray(batch.changes)||batch.changes.some(change=>!change||!paths.includes(change.path)||!['created','modified','deleted'].includes(change.kind)||(change.file&&!validFile(change.file))))throw invalidResponse('文件变化响应不完整，请重试');
+   for(const change of batch.changes){state.known.add(change.path);if(change.kind==='deleted')state.baseline.delete(change.path);else if(change.file)state.baseline.set(change.path,{...change.file});}
+   return batch.changes;
+  };
+  const hidden=()=>typeof document!=='undefined'&&document.visibilityState==='hidden';
   const scan=async()=>{
-   if(!alive)return;controller=new AbortController();const signal=controller.signal;
-   try{const files=await listFolder(backend,jobId,'',{signal,maxFiles:10000,maxBytes:Infinity});if(alive&&!signal.aborted)accept({type:'snapshot',files:files.map(file=>({...file,name:file.path.split('/').pop()??file.path,type:'file' as const})),complete:true});}
-   catch(error){if(alive&&!signal.aborted){attempt++;status('error',false,error instanceof Error?error.message:String(error));}}
-   finally{controller=null;if(alive)timer=setTimeout(()=>{timer=undefined;void scan();},Math.min(120000,interval*Math.max(1,attempt)));}
+   if(!alive||controller||hidden())return;
+   // A real event retained during cooldown starts one new bounded attempt wave.
+   if(dirty&&exhaustedUntil&&Date.now()>=exhaustedUntil){failed=0;exhaustedUntil=0;}
+   clearTimer();dirty=false;
+   const scope=readFileScope(backend,jobId);
+   // No open document/list: no idle root scan and no network subscription.
+   if(!scope.paths.length&&!scope.dirs.length){status('ready');return;}
+   const ctl=new AbortController();controller=ctl;const token=++generation;
+   let retryable=false;
+   const current=()=>alive&&!ctl.signal.aborted&&token===generation;
+   const state={baseline:new Map(baseline),known:new Set(known)},nextDirectories=new Map(directories),nextCursors=new Map(cursors);
+   try{
+    const changes:WorkspaceFileChange[]=[];
+    if(backend.pollFiles){
+     const activeKeys=new Set<string>();
+     const count=Math.max(Math.ceil(scope.paths.length/200),Math.ceil(scope.dirs.length/32));
+     for(let index=0;index<count;index++){
+      const paths=scope.paths.slice(index*200,index*200+200),dirs=scope.dirs.slice(index*32,index*32+32),key=JSON.stringify([paths,dirs]);activeKeys.add(key);
+      const batch=await requests.run(()=>backend.pollFiles!(jobId,{paths,dirs,cursor:nextCursors.get(key)},ctl.signal),ctl.signal);
+      if(!current())return;
+      if(!batch||typeof batch!=='object')throw invalidResponse('文件变化响应不完整，请重试');
+      if(batch.type==='resync'){cursors.delete(key);throw new Error('文件修订已变化，请重新核对');}
+      if(batch.cursor)nextCursors.set(key,batch.cursor);
+      changes.push(...accept(batch,paths,state));
+      if(!Array.isArray(batch.directories))throw invalidResponse('目录变化响应不完整，请重试');
+      for(const dir of batch.directories){
+       if(!dir||!dirs.includes(dir.path)||(dir.revision!==null&&typeof dir.revision!=='string'))throw invalidResponse('目录变化响应范围错误');
+       if(nextDirectories.has(dir.path)&&nextDirectories.get(dir.path)!==dir.revision)changes.push({kind:dir.revision===null?'deleted':'modified',path:dir.path});
+       nextDirectories.set(dir.path,dir.revision);
+      }
+     }
+     for(const key of nextCursors.keys())if(!activeKeys.has(key))nextCursors.delete(key);
+    }else{
+     // Compatibility hosts: inspect requested entries, never recurse a workspace.
+     const listed=new Map<string,FileEntry>();
+     for(const dir of scope.dirs){
+      const result=await requests.run(()=>backend.stat(jobId,dir||'.'),ctl.signal);if(!current())return;
+      if(result.type!=='dir')continue;
+      for(const file of result.entries)listed.set(file.path,file);
+      const revision=result.revision??JSON.stringify(result.entries.map(file=>[file.path,fingerprint(file)]));
+      if(nextDirectories.has(dir)&&nextDirectories.get(dir)!==revision)changes.push({kind:'modified',path:dir});
+      nextDirectories.set(dir,revision);
+     }
+     const files:FileEntry[]=[];
+     for(const path of scope.paths){
+      const listedFile=listed.get(path);if(listedFile){files.push(listedFile);continue;}
+      try{const result=await requests.run(()=>backend.stat(jobId,path),ctl.signal);if(result.type==='file')files.push(result);}
+      catch(error){if((error as {status?:number}).status!==404)throw error;}
+      if(!current())return;
+     }
+     changes.push(...snapshot(files,scope.paths,state));
+    }
+    if(!current())return;
+    const previews=backend.fileSync?await refreshFilePreviews(backend.fileSync,jobId,scope.paths,ctl.signal):undefined;
+    if(!current())return;
+    const changedPaths=new Set(changes.map(change=>change.path));
+    for(const path of previews?.changed??[])if(!changedPaths.has(path)){changes.push({kind:'modified',path});changedPaths.add(path);}
+    const active=new Set(scope.paths);for(const path of state.known)if(!active.has(path)){state.known.delete(path);state.baseline.delete(path);}
+    for(const dir of nextDirectories.keys())if(!scope.dirs.includes(dir))nextDirectories.delete(dir);
+    baseline=state.baseline;known=state.known;directories=nextDirectories;cursors=nextCursors;
+    publish(changes);
+    if(previews?.error)throw previews.error;
+    failed=0;serverNotBefore=0;retryAt=0;exhaustedUntil=0;if(current())status('ready');
+   }catch(error){if(current()){
+    failed++;const code=(error as {status?:number}).status??0;
+    const failureCode=(error as {code?:string}).code;
+    retryable=!['invalid_manifest','invalid_response','integrity','response_too_large','client_queue_timeout'].includes(failureCode??'')&&(!code||[408,429,500,502,503,504].includes(code));
+    if(retryable){
+     const hint=Number((error as {retryAfterMs?:number}).retryAfterMs);
+     if(Number.isFinite(hint)&&hint>0)serverNotBefore=Math.max(serverNotBefore,Date.now()+hint);
+     const base=retryDelays[Math.min(failed-1,retryDelays.length-1)];
+     retryAt=Math.max(Date.now()+base,serverNotBefore)+Math.floor(Math.random()*base/2);
+     if(failed>retryDelays.length)exhaustedUntil=Math.max(Date.now()+30000,serverNotBefore);
+    }
+    if([401,403].includes(code))denyFileScope(backend,jobId);
+    status('error',error instanceof Error?error.message:String(error));
+   }}
+   finally{if(controller===ctl){
+    controller=null;
+    if(alive&&!hidden()){
+     if(retryable){
+      // A new round during an outage cannot skip backoff or replenish this retry budget.
+      if(failed<=retryDelays.length){const pending=dirty;dirty=false;schedule(Math.max(0,retryAt-Date.now()),pending);}
+      else if(dirty)schedule(Math.max(0,exhaustedUntil-Date.now(),serverNotBefore-Date.now()),true);
+     }else if(dirty)schedule(Math.max(100,serverNotBefore-Date.now()),true);
+    }
+   }}
+  };
+  function clearTimer(){if(timer!==undefined)clearTimeout(timer);timer=undefined;}
+  function schedule(delay:number,pending=false){
+   clearTimer();
+   // Long server cooldowns defer a real event once, never extend idle retries.
+   // Do not let setTimeout overflow and retry before the server's deadline.
+   if(delay>2147483647||(!pending&&delay>180000))return;
+   timer=setTimeout(()=>{timer=undefined;void scan();},delay);
+  }
+  const wake=(manual=false)=>{
+   if(!alive)return;
+   const now=Date.now();
+   if(manual){failed=0;exhaustedUntil=0;clearTimer();}
+   else if(exhaustedUntil&&now>=exhaustedUntil){
+    // Exhaustion alone never restarts work; a later event can restore its budget.
+    failed=0;exhaustedUntil=0;
+   }
+   dirty=true;
+   // Pending events coalesce, and automatic wakes cannot bypass an existing retry delay.
+   if(!controller&&!hidden()&&timer===undefined)schedule(Math.max(100,serverNotBefore-now,manual?0:Math.max(retryAt,exhaustedUntil)-now),true);
+  };
+  const recover=()=>wake();
+  const scopeChanged=()=>{
+   if(!alive)return;
+   const next=JSON.stringify(readFileScope(backend,jobId));if(next===scopeKey)return;scopeKey=next;
+   generation++;const old=controller;controller=null;old?.abort();wake(true);
   };
-  const connect=()=>{
-   if(!alive||!backend.watchFiles)return;const token=++generation;let finished=false,cleanup:(()=>void)|null=null;
-   blocked=false;
-   status(attempt?'reconnecting':'connecting');
-   if(!alive||token!==generation)return;
-   // Retirement can precede watchFiles returning its disposer. Clearing the
-   // owned handle first also makes reentrant cancellation release it once.
-   const retire=()=>{finished=true;if(stopTransport===retire)stopTransport=null;const dispose=cleanup;cleanup=null;notifyCallback(dispose??undefined,undefined);};
-   const close=(error:unknown)=>{
-    if(!alive||finished||token!==generation)return;retire();if(!alive||token!==generation)return;const code=error instanceof CenterError?error.status:0;
-    blocked=[400,404,405,410,501].includes(code);const slow=[401,403,429].includes(code);
-    status(blocked||slow?'error':'reconnecting',false,error instanceof Error?error.message:undefined);
-    if(!alive||token!==generation||blocked)return;
-    const delay=slow?30000:Math.min(30000,1000*2**Math.min(attempt++,5));
-    timer=setTimeout(()=>{timer=undefined;connect();},delay);
-   };
-   stopTransport=retire;
-   try{cleanup=backend.watchFiles(jobId,{onEvent:batch=>{if(alive&&!finished&&token===generation)accept(batch);},onClose:close});if(finished||!alive||token!==generation)retire();}catch(error){close(error);}
+  const visibility=()=>{
+   if(hidden()){generation++;const old=controller;controller=null;old?.abort();clearTimer();dirty=true;}
+   else recover();
   };
-  const wake=()=>{if(!alive)return;if(typeof document!=='undefined'&&document.visibilityState==='hidden')return;if(timer){clearTimeout(timer);timer=undefined;}if(mode==='poll'){if(!controller)void scan();}else{const token=++generation,retire=stopTransport;stopTransport=null;retire?.();if(alive&&token===generation)connect();}};
-  owned.retry=()=>{if(blocked)wake();};
-  if(typeof window!=='undefined'){window.addEventListener('online',wake);document.addEventListener('visibilitychange',wake);}
-  owned.stop=()=>{alive=false;generation++;if(timer)clearTimeout(timer);controller?.abort();stopTransport?.();if(typeof window!=='undefined'){window.removeEventListener('online',wake);document.removeEventListener('visibilitychange',wake);}};
-  // Defer initialization until the first listener has been registered.
-  queueMicrotask(()=>{if(alive){if(mode==='events')connect();else void scan();}});
+  const releaseScope=onFileScope(backend,jobId,scopeChanged);
+  const releasePreviews=backend.fileSync?onFilePreviewScope(backend.fileSync,jobId,()=>wake()):()=>{};
+  if(typeof window!=='undefined'){window.addEventListener('online',recover);document.addEventListener('visibilitychange',visibility);}
+  owned.retry=wake;
+  owned.stop=()=>{alive=false;clearTimer();controller?.abort();releaseScope();releasePreviews();if(typeof window!=='undefined'){window.removeEventListener('online',recover);document.removeEventListener('visibilitychange',visibility);}};
+  queueMicrotask(()=>{if(alive)void scan();});
  }
- const owned=entry;owned.listeners.add(subscription);notifyCallback(subscription.status,{...owned.status});owned.retry?.();
- let active=true;return()=>{if(!active)return;active=false;owned.listeners.delete(subscription);if(!owned.listeners.size){if(entries!.get(jobId)===owned)entries!.delete(jobId);owned.stop();}};
+ const owned=entry,subscription={change:listener,status:options.onStatus};owned.listeners.add(subscription);notifyCallback(subscription.status,{...owned.status});
+ let active=true;return()=>{if(!active)return;active=false;owned.listeners.delete(subscription);if(!owned.listeners.size){if(jobs!.get(jobId)===owned)jobs!.delete(jobId);owned.stop();}releaseOwnedScope();};
 }

package/src/board/folderDownload.ts

@@ -3,6 +3,7 @@
 // 弱网 / 节点忙：每个请求失败了按退避重试几次；某个文件一直读不到（或读的时候被任务删了）就跳过，
 // 照样把其余的打包，失败的清单放进压缩包里的 FAILED_LIST_NAME，并告诉调用方。取消会中止正在传的请求。
 import { CenterError, type BoardBackend } from "../core/client";
+import type { DirListing, FileEntry } from "../core/types";
 import { fmtSize } from "./fileKind";
 import { saveBlob, readBoundedBuffer, FileReadLimitError } from "./fileOps";
 import { buildZip, type ZipEntry } from "./zip";
@@ -68,17 +69,50 @@ export async function listFolder(backend: BoardBackend, jobId: string, dir: stri
   while (queue.length) {
     if (signal?.aborted) throw abortError();
     const cur = queue.shift()!;
-    let res;
+    const entries = new Map<string, FileEntry>();
+    const cursors = new Set<string>();
+    let cursor: string | undefined, revision: string | undefined;
+    let directoryBytes = 0, directoryFiles = 0;
     try {
-      res = await withRetry(() => backend.stat(jobId, cur), signal, undefined, backoff);
+      do {
+        const res = await withRetry(async () => {
+          try { return backend.listFiles ? await backend.listFiles(jobId, cur, { cursor, limit: 200, signal }) : await backend.stat(jobId, cur); }
+          catch (error) {
+            // New short-HTTP clients preserve status on ordinary Errors too.
+            const http = error as { status?: number; code?: string; message?: string };
+            if (!(error instanceof CenterError) && typeof http.status === "number") throw new CenterError(http.message ?? "列出目录失败", http.code ?? `HTTP_${http.status}`, http.status);
+            throw error;
+          }
+        }, signal, undefined, backoff);
+        if (res.type !== "dir") {
+          if (cursor) throw new Error("目录在读取时发生变化，请重新下载");
+          break;
+        }
+        const page: DirListing = res;
+        if (cursor && (!revision || page.revision !== revision)) throw new Error("目录在读取时发生变化，请重新下载");
+        revision ??= page.revision;
+        for (const entry of page.entries) {
+          if (entries.has(entry.path)) throw new Error("目录分页数据重复，请重新下载");
+          entries.set(entry.path, entry);
+          if (entry.type === "file") {
+            directoryFiles++; directoryBytes += entry.size;
+            if (out.length + directoryFiles > maxFiles) throw new Error(`文件超过 ${maxFiles} 个，请进到更小的目录再下载`);
+            if (bytes + directoryBytes > maxBytes) throw new Error(`总大小超过 ${fmtSize(maxBytes)}，请进到更小的目录或单个下载`);
+          }
+        }
+        cursor = page.nextCursor;
+        if (page.truncated && (!cursor || !backend.listFiles)) throw new Error(`「${cur === "." ? "工作区" : cur}」里文件太多，节点只列出了一部分；请进到更小的目录再下载`);
+        if (cursor && (!revision || cursors.has(cursor))) throw new Error("目录分页游标无效，请重新下载");
+        if (cursor) cursors.add(cursor);
+      } while (cursor);
     } catch (error) {
       // 子目录在列的时候被任务删了：跳过它；要下载的目录本身没了照常报错。
       if (cur !== (dir || ".") && error instanceof CenterError && error.status === 404) continue;
+      if (error instanceof CenterError && error.status === 409) throw new Error("目录在读取时发生变化，请重新下载");
       throw error;
     }
-    if (res.type !== "dir") continue;
-    if (res.truncated) throw new Error(`「${cur === "." ? "工作区" : cur}」里文件太多，节点只列出了一部分；请进到更小的目录再下载`);
-    for (const e of res.entries) {
+    // Commit a directory only after every page has the same revision.
+    for (const e of entries.values()) {
       if (e.type === "dir") { queue.push(e.path); continue; }
       out.push({ path: e.path, size: e.size, mtime: e.mtime });
       bytes += e.size;

package/src/board/frameQuote.ts

@@ -6,7 +6,7 @@
 //   · 相对路径的样式 / 图片按文件原地址解析（<base>），文档里的 #锚点 在页内滚动（不然会按 <base> 整页跳走）。
 
 /** iframe → 宿主：选区（text 为空 = 取消了选择）或滚动了（收起按钮）。 */
-export interface FrameSelMessage { cliUiSel: string; text?: string; rect?: { left: number; top: number; width: number } | null; scroll?: boolean }
+export interface FrameSelMessage { cliUiSel: string; text?: string; rect?: { left: number; top: number; width: number } | null; scroll?: boolean; top?: number; left?: number; ready?: boolean }
 
 const randomId = () => Math.random().toString(36).slice(2, 12) + Math.random().toString(36).slice(2, 12);
 
@@ -16,13 +16,15 @@ export const frameToken = randomId;
 function bridgeScript(token: string) {
   const t = JSON.stringify(token);
   return `(function(){var t=${t};function post(m){m.cliUiSel=t;try{parent.postMessage(m,"*")}catch(e){}}
+function ready(){requestAnimationFrame(function(){requestAnimationFrame(function(){post({ready:true})})})}if(document.readyState==='loading')document.addEventListener('DOMContentLoaded',ready,{once:true});else ready();
 function send(){var s=getSelection(),text=s&&!s.isCollapsed?String(s).trim():"",rect=null;
 if(text&&s.rangeCount){var b=s.getRangeAt(0).getBoundingClientRect();rect={left:b.left,top:b.top,width:b.width}}post({text:text,rect:rect})}
-function later(){setTimeout(send,0)}
+var timer;function later(){clearTimeout(timer);timer=setTimeout(send,0)}
 document.addEventListener("mouseup",later);document.addEventListener("keyup",later);
-document.addEventListener("selectionchange",function(){var s=getSelection();if(!s||s.isCollapsed)post({text:""})});
-addEventListener("scroll",function(){post({scroll:true})},true);
+document.addEventListener("selectionchange",later);
+addEventListener("scroll",function(){post({scroll:true,top:scrollY,left:scrollX})},true);
 addEventListener("message",function(e){if(e.source===parent&&e.data&&e.data.cliUiClear===t){var s=getSelection();s&&s.removeAllRanges()}});
+addEventListener("message",function(e){if(e.source===parent&&e.data&&e.data.cliUiRestore===t)scrollTo(Number(e.data.left)||0,Number(e.data.top)||0)});
 document.addEventListener("click",function(e){var a=e.target&&e.target.closest&&e.target.closest('a[href^="#"]');if(!a)return;e.preventDefault();
 var id=decodeURIComponent(a.getAttribute("href").slice(1)),el=id?document.getElementById(id)||document.getElementsByName(id)[0]:document.body;el&&el.scrollIntoView()});})();`;
 }
@@ -41,10 +43,10 @@ export function bridgeDoc(html: string, opts: { token: string; base?: string })
   const head = `<meta http-equiv="Content-Security-Policy" content="${escAttr(csp)}">`
     + (opts.base ? `<base href="${escAttr(opts.base)}">` : "")
     + `<script nonce="${opts.token}">${bridgeScript(opts.token)}</script>`;
-  // 插在 <head> 里最前面；没有 <head> 就插在 doctype 后面（解析器会自动补出 head），不放到 doctype 前面免得变成怪异模式。
-  const headTag = /<head(\s[^>]*)?>/i.exec(html);
-  if (headTag) { const at = headTag.index + headTag[0].length; return html.slice(0, at) + head + html.slice(at); }
-  const doctype = /^\s*<!doctype[^>]*>/i.exec(html);
-  if (doctype) return doctype[0] + head + html.slice(doctype[0].length);
-  return head + html;
+  // 只保留首部完整、常见的 doctype；其他原件内容必须全部位于 CSP 和桥之后。
+  // 不搜索原件中的 <head>：它可能在注释 / 脚本字符串中，未闭合标签也会令全文正则反复回溯。
+  // 有界首部匹配同时避开带引号的异常 doctype 把策略吞进声明里的情况。
+  const doctype = /^(?:\uFEFF)?[ \t\r\n\f]*(<!doctype[ \t\r\n\f]+html(?:[ \t\r\n\f]+(?:public[ \t\r\n\f]+(?:"[^"<>\0]*"|'[^'<>\0]*')(?:[ \t\r\n\f]+(?:"[^"<>\0]*"|'[^'<>\0]*'))?|system[ \t\r\n\f]+(?:"[^"<>\0]*"|'[^'<>\0]*')))?[ \t\r\n\f]*>)/i.exec(html.slice(0, 4096));
+  // 解析器会自动建立 head，再读取原件的 html/head/body，保留文档内容及 html 属性。
+  return doctype ? doctype[1] + head + html.slice(doctype[0].length) : "<!doctype html>" + head + html;
 }

package/src/board/htmlReading.ts

@@ -0,0 +1,148 @@
+import { Parser } from "htmlparser2";
+
+export interface HtmlReadingBlock {
+  kind: "heading" | "paragraph" | "list-item" | "code" | "table-row" | "image";
+  text: string;
+  level?: number;
+}
+export interface HtmlReadingPage { blocks: HtmlReadingBlock[]; textLength: number }
+export interface HtmlReadingResult {
+  pages: HtmlReadingPage[];
+  pageCount: number;
+  pageOffset: number;
+  limited: boolean;
+  reason?: "depth" | "markup";
+  complete: boolean;
+}
+
+const BATCH = 8 * 1024, BLOCK_TEXT = 8 * 1024, PAGE_TEXT = 16 * 1024;
+const TOKEN_GAP = 64 * 1024, EMPTY_TAGS = 100_000;
+const ignored = new Set(["head", "script", "style", "iframe", "object", "embed", "svg", "math", "canvas", "template", "video", "audio"]);
+const boundaries = new Set(["p", "div", "section", "article", "main", "header", "footer", "nav", "aside", "blockquote", "figure", "figcaption", "address", "details", "summary", "dl", "dt", "dd", "ul", "ol", "li", "pre", "table", "tr", "hr", "h1", "h2", "h3", "h4", "h5", "h6"]);
+interface Frame { tag: string; skipped: boolean; kind?: HtmlReadingBlock["kind"]; level?: number; count?: number; marker?: string; alt?: string }
+
+/** Static reader only: outputs text, never markup, attributes, CSS or resource URLs.
+ * Reparse each verified prefix. Only call end() at actual EOF, so partial tags/entities
+ * remain pending instead of being mistaken for completed source content.
+ */
+export async function readHtmlSections(text: string, options: { signal?: AbortSignal; eof?: boolean; page?: number } = {}): Promise<HtmlReadingResult> {
+  const pages: HtmlReadingPage[] = [], stack: Frame[] = [];
+  const target = options.page === undefined ? undefined : Math.max(0, Number.isFinite(options.page) ? Math.floor(options.page) : 0);
+  let currentPage: HtmlReadingPage | undefined, selectedPage: HtmlReadingPage | undefined, pageCount = 0;
+  let active: HtmlReadingBlock | undefined, reason: HtmlReadingResult["reason"], emptyTags = 0;
+  const check = () => { if (options.signal?.aborted) throw new DOMException("已取消", "AbortError"); };
+  const emit = () => {
+    if (!active) return;
+    const block = active; active = undefined;
+    if (block.kind !== "code") block.text = block.text.trim();
+    if (!block.text.trim()) return;
+    if (!currentPage || currentPage.blocks.length >= 64 || currentPage.textLength + block.text.length > PAGE_TEXT) {
+      currentPage = { blocks: [], textLength: 0 }; pageCount++;
+      if (target === undefined) pages.push(currentPage);
+      else if (pageCount - 1 === target) selectedPage = currentPage;
+    }
+    // With a requested page, all other completed pages are released immediately.
+    // Keep the last page too, so a shortened revision can fall back without another scan.
+    currentPage.blocks.push(block); currentPage.textLength += block.text.length;
+  };
+  const context = (): Frame | undefined => {
+    // A paragraph inside a cell/code block must not break its enclosing row/code.
+    const fixed = stack.find(frame => frame.kind === "code" || frame.kind === "table-row");
+    const closest = [...stack].reverse();
+    return fixed ?? closest.find(frame => frame.kind && frame.kind !== "paragraph") ?? closest.find(frame => frame.kind);
+  };
+  const append = (data: string) => {
+    if (!data || stack[stack.length - 1]?.skipped || reason) return;
+    const frame = context(), kind = frame?.kind ?? "paragraph", level = frame?.level;
+    if (kind !== "code") data = data.replace(/[ \t\r\n\f]+/g, " ");
+    if (kind !== "code" && !data.trim() && !active) return;
+    if (data.trim()) emptyTags = 0;
+    if (active && (active.kind !== kind || active.level !== level)) emit();
+    if (frame?.marker && data.trim()) { data = frame.marker + data.trimStart(); frame.marker = undefined; }
+    let offset = 0;
+    while (offset < data.length) {
+      active ??= { kind, text: "", ...(level === undefined ? {} : { level }) };
+      if (kind !== "code" && data[offset] === " " && (!active.text || active.text.endsWith(" "))) offset++;
+      if (offset >= data.length) break;
+      let take = Math.min(BLOCK_TEXT - active.text.length, data.length - offset);
+      // Do not cut an emoji/supplementary character into two React text blocks.
+      const last = data.charCodeAt(offset + take - 1), next = data.charCodeAt(offset + take);
+      if (last >= 0xd800 && last <= 0xdbff && next >= 0xdc00 && next <= 0xdfff) take--;
+      if (!take) { emit(); continue; }
+      active.text += data.slice(offset, offset + take); offset += take;
+      if (active.text.length >= BLOCK_TEXT) emit();
+    }
+  };
+  const stop = (why: NonNullable<HtmlReadingResult["reason"]>) => { reason = why; parser.pause(); };
+  const parser = new Parser({
+    onopentagname(tag) {
+      if (reason) return;
+      if (stack.length >= 32) { stop("depth"); return; }
+      if (++emptyTags > EMPTY_TAGS) { stop("markup"); return; }
+      const skipped = !!stack[stack.length - 1]?.skipped || ignored.has(tag);
+      const fixed = context();
+      if (!skipped && (boundaries.has(tag) || tag === "img") && fixed?.kind !== "code" && fixed?.kind !== "table-row") emit();
+      const frame: Frame = { tag, skipped };
+      if (tag.length === 2 && tag[0] === "h" && tag[1] >= "1" && tag[1] <= "6") { frame.kind = "heading"; frame.level = Number(tag[1]); }
+      else if (tag === "pre") frame.kind = "code";
+      else if (tag === "tr") { frame.kind = "table-row"; frame.count = 0; }
+      else if (tag === "li") {
+        const list = [...stack].reverse().find(parent => parent.tag === "ol" || parent.tag === "ul");
+        frame.kind = "list-item";
+        frame.marker = list?.tag === "ol" ? `${list.count = (list.count ?? 0) + 1}. ` : "• ";
+      }
+      else if (boundaries.has(tag)) frame.kind = "paragraph";
+      if (!skipped && (tag === "td" || tag === "th")) {
+        const row = stack.find(parent => parent.tag === "tr");
+        if (row && (row.count = (row.count ?? 0) + 1) > 1) append(" | ");
+      }
+      stack.push(frame);
+      if (!skipped && tag === "br") append(fixed?.kind === "code" ? "\n" : " ");
+    },
+    // No onopentag callback: htmlparser2 does not build an attributes object.
+    // The one permitted attribute is copied as bounded, inert text.
+    onattribute(name, value) {
+      const frame = stack[stack.length - 1];
+      if (!reason && frame?.tag === "img" && !frame.skipped && name === "alt") frame.alt = value.slice(0, BLOCK_TEXT - 6);
+    },
+    ontext: append,
+    onclosetag(tag) {
+      if (reason) return;
+      const frame = stack[stack.length - 1];
+      if (!frame || frame.tag !== tag) return;
+      if (!frame.skipped) {
+        if (tag === "img") {
+          emit(); active = { kind: "image", text: frame.alt?.trim() ? `[图片：${frame.alt.trim()}]` : "[图片]" }; emit();
+        }
+        const fixed = context();
+        if (boundaries.has(tag) && (fixed?.kind !== "code" && fixed?.kind !== "table-row" || fixed === frame)) emit();
+      }
+      stack.pop();
+    },
+  }, { decodeEntities: true });
+  check();
+  let yieldedAt = performance.now();
+  try {
+    for (let offset = 0; offset < text.length && !reason;) {
+      check(); let end = Math.min(text.length, offset + BATCH);
+      const last = text.charCodeAt(end - 1), next = text.charCodeAt(end);
+      if (last >= 0xd800 && last <= 0xdbff && next >= 0xdc00 && next <= 0xdfff) end--;
+      parser.write(text.slice(offset, end));
+      offset = end;
+      // Bound parser retention for a single unfinished comment/tag/attribute.
+      if (!reason && end - Math.max(parser.startIndex, parser.endIndex) > TOKEN_GAP) stop("markup");
+      if (performance.now() - yieldedAt >= 8) {
+        await new Promise<void>(resolve => setTimeout(resolve, 0)); check(); yieldedAt = performance.now();
+      }
+    }
+    check();
+    if (options.eof && !reason) parser.end();
+    emit();
+    const selected = selectedPage ?? currentPage;
+    return {
+      pages: target === undefined ? pages : selected ? [selected] : [], pageCount,
+      pageOffset: target === undefined ? 0 : selectedPage ? target : Math.max(0, pageCount - 1),
+      limited: !!reason, ...(reason ? { reason } : {}), complete: !!options.eof && !reason,
+    };
+  } finally { parser.reset(); }
+}