incanto 0.1.0

package/dist/env.js

@@ -0,0 +1,3152 @@
+import { t as IncantoError } from "./errors-BpWbnbb_.js";
+import { t as Rng } from "./rng-DP-SR7eg.js";
+import { t as createNoise2D } from "./noise-CGUMx44x.js";
+import { t as buildHeightmap } from "./heightmap-CroQPEER.js";
+//#region src/env/round.ts
+/** 2-decimal rounding — keeps generated JSON readable without hurting determinism. */
+function round2(value) {
+	return Math.round(value * 100) / 100;
+}
+//#endregion
+//#region src/env/pieces.ts
+/**
+* Shared building blocks for the environment generators — the canonical
+* visible+collidable compositions and the recurring primitive props (trees,
+* boulders, sky lights). Internal to `incanto/env`; not exported from the
+* package surface.
+*/
+/** StaticBody3D box collider + MeshInstance3D 'Skin' child of the same size. */
+function staticBox(name, size, position, skin, rotation) {
+	return {
+		name,
+		type: "StaticBody3D",
+		props: {
+			collider: {
+				shape: "box",
+				size
+			},
+			position,
+			...rotation ? { rotation } : {}
+		},
+		children: [{
+			name: "Skin",
+			type: "MeshInstance3D",
+			props: {
+				mesh: "box",
+				size,
+				...skin
+			}
+		}]
+	};
+}
+const TRUNK_COLORS = [
+	"#6b4a2b",
+	"#7a5230",
+	"#5d4023"
+];
+const CANOPY_COLORS = [
+	"#3f6b2f",
+	"#4f8a3d",
+	"#2f5d28",
+	"#5b8266"
+];
+/**
+* A primitive tree: a StaticBody3D trunk collider with a cylinder 'Trunk' and
+* sphere 'Canopy' MeshInstance3D skin (no cone primitive exists — the sphere
+* canopy IS the house look).
+*/
+function tree(index, x, z, rng) {
+	const trunkHeight = round2(rng.range(1.6, 2.8));
+	const trunkRadius = round2(rng.range(.12, .22));
+	const canopyRadius = round2(rng.range(.9, 1.6));
+	return {
+		name: `Tree${index}`,
+		type: "StaticBody3D",
+		props: {
+			position: [
+				x,
+				0,
+				z
+			],
+			collider: {
+				shape: "box",
+				size: [
+					round2(trunkRadius * 2),
+					trunkHeight,
+					round2(trunkRadius * 2)
+				],
+				offset: [
+					0,
+					round2(trunkHeight / 2),
+					0
+				]
+			}
+		},
+		children: [{
+			name: "Trunk",
+			type: "MeshInstance3D",
+			props: {
+				mesh: "cylinder",
+				size: [
+					trunkRadius,
+					trunkHeight,
+					trunkRadius
+				],
+				position: [
+					0,
+					round2(trunkHeight / 2),
+					0
+				],
+				material: {
+					color: rng.pick(TRUNK_COLORS),
+					roughness: 1
+				},
+				castShadow: true
+			}
+		}, {
+			name: "Canopy",
+			type: "MeshInstance3D",
+			props: {
+				mesh: "sphere",
+				size: [
+					canopyRadius,
+					canopyRadius,
+					canopyRadius
+				],
+				position: [
+					0,
+					round2(trunkHeight + canopyRadius * .6),
+					0
+				],
+				material: {
+					color: rng.pick(CANOPY_COLORS),
+					roughness: 1
+				},
+				castShadow: true
+			}
+		}]
+	};
+}
+/** A boulder: a sphere mesh squashed on y, slightly sunken, gray-jittered —
+* or tinted by an explicit `color` (the forest's mossy variant). */
+function rock(index, x, z, rng, sizeRange, color) {
+	const radius = round2(rng.range(sizeRange[0], sizeRange[1]));
+	const squash = round2(rng.range(.5, .7));
+	return {
+		name: `Rock${index}`,
+		type: "MeshInstance3D",
+		props: {
+			mesh: "sphere",
+			size: [
+				1,
+				1,
+				1
+			],
+			position: [
+				x,
+				round2(radius * squash * .6),
+				z
+			],
+			rotation: [
+				0,
+				rng.int(0, 359),
+				0
+			],
+			scale: [
+				radius,
+				round2(radius * squash),
+				round2(radius * rng.range(.8, 1.1))
+			],
+			material: {
+				color: color ?? grayTone(rng),
+				roughness: 1
+			},
+			castShadow: true
+		}
+	};
+}
+/** A deterministic stony gray — the "slight color jitter" for boulders. */
+function grayTone(rng) {
+	const hex = Math.round(rng.range(110, 160)).toString(16).padStart(2, "0");
+	return `#${hex}${hex}${hex}`;
+}
+/** Sun + cool fill — the standard outdoor key/fill pair (same recipe as arena). */
+function skyLights(span) {
+	return [{
+		name: "Sun",
+		type: "DirectionalLight3D",
+		props: {
+			position: [
+				round2(span * .8),
+				round2(span * 1.5),
+				round2(span * .6)
+			],
+			intensity: 1,
+			castShadow: true,
+			shadowArea: round2(span * 1.2)
+		}
+	}, {
+		name: "FillLight",
+		type: "DirectionalLight3D",
+		props: {
+			position: [
+				round2(-span * .8),
+				round2(span * .8),
+				round2(-span * .6)
+			],
+			intensity: .4,
+			color: "#b9d4ff"
+		}
+	}];
+}
+/** Normalize a square-number-or-[x, z] extent (the CLI passes a single number). */
+function extent(area, fallback) {
+	if (area === void 0) return fallback;
+	return typeof area === "number" ? [area, area] : area;
+}
+function clamp(value, min, max) {
+	return Math.min(Math.max(value, min), max);
+}
+//#endregion
+//#region src/env/arena.ts
+/** Valid `generateArena` themes — drives the catalog options AND validation. */
+const ARENA_THEMES = [
+	"boxes",
+	"ruins",
+	"garden"
+];
+const WALL_THICKNESS = .5;
+const FLOOR_THICKNESS$1 = .1;
+const OBSTACLE_MARGIN = 2;
+const PALETTES = {
+	boxes: {
+		floor: "#3f3f3f",
+		wall: "#55504a",
+		obstacles: [
+			"#b0413e",
+			"#5b8266",
+			"#3e6990",
+			"#a26b38",
+			"#6d5a96",
+			"#878787"
+		]
+	},
+	ruins: {
+		floor: "#7d766b",
+		wall: "#8a8378",
+		obstacles: [
+			"#8a8378",
+			"#979085",
+			"#a39a8d",
+			"#7b746a"
+		]
+	},
+	garden: {
+		floor: "#4d7c3a",
+		wall: "#2f6b2f",
+		obstacles: [
+			"#2f6b2f",
+			"#3a7a38",
+			"#356e33"
+		]
+	}
+};
+/**
+* A 3D FPS stage: floor + 4 perimeter walls + N obstacles (every body a
+* StaticBody3D box collider with a MeshInstance3D 'Skin' child — the
+* canonical visible+collidable composition) + sun/fill/lamp lighting, dressed
+* by `theme`: 'boxes' strews colorful crates, 'ruins' lays broken stone
+* colonnade rows, 'garden' grows hedge blocks plus Foliage3D grass patches
+* and a Water3D pool at the center.
+*/
+function generateArena(opts) {
+	const { seed, width = 30, depth = 30, wallHeight = 3, obstacles = 8, theme = "boxes" } = opts;
+	if (!ARENA_THEMES.includes(theme)) throw new IncantoError("BAD_FORMAT", `generateArena theme must be one of [${ARENA_THEMES.join(", ")}], got '${theme}'.`, {
+		prop: "theme",
+		validOptions: [...ARENA_THEMES]
+	});
+	const palette = PALETTES[theme];
+	const rng = new Rng(seed);
+	const children = [staticBox("Floor", [
+		width,
+		FLOOR_THICKNESS$1,
+		depth
+	], [
+		0,
+		-.1 / 2,
+		0
+	], {
+		material: {
+			color: palette.floor,
+			roughness: 1
+		},
+		receiveShadow: true
+	})];
+	const wallY = wallHeight / 2;
+	const nsSize = [
+		width + WALL_THICKNESS * 2,
+		wallHeight,
+		WALL_THICKNESS
+	];
+	const ewSize = [
+		WALL_THICKNESS,
+		wallHeight,
+		depth
+	];
+	const wallSkin = {
+		material: {
+			color: palette.wall,
+			roughness: .9
+		},
+		receiveShadow: true
+	};
+	children.push(staticBox("Wall1", nsSize, [
+		0,
+		wallY,
+		-(depth + WALL_THICKNESS) / 2
+	], wallSkin), staticBox("Wall2", nsSize, [
+		0,
+		wallY,
+		(depth + WALL_THICKNESS) / 2
+	], wallSkin), staticBox("Wall3", ewSize, [
+		-(width + WALL_THICKNESS) / 2,
+		wallY,
+		0
+	], wallSkin), staticBox("Wall4", ewSize, [
+		(width + WALL_THICKNESS) / 2,
+		wallY,
+		0
+	], wallSkin));
+	if (theme === "ruins") children.push(...ruinRows(rng, palette, width, depth, wallHeight, obstacles));
+	else children.push(...scatteredObstacles(rng, palette, width, depth, wallHeight, obstacles, theme));
+	if (theme === "garden") children.push(...gardenDressing(rng, width, depth));
+	const span = Math.max(width, depth);
+	children.push({
+		name: "Sun",
+		type: "DirectionalLight3D",
+		props: {
+			position: [
+				round2(span * .8),
+				round2(span * 1.5),
+				round2(span * .6)
+			],
+			intensity: 1,
+			castShadow: true,
+			shadowArea: round2(span * 1.2)
+		}
+	}, {
+		name: "FillLight",
+		type: "DirectionalLight3D",
+		props: {
+			position: [
+				round2(-span * .8),
+				round2(span * .8),
+				round2(-span * .6)
+			],
+			intensity: .4,
+			color: "#b9d4ff"
+		}
+	}, {
+		name: "Lamp",
+		type: "OmniLight3D",
+		props: {
+			position: [
+				0,
+				round2(wallHeight + 2),
+				0
+			],
+			intensity: .5,
+			color: "#fff3d6",
+			range: round2(span)
+		}
+	});
+	return {
+		name: "Arena",
+		type: "Node3D",
+		children
+	};
+}
+/** The classic random-crate scatter ('boxes'), reused green for 'garden' hedges. */
+function scatteredObstacles(rng, palette, width, depth, wallHeight, obstacles, theme) {
+	const out = [];
+	const poolClearance = theme === "garden" ? Math.min(width, depth) * .16 : 0;
+	for (let i = 1; i <= obstacles; i++) {
+		const size = [
+			round2(rng.range(.8, 2.6)),
+			round2(rng.range(.8, Math.max(1.2, wallHeight * .8))),
+			round2(rng.range(.8, 2.6))
+		];
+		let x = round2(rng.range(-(width / 2 - OBSTACLE_MARGIN), width / 2 - OBSTACLE_MARGIN));
+		let z = round2(rng.range(-(depth / 2 - OBSTACLE_MARGIN), depth / 2 - OBSTACLE_MARGIN));
+		if (poolClearance > 0 && Math.hypot(x, z) < poolClearance + 1.5) {
+			const away = Math.max(Math.hypot(x, z), .001);
+			x = round2(x / away * (poolClearance + 1.5 + rng.range(0, 2)));
+			z = round2(z / away * (poolClearance + 1.5 + rng.range(0, 2)));
+		}
+		const yaw = rng.int(0, 359);
+		out.push(staticBox(`Obstacle${i}`, size, [
+			x,
+			round2(size[1] / 2),
+			z
+		], {
+			material: {
+				color: rng.pick(palette.obstacles),
+				roughness: .8
+			},
+			castShadow: true
+		}, [
+			0,
+			yaw,
+			0
+		]));
+	}
+	return out;
+}
+/**
+* Broken colonnade rows: obstacles become stone pillars laid out along
+* z-rows, with rng-varied heights (toppled stumps between standing columns)
+* and a slight per-pillar drift so the ruin reads weathered, not minted.
+*/
+function ruinRows(rng, palette, width, depth, wallHeight, obstacles) {
+	const out = [];
+	if (obstacles <= 0) return out;
+	const rows = Math.max(1, Math.round(Math.sqrt(obstacles / 2)));
+	const perRow = Math.ceil(obstacles / rows);
+	const usableW = width - OBSTACLE_MARGIN * 2;
+	const usableD = depth - OBSTACLE_MARGIN * 2;
+	let placed = 0;
+	for (let r = 0; r < rows && placed < obstacles; r++) {
+		const z = round2(rows === 1 ? 0 : -usableD / 2 + r / (rows - 1) * usableD);
+		for (let c = 0; c < perRow && placed < obstacles; c++) {
+			placed++;
+			const x = round2((perRow === 1 ? 0 : -usableW / 2 + c / (perRow - 1) * usableW) + rng.range(-.4, .4));
+			const height = round2(rng.next() > .35 ? rng.range(wallHeight * .7, wallHeight * 1.2) : rng.range(.4, .9));
+			const girth = round2(rng.range(.8, 1.2));
+			out.push(staticBox(`Obstacle${placed}`, [
+				girth,
+				height,
+				girth
+			], [
+				x,
+				round2(height / 2),
+				round2(z + rng.range(-.4, .4))
+			], {
+				material: {
+					color: rng.pick(palette.obstacles),
+					roughness: .95
+				},
+				castShadow: true
+			}, [
+				0,
+				rng.int(-8, 8),
+				0
+			]));
+		}
+	}
+	return out;
+}
+/** Garden extras: Foliage3D grass + LUSH Flowers3D beds around a center pool. */
+function gardenDressing(rng, width, depth) {
+	const out = [];
+	const poolRadius = Math.min(width, depth) * .16;
+	/** A spot whose whole patch clears the center pool. */
+	const clearOfPool = (patch) => {
+		const reach = Math.min(width, depth) / 2 - patch / 2 - 1;
+		let x = round2(rng.range(-reach, reach));
+		let z = round2(rng.range(-reach, reach));
+		const away = Math.max(Math.hypot(x, z), .001);
+		if (away < poolRadius + patch / 2) {
+			x = round2(x / away * (poolRadius + patch / 2 + .5));
+			z = round2(z / away * (poolRadius + patch / 2 + .5));
+		}
+		return [x, z];
+	};
+	for (let i = 1; i <= 3; i++) {
+		const patch = round2(Math.min(width, depth) * rng.range(.18, .26));
+		const [x, z] = clearOfPool(patch);
+		out.push({
+			name: `Grass${i}`,
+			type: "Foliage3D",
+			props: {
+				kind: "grass",
+				area: [patch, patch],
+				density: 10,
+				seed: rng.int(1, 1e9),
+				position: [
+					x,
+					0,
+					z
+				]
+			}
+		});
+	}
+	for (let i = 1; i <= 2; i++) {
+		const patch = round2(Math.min(width, depth) * rng.range(.12, .18));
+		const [x, z] = clearOfPool(patch);
+		out.push({
+			name: `FlowerBed${i}`,
+			type: "Flowers3D",
+			props: {
+				density: "lush",
+				clustering: .3,
+				area: [patch, patch],
+				seed: rng.int(1, 1e9),
+				position: [
+					x,
+					0,
+					z
+				]
+			}
+		});
+	}
+	out.push({
+		name: "Pool",
+		type: "Water3D",
+		props: {
+			size: [round2(poolRadius * 2), round2(poolRadius * 2)],
+			position: [
+				0,
+				.3,
+				0
+			],
+			waveHeight: .04
+		}
+	});
+	return out;
+}
+//#endregion
+//#region src/env/dungeon-2d.ts
+/** Tile size in px — rooms, corridors and walls snap to this grid. */
+const TILE = 32;
+const ROOM_TILES = [4, 8];
+const FLOOR_COLOR$1 = "#332f3a";
+const WALL_COLOR$1 = "#6b6357";
+/**
+* A roguelike 2D dungeon: rectangular rooms connected by 1-tile L-corridors
+* (horizontal leg, then vertical), rasterized onto a 32px tile grid. Floors
+* are ColorRect2D rects ('Room1'…, 'Corridor1H'/'Corridor1V'…); every
+* non-floor tile touching a floor tile becomes a StaticBody2D wall segment
+* (merged into runs along x) with a ColorRect2D skin. Centered on the origin.
+*/
+function generateDungeon2D(opts) {
+	const { seed, rooms = 5 } = opts;
+	const [width, height] = extent(opts.size, [960, 720]);
+	const cols = Math.max(8, Math.floor(width / TILE));
+	const rows = Math.max(8, Math.floor(height / TILE));
+	const rng = new Rng(seed);
+	const placed = [];
+	for (let attempt = 0; attempt < rooms * 12 && placed.length < rooms; attempt++) {
+		const w = rng.int(ROOM_TILES[0], ROOM_TILES[1]);
+		const h = rng.int(ROOM_TILES[0], ROOM_TILES[1]);
+		const candidate = {
+			x: rng.int(1, Math.max(1, cols - w - 1)),
+			y: rng.int(1, Math.max(1, rows - h - 1)),
+			w,
+			h
+		};
+		if (placed.some((room) => overlaps(room, candidate, 1))) continue;
+		placed.push(candidate);
+	}
+	const floor = /* @__PURE__ */ new Set();
+	const markFloor = (rect) => {
+		for (let ty = rect.y; ty < rect.y + rect.h; ty++) for (let tx = rect.x; tx < rect.x + rect.w; tx++) floor.add(`${tx},${ty}`);
+	};
+	for (const room of placed) markFloor(room);
+	const corridors = [];
+	for (let i = 1; i < placed.length; i++) {
+		const [ax, ay] = center(placed[i - 1]);
+		const [bx, by] = center(placed[i]);
+		const legH = {
+			x: Math.min(ax, bx),
+			y: ay,
+			w: Math.abs(ax - bx) + 1,
+			h: 1
+		};
+		const legV = {
+			x: bx,
+			y: Math.min(ay, by),
+			w: 1,
+			h: Math.abs(ay - by) + 1
+		};
+		for (const [suffix, rect] of [["H", legH], ["V", legV]]) {
+			markFloor(rect);
+			if (rect.w > 1 || rect.h > 1) corridors.push({
+				name: `Corridor${i}${suffix}`,
+				rect
+			});
+		}
+	}
+	const wallTiles = /* @__PURE__ */ new Set();
+	for (const key of floor) {
+		const [tx, ty] = key.split(",").map(Number);
+		for (let dy = -1; dy <= 1; dy++) for (let dx = -1; dx <= 1; dx++) {
+			const neighbor = `${tx + dx},${ty + dy}`;
+			if (!floor.has(neighbor)) wallTiles.add(neighbor);
+		}
+	}
+	const offsetX = -(cols * TILE) / 2;
+	const offsetY = -(rows * TILE) / 2;
+	const rectNode = (name, rect, color) => ({
+		name,
+		type: "ColorRect2D",
+		props: {
+			position: [offsetX + (rect.x + rect.w / 2) * TILE, offsetY + (rect.y + rect.h / 2) * TILE],
+			size: [rect.w * TILE, rect.h * TILE],
+			color
+		}
+	});
+	const children = placed.map((room, i) => rectNode(`Room${i + 1}`, room, FLOOR_COLOR$1));
+	for (const corridor of corridors) children.push(rectNode(corridor.name, corridor.rect, FLOOR_COLOR$1));
+	let wallIndex = 0;
+	for (let ty = -1; ty <= rows; ty++) {
+		let tx = -1;
+		while (tx <= cols) {
+			if (!wallTiles.has(`${tx},${ty}`)) {
+				tx++;
+				continue;
+			}
+			let run = 1;
+			while (tx + run <= cols && wallTiles.has(`${tx + run},${ty}`)) run++;
+			wallIndex++;
+			const size = [run * TILE, TILE];
+			children.push({
+				name: `Wall${wallIndex}`,
+				type: "StaticBody2D",
+				props: {
+					position: [offsetX + (tx + run / 2) * TILE, offsetY + (ty + .5) * TILE],
+					collider: {
+						shape: "rect",
+						size
+					}
+				},
+				children: [{
+					name: "Skin",
+					type: "ColorRect2D",
+					props: {
+						size,
+						color: WALL_COLOR$1
+					}
+				}]
+			});
+			tx += run;
+		}
+	}
+	return {
+		name: "Dungeon",
+		type: "Node2D",
+		children
+	};
+}
+function overlaps(a, b, gap) {
+	return a.x - gap < b.x + b.w && a.x + a.w + gap > b.x && a.y - gap < b.y + b.h && a.y + a.h + gap > b.y;
+}
+function center(rect) {
+	return [Math.floor(rect.x + rect.w / 2), Math.floor(rect.y + rect.h / 2)];
+}
+//#endregion
+//#region src/env/maze-grid.ts
+const DIRECTIONS = [
+	[0, -1],
+	[1, 0],
+	[0, 1],
+	[-1, 0]
+];
+/**
+* Recursive-backtracker maze (the classic): carve from cell (0,0), always
+* advancing to a random unvisited neighbor and knocking down the wall
+* between, backtracking when stuck — every cell ends up reachable. Then the
+* entrance (west wall of the first cell) and exit (east wall of the last)
+* are opened. Shared by `generateMaze` (3D) and `generateMaze2D`; games can
+* BFS over `cells` for pathing or item placement.
+*/
+function carveMaze(rng, cols, rows) {
+	const width = 2 * cols + 1;
+	const height = 2 * rows + 1;
+	const cells = Array.from({ length: height }, () => new Array(width).fill(false));
+	const open = (x, z) => {
+		cells[z][x] = true;
+	};
+	open(1, 1);
+	const visited = new Set(["0,0"]);
+	const stack = [[0, 0]];
+	while (stack.length > 0) {
+		const [c, r] = stack[stack.length - 1];
+		const neighbors = [];
+		for (const [dc, dr] of DIRECTIONS) {
+			const nc = c + dc;
+			const nr = r + dr;
+			if (nc >= 0 && nc < cols && nr >= 0 && nr < rows && !visited.has(`${nc},${nr}`)) neighbors.push([nc, nr]);
+		}
+		if (neighbors.length === 0) {
+			stack.pop();
+			continue;
+		}
+		const [nc, nr] = rng.pick(neighbors);
+		visited.add(`${nc},${nr}`);
+		open(2 * nc + 1, 2 * nr + 1);
+		open(c + nc + 1, r + nr + 1);
+		stack.push([nc, nr]);
+	}
+	open(0, 1);
+	open(2 * cols, 2 * rows - 1);
+	return {
+		cols,
+		rows,
+		cells
+	};
+}
+//#endregion
+//#region src/env/maze.ts
+/** Valid `generateMaze` themes — drives the catalog options AND validation. */
+const MAZE_THEMES = [
+	"stone",
+	"hedge",
+	"canyon"
+];
+const FLOOR_THICKNESS = .1;
+/** Live CDNs the textures stream from (same hosts as Terrain3D's splats and
+* the arena dressing — zero-setup contract). */
+const WALL_TEXTURE_BASE = "https://agent8-games.verse8.io/assets/3D/default/textures/wall";
+const TERRAIN_TEXTURE_BASE = "https://agent8-games.verse8.io/assets/3D/default/textures/terrain";
+/**
+* Theme materials. Tiling rule of thumb (verified at eye level in the
+* playground maze demo): bricks read right at one repeat per 2 m, the terrain
+* sets per 2.5–3.5 m. Box UVs span 0..1 per face, so emit
+* `repeat: [length/tile, height/tile]` per box — run ends compress a little,
+* but they abut other walls/pillars and never read.
+*/
+const THEMES$1 = {
+	stone: {
+		wall: {
+			color: "#e8e2d8",
+			map: `${WALL_TEXTURE_BASE}/blocks.png`,
+			normalMap: `${WALL_TEXTURE_BASE}/blocks_normal.png`,
+			tile: 2,
+			roughness: .95
+		},
+		floor: {
+			color: "#99938a",
+			map: `${TERRAIN_TEXTURE_BASE}/stone.png`,
+			normalMap: `${TERRAIN_TEXTURE_BASE}/stone_normal.png`,
+			tile: 3,
+			roughness: 1
+		},
+		cap: "#6b5848",
+		pillar: "#cfc8bb",
+		path: "#665f55",
+		sun: {
+			color: "#c9d6ea",
+			intensity: .75,
+			height: .5
+		},
+		fill: "#9fb4cc",
+		mood: {
+			sky: {
+				elevationDeg: 10,
+				azimuthDeg: 150,
+				turbidity: 16,
+				rayleigh: 3.2
+			},
+			fog: {
+				near: .5,
+				far: 3.5,
+				color: "#86909c"
+			},
+			exposure: .82,
+			ambient: {
+				color: "#c9d4e2",
+				intensity: .12
+			}
+		}
+	},
+	hedge: {
+		wall: {
+			color: "#55a83e",
+			map: `${TERRAIN_TEXTURE_BASE}/grass.png`,
+			normalMap: `${TERRAIN_TEXTURE_BASE}/grass_normal.png`,
+			tile: 1.4,
+			roughness: 1
+		},
+		floor: {
+			color: "#86b06d",
+			map: `${TERRAIN_TEXTURE_BASE}/grass.png`,
+			normalMap: `${TERRAIN_TEXTURE_BASE}/grass_normal.png`,
+			tile: 3,
+			roughness: 1
+		},
+		pillar: "#3d7531",
+		path: "#7d6845",
+		sun: {
+			color: "#e9eee6",
+			intensity: .7,
+			height: 1
+		},
+		fill: "#b9c8b4",
+		mood: {
+			sky: {
+				elevationDeg: 35,
+				azimuthDeg: 150,
+				turbidity: 18,
+				rayleigh: 4.2
+			},
+			fog: {
+				near: .8,
+				far: 5,
+				color: "#aab8a6"
+			},
+			exposure: .88,
+			ambient: {
+				color: "#dde5d8",
+				intensity: .15
+			}
+		}
+	},
+	canyon: {
+		wall: {
+			color: "#f0b070",
+			map: `${TERRAIN_TEXTURE_BASE}/stone.png`,
+			normalMap: `${TERRAIN_TEXTURE_BASE}/stone_normal.png`,
+			tile: 2.4,
+			roughness: 1
+		},
+		floor: {
+			color: "#e3c193",
+			map: `${TERRAIN_TEXTURE_BASE}/sand.png`,
+			normalMap: `${TERRAIN_TEXTURE_BASE}/sand_normal.png`,
+			tile: 3.5,
+			roughness: 1
+		},
+		pillar: "#d8a868",
+		path: "#a98a58",
+		sun: {
+			color: "#ffb572",
+			intensity: 1.15,
+			height: .35
+		},
+		fill: "#caa37e",
+		mood: {
+			sky: {
+				elevationDeg: 9,
+				azimuthDeg: 230,
+				turbidity: 9,
+				rayleigh: 3.5
+			},
+			fog: {
+				near: .7,
+				far: 4.5,
+				color: "#c79c6e"
+			},
+			exposure: .92,
+			ambient: {
+				color: "#ffdcb6",
+				intensity: .13
+			}
+		}
+	}
+};
+/** Span of the default 8×8/cellSize-2 maze — fog multiples are tuned vs it. */
+const DEFAULT_SPAN = 34;
+/**
+* The environment header that matches a maze theme — the terrainEnvironment
+* contract (spread into the scene's `environment`; scene keys layer on top),
+* tuned MOODY at corridor level: low hazy sun, sub-1 exposure, dim ambient
+* and a fog window that closes in on the walls. 'stone' is the coolest and
+* foggiest (dungeon courtyard), 'hedge' an overcast garden, 'canyon' a warm
+* dusk. `span` is the maze's world extent ((2·width+1)·cellSize, default 34).
+*/
+function mazeEnvironment(theme, span = DEFAULT_SPAN) {
+	const spec = THEMES$1[theme];
+	if (!spec) throw new IncantoError("BAD_FORMAT", `mazeEnvironment theme must be one of [${MAZE_THEMES.join(", ")}], got '${theme}'.`, {
+		prop: "theme",
+		validOptions: [...MAZE_THEMES]
+	});
+	const { mood } = spec;
+	return {
+		sky: {
+			type: "atmosphere",
+			...mood.sky
+		},
+		fog: {
+			near: round2(span * mood.fog.near),
+			far: round2(span * mood.fog.far),
+			color: mood.fog.color
+		},
+		shadows: true,
+		exposure: mood.exposure,
+		ambient: {
+			color: mood.ambient.color,
+			intensity: mood.ambient.intensity
+		}
+	};
+}
+/** Material JSON for a textured surface over a box of [length × height]. */
+function surfaceMaterial(surface, length, height) {
+	return {
+		color: surface.color,
+		roughness: surface.roughness,
+		map: surface.map,
+		...surface.normalMap ? { normalMap: surface.normalMap } : {},
+		repeat: [round2(length / surface.tile), round2(height / surface.tile)]
+	};
+}
+/** Junction pillars per maze (caps keep VRAM sane: every textured box loads
+* its own GL textures — see docs/ax/LEARNINGS.md). */
+const MAX_PILLARS = 10;
+/**
+* A 3D maze: recursive-backtracker corridors (entrance on the west edge,
+* exit on the east) as chunky one-tile-thick StaticBody3D walls over a
+* textured floor slab, plus sun/fill lights. Consecutive wall tiles merge
+* into single boxes along x to keep the node count down. Same algorithm as
+* `generateMaze2D`; `theme` swaps the materials and dressing over the
+* IDENTICAL carved layout — every theme gets textured walls/floor (worldspace
+* brick/grass/sandstone tiling), junction pillars, and a pillar-framed
+* entrance/exit with a tinted path tile; 'stone' adds coping caps on every
+* run, 'hedge' grows grass strips along the wall tops + corridor patches,
+* 'canyon' perches boulders on the rim. Deterministic from `seed`.
+*/
+function generateMaze(opts) {
+	const { seed, width = 8, depth = 8, cellSize = 2, wallHeight = 2.5, theme = "stone" } = opts;
+	if (!MAZE_THEMES.includes(theme)) throw new IncantoError("BAD_FORMAT", `generateMaze theme must be one of [${MAZE_THEMES.join(", ")}], got '${theme}'.`, {
+		prop: "theme",
+		validOptions: [...MAZE_THEMES]
+	});
+	const spec = THEMES$1[theme];
+	const rng = new Rng(seed);
+	const grid = carveMaze(rng, width, depth);
+	const gridWidth = 2 * width + 1;
+	const gridDepth = 2 * depth + 1;
+	const spanX = round2(gridWidth * cellSize);
+	const spanZ = round2(gridDepth * cellSize);
+	const tileCenter = (gx, gz) => [round2((gx + .5) * cellSize - spanX / 2), round2((gz + .5) * cellSize - spanZ / 2)];
+	const children = [staticBox("Floor", [
+		spanX,
+		FLOOR_THICKNESS,
+		spanZ
+	], [
+		0,
+		-.1 / 2,
+		0
+	], {
+		material: surfaceMaterial(spec.floor, spanX, spanZ),
+		receiveShadow: true
+	})];
+	const wallRuns = [];
+	let wallIndex = 0;
+	for (let gz = 0; gz < gridDepth; gz++) {
+		let gx = 0;
+		while (gx < gridWidth) {
+			if (grid.cells[gz]?.[gx]) {
+				gx++;
+				continue;
+			}
+			let run = 1;
+			while (gx + run < gridWidth && !grid.cells[gz]?.[gx + run]) run++;
+			wallRuns.push({
+				gx,
+				gz,
+				run
+			});
+			wallIndex++;
+			const length = round2(run * cellSize);
+			children.push(staticBox(`Wall${wallIndex}`, [
+				length,
+				wallHeight,
+				cellSize
+			], [
+				round2((gx + run / 2) * cellSize - spanX / 2),
+				round2(wallHeight / 2),
+				round2((gz + .5) * cellSize - spanZ / 2)
+			], {
+				material: surfaceMaterial(spec.wall, length, wallHeight),
+				castShadow: true,
+				receiveShadow: true
+			}));
+			gx += run;
+		}
+	}
+	if (spec.cap) children.push(...wallCaps(wallRuns, cellSize, wallHeight, spanX, spanZ, spec.cap));
+	children.push(...junctionPillars(rng, grid, cellSize, wallHeight, tileCenter, spec));
+	if (theme === "hedge") {
+		children.push(...hedgeTops(rng, wallRuns, cellSize, wallHeight, tileCenter));
+		children.push(...hedgeGrass(rng, grid, cellSize, tileCenter, width, depth));
+	} else if (theme === "canyon") children.push(...rimRocks(rng, wallRuns, cellSize, wallHeight, tileCenter));
+	children.push(...gates(grid, cellSize, wallHeight, tileCenter, spec));
+	children.push(...skyLights(Math.max(spanX, spanZ)).map((light, i) => {
+		if (i !== 0) return {
+			...light,
+			props: {
+				...light.props,
+				color: spec.fill
+			}
+		};
+		const position = light.props?.position;
+		return {
+			...light,
+			props: {
+				...light.props,
+				color: spec.sun.color,
+				intensity: spec.sun.intensity,
+				position: [
+					position[0] ?? 0,
+					round2((position[1] ?? 0) * spec.sun.height),
+					position[2] ?? 0
+				]
+			}
+		};
+	}));
+	return {
+		name: "Maze",
+		type: "Node3D",
+		children
+	};
+}
+/** Decorative coping trim atop each wall run (slight overhang, no collider —
+* dressing never changes the collision layout between themes). */
+function wallCaps(wallRuns, cellSize, wallHeight, spanX, spanZ, color) {
+	return wallRuns.map((wall, i) => ({
+		name: `Cap${i + 1}`,
+		type: "MeshInstance3D",
+		props: {
+			mesh: "box",
+			size: [
+				round2(wall.run * cellSize + .16),
+				.12,
+				round2(cellSize + .16)
+			],
+			position: [
+				round2((wall.gx + wall.run / 2) * cellSize - spanX / 2),
+				round2(wallHeight + .06),
+				round2((wall.gz + .5) * cellSize - spanZ / 2)
+			],
+			material: {
+				color,
+				roughness: 1
+			},
+			castShadow: true,
+			receiveShadow: true
+		}
+	}));
+}
+/**
+* Slightly wider/taller columns on wall-junction posts (grid tiles with even
+* coordinates and ≥3 wall neighbors — where runs meet in a T or X). Up to
+* MAX_PILLARS, chosen deterministically.
+*/
+function junctionPillars(rng, grid, cellSize, wallHeight, tileCenter, spec) {
+	const candidates = [];
+	const isWall = (gx, gz) => grid.cells[gz]?.[gx] === false;
+	for (let gz = 2; gz < grid.cells.length - 1; gz += 2) for (let gx = 2; gx < (grid.cells[gz]?.length ?? 0) - 1; gx += 2) {
+		if (!isWall(gx, gz)) continue;
+		if (Number(isWall(gx - 1, gz)) + Number(isWall(gx + 1, gz)) + Number(isWall(gx, gz - 1)) + Number(isWall(gx, gz + 1)) >= 3) candidates.push([gx, gz]);
+	}
+	const count = Math.min(MAX_PILLARS, candidates.length);
+	const out = [];
+	const used = /* @__PURE__ */ new Set();
+	const side = round2(cellSize * 1.2);
+	const height = round2(wallHeight * 1.12);
+	for (let i = 1; i <= count; i++) {
+		let idx = rng.int(0, candidates.length - 1);
+		while (used.has(idx)) idx = (idx + 1) % candidates.length;
+		used.add(idx);
+		const [gx, gz] = candidates[idx];
+		const [x, z] = tileCenter(gx, gz);
+		out.push(pillar(`Pillar${i}`, x, z, side, height, spec));
+	}
+	return out;
+}
+/** One decorative column over the wall texture (caps walls visually). */
+function pillar(name, x, z, side, height, spec) {
+	return {
+		name,
+		type: "MeshInstance3D",
+		props: {
+			mesh: "box",
+			size: [
+				side,
+				height,
+				side
+			],
+			position: [
+				x,
+				round2(height / 2),
+				z
+			],
+			material: {
+				...surfaceMaterial(spec.wall, side, height),
+				color: spec.pillar
+			},
+			castShadow: true,
+			receiveShadow: true
+		}
+	};
+}
+/** Gate posts flanking the entrance (west, tile (0,1)) and exit (east) plus
+* a tinted path tile in each opening — arrivals read the way in/out. */
+function gates(grid, cellSize, wallHeight, tileCenter, spec) {
+	const lastX = 2 * grid.cols;
+	const lastZ = 2 * grid.rows - 1;
+	const side = round2(cellSize * 1.1);
+	const height = round2(wallHeight * 1.25);
+	const out = [
+		[0, 0],
+		[0, 2],
+		[lastX, lastZ - 1],
+		[lastX, lastZ + 1]
+	].map(([gx, gz], i) => {
+		const [x, z] = tileCenter(gx, gz);
+		return pillar(`Gate${i + 1}`, x, z, side, height, spec);
+	});
+	for (const [name, gx, gz] of [[
+		"EntrancePath",
+		0,
+		1
+	], [
+		"ExitPath",
+		lastX,
+		lastZ
+	]]) {
+		const [x, z] = tileCenter(gx, gz);
+		out.push({
+			name,
+			type: "MeshInstance3D",
+			props: {
+				mesh: "box",
+				size: [
+					round2(cellSize * .96),
+					.04,
+					round2(cellSize * .96)
+				],
+				position: [
+					x,
+					.02,
+					z
+				],
+				material: {
+					...surfaceMaterial(spec.floor, cellSize, cellSize),
+					color: spec.path
+				},
+				receiveShadow: true
+			}
+		});
+	}
+	return out;
+}
+/** How many of the longest runs grow a trimmed-grass strip on top. */
+const MAX_HEDGE_TOPS = 10;
+/** Foliage3D strips along the rim of the longest hedge runs — the trimmed
+* hedge silhouette (every strip is one cheap instanced tuft field). */
+function hedgeTops(rng, wallRuns, cellSize, wallHeight, tileCenter) {
+	return [...wallRuns].filter((wall) => wall.run >= 2).sort((a, b) => b.run - a.run || a.gz - b.gz || a.gx - b.gx).slice(0, MAX_HEDGE_TOPS).map((wall, i) => {
+		const [, z] = tileCenter(wall.gx, wall.gz);
+		const [xStart] = tileCenter(wall.gx, wall.gz);
+		const [xEnd] = tileCenter(wall.gx + wall.run - 1, wall.gz);
+		return {
+			name: `HedgeTop${i + 1}`,
+			type: "Foliage3D",
+			props: {
+				kind: "grass",
+				style: "tufts",
+				area: [round2(wall.run * cellSize * .92), round2(cellSize * .7)],
+				density: 14,
+				height: .35,
+				sway: .4,
+				colorA: "#2f5e26",
+				colorB: "#5d8a3c",
+				seed: rng.int(1, 1e9),
+				position: [
+					round2((xStart + xEnd) / 2),
+					wallHeight,
+					z
+				]
+			}
+		};
+	});
+}
+/** Foliage3D grass patches on a handful of open corridor cells. */
+function hedgeGrass(rng, grid, cellSize, tileCenter, width, depth) {
+	const open = [];
+	for (let gz = 0; gz < grid.cells.length; gz++) for (let gx = 0; gx < (grid.cells[gz]?.length ?? 0); gx++) if (grid.cells[gz]?.[gx]) open.push([gx, gz]);
+	const patches = Math.min(open.length, Math.max(3, Math.floor(width * depth / 12)));
+	const out = [];
+	const used = /* @__PURE__ */ new Set();
+	for (let i = 1; i <= patches && used.size < open.length; i++) {
+		let idx = rng.int(0, open.length - 1);
+		while (used.has(idx)) idx = (idx + 1) % open.length;
+		used.add(idx);
+		const [gx, gz] = open[idx];
+		const [x, z] = tileCenter(gx, gz);
+		const patch = round2(cellSize * .8);
+		out.push({
+			name: `Grass${i}`,
+			type: "Foliage3D",
+			props: {
+				kind: "grass",
+				area: [patch, patch],
+				density: 8,
+				seed: rng.int(1, 1e9),
+				position: [
+					x,
+					0,
+					z
+				]
+			}
+		});
+	}
+	return out;
+}
+/** Boulders perched ON TOP of random wall runs — the canyon rim. */
+function rimRocks(rng, wallRuns, cellSize, wallHeight, tileCenter) {
+	const out = [];
+	if (wallRuns.length === 0) return out;
+	const count = Math.min(8, wallRuns.length);
+	for (let i = 1; i <= count; i++) {
+		const run = rng.pick(wallRuns);
+		const [x, z] = tileCenter(run.gx + rng.int(0, run.run - 1), run.gz);
+		const node = rock(i, x, z, rng, [.3, round2(cellSize * .35)], "#8f7355");
+		const position = node.props?.position;
+		position[1] = round2(position[1] + wallHeight);
+		out.push(node);
+	}
+	return out;
+}
+//#endregion
+//#region src/env/maze-2d.ts
+const FLOOR_COLOR = "#23222b";
+const WALL_COLOR = "#5f6672";
+/**
+* The 2D twin of `generateMaze` — the SAME recursive-backtracker grid
+* (entrance west, exit east) emitted as a ColorRect2D floor backdrop plus
+* StaticBody2D wall bodies with ColorRect2D skins (px, y-down, centered on
+* the origin). Consecutive wall tiles merge into single bodies along x.
+*/
+function generateMaze2D(opts) {
+	const { seed, cols = 10, rows = 8, cellPx = 64 } = opts;
+	const grid = carveMaze(new Rng(seed), cols, rows);
+	const gridWidth = 2 * cols + 1;
+	const gridHeight = 2 * rows + 1;
+	const spanX = round2(gridWidth * cellPx);
+	const spanY = round2(gridHeight * cellPx);
+	const children = [{
+		name: "Floor",
+		type: "ColorRect2D",
+		props: {
+			size: [spanX, spanY],
+			color: FLOOR_COLOR
+		}
+	}];
+	let wallIndex = 0;
+	for (let gy = 0; gy < gridHeight; gy++) {
+		let gx = 0;
+		while (gx < gridWidth) {
+			if (grid.cells[gy]?.[gx]) {
+				gx++;
+				continue;
+			}
+			let run = 1;
+			while (gx + run < gridWidth && !grid.cells[gy]?.[gx + run]) run++;
+			wallIndex++;
+			const size = [round2(run * cellPx), cellPx];
+			children.push({
+				name: `Wall${wallIndex}`,
+				type: "StaticBody2D",
+				props: {
+					position: [round2((gx + run / 2) * cellPx - spanX / 2), round2((gy + .5) * cellPx - spanY / 2)],
+					collider: {
+						shape: "rect",
+						size
+					}
+				},
+				children: [{
+					name: "Skin",
+					type: "ColorRect2D",
+					props: {
+						size,
+						color: WALL_COLOR
+					}
+				}]
+			});
+			gx += run;
+		}
+	}
+	return {
+		name: "Maze2D",
+		type: "Node2D",
+		children
+	};
+}
+//#endregion
+//#region src/env/platforms-2d.ts
+const THICKNESS = 16;
+const COLORS = [
+	"#5b8266",
+	"#3e6990",
+	"#a26b38",
+	"#6d5a96",
+	"#b0413e"
+];
+/**
+* A left-to-right 2D platform course: StaticBody2D rect colliders with
+* ColorRect2D 'Skin' children. Spacing is caller-tunable — keep `gapX` and
+* `stepY` inside your character's jump arc for a reachable course (px,
+* y-down: world gravity pulls +y, so negative `stepY` steps UP).
+*/
+function generatePlatforms2D(opts) {
+	const { seed, count = 10, width = [80, 160], gapX = [40, 120], stepY = [-80, 40], start = [0, 300] } = opts;
+	const rng = new Rng(seed);
+	const children = [];
+	let w = round2(rng.range(width[0], width[1]));
+	let x = start[0];
+	let y = start[1];
+	for (let i = 1; i <= count; i++) {
+		children.push(platform(i, x, y, w, rng.pick(COLORS)));
+		if (i === count) break;
+		const nextW = round2(rng.range(width[0], width[1]));
+		const gap = round2(rng.range(gapX[0], gapX[1]));
+		x = round2(x + w / 2 + gap + nextW / 2);
+		y = round2(y + rng.range(stepY[0], stepY[1]));
+		w = nextW;
+	}
+	return {
+		name: "Platforms",
+		type: "Node2D",
+		children
+	};
+}
+function platform(index, x, y, w, color) {
+	return {
+		name: `Platform${index}`,
+		type: "StaticBody2D",
+		props: {
+			position: [x, y],
+			collider: {
+				shape: "rect",
+				size: [w, THICKNESS]
+			}
+		},
+		children: [{
+			name: "Skin",
+			type: "ColorRect2D",
+			props: {
+				size: [w, THICKNESS],
+				color
+			}
+		}]
+	};
+}
+//#endregion
+//#region src/env/clouds.ts
+const PUFFS = [3, 5];
+const ALTITUDE_JITTER = 3;
+const CLOUD_MATERIAL = {
+	color: "#ffffff",
+	roughness: 1,
+	emissive: "#ffffff",
+	emissiveIntensity: .25
+};
+/**
+* Soft sky clouds: each a Node3D group of 3–5 overlapping white sphere puffs
+* stretched wide and squashed flat, floating around `altitude`. Pure visuals
+* — no colliders, no physics.
+*
+* @deprecated The island terrain theme ships its own cloud layer — use
+* `runGenerator('terrain', { seed, theme: 'island' })` for whole worlds.
+* Kept for custom library compositions (other themes, custom skies).
+*/
+function generateClouds(opts) {
+	const { seed, count = 8, altitude = 18 } = opts;
+	const [areaX, areaZ] = extent(opts.area, [60, 60]);
+	const rng = new Rng(seed);
+	const children = [];
+	for (let i = 1; i <= count; i++) {
+		const puffCount = rng.int(PUFFS[0], PUFFS[1]);
+		const puffs = [];
+		for (let p = 1; p <= puffCount; p++) {
+			const radius = round2(rng.range(1, 2.2));
+			puffs.push({
+				name: `Puff${p}`,
+				type: "MeshInstance3D",
+				props: {
+					mesh: "sphere",
+					size: [
+						1,
+						1,
+						1
+					],
+					position: [
+						round2((p - (puffCount + 1) / 2) * rng.range(1, 1.6)),
+						round2(rng.range(-.3, .3)),
+						round2(rng.range(-.6, .6))
+					],
+					scale: [
+						round2(radius * rng.range(1.1, 1.6)),
+						round2(radius * .55),
+						radius
+					],
+					material: CLOUD_MATERIAL
+				}
+			});
+		}
+		children.push({
+			name: `Cloud${i}`,
+			type: "Node3D",
+			props: { position: [
+				round2(rng.range(-areaX / 2, areaX / 2)),
+				round2(altitude + rng.range(-3, ALTITUDE_JITTER)),
+				round2(rng.range(-areaZ / 2, areaZ / 2))
+			] },
+			children: puffs
+		});
+	}
+	return {
+		name: "Clouds",
+		type: "Node3D",
+		children
+	};
+}
+//#endregion
+//#region src/env/terrain.ts
+/** Valid `generateTerrain` themes — drives the catalog options AND validation. */
+const TERRAIN_GENERATOR_THEMES = [
+	"island",
+	"alpine",
+	"plains",
+	"desert",
+	"meadow",
+	"forest",
+	"savanna",
+	"snow",
+	"wetland",
+	"volcanic"
+];
+/** Terrain3D's default grid segments — the probe MUST match the runtime grid. */
+const TERRAIN_RESOLUTION = 128;
+/** Terrain3D edge wrap: the rim drops this many meters before the −50 m skirt. */
+const EDGE_WRAP_DROP = 20;
+/** Sea margin above the highest rim cliff (> the ~0.52 m wave-trough dip). */
+const SEA_MARGIN = .8;
+/** Island sand splat band tops out at 12% of the realized height span. */
+const SAND_BAND = .12;
+/** Default IBL mood cut for tree-bearing themes (the eztree stand's lit form). */
+const DEFAULT_IBL_INTENSITY = .6;
+const THEMES = {
+	island: {
+		splat: "island",
+		maxHeight: 4.5,
+		sun: "#fff4d6",
+		fill: "#b9d4ff",
+		sky: {
+			elevationDeg: 38,
+			azimuthDeg: 145,
+			turbidity: 2.6,
+			rayleigh: 1.1
+		},
+		fog: {
+			near: 1,
+			far: 4
+		},
+		iblIntensity: .72
+	},
+	alpine: {
+		splat: "alpine",
+		maxHeight: 8,
+		roughness: .65,
+		detail: 5,
+		sun: "#f4f7ff",
+		fill: "#c9d8f2",
+		sky: {
+			elevationDeg: 45,
+			azimuthDeg: 35,
+			turbidity: 1.4,
+			rayleigh: 1.3
+		},
+		fog: {
+			near: 1.8,
+			far: 6.5
+		},
+		sunIntensity: 1.1,
+		exposure: .92,
+		iblIntensity: .72
+	},
+	plains: {
+		splat: "plains",
+		maxHeight: 4,
+		sun: "#fff2cf",
+		fill: "#bcd3ef",
+		sky: {
+			elevationDeg: 36,
+			azimuthDeg: 140,
+			turbidity: 2.4,
+			rayleigh: 1
+		},
+		fog: {
+			near: .9,
+			far: 4
+		},
+		iblIntensity: .58
+	},
+	desert: {
+		splat: "desert",
+		maxHeight: 5,
+		sun: "#ffe3b3",
+		fill: "#e8c9a6",
+		sky: {
+			elevationDeg: 42,
+			azimuthDeg: 160,
+			turbidity: 7,
+			rayleigh: .6
+		},
+		fog: {
+			near: .8,
+			far: 3.2,
+			color: "#e8d3ae"
+		},
+		sunIntensity: 1.35,
+		iblIntensity: .75
+	},
+	meadow: {
+		splat: "grassland",
+		maxHeight: 1.2,
+		sun: "#fff8e2",
+		fill: "#bfe0c9",
+		sky: {
+			elevationDeg: 55,
+			azimuthDeg: 125,
+			turbidity: 2.4,
+			rayleigh: .95
+		},
+		fog: {
+			near: 1,
+			far: 4.4
+		},
+		sunIntensity: 2.6,
+		exposure: 1.12,
+		iblIntensity: .62
+	},
+	forest: {
+		splat: "forest",
+		maxHeight: 2.5,
+		sun: "#ffdca8",
+		fill: "#a9c8b4",
+		sky: {
+			elevationDeg: 29,
+			azimuthDeg: 120,
+			turbidity: 5.5,
+			rayleigh: 1
+		},
+		fog: {
+			near: .22,
+			far: 1.8,
+			color: "#9fb494"
+		},
+		sunIntensity: 2.6,
+		ambient: .26,
+		iblIntensity: .55
+	},
+	savanna: {
+		splat: "savanna",
+		maxHeight: 3,
+		sun: "#ffdca0",
+		fill: "#e6d2a4",
+		sky: {
+			elevationDeg: 34,
+			azimuthDeg: 150,
+			turbidity: 5,
+			rayleigh: .7
+		},
+		fog: {
+			near: 1,
+			far: 4.2,
+			color: "#e3cf9f"
+		},
+		sunIntensity: 2,
+		exposure: 1.05,
+		iblIntensity: .6
+	},
+	snow: {
+		splat: "snow",
+		maxHeight: 2.2,
+		sun: "#dfe9ff",
+		fill: "#c2d2f0",
+		sky: {
+			elevationDeg: 22,
+			azimuthDeg: 35,
+			turbidity: 1.6,
+			rayleigh: 1.6
+		},
+		fog: {
+			near: 1.2,
+			far: 5,
+			color: "#dbe6f5"
+		},
+		sunIntensity: 1,
+		exposure: .9,
+		iblIntensity: .72
+	},
+	wetland: {
+		splat: "wetland",
+		maxHeight: 1.4,
+		sun: "#d6ddc8",
+		fill: "#9fb29a",
+		sky: {
+			elevationDeg: 24,
+			azimuthDeg: 115,
+			turbidity: 9,
+			rayleigh: 1.1
+		},
+		fog: {
+			near: .5,
+			far: 2,
+			color: "#92a288"
+		},
+		sunIntensity: 1.5,
+		exposure: .94,
+		ambient: .24,
+		iblIntensity: .66
+	},
+	volcanic: {
+		splat: "volcanic",
+		maxHeight: 4,
+		roughness: .7,
+		sun: "#ff8a4a",
+		fill: "#7a4a3a",
+		sky: {
+			elevationDeg: 14,
+			azimuthDeg: 135,
+			turbidity: 10,
+			rayleigh: .3
+		},
+		fog: {
+			near: .18,
+			far: 1.4,
+			color: "#2a211c"
+		},
+		sunIntensity: 1.7,
+		exposure: .86,
+		ambient: .22,
+		iblIntensity: .5
+	}
+};
+/**
+* The environment header that matches a generator theme — sky, horizon fog
+* and shadows composed for the same world `generateTerrain` emits (fog
+* distances scale with `size`). Spread it into the scene's `environment`;
+* scene-specific keys (ambient, background fallback) layer on top.
+*/
+function terrainEnvironment(theme, size = 200) {
+	const spec = THEMES[theme];
+	if (!spec) throw new IncantoError("BAD_FORMAT", `terrainEnvironment theme must be one of [${TERRAIN_GENERATOR_THEMES.join(", ")}], got '${theme}'.`, {
+		prop: "theme",
+		validOptions: [...TERRAIN_GENERATOR_THEMES]
+	});
+	return {
+		sky: {
+			type: "atmosphere",
+			...spec.sky
+		},
+		fog: {
+			near: round2(size * spec.fog.near),
+			far: round2(size * spec.fog.far),
+			...spec.fog.color ? { color: spec.fog.color } : {}
+		},
+		shadows: true,
+		...spec.exposure !== void 0 ? { exposure: spec.exposure } : {},
+		iblIntensity: spec.iblIntensity ?? DEFAULT_IBL_INTENSITY,
+		ambient: {
+			color: "#ffffff",
+			intensity: spec.ambient ?? .18
+		}
+	};
+}
+/**
+* A complete heightfield world from one seed + one theme: the canonical
+* physics recipe (`StaticBody3D{heightfield}` with a `Terrain3D` child) plus
+* theme dressing placed ON the surface via the same heightmap the node will
+* build at runtime — trees probe `heightAt` and reject steep/sand/snow cells,
+* the island sea level is COMPUTED from border probes (two-sided constraint:
+* above every rim cliff top, inside the sand band), rocks/foliage sit at
+* their sampled ground height. Sun/fill lights round out every theme.
+*
+* Replaces the old voxel terrain in the catalog — that lives on as the
+* library-only `generateVoxelTerrain` for minecraft-style block worlds.
+*/
+function generateTerrain(opts) {
+	const { seed, theme = "island", size = 200, water = false } = opts;
+	const spec = THEMES[theme];
+	if (!spec) throw new IncantoError("BAD_FORMAT", `generateTerrain theme must be one of [${TERRAIN_GENERATOR_THEMES.join(", ")}], got '${theme}'.`, {
+		prop: "theme",
+		validOptions: [...TERRAIN_GENERATOR_THEMES]
+	});
+	let maxHeight = opts.maxHeight || spec.maxHeight;
+	const rng = new Rng(seed);
+	const isIsland = theme === "island";
+	const probe = (h) => buildHeightmap({
+		width: size,
+		depth: size,
+		segsX: TERRAIN_RESOLUTION,
+		segsZ: TERRAIN_RESOLUTION,
+		maxHeight: h,
+		seed,
+		...spec.roughness !== void 0 ? { roughness: spec.roughness } : {},
+		...spec.detail !== void 0 ? { detail: spec.detail } : {},
+		islandEdge: isIsland
+	});
+	let hm = probe(maxHeight);
+	if (isIsland) for (let i = 0; i < 3; i++) {
+		const cliffTop = borderMaxHeight(hm) - EDGE_WRAP_DROP;
+		const span = hm.maxHeight - hm.minHeight;
+		const sandTop = hm.minHeight + SAND_BAND * span;
+		if (cliffTop + SEA_MARGIN <= sandTop) break;
+		const budget = EDGE_WRAP_DROP - SEA_MARGIN;
+		const needed = borderMaxHeight(hm) - hm.minHeight - SAND_BAND * span;
+		maxHeight = round2(maxHeight * Math.min(budget / needed * .95, .9));
+		hm = probe(maxHeight);
+	}
+	const children = [{
+		name: "Ground",
+		type: "StaticBody3D",
+		props: { collider: { shape: "heightfield" } },
+		children: [{
+			name: "Surface",
+			type: "Terrain3D",
+			props: {
+				size: [size, size],
+				maxHeight,
+				seed,
+				theme: spec.splat,
+				...spec.roughness !== void 0 ? { roughness: spec.roughness } : {},
+				...spec.detail !== void 0 ? { detail: spec.detail } : {}
+			}
+		}]
+	}];
+	const isWetland = theme === "wetland";
+	if (isIsland) children.push({
+		name: "Sea",
+		type: "Water3D",
+		props: {
+			size: [size * 8, size * 8],
+			position: [
+				0,
+				islandSeaLevel(hm),
+				0
+			],
+			opacity: 1
+		}
+	});
+	else if (isWetland) {
+		const span = hm.maxHeight - hm.minHeight || 1;
+		const waterLevel = round2(hm.minHeight + .22 * span);
+		children.push({
+			name: "Swamp",
+			type: "Water3D",
+			props: {
+				size: [size, size],
+				position: [
+					0,
+					waterLevel,
+					0
+				],
+				waveHeight: .02,
+				quality: "simple",
+				color: "#3a4a30",
+				opacity: .95
+			}
+		});
+	} else if (water) {
+		const lakeLevel = round2(hm.minHeight + .1 * (hm.maxHeight - hm.minHeight));
+		children.push({
+			name: "Lake",
+			type: "Water3D",
+			props: {
+				size: [size, size],
+				position: [
+					0,
+					lakeLevel,
+					0
+				],
+				waveHeight: .04
+			}
+		});
+	}
+	children.push(...dressing(theme, rng, hm, size));
+	if (isIsland) children.push(generateClouds({
+		seed: rng.int(1, 1e9),
+		count: 6,
+		area: size,
+		altitude: Math.round(hm.maxHeight + 12)
+	}));
+	children.push(...skyLights(size).map((light, i) => tintLight(light, i === 0 ? spec.sun : spec.fill, i === 0 ? spec.sunIntensity ?? 1.7 : void 0)));
+	return {
+		name: "Terrain",
+		type: "Node3D",
+		children
+	};
+}
+/**
+* The documented two-sided island sea-level constraint, computed instead of
+* guessed: the edge wrap drops the rim only 20 m before the vertical skirt,
+* so the sea must sit ABOVE (highest border height − 20 m) — probe the
+* border with `baseHeight` — while staying inside the sand band (bottom 12%
+* of the realized span) so the visible shore reads as beach. Drownability
+* wins when a tall island can't satisfy both.
+*/
+function islandSeaLevel(hm) {
+	const cliffTop = borderMaxHeight(hm) - EDGE_WRAP_DROP;
+	const sandTop = hm.minHeight + SAND_BAND * (hm.maxHeight - hm.minHeight);
+	return round2(Math.max(Math.min(cliffTop + SEA_MARGIN, sandTop), cliffTop + .55));
+}
+/** Highest no-wrap height along the terrain border (probed like the docs say). */
+function borderMaxHeight(hm) {
+	let borderMax = Number.NEGATIVE_INFINITY;
+	const hw = hm.width / 2;
+	const hd = hm.depth / 2;
+	for (let i = 0; i <= TERRAIN_RESOLUTION; i++) {
+		const x = -hw + i / TERRAIN_RESOLUTION * hm.width;
+		const z = -hd + i / TERRAIN_RESOLUTION * hm.depth;
+		borderMax = Math.max(borderMax, hm.baseHeight(x, -hd), hm.baseHeight(x, hd), hm.baseHeight(-hw, z), hm.baseHeight(hw, z));
+	}
+	return borderMax;
+}
+/** Rejection-sample terrain cells matching a height band + slope budget. */
+function sampleSpots(rng, hm, spec) {
+	const limit = Math.min(hm.width / 2 - spec.margin, spec.within ?? Number.POSITIVE_INFINITY);
+	const span = hm.maxHeight - hm.minHeight || 1;
+	const spots = [];
+	for (let attempt = 0; attempt < spec.count * 30 && spots.length < spec.count; attempt++) {
+		const x = round2(rng.range(-limit, limit));
+		const z = round2(rng.range(-limit, limit));
+		if (spec.clearing && Math.hypot(x, z) < spec.clearing) continue;
+		if (spec.within && Math.hypot(x, z) > spec.within) continue;
+		const y = hm.heightAt(x, z);
+		const h01 = (y - hm.minHeight) / span;
+		if (h01 < spec.band[0] || h01 > spec.band[1]) continue;
+		if (hm.slopeAt(x, z) > spec.maxSlope) continue;
+		spots.push({
+			x,
+			z,
+			y
+		});
+	}
+	return spots;
+}
+const CONIFER_PALETTE = [
+	{
+		canopy: "#2f5d44",
+		trunk: "#6e4a32"
+	},
+	{
+		canopy: "#356a4c",
+		trunk: "#71503a"
+	},
+	{
+		canopy: "#2c5740",
+		trunk: "#5f4530"
+	},
+	{
+		canopy: "#3a6b4a",
+		trunk: "#6a4c34"
+	}
+];
+const BROADLEAF_PALETTE = [
+	{
+		canopy: "#4a7c3f",
+		trunk: "#7a5a3a"
+	},
+	{
+		canopy: "#56883c",
+		trunk: "#806044"
+	},
+	{
+		canopy: "#7a9d3e",
+		trunk: "#9a9488"
+	},
+	{
+		canopy: "#86a346",
+		trunk: "#a39c8e"
+	},
+	{
+		canopy: "#b8862f",
+		trunk: "#7e5e38"
+	},
+	{
+		canopy: "#a8702c",
+		trunk: "#74552f"
+	}
+];
+/** Savanna acacia: a dry golden-green flat canopy over warm tan bark. */
+const ACACIA_PALETTE = {
+	canopy: "#9aa052",
+	trunk: "#8a6a44"
+};
+/** Snow tundra conifer: a cool DARK blue-green, frosted — reads dusted. */
+const SNOW_CONIFER_PALETTE = {
+	canopy: "#39513f",
+	trunk: "#5a5650"
+};
+/** A species canopy/trunk variant for a grove — drawn from the rng in a fixed
+* order so determinism holds. Conifers/broadleaf get their palettes; dead and
+* bush keep the node defaults (snags are barkless grey, bushes their own). */
+function speciesColors(type, rng) {
+	if (type === "conifer") return rng.pick(CONIFER_PALETTE);
+	if (type === "broadleaf") return rng.pick(BROADLEAF_PALETTE);
+	return null;
+}
+/** A Tree3D at a sampled spot — slightly sunk so the roots never float. The
+* grove draws a per-species canopy/trunk variant from the rng (fixed order →
+* deterministic), giving the world its tree-color variety; dead/bush keep the
+* node defaults. The rng draw happens for EVERY tree so the seed contract is
+* stable regardless of species. */
+function treeAt(name, spot, rng, type, grove) {
+	const heightRange = grove?.height ?? [4.5, 7];
+	const sink = grove?.sink ?? (grove?.count !== void 0 ? .3 : .05);
+	const extras = {};
+	if (grove?.tier !== void 0) extras.tier = grove.tier;
+	if (grove?.count !== void 0 && grove.area !== void 0) {
+		extras.count = grove.count;
+		extras.area = [grove.area, grove.area];
+	}
+	const colors = speciesColors(type, rng);
+	const tint = grove?.palette ?? colors;
+	if (tint) {
+		extras.canopyColor = tint.canopy;
+		extras.trunkColor = tint.trunk;
+	}
+	return {
+		name,
+		type: "Tree3D",
+		props: {
+			type,
+			seed: rng.int(1, 1e9),
+			height: round2(rng.range(heightRange[0], heightRange[1])),
+			position: [
+				spot.x,
+				round2(spot.y - sink),
+				spot.z
+			],
+			...extras
+		}
+	};
+}
+/** A Foliage3D grass patch hugging the surface at a sampled flat spot.
+* eztree-parity pass: carpets render the `tufts` style — recon showed the
+* reference 잔디밭 is instanced multi-blade tuft CARDS, not per-blade
+* geometry — with a taller stand (the reference grass is knee-high).
+* `flowers` sprinkles white/yellow/violet heads — a meadow thing (the node
+* default stays 0 for back-compat; themes opt in here). */
+function grassAt(name, spot, rng, patch, density, flowers = 0, look) {
+	return {
+		name,
+		type: "Foliage3D",
+		props: {
+			kind: "grass",
+			style: "tufts",
+			area: [patch, patch],
+			density,
+			height: look?.height ?? .3,
+			...look?.colors ? {
+				colorA: look.colors[0],
+				colorB: look.colors[1]
+			} : {},
+			seed: rng.int(1, 1e9),
+			position: [
+				spot.x,
+				round2(spot.y + .02),
+				spot.z
+			],
+			...flowers > 0 ? { flowers } : {}
+		}
+	};
+}
+/** A Foliage3D REED bed hugging the surface at a sampled flat spot — the
+* swamp's lush dark-green reeds (kind 'reeds' only has the 'simple' look:
+* tall crossed quads). Rooted at the water margin so they read as marsh. */
+function reedsAt(name, spot, rng, patch, density) {
+	return {
+		name,
+		type: "Foliage3D",
+		props: {
+			kind: "reeds",
+			style: "simple",
+			area: [patch, patch],
+			density,
+			height: .9,
+			colorA: "#2f4a26",
+			colorB: "#5a6f33",
+			seed: rng.int(1, 1e9),
+			position: [
+				spot.x,
+				round2(spot.y + .02),
+				spot.z
+			]
+		}
+	};
+}
+/** A Flowers3D patch hugging the surface at a sampled flat spot — real
+* flower plants (stems + petal heads), density preset per theme. */
+function flowersAt(name, spot, rng, patch, density) {
+	return {
+		name,
+		type: "Flowers3D",
+		props: {
+			density,
+			area: [patch, patch],
+			seed: rng.int(1, 1e9),
+			position: [
+				spot.x,
+				round2(spot.y + .02),
+				spot.z
+			]
+		}
+	};
+}
+/** Rocks ride their sampled ground height (rock() y is the boulder sink).
+* `tone` overrides the stony gray per boulder (the forest's moss tint). */
+function rocksAt(spots, rng, sizeRange, tone) {
+	return spots.map((spot, i) => {
+		const node = rock(i + 1, spot.x, spot.z, rng, sizeRange, tone?.(rng));
+		const position = node.props?.position;
+		position[1] = round2(position[1] + spot.y);
+		return node;
+	});
+}
+/** A deterministic moss green-grey — boulders under a canopy grow a coat.
+* Kept close to gray (green channel leads by a whisker): a saturated green
+* sphere reads as a glowing egg from the treeline, not a mossy rock. */
+function mossTone(rng) {
+	const g = Math.round(rng.range(104, 128));
+	const r = Math.round(g - rng.range(10, 18));
+	const b = Math.round(g - rng.range(20, 30));
+	const hex = (v) => v.toString(16).padStart(2, "0");
+	return `#${hex(r)}${hex(g)}${hex(b)}`;
+}
+/** A deterministic near-white grey — snow-dusted tundra boulders (cool, very
+* light, a faint blue cast so they read as snow-capped stone, not white eggs). */
+function snowTone(rng) {
+	const v = Math.round(rng.range(196, 224));
+	const b = Math.min(255, v + Math.round(rng.range(4, 12)));
+	const hex = (x) => x.toString(16).padStart(2, "0");
+	return `#${hex(v)}${hex(v)}${hex(b)}`;
+}
+/** A deterministic dark basalt grey — charred volcanic boulders (near-black,
+* a hair warm so they don't read as pure void under the ember light). */
+function basaltTone(rng) {
+	const v = Math.round(rng.range(34, 56));
+	const r = Math.min(255, v + Math.round(rng.range(2, 8)));
+	const hex = (x) => x.toString(16).padStart(2, "0");
+	return `#${hex(r)}${hex(v)}${hex(v)}`;
+}
+/** Weathered dead-wood browns for stumps (bark long gone, heartwood left). */
+const STUMP_COLORS = [
+	"#6f5b41",
+	"#7a644a",
+	"#665439"
+];
+/** Theme dressing — every spot is probed against the SAME runtime heightmap. */
+function dressing(theme, rng, hm, size) {
+	const out = [];
+	switch (theme) {
+		case "island": {
+			const spots = sampleSpots(rng, hm, {
+				count: 7,
+				band: [.18, .6],
+				maxSlope: .5,
+				margin: 26
+			});
+			out.push(...spots.map((s, i) => treeAt(`Tree${i + 1}`, s, rng, "conifer")));
+			break;
+		}
+		case "alpine": {
+			const treeline = sampleSpots(rng, hm, {
+				count: 10,
+				band: [.2, .5],
+				maxSlope: .55,
+				margin: 6
+			});
+			out.push(...treeline.map((s, i) => treeAt(`Tree${i + 1}`, s, rng, "conifer")));
+			const snowBand = sampleSpots(rng, hm, {
+				count: 8,
+				band: [.55, 1],
+				maxSlope: .9,
+				margin: 6
+			});
+			out.push(...rocksAt(snowBand, rng, [.6, 1.8]));
+			break;
+		}
+		case "plains": {
+			const trees = sampleSpots(rng, hm, {
+				count: 8,
+				band: [0, 1],
+				maxSlope: .4,
+				margin: 6
+			});
+			out.push(...trees.map((s, i) => treeAt(`Tree${i + 1}`, s, rng, "broadleaf")));
+			const boulders = sampleSpots(rng, hm, {
+				count: 6,
+				band: [0, 1],
+				maxSlope: .5,
+				margin: 6
+			});
+			out.push(...rocksAt(boulders, rng, [.4, 1.2]));
+			break;
+		}
+		case "desert": {
+			const trees = sampleSpots(rng, hm, {
+				count: 6,
+				band: [0, 1],
+				maxSlope: .45,
+				margin: 6
+			});
+			out.push(...trees.map((s, i) => treeAt(`Tree${i + 1}`, s, rng, "dead")));
+			const boulders = sampleSpots(rng, hm, {
+				count: 8,
+				band: [0, 1],
+				maxSlope: .6,
+				margin: 6
+			});
+			out.push(...rocksAt(boulders, rng, [.5, 1.6]));
+			break;
+		}
+		case "meadow": {
+			const patch = round2(size * .09);
+			const carpets = sampleSpots(rng, hm, {
+				count: 7,
+				band: [0, 1],
+				maxSlope: .05,
+				margin: patch / 2 + 8
+			});
+			out.push(...carpets.map((s, i) => grassAt(`Carpet${i + 1}`, s, rng, patch, 30)));
+			const bed = round2(size * .07);
+			const beds = sampleSpots(rng, hm, {
+				count: 3,
+				band: [0, 1],
+				maxSlope: .05,
+				margin: bed / 2 + 8
+			});
+			out.push(...beds.map((s, i) => flowersAt(`Flowers${i + 1}`, s, rng, bed, "sparse")));
+			const groves = sampleSpots(rng, hm, {
+				count: 4,
+				band: [0, 1],
+				maxSlope: .1,
+				margin: 12
+			});
+			out.push(...groves.map((s, i) => treeAt(`Grove${i + 1}`, s, rng, "broadleaf", {
+				count: 3,
+				area: 6
+			})));
+			const boulders = sampleSpots(rng, hm, {
+				count: 6,
+				band: [0, 1],
+				maxSlope: .2,
+				margin: 8
+			});
+			out.push(...rocksAt(boulders, rng, [.3, .9]));
+			break;
+		}
+		case "forest": {
+			const clearing = round2(size * .12);
+			const limit = size / 2 - 8;
+			const species = createNoise2D(rng.int(1, 1e9));
+			const speciesAt = (x, z, i) => {
+				const n = species(x / 70, z / 70);
+				if (n > .12) return "conifer";
+				if (n < -.12) return "broadleaf";
+				return i % 2 === 0 ? "conifer" : "broadleaf";
+			};
+			const clusters = sampleSpots(rng, hm, {
+				count: 40,
+				band: [0, 1],
+				maxSlope: .18,
+				margin: 8,
+				clearing: clearing + 6
+			});
+			const groveTypes = clusters.map((s, i) => speciesAt(s.x, s.z, i));
+			out.push(...clusters.map((s, i) => treeAt(`Grove${i + 1}`, s, rng, groveTypes[i], {
+				count: 12,
+				area: 13,
+				height: [5.5, 8]
+			})));
+			clusters.forEach((s, i) => {
+				if (i % 3 !== 0) return;
+				out.push(treeAt(`Sapling${i + 1}`, s, rng, groveTypes[i], {
+					count: 4,
+					area: 19,
+					height: [2.5, 3.4],
+					sink: .12
+				}));
+			});
+			const elderSpots = sampleSpots(rng, hm, {
+				count: 6,
+				band: [0, 1],
+				maxSlope: .2,
+				margin: 12,
+				clearing: clearing + 4
+			});
+			out.push(...elderSpots.map((s, i) => treeAt(`Elder${i + 1}`, s, rng, speciesAt(s.x, s.z, i), {
+				tier: "high",
+				height: [8.4, 9.8]
+			})));
+			const accentSpots = sampleSpots(rng, hm, {
+				count: 3,
+				band: [0, 1],
+				maxSlope: .18,
+				margin: 10,
+				clearing: clearing + 6
+			});
+			out.push(...accentSpots.map((s, i) => treeAt(`Accent${i + 1}`, s, rng, "broadleaf", {
+				tier: "high",
+				count: 3,
+				area: 7,
+				height: [5.6, 6.8]
+			})));
+			const bushSpots = sampleSpots(rng, hm, {
+				count: 10,
+				band: [0, 1],
+				maxSlope: .14,
+				margin: 9,
+				clearing: clearing + 2
+			});
+			out.push(...bushSpots.map((s, i) => treeAt(`Bush${i + 1}`, s, rng, "bush", {
+				count: 4,
+				area: 10,
+				height: [2.1, 3.1],
+				sink: .12
+			})));
+			let fernIndex = 0;
+			clusters.forEach((s, i) => {
+				if (i % 3 === 2) return;
+				const angle = rng.range(0, Math.PI * 2);
+				const dist = rng.range(2, 4.5);
+				const fernSeed = rng.int(1, 1e9);
+				const fx = round2(clamp(s.x + Math.cos(angle) * dist, -limit, limit));
+				const fz = round2(clamp(s.z + Math.sin(angle) * dist, -limit, limit));
+				if (hm.slopeAt(fx, fz) > .09) return;
+				fernIndex++;
+				out.push({
+					name: `Fern${fernIndex}`,
+					type: "Foliage3D",
+					props: {
+						kind: "grass",
+						style: "tufts",
+						tuftStyle: "fern",
+						area: [8, 8],
+						density: 9,
+						height: .4,
+						colorA: "#4a6b34",
+						colorB: "#82a258",
+						seed: fernSeed,
+						position: [
+							fx,
+							round2(hm.heightAt(fx, fz) + .02),
+							fz
+						]
+					}
+				});
+			});
+			const patch = round2(size * .08);
+			const patches = sampleSpots(rng, hm, {
+				count: 5,
+				band: [0, 1],
+				maxSlope: .06,
+				margin: patch / 2 + 8
+			});
+			out.push(...patches.map((s, i) => grassAt(`Grass${i + 1}`, s, rng, patch, 20, 0, {
+				height: .24,
+				colors: ["#4f7034", "#85a154"]
+			})));
+			const logCount = elderSpots.length > 0 ? rng.int(3, 5) : 0;
+			for (let i = 0; i < logCount; i++) {
+				const elder = elderSpots[i % elderSpots.length];
+				const angle = rng.range(0, Math.PI * 2);
+				const dist = rng.range(2.5, 4.5);
+				const lx = round2(clamp(elder.x + Math.cos(angle) * dist, -limit, limit));
+				const lz = round2(clamp(elder.z + Math.sin(angle) * dist, -limit, limit));
+				out.push({
+					name: `Log${i + 1}`,
+					type: "Tree3D",
+					props: {
+						type: "dead",
+						seed: rng.int(1, 1e9),
+						height: round2(rng.range(4.2, 5.6)),
+						trunkColor: "#4a4236",
+						position: [
+							lx,
+							round2(hm.heightAt(lx, lz) + .12),
+							lz
+						],
+						rotation: [
+							0,
+							rng.int(0, 359),
+							round2(rng.range(81, 97))
+						]
+					}
+				});
+			}
+			sampleSpots(rng, hm, {
+				count: 5,
+				band: [0, 1],
+				maxSlope: .25,
+				margin: 9,
+				clearing
+			}).forEach((s, i) => {
+				const radius = round2(rng.range(.16, .28));
+				const height = round2(rng.range(.3, .55));
+				out.push({
+					name: `Stump${i + 1}`,
+					type: "MeshInstance3D",
+					props: {
+						mesh: "cylinder",
+						size: [
+							radius,
+							height,
+							radius
+						],
+						position: [
+							s.x,
+							round2(s.y + height / 2 - .06),
+							s.z
+						],
+						rotation: [
+							0,
+							rng.int(0, 359),
+							0
+						],
+						material: {
+							color: rng.pick(STUMP_COLORS),
+							roughness: 1
+						},
+						castShadow: true
+					}
+				});
+			});
+			const boulders = sampleSpots(rng, hm, {
+				count: 8,
+				band: [0, 1],
+				maxSlope: .2,
+				margin: 8
+			});
+			out.push(...rocksAt(boulders, rng, [.3, 1], mossTone));
+			const carpet = round2(clearing * .75);
+			const carpets = sampleSpots(rng, hm, {
+				count: 3,
+				band: [0, 1],
+				maxSlope: .06,
+				margin: 8,
+				within: clearing - round2(carpet / Math.SQRT2)
+			});
+			out.push(...carpets.map((s, i) => grassAt(`Clearing${i + 1}`, s, rng, carpet, 30, 0, { colors: ["#5d8438", "#a8bc60"] })));
+			const bed = round2(clearing * .45);
+			const beds = sampleSpots(rng, hm, {
+				count: 2,
+				band: [0, 1],
+				maxSlope: .06,
+				margin: 8,
+				within: clearing - round2(bed / Math.SQRT2)
+			});
+			out.push(...beds.map((s, i) => flowersAt(`Flowers${i + 1}`, s, rng, bed, "sparse")));
+			break;
+		}
+		case "savanna": {
+			const trees = sampleSpots(rng, hm, {
+				count: 7,
+				band: [0, .85],
+				maxSlope: .35,
+				margin: 8
+			});
+			out.push(...trees.map((s, i) => treeAt(`Tree${i + 1}`, s, rng, "broadleaf", {
+				height: [3.5, 5],
+				palette: ACACIA_PALETTE
+			})));
+			const patch = round2(size * .09);
+			const carpets = sampleSpots(rng, hm, {
+				count: 6,
+				band: [0, 1],
+				maxSlope: .05,
+				margin: patch / 2 + 8
+			});
+			out.push(...carpets.map((s, i) => grassAt(`Carpet${i + 1}`, s, rng, patch, 26, 0, {
+				height: .34,
+				colors: ["#9a8f43", "#c9bd6a"]
+			})));
+			const boulders = sampleSpots(rng, hm, {
+				count: 7,
+				band: [0, 1],
+				maxSlope: .5,
+				margin: 8
+			});
+			out.push(...rocksAt(boulders, rng, [.4, 1.4]));
+			const scrub = sampleSpots(rng, hm, {
+				count: 4,
+				band: [0, 1],
+				maxSlope: .2,
+				margin: 9
+			});
+			out.push(...scrub.map((s, i) => treeAt(`Scrub${i + 1}`, s, rng, "bush", {
+				count: 3,
+				area: 8,
+				height: [1.4, 2.2]
+			})));
+			break;
+		}
+		case "snow": {
+			const trees = sampleSpots(rng, hm, {
+				count: 8,
+				band: [0, .9],
+				maxSlope: .4,
+				margin: 8
+			});
+			out.push(...trees.map((s, i) => treeAt(`Tree${i + 1}`, s, rng, "conifer", {
+				height: [4, 6.5],
+				palette: SNOW_CONIFER_PALETTE
+			})));
+			const boulders = sampleSpots(rng, hm, {
+				count: 10,
+				band: [0, 1],
+				maxSlope: .7,
+				margin: 8
+			});
+			out.push(...rocksAt(boulders, rng, [.5, 1.8], snowTone));
+			break;
+		}
+		case "wetland": {
+			const bed = round2(size * .08);
+			const reedBeds = sampleSpots(rng, hm, {
+				count: 6,
+				band: [0, .5],
+				maxSlope: .06,
+				margin: bed / 2 + 8
+			});
+			out.push(...reedBeds.map((s, i) => reedsAt(`Reeds${i + 1}`, s, rng, bed, 4)));
+			const patch = round2(size * .08);
+			const moss = sampleSpots(rng, hm, {
+				count: 4,
+				band: [.2, 1],
+				maxSlope: .05,
+				margin: patch / 2 + 8
+			});
+			out.push(...moss.map((s, i) => grassAt(`Moss${i + 1}`, s, rng, patch, 22, 0, {
+				height: .22,
+				colors: ["#3a5a2c", "#6f8a48"]
+			})));
+			const snags = sampleSpots(rng, hm, {
+				count: 6,
+				band: [.25, 1],
+				maxSlope: .35,
+				margin: 9
+			});
+			out.push(...snags.map((s, i) => treeAt(`Snag${i + 1}`, s, rng, "dead", { height: [4, 6] })));
+			const bushes = sampleSpots(rng, hm, {
+				count: 6,
+				band: [.2, 1],
+				maxSlope: .2,
+				margin: 9
+			});
+			out.push(...bushes.map((s, i) => treeAt(`Bush${i + 1}`, s, rng, "bush", {
+				count: 3,
+				area: 7,
+				height: [1.6, 2.6]
+			})));
+			const boulders = sampleSpots(rng, hm, {
+				count: 5,
+				band: [.2, 1],
+				maxSlope: .3,
+				margin: 8
+			});
+			out.push(...rocksAt(boulders, rng, [.3, 1], mossTone));
+			break;
+		}
+		case "volcanic": {
+			const trees = sampleSpots(rng, hm, {
+				count: 7,
+				band: [0, 1],
+				maxSlope: .45,
+				margin: 8
+			});
+			out.push(...trees.map((s, i) => treeAt(`Tree${i + 1}`, s, rng, "dead", { height: [4, 6.5] })));
+			const boulders = sampleSpots(rng, hm, {
+				count: 12,
+				band: [0, 1],
+				maxSlope: .7,
+				margin: 8
+			});
+			out.push(...rocksAt(boulders, rng, [.4, 1.8], basaltTone));
+			sampleSpots(rng, hm, {
+				count: 3,
+				band: [0, .6],
+				maxSlope: .18,
+				margin: 12
+			}).forEach((s, i) => {
+				rng.int(1, 1e9);
+				out.push({
+					name: `Smoke${i + 1}`,
+					type: "Particles3D",
+					props: {
+						preset: "smoke",
+						position: [
+							s.x,
+							round2(s.y + .2),
+							s.z
+						],
+						rate: 8,
+						maxParticles: 64,
+						colorStart: "#5a5048",
+						colorEnd: "#2a2422",
+						sizeStart: 18,
+						sizeEnd: 44
+					}
+				});
+				out.push({
+					name: `Embers${i + 1}`,
+					type: "Particles3D",
+					props: {
+						position: [
+							s.x,
+							round2(s.y + .1),
+							s.z
+						],
+						rate: 10,
+						maxParticles: 48,
+						lifetime: [.8, 1.8],
+						speed: [12, 34],
+						directionDeg: -90,
+						spreadDeg: 40,
+						gravity: [0, -18],
+						sizeStart: 4,
+						sizeEnd: 1,
+						colorStart: "#ffce6a",
+						colorEnd: "#d83a14",
+						blend: "add"
+					}
+				});
+			});
+			break;
+		}
+	}
+	return out;
+}
+/** Tint a skyLights() light toward the theme palette (fog-ready colors). */
+function tintLight(light, color, intensity) {
+	return {
+		...light,
+		props: {
+			...light.props,
+			color,
+			...intensity !== void 0 ? { intensity } : {}
+		}
+	};
+}
+//#endregion
+//#region src/env/catalog.ts
+/**
+* The generator catalog: name → description, dimension and CLI-typed params.
+* Drives the `incanto-env` CLI (`--list`, generic `--<param>` flags) and any
+* editor UI, so help text can never drift from the code. `seed` is implicit
+* — every generator requires it.
+*
+* The 3D set is EXACTLY arena/terrain/maze — themes do the heavy lifting
+* (the old meadow/forest/island/rocks/clouds generators became terrain/arena
+* themes; their functions live on in the library, deprecated). Tuple-typed
+* library options (scatter items, platforms2d ranges) and the voxel-world
+* `generateVoxelTerrain` stay library-only and are not listed.
+*/
+const GENERATORS = {
+	arena: {
+		description: "FPS stage: floor, 4 perimeter walls, obstacles, lights — themes: boxes (crates), ruins (broken stone rows), garden (hedges, grass, pool)",
+		dimension: "3d",
+		params: {
+			theme: {
+				type: "string",
+				default: "boxes",
+				options: [...ARENA_THEMES]
+			},
+			width: {
+				type: "number",
+				default: 30,
+				min: 4
+			},
+			depth: {
+				type: "number",
+				default: 30,
+				min: 4
+			},
+			wallHeight: {
+				type: "number",
+				default: 3,
+				min: .5
+			},
+			obstacles: {
+				type: "number",
+				default: 8,
+				min: 0
+			}
+		}
+	},
+	terrain: {
+		description: "Heightfield world: StaticBody3D{heightfield} + Terrain3D + theme dressing (trees, rocks, grass, sea/clouds on island, broad swamp water on wetland, smoke/ember emitters on volcanic; maxHeight 0 = theme default; water adds a lake to non-island themes)",
+		dimension: "3d",
+		params: {
+			theme: {
+				type: "string",
+				default: "island",
+				options: [...TERRAIN_GENERATOR_THEMES]
+			},
+			size: {
+				type: "number",
+				default: 200,
+				min: 40,
+				max: 400
+			},
+			maxHeight: {
+				type: "number",
+				default: 0,
+				min: 0
+			},
+			water: {
+				type: "boolean",
+				default: false
+			}
+		}
+	},
+	maze: {
+		description: "Recursive-backtracker 3D maze, west→east — themes: stone, hedge (green + grass), canyon (sandstone + rim rocks)",
+		dimension: "3d",
+		params: {
+			theme: {
+				type: "string",
+				default: "stone",
+				options: [...MAZE_THEMES]
+			},
+			width: {
+				type: "number",
+				default: 8,
+				min: 2,
+				max: 40
+			},
+			depth: {
+				type: "number",
+				default: 8,
+				min: 2,
+				max: 40
+			},
+			cellSize: {
+				type: "number",
+				default: 2,
+				min: .5
+			},
+			wallHeight: {
+				type: "number",
+				default: 2.5,
+				min: .5
+			}
+		}
+	},
+	maze2d: {
+		description: "The same maze algorithm as 2D ColorRect2D + StaticBody2D tiles",
+		dimension: "2d",
+		params: {
+			cols: {
+				type: "number",
+				default: 10,
+				min: 2,
+				max: 40
+			},
+			rows: {
+				type: "number",
+				default: 8,
+				min: 2,
+				max: 40
+			},
+			cellPx: {
+				type: "number",
+				default: 64,
+				min: 8
+			}
+		}
+	},
+	dungeon2d: {
+		description: "Roguelike rooms + L-corridors: floor rects, wall bodies (32px tiles)",
+		dimension: "2d",
+		params: {
+			rooms: {
+				type: "number",
+				default: 5,
+				min: 1,
+				max: 20
+			},
+			size: {
+				type: "number",
+				default: 960,
+				min: 256
+			}
+		}
+	},
+	platforms2d: {
+		description: "Left-to-right 2D platform course (tune ranges via the library)",
+		dimension: "2d",
+		params: { count: {
+			type: "number",
+			default: 10,
+			min: 1
+		} }
+	}
+};
+const RUNNERS = {
+	arena: generateArena,
+	terrain: generateTerrain,
+	maze: generateMaze,
+	maze2d: generateMaze2D,
+	dungeon2d: generateDungeon2D,
+	platforms2d: generatePlatforms2D
+};
+/**
+* Invoke any catalog generator uniformly by name (what the CLI and editor
+* call). Unknown names are a hard error listing the valid ones; option
+* validation stays with each generator.
+*/
+function runGenerator(name, opts) {
+	const fn = RUNNERS[name];
+	if (!fn) {
+		const valid = Object.keys(RUNNERS);
+		throw new IncantoError("BAD_FORMAT", `Unknown generator '${name}'. Valid: [${valid.join(", ")}] — the old meadow/forest/island/rocks/clouds generators became themes (e.g. terrain theme: 'meadow', arena theme: 'garden'); scatter is library-only (needs item templates).`, { validOptions: valid });
+	}
+	return fn(opts);
+}
+//#endregion
+//#region src/env/forest.ts
+const GROUND_COLOR$1 = "#3c5e2e";
+const GRASS_PATCHES = 3;
+const EDGE_MARGIN$1 = 1.5;
+/**
+* A primitive-tree forest: a ground slab planted with StaticBody3D
+* trunk+canopy trees whose density falls off into an optional central
+* clearing (hard-empty inside `clearing`, ramping to full density at 1.5×),
+* softened by a few Foliage3D grass patches, lit by sun/fill.
+*
+* @deprecated Use `runGenerator('terrain', { seed, theme: 'forest' })` — the
+* Terrain3D forest (dense mixed Tree3D groves, central clearing, grass
+* patches, heightfield collider) replaced this flat-slab version in the
+* catalog.
+*/
+function generateForest(opts) {
+	const { seed, size = 48, trees = 40, clearing = 6 } = opts;
+	const rng = new Rng(seed);
+	const children = [staticBox("Ground", [
+		size,
+		.2,
+		size
+	], [
+		0,
+		-.1,
+		0
+	], {
+		material: {
+			color: GROUND_COLOR$1,
+			roughness: 1
+		},
+		receiveShadow: true
+	})];
+	const limit = size / 2 - EDGE_MARGIN$1;
+	const rampEdge = clearing * 1.5;
+	let planted = 0;
+	for (let attempt = 0; attempt < trees * 8 && planted < trees; attempt++) {
+		const x = round2(rng.range(-limit, limit));
+		const z = round2(rng.range(-limit, limit));
+		const distance = Math.hypot(x, z);
+		if (clearing > 0) {
+			if (distance < clearing) continue;
+			if (distance < rampEdge && rng.next() > (distance - clearing) / (rampEdge - clearing)) continue;
+		}
+		planted++;
+		children.push(tree(planted, x, z, rng));
+	}
+	for (let i = 1; i <= GRASS_PATCHES; i++) {
+		const patch = round2(size * rng.range(.18, .3));
+		const reach = size / 2 - patch / 2;
+		children.push({
+			name: `Grass${i}`,
+			type: "Foliage3D",
+			props: {
+				kind: "grass",
+				area: [patch, patch],
+				density: 8,
+				seed: rng.int(1, 1e9),
+				position: [
+					round2(rng.range(-reach, reach)),
+					0,
+					round2(rng.range(-reach, reach))
+				]
+			}
+		});
+	}
+	children.push(...skyLights(size));
+	return {
+		name: "Forest",
+		type: "Node3D",
+		children
+	};
+}
+//#endregion
+//#region src/env/insert.ts
+/**
+* PURE insertion: a NEW scene JSON with `node` appended under the node at
+* `at` (default: the scene root). Neither input is mutated.
+*
+* `at` is the '/'-joined chain of node NAMES from the root, ROOT INCLUDED —
+* 'Root/Level' targets the root's child 'Level' (NodePath semantics applied
+* to the JSON tree). A missing path is a hard NODE_NOT_FOUND listing what IS
+* there. Sibling name clashes are fine — the loader uniquifies on load.
+*/
+function insertIntoScene(scene, node, at) {
+	const out = structuredClone(scene);
+	const target = resolveJsonPath(out.root, at);
+	target.children = [...target.children ?? [], structuredClone(node)];
+	return out;
+}
+function resolveJsonPath(root, at) {
+	if (at === void 0 || at === "" || at === ".") return root;
+	const segments = (at.startsWith("/") ? at.slice(1) : at).split("/");
+	if (segments[0] !== root.name) throw new IncantoError("NODE_NOT_FOUND", `Scene path '${at}' must start at the root, which is named '${root.name}' (e.g. '${root.name}/Child').`, {
+		path: at,
+		validOptions: [root.name]
+	});
+	let current = root;
+	for (const segment of segments.slice(1)) {
+		const next = (current.children ?? []).find((child) => child.name === segment);
+		if (!next) {
+			const names = (current.children ?? []).map((child) => child.name);
+			throw new IncantoError("NODE_NOT_FOUND", `No node at '${at}': '${current.name}' has no child '${segment}'. Children: [${names.join(", ")}].`, {
+				path: at,
+				validOptions: names
+			});
+		}
+		current = next;
+	}
+	return current;
+}
+//#endregion
+//#region src/env/voxel-terrain.ts
+/** VOXEL_PALETTE tiles (see voxel-grid-3d.ts): grass top, dirt fill, bedrock base. */
+const GRASS$1 = 1;
+const DIRT$1 = 2;
+const BEDROCK$1 = 5;
+/** Lattice spacing for the value noise — bigger = smoother hills. */
+const LATTICE_STEP = 8;
+/**
+* A voxel heightfield for minecraft-style worlds: smooth-ish value noise (a
+* seeded lattice, bilinearly interpolated with a smoothstep fade) baked into
+* a VoxelGrid3D `voxels` prop as [x,y,z,tile] tuples — solid columns of
+* bedrock/dirt/grass centered on the origin. Colliders stay the game's job
+* (chunk trimeshes near the player — see the minecraft template).
+*
+* Library-only by design: the `terrain` catalog generator emits a smooth
+* Terrain3D heightfield instead — reach for THIS when blocks are the point
+* (digging, building, VoxelGrid3D worlds).
+*/
+function generateVoxelTerrain(opts) {
+	const { seed, size = 32, height = 8, water = false } = opts;
+	const noise = makeValueNoise(new Rng(seed), size);
+	const half = Math.floor(size / 2);
+	const voxels = [];
+	for (let x = 0; x < size; x++) for (let z = 0; z < size; z++) {
+		const columnHeight = 1 + Math.round(noise(x, z) * (height - 1));
+		for (let y = 0; y <= columnHeight; y++) {
+			const tile = y === 0 ? BEDROCK$1 : y === columnHeight ? GRASS$1 : DIRT$1;
+			voxels.push([
+				x - half,
+				y,
+				z - half,
+				tile
+			]);
+		}
+	}
+	const children = [{
+		name: "Voxels",
+		type: "VoxelGrid3D",
+		props: { voxels }
+	}];
+	if (water) {
+		const waterLevel = round2(Math.max(1, height * .35) + .4);
+		children.push({
+			name: "Water",
+			type: "Water3D",
+			props: {
+				size: [size, size],
+				position: [
+					0,
+					waterLevel,
+					0
+				]
+			}
+		});
+	}
+	return {
+		name: "VoxelTerrain",
+		type: "Node3D",
+		children
+	};
+}
+/**
+* Value noise over [0,size)² in [0,1] — random lattice + smooth interpolation.
+* Shared with `generateIsland` (which shapes it with a radial falloff).
+*/
+function makeValueNoise(rng, size) {
+	const cells = Math.ceil(size / LATTICE_STEP) + 1;
+	const lattice = [];
+	for (let i = 0; i < cells * cells; i++) lattice.push(rng.next());
+	const at = (ix, iz) => lattice[Math.min(iz, cells - 1) * cells + Math.min(ix, cells - 1)];
+	return (x, z) => {
+		const gx = x / LATTICE_STEP;
+		const gz = z / LATTICE_STEP;
+		const x0 = Math.floor(gx);
+		const z0 = Math.floor(gz);
+		const tx = fade(gx - x0);
+		const tz = fade(gz - z0);
+		return lerp(lerp(at(x0, z0), at(x0 + 1, z0), tx), lerp(at(x0, z0 + 1), at(x0 + 1, z0 + 1), tx), tz);
+	};
+}
+function fade(t) {
+	return t * t * (3 - 2 * t);
+}
+function lerp(a, b, t) {
+	return a + (b - a) * t;
+}
+//#endregion
+//#region src/env/island.ts
+/** VOXEL_PALETTE tiles (see voxel-grid-3d.ts): grass top, dirt fill, bedrock base, sandy shore. */
+const GRASS = 1;
+const DIRT = 2;
+const BEDROCK = 5;
+const SAND = 11;
+/**
+* A voxel island: the terrain value noise shaped by a radial dome falloff —
+* tall grassy center, sandy shore where columns dip to the waterline, bedrock
+* base — with an optional Water3D ring lapping the beach and sun/fill lights.
+* Colliders stay the game's job (chunk trimeshes near the player — see the
+* minecraft template).
+*
+* @deprecated Use `runGenerator('terrain', { seed, theme: 'island' })` — the
+* Terrain3D island (smooth heightfield, splatted beach/cliffs/snow, computed
+* drownable sea level, heightfield collider) replaced this in the catalog.
+* Kept for voxel-world library users.
+*/
+function generateIsland(opts) {
+	const { seed, radius = 16, height = 8, water = true } = opts;
+	const rng = new Rng(seed);
+	const size = radius * 2 + 1;
+	const noise = makeValueNoise(rng, size);
+	const waterLevel = Math.max(1, Math.round(height * .3));
+	const voxels = [];
+	for (let x = -radius; x <= radius; x++) for (let z = -radius; z <= radius; z++) {
+		const distance = Math.hypot(x, z);
+		if (distance > radius) continue;
+		const falloff = 1 - (distance / radius) ** 2;
+		const columnHeight = Math.round(height * falloff * (.55 + .45 * noise(x + radius, z + radius)));
+		for (let y = 0; y <= columnHeight; y++) {
+			const top = columnHeight <= waterLevel + 1 ? SAND : GRASS;
+			const tile = y === 0 ? BEDROCK : y === columnHeight ? top : DIRT;
+			voxels.push([
+				x,
+				y,
+				z,
+				tile
+			]);
+		}
+	}
+	const children = [{
+		name: "Voxels",
+		type: "VoxelGrid3D",
+		props: { voxels }
+	}];
+	if (water) children.push({
+		name: "Water",
+		type: "Water3D",
+		props: {
+			size: [round2(size * 1.6), round2(size * 1.6)],
+			position: [
+				0,
+				round2(waterLevel + .4),
+				0
+			]
+		}
+	});
+	children.push(...skyLights(size));
+	return {
+		name: "Island",
+		type: "Node3D",
+		children
+	};
+}
+//#endregion
+//#region src/env/meadow.ts
+const FOLIAGE_OPTIONS = [
+	"grass",
+	"flowers",
+	"mixed"
+];
+const GROUND_COLOR = "#4d7c3a";
+const FLOWER_COLOR_A = "#c95b8e";
+const FLOWER_COLOR_B = "#e8d36b";
+const ROCK_SIZE = [.3, .9];
+const EDGE_MARGIN = 2;
+/**
+* A grass field (잔디밭): a StaticBody3D ground slab carpeted with an
+* instanced Foliage3D field, plus scattered boulders, primitive trees and
+* sun/fill lighting. 'mixed' lays the full grass field with a smaller flower
+* patch on top.
+*
+* @deprecated Use `runGenerator('terrain', { seed, theme: 'meadow' })` — the
+* rolling Terrain3D meadow (blade carpets, broadleaf groves, rocks, a real
+* heightfield collider) replaced this flat-slab version in the catalog.
+*/
+function generateMeadow(opts) {
+	const { seed, size = 40, foliage = "grass", rocks = 6, trees = 4 } = opts;
+	if (!FOLIAGE_OPTIONS.includes(foliage)) throw new IncantoError("BAD_FORMAT", `generateMeadow foliage must be one of [${FOLIAGE_OPTIONS.join(", ")}], got '${foliage}'.`, { validOptions: FOLIAGE_OPTIONS });
+	const rng = new Rng(seed);
+	const children = [staticBox("Ground", [
+		size,
+		.2,
+		size
+	], [
+		0,
+		-.1,
+		0
+	], {
+		material: {
+			color: GROUND_COLOR,
+			roughness: 1
+		},
+		receiveShadow: true
+	})];
+	const field = round2(size * .92);
+	if (foliage === "grass" || foliage === "mixed") children.push(foliageField("Grass", "grass", [field, field], rng));
+	if (foliage === "flowers" || foliage === "mixed") {
+		const patch = foliage === "mixed" ? round2(size * .4) : field;
+		const offset = foliage === "mixed" ? [
+			round2(rng.range(-size / 6, size / 6)),
+			0,
+			round2(rng.range(-size / 6, size / 6))
+		] : void 0;
+		children.push(foliageField("Flowers", "flowers", [patch, patch], rng, {
+			density: 4,
+			height: .32,
+			colorA: FLOWER_COLOR_A,
+			colorB: FLOWER_COLOR_B,
+			...offset ? { position: offset } : {}
+		}));
+	}
+	const limit = size / 2 - EDGE_MARGIN;
+	for (let i = 1; i <= trees; i++) children.push(tree(i, round2(rng.range(-limit, limit)), round2(rng.range(-limit, limit)), rng));
+	for (let i = 1; i <= rocks; i++) children.push(rock(i, round2(rng.range(-limit, limit)), round2(rng.range(-limit, limit)), rng, ROCK_SIZE));
+	children.push(...skyLights(size));
+	return {
+		name: "Meadow",
+		type: "Node3D",
+		children
+	};
+}
+/** A Foliage3D field with a derived placement seed (deterministic from the rng). */
+function foliageField(name, kind, area, rng, extra = {}) {
+	return {
+		name,
+		type: "Foliage3D",
+		props: {
+			kind,
+			area,
+			seed: rng.int(1, 1e9),
+			...extra
+		}
+	};
+}
+//#endregion
+//#region src/env/rocks.ts
+/**
+* Clustered boulders: a few cluster anchors with rocks scattered tightly
+* around them — squashed, gray-jittered MeshInstance3D spheres (visual props,
+* no colliders; wrap one in a StaticBody3D yourself if it must block).
+*
+* @deprecated The terrain themes scatter their own rocks (alpine snow-band
+* boulders, desert/plains/meadow clusters) — use `runGenerator('terrain',
+* { seed, theme })` for whole worlds. Kept for custom library compositions.
+*/
+function generateRocks(opts) {
+	const { seed, count = 12, sizeRange = [.4, 1.6] } = opts;
+	const [areaX, areaZ] = extent(opts.area, [24, 24]);
+	const rng = new Rng(seed);
+	const clusters = [];
+	const clusterCount = clamp(Math.round(count / 4), 1, 4);
+	for (let i = 0; i < clusterCount; i++) clusters.push([rng.range(-areaX * .3, areaX * .3), rng.range(-areaZ * .3, areaZ * .3)]);
+	const spread = Math.min(areaX, areaZ) / 5;
+	const children = [];
+	for (let i = 1; i <= count; i++) {
+		const [cx, cz] = rng.pick(clusters);
+		const x = round2(clamp(cx + rng.range(-spread, spread), -areaX / 2, areaX / 2));
+		const z = round2(clamp(cz + rng.range(-spread, spread), -areaZ / 2, areaZ / 2));
+		children.push(rock(i, x, z, rng, sizeRange));
+	}
+	return {
+		name: "Rocks",
+		type: "Node3D",
+		children
+	};
+}
+//#endregion
+//#region src/env/scatter.ts
+const SCALE_JITTER = [.8, 1.2];
+/**
+* Scatter N instances of caller-provided node templates over an XZ area:
+* random position, y-rotation, and uniform scale jitter (multiplied onto the
+* template's own scale). The template's `position[1]` survives as the ground
+* offset. Library-only — the items make it too open-ended for CLI flags.
+*/
+function generateScatter(opts) {
+	const { seed, count = 20, area = [20, 20], items } = opts;
+	if (items.length === 0) throw new IncantoError("BAD_FORMAT", "generateScatter needs at least one item template, e.g. {type: 'MeshInstance3D', props: {mesh: 'box'}}.");
+	const rng = new Rng(seed);
+	const totalWeight = items.reduce((sum, item) => sum + (item.weight ?? 1), 0);
+	const children = [];
+	for (let i = 1; i <= count; i++) {
+		const item = pickWeighted(items, rng.next() * totalWeight);
+		const template = structuredClone(item.props ?? {});
+		const x = round2(rng.range(-area[0] / 2, area[0] / 2));
+		const z = round2(rng.range(-area[1] / 2, area[1] / 2));
+		const yaw = rng.int(0, 359);
+		const jitter = round2(rng.range(SCALE_JITTER[0], SCALE_JITTER[1]));
+		const baseScale = Array.isArray(template.scale) ? template.scale : [
+			1,
+			1,
+			1
+		];
+		const y = Array.isArray(template.position) ? template.position[1] ?? 0 : 0;
+		children.push({
+			name: `${item.type}${i}`,
+			type: item.type,
+			props: {
+				...template,
+				position: [
+					x,
+					y,
+					z
+				],
+				rotation: [
+					0,
+					yaw,
+					0
+				],
+				scale: baseScale.map((s) => round2((typeof s === "number" ? s : 1) * jitter))
+			}
+		});
+	}
+	return {
+		name: "Scatter",
+		type: "Node3D",
+		children
+	};
+}
+function pickWeighted(items, roll) {
+	let cursor = roll;
+	for (const item of items) {
+		cursor -= item.weight ?? 1;
+		if (cursor < 0) return item;
+	}
+	return items[items.length - 1];
+}
+//#endregion
+export { ARENA_THEMES, GENERATORS, MAZE_THEMES, TERRAIN_GENERATOR_THEMES, carveMaze, generateArena, generateClouds, generateDungeon2D, generateForest, generateIsland, generateMaze, generateMaze2D, generateMeadow, generatePlatforms2D, generateRocks, generateScatter, generateTerrain, generateVoxelTerrain, insertIntoScene, makeValueNoise, mazeEnvironment, runGenerator, terrainEnvironment };