Skip to content

armgit / kiln

Public Imported from GitHub
0

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.

Reuse the host review scene across calls and pause long host steps (#349)

Matthew Kissinger04f02aacbc4a
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 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. A
batched 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 between
them, keyed by its bytes. A fully cached 9-shot call goes from 4.0–4.6 s to 2.8 s. The host keeps up
to 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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', async
await 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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 = {}): Reso
const 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 = {}): Reso
dir.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 = {}): Reso
if (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.ts
index 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.ts
index 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): unkno
return 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 | un
const 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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();