Skip to content

armgit / kiln

Public Imported from GitHub
0

Build and revise procedural 3D assets with your coding agent. Local MCP server, CLI and TypeScript engine with rendered review, editable source and GLB export.

feat(kiln): kiln_view_interior tool + free-fly Explore viewer (asset-viewing cycle)

Matt Kissinger23b44dd11506
diff --git a/__tests__/prompt.test.ts b/__tests__/prompt.test.ts
index 1a4b4235..a53ac55d 100644
--- a/__tests__/prompt.test.ts
+++ b/__tests__/prompt.test.ts
@@ -115,6 +115,11 @@ describe('buildUserPrompt', () => {
expect(prompt.indexOf('## Task')).toBeLessThan(prompt.indexOf(ARCHITECTURE_CONTEXT));
});
+ test('the architecture directive names the interior-QA tool + the Roof part', () => {
+ expect(ARCHITECTURE_CONTEXT).toContain('kiln_view_interior');
+ expect(ARCHITECTURE_CONTEXT).toContain('Roof');
+ });
+
test('does not append the architecture directive for other categories', () => {
const prompt = buildUserPrompt({ prompt: 'a barrel', mode: 'glb', category: 'prop' });
expect(prompt).not.toContain(ARCHITECTURE_CONTEXT);
@@ -232,6 +237,11 @@ describe('unified tool surface prompt', () => {
expect(unified).not.toContain('Before kiln_submit, call kiln_screenshot');
});
+ test('the unified visual-qa nudges the interior view for buildings', () => {
+ expect(KILN_VISUAL_QA_UNIFIED).toContain('kiln_view_interior');
+ expect(KILN_VISUAL_QA_UNIFIED).toContain('BUILDING');
+ });
+
test('unified takes precedence over apiSurface:trimmed (which points at the removed list tool)', () => {
expect(getSystemPrompt('glb', { toolSurface: 'unified', apiSurface: 'trimmed' })).toBe(
getSystemPrompt('glb', { toolSurface: 'unified' }),
diff --git a/agent/run-surface.test.ts b/agent/run-surface.test.ts
index 31961155..45f1db33 100644
--- a/agent/run-surface.test.ts
+++ b/agent/run-surface.test.ts
@@ -34,6 +34,7 @@ const UNIFIED = [
'kiln_validate',
'kiln_render',
'kiln_screenshot_animation',
+ 'kiln_view_interior',
'kiln_finalize',
];
const CURRENT_GEN = [
@@ -56,11 +57,11 @@ const CURRENT_EDIT = [
];
describe('buildAgentTools', () => {
- test('unified surface -> the six buffer tools (fresh generate, empty seed)', () => {
+ test('unified surface -> the eight buffer tools (fresh generate, empty seed)', () => {
expect(names(buildAgentTools('unified', base, freshSinks()))).toEqual(UNIFIED);
});
- test('unified surface -> the same six tools when refining (seeded buffer)', () => {
+ test('unified surface -> the same eight tools when refining (seeded buffer)', () => {
const opts = { ...base, existingCode: 'const meta = {};', refineMode: 'edit' as const };
expect(names(buildAgentTools('unified', opts, freshSinks()))).toEqual(UNIFIED);
});
diff --git a/agent/tools-unified.test.ts b/agent/tools-unified.test.ts
index e2fb275a..939ea846 100644
--- a/agent/tools-unified.test.ts
+++ b/agent/tools-unified.test.ts
@@ -24,6 +24,20 @@ function build() {
}
`;
+// An enterable building: a hollow room (walls named Shell_Wall<Side>) under a
+// separable roof group named 'Roof' — the shape kiln_view_interior lifts.
+const BUILDING_CODE = `
+const meta = { name: 'test-hut', category: 'architecture' };
+function build() {
+ const root = createRoot('Hut');
+ const mat = gameMaterial('#caa472');
+ room('Shell', mat, { width: 4, depth: 4, height: 2.8, parent: root });
+ const roof = createRoofPlanes('Roof', mat, { width: 4, depth: 4, height: 1.2, parent: root });
+ roof.root.position.set(0, 2.8, 0);
+ return root;
+}
+`;
+
function findTool(tools: ReturnType<typeof makeKilnUnifiedTools>, name: string) {
const t = tools.find((x) => x.name === name) as
| { invoke(input: unknown): Promise<unknown> }
@@ -61,7 +75,7 @@ describe('KilnDraftBuffer', () => {
});
describe('makeKilnUnifiedTools', () => {
- test('exposes exactly the seven unified tools in order (incl. the animation view)', () => {
+ test('exposes exactly the eight unified tools in order (incl. the motion + interior views)', () => {
const sink: UnifiedSink = { edits: [] };
const tools = makeKilnUnifiedTools({ sink });
expect(tools.map((t) => t.name)).toEqual([
@@ -71,10 +85,11 @@ describe('makeKilnUnifiedTools', () => {
'kiln_validate',
'kiln_render',
'kiln_screenshot_animation',
+ 'kiln_view_interior',
'kiln_finalize',
]);
// No legacy verbs leak into the unified surface (the static screenshot collapsed
- // into kiln_render; only the dedicated motion view kiln_screenshot_animation is added).
+ // into kiln_render; only the dedicated motion + interior views are added).
expect(tools.map((t) => t.name)).not.toContain('kiln_list_primitives');
expect(tools.map((t) => t.name)).not.toContain('kiln_screenshot');
expect(tools.map((t) => t.name)).not.toContain('kiln_submit');
@@ -160,6 +175,40 @@ describe('makeKilnUnifiedTools', () => {
expect(got).toHaveLength(0); // a failed render has no image → no candidate
});
+ test('kiln_view_interior returns [ImageBlock, JsonBlock] for a building buffer', async () => {
+ const sink: UnifiedSink = { edits: [] };
+ const tools = makeKilnUnifiedTools({ seedCode: BUILDING_CODE, sink });
+ const out = (await findTool(tools, 'kiln_view_interior').invoke({})) as unknown[];
+ expect(Array.isArray(out)).toBe(true);
+ expect(out).toHaveLength(2);
+ expect(out[0]).toBeInstanceOf(ImageBlock);
+ expect(out[1]).toBeInstanceOf(JsonBlock);
+ const json = (out[1] as JsonBlock).json as Record<string, unknown>;
+ expect(json['ok']).toBe(true);
+ expect(json['roofsHidden']).toBeGreaterThanOrEqual(1); // the 'Roof' group was lifted
+ expect(json['wallsHidden']).toBeGreaterThanOrEqual(1); // near walls cut for the eye-level cell
+ expect('pngBase64' in json).toBe(false); // image stripped by the media extractor
+ });
+
+ test('kiln_view_interior on a broken buffer is image-free (plain JSON error)', async () => {
+ const sink: UnifiedSink = { edits: [] };
+ const tools = makeKilnUnifiedTools({ seedCode: 'not a kiln program (', sink });
+ const out = (await findTool(tools, 'kiln_view_interior').invoke({})) as { ok: boolean; error?: string };
+ expect(Array.isArray(out)).toBe(false);
+ expect(out.ok).toBe(false);
+ expect(out.error).toBeDefined();
+ });
+
+ test('kiln_view_interior warns when the roof is not named "Roof"', async () => {
+ const sink: UnifiedSink = { edits: [] };
+ const lidCode = BUILDING_CODE.replace("createRoofPlanes('Roof'", "createRoofPlanes('Lid'");
+ const tools = makeKilnUnifiedTools({ seedCode: lidCode, sink });
+ const out = (await findTool(tools, 'kiln_view_interior').invoke({})) as unknown[];
+ const json = (out[1] as JsonBlock).json as Record<string, unknown>;
+ expect(json['roofsHidden']).toBe(0); // no node named "Roof" → nothing lifted
+ expect((json['warnings'] as string[]).join(' ')).toContain('Roof');
+ });
+
test('kiln_finalize captures the buffer and marks finalized', async () => {
const sink: UnifiedSink = { edits: [] };
const tools = makeKilnUnifiedTools({ sink });
diff --git a/agent/tools.ts b/agent/tools.ts
index 0c5977b0..e022081d 100644
--- a/agent/tools.ts
+++ b/agent/tools.ts
@@ -20,7 +20,12 @@
import { tool, ImageBlock, JsonBlock, type Tool, type JSONValue } from '@strands-agents/sdk';
import { z } from 'zod';
-import { kilnToolRegistry, kilnRenderViewsDef, kilnScreenshotAnimationDef } from '../tools/registry';
+import {
+ kilnToolRegistry,
+ kilnRenderViewsDef,
+ kilnScreenshotAnimationDef,
+ kilnViewInteriorDef,
+} from '../tools/registry';
/** Name of the terminal tool the agent calls to record its final program. */
export const KILN_SUBMIT_TOOL_NAME = 'kiln_submit';
@@ -558,6 +563,24 @@ export function makeKilnUnifiedTools(opts: {
// clip move (sideways walk, reverse knee, backward swing, item not tracking).
const animationTool = makeBufferAnimationTool(() => buffer.code);
+ // Buffer-aware interior view: after drafting/editing a BUILDING, SEE inside it
+ // (roof off — open floor, real doorway gap, fixtures grounded, nothing buried).
+ const interiorTool: Tool = tool({
+ name: 'kiln_view_interior',
+ description: kilnViewInteriorDef.description + ' Operates on your current working buffer (omit code).',
+ inputSchema: z.object({
+ nodeName: z
+ .string()
+ .optional()
+ .describe('The roof part to lift, by name (default "Roof").'),
+ }),
+ callback: async (input) => {
+ const n = (input as { nodeName?: string }).nodeName;
+ const out = await kilnViewInteriorDef.run({ code: buffer.code, ...(n ? { nodeName: n } : {}) });
+ return toCallbackResult(kilnViewInteriorDef, out);
+ },
+ });
+
const finalizeTool: Tool = tool({
name: 'kiln_finalize',
description:
@@ -572,5 +595,5 @@ export function makeKilnUnifiedTools(opts: {
},
});
- return [draftTool, viewTool, editTool, validateTool, renderTool, animationTool, finalizeTool];
+ return [draftTool, viewTool, editTool, validateTool, renderTool, animationTool, interiorTool, finalizeTool];
}
diff --git a/prompt.ts b/prompt.ts
index e1164d9d..431e13b6 100644
--- a/prompt.ts
+++ b/prompt.ts
@@ -310,6 +310,16 @@ and check the MOTION (the static render cannot show it):
- Block/guard: the shield or arm comes UP toward the front — the body does not step backward.
If unresolvedTracks comes back non-empty, the clip is frozen because a track targets a joint
that doesn't exist — fix the joint name. Fix any motion defect and re-render the clip again.
+If this is a BUILDING, also call kiln_view_interior before finalizing — it lifts the roof and shows
+three roof-off views the exterior six cannot, and you check the INSIDE:
+- Floor plan (top-down): the floor area is open and walkable — no solid block filling the interior,
+ no stray wall partitioning it unless intended.
+- Dollhouse (3/4 cutaway): built-in fixtures (hearth, counter, shelves) rest ON the floor, not
+ floating or sunk through it; the walls enclose a real volume with standing headroom.
+- Eye-level (looking in through the doorway, near walls removed): the doorway is a REAL gap you
+ could walk through (not a panel), and no glass or wall is buried inside a solid mass.
+If roofsHidden comes back 0 the roof was not named Roof — rename it so the tool can lift it. Fix any
+sealed, buried, or floating interior and view it again.
</visual-qa>`;
export const KILN_EXAMPLES = `<example name="animated-chest">
@@ -813,15 +823,19 @@ export const ARCHITECTURE_CONTEXT =
'Walls meet squarely at the corners with no gaps; give large coplanar surfaces a hair of ' +
'separation so they do not flicker. Cap it with a roof that matches the footprint and overhangs ' +
"slightly at the eaves; a pitched roof's two sides slope DOWN-AND-OUTWARD from one ridge line — " +
- 'they fall away from each other, never tilt the same way. Name the roof as its own part so the ' +
- 'engine can lift it to reveal the inside.\n\n' +
+ 'they fall away from each other, never tilt the same way. Name the roof group exactly `Roof` (its ' +
+ 'own part) so the engine — and the interior view — can lift it to reveal the inside.\n\n' +
'Spend detail where a building reads: the roofline and eaves, a framed door, window sills or ' +
'mullions, a chimney, a porch or entry overhang, a foundation course, corner posts, trim — and ' +
'built-in fixtures (a hearth, a counter, shelving). Leave the floor space open for furniture to ' +
'be placed later.\n\n' +
'Use room(...) to build the hollow walled-and-floored shell with its doorway, wallWithOpening(...) ' +
'for extra doors or windows, and createRoofPlanes(...) for the pitched roof; createStairs(...) ' +
- 'makes porch steps or connects floors.';
+ 'makes porch steps or connects floors.\n\n' +
+ 'Before you finalize, call kiln_view_interior and check the roof-off views: the interior is open ' +
+ 'and walkable (no solid fill, no interior wall left buried in a mass), the doorway is a real gap ' +
+ 'you could pass through, and any built-in fixtures rest on the floor. Fix anything sealed, buried, ' +
+ 'or floating, then view the interior again.';
/**
* Per-category context appended to fresh-generation prompts by
diff --git a/tools/registry.ts b/tools/registry.ts
index 46158666..04dcba07 100644
--- a/tools/registry.ts
+++ b/tools/registry.ts
@@ -97,6 +97,14 @@ const screenshotAnimationInput = z.object({
.describe('Return the frames as separate high-res images instead of one composite grid. Default false.'),
});
+const viewInteriorInput = z.object({
+ code: z.string().describe('Kiln source code to execute and render with the roof hidden.'),
+ nodeName: z
+ .string()
+ .optional()
+ .describe('The roof part to lift, by name (default "Roof"). Matches that node and its children.'),
+});
+
// =============================================================================
// kiln_list_primitives
// =============================================================================
@@ -504,6 +512,88 @@ export const kilnScreenshotAnimationDef: KilnToolDef = {
mediaMulti: screenshotAnimationMediaMulti,
};
+// =============================================================================
+// kiln_view_interior (unified) — see INSIDE an enterable building, roof off
+// =============================================================================
+
+export interface KilnViewInteriorResult {
+ ok: boolean;
+ /** View names in grid order: Floor plan, Dollhouse, Eye-level. */
+ views?: string[];
+ gridWidth?: number;
+ gridHeight?: number;
+ /** Roof subtree roots hidden (0 → the roof part was not named "Roof"). */
+ roofsHidden?: number;
+ /** Near-wall subtree roots removed for the eye-level cutaway (0 → not a room()). */
+ wallsHidden?: number;
+ /** The single-row grid PNG, base64 (image transports strip this and attach the bytes). */
+ pngBase64?: string;
+ warnings: string[];
+ error?: string;
+}
+
+/**
+ * Render the asset with its roof hidden so the agent can SEE the interior the six
+ * exterior views cannot (open/walkable floor, a doorway that is a real gap, fixtures
+ * on the floor, nothing buried/sealed). Three roof-off cells: Floor plan, Dollhouse,
+ * Eye-level. A build error comes back image-free ({ ok:false, error }). When the roof
+ * could not be lifted (roofsHidden === 0) the interior stays occluded — a warning tells
+ * the agent to name the roof part "Roof". Pure visual QA: does NOT run the structural
+ * inspector (the agent already gets floating/stray warnings from kiln_render). The views
+ * module is imported lazily to keep node:zlib out of the browser bundle graph.
+ */
+async function runViewInterior(input: z.infer<typeof viewInteriorInput>): Promise<KilnViewInteriorResult> {
+ try {
+ const { renderInteriorGrid } = await import('../views');
+ const { root } = await executeKilnCode(input.code);
+ const nodeName = input.nodeName ?? 'Roof';
+ const grid = await renderInteriorGrid(root, { nodeName });
+ const warnings: string[] = [];
+ if (grid.roofsHidden === 0) {
+ warnings.push(
+ `No node named "${nodeName}" was found, so the roof could not be lifted and the interior is still occluded. Name the roof group exactly "${nodeName}".`,
+ );
+ }
+ return {
+ ok: true,
+ views: grid.views,
+ gridWidth: grid.width,
+ gridHeight: grid.height,
+ roofsHidden: grid.roofsHidden,
+ wallsHidden: grid.wallsHidden,
+ pngBase64: grid.png.toString('base64'),
+ warnings,
+ };
+ } catch (err) {
+ return {
+ ok: false,
+ error: err instanceof Error ? err.message : String(err),
+ warnings: [],
+ };
+ }
+}
+
+/**
+ * The unified-surface interior-QA tool. Exported separately and intentionally NOT
+ * part of `kilnToolRegistry` (the four-tool bench baseline stays unchanged). Shares
+ * `screenshotMedia` so image transports attach the PNG bytes and strip the base64.
+ */
+export const kilnViewInteriorDef: KilnToolDef = {
+ name: 'kiln_view_interior',
+ description:
+ 'SEE INSIDE an enterable building: renders it with the roof (the part named "Roof") lifted off, as a ' +
+ 'three-view grid. (1) Floor plan: top-down — check the interior is open and walkable and the footprint ' +
+ 'is right. (2) Dollhouse: a 3/4 cutaway — check built-in fixtures (hearth, counter, shelves) rest ON the ' +
+ 'floor, not floating or sunk, and the walls enclose a real volume with headroom. (3) Eye-level: a low ' +
+ 'angle looking in through the doorway with the near walls also removed — confirm the doorway is a REAL ' +
+ 'gap you could walk through (not a panel) and no wall or glass is buried inside a solid mass. ' +
+ 'Call this before finalizing any building. If roofsHidden comes back 0 the roof part was not named ' +
+ '"Roof" (the interior stays hidden — rename it). Flat-shaded CPU render; writes no files.',
+ inputSchema: viewInteriorInput,
+ run: async (input) => runViewInterior(viewInteriorInput.parse(input)),
+ media: screenshotMedia,
+};
+
// =============================================================================
// Registry
// =============================================================================
diff --git a/views/__tests__/views.test.ts b/views/__tests__/views.test.ts
index f3d9361f..8b8b7235 100644
--- a/views/__tests__/views.test.ts
+++ b/views/__tests__/views.test.ts
@@ -1,6 +1,14 @@
import { describe, expect, test } from 'bun:test';
import sharp from 'sharp';
-import { coverage, rasterizeView, renderViewGrid, renderCodeViewGrid, SIX_VIEWS } from '../index';
+import {
+ coverage,
+ rasterizeView,
+ renderViewGrid,
+ renderCodeViewGrid,
+ renderInteriorGrid,
+ hideNodeInScene,
+ SIX_VIEWS,
+} from '../index';
import { encodePng } from '../png';
import { executeKilnCode } from '../../render';
@@ -149,3 +157,70 @@ describe('renderViewGrid / renderCodeViewGrid', () => {
expect(result.png.length).toBeGreaterThan(100);
});
});
+
+// A roof group (named 'Roof') of child meshes — the rasterizer culls per-mesh, so
+// this proves hideNodeInScene recurses into descendants (hiding only the group would
+// leave the meshes drawn).
+const ROOF_ONLY_CODE = `
+const meta = { name: 'roof-only', category: 'architecture' };
+function build() {
+ const root = createRoot('Root');
+ createRoofPlanes('Roof', gameMaterial('#888888'), { width: 4, depth: 4, height: 1.2, parent: root });
+ return root;
+}
+`;
+
+// A hollow room (walls Shell_Wall<Side>) under a separable 'Roof' group.
+const BUILDING_CODE = `
+const meta = { name: 'hut', category: 'architecture' };
+function build() {
+ const root = createRoot('Hut');
+ const mat = gameMaterial('#caa472');
+ room('Shell', mat, { width: 4, depth: 4, height: 2.8, parent: root });
+ const roof = createRoofPlanes('Roof', mat, { width: 4, depth: 4, height: 1.2, parent: root });
+ roof.root.position.set(0, 2.8, 0);
+ return root;
+}
+`;
+
+describe('hideNodeInScene', () => {
+ test('hides the matched node AND its descendant meshes (per-mesh cull)', async () => {
+ const { root } = await executeKilnCode(ROOF_ONLY_CODE);
+ const dir: [number, number, number] = [0.7, 0.5, 0.7];
+ expect(coverage(rasterizeView(root, dir, { size: 64, backfaceCull: false }), 64)).toBeGreaterThan(0.1);
+ const hidden = hideNodeInScene(root, 'Roof');
+ expect(hidden).toBeGreaterThanOrEqual(1);
+ // If only the group's .visible flipped (not its child meshes), coverage would stay > 0.
+ expect(coverage(rasterizeView(root, dir, { size: 64, backfaceCull: false }), 64)).toBe(0);
+ });
+
+ test('returns 0 when nothing matches', async () => {
+ const { root } = await executeKilnCode(ROOF_ONLY_CODE);
+ expect(hideNodeInScene(root, 'Nonexistent')).toBe(0);
+ });
+});
+
+describe('renderInteriorGrid', () => {
+ test('returns three roof-off views with the roof + near walls hidden for a room()', async () => {
+ const { root } = await executeKilnCode(BUILDING_CODE);
+ const grid = await renderInteriorGrid(root, { size: 64 });
+ expect(grid.views).toEqual(['Floor plan', 'Dollhouse', 'Eye-level']);
+ expect(grid.roofsHidden).toBeGreaterThanOrEqual(1);
+ expect(grid.wallsHidden).toBeGreaterThanOrEqual(1); // Front + Right cut for the eye-level cell
+ expect(grid.width).toBe(3 * 64 + 4 * 4); // single row, 3 cols
+ expect(grid.height).toBe(64 + 2 * 4);
+ const meta = await sharp(grid.png).metadata();
+ expect(meta.format).toBe('png');
+ expect(meta.width).toBe(grid.width);
+ expect(meta.height).toBe(grid.height);
+ });
+
+ test('degrades gracefully on a non-building (no Roof, no walls) but still returns three views', async () => {
+ const { root } = await executeKilnCode(BOX_CODE);
+ const grid = await renderInteriorGrid(root, { size: 48 });
+ expect(grid.views).toHaveLength(3);
+ expect(grid.roofsHidden).toBe(0);
+ expect(grid.wallsHidden).toBe(0);
+ expect(grid.png.length).toBeGreaterThan(100);
+ });
+});
diff --git a/views/index.ts b/views/index.ts
index e4365dfc..b02bb724 100644
--- a/views/index.ts
+++ b/views/index.ts
@@ -11,7 +11,7 @@
* row 2: Left, Top, 3/4
*/
-import { rasterizeView, measureBounds, SIX_VIEWS, type RasterOptions, type ViewSpec } from './raster';
+import { rasterizeView, measureBounds, hideNodeInScene, SIX_VIEWS, type RasterOptions, type ViewSpec } from './raster';
import { encodePng } from './png';
import {
prepareClip,
@@ -23,7 +23,7 @@ import {
type DuckClip,
} from './pose';
-export { rasterizeView, measureBounds, SIX_VIEWS, coverage } from './raster';
+export { rasterizeView, measureBounds, hideNodeInScene, SIX_VIEWS, coverage } from './raster';
export type { RasterOptions, ViewSpec } from './raster';
export { encodePng } from './png';
export {
@@ -281,3 +281,114 @@ export async function renderClipAnimation(
}
return { ...baseMeta, width, height, png: encodePng(grid, width, height) };
}
+
+// =============================================================================
+// Interior views — see INSIDE an enterable building, roof off (kiln_view_interior)
+// =============================================================================
+
+export interface InteriorGridResult extends ViewGridResult {
+ /** Roof subtree roots hidden (0 → the roof part was not named like nodeName). */
+ roofsHidden: number;
+ /** Near-wall subtree roots hidden for the eye-level cutaway (0 → not a room()). */
+ wallsHidden: number;
+}
+
+export interface InteriorGridOptions extends RasterOptions {
+ /** Name of the roof part to lift. Default 'Roof'. */
+ nodeName?: string;
+}
+
+/** Outward face normals of room() walls, by lowercased name suffix (front faces +X). */
+const ROOM_WALL_NORMALS: Array<{ suffix: string; n: [number, number, number] }> = [
+ { suffix: 'wallfront', n: [1, 0, 0] },
+ { suffix: 'wallback', n: [-1, 0, 0] },
+ { suffix: 'wallleft', n: [0, 0, -1] },
+ { suffix: 'wallright', n: [0, 0, 1] },
+];
+
+const INTERIOR_VIEWS: ViewSpec[] = [
+ { name: 'Floor plan', dir: [0, 1, 0.0001] }, // top-down, roof off
+ { name: 'Dollhouse', dir: [0.7, 0.5, 0.7] }, // 3/4 cutaway, roof off
+ { name: 'Eye-level', dir: [0.55, 0.35, 0.45] }, // low angle, roof + near walls off
+];
+
+function normalizeVec(v: [number, number, number]): [number, number, number] {
+ const len = Math.hypot(v[0], v[1], v[2]) || 1;
+ return [v[0] / len, v[1] / len, v[2] / len];
+}
+function dotVec(a: [number, number, number], b: [number, number, number]): number {
+ return a[0] * b[0] + a[1] * b[1] + a[2] * b[2];
+}
+
+/**
+ * Render an enterable building with its roof — and, for the eye-level cell, the
+ * near walls — hidden, so the agent can SEE the interior the six exterior views
+ * cannot. Three roof-off cells in one row: Floor plan (top-down, layout +
+ * walkability), Dollhouse (3/4 cutaway, fixtures sit on the floor), Eye-level
+ * (low angle through the doorway with the camera-facing walls removed, so the
+ * doorway reads as a real gap and nothing is buried inside a solid mass).
+ *
+ * MUTATES `root` (callers pass a freshly executed scene — the tool re-executes
+ * per call). Interior faces point AWAY from the camera once the lid/near walls
+ * are off, so backface culling is OFF for every cell (the exterior grid keeps it
+ * ON to reveal winding bugs).
+ */
+export async function renderInteriorGrid(
+ root: unknown,
+ opts: InteriorGridOptions = {},
+): Promise<InteriorGridResult> {
+ const size = opts.size ?? 256;
+ const labelScale = Math.max(2, Math.round(size / 80));
+
+ // Lift the roof once — persists for every cell.
+ const roofsHidden = hideNodeInScene(root, opts.nodeName ?? 'Roof');
+
+ let wallsHidden = 0;
+ const cells: Uint8Array[] = [];
+ for (const view of INTERIOR_VIEWS) {
+ if (view.name === 'Eye-level') {
+ // Cutaway: also remove the walls facing the camera so the eye looks past
+ // them onto the far wall + floor. room() names walls `<root>_Wall<Side>`.
+ const d = normalizeVec(view.dir);
+ wallsHidden = hideNodeInScene(root, (name) => {
+ const lower = name.toLowerCase();
+ for (const w of ROOM_WALL_NORMALS) {
+ if (lower.endsWith(w.suffix) && dotVec(w.n, d) > 0.2) return true;
+ }
+ return false;
+ });
+ }
+ const cell = rasterizeView(root, view.dir, { size, backfaceCull: false });
+ stampLabel(cell, size, size, labelScale, labelScale, view.name, labelScale);
+ cells.push(cell);
+ }
+
+ // Single-row grid (reuse the six-view PAD/PAD_COLOR layout).
+ const cols = INTERIOR_VIEWS.length;
+ const width = cols * size + (cols + 1) * PAD;
+ const height = size + 2 * PAD;
+ const grid = new Uint8Array(width * height * 3);
+ for (let p = 0; p < width * height; p++) {
+ grid[p * 3] = PAD_COLOR[0];
+ grid[p * 3 + 1] = PAD_COLOR[1];
+ grid[p * 3 + 2] = PAD_COLOR[2];
+ }
+ for (let i = 0; i < cells.length; i++) {
+ const x0 = PAD + i * (size + PAD);
+ const y0 = PAD;
+ for (let y = 0; y < size; y++) {
+ const src = y * size * 3;
+ const dst = ((y0 + y) * width + x0) * 3;
+ grid.set(cells[i]!.subarray(src, src + size * 3), dst);
+ }
+ }
+
+ return {
+ png: encodePng(grid, width, height),
+ width,
+ height,
+ views: INTERIOR_VIEWS.map((v) => v.name),
+ roofsHidden,
+ wallsHidden,
+ };
+}
diff --git a/views/raster.ts b/views/raster.ts
index a9e33f5a..b63f44a5 100644
--- a/views/raster.ts
+++ b/views/raster.ts
@@ -340,3 +340,40 @@ export function coverage(rgb: Uint8Array, size: number): number {
}
return filled / (size * size);
}
+
+/**
+ * Hide a named subtree from the rasterizer so a view can see past it (lift a roof,
+ * cut away a near wall). CRITICAL: `collectTriangles` culls per-MESH on `.visible`
+ * and does NOT honor ancestor-group visibility — but kiln parts/walls/roofs are
+ * nested GROUPS, so hiding only the matched group would leave its child meshes
+ * drawn. This therefore sets `.visible = false` on each matched node AND every
+ * descendant.
+ *
+ * `match` is either a string (case-insensitive exact match OR startsWith — so
+ * "Roof" also lifts "Roof_Ridge") or a predicate over the node name. Returns the
+ * number of matched subtree roots hidden (0 → nothing matched; the caller decides
+ * whether to warn). Pure helper; mutates `.visible` on the passed scene.
+ */
+export function hideNodeInScene(root: unknown, match: string | ((name: string) => boolean)): number {
+ const test =
+ typeof match === 'function'
+ ? match
+ : (name: string) => {
+ const t = match.toLowerCase();
+ const n = name.toLowerCase();
+ return n === t || n.startsWith(t);
+ };
+ let hidden = 0;
+ const r = root as DuckObject3D;
+ r.traverse?.((obj) => {
+ const node = obj as { name?: string; traverse?(cb: (o: unknown) => void): void };
+ if (!node.name || !test(node.name)) return;
+ hidden++;
+ // Flip the matched node and its whole subtree (the per-mesh cull means hiding
+ // just the group is not enough — the leaf meshes must be invisible).
+ node.traverse?.((d) => {
+ (d as { visible?: boolean }).visible = false;
+ });
+ });
+ return hidden;
+}