Official Codebase of 3DCodeVerse
Python
/**
* Page-side host for `scene_threejs` workspaces (runs in headless Chrome).
*
* Boots a WebGLRenderer with the harness's fixed settings (antialias, ACES,
* sRGB, shadow maps), imports the agent's `src/scene.js` through the import
* map, calls `createScene({THREE, renderer, loaders})`, validates the returned
* shape and exposes `window.__c3v` with deterministic instruments:
* Scene renders go through the post chain (browser/post.js: GTAO + soft bloom +
* grade, `post: false` to disable); the coverage mask passes stay raw.
* boot(opts) · renderAt(cameraSpec, t) · census() · fps(seconds)
* cameraChecks(cameraSpec) (near geometry + luminance + content coverage)
* compileAll(cameraSpec) · shaderErrors()
* Node drivers (render_scene / probe_scene / check_shaders) call these via
* page.evaluate. Agent code never imports this file.
*/
import * as THREE from 'three';
import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
import { sceneCensus } from './host_census.mjs';
import { settleScene } from './host_placement.mjs';
import { FRAME_STAT_KEYS, frameStats, imageFrameStats, nearGeometry, repairCameraSpec } from './host_metrics.mjs';
import { frameCoverage, glbCoverage } from './host_coverage.mjs';
import { classifyBackdrop, nonSolid, drawableBox } from './backdrop.mjs';
import { installShaderErrorHook } from './host_shader_errors.mjs';
import { attributeErrors, captured, captureMaterialSources, materialAudit } from './host_compile.mjs';
import { makeRenderer, rendererString } from './browser/renderer.js';
import { observeUpdateHooks } from './update_hooks.mjs';
const FIXED_DT = 1 / 30;
const LOAD_IDLE_TIMEOUT_MS = 30000;
const CREATE_SCENE_TIMEOUT_MS = 20000;
const state = {
booted: false,
renderer: null,
canvas: null,
scene: null,
cameras: [],
update: null,
updateBroken: false,
updateErrors: [],
simTime: 0,
width: 1024,
height: 576,
rafCalls: 0,
shaderErrors: [],
loadErrors: [],
pendingLoads: new Set(),
hostWarnings: [],
bootInfo: null,
contentBox: null,
fullBox: null,
settleInfo: null,
cameraRepair: false,
cameraRepairs: [],
repairedSpecs: new Map(),
post: null,
postInfo: null,
};
/**
* Call the agent's update(t, dt), catching exceptions: the first throw is
* recorded (state.updateErrors + console.error so the node driver collects it
* as a console error → gate finding) and update() is disabled so the remaining
* views still render — an agent bug must never abort the whole render run.
*/
function runUpdate(t, dt) {
if (!state.update || state.updateBroken) return;
try {
state.update(t, dt);
} catch (e) {
state.updateBroken = true;
const msg = `update(t=${t.toFixed(2)}) threw: ${formatError(e)} — update() disabled, rendering continues without animation`;
state.updateErrors.push(msg);
console.error(msg);
}
}
/** Host canvas + the shared harness renderer (lib/browser/renderer.js). */
function makeHostRenderer(width, height) {
const canvas = document.createElement('canvas');
canvas.width = width;
canvas.height = height;
canvas.id = '3dcode-canvas';
document.body.appendChild(canvas);
return { renderer: makeRenderer(canvas, width, height), canvas };
}
/** The authored cameras, and each problem as {severity, text}: the severity is decided HERE,
* where the problem is known (the python gate used to re-derive it from the wording).
* The plan's own cameras pass the same fov / position / name rules (contracts/plan.CameraPlan). */
function validateCameras(raw) {
const out = [];
const problems = [];
const error = (text) => problems.push({ severity: 'error', text });
const warn = (text) => problems.push({ severity: 'warn', text });
if (!Array.isArray(raw)) {
error('createScene().cameras is not an array');
return { cameras: out, problems };
}
raw.forEach((c, i) => {
const p = c && c.position;
const l = c && c.lookAt;
const okVec = (v) => Array.isArray(v) && v.length === 3 && v.every((x) => Number.isFinite(x));
if (!c || typeof c !== 'object') { warn(`cameras[${i}] is not an object`); return; }
if (!okVec(p)) { error(`cameras[${i}] position must be [x,y,z] finite numbers`); return; }
if (!okVec(l)) { error(`cameras[${i}] lookAt must be [x,y,z] finite numbers`); return; }
const fov = Number.isFinite(c.fov) ? c.fov : 50;
if (fov < 5 || fov > 150) warn(`cameras[${i}] fov ${fov} outside [5,150]`);
if (p.every((x, k) => Math.abs(x - l[k]) < 1e-6)) warn(`cameras[${i}] position equals lookAt`);
const name = String(c.name || `cam_${i}`);
if (!/^[A-Za-z0-9_-]{1,64}$/.test(name)) {
warn(`cameras[${i}] name ${JSON.stringify(name)} must match [A-Za-z0-9_-]{1,64} — it becomes a render filename`);
return;
}
out.push({ name, position: p.map(Number), lookAt: l.map(Number), fov });
});
if (out.length === 0) error('no valid cameras (author 1-6 {name, position, lookAt, fov})');
if (out.length > 6) warn(`too many cameras (${out.length} > 6)`);
return { cameras: out, problems };
}
// Every GLB the scene asked for, with the geometry it brought: {url, geometry_uuids}.
// Reset per boot; read by census() to answer "was this asset actually USED?".
let loadedGlbs = [];
function makeLoaders(manager) {
const gltf = new GLTFLoader(manager);
// Record what each GLB load delivered. `Loader.loadAsync` is a promise wrapper around
// `this.load`, so wrapping load alone covers both call styles.
const origLoad = gltf.load.bind(gltf);
gltf.load = (url, onLoad, onProgress, onError) => origLoad(url, (res) => {
const uuids = [];
try { res?.scene?.traverse((o) => { if (o.geometry && o.geometry.uuid) uuids.push(o.geometry.uuid); }); } catch { /* census is best-effort */ }
loadedGlbs.push({ url: String(url), geometry_uuids: uuids });
if (onLoad) onLoad(res);
}, onProgress, onError);
const texture = new THREE.TextureLoader(manager);
const cube = new THREE.CubeTextureLoader(manager);
return { gltf, texture, cube, manager };
}
/** geometry uuid -> world box of every mesh drawing it (the GLB bookkeeping's one traversal). */
function geometryBoxes(scene) {
const used = new Map();
scene.traverse((o) => {
if (!o.geometry || !o.geometry.uuid || !(o.isMesh || o.isInstancedMesh)) return;
if (!used.has(o.geometry.uuid)) used.set(o.geometry.uuid, new THREE.Box3());
const box = drawableBox(o, THREE);
if (box) used.get(o.geometry.uuid).union(box);
});
return used;
}
/** Words of a GLB's file name that can name a camera for it: `lantern_room.glb` → ['lantern']. */
const GENERIC_HERO_WORDS = new Set(['room', 'detail', 'hero', 'main', 'view', 'shot', 'camera', 'asset', 'model', 'close', 'closeup', 'wide', 'zone', 'prop']);
function heroWords(url) {
const base = String(url).split('/').pop().replace(/\.glb$/i, '');
return base.replace(/([a-z0-9])([A-Z])/g, '$1 $2').split(/[^A-Za-z0-9]+/)
.map((w) => w.toLowerCase()).filter((w) => w.length >= 4 && !GENERIC_HERO_WORDS.has(w));
}
/** THE "camera named for a hero" rule: a name word of the GLB's file is in the camera's name.
* Camera repair re-aims by it, and the census carries it (`camera_checks[].hero_for`) for the
* frames gate (frame_metrics._hero_findings), which has no copy of its own. */
function namesHero(cameraName, url) {
const lower = String(cameraName || '').toLowerCase();
return heroWords(url).some((w) => lower.includes(w));
}
/** The loaded GLB a camera is named for, with its world box as placed — or null. */
function heroForCamera(name) {
if (!loadedGlbs.length) return null;
let boxes = null;
for (const g of loadedGlbs) {
if (!namesHero(name, g.url)) continue;
if (!boxes) { try { boxes = geometryBoxes(state.scene); } catch (e) { return null; } }
const all = new THREE.Box3();
for (const u of g.geometry_uuids) { const b = boxes.get(u); if (b && !b.isEmpty()) all.union(b); }
if (!all.isEmpty()) return { url: g.url, box: all };
}
return null;
}
/** World boxes of the SINGLE instances of one loaded GLB: its meshes in `scene`, grouped by the
* highest ancestor whose subtree draws each of the file's geometries no more often than the file
* itself does — a clone root, or a wrapper holding one clone; two clones under one wrapper split at
* the wrapper. `.clone()` shares geometry, so a uuid seen twice under a node is two copies. */
function glbInstanceBoxes(scene, g) {
const inFile = new Map();
for (const u of g.geometry_uuids) inFile.set(u, (inFile.get(u) || 0) + 1);
const meshes = [];
scene.traverse((o) => { if ((o.isMesh || o.isInstancedMesh) && o.geometry && inFile.has(o.geometry.uuid)) meshes.push(o); });
const below = new Map(); // ancestor -> Map(geometry uuid -> copies drawn under it)
for (const m of meshes) {
for (let a = m; a; a = a.parent) {
if (!below.has(a)) below.set(a, new Map());
const c = below.get(a);
c.set(m.geometry.uuid, (c.get(m.geometry.uuid) || 0) + 1);
}
}
const single = new Map(); // ancestor -> holds at most one copy of each geometry
const isSingle = (a) => {
if (!single.has(a)) single.set(a, [...below.get(a)].every(([u, n]) => n <= inFile.get(u)));
return single.get(a);
};
const boxes = new Map(); // instance root -> world box of its GLB meshes
for (const m of meshes) {
let root = m;
while (root.parent && isSingle(root.parent)) root = root.parent;
const box = drawableBox(m, THREE);
if (!box) continue;
if (!boxes.has(root)) boxes.set(root, new THREE.Box3());
boxes.get(root).union(box);
}
return [...boxes.values()].filter((b) => !b.isEmpty());
}
/** Per loaded GLB: did any of its geometry reach the rendered scene? `Object3D.clone()` SHARES
* BufferGeometry, so a cloned asset still matches; a deep `geometry.clone()` reads as unused —
* hence a WARN that says "no geometry from it", not "not used". */
function glbUsage(scene) {
let used;
try { used = geometryBoxes(scene); } catch { return []; }
return loadedGlbs.map((g) => {
let n = 0;
for (const u of g.geometry_uuids) if (used.has(u)) n += 1;
// the largest extent of ONE placed instance: "fills 0.3 % of the frame" reads as "microscopic"
// without a size (loop 23's lighthouse: a 4.4 m lantern room on a 30 m tower, far from every
// camera, judged "scaled far too small" for three rounds) — and until 2026-10-14 the union of
// every clone was that size (a 2.2 m sofa placed three times across a lounge was "6.5 m across
// as placed" to the frames gate and the judge). `instances` says how many copies stand in the scene.
let size = null;
let instances = 0;
try {
const boxes = glbInstanceBoxes(scene, g);
instances = boxes.length;
for (const b of boxes) size = Math.max(size ?? 0, ...b.getSize(new THREE.Vector3()).toArray());
} catch { size = null; }
return { url: g.url, meshes: g.geometry_uuids.length, meshes_in_scene: n, in_scene: n > 0,
size_m: size === null ? null : +size.toFixed(2), instances };
});
}
function waitForLoads(manager, timeoutMs) {
return new Promise((resolve) => {
let done = false;
const finish = (why) => { if (!done) { done = true; resolve(why); } };
// If nothing is loading the manager never fires onLoad; check idle flag.
const t0 = performance.now();
const tick = () => {
if (done) return;
if (!manager.__c3vPending) return finish('idle');
if (performance.now() - t0 > timeoutMs) return finish('timeout');
setTimeout(tick, 50);
};
tick();
});
}
/**
* Boot the host: renderer → import module → createScene → wait loads.
* @param {{sceneUrl:string,width?:number,height?:number}} opts
*/
async function boot(opts) {
const info = { ok: false, stage: 'init', error: '', cameras: [], camera_problems: [], renderer: '' };
state.bootInfo = info;
try {
loadedGlbs = [];
state.cameraRepair = !!opts.cameraRepair;
state.cameraRepairs = [];
state.repairedSpecs = new Map();
state.width = opts.width || 1024;
state.height = opts.height || 576;
window.requestAnimationFrame = () => { state.rafCalls += 1; return 0; };
window.cancelAnimationFrame = () => {};
const { renderer, canvas } = makeHostRenderer(state.width, state.height);
state.renderer = renderer;
state.canvas = canvas;
installShaderErrorHook(renderer, state.shaderErrors);
info.renderer = rendererString(renderer);
info.stage = 'import';
const mod = await import(opts.sceneUrl);
if (typeof mod.createScene !== 'function') {
throw new Error(`src/scene.js must export function createScene({THREE, renderer, loaders}); exports found: [${Object.keys(mod).join(', ')}]`);
}
info.stage = 'createScene';
const manager = new THREE.LoadingManager();
manager.__c3vPending = false;
manager.onStart = () => { manager.__c3vPending = true; };
manager.onLoad = () => { manager.__c3vPending = false; };
manager.onError = (url) => { const m = `failed to load ${url}`; if (!state.loadErrors.includes(m)) state.loadErrors.push(m); };
trackPendingLoads(manager);
const loaders = makeLoaders(manager);
const result = await raceCreateScene(mod, { THREE, renderer, loaders }, opts.createSceneTimeoutMs || CREATE_SCENE_TIMEOUT_MS);
if (!result || typeof result !== 'object') throw new Error('createScene() must return {scene, cameras, update}');
if (!(result.scene && result.scene.isScene)) throw new Error('createScene().scene is not a THREE.Scene');
const { cameras, problems } = validateCameras(result.cameras);
info.cameras = cameras;
info.camera_problems = problems;
state.scene = result.scene;
state.cameras = cameras;
state.update = typeof result.update === 'function' ? result.update : null;
if (!state.update) info.camera_problems.push({ severity: 'warn', text: 'createScene().update(t, dt) is not a function (scene will be static)' });
info.stage = 'loads';
const loadWait = await waitForLoads(manager, LOAD_IDLE_TIMEOUT_MS);
if (loadWait === 'timeout') state.hostWarnings.push('asset loads still pending after timeout');
info.stage = 'first_update';
runUpdate(0, 0);
state.simTime = 0;
state.scene.updateMatrixWorld(true);
// post chain (browser/post.js): ON for scene renders unless `post: false`.
// Built here — after the first update, so a scene that sets its grade hint
// while building has already set it. A chain that cannot be
// built is a host WARNING, never a boot failure: the raw path still renders.
if (opts.post !== false) {
info.stage = 'post';
try {
const { makePostChain } = await import('./browser/post.js');
state.post = makePostChain(state.renderer, state.scene, {
width: state.width, height: state.height, options: opts.postOptions || {},
});
state.postInfo = state.post.info;
for (const w of state.post.info.warnings) state.hostWarnings.push(`post: ${w}`);
} catch (e) {
state.post = null;
state.postInfo = { enabled: false, error: String((e && e.message) || e).slice(0, 300) };
state.hostWarnings.push(`post chain unavailable, plain render: ${state.postInfo.error}`);
}
} else {
state.postInfo = { enabled: false };
}
// settle (2026-08-30): deterministically seat floating / sunken assets before any
// census or render — the placement gate measured the errors for two batteries and
// the refine agent left 38 sunken + 22 floating standing in final rounds. Runs on
// every boot (probe and render see the same seated scene); --no-settle disables.
if (opts.settle !== false) {
info.stage = 'settle';
try {
const c0 = sceneCensus(state.scene, THREE);
const words = await (await fetch(new URL('./placement_words.json', import.meta.url))).json();
state.settleInfo = settleScene(state.scene, THREE, { groundY: c0.ground_y, contentBox: c0.content_bbox, words });
} catch (e) {
state.settleInfo = { count: 0, moves: [], error: String((e && e.message) || e).slice(0, 300) };
}
info.settled = state.settleInfo.count;
}
state.booted = true;
info.ok = cameras.length > 0;
// A camera-less scene used to fail with info.error EMPTY, so the caller
// reported `scene did not boot at stage 'ready': ` and named no reason —
// ~20 minutes of blind bisecting down to a two-line scene, twice.
// validateCameras already said WHY; carry it into the error.
if (!info.ok) {
info.error = 'createScene() returned no usable cameras'
+ (problems.length ? ': ' + problems.map((q) => q.text).join('; ') : '');
}
info.stage = 'ready';
} catch (e) {
info.error = formatError(e);
}
info.raf_calls = state.rafCalls;
info.load_errors = state.loadErrors.slice();
info.host_warnings = state.hostWarnings.slice();
return info;
}
function formatError(e) {
if (!e) return 'unknown error';
const msg = String(e.message || e);
const stack = String(e.stack || '').split('\n').slice(0, 6).join('\n');
return stack && stack.includes(msg) ? stack : `${msg}\n${stack}`;
}
/** Track which loader URLs are in flight so a boot timeout can name them. */
function trackPendingLoads(manager) {
const start = manager.itemStart.bind(manager);
const end = manager.itemEnd.bind(manager);
manager.itemStart = (url) => { state.pendingLoads.add(url); start(url); };
manager.itemEnd = (url) => { state.pendingLoads.delete(url); end(url); };
}
/**
* Await the agent's createScene() with a hard timeout: a classic
* `await new Promise(r => loaders.texture.load(url, r))` on a missing asset
* never settles (three's loaders skip onLoad on 404) and would otherwise hang
* the whole driver into its watchdog (exit 3, blamed on the harness). On
* expiry the boot fails at stage 'createScene' with an error naming the
* pending loader URLs — an agent-fixable scene failure, not a driver one.
*/
function raceCreateScene(mod, ctx, timeoutMs) {
const createScenePromise = Promise.resolve().then(() => mod.createScene(ctx));
createScenePromise.catch(() => {}); // no unhandled rejection if the timeout wins
let timer = null;
const timeout = new Promise((resolve, reject) => {
timer = setTimeout(() => {
const pending = [...state.pendingLoads].slice(0, 5);
let msg = `createScene() did not resolve within ${Math.round(timeoutMs / 1000)} s — an awaited promise never settled `
+ '(loader.load(...) without an onError handler on a missing/broken asset? prefer await loaders.gltf.loadAsync(url) in try/catch)';
if (pending.length) msg += `; pending loads: ${pending.join(', ')}`;
if (state.loadErrors.length) msg += `; load errors: ${state.loadErrors.slice(0, 5).join('; ')}`;
reject(new Error(msg));
}, timeoutMs);
});
return Promise.race([createScenePromise, timeout]).finally(() => clearTimeout(timer));
}
function buildCamera(spec) {
// camera repair (opt-in, --camera-repair): cameras belong to the plan and no refine
// agent can fix one, so a lens inside geometry is repaired here — the smallest
// backward/upward retreat that clears it, cached per camera name so every render of
// that camera uses the same repaired spec, recorded in census.camera_repair.
if (state.cameraRepair && spec && spec.name && Array.isArray(spec.position) && Array.isArray(spec.lookAt)) {
const key = spec.name + '|' + spec.position.join(',');
if (!state.repairedSpecs.has(key)) {
// A camera NAMED for a hero whose hero is out of its frame is re-aimed at the hero first:
// loop 25's lighthouse (2026-09-09) shot `LanternDetail` at the tower wall for three rounds
// while `hero_unseen` said 0.0 % each time and no session moved the plan's camera. Only
// when the hero's centre is outside the frustum — a small or far hero is the author's shot.
let base = spec;
let aimed = '';
try {
const hero = heroForCamera(spec.name);
if (hero) {
const c = hero.box.getCenter(new THREE.Vector3());
const cam0 = buildCameraRaw(spec);
const inFront = c.clone().applyMatrix4(cam0.matrixWorldInverse).z < 0;
const ndc = c.clone().project(cam0);
if (!(inFront && Math.abs(ndc.x) <= 1 && Math.abs(ndc.y) <= 1)) { base = { ...spec, lookAt: [c.x, c.y, c.z] }; aimed = hero.url; }
}
} catch (e) { base = spec; aimed = ''; }
let fix = null;
try { fix = repairCameraSpec(state.scene, base, THREE, buildCameraRaw); } catch (e) { fix = null; }
state.repairedSpecs.set(key, fix ? fix.spec : (aimed ? base : null));
if (fix || aimed) state.cameraRepairs.push({ name: spec.name, moved_back_m: fix ? fix.moved_back_m : 0, moved_up_m: fix ? fix.moved_up_m : 0,
moved_side_m: fix ? fix.moved_side_m || 0 : 0, nearest_before: fix ? fix.nearest_before : null,
inside_before: fix ? fix.inside_before : [], under_before: fix ? fix.under_before || '' : '',
blocked_before: !!(fix && fix.blocked_before), cut_before: fix ? fix.cut_before || '' : '',
aimed_at: aimed, nearest_after: fix ? fix.nearest_after : null });
}
const fixed = state.repairedSpecs.get(key);
if (fixed) return buildCameraRaw(fixed);
}
return buildCameraRaw(spec);
}
function buildCameraRaw(spec) {
const aspect = state.width / state.height;
if (!state.fullBox) { const c = sceneCensus(state.scene, THREE); state.fullBox = c.bbox; state.contentBox = c.content_bbox; }
const fb = state.fullBox;
let farCorner = 1000;
if (fb) {
farCorner = 0;
for (const x of [fb.min[0], fb.max[0]]) for (const y of [fb.min[1], fb.max[1]]) for (const z of [fb.min[2], fb.max[2]]) {
farCorner = Math.max(farCorner, Math.hypot(x - spec.position[0], y - spec.position[1], z - spec.position[2]));
}
}
const far = Number.isFinite(spec.far) ? spec.far : Math.max(1000, farCorner * 1.25 + 10);
const near = Number.isFinite(spec.near) ? spec.near : Math.max(0.05, Math.min(0.5, far / 20000));
const cam = new THREE.PerspectiveCamera(spec.fov || 50, aspect, near, far);
cam.position.set(...spec.position);
cam.lookAt(...spec.lookAt);
cam.updateMatrixWorld(true);
cam.updateProjectionMatrix();
return cam;
}
/** Advance the simulation deterministically to time t (fixed steps).
* Agent update() exceptions are recorded (runUpdate) and never propagate. */
function advanceTo(t) {
if (!state.update) return;
if (t < state.simTime - 1e-9) throw new Error(`cannot rewind time: at ${state.simTime}, asked ${t}`);
let steps = 0;
while (state.simTime + FIXED_DT <= t + 1e-9) {
state.simTime += FIXED_DT;
runUpdate(state.simTime, FIXED_DT);
steps += 1;
if (steps > 100000) throw new Error('too many update steps');
}
const rem = t - state.simTime;
if (rem > 1e-6) {
state.simTime = t;
runUpdate(t, rem);
}
}
/** One frame to the canvas — through the post chain when it is armed. */
function renderOnce(cam) {
if (state.post) {
state.post.refreshGrade(); // a scene may set userData.grade from update()
state.post.render(cam);
} else {
state.renderer.render(state.scene, cam);
}
try { const gl = state.renderer.getContext(); if (gl && gl.finish) gl.finish(); } catch (e) { /* ignore */ }
}
/**
* What a rig view must not draw: visible see-through meshes classified 'sky' whose whole box
* lies below `eye` (a cloud deck seen from above), and the harness-injected room shell's
* ceiling when the eye is above it — an interior seen by the overview rig was a closed box,
* and the pairwise judge called the bakery "a tiny fragment in the overviews" against a
* one-shot whose room had no roof (cmp7, 2026-09-09). Lifting the shell's lid shows the
* layout the rig exists to show; an author's own roof stays, and so does every authored camera.
*/
function skyLayersBelow(eye) {
const out = [];
state.scene.traverse((o) => {
if (!(o.isMesh || o.isInstancedMesh) || !o.visible || !o.geometry) return;
if (o.parent && o.parent.name === 'RoomShell' && /^Ceiling/.test(o.name || '')) {
const box = drawableBox(o, THREE);
if (box && box.max.y < eye.y) out.push(o);
return;
}
if (!nonSolid(o)) return;
const box = drawableBox(o, THREE);
if (!box) return;
if (o.frustumCulled === false && o.geometry.isInstancedBufferGeometry) {
// an instanced billboard deck keeps its quad at the origin and offsets it in the shader:
// its instance offsets are the only honest extent
const off = o.geometry.getAttribute('iOff');
if (off) { box.makeEmpty(); for (let i = 0; i < off.count; i++) box.expandByPoint(new THREE.Vector3(off.getX(i), off.getY(i), off.getZ(i))); }
}
if (box.isEmpty() || box.max.y >= eye.y) return;
if (classifyBackdrop(o, box) === 'sky' || /cloud|cumulus|cirrus/i.test(o.name || '')) out.push(o);
});
return out;
}
/** Render camera spec at time t; returns {dataUrl, ms}. */
function renderAt(spec, t) {
if (!state.booted) throw new Error('host not booted');
advanceTo(t);
state.scene.updateMatrixWorld(true);
const cam = buildCamera(spec);
const t0 = performance.now();
const savedFog = state.scene.fog;
if (spec.noFog) state.scene.fog = null; // overview rig: structure over atmosphere
// …and no see-through sky layer under the lens: a billboard cloud deck seen from above
// is a grid of white discs over the sea, and the judge read it as "a polka-dot sea
// shader" on two lighthouse runs (2026-09-09). The authored cameras keep their clouds.
const hiddenLayers = spec.noFog ? skyLayersBelow(cam.position) : [];
for (const o of hiddenLayers) o.visible = false;
try {
renderOnce(cam);
} finally {
state.scene.fog = savedFog;
for (const o of hiddenLayers) o.visible = true;
}
const ms = Math.round(performance.now() - t0);
// the camera actually used: differs from spec.position when camera repair fired
return { dataUrl: state.canvas.toDataURL('image/png'), ms,
position: [cam.position.x, cam.position.y, cam.position.z] };
}
/** Repairs performed so far ({name, moved_back_m, moved_up_m, ...} per camera).
* Repair fires lazily on the first build of each camera, so drivers read this
* AFTER their render evaluations to stitch census.camera_repair (review-3 S5). */
function cameraRepairs() {
return state.cameraRepairs.slice();
}
/**
* Camera instruments (renders): near geometry, frame luminance stats and
* coverage (content / ground / sky fractions of the frame, via mask passes).
*/
function cameraChecks(spec) {
const cam = buildCamera(spec);
state.scene.updateMatrixWorld(true);
const near = nearGeometry(state.scene, cam, THREE, undefined, Array.isArray(spec.lookAt) ? spec.lookAt : null);
// the instruments see what the rig view draws (a lifted lid, no cloud deck under the eye)
const hiddenLayers = spec.noFog ? skyLayersBelow(cam.position) : [];
for (const o of hiddenLayers) o.visible = false;
let stats = {};
let coverage = {};
let glbFrac = {};
try {
renderOnce(cam);
stats = frameStats(state.canvas);
try {
coverage = frameCoverage(state.renderer, state.scene, cam, state.canvas, THREE, state.contentBox);
} catch (e) {
state.hostWarnings.push(`coverage failed for ${spec.name}: ${e.message}`);
}
if (loadedGlbs.length) {
try {
glbFrac = glbCoverage(state.renderer, state.scene, cam, state.canvas, THREE, loadedGlbs);
} catch (e) {
state.hostWarnings.push(`glb coverage failed for ${spec.name}: ${e.message}`);
}
}
} finally {
for (const o of hiddenLayers) o.visible = true;
}
const heroFor = loadedGlbs.filter((g) => namesHero(spec.name, g.url)).map((g) => g.url);
return { name: spec.name, ...near, ...stats, ...coverage, glb_frac: glbFrac, hero_for: heroFor };
}
/**
* `cameraChecks` for a view whose PIXELS another renderer made (scene_blender, D1): the
* geometry instruments (near geometry, coverage masks) still come from this scene, the
* luminance statistics from `dataUrl` — the other renderer's frame — and a camera with no
* external frame carries no luminance at all (this scene's own pixels are not the picture).
*/
async function externalCameraChecks(spec, dataUrl) {
const chk = cameraChecks(spec);
for (const k of FRAME_STAT_KEYS) delete chk[k];
return dataUrl ? { ...chk, ...(await imageFrameStats(dataUrl)) } : chk;
}
/** Force-compile every material as seen from spec (or the first camera). */
function compileAll(spec) {
const cam = buildCamera(spec || state.cameras[0] || { position: [10, 10, 10], lookAt: [0, 0, 0], fov: 50 });
captureMaterialSources(state.scene, THREE);
const t0 = performance.now();
state.renderer.compile(state.scene, cam);
renderOnce(cam);
// shadow + depth programs compile lazily; a second frame from another spot
if (state.cameras.length > 1) renderOnce(buildCamera(state.cameras[state.cameras.length - 1]));
const ms = Math.round(performance.now() - t0);
attributeErrors(state.shaderErrors);
const programs = state.renderer.info.programs ? state.renderer.info.programs.length : null;
return { compile_ms: ms, programs, shader_errors: state.shaderErrors.slice(), material_audit: materialAudit(state.scene, THREE), custom_materials: captured.length };
}
/** Measure update+render throughput over ~seconds (advances sim time). */
function fps(seconds, spec) {
const cam = buildCamera(spec || state.cameras[0]);
const deadline = performance.now() + seconds * 1000;
let frames = 0;
const t0 = performance.now();
while (performance.now() < deadline) {
state.simTime += FIXED_DT;
runUpdate(state.simTime, FIXED_DT);
if (state.post) state.post.render(cam); else state.renderer.render(state.scene, cam);
frames += 1;
}
try { state.renderer.getContext().finish(); } catch (e) { /* ignore */ }
const elapsed = (performance.now() - t0) / 1000;
// draw calls / triangles must stay the SCENE's numbers: renderer.info resets on
// every render() call, so after a composer frame it holds the last full-screen
// quad. One plain render refills it with what the agent's budget is about.
if (state.post) state.renderer.render(state.scene, cam);
const r = state.renderer.info.render;
return { fps: frames / Math.max(elapsed, 1e-3), frames, seconds: elapsed, draw_calls: r.calls, triangles: r.triangles };
}
/** Per-asset placement table (host_placement.mjs) — never throws: a failure is `{error}`. */
function placement() {
try {
return sceneCensus(state.scene, THREE, { placement: true }).placement;
} catch (e) {
return { error: String((e && e.message) || e).slice(0, 400) };
}
}
function census() {
const c = sceneCensus(state.scene, THREE);
c.glb_assets = glbUsage(state.scene);
if (state.settleInfo) c.settle = state.settleInfo;
if (state.cameraRepairs.length) c.camera_repair = state.cameraRepairs.slice();
if (state.postInfo) c.post = state.postInfo;
state.contentBox = c.content_bbox;
state.fullBox = c.bbox;
c.cameras = state.cameras.length;
c.raf_calls = state.rafCalls;
return c;
}
/** Probe-only observation around the normal deterministic update steps. */
function probeUpdateHooks(t) {
const start = state.simTime;
try {
const report = observeUpdateHooks(state.scene, () => advanceTo(t));
return { ...report, from_time: start, to_time: state.simTime };
} catch (error) {
// Optional instrumentation must not turn an unusual userData descriptor
// into an agent build failure; the ordinary update error checks still run.
advanceTo(t);
return { error: String(error?.message || error).slice(0, 400), from_time: start, to_time: state.simTime };
}
}
window.__c3v = {
boot,
renderAt,
cameraChecks,
externalCameraChecks,
cameraRepairs,
compileAll,
census,
placement,
probeUpdateHooks,
fps,
post: () => (state.postInfo ? { ...state.postInfo } : null),
hostWarnings: () => state.hostWarnings.slice(),
shaderErrors: () => state.shaderErrors.slice(),
updateErrors: () => state.updateErrors.slice(),
cameras: () => state.cameras.slice(),
};
window.__c3v_ready = true;