Official Codebase of 3DCodeVerse
runtime_js — harness-owned node runtime
Everything Three.js / headless-Chrome the harness does lives here. Agent code
never imports from this directory; it only imports three (and
three/addons/...), which the harness resolves for it — through the
--import lib/resolve_three.mjs hook in node, and through the import map
serve.cjs::importMapHtml() in the browser (runtime_js is mounted at
/__runtime/; nothing is fetched from a CDN).
Install
This directory is an ordinary npm package owned by the harness: package.json
and package-lock.json are committed, node_modules/ is not (gitignored,
~97 MB, 99 packages). Node itself is a system prerequisite — installing it is
separate from what npm ci does here.
Node floor: 20.6.0 (package.json engines.node; developed on v24.14.0).
20.6.0 is where node --import lands, which lib/resolve_three.mjs needs; the
npm dependencies themselves bottom out at node 18, and node:util.parseArgs
(the CLI helpers) at 18.3. Between 20.6 and 22.15 the resolver registers the
older async loader hooks (lib/resolve_three_async.mjs, a separate loader
thread) instead of the in-thread module.registerHooks; the resolutions are
identical. The python side refuses to spawn an older node with an actionable
message (codeverse3d.spatial.node.NODE_MIN, mirrored by 3dcodeverse doctor's node
row), and tests/core/test_portability.py pins the two declarations together.
The floor is exercised, not assumed: the 139 node-marked tests all pass on node
20.19.5 (C3D_BINARIES__NODE=/path/to/node20 pytest tests -m "node and not live and not blender").
cd harness/runtime_js
npm ci # exact-lockfile install (~2 s); NOT `npm install`
npx puppeteer browsers install chrome # only if ~/.cache/puppeteer is empty
bash harness/setup.sh does both of these (plus the python install, the agy / claude / codex CLIs at their
latest, and 3dcodeverse doctor) and skips npm ci when the lockfile has not moved.
Re-run npm ci after a fresh clone or after pulling a package.json /
package-lock.json change — it deletes node_modules/ first, so never while a
render or bench is running. Deps: three 0.182 (export + render + scene host),
puppeteer 24 (headless Chrome, downloads its own build into ~/.cache/puppeteer).
Full guide: ../docs/INSTALL.md.
gpu_launch.cjs launchBrowser({gpu:'auto'|'on'|'off'}) → {browser, gpu, renderer, shared, release()};
rendererInfo(browser). Callers must release(), never browser.close(): connect-first
reuse shares one browser per backend via browser_daemon.cjs (endpoint file under
C3D_CACHE_DIR, connect ~5 ms vs ~0.55 s launch; C3D_BROWSER_REUSE=off disables).
WSL2 hardware WebGL (ANGLE gl-egl + Mesa d3d12 env), UNMASKED_RENDERER probe,
negative verdict cached 20 min in ~/.cache/codeverse3d/gpu_probe.json, SwiftShader fallback
browser_daemon.cjs detached keeper of the shared browser (one per gpu|cpu backend): advertises its
ws endpoint, reaps after ~90 s idle (endpoint-file mtime heartbeat + open-page count)
serve.cjs serveDirs({root, mounts, routes}) loopback static server (MIME table, CORS);
runtime_js is always mounted at /__runtime/; importMapHtml() maps 'three' +
'three/addons/' onto it — nothing is ever fetched from the internet
export_glb.mjs node --import lib/resolve_three.mjs export_glb.mjs --ws <ws> [--entry src/object.js]
[--out artifacts/object.glb] [--census artifacts/census.json]
imports the agent module, build(THREE) (awaits promises), validates
(NaN/empty-bbox errors name the mesh + part), runs an exported selfcheck(THREE, root)
if any (throw → SelfCheckError), bakes InstancedMesh copies into named meshes
(lib/instances.mjs — trimesh ignores EXT_mesh_gpu_instancing), keeps the source
placement (off-ground/off-centre → warning + census.placement_offset), strips textures (warning),
writes GLB + census.json (only what the export knows: placement offset, baked
instances, selfcheck, tick, unnamed meshes, warnings — spatial/measure.py measures
the GLB); on failure export_error.json +
{ok:false,error:{type,message,file,line,frames,part?}}
render_glb.mjs --glb --out --views '[{name,azimuth,elevation}]' [--mode shaded|wire|normals|silhouette|clay]
[--width --height] [--isolate A,B] [--explode 0.3] [--background studio|white|transparent]
[--anim-time t] [--gpu auto|on|off] [--shadow 0|1]
writes view_<name>.png + views.json; last stdout line = JSON record. Thin entry:
args/JSON protocol from lib/cli.mjs, browser + server from lib/host_env.mjs,
browser release from lib/host_page.mjs, everything visual from lib/browser/
lib/resolve_three.mjs node --import hook: bare 'three' / 'three/addons/*' resolve
from runtime_js/node_modules for modules anywhere on disk (NODE_PATH is CJS-only);
module.registerHooks on node >= 22.15, module.register + lib/resolve_three_async.mjs
on the 20.6 floor. Redirect rule stated once in lib/three_redirect.mjs
lib/node_polyfills.mjs FileReader shim so GLTFExporter writes binary GLB without a DOM
lib/census.mjs NaN/Infinity check naming mesh + part, world boxes, geometry triangles (node + browser)
lib/instances.mjs bakeInstancedMeshes(THREE, root): InstancedMesh → sibling plain meshes Name_0.. in its place
lib/stack.mjs Error → {type,message,file,line,frames} with workspace-relative src/ paths
lib/syntax_check.mjs THE JS syntax check: every file parsed as an ES module in ONE node
(vm.SourceTextModule, never linked or run; `node --check` only for a failing
file's line). CLI for the python lints, findSyntaxError() for export_glb
lib/asset_check.mjs the scene-asset checker: import one asset module, call build<Pascal>(THREE, {}),
measure the group (size, tris, meshes, materials, NaN positions); one JSON line
for tracks/scene_assets.check_threejs_asset
lib/browser/*.js page-side ESM (served through /__runtime/): renderer.js (THE WebGLRenderer factory —
sRGB + ACES + PCF shadows + pixel ratio 1, used by the object rig AND the scene host),
camera_fit.js (azimuth/elevation → tight bbox fit; the distance math itself is
lib/orbit.mjs::fitDistance, shared with the scene orbit rig), studio.js
(softbox PMREM + key/fill/rim, shadow catcher, render modes), render_rig.js
(load GLB, isolate/explode/anim, views)
lib/browser/studio_env.js procedural softbox environment, backdrop and contact-shadow textures of the
object rig (v2): generated from constants, so a render is byte-reproducible
lib/browser/post.js THE scene post chain (object renders stay raw): RenderPass → finite clamp → GTAO →
glow bloom → grade (scene.userData.grade) → OutputPass; `--no-post` / C3D_POST=0 skips it
probe_scene.mjs scene build gate: boot src/scene.js, census, update(t,dt), first-camera checks;
--compile folds the full shader preflight into the SAME boot (shader_report);
--sun-azimuth returns harness-fitted overview + per-group camera specs (lib/orbit.mjs)
check_shaders.mjs the effect-library tests' compile driver: the same preflight as probe_scene --compile,
plus --module to scope the static audit to one fixture file
render_scene.mjs authored cameras + orbit rig renders at times, metrics.json/views.json
fit_orbit.mjs the same framingBox + fitOrbitCameras on a census.json WITHOUT a browser (scene_blender)
lib/host_env.mjs ESM adapters over gpu_launch.cjs + serve.cjs (launchBrowser, serveWorkspace)
lib/host_page.mjs node-side page driver: serve ws, launch, boot scene, collect errors, release the browser
lib/scene_host.mjs page-side host (window.__c3v): boot/renderAt/census/compileAll/fps/cameraChecks
lib/glb_scene.mjs the createScene the host boots for an OFFLINE scene (`--glb`, scene_blender): hoists the
census GLB's root nodes + extras.c3d_cameras — the same census and placement code
lib/host_compile.mjs page-side compile machinery: capture every custom material's final GLSL, attribute
compiler errors to materials by source line, audit runtime materials (fog/uTime)
lib/host_shader_errors.mjs renderer.debug.onShaderError hook: every `ERROR: n:m` with its assembled source line
lib/host_placement.mjs placementTable(scene): does every placed asset sit on something (feet columns, gaps,
sunk, water, interpenetration; time-budgeted) + the boot-time settle
lib/placement_words.json the seated-vocabulary both the settle and spatial/scene_placement.py read
lib/update_hooks.mjs observeUpdateHooks: which userData.update hooks the sampled update interval never called
lib/orbit.mjs THE camera-fit owner: fitDistance (exact per-corner frustum fit — also used by the
object rig through lib/browser/camera_fit.js), fitOverviewCamera, fitZoneCamera
(eye level), fitOrbitCameras, framingBox
lib/backdrop.mjs THE sky/ground/content classifier (name + world-box rules), shared by the census
(host_census.mjs) and the frame-coverage instrument (host_coverage.mjs)
lib/host_metrics.mjs page-side frame instruments: sampleFrame (the shared 96x54 readback grid),
frameStats (luminance), nearGeometry (camera-in-geometry rays)
lib/shader_report.mjs shared shader-preflight report builder (static + compile stages)
lib/glsl_audit.mjs static GLSL audits + compiler-line → file:line mapping
Conventions (from codeverse3d/conventions.py): Y up, +Z front, meters; azimuth 0 = front,
counter-clockwise seen from above (90 = camera on +X); elevation above the horizon. Views are
fitted per camera so the projected bbox fills ~85 % of the frame.
Python entry points: codeverse3d.spatial.node.run_node, codeverse3d.spatial.render.render_glb,
codeverse3d.languages.threejs.ThreeJsRuntime.
Quick checks:
node --import lib/resolve_three.mjs export_glb.mjs --ws /path/to/ws
node render_glb.mjs --glb ws/artifacts/object.glb --out /tmp/r --views '[{"name":"front","azimuth":0,"elevation":10}]'