Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Add JS67_NATIVE_SESSIONS=off, per-frame routes in job metrics, a job-level sequence check and the large-scene sequence bench (#896)

Nguyen Xuan An96348c010a1c
diff --git a/bench/cycles-parity/large-scene.mjs b/bench/cycles-parity/large-scene.mjs
new file mode 100644
index 00000000..0452010b
--- /dev/null
+++ b/bench/cycles-parity/large-scene.mjs
@@ -0,0 +1,110 @@
+// Deterministic large scenes for the sequence bench, built straight as FORMAT-v2 scene descriptors (`{ materials, instances }`) so they pass
+// the package API and not the 400,000 triangle cap of `buildTraceScene`.
+// terrain: one subdivided, rippled surface of about `triangles` triangles under an emissive ceiling panel, plus one small box that moves.
+// forest: one 10,000 triangle mesh instanced `instanceCount` times over a ground quad, plus a lamp; one instance moves.
+import { createCamera } from '../../src/path-tracer.js';
+
+const FLOOR_MATERIAL = 0;
+const LAMP_MATERIAL = 1;
+const BOX_MATERIAL = 2;
+const MOVING_PART_STEPS = [-1.5, 1.5];
+
+function translationMatrix(x, y, z, scale = 1) {
+ return [scale, 0, 0, 0, 0, scale, 0, 0, 0, 0, scale, 0, x, y, z, 1];
+}
+
+function rippleHeight(x, z) {
+ return 0.35 * Math.sin(0.7 * x) * Math.cos(0.7 * z);
+}
+
+// A square grid of `cells` by `cells` quads over [-half, half] on x and z, two triangles per quad.
+export function buildRippledGrid(cells, half, heightOf = rippleHeight) {
+ const side = cells + 1;
+ const positions = new Float32Array(side * side * 3);
+ const normals = new Float32Array(side * side * 3);
+ const uvs = new Float32Array(side * side * 2);
+ const step = (2 * half) / cells;
+ for (let row = 0; row < side; row++) {
+ for (let column = 0; column < side; column++) {
+ const x = -half + column * step;
+ const z = -half + row * step;
+ const vertex = row * side + column;
+ positions.set([x, heightOf(x, z), z], vertex * 3);
+ const slopeX = (heightOf(x + step, z) - heightOf(x - step, z)) / (2 * step);
+ const slopeZ = (heightOf(x, z + step) - heightOf(x, z - step)) / (2 * step);
+ const length = Math.hypot(slopeX, 1, slopeZ);
+ normals.set([-slopeX / length, 1 / length, -slopeZ / length], vertex * 3);
+ uvs.set([column / cells, row / cells], vertex * 2);
+ }
+ }
+ const indices = new Uint32Array(cells * cells * 6);
+ let cursor = 0;
+ for (let row = 0; row < cells; row++) {
+ for (let column = 0; column < cells; column++) {
+ const topLeft = row * side + column;
+ const bottomLeft = topLeft + side;
+ indices.set([topLeft, bottomLeft, topLeft + 1, topLeft + 1, bottomLeft, bottomLeft + 1], cursor);
+ cursor += 6;
+ }
+ }
+ return { positions, normals, uvs, colors: new Float32Array(side * side * 3).fill(1), indices };
+}
+
+const UNIT_SQUARE = {
+ positions: new Float32Array([-1, 0, -1, 1, 0, -1, 1, 0, 1, -1, 0, 1]),
+ normals: new Float32Array([0, 1, 0, 0, 1, 0, 0, 1, 0, 0, 1, 0]),
+ uvs: new Float32Array([0, 0, 1, 0, 1, 1, 0, 1]),
+ colors: new Float32Array(12).fill(1),
+ indices: new Uint32Array([0, 2, 1, 0, 3, 2]),
+};
+const LAMP_SQUARE = { ...UNIT_SQUARE, normals: new Float32Array([0, -1, 0, 0, -1, 0, 0, -1, 0, 0, -1, 0]), indices: new Uint32Array([0, 1, 2, 0, 2, 3]) };
+
+const MATERIALS = [
+ { color: [0.55, 0.52, 0.48], roughness: 0.8 },
+ { color: [1, 0.95, 0.9], emission: 6, roughness: 1 },
+ { color: [0.8, 0.25, 0.2], roughness: 0.5 },
+];
+
+/** The scene descriptor with the moving instance at `step` (0 or 1) of its two placements. */
+export function buildLargeScene(kind, size, step) {
+ const movingX = MOVING_PART_STEPS[step];
+ if (kind === 'terrain') {
+ const cells = Math.round(Math.sqrt(size / 2));
+ const terrain = buildRippledGrid(cells, 10);
+ return { materials: MATERIALS, instances: [
+ { geometry: terrain, matrix: translationMatrix(0, 0, 0), materialIndex: FLOOR_MATERIAL },
+ { geometry: LAMP_SQUARE, matrix: translationMatrix(0, 7, 0, 4), materialOverride: LAMP_MATERIAL },
+ { geometry: UNIT_SQUARE, matrix: translationMatrix(movingX, 1.2, 0, 0.8), materialOverride: BOX_MATERIAL },
+ ] };
+ }
+ if (kind === 'forest') {
+ const tree = buildRippledGrid(Math.round(Math.sqrt(10000 / 2)), 0.8, (x, z) => 0.4 * Math.cos(2.1 * x) * Math.sin(2.1 * z));
+ const side = Math.ceil(Math.sqrt(size));
+ const instances = [
+ { geometry: UNIT_SQUARE, matrix: translationMatrix(0, -0.1, 0, side * 1.1), materialIndex: FLOOR_MATERIAL },
+ { geometry: LAMP_SQUARE, matrix: translationMatrix(0, 9, 0, side * 0.5), materialOverride: LAMP_MATERIAL },
+ ];
+ for (let index = 0; index < size; index++) {
+ const column = index % side;
+ const row = Math.floor(index / side);
+ const offsetX = (column - side / 2) * 2.2 + (index === 0 ? movingX : 0);
+ const height = 0.2 + ((index * 2654435761) % 1000) / 1000 * 0.8;
+ instances.push({ geometry: tree, matrix: translationMatrix(offsetX, height, (row - side / 2) * 2.2), materialIndex: BOX_MATERIAL });
+ }
+ return { materials: MATERIALS, instances };
+ }
+ throw new RangeError(`Unknown large scene "${kind}": pass terrain or forest.`);
+}
+
+/** The camera for orbit frame `frameIndex` of `frameCount`, a quarter turn around the scene. */
+export function orbitCameraFor(kind, size, frameIndex, frameCount, imageWidth, imageHeight) {
+ const radius = kind === 'forest' ? Math.sqrt(size) * 1.6 : 14;
+ const angle = (Math.PI / 2) * frameIndex / Math.max(1, frameCount - 1) + Math.PI / 4;
+ const eye = [radius * Math.sin(angle), radius * 0.45, radius * Math.cos(angle)];
+ return createCamera({ eye, target: [0, 0, 0], fov: 50, near: 0.05, far: 500 }, imageWidth, imageHeight);
+}
+
+export function describeLargeScene(kind, size) {
+ if (kind === 'terrain') return { kind, uniqueTriangles: 2 * Math.round(Math.sqrt(size / 2)) ** 2, instances: 3 };
+ return { kind, uniqueTriangles: 2 * Math.round(Math.sqrt(10000 / 2)) ** 2, instances: size + 2 };
+}
diff --git a/bench/cycles-parity/large-sequence-timing.mjs b/bench/cycles-parity/large-sequence-timing.mjs
new file mode 100644
index 00000000..34cd40a4
--- /dev/null
+++ b/bench/cycles-parity/large-sequence-timing.mjs
@@ -0,0 +1,87 @@
+// Times a 12 frame sequence on a large generated scene (bench/cycles-parity/large-scene.mjs), session against one-shot, in one process per mode.
+// Two variants run one after the other in that process: "camera" (the camera orbits) and "moving" (the camera orbits and one instance
+// alternates between two placements each frame, so the instance table changes every frame). Frame inputs are packed once per placement and
+// get the frame's camera words; the large tables are copied before each frame's timer starts, as a job decodes fresh tables per frame.
+// Prints one LARGE_SEQUENCE_TIMING line of JSON.
+// A scene of about 4,000,000 triangles packs about 900 MB of tables in JavaScript: run it with NODE_OPTIONS=--max-old-space-size=16384 (the default 4 GB heap
+// ran out in the pack step on 2026-11-12).
+// node bench/cycles-parity/large-sequence-timing.mjs --scene terrain|forest --size <triangles | instances> --mode session|oneshot
+// [--frames 12] [--samples 16] [--width 480] [--height 270] [--seed 1]
+import * as renderNative from '../../packages/render-native/index.mjs';
+import { buildLargeScene, describeLargeScene, orbitCameraFor } from './large-scene.mjs';
+import { PHASE_NAMES, averageOfWarmFrames, readFlag, runSequence } from './sequence-bench-core.mjs';
+
+const CAMERA_WORDS_START = 112;
+const CAMERA_WORDS_END = 192;
+const STEP_COUNT = 2;
+const PROBE_SCENE = { materials: [{}], instances: [{ geometry: {
+ positions: new Float32Array([-1, 0, -1, 1, 0, -1, 1, 0, 1]), normals: new Float32Array([0, 1, 0, 0, 1, 0, 0, 1, 0]),
+ uvs: new Float32Array([0, 0, 1, 0, 1, 1]), colors: new Float32Array(9).fill(1), indices: new Uint32Array([0, 2, 1]) },
+matrix: [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1], materialIndex: 0 }] };
+
+function requireNumber(argumentList, flagName, fallbackValue) {
+ const value = Number(readFlag(argumentList, flagName, fallbackValue));
+ if (!Number.isFinite(value) || value < 1) throw new RangeError(`${flagName} must be a number of at least 1; got ${value}.`);
+ return value;
+}
+
+// The camera words (bytes 112 to 191) of a FORMAT-v2 block for frame `frameIndex`, from a one triangle scene so no large pack is repeated.
+function cameraWordsFor(settings, frameIndex) {
+ const { scene, size, frameCount, packOptions } = settings;
+ const camera = orbitCameraFor(scene, size, frameIndex, frameCount, packOptions.width, packOptions.height);
+ return renderNative.buildNativeInputV2(PROBE_SCENE, camera, packOptions).kernelParams.slice(CAMERA_WORDS_START, CAMERA_WORDS_END);
+}
+
+function inputWithCamera(stateInput, cameraWords) {
+ const kernelParams = new Uint8Array(stateInput.kernelParams);
+ kernelParams.set(cameraWords, CAMERA_WORDS_START);
+ return { ...stateInput, kernelParams, triangles: stateInput.triangles.slice() };
+}
+
+function packStates(settings) {
+ const { scene, size, frameCount, packOptions } = settings;
+ const states = [];
+ for (let step = 0; step < STEP_COUNT; step++) {
+ const camera = orbitCameraFor(scene, size, 0, frameCount, packOptions.width, packOptions.height);
+ const packed = renderNative.buildNativeInputV2(buildLargeScene(scene, size, step), camera, packOptions);
+ if (step > 0) packed.triangles = states[0].triangles;
+ states.push(packed);
+ }
+ return states;
+}
+
+function summarize(label, run) {
+ const paths = {};
+ for (const frame of run.frames) paths[frame.path] = (paths[frame.path] ?? 0) + 1;
+ const warmAverage = Object.fromEntries([...PHASE_NAMES, 'wallSeconds'].map(name => [name, averageOfWarmFrames(run.frames, name)]));
+ return { variant: label, totalSeconds: run.totalSeconds, paths, coldFrame: run.frames[0], warmAverage, frameHashes: run.frames.map(frame => frame.rgbaSha256) };
+}
+
+function run() {
+ const argumentList = process.argv.slice(2);
+ const scene = readFlag(argumentList, '--scene', null);
+ const mode = readFlag(argumentList, '--mode', null);
+ if (!['terrain', 'forest'].includes(scene) || !['session', 'oneshot'].includes(mode)) {
+ throw new RangeError('Usage: node bench/cycles-parity/large-sequence-timing.mjs --scene terrain|forest --size <triangles | instances> --mode session|oneshot [--frames 12] [--samples 16] [--width 480] [--height 270] [--seed 1]');
+ }
+ const size = requireNumber(argumentList, '--size', 400000);
+ const frameCount = requireNumber(argumentList, '--frames', 12);
+ const width = requireNumber(argumentList, '--width', 480);
+ const height = requireNumber(argumentList, '--height', 270);
+ const samples = requireNumber(argumentList, '--samples', 16);
+ const seed = requireNumber(argumentList, '--seed', 1);
+ const packOptions = { width, height, samples, bounces: 4, seed, near: 0.05, far: 500 };
+ const settings = { scene, size, frameCount, packOptions };
+ const states = packStates(settings);
+ const cameraWords = Array.from({ length: frameCount }, (unused, frameIndex) => cameraWordsFor(settings, frameIndex));
+ const traceOptions = { ...packOptions, kernel: 'cycles' };
+ const variants = [
+ ['camera', frameIndex => inputWithCamera(states[0], cameraWords[frameIndex])],
+ ['moving', frameIndex => inputWithCamera(states[frameIndex % STEP_COUNT], cameraWords[frameIndex])],
+ ];
+ const results = variants.map(([label, prepareInput]) => summarize(label, runSequence(frameCount, prepareInput, mode, traceOptions)));
+ const summary = { ...describeLargeScene(scene, size), mode, frameCount, width, height, samples, triangleCount: states[0].triangleCount, results };
+ console.log(`LARGE_SEQUENCE_TIMING ${JSON.stringify(summary)}`);
+}
+
+run();
diff --git a/bench/cycles-parity/sequence-bench-core.mjs b/bench/cycles-parity/sequence-bench-core.mjs
new file mode 100644
index 00000000..324258e1
--- /dev/null
+++ b/bench/cycles-parity/sequence-bench-core.mjs
@@ -0,0 +1,54 @@
+// Shared by the sequence benches: hashing, per-frame summaries and the session / one-shot frame loop.
+import { createHash } from 'node:crypto';
+import * as renderNative from '../../packages/render-native/index.mjs';
+import { createNativeSequence } from '../../scripts/agent-native-sequence.mjs';
+
+export const PHASE_NAMES = ['setupSeconds', 'compileSeconds', 'uploadSeconds', 'accelerationBuildSeconds', 'tracedSeconds'];
+
+export function readFlag(argumentList, flagName, fallbackValue) {
+ const flagIndex = argumentList.indexOf(flagName);
+ return flagIndex === -1 ? fallbackValue : argumentList[flagIndex + 1];
+}
+
+function sha256Of(values) {
+ return createHash('sha256').update(Buffer.from(values.buffer, values.byteOffset, values.byteLength)).digest('hex');
+}
+
+function summarizeFrame(traced, route, wallSeconds) {
+ const frame = { rgbaSha256: sha256Of(traced.rgba), wallSeconds: Number(wallSeconds.toFixed(6)), path: route?.path ?? 'one-shot' };
+ for (const phaseName of PHASE_NAMES) frame[phaseName] = Number((traced[phaseName] ?? 0).toFixed(6));
+ if (route?.reason) frame.reason = route.reason;
+ if (route?.changedTables) frame.changedTables = route.changedTables;
+ return frame;
+}
+
+export function averageOfWarmFrames(frames, fieldName) {
+ const warmFrames = frames.slice(1);
+ const total = warmFrames.reduce((sum, frame) => sum + frame[fieldName], 0);
+ return Number((total / Math.max(1, warmFrames.length)).toFixed(6));
+}
+
+/**
+ * Renders the frames in order through a native sequence ("session") or one by one with traceNative ("oneshot"). `prepareInput(frameIndex)`
+ * runs before the frame's timer starts and returns the frame's input, so copying a large table never counts as render time.
+ */
+export function runSequence(frameCount, prepareInput, mode, traceOptions) {
+ const sequence = mode === 'session' ? createNativeSequence({ tracer: renderNative }) : null;
+ const frames = [];
+ const sequenceStarted = performance.now();
+ let preparationSeconds = 0;
+ try {
+ for (let frameIndex = 0; frameIndex < frameCount; frameIndex++) {
+ const preparationStarted = performance.now();
+ const input = prepareInput(frameIndex);
+ preparationSeconds += (performance.now() - preparationStarted) / 1000;
+ const frameStarted = performance.now();
+ const { traced, route } = sequence ? sequence.trace(input, traceOptions) : { traced: renderNative.traceNative(input, traceOptions) };
+ frames.push(summarizeFrame(traced, route, (performance.now() - frameStarted) / 1000));
+ }
+ } finally {
+ sequence?.close();
+ }
+ const totalSeconds = (performance.now() - sequenceStarted) / 1000 - preparationSeconds;
+ return { frames, totalSeconds: Number(totalSeconds.toFixed(6)) };
+}
diff --git a/bench/cycles-parity/sequence-timing.mjs b/bench/cycles-parity/sequence-timing.mjs
index 9f8d78bc..cf6b2fdd 100644
--- a/bench/cycles-parity/sequence-timing.mjs
+++ b/bench/cycles-parity/sequence-timing.mjs
@@ -6,31 +6,20 @@
// [--samples 16] [--width 480] [--height 270] [--seed 1] [--instancing]
// Variants: "camera" orbits the camera; "object-light" also moves the part named "block" and swings the first point light's intensity.
// --instancing builds the scene with shared geometry, so a moved part is an instance transform (an update) instead of new triangles.
-import { createHash } from 'node:crypto';
import { readFile } from 'node:fs/promises';
import { resolve } from 'node:path';
import { createCamera } from '../../src/path-tracer.js';
import * as packModule from '../../src/path-tracer-gpu-pack.js';
import { buildTraceScene } from '../../src/path-tracer-scene.js';
import * as renderNative from '../../packages/render-native/index.mjs';
-import { createNativeSequence } from '../../scripts/agent-native-sequence.mjs';
+import { PHASE_NAMES, averageOfWarmFrames, readFlag, runSequence } from './sequence-bench-core.mjs';
import { applyCookOnlyFields } from './cook-only-fields.mjs';
import { buildTraceSceneWithManyLights } from './trace-scene-many-lights.mjs';
import { reconstructTraceSceneSource } from './scene-bridge.mjs';
-const PHASE_NAMES = ['setupSeconds', 'compileSeconds', 'uploadSeconds', 'accelerationBuildSeconds', 'tracedSeconds'];
const MOVING_PART_NAME = 'block';
const ORBIT_RADIANS = Math.PI / 6;
-function readFlag(argumentList, flagName, fallbackValue) {
- const flagIndex = argumentList.indexOf(flagName);
- return flagIndex === -1 ? fallbackValue : argumentList[flagIndex + 1];
-}
-
-function sha256Of(values) {
- return createHash('sha256').update(Buffer.from(values.buffer, values.byteOffset, values.byteLength)).digest('hex');
-}
-
function orbitedCamera(camera, frameIndex, frameCount) {
const angle = ORBIT_RADIANS * frameIndex / Math.max(1, frameCount - 1);
const [targetX, , targetZ] = camera.target;
@@ -67,36 +56,6 @@ function buildInputs(source, settings) {
return inputs;
}
-function summarizeFrame(traced, route, wallSeconds) {
- const frame = { rgbaSha256: sha256Of(traced.rgba), wallSeconds: Number(wallSeconds.toFixed(6)), path: route?.path ?? 'one-shot' };
- for (const phaseName of PHASE_NAMES) frame[phaseName] = Number((traced[phaseName] ?? 0).toFixed(6));
- if (route?.reason) frame.reason = route.reason;
- if (route?.changedTables) frame.changedTables = route.changedTables;
- return frame;
-}
-
-function averageOfWarmFrames(frames, fieldName) {
- const warmFrames = frames.slice(1);
- const total = warmFrames.reduce((sum, frame) => sum + frame[fieldName], 0);
- return Number((total / Math.max(1, warmFrames.length)).toFixed(6));
-}
-
-function runSequence(inputs, mode, traceOptions) {
- const sequence = mode === 'session' ? createNativeSequence({ tracer: renderNative }) : null;
- const frames = [];
- const sequenceStarted = performance.now();
- try {
- for (const input of inputs) {
- const frameStarted = performance.now();
- const { traced, route } = sequence ? sequence.trace(input, traceOptions) : { traced: renderNative.traceNative(input, traceOptions) };
- frames.push(summarizeFrame(traced, route, (performance.now() - frameStarted) / 1000));
- }
- } finally {
- sequence?.close();
- }
- return { frames, totalSeconds: Number(((performance.now() - sequenceStarted) / 1000).toFixed(6)) };
-}
-
async function run() {
const argumentList = process.argv.slice(2);
const mode = readFlag(argumentList, '--mode', null);
@@ -115,7 +74,7 @@ async function run() {
const source = await reconstructTraceSceneSource(description);
const renderOptions = { width, height, samples, bounces: 8, seed };
const inputs = buildInputs(source, { variant, frameCount, width, height, instancing, renderOptions });
- const { frames, totalSeconds } = runSequence(inputs, mode, { ...renderOptions, kernel: 'cycles' });
+ const { frames, totalSeconds } = runSequence(inputs.length, frameIndex => inputs[frameIndex], mode, { ...renderOptions, kernel: 'cycles' });
const paths = {};
for (const frame of frames) paths[frame.path] = (paths[frame.path] ?? 0) + 1;
const summary = { scene: description.id, mode, variant, instancing, frameCount, width, height, samples, seed, totalSeconds, paths,
diff --git a/bench/native-tracer/sequence-job.mjs b/bench/native-tracer/sequence-job.mjs
new file mode 100644
index 00000000..1a97a31e
--- /dev/null
+++ b/bench/native-tracer/sequence-job.mjs
@@ -0,0 +1,109 @@
+// Runs real multi-frame native stills jobs through the MCP server, once with sessions and once with JS67_NATIVE_SESSIONS=off, and checks
+// that every frame of the two runs has the same bytes and that the frames after the first took the route the sequence calls for.
+// node bench/native-tracer/sequence-job.mjs <output directory> [--browser <chrome path>] [--runtime-backend gpu|cpu] [--samples 8] [--width 480] [--height 270]
+// Variants (the demo room with its motion edited): camera (camera tracks only), material (plus a roughness track), light (plus a point light
+// intensity track), transform (the recipe's own tracks, where a pendant swings: the exported triangles change, so each frame gets a session).
+// Prints one SEQUENCE_JOB line of JSON and exits 1 when a frame differs or a route is not the expected one.
+import { createHash } from 'node:crypto';
+import { mkdir, mkdtemp, readFile, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { Client } from '@modelcontextprotocol/client';
+import { StdioClientTransport } from '@modelcontextprotocol/client/stdio';
+
+const argumentList = process.argv.slice(2);
+const outputDirectory = resolve(argumentList[0]);
+const flag = (name, fallback) => (argumentList.includes(name) ? argumentList[argumentList.indexOf(name) + 1] : fallback);
+const width = Number(flag('--width', 480));
+const height = Number(flag('--height', 270));
+const samples = Number(flag('--samples', 8));
+const browserPath = flag('--browser', '');
+// "cpu" runs the page on SwiftShader, which is how a box whose headless Chrome cannot get a hardware renderer still traces on the native GPU tracer.
+const runtimeBackend = flag('--runtime-backend', 'gpu');
+const STILLS_PER_JOB = 8;
+const MOTION_SECONDS = 6;
+const RECIPE_MOTION_SECONDS = 12;
+
+function keyframes(first, last) {
+ return [{ time: 0, value: first }, { time: RECIPE_MOTION_SECONDS, value: last }];
+}
+
+function buildVariants(recipe) {
+ const cameraTracks = recipe.motion.tracks.filter(track => track.kind === 'camera');
+ const materialId = recipe.nodes.find(node => node.id === 'left-wall').material;
+ const withMotion = tracks => ({ ...recipe, motion: { ...recipe.motion, tracks } });
+ return {
+ camera: { recipe: withMotion(cameraTracks), expectedLaterRoutes: ['reused'] },
+ material: { recipe: withMotion([...cameraTracks, { kind: 'material', id: materialId, property: 'roughness', interpolation: 'LINEAR', keyframes: keyframes(0.9, 0.2) }]), expectedLaterRoutes: ['reused', 'updated'] },
+ light: { recipe: withMotion([...cameraTracks, { kind: 'light', id: 'point:0', property: 'intensity', interpolation: 'LINEAR', keyframes: keyframes(14, 4) }]), expectedLaterRoutes: ['reused', 'updated'] },
+ transform: { recipe: withMotion(recipe.motion.tracks), expectedLaterRoutes: ['reused', 'updated', 'new-session'] },
+ };
+}
+
+async function runJob(variantRecipe, sessions) {
+ const workDirectory = await mkdtemp(join(tmpdir(), '67js-sequence-job-'));
+ const transport = new StdioClientTransport({ command: process.execPath,
+ args: [resolve('bin/67js-mcp.mjs'), '--backend', runtimeBackend, '--memory', '384', '--jobs', join(workDirectory, 'jobs'), ...(browserPath ? ['--browser', browserPath] : [])],
+ cwd: workDirectory, stderr: 'pipe', env: { ...process.env, JS67_NATIVE_SESSIONS: sessions ? 'on' : 'off' } });
+ let diagnostics = '';
+ transport.stderr.on('data', bytes => { diagnostics = (diagnostics + bytes).slice(-4096); });
+ const client = new Client({ name: '67js-sequence-job', version: '1' });
+ const call = (name, toolArguments) => client.callTool({ name, arguments: toolArguments }, { timeout: 600000 });
+ try {
+ await client.connect(transport);
+ const createResult = await call('scene_create', { recipe: variantRecipe });
+ const created = createResult.structuredContent;
+ if (!created) throw new Error(`scene_create failed: ${createResult.content?.[0]?.text}`);
+ const settings = { kind: 'stills', duration: MOTION_SECONDS, motion: { start: 0 }, width, height,
+ renderer: { type: 'pathTracer', backend: 'native', samples, bounces: 6, denoise: false, maxSeconds: 120, seed: 3 } };
+ const submitted = await call('scene_render_submit', { sessionId: created.sessionId, expectedRevision: 0, settings });
+ if (submitted.isError) throw new Error(submitted.content?.[0]?.text);
+ const { jobId } = submitted.structuredContent;
+ let record;
+ for (;;) {
+ record = (await call('scene_render_status', { jobId })).structuredContent;
+ if (['completed', 'cancelled', 'failed'].includes(record.state)) break;
+ await delay(100);
+ }
+ if (record.state !== 'completed') throw new Error(`job ${record.state}: ${JSON.stringify(record.reason ?? record.error)}`);
+ const result = (await call('scene_render_result', { jobId })).structuredContent;
+ const frameHashes = [];
+ for (const artifact of result.artifacts) frameHashes.push(createHash('sha256').update(await readFile(artifact.path)).digest('hex'));
+ const metrics = result.metrics;
+ await call('scene_render_release', { jobId });
+ return { frameHashes, routes: metrics.nativeSessionRoutes ?? [], backend: metrics.pathTracer?.backend, backendNote: metrics.pathTracer?.backendNote, lastSession: metrics.pathTracer?.nativeSession };
+ } catch (error) {
+ console.error(diagnostics);
+ throw error;
+ } finally {
+ await client.close();
+ }
+}
+
+await mkdir(outputDirectory, { recursive: true });
+const variants = buildVariants(JSON.parse(await readFile('tests/fixtures/demo-room.recipe.json', 'utf8')));
+const report = { width, height, samples, frames: STILLS_PER_JOB, variants: {} };
+let failed = false;
+for (const [name, { recipe, expectedLaterRoutes }] of Object.entries(variants)) {
+ let withSessions;
+ let withoutSessions;
+ try {
+ withSessions = await runJob(recipe, true);
+ withoutSessions = await runJob(recipe, false);
+ } catch (error) {
+ report.variants[name] = { error: error.message };
+ failed = true;
+ continue;
+ }
+ const identical = withSessions.frameHashes.length === STILLS_PER_JOB && withSessions.frameHashes.every((hash, index) => hash === withoutSessions.frameHashes[index]);
+ const laterRoutes = withSessions.routes.slice(1);
+ const routesAsExpected = withSessions.routes[0] === 'new-session' && withSessions.routes.length === STILLS_PER_JOB && laterRoutes.every(route => expectedLaterRoutes.includes(route))
+ && (name === 'camera' ? laterRoutes.every(route => route === 'reused') : laterRoutes.some(route => route !== 'new-session'));
+ const sessionsOffRoutes = withoutSessions.routes;
+ report.variants[name] = { identical, routes: withSessions.routes, routesAsExpected, sessionsOffRoutes, backend: withSessions.backend, backendNote: withSessions.backendNote, lastFrameSession: withSessions.lastSession };
+ if (!identical || !routesAsExpected || sessionsOffRoutes.length > 0) failed = true;
+}
+await writeFile(join(outputDirectory, 'sequence-job.json'), JSON.stringify(report, null, 1));
+console.log(`SEQUENCE_JOB ${JSON.stringify(report)}`);
+process.exit(failed ? 1 : 0);
diff --git a/docs/agent-render-jobs.md b/docs/agent-render-jobs.md
index 8d5e55a8..887d37f0 100644
--- a/docs/agent-render-jobs.md
+++ b/docs/agent-render-jobs.md
@@ -185,7 +185,7 @@ An `image`, `stills` or `video` job can ask for the offline [path tracer](https:
"renderer": { "type": "pathTracer", "backend": "gpu", "samples": 64, "bounces": 8, "denoise": true, "seed": 0, "maxSeconds": 120 } }
```
-Every field after `type` is optional. `backend` is `cpu` (the default, byte-identical on SwiftShader smokes), `gpu`, which traces in a WebGL2 shader and needs a runtime started on the GPU backend (a `--backend cpu` runtime refuses it), or `native`, which traces on hardware ray queries (Vulkan) through the optional `@codepawlhq/67js-render-native` package. A native job exports the scene from the job page, traces it in the job runner with the Cycles-matching kernel (`JS67_NATIVE_KERNEL=legacy` keeps the older one), then denoises (OIDN runs on a device kept alive between frames when the OIDN library is installed, so only the first frame pays for the device and the filter commit; `metrics.pathTracer.oidnMode` says `in-process` or `cli`) and writes the PNG as the other backends do: `denoise: true` means OIDN with the albedo and normal guides when `@codepawlhq/67js-denoise-oidn` and its binary are installed, else (or when OIDN fails) the GPU a-trous filter of the native tracer with a note in `metrics.pathTracer.denoiserNote` (`denoiser: "atrous"`; it is biased, it smooths; `denoise: "wavelet"` asks for the CPU filter). The report carries `kernel` and `averageSamples`. It never fails for lack of the package: without it, without its built binary or without a Vulkan ray query adapter the job runs on `gpu` (`cpu` on a cpu runtime) and `metrics.pathTracer.backendNote` says why; `metrics.pathTracer.backend` always names what ran. The look up costs one import and is cached per process. Native traces volume fog and subsurface scattering with the same walk as the WebGPU megakernel, honours `maxSeconds`, and honours `noiseThreshold` on the GPU (after 16 samples, and then every 8, a converged pixel draws no more; `report.averageSamples` is the mean a pixel drew). The `gpu` fallback ignores `noiseThreshold`. The report in `metrics.pathTracer` names the `backend` that ran, the `gpu`, `gpuCompileSeconds` and `gpuKernelCompiles`. A `stills` or `video` job traces every frame with the same options: the kernel compiles once per job page and each frame reuses it, so a film shows `gpuKernelCompiles: 1`. A native `stills` or `video` job (the Cycles-matching kernel) also keeps one native session for the whole job: a frame that only moves the camera reuses the uploaded scene, the compiled kernel and the acceleration structures; changed materials, lights or instance transforms are sent to the session; a frame whose counts, geometry, textures or environment changed gets a new session, and a failed session update or render falls back to a new session or a one-shot trace for that frame. `metrics.pathTracer.nativeSession` says which one each frame took (`path` is `new-session`, `reused`, `updated` or `one-shot`, with `reason`, `changedTables`, `pipelineReused` and `accelerationReused`); a single-frame job and `JS67_NATIVE_KERNEL=legacy` trace one-shot and carry no `nativeSession`. The session is closed when the job ends or fails, and every frame equals the one-shot render byte for byte. A video of traced frames goes through the ffmpeg encoder (the browser H.264 encoder has no drawn frame to read), `maxSeconds` limits each frame, and the job deadline is `maxSeconds` times the frame count plus 60 seconds, up to the job ceiling. Limits: `samples` 1 to 1024, `bounces` 1 to 16, `seed` 0 to 2147483647, `maxSeconds` 1 to 600 (the job's deadline is `maxSeconds` plus 60 seconds; a 1920 by 1080 still of a 180,000 triangle room at 64 samples took 246 s, so give a large still `maxSeconds` 600). `passes` are refused with it. The tracer loads in the job page on demand, uses eight threads at below-normal priority, stops pixels that have converged (`report.averageSamples`), and writes `render.png`; `scene_render_result` metrics carry `pathTracer` with the samples, threads, seconds and what the scene asked for that was not drawn. The same recipe and seed give the same PNG on the cpu and gpu backends; the native Cycles-matching kernel is not always byte-identical between runs (on the demo room at 960 by 540 and 256 samples two jobs differed in a few bytes; a 480 by 270 job with OIDN did not). A job that passes `maxSeconds` fails and writes no image.
+Every field after `type` is optional. `backend` is `cpu` (the default, byte-identical on SwiftShader smokes), `gpu`, which traces in a WebGL2 shader and needs a runtime started on the GPU backend (a `--backend cpu` runtime refuses it), or `native`, which traces on hardware ray queries (Vulkan) through the optional `@codepawlhq/67js-render-native` package. A native job exports the scene from the job page, traces it in the job runner with the Cycles-matching kernel (`JS67_NATIVE_KERNEL=legacy` keeps the older one), then denoises (OIDN runs on a device kept alive between frames when the OIDN library is installed, so only the first frame pays for the device and the filter commit; `metrics.pathTracer.oidnMode` says `in-process` or `cli`) and writes the PNG as the other backends do: `denoise: true` means OIDN with the albedo and normal guides when `@codepawlhq/67js-denoise-oidn` and its binary are installed, else (or when OIDN fails) the GPU a-trous filter of the native tracer with a note in `metrics.pathTracer.denoiserNote` (`denoiser: "atrous"`; it is biased, it smooths; `denoise: "wavelet"` asks for the CPU filter). The report carries `kernel` and `averageSamples`. It never fails for lack of the package: without it, without its built binary or without a Vulkan ray query adapter the job runs on `gpu` (`cpu` on a cpu runtime) and `metrics.pathTracer.backendNote` says why; `metrics.pathTracer.backend` always names what ran. The look up costs one import and is cached per process. Native traces volume fog and subsurface scattering with the same walk as the WebGPU megakernel, honours `maxSeconds`, and honours `noiseThreshold` on the GPU (after 16 samples, and then every 8, a converged pixel draws no more; `report.averageSamples` is the mean a pixel drew). The `gpu` fallback ignores `noiseThreshold`. The report in `metrics.pathTracer` names the `backend` that ran, the `gpu`, `gpuCompileSeconds` and `gpuKernelCompiles`. A `stills` or `video` job traces every frame with the same options: the kernel compiles once per job page and each frame reuses it, so a film shows `gpuKernelCompiles: 1`. A native `stills` or `video` job (the Cycles-matching kernel) also keeps one native session for the whole job: a frame that only moves the camera reuses the uploaded scene, the compiled kernel and the acceleration structures; changed materials, lights or instance transforms are sent to the session; a frame whose counts, geometry, textures or environment changed gets a new session, and a failed session update or render falls back to a new session or a one-shot trace for that frame. `metrics.pathTracer.nativeSession` says which one each frame took (`path` is `new-session`, `reused`, `updated` or `one-shot`, with `reason`, `changedTables`, `pipelineReused` and `accelerationReused`); `metrics.nativeSessionRoutes` lists the `path` of every frame. A single-frame job and `JS67_NATIVE_KERNEL=legacy` trace one-shot and carry no `nativeSession`; `JS67_NATIVE_SESSIONS=off` in the server's environment traces every frame one-shot (default on). The session is closed when the job ends or fails, and every frame equals the one-shot render byte for byte. A video of traced frames goes through the ffmpeg encoder (the browser H.264 encoder has no drawn frame to read), `maxSeconds` limits each frame, and the job deadline is `maxSeconds` times the frame count plus 60 seconds, up to the job ceiling. Limits: `samples` 1 to 1024, `bounces` 1 to 16, `seed` 0 to 2147483647, `maxSeconds` 1 to 600 (the job's deadline is `maxSeconds` plus 60 seconds; a 1920 by 1080 still of a 180,000 triangle room at 64 samples took 246 s, so give a large still `maxSeconds` 600). `passes` are refused with it. The tracer loads in the job page on demand, uses eight threads at below-normal priority, stops pixels that have converged (`report.averageSamples`), and writes `render.png`; `scene_render_result` metrics carry `pathTracer` with the samples, threads, seconds and what the scene asked for that was not drawn. The same recipe and seed give the same PNG on the cpu and gpu backends; the native Cycles-matching kernel is not always byte-identical between runs (on the demo room at 960 by 540 and 256 samples two jobs differed in a few bytes; a 480 by 270 job with OIDN did not). A job that passes `maxSeconds` fails and writes no image.
## Controller API
diff --git a/docs/cycles-parity.md b/docs/cycles-parity.md
index 111d2354..2ecbc09a 100644
--- a/docs/cycles-parity.md
+++ b/docs/cycles-parity.md
@@ -921,7 +921,28 @@ Measured on one NVIDIA RTX 4090 (Vast instance, 24 frames, 480 x 270, 16 samples
| `many-lights-500` (3,646 triangles, 350 lights), camera orbit | session | 302 / 33 / 0.7 / 2.7 / 70 | 0 / 1.9 / 0.1 / 0 / 19 | 1.00 | 1 new, 23 reused |
| | one-shot | 286 / 33 / 0.7 / 2.6 / 66 | 0 / 1.8 / 0.3 / 2.0 / 18 | 1.32 (one run 7.5 s, two near 1.0) | |
-What the numbers say `[inferred]`: a session removes the acceleration build and most of the upload from frame 2 on (camera-only: 0 ms against 0.9 to 2.0 ms of build, 0.1 against 0.3 ms of upload), and `pipelineReused` and `accelerationReused` are true on every later frame. Compile does not read zero: the 1.8 ms is the lookup of the process-wide compiled-kernel cache, which a one-shot trace also hits from its second frame, so a one-shot sequence in a warm process already skips the 33 ms compile and the 240 to 320 ms device start. These scenes hold about 3,000 triangles, so the saving is 1 to 3 ms of a 18 to 25 ms frame and the sequence totals sit within run-to-run noise (the instanced rows show the spread: 0.73 to 1.04 s for the same work). A session pays when the scene is large enough for the build and upload to matter; a bench at that size is not recorded here. A moving object in the flattened scene changes the `triangles` table, so every frame there is a new session (as costly as a one-shot trace); only a scene packed with shared geometry turns a moved object into an instance-transform update.
+What the numbers say `[inferred]`: a session removes the acceleration build and most of the upload from frame 2 on (camera-only: 0 ms against 0.9 to 2.0 ms of build, 0.1 against 0.3 ms of upload), and `pipelineReused` and `accelerationReused` are true on every later frame. Compile does not read zero: the 1.8 ms is the lookup of the process-wide compiled-kernel cache, which a one-shot trace also hits from its second frame, so a one-shot sequence in a warm process already skips the 33 ms compile and the 240 to 320 ms device start. These scenes hold about 3,000 triangles, so the saving is 1 to 3 ms of a 18 to 25 ms frame and the sequence totals sit within run-to-run noise (the instanced rows show the spread: 0.73 to 1.04 s for the same work). A moving object in the flattened scene changes the `triangles` table, so every frame there is a new session (as costly as a one-shot trace); only a scene packed with shared geometry turns a moved object into an instance-transform update.
+
+### Large scenes (12 frames, same card)
+
+Generated scenes from `bench/cycles-parity/large-scene.mjs` through `large-sequence-timing.mjs` (480 x 270, 16 samples, medians of three runs, session against one-shot on identical inputs; every frame of every run is byte-identical between the two modes). "Camera" orbits the camera and runs first in the process, so its frame 1 includes the 300 to 400 ms start of the device; "moving" orbits the camera and alternates one instance between two placements every frame (an instance-table update, the TLAS rebuilt over the kept BLAS), and runs second in a warm process. `[measured]`
+
+| Scene | Variant | Mode | Sequence total (s) | Frames 2-12 mean: upload / acceleration / trace / wall (ms) | Routes |
+| --- | --- | --- | --- | --- | --- |
+| terrain, 400k triangles | camera | session | 0.66 | 0 / 0 / 5 / 18 | 1 new, 11 reused |
+| | | one-shot | 1.26 | 47 / 14 / 5 / 73 | |
+| | moving | session | 0.37 | 0 / 0 / 5 / 25 | 1 new, 11 updated |
+| | | one-shot | 0.88 | 46 / 14 / 5 / 72 | |
+| terrain, 1M triangles | camera | session | 1.16 | 0 / 0 / 5 / 29 | 1 new, 11 reused |
+| | | one-shot | 3.32 | 141 / 58 / 6 / 213 | |
+| | moving | session | 0.73 | 0 / 0 / 5 / 46 | 1 new, 11 updated |
+| | | one-shot | 3.67 | 143 / 130 / 24 / 308 | |
+| forest, 1,002 instances of one 10k mesh | camera | session | 0.53 | 0 / 0 / 10 / 14 | 1 new, 11 reused |
+| | | one-shot | 0.51 | 1 / 1 / 10 / 16 | |
+| | moving | session | 0.19 | 0 / 0 / 10 / 15 | 1 new, 11 updated |
+| | | one-shot | 0.19 | 1 / 1 / 10 / 15 | |
+
+What this says `[inferred]`: a one-shot frame pays about 120 to 140 ns per triangle for upload and 35 to 60 ns for the acceleration build every frame, so a session saves roughly 60 ms per frame at 400,000 triangles and 200 ms at 1,000,000 (3.32 s against 1.16 s for a 12 frame orbit, about 2.9 times faster; 0.88 against 0.37 s with a moving instance), and the saving grows with the triangle count. On small scenes there is no gain: the 3,000 triangle rooms above and the forest here (10,000 unique triangles, many instances) cost 1 to 3 ms of build and upload per frame, which a session removes, but the sequence totals do not move. The forest case also shows that the cost follows unique triangles, not instances. Not measured: 4,000,000 triangles (the bench's JavaScript heap ran out in the pack step at the default 4 GB; the job path takes at most 400,000 triangles anyway, so a job reaches the first row only), and peak VRAM (the card readings were the same for both modes, so they say nothing about the difference).
## Reproducible Commands
diff --git a/scripts/agent-runtime.mjs b/scripts/agent-runtime.mjs
index 3059eed4..138b4975 100644
--- a/scripts/agent-runtime.mjs
+++ b/scripts/agent-runtime.mjs
@@ -569,7 +569,7 @@ export function createAgentRuntime({ kernelWorkers = true, backend = 'gpu', brow
if (trace.backend === 'native') {
try {
const exported = await jobPage.evaluate(input => window.__agentPreview.exportNativeScene(input), { ...frameInput, options: { width, height, bounces: tracerOptions.bounces, seed: tracerOptions.seed, fireflyClamp: 20, noiseThreshold: tracerOptions.noiseThreshold } });
- if (settings.frameCount > 1) nativeSequence ??= createNativeSequence({ tracer: trace.tracer });
+ if (settings.frameCount > 1 && process.env.JS67_NATIVE_SESSIONS !== 'off') nativeSequence ??= createNativeSequence({ tracer: trace.tracer });
traced = await traceFrameNative({ tracer: trace.tracer, sequence: nativeSequence, exported, width, height, samples: tracerOptions.samples, bounces: tracerOptions.bounces,
seed: tracerOptions.seed, denoise: choice.denoise === true ? 'wavelet' : choice.denoise === false ? 'none' : choice.denoise, denoiser: choice.denoiser,
maxSeconds: tracerOptions.maxSeconds, noiseThreshold: tracerOptions.noiseThreshold });
@@ -598,6 +598,7 @@ export function createAgentRuntime({ kernelWorkers = true, backend = 'gpu', brow
metrics.width = width;
metrics.height = height;
metrics.pathTracer = traced.report;
+ if (traced.report.nativeSession) (metrics.nativeSessionRoutes ??= []).push(traced.report.nativeSession.path);
const tracedBytes = Buffer.from(traced.data, 'base64');
if (tracedBytes.length > MAXIMUM_JOB_FRAME_BYTES) throw new Error('Path traced frame exceeded 12 MiB.');
if (encoder) {