@johnmorrisdotca/houseki 0.4.0 → 0.4.2

package/dist/magnetic-blocks/physics.js

@@ -1,8 +1,45 @@
 export const HIDDEN_ROWS = 0;
-export 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 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 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 const GRAVITY_TICKS = 9;
 export const cell = (x, y, width) => y * width + x;
 const BASE = [[0, 0], [1, 0], [1, 1], [0, 1]];
-/** 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 function blockCells(block, width) {
     return block.gems.map((gem, corner) => {
         let [x, y] = BASE[corner];
@@ -11,18 +48,64 @@ export function blockCells(block, width) {
         return { index: cell(block.x + x, block.y + y, width), 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 function canPlace(block, board, width, height, mask) {
     if (block.x < 0 || block.x + 1 >= width || block.y < 0 || block.y + 1 >= height)
         return false;
     return blockCells(block, width).every(({ index }) => { const x = index % width, y = Math.floor(index / width); return x >= 0 && x < width && y >= 0 && y < height && mask[index] && !board[index]; });
 }
+/** 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 function landingY(block, board, width, height, mask) {
     let y = block.y;
     while (canPlace({ ...block, y: y + 1 }, board, width, height, mask))
         y++;
     return y;
 }
-/** 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 function matchGroups(board, width, height, mask) {
     const seen = new Set(), matches = [];
     for (let start = 0; start < board.length; start++) {
@@ -46,6 +129,20 @@ export function matchGroups(board, width, height, mask) {
     return matches;
 }
 export function allMatchedCells(groups) { return [...new Set(groups.flat())].sort((a, b) => a - b); }
+/** 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 function removeIds(board, bonds, indices) {
     const removed = new Set(indices), ids = indices.flatMap(index => board[index] ? [board[index].id] : []), remaining = board.map((gem, index) => removed.has(index) ? null : gem), alive = new Set(remaining.flatMap(gem => gem ? [gem.id] : []));
     return { board: Object.freeze(remaining), bonds: Object.freeze(bonds.filter(edge => alive.has(edge.a) && alive.has(edge.b))), ids: Object.freeze(ids) };
@@ -81,7 +178,22 @@ function connectedComponents(board, bonds) {
     }
     return groups;
 }
-/** 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 function calmGravity(initial, bonds, width, height, mask) {
     let board = [...initial], moved = true, guard = width * height * height;
     while (moved && guard-- > 0) {
@@ -106,7 +218,21 @@ export function calmGravity(initial, bonds, width, height, mask) {
         throw new RangeError('Calm gravity did not converge within its board-derived step bound');
     return Object.freeze(board);
 }
-/** 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 function magneticGravity(initial, width, height, mask) {
     const board = [...initial];
     for (let x = 0; x < width; x++) {
@@ -131,10 +257,42 @@ export function magneticGravity(initial, width, height, mask) {
     }
     return Object.freeze(board);
 }
+/** 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 function settle(initial, bonds, floor, width, height, mask) {
     return floor === 'magnetic' ? { board: magneticGravity(initial, width, height, mask), bonds: Object.freeze([]) } : { board: calmGravity(initial, bonds, width, height, mask), bonds };
 }
-/** 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 function impactSupportIds(block, board, width, height, mask) {
     const byColumn = new Map();
     for (const { index } of blockCells(block, width)) {
@@ -152,4 +310,16 @@ export function impactSupportIds(block, board, width, height, mask) {
     }
     return Object.freeze([...ids].sort((a, b) => a - b));
 }
+/** 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 function blockBonds(block) { return Object.freeze([[0, 1], [1, 2], [2, 3], [3, 0]].map(([a, b]) => { const ids = [block.gems[a].id, block.gems[b].id].sort((x, y) => x - y); return Object.freeze({ a: ids[0], b: ids[1] }); }).sort((a, b) => a.a - b.a || a.b - b.b)); }

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

@@ -1,6 +1,35 @@
-/** A standard gem colour used by a magnetic block. */
+/** A standard gem colour used by a magnetic block.
+ *
+ * @example
+ * ```ts
+ * import type { Colour } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const value: Colour = "red";
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type Colour = 'red' | 'blue' | 'green' | 'gold' | 'purple' | 'teal';
+/** The native calm or magnetic floor used when settling blocks.
+ *
+ * @example
+ * ```ts
+ * import type { Floor } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const value: Floor = "calm";
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type Floor = 'calm' | 'magnetic';
+/** A fixed, periodic or authored schedule selecting the floor for committed block placements.
+ *
+ * @example
+ * ```ts
+ * import type { FloorSchedule } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const value: FloorSchedule = {kind:"fixed",floor:"calm"};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type FloorSchedule = {
     readonly kind: 'frequent';
 } | {
@@ -18,16 +47,70 @@ export type FloorSchedule = {
     readonly magneticPlacements: readonly number[];
     readonly defaultFloor?: Floor;
 };
+/** The native game mode; authored challenges have fixed setup and queue rules.
+ *
+ * @example
+ * ```ts
+ * import type { Mode } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const value: Mode = "relaxed";
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type Mode = 'relaxed' | 'arcade';
+/** The native falling, resolution, pause and ending phases.
+ *
+ * @example
+ * ```ts
+ * import { createGame } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ * import type { Phase } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const state=createGame({seed:"docs"});
+ * const value: Phase = state.phase;
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type Phase = 'falling' | 'clear-mark' | 'clear-remove' | 'gravity' | 'paused' | 'won' | 'lost' | 'finished';
+/** A native gem with a stable run-local id and colour.
+ *
+ * @example
+ * ```ts
+ * import type { Gem } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const value: Gem = {id:1,colour:"red"};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface Gem {
     readonly id: number;
     readonly colour: Colour;
 }
+/** An undirected stable-id connection between two gems in a magnetic block.
+ *
+ * @example
+ * ```ts
+ * import type { Bond } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const value: Bond = {a:1,b:2};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface Bond {
     readonly a: number;
     readonly b: number;
 }
+/** The native active 2×2 block, orientation and fixed-tick descent/lock counters.
+ *
+ * @example
+ * ```ts
+ * import { createGame } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ * import type { Block } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const state=createGame({seed:"docs"});
+ * const value: Block = state.active!;
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface Block {
     readonly x: number;
     readonly y: number;
@@ -38,12 +121,32 @@ export interface Block {
     readonly lockResets: number;
     readonly lockStarted: boolean;
 }
+/** The native authored goal; its discriminant selects the required collection or clearing condition.
+ *
+ * @example
+ * ```ts
+ * import type { Goal } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const value: Goal = {kind:"clear-all"};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type Goal = {
     readonly kind: 'clear-all';
 } | {
     readonly kind: 'clear-targets';
     readonly targetIds: readonly number[];
 };
+/** Creation settings for this native engine; dimensions, mode, seed and optional mechanics are validated together.
+ *
+ * @example
+ * ```ts
+ * import type { CreateOptions } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * 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?: Mode;
     readonly width?: number;
@@ -60,6 +163,18 @@ export interface CreateOptions {
     readonly magneticImpact?: boolean;
     readonly goal?: Goal;
 }
+/** Validated settings fixed at native game creation.
+ *
+ * @example
+ * ```ts
+ * import { createGame } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ * import type { Settings } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * 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: Mode;
     readonly width: number;
@@ -76,6 +191,18 @@ export interface Settings {
     readonly initialQueue?: readonly (readonly [Colour, Colour, Colour, Colour])[];
     readonly goal?: Goal;
 }
+/** The immutable authoritative native game state, including its board, random state and recording.
+ *
+ * @example
+ * ```ts
+ * import { createGame } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ * import type { GameState } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * 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: 'magnetic-blocks';
     readonly rules: 'magnetic-blocks-1';
@@ -105,6 +232,17 @@ export interface GameState {
     readonly recording: readonly RecordedAction[];
     readonly reason?: string;
 }
+/** A native player action accepted or rejected according to the current phase and rules.
+ *
+ * @example
+ * ```ts
+ * import type { Action } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const action: Action={kind:"left"};
+ * const value: Action = action;
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type Action = {
     readonly kind: 'left';
 } | {
@@ -129,21 +267,67 @@ export type Action = {
 } | {
     readonly kind: 'cancel-floor-override';
 };
+/** A native action recording with the logical position needed for deterministic replay.
+ *
+ * @example
+ * ```ts
+ * import type { Action, RecordedAction } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const action: Action={kind:"left"};
+ * const value: RecordedAction = {tick:0,ordinal:0,action};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface RecordedAction {
     readonly tick: number;
     readonly ordinal: number;
     readonly action: Action;
 }
+/** An event emitted by one native transition; type selects the event’s additional fields.
+ *
+ * @example
+ * ```ts
+ * import type { GameEvent } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * 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/magnetic-blocks";
+ * import type { Action, Transition } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const state=createGame({seed:"docs"});
+ * const action: Action={kind:"left"};
+ * 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;
 }
+/** A compact native status derived from the authoritative state for a host’s labels.
+ *
+ * @example
+ * ```ts
+ * import { createGame, statusOf } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ * import type { GameStatus } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * 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 phase: Phase;
     readonly score: number;

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

@@ -1,4 +1,16 @@
 import type { Bond, Colour, CreateOptions, FloorSchedule, Gem, Goal, Mode } from './types.js';
+/** A typed native magnetic-block setup validation error.
+ *
+ * @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 { MagneticBlocksOptionsError } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const error=new MagneticBlocksOptionsError("docs-example","Invalid example setup");
+ * console.log(error.name,error.code,error.message);
+ * ```
+ */
 export declare class MagneticBlocksOptionsError extends RangeError {
     readonly code: string;
     constructor(code: string, message: string);

package/dist/magnetic-blocks/validation.js

@@ -1,4 +1,16 @@
 import { calmGravity } from './physics.js';
+/** A typed native magnetic-block setup validation error.
+ *
+ * @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 { MagneticBlocksOptionsError } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const error=new MagneticBlocksOptionsError("docs-example","Invalid example setup");
+ * console.log(error.name,error.code,error.message);
+ * ```
+ */
 export class MagneticBlocksOptionsError extends RangeError {
     code;
     constructor(code, message) { super(message); this.name = 'MagneticBlocksOptionsError'; this.code = code; }

package/dist/nature/attraction.d.ts

@@ -1,5 +1,27 @@
 import type { MagneticPreview, NatureState, NatureTransition } from './types.js';
-/** Preview one bounded deterministic attraction pulse without mutating the state. */
+/** Preview one bounded deterministic attraction pulse without mutating the state.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Preview one bounded deterministic attraction pulse without mutating the state.
+ * @example
+ * ```ts
+ * import { createNatureState, previewMagneticPulse } from "@johnmorrisdotca/houseki/nature";
+ *
+ * const state=createNatureState({width:4,height:4,seed:"docs"});
+ * console.log(previewMagneticPulse(state).moves.length);
+ * ```
+ */
 export declare function previewMagneticPulse(state: NatureState): MagneticPreview;
-/** Apply one attraction pulse. Disabled nature rules preserve the exact state reference and consume no random state. */
+/** Apply one attraction pulse. Disabled nature rules preserve the exact state reference and consume no random state.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Apply one attraction pulse. Disabled nature rules preserve the exact state reference and consume no random state.
+ * @example
+ * ```ts
+ * import { applyMagneticPulse, createNatureState } from "@johnmorrisdotca/houseki/nature";
+ *
+ * const state=createNatureState({width:4,height:4,seed:"docs"});
+ * console.log(applyMagneticPulse(state).accepted);
+ * ```
+ */
 export declare function applyMagneticPulse(state: NatureState): NatureTransition;

package/dist/nature/attraction.js

@@ -116,7 +116,18 @@ function movePair(board, state, pair) {
     const a = coordinates(aIndex, state.width), b = coordinates(bIndex, state.width);
     return deepFreeze({ ids, axis: pair.axis, emptyGap: pair.gap, midpoint: { x: (a.x + b.x) / 2, y: (a.y + b.y) / 2 }, ...(pair.a.anchored || pair.b.anchored ? { anchoredId: pair.a.anchored ? pair.a.id : pair.b.id } : {}), moves: localMoves });
 }
-/** Preview one bounded deterministic attraction pulse without mutating the state. */
+/** Preview one bounded deterministic attraction pulse without mutating the state.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Preview one bounded deterministic attraction pulse without mutating the state.
+ * @example
+ * ```ts
+ * import { createNatureState, previewMagneticPulse } from "@johnmorrisdotca/houseki/nature";
+ *
+ * const state=createNatureState({width:4,height:4,seed:"docs"});
+ * console.log(previewMagneticPulse(state).moves.length);
+ * ```
+ */
 export function previewMagneticPulse(state) {
     validateState(state);
     if (!state.rules.magneticEnabled)
@@ -126,7 +137,18 @@ export function previewMagneticPulse(state) {
     const moves = pairs.flatMap(pair => pair.moves);
     return deepFreeze({ pairs, moves, cells: board });
 }
-/** Apply one attraction pulse. Disabled nature rules preserve the exact state reference and consume no random state. */
+/** Apply one attraction pulse. Disabled nature rules preserve the exact state reference and consume no random state.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Apply one attraction pulse. Disabled nature rules preserve the exact state reference and consume no random state.
+ * @example
+ * ```ts
+ * import { applyMagneticPulse, createNatureState } from "@johnmorrisdotca/houseki/nature";
+ *
+ * const state=createNatureState({width:4,height:4,seed:"docs"});
+ * console.log(applyMagneticPulse(state).accepted);
+ * ```
+ */
 export function applyMagneticPulse(state) {
     const preview = previewMagneticPulse(state);
     if (!state.rules.magneticEnabled || preview.moves.length === 0)