docs(tests): explain model preview dependencies and loading completion

tests/headless/model-stream.test.mjs

@@ -29,6 +29,7 @@ const scope={accountId:account,workspaceId:workspace,projectId:null,canvasId:roo
 // 逐字节传入 Unicode/换行，依次输出接收头、元素 delta、最终 ready；正文/墓碑及总 byteLength 完整，记录冻结。
 test('stream decoder frames split UTF8/newlines, emits deltas and validates one final complete model',async()=>{
  const bytes=encode(records());/* 每批只发一个字节，主动拆开多字节 UTF-8 与记录边界。 */ async function* split(){for(const byte of bytes)yield Uint8Array.of(byte);}
+ // collect 会读到生成器 EOF：看到 complete 记录还不够，尾部 framing 校验也必须成功。
  const chunks=await collect(decodeModelStream(split(),root,registry,signal()));
  assert.deepEqual(chunks.map(chunk=>[chunk.sequence,chunk.complete,chunk.value.status]),[[0,false,'receiving'],[1,false,'receiving'],[2,true,'ready']]);
  assert.equal(chunks[1].value.elements[0].data.text,'🙂');assert.equal(chunks[2].value.document.elements.get('a').data.title,'中文');assert.equal(chunks[2].value.document.tombstones.get('old'),2);assert.equal(chunks.reduce((sum,chunk)=>sum+chunk.byteLength,0),bytes.length);assert.ok(Object.isFrozen(chunks[1].value.elements[0]));
@@ -63,6 +64,7 @@ test('malformed tails retain read deltas without yielding an authoritative model
 test('terminal record still requires EOF; trailing garbage rejects rather than opening a baseline',async()=>{
  const gate={},rows=records();let release;gate.promise=new Promise(resolve=>release=resolve);
  /* complete 之后仍阻塞迭代器 EOF，之后追加垃圾，检查 ready 不会过早成功。 */ async function* trailing(){yield encode(rows);await gate.promise;yield new TextEncoder().encode('x\n');}
+ // trailing 先交出终态记录再等待，检测 ready 是否在底层迭代结束前过早解决；放行后追加垃圾使它最终拒绝。
  const loader=createScopedLoader({load:createFoundryModelLoader({workspaceId:workspace,registry,transport:async()=>({status:200,body:null,stream:trailing()})}),current:()=>true}),handle=loader.acquire(scope);let ready=false;handle.ready.then(()=>ready=true,()=>{});
  try{while(handle.getSnapshot().chunks.length<2)await new Promise(resolve=>setImmediate(resolve));assert.equal(ready,false);release();await assert.rejects(handle.ready);assert.equal(handle.getSnapshot().status,'failed-with-partial');}finally{release();handle.release();loader.close();}
 });