@woosh/meep-engine 3.28.0 → 3.30.0

package/src/core/model/node-graph/visual/layout/NodeGraphLayoutOptions.d.ts

@@ -1,55 +1,15 @@
 /**
- * Every number the layout is allowed to be tuned by.
+ * Every number the layout is allowed to be tuned by, the router's included.
  *
- * They live in one place because they are not independent: the room a channel has for tracks is set
- * by `layer_gap`, the room a wire lane has is set by `wire_gap`, and a router told to bend for less
- * than it costs to go around will do neither well. Somebody changing one of these needs to see the
- * others.
+ * The placement half of them is {@link BoxLayoutOptions}, and what is added here is not independent
+ * of it: the room a channel has for tracks is set by `layer_gap`, the room a wire lane has is set by
+ * `wire_gap`, and a router told to bend for less than it costs to go around will do neither well.
+ * Somebody changing one of these needs to see the others.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
-export class NodeGraphLayoutOptions {
-    /**
-     * @param {Partial<NodeGraphLayoutOptions>} [overrides]
-     * @returns {NodeGraphLayoutOptions}
-     */
-    static from(overrides?: Partial<NodeGraphLayoutOptions>): NodeGraphLayoutOptions;
-    /**
-     * Horizontal gap between one column of boxes and the next.
-     *
-     * This is the width of the channel every edge crossing that boundary has to share, so it is
-     * also what limits how many wires can run side by side without one of them having to detour.
-     *
-     * @type {number}
-     */
-    layer_gap: number;
-    /**
-     * Vertical gap between two node boxes sharing a column.
-     * @type {number}
-     */
-    node_gap: number;
-    /**
-     * Vertical room reserved for one wire passing through a column it does not stop at.
-     *
-     * An edge spanning several columns gets a lane of this height in each one it crosses, which is
-     * what keeps a long edge from being drawn over the boxes it passes.
-     *
-     * @type {number}
-     */
-    wire_gap: number;
-    /**
-     * How far outside a box the router runs alongside it, and how far a wire leaves its port before
-     * it is allowed to turn.
-     *
-     * It is one number because it is one line: the grid's line around a box is where a wire
-     * alongside it runs, and it is also the first place a wire leaving a port can turn. A wire on
-     * the box boundary reads as touching it, and a wire that turns the moment it leaves a port
-     * makes it hard to see which port it belongs to.
-     *
-     * @type {number}
-     */
-    clearance: number;
+export class NodeGraphLayoutOptions extends BoxLayoutOptions {
     /**
      * Routing tracks placed across each channel, on top of the lines the boxes themselves induce.
      *
@@ -147,11 +107,6 @@ export class NodeGraphLayoutOptions {
      * @type {number}
      */
     corner_radius: number;
-    /**
-     * Ordering passes over the layers.
-     * @type {number}
-     */
-    order_sweeps: number;
     /**
      * Ceiling on the routing grid, in vertices.
      *
@@ -172,4 +127,5 @@ export class NodeGraphLayoutOptions {
      */
     max_route_expansions: number;
 }
+import { BoxLayoutOptions } from "../../../../graph/layout/layered/BoxLayoutOptions.js";
 //# sourceMappingURL=NodeGraphLayoutOptions.d.ts.map

package/src/core/model/node-graph/visual/layout/NodeGraphLayoutOptions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"NodeGraphLayoutOptions.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/model/node-graph/visual/layout/NodeGraphLayoutOptions.js"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH;IA8KI;;;OAGG;IACH,wBAHW,QAAQ,sBAAsB,CAAC,GAC7B,sBAAsB,CAclC;IA5LD;;;;;;;OAOG;IACH,WAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,UAFU,MAAM,CAEF;IAEd;;;;;;;OAOG;IACH,UAFU,MAAM,CAEF;IAEd;;;;;;;;;;OAUG;IACH,WAFU,MAAM,CAED;IAEf;;;;;;;;OAQG;IACH,gBAFU,MAAM,CAEG;IAEnB;;;;;;;;;OASG;IACH,cAFU,MAAM,CAEE;IAElB;;;;;;;;;;;OAWG;IACH,kBAFU,MAAM,CAEM;IAEtB;;;;;;;;;;;OAWG;IACH,oBAFU,MAAM,CAEO;IAEvB;;;;;;;;;;;;;OAaG;IACH,uBAFU,MAAM,CAEU;IAE1B;;;;;;;;;OASG;IACH,cAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,gBAFU,MAAM,CAEG;IAEnB;;;;;;;;OAQG;IACH,cAFU,MAAM,CAEC;IAEjB;;;;;;;OAOG;IACH,eAFU,MAAM,CAEG;IAEnB;;;OAGG;IACH,cAFU,MAAM,CAEC;IAEjB;;;;;;;;OAQG;IACH,mBAFU,MAAM,CAEY;IAE5B;;;;;;;OAOG;IACH,sBAFU,MAAM,CAEc;CAmBjC"}
+{"version":3,"file":"NodeGraphLayoutOptions.d.ts","sourceRoot":"","sources":["../../../../../../../src/core/model/node-graph/visual/layout/NodeGraphLayoutOptions.js"],"names":[],"mappings":"AAEA;;;;;;;;;;GAUG;AACH;IAEI;;;;;;;;OAQG;IACH,gBAFU,MAAM,CAEG;IAEnB;;;;;;;;;OASG;IACH,cAFU,MAAM,CAEE;IAElB;;;;;;;;;;;OAWG;IACH,kBAFU,MAAM,CAEM;IAEtB;;;;;;;;;;;OAWG;IACH,oBAFU,MAAM,CAEO;IAEvB;;;;;;;;;;;;;OAaG;IACH,uBAFU,MAAM,CAEU;IAE1B;;;;;;;;;OASG;IACH,cAFU,MAAM,CAEC;IAEjB;;;OAGG;IACH,gBAFU,MAAM,CAEG;IAEnB;;;;;;;;OAQG;IACH,cAFU,MAAM,CAEC;IAEjB;;;;;;;OAOG;IACH,eAFU,MAAM,CAEG;IAEnB;;;;;;;;OAQG;IACH,mBAFU,MAAM,CAEY;IAE5B;;;;;;;OAOG;IACH,sBAFU,MAAM,CAEc;CACjC;iCA7IgC,sDAAsD"}

package/src/core/model/node-graph/visual/layout/NodeGraphLayoutOptions.js

@@ -1,54 +1,17 @@
+import { BoxLayoutOptions } from "../../../../graph/layout/layered/BoxLayoutOptions.js";
+
 /**
- * Every number the layout is allowed to be tuned by.
+ * Every number the layout is allowed to be tuned by, the router's included.
  *
- * They live in one place because they are not independent: the room a channel has for tracks is set
- * by `layer_gap`, the room a wire lane has is set by `wire_gap`, and a router told to bend for less
- * than it costs to go around will do neither well. Somebody changing one of these needs to see the
- * others.
+ * The placement half of them is {@link BoxLayoutOptions}, and what is added here is not independent
+ * of it: the room a channel has for tracks is set by `layer_gap`, the room a wire lane has is set by
+ * `wire_gap`, and a router told to bend for less than it costs to go around will do neither well.
+ * Somebody changing one of these needs to see the others.
  *
  * @author Alex Goldring
  * @copyright Company Named Limited (c) 2026
  */
-export class NodeGraphLayoutOptions {
-
-    /**
-     * Horizontal gap between one column of boxes and the next.
-     *
-     * This is the width of the channel every edge crossing that boundary has to share, so it is
-     * also what limits how many wires can run side by side without one of them having to detour.
-     *
-     * @type {number}
-     */
-    layer_gap = 140;
-
-    /**
-     * Vertical gap between two node boxes sharing a column.
-     * @type {number}
-     */
-    node_gap = 44;
-
-    /**
-     * Vertical room reserved for one wire passing through a column it does not stop at.
-     *
-     * An edge spanning several columns gets a lane of this height in each one it crosses, which is
-     * what keeps a long edge from being drawn over the boxes it passes.
-     *
-     * @type {number}
-     */
-    wire_gap = 20;
-
-    /**
-     * How far outside a box the router runs alongside it, and how far a wire leaves its port before
-     * it is allowed to turn.
-     *
-     * It is one number because it is one line: the grid's line around a box is where a wire
-     * alongside it runs, and it is also the first place a wire leaving a port can turn. A wire on
-     * the box boundary reads as touching it, and a wire that turns the moment it leaves a port
-     * makes it hard to see which port it belongs to.
-     *
-     * @type {number}
-     */
-    clearance = 24;
+export class NodeGraphLayoutOptions extends BoxLayoutOptions {
 
     /**
      * Routing tracks placed across each channel, on top of the lines the boxes themselves induce.
@@ -156,12 +119,6 @@ export class NodeGraphLayoutOptions {
      */
     corner_radius = 30;
 
-    /**
-     * Ordering passes over the layers.
-     * @type {number}
-     */
-    order_sweeps = 8;
-
     /**
      * Ceiling on the routing grid, in vertices.
      *
@@ -182,22 +139,4 @@ export class NodeGraphLayoutOptions {
      * @type {number}
      */
     max_route_expansions = 200000;
-
-    /**
-     * @param {Partial<NodeGraphLayoutOptions>} [overrides]
-     * @returns {NodeGraphLayoutOptions}
-     */
-    static from(overrides) {
-        const r = new NodeGraphLayoutOptions();
-
-        if (overrides !== undefined) {
-            for (const key in overrides) {
-                if (key in r) {
-                    r[key] = overrides[key];
-                }
-            }
-        }
-
-        return r;
-    }
 }

package/src/core/model/node-graph/visual/layout/layout_build_problem.js

@@ -1,5 +1,5 @@
 import { number_compare_ascending } from "../../../../primitives/numbers/number_compare_ascending.js";
-import { LayoutBoxGraph, LAYOUT_BOX_NODE } from "./LayoutBoxGraph.js";
+import { LayoutBoxGraph, LAYOUT_BOX_NODE } from "../../../../graph/layout/layered/LayoutBoxGraph.js";
 import { LayoutProblem, layout_side_of } from "./LayoutProblem.js";
 
 /**

package/src/core/model/node-graph/visual/layout/layout_node_graph.js

@@ -1,10 +1,10 @@
-import { layout_assign_coordinates } from "./layout_assign_coordinates.js";
-import { layout_assign_layers } from "./layout_assign_layers.js";
-import { layout_break_cycles } from "./layout_break_cycles.js";
+import { layout_assign_coordinates } from "../../../../graph/layout/layered/layout_assign_coordinates.js";
+import { layout_assign_layers } from "../../../../graph/layout/layered/layout_assign_layers.js";
+import { layout_break_cycles } from "../../../../graph/layout/layered/layout_break_cycles.js";
 import { layout_build_problem } from "./layout_build_problem.js";
-import { layout_insert_lanes } from "./layout_insert_lanes.js";
-import { layout_order_layers } from "./layout_order_layers.js";
-import { layout_orient_links } from "./layout_orient_links.js";
+import { layout_insert_lanes } from "../../../../graph/layout/layered/layout_insert_lanes.js";
+import { layout_order_layers } from "../../../../graph/layout/layered/layout_order_layers.js";
+import { layout_orient_links } from "../../../../graph/layout/layered/layout_orient_links.js";
 import { NodeGraphLayoutOptions } from "./NodeGraphLayoutOptions.js";
 import { route_connections } from "./route_connections.js";
 import { route_grid_build } from "./route_grid_build.js";

package/src/core/model/node-graph/visual/layout/route_grid_build.js

@@ -1,4 +1,4 @@
-import { LAYOUT_BOX_LANE } from "./LayoutBoxGraph.js";
+import { LAYOUT_BOX_LANE } from "../../../../graph/layout/layered/LayoutBoxGraph.js";
 import { number_compare_ascending } from "../../../../primitives/numbers/number_compare_ascending.js";
 import { LAYOUT_SIDE_BOTTOM, LAYOUT_SIDE_TOP } from "./LayoutProblem.js";
 import { ROUTE_GRID_EPSILON, RouteGrid } from "./RouteGrid.js";

package/src/core/model/object/ImmutableObjectPool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ImmutableObjectPool.d.ts","sourceRoot":"","sources":["../../../../../src/core/model/object/ImmutableObjectPool.js"],"names":[],"mappings":"AAIA;;GAEG;AACH;IA+BI;;;OAaC;IA3CD;;;OAGG;IACH,wBAAwB;IACxB;;;OAGG;IACH,MAFU,QAAQ,GAAG,EAAE,aAAa,GAAG,EAAC,KAAK,CAAC,EAAE,CAAC,CAE5B;IAErB;;;;OAIG;IACH,gBAAe;IACf;;;;OAIG;IACH,eAAc;IAEd;;;OAGG;IACH,MAFU,MAAM,CAEP;IAIL;;;OAGG;IACH,UAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,gBAFU,MAAM,CAEoB;IAGxC,qBAuBC;IAED;;;;;OAKG;IACH,yBAUC;IAED;;;OAGG;IACH,cAIC;IAED;;;;OAIG;IACH,wBAkBC;IAED,mCA2CC;CACJ;wBA9KuB,iCAAiC;6BAD5B,6BAA6B"}
+{"version":3,"file":"ImmutableObjectPool.d.ts","sourceRoot":"","sources":["../../../../../src/core/model/object/ImmutableObjectPool.js"],"names":[],"mappings":"AAIA;;GAEG;AACH;IA+BI;;;OAaC;IA3CD;;;OAGG;IACH,wBAAwB;IACxB;;;OAGG;IACH,MAFU,QAAQ,GAAG,EAAE,aAAa,GAAG,EAAC,KAAK,CAAC,EAAE,CAAC,CAE5B;IAErB;;;;OAIG;IACH,gBAAe;IACf;;;;OAIG;IACH,eAAc;IAEd;;;OAGG;IACH,MAFU,MAAM,CAEP;IAIL;;;OAGG;IACH,UAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,gBAFU,MAAM,CAEoB;IAGxC,qBAuBC;IAED;;;;;OAKG;IACH,yBAUC;IAED;;;OAGG;IACH,cAIC;IAED;;;;OAIG;IACH,wBAkBC;IAED,mCAqDC;CACJ;wBAxLuB,iCAAiC;6BAD5B,6BAA6B"}

package/src/core/model/object/ImmutableObjectPool.js

@@ -131,14 +131,9 @@ export class ImmutableObjectPool {
 
     add(key, value) {
 
-        let elements = this.data.get(key);
-
-        if (elements === undefined) {
-            // no elements for this key, create container
-            elements = [];
-            this.data.set(key, elements);
+        const existing_elements = this.data.get(key);
 
-        } else if (elements.length >= this.perKeyCapacity) {
+        if (existing_elements !== undefined && existing_elements.length >= this.perKeyCapacity) {
             // reached capacity for this key, discard element
             return false;
         }
@@ -149,6 +144,21 @@ export class ImmutableObjectPool {
             this.__removeElement(this.__first);
         }
 
+        /**
+         * Resolved after the eviction, never before. When the victim is the last element under this
+         * same key, `__removeElement` deletes the bucket out of the map — a reference taken before
+         * that points at an array nothing can reach any more, and the element pushed into it is
+         * counted in `size` and linked into the eviction list but invisible to `get`, which then
+         * makes `clear` throw when it walks the list onto it.
+         */
+        let elements = this.data.get(key);
+
+        if (elements === undefined) {
+            // no elements for this key, create container
+            elements = [];
+            this.data.set(key, elements);
+        }
+
         const cache_element = new CacheElement();
 
         cache_element.value = value;

package/src/core/process/executor/ConcurrentExecutor.d.ts

@@ -85,11 +85,7 @@ declare class ConcurrentExecutor {
      * @returns {boolean}
      */
     contains(task: Task): boolean;
-    /**
-     * kicks the scheduler into action, this is an internal method and should not be called from outside
-     * @private
-     */
-    private prod;
+    prod(): void;
     join(callback: any): void;
     #private;
 }

package/src/core/process/executor/ConcurrentExecutor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ConcurrentExecutor.d.ts","sourceRoot":"","sources":["../../../../../src/core/process/executor/ConcurrentExecutor.js"],"names":[],"mappings":";mBAQa,OAAO,iBAAiB,EAAE,IAAI;wBAC9B,OAAO,sBAAsB,EAAE,OAAO;AAYnD;;GAEG;AACH;IAaI;;;;;OAKG;IACH,wBAJW,MAAM,aACN,MAAM,EAwChB;IApCG;;;OAGG;IACH,WAFU,MAAM,CAEU;IAC1B;;;OAGG;IACH,UAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,iBAFU,IAAI,EAAE,CAES;IAEzB;;;OAGG;IACH,YAFU,IAAI,EAAE,CAEI;IAEpB;;;;MAIC;IAED,cAAiB;IAEjB;;;OAGG;IACH,QAFU,MAAM,GAAC,gBAAgB,CAES;IAG9C;;;OAGG;IACH,oBAFW,SAAS,QAqEnB;IAED;;;OAGG;IACH,mBAFW,SAAS,QAenB;IAED;;;;OAIG;IACH,iBAHW,IAAI,GACH,OAAO,CAwBlB;IAED;;;OAGG;IACH,UAFW,IAAI,QAKd;IAED;;;OAGG;IACH,eAFW,IAAI,EAAE,QAMhB;IAED;;;;OAIG;IACH,kBAkCC;IAED;;OAEG;IACH,qBAyCC;IAED;;;;OAIG;IACH,eAHW,IAAI,GACF,OAAO,CAYnB;IAwLD;;;OAGG;IACH,aAQC;IAED,0BAMC;;CACJ;;;;mBAhhBkB,+BAA+B;wBAohBxC,MAAM"}
+{"version":3,"file":"ConcurrentExecutor.d.ts","sourceRoot":"","sources":["../../../../../src/core/process/executor/ConcurrentExecutor.js"],"names":[],"mappings":";mBASa,OAAO,iBAAiB,EAAE,IAAI;wBAC9B,OAAO,sBAAsB,EAAE,OAAO;AAYnD;;GAEG;AACH;IAaI;;;;;OAKG;IACH,wBAJW,MAAM,aACN,MAAM,EAwChB;IApCG;;;OAGG;IACH,WAFU,MAAM,CAEU;IAC1B;;;OAGG;IACH,UAFU,MAAM,CAEQ;IAExB;;;OAGG;IACH,iBAFU,IAAI,EAAE,CAES;IAEzB;;;OAGG;IACH,YAFU,IAAI,EAAE,CAEI;IAEpB;;;;MAIC;IAED,cAAiB;IAEjB;;;OAGG;IACH,QAFU,MAAM,GAAC,gBAAgB,CAES;IAG9C;;;OAGG;IACH,oBAFW,SAAS,QAqEnB;IAED;;;OAGG;IACH,mBAFW,SAAS,QAenB;IAED;;;;OAIG;IACH,iBAHW,IAAI,GACH,OAAO,CAwBlB;IAED;;;OAGG;IACH,UAFW,IAAI,QAKd;IAED;;;OAGG;IACH,eAFW,IAAI,EAAE,QAMhB;IAED;;;;OAIG;IACH,kBAkCC;IAED;;OAEG;IACH,qBAgDC;IAED;;;;OAIG;IACH,eAHW,IAAI,GACF,OAAO,CAYnB;IA8QD,aAYC;IAED,0BAMC;;CACJ;;;;mBA9mBkB,+BAA+B;wBAknBxC,MAAM"}

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
+};