@cubingcenter/scrambler 0.7.0 → 0.8.0

package/dist/puzzles/sq1/solver/browser-loader.js

@@ -1,29 +1,48 @@
 import { SQ1_SOLVER_TABLE_METADATA } from "./table-metadata.js";
 import { fetchTableBuffer } from "../../shared/compressed-fetch.js";
 const TABLES_DIR = "puzzles/sq1/solver/generated";
+const CACHE_NAME = "cubingcenter-scrambler-tables-v1";
 let cachedBrowserTables;
+let cachedBrowserTablesPromise;
 export function getCachedBrowserTables() {
     return cachedBrowserTables;
 }
 export function clearCachedBrowserTables() {
     cachedBrowserTables = undefined;
+    cachedBrowserTablesPromise = undefined;
 }
 export async function loadBrowserTables(baseUrl) {
     if (cachedBrowserTables) {
         return cachedBrowserTables;
     }
+    if (cachedBrowserTablesPromise) {
+        // One shared in-flight promise: concurrent calls trigger exactly one
+        // fetch pass (dedup).
+        return cachedBrowserTablesPromise;
+    }
+    const promise = fetchTables(baseUrl);
+    cachedBrowserTablesPromise = promise;
+    promise.then(() => { }, () => {
+        // A failed load must not poison the dedup slot: purge the rejected
+        // promise so a later call retries from scratch.
+        if (cachedBrowserTablesPromise === promise)
+            cachedBrowserTablesPromise = undefined;
+    });
+    return promise;
+}
+async function fetchTables(baseUrl) {
     const resolved = resolveBaseUrl(baseUrl);
     const manifest = await fetchManifest(resolved);
     const [shapeIdx, shapePrun, shapeTopMove, shapeBottomMove, shapeTwistMove, squareTwistMove, squareTopMove, squareBottomMove, squarePrun] = await Promise.all([
-        fetchInt32Table(resolved, manifest.files.shapeIdx, SQ1_SOLVER_TABLE_METADATA.shapeIdx.entries),
-        fetchInt8Table(resolved, manifest.files.shapePrun, SQ1_SOLVER_TABLE_METADATA.shapePrun.entries),
-        fetchInt32Table(resolved, manifest.files.shapeTopMove, SQ1_SOLVER_TABLE_METADATA.shapeTopMove.entries),
-        fetchInt32Table(resolved, manifest.files.shapeBottomMove, SQ1_SOLVER_TABLE_METADATA.shapeBottomMove.entries),
-        fetchInt32Table(resolved, manifest.files.shapeTwistMove, SQ1_SOLVER_TABLE_METADATA.shapeTwistMove.entries),
-        fetchUint16Table(resolved, manifest.files.squareTwistMove, SQ1_SOLVER_TABLE_METADATA.squareTwistMove.entries),
-        fetchUint16Table(resolved, manifest.files.squareTopMove, SQ1_SOLVER_TABLE_METADATA.squareTopMove.entries),
-        fetchUint16Table(resolved, manifest.files.squareBottomMove, SQ1_SOLVER_TABLE_METADATA.squareBottomMove.entries),
-        fetchInt8Table(resolved, manifest.files.squarePrun, SQ1_SOLVER_TABLE_METADATA.squarePrun.entries),
+        fetchInt32Table(resolved, manifest.files.shapeIdx, SQ1_SOLVER_TABLE_METADATA.shapeIdx),
+        fetchInt8Table(resolved, manifest.files.shapePrun, SQ1_SOLVER_TABLE_METADATA.shapePrun),
+        fetchInt32Table(resolved, manifest.files.shapeTopMove, SQ1_SOLVER_TABLE_METADATA.shapeTopMove),
+        fetchInt32Table(resolved, manifest.files.shapeBottomMove, SQ1_SOLVER_TABLE_METADATA.shapeBottomMove),
+        fetchInt32Table(resolved, manifest.files.shapeTwistMove, SQ1_SOLVER_TABLE_METADATA.shapeTwistMove),
+        fetchUint16Table(resolved, manifest.files.squareTwistMove, SQ1_SOLVER_TABLE_METADATA.squareTwistMove),
+        fetchUint16Table(resolved, manifest.files.squareTopMove, SQ1_SOLVER_TABLE_METADATA.squareTopMove),
+        fetchUint16Table(resolved, manifest.files.squareBottomMove, SQ1_SOLVER_TABLE_METADATA.squareBottomMove),
+        fetchInt8Table(resolved, manifest.files.squarePrun, SQ1_SOLVER_TABLE_METADATA.squarePrun),
     ]);
     cachedBrowserTables = {
         shapeIdx,
@@ -59,34 +78,47 @@ async function fetchManifest(baseUrl) {
     }
     return (await response.json());
 }
-async function fetchInt32Table(baseUrl, entry, expectedEntries) {
-    const buffer = await fetchTableBuffer(baseUrl, TABLES_DIR, entry.file, { compressed: entry.compressed !== false });
-    if (buffer.byteLength !== expectedEntries * 4) {
-        throw new Error(`Invalid byte size for ${entry.file}`);
-    }
-    const values = new Int32Array(expectedEntries);
+/**
+ * Fetch + verify with the SAME checks as node-loader.ts: byte length from
+ * the manifest entries, FNV-1a checksum against the table-metadata
+ * constants (node skips the checksum when that constant is 0 = "unchecked";
+ * the browser mirrors the guard).
+ */
+async function fetchInt32Table(baseUrl, entry, meta) {
+    const buffer = await fetchTableBuffer(baseUrl, TABLES_DIR, entry.file, {
+        cacheName: CACHE_NAME,
+        compressed: entry.compressed !== false,
+        expectedBytes: entry.entries * 4,
+        ...(meta.checksum !== 0 ? { expectedFnv1a: { value: meta.checksum, elementSize: 4 } } : {})
+    });
+    const values = new Int32Array(entry.entries);
     const view = new DataView(buffer);
     for (let i = 0; i < values.length; i++) {
         values[i] = view.getInt32(i * 4, true);
     }
     return values;
 }
-async function fetchUint16Table(baseUrl, entry, expectedEntries) {
-    const buffer = await fetchTableBuffer(baseUrl, TABLES_DIR, entry.file, { compressed: entry.compressed !== false });
-    if (buffer.byteLength !== expectedEntries * 2) {
-        throw new Error(`Invalid byte size for ${entry.file}`);
-    }
-    const values = new Uint16Array(expectedEntries);
+async function fetchUint16Table(baseUrl, entry, meta) {
+    const buffer = await fetchTableBuffer(baseUrl, TABLES_DIR, entry.file, {
+        cacheName: CACHE_NAME,
+        compressed: entry.compressed !== false,
+        expectedBytes: entry.entries * 2,
+        ...(meta.checksum !== 0 ? { expectedFnv1a: { value: meta.checksum, elementSize: 2 } } : {})
+    });
+    const values = new Uint16Array(entry.entries);
     const view = new DataView(buffer);
     for (let i = 0; i < values.length; i++) {
         values[i] = view.getUint16(i * 2, true);
     }
     return values;
 }
-async function fetchInt8Table(baseUrl, entry, expectedEntries) {
-    const buffer = await fetchTableBuffer(baseUrl, TABLES_DIR, entry.file, { compressed: entry.compressed !== false });
-    if (buffer.byteLength !== expectedEntries) {
-        throw new Error(`Invalid byte size for ${entry.file}`);
-    }
+async function fetchInt8Table(baseUrl, entry, meta) {
+    const buffer = await fetchTableBuffer(baseUrl, TABLES_DIR, entry.file, {
+        cacheName: CACHE_NAME,
+        compressed: entry.compressed !== false,
+        expectedBytes: entry.entries,
+        // Square-1's int8 tables hash SIGNED values in node (Int8Array).
+        ...(meta.checksum !== 0 ? { expectedFnv1a: { value: meta.checksum, elementSize: 1, signed: true } } : {})
+    });
     return new Int8Array(buffer);
 }

package/dist-cjs/core/api.js

@@ -80,8 +80,16 @@ async function initializeScrambler(baseUrl, eventId) {
         await loadBrowserTables(baseUrl);
     }
     else if (eventId === "444") {
-        const { loadCube4ReductionTablesBrowser } = await Promise.resolve().then(() => __importStar(require("../puzzles/cube4/reduction/browser-loader.js")));
-        await loadCube4ReductionTablesBrowser(baseUrl);
+        // Reduction ends with a 3x3 solve in the same worker. Initializing 444
+        // must also load those required tables, including the caller's base URL.
+        const [cube4, cube3] = await Promise.all([
+            Promise.resolve().then(() => __importStar(require("../puzzles/cube4/reduction/browser-loader.js"))),
+            Promise.resolve().then(() => __importStar(require("../puzzles/cube3/solver/browser-loader.js")))
+        ]);
+        await Promise.all([
+            cube4.loadCube4ReductionTablesBrowser(baseUrl),
+            cube3.loadBrowserTables(baseUrl)
+        ]);
     }
     else if (!eventId) {
         await Promise.all([

package/dist-cjs/puzzles/cube2/solver/browser-loader.js

@@ -6,23 +6,42 @@ exports.loadBrowserTables = loadBrowserTables;
 const table_metadata_js_1 = require("./table-metadata.js");
 const compressed_fetch_js_1 = require("../../shared/compressed-fetch.js");
 const TABLES_DIR = "puzzles/cube2/solver/generated";
+const CACHE_NAME = "cubingcenter-scrambler-tables-v1";
 let cachedBrowserTables;
+let cachedBrowserTablesPromise;
 function getCachedBrowserTables() {
     return cachedBrowserTables;
 }
 function clearCachedBrowserTables() {
     cachedBrowserTables = undefined;
+    cachedBrowserTablesPromise = undefined;
 }
 async function loadBrowserTables(baseUrl) {
     if (cachedBrowserTables) {
         return cachedBrowserTables;
     }
+    if (cachedBrowserTablesPromise) {
+        // One shared in-flight promise: concurrent calls trigger exactly one
+        // fetch pass (dedup).
+        return cachedBrowserTablesPromise;
+    }
+    const promise = fetchTables(baseUrl);
+    cachedBrowserTablesPromise = promise;
+    promise.then(() => { }, () => {
+        // A failed load must not poison the dedup slot: purge the rejected
+        // promise so a later call retries from scratch.
+        if (cachedBrowserTablesPromise === promise)
+            cachedBrowserTablesPromise = undefined;
+    });
+    return promise;
+}
+async function fetchTables(baseUrl) {
     const resolved = resolveBaseUrl(baseUrl);
     const manifest = await fetchManifest(resolved);
     const [permTable, orientTable, dist] = await Promise.all([
-        fetchUint16Table(resolved, manifest.files.permutationTable, table_metadata_js_1.CUBE2_SOLVER_TABLE_METADATA.permutationTable.entries),
-        fetchUint16Table(resolved, manifest.files.orientationTable, table_metadata_js_1.CUBE2_SOLVER_TABLE_METADATA.orientationTable.entries),
-        fetchUint8Table(resolved, manifest.files.policy, table_metadata_js_1.CUBE2_SOLVER_TABLE_METADATA.policy.entries)
+        fetchUint16Table(resolved, manifest.files.permutationTable, table_metadata_js_1.CUBE2_SOLVER_TABLE_METADATA.permutationTable),
+        fetchUint16Table(resolved, manifest.files.orientationTable, table_metadata_js_1.CUBE2_SOLVER_TABLE_METADATA.orientationTable),
+        fetchUint8Table(resolved, manifest.files.policy, table_metadata_js_1.CUBE2_SOLVER_TABLE_METADATA.policy)
     ]);
     cachedBrowserTables = {
         permutationTable: permTable,
@@ -56,22 +75,31 @@ async function fetchManifest(baseUrl) {
     }
     return manifest;
 }
-async function fetchUint16Table(baseUrl, entry, expectedEntries) {
-    const buffer = await (0, compressed_fetch_js_1.fetchTableBuffer)(baseUrl, TABLES_DIR, entry.file, { compressed: entry.compressed !== false });
-    if (buffer.byteLength !== expectedEntries * 2) {
-        throw new Error(`Invalid byte size for ${entry.file}`);
-    }
-    const values = new Uint16Array(expectedEntries);
+/**
+ * Fetch + verify with the SAME checks as node-loader.ts: byte length from
+ * the manifest entries, FNV-1a checksum against the table-metadata
+ * constants (the values node asserts against).
+ */
+async function fetchUint16Table(baseUrl, entry, meta) {
+    const buffer = await (0, compressed_fetch_js_1.fetchTableBuffer)(baseUrl, TABLES_DIR, entry.file, {
+        cacheName: CACHE_NAME,
+        compressed: entry.compressed !== false,
+        expectedBytes: entry.entries * 2,
+        expectedFnv1a: { value: meta.checksum, elementSize: 2 }
+    });
+    const values = new Uint16Array(entry.entries);
     const view = new DataView(buffer);
     for (let i = 0; i < values.length; i++) {
         values[i] = view.getUint16(i * 2, true);
     }
     return values;
 }
-async function fetchUint8Table(baseUrl, entry, expectedEntries) {
-    const buffer = await (0, compressed_fetch_js_1.fetchTableBuffer)(baseUrl, TABLES_DIR, entry.file, { compressed: entry.compressed !== false });
-    if (buffer.byteLength !== expectedEntries) {
-        throw new Error(`Invalid byte size for ${entry.file}`);
-    }
+async function fetchUint8Table(baseUrl, entry, meta) {
+    const buffer = await (0, compressed_fetch_js_1.fetchTableBuffer)(baseUrl, TABLES_DIR, entry.file, {
+        cacheName: CACHE_NAME,
+        compressed: entry.compressed !== false,
+        expectedBytes: entry.entries,
+        expectedFnv1a: { value: meta.checksum, elementSize: 1 }
+    });
     return new Uint8Array(buffer);
 }

package/dist-cjs/puzzles/cube2/solver/generated-assets.js

@@ -35,7 +35,13 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.loadGeneratedCube2SolverTables = loadGeneratedCube2SolverTables;
 const browser_loader_js_1 = require("./browser-loader.js");
-let cachedTables;
+const load_once_js_1 = require("../../shared/load-once.js");
+// One shared in-flight promise for the node fs load (same pattern as
+// cube3/solver/generated-assets.ts): the previous `cached ??= await …` raced —
+// concurrent callers interleaving on the await both ran `loadNodeTables()`
+// (two filesystem reads, last assignment wins). On rejection the slot is
+// purged so the next call can retry.
+const nodeTablesSlot = { promise: undefined };
 function isBrowser() {
     return typeof self !== "undefined";
 }
@@ -49,8 +55,7 @@ async function loadGeneratedCube2SolverTables() {
             "In browser environments, call `initializeScrambler(baseUrl)` " +
             "before generating scrambles.");
     }
-    cachedTables ??= await loadNodeTables();
-    return cachedTables;
+    return (0, load_once_js_1.loadOnce)(nodeTablesSlot, loadNodeTables);
 }
 async function loadNodeTables() {
     const loader = await Promise.resolve().then(() => __importStar(require(

package/dist-cjs/puzzles/cube3/solver/browser-loader.js

@@ -7,6 +7,7 @@ const compressed_fetch_js_1 = require("../../shared/compressed-fetch.js");
 const TABLES_DIR = "puzzles/cube3/solver/generated";
 const CACHE_NAME = "cubingcenter-scrambler-tables-v1";
 let browserTables;
+let browserTablesPromise;
 function resolveBaseUrl(provided) {
     if (provided) {
         return provided.replace(/\/$/, "");
@@ -25,11 +26,28 @@ function getCachedBrowserTables() {
 }
 function clearCachedBrowserTables() {
     browserTables = undefined;
+    browserTablesPromise = undefined;
 }
 async function loadBrowserTables(baseUrl) {
     if (browserTables) {
         return browserTables;
     }
+    if (browserTablesPromise) {
+        // One shared in-flight promise: concurrent calls trigger exactly one
+        // fetch pass (dedup).
+        return browserTablesPromise;
+    }
+    const promise = fetchTables(baseUrl);
+    browserTablesPromise = promise;
+    promise.then(() => { }, () => {
+        // A failed load must not poison the dedup slot: purge the rejected
+        // promise so a later call retries from scratch.
+        if (browserTablesPromise === promise)
+            browserTablesPromise = undefined;
+    });
+    return promise;
+}
+async function fetchTables(baseUrl) {
     const resolvedBase = resolveBaseUrl(baseUrl);
     const manifest = await fetchManifest(resolvedBase);
     browserTables = {
@@ -63,19 +81,15 @@ async function fetchJointTables(baseUrl, entries) {
         return undefined;
     }
     const fetchJoint = async (entry) => {
+        // Verified by fetchTableBuffer with the SAME checks as node-loader.ts:
+        // nibble-packed byte length + FNV-1a over the packed bytes.
         const buffer = await (0, compressed_fetch_js_1.fetchTableBuffer)(baseUrl, TABLES_DIR, entry.file, {
             cacheName: CACHE_NAME,
-            compressed: entry.compressed !== false
+            compressed: entry.compressed !== false,
+            expectedBytes: Math.ceil((entry.rangeA * entry.rangeB) / 2),
+            expectedFnv1a: { value: entry.checksum, elementSize: 1 }
         });
-        const expectedBytes = Math.ceil((entry.rangeA * entry.rangeB) / 2);
-        if (buffer.byteLength !== expectedBytes) {
-            throw new Error(`Invalid byte size for ${entry.file}.`);
-        }
-        const values = new Uint8Array(buffer);
-        if (checksum(values) !== entry.checksum) {
-            throw new Error(`Checksum mismatch for ${entry.file}.`);
-        }
-        return values;
+        return new Uint8Array(buffer);
     };
     return {
         jointUdCo: await fetchJoint(entries.udCo),
@@ -95,11 +109,15 @@ async function fetchManifest(baseUrl) {
     return manifest;
 }
 async function fetchMoveTable(baseUrl, entry) {
-    const buffer = await (0, compressed_fetch_js_1.fetchTableBuffer)(baseUrl, TABLES_DIR, entry.file, { cacheName: CACHE_NAME, compressed: entry.compressed !== false });
-    const expectedBytes = entry.range * entry.moves.length * 4;
-    if (buffer.byteLength !== expectedBytes) {
-        throw new Error(`Invalid byte size for ${entry.coordinate} move table.`);
-    }
+    // Verified by fetchTableBuffer with the SAME checks as node-loader.ts:
+    // int32 wire length + FNV-1a over the decoded coordinate values (element
+    // size 4 reproduces node's hash over the uint16 values — same numbers).
+    const buffer = await (0, compressed_fetch_js_1.fetchTableBuffer)(baseUrl, TABLES_DIR, entry.file, {
+        cacheName: CACHE_NAME,
+        compressed: entry.compressed !== false,
+        expectedBytes: entry.range * entry.moves.length * 4,
+        expectedFnv1a: { value: entry.checksum, elementSize: 4 }
+    });
     const values = new Uint16Array(entry.range * entry.moves.length);
     const view = new DataView(buffer);
     for (let index = 0; index < values.length; index += 1) {
@@ -119,11 +137,15 @@ async function fetchMoveTable(baseUrl, entry) {
     };
 }
 async function fetchPruningTable(baseUrl, entry) {
-    const buffer = await (0, compressed_fetch_js_1.fetchTableBuffer)(baseUrl, TABLES_DIR, entry.file, { cacheName: CACHE_NAME, compressed: entry.compressed !== false });
-    const expectedBytes = Math.ceil(entry.range / 2);
-    if (buffer.byteLength !== expectedBytes) {
-        throw new Error(`Invalid byte size for ${entry.coordinate} pruning table.`);
-    }
+    // Verified by fetchTableBuffer with the SAME checks as node-loader.ts:
+    // nibble-packed byte length + FNV-1a over the packed bytes (this browser
+    // path did NOT compare the pruning checksum before — only the length).
+    const buffer = await (0, compressed_fetch_js_1.fetchTableBuffer)(baseUrl, TABLES_DIR, entry.file, {
+        cacheName: CACHE_NAME,
+        compressed: entry.compressed !== false,
+        expectedBytes: Math.ceil(entry.range / 2),
+        expectedFnv1a: { value: entry.checksum, elementSize: 1 }
+    });
     const values = new Uint8Array(buffer);
     return {
         coordinate: entry.coordinate,

package/dist-cjs/puzzles/cube3/solver/generated-assets.js

@@ -37,10 +37,17 @@ exports.loadGeneratedCube3SolverTables = loadGeneratedCube3SolverTables;
 exports.loadGeneratedCube3Phase1Tables = loadGeneratedCube3Phase1Tables;
 exports.loadGeneratedCube3Phase2Tables = loadGeneratedCube3Phase2Tables;
 const browser_loader_js_1 = require("./browser-loader.js");
-let cachedGeneratedTables;
+const load_once_js_1 = require("../../shared/load-once.js");
 function isBrowser() {
     return typeof self !== "undefined";
 }
+// One shared in-flight promise for the node fs load: mixed concurrent
+// phase-1 + phase-2 loads (separate slots in tables.ts) converge on ONE
+// `readGeneratedCube3SolverTables()` call. The previous `cached ??= await …`
+// raced — two callers interleaving on the await both ran `loadNodeTables()`
+// (two filesystem reads, two table sets, last assignment wins). On
+// rejection the slot is purged so the next call can retry.
+const nodeTablesSlot = { promise: undefined };
 async function loadGeneratedCube3SolverTables() {
     if (isBrowser()) {
         const browserTables = (0, browser_loader_js_1.getCachedBrowserTables)();
@@ -51,8 +58,7 @@ async function loadGeneratedCube3SolverTables() {
             "In browser environments, call `initializeScrambler(baseUrl)` " +
             "before generating scrambles.");
     }
-    cachedGeneratedTables ??= await loadNodeTables();
-    return cachedGeneratedTables;
+    return (0, load_once_js_1.loadOnce)(nodeTablesSlot, loadNodeTables);
 }
 async function loadNodeTables() {
     const loader = await Promise.resolve().then(() => __importStar(require(

package/dist-cjs/puzzles/cube3/solver/phase1.js

@@ -37,7 +37,7 @@ async function solveCube3Phase1(state, options = {}) {
     const maxDepth = options.maxDepth ?? 12;
     const start = encodeCube3Phase1Coordinates(state);
     const deadline = options.timeoutMs === undefined ? undefined : performance.now() + options.timeoutMs;
-    const context = createPhase1SearchContext(tables, jointTables, maxDepth, deadline);
+    const context = createPhase1SearchContext(tables, jointTables, maxDepth, deadline, options.maxNodes);
     if (await isCube3Phase1Solved(start, tables)) {
         return {
             moves: [],
@@ -79,6 +79,9 @@ async function solveCube3Phase1(state, options = {}) {
                 visitedNodes: context.visitedNodes
             };
         }
+        if (context.nodesExceeded) {
+            throw new Cube3Phase1SearchError(`3x3 Phase 1 node budget exceeded (${options.maxNodes} nodes).`, context.visitedNodes);
+        }
         if (context.timedOut) {
             throw new Cube3Phase1SearchError(`3x3 Phase 1 search timed out after ${options.timeoutMs}ms.`, context.visitedNodes);
         }
@@ -109,8 +112,17 @@ const PHASE1_MOVE_FACES = tables_js_1.CUBE3_PHASE1_MOVES.map((move) => {
 });
 function searchPhase1(cornerOrientation, edgeOrientation, udSlice, previousFace, previousPreviousFace, remainingDepth, path, context) {
     context.visitedNodes += 1;
-    if (context.deadline !== undefined && (context.visitedNodes & 1023) === 0 && performance.now() > context.deadline) {
+    if (context.nodeCap !== undefined &&
+        context.visitedNodes > context.nodeCap) {
+        context.nodesExceeded = true;
+    }
+    if (!context.nodesExceeded &&
+        context.deadline !== undefined &&
+        (context.visitedNodes & 1023) === 0 &&
+        performance.now() > context.deadline) {
         context.timedOut = true;
+    }
+    if (context.timedOut || context.nodesExceeded) {
         return false;
     }
     if (remainingDepth === 0) {
@@ -133,7 +145,7 @@ function searchPhase1(cornerOrientation, edgeOrientation, udSlice, previousFace,
             return true;
         }
         path.pop();
-        if (context.timedOut) {
+        if (context.timedOut || context.nodesExceeded) {
             return false;
         }
     }
@@ -150,13 +162,13 @@ async function collectCube3Phase1Solutions(state, depth, options = {}) {
     const jointTables = options.jointTables ?? tables.jointTables;
     const limit = options.limit ?? 32;
     const deadline = options.timeoutMs === undefined ? undefined : performance.now() + options.timeoutMs;
-    const context = createPhase1SearchContext(tables, jointTables, depth, deadline);
+    const context = createPhase1SearchContext(tables, jointTables, depth, deadline, options.maxNodes);
     const start = encodeCube3Phase1Coordinates(state);
     const solutions = [];
     searchPhase1Collect(start.cornerOrientation, start.edgeOrientation, start.udSlice, -1, -1, depth, [], solutions, limit, context);
     return { solutions, visitedNodes: context.visitedNodes };
 }
-function createPhase1SearchContext(tables, jointTables, maxDepth, deadline) {
+function createPhase1SearchContext(tables, jointTables, maxDepth, deadline, nodeCap) {
     const scratchLevels = maxDepth + 1;
     const scratchSize = scratchLevels * tables_js_1.CUBE3_PHASE1_MOVES.length;
     return {
@@ -164,8 +176,10 @@ function createPhase1SearchContext(tables, jointTables, maxDepth, deadline) {
         jointTables,
         maxDepth,
         deadline,
+        nodeCap,
         visitedNodes: 0,
         timedOut: false,
+        nodesExceeded: false,
         scratchMove: new Int32Array(scratchSize),
         scratchBound: new Int32Array(scratchSize),
         scratchCo: new Int32Array(scratchSize),
@@ -261,8 +275,17 @@ function collectPhase1Children(cornerOrientation, edgeOrientation, udSlice, prev
  */
 function searchPhase1Collect(cornerOrientation, edgeOrientation, udSlice, previousFace, previousPreviousFace, remainingDepth, path, solutions, limit, context) {
     context.visitedNodes += 1;
-    if (context.deadline !== undefined && (context.visitedNodes & 1023) === 0 && performance.now() > context.deadline) {
+    if (context.nodeCap !== undefined &&
+        context.visitedNodes > context.nodeCap) {
+        context.nodesExceeded = true;
+    }
+    if (!context.nodesExceeded &&
+        context.deadline !== undefined &&
+        (context.visitedNodes & 1023) === 0 &&
+        performance.now() > context.deadline) {
         context.timedOut = true;
+    }
+    if (context.timedOut || context.nodesExceeded) {
         return true;
     }
     if (remainingDepth === 0) {

package/dist-cjs/puzzles/cube3/solver/phase2.js

@@ -55,7 +55,7 @@ async function solveCube3Phase2(state, options = {}) {
     const maxDepth = options.maxDepth ?? 18;
     const start = encodeCube3Phase2Coordinates(state);
     const deadline = options.timeoutMs === undefined ? undefined : performance.now() + options.timeoutMs;
-    const context = createPhase2SearchContext(tables, pairTables, maxDepth, deadline);
+    const context = createPhase2SearchContext(tables, pairTables, maxDepth, deadline, options.maxNodes);
     const spRange = tables.moveTables.slicePermutation.range;
     const cpspTable = tables.pruningTables.cornerPermutationSlicePermutation.values;
     const epspTable = tables.pruningTables.udEdgePermutationSlicePermutation.values;
@@ -86,6 +86,9 @@ async function solveCube3Phase2(state, options = {}) {
                 visitedNodes: context.visitedNodes
             };
         }
+        if (context.nodesExceeded) {
+            throw new Cube3Phase2SearchError(`3x3 Phase 2 node budget exceeded (${options.maxNodes} nodes).`, context.visitedNodes);
+        }
         if (context.timedOut) {
             throw new Cube3Phase2SearchError(`3x3 Phase 2 search timed out after ${options.timeoutMs}ms.`, context.visitedNodes);
         }
@@ -126,7 +129,19 @@ async function solveCube3State(state, options = {}) {
         const p2Tables = options.phase2?.tables ?? await (0, tables_js_1.loadCube3Phase2Tables)();
         const scoredPairTables = options.phase2?.pairTables ??
             (options.phase2?.skipPairTables ? undefined : await (0, pair_tables_js_1.loadCube3PairTables)());
-        const deadline = performance.now() + (options.timeoutMs ?? 800);
+        // Work budget for the improvement loop. Preferred: `improveMaxNodes`
+        // (deterministic node counter — the wall deadline stays unarmed so the
+        // outcome cannot depend on CPU load/clock). Legacy: `timeoutMs ?? 800`
+        // wall deadline, kept for existing callers.
+        const nodeMode = options.improveMaxNodes !== undefined;
+        let remainingNodes = options.improveMaxNodes ?? 0;
+        const deadline = nodeMode ? undefined : performance.now() + (options.timeoutMs ?? 800);
+        const budgetExhausted = () => nodeMode ? remainingNodes <= 0 : performance.now() > deadline;
+        const spendNodes = (used) => {
+            if (nodeMode) {
+                remainingNodes = Math.max(0, remainingNodes - used);
+            }
+        };
         const p2SpRange = p2Tables.moveTables.slicePermutation.range;
         const p2cpsp = p2Tables.pruningTables.cornerPermutationSlicePermutation.values;
         const p2uepsp = p2Tables.pruningTables.udEdgePermutationSlicePermutation.values;
@@ -138,18 +153,21 @@ async function solveCube3State(state, options = {}) {
         const minDepth = phase1.depth;
         const scored = [];
         for (let d = minDepth; d <= minDepth + improveDepths && d < bestMoves.length; d++) {
-            if (performance.now() > deadline)
+            if (budgetExhausted())
                 break;
             const { solutions: p1Solutions, visitedNodes } = await (0, phase1_js_1.collectCube3Phase1Solutions)(state, d, {
                 tables: p1Tables,
                 limit: solutionLimit,
-                timeoutMs: Math.max(1, deadline - performance.now())
+                ...(nodeMode
+                    ? { maxNodes: Math.max(1, remainingNodes) }
+                    : { timeoutMs: Math.max(1, deadline - performance.now()) })
             });
             improvementNodes += visitedNodes;
-            if (performance.now() > deadline)
+            spendNodes(visitedNodes);
+            if (budgetExhausted())
                 break;
             for (const p1Moves of p1Solutions) {
-                if (performance.now() > deadline)
+                if (budgetExhausted())
                     break;
                 if (p1Moves.length >= bestMoves.length)
                     continue;
@@ -186,7 +204,7 @@ async function solveCube3State(state, options = {}) {
         // Sort ALL candidates globally across depths by admissible total lower bound
         scored.sort((left, right) => left.est - right.est);
         for (const cand of scored) {
-            if (performance.now() > deadline)
+            if (budgetExhausted())
                 break;
             // Prune: since candidates are sorted by est, no subsequent candidate can beat bestMoves.length
             if (cand.est >= bestMoves.length)
@@ -195,19 +213,31 @@ async function solveCube3State(state, options = {}) {
             if (maxP2 <= 0)
                 continue;
             try {
-                const remainingBudget = Math.max(1, deadline - performance.now());
-                const attemptTimeout = options.improvePhase2TimeoutMs ??
-                    options.phase2?.timeoutMs ?? 25;
+                // Strip any legacy wall `timeoutMs` from the spread: in node mode
+                // the wall deadline must not be armed at all (pure function of
+                // budgets); in wall mode the per-candidate cap below re-adds it.
+                const phase2Source = options.phase2 ?? {};
+                const { timeoutMs: legacyPhase2Wall, ...phase2CandidateBase } = phase2Source;
+                // Per-candidate budget: node cap (deterministic) when the loop runs
+                // on `improveMaxNodes`, else the legacy wall cap.
+                const candidateCap = nodeMode
+                    ? {
+                        maxNodes: Math.max(1, Math.min(options.improvePhase2MaxNodes ?? phase2CandidateBase.maxNodes ?? remainingNodes, remainingNodes))
+                    }
+                    : {
+                        timeoutMs: Math.min(options.improvePhase2TimeoutMs ?? legacyPhase2Wall ?? 25, Math.max(1, deadline - performance.now()))
+                    };
                 const candP2 = await solveCube3Phase2(cand.state, {
-                    ...options.phase2,
+                    ...phase2CandidateBase,
                     pairTables: scoredPairTables,
                     tables: p2Tables,
                     maxDepth: maxP2,
                     previousFace: cand.pFace,
                     previousPreviousFace: cand.ppFace,
-                    timeoutMs: Math.min(attemptTimeout, remainingBudget)
+                    ...candidateCap
                 });
                 improvementNodes += candP2.visitedNodes;
+                spendNodes(candP2.visitedNodes);
                 const candTotal = cand.moves.length + candP2.moves.length;
                 if (candTotal < bestMoves.length) {
                     bestMoves = [...cand.moves, ...candP2.moves];
@@ -301,7 +331,7 @@ const PHASE2_MOVE_FACES = tables_js_1.CUBE3_PHASE2_MOVES.map((move) => {
     const char = move[0];
     return char === "U" ? 0 : char === "D" ? 1 : char === "R" ? 2 : char === "L" ? 3 : char === "F" ? 4 : 5;
 });
-function createPhase2SearchContext(tables, pairTables, maxDepth, deadline) {
+function createPhase2SearchContext(tables, pairTables, maxDepth, deadline, nodeCap = undefined) {
     const scratchLevels = maxDepth + 1;
     const scratchSize = scratchLevels * tables_js_1.CUBE3_PHASE2_MOVES.length;
     return {
@@ -309,8 +339,10 @@ function createPhase2SearchContext(tables, pairTables, maxDepth, deadline) {
         pairTables,
         maxDepth,
         deadline,
+        nodeCap,
         visitedNodes: 0,
         timedOut: false,
+        nodesExceeded: false,
         scratchMove: new Int32Array(scratchSize),
         scratchBound: new Int32Array(scratchSize),
         scratchCp: new Int32Array(scratchSize),
@@ -320,8 +352,17 @@ function createPhase2SearchContext(tables, pairTables, maxDepth, deadline) {
 }
 function searchPhase2(cornerPermutation, udEdgePermutation, slicePermutation, previousFace, previousPreviousFace, remainingDepth, path, context) {
     context.visitedNodes += 1;
-    if (context.deadline !== undefined && (context.visitedNodes & 1023) === 0 && performance.now() > context.deadline) {
+    if (context.nodeCap !== undefined &&
+        context.visitedNodes > context.nodeCap) {
+        context.nodesExceeded = true;
+    }
+    if (!context.nodesExceeded &&
+        context.deadline !== undefined &&
+        (context.visitedNodes & 1023) === 0 &&
+        performance.now() > context.deadline) {
         context.timedOut = true;
+    }
+    if (context.timedOut || context.nodesExceeded) {
         return false;
     }
     if (remainingDepth === 0) {
@@ -412,7 +453,7 @@ function searchPhase2(cornerPermutation, udEdgePermutation, slicePermutation, pr
             return true;
         }
         path.pop();
-        if (context.timedOut) {
+        if (context.timedOut || context.nodesExceeded) {
             return false;
         }
     }