@adatechnology/game-floorplan 0.0.0-stage → 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,1054 @@
+/** Seeded random helpers. Same seed and key always produce the same stream. */
+type Rng = () => number;
+declare function mulberry32(a: number): Rng;
+declare function hashString(input: string | number): number;
+/** Independent stream for a `(seed, key)` pair. */
+declare const createRng: (seed: string | number, key: string) => Rng;
+
+/** 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;
+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. */
+type ItemColor = {
+    role: string;
+} | {
+    hex: number;
+} | {
+    pick: number[];
+};
+interface FurnitureDef {
+    type: string;
+    category: string;
+    w: number;
+    d: number;
+    h: number;
+    /** Local mesh axis that is the front (default `+z`). */
+    front: MeshFront;
+    /** May sit under a window (default: `h <= 0.95`). */
+    window: boolean;
+    /** Does not need a clearance in front (default: `h <= 0.5`). */
+    low: boolean;
+    /** Rugs, decks: ignores collisions. */
+    flat: boolean;
+    deck: boolean;
+    /** Keep-out margin around the item (pools). */
+    rim: number;
+    decor?: boolean;
+    /** Hangs a wall cabinet over the counter (y 1.55 to 2.15 m): it blocks a window unless the fill dropped the cabinet. */
+    overhead?: boolean;
+    /** Effective height that blocks a window when taller than `h` (a shower enclosure is 0.1 m tray plus 1.95 m glass). */
+    windowHeight?: number;
+    /** Plugs into a socket (lamps, appliances). */
+    powered?: boolean;
+    /** Only picked when a slot names its exact type (`=type`), never through its category. */
+    exactOnly?: boolean;
+    mount?: Mount;
+    equip?: string[];
+    color?: ItemColor;
+}
+type ItemInput = Pick<FurnitureDef, 'type' | 'category' | 'w' | 'd' | 'h'> & Partial<FurnitureDef>;
+type Anchor = 'wall' | 'corner' | 'center' | 'window' | 'on' | 'inside';
+type Side = 'left' | 'right' | 'front' | 'back' | 'any';
+type FacingRule = 'center' | 'door' | 'target' | 'u+' | 'u-' | 'v+' | 'v-';
+interface SlotDef {
+    id: string;
+    anchor: Anchor;
+    size?: number[];
+    cats: Weights;
+    side?: Side;
+    pos?: number;
+    shift?: number;
+    corner?: string;
+    fx?: number;
+    fz?: number;
+    dx?: number;
+    dz?: number;
+    on?: string;
+    n?: number;
+    part?: number;
+    required?: boolean;
+    chance?: number;
+    clearance?: number;
+    group?: string;
+    requires?: string;
+    facing?: FacingRule;
+    target?: string;
+    slide?: number;
+    [extra: string]: Json;
+}
+type SlotLibrary = SlotDef[] | ((room: {
+    w: number;
+    d: number;
+}) => SlotDef[]);
+interface SlotKit {
+    wall(id: string, side: Side, pos: number, size: number[], cats: Weights, o?: Partial<SlotDef>): SlotDef;
+    corner(id: string, corner: string, size: number[], cats: Weights, o?: Partial<SlotDef>): SlotDef;
+    center(id: string, fx: number, fz: number, size: number[], cats: Weights, o?: Partial<SlotDef>): SlotDef;
+    windowSlot(id: string, size: number[], cats: Weights, o?: Partial<SlotDef>): SlotDef;
+    on(id: string, parent: string, cats: Weights, o?: Partial<SlotDef>): SlotDef;
+    inside(id: string, parent: string, cats: Weights, o?: Partial<SlotDef>): SlotDef;
+}
+interface RoomDef {
+    id: string;
+    type: string;
+    label?: string;
+    rect: number[];
+    parts?: number[][];
+    library?: string;
+    without?: string[];
+    overrides?: Record<string, Json>;
+    extras?: SlotDef[];
+    slots?: SlotLibrary;
+    link?: number[];
+    outdoor?: boolean;
+    ceiling?: number;
+    seedKey?: string;
+    [extra: string]: Json;
+}
+interface DoorDef {
+    a: string;
+    b: string;
+    side?: string;
+    at?: number;
+    width: number;
+    opensTo?: string;
+    steel?: boolean;
+    /** Clear wall from the opening to a corner or junction; defaults to the template's `clearance.door`, else 0.12 m. */
+    clearance?: number;
+    /** Explicit position instead of a wall edge (a tent flap in the middle of the lot). */
+    edge?: {
+        axis: 'u' | 'v';
+        pos: number;
+        a0: number;
+        a1: number;
+    };
+    model?: string;
+    type?: string;
+    steps?: number;
+    [extra: string]: Json;
+}
+interface WindowDef {
+    room: string;
+    side: string;
+    at?: number;
+    n?: number;
+    width: number;
+    y0?: number;
+    y1?: number;
+    [extra: string]: Json;
+}
+interface FloorDef {
+    label?: string;
+    ceiling: number;
+    openPairs?: [string, string][];
+    rooms(w: number, d: number, options: FloorplanOptions): RoomDef[];
+    doors(w: number, d: number, options: FloorplanOptions): DoorDef[];
+    windows(w: number, d: number, options: FloorplanOptions): WindowDef[];
+}
+interface GateCfg {
+    u: number;
+    width: number;
+    to?: string;
+}
+interface LotConfig {
+    frontSetback: number;
+    marginLeft: number;
+    marginRight: number;
+    backyardDepth: number;
+    parking?: {
+        width: number;
+    };
+    garage?: GateCfg;
+    pedestrian?: {
+        u: number;
+    };
+    cargo?: GateCfg;
+    doorTarget?: {
+        a: string;
+        side: string;
+    };
+    libraries?: Record<string, string>;
+    /** Lot zones over the building area (a camp). */
+    extraZones?: {
+        id: string;
+        type: string;
+        label?: string;
+        parts: Rect[];
+        library?: string;
+    }[];
+    yardZones?: {
+        id: string;
+        type: string;
+        label?: string;
+        v0: number;
+        v1: number;
+        library?: string;
+    }[];
+    grounds?: Record<string, string>;
+    pool?: boolean;
+}
+interface TemplateDef {
+    id: string;
+    /** Declared use for zoning, e.g. `residential_single`. */
+    use?: string;
+    style: string | ((o: FloorplanOptions) => string);
+    limits: {
+        w: number[];
+        d: number[];
+    };
+    defaults: {
+        w: number;
+        d: number;
+    };
+    limitsFn?: (o: FloorplanOptions) => TemplateDef['limits'];
+    defaultsFn?: (o: FloorplanOptions) => TemplateDef['defaults'];
+    floors?: FloorDef[];
+    floorsFn?: (o: FloorplanOptions) => FloorDef[];
+    /** Highest floor count the template can reach (zoning); defaults to the generated floor count. */
+    /** Adjustable storey count `[min, max]` through `options.floors`; lets zoning clamp the plan. */
+    floorRange?: [number, number];
+    lot?: ((w: number, d: number, style: StyleDef, o: FloorplanOptions) => LotConfig) | null;
+    facade?: {
+        balcony?: boolean;
+        veranda?: boolean;
+        steelDoor?: boolean;
+    };
+    facadeExtra?: (facade: Json, 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`...). */
+    place?: string;
+    /** Building system the structure pack builds (a reference registered there). */
+    construction?: string;
+    /** Region of the content (`br`...), chosen by the pack that registered the template. */
+    region?: string;
+    /** Clear wall around openings: from a door to a corner or junction, and from a window to a corner, junction or door. */
+    clearance?: {
+        door?: number;
+        window?: number;
+    };
+    /** No walls are built (a tent): rooms and openings stay. */
+    noWalls?: boolean;
+    /** Storey heights add up (a mezzanine with a different ceiling) instead of `index * ceiling`. */
+    cumulativeCeilings?: boolean;
+    /** Settings the packs read from the plan (`power`: `grid`, `offgrid` or `tap`; `solar`); it lands in `result.config`. */
+    config?: (o: FloorplanOptions, w: number, d: number) => Json;
+    /** Marks lot areas taken by the building (chimney, tank, tents) as keep-out zones for the lot fill. */
+    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[];
+        setback: number;
+        marginLeft: number;
+        marginRight: number;
+        backyard: number;
+        w: number;
+        d: number;
+    }) => Json[];
+    /** Sides built against a neighbour (`left` / `right`): exempt from the side setback. */
+    partyWalls?: ('left' | 'right')[];
+    options?: Json;
+    [extra: string]: Json;
+}
+interface BoundaryRule {
+    type: Weights;
+    top: Weights;
+}
+interface StyleDef {
+    id: string;
+    /** Other ids resolving to this style. */
+    aliases?: string[];
+    /** Name of the legacy palette RNG stream (kept so old seeds still reproduce). */
+    seedKey?: string;
+    height: number;
+    /** Height of a fence boundary (default 2.0 m). */
+    fenceHeight?: number;
+    front: BoundaryRule;
+    sideYard: BoundaryRule;
+    back: BoundaryRule;
+    gate: {
+        garage: Weights;
+    };
+    facade: {
+        finish: Weights;
+        grilles: number;
+        roof: Weights;
+    };
+    /** Facade swatches `[labelKey, hex]`. */
+    swatches: [string, string][];
+    /** Ground type weights per lot zone type. */
+    grounds: Record<string, Weights>;
+}
+interface CarClearance {
+    /** Clear space beside the driver door (m). */
+    driver: number;
+    /** Clear space on the passenger side (m). */
+    side: number;
+    /** Clear space in front of and behind the car (m). */
+    end: number;
+}
+interface ResultExtensionContext {
+    plan: Plan;
+    /** The result built so far: the plan, the items, the state items and the extensions that ran before. */
+    result: Json;
+    seed: number | string;
+    /** Seeded stream of the extension: `createRng(seed, seedKey ?? name)`. */
+    rng: Rng;
+    options: FloorplanOptions;
+}
+type ResultExtensionRun = (context: ResultExtensionContext) => Json;
+interface ResultExtensionOptions {
+    /** Extensions that must run first. */
+    after?: string[];
+    /** Name of the seeded stream; defaults to the extension name. A pack sets the name of the team's own flow to reproduce its seeds. */
+    seedKey?: string;
+}
+interface FindStack {
+    readonly itemId: string;
+    readonly count: number;
+    readonly data?: {
+        readonly ageDays?: number;
+        readonly condition?: number;
+        readonly charge?: number;
+        readonly fill?: number;
+    };
+}
+interface FindsQuery {
+    /** Kind of place (`TemplateDef.place`, a room type, a lot zone type). */
+    place: string;
+    /** Kind of container (a furniture category). */
+    container: string;
+    state: string;
+    rng: Rng;
+    /** Outbreak days; 0 is the normal world. */
+    day?: number;
+    region?: string;
+    /** Footprint of the place in m². */
+    footprint?: number;
+    key?: string;
+}
+/**
+ * Answers what a container holds. Registered by an item pack; the engine only keeps the registry. An array is the answer, even an empty one (an abandoned
+ * cupboard that holds nothing); `null` means this provider does not know the container, and the next provider (or the default of the pack) answers.
+ */
+interface FindsProvider {
+    findsFor(query: FindsQuery): readonly FindStack[] | null;
+}
+interface FloorplanOptions {
+    /** Number of storeys, for templates that accept it. */
+    floors?: number;
+    /** Building system of the structure pack (`masonry`, `wood_frame`, ...). */
+    construction?: string;
+    /** How finely the structure pack splits the walls (`coarse`, `panels`, `units`). */
+    wallDetail?: 'coarse' | 'panels' | 'units';
+    /** Radius of the player body (m, default 0.24): a disc this wide must pass between doors and rooms once the furniture is placed. */
+    playerRadius?: number;
+    /** Space a parked car keeps from walls (default driver 0.8, side 0.6, end 0.6). */
+    carClearance?: Partial<CarClearance>;
+    seed?: number | string;
+    w?: number;
+    d?: number;
+    style?: string;
+    state?: string;
+    /** Quality tier used by some templates. */
+    tier?: string;
+    floor?: number;
+    /** Output language for names and messages (default `en`). */
+    locale?: string;
+    /** Urban zone id or definition to clamp the plan to. */
+    zone?: string | ZoneDef;
+    /** Outbreak days for the finds (`FindsQuery.day`); 0 or none is the normal world. */
+    day?: number;
+    /** Region of the world for the finds (`FindsQuery.region`), as the item pack names it. */
+    region?: string;
+    [extra: string]: Json;
+}
+interface Room {
+    id: string;
+    type: string;
+    label?: string;
+    floor: number;
+    parts: Rect[];
+    library: string | null;
+    without: string[];
+    overrides: Record<string, Json>;
+    extras: SlotDef[];
+    slots: SlotLibrary | null;
+    link: number[] | null;
+    outdoor: boolean;
+    ceiling: number | null;
+    seedKey?: string;
+    ground?: string;
+}
+interface Plan {
+    w: number;
+    d: number;
+    tpl: TemplateDef;
+    floorDefs: FloorDef[];
+    style: string;
+    floors: {
+        index: number;
+        name?: string;
+        number?: number;
+        y0: number;
+        ceiling: number;
+    }[];
+    rooms: Room[];
+    zones: Room[];
+    doors: Json[];
+    windows: Json[];
+    walls: Json[];
+    gates: Json[];
+    paths: Json[];
+    lot: Json;
+    facade?: Json;
+    openPairs: Record<number, [string, string][]>;
+    zoning?: ZoningReport;
+    /** Lot areas the building keeps out of the fill (set by `TemplateDef.reservations`). */
+    reservations: Rect[];
+    /** The options the plan was built with (seed included). */
+    options: FloorplanOptions;
+    /** Result of `TemplateDef.config`. */
+    config?: Json;
+    /** Cache of the wall bodies per storey, filled by the walkability grid. */
+    wallBodies?: Record<number, Rect[]>;
+    playerRadius: number;
+    carClearance: CarClearance;
+}
+interface Slot {
+    id: string;
+    room: string;
+    floor: number;
+    outdoor: boolean;
+    anchor: string;
+    side: string | null;
+    cats: Weights;
+    valid: boolean;
+    reason: string | null;
+    [extra: string]: Json;
+}
+interface PlacedItem {
+    id: string;
+    type: string;
+    category: string;
+    x: number;
+    z: number;
+    ry: number;
+    w: number;
+    d: number;
+    h: number;
+    y: number;
+    room: string | null;
+    floor: number;
+    outdoor: boolean;
+    aabb: Rect;
+    color?: number | string;
+    [extra: string]: Json;
+}
+interface ZoneDef {
+    id: string;
+    /** Generic use strings: `residential_single`, `residential_multi`, `commercial`, `mixed`, `industrial`... */
+    allowedUses: string[];
+    maxFloors: number;
+    /** Metres. */
+    maxHeight: number;
+    /** Minimum setbacks in metres. */
+    setbacks: {
+        front: number;
+        side: number;
+        back: number;
+    };
+    /** Maximum building footprint / lot area (taxa de ocupacao). */
+    maxCoverage: number;
+    /** Maximum total built area / lot area (coeficiente de aproveitamento). */
+    maxFar: number;
+    /** Minimum lot area in m2. */
+    minLot: number;
+    /** Minimum lot frontage in metres. */
+    minFrontage: number;
+    /** Minimum permeable fraction of the lot (taxa de permeabilidade). */
+    permeableMin: number;
+}
+interface ZoneViolation {
+    rule: 'use' | 'floors' | 'height' | 'setback_front' | 'setback_side' | 'setback_back' | 'coverage' | 'far' | 'min_lot' | 'min_frontage' | 'permeable';
+    actual: number | string;
+    limit: number | string;
+    message?: string;
+}
+interface ZoneAdjustment {
+    field: string;
+    from: number | string;
+    to: number | string;
+    reason: string;
+}
+interface ZoningReport {
+    zone: string;
+    adjustments: ZoneAdjustment[];
+    violations: ZoneViolation[];
+}
+interface StateContext {
+    plan: Plan;
+    items: PlacedItem[];
+    seed: number | string;
+    state: string;
+    rng: Rng;
+    /** Placement helpers shared with the decor passes. */
+    ctx: PlacementContext;
+    kit: PlacementKit;
+    catalog: Record<string, FurnitureDef>;
+    wallTopHeights: Record<string, number>;
+}
+interface StatePlugin {
+    /** Name of the legacy RNG stream (kept so old seeds still reproduce). */
+    seedKey?: string;
+    /** Applies the state and returns the state items (not part of `items`). */
+    apply(c: StateContext): PlacedItem[];
+    /** Adjusts the palette roles (HSL) before the contrast rules run. */
+    adjustPalette?(roles: Record<string, Hsl>): void;
+}
+interface PlacementContext {
+    make(room: Room, type: string, rect: Rect, front: Vec2, extra?: Json): PlacedItem;
+    add(item: PlacedItem): PlacedItem;
+    placeOnFloor(room: Room, type: string, rng: Rng, opts?: Json): Rect | null;
+    itemsOfRoom(room: Room): PlacedItem[];
+    solidsOfRoom(room: Room): Rect[];
+    gridOf(room: Room): Json;
+    extraSolids: Record<string, Rect[]>;
+    roomById(id: string): Room | undefined;
+    setIgnored(ids: Set<string> | null): void;
+    added: PlacedItem[];
+}
+interface PlacementKit {
+    MARGIN: number;
+    EPS: number;
+    r2(x: number): number;
+    clamp(x: number, a: number, b: number): number;
+    overlaps(a: Rect, b: Rect, e?: number): boolean;
+    inner(p: Rect): Rect;
+    inflate(r: Rect, e: number): Rect;
+    areaOf(r: Rect): number;
+    topOf(m: PlacedItem): number;
+    extent(size: Vec2, f: Vec2): Vec2;
+    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;
+    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;
+    clearRect(r: Rect, f: Vec2, clearance: number): Rect;
+    pickWeighted(rng: Rng, w: Weights): string;
+    createRng(seed: number | string, key: string): Rng;
+    /** Name of the room in seeded streams: the legacy key when the room id was renamed, else the id. */
+    roomSeedKey(room: Room): string;
+    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;
+}
+interface DecorPassContext {
+    plan: Plan;
+    items: PlacedItem[];
+    seed: number | string;
+    rng: Rng;
+    ctx: PlacementContext;
+    kit: PlacementKit;
+    catalog: Record<string, FurnitureDef>;
+    /** Decor profiles registered per style id. */
+    profiles: Record<string, Json>;
+}
+type DecorPass = (c: DecorPassContext) => void;
+interface GroundOverlayRule {
+    /** Item category that triggers the overlay (e.g. `pool`). */
+    category: string;
+    /** Ground type drawn around it. */
+    ground: string;
+    /** Metres added around the trigger footprint. */
+    inflate: number;
+    /** Skip when the zone already uses this ground type. */
+    unlessGround?: string;
+    /** Merge all triggers of the zone into one rectangle. */
+    merge?: boolean;
+}
+interface RoomColorDef {
+    type: string;
+    /** Position in the colour stream, so legacy seeds keep their draws. */
+    order: number;
+    /** Wall `[hue, lightness]` for a style context. */
+    wall(c: PaletteContext): [number, number];
+    /** Fixed floor base `[hue, saturation, lightness]`; falls back to the style's general floor. */
+    floor?: [number, number, number];
+    /** Neutral rooms are capped to low saturation. */
+    neutral?: boolean;
+}
+interface Hsl {
+    h: number;
+    s: number;
+    l: number;
+}
+interface FloorplanLocale {
+    labels?: Record<string, string>;
+    templates?: Record<string, string>;
+    styles?: Record<string, string>;
+    facadeColors?: Record<string, string>;
+    zones?: Record<string, string>;
+    reasons?: Record<string, string>;
+    messages?: Record<string, string>;
+    ui?: Record<string, string>;
+}
+interface ViewerLayerContext {
+    /** Canvas 2D context, already in CSS pixels. */
+    g: CanvasRenderingContext2D;
+    plan: Json;
+    /** Storey being drawn (0 when `all`). */
+    floor: number;
+    /** All storeys at once (the lot view). */
+    all: boolean;
+    /** Metres to pixels. */
+    scale: number;
+    X(u: number): number;
+    Z(v: number): number;
+    rect(r: Rect, fill?: string | null, stroke?: string | null, lineWidth?: number): void;
+    /** Tooltip area (metres) with its text. */
+    hit(r: Rect, text: string): void;
+}
+interface ViewerLayerLegendEntry {
+    label: string;
+    color: string;
+    shape: 'filled' | 'hollow' | 'dashed' | 'line';
+}
+/** A layer a pack adds to the 2D viewer (the structure pack draws pillars and beams); the viewer shows a checkbox for it. */
+interface ViewerLayer {
+    id: string;
+    /** Checkbox text, or a key of the `ui` locale table. */
+    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;
+}
+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;
+
+/** Recorded slots (resolved positions) of every storey and of the lot. */
+declare function slots(template: string | TemplateDef, options?: FloorplanOptions): Json[];
+/** Generates a plan: building, lot, seeded item fill, decor, house state and palette. */
+declare function generate(template: string | TemplateDef, options?: FloorplanOptions): Json;
+/** Validates a result of `generate`; returns a list of messages (empty when valid). */
+declare function validate(result: Json, options?: {
+    locale?: string;
+}): string[];
+/** Size limits and default size of a template (they can depend on options such as `tier`). */
+declare function limitsOf(template: string | TemplateDef, options?: FloorplanOptions): {
+    limits: {
+        w: number[];
+        d: number[];
+    };
+    defaults: {
+        w: number;
+        d: number;
+    };
+};
+declare function listTemplates(locale?: string): {
+    id: string;
+    name: string;
+    use: string;
+    style: string;
+    limits: {
+        w: number[];
+        d: number[];
+    };
+    defaults: {
+        w: number;
+        d: number;
+    };
+    floors: number;
+    floorRange: [number, number] | null;
+    lot: boolean;
+    options: any;
+}[];
+
+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;
+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;
+
+/** Registers an urban zone (zoning rules). Returns the stored definition. */
+declare function defineZone(zone: ZoneDef): ZoneDef;
+declare const getZone: (id: string) => ZoneDef | undefined;
+declare const listZones: () => ZoneDef[];
+/** Marks ground types (e.g. `lawn`, `dirt`) that count towards the permeable area of a lot. */
+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 const overlaps: (a: Rect, b: Rect, e?: number) => boolean;
+declare function openingZones(u: number, v: number, axis: 'u' | 'v', width: number, depth: number): Rect[];
+
+/** 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;
+
+/** 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 = {
+    shape: 'group';
+    parent: number;
+    x: number;
+    y: number;
+    z: number;
+    ry: number;
+} | {
+    shape: 'box';
+    parent: number;
+    x: number;
+    y: number;
+    z: number;
+    width: number;
+    height: number;
+    depth: number;
+    color: number;
+    emissive: boolean;
+    ry: number;
+    rz: number;
+    radius: number;
+} | {
+    shape: 'prism';
+    parent: number;
+    x: number;
+    y: number;
+    z: number;
+    width: number;
+    height: number;
+    depth: number;
+    color: number;
+    ry: number;
+} | {
+    shape: 'cylinder';
+    parent: number;
+    x: number;
+    y: number;
+    z: number;
+    radiusTop: number;
+    radiusBottom: number;
+    height: number;
+    color: number;
+    segments: number;
+} | {
+    shape: 'line';
+    parent: number;
+    points: [number, number, number][];
+    color: number;
+} | {
+    shape: 'sign';
+    parent: number;
+    x: number;
+    y: number;
+    z: number;
+    width: number;
+    height: number;
+    ry: number;
+    text: string;
+    background: string;
+    foreground: string;
+};
+/** A window the renderer draws as an instance (a lit one glows). `ry` is the facing; the size is width by height. */
+type SilhouetteWindow = {
+    x: number;
+    y: number;
+    z: number;
+    ry: number;
+    width: number;
+    height: number;
+    isLit: boolean;
+};
+type Silhouette = {
+    parts: SilhouettePart[];
+    windows: SilhouetteWindow[];
+    /** Footprint on the ground: centre and size, for the LOD plan. */
+    footprint: {
+        x: number;
+        z: number;
+        width: number;
+        depth: number;
+        height: number;
+    };
+};
+type RandomSource = () => number;
+
+/** The page's own seeded generator (mulberry32), so a silhouette drawn from the same seed has the same windows and colours. */
+declare function createSilhouetteRandom(seed: number): RandomSource;
+
+type CityBuildingParams = {
+    x: number;
+    z: number;
+    width: number;
+    depth: number;
+    height: number;
+    color: number;
+    /** Chance of a ground-floor shop on both long faces; omitted means none. */
+    shopChance?: number;
+    /** Chance that a window is lit. */
+    litChance?: number;
+    random?: RandomSource;
+    seed?: number;
+};
+/** City building: block, roof slab, maybe a vent, maybe a shop front, and window instances on the four faces. */
+declare function createCityBuilding(p: CityBuildingParams): Silhouette;
+
+type Seeded = {
+    random?: RandomSource;
+    seed?: number;
+};
+type TwoStoreyParams = Seeded & {
+    x: number;
+    z: number;
+    width: number;
+    depth: number;
+    color: number;
+    roofColor?: number;
+    ry?: number;
+};
+/** Two-storey house with a balcony slab, pitched roof and four windows. */
+declare function createTwoStoreyHouse(p: TwoStoreyParams): Silhouette;
+type SlabHouseParams = Seeded & {
+    x: number;
+    z: number;
+    width: number;
+    depth: number;
+    floors: number;
+    color: number;
+};
+/** Reinforced-concrete slab house of one to three floors, with water tank, side stair and sometimes rebar starters. */
+declare function createSlabHouse(p: SlabHouseParams): Silhouette;
+type ColonialParams = Seeded & {
+    x: number;
+    z: number;
+    width: number;
+    color: number;
+    hasDoor: boolean;
+};
+/** Colonial terrace house: parapet, roof behind it and a row of doors or windows. */
+declare function createColonialHouse(p: ColonialParams): Silhouette;
+type ChaletParams = Seeded & {
+    x: number;
+    z: number;
+    color?: number;
+    ry?: number;
+};
+/** Wooden chalet on a stone base with a steep roof and a chimney. */
+declare function createChalet(p: ChaletParams): Silhouette;
+type CompanyHouseParams = Seeded & {
+    x: number;
+    z: number;
+    color?: number;
+};
+/** Company-town house with a low front fence. */
+declare function createCompanyHouse(p: CompanyHouseParams): Silhouette;
+type StiltHouseParams = Seeded & {
+    x: number;
+    z: number;
+    color?: number;
+};
+/** House on stilts with a ramp-like entry platform. */
+declare function createStiltHouse(p: StiltHouseParams): Silhouette;
+type FarmhouseParams = Seeded & {
+    x: number;
+    z: number;
+};
+/** Farm house with a long covered porch on six posts. */
+declare function createFarmhouse(p: FarmhouseParams): Silhouette;
+type DetachedHouseParams = Seeded & {
+    x: number;
+    z: number;
+    width: number;
+    depth: number;
+    color: number;
+    roofColor?: number;
+    ry?: number;
+    isBoarded?: boolean;
+};
+/** 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.
+ */
+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;
+
+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, 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 };