@jgengine/core 0.17.0 → 0.18.1

package/dist/time/rateWindow.d.ts

@@ -0,0 +1,16 @@
+/** Maximum accepted operations in a sliding duration. */
+export interface RateWindowPolicy {
+    windowMs: number;
+    max: number;
+}
+/** Admission result, next stored timestamps, and wait before retrying. */
+export interface RateWindowDecision {
+    allowed: boolean;
+    timestamps: number[];
+    retryAfterMs: number;
+}
+/**
+ * A sliding rate window; persist timestamps only alongside the accepted operation.
+ * @capability rate-window-policy Evaluate deterministic request windows with retry timing.
+ */
+export declare function decideRateWindow(timestamps: readonly number[], nowMs: number, policy: RateWindowPolicy): RateWindowDecision;

package/dist/time/rateWindow.js

@@ -0,0 +1,14 @@
+/**
+ * A sliding rate window; persist timestamps only alongside the accepted operation.
+ * @capability rate-window-policy Evaluate deterministic request windows with retry timing.
+ */
+export function decideRateWindow(timestamps, nowMs, policy) {
+    if (!Number.isFinite(nowMs) || !Number.isFinite(policy.windowMs) || policy.windowMs <= 0 ||
+        !Number.isSafeInteger(policy.max) || policy.max < 1)
+        throw new RangeError("Invalid rate window policy");
+    const active = timestamps.filter((at) => Number.isFinite(at) && at > nowMs - policy.windowMs).sort((a, b) => a - b);
+    if (active.length >= policy.max) {
+        return { allowed: false, timestamps: active, retryAfterMs: Math.max(0, active[active.length - policy.max] + policy.windowMs - nowMs) };
+    }
+    return { allowed: true, timestamps: [...active, nowMs], retryAfterMs: 0 };
+}

package/dist/time/serverTick.d.ts

@@ -2,11 +2,26 @@ export interface TickSystemDefinition<TSystemId extends string = string> {
     id: TSystemId;
     /** Minimum real time between runs; the heartbeat fires the system on the first tick at or past it. */
     intervalMs: number;
+    scope?: "onlinePlayers" | "allServers";
+    batchSize?: number;
 }
 /** Last-run timestamp per system id. */
 export type TickAnchors = Record<string, number>;
+/** One due system and how many times this heartbeat owes it. */
+export interface TickSystemRun<TSystemId extends string = string> {
+    id: TSystemId;
+    /** Times to run the system now; above 1 when wall time stalled past several intervals. */
+    runs: number;
+    scope?: "onlinePlayers" | "allServers";
+    batchSize?: number;
+}
 export interface ServerTickPlan<TSystemId extends string = string> {
-    due: TSystemId[];
+    /**
+     * Due systems, at most one entry per id. `runs` carries catch-up multiplicity — the anchors were
+     * advanced by that many intervals, so a host that runs the handler once per entry silently drops
+     * the rest.
+     */
+    due: TickSystemRun<TSystemId>[];
     anchors: TickAnchors;
 }
 export type PlanServerTickOptions = {
@@ -15,8 +30,11 @@ export type PlanServerTickOptions = {
 };
 /**
  * Decides which systems a heartbeat should run. A system with no anchor runs immediately.
- * When wall time stalls past multiple intervals, the system id is repeated (bounded by
- * maxCatchUp). Excess lag past the bound resyncs the anchor to `now`.
+ * When wall time stalls past multiple intervals the system's `runs` climbs (bounded by
+ * maxCatchUp), and the returned anchor moves by that many intervals — so a host that ignores
+ * `runs` loses the catch-up work. Excess lag past the bound resyncs the anchor to `now`.
  * Returned anchors carry only systems present in the pipeline, so removed systems clean up.
  */
 export declare function planServerTick<TSystemId extends string>(systems: readonly TickSystemDefinition<TSystemId>[], anchors: TickAnchors, now: number, options?: PlanServerTickOptions): ServerTickPlan<TSystemId>;
+/** Times this plan owes `id`, or 0 when it is not due. Saves a host a lookup over {@link ServerTickPlan.due}. */
+export declare function tickRunCount<TSystemId extends string>(plan: ServerTickPlan<TSystemId>, id: TSystemId): number;

package/dist/time/serverTick.js

@@ -1,8 +1,9 @@
 const DEFAULT_MAX_CATCH_UP = 3;
 /**
  * Decides which systems a heartbeat should run. A system with no anchor runs immediately.
- * When wall time stalls past multiple intervals, the system id is repeated (bounded by
- * maxCatchUp). Excess lag past the bound resyncs the anchor to `now`.
+ * When wall time stalls past multiple intervals the system's `runs` climbs (bounded by
+ * maxCatchUp), and the returned anchor moves by that many intervals — so a host that ignores
+ * `runs` loses the catch-up work. Excess lag past the bound resyncs the anchor to `now`.
  * Returned anchors carry only systems present in the pipeline, so removed systems clean up.
  */
 export function planServerTick(systems, anchors, now, options) {
@@ -10,14 +11,12 @@ export function planServerTick(systems, anchors, now, options) {
     const due = [];
     const nextAnchors = {};
     for (const system of systems) {
+        if (system.batchSize !== undefined && (!Number.isSafeInteger(system.batchSize) || system.batchSize < 1 || system.batchSize > 1000))
+            throw new RangeError("batchSize must be an integer from 1 to 1000");
+        const dispatch = { ...(system.scope === undefined ? {} : { scope: system.scope }), ...(system.batchSize === undefined ? {} : { batchSize: system.batchSize }) };
         const lastRunAt = anchors[system.id];
-        if (lastRunAt === undefined) {
-            due.push(system.id);
-            nextAnchors[system.id] = now;
-            continue;
-        }
-        if (system.intervalMs <= 0) {
-            due.push(system.id);
+        if (lastRunAt === undefined || system.intervalMs <= 0) {
+            due.push({ id: system.id, runs: 1, ...dispatch });
             nextAnchors[system.id] = now;
             continue;
         }
@@ -28,14 +27,16 @@ export function planServerTick(systems, anchors, now, options) {
         }
         const missed = Math.floor(elapsed / system.intervalMs);
         if (missed > maxCatchUp) {
-            for (let i = 0; i < maxCatchUp; i += 1)
-                due.push(system.id);
+            due.push({ id: system.id, runs: maxCatchUp, ...dispatch });
             nextAnchors[system.id] = now;
             continue;
         }
-        for (let i = 0; i < missed; i += 1)
-            due.push(system.id);
+        due.push({ id: system.id, runs: missed, ...dispatch });
         nextAnchors[system.id] = lastRunAt + missed * system.intervalMs;
     }
     return { due, anchors: nextAnchors };
 }
+/** Times this plan owes `id`, or 0 when it is not due. Saves a host a lookup over {@link ServerTickPlan.due}. */
+export function tickRunCount(plan, id) {
+    return plan.due.find((entry) => entry.id === id)?.runs ?? 0;
+}

package/dist/vfx/particleDirector.d.ts

@@ -0,0 +1,68 @@
+import type { EmitterConfig, Vec3 } from "./particles.js";
+/** How a particle effect composites on screen: `additive` for sparks/fire/glow, `normal` for smoke/dust. */
+export type ParticleBlendHint = "additive" | "normal";
+/** A one-shot burst request — consumed once by the renderer, never serialized. */
+export interface ParticleBurst {
+    /** Monotonic sequence id so a renderer can consume each burst exactly once. */
+    seq: number;
+    config: EmitterConfig;
+    /** Particles to emit immediately. */
+    count: number;
+    blending?: ParticleBlendHint;
+}
+/** Options for {@link ParticleDirector.attach}. */
+export interface ParticleAttachOptions {
+    /** Scene entity id the emitter origin tracks each frame (plus `offset`). */
+    follow?: string;
+    /** World offset from the followed entity (or from the config position when unfollowed). */
+    offset?: Vec3;
+    blending?: ParticleBlendHint;
+}
+/** A keyed continuous emitter owned by the director until detached. */
+export interface ParticleEmitterSpec {
+    id: string;
+    config: EmitterConfig;
+    follow?: string;
+    offset?: Vec3;
+    blending?: ParticleBlendHint;
+}
+/** Serializable director state: the standing emitters (bursts are transient by nature). */
+export interface ParticleDirectorState {
+    nextSeq: number;
+    emitters: ParticleEmitterSpec[];
+}
+/**
+ * The game-side seam for particle effects. Game logic requests one-shot bursts and
+ * standing emitters as plain data; the shell renders them through
+ * `createParticleSystem`/`ParticleField`, applies the graphics-quality particle cap,
+ * and tracks `follow` entities. Nothing here touches a renderer, so commands and
+ * `onTick` systems can drive VFX headlessly and tests can assert the requested effects.
+ */
+export interface ParticleDirector {
+    /** Queue a one-shot burst (impact puff, debris, muzzle smoke). */
+    burst(config: EmitterConfig, count: number, blending?: ParticleBlendHint): void;
+    /** Create or replace a standing emitter under `id` (exhaust, dust plume, torch smoke). */
+    attach(id: string, config: EmitterConfig, options?: ParticleAttachOptions): void;
+    /** Patch a standing emitter's config in place (e.g. scale exhaust rate with speed). */
+    retune(id: string, patch: Partial<EmitterConfig>): void;
+    /** Remove a standing emitter. Unknown ids are ignored. */
+    detach(id: string): void;
+    /** Drop every standing emitter and any unconsumed bursts. */
+    clear(): void;
+    /** The standing emitters, for renderers and assertions. */
+    emitters(): readonly ParticleEmitterSpec[];
+    /** Return and forget the queued bursts — the renderer's consume-once read. */
+    drainBursts(): ParticleBurst[];
+    subscribe(listener: () => void): () => void;
+    snapshot(): ParticleDirectorState;
+    restore(state: ParticleDirectorState): void;
+}
+/**
+ * Create the particle intent registry a `GameContext` exposes as `ctx.particles`.
+ * State is data-only and serializable: standing emitters survive `snapshot`/`restore`,
+ * queued bursts are transient. The renderer subscribes, drains bursts, and mirrors
+ * the emitter list — the director never allocates particle pools itself.
+ *
+ * @capability particle-director game-reachable VFX seam: queue one-shot particle bursts and keyed follow-capable standing emitters as serializable data for the shell to render
+ */
+export declare function createParticleDirector(): ParticleDirector;

package/dist/vfx/particleDirector.js

@@ -0,0 +1,81 @@
+/**
+ * Create the particle intent registry a `GameContext` exposes as `ctx.particles`.
+ * State is data-only and serializable: standing emitters survive `snapshot`/`restore`,
+ * queued bursts are transient. The renderer subscribes, drains bursts, and mirrors
+ * the emitter list — the director never allocates particle pools itself.
+ *
+ * @capability particle-director game-reachable VFX seam: queue one-shot particle bursts and keyed follow-capable standing emitters as serializable data for the shell to render
+ */
+export function createParticleDirector() {
+    let nextSeq = 1;
+    let bursts = [];
+    const emitters = new Map();
+    const listeners = new Set();
+    function notify() {
+        for (const listener of listeners)
+            listener();
+    }
+    return {
+        burst(config, count, blending) {
+            const wanted = Math.floor(count);
+            if (wanted <= 0)
+                return;
+            bursts.push({ seq: nextSeq++, config, count: wanted, ...(blending === undefined ? {} : { blending }) });
+            notify();
+        },
+        attach(id, config, options) {
+            emitters.set(id, {
+                id,
+                config,
+                ...(options?.follow === undefined ? {} : { follow: options.follow }),
+                ...(options?.offset === undefined ? {} : { offset: options.offset }),
+                ...(options?.blending === undefined ? {} : { blending: options.blending }),
+            });
+            notify();
+        },
+        retune(id, patch) {
+            const current = emitters.get(id);
+            if (current === undefined)
+                return;
+            emitters.set(id, { ...current, config: { ...current.config, ...patch } });
+            notify();
+        },
+        detach(id) {
+            if (!emitters.delete(id))
+                return;
+            notify();
+        },
+        clear() {
+            if (emitters.size === 0 && bursts.length === 0)
+                return;
+            emitters.clear();
+            bursts = [];
+            notify();
+        },
+        emitters() {
+            return Array.from(emitters.values());
+        },
+        drainBursts() {
+            if (bursts.length === 0)
+                return [];
+            const drained = bursts;
+            bursts = [];
+            return drained;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        snapshot() {
+            return { nextSeq, emitters: Array.from(emitters.values()) };
+        },
+        restore(state) {
+            nextSeq = state.nextSeq;
+            bursts = [];
+            emitters.clear();
+            for (const spec of state.emitters)
+                emitters.set(spec.id, spec);
+            notify();
+        },
+    };
+}

package/dist/world/buildings.d.ts

@@ -108,6 +108,18 @@ export type BuildingPaletteOverrides = Partial<BuildingPalette>;
 export type BuildingStyle = "generic" | "capital" | "village" | "desert" | "industrial" | "coastal" | "neon" | "ruin" | "frontier" | "aerial";
 export declare const DEFAULT_BUILDING_STYLE: BuildingStyle;
 export declare const BUILDING_STYLE_PALETTES: Record<BuildingStyle, BuildingPalette>;
+/**
+ * Per-style facade-tone family: the wall colours a district spreads across its buildings so
+ * neighbours differ in hue and value while the block stays one palette. Index 0 is the palette's
+ * own `wall`; the rest fan warmer/cooler and lighter/darker around it.
+ */
+export declare const BUILDING_STYLE_WALL_TONES: Record<BuildingStyle, readonly string[]>;
+/**
+ * The facade-tone family for a style — the ramp {@link BUILDING_STYLE_WALL_TONES} keeps, falling
+ * back to the style's single palette wall when a style has no ramp.
+ * @internal
+ */
+export declare function resolveBuildingWallTones(style?: BuildingStyle): readonly string[];
 /** @internal */
 export declare function resolveBuildingPalette(style?: BuildingStyle, overrides?: BuildingPaletteOverrides): BuildingPalette;
 /**

package/dist/world/buildings.js

@@ -181,6 +181,34 @@ export const BUILDING_STYLE_PALETTES = {
         corner: "#c3d0d7",
     },
 };
+/**
+ * Per-style facade-tone family: the wall colours a district spreads across its buildings so
+ * neighbours differ in hue and value while the block stays one palette. Index 0 is the palette's
+ * own `wall`; the rest fan warmer/cooler and lighter/darker around it.
+ */
+export const BUILDING_STYLE_WALL_TONES = {
+    generic: ["#9c8f80", "#736a60", "#b7a894", "#8b8a80", "#c3ac90", "#635c54", "#a1978c"],
+    capital: ["#cfc5ad", "#ac9878", "#e6e0cf", "#a8a698", "#c8b48d", "#847b68", "#ded2b3"],
+    village: ["#b59e7a", "#9c8360", "#c9b895", "#8d7a5f", "#c2a173", "#a8977f", "#d6c3a1"],
+    desert: ["#c9a877", "#b08f61", "#ddc396", "#a4855c", "#d3b98d", "#93764f", "#c6b189"],
+    industrial: ["#7c838f", "#565d69", "#96a0ac", "#68737a", "#8a8173", "#4a5058", "#a0a6ac"],
+    coastal: ["#e8e2d2", "#cfd6d3", "#f1ece0", "#c9c0ac", "#dbe0dc", "#b7b3a3", "#e5d9c4"],
+    neon: ["#1b1b26", "#262233", "#141a24", "#2c2030", "#181f2b", "#221d1f", "#101018"],
+    ruin: ["#6b6156", "#57503f", "#7d7266", "#4f4a44", "#736450", "#8a8072", "#5d5b53"],
+    frontier: ["#7f5539", "#6a462d", "#96684a", "#5c4331", "#8a6540", "#a07a55", "#6f523c"],
+    aerial: ["#dfe7ec", "#c6d2da", "#eef3f6", "#b6c3cb", "#d3dde2", "#a7b7c0", "#e7eef1"],
+};
+/**
+ * The facade-tone family for a style — the ramp {@link BUILDING_STYLE_WALL_TONES} keeps, falling
+ * back to the style's single palette wall when a style has no ramp.
+ * @internal
+ */
+export function resolveBuildingWallTones(style = DEFAULT_BUILDING_STYLE) {
+    const tones = BUILDING_STYLE_WALL_TONES[style];
+    if (tones !== undefined && tones.length > 0)
+        return tones;
+    return [resolveBuildingPalette(style).wall];
+}
 /** @internal */
 export function resolveBuildingPalette(style = DEFAULT_BUILDING_STYLE, overrides) {
     const preset = BUILDING_STYLE_PALETTES[style];
@@ -413,9 +441,21 @@ function pushRoof(parts, config, width, depth) {
     for (let index = 0; index < roofCells; index += 1) {
         if (!chance(config.seed, `roof:prop:${index}`, config.probabilities.roofProp))
             continue;
-        const x = config.center[0] - width / 2 + config.bayWidth * ((index % config.baysWide) + 0.5);
-        const z = config.center[1] - depth / 2 + config.bayWidth * (Math.floor(index / config.baysWide) + 0.5);
-        parts.push(part(config, "roofProp", "roof", [x, height + config.facadeDepth + config.floorHeight * 0.16, z], [config.bayWidth * 0.34, config.floorHeight * 0.32, config.bayWidth * 0.34], `roof:prop:${index}`, { facade: "roof", level: config.floors, bay: index }, ["decor"]));
+        // Plant sized and nudged off its cell centre: props locked to the bay grid at one size read as
+        // a checkerboard of cubes rather than a roof of mechanical units.
+        const wide = hash01(config.seed, `roof:prop:${index}:w`);
+        const tall = hash01(config.seed, `roof:prop:${index}:h`);
+        const propW = config.bayWidth * (0.2 + wide * 0.4);
+        const propD = config.bayWidth * (0.18 + (1 - wide) * 0.36);
+        const propH = config.floorHeight * (0.14 + tall * 0.52);
+        const x = config.center[0] -
+            width / 2 +
+            config.bayWidth * ((index % config.baysWide) + 0.5 + (hash01(config.seed, `roof:prop:${index}:x`) - 0.5) * 0.5);
+        const z = config.center[1] -
+            depth / 2 +
+            config.bayWidth *
+                (Math.floor(index / config.baysWide) + 0.5 + (hash01(config.seed, `roof:prop:${index}:z`) - 0.5) * 0.5);
+        parts.push(part(config, "roofProp", "roof", [x, height + config.facadeDepth + propH / 2, z], [propW, propH, propD], `roof:prop:${index}`, { facade: "roof", level: config.floors, bay: index }, ["decor"]));
     }
 }
 function pushCorners(parts, config, width, depth) {

package/dist/world/cityContent.js

@@ -13,18 +13,18 @@ export const CITY_LOT_CLASSES = [
 /** All filler classes, for validation and interior-pass allow-lists. */
 export const CITY_FILLER_CLASSES = ["garage", "depot"];
 const CLASS_PROFILES = {
-    tower: { width: [16, 24], depth: [14, 20], setbackFactor: 0.3, spacingFactor: 1, floors: [12, 34], backRow: true },
-    slab: { width: [14, 20], depth: [11, 15], setbackFactor: 0.5, spacingFactor: 1, floors: [4, 9], backRow: true },
-    shop: { width: [10, 15], depth: [8, 12], setbackFactor: 0.2, spacingFactor: 0.6, floors: [1, 2], backRow: true },
-    rowhouse: { width: [6, 8.5], depth: [9, 12], setbackFactor: 0.5, spacingFactor: 0.12, floors: [2, 3], backRow: true },
+    tower: { width: [14, 22], depth: [12, 20], setbackFactor: 0.15, spacingFactor: 0.35, floors: [12, 34], backRow: true },
+    slab: { width: [12, 20], depth: [10, 16], setbackFactor: 0.2, spacingFactor: 0.4, floors: [4, 9], backRow: true },
+    shop: { width: [8, 14], depth: [8, 12], setbackFactor: 0.05, spacingFactor: 0.15, floors: [1, 2], backRow: true },
+    rowhouse: { width: [5.5, 8], depth: [9, 13], setbackFactor: 0.2, spacingFactor: 0.05, floors: [2, 3], backRow: true },
     house: { width: [9, 12], depth: [8, 11], setbackFactor: 1, spacingFactor: 1, floors: [1, 2], backRow: true },
     mansion: { width: [18, 26], depth: [14, 20], setbackFactor: 2, spacingFactor: 1.6, floors: [2, 3], backRow: false },
     farmhouse: { width: [11, 14], depth: [9, 12], setbackFactor: 2.8, spacingFactor: 4, floors: [2, 2], backRow: false },
     barn: { width: [12, 16], depth: [9, 13], setbackFactor: 3.6, spacingFactor: 5, floors: [1, 1], backRow: false },
     silo: { width: [5, 6], depth: [5, 6], setbackFactor: 4, spacingFactor: 3, floors: [1, 1], backRow: false },
     // Interior-fill fillers: broad, plain footprints that pack the backs of dense blocks.
-    garage: { width: [18, 26], depth: [16, 22], setbackFactor: 0.3, spacingFactor: 0.4, floors: [2, 6], backRow: true },
-    depot: { width: [20, 30], depth: [18, 26], setbackFactor: 0.4, spacingFactor: 0.5, floors: [1, 2], backRow: true },
+    garage: { width: [16, 24], depth: [14, 20], setbackFactor: 0.2, spacingFactor: 0.3, floors: [2, 6], backRow: true },
+    depot: { width: [18, 28], depth: [16, 24], setbackFactor: 0.25, spacingFactor: 0.35, floors: [1, 2], backRow: true },
 };
 /**
  * Natural frontage-width range (meters) of a class's massing — what the plot-size class bias reads
@@ -131,6 +131,59 @@ function box(offset, size, role, options = {}) {
 function gable(offset, size, rotationY = 0) {
     return { shape: "gable", offset, size, rotationY, role: "roof", grounded: false, banded: false };
 }
+/**
+ * Finish a flat roof at height `top`: a recessed dark deck, a parapet upstand on all four edges,
+ * and seeded rooftop plant (mechanical units, a stair bulkhead, a tank). A city skyline is mostly
+ * roofs seen from above, so every flat-capped class runs through here instead of a bare slab.
+ */
+function flatRoofTop(pieces, width, depth, top, rng) {
+    const rail = Math.min(1.15, 0.55 + rng() * 0.55);
+    const wall = Math.min(0.55, Math.max(0.18, Math.min(width, depth) * 0.035));
+    const innerW = Math.max(0.4, width - wall * 2);
+    const innerD = Math.max(0.4, depth - wall * 2);
+    pieces.push(box([0, top, 0], [innerW, 0.14, innerD], "roof"));
+    pieces.push(box([0, top, (depth - wall) / 2], [width, rail, wall], "trim"));
+    pieces.push(box([0, top, -(depth - wall) / 2], [width, rail, wall], "trim"));
+    pieces.push(box([(width - wall) / 2, top, 0], [wall, rail, innerD], "trim"));
+    pieces.push(box([-(width - wall) / 2, top, 0], [wall, rail, innerD], "trim"));
+    const deck = top + 0.14;
+    const units = innerW * innerD > 110 ? 1 + Math.floor(rng() * 3) : rng() < 0.7 ? 1 : 0;
+    for (let i = 0; i < units; i += 1) {
+        const uw = Math.min(innerW * 0.34, 1.6 + rng() * 2.4);
+        const ud = Math.min(innerD * 0.34, 1.4 + rng() * 2);
+        pieces.push(box([(rng() - 0.5) * Math.max(0, innerW - uw), deck, (rng() - 0.5) * Math.max(0, innerD - ud)], [uw, 0.6 + rng() * 0.9, ud], "roof"));
+    }
+    if (rng() < 0.55) {
+        const bw = Math.min(innerW * 0.34, 2.2 + rng() * 1.6);
+        const bd = Math.min(innerD * 0.36, 2 + rng() * 1.4);
+        pieces.push(box([(rng() - 0.5) * Math.max(0, innerW - bw), deck, (rng() - 0.5) * Math.max(0, innerD - bd)], [bw, 1.9 + rng() * 1.1, bd], "trim"));
+    }
+    if (rng() < 0.4) {
+        const r = Math.min(2.2, Math.min(innerW, innerD) * 0.26);
+        pieces.push({
+            shape: "cylinder",
+            offset: [(rng() - 0.5) * Math.max(0, innerW - r), deck, (rng() - 0.5) * Math.max(0, innerD - r)],
+            size: [r, 1.4 + rng() * 1.2, r],
+            rotationY: 0,
+            role: "trim",
+            grounded: false,
+            banded: false,
+        });
+    }
+}
+/**
+ * Street-level treatment for a commercial frontage: a plinth course wrapping the base, a recessed
+ * dark entrance on the street face, and a canopy over the sidewalk — so floor 1 never reads like
+ * floor 30. `overhang` is the plinth's outward step (0 keeps it flush for terraced classes).
+ */
+function streetLevel(pieces, width, depth, bandHeight, overhang, rng) {
+    pieces.push(box([0, 0, 0], [width + overhang, bandHeight, depth + overhang], "trim", { grounded: true }));
+    const doorW = Math.min(width * 0.32, 3.4);
+    const doorX = (rng() - 0.5) * Math.max(0, width - doorW * 1.6) * 0.5;
+    const face = depth / 2 + overhang / 2;
+    pieces.push(box([doorX, 0, face], [doorW, bandHeight * 0.76, 0.5], "roof", { grounded: true }));
+    pieces.push(box([doorX, bandHeight * 0.8, face + 0.6], [doorW * 1.5, 0.22, 1.3], "accent"));
+}
 /**
  * Compose the massing pieces for one lot. Deterministic per `rng` stream: the same class, size,
  * floors, and stream always yield the identical silhouette. Sizes are in meters, lot-local.
@@ -147,17 +200,22 @@ export function buildLotPieces(cls, width, depth, floors, floorHeight, rng) {
                 const h2 = H * (0.24 + rng() * 0.08);
                 const h3 = H - h1 - h2;
                 pieces.push(box([0, 0, 0], [width, h1, depth], "wall", { grounded: true, banded: true }));
+                // Occasional attached wing breaks the identical-rect streetwall without replacing the shaft.
+                if (width >= 16 && depth >= 14 && rng() < 0.42) {
+                    const wingW = width * (0.34 + rng() * 0.1);
+                    const side = rng() < 0.5 ? 1 : -1;
+                    pieces.push(box([side * (width / 2 - wingW / 2), 0, depth * 0.28], [wingW, h1 * (0.55 + rng() * 0.2), depth * 0.42], "wall", { grounded: true, banded: true }));
+                }
                 const w2 = width * (0.78 + rng() * 0.08);
                 const d2 = depth * (0.78 + rng() * 0.08);
                 pieces.push(box([0, h1, 0], [w2, h2, d2], "wall", { banded: true }));
                 const w3 = width * (0.55 + rng() * 0.1);
                 const d3 = depth * (0.55 + rng() * 0.1);
                 pieces.push(box([0, h1 + h2, 0], [w3, h3, d3], "wall", { banded: true }));
-                pieces.push(box([0, H, 0], [w3 * 1.04, 0.5, d3 * 1.04], "trim"));
+                flatRoofTop(pieces, w3 * 1.04, d3 * 1.04, H, rng);
                 if (rng() < 0.35)
                     pieces.push(box([0, H + 0.5, 0], [1.2, 3 + rng() * 5, 1.2], "trim"));
-                else if (rng() < 0.5)
-                    pieces.push(box([0, H + 0.5, 0], [w3 * 0.4, 1.6, d3 * 0.4], "roof"));
+                streetLevel(pieces, width, depth, Math.min(floorHeight * 1.1, H * 0.5), 0.35, rng);
             }
             else {
                 const h1 = H * (0.66 + rng() * 0.1);
@@ -165,32 +223,58 @@ export function buildLotPieces(cls, width, depth, floors, floorHeight, rng) {
                 const w2 = width * (0.72 + rng() * 0.1);
                 const d2 = depth * (0.72 + rng() * 0.1);
                 pieces.push(box([0, h1, 0], [w2, H - h1, d2], "wall", { banded: true }));
-                pieces.push(box([0, H, 0], [w2 * 1.05, 0.45, d2 * 1.05], "trim"));
+                flatRoofTop(pieces, w2 * 1.05, d2 * 1.05, H, rng);
+                streetLevel(pieces, width, depth, Math.min(floorHeight * 1.1, H * 0.5), 0.35, rng);
             }
             return pieces;
         }
         case "slab": {
-            pieces.push(box([0, 0, 0], [width, H, depth * 0.95], "wall", { grounded: true, banded: true }));
-            pieces.push(box([0, H, 0], [width * 1.02, 0.35, depth * 0.97], "trim"));
-            if (rng() < 0.6)
-                pieces.push(box([(rng() - 0.5) * width * 0.4, H + 0.35, 0], [width * 0.22, 2, depth * 0.3], "roof"));
+            // Full streetwall depth; irregular plans break the identical-cell silhouette.
+            if (width >= 14 && depth >= 12 && rng() < 0.55) {
+                const wing = width * (0.38 + rng() * 0.14);
+                const side = rng() < 0.5 ? 1 : -1;
+                const frontH = H * (0.92 + rng() * 0.12);
+                const wingH = H * (0.7 + rng() * 0.25);
+                pieces.push(box([0, 0, depth * 0.08], [width, frontH, depth * 0.62], "wall", { grounded: true, banded: true }));
+                pieces.push(box([side * (width / 2 - wing / 2), 0, -depth * 0.08], [wing, wingH, depth * 0.82], "wall", { grounded: true, banded: true }));
+                flatRoofTop(pieces, width * 0.98, depth * 0.62, frontH, rng);
+                if (rng() < 0.45)
+                    flatRoofTop(pieces, wing * 1.02, depth * 0.78, wingH, rng);
+                streetLevel(pieces, width, depth * 0.62, Math.min(floorHeight * 1.05, frontH * 0.5), 0.25, rng);
+            }
+            else if (width >= 16 && depth >= 14 && rng() < 0.35) {
+                // Open mid-block court: street wall + two side wings, rear open as a service yard.
+                const wallT = Math.min(width, depth) * 0.28;
+                pieces.push(box([0, 0, (depth - wallT) / 2], [width, H, wallT], "wall", { grounded: true, banded: true }));
+                pieces.push(box([(width - wallT) / 2, 0, -wallT * 0.15], [wallT, H * (0.75 + rng() * 0.2), depth - wallT], "wall", { grounded: true, banded: true }));
+                pieces.push(box([-(width - wallT) / 2, 0, -wallT * 0.15], [wallT, H * (0.7 + rng() * 0.2), depth - wallT], "wall", { grounded: true, banded: true }));
+                flatRoofTop(pieces, width * 1.01, wallT * 1.02, H, rng);
+                streetLevel(pieces, width, wallT, Math.min(floorHeight * 1.05, H * 0.5), 0.25, rng);
+            }
+            else {
+                pieces.push(box([0, 0, 0], [width, H, depth], "wall", { grounded: true, banded: true }));
+                flatRoofTop(pieces, width * 1.02, depth * 1.02, H, rng);
+                streetLevel(pieces, width, depth, Math.min(floorHeight * 1.05, H * 0.5), 0.25, rng);
+            }
             return pieces;
         }
         case "shop": {
             pieces.push(box([0, 0, 0], [width, H, depth], "wall", { grounded: true }));
-            pieces.push(box([0, H, 0], [width * 1.03, 0.5, depth * 1.03], "trim"));
+            flatRoofTop(pieces, width * 1.03, depth * 1.03, H, rng);
             // Front awning strip over the sidewalk face.
             pieces.push(box([0, Math.min(H - 0.4, 2.6), depth / 2 + 0.35], [width * 0.9, 0.35, 0.9], "accent"));
+            pieces.push(box([0, 0, depth / 2 - 0.05], [width * 0.82, Math.min(H * 0.62, 2.5), 0.4], "roof", { grounded: true }));
             return pieces;
         }
         case "rowhouse": {
-            pieces.push(box([0, 0, 0], [width * 0.96, H, depth * 0.85], "wall", { grounded: true, banded: true }));
+            pieces.push(box([0, 0, 0], [width * 0.98, H, depth * 0.92], "wall", { grounded: true, banded: true }));
             if (rng() < 0.55) {
-                pieces.push(gable([0, H, 0], [width * 0.96, 1.6 + rng() * 0.8, depth * 0.9]));
+                pieces.push(gable([0, H, 0], [width * 0.98, 1.6 + rng() * 0.8, depth * 0.96]));
             }
             else {
-                pieces.push(box([0, H, 0], [width * 1.0, 0.45, depth * 0.9], "trim"));
+                pieces.push(box([0, H, 0], [width * 1.0, 0.45, depth * 0.94], "trim"));
             }
+            streetLevel(pieces, width * 0.98, depth * 0.92, Math.min(floorHeight * 0.95, H * 0.5), 0.04, rng);
             return pieces;
         }
         case "house": {
@@ -273,13 +357,7 @@ export function buildLotPieces(cls, width, depth, floors, floorHeight, rng) {
         case "garage": {
             // Parking structure: a plain banded box (the window bands read as deck slots) with a flat cap.
             pieces.push(box([0, 0, 0], [width, H, depth], "wall", { grounded: true, banded: true }));
-            pieces.push(box([0, H, 0], [width * 1.02, 0.4, depth * 1.02], "trim"));
-            if (rng() < 0.6) {
-                // Stair/lift core poking above the roof deck.
-                const cx = (rng() - 0.5) * width * 0.5;
-                const cz = (rng() - 0.5) * depth * 0.4;
-                pieces.push(box([cx, H + 0.4, cz], [width * 0.16, 1.6 + rng() * 1.2, depth * 0.16], "accent"));
-            }
+            flatRoofTop(pieces, width * 1.02, depth * 1.02, H, rng);
             return pieces;
         }
         case "depot": {