Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.
JavaScript 3d3d-assets3d-modelingagent-skillsagent-toolsai-agentsasset-pipelinecligame-assetsglbgltfmcpmcp-servermodel-context-protocolprocedural-generationprocedural-modelingtext-to-3dthreejstypescript
Reuse the host review scene across calls and pause long host steps (#349)
Matthew Kissinger04f02aacbc4a
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex a95c8dc2..045a306e 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,29 @@ does not publish a package.## Unreleased+- Calls on an artifact the host already loaded skip the load, and long host steps no longer hold up+ other calls on the same MCP process. Measured on the 2,635,224-triangle cathedral against a warm+ GPU service (two runs each):+ - `kiln_render`, `kiln_inspect`, `kiln_screenshot_animation` and `kiln_view_interior` borrow the+ review scene from a host cache keyed by the artifact hash. Each call has the scene to itself. A+ concurrent call on the same artifact loads its own copy rather than wait. A scene goes back only if+ its state key matches the one taken at load; a scene a call left changed, posed or added to is+ dropped, as is one left with a lower level of detail drawn or a level set aside changed. A lease has its+ own copies of the scene's lists (reason codes, clips). The host keeps up to two idle scenes, 6,000,000+ triangles and 256 MiB of scene arrays and encoded textures, measured off each scene (the cathedral holds+ 136 MB). A scene no call asked for in 32 leases is dropped, and clear() drops all. A fully cached 9-shot call+ goes from 2.7–2.8 s to 1.4–2.0 s, a default-grid repeat from 1.5–1.6 s to 0.7–0.8 s, and a repeated+ isolated or `kiln_inspect` shot from 1.6–1.9 s to 0.7–1.0 s.+ - Every shot of a call frames against bounds walked once per scene state.+ - Scene loading, shot planning and drawing, the capture cache's cell checks and the CPU rasterizer+ pause for the event loop. They pause per batch of vertices or triangles, per shot or per cell, and+ the call's cancellation takes effect at the next pause. Pauses are counted in work, never timed, and+ change no output. The longest wait a concurrent call saw during a cached 9-shot call goes from+ 1.4–1.5 s to 0.35 s. On the CPU route the longest wait during rendering goes from 5.5–6.1 s to+ 3.0–3.1 s. A derivative export (about 2 s on this asset, most of it atlas provenance validation)+ is still one stretch.+ - Images, hashes, receipts and tool schemas are unchanged.+- `--draws minimal` names each batch node after its first copy, `<copy>_Instances`, and`drawReduction.instancing` records which node names went into each batch, in instance order. Abatched copy loses its mesh, and a mesh-less copy with no children or extensions is removed. Clips@@ -25,11 +48,12 @@ does not publish a package.- every node's visibility, transform and place in the tree;- each geometry attribute's identity and edit version;- every material property, and each texture's identity, version and transform;- - morph weights, skinned bone poses and instance buffers.+ - morph weights, skinned bone poses and instance buffers;+ - the lower levels of detail set aside.- A hidden part or a posed clip therefore exports its own bytes. A shot of a lower level of detail,- or a scene holding anything added after it was loaded, has no key and exports every time, as- before. The host keeps up to 64 MB of derivatives for its lifetime.+ A hidden part, a posed clip or a lower level of detail drawn therefore exports its own bytes. A scene+ holding anything added after it was loaded has no key and exports every time, as before. Two calls+ that export one state at once store it once. The host keeps up to 64 MB of derivatives for its lifetime.- The capture cache's check, the port's trust check and the annotator decode one frame once betweenthem, keyed by its bytes. A fully cached 9-shot call goes from 4.0–4.6 s to 2.8 s. The host keeps upto 64 MB of decoded frames for its lifetime.diff --git a/src/tools/__tests__/review-scene-reuse.test.ts b/src/tools/__tests__/review-scene-reuse.test.tsnew file mode 100644index 00000000..595bbdf4--- /dev/null+++ b/src/tools/__tests__/review-scene-reuse.test.ts@@ -0,0 +1,132 @@+import { describe, expect, spyOn, test } from 'bun:test';++import * as glbModule from '../../views/glb';+import { createKilnProgramToolRegistry, type KilnToolContext } from '../registry';++function tool(name: string, context: KilnToolContext = {}) {+ const def = createKilnProgramToolRegistry(context).find((candidate) => candidate.name === name);+ if (!def) throw new Error(`no ${name}`);+ return def;+}++// A unique name per test keeps each test's artifact, and so its cached scene, its own.+const code = (name: string, animated = false) => `+const meta = { name: '${name}', category: 'prop' };+function build() {+ const root = createRoot('Root');+ const arm = createPivot('Arm', [0, 0, 0], root);+ createPart('Left', boxGeo(1, 1, 1), gameMaterial('#cc3333'), { parent: arm, position: [-1, 0, 0] });+ createPart('Right', boxGeo(1, 1, 1), gameMaterial('#3333cc'), { parent: root, position: [1, 0, 0] });+ return root;+}${+ animated+ ? `+function animate() {+ return [createClip('swing', 1, [rotationTrack('Joint_Arm', [+ { time: 0, rotation: [0, 0, 0] }, { time: 1, rotation: [0, 90, 0] }+ ])])];+}`+ : ''+}`;++const shot = (azimuthDeg: number, extra: Record<string, unknown> = {}) => ({+ version: 'kiln.capture.v1',+ size: 128,+ shots: [+ { name: `S${azimuthDeg}`, camera: { type: 'orbit', azimuthDeg, elevationDeg: 20 }, ...extra },+ ],+});++type Result = { ok: boolean; programRef?: string; pngBase64?: string; error?: string };++describe('one review scene per artifact across calls', () => {+ test('later calls on a programRef reuse the loaded scene and draw the same pixels', async () => {+ const load = spyOn(glbModule, 'loadGlbReviewScene');+ try {+ const render = tool('kiln_render');+ const first = (await render.run({ code: code('reuse-a'), capture: shot(30) })) as Result;+ expect(first.ok).toBe(true);+ const loads = load.mock.calls.length;+ expect(loads).toBeGreaterThanOrEqual(1);+ const isolated = (await render.run({+ programRef: first.programRef!,+ capture: shot(60, {+ subject: { path: '/reuse-a[0]/Root[0]/Joint_Arm[0]' },+ visibility: 'isolate',+ }),+ })) as Result;+ const again = (await render.run({+ programRef: first.programRef!,+ capture: shot(30),+ })) as Result;+ expect(isolated.ok).toBe(true);+ expect(again.ok).toBe(true);+ expect(load.mock.calls.length).toBe(loads);+ // The isolation was undone before the scene went back: the repeat draws what the first did.+ expect(again.pngBase64).toBe(first.pngBase64);+ } finally {+ load.mockRestore();+ }+ });++ test('kiln_inspect and kiln_render share the scene of one artifact', async () => {+ const load = spyOn(glbModule, 'loadGlbReviewScene');+ try {+ const first = (await tool('kiln_render').run({+ code: code('reuse-b'),+ capture: shot(30),+ })) as Result;+ const loads = load.mock.calls.length;+ expect(loads).toBeGreaterThanOrEqual(1);+ const inspected = (await tool('kiln_inspect').run({+ code: code('reuse-b'),+ listParts: {},+ image: false,+ })) as Result;+ expect(first.ok && inspected.ok).toBe(true);+ expect(load.mock.calls.length).toBe(loads);+ } finally {+ load.mockRestore();+ }+ });++ test('a scene a call leaves posed is not lent again', async () => {+ const source = code('reuse-c', true);+ const render = tool('kiln_render');+ const before = (await render.run({ code: source, capture: shot(30) })) as Result;+ const animated = (await tool('kiln_screenshot_animation').run({+ code: source,+ clip: 'swing',+ frameTimes: [1],+ })) as Result;+ expect(animated.ok).toBe(true);+ const after = (await render.run({ code: source, capture: shot(30) })) as Result;+ expect(after.pngBase64).toBe(before.pngBase64);+ });++ test('concurrent calls on one artifact each get a scene of their own', async () => {+ const render = tool('kiln_render');+ const source = code('reuse-d');+ const alone = (await render.run({+ code: source,+ capture: shot(45, {+ subject: { path: '/reuse-d[0]/Root[0]/Joint_Arm[0]' },+ visibility: 'isolate',+ }),+ })) as Result;+ const [isolated, whole] = (await Promise.all([+ render.run({+ code: source,+ capture: shot(45, {+ subject: { path: '/reuse-d[0]/Root[0]/Joint_Arm[0]' },+ visibility: 'isolate',+ }),+ }),+ render.run({ code: source, capture: shot(45) }),+ ])) as [Result, Result];+ const wholeAlone = (await render.run({ code: source, capture: shot(45) })) as Result;+ expect(isolated.pngBase64).toBe(alone.pngBase64);+ expect(whole.pngBase64).toBe(wholeAlone.pngBase64);+ expect(whole.pngBase64).not.toBe(isolated.pngBase64);+ });+});diff --git a/src/tools/registry.ts b/src/tools/registry.tsindex 26eaa924..298adead 100644--- a/src/tools/registry.ts+++ b/src/tools/registry.ts@@ -462,7 +462,17 @@ function evaluationEvidence(rendered: RenderResult): EvaluationEvidence {};}-async function loadEvaluatedReviewScene(code: string, context: KilnToolContext) {+/**+ * Build (or take from the build cache) and load the review scene. The scene is lent by the+ * host's review scene cache: the caller owns it until it runs the release pushed onto+ * `releases`, which it must do in a `finally`. A later call on the same artifact then skips the+ * load, and a concurrent one loads its own copy.+ */+async function loadEvaluatedReviewScene(+ code: string,+ context: KilnToolContext,+ releases: Array<() => void>,+) {const rendered = await evaluateGeneratedSource(code, context);try {context.liveReview?.artifact(code, rendered);@@ -470,13 +480,19 @@ async function loadEvaluatedReviewScene(code: string, context: KilnToolContext)/* Optional observation. */}const { loadGlbReviewScene } = await import('../views');- const scene = await loadGlbReviewScene(rendered.glb);- // Shots of one scene state, in this call or a later one on the same artifact, share an export.- (await import('../views/derivative-memo')).registerReviewArtifact(- scene.root,+ const { reviewSceneCache } = await import('../views/review-scene-cache');+ // The cache registers the scene, so shots of one state also share a derivative export.+ const lease = await reviewSceneCache.lease(rendered.artifactGlbSha256,+ () => loadGlbReviewScene(rendered.glb, context.evaluationControls?.()),+ rendered.tris,);- return { rendered, ...scene };+ releases.push(lease.release);+ // The build, the load and the scene check are long steps; let other calls run between them.+ await (await import('../views/event-loop')).pauseForEventLoop(+ context.evaluationControls?.().signal,+ );+ return { rendered, ...lease.scene };}const viewEvidenceHistoryByContext = new WeakMap<KilnToolContext, ViewEvidenceHistoryStore>();@@ -614,6 +630,7 @@ async function renderDerivativeCell(renderGlbViewCell(derivativeGlb, input.view, {size: input.size,camera,+ ...(context.evaluationControls ? { execution: context.evaluationControls() } : {}),...(input.backdrop ? { backdrop: input.backdrop } : {}),...(input.backfaceCull !== undefined ? { backfaceCull: input.backfaceCull } : {}),...(input.frameBounds ? { frameBounds: input.frameBounds } : {}),@@ -1269,6 +1286,7 @@ async function runRenderViews(onEvaluated?: (artifact: RenderResult) => void,): Promise<KilnRenderViewsResult> {context = snapshotRenderContext(context);+ const releases: Array<() => void> = [];try {context.evaluationControls?.().signal?.throwIfAborted();// `CPU_RASTER_RENDERER_ID` and `resolveGridCapture` come from this SAME lazy@@ -1280,7 +1298,11 @@ async function runRenderViews(const { renderGlbViewGrid, CPU_RASTER_RENDERER_ID, resolveGridCapture } = await import('../views');- const { root, rendered, reasonCodes } = await loadEvaluatedReviewScene(input.code, context);+ const { root, rendered, reasonCodes } = await loadEvaluatedReviewScene(+ input.code,+ context,+ releases,+ );onEvaluated?.(rendered);context = { ...context, requirements: rendered.requirements.binding };const materialContractFailure = missingProceduralTextureResult(rendered, context);@@ -1290,6 +1312,9 @@ async function runRenderViews(// scene; repeating it over the re-imported review scene named every// floating part a second time under its primitive name.const metrics = collectSceneMetrics(root);+ await (await import('../views/event-loop')).pauseForEventLoop(+ context.evaluationControls?.().signal,+ );if ('shots' in (input.capture ?? {})) {const { renderCaptureGrid } = await import('../views');const grid = await renderCaptureGrid(@@ -1299,6 +1324,7 @@ async function runRenderViews(context.captureLimits,{framesOnly: true,+ ...(context.evaluationControls ? { execution: context.evaluationControls() } : {}),renderExactShots: (shots) => renderExactArtifactShots(shots, rendered.glb, context),},);@@ -1514,6 +1540,9 @@ async function runRenderViews(error: appendSourceCheck(err instanceof Error ? err.message : String(err), input.code),warnings: [],};+ } finally {+ // Give the review scene back for a later call on this artifact; see views/review-scene-cache.ts.+ for (const release of releases) release();}}@@ -1586,9 +1615,10 @@ async function runScreenshotAnimation(context: KilnToolContext,): Promise<KilnScreenshotAnimationResult> {context = snapshotRenderContext(context);+ const releases: Array<() => void> = [];try {const { renderClipAnimation } = await import('../views');- const { root, clips, rendered } = await loadEvaluatedReviewScene(input.code, context);+ const { root, clips, rendered } = await loadEvaluatedReviewScene(input.code, context, releases);context = { ...context, requirements: rendered.requirements.binding };const warnings = inspectSceneStructure(root);const r = await renderClipAnimation(root, clips, {@@ -1648,6 +1678,9 @@ async function runScreenshotAnimation(error: appendSourceCheck(err instanceof Error ? err.message : String(err), input.code),warnings: [],};+ } finally {+ // Give the review scene back for a later call on this artifact; see views/review-scene-cache.ts.+ for (const release of releases) release();}}@@ -1759,9 +1792,14 @@ async function runViewInterior(context: KilnToolContext,): Promise<KilnViewInteriorResult> {context = snapshotRenderContext(context);+ const releases: Array<() => void> = [];try {const { renderInteriorGrid } = await import('../views');- const { root, rendered: evaluated } = await loadEvaluatedReviewScene(input.code, context);+ const { root, rendered: evaluated } = await loadEvaluatedReviewScene(+ input.code,+ context,+ releases,+ );context = { ...context, requirements: evaluated.requirements.binding };// No default name. An explicit nodeName stays an exact-name override; with// none, the grid resolves the roof from its semantic role (and only then@@ -1808,6 +1846,9 @@ async function runViewInterior(error: appendSourceCheck(err instanceof Error ? err.message : String(err), input.code),warnings: [],};+ } finally {+ // Give the review scene back for a later call on this artifact; see views/review-scene-cache.ts.+ for (const release of releases) release();}}@@ -2001,6 +2042,7 @@ async function runInspect(context: KilnToolContext,): Promise<KilnInspectResult> {context = snapshotRenderContext(context);+ const releases: Array<() => void> = [];try {const legacyCamera = [input.part,@@ -2027,7 +2069,7 @@ async function runInspect(root,rendered: evaluated,reasonCodes,- } = await loadEvaluatedReviewScene(input.code, context);+ } = await loadEvaluatedReviewScene(input.code, context, releases);context = { ...context, requirements: evaluated.requirements.binding };const { measureAttachment, describeSubjectFrame } = await import('../views/measurement');let comparison: KilnInspectResult['comparison'];@@ -2083,6 +2125,8 @@ async function runInspect(root,{ version: shot.hide ? 'kiln.capture.v2' : 'kiln.capture.v1', shots: [shot], size: 512 },(cell) => renderDerivativeCell(cell, context),+ context.captureLimits,+ context.evaluationControls ? { execution: context.evaluationControls() } : {},);return {ok: true,@@ -2166,6 +2210,9 @@ async function runInspect(ok: false,error: appendSourceCheck(err instanceof Error ? err.message : String(err), input.code),};+ } finally {+ // Give the review scene back for a later call on this artifact; see views/review-scene-cache.ts.+ for (const release of releases) release();}}diff --git a/src/views/__tests__/capture-cache.test.ts b/src/views/__tests__/capture-cache.test.tsindex 95edc299..8439b713 100644--- a/src/views/__tests__/capture-cache.test.ts+++ b/src/views/__tests__/capture-cache.test.ts@@ -157,3 +157,39 @@ test('producer changing during render never populates an older identity', asyncawait port(request);expect(calls).toBe(2);});++test('checking cached cells lets other work run between them', async () => {+ const port = createCachedRenderPort(+ async (request) => ({+ ok: true,+ rendererId: 'gpu',+ cameras: request.cameras,+ width: 128,+ height: 128,+ viewsPng: request.cameras!.map(() => png),+ derivativeFidelity: { materialFaithful: true, inputGlbSha256: hash },+ }),+ { cache: new MemoryCaptureCache(), identity: () => 'paced-producer' },+ );+ const cameras = [1, 2, 3].map((x) =>+ cameraFromBounds({ min: [-1, -1, -1], max: [1, 1, 1] }, [x, 1, 0]),+ );+ const request = { glb, cameras, width: 128, height: 128 };+ await port(request);+ let turns = 0;+ let running = true;+ const tick = () => {+ if (!running) return;+ turns++;+ setImmediate(tick);+ };+ setImmediate(tick);+ const hit = await port(request);+ running = false;+ expect(hit.captureCache).toEqual({ hit: true, reused: 3, total: 3 });+ expect(turns).toBeGreaterThanOrEqual(3);+ // A call cancelled while its cells are checked stops at the next pause.+ const controller = new AbortController();+ setImmediate(() => controller.abort(new Error('call cancelled')));+ await expect(port(request, { signal: controller.signal })).rejects.toThrow('call cancelled');+});diff --git a/src/views/__tests__/derivative-memo.test.ts b/src/views/__tests__/derivative-memo.test.tsindex afd4ac7e..ee6f6b53 100644--- a/src/views/__tests__/derivative-memo.test.ts+++ b/src/views/__tests__/derivative-memo.test.ts@@ -40,6 +40,28 @@ async function loaded(bytes: Uint8Array, sha = SHA) {}const find = (root: THREE.Object3D, name: string) => root.getObjectByName(name)!;++describe('derivative memo under concurrent calls', () => {+ test('two calls producing one key store it once, and later stores still fit', async () => {+ const memo = createDerivativeGlbMemo(100);+ let release!: () => void;+ const gate = new Promise<void>((resolve) => {+ release = resolve;+ });+ const produce = async () => {+ await gate;+ return new Uint8Array(40);+ };+ const both = Promise.all([memo.bytes('k', produce), memo.bytes('k', produce)]);+ release();+ await both;+ expect(memo.stats()).toMatchObject({ entries: 1, bytes: 40 });+ await memo.bytes('other', async () => new Uint8Array(70));+ expect(memo.stats()).toMatchObject({ entries: 1, bytes: 70 });+ await memo.bytes('third', async () => new Uint8Array(70));+ expect(memo.stats()).toMatchObject({ entries: 1, bytes: 70 });+ });+});const meshes = (root: THREE.Object3D) => {const found: THREE.Mesh[] = [];root.traverse((node) => {diff --git a/src/views/__tests__/drawn-geometry-memo.test.ts b/src/views/__tests__/drawn-geometry-memo.test.tsnew file mode 100644index 00000000..4fc55cb2--- /dev/null+++ b/src/views/__tests__/drawn-geometry-memo.test.ts@@ -0,0 +1,123 @@+import { describe, expect, spyOn, test } from 'bun:test';+import * as THREE from 'three';+import { renderSceneToGLB } from '../../render';+import { resolveAssetCamera } from '../camera';+import { registerReviewArtifact } from '../derivative-memo';+import { measuredDrawnGeometry } from '../drawn-geometry-memo';+import { loadGlbReviewScene } from '../glb';+import * as rasterModule from '../raster';++async function scene(register = true) {+ const source = new THREE.Group();+ source.name = 'Root';+ for (const [name, x] of [+ ['Left', -1],+ ['Right', 1],+ ] as const) {+ const mesh = new THREE.Mesh(new THREE.BoxGeometry(1, 1, 1), new THREE.MeshStandardMaterial());+ mesh.name = name;+ mesh.position.x = x;+ source.add(mesh);+ }+ const bytes = (await renderSceneToGLB(source, { derivative: true, gltfExporter: 'three' })).bytes;+ const { root } = await loadGlbReviewScene(Uint8Array.from(bytes));+ if (register) registerReviewArtifact(root, 'sha256:bounds');+ return root as THREE.Object3D;+}++const orbit = (azimuthDeg: number) => ({ camera: { type: 'orbit' as const, azimuthDeg } });++describe('drawn geometry measured once per scene state', () => {+ test('shots of one state walk the geometry once, and the cameras do not change', async () => {+ const root = await scene();+ const reference = await scene(false);+ const walk = spyOn(rasterModule, 'measureDrawnGeometry');+ try {+ const shots = [0, 90, 180, 270].map((azimuth) => resolveAssetCamera(root, orbit(azimuth)));+ // The subject is the whole asset, so one walk answers both its box and the scene's.+ expect(walk).toHaveBeenCalledTimes(1);+ walk.mockClear();+ const expected = [0, 90, 180, 270].map((azimuth) =>+ resolveAssetCamera(reference, orbit(azimuth)),+ );+ expect(shots).toEqual(expected);+ } finally {+ walk.mockRestore();+ }+ });++ test('a hidden or moved part is measured again', async () => {+ const root = await scene();+ const first = measuredDrawnGeometry(root);+ const right = root.getObjectByName('Right')!;+ right.visible = false;+ expect(measuredDrawnGeometry(root).max[0]).toBeLessThan(first.max[0]);+ right.visible = true;+ right.position.x = 5;+ expect(measuredDrawnGeometry(root).max[0]).toBeGreaterThan(first.max[0]);+ right.position.x = 1;+ expect(measuredDrawnGeometry(root)).toEqual(first);+ });++ test('a morph weight or a bone pose that changes is measured again', async () => {+ const geometry = new THREE.BoxGeometry(1, 1, 1);+ geometry.morphAttributes.position = [geometry.getAttribute('position').clone()];+ const morph = new THREE.Mesh(geometry, new THREE.MeshStandardMaterial());+ morph.name = 'Morph';+ morph.updateMorphTargets();+ const bone = new THREE.Bone();+ const skinGeometry = new THREE.BoxGeometry(1, 1, 1);+ const count = skinGeometry.getAttribute('position').count;+ skinGeometry.setAttribute(+ 'skinIndex',+ new THREE.Uint16BufferAttribute(new Uint16Array(count * 4), 4),+ );+ skinGeometry.setAttribute(+ 'skinWeight',+ new THREE.Float32BufferAttribute(+ new Float32Array(count * 4).map((_, i) => (i % 4 === 0 ? 1 : 0)),+ 4,+ ),+ );+ const skinned = new THREE.SkinnedMesh(skinGeometry, new THREE.MeshStandardMaterial());+ skinned.add(bone);+ skinned.bind(new THREE.Skeleton([bone]));+ const root = new THREE.Group();+ root.add(morph, skinned);+ root.updateMatrixWorld(true);+ registerReviewArtifact(root, 'sha256:poses');+ const walk = spyOn(rasterModule, 'measureDrawnGeometry');+ try {+ measuredDrawnGeometry(root);+ measuredDrawnGeometry(root);+ expect(walk).toHaveBeenCalledTimes(1);+ morph.morphTargetInfluences![0] = 0.5;+ measuredDrawnGeometry(root);+ expect(walk).toHaveBeenCalledTimes(2);+ bone.position.x = 2;+ bone.updateMatrixWorld(true);+ measuredDrawnGeometry(root);+ expect(walk).toHaveBeenCalledTimes(3);+ measuredDrawnGeometry(root);+ expect(walk).toHaveBeenCalledTimes(3);+ } finally {+ walk.mockRestore();+ }+ });++ test('callers get their own copies, and an unregistered scene is always walked', async () => {+ const root = await scene();+ const box = measuredDrawnGeometry(root);+ box.min[0] = 99;+ expect(measuredDrawnGeometry(root).min[0]).not.toBe(99);+ const loose = await scene(false);+ const walk = spyOn(rasterModule, 'measureDrawnGeometry');+ try {+ measuredDrawnGeometry(loose);+ measuredDrawnGeometry(loose);+ expect(walk).toHaveBeenCalledTimes(2);+ } finally {+ walk.mockRestore();+ }+ });+});diff --git a/src/views/__tests__/event-loop.test.ts b/src/views/__tests__/event-loop.test.tsnew file mode 100644index 00000000..1701ae73--- /dev/null+++ b/src/views/__tests__/event-loop.test.ts@@ -0,0 +1,161 @@+import { describe, expect, spyOn, test } from 'bun:test';+import * as THREE from 'three';+import { renderSceneToGLB } from '../../render';+import * as eventLoopModule from '../event-loop';+import { eventLoopPace, TRIANGLE_BUDGET, VERTEX_BUDGET } from '../event-loop';+import { rasterizeCamera, rasterizeCameraPaced, resolveAssetCamera } from '../camera';+import { renderCaptureGrid } from '../camera-capture';+import { loadGlbReviewScene } from '../glb';++/** Count event-loop turns until `done` resolves: what another call waiting on this process sees. */+async function turnsDuring<T>(work: () => Promise<T>): Promise<{ turns: number; value: T }> {+ let turns = 0;+ let running = true;+ const tick = () => {+ if (!running) return;+ turns++;+ setImmediate(tick);+ };+ setImmediate(tick);+ try {+ const value = await work();+ return { turns, value };+ } finally {+ running = false;+ }+}++async function denseScene(): Promise<Uint8Array> {+ const root = new THREE.Group();+ root.name = 'Dense';+ for (let i = 0; i < 12; i++) {+ const mesh = new THREE.Mesh(+ new THREE.SphereGeometry(1, 256, 128),+ new THREE.MeshStandardMaterial(),+ );+ mesh.name = `Ball${i}`;+ mesh.position.x = i * 3;+ root.add(mesh);+ }+ return Uint8Array.from(+ (await renderSceneToGLB(root, { derivative: true, gltfExporter: 'three' })).bytes,+ );+}++describe('event-loop pace', () => {+ test('pauses once the budget is spent, and only then', async () => {+ const pace = eventLoopPace(10);+ expect(pace.step(4)).toBeUndefined();+ expect(pace.step(5)).toBeUndefined();+ const { turns } = await turnsDuring(async () => pace.step(1));+ expect(turns).toBe(1);+ expect(pace.step(9)).toBeUndefined();+ });++ test('honours cancellation at a pause', async () => {+ const controller = new AbortController();+ const pace = eventLoopPace(1, controller.signal);+ controller.abort(new Error('cancelled'));+ await expect(pace.step(1)!).rejects.toThrow('cancelled');+ });+});++describe('loading a large review scene', () => {+ test('lets other work run between node batches and stops when cancelled', async () => {+ const bytes = await denseScene();+ // 12 spheres of about 33,000 vertices each.+ expect(12 * 257 * 129).toBeGreaterThan(2 * VERTEX_BUDGET);+ const loaded = await turnsDuring(() => loadGlbReviewScene(bytes));+ expect(loaded.turns).toBeGreaterThanOrEqual(2);+ const controller = new AbortController();+ setImmediate(() => controller.abort(new Error('call cancelled')));+ await expect(loadGlbReviewScene(bytes, { signal: controller.signal })).rejects.toThrow(+ 'call cancelled',+ );+ });++ test('a scene loaded with pauses is the scene loaded without them', async () => {+ const bytes = await denseScene();+ const describe = (root: THREE.Object3D) => {+ const out: unknown[] = [];+ root.traverse((node) => out.push([node.name, node.type, node.position.toArray()]));+ return out;+ };+ const paced = eventLoopModule.eventLoopPace;+ const unpaced = spyOn(eventLoopModule, 'eventLoopPace').mockImplementation((_, signal) =>+ paced(Number.POSITIVE_INFINITY, signal),+ );+ let a: Awaited<ReturnType<typeof loadGlbReviewScene>>;+ try {+ const counted = await turnsDuring(() => loadGlbReviewScene(bytes));+ expect(counted.turns).toBe(0);+ a = counted.value;+ } finally {+ unpaced.mockRestore();+ }+ const b = await turnsDuring(() => loadGlbReviewScene(bytes));+ expect(b.turns).toBeGreaterThanOrEqual(2);+ expect(describe(b.value.root as THREE.Object3D)).toEqual(describe(a.root as THREE.Object3D));+ });+});++describe('drawing a shot set', () => {+ const shots = (n: number) => ({+ version: 'kiln.capture.v1' as const,+ size: 128,+ shots: Array.from({ length: n }, (_, i) => ({+ name: `S${i}`,+ camera: { type: 'orbit' as const, azimuthDeg: i * 40 },+ })),+ });++ test('pauses between shots, and a cancelled call stops before its next shot', async () => {+ const root = new THREE.Group();+ root.add(new THREE.Mesh(new THREE.BoxGeometry(), new THREE.MeshStandardMaterial()));+ const { turns } = await turnsDuring(() => renderCaptureGrid(root, shots(3)));+ // One pause after resolving each shot's camera and one after drawing each.+ expect(turns).toBeGreaterThanOrEqual(6);+ const controller = new AbortController();+ let drawn = 0;+ await expect(+ renderCaptureGrid(+ root,+ shots(3),+ async (input) => {+ drawn++;+ controller.abort(new Error('call cancelled'));+ const { encodePng } = await import('../png');+ return {+ png: encodePng(new Uint8Array(input.size * input.size * 3), input.size, input.size),+ receipt: {} as never,+ };+ },+ undefined,+ { execution: { signal: controller.signal } },+ ),+ ).rejects.toThrow('call cancelled');+ expect(drawn).toBe(1);+ });+});++describe('the CPU rasterizer', () => {+ test('pauses between triangle batches and draws the same pixels', async () => {+ const root = new THREE.Group();+ root.add(+ new THREE.Mesh(new THREE.SphereGeometry(1, 200, 100), new THREE.MeshStandardMaterial()),+ );+ // 200 x 100 segments: about 39,600 triangles.+ expect(39_600).toBeGreaterThan(TRIANGLE_BUDGET);+ const { camera } = resolveAssetCamera(root, { camera: { type: 'orbit', azimuthDeg: 30 } });+ const { turns, value } = await turnsDuring(() =>+ rasterizeCameraPaced(root, camera, 96, true, 'neutral'),+ );+ expect(turns).toBeGreaterThanOrEqual(1);+ expect(value).toEqual(rasterizeCamera(root, camera, 96, true, 'neutral'));+ const controller = new AbortController();+ setImmediate(() => controller.abort(new Error('call cancelled')));+ await expect(+ rasterizeCameraPaced(root, camera, 96, true, 'neutral', controller.signal),+ ).rejects.toThrow('call cancelled');+ });+});diff --git a/src/views/__tests__/review-scene-cache.test.ts b/src/views/__tests__/review-scene-cache.test.tsnew file mode 100644index 00000000..88b1404c--- /dev/null+++ b/src/views/__tests__/review-scene-cache.test.ts@@ -0,0 +1,226 @@+import { describe, expect, test } from 'bun:test';+import * as THREE from 'three';+import { renderSceneToGLB } from '../../render';+import { loadGlbReviewScene } from '../glb';+import { registerReviewLodChains } from '../lod';+import { createReviewSceneCache, reviewSceneBytes } from '../review-scene-cache';++async function fixtureBytes(color = '#cc3333'): Promise<Uint8Array> {+ const root = new THREE.Group();+ root.name = 'Root';+ const box = new THREE.Mesh(+ new THREE.BoxGeometry(1, 1, 1),+ new THREE.MeshStandardMaterial({ color }),+ );+ box.name = 'Box';+ root.add(box);+ return Uint8Array.from(+ (await renderSceneToGLB(root, { derivative: true, gltfExporter: 'three' })).bytes,+ );+}++function counted(bytes: Uint8Array) {+ const loader = {+ loads: 0,+ load: async () => {+ loader.loads++;+ return loadGlbReviewScene(bytes);+ },+ };+ return loader;+}++const box = (root: unknown) => (root as THREE.Object3D).getObjectByName('Box')!;++describe('review scene cache', () => {+ test('a released scene is lent again for the same artifact', async () => {+ const cache = createReviewSceneCache();+ const loader = counted(await fixtureBytes());+ const first = await cache.lease('sha256:a', loader.load, 12);+ expect(first.reused).toBe(false);+ first.release();+ const second = await cache.lease('sha256:a', loader.load, 12);+ expect(second.reused).toBe(true);+ expect(second.scene.root).toBe(first.scene.root);+ expect(loader.loads).toBe(1);+ second.release();+ });++ test('a scene on lease is never lent twice: a concurrent call loads its own', async () => {+ const cache = createReviewSceneCache();+ const loader = counted(await fixtureBytes());+ const first = await cache.lease('sha256:a', loader.load, 12);+ const second = await cache.lease('sha256:a', loader.load, 12);+ expect(second.scene).not.toBe(first.scene);+ expect(loader.loads).toBe(2);+ first.release();+ second.release();+ // One idle copy per artifact is kept.+ expect(cache.stats().entries).toBe(1);+ });++ test('a scene returned changed is dropped, not lent again', async () => {+ const cache = createReviewSceneCache();+ const loader = counted(await fixtureBytes());+ const changes: Array<(root: unknown) => void> = [+ (root) => {+ box(root).visible = false;+ },+ (root) => {+ box(root).position.x = 3;+ },+ (root) => {+ (root as THREE.Object3D).add(new THREE.Group());+ },+ (root) => {+ let mesh: THREE.Mesh | undefined;+ (root as THREE.Object3D).traverse((node) => {+ if ((node as THREE.Mesh).isMesh) mesh ??= node as THREE.Mesh;+ });+ mesh!.geometry.getAttribute('position').needsUpdate = true;+ },+ (root) => {+ let mesh: THREE.Mesh | undefined;+ (root as THREE.Object3D).traverse((node) => {+ if ((node as THREE.Mesh).isMesh) mesh ??= node as THREE.Mesh;+ });+ (mesh!.material as THREE.MeshStandardMaterial).color.set('#00ff00');+ },+ ];+ for (const change of changes) {+ const lease = await cache.lease('sha256:a', loader.load, 12);+ change(lease.scene.root);+ lease.release();+ expect(cache.stats().entries).toBe(0);+ }+ expect(loader.loads).toBe(changes.length);+ });++ test('releasing twice is harmless and other artifacts get their own scene', async () => {+ const cache = createReviewSceneCache();+ const a = counted(await fixtureBytes());+ const b = counted(await fixtureBytes('#3333cc'));+ const lease = await cache.lease('sha256:a', a.load, 12);+ lease.release();+ lease.release();+ const other = await cache.lease('sha256:b', b.load, 12);+ expect(other.reused).toBe(false);+ other.release();+ expect(cache.stats().entries).toBe(2);+ });++ test('idle scenes stay within the entry and triangle budgets, oldest out first', async () => {+ const cache = createReviewSceneCache({ maxEntries: 2, maxTriangles: 30 });+ const bytes = await fixtureBytes();+ for (const artifact of ['sha256:a', 'sha256:b', 'sha256:c']) {+ const lease = await cache.lease(artifact, counted(bytes).load, 12);+ lease.release();+ }+ expect(cache.stats()).toMatchObject({ entries: 2, triangles: 24 });+ const oldest = counted(bytes);+ (await cache.lease('sha256:a', oldest.load, 12)).release();+ expect(oldest.loads).toBe(1);+ const kept = counted(bytes);+ (await cache.lease('sha256:c', kept.load, 12)).release();+ expect(kept.loads).toBe(0);+ // A scene larger than the whole budget is never kept.+ (await cache.lease('sha256:huge', counted(bytes).load, 31)).release();+ expect(cache.stats().triangles).toBeLessThanOrEqual(30);+ expect((await cache.lease('sha256:huge', counted(bytes).load, 31)).reused).toBe(false);+ });++ test('a lease gets its own arrays; the scene objects are shared', async () => {+ const cache = createReviewSceneCache();+ const loader = counted(await fixtureBytes());+ const first = await cache.lease('sha256:a', loader.load, 12);+ const codes = first.scene.reasonCodes as string[];+ first.release();+ codes.push('GLB_FLAT_PARSE_FAILED');+ const second = await cache.lease('sha256:a', loader.load, 12);+ expect(second.reused).toBe(true);+ expect(second.scene.reasonCodes).not.toContain('GLB_FLAT_PARSE_FAILED');+ (second.scene.reasonCodes as string[]).push('GLB_FLAT_PARSE_FAILED');+ second.release();+ const third = await cache.lease('sha256:a', loader.load, 12);+ expect(third.scene.reasonCodes).not.toContain('GLB_FLAT_PARSE_FAILED');+ third.release();+ });++ test('idle scenes stay within a byte budget measured off the scene', async () => {+ const bytes = await fixtureBytes();+ const one = reviewSceneBytes((await loadGlbReviewScene(bytes)).root);+ expect(one).toBeGreaterThan(0);+ const cache = createReviewSceneCache({ maxEntries: 4, maxBytes: one * 2 });+ for (const artifact of ['sha256:a', 'sha256:b', 'sha256:c'])+ (await cache.lease(artifact, counted(bytes).load, 1)).release();+ expect(cache.stats()).toMatchObject({ entries: 2, bytes: one * 2 });+ const small = createReviewSceneCache({ maxBytes: one - 1 });+ (await small.lease('sha256:a', counted(bytes).load, 1)).release();+ expect(small.stats()).toMatchObject({ entries: 0, bytes: 0 });+ });++ test('an idle scene no call asks for is dropped after maxIdleLeases leases, and clear drops all', async () => {+ const bytes = await fixtureBytes();+ const cache = createReviewSceneCache({ maxEntries: 4, maxIdleLeases: 2 });+ (await cache.lease('sha256:a', counted(bytes).load, 1)).release();+ for (const other of ['sha256:b', 'sha256:b'])+ (await cache.lease(other, counted(bytes).load, 1)).release();+ expect(cache.stats().entries).toBe(2);+ (await cache.lease('sha256:b', counted(bytes).load, 1)).release();+ // `a` was last used three leases ago.+ expect(cache.stats().entries).toBe(1);+ const lent = await cache.lease('sha256:c', counted(bytes).load, 1);+ cache.clear();+ expect(cache.stats()).toMatchObject({ entries: 0, triangles: 0, bytes: 0 });+ lent.release();+ expect(cache.stats().entries).toBe(0);+ });++ test('a lower level of detail left drawn, or a level set aside that changed, drops the scene', async () => {+ const cache = createReviewSceneCache();+ const bytes = await fixtureBytes();+ const withLevel = async () => {+ const loaded = await loadGlbReviewScene(bytes);+ const base = box(loaded.root);+ const level = new THREE.Mesh(+ new THREE.BoxGeometry(0.5, 0.5, 0.5),+ new THREE.MeshStandardMaterial(),+ );+ level.name = 'Box_LOD1';+ registerReviewLodChains(loaded.root as THREE.Object3D, [{ base, levels: [level] }]);+ return loaded;+ };+ // Unchanged: lent again.+ const kept = await cache.lease('sha256:lod', withLevel, 12);+ kept.release();+ expect(cache.stats().entries).toBe(1);+ // A swap left in place.+ const swapped = await cache.lease('sha256:lod', withLevel, 12);+ expect(swapped.reused).toBe(true);+ const base = box(swapped.scene.root);+ const parent = base.parent!;+ const chainLevel = (await import('../lod')).reviewLodChains(swapped.scene.root)[0]!.levels[0]!;+ parent.children[parent.children.indexOf(base)] = chainLevel;+ chainLevel.parent = parent;+ base.parent = null;+ swapped.release();+ expect(cache.stats().entries).toBe(0);+ // A level set aside, moved.+ const fresh = await cache.lease('sha256:lod', withLevel, 12);+ expect(fresh.reused).toBe(false);+ fresh.release();+ const edited = await cache.lease('sha256:lod', withLevel, 12);+ expect(edited.reused).toBe(true);+ (await import('../lod')).reviewLodChains(edited.scene.root)[0]!.levels[0]!.position.x = 4;+ edited.release();+ expect(cache.stats().entries).toBe(0);+ });++ test('a load that fails leaves nothing behind', async () => {+ const cache = createReviewSceneCache();+ await expect(+ cache.lease('sha256:a', async () => Promise.reject(new Error('bad glb')), 12),+ ).rejects.toThrow('bad glb');+ expect(cache.stats().entries).toBe(0);+ });+});diff --git a/src/views/camera-capture.ts b/src/views/camera-capture.tsindex 6a70d112..00cdac97 100644--- a/src/views/camera-capture.ts+++ b/src/views/camera-capture.ts@@ -7,7 +7,7 @@ import {} from './capture-limits';import {resolveAssetCamera,- rasterizeCamera,+ rasterizeCameraPaced,withCameraVisibility,type CameraShotV1,type ResolvedCameraShotV1,@@ -17,6 +17,7 @@ import type { BackdropId } from './background';import type { DerivativeCellRenderer, DerivativeCellRenderResult, ViewGridResult } from './index';import { encodePng } from './png';import { decodePngShared } from './png-memo';+import { eventLoopPace } from './event-loop';import { compositeCellGrid, PAD } from './grid';import { annotateViewCell } from './annotate';import type { DerivativeViewReceiptV1 } from '../composer/render-port';@@ -30,6 +31,8 @@ export interface CameraCaptureGridResult extends ViewGridResult {viewLevels?: number[][];}export interface CaptureGridOptions {+ /** The call's cancellation, honoured at the pause after each shot is planned and drawn. */+ execution?: { signal?: AbortSignal };/*** The caller delivers `perFramePngs` for `output: 'separate'` and never reads the sheet, so it* is neither built nor charged to the pixel budget; `png` is then empty.@@ -79,6 +82,9 @@ export async function renderCaptureGrid(options: CaptureGridOptions = {},): Promise<CameraCaptureGridResult> {validateAdvancedCapture(config);+ // Each shot's planning and drawing is a long synchronous stretch on a large asset; other calls+ // on this process run, and cancellation lands, at the pause after each.+ const pace = eventLoopPace(1, options.execution?.signal);// A shot whose subject names a lower level of detail resolves and draws with that level in// its LOD0's place; every shot resolves before any draws.const plans: {@@ -86,7 +92,7 @@ export async function renderCaptureGrid(shot: ResolvedCameraShotV1;levels: number[];}[] = [];- for (const request of config.shots!)+ for (const request of config.shots!) {plans.push(await withSubjectLevel(root, request.subject, async (levels) => ({subject: request.subject,@@ -94,6 +100,8 @@ export async function renderCaptureGrid(levels,})),);+ await pace.pause();+ }const shots = plans.map((plan) => plan.shot);const size = config.size ?? 384;const cols = config.cols ?? Math.min(3, shots.length);@@ -147,7 +155,15 @@ export async function renderCaptureGrid(derivativeReceipts.push(result.receipt);return result.png;}- return encodePng(rasterizeCamera(root, shot.camera, size, true, backdrop), size, size);+ const rgb = await rasterizeCameraPaced(+ root,+ shot.camera,+ size,+ true,+ backdrop,+ options.execution?.signal,+ );+ return encodePng(rgb, size, size);}),));const decoded = decodePngShared(png);@@ -156,6 +172,7 @@ export async function renderCaptureGrid(annotateViewCell(decoded.rgb, size, view);cells.push(decoded.rgb);perFramePngs.push(encodePng(decoded.rgb, size, size));+ await pace.pause();}const rows = Math.ceil(shots.length / cols);const sheet = framesOnly ? undefined : compositeCellGrid(cells, size, cols);diff --git a/src/views/camera.ts b/src/views/camera.tsindex bc58e98e..33ddff0e 100644--- a/src/views/camera.ts+++ b/src/views/camera.ts@@ -2,12 +2,12 @@ import { Vector3, Matrix4, Euler, Group, type Object3D } from 'three';import {collectTriangles,compositingOrder,- measureBounds,- measureDrawnGeometry,nearestDrawnTriangleDistance,orbitDir,} from './raster';import { resolveBackdrop, type BackdropId } from './background';+import { measuredDrawnGeometry } from './drawn-geometry-memo';+import { eventLoopPace, TRIANGLE_BUDGET } from './event-loop';import { cloneReviewScene } from './scene-copy';import { visibleNormalSign } from './face-policy';import { prepareTriangleCoverage } from './triangle-coverage';@@ -304,7 +304,12 @@ export function resolveAssetCamera(root: unknown, shot: CameraShotV1 = {}): Resoconst rootNode = root as Object3D;rootNode.updateMatrixWorld(true);const selected = selectCameraSubject(root, shot.subject);- const { triangles, ...bounds } = measureDrawnGeometry(selected.node);+ // Shots of one scene state share these walks; see views/drawn-geometry-memo.ts.+ const { triangles, ...bounds } = measuredDrawnGeometry(selected.node);+ const sceneBounds = () => {+ const { min, max } = measuredDrawnGeometry(root);+ return { min, max };+ };if (!triangles) throw new Error(`subject ${selected.path} has no visible geometry`);const request = shot.camera ?? { type: 'orbit' };let camera: ResolvedAssetCameraV1;@@ -324,7 +329,7 @@ export function resolveAssetCamera(root: unknown, shot: CameraShotV1 = {}): Resodir.transformDirection(node.matrixWorld);up = tuple(new Vector3(0, 1, 0).transformDirection(node.matrixWorld));}- camera = cameraFromBounds(bounds, tuple(dir), request.padding ?? 1.2, up, measureBounds(root));+ camera = cameraFromBounds(bounds, tuple(dir), request.padding ?? 1.2, up, sceneBounds());} else if (request.type === 'explicit') {strict(request,@@ -402,13 +407,7 @@ export function resolveAssetCamera(root: unknown, shot: CameraShotV1 = {}): Resoif (direction.lengthSq() < 1e-20)throw new Error('bounds framing position and target must differ');const padding = request.padding ?? 1.2;- const fit = cameraFromBounds(- bounds,- tuple(direction),- padding,- tuple(up),- measureBounds(root),- );+ const fit = cameraFromBounds(bounds, tuple(direction), padding, tuple(up), sceneBounds());if (request.projection === 'orthographic')camera = {...fit,@@ -519,6 +518,44 @@ export function rasterizeCamera(backfaceCull = true,backdrop?: BackdropId,): Uint8Array {+ const steps = rasterizeCameraSteps(root, input, size, backfaceCull, backdrop, Infinity);+ for (;;) {+ const step = steps.next();+ if (step.done) return step.value;+ }+}++/**+ * `rasterizeCamera`, pausing for the event loop every `TRIANGLE_BUDGET` triangles and stopping+ * there when `signal` aborts. A large asset takes seconds to draw on the CPU; the pauses let+ * the process serve other calls meanwhile. The pixels are `rasterizeCamera`'s.+ */+export async function rasterizeCameraPaced(+ root: unknown,+ input: ResolvedAssetCameraV1,+ size = 384,+ backfaceCull = true,+ backdrop?: BackdropId,+ signal?: AbortSignal,+): Promise<Uint8Array> {+ const pace = eventLoopPace(1, signal);+ const steps = rasterizeCameraSteps(root, input, size, backfaceCull, backdrop, TRIANGLE_BUDGET);+ for (;;) {+ const step = steps.next();+ if (step.done) return step.value;+ await pace.pause();+ }+}++/** The rasterizer, yielding after every `every` triangles drawn or skipped. */+function* rasterizeCameraSteps(+ root: unknown,+ input: ResolvedAssetCameraV1,+ size: number,+ backfaceCull: boolean,+ backdrop: BackdropId | undefined,+ every: number,+): Generator<void, Uint8Array> {const camera = validateResolvedAssetCamera(input);const bg = resolveBackdrop(backdrop).rgb;if (!Number.isInteger(size) || size < 1 || size > 2048)@@ -557,7 +594,12 @@ export function rasterizeCamera(? Math.hypot(px - position.x, py - position.y, pz - position.z): (position.x - px) * z.x + (position.y - py) * z.y + (position.z - pz) * z.z,);+ let sincePause = 0;for (const tri of ordered) {+ if (++sincePause >= every) {+ sincePause = 0;+ yield;+ }const world = [0, 1, 2].map((i) => new Vector3(tri.v[i * 3]!, tri.v[i * 3 + 1]!, tri.v[i * 3 + 2]!),);diff --git a/src/views/capture-cache.ts b/src/views/capture-cache.tsindex 79b2aa7b..3d42529b 100644--- a/src/views/capture-cache.ts+++ b/src/views/capture-cache.ts@@ -9,6 +9,7 @@ import type { GlbViewCellResult } from './index';import type { ResolvedAssetCameraV1 } from './camera';import { decodePngShared } from './png-memo';import { enforcePngCaptureBudget } from './capture-limits';+import { pauseForEventLoop } from './event-loop';export type CaptureCacheEntry =| { kind: 'gpu'; result: PbrRenderResult }| { kind: 'cpu'; result: GlbViewCellResult };@@ -168,6 +169,8 @@ export function createCachedRenderPort(};if (cached?.kind === 'gpu' && usable(cached.result, single, hash)) cells[i] = cached.result;else missing.push(i);+ // Checking a cell decodes its frame: let other calls run between cells.+ await pauseForEventLoop(execution?.signal);}if (missing.length) {const subrequest = {diff --git a/src/views/derivative-memo.ts b/src/views/derivative-memo.tsindex fe5595a7..10691eae 100644--- a/src/views/derivative-memo.ts+++ b/src/views/derivative-memo.ts@@ -1,4 +1,5 @@import { createHash } from 'node:crypto';+import { reviewLodChains } from './lod';import type {BufferAttribute,BufferGeometry,@@ -29,8 +30,9 @@ import type {** A scene is keyed only once it is registered with the hash of the GLB it was loaded from, and* only while every node, geometry, attribute, material and texture in it was there at- * registration. Anything new (a fresh attribute, a swapped-in level of detail, a new texture)- * gives no key, and the export runs. What the key cannot see is an edit inside an attribute's+ * registration, lower levels of detail included. An export key also describes the levels set+ * aside, so an edit to one shows. Anything new (a fresh attribute, a new texture) gives no key,+ * and the export runs. What the key cannot see is an edit inside an attribute's* array or a texture's image that does not bump its `version`. three needs that bump* (`needsUpdate`) to draw such an edit too, and no review path makes one.*/@@ -58,7 +60,7 @@ export function registerReviewArtifact(root: unknown, artifact: string): void {if ((attribute as InterleavedBufferAttribute).isInterleavedBufferAttribute)number((attribute as InterleavedBufferAttribute).data);};- scene.traverse((node) => {+ const visit = (node: Object3D) => {number(node);registrations.set(node, registration);const mesh = node as Mesh;@@ -77,7 +79,11 @@ export function registerReviewArtifact(root: unknown, artifact: string): void {for (const value of Object.values(material))if ((value as Texture | null)?.isTexture) number(value as Texture);}- });+ };+ scene.traverse(visit);+ // Lower levels of detail are built beside the scene, detached until a shot draws one.+ for (const chain of reviewLodChains(scene))+ for (const level of chain.levels) level.traverse(visit);}class Unkeyable extends Error {}@@ -169,26 +175,34 @@ function materialState(material: Material, id: (value: object) => number): unknoreturn fields;}+/**+ * What a key covers. An `export` key covers everything a derivative export reads. A+ * `geometry` key covers only what decides where drawn vertices land: the tree, visibility,+ * transforms, attributes, morph weights, skins and instances. It leaves out names, userData,+ * materials and textures, which no bounds walk reads.+ */+export type StateKeyScope = 'export' | 'geometry';+function nodeState(node: Object3D,id: (value: object) => number,materials: Map<Material, unknown>,+ scope: StateKeyScope,): unknown[] {const state: unknown[] = [id(node),node.parent ? id(node.parent) : null,- node.name,node.visible,node.position.toArray(),node.quaternion.toArray(),node.scale.toArray(),node.matrixAutoUpdate,Array.from(node.matrix.elements),- JSON.stringify(node.userData),];+ if (scope === 'export') state.push(node.name, JSON.stringify(node.userData));const mesh = node as Mesh;if (mesh.geometry) state.push(geometryState(mesh.geometry, id));- if (mesh.material)+ if (scope === 'export' && mesh.material)state.push(materialsOf(mesh).map((material) => {// Shared by many meshes: describe each once per key.@@ -223,7 +237,11 @@ function nodeState(* `undefined` when the scene is not registered, holds something added since, or cannot be* described as data.*/-export function derivativeStateKey(root: unknown, options: unknown): string | undefined {+export function derivativeStateKey(+ root: unknown,+ options: unknown,+ scope: StateKeyScope = 'export',+): string | undefined {const scene = root as Object3D;const registration = registrations.get(scene);if (!registration) return undefined;@@ -237,19 +255,31 @@ export function derivativeStateKey(root: unknown, options: unknown): string | unconst nodes: unknown[] = [];scene.traverse((node) => {if (registrations.get(node) !== registration) throw new Unkeyable();- nodes.push(nodeState(node, id, materials));+ nodes.push(nodeState(node, id, materials, scope));});+ // The levels of detail set aside: what a swap would draw, and what it would put back.+ const detached: unknown[] = [];+ if (scope === 'export')+ for (const chain of reviewLodChains(scene))+ for (const member of [chain.base, ...chain.levels])+ if (member.parent === null)+ member.traverse((node) => {+ if (registrations.get(node) !== registration) throw new Unkeyable();+ detached.push(nodeState(node, id, materials, scope));+ });// A subtree's placement is its ancestors'.const ancestors: unknown[] = [];for (let node = scene.parent; node; node = node.parent)- ancestors.push(nodeState(node, id, materials));+ ancestors.push(nodeState(node, id, materials, scope));return createHash('sha256').update(JSON.stringify({version: 'kiln.derivative-memo.v1',+ scope,artifact: registration.artifact,options,nodes,+ detached,ancestors,materials: [...materials.values()],}),@@ -280,7 +310,13 @@ export function createDerivativeGlbMemo(maxBytes = 64 * 1024 * 1024): Derivative}const produced = Uint8Array.from(await produce());if (key !== undefined && produced.byteLength <= maxBytes) {- while (held + produced.byteLength > maxBytes) {+ // Two calls on one scene state can both miss and both produce: the later replaces.+ const stored = entries.get(key);+ if (stored) {+ entries.delete(key);+ held -= stored.byteLength;+ }+ while (entries.size > 0 && held + produced.byteLength > maxBytes) {const [oldest, value] = entries.entries().next().value!;entries.delete(oldest);held -= value.byteLength;diff --git a/src/views/drawn-geometry-memo.ts b/src/views/drawn-geometry-memo.tsnew file mode 100644index 00000000..e3da304e--- /dev/null+++ b/src/views/drawn-geometry-memo.ts@@ -0,0 +1,30 @@+import { derivativeStateKey } from './derivative-memo';+import * as raster from './raster';++type DrawnGeometry = ReturnType<typeof raster.measureDrawnGeometry>;++const measured = new WeakMap<object, { key: string; result: DrawnGeometry }>();++const copy = (result: DrawnGeometry): DrawnGeometry => ({+ min: [...result.min],+ max: [...result.max],+ triangles: result.triangles,+});++/**+ * `measureDrawnGeometry`, walked once per node and scene state. Every shot of a call frames+ * against the subject's box and the scene's, and on a large asset each walk visits millions of+ * vertices. The answer depends only on what a `geometry` state key (views/derivative-memo.ts)+ * names: the tree, visibility, transforms, attributes, morphs, skins and instances. An unchanged+ * node answers from its last walk.+ * A scene that is not registered is walked every time.+ */+export function measuredDrawnGeometry(node: unknown): DrawnGeometry {+ const key = derivativeStateKey(node, {}, 'geometry');+ if (key === undefined) return raster.measureDrawnGeometry(node);+ const hit = measured.get(node as object);+ if (hit?.key === key) return copy(hit.result);+ const result = raster.measureDrawnGeometry(node);+ measured.set(node as object, { key, result: copy(result) });+ return result;+}diff --git a/src/views/event-loop.ts b/src/views/event-loop.tsnew file mode 100644index 00000000..92adec9f--- /dev/null+++ b/src/views/event-loop.ts@@ -0,0 +1,48 @@+/**+ * One MCP process serves every call of a session, so a long synchronous stretch in one call+ * holds up the others: their requests, their cancellations and their replies. Long host loops+ * call `pace.step(work)` with the work each item cost; once the work since the last pause+ * reaches the budget, `step` waits for one turn of the event loop (a macrotask, so pending I/O+ * and timers run) and then honours cancellation. Work is counted in the loop's own units+ * (vertices, triangles, frames), never by a clock, so where a call pauses does not depend on+ * how busy the machine is, and nothing a call produces depends on it either.+ */+export interface EventLoopPace {+ /** Count `work` units; pause when the budget is spent. Resolves at once otherwise. */+ step(work?: number): Promise<void> | undefined;+ /** Pause now, whatever has been counted. */+ pause(): Promise<void>;+}++export function eventLoopPace(budget: number, signal?: AbortSignal): EventLoopPace {+ let spent = 0;+ const pause = () =>+ new Promise<void>((resolve, reject) => {+ setImmediate(() => {+ spent = 0;+ try {+ signal?.throwIfAborted();+ resolve();+ } catch (error) {+ reject(error);+ }+ });+ });+ return {+ step(work = 1) {+ spent += work;+ return spent >= budget ? pause() : undefined;+ },+ pause,+ };+}++/** One turn of the event loop between two long steps of a call, then its cancellation. */+export function pauseForEventLoop(signal?: AbortSignal): Promise<void> {+ return eventLoopPace(1, signal).pause();+}++/** Vertices a scene load or bounds walk handles between pauses: about 10–20 ms on a 2026 desktop. */+export const VERTEX_BUDGET = 150_000;+/** Triangles the CPU rasterizer draws between pauses. */+export const TRIANGLE_BUDGET = 20_000;diff --git a/src/views/glb.ts b/src/views/glb.tsindex c80b3699..10323c92 100644--- a/src/views/glb.ts+++ b/src/views/glb.ts@@ -5,6 +5,7 @@ import { isCubicSplineTrack } from '../animation-spline';import { createGltfIO } from '../gltf-io';import { listLodChainNodes } from '../lod-export';import { isHiddenGltfNode } from '../metrics';+import { eventLoopPace, VERTEX_BUDGET, type EventLoopPace } from './event-loop';import { registerReviewLodChains } from './lod';import {atlasDocumentTable,@@ -585,20 +586,35 @@ function localInstanceMatrices(node: import('@gltf-transform/core').Node): Matri* production replacement for re-executing generated source in animation,* interior, inspect, and composed-scene review tools. Textures are deliberately* not sampled by the CPU scene; the same reason codes remain explicit. */-export async function loadGlbReviewScene(bytes: Uint8Array): Promise<LoadedGlbReviewScene> {+export async function loadGlbReviewScene(+ bytes: Uint8Array,+ execution?: { signal?: AbortSignal },+): Promise<LoadedGlbReviewScene> {let document: import('@gltf-transform/core').Document;try {document = await glbIO().readBinary(Uint8Array.from(bytes));} catch {throw new GlbGeometryFlatError('GLB_FLAT_PARSE_FAILED', 'Could not parse final GLB bytes.');}+ execution?.signal?.throwIfAborted();await validateAtlasDocumentProvenance(document);- return reviewSceneFromDocument(document);+ // Building a large scene takes long enough to hold up other calls on this process: pause+ // between node batches, and stop there if the call was cancelled.+ return reviewSceneFromDocument(document, eventLoopPace(VERTEX_BUDGET, execution?.signal));+}++/** A node just built, and the vertices of the meshes built for it: its share of a load's work. */+function builtVertices(target: Object3D): number {+ let work = 1;+ for (const child of target.children)+ work += (child as Mesh).geometry?.getAttribute('position')?.count ?? 0;+ return work;}-function reviewSceneFromDocument(+async function reviewSceneFromDocument(document: import('@gltf-transform/core').Document,-): LoadedGlbReviewScene {+ pace?: EventLoopPace,+): Promise<LoadedGlbReviewScene> {const sourceScene = document.getRoot().getDefaultScene() ?? document.getRoot().listScenes()[0];if (!sourceScene) throw new GlbGeometryFlatError('GLB_FLAT_NO_SCENE', 'Final GLB has no scene.');const reasons = new Set<GlbGeometryFlatReasonCode>();@@ -637,7 +653,7 @@ function reviewSceneFromDocument(let meshCount = 0;let instanceCount = 0;- const buildNode = (source: import('@gltf-transform/core').Node): Object3D => {+ const buildNode = async (source: import('@gltf-transform/core').Node): Promise<Object3D> => {const existing = nodeMap.get(source);if (existing) return existing;const target = joints.has(source) ? new Bone() : new Group();@@ -866,10 +882,11 @@ function reviewSceneFromDocument(}}}- for (const child of source.listChildren()) target.add(buildNode(child));+ await pace?.step(builtVertices(target));+ for (const child of source.listChildren()) target.add(await buildNode(child));return target;};- for (const child of sourceScene.listChildren()) root.add(buildNode(child));+ for (const child of sourceScene.listChildren()) root.add(await buildNode(child));root.updateMatrixWorld(true);if (meshCount === 0)throw new GlbGeometryFlatError(@@ -881,13 +898,16 @@ function reviewSceneFromDocument(const sceneMeshCount = meshCount;const sceneInstanceCount = instanceCount;const sceneReasons = new Set(reasons);- registerReviewLodChains(- root,- listLodChainNodes(document).map(({ levels: [base, ...lower] }) => ({- base: nodeMap.get(base!)!,- levels: lower.some((level) => nodeMap.has(level)) ? [] : lower.map(buildNode),- })),- );+ const chains: Array<{ base: Object3D; levels: Object3D[] }> = [];+ for (const {+ levels: [base, ...lower],+ } of listLodChainNodes(document)) {+ const levels: Object3D[] = [];+ if (!lower.some((level) => nodeMap.has(level)))+ for (const level of lower) levels.push(await buildNode(level));+ chains.push({ base: nodeMap.get(base!)!, levels });+ }+ registerReviewLodChains(root, chains);for (const { source, mesh } of pendingSkins) {const skin = source.getSkin()!;diff --git a/src/views/index.ts b/src/views/index.tsindex 7beb2d78..25d33e91 100644--- a/src/views/index.ts+++ b/src/views/index.ts@@ -6,6 +6,7 @@ import { captureCpuCell, type CaptureCache } from './capture-cache';export * from './capture-cache';import {rasterizeCamera,+ rasterizeCameraPaced,cameraFromBounds,resolveAssetCamera,selectCameraSubject,@@ -476,13 +477,24 @@ export interface GlbViewCellResult {export async function renderGlbViewCell(bytes: Uint8Array,view: ViewSpec,- options: RasterOptions & { camera?: ResolvedAssetCameraV1 } = {},+ options: RasterOptions & {+ camera?: ResolvedAssetCameraV1;+ /** The call's cancellation, honoured at the rasterizer's pauses. */+ execution?: { signal?: AbortSignal };+ } = {},): Promise<GlbViewCellResult> {const exactBytes = Uint8Array.from(bytes);const loaded = await loadGlbGeometryFlatScene(exactBytes);const size = options.size ?? 256;const rgb = options.camera- ? rasterizeCamera(loaded.root, options.camera, size, options.backfaceCull, options.backdrop)+ ? await rasterizeCameraPaced(+ loaded.root,+ options.camera,+ size,+ options.backfaceCull,+ options.backdrop,+ options.execution?.signal,+ ): rasterizeView(loaded.root, view.dir, {size,...(options.backdrop ? { backdrop: options.backdrop } : {}),diff --git a/src/views/png-memo.ts b/src/views/png-memo.tsindex 2791396a..85c4f220 100644--- a/src/views/png-memo.ts+++ b/src/views/png-memo.ts@@ -25,7 +25,7 @@ export function createPngDecodeMemo(const decoded = png.decodePng(bytes);const size = decoded.rgb.byteLength;if (size <= maxBytes) {- while (held + size > maxBytes) {+ while (entries.size > 0 && held + size > maxBytes) {const [oldest, value] = entries.entries().next().value!;entries.delete(oldest);held -= value.rgb.byteLength;diff --git a/src/views/port.ts b/src/views/port.tsindex 0671ec9c..24e2981e 100644--- a/src/views/port.ts+++ b/src/views/port.ts@@ -325,7 +325,7 @@ export async function captureViewsViaPort('./derivative-memo');const { createHash } = await import('node:crypto');- const loaded = await loadGlbReviewScene(Uint8Array.from(glb));+ const loaded = await loadGlbReviewScene(Uint8Array.from(glb), execution);registerReviewArtifact(loaded.root,`sha256:${createHash('sha256').update(glb).digest('hex')}`,@@ -379,6 +379,7 @@ export async function captureViewsViaPort(},limits,{+ ...(execution ? { execution } : {}),renderExactShots: ({ shots, size, backdrop }) =>captureExactArtifactShotsViaPort(port, glb, timeoutMs, shots, size, {// These are the bytes the caller produced, which is what it asked to see.diff --git a/src/views/review-scene-cache.ts b/src/views/review-scene-cache.tsnew file mode 100644index 00000000..8fc0e737--- /dev/null+++ b/src/views/review-scene-cache.ts@@ -0,0 +1,214 @@+import type { BufferAttribute, InterleavedBufferAttribute, Mesh, Object3D, Texture } from 'three';+import { derivativeStateKey, registerReviewArtifact } from './derivative-memo';+import { reviewLodChains } from './lod';++/**+ * The host loads a review scene from the artifact's GLB on every kiln_render, kiln_inspect,+ * kiln_screenshot_animation and kiln_view_interior call, even when the build cache hands back the+ * same bytes. On a large asset that load is the largest part of a call that renders nothing new.+ * This cache lends a loaded scene to one call at a time and takes it back afterwards.+ *+ * A lease is exclusive. A scene on lease is never lent to a second call; a call that finds its+ * artifact's scene out loads its own copy, so calls never wait on each other and never see+ * another call's isolation, hidden parts, level-of-detail swap or pose. On release the scene's+ * state key (views/derivative-memo.ts) must equal the one taken when it was loaded. A scene that+ * comes back with anything changed, added or posed is dropped, never lent again.+ *+ * Idle scenes are bounded by count, triangles and the bytes they hold (attribute and index arrays+ * and encoded textures, lower levels of detail included), and an idle scene no call has asked+ * for in `maxIdleLeases` leases is dropped. The lifetime is counted in calls, never timed.+ * `clear()` drops every idle scene.+ */++export interface ReviewSceneLease<T extends { root: unknown }> {+ scene: T;+ /** True when the scene was loaded by an earlier call. Its top-level arrays are this lease's copies. */+ reused: boolean;+ /** Give the scene back. Idempotent; call it in a `finally`. */+ release(): void;+}++interface Idle<T> {+ scene: T;+ key: string;+ triangles: number;+ bytes: number;+ /** The lease count when a call last had this scene. */+ used: number;+}++/** Bytes a loaded scene holds: attribute, index and instance arrays and encoded textures. */+export function reviewSceneBytes(root: unknown): number {+ const seen = new Set<object>();+ let bytes = 0;+ const add = (owner: object, length: number | undefined) => {+ if (seen.has(owner)) return;+ seen.add(owner);+ bytes += length ?? 0;+ };+ const attribute = (value: BufferAttribute | InterleavedBufferAttribute) =>+ (value as InterleavedBufferAttribute).isInterleavedBufferAttribute+ ? add(+ (value as InterleavedBufferAttribute).data,+ (value as InterleavedBufferAttribute).data.array.byteLength,+ )+ : add(value, (value as BufferAttribute).array.byteLength);+ const visit = (node: Object3D) => {+ const mesh = node as Mesh & {+ instanceMatrix?: BufferAttribute;+ instanceColor?: BufferAttribute | null;+ };+ const geometry = mesh.geometry;+ if (geometry) {+ for (const value of Object.values(geometry.attributes)) attribute(value);+ for (const list of Object.values(+ geometry.morphAttributes as Record<+ string,+ Array<BufferAttribute | InterleavedBufferAttribute>+ >,+ ))+ for (const value of list) attribute(value);+ if (geometry.index) attribute(geometry.index);+ }+ if (mesh.instanceMatrix) attribute(mesh.instanceMatrix);+ if (mesh.instanceColor) attribute(mesh.instanceColor);+ if (mesh.material)+ for (const material of [mesh.material].flat())+ for (const value of Object.values(material))+ if ((value as Texture | null)?.isTexture) {+ const encoded = (value as Texture).userData?.encoded as+ | { byteLength?: number }+ | undefined;+ add(value as Texture, encoded?.byteLength);+ }+ };+ (root as Object3D).traverse(visit);+ for (const chain of reviewLodChains(root))+ for (const member of [chain.base, ...chain.levels])+ if (member.parent === null) member.traverse(visit);+ return bytes;+}++/** A lease's own top-level arrays (reason codes, clips): the scene's objects stay shared. */+function lend<T extends object>(scene: T): T {+ const copy = { ...scene } as Record<string, unknown>;+ for (const [name, value] of Object.entries(copy))+ if (Array.isArray(value)) copy[name] = [...value];+ return copy as T;+}++export interface ReviewSceneCache {+ lease<T extends { root: unknown }>(+ artifact: string,+ load: () => Promise<T>,+ triangles: number,+ ): Promise<ReviewSceneLease<T>>;+ stats(): {+ entries: number;+ triangles: number;+ bytes: number;+ maxEntries: number;+ maxTriangles: number;+ maxBytes: number;+ };+ /** Drop every idle scene. Scenes on lease are unaffected and are not taken back. */+ clear(): void;+}++export function createReviewSceneCache(+ options: {+ maxEntries?: number;+ maxTriangles?: number;+ maxBytes?: number;+ maxIdleLeases?: number;+ } = {},+): ReviewSceneCache {+ const maxEntries = options.maxEntries ?? 2;+ const maxTriangles = options.maxTriangles ?? 6_000_000;+ // The 2,635,224-triangle cathedral holds 136 MB, its GLB 15 MB: one such scene fits.+ const maxBytes = options.maxBytes ?? 256 * 1024 * 1024;+ const maxIdleLeases = options.maxIdleLeases ?? 32;+ const idle = new Map<string, Idle<{ root: unknown }>>();+ let held = 0;+ let heldBytes = 0;+ let leases = 0;+ let generation = 0;+ const drop = (artifact: string) => {+ const entry = idle.get(artifact);+ if (!entry) return;+ idle.delete(artifact);+ held -= entry.triangles;+ heldBytes -= entry.bytes;+ };+ return {+ async lease<T extends { root: unknown }>(+ artifact: string,+ load: () => Promise<T>,+ triangles: number,+ ): Promise<ReviewSceneLease<T>> {+ leases++;+ for (const [other, value] of [...idle])+ if (other !== artifact && leases - value.used > maxIdleLeases) drop(other);+ let entry = idle.get(artifact) as Idle<T> | undefined;+ let reused = false;+ if (entry) {+ // Only ever put back unchanged (see `release`), and nothing touches an idle scene.+ drop(artifact);+ reused = true;+ }+ if (!entry) {+ const scene = await load();+ registerReviewArtifact(scene.root, artifact);+ const key = derivativeStateKey(scene.root, {});+ entry = { scene, key: key ?? '', triangles, bytes: 0, used: leases };+ if (key === undefined) {+ // Not describable as data: lend it, but never take it back.+ return { scene, reused: false, release: () => {} };+ }+ entry.bytes = reviewSceneBytes(scene.root);+ }+ const lent = entry;+ const leasedIn = generation;+ let released = false;+ return {+ scene: lend(lent.scene),+ reused,+ release: () => {+ if (released) return;+ released = true;+ if (leasedIn !== generation) return;+ if (derivativeStateKey(lent.scene.root, {}) !== lent.key) return;+ if (idle.has(artifact) || lent.triangles > maxTriangles || lent.bytes > maxBytes) return;+ while (+ idle.size >= maxEntries ||+ held + lent.triangles > maxTriangles ||+ heldBytes + lent.bytes > maxBytes+ ) {+ const oldest = idle.keys().next().value;+ if (oldest === undefined) break;+ drop(oldest);+ }+ lent.used = leases;+ idle.set(artifact, lent);+ held += lent.triangles;+ heldBytes += lent.bytes;+ },+ };+ },+ stats: () => ({+ entries: idle.size,+ triangles: held,+ bytes: heldBytes,+ maxEntries,+ maxTriangles,+ maxBytes,+ }),+ clear: () => {+ generation++;+ for (const artifact of [...idle.keys()]) drop(artifact);+ },+ };+}++/** The host's shared review scenes. Keys are artifact hashes, so calls never collide. */+export const reviewSceneCache = createReviewSceneCache();