@johnmorrisdotca/houseki 0.4.0 → 0.4.2

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);

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

@@ -1,7 +1,40 @@
 import type { GameState } from './types.js';
-/** Restarts the same seed/date or original witnessed challenge board and queue. */
+/** Restarts the same seed/date or original witnessed challenge board and queue.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Restarts the same seed/date or original witnessed challenge board and queue.
+ * @example
+ * ```ts
+ * import { createGame, restartGame } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(restartGame(state).phase);
+ * ```
+ */
 export declare function restartGame(state: GameState): GameState;
-/** Encodes canonical initial settings, accepted ordinal actions and a derived checkpoint. */
+/** Encodes canonical initial settings, accepted ordinal actions and a derived checkpoint.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Encodes canonical initial settings, accepted ordinal actions and a derived checkpoint.
+ * @example
+ * ```ts
+ * import { createGame, encodeGame } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(encodeGame(state).length);
+ * ```
+ */
 export declare function encodeGame(state: GameState): string;
-/** Reconstructs a bounded action replay and rejects any checkpoint that differs from replay. */
+/** Reconstructs a bounded action replay and rejects any checkpoint that differs from replay.
+ *
+ * @param text - A saved JSON recording from this entry’s encodeGame; malformed or inconsistent saves throw.
+ * @returns Reconstructs a bounded action replay and rejects any checkpoint that differs from replay.
+ * @example
+ * ```ts
+ * import { createGame, decodeGame, encodeGame } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(decodeGame(encodeGame(state)).phase);
+ * ```
+ */
 export declare function decodeGame(text: string): GameState;

package/dist/colour-chains/persistence.js

@@ -30,9 +30,31 @@ function createFromSettings(settings) {
         throw new TypeError('Save settings are not canonical');
     return state;
 }
-/** Restarts the same seed/date or original witnessed challenge board and queue. */
+/** Restarts the same seed/date or original witnessed challenge board and queue.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Restarts the same seed/date or original witnessed challenge board and queue.
+ * @example
+ * ```ts
+ * import { createGame, restartGame } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(restartGame(state).phase);
+ * ```
+ */
 export function restartGame(state) { return createFromSettings(state.settings); }
-/** Encodes canonical initial settings, accepted ordinal actions and a derived checkpoint. */
+/** Encodes canonical initial settings, accepted ordinal actions and a derived checkpoint.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Encodes canonical initial settings, accepted ordinal actions and a derived checkpoint.
+ * @example
+ * ```ts
+ * import { createGame, encodeGame } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(encodeGame(state).length);
+ * ```
+ */
 export function encodeGame(state) {
     if (!Number.isSafeInteger(state.elapsedTicks) || state.elapsedTicks < 0 || state.elapsedTicks > MAX_TICKS || state.recording.length > MAX_ACTIONS)
         throw new RangeError('Run exceeds replay limits');
@@ -41,7 +63,18 @@ export function encodeGame(state) {
         throw new RangeError('Save exceeds 2 MiB');
     return text;
 }
-/** Reconstructs a bounded action replay and rejects any checkpoint that differs from replay. */
+/** Reconstructs a bounded action replay and rejects any checkpoint that differs from replay.
+ *
+ * @param text - A saved JSON recording from this entry’s encodeGame; malformed or inconsistent saves throw.
+ * @returns Reconstructs a bounded action replay and rejects any checkpoint that differs from replay.
+ * @example
+ * ```ts
+ * import { createGame, decodeGame, encodeGame } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const state=createGame({seed:"docs"});
+ * console.log(decodeGame(encodeGame(state)).phase);
+ * ```
+ */
 export function decodeGame(text) {
     if (typeof text !== 'string' || new TextEncoder().encode(text).byteLength > MAX_SAVE_BYTES)
         throw new RangeError('Save must be text no larger than 2 MiB');