@jgengine/core 0.14.0 → 0.15.0

package/dist/vfx/screenEffects.d.ts

@@ -0,0 +1,149 @@
+/** How a transient effect's intensity curves from peak to zero over its life. */
+export type ScreenEffectEasing = "linear" | "easeIn" | "easeOut" | "easeInOut";
+/**
+ * The screen region an effect tints. `"full"` grades the whole frame (a flash);
+ * `"vignette"` grades only the edges, leaving the center clear (a directional or
+ * ambient border tint). Purely a shape hint for the renderer — no genre meaning.
+ */
+export type ScreenEffectShape = "full" | "vignette";
+/**
+ * One screen-feedback effect, fully data-first so a whole controller serializes.
+ * `kind` is a free label the game assigns and styles ("damage", "heal", "poison",
+ * "boost", …); the model never interprets it. Everything visible is a parameter:
+ * color, peak intensity, region shape, easing, and either a transient duration or
+ * a sustained (optionally oscillating) hold.
+ */
+export interface ScreenEffectSpec {
+    /** Free-string label the game owns; the model treats it as opaque. */
+    kind: string;
+    /** CSS color the region is tinted with (e.g. `"#ff2b2b"`, `"rgb(80,200,120)"`). */
+    color: string;
+    /** Peak opacity `0..1` at full strength. Default `1`. */
+    intensity?: number;
+    /** Which region is tinted. Default `"full"`. */
+    shape?: ScreenEffectShape;
+    /** Intensity curve for a transient effect. Default `"easeOut"`. */
+    easing?: ScreenEffectEasing;
+    /**
+     * Lifetime in ms for a transient effect (ignored when `sustained`). The effect
+     * peaks immediately and eases to zero over this window. Default `400`.
+     */
+    durationMs?: number;
+    /**
+     * When true the effect holds until {@link ScreenEffectsController.clear} instead
+     * of expiring — a low-health tint, a status aura. Default `false`.
+     */
+    sustained?: boolean;
+    /**
+     * Oscillation frequency in Hz for a sustained effect (a pulse). `0` holds steady
+     * at `intensity`; `>0` breathes between `minIntensity` and `intensity`. Ignored
+     * for transient effects. Default `0`.
+     */
+    pulseHz?: number;
+    /** Trough opacity `0..1` a pulsing sustained effect dips to. Default `0`. */
+    minIntensity?: number;
+}
+/**
+ * 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.
+ */
+export interface ScreenEffect {
+    /** Stable id assigned at trigger time (use it to {@link ScreenEffectsController.clear}). */
+    id: number;
+    /** The game-owned label from the spec. */
+    kind: string;
+    /** CSS color to tint with. */
+    color: string;
+    /** Region to tint. */
+    shape: ScreenEffectShape;
+    /** Current eased opacity `0..1`. */
+    intensity: number;
+}
+/** A persisted effect record (all spec fields resolved plus its start time and id). */
+export interface StoredScreenEffect {
+    id: number;
+    kind: string;
+    color: string;
+    shape: ScreenEffectShape;
+    easing: ScreenEffectEasing;
+    intensity: number;
+    durationMs: number;
+    sustained: boolean;
+    pulseHz: number;
+    minIntensity: number;
+    /** Clock time (ms) the effect started, for elapsed-time evaluation. */
+    startAt: number;
+}
+/** Serializable state of every active effect, for save/restore and replay. */
+export interface ScreenEffectsSnapshot {
+    /** Wall-clock (ms) the snapshot was taken, so restore re-anchors elapsed time. */
+    now: number;
+    /** Next id to hand out. */
+    nextId: number;
+    /** Every active effect, transient and sustained. */
+    effects: readonly StoredScreenEffect[];
+}
+/** A live, clock-driven screen-feedback controller. */
+export interface ScreenEffectsController {
+    /**
+     * Trigger a transient full-screen flash. Convenience for {@link trigger} with
+     * `shape: "full"`. Returns the new effect id.
+     */
+    flash(kind: string, spec: Omit<ScreenEffectSpec, "kind" | "shape" | "sustained">): number;
+    /**
+     * Trigger a transient edge vignette. Convenience for {@link trigger} with
+     * `shape: "vignette"`. Returns the new effect id.
+     */
+    vignette(kind: string, spec: Omit<ScreenEffectSpec, "kind" | "shape" | "sustained">): number;
+    /**
+     * Start a sustained pulse that holds until {@link clear}. Convenience for a
+     * sustained effect; pass `pulseHz > 0` to breathe. Returns the new effect id.
+     */
+    pulse(kind: string, spec: Omit<ScreenEffectSpec, "kind" | "sustained">): number;
+    /** Trigger any effect from a full spec. Returns the new effect id. */
+    trigger(spec: ScreenEffectSpec): number;
+    /** Remove one effect by id (typically a sustained one). No-op if unknown. */
+    clear(id: number): void;
+    /** Remove every active effect. */
+    clearAll(): void;
+    /**
+     * Re-evaluate every effect against the clock: recompute eased intensities, reap
+     * expired transients, and notify subscribers. Allocation-free on the hot path.
+     * Pass an explicit `nowMs` to drive deterministically, else the injected clock.
+     */
+    advance(nowMs?: number): void;
+    /**
+     * The current composite: active effects with their eased `intensity`. The array
+     * and its entries are pooled and overwritten on the next call — do not retain.
+     */
+    composite(): readonly ScreenEffect[];
+    /** Number of active effects. */
+    active(): number;
+    /** Observe changes (trigger, clear, advance). Returns an unsubscribe fn. */
+    subscribe(listener: () => void): () => void;
+    /** Serializable state for a save. */
+    snapshot(): ScreenEffectsSnapshot;
+    /** Restore from a {@link ScreenEffectsSnapshot}. */
+    restore(snapshot: ScreenEffectsSnapshot): void;
+}
+/** Options for {@link createScreenEffects}. */
+export interface ScreenEffectsOptions {
+    /** Injected clock (ms). Default `Date.now`. */
+    now?: () => number;
+}
+/**
+ * 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 declare function createScreenEffects(options?: ScreenEffectsOptions): ScreenEffectsController;

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[];