@johnmorrisdotca/houseki 0.4.0 → 0.4.2

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

@@ -1,22 +1,78 @@
 import type { NaturePieceCell, PowerDropPreview } from '../nature/types.js';
-/** A gem colour used by Colour Chains. */
+/** A gem colour used by Colour Chains.
+ *
+ * @example
+ * ```ts
+ * import type { Colour } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const value: Colour = "red";
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type Colour = 'red' | 'blue' | 'green' | 'gold' | 'purple' | 'teal';
-/** A settled or active stone with a stable run-local identity. */
+/** A settled or active stone with a stable run-local identity.
+ *
+ * @example
+ * ```ts
+ * import type { Gem } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const value: Gem = {id:1,colour:"red"};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface Gem {
     readonly id: number;
     readonly colour: Colour;
     readonly magnetic?: true;
 }
-/** Authored challenge layouts can include explicit Shizen-marked stones. */
+/** Authored challenge layouts can include explicit Shizen-marked stones.
+ *
+ * @example
+ * ```ts
+ * import type { ChallengeGem } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const value: ChallengeGem = {id:1,colour:"red",magnetic:true};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type ChallengeGem = Gem;
-/** The pivot-to-satellite direction, in clockwise order. */
+/** The pivot-to-satellite direction, in clockwise order.
+ *
+ * @example
+ * ```ts
+ * import type { Orientation } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const value: Orientation = "up";
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type Orientation = 'up' | 'right' | 'down' | 'left';
-/** A visible or hidden board coordinate. */
+/** A visible or hidden board coordinate.
+ *
+ * @example
+ * ```ts
+ * import type { Cell } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const value: Cell = {x:0,y:0};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface Cell {
     readonly x: number;
     readonly y: number;
 }
-/** The active rigid pair. The pivot always retains its own gem identity. */
+/** The active rigid pair. The pivot always retains its own gem identity.
+ *
+ * @example
+ * ```ts
+ * import { createGame } from "@johnmorrisdotca/houseki/colour-chains";
+ * import type { Pair } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const state=createGame({seed:"docs"});
+ * const value: Pair = state.active!;
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface Pair {
     readonly pivot: Cell;
     readonly orientation: Orientation;
@@ -27,10 +83,49 @@ export interface Pair {
     readonly resetCount: number;
     readonly groundedStarted: boolean;
 }
-/** Supported well presets. */
+/** Supported well presets.
+ *
+ * @example
+ * ```ts
+ * import type { Preset } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const value: Preset = "standard";
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type Preset = 'narrow' | 'standard' | 'wide' | 'tall' | 'extraWide' | 'deep' | 'large';
+/** The native game mode; authored challenges have fixed setup and queue rules.
+ *
+ * @example
+ * ```ts
+ * import type { Mode } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const value: Mode = "relaxed";
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type Mode = 'relaxed' | 'arcade' | 'daily' | 'challenge';
+/** The native frequent or rare weather schedule for Colour Chains.
+ *
+ * @example
+ * ```ts
+ * import type { WeatherSchedule } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const value: WeatherSchedule = "frequent";
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type WeatherSchedule = 'frequent' | 'rare';
+/** Creation settings for this native engine; dimensions, mode, seed and optional mechanics are validated together.
+ *
+ * @example
+ * ```ts
+ * import type { CreateOptions } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const value: CreateOptions = {seed:"docs"};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface CreateOptions {
     readonly mode?: Exclude<Mode, 'challenge'>;
     readonly seed?: string;
@@ -43,7 +138,18 @@ export interface CreateOptions {
     readonly nature?: boolean;
     readonly weather?: WeatherSchedule;
 }
-/** Run settings fixed at game creation. */
+/** Run settings fixed at game creation.
+ *
+ * @example
+ * ```ts
+ * import { createGame } from "@johnmorrisdotca/houseki/colour-chains";
+ * import type { Settings } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const state=createGame({seed:"docs"});
+ * const value: Settings = state.settings;
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface Settings {
     readonly mode: Mode;
     readonly width: number;
@@ -61,7 +167,16 @@ export interface Settings {
     readonly magneticQueue?: readonly (readonly [boolean, boolean])[];
     readonly witness?: readonly WitnessStep[];
 }
-/** Challenge objective; target IDs refer to the visible starting board. */
+/** Challenge objective; target IDs refer to the visible starting board.
+ *
+ * @example
+ * ```ts
+ * import type { ChallengeGoal } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const value: ChallengeGoal = {kind:"empty-board"};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type ChallengeGoal = {
     readonly kind: 'clear-targets';
     readonly targetIds: readonly number[];
@@ -71,10 +186,32 @@ export type ChallengeGoal = {
 } | {
     readonly kind: 'empty-board';
 };
+/** One witnessed Colour Chains pair placement using pivot column and orientation.
+ *
+ * @example
+ * ```ts
+ * import type { WitnessStep } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const value: WitnessStep = {pivotX:0,orientation:"up"};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface WitnessStep {
     readonly pivotX: number;
     readonly orientation: Orientation;
 }
+/** Authored challenge inputs including the starting board, finite goal and supplied witness.
+ *
+ * @example
+ * ```ts
+ * import { createGame } from "@johnmorrisdotca/houseki/colour-chains";
+ * import type { ChallengeOptions } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const state=createGame({seed:"docs"});
+ * const value: ChallengeOptions = {id:"docs",board:state.board,queue:[["red","green"]],goal:{kind:"empty-board"}};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface ChallengeOptions {
     readonly id: string;
     readonly width?: number;
@@ -89,15 +226,46 @@ export interface ChallengeOptions {
     readonly goal: ChallengeGoal;
     readonly witness?: readonly WitnessStep[];
 }
-/** Observable game phases. */
+/** Observable game phases.
+ *
+ * @example
+ * ```ts
+ * import { createGame } from "@johnmorrisdotca/houseki/colour-chains";
+ * import type { Phase } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const state=createGame({seed:"docs"});
+ * const value: Phase = state.phase;
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type Phase = 'falling' | 'clear-mark' | 'clear-remove' | 'gravity' | 'paused' | 'won' | 'lost' | 'finished';
-/** A scored simultaneous match wave. */
+/** A scored simultaneous match wave.
+ *
+ * @example
+ * ```ts
+ * import type { Wave } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const value: Wave = {chain:1,cells:[],points:0,ids:[]};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface Wave {
     readonly chain: number;
     readonly cells: readonly number[];
     readonly ids: readonly number[];
     readonly points: number;
 }
+/** One native Colour Chains player command, including pause and hint commands.
+ *
+ * @example
+ * ```ts
+ * import type { Action, PlayAction } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const action: Action={kind:"left"};
+ * const value: PlayAction = action;
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type PlayAction = {
     readonly kind: 'left';
 } | {
@@ -119,8 +287,39 @@ export type PlayAction = {
 } | {
     readonly kind: 'hint';
 };
+/** A native player action accepted or rejected according to the current phase and rules.
+ *
+ * @example
+ * ```ts
+ * import type { Action } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const action: Action={kind:"left"};
+ * const value: Action = action;
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type Action = PlayAction;
+/** A lateral or soft-drop control which the input scheduler can repeat.
+ *
+ * @example
+ * ```ts
+ * import type { HeldControl } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const value: HeldControl = "left";
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type HeldControl = 'left' | 'right' | 'soft-drop';
+/** A native held-control change or one-shot edge command for Colour Chains.
+ *
+ * @example
+ * ```ts
+ * import type { InputCommand } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const value: InputCommand = {kind:"hold",control:"left",pressed:true};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type InputCommand = {
     readonly kind: 'hold';
     readonly control: HeldControl;
@@ -131,12 +330,34 @@ export type InputCommand = {
         kind: 'rotate-clockwise' | 'rotate-anticlockwise' | 'hard-drop' | 'place' | 'pause' | 'resume';
     }>;
 };
+/** A native action recording with the logical position needed for deterministic replay.
+ *
+ * @example
+ * ```ts
+ * import type { Action, RecordedAction } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const action: Action={kind:"left"};
+ * const value: RecordedAction = {tick:0,ordinal:0,action};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface RecordedAction {
     readonly tick: number;
     readonly ordinal: number;
     readonly action: PlayAction;
 }
-/** An immutable Colour Chains rules state. Board rows include the three hidden rows above the well. */
+/** An immutable Colour Chains rules state. Board rows include the three hidden rows above the well.
+ *
+ * @example
+ * ```ts
+ * import { createGame } from "@johnmorrisdotca/houseki/colour-chains";
+ * import type { GameState } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const state=createGame({seed:"docs"});
+ * const value: GameState = state;
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface GameState {
     readonly game: 'colour-chains';
     readonly rules: 'chains-1';
@@ -169,19 +390,51 @@ export interface GameState {
     readonly recording: readonly RecordedAction[];
     readonly reason?: string;
 }
-/** A deterministic transition; rejected actions retain the exact input state. */
+/** A deterministic transition; rejected actions retain the exact input state.
+ *
+ * @example
+ * ```ts
+ * import { applyAction, createGame } from "@johnmorrisdotca/houseki/colour-chains";
+ * import type { Action, Transition } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const state=createGame({seed:"docs"});
+ * const action: Action={kind:"left"};
+ * const value: Transition = applyAction(state,action);
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface Transition {
     readonly state: GameState;
     readonly events: readonly GameEvent[];
     readonly accepted: boolean;
     readonly reason?: string;
 }
-/** A domain event emitted by one transition. */
+/** A domain event emitted by one transition.
+ *
+ * @example
+ * ```ts
+ * import type { GameEvent } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const value: GameEvent = {type:"host-example"};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface GameEvent {
     readonly type: string;
     readonly [key: string]: unknown;
 }
-/** Compact player status derived from the current state. */
+/** Compact player status derived from the current state.
+ *
+ * @example
+ * ```ts
+ * import { createGame, statusOf } from "@johnmorrisdotca/houseki/colour-chains";
+ * import type { GameStatus } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const state=createGame({seed:"docs"});
+ * const value: GameStatus = statusOf(state);
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface GameStatus {
     readonly mode: Mode;
     readonly phase: Phase;
@@ -192,9 +445,30 @@ export interface GameStatus {
     readonly assisted: boolean;
     readonly reason?: string;
 }
-/** Destination cells for the two independently settled ghost stones. */
+/** Destination cells for the two independently settled ghost stones.
+ *
+ * @example
+ * ```ts
+ * import { createGame, landingCells } from "@johnmorrisdotca/houseki/colour-chains";
+ * import type { Landing } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const state=createGame({seed:"docs"});
+ * const value: Landing = landingCells(state)!;
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type Landing = readonly [Cell, Cell];
-/** The Shizen hard-drop preview: the one-step rebound and where the pair locks (`finalCells`), and where each stone of the pair comes to rest once the committed drop's gravity has run (`settledCells`). */
+/** The Shizen hard-drop preview: the one-step rebound and where the pair locks (`finalCells`), and where each stone of the pair comes to rest once the committed drop's gravity has run (`settledCells`).
+ *
+ * @example
+ * ```ts
+ * import type { ChainsPowerDropPreview } from "@johnmorrisdotca/houseki/colour-chains";
+ * import { createGame, powerDropPreview } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const value: ChainsPowerDropPreview = powerDropPreview(createGame({seed:"docs",nature:true}))!;
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface ChainsPowerDropPreview extends PowerDropPreview {
     readonly settledCells: readonly NaturePieceCell[];
 }

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

@@ -1,7 +1,18 @@
 import type { ChallengeGoal, Colour, CreateOptions, Mode, Preset, Settings } from './types.js';
 declare const PRESETS: Readonly<Record<Preset, readonly [number, number]>>;
 declare const COLOURS: readonly Colour[];
-/** Typed setup and authored challenge error. */
+/** Typed setup and authored challenge error.
+ *
+ * @param code - The native stable error code used by callers to distinguish setup or replay failures.
+ * @param message - The human-readable diagnostic accompanying the native code.
+ * @example
+ * ```ts
+ * import { StoneChainsOptionsError } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const error=new StoneChainsOptionsError("docs-example","Invalid example setup");
+ * console.log(error.name,error.code,error.message);
+ * ```
+ */
 export declare class StoneChainsOptionsError extends RangeError {
     readonly code: string;
     constructor(code: string, message: string);

package/dist/colour-chains/validation.js

@@ -1,6 +1,17 @@
 const PRESETS = { narrow: [5, 12], standard: [6, 12], wide: [8, 12], tall: [6, 16], extraWide: [12, 12], deep: [8, 32], large: [12, 32] };
 const COLOURS = ['red', 'blue', 'green', 'gold', 'purple', 'teal'];
-/** Typed setup and authored challenge error. */
+/** Typed setup and authored challenge error.
+ *
+ * @param code - The native stable error code used by callers to distinguish setup or replay failures.
+ * @param message - The human-readable diagnostic accompanying the native code.
+ * @example
+ * ```ts
+ * import { StoneChainsOptionsError } from "@johnmorrisdotca/houseki/colour-chains";
+ *
+ * const error=new StoneChainsOptionsError("docs-example","Invalid example setup");
+ * console.log(error.name,error.code,error.message);
+ * ```
+ */
 export class StoneChainsOptionsError extends RangeError {
     code;
     constructor(code, message) { super(message); this.name = 'StoneChainsOptionsError'; this.code = code; }

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

@@ -1,8 +1,30 @@
 import type { ChallengeGoal, ChallengeHint, Colour, Gem, Triplet } from './types.js';
+/** One authored text in English and Japanese.
+ *
+ * @example
+ * ```ts
+ * import type { LocalizedText } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * const value: LocalizedText = {en:"A small puzzle",ja:"小さいパズル"};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface LocalizedText {
     readonly en: string;
     readonly ja: string;
 }
+/** The bounded engine measurements used to grade this campaign; they do not claim human difficulty.
+ *
+ * @example
+ * ```ts
+ * import { levelManifest } from "@johnmorrisdotca/houseki/falling-triplets";
+ * import type { DifficultyMetrics } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * const level=levelManifest[0];
+ * const value: DifficultyMetrics = level.rawMetrics;
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface DifficultyMetrics {
     readonly seededGoalSuccesses: number;
     readonly seededGoalSamples: number;
@@ -17,6 +39,18 @@ export interface DifficultyMetrics {
     readonly witnessPlanningLength: number;
     readonly payoffDirections: number;
 }
+/** One authored native challenge with its stable id, setup, winning witness, measurements and review status.
+ *
+ * @example
+ * ```ts
+ * import { levelManifest } from "@johnmorrisdotca/houseki/falling-triplets";
+ * import type { CampaignLevel } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * const level=levelManifest[0];
+ * const value: CampaignLevel = level;
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface CampaignLevel {
     readonly id: string;
     readonly seed: string;
@@ -39,6 +73,17 @@ export interface CampaignLevel {
     readonly proofStatus: 'engine-witness-verified';
     readonly reviewStatus: 'human-review-pending' | 'human-reviewed';
 }
+/** The ordered native campaign, its generation/grading revisions, checksum and measured levels.
+ *
+ * @example
+ * ```ts
+ * import type { CampaignManifest } from "@johnmorrisdotca/houseki/falling-triplets";
+ * import { campaignManifest } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * const value: CampaignManifest = campaignManifest;
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface CampaignManifest {
     readonly count: number;
     readonly candidatePoolCount: number;
@@ -52,10 +97,34 @@ export interface CampaignManifest {
     readonly checksum: string;
     readonly levels: readonly CampaignLevel[];
 }
+/** One bilingual native lesson instruction and the corresponding action or tick step.
+ *
+ * @example
+ * ```ts
+ * import { tutorialManifest } from "@johnmorrisdotca/houseki/falling-triplets";
+ * import type { TutorialStep } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * const lesson=tutorialManifest[0];
+ * const value: TutorialStep = lesson.steps[0];
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface TutorialStep {
     readonly instruction: LocalizedText;
     readonly action: string;
 }
+/** One bilingual native lesson with its authored setup, teaching steps and winning witness.
+ *
+ * @example
+ * ```ts
+ * import { tutorialManifest } from "@johnmorrisdotca/houseki/falling-triplets";
+ * import type { TutorialDefinition } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * const lesson=tutorialManifest[0];
+ * const value: TutorialDefinition = lesson;
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface TutorialDefinition {
     readonly id: string;
     readonly title: LocalizedText;

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;