@johnmorrisdotca/houseki 0.4.1 → 0.4.2

package/dist/stone-collapse/engine.d.ts

@@ -1,19 +1,110 @@
 import type { Action, ChallengeOptions, CreateOptions, GameState, GameStatus, Stone, Transition } from './types.js';
 /** @internal Constructs the generator's bounded valid-pair fallback for direct invariant checks. */
 export declare function fallbackBoard(mask: readonly boolean[], width: number, height: number, colourCount: number): readonly (Stone | null)[];
-/** Creates a seeded full board; an all-singleton draw retries before using a checked adjacent pair. */
+/** Creates a seeded full board; an all-singleton draw retries before using a checked adjacent pair.
+ *
+ * @param options - Validated native creation, authored challenge, or environment options described by this signature.
+ * @returns Creates a seeded full board; an all-singleton draw retries before using a checked adjacent pair.
+ * @example
+ * ```ts
+ * import { createGame } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * console.log(createGame({seed:"docs"}).phase);
+ * ```
+ */
 export declare function createGame(options?: CreateOptions): GameState;
-/** Creates a fixed witnessed challenge after validating its board, objective, move budget, and every witness group. */
+/** Creates a fixed witnessed challenge after validating its board, objective, move budget, and every witness group.
+ *
+ * @param options - Validated native creation, authored challenge, or environment options described by this signature.
+ * @returns Creates a fixed witnessed challenge after validating its board, objective, move budget, and every witness group.
+ * @example
+ * ```ts
+ * import { createChallenge, levelManifest } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * const level=levelManifest[0];
+ * console.log(createChallenge({id:level.id,seed:level.seed,width:level.width,height:level.height,colourCount:level.colourCount,initialBoard:level.board,goal:level.goal,moveLimit:level.moveLimit,witness:level.witness}).phase);
+ * ```
+ */
 export declare function createChallenge(options: ChallengeOptions): GameState;
-/** Applies a selection, confirmation, or cancellation without mutating its input. */
+/** Applies a selection, confirmation, or cancellation without mutating its input.
+ *
+ * @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 a selection, confirmation, or cancellation without mutating its input.
+ * @example
+ * ```ts
+ * import { applyAction, createGame } from "@johnmorrisdotca/houseki/stone-collapse";
+ * import type { Action } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * 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;
-/** Selects the next supplied witness group only while the run still matches its path; accepted hints mark the run assisted. */
+/** Selects the next supplied witness group only while the run still matches its path; accepted hints mark the run assisted.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Selects the next supplied witness group only while the run still matches its path; accepted hints mark the run assisted.
+ * @example
+ * ```ts
+ * import { createGame, requestHint } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(requestHint(state).accepted);
+ * ```
+ */
 export declare function requestHint(state: GameState): Transition;
-/** Restores the full pre-move state in Relaxed or Challenge practice and permanently marks the attempt assisted. */
+/** Restores the full pre-move state in Relaxed or Challenge practice and permanently marks the attempt assisted.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Restores the full pre-move state in Relaxed or Challenge practice and permanently marks the attempt assisted.
+ * @example
+ * ```ts
+ * import { createGame, undo } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(undo(state).accepted);
+ * ```
+ */
 export declare function undo(state: GameState): Transition;
-/** Advances the observable 7/6/9 tick removal and gravity stages, bounded to 3600 ticks. */
+/** Advances the observable 7/6/9 tick removal and gravity stages, bounded to 3600 ticks.
+ *
+ * @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 the observable 7/6/9 tick removal and gravity stages, bounded to 3600 ticks.
+ * @example
+ * ```ts
+ * import { advanceTicks, createGame } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(advanceTicks(state,1).state.phase);
+ * ```
+ */
 export declare function advanceTicks(state: GameState, ticks: number): Transition;
-/** Lists every selection and confirmation currently accepted by the rules. */
+/** Lists every selection and confirmation currently accepted by the rules.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Lists every selection and confirmation currently accepted by the rules.
+ * @example
+ * ```ts
+ * import { createGame, legalActions } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(legalActions(state).length);
+ * ```
+ */
 export declare function legalActions(state: GameState): readonly Action[];
-/** Returns the stable public game status and the remaining-stone count. */
+/** Returns the stable public game status and the remaining-stone count.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Returns the stable public game status and the remaining-stone count.
+ * @example
+ * ```ts
+ * import { createGame, statusOf } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(statusOf(state).phase);
+ * ```
+ */
 export declare function statusOf(state: GameState): GameStatus;

package/dist/stone-collapse/engine.js

@@ -105,7 +105,17 @@ function baseState(settings, board, randomState, challenge, usedFallback = false
         selectedTool: null, toolTarget: null, toolPreview: Object.freeze([]),
     };
 }
-/** Creates a seeded full board; an all-singleton draw retries before using a checked adjacent pair. */
+/** Creates a seeded full board; an all-singleton draw retries before using a checked adjacent pair.
+ *
+ * @param options - Validated native creation, authored challenge, or environment options described by this signature.
+ * @returns Creates a seeded full board; an all-singleton draw retries before using a checked adjacent pair.
+ * @example
+ * ```ts
+ * import { createGame } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * console.log(createGame({seed:"docs"}).phase);
+ * ```
+ */
 export function createGame(options = {}) {
     const valid = optionsFor(options); // All settings are checked before drawing any random values.
     let randomState = hashSeed(`stone-collapse|${RULES}|${String(valid.seed)}`);
@@ -140,7 +150,18 @@ export function createGame(options = {}) {
     const state = baseState(settings, board, randomState, null, usedFallback);
     return { ...state, nextId };
 }
-/** Creates a fixed witnessed challenge after validating its board, objective, move budget, and every witness group. */
+/** Creates a fixed witnessed challenge after validating its board, objective, move budget, and every witness group.
+ *
+ * @param options - Validated native creation, authored challenge, or environment options described by this signature.
+ * @returns Creates a fixed witnessed challenge after validating its board, objective, move budget, and every witness group.
+ * @example
+ * ```ts
+ * import { createChallenge, levelManifest } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * const level=levelManifest[0];
+ * console.log(createChallenge({id:level.id,seed:level.seed,width:level.width,height:level.height,colourCount:level.colourCount,initialBoard:level.board,goal:level.goal,moveLimit:level.moveLimit,witness:level.witness}).phase);
+ * ```
+ */
 export function createChallenge(options) {
     if (!options || typeof options !== 'object' || Array.isArray(options))
         throw new StoneCollapseOptionsError('invalid-challenge', 'Challenge options must be an object');
@@ -466,13 +487,61 @@ function applyCore(state, action) {
     }
     return confirmSelected(state);
 }
-/** Applies a selection, confirmation, or cancellation without mutating its input. */
+/** Applies a selection, confirmation, or cancellation without mutating its input.
+ *
+ * @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 a selection, confirmation, or cancellation without mutating its input.
+ * @example
+ * ```ts
+ * import { applyAction, createGame } from "@johnmorrisdotca/houseki/stone-collapse";
+ * import type { Action } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * const state=createGame({seed:"docs"});
+ * const action: Action={kind:"hint"};
+ * console.log(applyAction(state,action).accepted);
+ * ```
+ */
 export function applyAction(state, action) { return applyCore(state, action); }
-/** Selects the next supplied witness group only while the run still matches its path; accepted hints mark the run assisted. */
+/** Selects the next supplied witness group only while the run still matches its path; accepted hints mark the run assisted.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Selects the next supplied witness group only while the run still matches its path; accepted hints mark the run assisted.
+ * @example
+ * ```ts
+ * import { createGame, requestHint } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(requestHint(state).accepted);
+ * ```
+ */
 export function requestHint(state) { return applyCore(state, { kind: 'hint' }); }
-/** Restores the full pre-move state in Relaxed or Challenge practice and permanently marks the attempt assisted. */
+/** Restores the full pre-move state in Relaxed or Challenge practice and permanently marks the attempt assisted.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Restores the full pre-move state in Relaxed or Challenge practice and permanently marks the attempt assisted.
+ * @example
+ * ```ts
+ * import { createGame, undo } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(undo(state).accepted);
+ * ```
+ */
 export function undo(state) { return undoCore(state); }
-/** Advances the observable 7/6/9 tick removal and gravity stages, bounded to 3600 ticks. */
+/** Advances the observable 7/6/9 tick removal and gravity stages, bounded to 3600 ticks.
+ *
+ * @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 the observable 7/6/9 tick removal and gravity stages, bounded to 3600 ticks.
+ * @example
+ * ```ts
+ * import { advanceTicks, createGame } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * 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');
@@ -521,7 +590,18 @@ export function advanceTicks(state, ticks) {
     }
     return { state: current, events: Object.freeze(events), accepted: true };
 }
-/** Lists every selection and confirmation currently accepted by the rules. */
+/** Lists every selection and confirmation currently accepted by the rules.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Lists every selection and confirmation currently accepted by the rules.
+ * @example
+ * ```ts
+ * import { createGame, legalActions } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(legalActions(state).length);
+ * ```
+ */
 export function legalActions(state) {
     if (state.phase === 'won' || state.phase === 'finished' || state.phase === 'lost')
         return canUndo(state) ? [{ kind: 'undo' }] : [];
@@ -564,7 +644,18 @@ export function legalActions(state) {
         actions.push({ kind: 'undo' });
     return actions;
 }
-/** Returns the stable public game status and the remaining-stone count. */
+/** Returns the stable public game status and the remaining-stone count.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Returns the stable public game status and the remaining-stone count.
+ * @example
+ * ```ts
+ * import { createGame, statusOf } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(statusOf(state).phase);
+ * ```
+ */
 export function statusOf(state) {
     return { mode: state.settings.mode, phase: state.phase, score: state.score, moves: state.moves, removed: state.removed, remaining: state.board.filter(Boolean).length, previewScore: state.previewScore, usedFallback: state.usedFallback, assisted: state.assisted, inventory: state.inventory, toolProgress: state.toolProgress, toolAwardCursor: state.toolAwardCursor, selectedTool: state.selectedTool, toolTarget: state.toolTarget, toolPreview: state.toolPreview, ...(state.settings.goal ? { goal: state.settings.goal } : {}), ...(state.reason ? { reason: state.reason } : {}) };
 }

package/dist/stone-collapse/persistence.d.ts

@@ -1,7 +1,40 @@
 import type { GameState } from './types.js';
-/** Starts a fresh attempt from the identical seeded board or preserved challenge definition. */
+/** Starts a fresh attempt from the identical seeded board or preserved challenge definition.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Starts a fresh attempt from the identical seeded board or preserved challenge definition.
+ * @example
+ * ```ts
+ * import { createGame, restartGame } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(restartGame(state).phase);
+ * ```
+ */
 export declare function restartGame(state: GameState): GameState;
-/** Encodes the canonical initial configuration, accepted replay actions, and a derived checkpoint. */
+/** Encodes the canonical initial configuration, accepted replay actions, and a derived checkpoint.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Encodes the canonical initial configuration, accepted replay actions, and a derived checkpoint.
+ * @example
+ * ```ts
+ * import { createGame, encodeGame } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(encodeGame(state).length);
+ * ```
+ */
 export declare function encodeGame(state: GameState): string;
-/** Reconstructs and validates a bounded replay before accepting its checkpoint. */
+/** Reconstructs and validates a bounded replay before accepting its checkpoint.
+ *
+ * @param text - A saved JSON recording from this entry’s encodeGame; malformed or inconsistent saves throw.
+ * @returns Reconstructs and validates a bounded replay before accepting its checkpoint.
+ * @example
+ * ```ts
+ * import { createGame, decodeGame, encodeGame } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(decodeGame(encodeGame(state)).phase);
+ * ```
+ */
 export declare function decodeGame(text: string): GameState;

package/dist/stone-collapse/persistence.js

@@ -35,7 +35,18 @@ function groupAt(board, settings, start) {
             }
     return [...found].sort((a, b) => a - b);
 }
-/** Starts a fresh attempt from the identical seeded board or preserved challenge definition. */
+/** Starts a fresh attempt from the identical seeded board or preserved challenge definition.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Starts a fresh attempt from the identical seeded board or preserved challenge definition.
+ * @example
+ * ```ts
+ * import { createGame, restartGame } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(restartGame(state).phase);
+ * ```
+ */
 export function restartGame(state) {
     if (state.settings.mode === 'challenge')
         return createChallenge(state.challenge);
@@ -45,7 +56,18 @@ export function restartGame(state) {
     const mode = settings.mode === 'arcade' ? 'arcade' : 'relaxed';
     return createGame({ mode, colourCount: settings.colourCount, seed: settings.seed, tools: settings.tools, ...(settings.shape ? { shape: settings.shape } : { width: settings.width, height: settings.height, ...(settings.mask.every(Boolean) ? {} : { mask: settings.mask }) }) });
 }
-/** Encodes the canonical initial configuration, accepted replay actions, and a derived checkpoint. */
+/** Encodes the canonical initial configuration, accepted replay actions, and a derived checkpoint.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Encodes the canonical initial configuration, accepted replay actions, and a derived checkpoint.
+ * @example
+ * ```ts
+ * import { createGame, encodeGame } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(encodeGame(state).length);
+ * ```
+ */
 export function encodeGame(state) {
     // Undo frames are derived by replaying committed actions; storing their full board snapshots scales poorly on deep boards.
     const { history: _history, ...checkpoint } = state;
@@ -99,7 +121,18 @@ function stateFromInitial(settings, challenge) {
         throw new TypeError('Initial settings are not canonical');
     return state;
 }
-/** Reconstructs and validates a bounded replay before accepting its checkpoint. */
+/** Reconstructs and validates a bounded replay before accepting its checkpoint.
+ *
+ * @param text - A saved JSON recording from this entry’s encodeGame; malformed or inconsistent saves throw.
+ * @returns Reconstructs and validates a bounded replay before accepting its checkpoint.
+ * @example
+ * ```ts
+ * import { createGame, decodeGame, encodeGame } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(decodeGame(encodeGame(state)).phase);
+ * ```
+ */
 export function decodeGame(text) {
     if (typeof text !== 'string' || new TextEncoder().encode(text).length > 2 * 1024 * 1024)
         throw new RangeError('Save must be text no larger than 2 MiB');

package/dist/stone-collapse/types.d.ts

@@ -1,19 +1,111 @@
-/** A colour used by a stone. */
+/** A colour used by a stone.
+ *
+ * @example
+ * ```ts
+ * import type { StoneColour } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * const value: StoneColour = "red";
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type StoneColour = 'red' | 'blue' | 'green' | 'gold' | 'purple' | 'teal';
-/** A stone keeps its run-local identity as it falls or changes column. */
+/** A stone keeps its run-local identity as it falls or changes column.
+ *
+ * @example
+ * ```ts
+ * import type { Stone } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * const value: Stone = {id:1,colour:"red"};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface Stone {
     readonly id: number;
     readonly colour: StoneColour;
 }
+/** A named native board geometry; custom dimensions remain a separate option.
+ *
+ * @example
+ * ```ts
+ * import type { BoardPreset } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * const value: BoardPreset = "compact";
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type BoardPreset = 'compact' | 'standard' | 'wide' | 'tall' | 'extraWide' | 'deep' | 'large';
+/** A native shaped active-cell layout applied to the row-major board.
+ *
+ * @example
+ * ```ts
+ * import type { BoardShape } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * const value: BoardShape = "heart";
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type BoardShape = 'heart' | 'star' | 'hexagon';
+/** The native free, timed, daily or authored-challenge game mode.
+ *
+ * @example
+ * ```ts
+ * import type { GameMode } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * const value: GameMode = "relaxed";
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type GameMode = 'relaxed' | 'arcade' | 'daily' | 'challenge';
+/** A stored Stone Collapse tool selected from the native Bomb and Pick tray.
+ *
+ * @example
+ * ```ts
+ * import type { StoredTool } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * const value: StoredTool = "bomb";
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type StoredTool = 'bomb' | 'pick';
+/** The native remaining counts of stored tools.
+ *
+ * @example
+ * ```ts
+ * import { createGame } from "@johnmorrisdotca/houseki/stone-collapse";
+ * import type { ToolInventory } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * const state=createGame({seed:"docs"});
+ * const value: ToolInventory = state.inventory;
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface ToolInventory {
     readonly bomb: number;
     readonly pick: number;
 }
+/** The native ready, resolution and ending phases.
+ *
+ * @example
+ * ```ts
+ * import { createGame } from "@johnmorrisdotca/houseki/stone-collapse";
+ * import type { GamePhase } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * const state=createGame({seed:"docs"});
+ * const value: GamePhase = state.phase;
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type GamePhase = 'ready' | 'clear-mark' | 'clear-remove' | 'gravity' | 'won' | 'lost' | 'finished';
+/** A native authored challenge objective; its discriminant selects target, chain, empty-board or score requirements.
+ *
+ * @example
+ * ```ts
+ * import type { ChallengeGoal } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * const value: ChallengeGoal = {kind:"clear-all"};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type ChallengeGoal = {
     readonly kind: 'clear-all';
 } | {
@@ -23,6 +115,18 @@ export type ChallengeGoal = {
     readonly kind: 'score-target';
     readonly minimumScore: number;
 };
+/** Validated settings fixed at native game creation.
+ *
+ * @example
+ * ```ts
+ * import { createGame } from "@johnmorrisdotca/houseki/stone-collapse";
+ * import type { Settings } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * const state=createGame({seed:"docs"});
+ * const value: Settings = state.settings;
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface Settings {
     readonly mode: GameMode;
     readonly width: number;
@@ -37,6 +141,18 @@ export interface Settings {
     readonly moveLimit?: number;
     readonly tools: boolean;
 }
+/** A validated Stone Collapse authored setup and stable-id group witness.
+ *
+ * @example
+ * ```ts
+ * import { createGame } from "@johnmorrisdotca/houseki/stone-collapse";
+ * import type { ChallengeDefinition } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * const state=createGame({seed:"docs"});
+ * const value: ChallengeDefinition = {id:"docs",width:state.settings.width,height:state.settings.height,colourCount:4,seed:"docs",mask:state.settings.mask,initialBoard:state.board,goal:{kind:"clear-all"},witness:[]};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface ChallengeDefinition {
     readonly id: string;
     readonly width: number;
@@ -50,7 +166,18 @@ export interface ChallengeDefinition {
     /** Each entry is the complete stable-ID set of the next witnessed group. */
     readonly witness: readonly (readonly number[])[];
 }
-/** Data sufficient to restore the complete game immediately before a committed move. */
+/** Data sufficient to restore the complete game immediately before a committed move.
+ *
+ * @example
+ * ```ts
+ * import { createGame } from "@johnmorrisdotca/houseki/stone-collapse";
+ * import type { UndoFrame } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * const state=createGame({seed:"docs"});
+ * const value: UndoFrame = {board:state.board,score:0,moves:0,removed:0,randomState:state.randomState,nextId:state.nextId,usedFallback:false,finishAdjustmentApplied:false,selectedId:null,selectedIds:[],previewScore:0,witnessIndex:0,inventory:state.inventory,toolProgress:0,toolAwardCursor:0,selectedTool:null,toolTarget:null,toolPreview:[]};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface UndoFrame {
     readonly board: readonly (Stone | null)[];
     readonly score: number;
@@ -71,6 +198,16 @@ export interface UndoFrame {
     readonly toolTarget: number | null;
     readonly toolPreview: readonly number[];
 }
+/** A native action recording with the logical position needed for deterministic replay.
+ *
+ * @example
+ * ```ts
+ * import type { RecordedAction } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * const value: RecordedAction = {kind:"ticks",count:1};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type RecordedAction = {
     readonly kind: 'remove';
     readonly move: number;
@@ -96,6 +233,18 @@ export type RecordedAction = {
     readonly kind: 'ticks';
     readonly count: number;
 };
+/** The immutable authoritative native game state, including its board, random state and recording.
+ *
+ * @example
+ * ```ts
+ * import { createGame } from "@johnmorrisdotca/houseki/stone-collapse";
+ * import type { GameState } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * const state=createGame({seed:"docs"});
+ * const value: GameState = state;
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface GameState {
     readonly game: 'stone-collapse';
     readonly rules: 'collapse-2';
@@ -136,6 +285,17 @@ export interface GameState {
     /** Exact row-major cells affected by the current target. */
     readonly toolPreview: readonly number[];
 }
+/** A native player action accepted or rejected according to the current phase and rules.
+ *
+ * @example
+ * ```ts
+ * import type { Action } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * const action: Action={kind:"hint"};
+ * const value: Action = action;
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type Action = {
     readonly kind: 'select';
     readonly stoneId: number;
@@ -158,16 +318,49 @@ export type Action = {
 } | {
     readonly kind: 'cancel-tool';
 };
+/** An event emitted by one native transition; type selects the event’s additional fields.
+ *
+ * @example
+ * ```ts
+ * import type { GameEvent } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * const value: GameEvent = {type:"host-example"};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface GameEvent {
     readonly type: string;
     readonly [key: string]: unknown;
 }
+/** The resulting native state, emitted events and acceptance decision; rejected actions preserve the input.
+ *
+ * @example
+ * ```ts
+ * import { applyAction, createGame } from "@johnmorrisdotca/houseki/stone-collapse";
+ * import type { Action, Transition } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * const state=createGame({seed:"docs"});
+ * const action: Action={kind:"hint"};
+ * const value: Transition = applyAction(state,action);
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface Transition {
     readonly state: GameState;
     readonly events: readonly GameEvent[];
     readonly accepted: boolean;
     readonly reason?: string;
 }
+/** Creation settings for this native engine; dimensions, mode, seed and optional mechanics are validated together.
+ *
+ * @example
+ * ```ts
+ * import type { CreateOptions } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * const value: CreateOptions = {seed:"docs"};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface CreateOptions {
     readonly mode?: Exclude<GameMode, 'challenge'>;
     readonly preset?: BoardPreset;
@@ -183,6 +376,18 @@ export interface CreateOptions {
     /** Optional Bomb and Pick tray; available only in Relaxed and Arcade. */
     readonly tools?: boolean;
 }
+/** Authored challenge inputs including the starting board, finite goal and supplied witness.
+ *
+ * @example
+ * ```ts
+ * import { createGame } from "@johnmorrisdotca/houseki/stone-collapse";
+ * import type { ChallengeOptions } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * const state=createGame({seed:"docs"});
+ * const value: ChallengeOptions = {id:"docs",width:6,height:6,colourCount:4,initialBoard:state.board,goal:{kind:"clear-all"},witness:[]};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface ChallengeOptions {
     readonly id: string;
     readonly width: number;
@@ -195,6 +400,18 @@ export interface ChallengeOptions {
     readonly moveLimit?: number;
     readonly witness: readonly (readonly number[])[];
 }
+/** A compact native status derived from the authoritative state for a host’s labels.
+ *
+ * @example
+ * ```ts
+ * import { createGame, statusOf } from "@johnmorrisdotca/houseki/stone-collapse";
+ * import type { GameStatus } from "@johnmorrisdotca/houseki/stone-collapse";
+ *
+ * const state=createGame({seed:"docs"});
+ * const value: GameStatus = statusOf(state);
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface GameStatus {
     readonly mode: GameMode;
     readonly phase: GamePhase;