@johnmorrisdotca/houseki 0.4.1 → 0.4.2

package/dist/nature/environment.d.ts

@@ -1,5 +1,25 @@
 import type { NatureEntity, NatureMove, NatureState } from './types.js';
+/** The native fault, jumble or combined earthquake mode.
+ *
+ * @example
+ * ```ts
+ * import type { EarthquakeKind } from "@johnmorrisdotca/houseki/nature";
+ *
+ * const value: EarthquakeKind = "fault";
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type EarthquakeKind = 'fault' | 'jumble' | 'combined';
+/** A periodic, one-turn or authored list of environment trigger turns.
+ *
+ * @example
+ * ```ts
+ * import type { EnvironmentSchedule } from "@johnmorrisdotca/houseki/nature";
+ *
+ * const value: EnvironmentSchedule = {kind:"authored",turns:[2,4]};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type EnvironmentSchedule = {
     readonly kind: 'frequent';
 } | {
@@ -11,15 +31,47 @@ export type EnvironmentSchedule = {
     readonly kind: 'authored';
     readonly turns: readonly number[];
 };
+/** The earthquake mode and optional enabled flag.
+ *
+ * @example
+ * ```ts
+ * import type { EarthquakeOptions } from "@johnmorrisdotca/houseki/nature";
+ *
+ * const value: EarthquakeOptions = {kind:"fault"};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface EarthquakeOptions {
     readonly kind: EarthquakeKind;
     readonly enabled?: boolean;
 }
+/** Lightning enablement and explicit columns or a bounded column count.
+ *
+ * @example
+ * ```ts
+ * import type { LightningOptions } from "@johnmorrisdotca/houseki/nature";
+ *
+ * const value: LightningOptions = {columns:[0]};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface LightningOptions {
     readonly enabled?: boolean;
     readonly columns?: readonly number[];
     readonly columnCount?: 1 | 2 | 3;
 }
+/** A pure earthquake fault path, removed ids and resulting occupants/passability mask.
+ *
+ * @example
+ * ```ts
+ * import { createNatureState, previewFault } from "@johnmorrisdotca/houseki/nature";
+ * import type { FaultPreview } from "@johnmorrisdotca/houseki/nature";
+ *
+ * const state=createNatureState({width:4,height:4,seed:"docs"});
+ * const value: FaultPreview = previewFault(state);
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface FaultPreview {
     readonly path: readonly number[];
     readonly fracturedCells: readonly number[];
@@ -28,6 +80,18 @@ export interface FaultPreview {
     readonly activeCells: readonly boolean[];
     readonly randomStateAfter: number;
 }
+/** A pure eligible-patch shuffle and resulting occupants; reason explains when no patch exists.
+ *
+ * @example
+ * ```ts
+ * import { createNatureState, previewJumble } from "@johnmorrisdotca/houseki/nature";
+ * import type { JumblePreview } from "@johnmorrisdotca/houseki/nature";
+ *
+ * const state=createNatureState({width:4,height:4,seed:"docs"});
+ * const value: JumblePreview = previewJumble(state);
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface JumblePreview {
     readonly patchCells: readonly number[];
     readonly moves: readonly NatureMove[];
@@ -44,6 +108,18 @@ export interface EarthquakePreview {
     readonly activeCells: readonly boolean[];
     readonly randomStateAfter: number;
 }
+/** A pure selected-column removal and resulting occupants/random state.
+ *
+ * @example
+ * ```ts
+ * import { createNatureState, previewLightning } from "@johnmorrisdotca/houseki/nature";
+ * import type { LightningPreview } from "@johnmorrisdotca/houseki/nature";
+ *
+ * const state=createNatureState({width:4,height:4,seed:"docs"});
+ * const value: LightningPreview = previewLightning(state,{columns:[0]});
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface LightningPreview {
     readonly columns: readonly number[];
     readonly removedCells: readonly number[];
@@ -51,7 +127,31 @@ export interface LightningPreview {
     readonly cells: readonly (NatureEntity | null)[];
     readonly randomStateAfter: number;
 }
+/** A native earthquake or lightning preview before it is committed.
+ *
+ * @example
+ * ```ts
+ * import { createNatureState, previewLightning } from "@johnmorrisdotca/houseki/nature";
+ * import type { EnvironmentPreview } from "@johnmorrisdotca/houseki/nature";
+ *
+ * const state=createNatureState({width:4,height:4,seed:"docs"});
+ * const value: EnvironmentPreview = previewLightning(state,{columns:[0]});
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type EnvironmentPreview = EarthquakePreview | LightningPreview;
+/** A committed earthquake or lightning event with its native preview fields.
+ *
+ * @example
+ * ```ts
+ * import { applyLightning, createNatureState } from "@johnmorrisdotca/houseki/nature";
+ * import type { EnvironmentEvent } from "@johnmorrisdotca/houseki/nature";
+ *
+ * const state=createNatureState({width:4,height:4,seed:"docs"});
+ * const value: EnvironmentEvent = applyLightning(state,{columns:[0]}).events[0];
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type EnvironmentEvent = {
     readonly type: 'fault-opened';
     readonly path: readonly number[];
@@ -69,23 +169,116 @@ export type EnvironmentEvent = {
     readonly removedCells: readonly number[];
     readonly removedIds: readonly number[];
 };
+/** The committed environment state, event list and pure preview.
+ *
+ * @example
+ * ```ts
+ * import { applyLightning, createNatureState } from "@johnmorrisdotca/houseki/nature";
+ * import type { EnvironmentTransition } from "@johnmorrisdotca/houseki/nature";
+ *
+ * const state=createNatureState({width:4,height:4,seed:"docs"});
+ * const value: EnvironmentTransition = applyLightning(state,{columns:[0]});
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface EnvironmentTransition {
     readonly state: NatureState;
     readonly accepted: true;
     readonly events: readonly EnvironmentEvent[];
     readonly preview: EnvironmentPreview;
 }
-/** Pure one-based schedule lookup: frequent is every second turn; rare is every eighth turn. */
+/** Pure one-based schedule lookup: frequent is every second turn; rare is every eighth turn.
+ *
+ * @param turn - The committed placement/turn number tested against the environment schedule.
+ * @param schedule - The native schedule with its authored or periodic trigger settings.
+ * @returns Pure one-based schedule lookup: frequent is every second turn; rare is every eighth turn.
+ * @example
+ * ```ts
+ * import { isEnvironmentTurnScheduled } from "@johnmorrisdotca/houseki/nature";
+ *
+ * console.log(isEnvironmentTurnScheduled(2,{kind:"authored",turns:[2,4]}));
+ * ```
+ */
 export declare function isEnvironmentTurnScheduled(turn: number, schedule: EnvironmentSchedule): boolean;
-/** Preview a bounded top-to-bottom fracture. The path keeps at least one column active on each side. */
+/** Preview a bounded top-to-bottom fracture. The path keeps at least one column active on each side.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Preview a bounded top-to-bottom fracture. The path keeps at least one column active on each side.
+ * @example
+ * ```ts
+ * import { createNatureState, previewFault } from "@johnmorrisdotca/houseki/nature";
+ *
+ * const state=createNatureState({width:4,height:4,seed:"docs"});
+ * console.log(previewFault(state).removedIds.length);
+ * ```
+ */
 export declare function previewFault(state: NatureState): FaultPreview;
-/** Preview one seeded, nontrivial stone permutation inside a fully active connected rectangle no larger than 3×3. */
+/** Preview one seeded, nontrivial stone permutation inside a fully active connected rectangle no larger than 3×3.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Preview one seeded, nontrivial stone permutation inside a fully active connected rectangle no larger than 3×3.
+ * @example
+ * ```ts
+ * import { createNatureState, previewJumble } from "@johnmorrisdotca/houseki/nature";
+ *
+ * const state=createNatureState({width:4,height:4,seed:"docs"});
+ * console.log(previewJumble(state).changed);
+ * ```
+ */
 export declare function previewJumble(state: NatureState): JumblePreview;
-/** Preview an earthquake, with Combined always fracturing before its one jumble attempt. */
+/** Preview an earthquake, with Combined always fracturing before its one jumble attempt.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @param options - Validated native creation, authored challenge, or environment options described by this signature.
+ * @returns Preview an earthquake, with Combined always fracturing before its one jumble attempt.
+ * @example
+ * ```ts
+ * import { createNatureState, previewEarthquake } from "@johnmorrisdotca/houseki/nature";
+ *
+ * const state=createNatureState({width:4,height:4,seed:"docs"});
+ * console.log(previewEarthquake(state,{kind:"fault"}).kind);
+ * ```
+ */
 export declare function previewEarthquake(state: NatureState, options: EarthquakeOptions): EarthquakePreview;
-/** Commit one bounded environmental resolution; matching, gravity and score remain the host game's job. */
+/** Commit one bounded environmental resolution; matching, gravity and score remain the host game's job.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @param options - Validated native creation, authored challenge, or environment options described by this signature.
+ * @returns Commit one bounded environmental resolution; matching, gravity and score remain the host game's job.
+ * @example
+ * ```ts
+ * import { applyEarthquake, createNatureState } from "@johnmorrisdotca/houseki/nature";
+ *
+ * const state=createNatureState({width:4,height:4,seed:"docs"});
+ * console.log(applyEarthquake(state,{kind:"fault"}).accepted);
+ * ```
+ */
 export declare function applyEarthquake(state: NatureState, options: EarthquakeOptions): EnvironmentTransition;
-/** Preview seeded or explicitly selected columns; a mask gap or obstacle blocks the strike below it. */
+/** Preview seeded or explicitly selected columns; a mask gap or obstacle blocks the strike below it.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @param options - Validated native creation, authored challenge, or environment options described by this signature.
+ * @returns Preview seeded or explicitly selected columns; a mask gap or obstacle blocks the strike below it.
+ * @example
+ * ```ts
+ * import { createNatureState, previewLightning } from "@johnmorrisdotca/houseki/nature";
+ *
+ * const state=createNatureState({width:4,height:4,seed:"docs"});
+ * console.log(previewLightning(state,{columns:[0]}).columns);
+ * ```
+ */
 export declare function previewLightning(state: NatureState, options?: LightningOptions): LightningPreview;
-/** Commit one lightning strike. It removes exposed stones only and consumes no scores or tools. */
+/** Commit one lightning strike. It removes exposed stones only and consumes no scores or tools.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @param options - Validated native creation, authored challenge, or environment options described by this signature.
+ * @returns Commit one lightning strike. It removes exposed stones only and consumes no scores or tools.
+ * @example
+ * ```ts
+ * import { applyLightning, createNatureState } from "@johnmorrisdotca/houseki/nature";
+ *
+ * const state=createNatureState({width:4,height:4,seed:"docs"});
+ * console.log(applyLightning(state,{columns:[0]}).accepted);
+ * ```
+ */
 export declare function applyLightning(state: NatureState, options?: LightningOptions): EnvironmentTransition;

package/dist/nature/environment.js

@@ -14,7 +14,18 @@ function drawBelow(state, bound) {
     const [next, value] = nextNatureUint32(state);
     return [next, value % bound];
 }
-/** Pure one-based schedule lookup: frequent is every second turn; rare is every eighth turn. */
+/** Pure one-based schedule lookup: frequent is every second turn; rare is every eighth turn.
+ *
+ * @param turn - The committed placement/turn number tested against the environment schedule.
+ * @param schedule - The native schedule with its authored or periodic trigger settings.
+ * @returns Pure one-based schedule lookup: frequent is every second turn; rare is every eighth turn.
+ * @example
+ * ```ts
+ * import { isEnvironmentTurnScheduled } from "@johnmorrisdotca/houseki/nature";
+ *
+ * console.log(isEnvironmentTurnScheduled(2,{kind:"authored",turns:[2,4]}));
+ * ```
+ */
 export function isEnvironmentTurnScheduled(turn, schedule) {
     if (!Number.isSafeInteger(turn) || turn < 1 || turn > 10_000_000 || !schedule || typeof schedule !== 'object' || Array.isArray(schedule))
         throw new NatureOptionsError('invalid-nature-options', 'Schedule turn and policy must be valid');
@@ -91,7 +102,18 @@ function faultPath(state) {
     }
     return [path, randomState];
 }
-/** Preview a bounded top-to-bottom fracture. The path keeps at least one column active on each side. */
+/** Preview a bounded top-to-bottom fracture. The path keeps at least one column active on each side.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Preview a bounded top-to-bottom fracture. The path keeps at least one column active on each side.
+ * @example
+ * ```ts
+ * import { createNatureState, previewFault } from "@johnmorrisdotca/houseki/nature";
+ *
+ * const state=createNatureState({width:4,height:4,seed:"docs"});
+ * console.log(previewFault(state).removedIds.length);
+ * ```
+ */
 export function previewFault(state) {
     validateState(state);
     const [path, randomStateAfter] = faultPath(state);
@@ -139,7 +161,18 @@ function candidatePatches(state) {
         }
     return patches;
 }
-/** Preview one seeded, nontrivial stone permutation inside a fully active connected rectangle no larger than 3×3. */
+/** Preview one seeded, nontrivial stone permutation inside a fully active connected rectangle no larger than 3×3.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Preview one seeded, nontrivial stone permutation inside a fully active connected rectangle no larger than 3×3.
+ * @example
+ * ```ts
+ * import { createNatureState, previewJumble } from "@johnmorrisdotca/houseki/nature";
+ *
+ * const state=createNatureState({width:4,height:4,seed:"docs"});
+ * console.log(previewJumble(state).changed);
+ * ```
+ */
 export function previewJumble(state) {
     validateState(state);
     const candidates = candidatePatches(state);
@@ -172,7 +205,19 @@ export function previewJumble(state) {
             cells[index] = null;
     return deepFreeze({ patchCells: patch.cells, moves, changed: moves.length > 0, cells, randomStateAfter: randomState });
 }
-/** Preview an earthquake, with Combined always fracturing before its one jumble attempt. */
+/** Preview an earthquake, with Combined always fracturing before its one jumble attempt.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @param options - Validated native creation, authored challenge, or environment options described by this signature.
+ * @returns Preview an earthquake, with Combined always fracturing before its one jumble attempt.
+ * @example
+ * ```ts
+ * import { createNatureState, previewEarthquake } from "@johnmorrisdotca/houseki/nature";
+ *
+ * const state=createNatureState({width:4,height:4,seed:"docs"});
+ * console.log(previewEarthquake(state,{kind:"fault"}).kind);
+ * ```
+ */
 export function previewEarthquake(state, options) {
     validateState(state);
     validateEarthquakeOptions(options);
@@ -194,7 +239,19 @@ export function previewEarthquake(state, options) {
     }
     return deepFreeze({ kind: options.kind, ...(fault ? { fault } : {}), ...(jumble ? { jumble } : {}), cells, activeCells, randomStateAfter });
 }
-/** Commit one bounded environmental resolution; matching, gravity and score remain the host game's job. */
+/** Commit one bounded environmental resolution; matching, gravity and score remain the host game's job.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @param options - Validated native creation, authored challenge, or environment options described by this signature.
+ * @returns Commit one bounded environmental resolution; matching, gravity and score remain the host game's job.
+ * @example
+ * ```ts
+ * import { applyEarthquake, createNatureState } from "@johnmorrisdotca/houseki/nature";
+ *
+ * const state=createNatureState({width:4,height:4,seed:"docs"});
+ * console.log(applyEarthquake(state,{kind:"fault"}).accepted);
+ * ```
+ */
 export function applyEarthquake(state, options) {
     const preview = previewEarthquake(state, options);
     if (options.enabled === false)
@@ -233,7 +290,19 @@ function chooseColumns(state, options) {
     }
     return [pool.slice(0, count).sort((a, b) => a - b), randomState];
 }
-/** Preview seeded or explicitly selected columns; a mask gap or obstacle blocks the strike below it. */
+/** Preview seeded or explicitly selected columns; a mask gap or obstacle blocks the strike below it.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @param options - Validated native creation, authored challenge, or environment options described by this signature.
+ * @returns Preview seeded or explicitly selected columns; a mask gap or obstacle blocks the strike below it.
+ * @example
+ * ```ts
+ * import { createNatureState, previewLightning } from "@johnmorrisdotca/houseki/nature";
+ *
+ * const state=createNatureState({width:4,height:4,seed:"docs"});
+ * console.log(previewLightning(state,{columns:[0]}).columns);
+ * ```
+ */
 export function previewLightning(state, options = {}) {
     validateState(state);
     validateLightningOptions(options, state.width);
@@ -258,7 +327,19 @@ export function previewLightning(state, options = {}) {
     }
     return deepFreeze({ columns, removedCells, removedIds, cells, randomStateAfter });
 }
-/** Commit one lightning strike. It removes exposed stones only and consumes no scores or tools. */
+/** Commit one lightning strike. It removes exposed stones only and consumes no scores or tools.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @param options - Validated native creation, authored challenge, or environment options described by this signature.
+ * @returns Commit one lightning strike. It removes exposed stones only and consumes no scores or tools.
+ * @example
+ * ```ts
+ * import { applyLightning, createNatureState } from "@johnmorrisdotca/houseki/nature";
+ *
+ * const state=createNatureState({width:4,height:4,seed:"docs"});
+ * console.log(applyLightning(state,{columns:[0]}).accepted);
+ * ```
+ */
 export function applyLightning(state, options = {}) {
     const preview = previewLightning(state, options);
     if (options.enabled === false)

package/dist/nature/marking.d.ts

@@ -1,3 +1,15 @@
 import type { MarkingOptions, NatureState, NatureTransition } from './types.js';
-/** Deterministically assign magnetic markings to settled stones without changing their IDs or colours. */
+/** Deterministically assign magnetic markings to settled stones without changing their IDs or colours.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @param options - Validated native creation, authored challenge, or environment options described by this signature.
+ * @returns Deterministically assign magnetic markings to settled stones without changing their IDs or colours.
+ * @example
+ * ```ts
+ * import { createNatureState, markMagneticStones } from "@johnmorrisdotca/houseki/nature";
+ *
+ * const state=createNatureState({width:4,height:4,seed:"docs"});
+ * console.log(markMagneticStones(state,{probability:0.25,maximum:2}).accepted);
+ * ```
+ */
 export declare function markMagneticStones(state: NatureState, options: MarkingOptions): NatureTransition;

package/dist/nature/marking.js

@@ -1,7 +1,19 @@
 import { validateMarkingOptions, validateState } from './validation.js';
 import { freezeNatureState } from './state.js';
 import { nextNatureUnit } from './random.js';
-/** Deterministically assign magnetic markings to settled stones without changing their IDs or colours. */
+/** Deterministically assign magnetic markings to settled stones without changing their IDs or colours.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @param options - Validated native creation, authored challenge, or environment options described by this signature.
+ * @returns Deterministically assign magnetic markings to settled stones without changing their IDs or colours.
+ * @example
+ * ```ts
+ * import { createNatureState, markMagneticStones } from "@johnmorrisdotca/houseki/nature";
+ *
+ * const state=createNatureState({width:4,height:4,seed:"docs"});
+ * console.log(markMagneticStones(state,{probability:0.25,maximum:2}).accepted);
+ * ```
+ */
 export function markMagneticStones(state, options) {
     validateState(state);
     validateMarkingOptions(options);

package/dist/nature/rebound.d.ts

@@ -1,5 +1,33 @@
 import type { NatureState, NatureTransition, PowerDropPreview, PowerDropRequest } from './types.js';
-/** Preview a single normal landing and, for a power drop, at most one validated one-cell rebound. */
+/** Preview a single normal landing and, for a power drop, at most one validated one-cell rebound.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @param request - The native falling piece, pivot id and power/rebound choice.
+ * @returns Preview a single normal landing and, for a power drop, at most one validated one-cell rebound.
+ * @example
+ * ```ts
+ * import { createNatureState, previewPowerDrop } from "@johnmorrisdotca/houseki/nature";
+ * import type { PowerDropRequest } from "@johnmorrisdotca/houseki/nature";
+ *
+ * const state=createNatureState({width:4,height:4,seed:"docs"});
+ * const request:PowerDropRequest={piece:[{id:1,kind:"stone",colour:"red",x:1,y:0}],pivotId:1,power:true};
+ * console.log(previewPowerDrop(state,request).finalCells.length);
+ * ```
+ */
 export declare function previewPowerDrop(state: NatureState, request: PowerDropRequest): PowerDropPreview;
-/** Commit a previewed landing as one immutable operation. A failed preview leaves the original state untouched. */
+/** Commit a previewed landing as one immutable operation. A failed preview leaves the original state untouched.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @param request - The native falling piece, pivot id and power/rebound choice.
+ * @returns Commit a previewed landing as one immutable operation. A failed preview leaves the original state untouched.
+ * @example
+ * ```ts
+ * import { applyPowerDrop, createNatureState } from "@johnmorrisdotca/houseki/nature";
+ * import type { PowerDropRequest } from "@johnmorrisdotca/houseki/nature";
+ *
+ * const state=createNatureState({width:4,height:4,seed:"docs"});
+ * const request:PowerDropRequest={piece:[{id:1,kind:"stone",colour:"red",x:1,y:0}],pivotId:1,power:true};
+ * console.log(applyPowerDrop(state,request).accepted);
+ * ```
+ */
 export declare function applyPowerDrop(state: NatureState, request: PowerDropRequest): NatureTransition;

package/dist/nature/rebound.js

@@ -44,7 +44,21 @@ function preferredDirection(state, request) {
         return [request.lastHorizontalDirection, state.randomState];
     return [state.committedPlacements % 2 === 0 ? 'left' : 'right', state.randomState];
 }
-/** Preview a single normal landing and, for a power drop, at most one validated one-cell rebound. */
+/** Preview a single normal landing and, for a power drop, at most one validated one-cell rebound.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @param request - The native falling piece, pivot id and power/rebound choice.
+ * @returns Preview a single normal landing and, for a power drop, at most one validated one-cell rebound.
+ * @example
+ * ```ts
+ * import { createNatureState, previewPowerDrop } from "@johnmorrisdotca/houseki/nature";
+ * import type { PowerDropRequest } from "@johnmorrisdotca/houseki/nature";
+ *
+ * const state=createNatureState({width:4,height:4,seed:"docs"});
+ * const request:PowerDropRequest={piece:[{id:1,kind:"stone",colour:"red",x:1,y:0}],pivotId:1,power:true};
+ * console.log(previewPowerDrop(state,request).finalCells.length);
+ * ```
+ */
 export function previewPowerDrop(state, request) {
     validateState(state);
     validatePowerDropRequest(state, request);
@@ -81,7 +95,21 @@ export function previewPowerDrop(state, request) {
     }
     return freeze({ normalLanding: normal, attempts, rebound: selectedDirection !== undefined, ...(selectedDirection ? { selectedDirection } : {}), quarterTurn: selectedTurn, finalCells, moves: movesBetween(request.piece, finalCells), randomStateAfter });
 }
-/** Commit a previewed landing as one immutable operation. A failed preview leaves the original state untouched. */
+/** Commit a previewed landing as one immutable operation. A failed preview leaves the original state untouched.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @param request - The native falling piece, pivot id and power/rebound choice.
+ * @returns Commit a previewed landing as one immutable operation. A failed preview leaves the original state untouched.
+ * @example
+ * ```ts
+ * import { applyPowerDrop, createNatureState } from "@johnmorrisdotca/houseki/nature";
+ * import type { PowerDropRequest } from "@johnmorrisdotca/houseki/nature";
+ *
+ * const state=createNatureState({width:4,height:4,seed:"docs"});
+ * const request:PowerDropRequest={piece:[{id:1,kind:"stone",colour:"red",x:1,y:0}],pivotId:1,power:true};
+ * console.log(applyPowerDrop(state,request).accepted);
+ * ```
+ */
 export function applyPowerDrop(state, request) {
     const preview = previewPowerDrop(state, request);
     const cells = [...state.cells];

package/dist/nature/state.d.ts

@@ -1,3 +1,14 @@
 import type { NatureOptions, NatureState } from './types.js';
 export declare function freezeNatureState(state: NatureState): NatureState;
+/** Create a validated seeded native environment grid with fixed masks and mechanic switches.
+ *
+ * @param options - Validated native creation, authored challenge, or environment options described by this signature.
+ * @returns Create a validated seeded native environment grid with fixed masks and mechanic switches.
+ * @example
+ * ```ts
+ * import { createNatureState } from "@johnmorrisdotca/houseki/nature";
+ *
+ * console.log(createNatureState({width:4,height:4,seed:"docs"}).width);
+ * ```
+ */
 export declare function createNatureState(options: NatureOptions): NatureState;

package/dist/nature/state.js

@@ -6,6 +6,17 @@ export function freezeNatureState(state) {
     const rules = Object.freeze({ ...state.rules });
     return Object.freeze({ ...state, cells, activeCells, rules });
 }
+/** Create a validated seeded native environment grid with fixed masks and mechanic switches.
+ *
+ * @param options - Validated native creation, authored challenge, or environment options described by this signature.
+ * @returns Create a validated seeded native environment grid with fixed masks and mechanic switches.
+ * @example
+ * ```ts
+ * import { createNatureState } from "@johnmorrisdotca/houseki/nature";
+ *
+ * console.log(createNatureState({width:4,height:4,seed:"docs"}).width);
+ * ```
+ */
 export function createNatureState(options) {
     validateNatureOptions(options);
     const cells = options.cells ?? Array(options.width * options.height).fill(null);