@jgengine/core 0.13.0 → 0.15.0-next.0

package/dist/vfx/screenEffects.js

@@ -0,0 +1,191 @@
+function clamp01(v) {
+    return v < 0 ? 0 : v > 1 ? 1 : v;
+}
+/** Eased progress `0..1` for a transient effect's decay curve. */
+function easeProgress(t, easing) {
+    const p = clamp01(t);
+    switch (easing) {
+        case "linear":
+            return p;
+        case "easeIn":
+            return p * p;
+        case "easeInOut":
+            return p < 0.5 ? 2 * p * p : 1 - (-2 * p + 2) ** 2 / 2;
+        case "easeOut":
+        default:
+            return 1 - (1 - p) ** 2;
+    }
+}
+const TWO_PI = Math.PI * 2;
+/**
+ * A serializable screen-feedback controller: a game triggers transient flashes and
+ * edge vignettes (a red damage hit, a green heal flash) or sustained, optionally
+ * oscillating tints (a low-health pulse), and reads back a composite of the effects
+ * to draw right now with their eased opacities. It is clock-driven — call
+ * `advance()` each frame against an injected `now` — and allocation-aware: the
+ * composite array and its entries are pooled and reused, so steady-state ticking
+ * never allocates. Nothing here is genre-specific: `kind` is a free label the game
+ * owns and styles, and vignette / flash / pulse are just parameterizations of the
+ * same data (region shape, decay easing, sustained oscillation). A shell overlay
+ * subscribes and renders; `snapshot`/`restore` round-trips through a save.
+ *
+ * @capability screen-effects serializable, pooled screen-feedback controller — transient flash/vignette and sustained low-health-style pulses with eased opacities, free-string kinds the game styles, and snapshot/restore
+ */
+export function createScreenEffects(options = {}) {
+    const now = options.now ?? Date.now;
+    const effects = [];
+    const listeners = new Set();
+    // Pooled composite output — reused across composite() calls, never per-tick allocated.
+    const viewPool = [];
+    const viewOut = [];
+    let nextId = 1;
+    function notify() {
+        for (const listener of listeners)
+            listener();
+    }
+    /** Eased current opacity for one effect at `t` ms clock time. */
+    function evaluate(effect, t) {
+        const elapsed = t - effect.startAt;
+        if (effect.sustained) {
+            if (effect.pulseHz <= 0)
+                return effect.intensity;
+            const phase = (elapsed / 1000) * effect.pulseHz * TWO_PI;
+            const osc = (Math.sin(phase) + 1) / 2; // 0..1
+            return effect.minIntensity + (effect.intensity - effect.minIntensity) * osc;
+        }
+        if (effect.durationMs <= 0)
+            return 0;
+        const progress = elapsed / effect.durationMs;
+        if (progress >= 1)
+            return 0;
+        return effect.intensity * (1 - easeProgress(progress, effect.easing));
+    }
+    function refresh(t) {
+        // Iterate backwards: reap expired transients with swap-remove, no allocation.
+        for (let i = effects.length - 1; i >= 0; i--) {
+            const effect = effects[i];
+            if (!effect.sustained && t - effect.startAt >= effect.durationMs) {
+                const last = effects.length - 1;
+                if (i !== last)
+                    effects[i] = effects[last];
+                effects.pop();
+                continue;
+            }
+            effect.current = evaluate(effect, t);
+        }
+    }
+    function add(spec) {
+        const id = nextId++;
+        const t = now();
+        const effect = {
+            id,
+            kind: spec.kind,
+            color: spec.color,
+            shape: spec.shape ?? "full",
+            easing: spec.easing ?? "easeOut",
+            intensity: clamp01(spec.intensity ?? 1),
+            durationMs: spec.durationMs ?? 400,
+            sustained: spec.sustained ?? false,
+            pulseHz: Math.max(0, spec.pulseHz ?? 0),
+            minIntensity: clamp01(spec.minIntensity ?? 0),
+            startAt: t,
+            current: 0,
+        };
+        effect.current = evaluate(effect, t);
+        effects.push(effect);
+        notify();
+        return id;
+    }
+    return {
+        flash(kind, spec) {
+            return add({ ...spec, kind, shape: "full", sustained: false });
+        },
+        vignette(kind, spec) {
+            return add({ ...spec, kind, shape: "vignette", sustained: false });
+        },
+        pulse(kind, spec) {
+            return add({ shape: "vignette", ...spec, kind, sustained: true });
+        },
+        trigger(spec) {
+            return add(spec);
+        },
+        clear(id) {
+            const index = effects.findIndex((effect) => effect.id === id);
+            if (index === -1)
+                return;
+            const last = effects.length - 1;
+            if (index !== last)
+                effects[index] = effects[last];
+            effects.pop();
+            notify();
+        },
+        clearAll() {
+            if (effects.length === 0)
+                return;
+            effects.length = 0;
+            notify();
+        },
+        advance(nowMs) {
+            refresh(nowMs ?? now());
+            notify();
+        },
+        composite() {
+            viewOut.length = 0;
+            for (let i = 0; i < effects.length; i++) {
+                const effect = effects[i];
+                if (effect.current <= 0)
+                    continue;
+                let view = viewPool[viewOut.length];
+                if (view === undefined) {
+                    view = { id: 0, kind: "", color: "", shape: "full", intensity: 0 };
+                    viewPool[viewOut.length] = view;
+                }
+                view.id = effect.id;
+                view.kind = effect.kind;
+                view.color = effect.color;
+                view.shape = effect.shape;
+                view.intensity = effect.current;
+                viewOut.push(view);
+            }
+            return viewOut;
+        },
+        active() {
+            return effects.length;
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        snapshot() {
+            return {
+                now: now(),
+                nextId,
+                effects: effects.map((effect) => ({
+                    id: effect.id,
+                    kind: effect.kind,
+                    color: effect.color,
+                    shape: effect.shape,
+                    easing: effect.easing,
+                    intensity: effect.intensity,
+                    durationMs: effect.durationMs,
+                    sustained: effect.sustained,
+                    pulseHz: effect.pulseHz,
+                    minIntensity: effect.minIntensity,
+                    startAt: effect.startAt,
+                })),
+            };
+        },
+        restore(snapshot) {
+            effects.length = 0;
+            nextId = snapshot.nextId;
+            const t = now();
+            const drift = t - snapshot.now;
+            for (const stored of snapshot.effects) {
+                const effect = { ...stored, startAt: stored.startAt + drift, current: 0 };
+                effect.current = evaluate(effect, t);
+                effects.push(effect);
+            }
+            notify();
+        },
+    };
+}

package/dist/world/authoredObjects.d.ts

@@ -1,4 +1,7 @@
+import type { ModelAnimationConfig } from "../game/playableGame.js";
 import type { SceneMarkerLike } from "./sceneShapes.js";
+/** A placement's authored rig animation override — the stored `marker.meta.animation` contract (#1274). */
+export type AuthoredAnimation = ModelAnimationConfig | "auto" | "none";
 /**
  * One authored catalog prop resolved from an editor marker — grounded at `x`/`z` with yaw, ready
  * for `ctx.scene.object.place` or {@link placeAuthoredObjects}.
@@ -11,6 +14,12 @@ export interface AuthoredObject {
     instanceId: string;
     /** Extra lift in meters from the marker (`catalogId` field / meta), applied on top of terrain height. */
     verticalOffset: number;
+    /**
+     * Per-placement rig animation override authored at `marker.meta.animation` (#1274), threaded onto the
+     * placed object's `ModelConfig.animation` so the override applies in game. `undefined` when the marker
+     * carries no override — behavior is exactly the catalog-resolved default.
+     */
+    animation?: AuthoredAnimation;
 }
 /** Minimal marker shape {@link resolveAuthoredObjects} reads; any `EditorMarker` satisfies it. */
 export interface AuthoredObjectMarkerLike extends SceneMarkerLike {
@@ -26,6 +35,7 @@ export interface AuthoredObjectPlaceTarget {
     place(catalogId: string, x: number, y: number, z: number, options?: {
         instanceId?: string;
         rotation?: number;
+        animation?: AuthoredAnimation;
         onExisting?: "throw" | "replace" | "keep";
     }): string;
 }
@@ -42,6 +52,14 @@ export interface PlaceAuthoredObjectsOptions {
  * @capability authored-objects place catalog mesh props from an editor document
  */
 export declare function markerCatalogId(marker: AuthoredObjectMarkerLike): string | null;
+/**
+ * The authored per-placement rig animation override stored at `marker.meta.animation` (#1274), or
+ * `undefined` when absent/malformed. `"auto"` / `"none"` pass through as the string modes; any other
+ * object is a `ModelAnimationConfig` the shell applies verbatim (validated at author time in the
+ * editor). Runtime trusts the persisted document here exactly like it trusts position and rotation.
+ * @capability authored-objects per-placement animation override from marker.meta.animation
+ */
+export declare function markerAnimation(marker: AuthoredObjectMarkerLike): AuthoredAnimation | undefined;
 /**
  * Marker kinds that are spawnable entities (materialized by `authoredEntitySpawns`), not static
  * catalog props. {@link resolveAuthoredObjects} skips them by default so a placed `mob`/`boss` is

package/dist/world/authoredObjects.js

@@ -16,6 +16,24 @@ export function markerCatalogId(marker) {
         return marker.catalogId;
     return metaString(marker.meta, "catalogId");
 }
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+ * The authored per-placement rig animation override stored at `marker.meta.animation` (#1274), or
+ * `undefined` when absent/malformed. `"auto"` / `"none"` pass through as the string modes; any other
+ * object is a `ModelAnimationConfig` the shell applies verbatim (validated at author time in the
+ * editor). Runtime trusts the persisted document here exactly like it trusts position and rotation.
+ * @capability authored-objects per-placement animation override from marker.meta.animation
+ */
+export function markerAnimation(marker) {
+    const value = marker.meta?.["animation"];
+    if (value === "auto" || value === "none")
+        return value;
+    if (isRecord(value))
+        return value;
+    return undefined;
+}
 function markerVerticalOffset(marker) {
     const fromMeta = metaNumber(marker.meta, "verticalOffset") ??
         metaNumber(marker.meta, "offsetY") ??
@@ -45,6 +63,7 @@ export function resolveAuthoredObjects(document, options = {}) {
         const catalogId = markerCatalogId(marker);
         if (catalogId === null)
             continue;
+        const animation = markerAnimation(marker);
         out.push({
             catalogId,
             x: marker.position.x,
@@ -52,6 +71,7 @@ export function resolveAuthoredObjects(document, options = {}) {
             rotationY: marker.rotationY ?? 0,
             instanceId: marker.id,
             verticalOffset: markerVerticalOffset(marker),
+            ...(animation === undefined ? {} : { animation }),
         });
     }
     return out;
@@ -70,6 +90,7 @@ export function placeAuthoredObjects(store, objects, sampleHeight, options = {})
         ids.push(store.place(object.catalogId, object.x, y, object.z, {
             instanceId: object.instanceId,
             rotation: object.rotationY,
+            ...(object.animation === undefined ? {} : { animation: object.animation }),
             ...(onExisting === undefined ? {} : { onExisting }),
         }));
     }

package/dist/world/authoredSpawn.js

@@ -1,3 +1,4 @@
+import { readSpawnOverride } from "./spawnOverride.js";
 /** Marker kind {@link authoredSpawnPosition} resolves by default. */
 export const PLAYER_SPAWN_KIND = "player_spawn";
 /**
@@ -8,6 +9,14 @@ export const PLAYER_SPAWN_KIND = "player_spawn";
 export function markersOfKind(document, kind) {
     return document.markers.filter((marker) => marker.kind === kind);
 }
+/**
+ * True when a query targets the *default player spawn* (default kind, no explicit id) — the only
+ * resolution an installed {@link readSpawnOverride} may replace. Marker queries for other kinds or
+ * a named id always read the authored document, so a capture-time override cannot perturb them.
+ */
+function targetsDefaultPlayerSpawn(options) {
+    return options.id === undefined && (options.kind === undefined || options.kind === PLAYER_SPAWN_KIND);
+}
 /**
  * Position of the authored spawn marker as a spawn-ready `[x, y, z]` tuple, or null when the
  * document has none. Reads the first `player_spawn` marker by default, so dragging the marker in
@@ -15,6 +24,11 @@ export function markersOfKind(document, kind) {
  * @capability authored-spawn read spawn points and markers from the editor document
  */
 export function authoredSpawnPosition(document, options = {}) {
+    if (targetsDefaultPlayerSpawn(options)) {
+        const override = readSpawnOverride();
+        if (override !== null)
+            return [override.x, override.y, override.z];
+    }
     const kind = options.kind ?? PLAYER_SPAWN_KIND;
     const marker = options.id === undefined
         ? document.markers.find((entry) => entry.kind === kind)
@@ -29,6 +43,11 @@ export function authoredSpawnPosition(document, options = {}) {
  * @capability authored-spawn read spawn points and markers from the editor document
  */
 export function authoredSpawnRotation(document, options = {}) {
+    if (targetsDefaultPlayerSpawn(options)) {
+        const override = readSpawnOverride();
+        if (override?.rotationY !== undefined)
+            return override.rotationY;
+    }
     const kind = options.kind ?? PLAYER_SPAWN_KIND;
     const marker = options.id === undefined
         ? document.markers.find((entry) => entry.kind === kind)

package/dist/world/buildingLots.d.ts

@@ -11,7 +11,7 @@
  *
  * @capability world-environment lots aligned to and facing road frontage, with a setback sidewalk strip
  */
-import type { Vec2 } from "./cityGeometry.js";
+import { type Vec2 } from "./cityGeometry.js";
 import type { WorldBounds } from "./features.js";
 /** One road the frontage placer lines with buildings: a centerline polyline and its full width. */
 export interface RoadFrontage {
@@ -27,24 +27,50 @@ export interface LotArea {
     /** Half-extents along world x and z. */
     halfExtents: Vec2;
 }
+/** One weighted plot size a frontage can mix in: `w` along the road, `d` into the block. */
+export interface PlotVariant extends WorldBounds {
+    /** Relative pick weight among the variants. Default 1. */
+    weight?: number;
+}
 /** Options for {@link deriveBuildingLots}. */
 export interface BuildingLotOptions {
     /** Roads whose frontage is lined with lots. */
     roads: readonly RoadFrontage[];
-    /** Lot footprint: `w` is frontage width (along the road), `d` is depth (into the block). Default `{ w: 12, d: 10 }`. */
-    footprint?: WorldBounds;
+    /**
+     * Plot size(s): `w` is frontage width (along the road), `d` is depth (into the block). Pass one
+     * {@link WorldBounds} for a uniform district, or a weighted {@link PlotVariant} list to mix plot
+     * sizes along the same frontage — narrow-deep apartment slices beside wide detached-house
+     * parcels beside tight terraces. Variant rolls are seeded per road AND side, so the two sides of
+     * a street can read differently. Default `{ w: 12, d: 10 }`.
+     */
+    footprint?: WorldBounds | readonly PlotVariant[];
     /** Gap between neighbouring lots along a frontage, world units. Default 2. */
     spacing?: number;
     /** Sidewalk strip between the curb (`width / 2`) and the building front, world units. Default 3. */
     setback?: number;
+    /**
+     * Manhattan streetwall dial (0..1). Omit (default) keeps the legacy look byte-for-byte. When set,
+     * frontage is compacted as it rises: the along-road gap between neighbours scales from `spacing` at
+     * `~0.45` down to 0 at 1 (buildings shoulder-to-shoulder), and each lot's frontage width widens by
+     * a modest factor above 0.45 so consecutive lots touch instead of leaving gaps. Below ~0.45 the gap
+     * grows past `spacing`, so a low dial reads sparser than the default. Depth is unchanged. This is
+     * pure frontage compaction; block-interior fill lives in the content pass (`resolveCityLotContent`).
+     */
+    blockFill?: number;
     /** Place lots on both sides of each road. Default true. */
     bothSides?: boolean;
     /** Clip region; lots whose center falls outside are dropped. Omit to keep every lot. */
     area?: LotArea;
     /**
-     * Seed forwarded by callers for parity with other feature configs. Lot GEOMETRY is fully
-     * determined by the roads and dials (so a layout is identical without it); per-building variation
-     * (floors, massing) is seeded downstream where the lots become buildings.
+     * Extra road corridors lots must keep clear of WITHOUT lining them with frontage — service
+     * alleys, lanes, trails. Every lot's full footprint is kept off these (and off `roads`).
+     */
+    avoid?: readonly RoadFrontage[];
+    /**
+     * Seed for the plot-variant rolls when `footprint` is a variant list (identical inputs always
+     * yield the identical layout, with or without it). With a single footprint, lot geometry is
+     * fully determined by the roads and dials; per-building variation (floors, massing) is seeded
+     * downstream where the lots become buildings.
      */
     seed?: string;
     /** Hard cap on emitted lots so a long network stays bounded. Default 400. */
@@ -65,6 +91,20 @@ export interface PlacedBuildingLot {
     /** Distance from the lot's front face to the road centerline (= `width / 2 + setback`). */
     frontDistance: number;
 }
+/**
+ * Frontage-fill reference point: at this dial value the compaction is a no-op (legacy spacing/width),
+ * so callers can leave `blockFill` unset for the classic look and this value reproduces it exactly.
+ */
+export declare const FRONTAGE_FILL_REFERENCE = 0.45;
+/**
+ * Map a `blockFill` dial to frontage compaction factors. `undefined` ⇒ identity (legacy path stays
+ * byte-identical). At {@link FRONTAGE_FILL_REFERENCE} the factors are exactly `{1, 1}`; toward 1 the
+ * gap collapses and lots widen, toward 0 the gap grows (sparser than default). @internal
+ */
+export declare function frontageCompaction(blockFill: number | undefined): {
+    spacingScale: number;
+    widthScale: number;
+};
 /**
  * Yaw that turns the building FRONT (local +z) to face the road. The lot center sits at
  * `roadPoint + outwardNormal * d`, so the road lies along `-outwardNormal` from the center. In the
@@ -74,11 +114,14 @@ export interface PlacedBuildingLot {
  */
 export declare function facingRotation(outwardNormal: Vec2): number;
 /**
- * Derive street-aligned building lots from road frontage. Lots are stepped along each road at
- * `footprint.w + spacing`, offset to each side by `width / 2 + setback + footprint.d / 2`, and
- * turned to face the road. Cross-road overlaps are rejected by a bounded nearest-neighbour test, so
- * two roads meeting at a corner don't stack buildings. Deterministic: identical inputs (including
- * seed) always yield the identical list.
+ * Derive street-aligned building lots (PLOTS) from road frontage. Each side of each road walks the
+ * frontage placing plots at `plot.w + spacing` pitch — rolling the next plot size from the weighted
+ * `footprint` variants when several are given — offset outward by `width / 2 + setback + plot.d / 2`
+ * and turned to face the road. The PLOT CONTRACT is enforced here, exactly: no two plots ever overlap
+ * (true oriented-rect separation with the spacing gap, so corners and curved frontage can't stack
+ * buildings), and no plot footprint ever touches any road corridor in `roads` or `avoid` — not
+ * just its own frontage road. Deterministic: identical inputs (including seed) always yield the
+ * identical list.
  * @capability building-lots derive street-facing building lots from road frontage
  */
 export declare function deriveBuildingLots(options: BuildingLotOptions): PlacedBuildingLot[];

package/dist/world/buildingLots.js

@@ -1,4 +1,39 @@
+/**
+ * Street-aware building placement: derive building LOTS along ROAD FRONTAGE. Given road segments
+ * (centerline + width) and a district area, walk each road by arc length and emit lots on both
+ * sides at a consistent setback — a curb + sidewalk strip — with each lot carrying the yaw that
+ * makes the building FRONT face its road. Unlike `cityBlocks` (which needs a CLOSED street network
+ * to extract planar block faces), this works on a sparse set of segments — the common authoring
+ * case — so buildings line the streets instead of scattering on plinths around a center point.
+ *
+ * Pure seeded math over `cityGeometry` `Vec2` primitives: no rendering, deterministic from the
+ * inputs, bounded by `maxLots`.
+ *
+ * @capability world-environment lots aligned to and facing road frontage, with a setback sidewalk strip
+ */
+import { rectClearsPolyline, rectsSeparated } from "./cityGeometry.js";
+import { seededStreams } from "../random/rng.js";
 const DEFAULT_FOOTPRINT = { w: 12, d: 10 };
+/**
+ * Frontage-fill reference point: at this dial value the compaction is a no-op (legacy spacing/width),
+ * so callers can leave `blockFill` unset for the classic look and this value reproduces it exactly.
+ */
+export const FRONTAGE_FILL_REFERENCE = 0.45;
+/** Modest extra frontage-width growth applied at full fill so consecutive lots touch (edge-to-edge). */
+const FRONTAGE_WIDTH_OVERFILL = 0.1;
+/**
+ * Map a `blockFill` dial to frontage compaction factors. `undefined` ⇒ identity (legacy path stays
+ * byte-identical). At {@link FRONTAGE_FILL_REFERENCE} the factors are exactly `{1, 1}`; toward 1 the
+ * gap collapses and lots widen, toward 0 the gap grows (sparser than default). @internal
+ */
+export function frontageCompaction(blockFill) {
+    if (blockFill === undefined)
+        return { spacingScale: 1, widthScale: 1 };
+    const f = Math.max(0, Math.min(1, blockFill));
+    const spacingScale = (1 - f) / (1 - FRONTAGE_FILL_REFERENCE);
+    const widthScale = 1 + (Math.max(0, f - FRONTAGE_FILL_REFERENCE) / (1 - FRONTAGE_FILL_REFERENCE)) * FRONTAGE_WIDTH_OVERFILL;
+    return { spacingScale, widthScale };
+}
 /** Cumulative arc length of a polyline. */
 function polylineLength(path) {
     let sum = 0;
@@ -45,27 +80,59 @@ export function facingRotation(outwardNormal) {
     return Math.atan2(-outwardNormal[0], -outwardNormal[1]);
 }
 /**
- * Derive street-aligned building lots from road frontage. Lots are stepped along each road at
- * `footprint.w + spacing`, offset to each side by `width / 2 + setback + footprint.d / 2`, and
- * turned to face the road. Cross-road overlaps are rejected by a bounded nearest-neighbour test, so
- * two roads meeting at a corner don't stack buildings. Deterministic: identical inputs (including
- * seed) always yield the identical list.
+ * Derive street-aligned building lots (PLOTS) from road frontage. Each side of each road walks the
+ * frontage placing plots at `plot.w + spacing` pitch — rolling the next plot size from the weighted
+ * `footprint` variants when several are given — offset outward by `width / 2 + setback + plot.d / 2`
+ * and turned to face the road. The PLOT CONTRACT is enforced here, exactly: no two plots ever overlap
+ * (true oriented-rect separation with the spacing gap, so corners and curved frontage can't stack
+ * buildings), and no plot footprint ever touches any road corridor in `roads` or `avoid` — not
+ * just its own frontage road. Deterministic: identical inputs (including seed) always yield the
+ * identical list.
  * @capability building-lots derive street-facing building lots from road frontage
  */
 export function deriveBuildingLots(options) {
-    const footprint = options.footprint ?? DEFAULT_FOOTPRINT;
-    const spacing = Math.max(0, options.spacing ?? 2);
+    const raw = options.footprint ?? DEFAULT_FOOTPRINT;
+    // `blockFill` compaction: widen each lot's frontage and shrink the along-road gap toward a
+    // Manhattan streetwall as the dial rises. Undefined ⇒ identity, so the classic path is untouched.
+    // Compaction composes with plot variants — every variant's frontage widens by the same factor.
+    const { spacingScale, widthScale } = frontageCompaction(options.blockFill);
+    const variants = (Array.isArray(raw) ? raw : [raw])
+        .filter((v) => v.w > 0.5 && v.d > 0.5)
+        .map((v) => ({ w: v.w * widthScale, d: v.d, weight: Math.max(0, v.weight ?? 1) }));
+    if (variants.length === 0)
+        variants.push({ ...DEFAULT_FOOTPRINT, weight: 1 });
+    const totalWeight = variants.reduce((sum, v) => sum + v.weight, 0) || 1;
+    const pickVariant = (roll) => {
+        let cursor = roll * totalWeight;
+        for (const v of variants) {
+            cursor -= v.weight;
+            if (cursor <= 0)
+                return v;
+        }
+        return variants[0];
+    };
+    const spacing = Math.max(0, options.spacing ?? 2) * spacingScale;
     const setback = Math.max(0, options.setback ?? 3);
     const bothSides = options.bothSides ?? true;
     const maxLots = Math.max(0, Math.floor(options.maxLots ?? 400));
-    const step = Math.max(1, footprint.w + spacing);
+    const streams = seededStreams(`plots:${options.seed ?? ""}`);
     const sides = bothSides ? [1, -1] : [1];
-    // Minimum center separation for cross-road de-dup: half the footprint diagonal, a touch under
-    // the along-road step so same-road neighbours are never rejected.
-    const minSep = Math.min(step * 0.95, Math.hypot(footprint.w, footprint.d) * 0.5);
-    const minSep2 = minSep * minSep;
+    const corridors = [];
+    for (const road of options.roads)
+        corridors.push({ path: road.path, half: road.width / 2 });
+    for (const road of options.avoid ?? [])
+        corridors.push({ path: road.path, half: road.width / 2 });
     const lots = [];
     const accepted = [];
+    // Gap grown onto the candidate for the plot-vs-plot separation test. Just under half the
+    // spacing keeps same-road neighbours (spaced exactly `spacing` apart) accepted while anything
+    // closer — corner stacking, inside-of-curve pinches — is rejected. At `spacing` 0 the gap goes
+    // slightly NEGATIVE (a shrink), so exactly-touching plots (terraces, rowhouse walls) are legal:
+    // touching is a valid look, overlapping never is.
+    const gap = spacing * 0.45 - 0.05;
+    // Plots may touch the asphalt edge but never intrude into it; the tiny epsilon keeps an exact
+    // setback-0 front face (touching the corridor boundary) legal.
+    const roadClearanceSlack = 0.02;
     for (let r = 0; r < options.roads.length && lots.length < maxLots; r += 1) {
         const road = options.roads[r];
         if (road.path.length < 2)
@@ -74,44 +141,63 @@ export function deriveBuildingLots(options) {
         if (total < 1e-6)
             continue;
         const front = road.width / 2 + setback;
-        const offset = front + footprint.d / 2;
-        // Center the run so lots sit symmetrically and endpoints keep a half-step margin.
-        const count = Math.max(1, Math.floor(total / step));
-        const startS = (total - (count - 1) * step) / 2;
-        for (let i = 0; i < count && lots.length < maxLots; i += 1) {
-            const s = startS + i * step;
-            const station = stationAt(road.path, s);
-            const [tx, tz] = station.tangent;
-            // Left normal of the tangent (CCW): (-tz, tx). Right side negates it.
-            for (const side of sides) {
-                if (lots.length >= maxLots)
+        // Each side walks its own seeded cursor so variant runs differ across the street — terraces
+        // can face detached houses. With a single variant the walk degenerates to the fixed pitch.
+        for (const side of sides) {
+            const roll = variants.length > 1 ? streams(`road:${r}:side:${side}`) : null;
+            let cursor = spacing / 2 + 0.5;
+            while (cursor < total && lots.length < maxLots) {
+                const plot = roll === null ? variants[0] : pickVariant(roll());
+                if (cursor + plot.w > total - 0.5)
                     break;
+                const s = cursor + plot.w / 2;
+                cursor += plot.w + spacing;
+                const station = stationAt(road.path, s);
+                const [tx, tz] = station.tangent;
+                // Left normal of the tangent (CCW): (-tz, tx). Right side negates it.
                 const nx = -tz * side;
                 const nz = tx * side;
+                const offset = front + plot.d / 2;
                 const cx = station.p[0] + nx * offset;
                 const cz = station.p[1] + nz * offset;
                 if (!inArea(options.area, cx, cz))
                     continue;
+                const rotationY = facingRotation([nx, nz]);
+                const hw = plot.w / 2;
+                const hd = plot.d / 2;
+                const rect = { x: cx, z: cz, hw, hd, angle: rotationY };
+                // Plot-vs-plot: reject any candidate whose rect (grown by the spacing gap) overlaps an
+                // accepted plot — regardless of which road placed it.
+                const grown = { ...rect, hw: hw + gap, hd: hd + gap };
                 let clash = false;
-                for (const [ax, az] of accepted) {
-                    const dx = ax - cx;
-                    const dz = az - cz;
-                    if (dx * dx + dz * dz < minSep2) {
+                for (const other of accepted) {
+                    if (!rectsSeparated(grown, other)) {
                         clash = true;
                         break;
                     }
                 }
                 if (clash)
                     continue;
+                // Plot-vs-road: the full footprint stays off every corridor (frontage roads AND avoid
+                // corridors), so a plot can never straddle a crossing street.
+                let onRoad = false;
+                for (const corridor of corridors) {
+                    if (!rectClearsPolyline(rect, corridor.path, corridor.half - roadClearanceSlack)) {
+                        onRoad = true;
+                        break;
+                    }
+                }
+                if (onRoad)
+                    continue;
                 lots.push({
                     center: [cx, cz],
-                    rotationY: facingRotation([nx, nz]),
-                    footprint: { w: footprint.w, d: footprint.d },
+                    rotationY,
+                    footprint: { w: plot.w, d: plot.d },
                     road: r,
                     side,
                     frontDistance: front,
                 });
-                accepted.push([cx, cz]);
+                accepted.push(rect);
             }
         }
     }