@woosh/meep-engine 3.29.0 → 3.30.0

package/src/core/wfc/WFCState.d.ts

@@ -0,0 +1,273 @@
+/**
+ * Everything a solve mutates: the wave, the aggregates derived from it, the propagation queue, the
+ * undo trail and the decision stack.
+ *
+ * All of it lives in the object, which is what makes {@link wfc_solve} resumable — a call that
+ * runs out of budget mid-propagation leaves its work here and the next call continues from it.
+ *
+ * Build one per solve. The {@link WFCRuleTable}, {@link WFCLattice} and {@link WFCTileWeights} it
+ * is given are read-only to it and can be shared across many.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class WFCState {
+    /**
+     * @param {WFCRuleTable} rules must be finalized
+     * @param {WFCLattice} lattice must have the same direction count as `rules`
+     * @param {WFCTileWeights} weights must have the same tile count as `rules`
+     * @param {function():number} random RNG returning values in `[0, 1)`. Consumed once here and
+     *        once per collapse, so a seeded generator reproduces a solve exactly.
+     * @param {WFCCellChoice} [cell_choice] defaults to {@link WFCCellChoice.SCANLINE}
+     */
+    constructor(rules: WFCRuleTable, lattice: WFCLattice, weights: WFCTileWeights, random: () => number, cell_choice?: WFCCellChoice);
+    /** @type {WFCRuleTable} */
+    rules: WFCRuleTable;
+    /** @type {WFCLattice} */
+    lattice: WFCLattice;
+    /** @type {WFCTileWeights} */
+    weights: WFCTileWeights;
+    /** @type {function():number} */
+    random: () => number;
+    /** @type {WFCCellChoice} */
+    cell_choice: WFCCellChoice;
+    /** @type {number} */
+    cell_count: number;
+    /** @type {number} */
+    tile_count: number;
+    /** @type {number} */
+    words_per_cell: number;
+    /** @type {number} */
+    direction_count: number;
+    /**
+     * A domain with every tile in it, tail-masked.
+     * @type {Uint32Array}
+     */
+    full_mask: Uint32Array;
+    /**
+     * Seeds the per-cell tie-break that separates cells of equal score. Drawn from `random`,
+     * so a seeded generator reproduces the whole solve.
+     * @type {number}
+     * @private
+     */
+    private __noise_seed;
+    /**
+     * @type {number}
+     * @private
+     */
+    private __jitter_scale;
+    /**
+     * Single backing buffer for every per-cell array.
+     * @type {ArrayBuffer}
+     * @private
+     */
+    private __data_buffer;
+    /**
+     * Sum of the weights still possible in each cell.
+     *
+     * Maintained incrementally and therefore subject to drift; only the entropy heuristic
+     * reads it, and {@link wfc_state_collapse} recomputes the sum exactly rather than trusting
+     * it.
+     * @type {Float64Array}
+     */
+    weight_sum: Float64Array;
+    /**
+     * Sum of `w·ln(w)` over the weights still possible in each cell.
+     * @type {Float64Array}
+     */
+    weight_log_sum: Float64Array;
+    /**
+     * `words_per_cell` bits per cell: is tile `t` still possible here?
+     * @type {Uint32Array}
+     */
+    wave: Uint32Array;
+    /**
+     * Population count of each cell's domain, cached rather than recomputed.
+     * @type {Uint32Array}
+     */
+    possibility_count: Uint32Array;
+    /**
+     * Cells whose domain shrank and whose neighbours have not been relaxed against them yet.
+     * Bounded at `cell_count` because {@link in_queue} de-duplicates.
+     * @type {Uint32Array}
+     */
+    queue: Uint32Array;
+    /**
+     * Cells whose selection score changed during the current wave. Flushed to the heap once
+     * per wave rather than once per banned tile.
+     * @type {Uint32Array}
+     */
+    dirty_list: Uint32Array;
+    /** @type {Uint8Array} */
+    in_queue: Uint8Array;
+    /** @type {Uint8Array} */
+    dirty: Uint8Array;
+    /**
+     * May the solver choose to collapse this cell? Cells outside the eligible set still
+     * constrain their neighbours through propagation; they are simply never selected.
+     * @type {Uint8Array}
+     */
+    eligible: Uint8Array;
+    /** @type {number} */
+    queue_count: number;
+    /** @type {number} */
+    dirty_count: number;
+    /**
+     * `(address, removed_bits)` pairs, in the order they were applied.
+     * @type {Uint32Array}
+     * @private
+     */
+    private __trail;
+    /**
+     * Entries, not words.
+     * @type {number}
+     * @private
+     */
+    private __trail_length;
+    /**
+     * `(cell, trail_mark, tried_tile)` triples.
+     * @type {Uint32Array}
+     * @private
+     */
+    private __decisions;
+    /** @type {number} @private */
+    private __decision_count;
+    /**
+     * Scratch for the propagator: the target bits not yet known to be supported.
+     * Owned by the state rather than the module, so two solves can interleave.
+     * @type {Uint32Array}
+     * @private
+     */
+    private __uncovered;
+    /**
+     * Set by {@link wfc_state_ban_bits} when a cell's domain empties. Checked once per
+     * relaxation rather than returned through every call.
+     * @type {boolean}
+     */
+    contradiction: boolean;
+    /**
+     * Eligible cells that still have more than one possibility. The solve is finished when it
+     * reaches zero.
+     * @type {number}
+     */
+    undecided_eligible: number;
+    /** @type {number} */
+    backtrack_count: number;
+    /**
+     * High-water mark of {@link __trail_length}, in entries — what a pathological rule set
+     * costs in memory.
+     * @type {number}
+     */
+    trail_peak: number;
+    /**
+     * Where {@link WFCCellChoice.SCANLINE} has reached.
+     * @type {number}
+     * @private
+     */
+    private __scan_cursor;
+    /**
+     * Present only for the policies that need a priority queue.
+     * @type {IndexedFloatMinHeap|null}
+     */
+    heap: IndexedFloatMinHeap | null;
+    /**
+     * Bytes held by the per-cell arrays. The heap, trail and decision stack are separate and grow.
+     * @returns {number}
+     */
+    get byte_size(): number;
+    /**
+     * Trail entries currently recorded.
+     * @returns {number}
+     */
+    get trail_length(): number;
+    /**
+     * Decisions currently on the stack — the depth of the search.
+     * @returns {number}
+     */
+    get decision_count(): number;
+    /**
+     * Selection score of a cell under the current {@link WFCCellChoice}; lower is chosen sooner.
+     *
+     * @param {number} cell
+     * @returns {number}
+     */
+    score_of(cell: number): number;
+    /**
+     * Make everything decided so far permanent: drop the decision stack and the undo trail, so no
+     * later contradiction can rewind past this point.
+     *
+     * The wave is untouched — this is about what the *search* may reconsider, not what the grid
+     * holds. Afterwards a contradiction reports {@link WFCStatus.UNSATISFIABLE} rather than
+     * dismantling work already treated as finished.
+     */
+    commit(): void;
+    /**
+     * Rebuild the selection queue and the undecided count from the current wave.
+     *
+     * Called at construction, and by {@link wfc_state_set_eligible} when the eligible set changes.
+     *
+     * @param {Uint32Array|number[]} [cells] the eligible set when it is already known, which makes
+     *        the rebuild proportional to it rather than to the whole grid. Must not repeat a cell;
+     *        {@link wfc_state_set_eligible} asserts that.
+     */
+    reseed_selection(cells?: Uint32Array | number[]): void;
+    /**
+     * Record that `bits` were cleared at `address`, so backtracking can put them back.
+     *
+     * @param {number} address `cell * words_per_cell + word`
+     * @param {number} bits the bits that were actually cleared
+     */
+    trail_push(address: number, bits: number): void;
+    /**
+     * @param {number} entry
+     * @returns {number} the address written by that trail entry
+     */
+    trail_address(entry: number): number;
+    /**
+     * @param {number} entry
+     * @returns {number} the bits that entry cleared
+     */
+    trail_bits(entry: number): number;
+    /**
+     * Drop trail entries above `length`. The caller has already restored the wave from them.
+     * @param {number} length
+     */
+    trail_truncate(length: number): void;
+    /**
+     * Push a decision the search can return to.
+     *
+     * `trail_mark` is taken before the collapse and `tile` is only known after it, so the caller
+     * passes both rather than this reading the current trail length.
+     *
+     * @param {number} cell
+     * @param {number} trail_mark trail length immediately before the collapse
+     * @param {number} tile
+     */
+    decision_push(cell: number, trail_mark: number, tile: number): void;
+    /**
+     * Remove the newest decision and report it.
+     *
+     * @param {Uint32Array|number[]} out receives `[cell, trail_mark, tried_tile]`
+     * @returns {boolean} false when the stack was already empty
+     */
+    decision_pop(out: Uint32Array | number[]): boolean;
+    /**
+     * Scratch for {@link wfc_state_propagate}.
+     * @returns {Uint32Array}
+     */
+    get uncovered(): Uint32Array;
+    /**
+     * @param {number} v
+     */
+    set scan_cursor(v: number);
+    /**
+     * @returns {number}
+     */
+    get scan_cursor(): number;
+}
+import { WFCRuleTable } from "./WFCRuleTable.js";
+import { WFCLattice } from "./WFCLattice.js";
+import { WFCTileWeights } from "./WFCTileWeights.js";
+import { WFCCellChoice } from "./WFCCellChoice.js";
+import { IndexedFloatMinHeap } from "../collection/heap/IndexedFloatMinHeap.js";
+//# sourceMappingURL=WFCState.d.ts.map

package/src/core/wfc/WFCState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WFCState.d.ts","sourceRoot":"","sources":["../../../../src/core/wfc/WFCState.js"],"names":[],"mappings":"AA0CA;;;;;;;;;;;;GAYG;AACH;IACI;;;;;;;OAOG;IACH,mBAPW,YAAY,WACZ,UAAU,WACV,cAAc,gBACH,MAAM,gBAEjB,aAAa,EA+PvB;IA3NG,2BAA2B;IAC3B,OADW,YAAY,CACL;IAClB,yBAAyB;IACzB,SADW,UAAU,CACC;IACtB,6BAA6B;IAC7B,SADW,cAAc,CACH;IACtB,gCAAgC;IAChC,cADsB,MAAM,CACR;IACpB,4BAA4B;IAC5B,aADW,aAAa,CACM;IAE9B,qBAAqB;IACrB,YADW,MAAM,CACW;IAC5B,qBAAqB;IACrB,YADW,MAAM,CACiB;IAClC,qBAAqB;IACrB,gBADW,MAAM,CACmB;IACpC,qBAAqB;IACrB,iBADW,MAAM,CAC2B;IAE5C;;;OAGG;IACH,WAFU,WAAW,CAE2B;IAIhD;;;;;OAKG;IACH,qBAAkD;IAElD;;;OAGG;IACH,uBAEwB;IAQxB;;;;OAIG;IACH,sBAAuG;IAEvG;;;;;;;OAOG;IACH,YAFU,YAAY,CAEoD;IAG1E;;;OAGG;IACH,gBAFU,YAAY,CAEwD;IAG9E;;;OAGG;IACH,MAFU,WAAW,CAE+D;IAGpF;;;OAGG;IACH,mBAFU,WAAW,CAE2D;IAGhF;;;;OAIG;IACH,OAFU,WAAW,CAE+C;IAGpE;;;;OAIG;IACH,YAFU,WAAW,CAEoD;IAGzE,yBAAyB;IACzB,UADW,UAAU,CACiD;IAGtE,yBAAyB;IACzB,OADW,UAAU,CAC8C;IAGnE;;;;OAIG;IACH,UAFU,UAAU,CAEkD;IAGtE,qBAAqB;IACrB,aADW,MAAM,CACG;IACpB,qBAAqB;IACrB,aADW,MAAM,CACG;IAEpB;;;;OAIG;IACH,gBAA0E;IAE1E;;;;OAIG;IACH,uBAAuB;IAEvB;;;;OAIG;IACH,oBAA6D;IAE7D,8BAA8B;IAC9B,yBAAyB;IAEzB;;;;;OAKG;IACH,oBAAkD;IAElD;;;;OAIG;IACH,eAFU,OAAO,CAES;IAE1B;;;;OAIG;IACH,oBAFU,MAAM,CAEW;IAE3B,qBAAqB;IACrB,iBADW,MAAM,CACO;IAExB;;;;OAIG;IACH,YAFU,MAAM,CAEG;IAEnB;;;;OAIG;IACH,sBAAsB;IAEtB;;;OAGG;IACH,MAFU,mBAAmB,GAAC,IAAI,CAIO;IA0B7C;;;OAGG;IACH,wBAEC;IAED;;;OAGG;IACH,2BAEC;IAED;;;OAGG;IACH,6BAEC;IAED;;;;;OAKG;IACH,eAHW,MAAM,GACJ,MAAM,CAYlB;IAED;;;;;;;OAOG;IACH,eAGC;IAED;;;;;;;;OAQG;IACH,yBAJW,WAAW,GAAC,MAAM,EAAE,QAyC9B;IAED;;;;;OAKG;IACH,oBAHW,MAAM,QACN,MAAM,QAyBhB;IAED;;;OAGG;IACH,qBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,kBAHW,MAAM,GACJ,MAAM,CAIlB;IAED;;;OAGG;IACH,uBAFW,MAAM,QAIhB;IAED;;;;;;;;;OASG;IACH,oBAJW,MAAM,cACN,MAAM,QACN,MAAM,QAoBhB;IAED;;;;;OAKG;IACH,kBAHW,WAAW,GAAC,MAAM,EAAE,GAClB,OAAO,CAiBnB;IAED;;;OAGG;IACH,6BAEC;IASD;;OAEG;IACH,2BAEC;IAZD;;OAEG;IACH,0BAEC;CAQJ;6BAliB2C,mBAAmB;2BADpC,iBAAiB;+BAEb,qBAAqB;8BAHtB,oBAAoB;oCAFd,2CAA2C"}