@johnmorrisdotca/houseki 0.4.1 → 0.4.2

package/dist/magnetic-blocks/content.js

@@ -8,28 +8,114 @@ function deepFreeze(value) {
     }
     return value;
 }
+/** The frozen native campaign manifest with its ordering, revisions, checksum and measured levels.
+ *
+ * @example
+ * ```ts
+ * import { campaignManifest } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * console.log(campaignManifest.count);
+ * ```
+ */
 export const campaignManifest = deepFreeze(contentData.campaign);
+/** The frozen ordered native levels; array indices start at zero and display numbers start at one.
+ *
+ * @example
+ * ```ts
+ * import { levelManifest } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * console.log(levelManifest.length);
+ * ```
+ */
 export const levelManifest = campaignManifest.levels;
-/** Alias kept alongside other Houseki campaign lesson APIs. */
+/** Alias kept alongside other Houseki campaign lesson APIs.
+ *
+ * @example
+ * ```ts
+ * import { tutorialManifest } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * console.log(tutorialManifest.length);
+ * ```
+ */
 export const tutorialManifest = deepFreeze(contentData.lessons);
+/** The frozen native bilingual lessons and their authored teaching steps.
+ *
+ * @example
+ * ```ts
+ * import { lessonManifest } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * console.log(lessonManifest.length);
+ * ```
+ */
 export const lessonManifest = tutorialManifest;
-/** Finds a Magnetic Blocks campaign level by stable ID or one-based display number. */
+/** Finds a Magnetic Blocks campaign level by stable ID or one-based display number.
+ *
+ * @param id - A stable content id, or the one-based display number when numbers are accepted.
+ * @returns Finds a Magnetic Blocks campaign level by stable ID or one-based display number. Returns undefined when the id or display number is absent.
+ * @example
+ * ```ts
+ * import { getLevel } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * console.log(getLevel(1)?.id);
+ * ```
+ */
 export function getLevel(id) {
     if (typeof id === 'number')
         return Number.isInteger(id) ? levelManifest.find(level => level.number === id) : undefined;
     return levelManifest.find(level => level.id === id);
 }
-/** Creates a fresh game with the authored rules, board, queue, and finite move budget. */
+/** Creates a fresh game with the authored rules, board, queue, and finite move budget.
+ *
+ * @param id - A stable content id, or the one-based display number when numbers are accepted.
+ * @returns Creates a fresh game with the authored rules, board, queue, and finite move budget.
+ * @example
+ * ```ts
+ * import { createLevel } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * console.log(createLevel(1).phase);
+ * ```
+ */
 export function createLevel(id) {
     const level = getLevel(id);
     if (!level)
         throw new RangeError(`Unknown Magnetic Blocks level: ${String(id)}`);
     return createGame(level.options);
 }
-/** Finds one of the three bilingual rules lessons by stable ID. */
+/** Finds one of the three bilingual rules lessons by stable ID.
+ *
+ * @param id - A stable content id, or the one-based display number when numbers are accepted.
+ * @returns Finds one of the three bilingual rules lessons by stable ID. Returns undefined when the id or display number is absent.
+ * @example
+ * ```ts
+ * import { getLesson, lessonManifest } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * console.log(getLesson(lessonManifest[0].id)?.id);
+ * ```
+ */
 export function getLesson(id) { return tutorialManifest.find(lesson => lesson.id === id); }
+/** Find a magnetic-block lesson by stable id; returns undefined when no lesson has that id.
+ *
+ * @param id - A stable content id, or the one-based display number when numbers are accepted.
+ * @returns Find a magnetic-block lesson by stable id; returns undefined when no lesson has that id. Returns undefined when the id or display number is absent.
+ * @example
+ * ```ts
+ * import { getTutorial, lessonManifest } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * console.log(getTutorial(lessonManifest[0].id)?.id);
+ * ```
+ */
 export const getTutorial = getLesson;
-/** Creates a fresh lesson game with its authored setup and queue. */
+/** Creates a fresh lesson game with its authored setup and queue.
+ *
+ * @param id - A stable content id, or the one-based display number when numbers are accepted.
+ * @returns Creates a fresh lesson game with its authored setup and queue.
+ * @example
+ * ```ts
+ * import { createLesson, lessonManifest } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * console.log(createLesson(lessonManifest[0].id).phase);
+ * ```
+ */
 export function createLesson(id) {
     const lesson = getLesson(id);
     if (!lesson)

package/dist/magnetic-blocks/engine.d.ts

@@ -1,11 +1,69 @@
 import type { Action, GameState, GameStatus, Transition } from './types.js';
-/** Creates an immutable seeded 2×2-block game with a fixed queue and explicit floor schedule. */
+/** Creates an immutable seeded 2×2-block game with a fixed queue and explicit floor schedule.
+ *
+ * @param options - Validated native creation, authored challenge, or environment options described by this signature.
+ * @returns Creates an immutable seeded 2×2-block game with a fixed queue and explicit floor schedule.
+ * @example
+ * ```ts
+ * import { createGame } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * console.log(createGame({seed:"docs"}).phase);
+ * ```
+ */
 export declare function createGame(options?: import('./types.js').CreateOptions): GameState;
-/** Applies one movement, rotation, floor-switch or placement action without mutation. */
+/** Applies one movement, rotation, floor-switch or placement action without mutation.
+ *
+ * @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 movement, rotation, floor-switch or placement action without mutation.
+ * @example
+ * ```ts
+ * import { applyAction, createGame } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ * import type { Action } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const state=createGame({seed:"docs"});
+ * const action: Action={kind:"left"};
+ * console.log(applyAction(state,action).accepted);
+ * ```
+ */
 export declare function applyAction(state: GameState, action: Action): Transition;
-/** Advances fixed 60 Hz time, resolving phases in all modes and falling/locking only in Arcade. */
+/** Advances fixed 60 Hz time, resolving phases in all modes and falling/locking only in Arcade.
+ *
+ * @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 fixed 60 Hz time, resolving phases in all modes and falling/locking only in Arcade.
+ * @example
+ * ```ts
+ * import { advanceTicks, createGame } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(advanceTicks(state,1).state.phase);
+ * ```
+ */
 export declare function advanceTicks(state: GameState, ticks: number): Transition;
-/** Lists accepted controls for the current falling or resolution phase. */
+/** Lists accepted controls for the current falling or resolution phase.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Lists accepted controls for the current falling or resolution phase.
+ * @example
+ * ```ts
+ * import { createGame, legalActions } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(legalActions(state).length);
+ * ```
+ */
 export declare function legalActions(state: GameState): readonly Action[];
-/** Returns a compact immutable status including current and upcoming floor state. */
+/** Returns a compact immutable status including current and upcoming floor state.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Returns a compact immutable status including current and upcoming floor state.
+ * @example
+ * ```ts
+ * import { createGame, statusOf } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(statusOf(state).phase);
+ * ```
+ */
 export declare function statusOf(state: GameState): GameStatus;

package/dist/magnetic-blocks/engine.js

@@ -154,7 +154,17 @@ function core(state, action) {
     const reset = state.settings.mode === 'arcade' && grounded && active.lockResets < 8;
     return { state: { ...state, active: freezeBlock({ ...rotated, lockTicks: reset ? 0 : active.lockTicks, lockResets: active.lockResets + (reset ? 1 : 0), lockStarted: reset ? true : active.lockStarted }) }, events: [{ type: 'piece-rotated', orientation, ids: rotated.gems.map(gem => gem.id), cells: blockCells(rotated, width).map(item => item.index) }], accepted: true };
 }
-/** Creates an immutable seeded 2×2-block game with a fixed queue and explicit floor schedule. */
+/** Creates an immutable seeded 2×2-block game with a fixed queue and explicit floor schedule.
+ *
+ * @param options - Validated native creation, authored challenge, or environment options described by this signature.
+ * @returns Creates an immutable seeded 2×2-block game with a fixed queue and explicit floor schedule.
+ * @example
+ * ```ts
+ * import { createGame } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * console.log(createGame({seed:"docs"}).phase);
+ * ```
+ */
 export function createGame(options = {}) {
     const valid = validateOptions(options);
     let randomState, queue;
@@ -175,7 +185,21 @@ export function createGame(options = {}) {
     const [started] = spawn(state);
     return freezeState(started);
 }
-/** Applies one movement, rotation, floor-switch or placement action without mutation. */
+/** Applies one movement, rotation, floor-switch or placement action without mutation.
+ *
+ * @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 movement, rotation, floor-switch or placement action without mutation.
+ * @example
+ * ```ts
+ * import { applyAction, createGame } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ * import type { Action } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const state=createGame({seed:"docs"});
+ * const action: Action={kind:"left"};
+ * console.log(applyAction(state,action).accepted);
+ * ```
+ */
 export function applyAction(state, action) {
     const result = core(state, action);
     if (!result.accepted)
@@ -186,7 +210,19 @@ export function applyAction(state, action) {
     const next = freezeState({ ...result.state, recording: Object.freeze([...state.recording, recorded]) });
     return { ...result, state: next };
 }
-/** Advances fixed 60 Hz time, resolving phases in all modes and falling/locking only in Arcade. */
+/** Advances fixed 60 Hz time, resolving phases in all modes and falling/locking only in Arcade.
+ *
+ * @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 fixed 60 Hz time, resolving phases in all modes and falling/locking only in Arcade.
+ * @example
+ * ```ts
+ * import { advanceTicks, createGame } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * 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');
@@ -245,7 +281,18 @@ export function advanceTicks(state, ticks) {
     }
     return { state: freezeState(current), events: Object.freeze(events), accepted: true };
 }
-/** Lists accepted controls for the current falling or resolution phase. */
+/** Lists accepted controls for the current falling or resolution phase.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Lists accepted controls for the current falling or resolution phase.
+ * @example
+ * ```ts
+ * import { createGame, legalActions } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(legalActions(state).length);
+ * ```
+ */
 export function legalActions(state) {
     if (state.phase === 'paused')
         return Object.freeze([{ kind: 'resume' }]);
@@ -261,5 +308,16 @@ export function legalActions(state) {
         ]);
     return Object.freeze([]);
 }
-/** Returns a compact immutable status including current and upcoming floor state. */
+/** Returns a compact immutable status including current and upcoming floor state.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Returns a compact immutable status including current and upcoming floor state.
+ * @example
+ * ```ts
+ * import { createGame, statusOf } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(statusOf(state).phase);
+ * ```
+ */
 export function statusOf(state) { return Object.freeze({ phase: state.phase, score: state.score, moves: state.moves, placements: state.placements, floor: state.pendingFloorOverride ?? state.floor, nextFloor: state.nextFloor, floorSwitchCharges: state.floorSwitchCharges, pendingFloorOverride: state.pendingFloorOverride, maxChain: state.maxChain, ...(state.reason ? { reason: state.reason } : {}) }); }

package/dist/magnetic-blocks/persistence.d.ts

@@ -1,7 +1,40 @@
 import type { GameState } from './types.js';
-/** Restarts the same seed, custom starting board, fixed queue, rules and floor options. */
+/** Restarts the same seed, custom starting board, fixed queue, rules and floor options.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Restarts the same seed, custom starting board, fixed queue, rules and floor options.
+ * @example
+ * ```ts
+ * import { createGame, restartGame } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(restartGame(state).phase);
+ * ```
+ */
 export declare function restartGame(state: GameState): GameState;
-/** Encodes canonical settings, accepted tick-stamped actions and a verified replay checkpoint. */
+/** Encodes canonical settings, accepted tick-stamped actions and a verified replay checkpoint.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Encodes canonical settings, accepted tick-stamped actions and a verified replay checkpoint.
+ * @example
+ * ```ts
+ * import { createGame, encodeGame } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(encodeGame(state).length);
+ * ```
+ */
 export declare function encodeGame(state: GameState): string;
-/** Replays bounded canonical input and verifies every saved checkpoint field. */
+/** Replays bounded canonical input and verifies every saved checkpoint field.
+ *
+ * @param text - A saved JSON recording from this entry’s encodeGame; malformed or inconsistent saves throw.
+ * @returns Replays bounded canonical input and verifies every saved checkpoint field.
+ * @example
+ * ```ts
+ * import { createGame, decodeGame, encodeGame } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(decodeGame(encodeGame(state)).phase);
+ * ```
+ */
 export declare function decodeGame(text: string): GameState;

package/dist/magnetic-blocks/persistence.js

@@ -68,9 +68,31 @@ function replay(settings, actions, elapsedTicks) {
     }
     return state;
 }
-/** Restarts the same seed, custom starting board, fixed queue, rules and floor options. */
+/** Restarts the same seed, custom starting board, fixed queue, rules and floor options.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Restarts the same seed, custom starting board, fixed queue, rules and floor options.
+ * @example
+ * ```ts
+ * import { createGame, restartGame } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(restartGame(state).phase);
+ * ```
+ */
 export function restartGame(state) { return createFromSettings(state.settings); }
-/** Encodes canonical settings, accepted tick-stamped actions and a verified replay checkpoint. */
+/** Encodes canonical settings, accepted tick-stamped actions and a verified replay checkpoint.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Encodes canonical settings, accepted tick-stamped actions and a verified replay checkpoint.
+ * @example
+ * ```ts
+ * import { createGame, encodeGame } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(encodeGame(state).length);
+ * ```
+ */
 export function encodeGame(state) {
     if (!Number.isSafeInteger(state.elapsedTicks) || state.elapsedTicks < 0 || state.elapsedTicks > MAX_TICKS || state.recording.length > MAX_ACTIONS)
         throw new RangeError('Run exceeds replay limits');
@@ -82,7 +104,18 @@ export function encodeGame(state) {
         throw new RangeError('Save exceeds 2 MiB');
     return text;
 }
-/** Replays bounded canonical input and verifies every saved checkpoint field. */
+/** Replays bounded canonical input and verifies every saved checkpoint field.
+ *
+ * @param text - A saved JSON recording from this entry’s encodeGame; malformed or inconsistent saves throw.
+ * @returns Replays bounded canonical input and verifies every saved checkpoint field.
+ * @example
+ * ```ts
+ * import { createGame, decodeGame, encodeGame } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(decodeGame(encodeGame(state)).phase);
+ * ```
+ */
 export function decodeGame(text) {
     if (typeof text !== 'string' || new TextEncoder().encode(text).byteLength > MAX_SAVE_BYTES)
         throw new RangeError('Save must be text no larger than 2 MiB');

package/dist/magnetic-blocks/physics.d.ts

@@ -1,30 +1,200 @@
 import type { Block, Bond, Floor, Gem } from './types.js';
 export declare const HIDDEN_ROWS = 0;
-export declare const MARK_TICKS = 7, REMOVE_TICKS = 6, GRAVITY_TICKS = 9;
+/** The fixed 60 Hz ticks showing the magnetic-block match mark phase.
+ *
+ * @example
+ * ```ts
+ * import { MARK_TICKS } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * console.log(MARK_TICKS);
+ * ```
+ */
+export declare const MARK_TICKS = 7;
+/** Fixed 60 Hz ticks in the magnetic-block removal phase.
+ * @example
+ * ```ts
+ * import { REMOVE_TICKS } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ * console.log(REMOVE_TICKS);
+ * ```
+ */
+export declare const REMOVE_TICKS = 6;
+/** Fixed 60 Hz ticks in the magnetic-block gravity phase.
+ * @example
+ * ```ts
+ * import { GRAVITY_TICKS } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ * console.log(GRAVITY_TICKS);
+ * ```
+ */
+export declare const GRAVITY_TICKS = 9;
 export declare const cell: (x: number, y: number, width: number) => number;
-/** Returns stable-gem addresses after rotating the square block around its centre. */
+/** Returns stable-gem addresses after rotating the square block around its centre.
+ *
+ * @param block - The native active 2×2 block and its stable gem ids.
+ * @param width - The native board width in cells.
+ * @returns Returns stable-gem addresses after rotating the square block around its centre.
+ * @example
+ * ```ts
+ * import { blockCells, createGame } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(blockCells(state.active!,state.settings.width).length);
+ * ```
+ */
 export declare function blockCells(block: Block, width: number): readonly {
     readonly index: number;
     readonly gem: Gem;
 }[];
+/** Test whether the whole native block fits passable empty board cells.
+ *
+ * @param block - The native active 2×2 block and its stable gem ids.
+ * @param board - The row-major native board; null cells are empty or masked.
+ * @param width - The native board width in cells.
+ * @param height - The native board height in cells.
+ * @param mask - The row-major active-cell mask; false cells cannot hold gems.
+ * @returns Test whether the whole native block fits passable empty board cells.
+ * @example
+ * ```ts
+ * import { canPlace, createGame } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(canPlace(state.active!,state.board,state.settings.width,state.settings.height,state.settings.mask));
+ * ```
+ */
 export declare function canPlace(block: Block, board: readonly (Gem | null)[], width: number, height: number, mask: readonly boolean[]): boolean;
+/** Find the last legal block row before downward collision.
+ *
+ * @param block - The native active 2×2 block and its stable gem ids.
+ * @param board - The row-major native board; null cells are empty or masked.
+ * @param width - The native board width in cells.
+ * @param height - The native board height in cells.
+ * @param mask - The row-major active-cell mask; false cells cannot hold gems.
+ * @returns Find the last legal block row before downward collision.
+ * @example
+ * ```ts
+ * import { createGame, landingY } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(landingY(state.active!,state.board,state.settings.width,state.settings.height,state.settings.mask));
+ * ```
+ */
 export declare function landingY(block: Block, board: readonly (Gem | null)[], width: number, height: number, mask: readonly boolean[]): number;
-/** Computes deterministic orthogonal colour components of at least four gems. */
+/** Computes deterministic orthogonal colour components of at least four gems.
+ *
+ * @param board - The row-major native board; null cells are empty or masked.
+ * @param width - The native board width in cells.
+ * @param height - The native board height in cells.
+ * @param mask - The row-major active-cell mask; false cells cannot hold gems.
+ * @returns Computes deterministic orthogonal colour components of at least four gems.
+ * @example
+ * ```ts
+ * import { createGame, matchGroups } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(matchGroups(state.board,state.settings.width,state.settings.height,state.settings.mask).length);
+ * ```
+ */
 export declare function matchGroups(board: readonly (Gem | null)[], width: number, height: number, mask: readonly boolean[]): readonly (readonly number[])[];
 export declare function allMatchedCells(groups: readonly (readonly number[])[]): readonly number[];
+/** Remove the selected native cell indices and discard bonds whose endpoint gems were removed.
+ *
+ * @param board - The row-major native board; null cells are empty or masked.
+ * @param bonds - Native stable-id bonds connecting surviving gems.
+ * @param indices - Row-major cell indices selected for removal.
+ * @returns Remove the selected native cell indices and discard bonds whose endpoint gems were removed. Nested null values denote empty board cells, absent active pieces, unselected tools or outcomes not yet reached; optional undefined fields are absent until applicable.
+ * @example
+ * ```ts
+ * import { createGame, removeIds } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(removeIds(state.board,state.bonds,[]).ids.length);
+ * ```
+ */
 export declare function removeIds(board: readonly (Gem | null)[], bonds: readonly Bond[], indices: readonly number[]): {
     readonly board: readonly (Gem | null)[];
     readonly bonds: readonly Bond[];
     readonly ids: readonly number[];
 };
-/** Settles bonded connected components one cell per deterministic bottom/ID priority step. */
+/** Settles bonded connected components one cell per deterministic bottom/ID priority step.
+ *
+ * @param initial - The row-major starting board for gravity settlement.
+ * @param bonds - Native stable-id bonds connecting surviving gems.
+ * @param width - The native board width in cells.
+ * @param height - The native board height in cells.
+ * @param mask - The row-major active-cell mask; false cells cannot hold gems.
+ * @returns Settles bonded connected components one cell per deterministic bottom/ID priority step. Nested null values denote empty board cells, absent active pieces, unselected tools or outcomes not yet reached; optional undefined fields are absent until applicable.
+ * @example
+ * ```ts
+ * import { calmGravity, createGame } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(calmGravity(state.board,state.bonds,state.settings.width,state.settings.height,state.settings.mask).length);
+ * ```
+ */
 export declare function calmGravity(initial: readonly (Gem | null)[], bonds: readonly Bond[], width: number, height: number, mask: readonly boolean[]): readonly (Gem | null)[];
-/** Magnetic floor removes all bonds and settles each column segment independently. */
+/** Magnetic floor removes all bonds and settles each column segment independently.
+ *
+ * @param initial - The row-major starting board for gravity settlement.
+ * @param width - The native board width in cells.
+ * @param height - The native board height in cells.
+ * @param mask - The row-major active-cell mask; false cells cannot hold gems.
+ * @returns Magnetic floor removes all bonds and settles each column segment independently. Nested null values denote empty board cells, absent active pieces, unselected tools or outcomes not yet reached; optional undefined fields are absent until applicable.
+ * @example
+ * ```ts
+ * import { createGame, magneticGravity } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(magneticGravity(state.board,state.settings.width,state.settings.height,state.settings.mask).length);
+ * ```
+ */
 export declare function magneticGravity(initial: readonly (Gem | null)[], width: number, height: number, mask: readonly boolean[]): readonly (Gem | null)[];
+/** Settle surviving gems with the chosen floor rule and retain valid stable-id bonds.
+ *
+ * @param initial - The row-major starting board for gravity settlement.
+ * @param bonds - Native stable-id bonds connecting surviving gems.
+ * @param floor - The native calm or magnetic floor rule to apply.
+ * @param width - The native board width in cells.
+ * @param height - The native board height in cells.
+ * @param mask - The row-major active-cell mask; false cells cannot hold gems.
+ * @returns Settle surviving gems with the chosen floor rule and retain valid stable-id bonds. Nested null values denote empty board cells, absent active pieces, unselected tools or outcomes not yet reached; optional undefined fields are absent until applicable.
+ * @example
+ * ```ts
+ * import { createGame, settle } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(settle(state.board,state.bonds,"calm",state.settings.width,state.settings.height,state.settings.mask).board.length);
+ * ```
+ */
 export declare function settle(initial: readonly (Gem | null)[], bonds: readonly Bond[], floor: Floor, width: number, height: number, mask: readonly boolean[]): {
     readonly board: readonly (Gem | null)[];
     readonly bonds: readonly Bond[];
 };
-/** Collects the occupied one-cell support layer under both block columns at first contact. */
+/** Collects the occupied one-cell support layer under both block columns at first contact.
+ *
+ * @param block - The native active 2×2 block and its stable gem ids.
+ * @param board - The row-major native board; null cells are empty or masked.
+ * @param width - The native board width in cells.
+ * @param height - The native board height in cells.
+ * @param mask - The row-major active-cell mask; false cells cannot hold gems.
+ * @returns Collects the occupied one-cell support layer under both block columns at first contact.
+ * @example
+ * ```ts
+ * import { createGame, impactSupportIds } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(impactSupportIds(state.active!,state.board,state.settings.width,state.settings.height,state.settings.mask).length);
+ * ```
+ */
 export declare function impactSupportIds(block: Block, board: readonly (Gem | null)[], width: number, height: number, mask: readonly boolean[]): readonly number[];
+/** List the native stable-id bonds connecting adjacent gems in the active block.
+ *
+ * @param block - The native active 2×2 block and its stable gem ids.
+ * @returns List the native stable-id bonds connecting adjacent gems in the active block.
+ * @example
+ * ```ts
+ * import { blockBonds, createGame } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(blockBonds(state.active!).length);
+ * ```
+ */
 export declare function blockBonds(block: Block): readonly Bond[];