@woosh/meep-engine 3.29.0 → 3.30.0

package/src/core/process/executor/ConcurrentExecutor.js

@@ -4,6 +4,7 @@ import { IllegalStateException } from "../../fsm/exceptions/IllegalStateExceptio
 import { objectKeyByValue } from "../../model/object/objectKeyByValue.js";
 import { TaskSignal } from "../task/TaskSignal.js";
 import TaskState from "../task/TaskState.js";
+import { task_find_dependency_cycle } from "../task/task_find_dependency_cycle.js";
 
 /**
  * @typedef {import("../task/Task.js").Task} Task
@@ -294,7 +295,14 @@ class ConcurrentExecutor {
                     // Dropping it from the queue is not enough: the task still
                     // has to reach a terminal state, or its promise never
                     // settles and everything awaiting it waits forever.
-                    unresolvedTask.state.set(TaskState.FAILED);
+                    //
+                    // Nor is the state enough on its own. `Task.join` reads the
+                    // state only at the moment it is called and otherwise
+                    // subscribes to `on.failed`, so a caller that takes the
+                    // promise before submitting the task was left waiting on a
+                    // signal nothing sent. The executor's other two terminal
+                    // transitions both dispatch; this one used not to.
+                    this.#fail_unresolved_task(unresolvedTask);
 
                     // its own dependants are now resolvable too, and they may
                     // sit earlier in the queue, so rescan from the start the
@@ -368,6 +376,38 @@ class ConcurrentExecutor {
 
     }
 
+    /**
+     * Fail a task that never got as far as the ready queue, because one of its dependencies failed.
+     * @param {Task} task
+     * @private
+     */
+    #fail_unresolved_task(task) {
+        const dependencies = task.dependencies;
+
+        let culprit = undefined;
+
+        for (let i = 0; i < dependencies.length; i++) {
+            if (dependencies[i].state.getValue() === TaskState.FAILED) {
+                culprit = dependencies[i];
+                break;
+            }
+        }
+
+        const reason = new Error(
+            `Task '${task.name}' failed because its dependency '${culprit === undefined ? '?' : culprit.name}' failed`
+        );
+
+        task.state.set(TaskState.FAILED);
+        task.on.failed.send1(reason);
+
+        if (!task.on.failed.hasHandlers()) {
+            // no one is watching for task failure
+            console.warn(`Task '${task.name}' failed.`, reason);
+        }
+
+        this.on.task_completed.send1(task);
+    }
+
     /**
      *
      * @param {Task} task
@@ -510,9 +550,63 @@ class ConcurrentExecutor {
      * kicks the scheduler into action, this is an internal method and should not be called from outside
      * @private
      */
+    /**
+     * Fail every task sitting on a dependency cycle, and then everything that depended on one.
+     *
+     * A cycle is the one form of "nothing can run" that no later `run` can rescue — an unsubmitted
+     * dependency is the other, and that one is a legal pattern here, so idleness alone is not the
+     * test. Left alone a cycle stopped the executor with no signal at all: `queueReady` never grows,
+     * `#executeTimeSlice` is the only place `on.completed` is sent and is never entered, so `join`
+     * subscribes to a signal that cannot fire and the task promises never settle.
+     * @private
+     */
+    #fail_dependency_cycles() {
+        for (
+            let cycle = task_find_dependency_cycle(this.queueUnresolved);
+            cycle !== null;
+            cycle = task_find_dependency_cycle(this.queueUnresolved)
+        ) {
+            const description = cycle.map(t => t.name).join(' -> ');
+
+            const reason = new Error(`Task dependency cycle: ${description} -> ${cycle[0].name}`);
+
+            console.error(reason.message, cycle.slice());
+
+            for (let i = 0; i < cycle.length; i++) {
+                const task = cycle[i];
+
+                const index = this.queueUnresolved.indexOf(task);
+
+                if (index !== -1) {
+                    this.queueUnresolved.splice(index, 1);
+                }
+
+                // as with any other failure, the task still has to reach a terminal state or its
+                // promise never settles and everything awaiting it waits forever
+                task.state.set(TaskState.FAILED);
+                task.on.failed.send1(reason);
+
+                this.on.task_completed.send1(task);
+            }
+
+            // the dependants of what just failed are resolvable now, as failures
+            this.resolveTasks();
+        }
+
+        if (this.queueReady.length === 0 && this.queueUnresolved.length === 0) {
+            // nothing is left to run, and `#executeTimeSlice` — which is what normally announces
+            // that — was never entered, so anything waiting on `join` would wait forever
+            this.on.completed.send0();
+        }
+    }
+
     prod() {
         this.resolveTasks();
 
+        if (!this.busy && this.queueReady.length === 0 && this.queueUnresolved.length > 0) {
+            this.#fail_dependency_cycles();
+        }
+
         if (!this.busy && this.queueReady.length > 0) {
             this.busy = true;
             this.#executeTimeSlice();

package/src/core/process/task/task_find_dependency_cycle.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Find one dependency cycle reachable from `roots`, following {@link Task#dependencies}.
+ *
+ * A cycle can never resolve: every task on it waits for a task that is waiting for it, so all of them
+ * stay INITIAL forever. Unlike a dependency that simply has not been submitted yet, no later `run`
+ * can rescue it — which is what makes this, and not "the executor is idle with work outstanding", the
+ * safe test for a deadlock.
+ *
+ * Iterative rather than recursive: task graphs are authored by hand but are not bounded in depth, and
+ * a stack overflow while diagnosing a hang is not an improvement on the hang.
+ *
+ * @param {Task[]} roots
+ * @returns {Task[]|null} the tasks on a cycle, in dependency order, or null if there is none. The
+ *  first element depends on the last.
+ */
+export function task_find_dependency_cycle(roots: Task[]): Task[] | null;
+//# sourceMappingURL=task_find_dependency_cycle.d.ts.map

package/src/core/process/task/task_find_dependency_cycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task_find_dependency_cycle.d.ts","sourceRoot":"","sources":["../../../../../src/core/process/task/task_find_dependency_cycle.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;;GAcG;AACH,kDAJW,MAAM,GACJ,MAAM,GAAC,IAAI,CAkDvB"}

package/src/core/process/task/task_find_dependency_cycle.js

@@ -0,0 +1,81 @@
+/**
+ * Not yet visited. Absent from the map, in practice — named for the comparison below.
+ * @type {number}
+ */
+const UNVISITED = 0;
+
+/**
+ * On the current DFS path. An edge back to one of these is a cycle.
+ * @type {number}
+ */
+const ON_PATH = 1;
+
+/**
+ * Fully explored, and no cycle was found through it.
+ * @type {number}
+ */
+const EXPLORED = 2;
+
+/**
+ * Find one dependency cycle reachable from `roots`, following {@link Task#dependencies}.
+ *
+ * A cycle can never resolve: every task on it waits for a task that is waiting for it, so all of them
+ * stay INITIAL forever. Unlike a dependency that simply has not been submitted yet, no later `run`
+ * can rescue it — which is what makes this, and not "the executor is idle with work outstanding", the
+ * safe test for a deadlock.
+ *
+ * Iterative rather than recursive: task graphs are authored by hand but are not bounded in depth, and
+ * a stack overflow while diagnosing a hang is not an improvement on the hang.
+ *
+ * @param {Task[]} roots
+ * @returns {Task[]|null} the tasks on a cycle, in dependency order, or null if there is none. The
+ *  first element depends on the last.
+ */
+export function task_find_dependency_cycle(roots) {
+    const states = new Map();
+
+    const root_count = roots.length;
+
+    for (let r = 0; r < root_count; r++) {
+        const root = roots[r];
+
+        if (states.get(root) === EXPLORED) {
+            continue;
+        }
+
+        const path = [root];
+
+        //frame `i` holds how many of `path[i]`'s dependencies have been taken
+        const cursors = [0];
+
+        states.set(root, ON_PATH);
+
+        while (path.length > 0) {
+            const depth = path.length - 1;
+            const task = path[depth];
+            const dependencies = task.dependencies;
+
+            if (cursors[depth] < dependencies.length) {
+                const dependency = dependencies[cursors[depth]];
+
+                cursors[depth]++;
+
+                const state = states.get(dependency) ?? UNVISITED;
+
+                if (state === ON_PATH) {
+                    return path.slice(path.indexOf(dependency));
+                } else if (state === UNVISITED) {
+                    states.set(dependency, ON_PATH);
+                    path.push(dependency);
+                    cursors.push(0);
+                }
+            } else {
+                states.set(task, EXPLORED);
+                path.pop();
+                cursors.pop();
+            }
+        }
+    }
+
+    return null;
+}

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

@@ -0,0 +1,17 @@
+/**
+ * Which cell the solver collapses next.
+ *
+ * Affects how reliably a solve finishes and how the output looks. It never affects *which* tile a
+ * cell ends up with — that is always a weighted draw — only the order cells are decided in.
+ *
+ * {@link SCANLINE } is the default and solves rule sets the other two fail on. Reach for
+ * {@link ENTROPY } when the character of the output matters more than first-time success.
+ * `WFC_DESIGN.md` §4.4 carries the measurements behind that.
+ */
+export type WFCCellChoice = number;
+export namespace WFCCellChoice {
+    let ENTROPY: number;
+    let MINIMUM_REMAINING: number;
+    let SCANLINE: number;
+}
+//# sourceMappingURL=WFCCellChoice.d.ts.map

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

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

package/src/core/wfc/WFCCellChoice.js

@@ -0,0 +1,36 @@
+/**
+ * Which cell the solver collapses next.
+ *
+ * Affects how reliably a solve finishes and how the output looks. It never affects *which* tile a
+ * cell ends up with — that is always a weighted draw — only the order cells are decided in.
+ *
+ * {@link SCANLINE} is the default and solves rule sets the other two fail on. Reach for
+ * {@link ENTROPY} when the character of the output matters more than first-time success.
+ * `WFC_DESIGN.md` §4.4 carries the measurements behind that.
+ *
+ * @readonly
+ * @enum {number}
+ */
+export const WFCCellChoice = {
+    /**
+     * Lowest Shannon entropy over the remaining weights. The only policy in which weights affect
+     * the order cells are decided in, which is what gives its output an organic look; it is what
+     * Gumin's original and DeBroglie both default to.
+     *
+     * Needs a priority queue, and fails on rule sets the other two solve.
+     */
+    ENTROPY: 0,
+    /**
+     * Fewest remaining possibilities. Identical to {@link ENTROPY} when every weight is equal, and
+     * an integer comparison rather than a logarithm. Needs the same priority queue.
+     */
+    MINIMUM_REMAINING: 1,
+    /**
+     * Ascending cell index, skipping cells already decided. The default: no priority structure,
+     * and the policy most likely to solve a given rule set.
+     *
+     * Its cost is a directional bias in the output. Solving in blocks
+     * (see {@link wfc_state_set_eligible}) confines that bias to a block.
+     */
+    SCANLINE: 2
+};

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

@@ -0,0 +1,105 @@
+/**
+ * Largest number of axes an {@link WFCLattice} can have.
+ *
+ * {@link WFCLattice#edge_flags} spends two bits per axis — one per side — in a `u32`.
+ * @type {number}
+ */
+export const WFC_MAX_DIMENSION_COUNT: number;
+/**
+ * An N-dimensional box of cells with per-axis wrapping. The topology the solver ships with, and
+ * the reason dimensionality is a number rather than three separate implementations.
+ *
+ * `WFCLattice.from_shape([64])` is 1-D, `[16, 16, 16]` is 3-D, `[8, 8, 8, 8]` is 4-D. Cells are
+ * numbered row-major — the last axis varies fastest — and {@link index_of} / {@link coordinate_of}
+ * convert between a cell index and coordinates.
+ *
+ * Direction `d` is `axis = d >> 1`, `side = d & 1` (0 toward the lower coordinate), and `d ^ 1` is
+ * the opposite direction. There are `2 × dimension_count` of them.
+ *
+ * At most {@link WFC_MAX_DIMENSION_COUNT} axes, which is what {@link edge_flags} can describe.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class WFCLattice {
+    /**
+     * @param {number[]|Uint32Array} shape
+     * @param {boolean[]|Uint8Array} [wrap]
+     * @returns {WFCLattice}
+     */
+    static from_shape(shape: number[] | Uint32Array, wrap?: boolean[] | Uint8Array): WFCLattice;
+    /**
+     * Prefer {@link WFCLattice.from_shape}.
+     *
+     * @param {number[]|Uint32Array} shape extent along each axis, every entry at least 1
+     * @param {boolean[]|Uint8Array} [wrap] per axis; defaults to no wrapping
+     */
+    constructor(shape: number[] | Uint32Array, wrap?: boolean[] | Uint8Array);
+    /** @type {number} */
+    dimension_count: number;
+    /** @type {number} */
+    direction_count: number;
+    /** @type {Uint32Array} */
+    shape: Uint32Array;
+    /** @type {Uint8Array} */
+    wrap: Uint8Array;
+    /** @type {number} */
+    cell_count: number;
+    /**
+     * Row-major: the last axis is the fastest-varying.
+     * @type {Uint32Array}
+     */
+    strides: Uint32Array;
+    /**
+     * `neighbour_offsets[d]` — what to add to a cell index to step in direction `d`, valid
+     * only when the cell is not on the face `d` points off.
+     * @type {Int32Array}
+     */
+    neighbour_offsets: Int32Array;
+    /**
+     * `wrap_offsets[d]` — what to add instead when the cell *is* on the face `d` points off
+     * and that axis wraps.
+     *
+     * An axis of extent 1 gives an offset of zero, making the cell its own neighbour. That is
+     * correct — stepping off a one-cell ring lands back where it started — and it means such a
+     * tile must be compatible with itself along that axis.
+     * @type {Int32Array}
+     */
+    wrap_offsets: Int32Array;
+    /**
+     * Bit `d` set means the neighbour in direction `d` is outside the lattice.
+     * @type {Uint32Array}
+     */
+    edge_flags: Uint32Array;
+    /**
+     * Mark the two faces of every axis.
+     *
+     * @private
+     */
+    private __build_edge_flags;
+    /**
+     * Cell index of a coordinate — how a caller turns its own coordinates into the cell ids this
+     * module speaks in.
+     *
+     * @param {number[]|Uint32Array} coordinate one entry per axis
+     * @returns {number}
+     */
+    index_of(coordinate: number[] | Uint32Array): number;
+    /**
+     * Inverse of {@link index_of}, written into `out`.
+     *
+     * @param {number[]|Uint32Array} out at least `dimension_count` long
+     * @param {number} index
+     */
+    coordinate_of(out: number[] | Uint32Array, index: number): void;
+    /**
+     * The neighbour of `cell` in direction `direction`, or `-1` when there is none — off a
+     * non-wrapping face.
+     *
+     * @param {number} cell
+     * @param {number} direction
+     * @returns {number} neighbour cell index, or -1
+     */
+    neighbour_of(cell: number, direction: number): number;
+}
+//# sourceMappingURL=WFCLattice.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"WFCLattice.d.ts","sourceRoot":"","sources":["../../../../src/core/wfc/WFCLattice.js"],"names":[],"mappings":"AAEA;;;;;GAKG;AACH,sCAFU,MAAM,CAE0B;AAE1C;;;;;;;;;;;;;;;GAeG;AACH;IAwMI;;;;OAIG;IACH,yBAJW,MAAM,EAAE,GAAC,WAAW,SACpB,OAAO,EAAE,GAAC,UAAU,GAClB,UAAU,CAItB;IA9MD;;;;;OAKG;IACH,mBAHW,MAAM,EAAE,GAAC,WAAW,SACpB,OAAO,EAAE,GAAC,UAAU,EAgG9B;IA9EG,qBAAqB;IACrB,iBADW,MAAM,CACqB;IACtC,qBAAqB;IACrB,iBADW,MAAM,CACyB;IAE1C,0BAA0B;IAC1B,OADW,WAAW,CACuB;IAC7C,yBAAyB;IACzB,MADW,UAAU,CACsB;IAmB3C,qBAAqB;IACrB,YADW,MAAM,CACW;IAE5B;;;OAGG;IACH,SAFU,WAAW,CAE0B;IAQ/C;;;;OAIG;IACH,mBAFU,UAAU,CAEyC;IAE7D;;;;;;;;OAQG;IACH,cAFU,UAAU,CAEoC;IAaxD;;;OAGG;IACH,YAFU,WAAW,CAEwB;IAKjD;;;;OAIG;IACH,2BAmBC;IAED;;;;;;OAMG;IACH,qBAHW,MAAM,EAAE,GAAC,WAAW,GAClB,MAAM,CAiBlB;IAED;;;;;OAKG;IACH,mBAHW,MAAM,EAAE,GAAC,WAAW,SACpB,MAAM,QAgBhB;IAED;;;;;;;OAOG;IACH,mBAJW,MAAM,aACN,MAAM,GACJ,MAAM,CAiBlB;CAUJ"}

package/src/core/wfc/WFCLattice.js

@@ -0,0 +1,235 @@
+import { assert } from "../assert.js";
+
+/**
+ * Largest number of axes an {@link WFCLattice} can have.
+ *
+ * {@link WFCLattice#edge_flags} spends two bits per axis — one per side — in a `u32`.
+ * @type {number}
+ */
+export const WFC_MAX_DIMENSION_COUNT = 16;
+
+/**
+ * An N-dimensional box of cells with per-axis wrapping. The topology the solver ships with, and
+ * the reason dimensionality is a number rather than three separate implementations.
+ *
+ * `WFCLattice.from_shape([64])` is 1-D, `[16, 16, 16]` is 3-D, `[8, 8, 8, 8]` is 4-D. Cells are
+ * numbered row-major — the last axis varies fastest — and {@link index_of} / {@link coordinate_of}
+ * convert between a cell index and coordinates.
+ *
+ * Direction `d` is `axis = d >> 1`, `side = d & 1` (0 toward the lower coordinate), and `d ^ 1` is
+ * the opposite direction. There are `2 × dimension_count` of them.
+ *
+ * At most {@link WFC_MAX_DIMENSION_COUNT} axes, which is what {@link edge_flags} can describe.
+ *
+ * @author Alex Goldring
+ * @copyright Company Named Limited (c) 2026
+ */
+export class WFCLattice {
+    /**
+     * Prefer {@link WFCLattice.from_shape}.
+     *
+     * @param {number[]|Uint32Array} shape extent along each axis, every entry at least 1
+     * @param {boolean[]|Uint8Array} [wrap] per axis; defaults to no wrapping
+     */
+    constructor(shape, wrap) {
+        assert.isArrayLike(shape, 'shape');
+
+        if (wrap !== undefined) {
+            assert.isArrayLike(wrap, 'wrap');
+            assert.greaterThanOrEqual(wrap.length, shape.length, 'wrap.length >= shape.length');
+        }
+
+        const dimension_count = shape.length;
+
+        assert.isPositiveInteger(dimension_count, 'shape.length');
+
+        if (dimension_count > WFC_MAX_DIMENSION_COUNT) {
+            throw new Error(`dimension_count(=${dimension_count}) exceeds ${WFC_MAX_DIMENSION_COUNT}; edge_flags holds two bits per axis`);
+        }
+
+        /** @type {number} */
+        this.dimension_count = dimension_count;
+        /** @type {number} */
+        this.direction_count = dimension_count * 2;
+
+        /** @type {Uint32Array} */
+        this.shape = new Uint32Array(dimension_count);
+        /** @type {Uint8Array} */
+        this.wrap = new Uint8Array(dimension_count);
+
+        let cell_count = 1;
+
+        for (let axis = 0; axis < dimension_count; axis++) {
+            const extent = shape[axis];
+
+            assert.isPositiveInteger(extent, 'shape[axis]');
+
+            this.shape[axis] = extent;
+            this.wrap[axis] = (wrap !== undefined && wrap[axis]) ? 1 : 0;
+
+            cell_count *= extent;
+        }
+
+        if (!Number.isSafeInteger(cell_count)) {
+            throw new Error(`cell count overflows: shape ${Array.from(shape).join('x')}`);
+        }
+
+        /** @type {number} */
+        this.cell_count = cell_count;
+
+        /**
+         * Row-major: the last axis is the fastest-varying.
+         * @type {Uint32Array}
+         */
+        this.strides = new Uint32Array(dimension_count);
+
+        this.strides[dimension_count - 1] = 1;
+
+        for (let axis = dimension_count - 2; axis >= 0; axis--) {
+            this.strides[axis] = this.strides[axis + 1] * this.shape[axis + 1];
+        }
+
+        /**
+         * `neighbour_offsets[d]` — what to add to a cell index to step in direction `d`, valid
+         * only when the cell is not on the face `d` points off.
+         * @type {Int32Array}
+         */
+        this.neighbour_offsets = new Int32Array(this.direction_count);
+
+        /**
+         * `wrap_offsets[d]` — what to add instead when the cell *is* on the face `d` points off
+         * and that axis wraps.
+         *
+         * An axis of extent 1 gives an offset of zero, making the cell its own neighbour. That is
+         * correct — stepping off a one-cell ring lands back where it started — and it means such a
+         * tile must be compatible with itself along that axis.
+         * @type {Int32Array}
+         */
+        this.wrap_offsets = new Int32Array(this.direction_count);
+
+        for (let axis = 0; axis < dimension_count; axis++) {
+            const stride = this.strides[axis];
+            const span = stride * (this.shape[axis] - 1);
+
+            this.neighbour_offsets[axis * 2] = -stride;
+            this.neighbour_offsets[axis * 2 + 1] = stride;
+
+            this.wrap_offsets[axis * 2] = span;
+            this.wrap_offsets[axis * 2 + 1] = -span;
+        }
+
+        /**
+         * Bit `d` set means the neighbour in direction `d` is outside the lattice.
+         * @type {Uint32Array}
+         */
+        this.edge_flags = new Uint32Array(cell_count);
+
+        this.__build_edge_flags();
+    }
+
+    /**
+     * Mark the two faces of every axis.
+     *
+     * @private
+     */
+    __build_edge_flags() {
+        const { cell_count, dimension_count, edge_flags, shape, strides } = this;
+
+        for (let axis = 0; axis < dimension_count; axis++) {
+            const stride = strides[axis];
+            const extent = shape[axis];
+            const block = stride * extent;
+            const high_offset = stride * (extent - 1);
+
+            const low_bit = 1 << (axis * 2);
+            const high_bit = 1 << (axis * 2 + 1);
+
+            for (let block_start = 0; block_start < cell_count; block_start += block) {
+                for (let k = 0; k < stride; k++) {
+                    edge_flags[block_start + k] |= low_bit;
+                    edge_flags[block_start + high_offset + k] |= high_bit;
+                }
+            }
+        }
+    }
+
+    /**
+     * Cell index of a coordinate — how a caller turns its own coordinates into the cell ids this
+     * module speaks in.
+     *
+     * @param {number[]|Uint32Array} coordinate one entry per axis
+     * @returns {number}
+     */
+    index_of(coordinate) {
+        assert.equal(coordinate.length, this.dimension_count, 'coordinate.length === dimension_count');
+
+        let index = 0;
+
+        for (let axis = 0; axis < this.dimension_count; axis++) {
+            const value = coordinate[axis];
+
+            assert.isNonNegativeInteger(value, 'coordinate[axis]');
+            assert.lessThan(value, this.shape[axis], 'coordinate[axis] < shape[axis]');
+
+            index += value * this.strides[axis];
+        }
+
+        return index;
+    }
+
+    /**
+     * Inverse of {@link index_of}, written into `out`.
+     *
+     * @param {number[]|Uint32Array} out at least `dimension_count` long
+     * @param {number} index
+     */
+    coordinate_of(out, index) {
+        assert.isArrayLike(out, 'out');
+        assert.greaterThanOrEqual(out.length, this.dimension_count, 'out.length >= dimension_count');
+        assert.isNonNegativeInteger(index, 'index');
+        assert.lessThan(index, this.cell_count, 'index < cell_count');
+
+        let rest = index;
+
+        for (let axis = 0; axis < this.dimension_count; axis++) {
+            const stride = this.strides[axis];
+
+            out[axis] = (rest / stride) | 0;
+            rest = rest % stride;
+        }
+    }
+
+    /**
+     * The neighbour of `cell` in direction `direction`, or `-1` when there is none — off a
+     * non-wrapping face.
+     *
+     * @param {number} cell
+     * @param {number} direction
+     * @returns {number} neighbour cell index, or -1
+     */
+    neighbour_of(cell, direction) {
+        assert.isNonNegativeInteger(cell, 'cell');
+        assert.isNonNegativeInteger(direction, 'direction');
+        assert.lessThan(cell, this.cell_count, 'cell < cell_count');
+        assert.lessThan(direction, this.direction_count, 'direction < direction_count');
+
+        if (((this.edge_flags[cell] >> direction) & 1) === 1) {
+            if (this.wrap[direction >> 1] === 0) {
+                return -1;
+            }
+
+            return cell + this.wrap_offsets[direction];
+        }
+
+        return cell + this.neighbour_offsets[direction];
+    }
+
+    /**
+     * @param {number[]|Uint32Array} shape
+     * @param {boolean[]|Uint8Array} [wrap]
+     * @returns {WFCLattice}
+     */
+    static from_shape(shape, wrap) {
+        return new WFCLattice(shape, wrap);
+    }
+}