@johnmorrisdotca/houseki 0.4.1 → 0.4.2

package/dist/falling-triplets/content.d.ts

@@ -1,11 +1,68 @@
 import type { CampaignLevel, CampaignManifest, TutorialDefinition } 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/falling-triplets";
+ *
+ * console.log(campaignManifest.count);
+ * ```
+ */
 export declare const campaignManifest: CampaignManifest;
+/** The frozen ordered native levels; array indices start at zero and display numbers start at one.
+ *
+ * @example
+ * ```ts
+ * import { levelManifest } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * console.log(levelManifest.length);
+ * ```
+ */
 export declare const levelManifest: readonly CampaignLevel[];
+/** The frozen native bilingual lessons and their authored teaching steps.
+ *
+ * @example
+ * ```ts
+ * import { tutorialManifest } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * console.log(tutorialManifest.length);
+ * ```
+ */
 export declare const tutorialManifest: readonly TutorialDefinition[];
-/** Find a level by stable content ID or its current one-based display number. */
+/** Find a level by stable content ID or its current one-based display number.
+ *
+ * @param id - A stable content id, or the one-based display number when numbers are accepted.
+ * @returns Find a level by stable content ID or its current one-based display number. Returns undefined when the id or display number is absent.
+ * @example
+ * ```ts
+ * import { getLevel } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * console.log(getLevel(1)?.id);
+ * ```
+ */
 export declare function getLevel(id: string | number): CampaignLevel | undefined;
-/** Construct a fresh validated challenge state for a stable level ID or display number. */
+/** Construct a fresh validated challenge state for a stable level ID or display number.
+ *
+ * @param id - A stable content id, or the one-based display number when numbers are accepted.
+ * @returns Construct a fresh validated challenge state for a stable level ID or display number.
+ * @example
+ * ```ts
+ * import { createLevel } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * console.log(createLevel(1).phase);
+ * ```
+ */
 export declare function createLevel(id: string | number): GameState;
-/** Find a lesson by its persistent ID. */
+/** Find a lesson by its persistent ID.
+ *
+ * @param id - A stable content id, or the one-based display number when numbers are accepted.
+ * @returns Find a lesson by its persistent ID. Returns undefined when the id or display number is absent.
+ * @example
+ * ```ts
+ * import { getTutorial, tutorialManifest } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * console.log(getTutorial(tutorialManifest[0].id)?.id);
+ * ```
+ */
 export declare function getTutorial(id: string): TutorialDefinition | undefined;

package/dist/falling-triplets/content.js

@@ -8,16 +8,63 @@ 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/falling-triplets";
+ *
+ * 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/falling-triplets";
+ *
+ * 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/falling-triplets";
+ *
+ * console.log(tutorialManifest.length);
+ * ```
+ */
 export const tutorialManifest = deepFreeze(contentData.tutorials);
-/** Find a level by stable content ID or its current one-based display number. */
+/** Find a level by stable content ID or its current one-based display number.
+ *
+ * @param id - A stable content id, or the one-based display number when numbers are accepted.
+ * @returns Find a level by stable content ID or its current one-based display number. Returns undefined when the id or display number is absent.
+ * @example
+ * ```ts
+ * import { getLevel } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * 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);
 }
-/** Construct a fresh validated challenge state for a stable level ID or display number. */
+/** Construct a fresh validated challenge state for a stable level ID or display number.
+ *
+ * @param id - A stable content id, or the one-based display number when numbers are accepted.
+ * @returns Construct a fresh validated challenge state for a stable level ID or display number.
+ * @example
+ * ```ts
+ * import { createLevel } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * console.log(createLevel(1).phase);
+ * ```
+ */
 export function createLevel(id) {
     const level = getLevel(id);
     if (!level)
@@ -33,7 +80,17 @@ export function createLevel(id) {
         witness: level.witness
     });
 }
-/** Find a lesson by its persistent ID. */
+/** Find a lesson by its persistent ID.
+ *
+ * @param id - A stable content id, or the one-based display number when numbers are accepted.
+ * @returns Find a lesson by its persistent ID. Returns undefined when the id or display number is absent.
+ * @example
+ * ```ts
+ * import { getTutorial, tutorialManifest } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * console.log(getTutorial(tutorialManifest[0].id)?.id);
+ * ```
+ */
 export function getTutorial(id) {
     return tutorialManifest.find(tutorial => tutorial.id === id);
 }

package/dist/falling-triplets/engine.d.ts

@@ -1,26 +1,138 @@
 import type { Action, ChallengeOptions, CreateOptions, GameState, Transition } from './types.js';
-/** Returns the exact landing row for the current rigid triplet. */
+/** Returns the exact landing row for the current rigid triplet.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Returns the exact landing row for the current rigid triplet. Returns null when there is no active piece or applicable preview.
+ * @example
+ * ```ts
+ * import { createGame, landingY } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(landingY(state));
+ * ```
+ */
 export declare function landingY(state: GameState): number | null;
-/** Creates a deterministic empty game with an active piece and three-piece preview. */
+/** Creates a deterministic empty game with an active piece and three-piece preview.
+ *
+ * @param options - Validated native creation, authored challenge, or environment options described by this signature.
+ * @returns Creates a deterministic empty game with an active piece and three-piece preview.
+ * @example
+ * ```ts
+ * import { createGame } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * console.log(createGame({seed:"docs"}).phase);
+ * ```
+ */
 export declare function createGame(options?: CreateOptions): GameState;
-/** Creates a challenge after validating its authored board, finite queue, goal, and witness. */
+/** Creates a challenge after validating its authored board, finite queue, goal, and witness.
+ *
+ * @param options - Validated native creation, authored challenge, or environment options described by this signature.
+ * @returns Creates a challenge after validating its authored board, finite queue, goal, and witness.
+ * @example
+ * ```ts
+ * import { createChallenge } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * console.log(createChallenge({width:6,height:12,board:Array(72).fill(null),queue:[["red","green","blue"],["blue","red","green"]],goal:{type:"empty"}}).phase);
+ * ```
+ */
 export declare function createChallenge(options: ChallengeOptions): GameState;
-/** Applies and records one immutable action; rejected actions preserve state identity. */
+/** Applies and records one immutable action; rejected actions preserve state identity.
+ *
+ * @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 and records one immutable action; rejected actions preserve state identity.
+ * @example
+ * ```ts
+ * import { applyAction, createGame } from "@johnmorrisdotca/houseki/falling-triplets";
+ * import type { Action } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * const state=createGame({seed:"docs"});
+ * const action: Action={kind:"left"};
+ * console.log(applyAction(state,action).accepted);
+ * ```
+ */
 export declare function applyAction(state: GameState, action: Action): Transition;
-/** Advances fixed 60 Hz game ticks. Arcade timing is applied to the active piece. */
+/** Advances fixed 60 Hz game ticks. Arcade timing is applied to the active piece.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @param ticks - The nonnegative number of fixed 60 Hz logical ticks to advance.
+ * @returns Advances fixed 60 Hz game ticks. Arcade timing is applied to the active piece.
+ * @example
+ * ```ts
+ * import { advanceTicks, createGame } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(advanceTicks(state,1).state.phase);
+ * ```
+ */
 export declare function advanceTicks(state: GameState, ticks: number): Transition;
-/** Lists the core actions currently available to the player. */
+/** Lists the core actions currently available to the player.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Lists the core actions currently available to the player.
+ * @example
+ * ```ts
+ * import { createGame, legalActions } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(legalActions(state).length);
+ * ```
+ */
 export declare function legalActions(state: GameState): readonly Action[];
-/** Returns a plain status summary suitable for UI labels. */
+/** Returns a plain status summary suitable for UI labels.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Returns a plain status summary suitable for UI labels.
+ * @example
+ * ```ts
+ * import { createGame, statusOf } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(statusOf(state).phase);
+ * ```
+ */
 export declare function statusOf(state: GameState): Readonly<{
     phase: GameState['phase'];
     score: number;
     maxChain: number;
     reason?: string;
 }>;
-/** Recreates the same authored mode, seed, and challenge configuration from its original setup. */
+/** Recreates the same authored mode, seed, and challenge configuration from its original setup.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Recreates the same authored mode, seed, and challenge configuration from its original setup.
+ * @example
+ * ```ts
+ * import { createGame, restartGame } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(restartGame(state).phase);
+ * ```
+ */
 export declare function restartGame(state: GameState): GameState;
-/** Encodes the authoritative settings, action recording, and derived checkpoint. */
+/** Encodes the authoritative settings, action recording, and derived checkpoint.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Encodes the authoritative settings, action recording, and derived checkpoint.
+ * @example
+ * ```ts
+ * import { createGame, encodeGame } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(encodeGame(state).length);
+ * ```
+ */
 export declare function encodeGame(state: GameState): string;
-/** Replays and validates a bounded save, then verifies its checkpoint against the derived state. */
+/** Replays and validates a bounded save, then verifies its checkpoint against the derived state.
+ *
+ * @param text - A saved JSON recording from this entry’s encodeGame; malformed or inconsistent saves throw.
+ * @returns Replays and validates a bounded save, then verifies its checkpoint against the derived state.
+ * @example
+ * ```ts
+ * import { createGame, decodeGame, encodeGame } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(decodeGame(encodeGame(state)).phase);
+ * ```
+ */
 export declare function decodeGame(text: string): GameState;

package/dist/falling-triplets/engine.js

@@ -28,7 +28,18 @@ function activeFromColours(state, colours, y = -3) {
 function occupied(state, piece, x = piece.x, y = piece.y) {
     return piece.gems.some((_, i) => { const cy = y + i; return x < 0 || x >= state.settings.width || cy < -HIDDEN || cy >= state.settings.height || state.board[addr(x, cy, state.settings.width)] !== null; });
 }
-/** Returns the exact landing row for the current rigid triplet. */
+/** Returns the exact landing row for the current rigid triplet.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Returns the exact landing row for the current rigid triplet. Returns null when there is no active piece or applicable preview.
+ * @example
+ * ```ts
+ * import { createGame, landingY } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(landingY(state));
+ * ```
+ */
 export function landingY(state) {
     if (!state.active)
         return null;
@@ -48,7 +59,17 @@ function advanceBag(state) {
     }
     return [bag, randomState, next];
 }
-/** Creates a deterministic empty game with an active piece and three-piece preview. */
+/** Creates a deterministic empty game with an active piece and three-piece preview.
+ *
+ * @param options - Validated native creation, authored challenge, or environment options described by this signature.
+ * @returns Creates a deterministic empty game with an active piece and three-piece preview.
+ * @example
+ * ```ts
+ * import { createGame } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * console.log(createGame({seed:"docs"}).phase);
+ * ```
+ */
 export function createGame(options = {}) {
     if (options.preset !== undefined && !Object.hasOwn(PRESETS, options.preset))
         throw new RangeError('Unsupported board preset');
@@ -88,7 +109,17 @@ export function createGame(options = {}) {
     return state;
 }
 const VALID_COLOURS = new Set(['red', 'blue', 'green', 'gold', 'purple', 'teal']);
-/** Creates a challenge after validating its authored board, finite queue, goal, and witness. */
+/** Creates a challenge after validating its authored board, finite queue, goal, and witness.
+ *
+ * @param options - Validated native creation, authored challenge, or environment options described by this signature.
+ * @returns Creates a challenge after validating its authored board, finite queue, goal, and witness.
+ * @example
+ * ```ts
+ * import { createChallenge } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * console.log(createChallenge({width:6,height:12,board:Array(72).fill(null),queue:[["red","green","blue"],["blue","red","green"]],goal:{type:"empty"}}).phase);
+ * ```
+ */
 export function createChallenge(options) {
     const width = options.width ?? 6;
     const height = options.height ?? 13;
@@ -386,7 +417,21 @@ function applyActionCore(state, action) {
     }
     return emptyTransition(state, 'unsupported-action');
 }
-/** Applies and records one immutable action; rejected actions preserve state identity. */
+/** Applies and records one immutable action; rejected actions preserve state identity.
+ *
+ * @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 and records one immutable action; rejected actions preserve state identity.
+ * @example
+ * ```ts
+ * import { applyAction, createGame } from "@johnmorrisdotca/houseki/falling-triplets";
+ * import type { Action } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * const state=createGame({seed:"docs"});
+ * const action: Action={kind:"left"};
+ * console.log(applyAction(state,action).accepted);
+ * ```
+ */
 export function applyAction(state, action) {
     const result = applyActionCore(state, action);
     if (!result.accepted || action.kind === 'tick')
@@ -395,7 +440,19 @@ export function applyAction(state, action) {
     const ordinal = last?.tick === state.elapsedTicks ? last.ordinal + 1 : 0;
     return { ...result, state: { ...result.state, recording: [...state.recording, { tick: state.elapsedTicks, ordinal, action }] } };
 }
-/** Advances fixed 60 Hz game ticks. Arcade timing is applied to the active piece. */
+/** Advances fixed 60 Hz game ticks. Arcade timing is applied to the active piece.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @param ticks - The nonnegative number of fixed 60 Hz logical ticks to advance.
+ * @returns Advances fixed 60 Hz game ticks. Arcade timing is applied to the active piece.
+ * @example
+ * ```ts
+ * import { advanceTicks, createGame } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * 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');
@@ -437,7 +494,18 @@ export function advanceTicks(state, ticks) {
     }
     return { state: current, events, accepted: true };
 }
-/** Lists the core actions currently available to the player. */
+/** Lists the core actions currently available to the player.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Lists the core actions currently available to the player.
+ * @example
+ * ```ts
+ * import { createGame, legalActions } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(legalActions(state).length);
+ * ```
+ */
 export function legalActions(state) {
     if (state.phase === 'paused')
         return [{ kind: 'resume' }];
@@ -461,9 +529,31 @@ export function legalActions(state) {
     actions.push({ kind: 'pause' });
     return actions;
 }
-/** Returns a plain status summary suitable for UI labels. */
+/** Returns a plain status summary suitable for UI labels.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Returns a plain status summary suitable for UI labels.
+ * @example
+ * ```ts
+ * import { createGame, statusOf } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(statusOf(state).phase);
+ * ```
+ */
 export function statusOf(state) { return { phase: state.phase, score: state.score, maxChain: state.maxChain, ...(state.reason ? { reason: state.reason } : {}) }; }
-/** Recreates the same authored mode, seed, and challenge configuration from its original setup. */
+/** Recreates the same authored mode, seed, and challenge configuration from its original setup.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Recreates the same authored mode, seed, and challenge configuration from its original setup.
+ * @example
+ * ```ts
+ * import { createGame, restartGame } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(restartGame(state).phase);
+ * ```
+ */
 export function restartGame(state) {
     if (state.settings.mode === 'challenge') {
         const settings = state.settings;
@@ -472,7 +562,18 @@ export function restartGame(state) {
     }
     return createGame({ mode: state.settings.mode, seed: state.settings.seed, width: state.settings.width, height: state.settings.height, colourCount: state.settings.colourCount, ...(state.settings.pieceLimit === undefined ? {} : { pieceLimit: state.settings.pieceLimit }) });
 }
-/** Encodes the authoritative settings, action recording, and derived checkpoint. */
+/** Encodes the authoritative settings, action recording, and derived checkpoint.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Encodes the authoritative settings, action recording, and derived checkpoint.
+ * @example
+ * ```ts
+ * import { createGame, encodeGame } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(encodeGame(state).length);
+ * ```
+ */
 export function encodeGame(state) { return JSON.stringify({ format: 1, game: state.game, rules: state.rules, settings: state.settings, actions: state.recording, elapsedTicks: state.elapsedTicks, checkpoint: state }); }
 function stable(value) {
     if (Array.isArray(value))
@@ -481,7 +582,18 @@ function stable(value) {
         return `{${Object.entries(value).filter(([, item]) => item !== undefined).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => `${JSON.stringify(key)}:${stable(item)}`).join(',')}}`;
     return JSON.stringify(value) ?? 'null';
 }
-/** Replays and validates a bounded save, then verifies its checkpoint against the derived state. */
+/** Replays and validates a bounded save, then verifies its checkpoint against the derived state.
+ *
+ * @param text - A saved JSON recording from this entry’s encodeGame; malformed or inconsistent saves throw.
+ * @returns Replays and validates a bounded save, then verifies its checkpoint against the derived state.
+ * @example
+ * ```ts
+ * import { createGame, decodeGame, encodeGame } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(decodeGame(encodeGame(state)).phase);
+ * ```
+ */
 export function decodeGame(text) {
     if (text.length > 2 * 1024 * 1024)
         throw new RangeError('Save exceeds 2 MiB');

package/dist/falling-triplets/input.d.ts

@@ -5,14 +5,70 @@ export interface InputSchedulerState {
     readonly held: Readonly<Partial<Record<HoldAction, number>>>;
     readonly queued: readonly Action[];
 }
-/** Creates an empty fixed-tick input scheduler state. */
+/** Creates an empty fixed-tick input scheduler state.
+ *
+ * @returns Creates an empty fixed-tick input scheduler state.
+ * @example
+ * ```ts
+ * import { createInputScheduler } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * console.log(Object.keys(createInputScheduler()));
+ * ```
+ */
 export declare function createInputScheduler(): InputSchedulerState;
-/** Starts or releases one held action; opposite lateral holds cancel during scheduling. */
+/** Starts or releases one held action; opposite lateral holds cancel during scheduling.
+ *
+ * @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.
+ * @param held - Whether this input is currently held.
+ * @returns Starts or releases one held action; opposite lateral holds cancel during scheduling.
+ * @example
+ * ```ts
+ * import { createInputScheduler, setHeldAction } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * const input=createInputScheduler();
+ * console.log(setHeldAction(input,"left",true));
+ * ```
+ */
 export declare function setHeldAction(state: InputSchedulerState, action: HoldAction, held: boolean): InputSchedulerState;
-/** Queues a one-shot cycle, drop, or pause edge for the next logical tick. */
+/** Queues a one-shot cycle, drop, or pause 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 cycle, drop, or pause edge for the next logical tick.
+ * @example
+ * ```ts
+ * import { createInputScheduler, queueInputEdge } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * const input=createInputScheduler();
+ * console.log(queueInputEdge(input,{kind:"hard-drop"}));
+ * ```
+ */
 export declare function queueInputEdge(state: InputSchedulerState, action: Action): InputSchedulerState;
-/** Resolves canonical actions in the design's per-tick order. */
+/** Resolves canonical actions in the design's per-tick order.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Resolves canonical actions in the design's per-tick order.
+ * @example
+ * ```ts
+ * import { actionsForTick, createInputScheduler } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * const input=createInputScheduler();
+ * console.log(actionsForTick(input)[0]);
+ * ```
+ */
 export declare function actionsForTick(state: InputSchedulerState): readonly [readonly Action[], InputSchedulerState];
-/** Releases every held action after blur, pause, or pointer cancellation. */
+/** Releases every held action after blur, pause, or pointer cancellation.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Releases every held action after blur, pause, or pointer cancellation.
+ * @example
+ * ```ts
+ * import { createInputScheduler, releaseAllActions } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * const input=createInputScheduler();
+ * console.log(releaseAllActions(input));
+ * ```
+ */
 export declare function releaseAllActions(state: InputSchedulerState): InputSchedulerState;
 export {};

package/dist/falling-triplets/input.js

@@ -1,6 +1,28 @@
-/** Creates an empty fixed-tick input scheduler state. */
+/** Creates an empty fixed-tick input scheduler state.
+ *
+ * @returns Creates an empty fixed-tick input scheduler state.
+ * @example
+ * ```ts
+ * import { createInputScheduler } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * console.log(Object.keys(createInputScheduler()));
+ * ```
+ */
 export function createInputScheduler() { return { held: {}, queued: [] }; }
-/** Starts or releases one held action; opposite lateral holds cancel during scheduling. */
+/** Starts or releases one held action; opposite lateral holds cancel during scheduling.
+ *
+ * @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.
+ * @param held - Whether this input is currently held.
+ * @returns Starts or releases one held action; opposite lateral holds cancel during scheduling.
+ * @example
+ * ```ts
+ * import { createInputScheduler, setHeldAction } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * const input=createInputScheduler();
+ * console.log(setHeldAction(input,"left",true));
+ * ```
+ */
 export function setHeldAction(state, action, held) {
     const next = { ...state.held };
     if (held) {
@@ -11,13 +33,36 @@ export function setHeldAction(state, action, held) {
         delete next[action];
     return { ...state, held: next };
 }
-/** Queues a one-shot cycle, drop, or pause edge for the next logical tick. */
+/** Queues a one-shot cycle, drop, or pause 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 cycle, drop, or pause edge for the next logical tick.
+ * @example
+ * ```ts
+ * import { createInputScheduler, queueInputEdge } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * const input=createInputScheduler();
+ * console.log(queueInputEdge(input,{kind:"hard-drop"}));
+ * ```
+ */
 export function queueInputEdge(state, action) {
     if (!['cycle-forward', 'cycle-backward', 'hard-drop', 'place', 'pause', 'resume'].includes(action.kind))
         return state;
     return { ...state, queued: [...state.queued, action] };
 }
-/** Resolves canonical actions in the design's per-tick order. */
+/** Resolves canonical actions in the design's per-tick order.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Resolves canonical actions in the design's per-tick order.
+ * @example
+ * ```ts
+ * import { actionsForTick, createInputScheduler } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * const input=createInputScheduler();
+ * console.log(actionsForTick(input)[0]);
+ * ```
+ */
 export function actionsForTick(state) {
     const actions = [];
     const held = { ...state.held };
@@ -37,6 +82,17 @@ export function actionsForTick(state) {
         held[key] = (held[key] ?? 0) + 1;
     return [actions, { held, queued: [] }];
 }
-/** Releases every held action after blur, pause, or pointer cancellation. */
+/** Releases every held action after blur, pause, or pointer cancellation.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Releases every held action after blur, pause, or pointer cancellation.
+ * @example
+ * ```ts
+ * import { createInputScheduler, releaseAllActions } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * const input=createInputScheduler();
+ * console.log(releaseAllActions(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 releaseAllActions(state) { return { held: {}, queued: [] }; }