3D engine that AI agents drive
JavaScript 3d3d-engineagentic-aiai-agentsblenderclaude-codegame-enginegaussian-splattinggltfjavascriptmcpmcp-servermodel-context-protocolpath-tracerpath-tracingpbrrenderingthreejs-alternativewebgl2webgpu
Add crucible pack and the <crucible-scene> runtime element (#2178)
Nguyen Xuan An08cfc9bf090e
diff --git a/FEATURES.md b/FEATURES.mdindex 6e5cdfca..8cc5752d 100644--- a/FEATURES.md+++ b/FEATURES.md@@ -472,6 +472,13 @@ optional `Ready` expression the driver waits for, and `Drive`.- Source: `bin/crucible-mcp.mjs`- Drive: none: not a page+### `crucible-pack`+- Name: Compiles a recipe into a runtime-only web bundle with a `<crucible-scene>` element (docs/pack.md)+- Surface: CLI+- Reach: command `npx crucible pack <scene.json> --out <dir>`+- Source: `bin/crucible.mjs`, `src/scene-pack.js`, `src/crucible-scene.js`+- Drive: none: not a page+### `crucible-addon-check`- Name: Checks an addon folder against the addon contract (docs/addons.md)- Surface: CLIdiff --git a/bin/crucible.mjs b/bin/crucible.mjsnew file mode 100644index 00000000..e80f1229--- /dev/null+++ b/bin/crucible.mjs@@ -0,0 +1,63 @@+#!/usr/bin/env node+// The crucible command line. `crucible pack <scene.json> --out <dir>` compiles a recipe into a runtime-only web bundle (docs/pack.md).+import { existsSync } from 'node:fs';+import { dirname, join, resolve } from 'node:path';+import { fileURLToPath, pathToFileURL } from 'node:url';++const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');+const USAGE = 'Usage: crucible pack <scene.json> --out <dir> [--poster <picture.webp>] [--runtime <crucible-scene.js>]';+const PACK_FLAGS = Object.freeze(['--out', '--poster', '--runtime']);++export function parsePackArguments(argumentList) {+ const options = { recipePath: null };+ for (let index = 0; index < argumentList.length; index += 1) {+ const argument = argumentList[index];+ if (PACK_FLAGS.includes(argument)) {+ const value = argumentList[index + 1];+ if (value === undefined || value.startsWith('--')) throw new TypeError(`${argument}: pass a value, such as ${argument} <path>.`);+ options[argument.slice(2)] = value;+ index += 1;+ } else if (argument.startsWith('--')) {+ throw new TypeError(`${argument}: unknown option; crucible pack takes ${PACK_FLAGS.join(', ')}.`);+ } else if (options.recipePath === null) {+ options.recipePath = argument;+ } else {+ throw new TypeError(`${argument}: only one scene.json can be packed at a time; pass the others in separate runs.`);+ }+ }+ return options;+}++// A published package carries build/scene-pack.js; a source checkout runs src/scene-pack.js directly.+async function loadPackModule() {+ const built = join(packageRoot, 'build', 'scene-pack.js');+ return import(pathToFileURL(existsSync(built) ? built : join(packageRoot, 'src', 'scene-pack.js')).href);+}++async function main(argumentList) {+ const [command, ...rest] = argumentList;+ if (command !== 'pack') {+ console.error(command === undefined ? USAGE : `${command}: unknown command; the only command is pack.\n${USAGE}`);+ return 1;+ }+ try {+ const options = parsePackArguments(rest);+ const { packRecipeFile } = await loadPackModule();+ const result = await packRecipeFile({+ recipePath: options.recipePath,+ outDir: options.out,+ posterPath: options.poster,+ runtimePath: options.runtime,+ packageRoot,+ });+ console.log(`Packed ${result.packBytes} bytes into ${result.outDir}: ${result.files.join(', ')}`);+ return 0;+ } catch (error) {+ console.error(`crucible pack: ${error.message}\n${USAGE}`);+ return 1;+ }+}++if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {+ process.exitCode = await main(process.argv.slice(2));+}diff --git a/changes/2178.md b/changes/2178.mdnew file mode 100644index 00000000..d03fe237--- /dev/null+++ b/changes/2178.md@@ -0,0 +1 @@+- `crucible pack <scene.json> --out <dir>` compiles a recipe into a runtime-only web bundle, and `<crucible-scene>` shows its poster at once and swaps in live 3D without the recipe compiler (#2178)diff --git a/config/vite.lib.config.js b/config/vite.lib.config.jsindex 6554250d..957b9106 100644--- a/config/vite.lib.config.js+++ b/config/vite.lib.config.js@@ -37,7 +37,7 @@ export default defineConfig({build: {copyPublicDir: false,rolldownOptions: {- external: ['@dimforge/rapier3d-compat', 'jolt-physics', 'manifold-3d'],+ external: ['@dimforge/rapier3d-compat', 'jolt-physics', 'manifold-3d', /^node:/],output: { banner: legalBanner },},outDir: 'build',@@ -73,6 +73,8 @@ export default defineConfig({grass: 'src/grass.js',clutter: 'src/clutter.js','light-bake': 'src/light-bake.js',+ 'scene-pack': 'src/scene-pack.js',+ 'crucible-scene': 'src/crucible-scene.js','light-bake-gpu': 'src/light-bake-gpu.js','ground-bounce': 'src/ground-bounce.js','floor-sky-visibility': 'src/floor-sky-visibility.js',diff --git a/docs/pack.md b/docs/pack.mdnew file mode 100644index 00000000..1bc96db8--- /dev/null+++ b/docs/pack.md@@ -0,0 +1,53 @@+# Pack: a recipe as a runtime-only web bundle++`crucible pack` compiles a recipe (`format: "crucible.scene"`) in Node into a compact data file, so a web page loads the renderer and the data but not the recipe compiler. The page uses a `<crucible-scene>` element: it shows a poster picture first, then swaps in live 3D when the scene is ready.++This is slice 1 of #2178. It packs a still scene. Scroll, hover and click triggers, and baked lightmaps, come in later slices.++## Pack a scene++```sh+npx crucible pack scene.json --out dist/scene --poster shot.webp+```++It writes into `dist/scene`:++| File | What it holds |+| --- | --- |+| `scene.pack` | the compiled parts (geometry as typed arrays), camera, lighting, effects and the shader modules the scene needs |+| `crucible-scene.js` and its chunks | the runtime: the `<crucible-scene>` element and the renderer |+| `poster.webp` | the picture you passed with `--poster` (WebP, PNG or JPEG) |+| `index.html` | a page that uses all of the above |++`--poster` copies a picture you rendered. Pack does not render one itself yet. Without it the element shows a dark box until the 3D is ready. `--runtime <file>` names a built `crucible-scene.js` when the package has no `build/` folder, such as in a source checkout.++Packing the same recipe twice writes the same `scene.pack` bytes.++## The element++```html+<script type="module" src="https://example.com/scene/crucible-scene.js"></script>+<crucible-scene src="https://example.com/scene/scene.pack" poster="https://example.com/scene/poster.webp" style="height: 480px"></crucible-scene>+```++- The poster draws at once. The element then loads the pack and the renderer, draws the scene and fades the poster out.+- The `state` attribute is `loading`, `live` or `error`. The element fires `crucible-scene-ready` or `crucible-scene-error` (with `detail.message`). After an error the poster stays.+- Changing `src` or `poster` reloads it. It draws again when it changes size.++`crucible-scene.js` imports no `agent-scene` module. `tests/scene-pack.test.js` checks the import graph.++## What a pack refuses++Pack names the recipe field and what to change. For now it refuses `motion`, `timeline`, `physics`, `cloth`, `particles`, `game`, `postPasses`, `armatures`, `environment.sky`, `environment.hdri`, cascaded shadows, area lights, line art, material snippets and procedural material patterns. Scenes light with `environment.setup`. The automatic floor is not drawn: put a floor in the recipe.++## What it costs++Measured on `public/recipes/view-transform.json` (a lamp, six parts), Chrome, gzip of every file the page downloaded, with the same lighting and the same still:++| | Recipe build (compiler + renderer + recipe) | Packed bundle |+| --- | --- | --- |+| JavaScript | 232,047 B | 113,960 B |+| Data | the recipe JSON, inside the JavaScript | `scene.pack`, 114,681 B |+| Total | 232,182 B | 228,641 B |++The JavaScript halves. The data does not shrink for this scene, because the baked reflection probes of its two metal parts are 196 KB before gzip. A scene without baked probes pays much less data.diff --git a/package.json b/package.jsonindex e45f3a17..cb5e1028 100644--- a/package.json+++ b/package.json@@ -64,6 +64,7 @@"module": "./build/67.module.js","bin": {"crucible-mcp": "./bin/crucible-mcp.mjs",+ "crucible": "./bin/crucible.mjs","crucible-addon-check": "./bin/crucible-addon-check.mjs","67js-mcp": "./bin/67js-mcp.mjs","67js-addon-check": "./bin/67js-addon-check.mjs"@@ -102,6 +103,7 @@"./addons/grass": "./build/grass.js","./addons/clutter": "./build/clutter.js","./addons/light-bake": "./build/light-bake.js",+ "./addons/crucible-scene": "./build/crucible-scene.js","./addons/light-bake-gpu": "./build/light-bake-gpu.js","./addons/ground-bounce": "./build/ground-bounce.js","./addons/floor-sky-visibility": "./build/floor-sky-visibility.js",diff --git a/src/crucible-scene.js b/src/crucible-scene.jsnew file mode 100644index 00000000..a03344cf--- /dev/null+++ b/src/crucible-scene.js@@ -0,0 +1,150 @@+// <crucible-scene src="scene.pack" poster="poster.webp">: the runtime of `crucible pack` (docs/pack.md).+// It shows the poster at once, loads the packed scene and the renderer, then swaps the canvas in. It imports no+// agent-scene module: the recipe was compiled ahead of time, so the page pays for the renderer and nothing else.+import { decodePack } from './scene-pack-format.js';+import { loadPackShaderModules } from './scene-pack-shaders.js';++export const SCENE_STATES = Object.freeze(['loading', 'live', 'error']);++const TEMPLATE = `+<style>+ :host { display: block; position: relative; overflow: hidden; background: #111; }+ canvas, img { position: absolute; inset: 0; width: 100%; height: 100%; display: block; }+ img { object-fit: cover; transition: opacity 240ms ease; }+ canvas { opacity: 0; transition: opacity 240ms ease; }+ :host([state="live"]) canvas { opacity: 1; }+ :host([state="live"]) img { opacity: 0; pointer-events: none; }+</style>+<img part="poster" alt="" hidden>+<canvas part="canvas"></canvas>+`;++async function fetchPack(url) {+ const response = await fetch(url);+ if (!response.ok) throw new Error(`<crucible-scene src="${url}"> answered ${response.status}; point src at the scene.pack that crucible pack wrote.`);+ return decodePack(await response.arrayBuffer());+}++// The renderer and its lighting load after the poster is on screen, so the first paint never waits for them.+async function createLiveRenderer(canvas, scene) {+ const [{ CrucibleRenderer }, { createLightingSetupMap }] = await Promise.all([+ import('./renderer.js'),+ import('./lighting-setups.js'),+ loadPackShaderModules(scene.shaderModules),+ ]);+ const environment = {+ ...scene.environment,+ map: createLightingSetupMap(scene.environment.setup, {+ intensity: scene.environment.environmentIntensity,+ rotation: scene.environment.environmentRotation,+ showBackground: scene.environment.world,+ }),+ };+ const renderer = new CrucibleRenderer(canvas, scene.parts, {+ ground: false,+ hdr: true,+ depth: true,+ world: scene.environment.world,+ environment,+ shadowBounds: scene.shadowBounds,+ });+ return { renderer, environment };+}++export class CrucibleSceneElement extends HTMLElement {+ static observedAttributes = ['src', 'poster'];++ #renderer = null;+ #frame = null;+ #resizeObserver = null;+ #loadToken = 0;+ // An element that upgrades after parsing gets its attributes before connectedCallback; only a change after the first load reloads.+ #started = false;++ constructor() {+ super();+ this.attachShadow({ mode: 'open' }).innerHTML = TEMPLATE;+ }++ connectedCallback() {+ this.#started = true;+ this.#showPoster();+ this.#load();+ }++ disconnectedCallback() {+ this.#started = false;+ this.#dispose();+ }++ attributeChangedCallback(name) {+ if (!this.#started) return;+ if (name === 'poster') this.#showPoster();+ if (name === 'src') this.#load();+ }++ get state() {+ return this.getAttribute('state');+ }++ #showPoster() {+ const image = this.shadowRoot.querySelector('img');+ const poster = this.getAttribute('poster');+ image.hidden = !poster;+ if (poster) image.src = poster;+ }++ #dispose() {+ this.#loadToken += 1;+ this.#resizeObserver?.disconnect();+ this.#resizeObserver = null;+ if (this.#frame !== null) cancelAnimationFrame(this.#frame);+ this.#frame = null;+ this.#renderer?.dispose?.();+ this.#renderer = null;+ }++ async #load() {+ this.#dispose();+ const token = this.#loadToken;+ const source = this.getAttribute('src');+ this.setAttribute('state', 'loading');+ try {+ if (!source) throw new Error('<crucible-scene> needs a src attribute: the scene.pack that crucible pack wrote.');+ const scene = await fetchPack(source);+ const canvas = this.shadowRoot.querySelector('canvas');+ const { renderer, environment } = await createLiveRenderer(canvas, scene);+ if (token !== this.#loadToken) {+ renderer.dispose?.();+ return;+ }+ this.#renderer = renderer;+ this.#startDrawing(scene, environment);+ this.setAttribute('state', 'live');+ this.dispatchEvent(new CustomEvent('crucible-scene-ready', { detail: { parts: scene.parts.length } }));+ } catch (error) {+ if (token !== this.#loadToken) return;+ this.setAttribute('state', 'error');+ this.dispatchEvent(new CustomEvent('crucible-scene-error', { detail: { message: error.message } }));+ }+ }++ // A still scene draws again only when the element changes size.+ #startDrawing(scene, environment) {+ const draw = () => {+ this.#frame = null;+ this.#renderer.resize();+ this.#renderer.render({ ...scene.camera, environment, effects: scene.effects, exposure: scene.effects.exposure, time: 0 });+ };+ const schedule = () => {+ if (this.#frame === null) this.#frame = requestAnimationFrame(draw);+ };+ this.#resizeObserver = new ResizeObserver(schedule);+ this.#resizeObserver.observe(this);+ schedule();+ }+}++if (typeof customElements !== 'undefined' && !customElements.get('crucible-scene')) {+ customElements.define('crucible-scene', CrucibleSceneElement);+}diff --git a/src/scene-pack-format.js b/src/scene-pack-format.jsnew file mode 100644index 00000000..c50ea474--- /dev/null+++ b/src/scene-pack-format.js@@ -0,0 +1,105 @@+// The file format of `crucible pack` (docs/pack.md): a compiled scene as one JSON header plus one binary block.+// This module is shared by the Node compiler (src/scene-pack.js) and the web runtime (src/crucible-scene.js), so it imports+// nothing: the runtime must not pull any agent-scene code through it.++export const PACK_FORMAT = 'crucible.pack';+export const PACK_VERSION = 1;++const TYPED_ARRAYS = Object.freeze({+ Float32Array, Float64Array, Int8Array, Uint8Array, Uint8ClampedArray, Int16Array, Uint16Array, Int32Array, Uint32Array,+});+const TYPED_MARKER = '$typed';+const ALIGNMENT = 4;+const HEADER_BYTES = 8;+const MAGIC = 0x4b435243; // "CRCK" read as little endian++function padTo(length, alignment) {+ return Math.ceil(length / alignment) * alignment;+}++function describeKind(value) {+ return Object.prototype.toString.call(value).slice(8, -1);+}++/**+ * Splits a value into JSON and binary: every typed array becomes a { $typed, offset, length } marker and its bytes go to+ * the binary block, so geometry is never written as text. Anything JSON cannot hold throws and names where it sits.+ */+function encodeValue(value, path, chunks, cursor) {+ if (value === null || typeof value === 'string' || typeof value === 'boolean') return value;+ if (typeof value === 'number') {+ if (!Number.isFinite(value)) throw new TypeError(`${path}: got ${value}; expected a finite number. Fix the recipe field that produced it.`);+ return value;+ }+ if (ArrayBuffer.isView(value)) {+ const name = value.constructor.name;+ if (!Object.hasOwn(TYPED_ARRAYS, name)) throw new TypeError(`${path}: got ${name}; expected a typed array such as Float32Array or Uint32Array.`);+ const offset = padTo(cursor.bytes, ALIGNMENT);+ const bytes = new Uint8Array(value.buffer, value.byteOffset, value.byteLength);+ chunks.push({ offset, bytes });+ cursor.bytes = offset + bytes.byteLength;+ return { [TYPED_MARKER]: name, offset, length: value.length };+ }+ if (Array.isArray(value)) return value.map((entry, index) => encodeValue(entry, `${path}[${index}]`, chunks, cursor));+ if (value !== undefined && typeof value === 'object') {+ const kind = describeKind(value);+ if (kind !== 'Object') throw new TypeError(`${path}: got a ${kind}; expected plain data. A pack holds numbers, strings, arrays, objects and typed arrays only.`);+ const encoded = {};+ for (const key of Object.keys(value)) {+ if (value[key] !== undefined) encoded[key] = encodeValue(value[key], `${path}.${key}`, chunks, cursor);+ }+ return encoded;+ }+ throw new TypeError(`${path}: got ${typeof value}; expected plain data. A pack holds numbers, strings, arrays, objects and typed arrays only.`);+}++function decodeValue(value, binary) {+ if (Array.isArray(value)) return value.map(entry => decodeValue(entry, binary));+ if (value === null || typeof value !== 'object') return value;+ if (Object.hasOwn(value, TYPED_MARKER)) {+ const Constructor = TYPED_ARRAYS[value[TYPED_MARKER]];+ if (!Constructor) throw new TypeError(`pack: unknown typed array "${value[TYPED_MARKER]}"; repack the scene with this version of crucible pack.`);+ return new Constructor(binary.buffer, binary.byteOffset + value.offset, value.length);+ }+ const decoded = {};+ for (const key of Object.keys(value)) decoded[key] = decodeValue(value[key], binary);+ return decoded;+}++/** Encodes a scene description into one deterministic Uint8Array: the same input always gives the same bytes. */+export function encodePack(scene) {+ if (scene === null || typeof scene !== 'object' || Array.isArray(scene)) {+ throw new TypeError('encodePack: pass the scene object to pack, such as { camera, environment, parts }.');+ }+ const chunks = [];+ const cursor = { bytes: 0 };+ const body = encodeValue(scene, 'scene', chunks, cursor);+ const header = new TextEncoder().encode(JSON.stringify({ format: PACK_FORMAT, version: PACK_VERSION, scene: body }));+ const binaryStart = padTo(HEADER_BYTES + header.length, ALIGNMENT);+ const output = new Uint8Array(binaryStart + cursor.bytes);+ const view = new DataView(output.buffer);+ view.setUint32(0, MAGIC, true);+ view.setUint32(4, header.length, true);+ output.set(header, HEADER_BYTES);+ for (const { offset, bytes } of chunks) output.set(bytes, binaryStart + offset);+ return output;+}++/** Reads what encodePack wrote. Typed arrays are views on `bytes`, so the caller must keep it alive. */+export function decodePack(input) {+ const bytes = input instanceof ArrayBuffer ? new Uint8Array(input) : input;+ if (!(bytes instanceof Uint8Array)) throw new TypeError('decodePack: pass the bytes of a .pack file as an ArrayBuffer or Uint8Array.');+ if (bytes.length < HEADER_BYTES || new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(0, true) !== MAGIC) {+ throw new TypeError('decodePack: these bytes are not a crucible pack. Pass a file written by `crucible pack`.');+ }+ const headerLength = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength).getUint32(4, true);+ if (HEADER_BYTES + headerLength > bytes.length) throw new TypeError('decodePack: the pack is cut short. Download or copy it again.');+ const header = JSON.parse(new TextDecoder().decode(bytes.subarray(HEADER_BYTES, HEADER_BYTES + headerLength)));+ if (header.format !== PACK_FORMAT || header.version !== PACK_VERSION) {+ throw new TypeError(`decodePack: got ${header.format} version ${header.version}; expected ${PACK_FORMAT} version ${PACK_VERSION}. Repack the scene with this version of crucible pack.`);+ }+ const binaryStart = padTo(HEADER_BYTES + headerLength, ALIGNMENT);+ // The typed array views need a 4 byte aligned buffer offset, so a pack read from an odd offset is copied once.+ const aligned = (bytes.byteOffset + binaryStart) % ALIGNMENT === 0 ? bytes.subarray(binaryStart) : bytes.slice(binaryStart);+ return decodeValue(header.scene, aligned);+}diff --git a/src/scene-pack-shaders.js b/src/scene-pack-shaders.jsnew file mode 100644index 00000000..117a1b56--- /dev/null+++ b/src/scene-pack-shaders.js@@ -0,0 +1,38 @@+// The shader code a packed scene can need at run time. The renderer draws a feature only after its shader module has been+// imported, which agent-scene does when it compiles a recipe (src/agent-scene-modules.js). A pack lists the module names+// its scene needs and the runtime imports exactly those, so the page never loads the recipe compiler. The names are the+// keys of agent-scene-modules.js; each module here only registers GLSL and imports no agent-scene code.++export const PACK_SHADER_MODULES = Object.freeze({+ layerShaders: () => import('./material-layer-shaders.js'),+ emissionMask: () => import('./emission-mask.js'),+ liquidShader: () => import('./liquid-shader.js'),+ subsurfaceShader: () => import('./subsurface-shader.js'),+ fogShader: () => import('./fog-shader.js'),+ retroShader: () => import('./retro-shader.js'),+ worldMaterials: () => import('./world-material-shader.js'),+ // The probe code of the object reflections a metal part carries; the traced probe data itself travels in the pack.+ reflections: () => import('./reflection-probes.js'),+ viewTransform: () => import('./view-transform-shader.js'),+ postSteps: () => import('./post-steps.js'),+ volumeGrid: () => import('./local-volume-grid.js'),+ volumeRamp: () => import('./local-volume-ramp.js'),+});++// Recipe features that need more than shader code at run time. A pack refuses them until a later slice of #2178 carries them.+export const PACK_UNSUPPORTED_MODULES = Object.freeze({+ cascades: 'cascaded shadows, sun angular radius, ies profiles or area lights',+ lineArt: 'line art or toon shading',+ userPass: 'postPasses',+ materialSnippet: 'material snippets',+ patterns: 'procedural material patterns',+});++/** Imports the shader modules a pack names. Throws for a name this runtime does not know, which means the pack is newer. */+export function loadPackShaderModules(names) {+ return Promise.all(names.map(name => {+ const load = PACK_SHADER_MODULES[name];+ if (!load) throw new Error(`The pack needs the shader module "${name}", which this runtime does not have; update crucible or repack the scene.`);+ return load();+ }));+}diff --git a/src/scene-pack.js b/src/scene-pack.jsnew file mode 100644index 00000000..82f5b6fc--- /dev/null+++ b/src/scene-pack.js@@ -0,0 +1,160 @@+// Compiles a recipe (format crucible.scene) in Node into a runtime-only web bundle (docs/pack.md).+// The compiler stays here; the page loads src/crucible-scene.js, which reads the result without any agent-scene code.+import { copyFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';+import { basename, dirname, extname, join, resolve } from 'node:path';+import { createAgentScene, loadAllAgentSceneModules } from './agent-scene.js';+import { fitAgentShadow, resolveAgentShadow } from './agent-look.js';+import { agentSceneModulesNeeded } from './agent-scene-modules.js';+import { encodePack } from './scene-pack-format.js';+import { PACK_SHADER_MODULES, PACK_UNSUPPORTED_MODULES } from './scene-pack-shaders.js';++export const PACK_FILE_NAME = 'scene.pack';+export const PACK_RUNTIME_FILE_NAME = 'crucible-scene.js';+export const PACK_POSTER_EXTENSIONS = Object.freeze(['.webp', '.png', '.jpg', '.jpeg']);+const RECIPE_FORMAT = 'crucible.scene';+// Sections of a recipe that move or simulate. Slice 1 of #2178 packs the scene at time zero only.+const UNSUPPORTED_SECTIONS = Object.freeze(['motion', 'timeline', 'physics', 'cloth', 'particles', 'game', 'postPasses', 'armatures']);++function refuse(message) {+ throw new TypeError(message);+}++/** The checks that need no compile: they name the recipe field and what to pass instead. */+export function validatePackRecipe(recipe) {+ if (recipe === null || typeof recipe !== 'object' || Array.isArray(recipe)) {+ refuse('recipe: got something that is not an object; pass a scene.json written for format crucible.scene.');+ }+ if (recipe.format !== RECIPE_FORMAT) {+ refuse(`recipe.format: got ${JSON.stringify(recipe.format)}; expected "${RECIPE_FORMAT}". Pass a scene recipe, not a glTF or a pack.`);+ }+ for (const section of UNSUPPORTED_SECTIONS) {+ if (recipe[section] !== undefined) {+ refuse(`recipe.${section}: crucible pack writes a still scene for now; remove "${section}" from the recipe (animated packs are planned in #2178).`);+ }+ }+ const needed = agentSceneModulesNeeded(recipe);+ for (const name of needed) {+ if (Object.hasOwn(PACK_UNSUPPORTED_MODULES, name)) {+ refuse(`recipe: it uses ${PACK_UNSUPPORTED_MODULES[name]}, which crucible pack does not carry yet; remove it from the recipe (planned in #2178).`);+ }+ }+ const environment = recipe.environment ?? {};+ for (const field of ['sky', 'hdri']) {+ if (environment[field]) {+ refuse(`recipe.environment.${field}: crucible pack lights a scene with a lighting setup for now; remove "${field}" and set environment.setup (daylight, studio and the other names scene_capabilities lists).`);+ }+ }+}++/** Compiles a recipe to the bytes of a `.pack` file: its parts, camera, lighting and effects, ready for the runtime. */+export async function compileRecipeToPack(recipe) {+ validatePackRecipe(recipe);+ await loadAllAgentSceneModules();+ const scene = createAgentScene(recipe);+ const environment = scene.environment;+ return encodePack({+ shaderModules: agentSceneModulesNeeded(recipe).filter(name => Object.hasOwn(PACK_SHADER_MODULES, name)),+ camera: scene.camera,+ environment,+ effects: scene.effects,+ shadowBounds: resolveAgentShadow(fitAgentShadow(scene.shadow, scene.parts), environment.lightDirection),+ parts: scene.parts.map(part => ({ name: part.name, geometry: part.geometry, material: part.material, matrix: part.matrix })),+ });+}++export function indexHtml({ title, posterName }) {+ const posterAttribute = posterName ? ` poster="./${posterName}"` : '';+ return `<!doctype html>+<html lang="en">+<head>+<meta charset="utf-8">+<meta name="viewport" content="width=device-width, initial-scale=1">+<title>${title}</title>+<style>html,body{margin:0;height:100%;background:#111}crucible-scene{display:block;width:100%;height:100%}</style>+<script type="module" src="./${PACK_RUNTIME_FILE_NAME}"></script>+</head>+<body>+<crucible-scene src="./${PACK_FILE_NAME}"${posterAttribute}></crucible-scene>+</body>+</html>+`;+}++function requireFile(path, flag, what) {+ if (!path) refuse(`${flag}: pass the path of ${what}.`);+ if (!existsSync(path) || !statSync(path).isFile()) refuse(`${flag}: ${path} is not a file; pass the path of ${what}.`);+}++// A `from "./x.js"`, a bare `import "./x.js"` at the start of a statement or an `import("./x.js")`. An error message that+// only mentions an import ("add import './x.js'") does not count.+const RELATIVE_IMPORT = /(?:\bfrom\s*|(?:^|[;}\n])\s*import\s*|\bimport\s*\(\s*)["'](\.\/[^"']+\.js)["']/g;++// Pages that import the runtime also need the chunks it imports, so the whole relative import tree is copied beside it.+function runtimeFilesOf(entryPath) {+ const found = new Set();+ const pending = [entryPath];+ while (pending.length > 0) {+ const path = pending.pop();+ if (found.has(path)) continue;+ found.add(path);+ const source = readFileSync(path, 'utf8');+ for (const match of source.matchAll(RELATIVE_IMPORT)) {+ pending.push(join(dirname(path), match[1]));+ }+ }+ return [...found];+}++/** The built runtime of this package, build/crucible-scene.js, or the file `--runtime` names. */+export function findRuntimeEntry(runtimePath, packageRoot) {+ if (runtimePath) {+ requireFile(runtimePath, '--runtime', 'a built crucible-scene.js');+ return resolve(runtimePath);+ }+ const built = join(packageRoot, 'build', PACK_RUNTIME_FILE_NAME);+ if (!existsSync(built)) refuse(`--runtime: ${built} does not exist; run npm run build, or pass --runtime <path to a built crucible-scene.js>.`);+ return built;+}++function readRecipe(recipePath) {+ requireFile(recipePath, '<scene.json>', 'the recipe to pack, such as scene.json');+ try {+ return JSON.parse(readFileSync(recipePath, 'utf8'));+ } catch (error) {+ return refuse(`<scene.json>: ${recipePath} is not valid JSON (${error.message}); pass a recipe file.`);+ }+}++function checkPosterFile(posterPath) {+ requireFile(posterPath, '--poster', 'a WebP, PNG or JPEG picture of the scene');+ if (!PACK_POSTER_EXTENSIONS.includes(extname(posterPath).toLowerCase())) {+ refuse(`--poster: ${posterPath} is not ${PACK_POSTER_EXTENSIONS.join(', ')}; pass a WebP, PNG or JPEG picture.`);+ }+}++/** Reads scene.json, writes <outDir>/scene.pack, the runtime, an optional poster and index.html. Returns what it wrote. */+export async function packRecipeFile({ recipePath, outDir, posterPath, runtimePath, packageRoot }) {+ const recipe = readRecipe(recipePath);+ if (!outDir) refuse('--out: pass the folder to write the web bundle into, such as --out dist/scene.');+ if (posterPath) checkPosterFile(posterPath);+ const runtimeEntry = findRuntimeEntry(runtimePath, packageRoot);+ const packBytes = await compileRecipeToPack(recipe);+ mkdirSync(outDir, { recursive: true });+ const files = [];+ writeFileSync(join(outDir, PACK_FILE_NAME), packBytes);+ files.push(PACK_FILE_NAME);+ for (const file of runtimeFilesOf(runtimeEntry)) {+ // The entry is always written as crucible-scene.js; its chunks keep their own names.+ const name = file === runtimeEntry ? PACK_RUNTIME_FILE_NAME : basename(file);+ copyFileSync(file, join(outDir, name));+ files.push(name);+ }+ const posterName = posterPath ? `poster${extname(posterPath).toLowerCase()}` : null;+ if (posterName) {+ copyFileSync(posterPath, join(outDir, posterName));+ files.push(posterName);+ }+ writeFileSync(join(outDir, 'index.html'), indexHtml({ title: basename(recipePath, extname(recipePath)), posterName }));+ files.push('index.html');+ return { outDir, files, packBytes: packBytes.length };+}diff --git a/tests/scene-pack.test.js b/tests/scene-pack.test.jsnew file mode 100644index 00000000..de7f8ee4--- /dev/null+++ b/tests/scene-pack.test.js@@ -0,0 +1,137 @@+import { test } from 'node:test';+import assert from 'node:assert/strict';+import { mkdtempSync, readFileSync, writeFileSync, existsSync, rmSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import { build } from 'esbuild';+import { createAgentScene, loadAllAgentSceneModules } from '../src/agent-scene.js';+import { encodePack, decodePack } from '../src/scene-pack-format.js';+import { compileRecipeToPack, validatePackRecipe, packRecipeFile, indexHtml } from '../src/scene-pack.js';+import { parsePackArguments } from '../bin/crucible.mjs';++const RECIPE = Object.freeze({+ format: 'crucible.scene',+ schemaVersion: 1,+ geometries: [{ id: 'cube', type: 'box', bevel: 0 }, { id: 'ball', type: 'sphere' }],+ materials: [{ id: 'blue', color: [0.1, 0.3, 0.8] }, { id: 'red', color: [0.8, 0.1, 0.1], roughness: 0.2 }],+ nodes: [+ { id: 'cube', geometry: 'cube', material: 'blue' },+ { id: 'ball', geometry: 'ball', material: 'red', translation: [1.5, 0.5, 0] },+ ],+});++function temporaryFolder() {+ return mkdtempSync(join(tmpdir(), 'crucible-pack-'));+}++test('a packed scene holds the same geometry bytes as compiling the recipe directly', async () => {+ await loadAllAgentSceneModules();+ const direct = createAgentScene(structuredClone(RECIPE));+ const packed = decodePack(await compileRecipeToPack(structuredClone(RECIPE)));+ assert.equal(packed.parts.length, direct.parts.length);+ direct.parts.forEach((part, index) => {+ const unpacked = packed.parts[index];+ assert.equal(unpacked.name, part.name);+ assert.deepEqual(unpacked.material, JSON.parse(JSON.stringify(part.material)));+ assert.deepEqual([...unpacked.matrix], [...part.matrix]);+ for (const [attribute, array] of Object.entries(part.geometry)) {+ assert.ok(unpacked.geometry[attribute] instanceof array.constructor, `${attribute} keeps its typed array type`);+ assert.deepEqual(Buffer.from(unpacked.geometry[attribute].buffer, unpacked.geometry[attribute].byteOffset, unpacked.geometry[attribute].byteLength),+ Buffer.from(array.buffer, array.byteOffset, array.byteLength), `${attribute} bytes of ${part.name}`);+ }+ });+ assert.deepEqual(packed.camera, direct.camera);+ assert.equal(packed.environment.setup, direct.environment.setup);+});++test('packing the same recipe twice gives the same bytes', async () => {+ const first = await compileRecipeToPack(structuredClone(RECIPE));+ const second = await compileRecipeToPack(structuredClone(RECIPE));+ assert.deepEqual(Buffer.from(first), Buffer.from(second));+});++test('the pack format keeps typed arrays aligned and rejects what JSON cannot hold', () => {+ const bytes = encodePack({ values: new Float32Array([1, 2, 3]), small: new Uint8Array([7]), more: new Uint32Array([9, 8]), label: 'x' });+ const decoded = decodePack(bytes);+ assert.deepEqual([...decoded.values], [1, 2, 3]);+ assert.deepEqual([...decoded.more], [9, 8]);+ assert.equal(decoded.label, 'x');+ const shifted = new Uint8Array(bytes.length + 1);+ shifted.set(bytes, 1);+ assert.deepEqual([...decodePack(shifted.subarray(1)).values], [1, 2, 3]);+ assert.throws(() => encodePack({ bad: Number.NaN }), /scene\.bad: got NaN; expected a finite number/);+ assert.throws(() => encodePack({ bad: new Map() }), /scene\.bad: got a Map; expected plain data/);+ assert.throws(() => encodePack({ bad: () => 1 }), /scene\.bad: got function/);+ assert.throws(() => encodePack(null), /pass the scene object to pack/);+ assert.throws(() => decodePack(new Uint8Array(16)), /not a crucible pack/);+ assert.throws(() => decodePack(bytes.subarray(0, 12)), /cut short/);+ assert.throws(() => decodePack('text'), /as an ArrayBuffer or Uint8Array/);+});++test('a recipe that crucible pack cannot write yet is refused with what to change', () => {+ assert.throws(() => validatePackRecipe([]), /not an object/);+ assert.throws(() => validatePackRecipe({ format: 'gltf' }), /expected "crucible.scene"/);+ assert.throws(() => validatePackRecipe({ ...RECIPE, motion: {} }), /recipe\.motion: .*remove "motion"/);+ assert.throws(() => validatePackRecipe({ ...RECIPE, environment: { hdri: 'studio' } }), /environment\.hdri: .*set environment\.setup/);+ assert.doesNotThrow(() => validatePackRecipe(RECIPE));+});++test('crucible pack arguments name the flag that is wrong', () => {+ assert.deepEqual(parsePackArguments(['scene.json', '--out', 'dist', '--poster', 'p.webp']), { recipePath: 'scene.json', out: 'dist', poster: 'p.webp' });+ assert.throws(() => parsePackArguments(['a.json', 'b.json']), /only one scene\.json/);+ assert.throws(() => parsePackArguments(['a.json', '--out']), /--out: pass a value/);+ assert.throws(() => parsePackArguments(['--minify']), /--minify: unknown option/);+});++test('packRecipeFile writes the pack, the runtime, the poster and an index.html that uses the runtime only', async () => {+ const folder = temporaryFolder();+ try {+ const recipePath = join(folder, 'scene.json');+ const runtimePath = join(folder, 'runtime.js');+ const posterPath = join(folder, 'shot.webp');+ writeFileSync(recipePath, JSON.stringify(RECIPE));+ writeFileSync(runtimePath, 'import "./chunk.js";\nexport const runtime = true;\nexport const hint = "add import \'./not-a-chunk.js\'";\n');+ writeFileSync(join(folder, 'chunk.js'), 'export const chunk = true;\n');+ writeFileSync(posterPath, 'poster');+ const outDir = join(folder, 'out');+ const result = await packRecipeFile({ recipePath, outDir, posterPath, runtimePath, packageRoot: folder });+ assert.deepEqual(result.files.sort(), ['chunk.js', 'crucible-scene.js', 'index.html', 'poster.webp', 'scene.pack']);+ const html = readFileSync(join(outDir, 'index.html'), 'utf8');+ assert.match(html, /<crucible-scene src="\.\/scene\.pack" poster="\.\/poster\.webp">/);+ assert.match(html, /src="\.\/crucible-scene\.js"/);+ assert.ok(!html.includes('agent-scene'));+ assert.equal(decodePack(readFileSync(join(outDir, 'scene.pack'))).parts.length, 2);+ assert.ok(!indexHtml({ title: 't', posterName: null }).includes('poster='));+ } finally {+ rmSync(folder, { recursive: true, force: true });+ }+});++test('packRecipeFile checks its inputs before it writes anything', async () => {+ const folder = temporaryFolder();+ try {+ const recipePath = join(folder, 'scene.json');+ writeFileSync(recipePath, JSON.stringify(RECIPE));+ const runtimePath = join(folder, 'runtime.js');+ writeFileSync(runtimePath, 'export {};');+ const outDir = join(folder, 'out');+ await assert.rejects(packRecipeFile({ recipePath: join(folder, 'none.json'), outDir, runtimePath }), /<scene\.json>: .*is not a file/);+ writeFileSync(join(folder, 'broken.json'), '{');+ await assert.rejects(packRecipeFile({ recipePath: join(folder, 'broken.json'), outDir, runtimePath }), /not valid JSON/);+ await assert.rejects(packRecipeFile({ recipePath, runtimePath }), /--out: pass the folder/);+ writeFileSync(join(folder, 'poster.bmp'), 'x');+ await assert.rejects(packRecipeFile({ recipePath, outDir, runtimePath, posterPath: join(folder, 'poster.bmp') }), /--poster: .*pass a WebP, PNG or JPEG/);+ await assert.rejects(packRecipeFile({ recipePath, outDir, packageRoot: folder }), /--runtime: .*does not exist; run npm run build/);+ assert.ok(!existsSync(outDir), 'nothing is written when an input is wrong');+ } finally {+ rmSync(folder, { recursive: true, force: true });+ }+});++test('the <crucible-scene> runtime imports no agent-scene compiler code', async () => {+ const result = await build({ entryPoints: ['src/crucible-scene.js'], bundle: true, write: false, metafile: true, format: 'esm', splitting: true, outdir: 'out', logLevel: 'error' });+ const inputs = Object.keys(result.metafile.inputs);+ assert.ok(inputs.includes('src/renderer.js'), 'the runtime reaches the renderer');+ const compilerModules = inputs.filter(path => /src\/(agent-scene(?!-capabilities)|agent-look|agent-apply|scene-pack\.js)/.test(path));+ assert.deepEqual(compilerModules, []);+});