@jgengine/core 0.15.0-next.0 → 0.16.0

package/dist/world/buildings.d.ts

@@ -1,3 +1,8 @@
+/**
+ * Seeded procedural buildings: a footprint of bays × floors emitted as placed facade parts — walls,
+ * windows, storefronts, roof and decor — each tagged with a kit slot `world/buildingKit` binds to a
+ * model. Deterministic and renderer-agnostic.
+ */
 import { type Aabb, type Footprint, type Vec2 } from "./geometry.js";
 export type BuildingSeed = number | string;
 export type Vec3 = readonly [number, number, number];
@@ -105,11 +110,28 @@ export declare const DEFAULT_BUILDING_STYLE: BuildingStyle;
 export declare const BUILDING_STYLE_PALETTES: Record<BuildingStyle, BuildingPalette>;
 /** @internal */
 export declare function resolveBuildingPalette(style?: BuildingStyle, overrides?: BuildingPaletteOverrides): BuildingPalette;
-/** @internal */
+/**
+ * Fill a partial building description out to a complete {@link BuildingConfig}, clamping counts and
+ * probabilities. Use it to inspect or adjust the resolved shape before generating.
+ *
+ * @capability building-generator generate seeded buildings as placed facade parts — bays, floors, roof, decor
+ */
 export declare function createBuildingConfig(input?: BuildingConfigInput): BuildingConfig;
-/** @internal */
+/**
+ * Generate one building as a flat list of placed facade parts: bays × floors per facade, a ground
+ * row, corners, and a roof, with every decorative part rolled from `probabilities` and every part
+ * tagged with a `kit` slot the renderer binds to a model (see `world/buildingKit`). Deterministic
+ * from `seed`.
+ *
+ * @capability building-generator generate a seeded building as placed facade parts (bays, floors, roof, decor)
+ */
 export declare function generateBuilding(input?: BuildingConfigInput): GeneratedBuilding;
 /** @internal */
 export declare function createBuildingGrid(config: BuildingGridConfig): BuildingLot[];
-/** @internal */
+/**
+ * Generate a grid of buildings on lots sized by `lotSize` and separated by `streetWidth`, each with
+ * its floor count rolled from `floorRange`.
+ *
+ * @capability building-generator generate a grid district of seeded buildings
+ */
 export declare function generateBuildingDistrict(config: BuildingGridConfig): GeneratedBuilding[];

package/dist/world/buildings.js

@@ -1,3 +1,8 @@
+/**
+ * Seeded procedural buildings: a footprint of bays × floors emitted as placed facade parts — walls,
+ * windows, storefronts, roof and decor — each tagged with a kit slot `world/buildingKit` binds to a
+ * model. Deterministic and renderer-agnostic.
+ */
 import { footprintAabb } from "./geometry.js";
 const DEFAULT_PROBABILITIES = {
     window: 0.88,
@@ -229,7 +234,12 @@ function rangeInt(seed, key, min, max) {
     const hi = Math.max(min, max);
     return lo + Math.floor(hash01(seed, key) * (hi - lo + 1));
 }
-/** @internal */
+/**
+ * Fill a partial building description out to a complete {@link BuildingConfig}, clamping counts and
+ * probabilities. Use it to inspect or adjust the resolved shape before generating.
+ *
+ * @capability building-generator generate seeded buildings as placed facade parts — bays, floors, roof, decor
+ */
 export function createBuildingConfig(input = {}) {
     return {
         id: input.id ?? DEFAULT_BUILDING_CONFIG.id,
@@ -291,6 +301,13 @@ function panelPosition(config, facade, bay, level, width, depth) {
     const z = config.center[1] - depth / 2 + config.bayWidth * (bay + 0.5);
     return [faceDepth(facade, width, depth, config), y, z];
 }
+/**
+ * Panel dimensions inside one bay. Structural parts (wall, shutter) must pass 1/1 so they tile their
+ * bay completely — a generated building is a shell of thin panels with no solid core, so any ratio
+ * below 1 leaves a continuous slit at every bay seam and floor line that you can see through the
+ * building and out the far side. Decorative overlays (window, storefront, awning, sign) sit on top of
+ * a full wall and are meant to be inset.
+ */
 function panelScale(config, _facade, heightRatio, widthRatio = 0.92) {
     const along = config.bayWidth * widthRatio;
     const high = config.floorHeight * heightRatio;
@@ -333,7 +350,7 @@ function pushUpperFloorParts(parts, config, facade, bay, level, width, depth) {
     const cell = { facade, level, bay };
     const key = `${facade}:${level}:${bay}`;
     const position = panelPosition(config, facade, bay, level, width, depth);
-    parts.push(part(config, "wall", facade, position, panelScale(config, facade, 0.92), `${key}:wall`, cell, ["structure", "upper"]));
+    parts.push(part(config, "wall", facade, position, panelScale(config, facade, 1, 1), `${key}:wall`, cell, ["structure", "upper"]));
     if (!chance(config.seed, `${key}:window`, config.probabilities.window))
         return;
     parts.push(part(config, "window", facade, position, panelScale(config, facade, 0.46, 0.58), `${key}:window`, cell, ["upper"]));
@@ -355,6 +372,11 @@ function pushGroundFloorParts(parts, config, facade, bay, width, depth) {
     const key = `${facade}:0:${bay}`;
     const position = panelPosition(config, facade, bay, 0, width, depth);
     if (facade === "front" && chance(config.seed, `${key}:open`, config.probabilities.openStore)) {
+        // Back the glass with a wall the way an upper floor backs its window. A generated building is a
+        // hollow shell, so a translucent storefront with nothing behind it is a hole 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 most visible place for it to read as see-through.
+        parts.push(part(config, "wall", facade, position, panelScale(config, facade, 1, 1), `${key}:wall`, cell, ["structure", "ground"]));
         parts.push(part(config, "storefront", facade, position, panelScale(config, facade, 0.86), `${key}:store`, cell, ["ground", "open"]));
         if (chance(config.seed, `${key}:sign`, config.probabilities.storeSign)) {
             const signPosition = [position[0], position[1] + config.floorHeight * 0.34, position[2]];
@@ -363,7 +385,7 @@ function pushGroundFloorParts(parts, config, facade, bay, width, depth) {
         return;
     }
     const kind = facade === "front" ? "shutter" : "wall";
-    parts.push(part(config, kind, facade, position, panelScale(config, facade, 0.86), `${key}:${kind}`, cell, ["ground", "closed"]));
+    parts.push(part(config, kind, facade, position, panelScale(config, facade, 1, 1), `${key}:${kind}`, cell, ["ground", "closed"]));
 }
 function pushFacade(parts, config, facade, width, depth) {
     const bays = facade === "front" || facade === "back" ? config.baysWide : config.baysDeep;
@@ -408,7 +430,14 @@ function pushCorners(parts, config, width, depth) {
         parts.push(part(config, "corner", index < 2 ? "back" : "front", position, [config.facadeDepth * 1.35, height, config.facadeDepth * 1.35], `corner:${index}`, undefined, ["structure"]));
     });
 }
-/** @internal */
+/**
+ * Generate one building as a flat list of placed facade parts: bays × floors per facade, a ground
+ * row, corners, and a roof, with every decorative part rolled from `probabilities` and every part
+ * tagged with a `kit` slot the renderer binds to a model (see `world/buildingKit`). Deterministic
+ * from `seed`.
+ *
+ * @capability building-generator generate a seeded building as placed facade parts (bays, floors, roof, decor)
+ */
 export function generateBuilding(input = {}) {
     const config = createBuildingConfig(input);
     const width = config.baysWide * config.bayWidth;
@@ -471,7 +500,12 @@ export function createBuildingGrid(config) {
     }
     return lots;
 }
-/** @internal */
+/**
+ * Generate a grid of buildings on lots sized by `lotSize` and separated by `streetWidth`, each with
+ * its floor count rolled from `floorRange`.
+ *
+ * @capability building-generator generate a grid district of seeded buildings
+ */
 export function generateBuildingDistrict(config) {
     return createBuildingGrid(config).map((lot) => generateBuilding(lot.config));
 }

package/dist/world/cityKind.d.ts

@@ -106,6 +106,12 @@ export interface CityRules {
     sidewalkWidth: number;
     /** Building style palette id (see {@link BUILDING_STYLE_PALETTES}). */
     style: BuildingStyle;
+    /**
+     * Name of the `BuildingKit` the near-LOD facades render with, or `""` for the palette blocks.
+     * A game registers its bound art under this name; the document carries only the name, so a scene
+     * stays portable and small.
+     */
+    buildingKit: string;
     /** Seed string; same seed reproduces the same city. Empty falls back to the volume id. */
     seed: string;
 }

package/dist/world/cityKind.js

@@ -103,6 +103,7 @@ export const CITY_DEFAULTS = {
     sidewalks: true,
     sidewalkWidth: 1.9,
     style: DEFAULT_BUILDING_STYLE,
+    buildingKit: "",
     seed: "",
 };
 /** The city parameter schema — drives the inspector sliders and `meta` parse via the studio seam. */
@@ -184,6 +185,7 @@ export const CITY_SCHEMA = {
             default: CITY_DEFAULTS.style,
             options: Object.keys(BUILDING_STYLE_PALETTES).map((style) => ({ value: style })),
         },
+        { type: "text", key: "buildingKit", label: "building kit", group: "buildings", default: CITY_DEFAULTS.buildingKit },
         { type: "range", key: "treeDensity", label: "tree density", group: "greenery", min: 0, max: 1, step: 0.01, default: CITY_DEFAULTS.treeDensity },
         { type: "weightedList", key: "treeMix", label: "tree mix", group: "greenery", itemLabel: "species", default: CITY_DEFAULTS.treeMix },
         { type: "range", key: "lightDensity", label: "street lights", group: "greenery", min: 0, max: 1, step: 0.01, default: CITY_DEFAULTS.lightDensity },
@@ -563,6 +565,7 @@ export function readCityRules(meta) {
         sidewalks: params["sidewalks"],
         sidewalkWidth: params["sidewalkWidth"],
         style: params["style"],
+        buildingKit: params["buildingKit"] ?? CITY_DEFAULTS.buildingKit,
         seed: params["seed"],
     };
 }

package/dist/world/environmentSummary.js

@@ -1,4 +1,5 @@
 import { DEFAULT_BUILDING_CONFIG, generateBuilding, generateBuildingDistrict, resolveBuildingPalette, } from "./buildings.js";
+import { buildingKitVariantCounts } from "./buildingKit.js";
 import { deriveBuildingLots } from "./buildingLots.js";
 import { pathLength } from "./roads.js";
 import { resolveTerrainField, resolveTerrainPalette } from "./terrain.js";
@@ -21,10 +22,17 @@ export function resolveStructureBuildings(descriptor) {
         lotSize: descriptor.footprint,
         streetWidth: spacing,
         floorRange: descriptor.stories,
-        base: { floorHeight: descriptor.storyHeight },
+        base: { floorHeight: descriptor.storyHeight, ...kitVariants(descriptor.kit) },
         ...(descriptor.seed === undefined ? {} : { seed: descriptor.seed }),
     }).slice(0, descriptor.count);
 }
+/** Spread seeded variant picks across exactly the models a kit binds, so no bound variant goes unused. */
+function kitVariants(kit) {
+    if (kit === undefined)
+        return {};
+    const variants = buildingKitVariantCounts(kit);
+    return Object.keys(variants).length === 0 ? {} : { variants };
+}
 function hashU32(input) {
     let hash = 2166136261;
     for (let i = 0; i < input.length; i += 1) {
@@ -57,9 +65,10 @@ function resolveFrontageBuildings(descriptor, along) {
     });
     const [floorsMin, floorsMax] = descriptor.stories;
     const bayWidth = DEFAULT_BUILDING_CONFIG.bayWidth;
-    return lots.map((lot, index) => buildLot(lot, index, seed, floorsMin, floorsMax, bayWidth, descriptor.storyHeight));
+    const variants = kitVariants(descriptor.kit);
+    return lots.map((lot, index) => buildLot(lot, index, seed, floorsMin, floorsMax, bayWidth, descriptor.storyHeight, variants));
 }
-function buildLot(lot, index, seed, floorsMin, floorsMax, bayWidth, storyHeight) {
+function buildLot(lot, index, seed, floorsMin, floorsMax, bayWidth, storyHeight, variants = {}) {
     const lo = Math.min(floorsMin, floorsMax);
     const hi = Math.max(floorsMin, floorsMax);
     const floors = lo + Math.floor((hashU32(`${seed}:floors:${index}`) / 4294967296) * (hi - lo + 1));
@@ -74,6 +83,7 @@ function buildLot(lot, index, seed, floorsMin, floorsMax, bayWidth, storyHeight)
         baysDeep,
         bayWidth,
         floorHeight: storyHeight,
+        ...variants,
     });
     return { ...building, rotationY: lot.rotationY };
 }

package/dist/world/features.d.ts

@@ -1,4 +1,5 @@
 import type { BuildingPaletteOverrides, BuildingStyle } from "./buildings.js";
+import type { BuildingKit } from "./buildingKit.js";
 import type { AvoidZone } from "./geometry.js";
 import type { TerrainPathProfile } from "./pathTerrain.js";
 import type { PlaceWorldFeature } from "./place.js";
@@ -352,6 +353,11 @@ export interface BuildingEnvironmentConfig {
      * back by a sidewalk strip) instead of the grid around `position`. See {@link BuildingFrontageConfig}.
      */
     along?: BuildingFrontageConfig;
+    /**
+     * Binds facade part slots to real models (see `world/buildingKit`). Unbound kinds keep the
+     * untextured block; without a kit the whole facade stays blocks, as before.
+     */
+    kit?: BuildingKit;
 }
 export type PadSize = readonly [number, number] | {
     radius: number;
@@ -393,7 +399,7 @@ export type OceanEnvironmentDescriptor = {
 } & Required<Pick<OceanEnvironmentConfig, "bounds" | "level" | "waveHeight" | "waveScale" | "waveSpeed" | "color">> & Pick<OceanEnvironmentConfig, "position" | "levelAt">;
 export type BuildingEnvironmentDescriptor = {
     kind: "building";
-} & Required<Pick<BuildingEnvironmentConfig, "count" | "footprint" | "stories" | "storyHeight" | "spacing" | "style">> & Pick<BuildingEnvironmentConfig, "seed" | "position" | "palette" | "along">;
+} & Required<Pick<BuildingEnvironmentConfig, "count" | "footprint" | "stories" | "storyHeight" | "spacing" | "style">> & Pick<BuildingEnvironmentConfig, "seed" | "position" | "palette" | "along" | "kit">;
 export type PadEnvironmentDescriptor = {
     kind: "pad";
 } & Required<Pick<PadEnvironmentConfig, "center" | "size" | "height" | "color">> & Pick<PadEnvironmentConfig, "rotationY" | "elevation">;

package/dist/world/features.js

@@ -247,6 +247,7 @@ export function building(config = {}) {
         ...(config.position === undefined ? {} : { position: config.position }),
         ...(config.palette === undefined ? {} : { palette: config.palette }),
         ...(config.along === undefined ? {} : { along: config.along }),
+        ...(config.kit === undefined ? {} : { kit: config.kit }),
     });
 }
 export function pad(config) {

package/dist/world.d.ts

@@ -50,6 +50,7 @@ export { StructureGraph, type CollapseEvent, type StructureMaterial } from "./ph
 export { Glide, Grapple } from "./physics/traversal.js";
 export { DEFAULT_GRIP_CURVE, createVehicleBody, sampleGripCurve, type GripCurve } from "./physics/vehicleBody.js";
 export { createVehicleObstacleClamp, type VehicleImpact, type VehicleObstacleClamp, } from "./physics/vehicleObstacles.js";
+export { type ObjectSlotRejection, type ObjectSlotResult, type ObjectSlotTransfer, type SceneObjectSlots, } from "./runtime/context/objectSlots.js";
 export { createAssetCatalog, type AssetCatalog, type ModelAssetRef, type ModelDims } from "./scene/assetCatalog.js";
 export { partsBounds, registerAssetGenerator, type GeneratedAsset, type GeneratedPart } from "./scene/assetGenerator.js";
 export { applyRotationPolicy, headingToRotationY, normalizeDegrees, parseAssetSpace, parseRotationPolicy, resolveAnchorOffset, resolveFacingRotationY, rotatedFootprint, rotationYToHeading, snapHeading, toEngineUnits, validateAssetSpace, type AssetAnchor, type AssetSpace, type AssetSpaceIssue, type PlacementRotationPolicy, } from "./scene/assetSpace.js";

package/dist/world.js

@@ -50,6 +50,7 @@ export { StructureGraph } from "./physics/structure.js";
 export { Glide, Grapple } from "./physics/traversal.js";
 export { DEFAULT_GRIP_CURVE, createVehicleBody, sampleGripCurve } from "./physics/vehicleBody.js";
 export { createVehicleObstacleClamp, } from "./physics/vehicleObstacles.js";
+export {} from "./runtime/context/objectSlots.js";
 export { createAssetCatalog } from "./scene/assetCatalog.js";
 export { partsBounds, registerAssetGenerator } from "./scene/assetGenerator.js";
 export { applyRotationPolicy, headingToRotationY, normalizeDegrees, parseAssetSpace, parseRotationPolicy, resolveAnchorOffset, resolveFacingRotationY, rotatedFootprint, rotationYToHeading, snapHeading, toEngineUnits, validateAssetSpace, } from "./scene/assetSpace.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jgengine/core",
-  "version": "0.15.0-next.0",
+  "version": "0.16.0",
   "description": "jgengine core — pure-TypeScript game framework SDK (npm @jgengine/core). Entity stores, commands, combat, inventory, multiplayer seams. Zero dependencies. Not an ECS. Agent skills ship in the tarball. https://jgengine.com",
   "keywords": [
     "jgengine",

package/skills/jgengine/api.md

@@ -6,7 +6,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.15.0-next.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.16.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/authoring
 
@@ -228,7 +228,7 @@
 
 - `CHANGELOG` (const): const CHANGELOG: Record<string, ChangelogEntry> — Per-version engine changelog keyed by semver string (e.g. `"0.10.0"`).
 - `ChangelogEntry` (interface): interface ChangelogEntry — One release's migrate steps plus added/changed/removed notes (typed mirror of CHANGELOG.md).
-- `VERSION` (const): const VERSION: "0.15.0-next.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
+- `VERSION` (const): const VERSION: "0.16.0" — Installed `@jgengine/core` semver — compare against {@link CHANGELOG} keys when migrating.
 
 ## @jgengine/core/runtime/adapter
 
@@ -264,6 +264,13 @@
 - `CommandValidationError` (type): type CommandValidationError = { reason: string } — ⚠ undocumented
 - `RunCommandResult` (type): type RunCommandResult = | { ok: true; snapshot: GameRuntimeSnapshot } | { ok: false; reason: string } — ⚠ undocumented
 
+## @jgengine/core/runtime/context/objectSlots
+
+- `ObjectSlotRejection` (type): type ObjectSlotRejection = | "unknown-object" | "no-slot-inventory" | "unknown-inventory" | "no-space" | "wrong-kind" | "slot-occupied" | "invalid-slot" | "insufficient" — Why an object slot mutation was refused — the instance, its catalog entry, the player inventory, or the declared `accepts`/capacity.
+- `ObjectSlotResult` (type): type ObjectSlotResult = { status: "ok" } | { status: "rejected"; reason: ObjectSlotRejection } — Outcome of an object slot mutation: applied, or refused with a reason and no state change on either side.
+- `ObjectSlotTransfer` (interface): interface ObjectSlotTransfer — Which player inventory a transfer moves between, and what it moves.
+- `SceneObjectSlots` (interface): interface SceneObjectSlots — Per-instance container contents for placed objects whose catalog entry declares `slotInventory` — the engine side of "install a GPU into a rack", "put an item in a chest". Contents live on `SceneObject.slots`, so they replicate and save with the object rather than needing a game-owned table keyed by `instanceId`, and every mutation is validated against the declared `accepts` and stack limits.
+
 ## @jgengine/core/runtime/gameContext
 
 - `CatalogEntityRole` (type): type CatalogEntityRole = "player" | "enemy" | "hostile" | "npc" | "vehicle" — ⚠ undocumented
@@ -402,6 +409,11 @@
 - `MotionIntentBatch` (interface): interface MotionIntentBatch — ⚠ undocumented
 - `MotionIntents` (interface): interface MotionIntents — Seam for game code to reach the motion the shell's FrameDriver otherwise owns privately (#162.4). Game code calls `impulse`, `pushHorizontal`, `setVerticalVelocity`, and/or `setY` from `onTick` or commands; the shell calls `takePending()` once per frame, before integrating gravity, to drain what accumulated. `setY` wins over physics for that frame; impulses add to the velocity the driver is about to integrate; a later `setVerticalVelocity` replaces that velocity outright. Horizontal pushes compose with the walk controller (#282.4): they add to its horizontal velocity and decay naturally as it re-blends toward input — knockback, dashes, explosion shoves without raw `setPose` offsets.
 
+## @jgengine/core/runtime/objectRows
+
+- `fromRuntimeObjectRow` (function): function fromRuntimeObjectRow(row: RuntimeObjectRow): SceneObject — Inverse of {@link toRuntimeObjectRow}: rebuild the live placed object a host persisted.
+- `toRuntimeObjectRow` (function): function toRuntimeObjectRow(object: SceneObject): RuntimeObjectRow — Convert a live placed object into its persisted row — the bridge between `ctx.scene.object` and `GameRuntimeSnapshot.server.objects`/`chunks[].objects`. Per-instance `state` is carried as `flags`. Presentation overrides (`visual`, `animation`) are catalog- and authoring-resolved and deliberately stay off the persisted row — put anything a command must own in `state`.
+
 ## @jgengine/core/runtime/perContext
 
 - `perContext` (function): function perContext<T>(init: (ctx: GameContext) => T): (ctx: GameContext) => T — Per-`GameContext` lazy state, keyed by context identity through a `WeakMap` so it is reclaimed when the context is — the seam a game uses instead of a module-global `Map`, which is process-global and bleeds across worlds when one host serves several `serverId`s (#632). `init` runs once per distinct context on first access; the same context always resolves to the same value. This mirrors the engine's built-in per-ctx pattern (`ctx.player.motion`, `stepPlayerMovement`).
@@ -441,7 +453,7 @@
 - `RuntimeChunkRow` (type): type RuntimeChunkRow = { chunkKey: string; objects: RuntimeObjectRow[]; entities: RuntimeEntityRow[]; flags?: Record<string, unknown>; } — ⚠ undocumented
 - `RuntimeEntityRow` (type): type RuntimeEntityRow = { instanceId: string; catalogId: string; position?: [number, number, number]; rotationY?: number; parentSpace?: string; group?: string; stats?: Record<string, { current: number; max: number; min?: number }>; targetInstanceId?: string | null; userId?: string; } — ⚠ undocumented
 - `RuntimeInventorySlot` (type): type RuntimeInventorySlot = { item: string; count: number; slot?: number; } — ⚠ undocumented
-- `RuntimeObjectRow` (type): type RuntimeObjectRow = { instanceId: string; catalogId: string; position: [number, number, number]; rotationY?: number; parentSpace?: string; flags?: Record<string, unknown>; } — ⚠ undocumented
+- `RuntimeObjectRow` (type): type RuntimeObjectRow = { instanceId: string; catalogId: string; position: [number, number, number]; rotationY?: number; parentSpace?: string; /** Opaque per-instance state; the persisted name for `SceneObject.state`. */ flags?: Record<string, unknown>; /** Container contents for a catalog `slotInve… — The persisted form of a placed `SceneObject`: identity, placement, per-instance state, and slot contents. Convert with `toRuntimeObjectRow`/`fromRuntimeObjectRow` (`runtime/objectRows`).
 - `RuntimePlayerRow` (type): type RuntimePlayerRow = { userId: string; inventories: Record<string, RuntimeInventorySlot[]>; economy: Record<string, number>; unlocks: string[]; quests?: unknown; social?: unknown; leaderboard?: Record<string, number>; session?: Record<string, unknown>; } — ⚠ undocumented
 - `RuntimeProfileRow` (type): type RuntimeProfileRow = { userId: string; gameId: string; player: RuntimePlayerRow; updatedAt: number; } — ⚠ undocumented
 - `RuntimeServerRow` (type): type RuntimeServerRow = { entities: RuntimeEntityRow[]; objects: RuntimeObjectRow[]; session: Record<string, unknown>; feeds?: Record<string, unknown[]>; } — ⚠ undocumented

package/skills/jgengine/capabilities.md

@@ -100,6 +100,18 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `ws` (function) · `import { ws } from "@jgengine/core/runtime/adapter"`
 
+## object-slot-inventory — placed objects hold validated per-instance container contents that replicate and save with the placement
+
+- `SceneObjectSlots` (interface) · `import { SceneObjectSlots } from "@jgengine/core/runtime/context/objectSlots"`
+
+## placed-object-rehydrate — rebuild live placed objects, with their state and slot contents, from persisted snapshot rows
+
+- `fromRuntimeObjectRow` (function) · `import { fromRuntimeObjectRow } from "@jgengine/core/runtime/objectRows"`
+
+## placed-object-rows — a placed object's per-instance state and container contents convert to and from the persisted snapshot row a host stores
+
+- `toRuntimeObjectRow` (function) · `import { toRuntimeObjectRow } from "@jgengine/core/runtime/objectRows"`
+
 ## render-fallback-diagnostics — Enable/disable the dev-only placeholder-fallback probe.
 
 - `armFallbackSeams` (function) · `import { armFallbackSeams } from "@jgengine/core/devtools/fallbackSeams"`

package/skills/jgengine-gameplay/api.md

@@ -695,7 +695,8 @@
 - `EntitySpriteConfig` (interface): interface EntitySpriteConfig — ⚠ undocumented
 - `FirstPersonCameraConfig` (interface): interface FirstPersonCameraConfig — ⚠ undocumented
 - `GameCameraConfig` (interface): interface GameCameraConfig — Camera tuning for the shell's rig stack: pick the rig via `rig`, then tune it through its matching config block. All fields optional — the default is the third-person orbit rig.
-- `GameCaptureConfig` (interface): interface GameCaptureConfig — How a screenshot host reaches live gameplay in this game — the data behind `shoot --mode play`.
+- `GameCaptureConfig` (interface): interface GameCaptureConfig — How a game makes itself screenshottable: the commands that reach live play or a named screen, the framings worth re-capturing, and the progress metrics a bot playtest samples. Declaring these once is what lets a capture host reproduce a view instead of re-deriving it by hand every run.
+- `GameCaptureView` (interface): interface GameCaptureView — How a screenshot host reaches live gameplay in this game — the data behind `shoot --mode play`.
 - `HemisphereLightingConfig` (interface): interface HemisphereLightingConfig — ⚠ undocumented
 - `InspectionCameraConfig` (interface): interface InspectionCameraConfig — Model-viewer / inspection rig (#207.7) — orbit + pan + anchored zoom around a fixed point, never reads player input.
 - `InspectionZoomAnchor` (type): type InspectionZoomAnchor = "target" | "cursor" | "center" — How scroll-zoom re-anchors the view for the inspection rig (#207.7): - `target` — dolly toward the orbit target (classic OrbitControls behavior). - `cursor` — dolly toward the point under the pointer. - `center` — dolly toward the viewport center; equivalent to `target` for an OrbitControls-driven rig, since the camera always faces `target` and that point already projects to the exact center of the viewport.

package/skills/jgengine-world/SKILL.md

@@ -14,6 +14,7 @@ Search [capabilities.md](capabilities.md) by intent before designing a primitive
 For a *connected* walkthrough that wires several primitives into a running loop, read the goal-oriented recipes under [recipes/](recipes/) — organized by composition seam (what connects to what), never by genre. Start there before reading a game's source to learn how pieces fit; a hybrid game is just a different composition of the same primitives.
 
 - [recipes/commanding-entities.md](recipes/commanding-entities.md) — select → order → tick → resolve: direct command over a group of entities (the command loop behind squad control, base-defense, herding, autobattle, or a mutating game's real-time phase).
+- [recipes/building-kit.md](recipes/building-kit.md) — bind the facade generator's part slots to real models: one massing, swappable art per style, blocks where the kit is silent.
 
 ## Canonical workflows
 
@@ -32,6 +33,10 @@ A world is the place you play in: substrate + laws, via `world()` from `@jgengin
 
 Choose input intent, controller/motor, collision/navigation, and camera as separate seams. Commands express game intent; world systems resolve motion. Interaction targets come from bounded spatial/sensor queries, not full-world scans.
 
+### Stateful placed objects
+
+Per-instance state belongs on the placement, not in a game-owned map keyed by `instanceId`. Set `SceneObject.state` (opaque) through `ctx.scene.object.setState`/`patchState`; declare `slotInventory` on the catalog entry and mutate contents through `ctx.scene.object.slots`, which enforces the declared capacity and `accepts`. Both replicate and save with the object through the always-on `objects` snapshot module, and `toRuntimeObjectRow`/`fromRuntimeObjectRow` (`@jgengine/core/multiplayer`) convert to and from the host's persisted rows.
+
 ### AI and navigation
 
 Compose perception, selection, planning/behavior, movement, and lifecycle independently. Inject randomness and scheduling. Use spatial indexes, interest tiers, or bounded candidate sets for scale.

package/skills/jgengine-world/api.md

@@ -223,6 +223,25 @@
 - `notesInWindow` (function): function notesInWindow(theme: MusicTheme, anchorSec: number, fromSec: number, toSec: number): ScheduledNote[] — Pure lookahead scheduler: every note occurrence of `theme` whose onset falls in the half-open window `(fromSec, toSec]`, given the theme's loop-zero at `anchorSec`. Handles any number of loop wraps, so a director calls it once per tick with a non-overlapping window and never double-schedules a note.
 - `themeLoopSeconds` (function): function themeLoopSeconds(theme: MusicTheme): number — Loop length of a theme in seconds.
 
+## @jgengine/core/audio/musicState
+
+- `MusicStateConfig` (interface): interface MusicStateConfig — The tier ladder plus the release margin that keeps a hovering intensity from flapping between tiers.
+- `MusicStateInput` (interface): interface MusicStateInput — The current intensity signal and clock reading for one resolve.
+- `MusicStateResult` (interface): interface MusicStateResult — Next state, the theme that should be playing, and whether this advance is the one that changed it.
+- `MusicStateSnapshot` (interface): interface MusicStateSnapshot — Which tier is playing and when it was entered, on the caller's clock. Serialisable.
+- `MusicTier` (interface): interface MusicTier — Hysteretic music-state selector: turns a continuous intensity signal (nearby threat, alert count, chase proximity) into a stable theme id. The engine can already crossfade a soundtrack; this decides *when*, without the flapping a bare threshold produces when one enemy walks in and out of range.
+- `createMusicState` (function): function createMusicState(): MusicStateSnapshot — Fresh state with no tier entered, so the first resolve always settles and reports `changed`.
+- `resolveMusicState` (function): function resolveMusicState(state: MusicStateSnapshot, input: MusicStateInput, config: MusicStateConfig): MusicStateResult — Pick the theme for the current intensity. Escalation is immediate; de-escalation waits for the tier's `holdMs` and needs the intensity to fall a `release` margin below the tier it is leaving.
+
+## @jgengine/core/audio/stepCadence
+
+- `StepCadenceConfig` (interface): interface StepCadenceConfig — Distance-driven footstep cadence. Pure state-in/state-out: feed it how far a mover travelled this frame and it tells you how many steps landed, so foley stays locked to ground distance instead of a wall-clock timer that desyncs when speed changes.
+- `StepCadenceInput` (interface): interface StepCadenceInput — What the mover did this advance: ground distance covered, whether feet are planting, and the stride multiplier.
+- `StepCadenceResult` (interface): interface StepCadenceResult — Outcome of one advance: the next state plus how many steps landed and which foot led.
+- `StepCadenceState` (interface): interface StepCadenceState — Cadence bookkeeping between advances — banked distance, last moving state, and the step count whose parity is the foot.
+- `advanceStepCadence` (function): function advanceStepCadence(state: StepCadenceState, input: StepCadenceInput, config: StepCadenceConfig): StepCadenceResult — Bank this advance's distance and report the steps it completed. Pure — same state and input always give the same result, so footstep timing is testable headless and replays identically.
+- `createStepCadenceState` (function): function createStepCadenceState(): StepCadenceState — Fresh cadence state for a mover that is standing still.
+
 ## @jgengine/core/audio/synth
 
 - `NoiseVoice` (interface): interface NoiseVoice — A filtered white-noise burst — impacts, whooshes, breath, crackle. Realised from a shared 1s noise buffer at a randomised playback rate and start offset, decaying exponentially to silence at `duration * decay`.
@@ -1598,7 +1617,7 @@
 - `BoundsSpec` (type): type BoundsSpec = | { readonly kind: "sphere"; readonly radius: number; readonly offset?: Vec3 } | { readonly kind: "aabb"; readonly half: Vec3; readonly offset?: Vec3 } | { readonly kind: "rect"; readonly halfWidth: number; readonly halfDepth: number; readonly halfHeight?: number; readonly offset?:… — How a renderable declares its extent. AABB, bounding sphere, and 2D rectangle cover the common cases; `point` is the degenerate zero-size default for objects that never override. `offset` shifts the volume from the object origin (e.g. a tall model whose pivot is at its feet).
 - `BoxFormationOptions` (interface): interface BoxFormationOptions — Options for {@link boxFormation}.
 - `BuildRole` (type): type BuildRole = "owner" | "editor" | "viewer" — ⚠ undocumented
-- `BuildingEnvironmentDescriptor` (type): type BuildingEnvironmentDescriptor = { kind: "building" } & Required< Pick<BuildingEnvironmentConfig, "count" | "footprint" | "stories" | "storyHeight" | "spacing" | "style"> > & Pick<BuildingEnvironmentConfig, "seed" | "position" | "palette" | "along"> — ⚠ undocumented
+- `BuildingEnvironmentDescriptor` (type): type BuildingEnvironmentDescriptor = { kind: "building" } & Required< Pick<BuildingEnvironmentConfig, "count" | "footprint" | "stories" | "storyHeight" | "spacing" | "style"> > & Pick<BuildingEnvironmentConfig, "seed" | "position" | "palette" | "along" | "kit"> — ⚠ undocumented
 - `BuildingIndex` (interface): interface BuildingIndex — ⚠ undocumented
 - `BuildingPaletteOverrides` (type): type BuildingPaletteOverrides = Partial<BuildingPalette> — ⚠ undocumented
 - `BuildingStyle` (type): type BuildingStyle = | "generic" | "capital" | "village" | "desert" | "industrial" | "coastal" | "neon" | "ruin" | "frontier" | "aerial" — ⚠ undocumented
@@ -1818,6 +1837,9 @@
 - `NoiseFieldConfig` (interface): interface NoiseFieldConfig — Configuration for {@link noiseField}: seed, amplitude, and fractal noise shaping.
 - `NoiseVoice` (interface): interface NoiseVoice — A filtered white-noise burst — impacts, whooshes, breath, crackle. Realised from a shared 1s noise buffer at a randomised playback rate and start offset, decaying exponentially to silence at `duration * decay`.
 - `NoteEvent` (interface): interface NoteEvent — One scheduled note in a theme, positioned on the loop's quarter-note grid.
+- `ObjectSlotRejection` (type): type ObjectSlotRejection = | "unknown-object" | "no-slot-inventory" | "unknown-inventory" | "no-space" | "wrong-kind" | "slot-occupied" | "invalid-slot" | "insufficient" — Why an object slot mutation was refused — the instance, its catalog entry, the player inventory, or the declared `accepts`/capacity.
+- `ObjectSlotResult` (type): type ObjectSlotResult = { status: "ok" } | { status: "rejected"; reason: ObjectSlotRejection } — Outcome of an object slot mutation: applied, or refused with a reason and no state change on either side.
+- `ObjectSlotTransfer` (interface): interface ObjectSlotTransfer — Which player inventory a transfer moves between, and what it moves.
 - `ObjectVisual` (interface): interface ObjectVisual — ⚠ undocumented
 - `OceanEnvironmentDescriptor` (type): type OceanEnvironmentDescriptor = { kind: "ocean" } & Required< Pick<OceanEnvironmentConfig, "bounds" | "level" | "waveHeight" | "waveScale" | "waveSpeed" | "color"> > & Pick<OceanEnvironmentConfig, "position" | "levelAt"> — ⚠ undocumented
 - `Order` (interface): interface Order<TPayload = unknown> — One issued order. Fully serializable: `kind` is a registry key (not a closure), `payload` is the caller's plain data, and `state` is the kind's own plain progress scratch (e.g. a patrol waypoint index) written during `start`/`update`. Never holds functions, so the whole queue round-trips through `JSON`/`structuredClone`.
@@ -1932,6 +1954,7 @@
 - `SceneKindObject` (interface): interface SceneKindObject — The raw document object a resolver receives — shape shared by markers, volumes, and paths.
 - `SceneKindResolveContext` (interface): interface SceneKindResolveContext — Ground sampler + options a resolver may read (terrain height/normal snap).
 - `SceneObject` (interface): interface SceneObject — ⚠ undocumented
+- `SceneObjectSlots` (interface): interface SceneObjectSlots — Per-instance container contents for placed objects whose catalog entry declares `slotInventory` — the engine side of "install a GPU into a rack", "put an item in a chest". Contents live on `SceneObject.slots`, so they replicate and save with the object rather than needing a game-owned table keyed by `instanceId`, and every mutation is validated against the declared `accepts` and stack limits.
 - `SceneRaycastApi` (interface): interface SceneRaycastApi — ⚠ undocumented
 - `SceneRaycastHit` (interface): interface SceneRaycastHit — ⚠ undocumented
 - `ScreenEffect` (interface): interface ScreenEffect — A live effect in the current composite: its label, color, region, and the eased opacity `0..1` to draw *right now*. These objects are pooled and reused across {@link ScreenEffectsController.composite} calls — read them, don't retain.
@@ -2471,6 +2494,18 @@
 - `BuildingIndex` (interface): interface BuildingIndex — ⚠ undocumented
 - `buildingIndex` (function): function buildingIndex(buildings: readonly GeneratedBuilding[]): BuildingIndex — ⚠ undocumented
 
+## @jgengine/core/world/buildingKit
+
+- `BuildingKit` (interface): interface BuildingKit — Binds a building's generated part slots to models. A kit is plain serializable data — scene documents can carry one — and is deliberately unopinionated about art direction: the engine ships the seam, games ship the bindings.
+- `BuildingKitBinding` (type): type BuildingKitBinding = | { readonly type: "model"; readonly part: BuildingKitPart; readonly fit: BuildingKitFit } | { readonly type: "box" } | { readonly type: "omit" } — What a renderer should do with one generated part.
+- `BuildingKitFit` (type): type BuildingKitFit = "stretch" | "contain" | "cover" | "native" — How a kit model's native bounds are mapped onto the slot box `BuildingPartPlacement.scale` describes.
+- `BuildingKitInput` (interface): interface BuildingKitInput — The authoring shape {@link defineBuildingKit} normalizes into a {@link BuildingKit}.
+- `BuildingKitPart` (interface): interface BuildingKitPart — One bindable variant for a building part slot. `model` is an opaque reference the host resolves (an asset id, a pack-relative path, or a URL) — core never loads anything.
+- `BuildingKitPartInput` (type): type BuildingKitPartInput = string | BuildingKitPart — A variant as authored: a bare model reference, or the full {@link BuildingKitPart} when it needs fit or transform tuning.
+- `buildingKitVariantCounts` (function): function buildingKitVariantCounts(kit: BuildingKit): Partial<BuildingVariantCounts> — The variant counts a kit actually supplies, shaped for `BuildingConfigInput.variants`. Feed this into `generateBuilding` so seeded picks spread across exactly the models the kit binds instead of indexing past them and wrapping unevenly.
+- `defineBuildingKit` (function): function defineBuildingKit(input: BuildingKitInput): BuildingKit — Validates and normalizes a kit description, accepting bare model strings as single-field variants. Throws on empty variant lists so a typo fails at authoring time rather than silently falling back to untextured boxes.
+- `resolveBuildingKitPart` (function): function resolveBuildingKitPart(kit: BuildingKit | undefined, kind: BuildingPartKind, slot?: BuildingKitSlot): BuildingKitBinding — Resolves one generated part against a kit. Pass the placement's `kind` and its `kit` slot; the slot's `variant` wraps around the bound list, so a kit may carry any number of variants independent of the generator's `variants` counts.
+
 ## @jgengine/core/world/buildingLots
 
 - `BuildingLotOptions` (interface): interface BuildingLotOptions — Options for {@link deriveBuildingLots}.
@@ -2504,6 +2539,9 @@
 - `DEFAULT_BUILDING_STYLE` (const): const DEFAULT_BUILDING_STYLE: BuildingStyle — ⚠ undocumented
 - `GeneratedBuilding` (interface): interface GeneratedBuilding — ⚠ undocumented
 - `Vec3` (type): type Vec3 = readonly [number, number, number] — ⚠ undocumented
+- `createBuildingConfig` (function): function createBuildingConfig(input: BuildingConfigInput = {}): BuildingConfig — Fill a partial building description out to a complete {@link BuildingConfig}, clamping counts and probabilities. Use it to inspect or adjust the resolved shape before generating.
+- `generateBuilding` (function): function generateBuilding(input: BuildingConfigInput = {}): GeneratedBuilding — Generate one building as a flat list of placed facade parts: bays × floors per facade, a ground row, corners, and a roof, with every decorative part rolled from `probabilities` and every part tagged with a `kit` slot the renderer binds to a model (see `world/buildingKit`). Deterministic from `seed`.
+- `generateBuildingDistrict` (function): function generateBuildingDistrict(config: BuildingGridConfig): GeneratedBuilding[] — Generate a grid of buildings on lots sized by `lotSize` and separated by `streetWidth`, each with its floor count rolled from `floorRange`.
 
 ## @jgengine/core/world/carve
 
@@ -2713,7 +2751,7 @@
 - `BiomeSky` (interface): interface BiomeSky — Per-band sky/light override cross-faded along z by `createBiomeSkySampler`; unset fields fall through to the base sky.
 - `BiomesWorldConfig` (interface): interface BiomesWorldConfig extends WorldGridConfig — ⚠ undocumented
 - `BuildingEnvironmentConfig` (interface): interface BuildingEnvironmentConfig — ⚠ undocumented
-- `BuildingEnvironmentDescriptor` (type): type BuildingEnvironmentDescriptor = { kind: "building" } & Required< Pick<BuildingEnvironmentConfig, "count" | "footprint" | "stories" | "storyHeight" | "spacing" | "style"> > & Pick<BuildingEnvironmentConfig, "seed" | "position" | "palette" | "along"> — ⚠ undocumented
+- `BuildingEnvironmentDescriptor` (type): type BuildingEnvironmentDescriptor = { kind: "building" } & Required< Pick<BuildingEnvironmentConfig, "count" | "footprint" | "stories" | "storyHeight" | "spacing" | "style"> > & Pick<BuildingEnvironmentConfig, "seed" | "position" | "palette" | "along" | "kit"> — ⚠ undocumented
 - `BuildingFrontageConfig` (interface): interface BuildingFrontageConfig — Street-aware placement for `building()`: instead of a grid scattered around `position`, lots are stepped along each road's frontage, offset by a consistent setback (a curb + sidewalk strip), and turned so every building FRONT faces its road. `footprint` (`w` = frontage width, `d` = depth) and `spacing` (along-road gap) are shared with the grid mode. Deterministic and bounded by `maxLots`.
 - `BuildingFrontageRoad` (interface): interface BuildingFrontageRoad — One road a `building({ along })` frontage lines with buildings: centerline + full width.
 - `EnvironmentArea` (interface): interface EnvironmentArea extends WorldBounds — ⚠ undocumented

package/skills/jgengine-world/capabilities.md

@@ -122,6 +122,18 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `createBuildSocketCatalog` (function) · `import { createBuildSocketCatalog } from "@jgengine/core/world/buildSockets"`
 
+## building-generator — generate seeded buildings as placed facade parts — bays, floors, roof, decor
+
+- `createBuildingConfig` (function) · `import { createBuildingConfig } from "@jgengine/core/world/buildings"`
+- `generateBuilding` (function) · `import { generateBuilding } from "@jgengine/core/world/buildings"`
+- `generateBuildingDistrict` (function) · `import { generateBuildingDistrict } from "@jgengine/core/world/buildings"`
+
+## building-kit — bind generated facade part slots to real models instead of untextured blocks
+
+- `buildingKitVariantCounts` (function) · `import { buildingKitVariantCounts } from "@jgengine/core/world/buildingKit"`
+- `defineBuildingKit` (function) · `import { defineBuildingKit } from "@jgengine/core/world/buildingKit"`
+- `resolveBuildingKitPart` (function) · `import { resolveBuildingKitPart } from "@jgengine/core/world/buildingKit"`
+
 ## building-lots — derive street-facing building lots from road frontage
 
 - `deriveBuildingLots` (function) · `import { deriveBuildingLots } from "@jgengine/core/world/buildingLots"`
@@ -354,6 +366,10 @@ Reach for these before hand-rolling. Each row is *the thing you need* → *the p
 
 - `defineMoveOrder` (function) · `import { defineMoveOrder } from "@jgengine/core/world"`
 
+## object-slot-inventory — placed objects hold validated per-instance container contents that replicate and save with the placement
+
+- `SceneObjectSlots` (interface) · `import { SceneObjectSlots } from "@jgengine/core/world"`
+
 ## order-queue — serializable per-entity command queue with lifecycle, preemption, and pluggable order kinds
 
 - `createOrderQueue` (function) · `import { createOrderQueue } from "@jgengine/core/world"`

package/skills/jgengine-world/recipes/building-kit.md

@@ -0,0 +1,78 @@
+# Recipe — dressing generated buildings with a model kit
+
+**What this wires:** the facade generator already emits every part slot a
+building needs — walls, windows, storefronts, awnings, roof clutter. A
+`BuildingKit` binds those slots to real GLBs, so the same massing renders as
+untextured blocks, as a clean prefab town, or as a ruin, purely by swapping the
+bound art.
+
+## Bind a pack to slots
+
+```ts
+import { defineBuildingKit } from "@jgengine/core/world/buildingKit";
+
+const kit = defineBuildingKit({
+  id: "settlement-clean",
+  parts: {
+    wall: ["/models/pack/Wall_Straight.glb", "/models/pack/Wall_Flat.glb"],
+    window: ["/models/pack/Wall_Window.glb"],
+    storefront: ["/models/pack/Door_Metal.glb"],
+    airConditioner: [{ model: "/models/pack/Vent_Big.glb", fit: "contain" }],
+  },
+  omit: ["clothesline"],
+});
+```
+
+A bare string is shorthand for `{ model }`. `fit` decides how the model meets
+its slot box: `stretch` (default) fills the bay — right for tiling panels;
+`contain` keeps a prop's proportions. `defineBuildingKit` throws on an empty
+variant list, so a typo fails at authoring time instead of rendering nothing.
+
+Resolve `model` through your game's asset catalog rather than typing URLs, and a
+missing id fails at boot:
+
+```ts
+const url = assets.resolve("pack/Wall_Straight")?.url;
+```
+
+## Hand it to the world
+
+```ts
+import { building } from "@jgengine/core/world/features";
+
+building({ position: [0, 0], count: 8, style: "desert", kit });
+```
+
+Kinds the kit leaves unbound keep the engine's untextured block, so a partial
+kit is a valid kit — bind walls and windows first, add roof clutter later.
+Kinds listed in `omit` render nothing at all: use it for parts the setting
+rejects, not for parts you have not got around to.
+
+## Two kits, one generator
+
+Bind a second kit with broken panels and welded-shut doors, pass it to the
+zones that should read as derelict, and the generator, seeds, and layout stay
+identical. That split is the point of the seam — style is art binding, not a
+second code path.
+
+## Spread the seeded picks
+
+The generator's `variants` counts decide which slot index each bay asks for. If
+a kit binds a different number of models than the config assumes, picks wrap
+unevenly and one wall model dominates. When you drive the generator directly,
+feed the kit's own counts back in:
+
+```ts
+import { buildingKitVariantCounts } from "@jgengine/core/world/buildingKit";
+import { generateBuilding } from "@jgengine/core/world/buildings";
+
+generateBuilding({ seed: "town-1", variants: buildingKitVariantCounts(kit) });
+```
+
+## Common traps
+
+- Do not bind `roof` to a wall-sized plate; the roof slot is one slab spanning
+  the whole footprint, not a tiling bay.
+- `contain` for anything that must not distort (vents, crates, signs);
+  `stretch` for panels authored to fill a bay.
+- `omit` and "unbound" are different outcomes — unbound still draws a block.