docs(canvas): explain compute workers and display resource lifetimes

src/lib/canvas-runtime/browser-digests.ts

@@ -1,14 +1,23 @@
+/**
+ * 浏览器摘要适配：每个活跃任务创建一个 module Worker，由通用 digest pool 限制并发。
+ * 没有 Worker 时才使用分块 fallback；Worker 创建/运行失败明确报错，不悄悄把整缓冲原生哈希移到 UI 线程。
+ */
 import {fault} from '../canvas-core/values.ts';
 import {createDigestPool} from './digest-pool.ts';
 /** Browser capability stays at the adapter; WorkspaceRuntime owns the pool's lifetime. */
+/** 构建 workspace 可共享的 DigestPort；任务 ID/长度/版本共同验证响应归属。 */
 export function createBrowserDigests(){
   let next=0;
   return createDigestPool({execute:typeof Worker==='undefined'?undefined:(bytes,signal)=>new Promise<string>((resolve,reject)=>{
     if(signal.aborted){reject(fault('import_aborted'));return;}
+    // 每请求独立 Worker，所以成功、失败或 abort 都可直接 terminate，不影响其它任务。
     let worker:Worker;try{worker=new Worker(new URL('./digest.worker.ts',import.meta.url),{type:'module'});}catch{reject(fault('digest_worker_unavailable'));return;}
     const id=++next;let done=false;
+    /** 幂等完成：解绑所有消息/错误/abort 监听并终止 Worker，防止迟到响应泄漏或重复 resolve。 */
     const finish=(error?:unknown,sha256?:string)=>{if(done)return;done=true;signal.removeEventListener('abort',abort);worker.onmessage=null;worker.onerror=null;worker.onmessageerror=null;worker.terminate();if(error)reject(error);else resolve(sha256!);},abort=()=>finish(fault('import_aborted'));
+    // 消息须精确匹配版本、任务 ID 和输入长度，再验64位十六进制摘要；已知错误也必须匹配身份。
     signal.addEventListener('abort',abort,{once:true});worker.onmessage=event=>{const value=event.data;if(value?.version===1&&value.id===id&&value.byteLength===bytes.size&&value.error==='digest_worker_failed'){finish(fault('digest_worker_failed'));return;}if(!value||value.version!==1||value.id!==id||value.byteLength!==bytes.size||typeof value.sha256!=='string'||!(/^[a-f0-9]{64}$/.test(value.sha256)))finish(fault('invalid_digest_response'));else finish(undefined,value.sha256);};worker.onerror=event=>{event.preventDefault();finish(fault('digest_worker_failed'));};worker.onmessageerror=()=>finish(fault('invalid_digest_response'));
+    // Blob 通过结构化克隆传递，不在 UI 主线程先读取整份 arrayBuffer。
     try{worker.postMessage({version:1,id,bytes});}catch{finish(fault('digest_worker_failed'));}
   })});
 }