Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Add scene-wide raycast, walk map and the scene_walkmap tool (closes #553)

Nguyen Xuan An6d97f05dbc10
diff --git a/changes/553.md b/changes/553.md
new file mode 100644
index 00000000..4d921c09
--- /dev/null
+++ b/changes/553.md
@@ -0,0 +1 @@
+- Add `addons/scene-query` and the `scene_walkmap` MCP tool (issue #553). `createSceneQuery(parts)` raycasts a whole loaded scene with each part's world matrix (nearest hit with point, distance, normal, part ID and material), builds the per-part BVH lazily and keeps it, and `walkMap` samples ground height and headroom on a grid. On the Bistro scene a 1 m grid of 12,630 cells matches a Blender sample within 5 cm on 12,619 of 12,629 cells. The MCP server now lists 23 tools. `mesh-query` keeps the last validated matrix per index, so repeated rays against one part skip the matrix checks.
diff --git a/docs/learn/connect-mcp.md b/docs/learn/connect-mcp.md
index 2b822980..b4566018 100644
--- a/docs/learn/connect-mcp.md
+++ b/docs/learn/connect-mcp.md
@@ -6,7 +6,7 @@ This page connects the 67js MCP server to an AI agent harness. A harness is the
`67js-mcp` is a local program. The harness starts it and talks to it over stdin and stdout. It has no network listener for MCP.
-The server holds one active scene. When the agent calls `scene_create`, the server starts your installed Chrome in the background and renders the scene there. It gives the agent 22 tools to build, look at and export the scene. The tools take JSON, and they never run code that the agent writes.
+The server holds one active scene. When the agent calls `scene_create`, the server starts your installed Chrome in the background and renders the scene there. It gives the agent 23 tools to build, look at and export the scene. The tools take JSON, and they never run code that the agent writes.
You need two things:
@@ -241,7 +241,7 @@ The Windsurf documentation pages now redirect to Devin Desktop, which names `.de
## Check that it works
-First, ask the harness to list its MCP tools. You must see 22 tools whose names start with `scene_`, `mesh_` or `scene_render_`. Some harnesses add the server name in front, for example `mcp__67js-scene__scene_look` in Claude Code.
+First, ask the harness to list its MCP tools. You must see 23 tools whose names start with `scene_`, `mesh_` or `scene_render_`. Some harnesses add the server name in front, for example `mcp__67js-scene__scene_look` in Claude Code.
Then give the agent this prompt:
diff --git a/docs/learn/models-and-ai-agents.md b/docs/learn/models-and-ai-agents.md
index f38ff2ef..ef7ee87f 100644
--- a/docs/learn/models-and-ai-agents.md
+++ b/docs/learn/models-and-ai-agents.md
@@ -10,7 +10,7 @@ Three pages cover the details:
## What the agent does
-The server has 22 tools for authoring, previewing and exporting scenes. A normal session uses them in this order:
+The server has 23 tools for authoring, previewing and exporting scenes. A normal session uses them in this order:
1. `scene_capabilities` reads the supported features and limits.
2. `scene_create` makes a scene from a [recipe](/agent-scene.md). A recipe is JSON with object IDs, geometry, materials, a hierarchy and a camera.
diff --git a/docs/mcp.md b/docs/mcp.md
index c9e673a1..a0d537ac 100644
--- a/docs/mcp.md
+++ b/docs/mcp.md
@@ -77,7 +77,7 @@ Every recorded agent run used Claude Code. This table says what was tried elsewh
| Client or check | Result |
|---|---|
| Official MCP SDK client over stdio (`npm run smoke:mcp-package`) | Passes. |
-| MCP Inspector CLI 2.13.0 (`npm run smoke:mcp-clients`) | Passes, 2026-11-03, Windows, `--backend cpu`. Lists all 22 tools through `tools/list` in 7 s. `tools/call` of `scene_create` with the lamp recipe succeeds in 10 s. The CLI starts a new server for every command and the scene lives in the server, so it cannot follow with `scene_look`. That call fails with "No scene is active" and returns no image. The preview image is not testable through this CLI. |
+| MCP Inspector CLI 2.13.0 (`npm run smoke:mcp-clients`) | Passes, 2026-11-03, Windows, `--backend cpu`. Lists all 23 tools through `tools/list` in 7 s. `tools/call` of `scene_create` with the lamp recipe succeeds in 10 s. The CLI starts a new server for every command and the scene lives in the server, so it cannot follow with `scene_look`. That call fails with "No scene is active" and returns no image. The preview image is not testable through this CLI. |
| Official MCP Python SDK 2.3.0 (`npm run smoke:mcp-clients`) | Passes, 2026-11-03, Windows, `--backend cpu`. Initialize, `tools/list` (22 tools), `scene_create` and `scene_look` in one session. `scene_look` returns a 20480 byte PNG. 11 s including the first `uv` download. |
| JSON Schema 2020-12 validator with strict mode (Ajv 8), run in `npm test` | Every tool input schema compiles. |
| Tool names and descriptions | Names are 9 to 24 characters from `[a-z_]`, within the 64-character limit OpenAI, Gemini and Anthropic share. No description is over 1024 characters. |
@@ -127,6 +127,7 @@ Inspect or export the recipe before retrying. Context loss still permits recipe
| `scene_create_asset` | `recipe` using `67js.asset` | Imported scene ID, revision, inspection and render status |
| `scene_inspect` | `sessionId`, optional `ids`, `limit`, `includeBounds` | Compact node records and revision |
| `scene_apply` | `sessionId`, `expectedRevision`, `operations` | Updated revision, inspection, and render status |
+| `scene_walkmap` | `sessionId`, `min`, `max`, optional `cellSize`, `clearance`, `groundRange`, `lowerPass`, `includeCells` | Grid rows of `.` walkable, `x` blocked and `#` no surface, with counts; ground height and headroom per cell with `includeCells`. See [scene-query.md](scene-query.md) |
| `mesh_inspect` | `sessionId`, optional `geometries` (up to 16 IDs) | Per geometry: polygon counts, face sizes, parts, face tags, bounds and lint problems with fixes |
| `mesh_edit` | `sessionId`, `expectedRevision`, `geometry`, `edits`, optional `replace` | Updated revision, render status and the mesh report with per-edit results |
| `mesh_stack` | `sessionId`, `expectedRevision`, `geometry`, optional `stack`, `apply` | Updated revision, render status and the mesh report with per-node results |
diff --git a/docs/scene-query.md b/docs/scene-query.md
new file mode 100644
index 00000000..94dc52a4
--- /dev/null
+++ b/docs/scene-query.md
@@ -0,0 +1,74 @@
+# Scene queries
+
+`addons/scene-query` casts rays against a whole loaded scene and samples a walk map: the ground height and the headroom on a grid.
+It builds on the per-geometry BVH of [mesh-query.md](mesh-query.md) and adds the part that was missing, the node transforms.
+
+```js
+import { loadGltf } from '67js/addons/gltf';
+import { createSceneQuery } from '67js/addons/scene-query';
+
+const asset = await loadGltf('scene.glb');
+const query = createSceneQuery(asset.parts);
+
+const hit = query.raycast({ origin: [0, 100, 0], direction: [0, -1, 0] });
+// { point, distance, normal, id, partIndex, material, triangle } or null
+
+query.dispose();
+```
+
+`createSceneQuery(parts)` takes objects like the `parts` of `loadGltf`: `geometry` (`positions` and `indices`), a 16 component world `matrix`, an optional `material`, and `id` or `name`.
+It does not copy anything until a ray needs a part.
+A ray first tests the world bounds of every part, nearest first, and builds the BVH of a part on its first candidate hit.
+The index stays cached, so only the first queries pay for building.
+
+`raycast({ origin, direction, maxDistance })` returns the nearest hit over all parts.
+`normal` is the face normal in world space, turned toward the side the ray came from.
+`id` is the part ID (`id`, else `name`), and `material` is the part's own `material` value.
+
+Triangles with no usable area are left out of the index, and `info.droppedTriangles` counts them.
+Parts the mesh query cannot index, such as skinned or morphed meshes, are listed in `query.skipped` and never hit.
+Each index is limited to 1,000,000 triangles and 256 MiB; pass `maxTriangles`, `maxVertices` or `memoryBudgetMiB` as the second argument to change that.
+
+## Walk map
+
+```js
+const map = query.walkMap({
+ min: [-62, -88],
+ max: [111, 97],
+ cellSize: 1,
+ topY: 60,
+ lowerPass: { fromY: 2.4, groundBelow: 1, maxDistance: 4, minHeadroom: 2.4 },
+});
+// { cellSize, min, columns, rows, cells: [[x, z, groundY, headroom], ...] }
+```
+
+For each cell a ray goes down from `topY` and the first surface is the ground.
+A ray up from `probeHeight` (default 0.3) above the ground gives the headroom, capped at `clearanceCap` (default 99).
+Cells without a surface are left out.
+`lowerPass` handles a roof or an arch that hides the street: when the top surface is above `groundBelow`, a second ray goes down from `fromY`, and a hit below `groundBelow` with more than `minHeadroom` of room replaces the ground.
+The region may hold up to `maxCells` cells (default 65,536).
+
+Check against a Blender sample of the Bistro scene, a 1 m grid of 12,629 cells in glTF coordinates (down ray from y = 60, second ray from y = 2.4): ground height within 5 cm on 12,619 cells, and on 8,511 of the 8,517 open cells (ground below 1 m, headroom above 2.4 m).
+The cells that differ sit on rays that graze an edge.
+Measured on a machine under load: about 8 s for the first 12,630 cells including building 155 BVHs of 2.8 million triangles, 3.6 s with the indexes cached.
+
+## MCP tool
+
+`scene_walkmap` runs the same query on the active imported asset scene (made with `scene_create_asset`; procedural recipe scenes are not supported yet) and returns text rows an agent can read.
+Rows follow z, columns follow x.
+
+```json
+{ "min": [-62, -88], "max": [111, 97], "cellSize": 1, "topY": 60, "clearance": 2.4,
+ "groundRange": [-1, 1], "lowerPass": { "fromY": 2.4, "groundBelow": 1 } }
+```
+
+```
+{ "columns": 174, "rows": 186, "surfaceCells": 12630, "walkableCells": 8517,
+ "grid": ["######...", "##....xx.", "..."] }
+```
+
+`.` is walkable (headroom of at least `clearance`, ground inside `groundRange`), `x` is ground that is blocked, `#` has no surface.
+Pass `includeCells: true` for `[x, z, groundY, headroom]` per cell, up to 4,096 cells.
+Plan a camera path over the `.` cells, set each eye at `groundY` plus the eye height, and check it with `scene_look`.
+The server holds one query per session and rebuilds it when the revision or a pose changes.
+The MCP asset catalog is limited to 1,000,000 vertices (see [gltf.md](gltf.md)); a larger scene such as Bistro loads through `loadGltf` and `createSceneQuery` in code.
diff --git a/index.html b/index.html
index 25eb176b..338ff973 100644
--- a/index.html
+++ b/index.html
@@ -46,7 +46,7 @@
</div>
<div class="hero-copy">
<h1>A 3D engine<br />agents can drive</h1>
- <p class="lede">Real-time WebGL2 with Glaze, offline path tracing with Cook, and 22 MCP tools in one package.</p>
+ <p class="lede">Real-time WebGL2 with Glaze, offline path tracing with Cook, and 23 MCP tools in one package.</p>
<div class="hero-actions">
<a href="/docs.html#getting-started" data-icon="book">Get started</a>
<a href="https://www.npmjs.com/package/@codepawlhq/67js"><span class="package-logo package-logo-npm brand-npm" aria-hidden="true"></span>npm</a>
@@ -122,7 +122,7 @@ renderer.render({ eye: [58, 31, 84], target: [-8, 3, -18] });</code></pre>
</div>
</div>
<div class="agent-cards">
- <a href="/mcp.md" data-icon="cube"><h3>22 MCP tools</h3><p>Create, edit, explode, blend and render over stdio.</p></a>
+ <a href="/mcp.md" data-icon="cube"><h3>23 MCP tools</h3><p>Create, edit, explode, blend and render over stdio.</p></a>
<a href="/path-tracer.md" data-icon="code"><h3>Glaze + Cook</h3><p>Real-time WebGL2 frames or path-traced stills.</p></a>
<a href="/agent-review.md" data-icon="image"><h3>Visual review</h3><p>Compare labeled views and normals from one snapshot.</p></a>
</div>
diff --git a/package.json b/package.json
index f91b355f..78e2f448 100644
--- a/package.json
+++ b/package.json
@@ -63,6 +63,7 @@
"./addons/sculpt": "./build/sculpt.js",
"./addons/surface": "./build/surface.js",
"./addons/mesh-query": "./build/mesh-query.js",
+ "./addons/scene-query": "./build/scene-query.js",
"./addons/mesh": "./build/mesh.js",
"./addons/shrinkwrap": "./build/shrinkwrap.js",
"./addons/surface-attachment": "./build/surface-attachment.js",
diff --git a/public/llms.txt b/public/llms.txt
index 02fafd5f..e7b3d899 100644
--- a/public/llms.txt
+++ b/public/llms.txt
@@ -145,6 +145,7 @@ Share the target's retained matrix to follow rigid motion. Skin, morph, assembly
Surface clearance prevents overlapping layers in this workflow. It does not detect general mesh penetration or provide whole-object shrinkwrap.
`addons/mesh-query` owns copied static geometry in disposable BVH indices. Read `docs/mesh-query.md` before querying.
+`addons/scene-query` raycasts a whole loaded scene (every part with its world matrix) and samples a walk map of ground height and headroom. Read `docs/scene-query.md`.
Use `solid: true` indices and `mode: 'closed-solids'` to distinguish boundary contact, containment and separation.
Surface contact does not prove volume penetration or identify z-fighting. Never substitute surface-only results for containment.
diff --git a/scripts/agent-preview-browser.js b/scripts/agent-preview-browser.js
index e16b7079..9113fe7f 100644
--- a/scripts/agent-preview-browser.js
+++ b/scripts/agent-preview-browser.js
@@ -26,6 +26,7 @@ import { clipFromGltfAnimation } from '../src/skeleton-pose.js';
import { sessionProblem } from '../src/agent-errors.js';
import { BRANCH_LIMITS, createBranchStore, printableLabel } from '../src/agent-branches.js';
import { agentAssetDecodeOptions, withCatalogLimitAdvice } from '../src/agent-asset-limits.js';
+import { sceneQueryFor, summarizeWalkMap } from './agent-walkmap.js';
let active = null;
let canvas = document.querySelector('canvas');
@@ -851,6 +852,15 @@ window.__agentPreview = {
if (!allAgentSceneModulesLoaded()) return loadAllAgentSceneModules().then(() => this.inspectMeshes({ sessionId, ...options }));
return { sessionId, ...scene.inspectMeshes(options) };
},
+ async walkMap({ sessionId, clearance = 2, groundRange, includeCells = false, ...options }) {
+ const record = requireSession(sessionId);
+ if (typeof record.scene.queryParts !== 'function') throw new TypeError('scene_walkmap needs an imported asset scene (scene_create_asset). Procedural recipe scenes have no loaded surfaces to query yet.');
+ if (!allAgentSceneModulesLoaded()) await loadAllAgentSceneModules();
+ const started = performance.now();
+ const query = sceneQueryFor(record);
+ const map = query.walkMap(options);
+ return { sessionId, revision: record.scene.revision, ...summarizeWalkMap(map, { clearance, groundRange, includeCells }), skippedParts: query.skipped.length, milliseconds: Math.round(performance.now() - started) };
+ },
apply(input) {
if (input.sequenceData) {
const { sequenceFrames } = requireSession(input.sessionId);
diff --git a/scripts/agent-runtime.mjs b/scripts/agent-runtime.mjs
index fab2461a..11e9fc93 100644
--- a/scripts/agent-runtime.mjs
+++ b/scripts/agent-runtime.mjs
@@ -637,6 +637,9 @@ export function createAgentRuntime({ kernelWorkers = true, backend = 'gpu', brow
inspectMeshes(input) {
return enqueue(() => invoke('inspectMeshes', input));
},
+ walkMap(input) {
+ return enqueue(() => invoke('walkMap', input));
+ },
setMeshStack(input) {
return enqueue(async () => {
await requirePreviewRenderer();
diff --git a/scripts/agent-walkmap.js b/scripts/agent-walkmap.js
new file mode 100644
index 00000000..7d031479
--- /dev/null
+++ b/scripts/agent-walkmap.js
@@ -0,0 +1,53 @@
+import { createSceneQuery } from '../src/scene-query.js';
+
+const MAXIMUM_LISTED_CELLS = 4096;
+
+function matrixChecksum(parts) {
+ let total = 0;
+ for (const part of parts) {
+ for (let index = 0; index < 16; index++) total += part.matrix[index] * (index + 1);
+ }
+ return total;
+}
+
+/** One cached scene query per session. It is rebuilt when the revision or any part matrix (a seeked pose) changes. */
+export function sceneQueryFor(record) {
+ const parts = record.scene.queryParts();
+ const key = `${record.scene.revision}:${parts.length}:${matrixChecksum(parts)}`;
+ if (record.sceneQueryKey !== key) {
+ record.sceneQuery?.dispose();
+ record.sceneQuery = createSceneQuery(parts);
+ record.sceneQueryKey = key;
+ }
+ return record.sceneQuery;
+}
+
+function rounded(value) {
+ return Math.round(value * 100) / 100;
+}
+
+/** Turns the raw cells into text rows an agent can read: '.' walkable, 'x' blocked, '#' no surface. */
+export function summarizeWalkMap(map, { clearance, groundRange, includeCells }) {
+ const { columns, rows, cellSize, min } = map;
+ const grid = Array.from({ length: rows }, () => Array(columns).fill('#'));
+ let walkable = 0;
+ const listed = [];
+ for (const [x, z, groundY, headroom] of map.cells) {
+ const column = Math.round((x - min[0]) / cellSize);
+ const row = Math.round((z - min[1]) / cellSize);
+ const inRange = !groundRange || (groundY >= groundRange[0] && groundY <= groundRange[1]);
+ const open = headroom >= clearance && inRange;
+ grid[row][column] = open ? '.' : 'x';
+ if (open) walkable++;
+ listed.push([x, z, rounded(groundY), rounded(headroom)]);
+ }
+ if (includeCells && listed.length > MAXIMUM_LISTED_CELLS) {
+ throw new RangeError(`includeCells lists at most ${MAXIMUM_LISTED_CELLS} cells and this region has ${listed.length} with a surface. Shrink the region or raise cellSize.`);
+ }
+ return {
+ cellSize, min, columns, rows, surfaceCells: map.cells.length, walkableCells: walkable,
+ legend: { '.': 'walkable', x: 'ground with too little headroom or outside groundRange', '#': 'no surface' },
+ grid: grid.map(row => row.join('')),
+ ...(includeCells ? { cells: listed } : {}),
+ };
+}
diff --git a/scripts/mcp-server.mjs b/scripts/mcp-server.mjs
index 483c8eb3..034a1f31 100644
--- a/scripts/mcp-server.mjs
+++ b/scripts/mcp-server.mjs
@@ -755,6 +755,7 @@ export function createAgentMcpServer(runtime, { version = packageMetadata.versio
register('scene_asset_catalog', 'List content-bound GLB and PNG, JPEG or WebP image IDs from the configured local asset directory. No arbitrary paths or downloads.', z.strictObject({}), readOnly, async () => jsonResult(await runtime.assetCatalog()));
register('scene_create_asset', 'Create the active scene from a catalog GLB and editable asset recipe. Preserves supported maps, skins, morphs and clips. Dispose the existing scene first.', z.strictObject({ recipe: assetRecipe }), { ...edit, destructiveHint: false }, async argumentsValue => jsonResult(await runtime.createAsset(argumentsValue)));
register('scene_inspect', 'Read revision, counts and selected nodes. For a recipe with physics, the result lists body final positions, resting times, contacts and sensor enter/leave events. Bounds describe authored geometry rather than shader displacement.', z.strictObject({ ...sessionFields, ids: z.array(identifier).max(4096).optional().describe('Selected node IDs. Omit to inspect scene order.'), kind: z.enum(['meshes', 'hierarchy']).optional().describe('Imported assets only: hierarchy exposes stable source-node IDs and joints.'), offset: z.number().int().min(0).max(4096).optional().describe('Imported assets only: pagination offset.'), limit: z.number().int().min(1).max(4096).optional().describe('Maximum returned node records. Defaults to 64.'), includeBounds: z.boolean().optional().describe('Include world geometry bounds. Defaults to false.'), path: z.record(z.string(), z.unknown()).optional().describe('Walking route over a ground node, around holes: fields in scene_capabilities navigation.') }), readOnly, async argumentsValue => jsonResult(await runtime.inspect(argumentsValue)));
+ register('scene_walkmap', 'Sample ground height and headroom on a grid over a region of the active imported asset scene with raycasts against every mesh, and return a walkable map: grid rows of "." (walkable), "x" (ground but too little headroom or outside groundRange) and "#" (no surface), x across and z down. Use it to plan a street-level camera path. Reads the current pose; the scene does not change.', z.strictObject({ ...sessionFields, min: z.tuple([z.number(), z.number()]).describe('Region corner [x, z] with the smaller values, in world units (y is up).'), max: z.tuple([z.number(), z.number()]).describe('Region corner [x, z] with the larger values.'), cellSize: z.number().min(0.05).max(100).default(1).describe('Grid step. The region may hold up to 65,536 cells.'), topY: z.number().optional().describe('Height the down rays start from, above the tallest surface. Defaults to 100.'), clearance: z.number().min(0).max(100).default(2).describe('Headroom a cell needs to count as walkable, in the same units.'), groundRange: z.tuple([z.number(), z.number()]).optional().describe('[lowest, highest] ground height that counts as walkable, to ignore roofs and upper floors.'), lowerPass: z.strictObject({ fromY: z.number(), groundBelow: z.number(), maxDistance: z.number().min(0).max(1000).optional(), minHeadroom: z.number().min(0).max(100).optional() }).optional().describe('For cells whose top surface is above groundBelow (a roof, an arch): a second down ray from fromY looks for ground underneath.'), includeCells: z.boolean().default(false).describe('Also return [x, z, groundY, headroom] for each cell with a surface (at most 4096 cells).') }), readOnly, async argumentsValue => jsonResult(await runtime.walkMap(argumentsValue)));
register('mesh_inspect', 'Check recipe geometries as polygon meshes: vertex, edge and face counts, triangles/quads/n-gons, connected and closed parts, face tags (top, bottom, side, left, right, front, back), bounds, and lint problems (non-manifold, inconsistent winding, inverted, degenerate, open, loose) with a suggested fix each. Also imported asset parts (mesh-0). Read-only and cached per geometry.', z.strictObject({ ...sessionFields, geometry: identifier.optional().describe('One geometry ID to check, as in mesh_edit.'), geometries: z.array(identifier).min(1).max(16).optional().describe('Geometry IDs to check. Omit both to check the first 16 geometries.') }), readOnly, async ({ geometry: geometryId, geometries, ...rest }) => jsonResult(await runtime.inspectMeshes({ ...rest, ...(geometries || geometryId ? { geometries: [...(geometries ?? []), ...(geometryId ? [geometryId] : [])] } : {}) })));
register('mesh_edit', 'Append edits to a recipe mesh geometry or an imported asset part such as mesh-0 (or replace its edit log), atomically like scene_apply: extrude, inset, delete, flip, translate with falloff, tag, loop cut, bevel, mirror, array, solidify, UV unwrap, set_position and displace with field expressions (math, noise, attributes), booleans with a primitive cutter, sculpt brush strokes and shrinkwrap onto a primitive. Edits that select no faces or break limits fail without changing the scene. Returns the new revision, render status and the mesh report with per-edit results.', z.strictObject({ ...sessionFields, expectedRevision, geometry: identifier.describe('ID of a geometry with type mesh, or an imported part such as mesh-0.'), edits: meshEdits.min(1), replace: z.boolean().optional().describe('Replace the whole edit log instead of appending.') }), edit, async argumentsValue => jsonResult(await runtime.editMesh(argumentsValue)));
register('mesh_stack', 'Set the non-destructive modifier stack of a recipe mesh geometry (ops and fields: scene_capabilities meshModifiers), evaluated after its edits, each prefix cached. apply: n moves the first n nodes into the edit log, as Blender\'s Apply modifier. Atomic like scene_apply. Returns the revision, render status and mesh report.', z.strictObject({ ...sessionFields, expectedRevision, geometry: identifier.describe('ID of a geometry with type mesh.'), stack: meshStack.optional().describe('The whole new stack. Omit to keep the current stack (for example with apply).'), apply: z.number().int().min(0).max(16).optional() }), edit, async argumentsValue => jsonResult(await runtime.setMeshStack(argumentsValue)));
diff --git a/scripts/smoke-mcp.mjs b/scripts/smoke-mcp.mjs
index 9c38040b..99f5f6b4 100644
--- a/scripts/smoke-mcp.mjs
+++ b/scripts/smoke-mcp.mjs
@@ -53,7 +53,7 @@ try {
await client.connect(transport);
processId = transport.pid;
const listing = await client.listTools();
- assert.equal(listing.tools.length, 22);
+ assert.equal(listing.tools.length, 23);
const capabilities = (await call('scene_capabilities')).structuredContent;
assert.equal(capabilities.phase, 'idle');
const fixture = createAgentPreviewFixture();
diff --git a/src/agent-asset.js b/src/agent-asset.js
index 54622e7e..bbde83de 100644
--- a/src/agent-asset.js
+++ b/src/agent-asset.js
@@ -1073,6 +1073,10 @@ export function createAgentAssetScene(asset, inputRecipe, { sources } = {}) {
});
return { revision, meshes, truncated: false };
},
+ /** The surfaces a scene query walks: every part with its geometry, world matrix and material ID. */
+ queryParts() {
+ return records.map(record => ({ id: record.id, geometry: geometryOf(record), matrix: matrices[Number(record.id.slice(5))], material: record.material.id }));
+ },
checkpoint() {
if (checkpoints.size >= MAX_CHECKPOINTS) {
throw new RangeError('Asset checkpoint budget exhausted. Release a checkpoint.');
diff --git a/src/mesh-query.js b/src/mesh-query.js
index 9198e7b6..5b03668f 100644
--- a/src/mesh-query.js
+++ b/src/mesh-query.js
@@ -295,7 +295,16 @@ function validateSelfIntersections(record, welded, maximum) {
return counter.tests;
}
+// A scene query casts thousands of rays against one part with the same matrix, so the last validated state is kept.
function matrixState(record, values) {
+ const cached = record.matrixCache;
+ if (cached && ArrayBuffer.isView(values) === cached.typed && values.length === 16 && cached.source.every((value, position) => value === values[position])) return cached.state;
+ const state = computeMatrixState(record, values);
+ record.matrixCache = { source: Array.from(values), typed: ArrayBuffer.isView(values), state };
+ return state;
+}
+
+function computeMatrixState(record, values) {
if ((!Array.isArray(values) && !ArrayBuffer.isView(values)) || values.length !== 16) throw new TypeError('Query matrix requires 16 affine components.');
const elements = Array.from(values, value => {
if (typeof value !== 'number' || !Number.isFinite(value) || !Number.isFinite(Math.fround(value))) throw new RangeError('Query matrix requires finite Float32 components.');
diff --git a/src/scene-query.js b/src/scene-query.js
new file mode 100644
index 00000000..754fbbcb
--- /dev/null
+++ b/src/scene-query.js
@@ -0,0 +1,258 @@
+import { createMeshQueryIndex } from './mesh-query.js';
+
+const INDEX_OPTIONS = Object.freeze({ maxTriangles: 1_000_000, maxVertices: 1_000_000, memoryBudgetMiB: 256 });
+const DEFAULT_WALK_OPTIONS = Object.freeze({
+ cellSize: 1,
+ topY: 100,
+ probeHeight: 0.3,
+ clearanceCap: 99,
+ maxCells: 65_536,
+});
+const WALK_OPTION_NAMES = new Set(['min', 'max', 'cellSize', 'topY', 'probeHeight', 'clearanceCap', 'maxCells', 'lowerPass']);
+const LOWER_PASS_NAMES = new Set(['fromY', 'maxDistance', 'groundBelow', 'minHeadroom']);
+
+function assertNumber(value, label) {
+ if (!Number.isFinite(value)) throw new TypeError(`${label} requires a finite number.`);
+ return value;
+}
+
+function localBounds(positions) {
+ const bounds = [Infinity, Infinity, Infinity, -Infinity, -Infinity, -Infinity];
+ for (let offset = 0; offset < positions.length; offset += 3) {
+ for (let axis = 0; axis < 3; axis++) {
+ bounds[axis] = Math.min(bounds[axis], positions[offset + axis]);
+ bounds[3 + axis] = Math.max(bounds[3 + axis], positions[offset + axis]);
+ }
+ }
+ return bounds;
+}
+
+function worldBounds(bounds, matrix) {
+ const result = [Infinity, Infinity, Infinity, -Infinity, -Infinity, -Infinity];
+ for (let corner = 0; corner < 8; corner++) {
+ const x = corner & 1 ? bounds[3] : bounds[0];
+ const y = corner & 2 ? bounds[4] : bounds[1];
+ const z = corner & 4 ? bounds[5] : bounds[2];
+ const world = [
+ matrix[0] * x + matrix[4] * y + matrix[8] * z + matrix[12],
+ matrix[1] * x + matrix[5] * y + matrix[9] * z + matrix[13],
+ matrix[2] * x + matrix[6] * y + matrix[10] * z + matrix[14],
+ ];
+ for (let axis = 0; axis < 3; axis++) {
+ result[axis] = Math.min(result[axis], world[axis]);
+ result[3 + axis] = Math.max(result[3 + axis], world[axis]);
+ }
+ }
+ return result;
+}
+
+// Slab test: the distance along the ray where it enters the box, or Infinity when it misses or the box is behind it.
+function enterDistance(origin, direction, bounds, maxDistance) {
+ let near = 0;
+ let far = maxDistance;
+ for (let axis = 0; axis < 3; axis++) {
+ if (direction[axis] === 0) {
+ if (origin[axis] < bounds[axis] || origin[axis] > bounds[3 + axis]) return Infinity;
+ continue;
+ }
+ const first = (bounds[axis] - origin[axis]) / direction[axis];
+ const second = (bounds[3 + axis] - origin[axis]) / direction[axis];
+ near = Math.max(near, Math.min(first, second));
+ far = Math.min(far, Math.max(first, second));
+ if (near > far) return Infinity;
+ }
+ return near;
+}
+
+// Slivers with no usable area crash the precision checks of the mesh query and can never be walked on, so they are
+// dropped from the indexed copy. The caller's geometry is not changed.
+function withoutSlivers(geometry, matrix, bounds) {
+ const { positions, indices } = geometry;
+ const extent = Math.max(bounds[3] - bounds[0], bounds[4] - bounds[1], bounds[5] - bounds[2]);
+ const columnLength = offset => Math.hypot(matrix[offset], matrix[offset + 1], matrix[offset + 2]);
+ const matrixScale = Math.max((columnLength(0) + columnLength(4) + columnLength(8)) / 3, 1e-12);
+ const minimumAltitude = Math.max(extent * 1e-6, (2 ** -19 * Math.max(...bounds.map(Math.abs))) / matrixScale);
+ const kept = [];
+ for (let offset = 0; offset < indices.length; offset += 3) {
+ const first = indices[offset] * 3;
+ const second = indices[offset + 1] * 3;
+ const third = indices[offset + 2] * 3;
+ const edgeA = [0, 1, 2].map(axis => positions[second + axis] - positions[first + axis]);
+ const edgeB = [0, 1, 2].map(axis => positions[third + axis] - positions[first + axis]);
+ const edgeC = [0, 1, 2].map(axis => edgeA[axis] - edgeB[axis]);
+ const cross = Math.hypot(
+ edgeA[1] * edgeB[2] - edgeA[2] * edgeB[1],
+ edgeA[2] * edgeB[0] - edgeA[0] * edgeB[2],
+ edgeA[0] * edgeB[1] - edgeA[1] * edgeB[0],
+ );
+ const longest = Math.max(Math.hypot(...edgeA), Math.hypot(...edgeB), Math.hypot(...edgeC));
+ if (longest > 0 && cross / longest > minimumAltitude) kept.push(indices[offset], indices[offset + 1], indices[offset + 2]);
+ }
+ if (kept.length === indices.length) return { geometry, dropped: 0 };
+ return { geometry: { positions, indices: Uint32Array.from(kept) }, dropped: (indices.length - kept.length) / 3 };
+}
+
+function faceNormal(geometry, triangle, matrix, direction) {
+ const corners = [0, 1, 2].map(corner => {
+ const offset = geometry.indices[triangle * 3 + corner] * 3;
+ const x = geometry.positions[offset];
+ const y = geometry.positions[offset + 1];
+ const z = geometry.positions[offset + 2];
+ return [
+ matrix[0] * x + matrix[4] * y + matrix[8] * z + matrix[12],
+ matrix[1] * x + matrix[5] * y + matrix[9] * z + matrix[13],
+ matrix[2] * x + matrix[6] * y + matrix[10] * z + matrix[14],
+ ];
+ });
+ const first = corners[1].map((value, axis) => value - corners[0][axis]);
+ const second = corners[2].map((value, axis) => value - corners[0][axis]);
+ const normal = [
+ first[1] * second[2] - first[2] * second[1],
+ first[2] * second[0] - first[0] * second[2],
+ first[0] * second[1] - first[1] * second[0],
+ ];
+ const length = Math.hypot(...normal) || 1;
+ // Face the side the ray came from, so a back face never reports a normal pointing away from the viewer.
+ const facing = normal[0] * direction[0] + normal[1] * direction[1] + normal[2] * direction[2] > 0 ? -1 : 1;
+ return normal.map(value => (value / length) * facing);
+}
+
+function readWalkOptions(options) {
+ if (!options || typeof options !== 'object') throw new TypeError('walkMap requires an options object.');
+ for (const name of Object.keys(options)) {
+ if (!WALK_OPTION_NAMES.has(name)) throw new TypeError(`Unsupported walkMap option ${name}.`);
+ }
+ const given = Object.fromEntries(Object.entries(options).filter(([, value]) => value !== undefined));
+ const settings = { ...DEFAULT_WALK_OPTIONS, ...given };
+ for (const field of ['min', 'max']) {
+ if (!Array.isArray(settings[field]) || settings[field].length !== 2) throw new TypeError(`walkMap ${field} requires [x, z].`);
+ settings[field].forEach((value, index) => assertNumber(value, `walkMap ${field}[${index}]`));
+ }
+ for (const field of ['cellSize', 'topY', 'probeHeight', 'clearanceCap', 'maxCells']) assertNumber(settings[field], `walkMap ${field}`);
+ if (settings.cellSize <= 0 || settings.probeHeight <= 0) throw new RangeError('walkMap cellSize and probeHeight must be positive.');
+ if (settings.max[0] < settings.min[0] || settings.max[1] < settings.min[1]) throw new RangeError('walkMap max must not be below min.');
+ if (settings.lowerPass !== undefined) {
+ for (const name of Object.keys(settings.lowerPass)) {
+ if (!LOWER_PASS_NAMES.has(name)) throw new TypeError(`Unsupported walkMap lowerPass option ${name}.`);
+ }
+ settings.lowerPass = { maxDistance: 4, minHeadroom: 2.4, ...settings.lowerPass };
+ for (const field of ['fromY', 'groundBelow']) assertNumber(settings.lowerPass[field], `walkMap lowerPass.${field}`);
+ }
+ settings.columns = Math.floor((settings.max[0] - settings.min[0]) / settings.cellSize + 1e-9) + 1;
+ settings.rows = Math.floor((settings.max[1] - settings.min[1]) / settings.cellSize + 1e-9) + 1;
+ if (settings.columns * settings.rows > settings.maxCells) {
+ throw new RangeError(`walkMap region holds ${settings.columns * settings.rows} cells, above maxCells ${settings.maxCells}. Use a larger cellSize or a smaller region.`);
+ }
+ return settings;
+}
+
+/**
+ * Raycasts and walk maps over a whole loaded scene. `parts` are objects like the `parts` of loadGltf:
+ * { geometry: { positions, indices }, matrix, material, name } with a 16 component world matrix, plus an optional `id`.
+ * Each part gets a BVH on its first query and keeps it, so repeated queries only pay for traversal.
+ * Parts the mesh query rejects (skinned or morphed meshes, degenerate matrices) are listed in `skipped`, never hit.
+ */
+export function createSceneQuery(parts, options = {}) {
+ if (!Array.isArray(parts)) throw new TypeError('createSceneQuery requires an array of parts.');
+ const indexOptions = { ...INDEX_OPTIONS, ...options };
+ const entries = parts.map((part, position) => ({
+ part, position, id: part.id ?? part.name ?? `part-${position}`, index: null, failed: null,
+ bounds: worldBounds(localBounds(part.geometry.positions), part.matrix),
+ }));
+ const skipped = [];
+ let disposed = false;
+ let droppedTriangles = 0;
+
+ function indexOf(entry) {
+ if (entry.failed) return null;
+ if (!entry.index) {
+ try {
+ const surface = withoutSlivers(entry.part.geometry, entry.part.matrix, entry.bounds);
+ entry.index = createMeshQueryIndex(surface.geometry, indexOptions);
+ entry.surface = surface.geometry;
+ droppedTriangles += surface.dropped;
+ } catch (error) {
+ entry.failed = error.message;
+ skipped.push({ id: entry.id, reason: error.message });
+ return null;
+ }
+ }
+ return entry.index;
+ }
+
+ function raycast(ray) {
+ if (disposed) throw new Error('Scene query was disposed. Create a new one.');
+ const direction = Array.from(ray.direction);
+ const length = Math.hypot(...direction);
+ if (!(length > 0)) throw new RangeError('Ray direction must be nonzero.');
+ const unit = direction.map(value => value / length);
+ const origin = Array.from(ray.origin);
+ const maxDistance = ray.maxDistance ?? Infinity;
+ const candidates = [];
+ for (const entry of entries) {
+ const enter = enterDistance(origin, unit, entry.bounds, maxDistance);
+ if (enter !== Infinity) candidates.push({ entry, enter });
+ }
+ candidates.sort((first, second) => first.enter - second.enter);
+ let best = null;
+ for (const { entry, enter } of candidates) {
+ if (best && enter > best.distance) break;
+ const index = indexOf(entry);
+ if (!index) continue;
+ const hit = index.raycast(entry.part.matrix, { origin, direction: unit, maxDistance });
+ if (hit && (!best || hit.distance < best.distance)) best = { ...hit, entry };
+ }
+ if (!best) return null;
+ return {
+ point: best.point, distance: best.distance, id: best.entry.id, partIndex: best.entry.position,
+ material: best.entry.part.material ?? null, triangle: best.triangle,
+ normal: faceNormal(best.entry.surface, best.triangle, best.entry.part.matrix, unit),
+ };
+ }
+
+ function walkMap(walkOptions) {
+ const settings = readWalkOptions(walkOptions);
+ const { cellSize, columns, rows, topY, probeHeight, clearanceCap, lowerPass } = settings;
+ const down = [0, -1, 0];
+ const up = [0, 1, 0];
+ function headroomAbove(x, z, groundY) {
+ const hit = raycast({ origin: [x, groundY + probeHeight, z], direction: up, maxDistance: topY - groundY });
+ return hit ? Math.min(hit.point[1] - groundY, clearanceCap) : clearanceCap;
+ }
+ const cells = [];
+ for (let column = 0; column < columns; column++) {
+ for (let row = 0; row < rows; row++) {
+ const x = settings.min[0] + column * cellSize;
+ const z = settings.min[1] + row * cellSize;
+ const top = raycast({ origin: [x, topY, z], direction: down });
+ if (!top) continue;
+ let groundY = top.point[1];
+ let headroom = headroomAbove(x, z, groundY);
+ // A roof or an arch can hide the street: a second ray from walking height finds the ground underneath.
+ if (lowerPass && groundY > lowerPass.groundBelow) {
+ const low = raycast({ origin: [x, lowerPass.fromY, z], direction: down, maxDistance: lowerPass.maxDistance });
+ if (low && low.point[1] < lowerPass.groundBelow) {
+ const lowHeadroom = headroomAbove(x, z, low.point[1]);
+ if (lowHeadroom > lowerPass.minHeadroom) {
+ groundY = low.point[1];
+ headroom = lowHeadroom;
+ }
+ }
+ }
+ cells.push([x, z, groundY, headroom]);
+ }
+ }
+ return { cellSize, min: settings.min, columns, rows, cells };
+ }
+
+ return Object.freeze({
+ raycast,
+ walkMap,
+ get skipped() { return skipped.slice(); },
+ get info() { return { parts: entries.length, indexed: entries.filter(entry => entry.index).length, droppedTriangles }; },
+ dispose() {
+ disposed = true;
+ for (const entry of entries) entry.index?.dispose();
+ },
+ });
+}
diff --git a/tests/agent-walkmap.test.js b/tests/agent-walkmap.test.js
new file mode 100644
index 00000000..44a14c4a
--- /dev/null
+++ b/tests/agent-walkmap.test.js
@@ -0,0 +1,22 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { previewHarness } from './support/preview-harness.mjs';
+import { carAsset } from './fixtures/car-glb.js';
+
+test('walkMap on an imported asset returns a grid and reuses the cached query', async () => {
+ const { preview } = previewHarness();
+ const sessionId = 'walkmap-asset';
+ await preview.createAsset({
+ sessionId, recipe: { format: '67js.asset', schemaVersion: 1, assetId: 'cd'.repeat(32) },
+ data: Buffer.from(carAsset()).toString('base64'), backend: 'cpu', memoryBudgetMiB: 64,
+ });
+ const region = { sessionId, min: [-3, -3], max: [3, 3], cellSize: 1, topY: 20, clearance: 1 };
+ const result = await preview.walkMap(region);
+ assert.equal(result.grid.length, 7);
+ assert.ok(result.grid.every(row => row.length === 7));
+ assert.ok(result.walkableCells > 0);
+ assert.equal(result.skippedParts, 0);
+ const listed = await preview.walkMap({ ...region, includeCells: true });
+ assert.equal(listed.cells.length, listed.surfaceCells);
+ await assert.rejects(async () => preview.walkMap({ ...region, max: [3000, 3000] }), /maxCells/);
+});
diff --git a/tests/mcp-tools.test.js b/tests/mcp-tools.test.js
index d554b943..3a7b2671 100644
--- a/tests/mcp-tools.test.js
+++ b/tests/mcp-tools.test.js
@@ -131,7 +131,7 @@ test('SDK advertises the complete strict JSON contract and truthful annotations'
assert.deepEqual(tools.map(tool => tool.name).sort(), [
'mesh_edit', 'mesh_inspect', 'mesh_stack', 'scene_apply', 'scene_asset_catalog', 'scene_capabilities', 'scene_checkpoint', 'scene_create', 'scene_create_asset', 'scene_dispose',
'scene_export_glb', 'scene_export_recipe', 'scene_inspect', 'scene_look', 'scene_review', 'scene_release_checkpoint', 'scene_restore',
- 'scene_render_cancel', 'scene_render_release', 'scene_render_result', 'scene_render_status', 'scene_render_submit',
+ 'scene_render_cancel', 'scene_render_release', 'scene_render_result', 'scene_render_status', 'scene_render_submit', 'scene_walkmap',
].sort());
for (const tool of tools) {
assert.equal(tool.inputSchema.type, 'object');
@@ -186,7 +186,7 @@ test('review SDK exposes one image and rejects unknown or unbounded shot fields
await client.callTool({ name: 'scene_create', arguments: { recipe: recipe() } });
const { tools } = await client.listTools();
const tool = tools.find(tool => tool.name === 'scene_review');
- assert.equal(tools.length, 22);
+ assert.equal(tools.length, 23);
assert.equal(tool.annotations.readOnlyHint, true);
assert.equal(tool.inputSchema.properties.shots.maxItems, 4);
assert.equal(tool.inputSchema.properties.shots.items.additionalProperties, false);
@@ -213,7 +213,7 @@ test('branch names and labels are bounded in every tool schema and rejected befo
await client.callTool({ name: 'scene_create', arguments: { recipe: recipe() } });
const { tools } = await client.listTools();
const schema = name => tools.find(tool => tool.name === name).inputSchema;
- assert.equal(tools.length, 22, 'branches add fields, not tools');
+ assert.equal(tools.length, 23, 'branches add fields, not tools');
const pattern = '^[a-z][a-z0-9_-]{0,23}$';
assert.equal(schema('scene_apply').properties.branch.pattern, pattern);
assert.equal(schema('scene_restore').properties.branch.pattern, pattern);
diff --git a/tests/scene-query.test.js b/tests/scene-query.test.js
new file mode 100644
index 00000000..111f4fd9
--- /dev/null
+++ b/tests/scene-query.test.js
@@ -0,0 +1,85 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createSceneQuery } from '../src/scene-query.js';
+
+function quad(size) {
+ return {
+ positions: Float32Array.of(-size, 0, -size, size, 0, -size, size, 0, size, -size, 0, size),
+ indices: Uint32Array.of(0, 2, 1, 0, 3, 2),
+ };
+}
+
+function translation(x, y, z) {
+ return Float32Array.of(1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, x, y, z, 1);
+}
+
+// A 10 m ground at y = 0.5 and a roof over the x > 0 half at y = 4.
+const parts = [
+ { id: 'ground', geometry: quad(5), matrix: translation(0, 0.5, 0), material: 'grass' },
+ { id: 'roof', geometry: quad(2.5), matrix: translation(2.5, 4, 0), material: 'tile' },
+];
+
+test('raycast returns the nearest hit over every part with its world matrix', () => {
+ const query = createSceneQuery(parts);
+ const hit = query.raycast({ origin: [2, 20, 0], direction: [0, -1, 0] });
+ assert.equal(hit.id, 'roof');
+ assert.equal(hit.material, 'tile');
+ assert.ok(Math.abs(hit.point[1] - 4) < 1e-6);
+ assert.ok(Math.abs(hit.distance - 16) < 1e-6);
+ assert.ok(Math.abs(hit.normal[1] - 1) < 1e-6);
+ assert.equal(query.raycast({ origin: [-2, 20, 0], direction: [0, -1, 0] }).id, 'ground');
+ assert.equal(query.raycast({ origin: [20, 20, 0], direction: [0, -1, 0] }), null);
+ assert.equal(query.raycast({ origin: [2, 20, 0], direction: [0, -1, 0], maxDistance: 5 }), null);
+ query.dispose();
+});
+
+test('normals face the ray, also from below', () => {
+ const query = createSceneQuery(parts);
+ const hit = query.raycast({ origin: [-2, -5, 0], direction: [0, 1, 0] });
+ assert.equal(hit.id, 'ground');
+ assert.ok(hit.normal[1] < -0.99);
+ query.dispose();
+});
+
+test('indexes are built lazily and kept', () => {
+ const query = createSceneQuery(parts);
+ assert.equal(query.info.indexed, 0);
+ query.raycast({ origin: [-2, 20, 0], direction: [0, -1, 0] });
+ assert.equal(query.info.indexed, 1);
+ query.raycast({ origin: [-1, 20, 0], direction: [0, -1, 0] });
+ assert.equal(query.info.indexed, 1);
+ query.dispose();
+});
+
+test('slivers do not stop a part from being queried', () => {
+ const geometry = quad(5);
+ const withSliver = {
+ positions: Float32Array.of(...geometry.positions, 0, 0, 0, 0, 0, 0, 1, 0, 0),
+ indices: Uint32Array.of(...geometry.indices, 4, 5, 6),
+ };
+ const query = createSceneQuery([{ id: 'ground', geometry: withSliver, matrix: translation(0, 0, 0) }]);
+ assert.equal(query.raycast({ origin: [1, 5, 1], direction: [0, -1, 0] }).id, 'ground');
+ assert.equal(query.skipped.length, 0);
+ assert.equal(query.info.droppedTriangles, 1);
+ query.dispose();
+});
+
+test('walkMap samples ground and headroom and finds the ground under a roof', () => {
+ const query = createSceneQuery(parts);
+ const map = query.walkMap({ min: [-4, 0], max: [4, 0], cellSize: 2, topY: 20, lowerPass: { fromY: 3, groundBelow: 1, maxDistance: 4 } });
+ assert.equal(map.columns, 5);
+ assert.equal(map.rows, 1);
+ const byX = new Map(map.cells.map(cell => [cell[0], cell]));
+ assert.ok(Math.abs(byX.get(-4)[2] - 0.5) < 1e-6);
+ assert.equal(byX.get(-4)[3], 99);
+ assert.ok(Math.abs(byX.get(2)[2] - 0.5) < 1e-6, 'the roof is skipped for the ground underneath');
+ assert.ok(Math.abs(byX.get(2)[3] - 3.5) < 1e-4, 'headroom runs up to the roof');
+ query.dispose();
+});
+
+test('walkMap refuses a region above maxCells and unknown options', () => {
+ const query = createSceneQuery(parts);
+ assert.throws(() => query.walkMap({ min: [0, 0], max: [1000, 1000], cellSize: 1 }), /maxCells/);
+ assert.throws(() => query.walkMap({ min: [0, 0], max: [1, 1], radius: 1 }), /Unsupported walkMap option/);
+ query.dispose();
+});
diff --git a/tests/support/preview-harness.mjs b/tests/support/preview-harness.mjs
index a095ea2b..a42b131a 100644
--- a/tests/support/preview-harness.mjs
+++ b/tests/support/preview-harness.mjs
@@ -13,6 +13,7 @@ import { assetCopyKey, recipeAssetNeeds } from '../../src/agent-scene-assets.js'
import { BRANCH_LIMITS, createBranchStore, printableLabel } from '../../src/agent-branches.js';
import { sessionProblem } from '../../src/agent-errors.js';
import { agentAssetDecodeOptions, withCatalogLimitAdvice } from '../../src/agent-asset-limits.js';
+import { sceneQueryFor, summarizeWalkMap } from '../../scripts/agent-walkmap.js';
// Runs the preview page's adapter code in a VM with a fault-injected renderer, the way the MCP preview runs it in a browser.
const source = (await readFile(new URL('../../scripts/agent-preview-browser.js', import.meta.url), 'utf8')).replace(/^import .+;\r?$/gm, '');
@@ -77,7 +78,7 @@ export function previewHarness() {
// The harness loads Manifold from node_modules directly, so the preview's served-file loader is ignored.
setManifoldModuleLoader: () => {},
needsPhysics, loadPhysicsEngine, physicsEngineLoaded, setPhysicsModuleLoader: () => {},
- parseGltf, hasPatternTextures, Uint8Array, atob, sessionProblem, assetCopyKey, recipeAssetNeeds, agentAssetDecodeOptions, withCatalogLimitAdvice,
+ sceneQueryFor, summarizeWalkMap, parseGltf, hasPatternTextures, Uint8Array, atob, sessionProblem, assetCopyKey, recipeAssetNeeds, agentAssetDecodeOptions, withCatalogLimitAdvice,
applyProjection, mat4, resolveAgentShadow, agentEnvironmentMap, BRANCH_LIMITS,
// Line art needs a real renderer with render passes, so the fault-injected one gets a no-op install.
agentSceneModule: name => (name === 'lineArt' ? { installLineArt: renderer => renderer } : name === 'userPass' ? { ...agentSceneModule(name), installUserPasses: renderer => renderer } : agentSceneModule(name)), agentSceneModuleLoaded, createBranchStore, printableLabel,
diff --git a/tests/support/walk-preview-paths.mjs b/tests/support/walk-preview-paths.mjs
index 36e30af5..611020db 100644
--- a/tests/support/walk-preview-paths.mjs
+++ b/tests/support/walk-preview-paths.mjs
@@ -30,6 +30,7 @@ async function walk(label, createSession) {
frame: () => preview.frame({ sessionId, rendererTime: 0 }),
exportGlb: () => preview.exportGlb({ sessionId, maximumBytes: 32 * 1024 * 1024 }),
inspectMeshes: () => preview.inspectMeshes({ sessionId }),
+ walkMap: () => preview.walkMap({ sessionId, min: [-2, -2], max: [2, 2], cellSize: 1 }),
exportRecipe: () => preview.exportRecipe({ sessionId }),
};
if (label === 'recipe') {
diff --git a/vite.lib.config.js b/vite.lib.config.js
index 134d2d83..b67e1f76 100644
--- a/vite.lib.config.js
+++ b/vite.lib.config.js
@@ -53,6 +53,7 @@ export default defineConfig({
sculpt: 'src/sculpt.js',
surface: 'src/surface.js',
'mesh-query': 'src/mesh-query.js',
+ 'scene-query': 'src/scene-query.js',
mesh: 'src/mesh.js',
shrinkwrap: 'src/shrinkwrap.js',
'surface-attachment': 'src/surface-attachment.js',