@jgengine/shell 0.18.1 → 0.21.0

package/dist/shellControlSuspension.js

@@ -0,0 +1,28 @@
+import { actionContextStack, playControlsActive } from "@jgengine/core/game/controlGate";
+/** Clears held input synchronously on play-gate transitions; ordinary context swaps retain it. @internal */
+export function attachShellControlSuspension({ ctx, tracker, pointerAxisRef, analogRef, primaryClickRef, cameraDraggingRef, f2HeldRef, }) {
+    const reset = () => {
+        tracker.reset();
+        pointerAxisRef.current = null;
+        analogRef.current = null;
+        primaryClickRef.current = false;
+        cameraDraggingRef.current = false;
+        f2HeldRef.current = false;
+        ctx.input.publish([]);
+        ctx.input.publishPointer(null);
+        ctx.input.publishAnalog(null);
+    };
+    let active = playControlsActive(ctx);
+    if (!active)
+        reset();
+    const changed = () => {
+        const next = playControlsActive(ctx);
+        if (next === active)
+            return;
+        active = next;
+        reset();
+    };
+    const detachStack = actionContextStack(ctx).subscribe(changed);
+    const detachContext = ctx.subscribe(changed);
+    return () => { detachStack(); detachContext(); };
+}

package/dist/shellInputPublication.d.ts

@@ -0,0 +1,28 @@
+import type { ActionStateTracker } from "@jgengine/core/input/actionBindings";
+import type { GameContext } from "@jgengine/core/runtime/gameContext";
+import type { InputFrame } from "@jgengine/core/runtime/hostedGameRunner";
+import type { InputSink } from "./inputSink.js";
+type Change = "discrete" | "reset" | "analog";
+/** Observes the actual shell tracker without moving command edges or changing binding behavior. @internal */
+export declare function observableShellTracker(tracker: ActionStateTracker<string>): {
+    isDown(action: string): boolean;
+    wasPressed(action: string): boolean;
+    endFrame(): void;
+    rebind(map: import("@jgengine/core/input/actionBindings").ActionStateBindingMap<string, string>): void;
+    actions(): readonly string[];
+    handleDown(code: string): string | null;
+    handleUp(code: string): string | null;
+    reset(): void;
+    notify: (change: Change, presses?: NonNullable<InputFrame["presses"]>) => void;
+    subscribe(listener: (change: Change, presses: NonNullable<InputFrame["presses"]>) => void): () => void;
+};
+/** Publishes discrete input above Canvas, so release and failure leases survive stalled or unmounted rendering. @internal */
+export declare function attachShellInputPublication({ ctx, tracker, active, analog, pointer, sink }: {
+    ctx: GameContext;
+    tracker: ReturnType<typeof observableShellTracker>;
+    active: () => boolean;
+    analog: () => InputFrame["analog"];
+    pointer: () => InputFrame["pointer"];
+    sink: () => InputSink;
+}): () => void;
+export {};

package/dist/shellInputPublication.js

@@ -0,0 +1,49 @@
+import { heldActionsFor } from "./boundActionDispatch.js";
+let lastPressSeq = 0;
+/** Observes the actual shell tracker without moving command edges or changing binding behavior. @internal */
+export function observableShellTracker(tracker) {
+    const listeners = new Set();
+    const notify = (change, presses = []) => { for (const listener of listeners)
+        listener(change, presses); };
+    return {
+        ...tracker,
+        handleDown(code) {
+            const result = tracker.handleDown(code);
+            if (result !== null) {
+                const now = typeof performance !== "undefined" ? performance.timeOrigin + performance.now() : Date.now();
+                lastPressSeq = Math.max(now, lastPressSeq + 0.001);
+                notify("discrete", [{ action: result, seq: lastPressSeq }]);
+            }
+            return result;
+        },
+        handleUp(code) { const result = tracker.handleUp(code); notify("discrete"); return result; },
+        reset() { tracker.reset(); notify("reset"); },
+        notify,
+        subscribe(listener) { listeners.add(listener); return () => { listeners.delete(listener); }; },
+    };
+}
+const owners = new WeakMap();
+/** Publishes discrete input above Canvas, so release and failure leases survive stalled or unmounted rendering. @internal */
+export function attachShellInputPublication({ ctx, tracker, active, analog, pointer, sink }) {
+    const owner = {};
+    owners.set(ctx, owner);
+    const publish = (change, presses = []) => {
+        if (owners.get(ctx) !== owner)
+            return;
+        const enabled = active() && change !== "reset";
+        const axes = enabled ? analog() : null;
+        ctx.input.publish(enabled ? heldActionsFor(tracker, tracker.actions()) : [], enabled ? { pressed: presses.map(press => press.action) } : { reset: true });
+        ctx.input.publishPointer(enabled ? pointer() : null);
+        ctx.input.publishAnalog(axes ?? null);
+        const urgent = change !== "analog" || axes == null || Object.values(axes).every(value => value === 0);
+        sink().send({ held: ctx.input.held(), pointer: ctx.input.pointer(), analog: ctx.input.analog(), tick: ctx.sim.tick(), ...(enabled && presses.length > 0 ? { presses } : {}) }, { urgent, ...(!enabled ? { reset: true } : {}) });
+    };
+    const detach = tracker.subscribe(publish);
+    return () => {
+        detach();
+        if (owners.get(ctx) !== owner)
+            return;
+        publish("reset");
+        owners.delete(ctx);
+    };
+}

package/dist/shellPointerInput.d.ts

@@ -0,0 +1,18 @@
+import type { ActionStateTracker } from "@jgengine/core/input/actionBindings";
+import type { observableShellTracker } from "./shellInputPublication.js";
+type Pointer = {
+    pointerId: number;
+    button: number;
+};
+/** Canvas-owned physical buttons; DOM overlays never begin gameplay input. @internal */
+export declare function shellPointerInput(tracker: Pick<ActionStateTracker<string>, "handleDown" | "handleUp">, active: () => boolean): {
+    down(event: Pointer, worldTarget: boolean): void;
+    up(event: Pointer): boolean;
+    /** Native mouse chords change buttons through pointermove, including releases outside the canvas. */
+    move(event: Pointer & {
+        buttons: number;
+    }, worldTarget: boolean): void;
+    cancel(pointerId?: number): void;
+    attachReset(source: Pick<ReturnType<typeof observableShellTracker>, "subscribe">, clearGesture: () => void): () => void;
+};
+export {};

package/dist/shellPointerInput.js

@@ -0,0 +1,49 @@
+// PointerEvent.buttons uses middle=4 and right=2, unlike PointerEvent.button.
+const buttonMask = (button) => [1, 4, 2, 8, 16][button] ?? 0;
+/** Canvas-owned physical buttons; DOM overlays never begin gameplay input. @internal */
+export function shellPointerInput(tracker, active) {
+    const buttons = new Map();
+    const input = {
+        down(event, worldTarget) {
+            if (!worldTarget || !active() || buttons.has(event.button))
+                return;
+            const action = tracker.handleDown(`mouse${event.button}`);
+            buttons.set(event.button, { pointerId: event.pointerId, bound: action !== null });
+        },
+        up(event) {
+            const held = buttons.get(event.button);
+            if (held === undefined || held.pointerId !== event.pointerId)
+                return false;
+            buttons.delete(event.button);
+            tracker.handleUp(`mouse${event.button}`);
+            return held.bound;
+        },
+        /** Native mouse chords change buttons through pointermove, including releases outside the canvas. */
+        move(event, worldTarget) {
+            for (const [button, held] of buttons) {
+                if (held.pointerId === event.pointerId && (event.buttons & buttonMask(button)) === 0) {
+                    input.up({ pointerId: event.pointerId, button });
+                }
+            }
+            if (event.button >= 0 && (event.buttons & buttonMask(event.button)) !== 0)
+                input.down(event, worldTarget);
+        },
+        cancel(pointerId) {
+            for (const [button, held] of buttons) {
+                if (pointerId !== undefined && held.pointerId !== pointerId)
+                    continue;
+                buttons.delete(button);
+                tracker.handleUp(`mouse${button}`);
+            }
+        },
+        attachReset(source, clearGesture) {
+            return source.subscribe(change => {
+                if (change !== "reset")
+                    return;
+                input.cancel();
+                clearGesture();
+            });
+        },
+    };
+    return input;
+}

package/dist/structures/BuildingKitBatch.d.ts

@@ -1,8 +1,10 @@
+import type { MaterialAsset } from "@jgengine/core/material/materialAsset";
 import { type BuildingKitInstance } from "./buildingKitFit.js";
 /** Props for {@link BuildingKitBatch}: one resolved model URL and every kit instance bound to it. @internal */
 export interface BuildingKitBatchProps {
     url: string;
     instances: readonly BuildingKitInstance[];
+    materialAssets?: readonly MaterialAsset[];
 }
 /**
  * GPU-instances one kit model across every building part bound to it: the GLB loads once, its meshes
@@ -10,4 +12,4 @@ export interface BuildingKitBatchProps {
  * while the GLB loads — mount it inside a `<Suspense>` so one slow model never blanks the rest.
  * @internal
  */
-export declare function BuildingKitBatch({ url, instances }: BuildingKitBatchProps): import("react").JSX.Element;
+export declare function BuildingKitBatch({ url, instances, materialAssets }: BuildingKitBatchProps): import("react").JSX.Element;

package/dist/structures/BuildingKitBatch.js

@@ -1,44 +1,29 @@
 import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
-import { useEffect, useMemo, useRef } from "react";
+import { useEffect, useLayoutEffect, useMemo, useRef } from "react";
 import { useLoader } from "@react-three/fiber";
 import * as THREE from "three";
+import { useModelMaterialTextures } from "../render/materialAsset.js";
 import { sharedGltfLoader } from "../render/modelLoad.js";
 import { buildScatterModelSources, disposeScatterModelSources, } from "../scatter/scatterModels.js";
-import { composeBuildingKitMatrix, measureBuildingKitModel, } from "./buildingKitFit.js";
+import { measureBuildingKitModel, } from "./buildingKitFit.js";
+import { useBuildingSurfaceTextures } from "./buildingSurface.js";
+import { groupBuildingKitInstances, buildBuildingKitSources, validateBuildingKitSource } from "./buildingKitMaterials.js";
+import { useBuildingChunkBudget } from "./BuildingRenderBudget.js";
+import { applyBuildingChunk, partitionBuildingMatrices } from "./buildingSpatialBatch.js";
 function KitSourceInstances({ source, material, matrices, }) {
+    const chunks = useMemo(() => partitionBuildingMatrices(source.geometry, matrices, source.localMatrix), [source, matrices]);
+    return _jsx(_Fragment, { children: chunks.map((chunk) => _jsx(KitSourceChunk, { source: source, material: material, chunk: chunk }, chunk.key)) });
+}
+function KitSourceChunk({ source, material, chunk }) {
     const meshRef = useRef(null);
-    useEffect(() => {
+    useBuildingChunkBudget(meshRef, chunk.bounds);
+    useLayoutEffect(() => {
         const mesh = meshRef.current;
         if (mesh === null)
             return;
-        const composed = new THREE.Matrix4();
-        for (let i = 0; i < matrices.length; i += 1) {
-            composed.multiplyMatrices(matrices[i], source.localMatrix);
-            mesh.setMatrixAt(i, composed);
-        }
-        mesh.count = matrices.length;
-        mesh.instanceMatrix.needsUpdate = true;
-        mesh.computeBoundingSphere();
-    }, [matrices, source]);
-    return (_jsx("instancedMesh", { ref: meshRef, args: [source.geometry, material, matrices.length], castShadow: true, receiveShadow: true }, matrices.length));
-}
-function tintOne(material, color) {
-    const clone = material.clone();
-    const tintable = clone;
-    if (tintable.color !== undefined)
-        tintable.color.copy(color);
-    return clone;
-}
-function tintMaterial(material, tint) {
-    const color = new THREE.Color(tint);
-    return Array.isArray(material) ? material.map((entry) => tintOne(entry, color)) : tintOne(material, color);
-}
-function disposeMaterial(material) {
-    if (Array.isArray(material))
-        for (const entry of material)
-            entry.dispose();
-    else
-        material.dispose();
+        return applyBuildingChunk(mesh, chunk);
+    }, [chunk, source, material]);
+    return (_jsx("instancedMesh", { ref: meshRef, args: [source.geometry, material, chunk.matrices.length], castShadow: true, receiveShadow: true, dispose: null }, chunk.matrices.length));
 }
 /**
  * GPU-instances one kit model across every building part bound to it: the GLB loads once, its meshes
@@ -46,33 +31,27 @@ function disposeMaterial(material) {
  * while the GLB loads — mount it inside a `<Suspense>` so one slow model never blanks the rest.
  * @internal
  */
-export function BuildingKitBatch({ url, instances }) {
+export function BuildingKitBatch({ url, instances, materialAssets }) {
     const gltf = useLoader(sharedGltfLoader, url);
+    useMemo(() => {
+        const checked = new Set();
+        for (const instance of instances)
+            if (!checked.has(instance.part)) {
+                validateBuildingKitSource(gltf.scene, instance.part, materialAssets);
+                checked.add(instance.part);
+            }
+    }, [gltf, instances, materialAssets]);
     const { sources, root } = useMemo(() => buildScatterModelSources(gltf.scene, { url }), [gltf, url]);
     useEffect(() => () => disposeScatterModelSources(root), [root]);
     const bounds = useMemo(() => measureBuildingKitModel(root), [root]);
-    const groups = useMemo(() => {
-        const byTint = new Map();
-        for (const instance of instances) {
-            const matrix = composeBuildingKitMatrix(instance, bounds, new THREE.Matrix4());
-            const tint = instance.part.tint ?? "";
-            const bucket = byTint.get(tint);
-            if (bucket === undefined)
-                byTint.set(tint, [matrix]);
-            else
-                bucket.push(matrix);
-        }
-        return [...byTint.entries()];
-    }, [instances, bounds]);
-    const tinted = useMemo(() => {
-        const map = new Map();
-        for (const [tint] of groups) {
-            if (tint === "")
-                continue;
-            map.set(tint, sources.map((source) => tintMaterial(source.material, tint)));
-        }
-        return map;
-    }, [groups, sources]);
-    useEffect(() => () => tinted.forEach((list) => list.forEach(disposeMaterial)), [tinted]);
-    return (_jsx(_Fragment, { children: groups.map(([tint, matrices]) => sources.map((source, index) => (_jsx(KitSourceInstances, { source: source, material: tinted.get(tint)?.[index] ?? source.material, matrices: matrices }, `${tint}:${index}`)))) }));
+    const groups = useMemo(() => groupBuildingKitInstances(instances, bounds, materialAssets), [instances, bounds, materialAssets]);
+    return (_jsx(_Fragment, { children: groups.map((group) => (group.part.tint ?? "") === "" && group.part.material === undefined && !group.part.materialAssignments?.length ? (sources.map((source, index) => (_jsx(KitSourceInstances, { source: source, material: source.material, matrices: group.matrices }, `${group.key}:${index}`)))) : (_jsx(StyledKitSources, { scene: gltf.scene, materialAssets: materialAssets, group: group }, group.key))) }));
+}
+function StyledKitSources({ scene, materialAssets, group }) {
+    useMemo(() => validateBuildingKitSource(scene, group.part, materialAssets), [scene, group.key]);
+    const textures = useBuildingSurfaceTextures(group.part.material);
+    const materialTextures = useModelMaterialTextures({ materialAssets, materialAssignments: group.part.materialAssignments });
+    const { sources, root } = useMemo(() => buildBuildingKitSources(scene, group.part, materialAssets, textures, materialTextures.assets), [scene, group.key, textures, materialTextures]);
+    useEffect(() => () => disposeScatterModelSources(root), [root]);
+    return (_jsx(_Fragment, { children: sources.map((source, index) => (_jsx(KitSourceInstances, { source: source, material: source.material, matrices: group.matrices }, index))) }));
 }

package/dist/structures/BuildingRenderBudget.d.ts

@@ -0,0 +1,23 @@
+import { type ReactNode, type RefObject } from "react";
+import * as THREE from "three";
+import type { VisibilityConfig } from "@jgengine/core/visibility/config";
+/** Resolved shell distance policy for generated facade batches. @internal */
+export interface BuildingRenderPolicy {
+    enabled: boolean;
+    minDistance: number;
+    maxDistance: number;
+    hysteresis: number;
+}
+/** Resolve existing visibility overrides over the already resolved graphics-tier distance. @internal */
+export declare function resolveBuildingRenderPolicy(drawDistance: number, config?: VisibilityConfig, cullingDisabled?: boolean): BuildingRenderPolicy;
+/** Forward the shell's resolved graphics distance without registering generated parts as scene objects. @internal */
+export declare function BuildingRenderBudget({ drawDistance, visibility, cullingDisabled, children }: {
+    drawDistance: number;
+    visibility?: VisibilityConfig;
+    cullingDisabled?: boolean;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** Test world bounds; transforming the box first also conservatively encloses affine shear. @internal */
+export declare function buildingChunkWithinBudget(bounds: THREE.Box3, matrixWorld: THREE.Matrix4, cameraPosition: THREE.Vector3, policy: BuildingRenderPolicy, previouslyVisible: boolean, worldBounds: THREE.Box3, worldSphere: THREE.Sphere, frustumSphere?: THREE.Sphere | null): boolean;
+/** Distance-gate chunks only; Three retains independent main-camera and shadow-camera frustum tests. @internal */
+export declare function useBuildingChunkBudget(meshRef: RefObject<THREE.InstancedMesh | null>, bounds: THREE.Box3): void;

package/dist/structures/BuildingRenderBudget.js

@@ -0,0 +1,54 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useMemo, useRef } from "react";
+import { useFrame } from "@react-three/fiber";
+import * as THREE from "three";
+import { culledByDistance } from "@jgengine/core/visibility/distance";
+import { DEFAULT_CULLING_SETTINGS } from "@jgengine/core/visibility/settings";
+import { CAMERA_POST_FRAME_PRIORITY } from "../camera/cameraRigs.js";
+const UNLIMITED = { enabled: false, minDistance: 0, maxDistance: Infinity, hysteresis: 0 };
+const BuildingRenderContext = createContext(UNLIMITED);
+/** Resolve existing visibility overrides over the already resolved graphics-tier distance. @internal */
+export function resolveBuildingRenderPolicy(drawDistance, config, cullingDisabled = false) {
+    const culling = config?.culling;
+    const scene = config?.scene;
+    return {
+        // Scene callbacks address visibility rows; generated parts have no row to evaluate safely.
+        enabled: !cullingDisabled && config?.enabled !== false && culling?.enabled !== false && culling?.distanceCulling !== false
+            && scene?.alwaysVisible !== true && scene?.cullingDisabled !== true && scene?.customVisibility === undefined,
+        minDistance: scene?.minRenderDistance ?? culling?.defaultMinRenderDistance ?? DEFAULT_CULLING_SETTINGS.defaultMinRenderDistance,
+        maxDistance: scene?.maxRenderDistance ?? culling?.defaultMaxRenderDistance ?? drawDistance,
+        hysteresis: culling?.hysteresis ?? DEFAULT_CULLING_SETTINGS.hysteresis,
+    };
+}
+/** Forward the shell's resolved graphics distance without registering generated parts as scene objects. @internal */
+export function BuildingRenderBudget({ drawDistance, visibility, cullingDisabled = false, children }) {
+    const policy = useMemo(() => resolveBuildingRenderPolicy(drawDistance, visibility, cullingDisabled), [drawDistance, visibility, cullingDisabled]);
+    return _jsx(BuildingRenderContext.Provider, { value: policy, children: children });
+}
+/** Test world bounds; transforming the box first also conservatively encloses affine shear. @internal */
+export function buildingChunkWithinBudget(bounds, matrixWorld, cameraPosition, policy, previouslyVisible, worldBounds, worldSphere, frustumSphere) {
+    worldBounds.copy(bounds).applyMatrix4(matrixWorld).getBoundingSphere(worldSphere);
+    if (frustumSphere !== undefined && frustumSphere !== null) {
+        bounds.getCenter(frustumSphere.center);
+        const worldScale = matrixWorld.getMaxScaleOnAxis();
+        // Three transforms this sphere using the largest matrix column, which can underbound shear.
+        frustumSphere.radius = Math.max(bounds.min.distanceTo(bounds.max) / 2, worldScale === 0 ? 0 : worldSphere.radius / worldScale);
+    }
+    if (!policy.enabled)
+        return true;
+    const { center, radius } = worldSphere;
+    return !culledByDistance(cameraPosition.x, cameraPosition.y, cameraPosition.z, center.x, center.y, center.z, policy.minDistance, policy.maxDistance, radius, previouslyVisible ? policy.hysteresis : 0);
+}
+/** Distance-gate chunks only; Three retains independent main-camera and shadow-camera frustum tests. @internal */
+export function useBuildingChunkBudget(meshRef, bounds) {
+    const policy = useContext(BuildingRenderContext);
+    const scratch = useRef({ box: new THREE.Box3(), sphere: new THREE.Sphere(), camera: new THREE.Vector3() });
+    useFrame(({ camera }) => {
+        const mesh = meshRef.current;
+        if (mesh === null)
+            return;
+        mesh.updateWorldMatrix(true, false);
+        camera.getWorldPosition(scratch.current.camera);
+        mesh.visible = buildingChunkWithinBudget(bounds, mesh.matrixWorld, scratch.current.camera, policy, mesh.visible, scratch.current.box, scratch.current.sphere, mesh.boundingSphere);
+    }, CAMERA_POST_FRAME_PRIORITY);
+}

package/dist/structures/GeneratedBuilding.d.ts

@@ -1,5 +1,5 @@
 import { type ReactNode } from "react";
-import type { BuildingKitSlot } from "@jgengine/core/world/buildings";
+import { type BuildingKitSlot, type BuildingSurface } from "@jgengine/core/world/buildings";
 import type { BuildingKit } from "@jgengine/core/world/buildingKit";
 export type BuildingFacade = "front" | "back" | "left" | "right" | "roof";
 export type BuildingPartKind = "wall" | "window" | "awning" | "airConditioner" | "clothesline" | "storefront" | "shutter" | "storeSign" | "roof" | "roofProp" | "guardrail" | "corner";
@@ -17,20 +17,8 @@ export interface GeneratedBuildingData {
     id: string;
     parts: readonly BuildingPartPlacement[];
 }
-export interface BuildingMaterialPalette {
-    wall?: string;
-    window?: string;
-    awning?: string;
-    airConditioner?: string;
-    clothesline?: string;
-    storefront?: string;
-    shutter?: string;
-    storeSign?: string;
-    roof?: string;
-    roofProp?: string;
-    guardrail?: string;
-    corner?: string;
-}
+/** Per part kind: a hex colour, or a colour plus tiled PBR maps (`BuildingSurfaceMaterial`). */
+export type BuildingMaterialPalette = Partial<Record<BuildingPartKind, BuildingSurface>>;
 export interface BuildingKitRenderer {
     renderPart?: (part: BuildingPartPlacement) => ReactNode | undefined;
 }

package/dist/structures/GeneratedBuilding.js

@@ -1,9 +1,13 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Suspense, useLayoutEffect, useMemo, useRef } from "react";
 import * as THREE from "three";
+import { buildingSurfaceColor, resolveBuildingSurface, } from "@jgengine/core/world/buildings";
 import { useDisposable } from "../render/useDisposable.js";
 import { BuildingKitBatch } from "./BuildingKitBatch.js";
+import { useBuildingChunkBudget } from "./BuildingRenderBudget.js";
+import { applyBuildingChunk, partitionBuildingMatrices } from "./buildingSpatialBatch.js";
 import { bucketBuildingParts, normalFor, outwardOffset } from "./buildingKitFit.js";
+import { applyBuildingSurface, useBuildingSurfaceTextures } from "./buildingSurface.js";
 const DEFAULT_PALETTE = {
     wall: "#83766a",
     window: "#8ecae6",
@@ -18,8 +22,12 @@ const DEFAULT_PALETTE = {
     guardrail: "#a8a29e",
     corner: "#6b6258",
 };
+function surfaceFor(kind, palette) {
+    const surface = resolveBuildingSurface(palette?.[kind] ?? DEFAULT_PALETTE[kind]);
+    return surface.color === undefined ? { ...surface, color: DEFAULT_PALETTE[kind] } : surface;
+}
 function colorFor(kind, palette) {
-    return palette?.[kind] ?? DEFAULT_PALETTE[kind];
+    return buildingSurfaceColor(palette?.[kind], DEFAULT_PALETTE[kind]);
 }
 function materialFor(part, palette) {
     const color = colorFor(part.kind, palette);
@@ -34,31 +42,34 @@ function materialFor(part, palette) {
     }
     return _jsx("meshStandardMaterial", { color: color, roughness: 0.88, metalness: 0 });
 }
-function batchMaterialFor(kind, palette) {
-    const color = colorFor(kind, palette);
-    if (kind === "window" || kind === "storefront") {
-        return new THREE.MeshPhysicalMaterial({ color, roughness: 0.12, metalness: 0, transparent: true, opacity: 0.56 });
-    }
-    if (kind === "storeSign") {
-        return new THREE.MeshStandardMaterial({ color, emissive: color, emissiveIntensity: 0.6, roughness: 0.5 });
-    }
-    if (kind === "roofProp") {
-        return new THREE.MeshStandardMaterial({ color, roughness: 0.65, metalness: 0.1 });
-    }
-    return new THREE.MeshStandardMaterial({ color, roughness: 0.88, metalness: 0 });
+function batchMaterialFor(kind, surface, textures) {
+    const color = surface.color ?? DEFAULT_PALETTE[kind];
+    const base = kind === "window" || kind === "storefront"
+        ? new THREE.MeshPhysicalMaterial({ color, roughness: 0.12, metalness: 0, transparent: true, opacity: 0.56 })
+        : kind === "storeSign"
+            ? new THREE.MeshStandardMaterial({ color, emissive: color, emissiveIntensity: 0.6, roughness: 0.5 })
+            : kind === "roofProp"
+                ? new THREE.MeshStandardMaterial({ color, roughness: 0.65, metalness: 0.1 })
+                : new THREE.MeshStandardMaterial({ color, roughness: 0.88, metalness: 0 });
+    return applyBuildingSurface(base, surface, textures);
+}
+function BuildingKindBatch({ kind, matrices, palette, geometry }) {
+    const surface = useMemo(() => surfaceFor(kind, palette), [kind, palette]);
+    const textures = useBuildingSurfaceTextures(surface);
+    const material = useDisposable(() => batchMaterialFor(kind, surface, textures), [kind, surface, textures]);
+    const chunks = useMemo(() => partitionBuildingMatrices(geometry, matrices), [geometry, matrices]);
+    return _jsx(_Fragment, { children: chunks.map((chunk) => _jsx(BuildingChunk, { chunk: chunk, material: material, geometry: geometry }, chunk.key)) });
 }
-function BuildingKindBatch({ kind, matrices, palette, geometry, }) {
+function BuildingChunk({ chunk, material, geometry }) {
     const meshRef = useRef(null);
-    const material = useDisposable(() => batchMaterialFor(kind, palette), [kind, palette]);
+    useBuildingChunkBudget(meshRef, chunk.bounds);
     useLayoutEffect(() => {
         const mesh = meshRef.current;
         if (mesh === null)
             return;
-        matrices.forEach((matrix, index) => mesh.setMatrixAt(index, matrix));
-        mesh.instanceMatrix.needsUpdate = true;
-        mesh.computeBoundingSphere();
-    }, [matrices, material]);
-    return (_jsx("instancedMesh", { ref: meshRef, args: [geometry, material, matrices.length], castShadow: true, receiveShadow: true }, matrices.length));
+        return applyBuildingChunk(mesh, chunk);
+    }, [chunk, geometry, material]);
+    return (_jsx("instancedMesh", { ref: meshRef, args: [geometry, material, chunk.matrices.length], castShadow: true, receiveShadow: true, dispose: null }, chunk.matrices.length));
 }
 export function InstancedBuildings({ buildings, palette, kit, resolveModelUrl, visibleKinds, }) {
     const geometry = useDisposable(() => new THREE.BoxGeometry(1, 1, 1), []);
@@ -68,7 +79,7 @@ export function InstancedBuildings({ buildings, palette, kit, resolveModelUrl, v
     }, [buildings, visibleKinds, kit, resolveModelUrl]);
     if (boxes.size === 0 && models.size === 0)
         return null;
-    return (_jsxs("group", { children: [[...boxes.entries()].map(([kind, matrices]) => (_jsx(BuildingKindBatch, { kind: kind, matrices: matrices, palette: palette, geometry: geometry }, kind))), [...models.entries()].map(([url, instances]) => (_jsx(Suspense, { fallback: null, children: _jsx(BuildingKitBatch, { url: url, instances: instances }) }, url)))] }));
+    return (_jsxs("group", { children: [[...boxes.entries()].map(([kind, matrices]) => (_jsx(BuildingKindBatch, { kind: kind, matrices: matrices, palette: palette, geometry: geometry }, kind))), [...models.entries()].map(([url, instances]) => (_jsx(Suspense, { fallback: null, children: _jsx(BuildingKitBatch, { url: url, instances: instances, materialAssets: kit?.materialAssets }) }, url)))] }));
 }
 function BlockMesh({ part, palette }) {
     const [nx, nz] = normalFor(part.facade);

package/dist/structures/buildingKitMaterials.d.ts

@@ -0,0 +1,20 @@
+import * as THREE from "three";
+import type { BuildingKitPart } from "@jgengine/core/world/buildingKit";
+import { type MaterialAsset } from "@jgengine/core/material/materialAsset";
+import type { MaterialOverrideTextures } from "../materialOverride.js";
+import { buildScatterModelSources } from "../scatter/scatterModels.js";
+import { type BuildingKitInstance, type BuildingKitModelBounds } from "./buildingKitFit.js";
+/** The material values used by one kit variant, excluding unrelated document library entries. @internal */
+export declare function buildingKitMaterialKey(part: BuildingKitPart, assets?: readonly MaterialAsset[]): string;
+/** One material style shared by every fitted instance using it. @internal */
+export interface BuildingKitStyleGroup {
+    key: string;
+    part: BuildingKitPart;
+    matrices: THREE.Matrix4[];
+}
+/** Group fitted instances while resolving each repeated variant's material identity only once. @internal */
+export declare function groupBuildingKitInstances(instances: readonly BuildingKitInstance[], bounds: BuildingKitModelBounds, assets?: readonly MaterialAsset[]): BuildingKitStyleGroup[];
+/** Validate named kit materials and native targets before any owned model or texture allocation. @internal */
+export declare function validateBuildingKitSource(scene: THREE.Object3D, part: BuildingKitPart, assets?: readonly MaterialAsset[]): void;
+/** Prepare one style's owned model materials before harvesting shared geometry for bounded instanced chunks. @internal */
+export declare function buildBuildingKitSources(scene: THREE.Object3D, part: BuildingKitPart, assets?: readonly MaterialAsset[], surfaceTextures?: MaterialOverrideTextures, assetTextures?: ReadonlyMap<string, MaterialOverrideTextures>): ReturnType<typeof buildScatterModelSources>;

package/dist/structures/buildingKitMaterials.js

@@ -0,0 +1,70 @@
+import * as THREE from "three";
+import { validateMaterialAssignments } from "@jgengine/core/material/materialAsset";
+import { applyMaterialAssignments, validateMaterialAssignmentTargets } from "../render/materialAsset.js";
+import { buildScatterModelSources, disposeScatterModelSources } from "../scatter/scatterModels.js";
+import { composeBuildingKitMatrix } from "./buildingKitFit.js";
+import { applyBuildingSurface, surfaceKey } from "./buildingSurface.js";
+/** The material values used by one kit variant, excluding unrelated document library entries. @internal */
+export function buildingKitMaterialKey(part, assets = []) {
+    const ids = new Set(part.materialAssignments?.map(assignment => assignment.materialId));
+    return JSON.stringify([part.tint ?? "", surfaceKey(part.material), part.materialAssignments ?? [], assets.filter(asset => ids.has(asset.id))]);
+}
+/** Group fitted instances while resolving each repeated variant's material identity only once. @internal */
+export function groupBuildingKitInstances(instances, bounds, assets = []) {
+    const byKey = new Map();
+    const styleKeys = new Map();
+    for (const instance of instances) {
+        const matrix = composeBuildingKitMatrix(instance, bounds, new THREE.Matrix4());
+        let key = styleKeys.get(instance.part);
+        if (key === undefined) {
+            key = buildingKitMaterialKey(instance.part, assets);
+            styleKeys.set(instance.part, key);
+        }
+        const bucket = byKey.get(key);
+        if (bucket === undefined)
+            byKey.set(key, { key, part: instance.part, matrices: [matrix] });
+        else
+            bucket.matrices.push(matrix);
+    }
+    return [...byKey.values()];
+}
+/** Validate named kit materials and native targets before any owned model or texture allocation. @internal */
+export function validateBuildingKitSource(scene, part, assets = []) {
+    const assignments = part.materialAssignments ?? [];
+    const errors = validateMaterialAssignments(assignments, assets, { disallowedTextureRoles: ["height"] }).filter(item => item.severity === "error");
+    if (errors.length > 0)
+        throw new Error(`Building kit ${part.model}: ${errors.map(item => `${item.path}: ${item.message}`).join("; ")}`);
+    validateMaterialAssignmentTargets(scene, assets, assignments);
+}
+/** Prepare one style's owned model materials before harvesting shared geometry for bounded instanced chunks. @internal */
+export function buildBuildingKitSources(scene, part, assets = [], surfaceTextures, assetTextures = new Map()) {
+    validateBuildingKitSource(scene, part, assets);
+    const prepared = buildScatterModelSources(scene, { url: part.model });
+    try {
+        const tint = part.tint === undefined || part.tint === "" ? undefined : new THREE.Color(part.tint);
+        prepared.root.traverseVisible(node => {
+            const mesh = node;
+            if (!mesh.isMesh)
+                return;
+            for (const material of Array.isArray(mesh.material) ? mesh.material : [mesh.material]) {
+                if (tint !== undefined && "color" in material)
+                    material.color.copy(tint);
+                if (part.material !== undefined && material.isMeshStandardMaterial)
+                    applyBuildingSurface(material, part.material, surfaceTextures);
+            }
+        });
+        if (part.materialAssignments?.length)
+            applyMaterialAssignments(prepared.root, assets, part.materialAssignments, assetTextures);
+        let index = 0;
+        prepared.root.traverseVisible(node => {
+            const mesh = node;
+            if (mesh.isMesh)
+                prepared.sources[index++].material = mesh.material;
+        });
+        return prepared;
+    }
+    catch (error) {
+        disposeScatterModelSources(prepared.root);
+        throw error;
+    }
+}

package/dist/structures/buildingSpatialBatch.d.ts

@@ -0,0 +1,11 @@
+import * as THREE from "three";
+/** A spatially bounded group of final, geometry-local instance matrices. @internal */
+export interface BuildingSpatialChunk {
+    key: string;
+    matrices: THREE.Matrix4[];
+    bounds: THREE.Box3;
+}
+/** Partition final geometry bounds without changing instance transforms or material groups. @internal */
+export declare function partitionBuildingMatrices(geometry: THREE.BufferGeometry, matrices: readonly THREE.Matrix4[], sourceMatrix?: THREE.Matrix4, cellSize?: number): BuildingSpatialChunk[];
+/** Install matrices and bounds; cleanup releases only the mesh's instance buffers, retaining shared assets. @internal */
+export declare function applyBuildingChunk(mesh: THREE.InstancedMesh, chunk: BuildingSpatialChunk): () => void;