@jgengine/shell 0.15.0 → 0.16.0

package/CHANGELOG.md

@@ -34,6 +34,38 @@ At publish, rename this heading to the new version and mirror the entries into
 
 ### Fixed
 
+## 0.16.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.16.0`:** `@jgengine/{core,react,ws,node,sql,convex,shell,editor,assets}`. CLI `jgengine` is `0.13.0`; `@jgengine/github` is `0.3.0`.
+- **Placed objects now replicate.** `objects` joined the always-on baseline snapshot modules, so `ctx.hydrate` replaces the client's placed object set with the host's, the way `entities` already did. A game whose peers all run the same authored placement is unaffected; a game that places props on the client only, after hydrate, must move that placement to the host or keep it out of `ctx.scene.object`.
+
+### Changed
+
+- **`GeneratedBuilding`'s `kit` prop is now the `BuildingKit`**; the per-part React escape hatch it used to name moved to `partRenderer`, so `kit` means the same thing on `GeneratedBuilding` and `InstancedBuildings`. Rename the prop if you passed a `BuildingKitRenderer`.
+
+### Added
+
+- **`modelLoadFallbacks()` from `@jgengine/shell/render/modelLoad`** lists every model the shared loader diagnosed as broken and replaced with a magenta placeholder. A placeholder was only ever a console warning, so a shipped game could render one in its starting area and nobody found out until someone looked at a screenshot; a capture host or smoke test can now require the list to be empty. `clearModelLoadFallbacks()` resets it between runs.
+- **`worldHealthBars.occlude` / `WorldHealthBars`+`WorldNameplates` `occlude` prop.** World bars and nameplates are a screen-space overlay drawn outside the WebGL depth buffer, so nothing in the scene can hide them and an enemy's health bar reads straight through the building it stands behind. Set `occlude: true` to drop a bar when world geometry blocks the line from the player to the entity. Default `false` preserves the always-visible behaviour every shipped game currently relies on.
+
+- **`DustField` + `WeatherLayer` mode `"dust"` (`@jgengine/shell/weather`) — wind-borne particulate.** `WeatherLayer` could only do `clear`/`rain`/`snow`/`mixed`, so an arid, volcanic, ashen, or blown-out world had no way to put anything in the air. Dust drifts on horizontal wind with a slow vertical bob rather than falling; `groundBias` packs density toward the surface, motes fade near the top of the volume so recycled ones do not pop against the sky, and faster motes ride higher. Set `dustAlways` to keep it in the air alongside rain or snow instead of replacing them. Defaults `DEFAULT_DUST_COUNT`/`DEFAULT_DUST_DENSITY` sit beside the rain and snow pair.
+
+- **Authored `city` volumes render their near-LOD facades with a `BuildingKit`.** `CityRules.buildingKit` names a kit; a game registers the bound art with `registerBuildingKit(kit)` from `@jgengine/shell/structures/buildingKitRegistry` and the scene document carries only the name, so a city stays portable and free of model paths. Unset or unknown names keep the palette blocks. This puts the whole `city` primitive — not just the `building()` feature — on the kit path.
+- **`BuildingKit` from `@jgengine/core/world/buildingKit`** binds a generated building's facade part slots to real models, so procedural buildings render as an instanced asset kit instead of untextured blocks. `defineBuildingKit({ parts: { wall: ["Wall_A.glb", …] } })` maps a part kind — or a `${facade}.${kind}` slot — to ordered variants that `kit.variant` indexes, with `fit`/`offset`/`rotation`/`scale`/`tint`/`autoOrient` per variant. Kinds a kit leaves unbound keep rendering the palette block, so a partial kit is a valid kit, and `omit` drops a kind entirely. Pass one through `building({ kit })` or straight to `InstancedBuildings`; `buildingKitVariantCounts(kit)` feeds `generateBuilding` so its seeded picks span exactly the models the kit binds.
+- **`generateBuilding`, `generateBuildingDistrict`, and `createBuildingConfig` are now documented public API** (`@jgengine/core/world/buildings`) and appear in `capabilities.md` under `building-generator`.
+- **`capture.views` on `defineGame`** — named framings (`GameCaptureView`: `look`, `lookFrom`, `spawn`, `state`, `run`, `settleMs`) that `shoot <game> --view <name>` and `drive --view <name>` replay exactly, so a before/after pair is the same view by construction. `shoot <game> --list-views` prints what a game declares; an unknown name fails listing them, and any explicit capture flag still wins over the view's value.
+- **`modelLoadIdleMs()` from `@jgengine/shell/render/modelLoad`** reports how long the shared GLB loader has been idle (`0` while a model is in flight). Capture hosts wait on it instead of guessing a settle delay, so an establishing shot no longer races streaming models.
+- **Per-instance state on placed objects** — `SceneObject.state` (opaque `Record`), set through `ctx.scene.object.setState`/`patchState`/`place({ state })`. It survives move/rotate/setVisual, replicates and saves with the object, and round-trips as `RuntimeObjectRow.flags` via `toRuntimeObjectRow`/`fromRuntimeObjectRow` (`@jgengine/core/multiplayer`). A chest's locked flag or a machine's fill level no longer needs a game-owned map keyed by `instanceId`.
+- **`slotInventory` is a working feature** — `ctx.scene.object.slots` gives objects whose catalog entry declares it real per-instance container contents: `layout`/`state`/`count`, `put`/`take`, and `transferIn`/`transferOut` between a player inventory and the object, all validated against the declared slot count, `accepts` kind filter, and stack limits, with neither side mutated on a rejection. Contents live on `SceneObject.slots`, so they replicate and save with the placement.
+- **`loadServerSnapshot` and `persistServerSnapshot` are public** (`@jgengine/convex/server`), and `createGameServerFunctions` also returns `helpers` (`loadSnapshot`, `applyCommand`, `persistSnapshot`, `runCommand`) bound to the same runtimes and auth mode. A host mutation can now pair snapshot work with its own table writes in one transaction; the registered `runCommand` mutation delegates to `helpers.runCommand`, so there is one implementation.
+
+### Fixed
+
+- **Open storefronts are no longer holes through the building.** `generateBuilding` emitted an open ground-floor store as a lone `storefront` panel with no wall behind it, while every upper-floor window was correctly backed by one. Storefront and window materials render at 0.56 opacity and a generated building is a hollow shell, so those bays let you see straight through the building to the world beyond — and open stores only land on the street-facing facade, so a row of shops along a road was the worst case. The bay now emits its wall first, exactly as an upper floor does.
+- **`joinServer`, `flushSave`, `flushDirtyServers`, and the `auto` autosave can write player profiles again.** All four cleared the snapshot's dirty set before handing it to the persist plan, which gates profile writes on exactly that set — so the functions named "flush" flushed the server row and chunks only, and an `onNewPlayer` grant (starting money, starting items) never reached `jgPlayerProfiles`. `joinServer` now persists the snapshot it just marked; the flush paths mark every player dirty first, since hydrating from storage resets the dirty set. `planServerPersist` also clears `dirtyAt` once everything outstanding is written, so a successful flush stops autosave from re-firing forever, and a profile patch no longer clobbers a host-maintained `dirtyAt`.
+
 ## 0.15.0
 
 ### Migrate

package/dist/Shell3dPresentation.js

@@ -289,7 +289,7 @@ export function Shell3dPresentation({ playable, ctx, multiplayer, tracker, point
                                             fov: playable.camera?.frustum?.fov ?? CAMERA_FRUSTUM_DEFAULTS.fov,
                                             near: playable.camera?.frustum?.near ?? CAMERA_FRUSTUM_DEFAULTS.near,
                                             far: playable.camera?.frustum?.far ?? CAMERA_FRUSTUM_DEFAULTS.far,
-                                        }, shadows: graphics.shadows, dpr: [Math.min(1, graphics.dpr), graphics.dpr], gl: { preserveDrawingBuffer: true }, style: { touchAction: "none" }, children: [backgroundColor !== undefined ? _jsx("color", { attach: "background", args: [backgroundColor] }) : null, cinematicLook ? (_jsx(EnvironmentLighting, { skyColor: lighting?.hemisphere?.skyColor ?? "#87b5e0", groundColor: lighting?.hemisphere?.groundColor ?? "#3d4a38", sunDirection: lighting?.directional?.[0]?.position, sunColor: lighting?.directional?.[0]?.color ?? "#fff2d6" })) : null, lighting !== undefined ? (_jsx(ConfiguredLighting, { lighting: lighting })) : effectiveSky === undefined ? (_jsxs(_Fragment, { children: [_jsx("ambientLight", { intensity: 0.55 }), _jsx("directionalLight", { position: [10, 16, 6], intensity: 1.3 })] })) : null, effectiveSky !== undefined ? (effectiveSky.timeOfDay ? (_jsx(TimeOfDayDaylight, { sky: effectiveSky, clock: ctx.time, bands: effectiveSky === worldSky ? biomeBands : undefined, lights: skyEmitsLights(resolveSkyLightOwnership(lighting !== undefined)) })) : (_jsx(SkyDaylight, { sky: effectiveSky, bands: effectiveSky === worldSky ? biomeBands : undefined, lights: skyEmitsLights(resolveSkyLightOwnership(lighting !== undefined)) }))) : null, _jsx(BackdropFog, { fog: backdrop?.fog }), _jsxs(GameProvider, { context: ctx, children: [_jsx(CullingProvider, { config: playable.visibility, children: _jsx(WorldView, { entitySprites: playable.entitySprites, entityModels: playable.entityModels, objectModels: playable.objectModels, objectStyles: playable.objectStyles, environment: AutoEnvironment, assets: playable.game.assets, renderEntity: playable.renderEntity, renderObject: playable.renderObject, selectedIds: selectedIds, hideLocalActor: firstPerson }) }), WorldOverlay !== undefined ? (_jsx("group", { userData: CAMERA_TRANSPARENT_USERDATA, children: _jsx(WorldOverlay, { ctx: ctx }) })) : null, bars !== null ? (_jsx(WorldEntityBars, { statId: bars.statId, roles: bars.roles, resolveRole: resolveEntityRole, ...(bars.maxDistance === undefined ? {} : { maxDistance: bars.maxDistance }) })) : null, nameplates !== null ? (_jsx(WorldNameplates, { statId: nameplates.statId, roles: nameplates.roles, resolveRole: resolveEntityRole, ...(nameplates.maxDistance === undefined ? {} : { maxDistance: nameplates.maxDistance }), ...(nameplates.showHealth === undefined ? {} : { showHealth: nameplates.showHealth }) })) : null, _jsx(WorldItems, { config: playable.worldItem }), _jsx(CombatPresentation, { effects: effects }), devtoolsEnabled ? _jsx(CollisionDebugWorld, {}) : null, _jsx(AudioListener, { engine: audioEngine }), _jsx(EntityAudioEmitters, { engine: audioEngine, entitySounds: playable.entitySounds }), _jsx(ObjectAudioEmitters, { engine: audioEngine, objectSounds: playable.objectSounds }), _jsx(GameCameraRig, { yawRef: yawRef, pitchRef: pitchRef, config: cameraConfig, viewmodel: playable.viewmodel, pointerControls: pointerUsesLeft, panKeysEnabled: rtsPanKeysEnabled, director: ctx.camera, onDragChange: (dragging) => {
+                                        }, shadows: graphics.shadows, dpr: [Math.min(1, graphics.dpr), graphics.dpr], gl: { preserveDrawingBuffer: true }, style: { touchAction: "none" }, children: [backgroundColor !== undefined ? _jsx("color", { attach: "background", args: [backgroundColor] }) : null, cinematicLook ? (_jsx(EnvironmentLighting, { skyColor: lighting?.hemisphere?.skyColor ?? "#87b5e0", groundColor: lighting?.hemisphere?.groundColor ?? "#3d4a38", sunDirection: lighting?.directional?.[0]?.position, sunColor: lighting?.directional?.[0]?.color ?? "#fff2d6" })) : null, lighting !== undefined ? (_jsx(ConfiguredLighting, { lighting: lighting })) : effectiveSky === undefined ? (_jsxs(_Fragment, { children: [_jsx("ambientLight", { intensity: 0.55 }), _jsx("directionalLight", { position: [10, 16, 6], intensity: 1.3 })] })) : null, effectiveSky !== undefined ? (effectiveSky.timeOfDay ? (_jsx(TimeOfDayDaylight, { sky: effectiveSky, clock: ctx.time, bands: effectiveSky === worldSky ? biomeBands : undefined, lights: skyEmitsLights(resolveSkyLightOwnership(lighting !== undefined)) })) : (_jsx(SkyDaylight, { sky: effectiveSky, bands: effectiveSky === worldSky ? biomeBands : undefined, lights: skyEmitsLights(resolveSkyLightOwnership(lighting !== undefined)) }))) : null, _jsx(BackdropFog, { fog: backdrop?.fog }), _jsxs(GameProvider, { context: ctx, children: [_jsx(CullingProvider, { config: playable.visibility, children: _jsx(WorldView, { entitySprites: playable.entitySprites, entityModels: playable.entityModels, objectModels: playable.objectModels, objectStyles: playable.objectStyles, environment: AutoEnvironment, assets: playable.game.assets, renderEntity: playable.renderEntity, renderObject: playable.renderObject, selectedIds: selectedIds, hideLocalActor: firstPerson }) }), WorldOverlay !== undefined ? (_jsx("group", { userData: CAMERA_TRANSPARENT_USERDATA, children: _jsx(WorldOverlay, { ctx: ctx }) })) : null, bars !== null ? (_jsx(WorldEntityBars, { statId: bars.statId, roles: bars.roles, resolveRole: resolveEntityRole, ...(bars.maxDistance === undefined ? {} : { maxDistance: bars.maxDistance }), ...(bars.occlude === undefined ? {} : { occlude: bars.occlude }) })) : null, nameplates !== null ? (_jsx(WorldNameplates, { statId: nameplates.statId, roles: nameplates.roles, resolveRole: resolveEntityRole, ...(nameplates.maxDistance === undefined ? {} : { maxDistance: nameplates.maxDistance }), ...(nameplates.showHealth === undefined ? {} : { showHealth: nameplates.showHealth }) })) : null, _jsx(WorldItems, { config: playable.worldItem }), _jsx(CombatPresentation, { effects: effects }), devtoolsEnabled ? _jsx(CollisionDebugWorld, {}) : null, _jsx(AudioListener, { engine: audioEngine }), _jsx(EntityAudioEmitters, { engine: audioEngine, entitySounds: playable.entitySounds }), _jsx(ObjectAudioEmitters, { engine: audioEngine, objectSounds: playable.objectSounds }), _jsx(GameCameraRig, { yawRef: yawRef, pitchRef: pitchRef, config: cameraConfig, viewmodel: playable.viewmodel, pointerControls: pointerUsesLeft, panKeysEnabled: rtsPanKeysEnabled, director: ctx.camera, onDragChange: (dragging) => {
                                                         cameraDraggingRef.current = dragging;
                                                     } }), _jsx(PointerProbe, { service: pointerService })] }), _jsx(RemotePlayers, { rows: remotePlayers }), _jsx(FrameDriver, { ctx: ctx, playable: playable, tracker: tracker, yawRef: yawRef, pitchRef: pitchRef, primaryClickRef: primaryClickRef, pointerAxisRef: pointerAxisRef, analogRef: analogRef, gateRef: gateRef, onRuntimeError: reportRuntimeError, multiplayer: multiplayer, serverIdRef: serverIdRef, pointerService: pointerService, pointerAim: pointer?.aim === true, pingCommand: pointer?.pingCommand, poster: poster, onPosterSettled: onPosterSettled }), _jsx(DevtoolsRendererProbe, {}), resolvedLook.postProcessing !== undefined && resolvedLook.postProcessing.enabled !== false ? (_jsx(PostProcessing, { config: resolvedLook.postProcessing, quality: graphics.quality })) : null] }), !poster &&
                                     !orientationGate &&

package/dist/environment/EnvironmentScene.js

@@ -147,7 +147,7 @@ function Structures({ structures, field }) {
         ...(building.rotationY === undefined ? {} : { rotationY: building.rotationY, pivot: building.center }),
     })), [structures, field]);
     const palette = useMemo(() => resolveBuildingPalette(structures.style, structures.palette), [structures.style, structures.palette]);
-    return _jsx(InstancedBuildings, { buildings: placements, palette: palette });
+    return (_jsx(InstancedBuildings, { buildings: placements, palette: palette, ...(structures.kit === undefined ? {} : { kit: structures.kit }) }));
 }
 export function EnvironmentScene({ feature }) {
     const field = useMemo(() => resolveEnvironmentField(feature), [feature]);

package/dist/presentationResolve.d.ts

@@ -7,6 +7,7 @@ export interface ResolvedWorldOverlayBars {
     maxDistance?: number;
     /** Nameplates only: draw the built-in HP bar. `false` yields a name-only plate. Defaults to `true`. */
     showHealth?: boolean;
+    occlude?: boolean;
 }
 /**
  * Normalize `worldHealthBars` / `nameplates` (`boolean | object | undefined`) into a
@@ -20,6 +21,7 @@ export declare function resolveWorldOverlayBars(config: boolean | {
     roles?: readonly CatalogEntityRole[];
     maxDistance?: number;
     showHealth?: boolean;
+    occlude?: boolean;
 } | undefined): ResolvedWorldOverlayBars | null;
 /** Resolved combat presentation channels (each boolean is whether that stack piece mounts). @internal */
 export interface ResolvedPresentationEffects {

package/dist/presentationResolve.js

@@ -15,6 +15,7 @@ export function resolveWorldOverlayBars(config) {
         ...(config.roles === undefined ? {} : { roles: config.roles }),
         ...(config.maxDistance === undefined ? {} : { maxDistance: config.maxDistance }),
         ...(config.showHealth === undefined ? {} : { showHealth: config.showHealth }),
+        ...(config.occlude === undefined ? {} : { occlude: config.occlude }),
     };
 }
 // Every channel defaults on EXCEPT tracers. `fireProjectile` is a generic seam (bullets,

package/dist/render/modelLoad.d.ts

@@ -44,6 +44,22 @@ export declare function handleModelLoadFailure(resolvedUrl: string, originalEven
     probe?: typeof probeModelUrl;
     warn?: (message: string) => void;
 }): Promise<void>;
+/**
+ * Every model the shared loader diagnosed as broken and replaced with a magenta placeholder, in
+ * load order.
+ *
+ * A placeholder is already a console warning, but a warning does not fail anything — a shipped game
+ * can render one in its starting area and nobody finds out until someone looks at a screenshot.
+ * Reading this turns "the loader knows the asset is bad" into an assertable fact: a capture host or
+ * a smoke test can require it to be empty.
+ * @capability model-fallbacks models the loader replaced with a placeholder, for capture and smoke assertions
+ */
+export declare function modelLoadFallbacks(): readonly {
+    url: string;
+    message: string;
+}[];
+/** Drops the recorded placeholder list. For tests and between capture runs. @internal */
+export declare function clearModelLoadFallbacks(): void;
 /**
  * A {@link GLTFLoader} whose success path is unchanged but whose failures degrade
  * gracefully: when a load errors, it probes the URL and — for a diagnosed broken
@@ -56,5 +72,13 @@ export declare function handleModelLoadFailure(resolvedUrl: string, originalEven
 export declare class DiagnosticGLTFLoader extends GLTFLoader {
     load(url: string, onLoad: (gltf: GLTF) => void, onProgress?: (event: ProgressEvent) => void, onError?: (event: unknown) => void): void;
 }
+/**
+ * How long the shared GLB loader has been idle, in ms — `0` while any model is still
+ * in flight. A capture host reads this to wait for streaming to finish instead of
+ * guessing a settle delay: models that pop in after the shot are why an establishing
+ * capture used to come back half-empty until someone hand-tuned `--settle`.
+ * @capability model-load-idle how long the shared GLB loader has been idle, for capture settle waits
+ */
+export declare function modelLoadIdleMs(): number;
 /** Shared GLTF loader used by shell entity/object model mounts. @internal */
 export declare const sharedGltfLoader: DiagnosticGLTFLoader;

package/dist/render/modelLoad.js

@@ -117,8 +117,27 @@ export async function handleModelLoadFailure(resolvedUrl, originalEvent, onLoad,
         return;
     }
     (overrides.warn ?? warnMissingModel)(diagnosis.message);
+    servedFallbacks.push({ url: resolvedUrl, message: diagnosis.message });
     onLoad(createFallbackModel(diagnosis));
 }
+const servedFallbacks = [];
+/**
+ * Every model the shared loader diagnosed as broken and replaced with a magenta placeholder, in
+ * load order.
+ *
+ * A placeholder is already a console warning, but a warning does not fail anything — a shipped game
+ * can render one in its starting area and nobody finds out until someone looks at a screenshot.
+ * Reading this turns "the loader knows the asset is bad" into an assertable fact: a capture host or
+ * a smoke test can require it to be empty.
+ * @capability model-fallbacks models the loader replaced with a placeholder, for capture and smoke assertions
+ */
+export function modelLoadFallbacks() {
+    return servedFallbacks;
+}
+/** Drops the recorded placeholder list. For tests and between capture runs. @internal */
+export function clearModelLoadFallbacks() {
+    servedFallbacks.length = 0;
+}
 /**
  * A {@link GLTFLoader} whose success path is unchanged but whose failures degrade
  * gracefully: when a load errors, it probes the URL and — for a diagnosed broken
@@ -138,6 +157,33 @@ export class DiagnosticGLTFLoader extends GLTFLoader {
         });
     }
 }
+// LoadingManager reports queue transitions, not per-item events: `onStart` fires when the
+// queue goes busy and `onLoad` when it drains (errors included, via itemEnd), so a flag plus
+// a drain timestamp is the whole state.
+let modelQueueBusy = false;
+let modelQueueDrainedAt = 0;
+const now = () => (typeof performance === "undefined" ? Date.now() : performance.now());
+modelLoadingManager.onStart = () => {
+    modelQueueBusy = true;
+};
+modelLoadingManager.onLoad = () => {
+    modelQueueBusy = false;
+    modelQueueDrainedAt = now();
+};
+/**
+ * How long the shared GLB loader has been idle, in ms — `0` while any model is still
+ * in flight. A capture host reads this to wait for streaming to finish instead of
+ * guessing a settle delay: models that pop in after the shot are why an establishing
+ * capture used to come back half-empty until someone hand-tuned `--settle`.
+ * @capability model-load-idle how long the shared GLB loader has been idle, for capture settle waits
+ */
+export function modelLoadIdleMs() {
+    if (modelQueueBusy)
+        return 0;
+    if (modelQueueDrainedAt === 0)
+        return Number.POSITIVE_INFINITY;
+    return now() - modelQueueDrainedAt;
+}
 /** Shared GLTF loader used by shell entity/object model mounts. @internal */
 export const sharedGltfLoader = new DiagnosticGLTFLoader(modelLoadingManager);
 sharedGltfLoader.setMeshoptDecoder(MeshoptDecoder);

package/dist/scene/CityRenderer.js

@@ -22,6 +22,8 @@ import { triangulatePolygon, triangulateRingBand } from "@jgengine/core/world/ci
 import { resolveCityObject, CITY_KIND, CITY_ZONE_KIND, } from "@jgengine/core/world/cityKind";
 import { generateBuilding, resolveBuildingPalette } from "@jgengine/core/world/buildings";
 import { buildScatterProxy } from "../scatter/scatterProxies.js";
+import { InstancedBuildings } from "../structures/GeneratedBuilding.js";
+import { getBuildingKit } from "../structures/buildingKitRegistry.js";
 import { createCityWindowMaterial } from "./cityWindowMaterial.js";
 import { registerSceneKindRenderer } from "./sceneKindRenderers.js";
 const ASPHALT_COLOR = "#3d3f45";
@@ -323,58 +325,25 @@ function roleColor(palette, role) {
 const DETAIL_RADIUS = 95;
 const DETAIL_MAX = 12;
 const DETAIL_CLASSES = new Set(["tower", "slab", "shop", "rowhouse"]);
-/** Per-part-kind instanced batches for the near-LOD facade buildings (full lot yaw support). */
-function DetailBuildings({ buildings, palette }) {
-    const meshes = useMemo(() => {
-        if (buildings.length === 0)
-            return null;
-        const buckets = new Map();
-        const partMatrix = new THREE.Matrix4();
-        const compose = new THREE.Matrix4();
-        for (const building of buildings) {
-            for (const part of building.parts) {
-                partMatrix.compose(new THREE.Vector3(part.position[0], part.position[1], part.position[2]), new THREE.Quaternion().setFromAxisAngle(new THREE.Vector3(0, 1, 0), part.rotationY), new THREE.Vector3(Math.max(0.01, part.scale[0]), Math.max(0.01, part.scale[1]), Math.max(0.01, part.scale[2])));
-                compose.multiplyMatrices(building.matrix, partMatrix);
-                const bucket = buckets.get(part.kind);
-                if (bucket === undefined)
-                    buckets.set(part.kind, [compose.clone()]);
-                else
-                    bucket.push(compose.clone());
-            }
-        }
-        const geometry = new THREE.BoxGeometry(1, 1, 1);
-        const out = [];
-        // Rooftop mechanical units read as debug cubes in the district's bright palette accent — force a
-        // muted metal grey so they look like real HVAC/plant, never placeholder geometry.
-        const ROOF_PROP_GREY = "#9a9ea3";
-        for (const [kind, matrices] of buckets) {
-            const color = kind === "roofProp" ? ROOF_PROP_GREY : palette[kind];
-            const material = 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 })
-                    : new THREE.MeshStandardMaterial({ color, roughness: 0.88, metalness: 0 });
-            const mesh = new THREE.InstancedMesh(geometry, material, matrices.length);
-            matrices.forEach((matrix, i) => mesh.setMatrixAt(i, matrix));
-            mesh.instanceMatrix.needsUpdate = true;
-            mesh.castShadow = true;
-            mesh.receiveShadow = true;
-            mesh.frustumCulled = false;
-            out.push(mesh);
-        }
-        return out;
-    }, [buildings, palette]);
-    useEffect(() => () => {
-        if (meshes === null)
-            return;
-        for (const mesh of meshes) {
-            mesh.geometry.dispose();
-            mesh.material.dispose();
-        }
-    }, [meshes]);
-    if (meshes === null)
+// Rooftop mechanical units read as debug cubes in the district's bright palette accent — force a
+// muted metal grey so they look like real HVAC/plant, never placeholder geometry.
+const ROOF_PROP_GREY = "#9a9ea3";
+/**
+ * Near-LOD facade buildings, rendered through the shared building path so an authored city picks up
+ * a `BuildingKit` exactly like a `building()` feature does: kit-bound parts instance their models,
+ * everything else keeps the palette blocks.
+ */
+function DetailBuildings({ buildings, palette, kitName, }) {
+    const placements = useMemo(() => buildings.map((entry) => ({
+        building: { id: entry.lotId, parts: entry.parts },
+        position: [entry.center[0], entry.baseY, entry.center[1]],
+        rotationY: entry.rotationY,
+    })), [buildings]);
+    const detailPalette = useMemo(() => ({ ...palette, roofProp: ROOF_PROP_GREY }), [palette]);
+    const kit = getBuildingKit(kitName);
+    if (placements.length === 0)
         return null;
-    return (_jsx(_Fragment, { children: meshes.map((mesh, i) => (_jsx("primitive", { object: mesh }, `detail:${i}`))) }));
+    return _jsx(InstancedBuildings, { buildings: placements, palette: detailPalette, ...(kit === undefined ? {} : { kit }) });
 }
 /** One authored city volume → the full merged/instanced district. */
 function OneCity({ object, context }) {
@@ -449,9 +418,14 @@ function OneCity({ object, context }) {
                 bayWidth: lot.size[0] / baysWide,
                 floorHeight: resolved.rules.floorHeight,
             });
-            const matrix = new THREE.Matrix4().compose(new THREE.Vector3(lot.center[0], maxY, lot.center[1]), new THREE.Quaternion().setFromAxisAngle(new THREE.Vector3(0, 1, 0), lot.rotationY), new THREE.Vector3(1, 1, 1));
             ids.add(lot.id);
-            buildings.push({ lotId: lot.id, matrix, parts: building.parts });
+            buildings.push({
+                lotId: lot.id,
+                center: lot.center,
+                baseY: maxY,
+                rotationY: lot.rotationY,
+                parts: building.parts,
+            });
         }
         return { ids, buildings };
     }, [resolved, detailKey, sample]);
@@ -1072,7 +1046,7 @@ function OneCity({ object, context }) {
     }, [furniture]);
     if (resolved === null)
         return null;
-    return (_jsxs("group", { children: [ground?.asphalt != null ? (_jsx("mesh", { geometry: ground.asphalt, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: ASPHALT_COLOR, roughness: 0.96, metalness: 0, side: THREE.DoubleSide }) })) : null, ground?.gravel != null ? (_jsx("mesh", { geometry: ground.gravel, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: GRAVEL_COLOR, roughness: 1, metalness: 0, side: THREE.DoubleSide }) })) : null, ground?.sidewalks != null ? (_jsx("mesh", { geometry: ground.sidewalks, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: SIDEWALK_COLOR, roughness: 1, metalness: 0, side: THREE.DoubleSide }) })) : null, ground?.patches != null ? (_jsx("mesh", { geometry: ground.patches, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: ASPHALT_COLOR, roughness: 0.96, metalness: 0, side: THREE.DoubleSide }) })) : null, ground?.curbs != null ? (_jsx("mesh", { geometry: ground.curbs, receiveShadow: true, castShadow: true, children: _jsx("meshStandardMaterial", { color: CURB_COLOR, roughness: 0.9, metalness: 0, side: THREE.DoubleSide }) })) : null, ground?.markings != null ? (_jsx("mesh", { geometry: ground.markings, renderOrder: 1, children: _jsx("meshStandardMaterial", { color: MARKING_COLOR, roughness: 0.8, metalness: 0, side: THREE.DoubleSide, polygonOffset: true, polygonOffsetFactor: -1, polygonOffsetUnits: -1 }) })) : null, ground?.medians != null ? (_jsx("mesh", { geometry: ground.medians, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: MEDIAN_COLOR, roughness: 1, metalness: 0, side: THREE.DoubleSide }) })) : null, ground?.pavementDrives != null ? (_jsx("mesh", { geometry: ground.pavementDrives, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: PAVEMENT_COLOR, roughness: 1, metalness: 0, side: THREE.DoubleSide }) })) : null, ground?.gravelDrives != null ? (_jsx("mesh", { geometry: ground.gravelDrives, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: GRAVEL_COLOR, roughness: 1, metalness: 0, side: THREE.DoubleSide }) })) : null, ground?.parks != null ? (_jsx("mesh", { geometry: ground.parks, receiveShadow: true, children: _jsx("meshStandardMaterial", { vertexColors: true, roughness: 1, metalness: 0, side: THREE.DoubleSide }) })) : null, ground?.crops != null ? (_jsx("mesh", { geometry: ground.crops, receiveShadow: true, children: _jsx("meshStandardMaterial", { vertexColors: true, roughness: 1, metalness: 0, side: THREE.DoubleSide }) })) : null, bridges?.deck != null ? (_jsx("mesh", { geometry: bridges.deck, castShadow: true, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: CONCRETE_COLOR, roughness: 0.85, metalness: 0.05, side: THREE.DoubleSide }) })) : null, bridges !== null && bridges.concrete.length > 0 ? (_jsx(InstancedBoxes, { matrices: bridges.concrete, color: CONCRETE_COLOR })) : null, bridges !== null && bridges.steel.length > 0 ? _jsx(InstancedBoxes, { matrices: bridges.steel, color: STEEL_COLOR }) : null, tunnels?.roof != null ? (_jsx("mesh", { geometry: tunnels.roof, castShadow: true, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: TUNNEL_COLOR, roughness: 0.95, metalness: 0, side: THREE.DoubleSide }) })) : null, tunnels !== null && tunnels.stone.length > 0 ? _jsx(InstancedBoxes, { matrices: tunnels.stone, color: TUNNEL_COLOR }) : null, massing !== null ? massing.meshes.map((mesh, i) => _jsx("primitive", { object: mesh }, `massing:${i}`)) : null, furniture !== null ? furniture.meshes.map((mesh, i) => _jsx("primitive", { object: mesh }, `furniture:${i}`)) : null, _jsx(DetailBuildings, { buildings: detail.buildings, palette: palette })] }));
+    return (_jsxs("group", { children: [ground?.asphalt != null ? (_jsx("mesh", { geometry: ground.asphalt, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: ASPHALT_COLOR, roughness: 0.96, metalness: 0, side: THREE.DoubleSide }) })) : null, ground?.gravel != null ? (_jsx("mesh", { geometry: ground.gravel, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: GRAVEL_COLOR, roughness: 1, metalness: 0, side: THREE.DoubleSide }) })) : null, ground?.sidewalks != null ? (_jsx("mesh", { geometry: ground.sidewalks, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: SIDEWALK_COLOR, roughness: 1, metalness: 0, side: THREE.DoubleSide }) })) : null, ground?.patches != null ? (_jsx("mesh", { geometry: ground.patches, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: ASPHALT_COLOR, roughness: 0.96, metalness: 0, side: THREE.DoubleSide }) })) : null, ground?.curbs != null ? (_jsx("mesh", { geometry: ground.curbs, receiveShadow: true, castShadow: true, children: _jsx("meshStandardMaterial", { color: CURB_COLOR, roughness: 0.9, metalness: 0, side: THREE.DoubleSide }) })) : null, ground?.markings != null ? (_jsx("mesh", { geometry: ground.markings, renderOrder: 1, children: _jsx("meshStandardMaterial", { color: MARKING_COLOR, roughness: 0.8, metalness: 0, side: THREE.DoubleSide, polygonOffset: true, polygonOffsetFactor: -1, polygonOffsetUnits: -1 }) })) : null, ground?.medians != null ? (_jsx("mesh", { geometry: ground.medians, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: MEDIAN_COLOR, roughness: 1, metalness: 0, side: THREE.DoubleSide }) })) : null, ground?.pavementDrives != null ? (_jsx("mesh", { geometry: ground.pavementDrives, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: PAVEMENT_COLOR, roughness: 1, metalness: 0, side: THREE.DoubleSide }) })) : null, ground?.gravelDrives != null ? (_jsx("mesh", { geometry: ground.gravelDrives, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: GRAVEL_COLOR, roughness: 1, metalness: 0, side: THREE.DoubleSide }) })) : null, ground?.parks != null ? (_jsx("mesh", { geometry: ground.parks, receiveShadow: true, children: _jsx("meshStandardMaterial", { vertexColors: true, roughness: 1, metalness: 0, side: THREE.DoubleSide }) })) : null, ground?.crops != null ? (_jsx("mesh", { geometry: ground.crops, receiveShadow: true, children: _jsx("meshStandardMaterial", { vertexColors: true, roughness: 1, metalness: 0, side: THREE.DoubleSide }) })) : null, bridges?.deck != null ? (_jsx("mesh", { geometry: bridges.deck, castShadow: true, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: CONCRETE_COLOR, roughness: 0.85, metalness: 0.05, side: THREE.DoubleSide }) })) : null, bridges !== null && bridges.concrete.length > 0 ? (_jsx(InstancedBoxes, { matrices: bridges.concrete, color: CONCRETE_COLOR })) : null, bridges !== null && bridges.steel.length > 0 ? _jsx(InstancedBoxes, { matrices: bridges.steel, color: STEEL_COLOR }) : null, tunnels?.roof != null ? (_jsx("mesh", { geometry: tunnels.roof, castShadow: true, receiveShadow: true, children: _jsx("meshStandardMaterial", { color: TUNNEL_COLOR, roughness: 0.95, metalness: 0, side: THREE.DoubleSide }) })) : null, tunnels !== null && tunnels.stone.length > 0 ? _jsx(InstancedBoxes, { matrices: tunnels.stone, color: TUNNEL_COLOR }) : null, massing !== null ? massing.meshes.map((mesh, i) => _jsx("primitive", { object: mesh }, `massing:${i}`)) : null, furniture !== null ? furniture.meshes.map((mesh, i) => _jsx("primitive", { object: mesh }, `furniture:${i}`)) : null, _jsx(DetailBuildings, { buildings: detail.buildings, palette: palette, kitName: resolved?.rules.buildingKit ?? "" })] }));
 }
 /** One instanced unit-box mesh from precomposed matrices (bridge parts). */
 function InstancedBoxes({ matrices, color }) {

package/dist/structures/BuildingKitBatch.d.ts

@@ -0,0 +1,13 @@
+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[];
+}
+/**
+ * GPU-instances one kit model across every building part bound to it: the GLB loads once, its meshes
+ * are harvested into instanceable draw sources, and each part's slot box drives the fit scale. Suspends
+ * 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;

package/dist/structures/BuildingKitBatch.js

@@ -0,0 +1,78 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useMemo, useRef } from "react";
+import { useLoader } from "@react-three/fiber";
+import * as THREE from "three";
+import { sharedGltfLoader } from "../render/modelLoad.js";
+import { buildScatterModelSources, disposeScatterModelSources, } from "../scatter/scatterModels.js";
+import { composeBuildingKitMatrix, measureBuildingKitModel, } from "./buildingKitFit.js";
+function KitSourceInstances({ source, material, matrices, }) {
+    const meshRef = useRef(null);
+    useEffect(() => {
+        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();
+}
+/**
+ * GPU-instances one kit model across every building part bound to it: the GLB loads once, its meshes
+ * are harvested into instanceable draw sources, and each part's slot box drives the fit scale. Suspends
+ * while the GLB loads — mount it inside a `<Suspense>` so one slow model never blanks the rest.
+ * @internal
+ */
+export function BuildingKitBatch({ url, instances }) {
+    const gltf = useLoader(sharedGltfLoader, url);
+    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}`)))) }));
+}

package/dist/structures/GeneratedBuilding.d.ts

@@ -1,4 +1,6 @@
 import { type ReactNode } from "react";
+import type { BuildingKitSlot } 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";
 export interface BuildingPartPlacement {
@@ -8,6 +10,8 @@ export interface BuildingPartPlacement {
     position: readonly [number, number, number];
     rotationY: number;
     scale: readonly [number, number, number];
+    /** Which kit variant this slot asks for; emitted by the generator, consumed by `BuildingKit` binding. */
+    kit?: BuildingKitSlot;
 }
 export interface GeneratedBuildingData {
     id: string;
@@ -37,7 +41,12 @@ export interface BuildingBlockProps {
 export interface GeneratedBuildingProps {
     building: GeneratedBuildingData;
     palette?: BuildingMaterialPalette;
-    kit?: BuildingKitRenderer;
+    /** Per-part React escape hatch, tried before the kit; return undefined to fall through. */
+    partRenderer?: BuildingKitRenderer;
+    /** Binds part kinds to instanced GLB models; unbound kinds keep the palette boxes. */
+    kit?: BuildingKit;
+    /** Maps a kit part's `model` reference to a loadable URL. Defaults to identity. */
+    resolveModelUrl?: (model: string) => string;
     visibleKinds?: readonly BuildingPartKind[];
 }
 export interface InstancedBuildingPlacement {
@@ -51,8 +60,15 @@ export interface InstancedBuildingPlacement {
 export interface InstancedBuildingsProps {
     buildings: readonly InstancedBuildingPlacement[];
     palette?: BuildingMaterialPalette;
+    /**
+     * Binds part kinds to instanced GLB models. Kinds the kit leaves unbound keep rendering the palette
+     * boxes, and kinds it lists in `omit` render nothing; omit the prop for today's all-box massing.
+     */
+    kit?: BuildingKit;
+    /** Maps a kit part's `model` reference to a loadable URL. Defaults to identity. */
+    resolveModelUrl?: (model: string) => string;
     visibleKinds?: readonly BuildingPartKind[];
 }
-export declare function InstancedBuildings({ buildings, palette, visibleKinds }: InstancedBuildingsProps): import("react").JSX.Element | null;
+export declare function InstancedBuildings({ buildings, palette, kit, resolveModelUrl, visibleKinds, }: InstancedBuildingsProps): import("react").JSX.Element | null;
 export declare function BuildingBlock({ part, palette }: BuildingBlockProps): import("react").JSX.Element;
-export declare function GeneratedBuilding({ building, palette, kit, visibleKinds }: GeneratedBuildingProps): import("react").JSX.Element;
+export declare function GeneratedBuilding({ building, palette, partRenderer, kit, resolveModelUrl, visibleKinds, }: GeneratedBuildingProps): import("react").JSX.Element;

package/dist/structures/GeneratedBuilding.js

@@ -1,7 +1,9 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useLayoutEffect, useMemo, useRef } from "react";
+import { Suspense, useLayoutEffect, useMemo, useRef } from "react";
 import * as THREE from "three";
 import { useDisposable } from "../render/useDisposable.js";
+import { BuildingKitBatch } from "./BuildingKitBatch.js";
+import { bucketBuildingParts, normalFor, outwardOffset } from "./buildingKitFit.js";
 const DEFAULT_PALETTE = {
     wall: "#83766a",
     window: "#8ecae6",
@@ -19,26 +21,6 @@ const DEFAULT_PALETTE = {
 function colorFor(kind, palette) {
     return palette?.[kind] ?? DEFAULT_PALETTE[kind];
 }
-function normalFor(facade) {
-    if (facade === "front")
-        return [0, 1];
-    if (facade === "back")
-        return [0, -1];
-    if (facade === "left")
-        return [-1, 0];
-    if (facade === "right")
-        return [1, 0];
-    return [0, 0];
-}
-function outwardOffset(part) {
-    if (part.kind === "wall" || part.kind === "roof" || part.kind === "corner")
-        return 0;
-    if (part.kind === "window" || part.kind === "shutter" || part.kind === "storefront")
-        return 0.025;
-    if (part.kind === "awning" || part.kind === "storeSign")
-        return 0.09;
-    return 0.12;
-}
 function materialFor(part, palette) {
     const color = colorFor(part.kind, palette);
     if (part.kind === "window" || part.kind === "storefront") {
@@ -65,56 +47,6 @@ function batchMaterialFor(kind, palette) {
     }
     return new THREE.MeshStandardMaterial({ color, roughness: 0.88, metalness: 0 });
 }
-const CLOTHESLINE_ROW_OFFSETS = [-0.09, 0.09];
-function bucketPartMatrices(buildings, visible) {
-    const dummy = new THREE.Object3D();
-    const buckets = new Map();
-    for (const placement of buildings) {
-        const [ox, oy, oz] = placement.position ?? [0, 0, 0];
-        // Building yaw turns the whole massing about its center. Engine Y-rotation convention (matches
-        // dummy.rotation.y below): a local vector (x, z) maps to (x·cos + z·sin, −x·sin + z·cos).
-        const yaw = placement.rotationY ?? 0;
-        const [px0, pz0] = placement.pivot ?? [0, 0];
-        const cos = Math.cos(yaw);
-        const sin = Math.sin(yaw);
-        for (const part of placement.building.parts) {
-            if (visible !== null && !visible.has(part.kind))
-                continue;
-            const [nx, nz] = normalFor(part.facade);
-            const offset = outwardOffset(part);
-            // Local offset from the pivot (part position + facade-normal nudge), then rotated by the yaw.
-            const lx = part.position[0] - px0 + nx * offset;
-            const lz = part.position[2] - pz0 + nz * offset;
-            const px = ox + px0 + lx * cos + lz * sin;
-            const py = oy + part.position[1];
-            const pz = oz + pz0 - lx * sin + lz * cos;
-            const partYaw = part.rotationY + yaw;
-            let bucket = buckets.get(part.kind);
-            if (bucket === undefined) {
-                bucket = [];
-                buckets.set(part.kind, bucket);
-            }
-            if (part.kind === "clothesline") {
-                const rowSin = Math.sin(partYaw);
-                const rowCos = Math.cos(partYaw);
-                for (const row of CLOTHESLINE_ROW_OFFSETS) {
-                    dummy.position.set(px + row * rowSin, py, pz + row * rowCos);
-                    dummy.rotation.set(0, partYaw, 0);
-                    dummy.scale.set(part.scale[0], Math.max(part.scale[1], 0.025), 0.025);
-                    dummy.updateMatrix();
-                    bucket.push(dummy.matrix.clone());
-                }
-                continue;
-            }
-            dummy.position.set(px, py, pz);
-            dummy.rotation.set(0, partYaw, 0);
-            dummy.scale.set(part.scale[0], part.scale[1], part.scale[2]);
-            dummy.updateMatrix();
-            bucket.push(dummy.matrix.clone());
-        }
-    }
-    return buckets;
-}
 function BuildingKindBatch({ kind, matrices, palette, geometry, }) {
     const meshRef = useRef(null);
     const material = useDisposable(() => batchMaterialFor(kind, palette), [kind, palette]);
@@ -128,15 +60,15 @@ function BuildingKindBatch({ kind, matrices, palette, geometry, }) {
     }, [matrices, material]);
     return (_jsx("instancedMesh", { ref: meshRef, args: [geometry, material, matrices.length], castShadow: true, receiveShadow: true }, matrices.length));
 }
-export function InstancedBuildings({ buildings, palette, visibleKinds }) {
+export function InstancedBuildings({ buildings, palette, kit, resolveModelUrl, visibleKinds, }) {
     const geometry = useDisposable(() => new THREE.BoxGeometry(1, 1, 1), []);
-    const buckets = useMemo(() => {
+    const { boxes, models } = useMemo(() => {
         const visible = visibleKinds === undefined ? null : new Set(visibleKinds);
-        return bucketPartMatrices(buildings, visible);
-    }, [buildings, visibleKinds]);
-    if (buckets.size === 0)
+        return bucketBuildingParts(buildings, visible, kit, resolveModelUrl);
+    }, [buildings, visibleKinds, kit, resolveModelUrl]);
+    if (boxes.size === 0 && models.size === 0)
         return null;
-    return (_jsx("group", { children: [...buckets.entries()].map(([kind, matrices]) => (_jsx(BuildingKindBatch, { kind: kind, matrices: matrices, palette: palette, geometry: geometry }, kind))) }));
+    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)))] }));
 }
 function BlockMesh({ part, palette }) {
     const [nx, nz] = normalFor(part.facade);
@@ -161,7 +93,7 @@ export function BuildingBlock({ part, palette }) {
     }
     return _jsx(BlockMesh, { part: part, palette: palette });
 }
-export function GeneratedBuilding({ building, palette, kit, visibleKinds }) {
+export function GeneratedBuilding({ building, palette, partRenderer, kit, resolveModelUrl, visibleKinds, }) {
     const { kitParts, batched } = useMemo(() => {
         const visible = visibleKinds === undefined ? null : new Set(visibleKinds);
         const kitRendered = [];
@@ -169,7 +101,7 @@ export function GeneratedBuilding({ building, palette, kit, visibleKinds }) {
         for (const part of building.parts) {
             if (visible !== null && !visible.has(part.kind))
                 continue;
-            const rendered = kit?.renderPart?.(part);
+            const rendered = partRenderer?.renderPart?.(part);
             if (rendered !== undefined) {
                 kitRendered.push({ id: part.id, node: rendered });
                 continue;
@@ -178,6 +110,6 @@ export function GeneratedBuilding({ building, palette, kit, visibleKinds }) {
         }
         const placements = batchedParts.length === 0 ? [] : [{ building: { id: building.id, parts: batchedParts } }];
         return { kitParts: kitRendered, batched: placements };
-    }, [building, kit, visibleKinds]);
-    return (_jsxs("group", { name: building.id, children: [kitParts.map((entry) => (_jsx("group", { children: entry.node }, entry.id))), _jsx(InstancedBuildings, { buildings: batched, palette: palette })] }));
+    }, [building, partRenderer, visibleKinds]);
+    return (_jsxs("group", { name: building.id, children: [kitParts.map((entry) => (_jsx("group", { children: entry.node }, entry.id))), _jsx(InstancedBuildings, { buildings: batched, palette: palette, kit: kit, resolveModelUrl: resolveModelUrl })] }));
 }