Show dependency-closed model prefixes before full canvas loading

src/components/canvas/headless-graph-canvas.tsx

@@ -1,7 +1,7 @@
 "use client";
 
 import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore, type ContextType } from "react";
-import { Background, BackgroundVariant, ConnectionMode, ReactFlow, ReactFlowProvider, useReactFlow, type Connection } from "@xyflow/react";
+import { Background, BackgroundVariant, ConnectionMode, ReactFlow, ReactFlowProvider, useReactFlow, type Connection,type Viewport } from "@xyflow/react";
 import { Copy, Download, Frame, Hand, ImagePlus, Maximize, Minus, Ratio, MousePointer2, Plus, Redo2, Sparkles, StickyNote, Type, Undo2 } from "lucide-react";
 import type { Board } from "@/lib/workspace";
 import type { ReactRenderers } from "@/lib/canvas-bindings/react-renderers";
@@ -261,8 +261,9 @@ function CanvasView({ engine, board, viewId, renderers }: { engine: ProjectEngin
     {error && <div className={styles.error} role="alert">{error} {displayState.engine===engine&&displayState.viewId===viewId&&displayState.failures>0&&<button onClick={()=>{setError('');resourceView.current?.retry();}}>重试图片</button>}<button onClick={() => setError('')}>关闭</button></div>}
   </div>;
 }
-export default function HeadlessGraphCanvas({ engine, board, renderers=defaultCanvasRenderers }: { engine: ProjectEngine; board: Board; renderers?:ReactRenderers }) {
+export default function HeadlessGraphCanvas({ engine, board, renderers=defaultCanvasRenderers,initialViewport }: { engine: ProjectEngine; board: Board; renderers?:ReactRenderers;initialViewport?:Viewport }) {
+  const [handoffViewport]=useState(initialViewport);
   const [viewId] = useState(() => crypto.randomUUID()), [attached, setAttached] = useState(false);
-  useEffect(() => { const detach = engine.sessions.attach(viewId, board.id); setAttached(true); return () => { setAttached(false); detach(); }; }, [engine, viewId, board.id]);
+  useEffect(() => { const detach = engine.sessions.attach(viewId, board.id);if(handoffViewport)engine.sessions.viewport(viewId,handoffViewport); setAttached(true); return () => { setAttached(false); detach(); }; }, [engine, viewId, board.id,handoffViewport]);
   return attached ? <ReactFlowProvider><CanvasView engine={engine} board={board} viewId={viewId} renderers={renderers} /></ReactFlowProvider> : <p role="status">正在准备画布…</p>;
 }

src/components/canvas/loading-graph-canvas.tsx

@@ -0,0 +1,40 @@
+"use client";
+
+import {useEffect,useMemo,useRef} from 'react';
+import {Background,BackgroundVariant,ReactFlow,useReactFlow,type Viewport,type NodeTypes} from '@xyflow/react';
+import type {Registry} from '@/lib/canvas-core/types';
+import type {ModelPreview} from '@/lib/canvas-runtime/model-preview';
+import type {ReactRenderers} from '@/lib/canvas-bindings/react-renderers';
+import {projectCanvas} from '@/lib/canvas-bindings/projection';
+import {CanvasRendererCommandsContext,type CanvasRendererCommands} from '@/lib/canvas-bindings/renderer-context';
+import {UnsupportedNode,UnsupportedEdge} from './unsupported-elements';
+import styles from './canvas.module.css';
+
+const reject=()=>({status:'rejected' as const,code:'model_loading',targets:[]});
+const commands:CanvasRendererCommands=Object.freeze({dispatch:reject,transaction:reject});
+function InitialPreviewViewport({onViewport,nodeCount}:{onViewport(viewport:Viewport):void;nodeCount:number}){
+ const flow=useReactFlow(),fitted=useRef(false),notify=useRef(onViewport);notify.current=onViewport;
+ useEffect(()=>{if(!flow.viewportInitialized||fitted.current||!nodeCount)return;fitted.current=true;let active=true;void flow.fitView({padding:.2,maxZoom:1}).then(()=>{if(active)notify.current(flow.getViewport());});return()=>{active=false;};},[flow,nodeCount]);
+ return null;
+}
+/** Render the validated read prefix directly. No temporary editor, ACK, ledger or
+ * writable engine is constructed, and no partial model enters durable storage. */
+export default function LoadingGraphCanvas({preview,canvasId,registry,renderers,workspaceId,onViewport}: {preview:ModelPreview;canvasId:string;workspaceId:string;registry:Registry;renderers:ReactRenderers;onViewport(viewport:Viewport):void}){
+ // Without a declared reference schema, use the existing opaque placeholder
+ // until the complete document is available to the installed renderer.
+ const catalog=useMemo(()=>({...renderers.catalog,resolve(element:Parameters<ReactRenderers['catalog']['resolve']>[0]){return registry.components.get(element.componentId)?.copy?renderers.catalog.resolve(element):undefined;}}),[registry,renderers]);
+ const projection=useMemo(()=>{
+  const value=projectCanvas(preview.document,canvasId,registry,new Set(),()=>undefined,undefined,catalog);
+  return{nodes:value.nodes.map(node=>({...node,draggable:false,selectable:false,focusable:false,connectable:false,style:{...node.style,pointerEvents:'none' as const},data:{...node.data,...(registry.resolve(preview.document.elements.get(node.id)!)==='known'&&typeof node.data.assetId==='string'&&registry.components.get(preview.document.elements.get(node.id)!.componentId)?.resourceFields?.includes('assetId')?{src:`/api/foundry/workspaces/${encodeURIComponent(workspaceId)}/assets/${encodeURIComponent(node.data.assetId)}?variant=preview`}:{})}})),edges:value.edges.map(edge=>({...edge,selectable:false,focusable:false}))};
+ },[preview.document,canvasId,workspaceId,registry,catalog]);
+ const nodeTypes=useMemo<NodeTypes>(()=>{const result:NodeTypes={};for(const [id,Renderer]of Object.entries({...renderers.nodeTypes,unsupported:UnsupportedNode}))result[id]=props=><div inert style={{width:'100%',height:'100%'}}><Renderer {...props}/></div>;return result;},[renderers]),edgeTypes=useMemo(()=>({...renderers.edgeTypes,unsupported:UnsupportedEdge}),[renderers]);
+ return <div className={styles.editor} data-canvas-loading-preview aria-label="正在加载的画布，只读预览">
+  <CanvasRendererCommandsContext.Provider value={commands}>
+   <ReactFlow nodes={projection.nodes} edges={projection.edges} nodeTypes={nodeTypes} edgeTypes={edgeTypes} nodesDraggable={false} nodesConnectable={false} elementsSelectable={false} nodesFocusable={false} edgesFocusable={false} panOnDrag panOnScroll zoomOnScroll={false} minZoom={.1} maxZoom={4} deleteKeyCode={null} onMoveEnd={(_,viewport)=>onViewport(viewport)}>
+    <InitialPreviewViewport onViewport={onViewport} nodeCount={projection.nodes.length}/>
+    <Background variant={BackgroundVariant.Dots} gap={24} size={1} />
+   </ReactFlow>
+  </CanvasRendererCommandsContext.Provider>
+  <p role="status" style={{position:'absolute',left:'50%',transform:'translateX(-50%)',bottom:16,pointerEvents:'none'}}>正在加载… {preview.receivedElements}/{preview.totalElements}，加载期间可浏览</p>
+ </div>;
+}

src/components/workspace/graph-page.tsx

@@ -1,6 +1,8 @@
 "use client";
 
 import { useEffect, useRef, useState } from "react";
+import type {Viewport} from '@xyflow/react';
+import type {ModelPreview} from '@/lib/canvas-runtime/model-preview';
 import { useRouter, useSearchParams } from "next/navigation";
 import { api, errorText } from "@/lib/api";
 import { readDemoBoards } from "@/lib/demo-workspace";
@@ -15,6 +17,7 @@ import dynamic from "next/dynamic";
 const GraphCanvas = dynamic(() => import("@/components/canvas/graph-canvas"), { ssr: false, loading: () => <p role="status">正在准备画布…</p> });
 
 const HeadlessGraphCanvas = dynamic(() => import("@/components/canvas/headless-graph-canvas"), { ssr: false, loading: () => <p role="status">正在准备画布…</p> });
+const LoadingGraphCanvas=dynamic(()=>import("@/components/canvas/loading-graph-canvas"),{ssr:false});
 type Loaded = { board: Board; snapshot?: CanvasSnapshot; route: string; engine?: ProjectEngine };
 export default function GraphPage({ workspaceId, boardId }: { workspaceId: string; boardId: string }) {
   const renderers=useCanvasRenderers();
@@ -24,11 +27,13 @@ export default function GraphPage({ workspaceId, boardId }: { workspaceId: strin
   const route = workspaceId + ":" + boardId;
   const { board: activeBoard, setBoard: setActiveBoard } = useActiveBoard();
   const [loaded, setLoaded] = useState<Loaded | null>(null);
+  const [preview,setPreview]=useState<{board:Board;value:ModelPreview;route:string}|null>(null);
+  const previewViewport=useRef<Viewport|undefined>(undefined);
   const [error, setError] = useState("");
   const [retry, setRetry] = useState(0);
   const navigationGeneration=useRef(0);
   useEffect(() => {
-    setLoaded(null); setError("");
+    setLoaded(null);setPreview(null);previewViewport.current=undefined; setError("");
     if (demo) {
       const item = readDemoBoards(workspaceId).find((board) => matchesRef(board, boardId));
       if (item) setLoaded({ board: item, route });
@@ -39,25 +44,27 @@ export default function GraphPage({ workspaceId, boardId }: { workspaceId: strin
     const controller = new AbortController();
     const startingIdentity=runtimeHost.identity();let currentIdentity:(()=>boolean)|undefined;
     loadCanvasEntry({ request: api, workspaceRef: workspaceId, boardRef: boardId, registry: runtimeHost.registry, signal: controller.signal,navigationGeneration:++navigationGeneration.current,
-      readModel:input=>{const identity=runtimeHost.identity();if(identity.authEpoch!==startingIdentity.authEpoch&&identity.accountId!==input.accountId)throw new Error('identity_changed');currentIdentity=runtimeHost.bindAccount(input.accountId);return runtimeHost.loadModel(input.accountId,input.workspaceId,input.canvasId,{signal:input.signal,navigationGeneration:input.navigationGeneration});},
+      onPreview:(value,board)=>{if(active&&(!currentIdentity||currentIdentity())&&value.document.canvases.has(board.id))setPreview({board,value,route});},
+      readModel:input=>{const identity=runtimeHost.identity();if(identity.authEpoch!==startingIdentity.authEpoch&&identity.accountId!==input.accountId)throw new Error('identity_changed');currentIdentity=runtimeHost.bindAccount(input.accountId);return runtimeHost.loadModel(input.accountId,input.workspaceId,input.canvasId,{signal:input.signal,navigationGeneration:input.navigationGeneration,onPreview:input.onPreview});},
     }).then(async result => {
       if (!active||currentIdentity&&!currentIdentity()) return;
-      if (result.mode === 'legacy') { setLoaded({ board: result.board, snapshot: result.snapshot, route }); return; }
+      if (result.mode === 'legacy') { setLoaded({ board: result.board, snapshot: result.snapshot, route });setPreview(null); return; }
       const engine = await runtimeHost.workspace(result.profile.id, result.board.workspace_id).open(result.model.document, result.model.versions);
-      if (active&&(!currentIdentity||currentIdentity())) setLoaded({ board: result.board, engine, route });
+      if (active&&(!currentIdentity||currentIdentity())){setLoaded({ board: result.board, engine, route });setPreview(null);}
     })
       .catch((error) => { if (active) { setError(errorText(error)); if (error.message === "invalid_session") router.replace("/login"); } });
     return () => { active = false; controller.abort(); };
   }, [workspaceId, boardId, route, demo, retry, router, runtimeHost]);
   const current = loaded?.route === route ? loaded : null;
-  const board = current?.board;
+  const currentPreview=preview?.route===route?preview:null;
+  const board = current?.board??currentPreview?.board;
   useEffect(() => {
     if (board) setActiveBoard({ id: board.id, slug: board.slug, workspace_id: board.workspace_id, workspace_ref: workspaceId, title: board.title });
     return () => setActiveBoard(null);
   }, [board, workspaceId, setActiveBoard]);
   const displayBoard = board && activeBoard?.id === board.id && activeBoard.workspace_id === board.workspace_id ? { ...board, title: activeBoard.title } : board;
-  return <main className={styles.graph} aria-label={displayBoard ? displayBoard.title + " · 无限图谱" : "无限图谱"} aria-busy={!board && !error}>
-    {displayBoard && current?.engine ? <HeadlessGraphCanvas key={displayBoard.workspace_id + ":" + displayBoard.id} board={displayBoard} engine={current.engine} renderers={renderers} /> : displayBoard ? <GraphCanvas key={displayBoard.workspace_id + ":" + displayBoard.id} board={displayBoard} snapshot={current?.snapshot} /> : <div className={styles.graphSurface} aria-label="正在读取画布" />}
+  return <main className={styles.graph} aria-label={displayBoard ? displayBoard.title + " · 无限图谱" : "无限图谱"} aria-busy={!current && !error}>
+    {displayBoard && current?.engine ? <HeadlessGraphCanvas key={displayBoard.workspace_id + ":" + displayBoard.id} board={displayBoard} engine={current.engine} renderers={renderers} initialViewport={previewViewport.current} /> : displayBoard&&currentPreview ? <LoadingGraphCanvas key={displayBoard.workspace_id+":"+displayBoard.id} preview={currentPreview.value} canvasId={displayBoard.id} workspaceId={displayBoard.workspace_id} registry={runtimeHost.registry} renderers={renderers} onViewport={viewport=>{previewViewport.current=viewport;}} /> : displayBoard ? <GraphCanvas key={displayBoard.workspace_id + ":" + displayBoard.id} board={displayBoard} snapshot={current?.snapshot} /> : <div className={styles.graphSurface} aria-label="正在读取画布" />}
     {error ? <div className={styles.graphStatus} role="alert">{error} <button onClick={() => setRetry((value) => value + 1)}>重新加载</button></div> : !board && <p className={styles.graphStatus} role="status">正在打开图谱…</p>}
   </main>;
 }

src/lib/api.ts

@@ -59,6 +59,12 @@ export async function startOAuth(provider: "google" | "slack") {
 export const errorText = (error: unknown) => {
   const code = error instanceof Error ? error.message : "";
   const messages: Record<string, string> = {
+    invalid_model_stream: "画布返回的数据无法解析，请重新加载。",
+    incomplete_model_stream: "画布数据未加载完整，请重新加载。",
+    unsupported_model_stream: "当前画布加载格式暂不受支持，请更新后重试。",
+    model_stream_budget: "画布数据量超过当前加载上限，请联系支持。",
+    load_snapshot_changed: "加载期间画布快照发生变化，请重新加载。",
+    model_loading: "画布尚在加载，请等待加载完成后编辑。",
     identity_changed: "账户已变化，当前画布已停止同步，请重新打开。",
     engine_closing: "画布正在关闭，本地修改会保留用于恢复。",
     storage_scope_in_use: "这张图谱已在另一个标签页中打开，请先关闭那里的编辑器。",

src/lib/canvas-core/document.ts

@@ -34,6 +34,17 @@ export function commonCanvas(document: Document, left: Id, right: Id): Id {
   if (!result) throw fault('no_common_canvas', [left, right]);
   return result;
 }
+/** Validate one record before its graph dependencies have arrived. This does not
+ * prove owner membership, endpoint existence or connection common ownership. */
+export function validateElementRecord(element: ElementRecord, registry: Registry, tombstones: ReadonlyMap<Id,number> = new Map(), componentData = true): void {
+  if (!element || !validJson(element) || typeof element.id !== 'string' || !element.id || typeof element.ownerCanvasId !== 'string' || !element.ownerCanvasId || typeof element.componentId !== 'string' || !element.componentId || !['node','connection'].includes(element.structure) || !Number.isSafeInteger(element.incarnation) || element.incarnation < 1 || !Number.isSafeInteger(element.dataVersion) || element.dataVersion < 1 || !element.data || typeof element.data !== 'object' || Array.isArray(element.data) || !validJson(element.data)) throw fault('invalid_element', [element?.id]);
+  const dead=tombstones.get(element.id);if(dead!==undefined&&element.incarnation<=dead)throw fault('stale_incarnation',[element.id]);
+  const definition=registry.components.get(element.componentId);
+  if(componentData&&registry.resolve(element)==='known'&&(!definition||definition.structure!==element.structure||!definition.validate(element.data)))throw fault('invalid_component_data',[element.id]);
+  if(element.structure==='node'){if(!geometryValid(element.geometry))throw fault('invalid_geometry',[element.id]);}
+  else if(!element.source||!element.target||typeof element.source.elementId!=='string'||!element.source.elementId||typeof element.target.elementId!=='string'||!element.target.elementId||[element.source,element.target].some(endpoint=>endpoint.portId!==undefined&&(typeof endpoint.portId!=='string'||!endpoint.portId))||!validJson(element.path))throw fault('invalid_endpoint',[element.id]);
+}
+
 /** Cooperative validation over an immutable document; synchronous callers drain the same checks. */
 function* validateDocumentChecks(document: Document, registry: Registry, componentData:boolean): Generator<void, void> {
   if (!document.canvases.size) throw fault('missing_root');
@@ -52,15 +63,9 @@ function* validateDocumentChecks(document: Document, registry: Registry, compone
   if (roots !== 1) throw fault('invalid_roots');
   for (const element of document.elements.values()) {
     yield;
-    if (typeof element.id !== 'string' || !element.id || typeof element.componentId !== 'string' || !element.componentId || !['node','connection'].includes(element.structure) || !document.canvases.has(element.ownerCanvasId) || !Number.isSafeInteger(element.incarnation) || element.incarnation < 1 || !Number.isSafeInteger(element.dataVersion) || element.dataVersion < 1 || !element.data || typeof element.data !== 'object' || Array.isArray(element.data) || !validJson(element.data)) throw fault('invalid_element', [element.id]);
-    const dead = document.tombstones.get(element.id);
-    if (dead !== undefined && element.incarnation <= dead) throw fault('stale_incarnation', [element.id]);
-    const definition = registry.components.get(element.componentId);
-    if (componentData && registry.resolve(element) === 'known' && (!definition || definition.structure !== element.structure || !definition.validate(element.data))) throw fault('invalid_component_data', [element.id]);
-    if (element.structure === 'node') {
-      if (!geometryValid(element.geometry)) throw fault('invalid_geometry', [element.id]);
-    } else {
-      if (!element.source || !element.target || typeof element.source.elementId !== 'string' || typeof element.target.elementId !== 'string' || [element.source,element.target].some(endpoint => endpoint.portId !== undefined && (typeof endpoint.portId !== 'string' || !endpoint.portId))) throw fault('invalid_endpoint', [element.id]);
+    validateElementRecord(element, registry, document.tombstones, componentData);
+    if (!document.canvases.has(element.ownerCanvasId)) throw fault('invalid_element', [element.id]);
+    if (element.structure === 'connection') {
       const source = document.elements.get(element.source.elementId), target = document.elements.get(element.target.elementId);
       if (!source || !target || source.structure !== 'node' || target.structure !== 'node' || !validJson(element.path)) throw fault('invalid_endpoint', [element.id]);
       if (commonCanvas(document, source.ownerCanvasId, target.ownerCanvasId) !== element.ownerCanvasId) throw fault('invalid_connection_owner', [element.id]);

src/lib/canvas-entry.ts

@@ -1,3 +1,4 @@
+import type {ModelPreview} from './canvas-runtime/model-preview.ts';
 import type { Profile } from './api.ts';
 import type { CanvasRequest } from './canvas-sync.ts';
 import { decodeSnapshot } from './canvas-sync.ts';
@@ -7,14 +8,14 @@ import type { Registry } from './canvas-core/types.ts';
 import { loadFoundryModel, type ModelLoad, type ServiceTransport } from './canvas-service/foundry.ts';
 
 /** Read canonical first: a migrated project must never be opened through snapshot writers. */
-export async function loadCanvasEntry(options: { request: CanvasRequest; workspaceRef: string; boardRef: string; registry: Registry; transport?(accountId: string): ServiceTransport; readModel?(input:{accountId:string;workspaceId:string;canvasId:string;signal?:AbortSignal;navigationGeneration:number}):Promise<ModelLoad>;signal?: AbortSignal;navigationGeneration?:number }) {
+export async function loadCanvasEntry(options: { request: CanvasRequest; workspaceRef: string; boardRef: string; registry: Registry; transport?(accountId: string): ServiceTransport; readModel?(input:{accountId:string;workspaceId:string;canvasId:string;signal?:AbortSignal;navigationGeneration:number;onPreview?:(preview:ModelPreview)=>void}):Promise<ModelLoad>;onPreview?:(preview:ModelPreview,board:Board,profile:Profile)=>void;signal?: AbortSignal;navigationGeneration?:number }) {
   const path = `workspaces/${encodeURIComponent(options.workspaceRef)}/materials/${encodeURIComponent(options.boardRef)}`;
   const [board, profile] = await Promise.all([options.request<Board>(path, { signal: options.signal }), options.request<Profile>('profile', { signal: options.signal })]);
   options.signal?.throwIfAborted();
   if (board.kind !== 'board' || !matchesRef(board, options.boardRef) || !board.workspace_id || !profile.id) throw new Error('invalid_reference');
   if(!options.readModel&&!options.transport)throw new Error('model_loader_unavailable');
   try {
-    const model = options.readModel?await options.readModel({accountId:profile.id,workspaceId:board.workspace_id,canvasId:board.id,signal:options.signal,navigationGeneration:options.navigationGeneration??0}):await loadFoundryModel(options.transport!(profile.id), board.workspace_id, board.id, options.registry, options.signal);
+    const model = options.readModel?await options.readModel({accountId:profile.id,workspaceId:board.workspace_id,canvasId:board.id,signal:options.signal,navigationGeneration:options.navigationGeneration??0,...(options.onPreview?{onPreview:(preview:ModelPreview)=>options.onPreview!(preview,board,profile)}:{})}):await loadFoundryModel(options.transport!(profile.id), board.workspace_id, board.id, options.registry, options.signal);
     options.signal?.throwIfAborted();
     if (model.status === 'ready') return { mode: 'headless' as const, board, profile, model };
     // Existing projects keep their current editor until the user explicitly migrates them.

src/lib/canvas-runtime/host.ts

@@ -1,3 +1,4 @@
+import {createModelPreview,type ModelPreview} from './model-preview.ts';
 import type { Id, Registry } from '../canvas-core/types.ts';
 import { fault, readMap } from '../canvas-core/values.ts';
 import type { WorkspaceRuntime } from './workspace.ts';
@@ -5,7 +6,7 @@ import { createScopedLoader, type LoadPort, type ScopedLoader } from './loader.t
 import type { CanonicalReadUpdate } from './contracts.ts';
 
 /** Host lifetime matches the signed-in application, independently of navigation. */
-export function createRuntimeHost(options: { registry: Registry; workspace(accountId: Id, workspaceId: Id, authEpoch: number, current: () => boolean): WorkspaceRuntime; modelLoader?(accountId:Id,workspaceId:Id,authEpoch:number,current:()=>boolean):LoadPort<CanonicalReadUpdate>; onError?: (error: unknown) => void }) {
+export function createRuntimeHost(options: { registry: Registry; workspace(accountId: Id, workspaceId: Id, authEpoch: number, current: () => boolean): WorkspaceRuntime; modelLoader?(accountId:Id,workspaceId:Id,authEpoch:number,current:()=>boolean):LoadPort<CanonicalReadUpdate>; onError?: (error: unknown) => void; onObserverError?: (error: unknown) => void }) {
   let accountId: Id | null = null, authEpoch = 0, disposed = false;
   const workspaces = new Map<Id, WorkspaceRuntime>(), retired = new Set<WorkspaceRuntime>();
   const readers = new Map<Id, ScopedLoader<CanonicalReadUpdate>>();
@@ -27,14 +28,20 @@ export function createRuntimeHost(options: { registry: Registry; workspace(accou
     bindAccount(account: Id) { activate(account); const epoch = authEpoch; return () => !disposed && accountId === account && authEpoch === epoch; },
     identity: () => Object.freeze({ accountId, authEpoch }),
     getWorkspaces: () => readMap(workspaces),
-    async loadModel(account:Id,workspace:Id,canvas:Id,settings:{signal?:AbortSignal;navigationGeneration?:number}={}) {
+    async loadModel(account:Id,workspace:Id,canvas:Id,settings:{signal?:AbortSignal;navigationGeneration?:number;onPreview?:(preview:ModelPreview)=>void}={}) {
       activate(account);
       const readEpoch=authEpoch;
       if(!options.modelLoader)throw fault('model_loader_unavailable');
       let reader=readers.get(workspace);
       if(!reader){const epoch=authEpoch,current=()=>!disposed&&accountId===account&&authEpoch===epoch;reader=createScopedLoader({load:options.modelLoader(account,workspace,epoch,current),current:()=>current(),maxCacheEntries:0});readers.set(workspace,reader);}
-      const handle=reader.acquire({accountId:account,workspaceId:workspace,projectId:null,canvasId:canvas,viewKey:'canonical-project',format:'canonical-model-v1',queryFingerprint:'full-project',source:'foundry',authEpoch,navigationGeneration:settings.navigationGeneration??0},{signal:settings.signal});
-      try{const snapshot=await handle.ready;if(disposed||accountId!==account||authEpoch!==readEpoch)throw fault('identity_changed');const last=snapshot.chunks.at(-1);if(!last||!last.complete||last.value.status==='receiving')throw fault('incomplete_load');return last.value;}finally{handle.release();}
+      const preview=settings.onPreview?createModelPreview(options.registry):undefined;let seen=0,previewFailed=false;
+      const onUpdate=(state:import('./loader.ts').LoadSnapshot<CanonicalReadUpdate>)=>{
+        if(!preview||previewFailed||disposed||accountId!==account||authEpoch!==readEpoch||settings.signal?.aborted)return;
+        try{for(;seen<state.chunks.length;seen++){const chunk=state.chunks[seen],value=preview.update(chunk.value);if(chunk.value.status==='receiving'&&value)settings.onPreview?.(value);}}
+        catch(error){previewFailed=true;try{options.onObserverError?.(error);}catch{}}
+      };
+      const handle=reader.acquire({accountId:account,workspaceId:workspace,projectId:null,canvasId:canvas,viewKey:'canonical-project',format:'canonical-model-v1',queryFingerprint:'full-project',source:'foundry',authEpoch,navigationGeneration:settings.navigationGeneration??0},{signal:settings.signal,onUpdate});
+      try{const snapshot=await handle.ready;if(disposed||accountId!==account||authEpoch!==readEpoch)throw fault('identity_changed');const last=snapshot.chunks.at(-1);if(!last||!last.complete||last.value.status==='receiving')throw fault('incomplete_load');return last.value;}finally{handle.release();preview?.close();}
     },
     workspace(account: Id, workspace: Id) {
       activate(account);

src/lib/canvas-runtime/index.ts

@@ -22,3 +22,6 @@ export { createDigestPool } from './digest-pool.ts';
 export type { DigestPort } from './digest-pool.ts';
 export { createImageDecodePool } from './image-decoder.ts';
 export type { ImageDecoderPort, ImageDimensions, ImageDecodeState } from './image-decoder.ts';
+
+export {createModelPreview} from './model-preview.ts';
+export type {ModelPreview} from './model-preview.ts';

src/lib/canvas-runtime/model-preview.ts

@@ -0,0 +1,61 @@
+import type { CanvasRecord, Document, ElementRecord, Id, Registry } from '../canvas-core/types.ts';
+import { ancestors, createDocument, validateDocument, validateElementRecord } from '../canvas-core/document.ts';
+import { copyReferenceIds } from '../canvas-core/copy-paths.ts';
+import { clone, equal, fault, freeze, readMap } from '../canvas-core/values.ts';
+import type { CanonicalReadUpdate } from './contracts.ts';
+
+export type ModelPreview = { readonly document:Document;readonly receivedElements:number;readonly totalElements:number;readonly waitingElements:number;readonly complete:false };
+/** An ephemeral read projection. It owns neither a working document nor ACKs,
+ * history, operations, file bytes or a durable recovery cut. */
+export function createModelPreview(registry:Registry){
+ let header=false,finished=false,projectId='',expected=0,received=0;
+ let tombstones:ReadonlyMap<Id,number>=new Map(),published:Document|undefined,snapshot:ModelPreview|undefined;
+ const canvases=new Map<Id,CanvasRecord>(),records=new Map<Id,ElementRecord>();
+ const key=(kind:'canvas'|'element',id:Id)=>JSON.stringify([kind,id]);
+ const known=new Set<string>();
+ function update(value:CanonicalReadUpdate):ModelPreview|undefined{
+  if(finished)throw fault('model_preview_closed');
+  if(value.status!=='receiving'){
+   if(header&&(value.status!=='ready'||value.document.projectId!==projectId||received!==expected||value.document.canvases.size!==canvases.size||[...canvases].some(([id,canvas])=>!equal(value.document.canvases.get(id),canvas))||!equal(Object.fromEntries(value.document.tombstones),Object.fromEntries(tombstones))||value.document.elements.size!==expected||[...(published?.elements??[]),...records].some(([id,record])=>!equal(value.document.elements.get(id),record))))throw fault('model_preview_changed');
+   finished=true;return snapshot;
+  }
+  if(!header){
+   if(value.receivedElements!==0||value.elements.length||!value.canvases.length||!Number.isSafeInteger(value.totalElements)||value.totalElements<0)throw fault('invalid_model_preview');
+   projectId=value.projectId;expected=value.totalElements;tombstones=readMap(new Map(value.tombstones));
+   for(const canvas of value.canvases){if(canvases.has(canvas.id))throw fault('invalid_model_preview');canvases.set(canvas.id,freeze(clone(canvas)));}
+   const topology=createDocument(projectId,[...canvases.values()]);let roots=0;const entries=new Set<Id>();
+   for(const canvas of canvases.values()){
+    if(!canvas.id||!Object.hasOwn(canvas,'parent'))throw fault('invalid_canvas');
+    ancestors(topology,canvas.id);
+    if(canvas.parent===null){roots++;if(canvas.id!==projectId)throw fault('project_mismatch');}
+    else if(!canvas.parent||typeof canvas.parent.entryElementId!=='string'||!canvas.parent.entryElementId||entries.has(canvas.parent.entryElementId))throw fault('invalid_canvas_entry');
+    else entries.add(canvas.parent.entryElementId);
+   }
+   if(roots!==1)throw fault('invalid_roots');header=true;
+  }else if(value.projectId!==projectId||value.totalElements!==expected||value.canvases.length||value.tombstones.size)throw fault('model_preview_changed');
+  if(value.receivedElements!==received+value.elements.length||value.receivedElements>expected)throw fault('invalid_model_preview');
+  // Validate the entire incoming batch before publishing any prefix from it.
+  const incoming=new Set<Id>();
+  for(const record of value.elements){if(records.has(record.id)||known.has(key('element',record.id))||incoming.has(record.id)||!canvases.has(record.ownerCanvasId))throw fault('invalid_model_preview');validateElementRecord(record,registry,tombstones);incoming.add(record.id);}
+  for(const record of value.elements)records.set(record.id,freeze(clone(record)));received=value.receivedElements;
+  // Greatest closed subset: removing an unavailable dependency also removes its
+  // dependants. Fully received cycles survive and publish in one legal prefix.
+  const candidates=new Map<string,{canvas?:CanvasRecord;element?:ElementRecord;deps:Set<string>}>();
+  for(const canvas of canvases.values())if(!known.has(key('canvas',canvas.id)))candidates.set(key('canvas',canvas.id),{canvas,deps:new Set(canvas.parent?[key('canvas',canvas.parent.canvasId),key('element',canvas.parent.entryElementId)]:[])});
+  for(const element of records.values())if(!known.has(key('element',element.id))){
+   const deps=new Set([key('canvas',element.ownerCanvasId)]);
+   if(element.structure==='connection'){deps.add(key('element',element.source.elementId));deps.add(key('element',element.target.elementId));}
+   const definition=registry.resolve(element)==='known'?registry.components.get(element.componentId):undefined;
+   for(const ref of definition?.copy?.references??[])for(const id of copyReferenceIds(element.data,ref))deps.add(key(ref.target,id));
+   candidates.set(key('element',element.id),{element,deps});
+  }
+  const dependants=new Map<string,Set<string>>(),blocked=new Set<string>(),queue:string[]=[];
+  for(const [id,item]of candidates)for(const dependency of item.deps){let users=dependants.get(dependency);if(!users){users=new Set();dependants.set(dependency,users);}users.add(id);if(!known.has(dependency)&&!candidates.has(dependency)&&!blocked.has(id)){blocked.add(id);queue.push(id);}}
+  for(let index=0;index<queue.length;index++)for(const id of dependants.get(queue[index])??[])if(!blocked.has(id)){blocked.add(id);queue.push(id);}
+  const nextCanvases=[...(published?.canvases.values()??[])],nextElements=[...(published?.elements.values()??[])],accepted:string[]=[];
+  for(const [id,item]of candidates)if(!blocked.has(id)){if(item.canvas)nextCanvases.push(item.canvas);if(item.element)nextElements.push(item.element);accepted.push(id);}
+  if(!published||accepted.length){const next=createDocument(projectId,nextCanvases,nextElements,tombstones);validateDocument(next,registry);published=next;for(const id of accepted){known.add(id);const item=candidates.get(id);if(item?.element)records.delete(item.element.id);}}
+  snapshot=Object.freeze({document:published,receivedElements:received,totalElements:expected,waitingElements:received-published.elements.size,complete:false});return snapshot;
+ }
+ return Object.freeze({update(value:CanonicalReadUpdate){try{return update(value);}catch(error){finished=true;throw error;}},getSnapshot:()=>snapshot,close(){finished=true;records.clear();canvases.clear();known.clear();published=undefined;snapshot=undefined;}});
+}

src/lib/canvas-service/model-stream.ts

@@ -9,18 +9,21 @@ const uuid=/^[a-f\d]{8}-[a-f\d]{4}-[a-f\d]{4}-[a-f\d]{4}-[a-f\d]{12}$/i;
 const object=(value:unknown):Record<string,unknown>=>{if(!value||typeof value!=='object'||Array.isArray(value)||!validJson(value))throw fault('invalid_model_stream');return value as Record<string,unknown>;};
 /** Bounded NDJSON framing. EOF is required even after a terminal record. */
 async function* lines(source:AsyncIterable<Uint8Array>,signal:AbortSignal){
- const decoder=new TextDecoder('utf-8',{fatal:true});let pending='',total=0,lineBytes=0,count=0;
+ const decoder=new TextDecoder('utf-8',{fatal:true});
+ const decode=(bytes?:Uint8Array,stream=false)=>{try{return decoder.decode(bytes,{stream});}catch{throw fault('invalid_model_stream');}};
+ let pending='',total=0,lineBytes=0,count=0;
  for await(const bytes of source){
   signal.throwIfAborted();if(!(bytes instanceof Uint8Array))throw fault('invalid_model_stream');total+=bytes.byteLength;if(total>maxBytes)throw fault('model_stream_budget');
   let start=0;
   for(let index=0;index<bytes.length;index++)if(bytes[index]===10){
    lineBytes+=index-start;if(lineBytes>maxLine)throw fault('model_stream_budget');
-   pending+=decoder.decode(bytes.subarray(start,index),{stream:true});pending+=decoder.decode();if(++count>maxLines||!pending)throw fault('invalid_model_stream');
-   yield{raw:JSON.parse(pending),byteLength:lineBytes+1};pending='';lineBytes=0;start=index+1;
+   pending+=decode(bytes.subarray(start,index),true);pending+=decode();if(++count>maxLines||!pending)throw fault('invalid_model_stream');
+   let raw:unknown;try{raw=JSON.parse(pending);}catch{throw fault('invalid_model_stream');}
+   yield{raw,byteLength:lineBytes+1};pending='';lineBytes=0;start=index+1;
   }
-  lineBytes+=bytes.length-start;if(lineBytes>maxLine)throw fault('model_stream_budget');pending+=decoder.decode(bytes.subarray(start),{stream:true});
+  lineBytes+=bytes.length-start;if(lineBytes>maxLine)throw fault('model_stream_budget');pending+=decode(bytes.subarray(start),true);
  }
- signal.throwIfAborted();pending+=decoder.decode();if(pending||lineBytes)throw fault('incomplete_model_stream');
+ signal.throwIfAborted();pending+=decode();if(pending||lineBytes)throw fault('incomplete_model_stream');
 }
 export async function* decodeModelStream(source:AsyncIterable<Uint8Array>,canvasId:Id,registry:Registry,signal:AbortSignal){
  let sequence=0,token='',projectId='',expected=0,ended=false;