@johnmorrisdotca/houseki 0.4.0 → 0.4.2

package/dist/gem-swap/engine.d.ts

@@ -1,25 +1,140 @@
 import type { Action, CreateOptions, GameState, GameStatus, Gem, Settings, Transition } from './types.js';
-/** Typed error for invalid settings or a board that cannot be generated safely. */
+/** Typed error for invalid settings or a board that cannot be generated safely.
+ *
+ * @param code - The native stable error code used by callers to distinguish setup or replay failures.
+ * @param message - The human-readable diagnostic accompanying the native code.
+ * @example
+ * ```ts
+ * import { GemSwapOptionsError } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const error=new GemSwapOptionsError("docs-example","Invalid example setup");
+ * console.log(error.name,error.code,error.message);
+ * ```
+ */
 export declare class GemSwapOptionsError extends RangeError {
     readonly code: string;
     constructor(code: string, message: string);
 }
 /** @internal Test seam for checking the built-in standard-board fallback witness. */
 export declare function fallbackBoardForTest(settings: Settings): readonly (Gem | null)[];
-/** Creates a deterministic stable board with at least one legal normal swap. */
+/** Creates a deterministic stable board with at least one legal normal swap.
+ *
+ * @param options - Validated native creation, authored challenge, or environment options described by this signature.
+ * @returns Creates a deterministic stable board with at least one legal normal swap.
+ * @example
+ * ```ts
+ * import { createGame } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * console.log(createGame({seed:"docs"}).phase);
+ * ```
+ */
 export declare function createGame(options?: CreateOptions): GameState;
-/** Applies one recorded player action. Rejected actions preserve state identity and are not recorded. */
+/** Applies one recorded player action. Rejected actions preserve state identity and are not recorded.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @param action - One native action for this entry point; inspect accepted and reason on the result.
+ * @returns Applies one recorded player action. Rejected actions preserve state identity and are not recorded.
+ * @example
+ * ```ts
+ * import { applyAction, createGame } from "@johnmorrisdotca/houseki/gem-swap";
+ * import type { Action } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const state=createGame({seed:"docs"});
+ * const action: Action={kind:"hint"};
+ * console.log(applyAction(state,action).accepted);
+ * ```
+ */
 export declare function applyAction(state: GameState, action: Action): Transition;
-/** Advances deterministic resolution ticks; wall-clock time is supplied separately by the host. */
+/** Advances deterministic resolution ticks; wall-clock time is supplied separately by the host.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @param ticks - The nonnegative number of fixed 60 Hz logical ticks to advance.
+ * @returns Advances deterministic resolution ticks; wall-clock time is supplied separately by the host.
+ * @example
+ * ```ts
+ * import { advanceTicks, createGame } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(advanceTicks(state,1).state.phase);
+ * ```
+ */
 export declare function advanceTicks(state: GameState, ticks: number): Transition;
-/** Adds explicit host-measured elapsed time. Arcade runs end at 180 seconds; no clock is read here. */
+/** Adds explicit host-measured elapsed time. Arcade runs end at 180 seconds; no clock is read here.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @param milliseconds - The nonnegative elapsed milliseconds for the native timer.
+ * @returns Adds explicit host-measured elapsed time. Arcade runs end at 180 seconds; no clock is read here.
+ * @example
+ * ```ts
+ * import { advanceTime, createGame } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(advanceTime(state,16).state.phase);
+ * ```
+ */
 export declare function advanceTime(state: GameState, milliseconds: number): Transition;
-/** Returns a deterministic legal swap hint and permanently marks the run assisted. */
+/** Returns a deterministic legal swap hint and permanently marks the run assisted.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Returns a deterministic legal swap hint and permanently marks the run assisted.
+ * @example
+ * ```ts
+ * import { createGame, hintGame } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(hintGame(state).accepted);
+ * ```
+ */
 export declare function hintGame(state: GameState): Transition;
-/** Shuffles existing gem records in Relaxed play, preserving their colour and special counts. */
+/** Shuffles existing gem records in Relaxed play, preserving their colour and special counts.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Shuffles existing gem records in Relaxed play, preserving their colour and special counts.
+ * @example
+ * ```ts
+ * import { createGame, reshuffleGame } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(reshuffleGame(state).accepted);
+ * ```
+ */
 export declare function reshuffleGame(state: GameState): Transition;
-/** Restores the last committed swap in Relaxed or Challenge play and marks assistance. */
+/** Restores the last committed swap in Relaxed or Challenge play and marks assistance.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Restores the last committed swap in Relaxed or Challenge play and marks assistance.
+ * @example
+ * ```ts
+ * import { createGame, undoGame } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(undoGame(state).accepted);
+ * ```
+ */
 export declare function undoGame(state: GameState): Transition;
-/** Lists all legal swaps that would be accepted from the current stable state. */
+/** Lists all legal swaps that would be accepted from the current stable state.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Lists all legal swaps that would be accepted from the current stable state.
+ * @example
+ * ```ts
+ * import { createGame, legalActions } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(legalActions(state).length);
+ * ```
+ */
 export declare function legalActions(state: GameState): readonly Action[];
+/** Derive the native phase, score, legal-move count, tools and goal/timer progress for host labels.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Derive the native phase, score, legal-move count, tools and goal/timer progress for host labels.
+ * @example
+ * ```ts
+ * import { createGame, statusOf } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(statusOf(state).phase);
+ * ```
+ */
 export declare function statusOf(state: GameState): GameStatus;

package/dist/gem-swap/engine.js

@@ -4,7 +4,18 @@ import { isValidSpecialSwap, materializeSpecials, planWave } from './specials.js
 import { previewTool } from './tools.js';
 import { consumePortal, contactCells, placementCells } from './black-hole.js';
 import { hintTransition, reshuffleTransition, undoTransition } from './practice.js';
-/** Typed error for invalid settings or a board that cannot be generated safely. */
+/** Typed error for invalid settings or a board that cannot be generated safely.
+ *
+ * @param code - The native stable error code used by callers to distinguish setup or replay failures.
+ * @param message - The human-readable diagnostic accompanying the native code.
+ * @example
+ * ```ts
+ * import { GemSwapOptionsError } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const error=new GemSwapOptionsError("docs-example","Invalid example setup");
+ * console.log(error.name,error.code,error.message);
+ * ```
+ */
 export class GemSwapOptionsError extends RangeError {
     code;
     constructor(code, message) { super(message); this.name = 'GemSwapOptionsError'; this.code = code; }
@@ -185,7 +196,17 @@ export function fallbackBoardForTest(settings) {
     // Swapping (3,4) blue with (3,3) red completes the red row at y=4, x=2..4.
     return Object.freeze(board);
 }
-/** Creates a deterministic stable board with at least one legal normal swap. */
+/** Creates a deterministic stable board with at least one legal normal swap.
+ *
+ * @param options - Validated native creation, authored challenge, or environment options described by this signature.
+ * @returns Creates a deterministic stable board with at least one legal normal swap.
+ * @example
+ * ```ts
+ * import { createGame } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * console.log(createGame({seed:"docs"}).phase);
+ * ```
+ */
 export function createGame(options = {}) {
     const config = optionsFor(options);
     const { settings } = config;
@@ -284,7 +305,21 @@ function appendHistory(state, operation) {
         return Object.freeze({ ...state, history: Object.freeze([...state.history.slice(0, -1), Object.freeze({ kind: 'time', milliseconds: previous.milliseconds + operation.milliseconds })]) });
     return Object.freeze({ ...state, history: Object.freeze([...state.history, Object.freeze(operation)]) });
 }
-/** Applies one recorded player action. Rejected actions preserve state identity and are not recorded. */
+/** Applies one recorded player action. Rejected actions preserve state identity and are not recorded.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @param action - One native action for this entry point; inspect accepted and reason on the result.
+ * @returns Applies one recorded player action. Rejected actions preserve state identity and are not recorded.
+ * @example
+ * ```ts
+ * import { applyAction, createGame } from "@johnmorrisdotca/houseki/gem-swap";
+ * import type { Action } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const state=createGame({seed:"docs"});
+ * const action: Action={kind:"hint"};
+ * console.log(applyAction(state,action).accepted);
+ * ```
+ */
 export function applyAction(state, action) {
     const explicitPracticeReshuffle = action?.kind === 'reshuffle' && state.mode === 'relaxed' && state.outcome === 'finished';
     if ((state.outcome && !explicitPracticeReshuffle) || (state.mode === 'arcade' && state.elapsedMs >= 180_000))
@@ -580,7 +615,19 @@ function advanceTicksBase(state, ticks) {
     }
     return { state: current, events: Object.freeze(events), accepted: true };
 }
-/** Advances deterministic resolution ticks; wall-clock time is supplied separately by the host. */
+/** Advances deterministic resolution ticks; wall-clock time is supplied separately by the host.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @param ticks - The nonnegative number of fixed 60 Hz logical ticks to advance.
+ * @returns Advances deterministic resolution ticks; wall-clock time is supplied separately by the host.
+ * @example
+ * ```ts
+ * import { advanceTicks, createGame } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(advanceTicks(state,1).state.phase);
+ * ```
+ */
 export function advanceTicks(state, ticks) {
     if (!Number.isInteger(ticks) || ticks < 0 || ticks > 3600)
         throw new RangeError('ticks must be an integer from 0 to 3600');
@@ -597,7 +644,19 @@ export function advanceTicks(state, ticks) {
         current = appendHistory(current, { kind: 'ticks', count: consumed });
     return { state: current, events: Object.freeze(events), accepted: true };
 }
-/** Adds explicit host-measured elapsed time. Arcade runs end at 180 seconds; no clock is read here. */
+/** Adds explicit host-measured elapsed time. Arcade runs end at 180 seconds; no clock is read here.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @param milliseconds - The nonnegative elapsed milliseconds for the native timer.
+ * @returns Adds explicit host-measured elapsed time. Arcade runs end at 180 seconds; no clock is read here.
+ * @example
+ * ```ts
+ * import { advanceTime, createGame } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(advanceTime(state,16).state.phase);
+ * ```
+ */
 export function advanceTime(state, milliseconds) {
     if (!Number.isInteger(milliseconds) || milliseconds < 0 || milliseconds > 180_000)
         throw new RangeError('milliseconds must be an integer from 0 to 180000');
@@ -629,13 +688,57 @@ function replayOperations(initial, operations) {
     }
     return state;
 }
-/** Returns a deterministic legal swap hint and permanently marks the run assisted. */
+/** Returns a deterministic legal swap hint and permanently marks the run assisted.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Returns a deterministic legal swap hint and permanently marks the run assisted.
+ * @example
+ * ```ts
+ * import { createGame, hintGame } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(hintGame(state).accepted);
+ * ```
+ */
 export function hintGame(state) { return applyAction(state, { kind: 'hint' }); }
-/** Shuffles existing gem records in Relaxed play, preserving their colour and special counts. */
+/** Shuffles existing gem records in Relaxed play, preserving their colour and special counts.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Shuffles existing gem records in Relaxed play, preserving their colour and special counts.
+ * @example
+ * ```ts
+ * import { createGame, reshuffleGame } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(reshuffleGame(state).accepted);
+ * ```
+ */
 export function reshuffleGame(state) { return applyAction(state, { kind: 'reshuffle' }); }
-/** Restores the last committed swap in Relaxed or Challenge play and marks assistance. */
+/** Restores the last committed swap in Relaxed or Challenge play and marks assistance.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Restores the last committed swap in Relaxed or Challenge play and marks assistance.
+ * @example
+ * ```ts
+ * import { createGame, undoGame } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(undoGame(state).accepted);
+ * ```
+ */
 export function undoGame(state) { return applyAction(state, { kind: 'undo' }); }
-/** Lists all legal swaps that would be accepted from the current stable state. */
+/** Lists all legal swaps that would be accepted from the current stable state.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Lists all legal swaps that would be accepted from the current stable state.
+ * @example
+ * ```ts
+ * import { createGame, legalActions } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(legalActions(state).length);
+ * ```
+ */
 export function legalActions(state) {
     if (state.phase === 'finished')
         return state.mode === 'relaxed' && state.outcome === 'finished' ? Object.freeze([{ kind: 'reshuffle' }]) : Object.freeze([]);
@@ -681,6 +784,18 @@ export function legalActions(state) {
 /** Returns the current score, move count and accurately enumerated legal move count. */
 function availableToolCount(state) { return TOOL_ORDER.reduce((count, tool) => count + state.inventory[tool], state.blackHoleCharges); }
 function hasUsableTool(state) { return TOOL_ORDER.some(tool => state.inventory[tool] > 0) || (state.settings.advancedTools && state.blackHoleCharges > 0 && state.blackHole === null); }
+/** Derive the native phase, score, legal-move count, tools and goal/timer progress for host labels.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Derive the native phase, score, legal-move count, tools and goal/timer progress for host labels.
+ * @example
+ * ```ts
+ * import { createGame, statusOf } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(statusOf(state).phase);
+ * ```
+ */
 export function statusOf(state) {
     const goals = state.challenge?.goals ?? Object.freeze([]);
     const goalProgress = goals.map(goal => ({ kind: goal.kind, ...(goal.kind === 'collect' ? { colour: goal.colour } : {}), current: goalValue(state, goal), target: goalTarget(state, goal), complete: goalValue(state, goal) >= goalTarget(state, goal) }));

package/dist/gem-swap/persistence.d.ts

@@ -1,15 +1,71 @@
 import type { CreateOptions, GameState, ReplayOperation } from './types.js';
+/** A typed rejection of a malformed, unsupported or inconsistent native replay.
+ *
+ * @param code - The native stable error code used by callers to distinguish setup or replay failures.
+ * @param message - The human-readable diagnostic accompanying the native code.
+ * @example
+ * ```ts
+ * import { ReplayError } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const error=new ReplayError("docs-example","Invalid example setup");
+ * console.log(error.name,error.code,error.message);
+ * ```
+ */
 export declare class ReplayError extends TypeError {
     readonly code: string;
     constructor(code: string, message: string);
 }
-/** Encodes the initial rules plus accepted actions and logical inputs in canonical JSON. */
+/** Encodes the initial rules plus accepted actions and logical inputs in canonical JSON.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Encodes the initial rules plus accepted actions and logical inputs in canonical JSON.
+ * @example
+ * ```ts
+ * import { createGame, encodeGame } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(encodeGame(state).length);
+ * ```
+ */
 export declare function encodeGame(state: GameState): string;
-/** Validates and reconstructs a state by replay; serialized board snapshots are never trusted. */
+/** Validates and reconstructs a state by replay; serialized board snapshots are never trusted.
+ *
+ * @param serialized - A saved JSON recording from this entry’s encodeGame; malformed or inconsistent saves throw.
+ * @returns Validates and reconstructs a state by replay; serialized board snapshots are never trusted.
+ * @example
+ * ```ts
+ * import { createGame, decodeGame, encodeGame } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(decodeGame(encodeGame(state)).phase);
+ * ```
+ */
 export declare function decodeGame(serialized: string): GameState;
-/** Starts the exact initial ruleset and seed again, discarding all run progress. */
+/** Starts the exact initial ruleset and seed again, discarding all run progress.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Starts the exact initial ruleset and seed again, discarding all run progress.
+ * @example
+ * ```ts
+ * import { createGame, restartGame } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(restartGame(state).phase);
+ * ```
+ */
 export declare function restartGame(state: GameState): GameState;
-/** Checks a complete authored witness through the public deterministic rules API. */
+/** Checks a complete authored witness through the public deterministic rules API.
+ *
+ * @param options - Validated native creation, authored challenge, or environment options described by this signature.
+ * @param witness - The ordered native replay operations proposed as a winning challenge proof.
+ * @returns Checks a complete authored witness through the public deterministic rules API.
+ * @example
+ * ```ts
+ * import { GEM_SWAP_CAMPAIGN, validateChallengeWitness } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * console.log(validateChallengeWitness(GEM_SWAP_CAMPAIGN[0].options,GEM_SWAP_CAMPAIGN[0].witness).valid);
+ * ```
+ */
 export declare function validateChallengeWitness(options: CreateOptions, witness: readonly ReplayOperation[]): {
     readonly valid: boolean;
     readonly state?: GameState;

package/dist/gem-swap/persistence.js

@@ -4,16 +4,30 @@ const MAX_BYTES = 262_144;
 const MAX_OPERATIONS = 5_000;
 const MAX_TICKS = 100_000;
 const byteLength = (value) => new TextEncoder().encode(value).byteLength;
+/** A typed rejection of a malformed, unsupported or inconsistent native replay.
+ *
+ * @param code - The native stable error code used by callers to distinguish setup or replay failures.
+ * @param message - The human-readable diagnostic accompanying the native code.
+ * @example
+ * ```ts
+ * import { ReplayError } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const error=new ReplayError("docs-example","Invalid example setup");
+ * console.log(error.name,error.code,error.message);
+ * ```
+ */
 export class ReplayError extends TypeError {
     code;
     constructor(code, message) { super(message); this.name = 'ReplayError'; this.code = code; }
 }
-function canonical(value) {
+function canonical(value, depth = 0) {
+    if (depth > 50)
+        throw new ReplayError('save-too-deep', 'Replay is nested too deeply');
     if (Array.isArray(value))
-        return `[${value.map(canonical).join(',')}]`;
+        return `[${value.map(item => canonical(item, depth + 1)).join(',')}]`;
     if (value && typeof value === 'object') {
         const object = value;
-        return `{${Object.keys(object).sort().map(key => `${JSON.stringify(key)}:${canonical(object[key])}`).join(',')}}`;
+        return `{${Object.keys(object).sort().map(key => `${JSON.stringify(key)}:${canonical(object[key], depth + 1)}`).join(',')}}`;
     }
     return JSON.stringify(value);
 }
@@ -55,7 +69,18 @@ function execute(initial, operations) {
     }
     return state;
 }
-/** Encodes the initial rules plus accepted actions and logical inputs in canonical JSON. */
+/** Encodes the initial rules plus accepted actions and logical inputs in canonical JSON.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Encodes the initial rules plus accepted actions and logical inputs in canonical JSON.
+ * @example
+ * ```ts
+ * import { createGame, encodeGame } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(encodeGame(state).length);
+ * ```
+ */
 export function encodeGame(state) {
     if (!state || state.game !== 'gem-swap' || state.history.length > MAX_OPERATIONS)
         throw new ReplayError('invalid-state', 'State is invalid or exceeds the operation limit');
@@ -68,7 +93,18 @@ export function encodeGame(state) {
         throw new ReplayError('save-too-large', 'Replay exceeds the 256 KiB size limit');
     return result;
 }
-/** Validates and reconstructs a state by replay; serialized board snapshots are never trusted. */
+/** Validates and reconstructs a state by replay; serialized board snapshots are never trusted.
+ *
+ * @param serialized - A saved JSON recording from this entry’s encodeGame; malformed or inconsistent saves throw.
+ * @returns Validates and reconstructs a state by replay; serialized board snapshots are never trusted.
+ * @example
+ * ```ts
+ * import { createGame, decodeGame, encodeGame } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(decodeGame(encodeGame(state)).phase);
+ * ```
+ */
 export function decodeGame(serialized) {
     if (typeof serialized !== 'string' || byteLength(serialized) > MAX_BYTES)
         throw new ReplayError('save-too-large', 'Replay must be a string no larger than 256 KiB');
@@ -89,9 +125,31 @@ export function decodeGame(serialized) {
     const operations = value.operations.map(validateOperation);
     return execute(value.initial, operations);
 }
-/** Starts the exact initial ruleset and seed again, discarding all run progress. */
+/** Starts the exact initial ruleset and seed again, discarding all run progress.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Starts the exact initial ruleset and seed again, discarding all run progress.
+ * @example
+ * ```ts
+ * import { createGame, restartGame } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(restartGame(state).phase);
+ * ```
+ */
 export function restartGame(state) { return createGame(state.initialOptions); }
-/** Checks a complete authored witness through the public deterministic rules API. */
+/** Checks a complete authored witness through the public deterministic rules API.
+ *
+ * @param options - Validated native creation, authored challenge, or environment options described by this signature.
+ * @param witness - The ordered native replay operations proposed as a winning challenge proof.
+ * @returns Checks a complete authored witness through the public deterministic rules API.
+ * @example
+ * ```ts
+ * import { GEM_SWAP_CAMPAIGN, validateChallengeWitness } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * console.log(validateChallengeWitness(GEM_SWAP_CAMPAIGN[0].options,GEM_SWAP_CAMPAIGN[0].witness).valid);
+ * ```
+ */
 export function validateChallengeWitness(options, witness) {
     try {
         if (options.mode !== 'challenge' || !Array.isArray(witness) || witness.length > MAX_OPERATIONS)

package/dist/gem-swap/practice.js

@@ -35,7 +35,7 @@ export function reshuffleTransition(state) {
     const finishedRelaxed = state.mode === 'relaxed' && state.phase === 'finished' && state.outcome === 'finished' && !findMatches(state.board, state.settings).length;
     if (state.mode !== 'relaxed' || (!onReady(state) && !finishedRelaxed) || state.selectedTool)
         return rejected(state, 'reshuffle-unavailable');
-    const gems = state.board.filter((item) => item !== null);
+    const gems = state.board.filter((item, index) => item !== null && index !== state.blackHole?.cell);
     let randomState = state.randomState;
     for (let attempt = 0; attempt < 128; attempt++) {
         const shuffled = [...gems];
@@ -47,7 +47,7 @@ export function reshuffleTransition(state) {
         const board = [...state.board];
         let at = 0;
         for (let index = 0; index < board.length; index++)
-            if (state.settings.mask[index])
+            if (state.settings.mask[index] && index !== state.blackHole?.cell)
                 board[index] = shuffled[at++];
         if (!findMatches(board, state.settings).length && listLegalSwaps({ ...state, board }).length) {
             return { state: Object.freeze({ ...state, board: Object.freeze(board), randomState, assisted: true, phase: 'ready', outcome: null, selectedTool: null, toolTarget: null, toolPreview: Object.freeze([]) }), events: Object.freeze([{ type: 'board-reshuffled', attempts: attempt + 1, assisted: true }]), accepted: true };