@johnmorrisdotca/houseki 0.4.0 → 0.4.2

package/dist/gem-swap/types.d.ts

@@ -1,30 +1,174 @@
-/** A colour used by a normal gem. */
+/** A colour used by a normal gem.
+ *
+ * @example
+ * ```ts
+ * import type { GemColour } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const value: GemColour = "red";
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type GemColour = 'red' | 'blue' | 'green' | 'gold' | 'purple' | 'teal';
+/** A Gem Swap beam, bomb or colour-burst special retained at its chosen anchor.
+ *
+ * @example
+ * ```ts
+ * import type { SpecialKind } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const value: SpecialKind = "row-beam";
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type SpecialKind = 'row-beam' | 'column-beam' | 'bomb' | 'colour-burst';
+/** A Gem Swap stored tool or advanced Black Hole selection.
+ *
+ * @example
+ * ```ts
+ * import type { ToolKind } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const value: ToolKind = "bomb";
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type ToolKind = 'bomb' | 'row-clear' | 'colour-clear' | 'black-hole';
+/** A Gem Swap stored tool excluding the separately charged Black Hole.
+ *
+ * @example
+ * ```ts
+ * import type { OrdinaryToolKind } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const value: OrdinaryToolKind = "bomb";
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type OrdinaryToolKind = Exclude<ToolKind, 'black-hole'>;
+/** The native remaining counts of stored tools.
+ *
+ * @example
+ * ```ts
+ * import { createGame } from "@johnmorrisdotca/houseki/gem-swap";
+ * import type { ToolInventory } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const state=createGame({seed:"docs"});
+ * const value: ToolInventory = state.inventory;
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type ToolInventory = Readonly<Record<OrdinaryToolKind, number>>;
+/** A Gem Swap portal’s cell, remaining capacity, move lifetime and consumed stable ids.
+ *
+ * @example
+ * ```ts
+ * import type { BlackHolePortal } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const value: BlackHolePortal = {cell:0,capacityRemaining:2,movesRemaining:2,consumedIds:[]};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface BlackHolePortal {
     readonly cell: number;
     readonly capacityRemaining: number;
     readonly movesRemaining: number;
     readonly consumedIds: readonly number[];
 }
-/** A gem has a stable identity and stored colour until it is cleared. Missing kind means normal. */
+/** A gem has a stable identity and stored colour until it is cleared. Missing kind means normal.
+ *
+ * @example
+ * ```ts
+ * import type { Gem } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * 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: GemColour;
     readonly kind?: SpecialKind;
 }
+/** The native Gem Swap cell and special kind planned for the end of a clear wave.
+ *
+ * @example
+ * ```ts
+ * import type { PlannedSpecial } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const value: PlannedSpecial = {cell:0,kind:"row-beam"};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface PlannedSpecial {
     readonly cell: number;
     readonly kind: SpecialKind;
 }
+/** A named native board geometry; custom dimensions remain a separate option.
+ *
+ * @example
+ * ```ts
+ * import type { BoardPreset } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const value: BoardPreset = "compact";
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type BoardPreset = 'compact' | 'standard' | 'wide' | 'tall' | 'extraWide' | 'deep' | 'large';
+/** A native shaped active-cell layout applied to the row-major board.
+ *
+ * @example
+ * ```ts
+ * import type { BoardShape } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const value: BoardShape = "heart";
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type BoardShape = 'heart' | 'star' | 'hexagon';
+/** The native ready, resolution and ending phases.
+ *
+ * @example
+ * ```ts
+ * import { createGame } from "@johnmorrisdotca/houseki/gem-swap";
+ * import type { GamePhase } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const state=createGame({seed:"docs"});
+ * const value: GamePhase = state.phase;
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type GamePhase = 'ready' | 'clear-mark' | 'clear-remove' | 'gravity' | 'refill' | 'finished';
+/** The native free, timed, daily or authored-challenge game mode.
+ *
+ * @example
+ * ```ts
+ * import type { GameMode } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const value: GameMode = "relaxed";
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type GameMode = 'relaxed' | 'arcade' | 'daily' | 'challenge';
+/** The terminal outcome; null means the run has no terminal outcome yet.
+ *
+ * @example
+ * ```ts
+ * import { createGame } from "@johnmorrisdotca/houseki/gem-swap";
+ * import type { GameOutcome } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const state=createGame({seed:"docs"});
+ * const value: GameOutcome = state.outcome;
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type GameOutcome = 'won' | 'lost' | 'finished' | null;
+/** The native authored goal; its discriminant selects the required collection or clearing condition.
+ *
+ * @example
+ * ```ts
+ * import type { Goal } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const value: Goal = {kind:"score",target:100};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type Goal = {
     readonly kind: 'score';
     readonly target: number;
@@ -38,15 +182,45 @@ export type Goal = {
 } | {
     readonly kind: 'seals';
 };
+/** A Gem Swap row-major seal cell and its remaining layers.
+ *
+ * @example
+ * ```ts
+ * import type { Seal } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const value: Seal = {cell:0,layers:1};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface Seal {
     readonly cell: number;
     readonly layers: number;
 }
+/** Gem Swap authored goals, optional move budget and seal layout.
+ *
+ * @example
+ * ```ts
+ * import type { ChallengeRules } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const value: ChallengeRules = {goals:[{kind:"score",target:100}],moveLimit:5};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface ChallengeRules {
     readonly goals: readonly Goal[];
     readonly moveLimit?: number;
     readonly seals?: readonly Seal[];
 }
+/** One native Gem Swap action, fixed-tick advance or elapsed-time replay operation.
+ *
+ * @example
+ * ```ts
+ * import type { ReplayOperation } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const value: ReplayOperation = {kind:"ticks",count:1};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type ReplayOperation = {
     readonly kind: 'action';
     readonly action: Action;
@@ -57,6 +231,18 @@ export type ReplayOperation = {
     readonly kind: 'time';
     readonly milliseconds: number;
 };
+/** Validated settings fixed at native game creation.
+ *
+ * @example
+ * ```ts
+ * import { createGame } from "@johnmorrisdotca/houseki/gem-swap";
+ * import type { Settings } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * 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 width: number;
     readonly height: number;
@@ -67,6 +253,18 @@ export interface Settings {
     readonly shape?: BoardShape;
     readonly mask: readonly boolean[];
 }
+/** The immutable authoritative native game state, including its board, random state and recording.
+ *
+ * @example
+ * ```ts
+ * import { createGame } from "@johnmorrisdotca/houseki/gem-swap";
+ * import type { GameState } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * 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: 'gem-swap';
     readonly rules: 'swap-1';
@@ -112,46 +310,169 @@ export interface GameState {
     readonly blackHoleContactPending: boolean;
     readonly pendingBlackHole: boolean;
 }
-/** Swaps two row-major cell addresses. */
+/** Swaps two row-major cell addresses.
+ *
+ * @example
+ * ```ts
+ * import type { SwapAction } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const value: SwapAction = {kind:"swap",from:0,to:1};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface SwapAction {
     readonly kind: 'swap';
     readonly from: number;
     readonly to: number;
 }
+/** Selects a stored Gem Swap tool without committing its target.
+ *
+ * @example
+ * ```ts
+ * import type { SelectToolAction } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const value: SelectToolAction = {kind:"select-tool",tool:"bomb"};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface SelectToolAction {
     readonly kind: 'select-tool';
     readonly tool: ToolKind;
 }
+/** Previews a selected Gem Swap tool on one row-major cell.
+ *
+ * @example
+ * ```ts
+ * import type { TargetToolAction } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const value: TargetToolAction = {kind:"target-tool",cell:0};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface TargetToolAction {
     readonly kind: 'target-tool';
     readonly cell: number;
 }
+/** Commits the currently selected Gem Swap tool and target.
+ *
+ * @example
+ * ```ts
+ * import type { ConfirmToolAction } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const value: ConfirmToolAction = {kind:"confirm-tool"};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface ConfirmToolAction {
     readonly kind: 'confirm-tool';
 }
+/** Clears the current Gem Swap tool preview.
+ *
+ * @example
+ * ```ts
+ * import type { CancelToolAction } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const value: CancelToolAction = {kind:"cancel-tool"};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface CancelToolAction {
     readonly kind: 'cancel-tool';
 }
+/** Requests restoration of the prior Gem Swap move.
+ *
+ * @example
+ * ```ts
+ * import type { UndoAction } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const value: UndoAction = {kind:"undo"};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface UndoAction {
     readonly kind: 'undo';
 }
+/** Requests a native Gem Swap hint and marks assisted play.
+ *
+ * @example
+ * ```ts
+ * import type { HintAction } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const value: HintAction = {kind:"hint"};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface HintAction {
     readonly kind: 'hint';
 }
+/** Requests a native Gem Swap recovery shuffle.
+ *
+ * @example
+ * ```ts
+ * import type { ReshuffleAction } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const value: ReshuffleAction = {kind:"reshuffle"};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface ReshuffleAction {
     readonly kind: 'reshuffle';
 }
+/** A native player action accepted or rejected according to the current phase and rules.
+ *
+ * @example
+ * ```ts
+ * import type { Action } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const action: Action={kind:"hint"};
+ * const value: Action = action;
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type Action = SwapAction | SelectToolAction | TargetToolAction | ConfirmToolAction | CancelToolAction | UndoAction | HintAction | ReshuffleAction;
+/** An event emitted by one native transition; type selects the event’s additional fields.
+ *
+ * @example
+ * ```ts
+ * import type { GameEvent } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * 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;
 }
+/** The resulting native state, emitted events and acceptance decision; rejected actions preserve the input.
+ *
+ * @example
+ * ```ts
+ * import { applyAction, createGame } from "@johnmorrisdotca/houseki/gem-swap";
+ * import type { Action, Transition } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const state=createGame({seed:"docs"});
+ * const action: Action={kind:"hint"};
+ * 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;
 }
+/** Creation settings for this native engine; dimensions, mode, seed and optional mechanics are validated together.
+ *
+ * @example
+ * ```ts
+ * import type { CreateOptions } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const value: CreateOptions = {seed:"docs"};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface CreateOptions {
     readonly preset?: BoardPreset;
     readonly width?: number;
@@ -169,6 +490,18 @@ export interface CreateOptions {
     /** Challenge-only finite goals and optional legal-swap budget. */
     readonly challenge?: ChallengeRules;
 }
+/** A compact native status derived from the authoritative state for a host’s labels.
+ *
+ * @example
+ * ```ts
+ * import { createGame, statusOf } from "@johnmorrisdotca/houseki/gem-swap";
+ * import type { GameStatus } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * 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 phase: GamePhase;
     readonly score: number;

package/dist/magnetic-blocks/content-types.d.ts

@@ -1,8 +1,30 @@
 import type { Action, Colour, CreateOptions, Floor, GameState, Gem } from './types.js';
+/** One authored text in English and Japanese.
+ *
+ * @example
+ * ```ts
+ * import type { LocalizedText } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * 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/magnetic-blocks";
+ * import type { MagneticDifficultyMetrics } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const level=levelManifest[0];
+ * const value: MagneticDifficultyMetrics = level.metrics;
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface MagneticDifficultyMetrics {
     readonly legalPlacementChoices: number;
     readonly setupPlacementChoices: number;
@@ -39,6 +61,18 @@ export interface MagneticDifficultyMetrics {
     };
 }
 export type MagneticDifficultyBand = 'entry' | 'easy' | 'intermediate' | 'hard' | 'expert';
+/** One authored native challenge with its stable id, setup, winning witness, measurements and review status.
+ *
+ * @example
+ * ```ts
+ * import { levelManifest } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ * import type { MagneticCampaignLevel } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const level=levelManifest[0];
+ * const value: MagneticCampaignLevel = level;
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface MagneticCampaignLevel {
     readonly id: string;
     readonly number: number;
@@ -67,6 +101,17 @@ export interface MagneticCampaignLevel {
         readonly disabledImpactResult: 'won';
     };
 }
+/** The ordered native campaign, its generation/grading revisions, checksum and measured levels.
+ *
+ * @example
+ * ```ts
+ * import type { MagneticCampaignManifest } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ * import { campaignManifest } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const value: MagneticCampaignManifest = campaignManifest;
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface MagneticCampaignManifest {
     readonly count: number;
     readonly currentCount?: number;
@@ -86,6 +131,17 @@ export interface MagneticCampaignManifest {
         readonly last: number;
     }[];
 }
+/** One bilingual native lesson with its authored setup, teaching steps and winning witness.
+ *
+ * @example
+ * ```ts
+ * import type { MagneticLesson } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ * import { lessonManifest } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * const value: MagneticLesson = lessonManifest[0];
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface MagneticLesson {
     readonly id: string;
     readonly title: LocalizedText;

package/dist/magnetic-blocks/content.d.ts

@@ -1,16 +1,102 @@
 import type { MagneticCampaignLevel, MagneticCampaignManifest, MagneticLesson } 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/magnetic-blocks";
+ *
+ * console.log(campaignManifest.count);
+ * ```
+ */
 export declare const campaignManifest: MagneticCampaignManifest;
+/** The frozen ordered native levels; array indices start at zero and display numbers start at one.
+ *
+ * @example
+ * ```ts
+ * import { levelManifest } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * console.log(levelManifest.length);
+ * ```
+ */
 export declare const levelManifest: readonly MagneticCampaignLevel[];
-/** Alias kept alongside other Houseki campaign lesson APIs. */
+/** Alias kept alongside other Houseki campaign lesson APIs.
+ *
+ * @example
+ * ```ts
+ * import { tutorialManifest } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * console.log(tutorialManifest.length);
+ * ```
+ */
 export declare const tutorialManifest: readonly MagneticLesson[];
+/** The frozen native bilingual lessons and their authored teaching steps.
+ *
+ * @example
+ * ```ts
+ * import { lessonManifest } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * console.log(lessonManifest.length);
+ * ```
+ */
 export declare const lessonManifest: readonly MagneticLesson[];
-/** Finds a Magnetic Blocks campaign level by stable ID or one-based display number. */
+/** Finds a Magnetic Blocks campaign level 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 Finds a Magnetic Blocks campaign level by stable ID or one-based display number. Returns undefined when the id or display number is absent.
+ * @example
+ * ```ts
+ * import { getLevel } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * console.log(getLevel(1)?.id);
+ * ```
+ */
 export declare function getLevel(id: string | number): MagneticCampaignLevel | undefined;
-/** Creates a fresh game with the authored rules, board, queue, and finite move budget. */
+/** Creates a fresh game with the authored rules, board, queue, and finite move budget.
+ *
+ * @param id - A stable content id, or the one-based display number when numbers are accepted.
+ * @returns Creates a fresh game with the authored rules, board, queue, and finite move budget.
+ * @example
+ * ```ts
+ * import { createLevel } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * console.log(createLevel(1).phase);
+ * ```
+ */
 export declare function createLevel(id: string | number): GameState;
-/** Finds one of the three bilingual rules lessons by stable ID. */
+/** Finds one of the three bilingual rules lessons by stable ID.
+ *
+ * @param id - A stable content id, or the one-based display number when numbers are accepted.
+ * @returns Finds one of the three bilingual rules lessons by stable ID. Returns undefined when the id or display number is absent.
+ * @example
+ * ```ts
+ * import { getLesson, lessonManifest } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * console.log(getLesson(lessonManifest[0].id)?.id);
+ * ```
+ */
 export declare function getLesson(id: string): MagneticLesson | undefined;
+/** Find a magnetic-block lesson by stable id; returns undefined when no lesson has that id.
+ *
+ * @param id - A stable content id, or the one-based display number when numbers are accepted.
+ * @returns Find a magnetic-block lesson by stable id; returns undefined when no lesson has that id. Returns undefined when the id or display number is absent.
+ * @example
+ * ```ts
+ * import { getTutorial, lessonManifest } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * console.log(getTutorial(lessonManifest[0].id)?.id);
+ * ```
+ */
 export declare const getTutorial: typeof getLesson;
-/** Creates a fresh lesson game with its authored setup and queue. */
+/** Creates a fresh lesson game with its authored setup and queue.
+ *
+ * @param id - A stable content id, or the one-based display number when numbers are accepted.
+ * @returns Creates a fresh lesson game with its authored setup and queue.
+ * @example
+ * ```ts
+ * import { createLesson, lessonManifest } from "@johnmorrisdotca/houseki/magnetic-blocks";
+ *
+ * console.log(createLesson(lessonManifest[0].id).phase);
+ * ```
+ */
 export declare function createLesson(id: string): GameState;