@woosh/meep-engine 3.29.0 → 3.30.0

package/src/core/wfc/WFCState.js

@@ -0,0 +1,552 @@
+import { assert } from "../assert.js";
+import { IndexedFloatMinHeap } from "../collection/heap/IndexedFloatMinHeap.js";
+import { lowbias32 } from "../math/hash/lowbias32.js";
+import { WFCCellChoice } from "./WFCCellChoice.js";
+import { WFCLattice } from "./WFCLattice.js";
+import { WFCRuleTable, wfc_tail_mask } from "./WFCRuleTable.js";
+import { WFCTileWeights } from "./WFCTileWeights.js";
+
+/**
+ * Entropy differences below this are not meaningful — the heap stores a `float32`, whose precision
+ * near `ln(2)` is about `6e-8` — so a jitter of this size orders ties without reordering anything
+ * real.
+ * @type {number}
+ */
+const ENTROPY_JITTER_SCALE = 1e-6;
+
+/**
+ * Possibility counts are integers a whole unit apart, so half a unit of jitter separates ties at
+ * any count a `float32` can still resolve.
+ * @type {number}
+ */
+const COUNT_JITTER_SCALE = 0.5;
+
+/**
+ * Initial capacity of the undo trail, in entries. Grows by doubling; never shrinks.
+ * @type {number}
+ */
+const TRAIL_INITIAL_CAPACITY = 1024;
+
+/**
+ * `u32` words per trail entry: the address that was written, and the bits that were cleared.
+ * @type {number}
+ */
+const TRAIL_ENTRY_WORDS = 2;
+
+/**
+ * `u32` words per decision-stack entry: the cell, the trail length before the collapse, and the
+ * tile that was tried.
+ * @type {number}
+ */
+const DECISION_ENTRY_WORDS = 3;
+
+/**
+ * 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, lattice, weights, random, cell_choice = WFCCellChoice.SCANLINE) {
+        assert.isInstanceOf(rules, WFCRuleTable, 'rules');
+        assert.isInstanceOf(lattice, WFCLattice, 'lattice');
+        assert.isInstanceOf(weights, WFCTileWeights, 'weights');
+        assert.isFunction(random, 'random');
+        assert.isOneOf(
+            cell_choice,
+            [WFCCellChoice.ENTROPY, WFCCellChoice.MINIMUM_REMAINING, WFCCellChoice.SCANLINE],
+            'cell_choice'
+        );
+
+        if (!rules.finalized) {
+            throw new Error('rule table is not finalized; call finalize() after the last mutation');
+        }
+
+        if (rules.direction_count !== lattice.direction_count) {
+            throw new Error(`rule table has ${rules.direction_count} directions, lattice has ${lattice.direction_count}`);
+        }
+
+        if (rules.tile_count !== weights.tile_count) {
+            throw new Error(`rule table has ${rules.tile_count} tiles, weights have ${weights.tile_count}`);
+        }
+
+        const cell_count = lattice.cell_count;
+        const words_per_cell = rules.words_per_cell;
+
+        // the trail stores `cell * words_per_cell + word` in a u32 and decodes it back with an
+        // int32 conversion, so the bound is 2^31 rather than 2^32. A real throw: consumers strip
+        // assert.* out of shipped builds, and silent index wraparound is exactly what must not
+        // depend on a build flag.
+        if (cell_count * words_per_cell >= 0x80000000) {
+            throw new Error(`cell_count(=${cell_count}) x words_per_cell(=${words_per_cell}) must stay below 2^31`);
+        }
+
+        /** @type {WFCRuleTable} */
+        this.rules = rules;
+        /** @type {WFCLattice} */
+        this.lattice = lattice;
+        /** @type {WFCTileWeights} */
+        this.weights = weights;
+        /** @type {function():number} */
+        this.random = random;
+        /** @type {WFCCellChoice} */
+        this.cell_choice = cell_choice;
+
+        /** @type {number} */
+        this.cell_count = cell_count;
+        /** @type {number} */
+        this.tile_count = rules.tile_count;
+        /** @type {number} */
+        this.words_per_cell = words_per_cell;
+        /** @type {number} */
+        this.direction_count = rules.direction_count;
+
+        /**
+         * A domain with every tile in it, tail-masked.
+         * @type {Uint32Array}
+         */
+        this.full_mask = new Uint32Array(words_per_cell);
+        this.full_mask.fill(0xFFFFFFFF);
+        this.full_mask[words_per_cell - 1] = wfc_tail_mask(this.tile_count);
+
+        /**
+         * 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
+         */
+        this.__noise_seed = (random() * 0x100000000) >>> 0;
+
+        /**
+         * @type {number}
+         * @private
+         */
+        this.__jitter_scale = cell_choice === WFCCellChoice.ENTROPY
+            ? ENTROPY_JITTER_SCALE
+            : COUNT_JITTER_SCALE;
+
+        const f64_bytes = cell_count * 8;
+        const wave_bytes = cell_count * words_per_cell * 4;
+        const u32_bytes = cell_count * 4;
+
+        let offset = 0;
+
+        /**
+         * Single backing buffer for every per-cell array.
+         * @type {ArrayBuffer}
+         * @private
+         */
+        this.__data_buffer = new ArrayBuffer((f64_bytes * 2) + wave_bytes + (u32_bytes * 3) + (cell_count * 3));
+
+        /**
+         * 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}
+         */
+        this.weight_sum = new Float64Array(this.__data_buffer, offset, cell_count);
+        offset += f64_bytes;
+
+        /**
+         * Sum of `w·ln(w)` over the weights still possible in each cell.
+         * @type {Float64Array}
+         */
+        this.weight_log_sum = new Float64Array(this.__data_buffer, offset, cell_count);
+        offset += f64_bytes;
+
+        /**
+         * `words_per_cell` bits per cell: is tile `t` still possible here?
+         * @type {Uint32Array}
+         */
+        this.wave = new Uint32Array(this.__data_buffer, offset, cell_count * words_per_cell);
+        offset += wave_bytes;
+
+        /**
+         * Population count of each cell's domain, cached rather than recomputed.
+         * @type {Uint32Array}
+         */
+        this.possibility_count = new Uint32Array(this.__data_buffer, offset, cell_count);
+        offset += u32_bytes;
+
+        /**
+         * 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}
+         */
+        this.queue = new Uint32Array(this.__data_buffer, offset, cell_count);
+        offset += u32_bytes;
+
+        /**
+         * Cells whose selection score changed during the current wave. Flushed to the heap once
+         * per wave rather than once per banned tile.
+         * @type {Uint32Array}
+         */
+        this.dirty_list = new Uint32Array(this.__data_buffer, offset, cell_count);
+        offset += u32_bytes;
+
+        /** @type {Uint8Array} */
+        this.in_queue = new Uint8Array(this.__data_buffer, offset, cell_count);
+        offset += cell_count;
+
+        /** @type {Uint8Array} */
+        this.dirty = new Uint8Array(this.__data_buffer, offset, cell_count);
+        offset += cell_count;
+
+        /**
+         * 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}
+         */
+        this.eligible = new Uint8Array(this.__data_buffer, offset, cell_count);
+        offset += cell_count;
+
+        /** @type {number} */
+        this.queue_count = 0;
+        /** @type {number} */
+        this.dirty_count = 0;
+
+        /**
+         * `(address, removed_bits)` pairs, in the order they were applied.
+         * @type {Uint32Array}
+         * @private
+         */
+        this.__trail = new Uint32Array(TRAIL_INITIAL_CAPACITY * TRAIL_ENTRY_WORDS);
+
+        /**
+         * Entries, not words.
+         * @type {number}
+         * @private
+         */
+        this.__trail_length = 0;
+
+        /**
+         * `(cell, trail_mark, tried_tile)` triples.
+         * @type {Uint32Array}
+         * @private
+         */
+        this.__decisions = new Uint32Array(64 * DECISION_ENTRY_WORDS);
+
+        /** @type {number} @private */
+        this.__decision_count = 0;
+
+        /**
+         * 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
+         */
+        this.__uncovered = new Uint32Array(words_per_cell);
+
+        /**
+         * 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}
+         */
+        this.contradiction = false;
+
+        /**
+         * Eligible cells that still have more than one possibility. The solve is finished when it
+         * reaches zero.
+         * @type {number}
+         */
+        this.undecided_eligible = 0;
+
+        /** @type {number} */
+        this.backtrack_count = 0;
+
+        /**
+         * High-water mark of {@link __trail_length}, in entries — what a pathological rule set
+         * costs in memory.
+         * @type {number}
+         */
+        this.trail_peak = 0;
+
+        /**
+         * Where {@link WFCCellChoice.SCANLINE} has reached.
+         * @type {number}
+         * @private
+         */
+        this.__scan_cursor = 0;
+
+        /**
+         * Present only for the policies that need a priority queue.
+         * @type {IndexedFloatMinHeap|null}
+         */
+        this.heap = cell_choice === WFCCellChoice.SCANLINE
+            ? null
+            : new IndexedFloatMinHeap(cell_count);
+
+        // every cell starts with every tile, and every cell starts queued: the initial sweep is
+        // the propagation queue being pre-filled. Each relaxation in it has a pristine source, so
+        // the rule table's full_support answers it in O(words_per_cell).
+        for (let cell = 0; cell < cell_count; cell++) {
+            const base = cell * words_per_cell;
+
+            for (let w = 0; w < words_per_cell; w++) {
+                this.wave[base + w] = this.full_mask[w];
+            }
+
+            this.possibility_count[cell] = this.tile_count;
+            this.weight_sum[cell] = weights.total_weight;
+            this.weight_log_sum[cell] = weights.total_weight_log_weight;
+
+            this.queue[cell] = cell;
+            this.in_queue[cell] = 1;
+            this.eligible[cell] = 1;
+        }
+
+        this.queue_count = cell_count;
+
+        this.reseed_selection();
+    }
+
+    /**
+     * Bytes held by the per-cell arrays. The heap, trail and decision stack are separate and grow.
+     * @returns {number}
+     */
+    get byte_size() {
+        return this.__data_buffer.byteLength;
+    }
+
+    /**
+     * Trail entries currently recorded.
+     * @returns {number}
+     */
+    get trail_length() {
+        return this.__trail_length;
+    }
+
+    /**
+     * Decisions currently on the stack — the depth of the search.
+     * @returns {number}
+     */
+    get decision_count() {
+        return this.__decision_count;
+    }
+
+    /**
+     * Selection score of a cell under the current {@link WFCCellChoice}; lower is chosen sooner.
+     *
+     * @param {number} cell
+     * @returns {number}
+     */
+    score_of(cell) {
+        const jitter = ((lowbias32(cell ^ this.__noise_seed) >>> 8) / 0x1000000) * this.__jitter_scale;
+
+        if (this.cell_choice === WFCCellChoice.ENTROPY) {
+            const sum = this.weight_sum[cell];
+
+            return Math.log(sum) - (this.weight_log_sum[cell] / sum) + jitter;
+        }
+
+        return this.possibility_count[cell] + jitter;
+    }
+
+    /**
+     * 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() {
+        this.__decision_count = 0;
+        this.__trail_length = 0;
+    }
+
+    /**
+     * 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) {
+        const { cell_count, heap, possibility_count, eligible } = this;
+
+        this.__scan_cursor = 0;
+
+        // clear only the flags that are actually set — `dirty[cell]` is raised only when the cell
+        // is appended to `dirty_list`, so the list names every one. A `fill(0)` here is a
+        // whole-grid memset, which block solving pays once per block.
+        for (let i = 0; i < this.dirty_count; i++) {
+            this.dirty[this.dirty_list[i]] = 0;
+        }
+
+        this.dirty_count = 0;
+
+        if (heap !== null) {
+            heap.clear();
+        }
+
+        let undecided = 0;
+
+        const count = cells === undefined ? cell_count : cells.length;
+
+        for (let i = 0; i < count; i++) {
+            const cell = cells === undefined ? i : cells[i];
+
+            if (eligible[cell] === 0 || possibility_count[cell] <= 1) {
+                continue;
+            }
+
+            undecided++;
+
+            if (heap !== null) {
+                heap.insert(cell, this.score_of(cell));
+            }
+        }
+
+        this.undecided_eligible = undecided;
+    }
+
+    /**
+     * 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, bits) {
+        const length = this.__trail_length;
+
+        if ((length + 1) * TRAIL_ENTRY_WORDS > this.__trail.length) {
+            const grown = new Uint32Array(this.__trail.length * 2);
+
+            grown.set(this.__trail);
+
+            this.__trail = grown;
+        }
+
+        const word = length * TRAIL_ENTRY_WORDS;
+
+        this.__trail[word] = address;
+        this.__trail[word + 1] = bits;
+
+        const next = length + 1;
+
+        this.__trail_length = next;
+
+        if (next > this.trail_peak) {
+            this.trail_peak = next;
+        }
+    }
+
+    /**
+     * @param {number} entry
+     * @returns {number} the address written by that trail entry
+     */
+    trail_address(entry) {
+        return this.__trail[entry * TRAIL_ENTRY_WORDS];
+    }
+
+    /**
+     * @param {number} entry
+     * @returns {number} the bits that entry cleared
+     */
+    trail_bits(entry) {
+        return this.__trail[entry * TRAIL_ENTRY_WORDS + 1];
+    }
+
+    /**
+     * Drop trail entries above `length`. The caller has already restored the wave from them.
+     * @param {number} length
+     */
+    trail_truncate(length) {
+        this.__trail_length = length;
+    }
+
+    /**
+     * 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, trail_mark, tile) {
+        const count = this.__decision_count;
+
+        if ((count + 1) * DECISION_ENTRY_WORDS > this.__decisions.length) {
+            const grown = new Uint32Array(this.__decisions.length * 2);
+
+            grown.set(this.__decisions);
+
+            this.__decisions = grown;
+        }
+
+        const word = count * DECISION_ENTRY_WORDS;
+
+        this.__decisions[word] = cell;
+        this.__decisions[word + 1] = trail_mark;
+        this.__decisions[word + 2] = tile;
+
+        this.__decision_count = count + 1;
+    }
+
+    /**
+     * 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) {
+        if (this.__decision_count === 0) {
+            return false;
+        }
+
+        const count = this.__decision_count - 1;
+        const word = count * DECISION_ENTRY_WORDS;
+
+        out[0] = this.__decisions[word];
+        out[1] = this.__decisions[word + 1];
+        out[2] = this.__decisions[word + 2];
+
+        this.__decision_count = count;
+
+        return true;
+    }
+
+    /**
+     * Scratch for {@link wfc_state_propagate}.
+     * @returns {Uint32Array}
+     */
+    get uncovered() {
+        return this.__uncovered;
+    }
+
+    /**
+     * @returns {number}
+     */
+    get scan_cursor() {
+        return this.__scan_cursor;
+    }
+
+    /**
+     * @param {number} v
+     */
+    set scan_cursor(v) {
+        this.__scan_cursor = v;
+    }
+}

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

@@ -0,0 +1,11 @@
+/**
+ * Outcome of a call to {@link wfc_solve }.
+ */
+export type WFCStatus = number;
+export namespace WFCStatus {
+    let SOLVED: number;
+    let RUNNING: number;
+    let UNSATISFIABLE: number;
+    let EXHAUSTED: number;
+}
+//# sourceMappingURL=WFCStatus.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WFCStatus.d.ts","sourceRoot":"","sources":["../../../../src/core/wfc/WFCStatus.js"],"names":[],"mappings":";;;wBAIU,MAAM"}

package/src/core/wfc/WFCStatus.js

@@ -0,0 +1,28 @@
+/**
+ * Outcome of a call to {@link wfc_solve}.
+ *
+ * @readonly
+ * @enum {number}
+ */
+export const WFCStatus = {
+    /**
+     * Every eligible cell has exactly one possibility left. The result is ready to read.
+     */
+    SOLVED: 0,
+    /**
+     * The operation budget ran out. Nothing is wrong; call again to continue. All progress,
+     * including a half-drained propagation queue, lives in the state.
+     */
+    RUNNING: 1,
+    /**
+     * The search space is exhausted — the instance has no solution under the caller's initial
+     * restrictions. This is an answer, not a failure.
+     */
+    UNSATISFIABLE: 2,
+    /**
+     * The backtrack budget ran out before the search either succeeded or proved the instance
+     * unsatisfiable. The conventional response is to restart with a different seed; a caller
+     * that wants to keep searching raises `max_backtracks` instead.
+     */
+    EXHAUSTED: 3
+};

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

@@ -0,0 +1,48 @@
+/**
+ * Relative placement likelihoods, one per tile.
+ *
+ * Nothing is normalised — `[1, 9]` and `[0.1, 0.9]` behave identically.
+ *
+ * Weights must be finite and strictly positive; a non-positive one throws. A zero-weight tile
+ * would sit in a cell's domain, count toward its possibility count and never be selected, which
+ * surfaces much later as a solve that cannot finish. A tile you do not want is one you leave out
+ * of the rule table.
+ *
+ * Held apart from {@link WFCRuleTable} so the same structure can be solved with different
+ * preferences.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class WFCTileWeights {
+    /**
+     * Every tile equally likely — the same as passing an array of ones.
+     *
+     * @param {number} tile_count
+     * @returns {WFCTileWeights}
+     */
+    static uniform(tile_count: number): WFCTileWeights;
+    /**
+     * @param {number[]|Float64Array} weights one strictly positive, finite weight per tile
+     */
+    constructor(weights: number[] | Float64Array);
+    /** @type {number} */
+    tile_count: number;
+    /** @type {Float64Array} */
+    weight: Float64Array;
+    /**
+     * `w · ln(w)`, the numerator term of the Shannon entropy of a weighted domain.
+     * @type {Float64Array}
+     */
+    weight_log_weight: Float64Array;
+    /**
+     * Sum over every tile — the value a pristine cell's running sum starts at.
+     * @type {number}
+     */
+    total_weight: number;
+    /**
+     * @type {number}
+     */
+    total_weight_log_weight: number;
+}
+//# sourceMappingURL=WFCTileWeights.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WFCTileWeights.d.ts","sourceRoot":"","sources":["../../../../src/core/wfc/WFCTileWeights.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;GAeG;AACH;IAwDI;;;;;OAKG;IACH,2BAHW,MAAM,GACJ,cAAc,CAM1B;IAjED;;OAEG;IACH,qBAFW,MAAM,EAAE,GAAC,YAAY,EAoD/B;IA3CG,qBAAqB;IACrB,YADW,MAAM,CACW;IAE5B,2BAA2B;IAC3B,QADW,YAAY,CACmB;IAE1C;;;OAGG;IACH,mBAFU,YAAY,CAE+B;IAuBrD;;;OAGG;IACH,cAFU,MAAM,CAES;IAEzB;;OAEG;IACH,yBAFU,MAAM,CAEwB;CAc/C"}