@jgengine/shell 0.15.0 → 0.17.0

package/CHANGELOG.md

@@ -34,6 +34,68 @@ At publish, rename this heading to the new version and mirror the entries into
 
 ### Fixed
 
+## 0.17.0
+
+### Migrate
+
+- **Bump lockstep SDK packages to `^0.17.0`:** `@jgengine/{core,react,ws,node,sql,convex,shell,editor,assets}`. CLI `jgengine` is `0.14.0`; `@jgengine/github` is `0.4.0`.
+- **A deleted player profile stays deleted.** When a game persists players (`save.scope` includes `player`), hydrating a member with no `jgPlayerProfiles` row no longer falls back to the copy of their state kept on the server row — that copy was resurrected and then written back as authoritative, so a world reset that cleared profiles but not servers silently restored every player's old balance. A game whose save scope excludes players (`"none"`, `"chunks"`) is unchanged: the server-row copy is still their state. If you seed members onto a server row without going through `joinServer`, write their profile row too.
+- **`slotsPerServer` is capped at 256** (`JG_MAX_MEMBERS_PER_SERVER`). `createGameServerFunctions` now throws at wiring time on a larger value instead of accepting it and failing at the write that overflows the document. One server is one Convex document holding the world row, the roster, and every member's session state; a bigger number was never a bigger world. Shard across servers, or move world state into `jgWorldChunks`.
+- **The tick cron only sweeps games that declare `loop.onTick`.** A game with no tick hook used to pay a full hydrate plus a full persist every second per running server, for a snapshot `runtime.tick` returned unchanged; it now costs nothing while idle. If you relied on the tick cron to autosave a hookless game, the 60s `flushDirtyServers` cron and the `flushSave` mutation still do it.
+
+### Changed
+
+- **Walking NPCs now stop at the geometry that stops the player.** `wander`, `patrol`, and `ctx.scene.entity.moveToward` consulted no obstacles at all, so a pedestrian walked through the building the player cannot enter. All three now slide their step against the scene's blocking physical colliders — the same query `stepPlayerMovement` reads. A patrol's path state still advances on its own clock (an authored route is not rewound by contact), but the entity can no longer end a tick inside a solid. Pass `avoidSolids: false` to `moveToward` for a mover meant to ignore the world (a flier, a camera rig).
+- **`@jgengine/assets` verify fails a model source that contributes no index entries.** A model pack that has never been pulled is a pin nothing has ever checked — that is how a Street Pack archive sat in the catalogue titled "Downtown City MegaKit". Record why a pack is not pulled in the new `AssetSource.unpulled` string; materials and sprites pull on demand and are exempt.
+- **`persistServerSnapshot` returns `boolean` and skips a write that would change nothing.** Every subscriber of a query that read a server row re-receives the whole result when that document changes, so an unconditional write on the 1 Hz tick re-pushed the entire world to every client once a second whether or not anything moved. `ServerPersistPlan` gains `changed` (`serverState` / `sessionPlayers` / `revision` / `any`) for hosts that write field-by-field.
+- **`sessionPlayers` is merged over the stored map, not rebuilt from the snapshot**, and entries for non-members are pruned. This is what makes a partially hydrated snapshot safe to persist.
+- **`tickActiveServers` is bounded** to `maxServersPerTick` (default 32) servers per transaction, oldest tick anchor first, instead of pulling every running server of every game into one transaction. `flushDirtyServers` is bounded the same way.
+
+### Added
+
+- **`solidObstaclesNear` / `resolveWalkerStep` (`@jgengine/core/movement/solidObstacles`)** — the engine's single answer to "what is solid here", now shared rather than re-derived per consumer. `solidObstaclesNear(ctx, position, reachX, reachZ)` returns the blocking physical colliders near a point through a bounded `inBox` broadphase; `resolveWalkerStep(ctx, position, stepX, stepZ)` slides a horizontal step against them with the player's axis-separated sliding. Reach for these instead of deriving obstacles from a game catalog's own solidity flags.
+- **Bounded hydration and a client chunk read** — `loadServerSnapshot(ctx, server, runtime, { players, chunkKeys })` hydrates only the members and chunks a mutation will touch instead of a document read per member plus one per chunk, and the generated `getChunks` query lets a client read chunk state by key (capped at `MAX_CHUNKS_PER_QUERY`). Chunks were the documented escape hatch for world state too large for one row, but reads were unbounded and clients could not see them at all, so moving geometry there made things worse. `getServerMeta` returns lobby state (status, member count, revision) without the world payload.
+- **`@jgengine/core/runtime/worldChunks`** — `chunkKeyAt` / `chunkCoordAt` / `chunkKeyOf` / `parseChunkKey` / `chunkKeysInRadius` at a declared cell size, plus `setChunk` / `updateChunk` / `deleteChunk`, which mark the key dirty so the host actually persists it. `chunkKey` was an opaque game-chosen string and the engine never wrote `dirty.chunks`, so every game reimplemented the coordinate mapping and a game that forgot to push a key silently never saved that chunk.
+- **Placed objects cull to `replication.aoiRadius`.** `objects` is the one large spatial replicated set and had no projector, so a world with a few thousand placements sent all of them to every viewer. It now joins the same area-of-interest policy as `entities` and `stats`. Unset `aoiRadius` still replicates everything.
+- **`createGameServerFunctions({ matchmaking: "singleton" })`** — one shared world per game: auto-match always targets the existing world and a join past capacity fails loudly, instead of quietly creating a second world the player would be alone in. `joinServer` also reconciles a stored `slotsPerServer`/`save` that has drifted from the host options, which previously made raising the option a no-op on worlds that already existed. `selectJoinTarget` (`@jgengine/core/runtime/hostPolicy`) is the pure decision behind it.
+- **`GameRuntime.hasTick`** reports whether a runtime declares `loop.onTick`, so any host's scheduler can skip a server whose tick is a no-op by construction.
+
+### Removed
+
+- **Asset source `quaternius-downtown-city`.** It was titled "Downtown City MegaKit" but pinned at the Street Pack archive, which ships Blends/FBX/OBJ only — a pull found no models. Nothing referenced it.
+
+## 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;