@johnmorrisdotca/houseki 0.4.1 → 0.4.2

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 } : {}) };

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

@@ -7,18 +7,108 @@ export interface InputSchedulerState {
     readonly held: Readonly<Partial<Record<HeldControl, number>>>;
     readonly queued: readonly EdgeAction[];
 }
-/** Creates an empty held-input scheduler. */
+/** Creates an empty held-input scheduler.
+ *
+ * @returns Creates an empty held-input scheduler.
+ * @example
+ * ```ts
+ * import { createInputScheduler } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * console.log(Object.keys(createInputScheduler()));
+ * ```
+ */
 export declare function createInputScheduler(): InputSchedulerState;
-/** Starts or releases one held control. Repeated press edges do not reset its repeat counter. */
+/** Starts or releases one held control. Repeated press edges do not reset its repeat counter.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @param control - The native held-control name.
+ * @param pressed - Whether this control is currently pressed.
+ * @returns Starts or releases one held control. Repeated press edges do not reset its repeat counter.
+ * @example
+ * ```ts
+ * import { createInputScheduler, setHeldInput } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const input=createInputScheduler();
+ * console.log(setHeldInput(input,"left",true));
+ * ```
+ */
 export declare function setHeldInput(state: InputSchedulerState, control: HeldControl, pressed: boolean): InputSchedulerState;
-/** Queues a one-shot rotation, drop, Place, pause or resume edge for the next logical tick. */
+/** Queues a one-shot rotation, drop, Place, pause or resume edge for the next logical tick.
+ *
+ * @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 Queues a one-shot rotation, drop, Place, pause or resume edge for the next logical tick.
+ * @example
+ * ```ts
+ * import { createInputScheduler, queueInputEdge } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const input=createInputScheduler();
+ * console.log(queueInputEdge(input,{kind:"hard-drop"}));
+ * ```
+ */
 export declare function queueInputEdge(state: InputSchedulerState, action: EdgeAction): InputSchedulerState;
-/** Releases every held or queued control after focus loss, lock, resolution or pause. */
+/** Releases every held or queued control after focus loss, lock, resolution or pause.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Releases every held or queued control after focus loss, lock, resolution or pause.
+ * @example
+ * ```ts
+ * import { createInputScheduler, releaseAllInput } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const input=createInputScheduler();
+ * console.log(releaseAllInput(input));
+ * ```
+ */
 export declare function releaseAllInput(state: InputSchedulerState): InputSchedulerState;
-/** Resolves this tick's inputs in lateral, rotation, drop, soft-drop, pause order. */
+/** Resolves this tick's inputs in lateral, rotation, drop, soft-drop, pause order.
+ *
+ * @param game - The native game state used to resolve scheduled input.
+ * @param input - The held-input scheduler state for this logical tick.
+ * @returns Resolves this tick's inputs in lateral, rotation, drop, soft-drop, pause order.
+ * @example
+ * ```ts
+ * import { actionsForTick, createGame, createInputScheduler } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const state=createGame({seed:"docs"});
+ * const input=createInputScheduler();
+ * console.log(actionsForTick(state,input)[0]);
+ * ```
+ */
 export declare function actionsForTick(game: GameState, input: InputSchedulerState): readonly [readonly Action[], InputSchedulerState];
-/** Applies a scheduler batch until the pair locks or the run pauses; accepted actions are recorded by the engine. */
+/** Applies a scheduler batch until the pair locks or the run pauses; accepted actions are recorded by the engine.
+ *
+ * @param game - The native game state used to resolve scheduled input.
+ * @param input - The held-input scheduler state for this logical tick.
+ * @param actions - Native actions in the scheduler’s canonical order.
+ * @param applyAction - The native applyAction function for this game.
+ * @returns Applies a scheduler batch until the pair locks or the run pauses; accepted actions are recorded by the engine.
+ * @example
+ * ```ts
+ * import { applyAction, applyScheduledActions, createGame, createInputScheduler } from "@johnmorrisdotca/houseki/colour-chains";
+ * import type { Action } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const state=createGame({seed:"docs"});
+ * const action: Action={kind:"left"};
+ * const input=createInputScheduler();
+ * console.log(applyScheduledActions(state,input,[action],applyAction)[0].phase);
+ * ```
+ */
 export declare function applyScheduledActions(game: GameState, input: InputSchedulerState, actions: readonly Action[], applyAction: (state: GameState, action: Action) => Transition): readonly [GameState, InputSchedulerState, readonly Transition[]];
-/** Applies a complete deterministic held-input and simulation tick, releasing controls on lock or resolution. */
+/** Applies a complete deterministic held-input and simulation tick, releasing controls on lock or resolution.
+ *
+ * @param game - The native game state used to resolve scheduled input.
+ * @param input - The held-input scheduler state for this logical tick.
+ * @param apply - The native applyAction function for this game.
+ * @param tick - The native advanceTicks function for this game.
+ * @returns Applies a complete deterministic held-input and simulation tick, releasing controls on lock or resolution.
+ * @example
+ * ```ts
+ * import { advanceTicks, applyAction, createGame, createInputScheduler, processInputTick } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const state=createGame({seed:"docs"});
+ * const input=createInputScheduler();
+ * console.log(processInputTick(state,input,applyAction,advanceTicks)[0].phase);
+ * ```
+ */
 export declare function processInputTick(game: GameState, input: InputSchedulerState, apply: (state: GameState, action: Action) => Transition, tick: (state: GameState, ticks: number) => Transition): readonly [GameState, InputSchedulerState, readonly Transition[]];
 export {};

package/dist/colour-chains/input.js

@@ -1,6 +1,28 @@
-/** Creates an empty held-input scheduler. */
+/** Creates an empty held-input scheduler.
+ *
+ * @returns Creates an empty held-input scheduler.
+ * @example
+ * ```ts
+ * import { createInputScheduler } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * console.log(Object.keys(createInputScheduler()));
+ * ```
+ */
 export function createInputScheduler() { return { held: Object.freeze({}), queued: Object.freeze([]) }; }
-/** Starts or releases one held control. Repeated press edges do not reset its repeat counter. */
+/** Starts or releases one held control. Repeated press edges do not reset its repeat counter.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @param control - The native held-control name.
+ * @param pressed - Whether this control is currently pressed.
+ * @returns Starts or releases one held control. Repeated press edges do not reset its repeat counter.
+ * @example
+ * ```ts
+ * import { createInputScheduler, setHeldInput } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const input=createInputScheduler();
+ * console.log(setHeldInput(input,"left",true));
+ * ```
+ */
 export function setHeldInput(state, control, pressed) {
     const held = { ...state.held };
     if (pressed) {
@@ -11,12 +33,48 @@ export function setHeldInput(state, control, pressed) {
         delete held[control];
     return { ...state, held: Object.freeze(held) };
 }
-/** Queues a one-shot rotation, drop, Place, pause or resume edge for the next logical tick. */
+/** Queues a one-shot rotation, drop, Place, pause or resume edge for the next logical tick.
+ *
+ * @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 Queues a one-shot rotation, drop, Place, pause or resume edge for the next logical tick.
+ * @example
+ * ```ts
+ * import { createInputScheduler, queueInputEdge } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const input=createInputScheduler();
+ * console.log(queueInputEdge(input,{kind:"hard-drop"}));
+ * ```
+ */
 export function queueInputEdge(state, action) { return { ...state, queued: Object.freeze([...state.queued, action]) }; }
-/** Releases every held or queued control after focus loss, lock, resolution or pause. */
+/** Releases every held or queued control after focus loss, lock, resolution or pause.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Releases every held or queued control after focus loss, lock, resolution or pause.
+ * @example
+ * ```ts
+ * import { createInputScheduler, releaseAllInput } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const input=createInputScheduler();
+ * console.log(releaseAllInput(input));
+ * ```
+ */
 // eslint-disable-next-line @typescript-eslint/no-unused-vars -- the public signature takes the state a caller holds, though nothing of it is kept
 export function releaseAllInput(state) { return createInputScheduler(); }
-/** Resolves this tick's inputs in lateral, rotation, drop, soft-drop, pause order. */
+/** Resolves this tick's inputs in lateral, rotation, drop, soft-drop, pause order.
+ *
+ * @param game - The native game state used to resolve scheduled input.
+ * @param input - The held-input scheduler state for this logical tick.
+ * @returns Resolves this tick's inputs in lateral, rotation, drop, soft-drop, pause order.
+ * @example
+ * ```ts
+ * import { actionsForTick, createGame, createInputScheduler } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const state=createGame({seed:"docs"});
+ * const input=createInputScheduler();
+ * console.log(actionsForTick(state,input)[0]);
+ * ```
+ */
 export function actionsForTick(game, input) {
     if (game.phase === 'paused') {
         const resume = input.queued.filter(action => action.kind === 'resume');
@@ -45,7 +103,24 @@ export function actionsForTick(game, input) {
         held[control] = (held[control] ?? 0) + 1;
     return [actions, { held: Object.freeze(held), queued: Object.freeze([]) }];
 }
-/** Applies a scheduler batch until the pair locks or the run pauses; accepted actions are recorded by the engine. */
+/** Applies a scheduler batch until the pair locks or the run pauses; accepted actions are recorded by the engine.
+ *
+ * @param game - The native game state used to resolve scheduled input.
+ * @param input - The held-input scheduler state for this logical tick.
+ * @param actions - Native actions in the scheduler’s canonical order.
+ * @param applyAction - The native applyAction function for this game.
+ * @returns Applies a scheduler batch until the pair locks or the run pauses; accepted actions are recorded by the engine.
+ * @example
+ * ```ts
+ * import { applyAction, applyScheduledActions, createGame, createInputScheduler } from "@johnmorrisdotca/houseki/colour-chains";
+ * import type { Action } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const state=createGame({seed:"docs"});
+ * const action: Action={kind:"left"};
+ * const input=createInputScheduler();
+ * console.log(applyScheduledActions(state,input,[action],applyAction)[0].phase);
+ * ```
+ */
 export function applyScheduledActions(game, input, actions, applyAction) {
     let state = game;
     const transitions = [];
@@ -64,7 +139,22 @@ export function applyScheduledActions(game, input, actions, applyAction) {
     const lockedOrPaused = transitions.some(result => result.events.some(event => event.type === 'pair-locked' || event.type === 'paused')) || state.phase !== 'falling';
     return [state, lockedOrPaused ? createInputScheduler() : input, transitions];
 }
-/** Applies a complete deterministic held-input and simulation tick, releasing controls on lock or resolution. */
+/** Applies a complete deterministic held-input and simulation tick, releasing controls on lock or resolution.
+ *
+ * @param game - The native game state used to resolve scheduled input.
+ * @param input - The held-input scheduler state for this logical tick.
+ * @param apply - The native applyAction function for this game.
+ * @param tick - The native advanceTicks function for this game.
+ * @returns Applies a complete deterministic held-input and simulation tick, releasing controls on lock or resolution.
+ * @example
+ * ```ts
+ * import { advanceTicks, applyAction, createGame, createInputScheduler, processInputTick } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const state=createGame({seed:"docs"});
+ * const input=createInputScheduler();
+ * console.log(processInputTick(state,input,applyAction,advanceTicks)[0].phase);
+ * ```
+ */
 export function processInputTick(game, input, apply, tick) {
     const [actions, scheduled] = actionsForTick(game, input);
     const [afterInput, retained, transitions] = applyScheduledActions(game, scheduled, actions, apply);