@jgengine/shell 0.15.0-next.0 → 0.16.0

package/CHANGELOG.md

@@ -28,6 +28,49 @@ At publish, rename this heading to the new version and mirror the entries into
 
 ### Migrate
 
+### Changed
+
+### Added
+
+### 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
+
+- **Bump lockstep SDK packages to `^0.15.0`:** `@jgengine/{core,react,ws,node,sql,convex,shell,editor,assets}`. CLI `jgengine` is `0.12.0`; `@jgengine/github` is `0.2.0`.
 - **`jgengine create` scaffolds a textured world by default (#1550).** `--world` is now the default and `--no-world` is the opt-out (matching `--no-editor`); `--world` is still accepted. The default scaffold previously emitted untextured proxy geometry, which the AGENTS.md it ships declares a failing result. `create` now also pulls the starter asset packs into `public/models` after install, and never fails the scaffold if that pull cannot run (offline, blocked proxy, `--no-install`) — it prints `npx assets pull starter` in next steps instead, and the emitted AGENTS.md documents the same command. Skip the pull explicitly with `--no-assets`.
 - **Start game code at `@jgengine/shell/gameKit` (#1541).** Prefer that surface for `defineGame`, `GameHost`, stores, systems, authored-scene helpers, and HUD building blocks. `@jgengine/core/authoring` remains for pure core helpers the kit does not re-export but is no longer a competing start-here path.
 - **Every game must now declare its run-phase story — silence is a gate error (#1337).** The run-phase
@@ -73,10 +116,16 @@ At publish, rename this heading to the new version and mirror the entries into
 
 ### Added
 
+- **`advanceStepCadence` (`@jgengine/core/audio/stepCadence`) — distance-driven footstep timing.** Pure state-in/state-out: feed it the ground distance a mover covered this frame and it reports how many steps landed and which foot led, so foley stays locked to distance instead of a wall-clock timer that desyncs the moment speed changes. Configurable stride, per-advance `strideScale` for crouch/sprint, and a shorter first step from rest so walking off is heard immediately.
+- **`resolveMusicState` (`@jgengine/core/audio/musicState`) — combat-reactive soundtrack selection.** The engine could already crossfade themes but nothing decided *when*, so every game re-handrolled the threshold and got a track that flapped as one enemy walked in and out of range. Give it a tier ladder (intensity → theme) and it resolves the theme to play: escalation is immediate, de-escalation waits for the tier's `holdMs` and needs intensity to fall a `release` margin below the tier it is leaving. Pure and serialisable.
+- **Synth voices take a `sustain` (`ToneVoice`/`NoiseVoice`).** Seconds held at full gain before the decay. Default 0 preserves every existing patch. Without it there was no way to author a *sustained* sound at all: every voice decayed to silence inside its duration, so a patch rendered once and looped as an ambient bed pulsed audibly once per loop. Set `sustain` to `duration` for a flat wind, rain, or machine-hum bed that loops seamlessly.
+
 - **`ModelMaterialOverride.rim` — a fresnel rim light on any entity/object model.** `{ color, strength, power }` adds a bright edge where the surface turns away from the viewer, patched into the material's own shader so it shadows, fogs, and tonemaps with the body rather than floating in front of it. This is the standard fix for an actor that shares a value band with its ground: no albedo choice separates a body from terrain lit by the same key, but an edge does. Omit for no rim (default).
 
 ### Fixed
 
+- **Noise voices longer than the shared noise buffer no longer go silent partway through.** The 1-second buffer is sampled from a random offset, so any `NoiseVoice` whose duration exceeded the remainder ran off the end and finished in silence — invisible on short impact bursts, fatal for anything sustained. The source now wraps; the voice still ends on time.
+
 - **`terrain({ detail: { material: { tint } } })` separates a ground texture's grain from its hue.** A detail material's colour map used to replace the terrain's authored colour outright, so the biome palette, macro sweeps, and slope-rock blend under it were painted over and a whole region flattened to the texture's single hue — despite the API documenting that it "blends with, never replaces". `tint` defaults to 1 (the existing behaviour, so no shipped game changes); drop it toward 0 to keep the authored colour and take only the map's light and shade.
 - **`sky({ gradientExponent, cloudiness })` are now authorable — and `sky()` no longer silently drops them.** `gradientExponent` controls how fast the gradient reaches `zenithColor` off the horizon (default 0.65, unchanged): below 1 pulls the zenith hue down into the frame, which is what an eye-level camera in flat terrain actually needs — at the default the sky reads as one horizon-coloured wash however saturated the authored zenith is. `cloudiness` (default 0.35, unchanged) is the procedural cloud-band opacity.
 - **A model that throws while rendering is now reported instead of vanishing (#1588).** `ModelFallbackBoundary` swapped in its fallback (usually nothing) and stayed silent: `probes.fallbacks` stayed empty, no warning was logged, and an entity simply disappeared. It now reports a new `renderError` fallback cause on every failed render and warns once with the model url and the caught error.

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/audio/synthEngine.js

@@ -16,10 +16,13 @@ function realizeTone(ctx, out, voice, cueGain, at) {
     osc.frequency.setValueAtTime(voice.freq, t);
     if (voice.slideTo !== undefined)
         osc.frequency.exponentialRampToValueAtTime(Math.max(1, voice.slideTo), t + voice.duration);
+    const sustainEnd = Math.max(attack, voice.sustain ?? 0);
     const g = ctx.createGain();
     g.gain.setValueAtTime(0, t);
     g.gain.linearRampToValueAtTime(peak, t + attack);
-    g.gain.exponentialRampToValueAtTime(0.001, t + voice.duration);
+    if (sustainEnd > attack)
+        g.gain.setValueAtTime(peak, t + sustainEnd);
+    g.gain.exponentialRampToValueAtTime(0.001, t + Math.max(voice.duration, sustainEnd + 0.001));
     osc.connect(g).connect(out);
     osc.start(t);
     osc.stop(t + voice.duration + 0.05);
@@ -31,12 +34,19 @@ function realizeNoise(ctx, out, noiseBuf, voice, cueGain, at) {
     const src = ctx.createBufferSource();
     src.buffer = noiseBuf;
     src.playbackRate.value = 0.8 + Math.random() * 0.4;
+    // The shared buffer is 1 s and playback starts at a random offset inside it, so any voice longer
+    // than the remainder used to run off the end and go silent early. Wrapping keeps it noise throughout;
+    // the `duration` argument to start() still ends the voice on time.
+    src.loop = true;
     const filter = ctx.createBiquadFilter();
     filter.type = voice.filterType ?? "lowpass";
     filter.frequency.value = voice.filterFreq;
+    const sustain = Math.max(0, voice.sustain ?? 0);
     const g = ctx.createGain();
     g.gain.setValueAtTime(peak, t);
-    g.gain.exponentialRampToValueAtTime(0.001, t + voice.duration * decay);
+    if (sustain > 0)
+        g.gain.setValueAtTime(peak, t + sustain);
+    g.gain.exponentialRampToValueAtTime(0.001, t + Math.max(voice.duration * decay, sustain + 0.001));
     src.connect(filter).connect(g).connect(out);
     src.start(t, Math.random() * 0.5, voice.duration);
 }

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;