@adatechnology/game-floorplan 0.2.2 → 0.3.1

package/dist/index.d.ts

@@ -1,3 +1,5 @@
+import { DeepPartial } from '@adatechnology/game-contracts';
+
 /** Seeded random helpers. Same seed and key always produce the same stream. */
 type Rng = () => number;
 declare function mulberry32(a: number): Rng;
@@ -5,11 +7,66 @@ declare function hashString(input: string | number): number;
 /** Independent stream for a `(seed, key)` pair. */
 declare const createRng: (seed: string | number, key: string) => Rng;
 
+/** Tools handed to a style recipe. `jit` and `rng` draw from the style's seeded stream: draw order is part of the contract. */
+interface PaletteDraw {
+    rng: Rng;
+    base: [string, number, number, number];
+    H0: number;
+    H1: number;
+    H2: number;
+    jit(v: number, a: number): number;
+    hsl(h: number, s: number, l: number): Hsl;
+}
+interface PaletteEarly {
+    /** Accent mode: true saturates walls, false puts accents on objects. */
+    wallMode: boolean;
+    /** Maximum wall saturation. */
+    sMax: number;
+    /** Facade, wall, gate, roof, ceiling... in insertion order. */
+    roles: Record<string, Hsl>;
+    /** General floor `[h, s, l]` for room types that do not define their own. */
+    generalFloor: [number, number, number];
+}
+interface PaletteStyleDef {
+    /** Legacy stream suffix; defaults to the style id. */
+    seedKey?: string;
+    /** Facade colour table `[labelKey, h, s, l]`. */
+    facadeColors: [string, number, number, number][];
+    /** Draws up to the room colours (before the room loop). */
+    early(d: PaletteDraw): PaletteEarly;
+    /** Draws the object roles (wood, fabrics, metal, ground colours) after the room loop. */
+    late(d: PaletteDraw, e: PaletteEarly): Record<string, Hsl>;
+}
+interface PaletteContext extends PaletteDraw {
+    style: string;
+    sMax: number;
+    wallMode: boolean;
+    generalFloor: [number, number, number];
+}
+interface PaletteOptions {
+    seed?: number | string;
+    style?: string;
+    state?: string;
+}
+type Palette = {
+    meta: {
+        seed: number | string;
+        style: string;
+        state: string;
+        scheme: string;
+        base: string;
+        accentMode: 'wall' | 'object';
+    };
+} & Record<string, number | object>;
+/** Seeded colour-harmony palette: a facade base colour, a harmony scheme, role colours and contrast rules. */
+declare function palette(o?: PaletteOptions): Palette;
+
 /** Axis-aligned rectangle `[u0, v0, u1, v1]`. `u` runs along the facade, `v` from the street to the back. */
 type Rect = [number, number, number, number];
 type Vec2 = [number, number];
 type Weights = Record<string, number>;
-type Json = any;
+/** An open value from a template or a plugin: narrow it before use. */
+type Json = unknown;
 type MeshFront = '+z' | '-z' | '+x' | '-x';
 type Mount = 'ceiling' | 'wall' | 'window' | 'support' | 'floor' | 'roof' | 'ground' | 'wall_top' | (string & {});
 /** How an item is coloured: a palette role, a fixed colour, or a seeded pick from a list. */
@@ -78,6 +135,10 @@ interface SlotDef {
     facing?: FacingRule;
     target?: string;
     slide?: number;
+    /** Parent slot id of an `on`/`inside` slot (copied from `on` when the room's slots are expanded). */
+    parent?: string;
+    /** The slot may sit over door and stair swing zones. */
+    floorFree?: boolean;
     [extra: string]: Json;
 }
 type SlotLibrary = SlotDef[] | ((room: {
@@ -217,7 +278,7 @@ interface TemplateDef {
         veranda?: boolean;
         steelDoor?: boolean;
     };
-    facadeExtra?: (facade: Json, rng: Rng, w: number, d: number, o: FloorplanOptions) => void;
+    facadeExtra?: (facade: Facade, rng: Rng, w: number, d: number, o: FloorplanOptions) => void;
     building?: (w: number, d: number, o: FloorplanOptions) => Json;
     singleFloor?: boolean;
     /** Place tag of the building for finds (`house`, `pharmacy`...). */
@@ -241,14 +302,14 @@ interface TemplateDef {
     reservations?: (plan: Plan) => void;
     /** Own paths from the doors that sit away from the building edge (tents); replaces the generated ones. */
     paths?: (plan: Plan, context: {
-        gates: Json[];
+        gates: PlanGate[];
         setback: number;
         marginLeft: number;
         marginRight: number;
         backyard: number;
         w: number;
         d: number;
-    }) => Json[];
+    }) => LotPath[];
     /** Sides built against a neighbour (`left` / `right`): exempt from the side setback. */
     partyWalls?: ('left' | 'right')[];
     options?: Json;
@@ -294,13 +355,13 @@ interface CarClearance {
 interface ResultExtensionContext {
     plan: Plan;
     /** The result built so far: the plan, the items, the state items and the extensions that ran before. */
-    result: Json;
+    result: FloorplanResult;
     seed: number | string;
     /** Seeded stream of the extension: `createRng(seed, seedKey ?? name)`. */
     rng: Rng;
     options: FloorplanOptions;
 }
-type ResultExtensionRun = (context: ResultExtensionContext) => Json;
+type ResultExtensionRun = (context: ResultExtensionContext) => unknown;
 interface ResultExtensionOptions {
     /** Extensions that must run first. */
     after?: string[];
@@ -384,6 +445,156 @@ interface Room {
     seedKey?: string;
     ground?: string;
 }
+/** Axis a wall or opening runs along: `u` is across the lot (x), `v` is front to back (z). */
+type PlanAxis = 'u' | 'v';
+/** A door placed on a wall of one storey (`Plan.doors`). */
+interface PlanDoor {
+    id: string;
+    floor: number;
+    u: number;
+    v: number;
+    axis: PlanAxis;
+    /** Position of the wall line on the other axis. */
+    pos: number;
+    /** Centre of the door along the wall. */
+    at: number;
+    width: number;
+    /** Room on each side; `b` is `outside` on an exterior door. */
+    a: string;
+    b: string;
+    opensTo: string;
+    exterior: boolean;
+    side: string | null;
+    leaves: number;
+    model: string;
+    type: string;
+    steps: number;
+    hinge: string;
+    /** Swing areas on both sides that furniture keeps clear of. */
+    zones: Rect[];
+    /** Left open (set by a house state). */
+    open?: boolean;
+    /** Blocked shut, e.g. barricaded (set by a house state). */
+    blocked?: boolean;
+}
+/** One straight piece of wall or railing of one storey (`Plan.walls`). */
+interface PlanWall {
+    floor: number;
+    axis: PlanAxis;
+    u0: number;
+    v0: number;
+    u1: number;
+    v1: number;
+    thickness: number;
+    /** Room ids on each face (`outside` for the street side). */
+    sides: [string, string];
+    exterior: boolean;
+    type: 'railing' | 'wall';
+    /** Height in metres (the storey ceiling for a full wall). */
+    h: number;
+}
+/** A window on an exterior wall (`Plan.windows`). */
+interface PlanWindow {
+    id: string;
+    floor: number;
+    u: number;
+    v: number;
+    axis: PlanAxis;
+    pos: number;
+    at: number;
+    width: number;
+    /** Sill and head heights above the storey floor. */
+    y0: number;
+    y1: number;
+    room: string;
+    side: string;
+    /** Boarded up (set by a house state). */
+    boards?: boolean;
+}
+/** A gate in the lot boundary (`Plan.gates`). */
+interface PlanGate {
+    id: string;
+    type: string;
+    model: string;
+    u: number;
+    v: number;
+    axis: PlanAxis;
+    width: number;
+    height: number;
+    side: string;
+    /** What the gate leads to (`door`, `inner_garage`...), or null. */
+    to: string | null;
+    material: string;
+    zones: Rect[];
+    /** Starts open (set by a template or a later pass). */
+    open?: boolean;
+}
+/** A door or a lot gate: anything a path or the furniture fill has to keep clear. */
+type PlanOpening = PlanDoor | PlanGate;
+/** A walkway or driveway across the lot (`Plan.paths`). */
+interface LotPath {
+    id: string;
+    type: 'pedestrian' | 'vehicle' | string;
+    /** Gate the path starts at, or null when it starts at no gate. */
+    from: string | null;
+    to: string;
+    width: number;
+    rects: Rect[];
+    points: Vec2[];
+}
+/** How one side of the lot is closed (wall, fence or railing). */
+interface LotBoundary {
+    type: string;
+    material: string;
+    height: number;
+    top: string;
+    totalHeight: number;
+    thickness: number;
+}
+/** One straight piece of the lot boundary. */
+interface LotPerimeterPiece extends LotBoundary {
+    id: string;
+    side: string;
+    u0: number;
+    v0: number;
+    u1: number;
+    v1: number;
+}
+/** The lot around the building (`Plan.lot`). */
+interface Lot {
+    rect: Rect;
+    setback: number;
+    sideYard: {
+        left: number;
+        right: number;
+    };
+    backyard: number;
+    style: string;
+    zones: Room[];
+    perimeter: LotPerimeterPiece[];
+    gates: PlanGate[];
+    paths: LotPath[];
+    pool: boolean;
+}
+/** The known fields of a facade. */
+interface FacadeFields {
+    style: string;
+    color: {
+        name: string;
+        hex: string;
+    };
+    finish: string;
+    grilles: boolean;
+    roof: string;
+    balcony: boolean;
+    veranda: boolean;
+    steelDoor: boolean;
+    floors: number;
+}
+/** The look of the building from the street (`Plan.facade`); templates may add fields through `facadeExtra`. */
+interface Facade extends FacadeFields {
+    [extra: string]: unknown;
+}
 interface Plan {
     w: number;
     d: number;
@@ -399,13 +610,13 @@ interface Plan {
     }[];
     rooms: Room[];
     zones: Room[];
-    doors: Json[];
-    windows: Json[];
-    walls: Json[];
-    gates: Json[];
-    paths: Json[];
-    lot: Json;
-    facade?: Json;
+    doors: PlanDoor[];
+    windows: PlanWindow[];
+    walls: PlanWall[];
+    gates: PlanGate[];
+    paths: LotPath[];
+    lot: Lot | null;
+    facade?: Facade;
     openPairs: Record<number, [string, string][]>;
     zoning?: ZoningReport;
     /** Lot areas the building keeps out of the fill (set by `TemplateDef.reservations`). */
@@ -419,7 +630,16 @@ interface Plan {
     playerRadius: number;
     carClearance: CarClearance;
 }
-interface Slot {
+/** Where a resolved slot sits inside the room: its cell, facing, the room part and the walls it leans on. */
+interface SlotCell {
+    rect: Rect;
+    f: Vec2;
+    enclosed: string[];
+    R: Rect;
+    size: Vec2;
+}
+/** The known fields of a resolved slot. */
+interface SlotFields {
     id: string;
     room: string;
     floor: number;
@@ -427,11 +647,35 @@ interface Slot {
     anchor: string;
     side: string | null;
     cats: Weights;
+    slide?: number;
+    required: boolean;
+    chance: number;
+    clearance: number;
+    front: string;
+    group: string | null;
+    requires: string | null;
+    /** Parent slot of an `on`/`inside` slot. */
+    on: string | null;
+    target: string | null;
     valid: boolean;
     reason: string | null;
+    x: number;
+    z: number;
+    ry: number;
+    w: number;
+    d: number;
+    frontU: number;
+    frontV: number;
+    aabb: Rect;
+    /** Null on an invalid slot. */
+    _cell: SlotCell | null;
+}
+/** A slot of a room after it has been placed (`resolveSlot`); a library may carry fields of its own. */
+interface Slot extends SlotFields {
     [extra: string]: Json;
 }
-interface PlacedItem {
+/** The known fields of a placed item (`PlacedItem` without its open extras). */
+interface PlacedItemFields {
     id: string;
     type: string;
     category: string;
@@ -447,8 +691,149 @@ interface PlacedItem {
     outdoor: boolean;
     aabb: Rect;
     color?: number | string;
+    /** Facing of the item's front. */
+    frontU?: number;
+    frontV?: number;
+    /** Slot that placed it, and the item it stands on or in. */
+    slot?: string;
+    on?: string | null;
+    mode?: 'on' | 'inside' | null;
+    clearance?: number;
+    flat?: boolean;
+    low?: boolean;
+    decor?: boolean;
+    overhead?: boolean;
+    /** Driver side of a car (unit vector). */
+    driver?: Vec2;
+    carClearance?: CarClearance;
+    /** Storeys a stair or passage room connects, or the id of the item this one serves (a gas cylinder names its stove). */
+    link?: {
+        from: number;
+        to: number;
+    } | string;
+    /** Unrounded footprint used by the fill, dropped from the result. */
+    _r?: Rect;
+    _seedId?: string;
+    /** Where a decor item hangs (`floor`, `wall`...). */
+    mount?: Mount;
+    /** Colour rule set by a plugin; replaced by `color` in the result. */
+    colorSpec?: ItemColor;
+}
+/** An item placed by the fill, a decor pass or a state plugin; plugins may add fields of their own. */
+interface PlacedItem extends PlacedItemFields {
     [extra: string]: Json;
 }
+/** A storey of the result. */
+interface ResultFloor {
+    index: number;
+    label?: string;
+    name?: string;
+    number?: number;
+    y0: number;
+    ceiling: number;
+}
+/** A room of the result, with its first part spread as `u0..v1` and the colour roles of its wall and floor. */
+interface ResultRoom {
+    id: string;
+    type: string;
+    label?: string;
+    name?: string;
+    floor: number;
+    u0: number;
+    v0: number;
+    u1: number;
+    v1: number;
+    parts: Rect[];
+    link: number[] | null;
+    ceiling: number;
+    color: {
+        wall: string;
+        floor: string;
+    };
+}
+/** A gate of the result lot. */
+interface ResultGate extends Omit<PlanGate, 'zones' | 'open'> {
+    open: boolean;
+    color: string;
+}
+/** The lot of the result (null for apartments). */
+interface ResultLot {
+    rect: Rect;
+    setback: number;
+    backyard: number;
+    sideYard: {
+        left: number;
+        right: number;
+    };
+    style: string;
+    pool: boolean;
+    zones: {
+        id: string;
+        type: string;
+        label?: string;
+        name?: string;
+        parts: Rect[];
+        ground?: string;
+    }[];
+    perimeter: (LotPerimeterPiece & {
+        color: string;
+    })[];
+    gates: ResultGate[];
+    paths: LotPath[];
+}
+/** The facade of the result: the plan facade with the palette colour and the colour roles. */
+interface ResultFacade extends Omit<FacadeFields, 'color'> {
+    color: {
+        name?: string;
+        key: string;
+        hex: string;
+    };
+    roles: Record<string, string>;
+    [extra: string]: unknown;
+}
+/** An item of the result: the placed item without its internal fields, with its colour role or value. */
+interface ResultItem extends Omit<PlacedItemFields, '_r' | '_seedId' | 'colorSpec'> {
+    [extra: string]: unknown;
+}
+/** The known fields of a `generate` result. */
+interface FloorplanResultFields {
+    template: string;
+    name: string;
+    use: string;
+    seed: number | string;
+    style: string;
+    state: string;
+    locale?: string;
+    w: number;
+    d: number;
+    floors: ResultFloor[];
+    rooms: ResultRoom[];
+    walls: PlanWall[];
+    doors: PlanDoor[];
+    windows: PlanWindow[];
+    openPairs: [string, string][];
+    facade: ResultFacade;
+    lot: ResultLot | null;
+    items: ResultItem[];
+    stateItems: ResultItem[];
+    colors: Palette;
+    /** Output of `TemplateDef.building`. */
+    building: Json;
+    missing: {
+        room: string;
+        slot: string;
+    }[];
+    /** Storey of an apartment unit. */
+    floorNumber?: number;
+    partyWalls: string[];
+    /** Output of `TemplateDef.config`. */
+    config?: Json;
+    zoning?: ZoningReport;
+}
+/** What `generate` returns. Result extensions add their output under their own name. */
+interface FloorplanResult extends FloorplanResultFields {
+    [extension: string]: unknown;
+}
 interface ZoneDef {
     id: string;
     /** Generic use strings: `residential_single`, `residential_multi`, `commercial`, `mixed`, `industrial`... */
@@ -510,13 +895,39 @@ interface StatePlugin {
     /** Adjusts the palette roles (HSL) before the contrast rules run. */
     adjustPalette?(roles: Record<string, Hsl>): void;
 }
+/** Walkability grid of a room (`createGrid`): cells of `gs` metres, the walkable ones and the entry cells. */
+interface WalkGrid {
+    gs: number;
+    u0: number;
+    v0: number;
+    nx: number;
+    nz: number;
+    inside: Uint8Array;
+    entries: [number, number][];
+    center: [number, number];
+}
+/** Options of `PlacementContext.placeOnFloor`. */
+interface PlaceOnFloorOptions {
+    /** Treat the item as flat (no clearance or walkability check). */
+    flat?: boolean;
+    /** Candidate rectangles to try instead of the corners and walls. */
+    cands?: Rect[];
+    /** Footprint to use instead of the catalogue size. */
+    dim?: readonly number[];
+    /** Try the candidates in order instead of shuffled. */
+    ordered?: boolean;
+    /** Rejects a candidate. */
+    without?: (rect: Rect) => boolean;
+    /** Walkability grid to check instead of the room's. */
+    railing?: WalkGrid;
+}
 interface PlacementContext {
-    make(room: Room, type: string, rect: Rect, front: Vec2, extra?: Json): PlacedItem;
+    make(room: Room, type: string, rect: Rect, front: Vec2, extra?: Partial<PlacedItem>): PlacedItem;
     add(item: PlacedItem): PlacedItem;
-    placeOnFloor(room: Room, type: string, rng: Rng, opts?: Json): Rect | null;
+    placeOnFloor(room: Room, type: string, rng: Rng, opts?: PlaceOnFloorOptions): Rect | null;
     itemsOfRoom(room: Room): PlacedItem[];
     solidsOfRoom(room: Room): Rect[];
-    gridOf(room: Room): Json;
+    gridOf(room: Room): WalkGrid;
     extraSolids: Record<string, Rect[]>;
     roomById(id: string): Room | undefined;
     setIgnored(ids: Set<string> | null): void;
@@ -536,11 +947,11 @@ interface PlacementKit {
     insideUnion(r: Rect, inners: Rect[]): boolean;
     usableParts(room: Room, extra?: number): Rect[];
     zonesOfFloor(plan: Plan, floor: number): Rect[];
-    windowsOfRoom(plan: Plan, room: Room): Json[];
-    windowZone(j: Json, outside?: boolean): Rect;
+    windowsOfRoom(plan: Plan, room: Room): PlanWindow[];
+    windowZone(j: Pick<PlanWindow, 'width' | 'side' | 'u' | 'v' | 'axis'>, outside?: boolean): Rect;
     roomAt(plan: Plan, u: number, v: number, floor: number): Room | null;
-    reachable(grid: Json, solids: Rect[], inflation: number): boolean;
-    createGrid(plan: Plan, room: Room, ignored?: Set<string> | null): Json;
+    reachable(grid: WalkGrid, solids: Rect[], inflation: number): boolean;
+    createGrid(plan: Plan, room: Room, ignored?: Set<string> | null): WalkGrid;
     clearRect(r: Rect, f: Vec2, clearance: number): Rect;
     pickWeighted(rng: Rng, w: Weights): string;
     createRng(seed: number | string, key: string): Rng;
@@ -549,7 +960,7 @@ interface PlacementKit {
     shuffle<T>(a: T[], rng: Rng): T[];
     facingRotation(f: Vec2, type: string): number;
     cutIntervals(intervals: [number, number][], a: number, b: number): [number, number][];
-    blocksWindow(it: FurnitureDef, j: Json, overheadOff?: boolean): boolean;
+    blocksWindow(it: FurnitureDef, j: Pick<PlanWindow, 'y0'>, overheadOff?: boolean): boolean;
 }
 interface DecorPassContext {
     plan: Plan;
@@ -604,7 +1015,8 @@ interface FloorplanLocale {
 interface ViewerLayerContext {
     /** Canvas 2D context, already in CSS pixels. */
     g: CanvasRenderingContext2D;
-    plan: Json;
+    /** The `generate` result being drawn. */
+    plan: FloorplanResult;
     /** Storey being drawn (0 when `all`). */
     floor: number;
     /** All storeys at once (the lot view). */
@@ -629,103 +1041,25 @@ interface ViewerLayer {
     label: string;
     defaultOn?: boolean;
     draw(context: ViewerLayerContext): void;
-    legend?(plan: Json): ViewerLayerLegendEntry[];
-}
-
-/** Tools handed to a style recipe. `jit` and `rng` draw from the style's seeded stream: draw order is part of the contract. */
-interface PaletteDraw {
-    rng: Rng;
-    base: [string, number, number, number];
-    H0: number;
-    H1: number;
-    H2: number;
-    jit(v: number, a: number): number;
-    hsl(h: number, s: number, l: number): Hsl;
-}
-interface PaletteEarly {
-    /** Accent mode: true saturates walls, false puts accents on objects. */
-    wallMode: boolean;
-    /** Maximum wall saturation. */
-    sMax: number;
-    /** Facade, wall, gate, roof, ceiling... in insertion order. */
-    roles: Record<string, Hsl>;
-    /** General floor `[h, s, l]` for room types that do not define their own. */
-    generalFloor: [number, number, number];
-}
-interface PaletteStyleDef {
-    /** Legacy stream suffix; defaults to the style id. */
-    seedKey?: string;
-    /** Facade colour table `[labelKey, h, s, l]`. */
-    facadeColors: [string, number, number, number][];
-    /** Draws up to the room colours (before the room loop). */
-    early(d: PaletteDraw): PaletteEarly;
-    /** Draws the object roles (wood, fabrics, metal, ground colours) after the room loop. */
-    late(d: PaletteDraw, e: PaletteEarly): Record<string, Hsl>;
-}
-interface PaletteContext extends PaletteDraw {
-    style: string;
-    sMax: number;
-    wallMode: boolean;
-    generalFloor: [number, number, number];
-}
-interface PaletteOptions {
-    seed?: number | string;
-    style?: string;
-    state?: string;
+    legend?(plan: FloorplanResult): ViewerLayerLegendEntry[];
 }
-type Palette = {
-    meta: {
-        seed: number | string;
-        style: string;
-        state: string;
-        scheme: string;
-        base: string;
-        accentMode: 'wall' | 'object';
-    };
-} & Record<string, number | object>;
-/** Seeded colour-harmony palette: a facade base colour, a harmony scheme, role colours and contrast rules. */
-declare function palette(o?: PaletteOptions): Palette;
 
 /** What a container holds, from the first registered provider that answers (`null` passes to the next); none answering means nothing. */
 declare function findsFor(query: FindsQuery): readonly FindStack[];
 /** Like `findsFor`, but `null` when no provider answered, so a pack can fall back to its own default. */
 declare function findsAnswer(query: FindsQuery): readonly FindStack[] | null;
 
-declare function registerItem(def: ItemInput): FurnitureDef;
-declare function registerItems(list: ItemInput[]): void;
-declare function registerLibrary(id: string, library: SlotLibrary): void;
-declare function registerLibraryAlias(alias: string, id: string): void;
-declare function registerTemplate<T extends TemplateDef>(t: T): T;
-declare function registerStyle(style: StyleDef): void;
-declare function registerPaletteStyle(id: string, def: PaletteStyleDef): void;
-declare function registerRoomColors(list: RoomColorDef[]): void;
-declare function registerDecorProfile(styleId: string, profile: Json): void;
-declare function registerPass(name: string, run: DecorPass): void;
-declare function registerGroundOverlay(rule: GroundOverlayRule): void;
-declare function registerWallTop(id: string, height: number): void;
-/** Legacy RNG stream names for rooms and items, so seeds recorded before the English ids still reproduce. */
-declare function registerSeedKeys(keys: {
-    rooms?: Record<string, string>;
-    items?: Record<string, string>;
-}): void;
-/** Registers a house state. The engine only ships `normal`. */
-declare function registerState(name: string, plugin: StatePlugin): void;
-/** Default state draw when `options.state` is absent: `{ state: weight }` on its own seeded stream. */
-declare function setStateDistribution(weights: Record<string, number> | null, seedKey?: string): void;
-declare const listStates: () => string[];
-/** Adds a named piece to every result, after the state and before the zoning report; its output lands in `result[name]`. */
-declare function registerResultExtension(name: string, run: ResultExtensionRun, options?: ResultExtensionOptions): void;
-/** Registers who answers what a container holds (the item packs, from phase 3 on). */
-declare function registerFindsProvider(provider: FindsProvider): void;
-/** Adds (or replaces, by id) a layer of the 2D viewer; drawn after the items, before the labels. */
-declare function registerViewerLayer(layer: ViewerLayer): void;
-
+/** A recorded slot: the resolved slot without its internal fields, with the category names only. */
+interface RecordedSlot extends Omit<SlotFields, '_cell' | 'cats'> {
+    cats: string[];
+    [extra: string]: unknown;
+}
 /** Recorded slots (resolved positions) of every storey and of the lot. */
-declare function slots(template: string | TemplateDef, options?: FloorplanOptions): Json[];
+declare function slots(template: string | TemplateDef, options?: FloorplanOptions): RecordedSlot[];
 /** Generates a plan: building, lot, seeded item fill, decor, house state and palette. */
-declare function generate(template: string | TemplateDef, options?: FloorplanOptions): Json;
+declare function generate(template: string | TemplateDef, options?: FloorplanOptions): FloorplanResult;
 /** Validates a result of `generate`; returns a list of messages (empty when valid). */
-declare function validate(result: Json, options?: {
+declare function validate(result: FloorplanResult, options?: {
     locale?: string;
 }): string[];
 /** Size limits and default size of a template (they can depend on options such as `tier`). */
@@ -755,9 +1089,12 @@ declare function listTemplates(locale?: string): {
     floors: number;
     floorRange: [number, number] | null;
     lot: boolean;
-    options: any;
+    options: {};
 }[];
 
+declare const overlaps: (a: Rect, b: Rect, e?: number) => boolean;
+declare function openingZones(u: number, v: number, axis: 'u' | 'v', width: number, depth: number): Rect[];
+
 type Namespace = keyof FloorplanLocale;
 /** Registers (or extends) the strings of a language. Packs call this with their JSON files. */
 declare function registerLocale(code: string, table: FloorplanLocale): void;
@@ -765,9 +1102,111 @@ declare const listLocales: () => string[];
 /** Looks a key up in a namespace. Falls back to English, then to the key itself. `{n}`-style variables are replaced. */
 declare function translate(ns: Namespace, key: string, locale?: string, vars?: Record<string, string | number>): string;
 
-/** Builders for the slot definitions of a room library. */
-declare const slotKit: SlotKit;
+/** Keep-out zone of a window (inside, or outside for the lot). */
+declare function windowZone(j: Pick<PlanWindow, 'width' | 'side' | 'u' | 'v' | 'axis'>, outside?: boolean): Rect;
+/** `overheadOff`: the counter sits under the window without its wall cabinet. */
+declare function blocksWindow(it: Pick<FurnitureDef, 'window' | 'overhead' | 'windowHeight'> & {
+    h: number;
+}, win: Pick<PlanWindow, 'y0'>, overheadOff?: boolean): boolean;
+
+/** All content registries of one engine instance. Content packs fill them through the `register*` functions. */
+type Registries = {
+    CATALOG: Record<string, FurnitureDef>;
+    LIBRARIES: Record<string, SlotLibrary>;
+    LIBRARY_ALIAS: Record<string, string>;
+    TEMPLATES: Record<string, TemplateDef>;
+    STYLES: Record<string, StyleDef>;
+    STYLE_ALIAS: Record<string, string>;
+    PALETTE_STYLES: Record<string, PaletteStyleDef>;
+    ROOM_COLORS: RoomColorDef[];
+    PASSES: {
+        name: string;
+        run: DecorPass;
+    }[];
+    DECOR_PROFILES: Record<string, Json>;
+    GROUND_OVERLAYS: GroundOverlayRule[];
+    STATE_PLUGINS: Record<string, StatePlugin>;
+    WALL_TOP_HEIGHTS: Record<string, number>;
+    SEED_KEYS: {
+        rooms: Record<string, string>;
+        items: Record<string, string>;
+    };
+    stateDistribution: {
+        weights: Record<string, number> | null;
+        seedKey: string;
+    };
+    RESULT_EXTENSIONS: ResultExtension[];
+    FINDS_PROVIDERS: FindsProvider[];
+    VIEWER_LAYERS: ViewerLayer[];
+    LOCALES: Record<string, FloorplanLocale>;
+    ZONES: Record<string, ZoneDef>;
+    PERMEABLE_GROUNDS: Set<string>;
+};
+declare function registerItem(def: ItemInput): FurnitureDef;
+declare function registerItems(list: ItemInput[]): void;
+declare function registerLibrary(id: string, library: SlotLibrary): void;
+declare function registerLibraryAlias(alias: string, id: string): void;
+declare function registerTemplate<T extends TemplateDef>(t: T): T;
+declare function registerStyle(style: StyleDef): void;
+declare function registerPaletteStyle(id: string, def: PaletteStyleDef): void;
+declare function registerRoomColors(list: RoomColorDef[]): void;
+declare function registerDecorProfile(styleId: string, profile: Json): void;
+declare function registerPass(name: string, run: DecorPass): void;
+declare function registerGroundOverlay(rule: GroundOverlayRule): void;
+declare function registerWallTop(id: string, height: number): void;
+/** Legacy RNG stream names for rooms and items, so seeds recorded before the English ids still reproduce. */
+declare function registerSeedKeys(keys: {
+    rooms?: Record<string, string>;
+    items?: Record<string, string>;
+}): void;
+/** Registers a house state. The engine only ships `normal`. */
+declare function registerState(name: string, plugin: StatePlugin): void;
+/** Default state draw when `options.state` is absent: `{ state: weight }` on its own seeded stream. */
+declare function setStateDistribution(weights: Record<string, number> | null, seedKey?: string): void;
+declare const listStates: () => string[];
+interface ResultExtension {
+    name: string;
+    run: ResultExtensionRun;
+    after: string[];
+    seedKey: string;
+}
+/** Adds a named piece to every result, after the state and before the zoning report; its output lands in `result[name]`. */
+declare function registerResultExtension(name: string, run: ResultExtensionRun, options?: ResultExtensionOptions): void;
+/** Registers who answers what a container holds (the item packs, from phase 3 on). */
+declare function registerFindsProvider(provider: FindsProvider): void;
+/** Adds (or replaces, by id) a layer of the 2D viewer; drawn after the items, before the labels. */
+declare function registerViewerLayer(layer: ViewerLayer): void;
 
+/** What the zone checks read from a plan: a generated result or the internal plan. */
+interface ZoneCheckedPlan {
+    floors: {
+        y0: number;
+        ceiling: number;
+    }[];
+    floorNumber?: number | null;
+    rooms?: {
+        floor: number;
+        parts: readonly (readonly number[])[];
+    }[];
+    w: number;
+    d: number;
+    use?: string;
+    partyWalls?: string[];
+}
+/** What the zone checks read from a lot (`result.lot`). */
+interface ZoneCheckedLot {
+    rect: readonly number[];
+    setback: number;
+    sideYard: {
+        left: number;
+        right: number;
+    };
+    backyard: number;
+    zones: {
+        ground?: string;
+        parts: readonly (readonly number[])[];
+    }[];
+}
 /** Registers an urban zone (zoning rules). Returns the stored definition. */
 declare function defineZone(zone: ZoneDef): ZoneDef;
 declare const getZone: (id: string) => ZoneDef | undefined;
@@ -778,17 +1217,106 @@ declare function registerPermeableGround(...types: string[]): void;
  * Checks a generated lot against a zone and returns the violations (empty when compliant).
  * `lot` is `result.lot` (may be null for apartments), `plan` is the result of `generate`.
  */
-declare function checkLot(zoneIn: string | ZoneDef, lot: Json, plan: Json): ZoneViolation[];
+declare function checkLot(zoneIn: string | ZoneDef, lot: ZoneCheckedLot | null | undefined, plan: ZoneCheckedPlan): ZoneViolation[];
 
-declare const overlaps: (a: Rect, b: Rect, e?: number) => boolean;
-declare function openingZones(u: number, v: number, axis: 'u' | 'v', width: number, depth: number): Rect[];
+declare const version = "0.1.0";
+/** Registers `packs` and applies `patch` / `remove` over the catalogs, by id. Items are keyed by `type`, templates by `id`. */
+type CreateFloorplanOptions = {
+    /** Content packs, applied in order: a function `(engine) => void` or an object with `register(engine)`. */
+    readonly packs?: readonly FloorplanPack[];
+    readonly patch?: {
+        readonly items?: Readonly<Record<string, DeepPartial<FurnitureDef>>>;
+        readonly templates?: Readonly<Record<string, DeepPartial<TemplateDef>>>;
+    };
+    readonly remove?: {
+        readonly items?: readonly string[];
+        readonly templates?: readonly string[];
+    };
+};
+type FloorplanPack = ((engine: FloorplanEngine) => void) | {
+    readonly register: (engine: FloorplanEngine) => void;
+};
+declare function buildEngine(scope: Registries): {
+    version: string;
+    generate: typeof generate;
+    slots: typeof slots;
+    validate: typeof validate;
+    palette: typeof palette;
+    limitsOf: typeof limitsOf;
+    listTemplates: typeof listTemplates;
+    listStates: () => string[];
+    registerItem: typeof registerItem;
+    registerItems: typeof registerItems;
+    registerLibrary: typeof registerLibrary;
+    registerLibraryAlias: typeof registerLibraryAlias;
+    registerTemplate: typeof registerTemplate;
+    registerStyle: typeof registerStyle;
+    registerPaletteStyle: typeof registerPaletteStyle;
+    registerRoomColors: typeof registerRoomColors;
+    registerDecorProfile: typeof registerDecorProfile;
+    registerPass: typeof registerPass;
+    registerGroundOverlay: typeof registerGroundOverlay;
+    registerWallTop: typeof registerWallTop;
+    registerSeedKeys: typeof registerSeedKeys;
+    registerState: typeof registerState;
+    setStateDistribution: typeof setStateDistribution;
+    registerLocale: typeof registerLocale;
+    registerResultExtension: typeof registerResultExtension;
+    registerFindsProvider: typeof registerFindsProvider;
+    findsFor: typeof findsFor;
+    findsAnswer: typeof findsAnswer;
+    registerViewerLayer: typeof registerViewerLayer;
+    viewerLayers: ViewerLayer[];
+    blocksWindow: typeof blocksWindow;
+    defineZone: typeof defineZone;
+    getZone: (id: string) => ZoneDef | undefined;
+    listZones: () => ZoneDef[];
+    checkLot: typeof checkLot;
+    registerPermeableGround: typeof registerPermeableGround;
+    slotKit: SlotKit;
+    translate: typeof translate;
+    listLocales: () => string[];
+    templates: Record<string, TemplateDef>;
+    catalog: Record<string, FurnitureDef>;
+    libraries: Record<string, SlotLibrary>;
+    styles: Record<string, StyleDef>;
+    paletteStyles: Record<string, PaletteStyleDef>;
+    createRng: (seed: string | number, key: string) => Rng;
+    mulberry32: typeof mulberry32;
+    hashString: typeof hashString;
+    overlaps: (a: Rect, b: Rect, e?: number) => boolean;
+    windowZone: typeof windowZone;
+    openingZones: typeof openingZones;
+    color: {
+        lstar: (n: number) => number;
+        hex: (n: number) => string;
+        hsl: (n: number) => Hsl;
+        HIGH_SATURATION: number;
+        MIN_WALL_FLOOR_CONTRAST: number;
+        MIN_FABRIC_FLOOR_CONTRAST: number;
+    };
+    constants: {
+        WALL_THICKNESS: number;
+        DOOR_CLEARANCE: number;
+        PLAYER_RADIUS: number;
+        DOOR_EDGE_CLEARANCE: number;
+        WINDOW_EDGE_CLEARANCE: number;
+        OVERHEAD_TOP: number;
+        CAR_CLEARANCE: {
+            readonly driver: 0.8;
+            readonly side: 0.6;
+            readonly end: 0.6;
+        };
+    };
+};
+type FloorplanEngine = ReturnType<typeof buildEngine>;
+/** An engine of its own: registries, zones and locales are not shared with any other engine on the page. */
+declare function createFloorplan(options?: CreateFloorplanOptions): FloorplanEngine;
+/** The engine the global `engine` stands for, created on first use. Content packs of the old `register(engine)` calls fill this one. */
+declare function defaultFloorplan(): FloorplanEngine;
 
-/** Keep-out zone of a window (inside, or outside for the lot). */
-declare function windowZone(j: Json, outside?: boolean): Rect;
-/** `overheadOff`: the counter sits under the window without its wall cabinet. */
-declare function blocksWindow(it: Pick<FurnitureDef, 'window' | 'overhead' | 'windowHeight'> & {
-    h: number;
-}, win: Json, overheadOff?: boolean): boolean;
+/** Builders for the slot definitions of a room library. */
+declare const slotKit: SlotKit;
 
 /** One primitive of a far-away silhouette. Parts are listed in creation order; `parent` is the index of a group part (`-1` is the root). */
 type SilhouettePart = {
@@ -974,84 +1502,10 @@ type DetachedHouseParams = Seeded & {
 /** One-storey detached house; boarded windows get two crossed planks each. */
 declare function createDetachedHouse(p: DetachedHouseParams): Silhouette;
 
-declare const version = "0.1.0";
 /**
- * The engine as a single object. Content packs take it as an argument (`register(engine)`), so that
- * several bundles (ESM or IIFE) always fill the same registries.
+ * The global engine. Content packs take it as an argument (`register(engine)`), so that several bundles (ESM or IIFE) fill the same registries.
+ * @deprecated use `createFloorplan({ packs, patch, remove })`, an engine of its own, or `defaultFloorplan()` for the shared one.
  */
-declare const engine: {
-    version: string;
-    generate: typeof generate;
-    slots: typeof slots;
-    validate: typeof validate;
-    palette: typeof palette;
-    limitsOf: typeof limitsOf;
-    listTemplates: typeof listTemplates;
-    listStates: () => string[];
-    registerItem: typeof registerItem;
-    registerItems: typeof registerItems;
-    registerLibrary: typeof registerLibrary;
-    registerLibraryAlias: typeof registerLibraryAlias;
-    registerTemplate: typeof registerTemplate;
-    registerStyle: typeof registerStyle;
-    registerPaletteStyle: typeof registerPaletteStyle;
-    registerRoomColors: typeof registerRoomColors;
-    registerDecorProfile: typeof registerDecorProfile;
-    registerPass: typeof registerPass;
-    registerGroundOverlay: typeof registerGroundOverlay;
-    registerWallTop: typeof registerWallTop;
-    registerSeedKeys: typeof registerSeedKeys;
-    registerState: typeof registerState;
-    setStateDistribution: typeof setStateDistribution;
-    registerLocale: typeof registerLocale;
-    registerResultExtension: typeof registerResultExtension;
-    registerFindsProvider: typeof registerFindsProvider;
-    findsFor: typeof findsFor;
-    findsAnswer: typeof findsAnswer;
-    registerViewerLayer: typeof registerViewerLayer;
-    viewerLayers: ViewerLayer[];
-    blocksWindow: typeof blocksWindow;
-    defineZone: typeof defineZone;
-    getZone: (id: string) => ZoneDef | undefined;
-    listZones: () => ZoneDef[];
-    checkLot: typeof checkLot;
-    registerPermeableGround: typeof registerPermeableGround;
-    slotKit: SlotKit;
-    translate: typeof translate;
-    listLocales: () => string[];
-    templates: Record<string, TemplateDef>;
-    catalog: Record<string, FurnitureDef>;
-    libraries: Record<string, SlotLibrary>;
-    styles: Record<string, StyleDef>;
-    paletteStyles: Record<string, PaletteStyleDef>;
-    createRng: (seed: string | number, key: string) => Rng;
-    mulberry32: typeof mulberry32;
-    hashString: typeof hashString;
-    overlaps: (a: Rect, b: Rect, e?: number) => boolean;
-    windowZone: typeof windowZone;
-    openingZones: typeof openingZones;
-    color: {
-        lstar: (n: number) => number;
-        hex: (n: number) => string;
-        hsl: (n: number) => Hsl;
-        HIGH_SATURATION: number;
-        MIN_WALL_FLOOR_CONTRAST: number;
-        MIN_FABRIC_FLOOR_CONTRAST: number;
-    };
-    constants: {
-        WALL_THICKNESS: number;
-        DOOR_CLEARANCE: number;
-        PLAYER_RADIUS: number;
-        DOOR_EDGE_CLEARANCE: number;
-        WINDOW_EDGE_CLEARANCE: number;
-        OVERHEAD_TOP: number;
-        CAR_CLEARANCE: {
-            readonly driver: 0.8;
-            readonly side: 0.6;
-            readonly end: 0.6;
-        };
-    };
-};
-type FloorplanEngine = typeof engine;
+declare const engine: FloorplanEngine;
 
-export { type Anchor, type BoundaryRule, type CarClearance, type ChaletParams, type CityBuildingParams, type ColonialParams, type CompanyHouseParams, type DecorPass, type DecorPassContext, type DetachedHouseParams, type DoorDef, type FacingRule, type FarmhouseParams, type FindStack, type FindsProvider, type FindsQuery, type FloorDef, type FloorplanEngine, type FloorplanLocale, type FloorplanOptions, type FurnitureDef, type GateCfg, type GroundOverlayRule, type Hsl, type ItemColor, type ItemInput, type Json, type LotConfig, type MeshFront, type Mount, type PaletteDraw, type PaletteEarly, type PaletteStyleDef, type PlacedItem, type PlacementContext, type PlacementKit, type Plan, type RandomSource, type Rect, type ResultExtensionContext, type ResultExtensionOptions, type ResultExtensionRun, type Room, type RoomColorDef, type RoomDef, type Side, type Silhouette, type SilhouettePart, type SilhouetteWindow, type SlabHouseParams, type Slot, type SlotDef, type SlotKit, type SlotLibrary, type StateContext, type StatePlugin, type StiltHouseParams, type StyleDef, type TemplateDef, type TwoStoreyParams, type Vec2, type ViewerLayer, type ViewerLayerContext, type ViewerLayerLegendEntry, type Weights, type WindowDef, type ZoneAdjustment, type ZoneDef, type ZoneViolation, type ZoningReport, blocksWindow, boxRadius, checkLot, createChalet, createCityBuilding, createColonialHouse, createCompanyHouse, createDetachedHouse, createFarmhouse, createRng, createSilhouetteRandom, createSlabHouse, createStiltHouse, createTwoStoreyHouse, defineZone, engine, findsAnswer, findsFor, generate, getZone, hashString, limitsOf, listLocales, listStates, listTemplates, listZones, mulberry32, openingZones, overlaps, palette, registerDecorProfile, registerFindsProvider, registerGroundOverlay, registerItem, registerItems, registerLibrary, registerLibraryAlias, registerLocale, registerPaletteStyle, registerPass, registerPermeableGround, registerResultExtension, registerRoomColors, registerSeedKeys, registerState, registerStyle, registerTemplate, registerViewerLayer, registerWallTop, setStateDistribution, slotKit, slots, translate, validate, version, windowZone };
+export { type Anchor, type BoundaryRule, type CarClearance, type ChaletParams, type CityBuildingParams, type ColonialParams, type CompanyHouseParams, type CreateFloorplanOptions, type DecorPass, type DecorPassContext, type DetachedHouseParams, type DoorDef, type Facade, type FacadeFields, type FacingRule, type FarmhouseParams, type FindStack, type FindsProvider, type FindsQuery, type FloorDef, type FloorplanEngine, type FloorplanLocale, type FloorplanOptions, type FloorplanPack, type FloorplanResult, type FloorplanResultFields, type FurnitureDef, type GateCfg, type GroundOverlayRule, type Hsl, type ItemColor, type ItemInput, type Json, type Lot, type LotBoundary, type LotConfig, type LotPath, type LotPerimeterPiece, type MeshFront, type Mount, type PaletteDraw, type PaletteEarly, type PaletteStyleDef, type PlaceOnFloorOptions, type PlacedItem, type PlacedItemFields, type PlacementContext, type PlacementKit, type Plan, type PlanAxis, type PlanDoor, type PlanGate, type PlanOpening, type PlanWall, type PlanWindow, type RandomSource, type RecordedSlot, type Rect, type ResultExtensionContext, type ResultExtensionOptions, type ResultExtensionRun, type ResultFacade, type ResultFloor, type ResultGate, type ResultItem, type ResultLot, type ResultRoom, type Room, type RoomColorDef, type RoomDef, type Side, type Silhouette, type SilhouettePart, type SilhouetteWindow, type SlabHouseParams, type Slot, type SlotCell, type SlotDef, type SlotFields, type SlotKit, type SlotLibrary, type StateContext, type StatePlugin, type StiltHouseParams, type StyleDef, type TemplateDef, type TwoStoreyParams, type Vec2, type ViewerLayer, type ViewerLayerContext, type ViewerLayerLegendEntry, type WalkGrid, type Weights, type WindowDef, type ZoneAdjustment, type ZoneCheckedLot, type ZoneCheckedPlan, type ZoneDef, type ZoneViolation, type ZoningReport, blocksWindow, boxRadius, checkLot, createChalet, createCityBuilding, createColonialHouse, createCompanyHouse, createDetachedHouse, createFarmhouse, createFloorplan, createRng, createSilhouetteRandom, createSlabHouse, createStiltHouse, createTwoStoreyHouse, defaultFloorplan, defineZone, engine, findsAnswer, findsFor, generate, getZone, hashString, limitsOf, listLocales, listStates, listTemplates, listZones, mulberry32, openingZones, overlaps, palette, registerDecorProfile, registerFindsProvider, registerGroundOverlay, registerItem, registerItems, registerLibrary, registerLibraryAlias, registerLocale, registerPaletteStyle, registerPass, registerPermeableGround, registerResultExtension, registerRoomColors, registerSeedKeys, registerState, registerStyle, registerTemplate, registerViewerLayer, registerWallTop, setStateDistribution, slotKit, slots, translate, validate, version, windowZone };