@johnmorrisdotca/houseki 0.4.0 → 0.4.2

package/dist/colour-chains/content.d.ts

@@ -1,19 +1,156 @@
 import type { ChainCampaignLevel, ChainCampaignManifest, ChainTutorialDefinition, NatureChainCampaignLevel, NatureChainCampaignManifest } from './content-types.js';
 import type { GameState } from './types.js';
+/** The frozen native campaign manifest with its ordering, revisions, checksum and measured levels.
+ *
+ * @example
+ * ```ts
+ * import { campaignManifest } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * console.log(campaignManifest.count);
+ * ```
+ */
 export declare const campaignManifest: ChainCampaignManifest;
+/** The frozen ordered native levels; array indices start at zero and display numbers start at one.
+ *
+ * @example
+ * ```ts
+ * import { levelManifest } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * console.log(levelManifest.length);
+ * ```
+ */
 export declare const levelManifest: readonly ChainCampaignLevel[];
+/** The frozen native bilingual lessons and their authored teaching steps.
+ *
+ * @example
+ * ```ts
+ * import { tutorialManifest } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * console.log(tutorialManifest.length);
+ * ```
+ */
 export declare const tutorialManifest: readonly ChainTutorialDefinition[];
+/** The ordered native campaign, its generation/grading revisions, checksum and measured levels.
+ *
+ * @example
+ * ```ts
+ * import { shizenCampaignManifest } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * console.log(shizenCampaignManifest.count);
+ * ```
+ */
 export declare const shizenCampaignManifest: NatureChainCampaignManifest;
+/** The frozen ordered native levels; array indices start at zero and display numbers start at one.
+ *
+ * @example
+ * ```ts
+ * import { shizenLevelManifest } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * console.log(shizenLevelManifest.length);
+ * ```
+ */
 export declare const shizenLevelManifest: readonly NatureChainCampaignLevel[];
+/** The ordered native campaign, its generation/grading revisions, checksum and measured levels.
+ *
+ * @example
+ * ```ts
+ * import { arashiCampaignManifest } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * console.log(arashiCampaignManifest.count);
+ * ```
+ */
 export declare const arashiCampaignManifest: NatureChainCampaignManifest;
+/** The frozen ordered native levels; array indices start at zero and display numbers start at one.
+ *
+ * @example
+ * ```ts
+ * import { arashiLevelManifest } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * console.log(arashiLevelManifest.length);
+ * ```
+ */
 export declare const arashiLevelManifest: readonly NatureChainCampaignLevel[];
-/** Find a campaign challenge by stable content ID or its current one-based number. */
+/** Find a campaign challenge by stable content ID or its current one-based number.
+ *
+ * @param id - A stable content id, or the one-based display number when numbers are accepted.
+ * @returns Find a campaign challenge by stable content ID or its current one-based number. Returns undefined when the id or display number is absent.
+ * @example
+ * ```ts
+ * import { getLevel } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * console.log(getLevel(1)?.id);
+ * ```
+ */
 export declare function getLevel(id: string | number): ChainCampaignLevel | undefined;
-/** Create a fresh engine-validated challenge from a stable content ID or display number. */
+/** Create a fresh engine-validated challenge from a stable content ID or display number.
+ *
+ * @param id - A stable content id, or the one-based display number when numbers are accepted.
+ * @returns Create a fresh engine-validated challenge from a stable content ID or display number.
+ * @example
+ * ```ts
+ * import { createLevel } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * console.log(createLevel(1).phase);
+ * ```
+ */
 export declare function createLevel(id: string | number): GameState;
+/** Find a native Shizen challenge 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 Find a native Shizen challenge by stable id or one-based display number. Returns undefined when the id or display number is absent.
+ * @example
+ * ```ts
+ * import { getShizenLevel } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * console.log(getShizenLevel(1)?.id);
+ * ```
+ */
 export declare function getShizenLevel(id: string | number): NatureChainCampaignLevel | undefined;
+/** Create a validated native Shizen challenge using its stored setup and winning witness.
+ *
+ * @param id - A stable content id, or the one-based display number when numbers are accepted.
+ * @returns Create a validated native Shizen challenge using its stored setup and winning witness.
+ * @example
+ * ```ts
+ * import { createShizenLevel } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * console.log(createShizenLevel(1).phase);
+ * ```
+ */
 export declare function createShizenLevel(id: string | number): GameState;
+/** Find a native Arashi challenge 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 Find a native Arashi challenge by stable id or one-based display number. Returns undefined when the id or display number is absent.
+ * @example
+ * ```ts
+ * import { getArashiLevel } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * console.log(getArashiLevel(1)?.id);
+ * ```
+ */
 export declare function getArashiLevel(id: string | number): NatureChainCampaignLevel | undefined;
+/** Create a validated native Arashi challenge using its stored setup and winning witness.
+ *
+ * @param id - A stable content id, or the one-based display number when numbers are accepted.
+ * @returns Create a validated native Arashi challenge using its stored setup and winning witness.
+ * @example
+ * ```ts
+ * import { createArashiLevel } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * console.log(createArashiLevel(1).phase);
+ * ```
+ */
 export declare function createArashiLevel(id: string | number): GameState;
-/** Find a persistent interactive lesson by its stable ID. */
+/** Find a persistent interactive lesson by its stable ID.
+ *
+ * @param id - A stable content id, or the one-based display number when numbers are accepted.
+ * @returns Find a persistent interactive lesson by its stable ID. Returns undefined when the id or display number is absent.
+ * @example
+ * ```ts
+ * import { getTutorial, tutorialManifest } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * console.log(getTutorial(tutorialManifest[0].id)?.id);
+ * ```
+ */
 export declare function getTutorial(id: string): ChainTutorialDefinition | undefined;

package/dist/colour-chains/content.js

@@ -8,20 +8,103 @@ 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/colour-chains";
+ *
+ * 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/colour-chains";
+ *
+ * console.log(levelManifest.length);
+ * ```
+ */
 export const levelManifest = campaignManifest.levels;
+/** The frozen native bilingual lessons and their authored teaching steps.
+ *
+ * @example
+ * ```ts
+ * import { tutorialManifest } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * console.log(tutorialManifest.length);
+ * ```
+ */
 export const tutorialManifest = deepFreeze(contentData.tutorials);
+/** The ordered native campaign, its generation/grading revisions, checksum and measured levels.
+ *
+ * @example
+ * ```ts
+ * import { shizenCampaignManifest } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * console.log(shizenCampaignManifest.count);
+ * ```
+ */
 export const shizenCampaignManifest = deepFreeze((contentData.shizen ?? { ...contentData.campaign, count: 0, levels: [], checksum: '' }));
+/** The frozen ordered native levels; array indices start at zero and display numbers start at one.
+ *
+ * @example
+ * ```ts
+ * import { shizenLevelManifest } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * console.log(shizenLevelManifest.length);
+ * ```
+ */
 export const shizenLevelManifest = shizenCampaignManifest.levels;
+/** The ordered native campaign, its generation/grading revisions, checksum and measured levels.
+ *
+ * @example
+ * ```ts
+ * import { arashiCampaignManifest } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * console.log(arashiCampaignManifest.count);
+ * ```
+ */
 export const arashiCampaignManifest = deepFreeze((contentData.arashi ?? { ...contentData.campaign, count: 0, levels: [], checksum: '' }));
+/** The frozen ordered native levels; array indices start at zero and display numbers start at one.
+ *
+ * @example
+ * ```ts
+ * import { arashiLevelManifest } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * console.log(arashiLevelManifest.length);
+ * ```
+ */
 export const arashiLevelManifest = arashiCampaignManifest.levels;
-/** Find a campaign challenge by stable content ID or its current one-based number. */
+/** Find a campaign challenge by stable content ID or its current one-based number.
+ *
+ * @param id - A stable content id, or the one-based display number when numbers are accepted.
+ * @returns Find a campaign challenge by stable content ID or its current one-based number. Returns undefined when the id or display number is absent.
+ * @example
+ * ```ts
+ * import { getLevel } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * 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);
 }
-/** Create a fresh engine-validated challenge from a stable content ID or display number. */
+/** Create a fresh engine-validated challenge from a stable content ID or display number.
+ *
+ * @param id - A stable content id, or the one-based display number when numbers are accepted.
+ * @returns Create a fresh engine-validated challenge from a stable content ID or display number.
+ * @example
+ * ```ts
+ * import { createLevel } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * console.log(createLevel(1).phase);
+ * ```
+ */
 export function createLevel(id) {
     const level = getLevel(id);
     if (!level)
@@ -31,11 +114,65 @@ export function createLevel(id) {
 function createNatureLevel(level) {
     return createChallenge({ id: level.id, seed: level.seed, width: level.width, height: level.height, colourCount: level.colourCount, board: level.board, queue: level.queue, goal: level.goal, witness: level.witness, nature: true, ...(level.weather ? { weather: level.weather } : {}), ...(level.magneticQueue ? { magneticQueue: level.magneticQueue } : {}) });
 }
+/** Find a native Shizen challenge 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 Find a native Shizen challenge by stable id or one-based display number. Returns undefined when the id or display number is absent.
+ * @example
+ * ```ts
+ * import { getShizenLevel } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * console.log(getShizenLevel(1)?.id);
+ * ```
+ */
 export function getShizenLevel(id) { return typeof id === 'number' ? shizenLevelManifest.find(level => level.number === id) : shizenLevelManifest.find(level => level.id === id); }
+/** Create a validated native Shizen challenge using its stored setup and winning witness.
+ *
+ * @param id - A stable content id, or the one-based display number when numbers are accepted.
+ * @returns Create a validated native Shizen challenge using its stored setup and winning witness.
+ * @example
+ * ```ts
+ * import { createShizenLevel } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * console.log(createShizenLevel(1).phase);
+ * ```
+ */
 export function createShizenLevel(id) { const level = getShizenLevel(id); if (!level)
     throw new RangeError(`Unknown Shizen Colour Chains level: ${String(id)}`); return createNatureLevel(level); }
+/** Find a native Arashi challenge 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 Find a native Arashi challenge by stable id or one-based display number. Returns undefined when the id or display number is absent.
+ * @example
+ * ```ts
+ * import { getArashiLevel } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * console.log(getArashiLevel(1)?.id);
+ * ```
+ */
 export function getArashiLevel(id) { return typeof id === 'number' ? arashiLevelManifest.find(level => level.number === id) : arashiLevelManifest.find(level => level.id === id); }
+/** Create a validated native Arashi challenge using its stored setup and winning witness.
+ *
+ * @param id - A stable content id, or the one-based display number when numbers are accepted.
+ * @returns Create a validated native Arashi challenge using its stored setup and winning witness.
+ * @example
+ * ```ts
+ * import { createArashiLevel } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * console.log(createArashiLevel(1).phase);
+ * ```
+ */
 export function createArashiLevel(id) { const level = getArashiLevel(id); if (!level)
     throw new RangeError(`Unknown Arashi Colour Chains level: ${String(id)}`); return createNatureLevel(level); }
-/** Find a persistent interactive lesson by its stable ID. */
+/** Find a persistent interactive lesson by its stable ID.
+ *
+ * @param id - A stable content id, or the one-based display number when numbers are accepted.
+ * @returns Find a persistent interactive lesson by its stable ID. Returns undefined when the id or display number is absent.
+ * @example
+ * ```ts
+ * import { getTutorial, tutorialManifest } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * console.log(getTutorial(tutorialManifest[0].id)?.id);
+ * ```
+ */
 export function getTutorial(id) { return tutorialManifest.find(tutorial => tutorial.id === id); }

package/dist/colour-chains/engine.d.ts

@@ -1,12 +1,60 @@
 import type { Action, ChainsPowerDropPreview, Colour, CreateOptions, GameState, GameStatus, Gem, Landing, Settings, Transition } from './types.js';
 export { StoneChainsOptionsError } from './validation.js';
-/** Applies one immutable accepted action and records its logical-tick position. */
+/** Applies one immutable accepted action and records its logical-tick position.
+ *
+ * @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 immutable accepted action and records its logical-tick position.
+ * @example
+ * ```ts
+ * import { applyAction, createGame } from "@johnmorrisdotca/houseki/colour-chains";
+ * import type { Action } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * 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 deterministic 60 Hz simulation and resolution; Relaxed and Challenges do not force a falling clock. */
+/** Advances deterministic 60 Hz simulation and resolution; Relaxed and Challenges do not force a falling clock.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @param ticks - The nonnegative number of fixed 60 Hz logical ticks to advance.
+ * @returns Advances deterministic 60 Hz simulation and resolution; Relaxed and Challenges do not force a falling clock.
+ * @example
+ * ```ts
+ * import { advanceTicks, createGame } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(advanceTicks(state,1).state.phase);
+ * ```
+ */
 export declare function advanceTicks(state: GameState, ticks: number): Transition;
-/** Lists only actions accepted by the current game state. */
+/** Lists only actions accepted by the current game state.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Lists only actions accepted by the current game state.
+ * @example
+ * ```ts
+ * import { createGame, legalActions } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(legalActions(state).length);
+ * ```
+ */
 export declare function legalActions(state: GameState): readonly Action[];
-/** Returns the exact independent landing cells for the current rigid pair without consuming random values. */
+/** Returns the exact independent landing cells for the current rigid pair without consuming random values.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Returns the exact independent landing cells for the current rigid pair without consuming random values. Returns null when there is no active piece or applicable preview.
+ * @example
+ * ```ts
+ * import { createGame, landingCells } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(landingCells(state));
+ * ```
+ */
 export declare function landingCells(state: GameState): Landing | null;
 /**
  * Returns the Shizen hard-drop landing and one-step rebound preview without changing state.
@@ -15,11 +63,42 @@ export declare function landingCells(state: GameState): Landing | null;
  * gap then fall, so `settledCells` is where each stone of the pair comes to rest in the board the hard drop commits,
  * before any clear: draw a ghost from it. Both carry the pair's stable stone ids, and both are checked against
  * `applyAction` with a `hard-drop` over many played boards.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Returns the Shizen hard-drop landing and one-step rebound preview without changing state. Returns null when there is no active piece or applicable preview.
+ * @example
+ * ```ts
+ * import { createGame, powerDropPreview } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(powerDropPreview(state));
+ * ```
  */
 export declare function powerDropPreview(state: GameState): ChainsPowerDropPreview | null;
-/** Returns score, mode, chain and completion fields derived from state. */
+/** Returns score, mode, chain and completion fields derived from state.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Returns score, mode, chain and completion fields derived from state.
+ * @example
+ * ```ts
+ * import { createGame, statusOf } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(statusOf(state).phase);
+ * ```
+ */
 export declare function statusOf(state: GameState): GameStatus;
 /** Creates a base challenge state with a previously validated visible board and pair queue. @internal */
 export declare function initialChallengeState(settings: Settings, visibleBoard: readonly (Gem | null)[], queue: readonly (readonly [Colour, Colour])[]): GameState;
-/** Creates a deterministic seeded game with one active pair and three previews. */
+/** Creates a deterministic seeded game with one active pair and three previews.
+ *
+ * @param options - Validated native creation, authored challenge, or environment options described by this signature.
+ * @returns Creates a deterministic seeded game with one active pair and three previews.
+ * @example
+ * ```ts
+ * import { createGame } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * console.log(createGame({seed:"docs"}).phase);
+ * ```
+ */
 export declare function createGame(options?: CreateOptions): GameState;

package/dist/colour-chains/engine.js

@@ -315,7 +315,21 @@ function applyCore(state, action) {
         }
     }
 }
-/** Applies one immutable accepted action and records its logical-tick position. */
+/** Applies one immutable accepted action and records its logical-tick position.
+ *
+ * @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 immutable accepted action and records its logical-tick position.
+ * @example
+ * ```ts
+ * import { applyAction, createGame } from "@johnmorrisdotca/houseki/colour-chains";
+ * import type { Action } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const state=createGame({seed:"docs"});
+ * const action: Action={kind:"left"};
+ * console.log(applyAction(state,action).accepted);
+ * ```
+ */
 export function applyAction(state, action) {
     const result = applyCore(state, action);
     if (!result.accepted)
@@ -376,7 +390,19 @@ function advanceResolution(state) {
 function lockGrounded(state) {
     return lock(state, rigidLanding(state, state.active));
 }
-/** Advances deterministic 60 Hz simulation and resolution; Relaxed and Challenges do not force a falling clock. */
+/** Advances deterministic 60 Hz simulation and resolution; Relaxed and Challenges do not force a falling clock.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @param ticks - The nonnegative number of fixed 60 Hz logical ticks to advance.
+ * @returns Advances deterministic 60 Hz simulation and resolution; Relaxed and Challenges do not force a falling clock.
+ * @example
+ * ```ts
+ * import { advanceTicks, createGame } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * 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');
@@ -420,7 +446,18 @@ export function advanceTicks(state, ticks) {
     }
     return { state: current, events, accepted: true };
 }
-/** Lists only actions accepted by the current game state. */
+/** Lists only actions accepted by the current game state.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Lists only actions accepted by the current game state.
+ * @example
+ * ```ts
+ * import { createGame, legalActions } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(legalActions(state).length);
+ * ```
+ */
 export function legalActions(state) {
     if (state.phase === 'paused')
         return [{ kind: 'resume' }];
@@ -446,7 +483,18 @@ export function legalActions(state) {
     actions.push({ kind: 'pause' });
     return actions;
 }
-/** Returns the exact independent landing cells for the current rigid pair without consuming random values. */
+/** Returns the exact independent landing cells for the current rigid pair without consuming random values.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Returns the exact independent landing cells for the current rigid pair without consuming random values. Returns null when there is no active piece or applicable preview.
+ * @example
+ * ```ts
+ * import { createGame, landingCells } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(landingCells(state));
+ * ```
+ */
 export function landingCells(state) {
     if (!state.active)
         return null;
@@ -464,6 +512,16 @@ export function landingCells(state) {
  * gap then fall, so `settledCells` is where each stone of the pair comes to rest in the board the hard drop commits,
  * before any clear: draw a ghost from it. Both carry the pair's stable stone ids, and both are checked against
  * `applyAction` with a `hard-drop` over many played boards.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Returns the Shizen hard-drop landing and one-step rebound preview without changing state. Returns null when there is no active piece or applicable preview.
+ * @example
+ * ```ts
+ * import { createGame, powerDropPreview } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(powerDropPreview(state));
+ * ```
  */
 export function powerDropPreview(state) {
     if (!state.settings.nature || state.settings.mode === 'relaxed' || !state.active)
@@ -478,7 +536,18 @@ export function powerDropPreview(state) {
         : preview.finalCells;
     return Object.freeze({ ...preview, settledCells: Object.freeze(settledCells) });
 }
-/** Returns score, mode, chain and completion fields derived from state. */
+/** Returns score, mode, chain and completion fields derived from state.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Returns score, mode, chain and completion fields derived from state.
+ * @example
+ * ```ts
+ * import { createGame, statusOf } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * 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, maxChain: state.maxChain, allClears: state.allClears, completedPairs: state.completedPairs, assisted: state.assisted, ...(state.reason ? { reason: state.reason } : {}) }; }
 /** Creates a base challenge state with a previously validated visible board and pair queue. @internal */
 export function initialChallengeState(settings, visibleBoard, queue) {
@@ -491,7 +560,17 @@ export function initialChallengeState(settings, visibleBoard, queue) {
     const nextMagnetic = settings.nature ? queue.slice(1, 4).map((_, index) => settings.magneticQueue?.[index + 1] ?? [false, false]) : undefined;
     return { ...base, active, ...(nextMagnetic ? { nextMagnetic: Object.freeze(nextMagnetic) } : {}), nextId: maxId + 3 };
 }
-/** Creates a deterministic seeded game with one active pair and three previews. */
+/** Creates a deterministic seeded game with one active pair and three previews.
+ *
+ * @param options - Validated native creation, authored challenge, or environment options described by this signature.
+ * @returns Creates a deterministic seeded game with one active pair and three previews.
+ * @example
+ * ```ts
+ * import { createGame } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * console.log(createGame({seed:"docs"}).phase);
+ * ```
+ */
 export function createGame(options = {}) {
     const valid = normalizeOptions(options);
     let state = { game: 'colour-chains', rules: RULES, settings: valid, board: Array(valid.width * (valid.height + HIDDEN)).fill(null), phase: 'falling', active: null, next: [], bag: [], randomState: seedState(`colour-chains|${RULES}|${valid.seed}`), nextId: 1, score: 0, maxChain: 0, allClears: 0, completedPairs: 0, resolutionTick: 0, waves: [], clearCells: [], gravityBoard: null, resolutionHadClear: false, elapsedTicks: 0, assisted: false, witnessIndex: -1, recording: [], ...(valid.weather ? { weatherResolvedPairs: 0 } : {}) };