@johnmorrisdotca/houseki 0.4.0 → 0.4.2

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

@@ -1,9 +1,40 @@
 import type { Colour } from './types.js';
-/** Hashes a string seed with UTF-8 FNV-1a and returns a nonzero uint32 state. */
+/** Hashes a string seed with UTF-8 FNV-1a and returns a nonzero uint32 state.
+ *
+ * @param seed - A string seed hashed into a nonzero deterministic random state.
+ * @returns Hashes a string seed with UTF-8 FNV-1a and returns a nonzero uint32 state.
+ * @example
+ * ```ts
+ * import { seedState } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * console.log(seedState("docs"));
+ * ```
+ */
 export declare function seedState(seed: string): number;
-/** Advances the reference xorshift32 source. */
+/** Advances the reference xorshift32 source.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Advances the reference xorshift32 source.
+ * @example
+ * ```ts
+ * import { nextUint32, seedState } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * console.log(nextUint32(seedState("docs")));
+ * ```
+ */
 export declare function nextUint32(state: number): readonly [number, number];
-/** Draws an unbiased integer and updated state using rejection sampling. */
+/** Draws an unbiased integer and updated state using rejection sampling.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @param n - The positive upper bound of the integer draw; the result is below this bound.
+ * @returns Draws an unbiased integer and updated state using rejection sampling.
+ * @example
+ * ```ts
+ * import { nextInt, seedState } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * console.log(nextInt(seedState("docs"),6));
+ * ```
+ */
 export declare function nextInt(state: number, n: number): readonly [number, number];
 /** Creates a shuffled bag with three of each available colour. */
 export declare function drawBag(bag: readonly Colour[], state: number, count: 4 | 5 | 6): readonly [readonly Colour[], number];

package/dist/falling-triplets/random.js

@@ -1,12 +1,32 @@
 const COLOURS = ['red', 'blue', 'green', 'gold', 'purple', 'teal'];
-/** Hashes a string seed with UTF-8 FNV-1a and returns a nonzero uint32 state. */
+/** Hashes a string seed with UTF-8 FNV-1a and returns a nonzero uint32 state.
+ *
+ * @param seed - A string seed hashed into a nonzero deterministic random state.
+ * @returns Hashes a string seed with UTF-8 FNV-1a and returns a nonzero uint32 state.
+ * @example
+ * ```ts
+ * import { seedState } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * console.log(seedState("docs"));
+ * ```
+ */
 export function seedState(seed) {
     let hash = 0x811c9dc5;
     for (const byte of new TextEncoder().encode(seed))
         hash = Math.imul(hash ^ byte, 0x01000193) >>> 0;
     return hash || 0x6d2b79f5;
 }
-/** Advances the reference xorshift32 source. */
+/** Advances the reference xorshift32 source.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @returns Advances the reference xorshift32 source.
+ * @example
+ * ```ts
+ * import { nextUint32, seedState } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * console.log(nextUint32(seedState("docs")));
+ * ```
+ */
 export function nextUint32(state) {
     let next = state >>> 0;
     next ^= next << 13;
@@ -15,7 +35,18 @@ export function nextUint32(state) {
     next >>>= 0;
     return [next, next];
 }
-/** Draws an unbiased integer and updated state using rejection sampling. */
+/** Draws an unbiased integer and updated state using rejection sampling.
+ *
+ * @param state - The immutable native state to read or transition; the input is retained.
+ * @param n - The positive upper bound of the integer draw; the result is below this bound.
+ * @returns Draws an unbiased integer and updated state using rejection sampling.
+ * @example
+ * ```ts
+ * import { nextInt, seedState } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * console.log(nextInt(seedState("docs"),6));
+ * ```
+ */
 export function nextInt(state, n) {
     if (!Number.isInteger(n) || n < 1 || n > 0x100000000)
         throw new RangeError('n must be an integer from 1 to 2^32');

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

@@ -1,13 +1,65 @@
-/** A gem colour ID. */
+/** A gem colour ID.
+ *
+ * @example
+ * ```ts
+ * import type { Colour } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * 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 gem with a stable run-local identity. */
+/** A settled or active gem with a stable run-local identity.
+ *
+ * @example
+ * ```ts
+ * import type { Gem } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * 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 target?: boolean;
 }
+/** The native game mode; authored challenges have fixed setup and queue rules.
+ *
+ * @example
+ * ```ts
+ * import type { Mode } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * 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 falling, resolution, pause and ending phases.
+ *
+ * @example
+ * ```ts
+ * import { createGame } from "@johnmorrisdotca/houseki/falling-triplets";
+ * import type { Phase } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * 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';
+/** The native falling triplet with stable gem ids, orientation, descent and lock counters.
+ *
+ * @example
+ * ```ts
+ * import { createGame } from "@johnmorrisdotca/houseki/falling-triplets";
+ * import type { Piece } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * const state=createGame({seed:"docs"});
+ * const value: Piece = state.active!;
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface Piece {
     readonly gems: readonly [Gem, Gem, Gem];
     readonly x: number;
@@ -19,6 +71,18 @@ export interface Piece {
     readonly lockResets: number;
     readonly lockStarted: boolean;
 }
+/** Validated settings fixed at native game creation.
+ *
+ * @example
+ * ```ts
+ * import { createGame } from "@johnmorrisdotca/houseki/falling-triplets";
+ * import type { Settings } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * 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;
@@ -33,35 +97,129 @@ export interface Settings {
     readonly challengeQueue?: readonly Triplet[];
     readonly witness?: readonly ChallengeHint[];
 }
+/** Three ordered gem colours composing one falling triplet.
+ *
+ * @example
+ * ```ts
+ * import type { Triplet } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * const value: Triplet = ["red","green","blue"];
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type Triplet = readonly [Colour, Colour, Colour];
+/** A Falling Triplets objective requiring the supplied stable target ids to be cleared.
+ *
+ * @example
+ * ```ts
+ * import type { ChallengeGoalTargets } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * const value: ChallengeGoalTargets = {type:"targets",targetIds:[1]};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface ChallengeGoalTargets {
     readonly type: 'targets';
     readonly targetIds: readonly number[];
 }
+/** A Falling Triplets objective requiring at least the supplied chain depth.
+ *
+ * @example
+ * ```ts
+ * import type { ChallengeGoalChain } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * const value: ChallengeGoalChain = {type:"chain",minimumChain:2};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface ChallengeGoalChain {
     readonly type: 'chain';
     readonly minimumChain: number;
 }
+/** A Falling Triplets objective requiring an empty board.
+ *
+ * @example
+ * ```ts
+ * import type { ChallengeGoalEmpty } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * const value: ChallengeGoalEmpty = {type:"empty"};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface ChallengeGoalEmpty {
     readonly type: 'empty';
 }
+/** A native authored challenge objective; its discriminant selects target, chain, empty-board or score requirements.
+ *
+ * @example
+ * ```ts
+ * import type { ChallengeGoal } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * const value: ChallengeGoal = {type:"empty"};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type ChallengeGoal = ChallengeGoalTargets | ChallengeGoalChain | ChallengeGoalEmpty;
+/** One witnessed Falling Triplets placement with a column and cycle orientation.
+ *
+ * @example
+ * ```ts
+ * import type { ChallengeHint } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * const value: ChallengeHint = {x:0,orientation:0};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface ChallengeHint {
     readonly x: number;
     readonly orientation: 0 | 1 | 2;
 }
+/** The fixed Falling Triplets challenge settings with the original board and finite triplet queue.
+ *
+ * @example
+ * ```ts
+ * import { createGame } from "@johnmorrisdotca/houseki/falling-triplets";
+ * import type { ChallengeSettings } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * const state=createGame({seed:"docs"});
+ * const value: ChallengeSettings = {...state.settings,mode:"challenge",goal:"empty",challengeBoard:state.board,challengeQueue:[["red","green","blue"]]};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface ChallengeSettings extends Settings {
     readonly mode: 'challenge';
     readonly goal: ChallengeGoal['type'];
     readonly challengeBoard: readonly (Gem | null)[];
     readonly challengeQueue: readonly Triplet[];
 }
+/** One simultaneous native match wave, its cleared cells and chain score.
+ *
+ * @example
+ * ```ts
+ * import type { Wave } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * const value: Wave = {chain:1,cells:[],points:0,clearedIds:[]};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface Wave {
     readonly clearedIds: readonly number[];
     readonly cells: readonly number[];
     readonly chain: number;
     readonly points: number;
 }
+/** The immutable authoritative native game state, including its board, random state and recording.
+ *
+ * @example
+ * ```ts
+ * import { createGame } from "@johnmorrisdotca/houseki/falling-triplets";
+ * import type { GameState } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * 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: 'falling-triplets';
     readonly rules: 'triplets-1';
@@ -92,16 +250,50 @@ export interface GameState {
     readonly recording: readonly RecordedAction[];
     readonly reason?: string;
 }
+/** A native player action accepted or rejected according to the current phase and rules.
+ *
+ * @example
+ * ```ts
+ * import type { Action } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * 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 = {
     readonly kind: 'left' | 'right' | 'soft-drop' | 'hard-drop' | 'place' | 'cycle-forward' | 'cycle-backward' | 'pause' | 'resume' | 'hint' | 'tick';
 };
+/** The resulting native state, emitted events and acceptance decision; rejected actions preserve the input.
+ *
+ * @example
+ * ```ts
+ * import { applyAction, createGame } from "@johnmorrisdotca/houseki/falling-triplets";
+ * import type { Action, Transition } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * 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;
 }
-/** One accepted canonical action and its logical tick position. */
+/** One accepted canonical action and its logical tick position.
+ *
+ * @example
+ * ```ts
+ * import type { Action, RecordedAction } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * 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;
@@ -109,10 +301,30 @@ export interface RecordedAction {
         readonly kind: 'tick';
     }>;
 }
+/** An event emitted by one native transition; type selects the event’s additional fields.
+ *
+ * @example
+ * ```ts
+ * import type { GameEvent } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * 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;
 }
+/** Creation settings for this native engine; dimensions, mode, seed and optional mechanics are validated together.
+ *
+ * @example
+ * ```ts
+ * import type { CreateOptions } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * 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;
@@ -122,6 +334,18 @@ export interface CreateOptions {
     readonly colourCount?: 4 | 5 | 6;
     readonly pieceLimit?: number;
 }
+/** Authored challenge inputs including the starting board, finite goal and supplied witness.
+ *
+ * @example
+ * ```ts
+ * import { createGame } from "@johnmorrisdotca/houseki/falling-triplets";
+ * import type { ChallengeOptions } from "@johnmorrisdotca/houseki/falling-triplets";
+ *
+ * const state=createGame({seed:"docs"});
+ * const value: ChallengeOptions = {width:6,height:12,board:state.board,queue:[["red","green","blue"]],goal:{type:"empty"}};
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface ChallengeOptions {
     readonly seed?: string;
     readonly width?: number;

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

@@ -1,5 +1,27 @@
 import type { Action, CreateOptions, ReplayOperation } from './types.js';
+/** The existing campaign’s human-review-pending status; an engine witness is not human review.
+ *
+ * @example
+ * ```ts
+ * import type { GemSwapReviewStatus } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const value: GemSwapReviewStatus = "human-review-pending";
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type GemSwapReviewStatus = 'human-review-pending';
+/** One authored native challenge with its stable id, setup, winning witness, measurements and review status.
+ *
+ * @example
+ * ```ts
+ * import { GEM_SWAP_CAMPAIGN } from "@johnmorrisdotca/houseki/gem-swap";
+ * import type { GemSwapCampaignLevel } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const level=GEM_SWAP_CAMPAIGN[0];
+ * const value: GemSwapCampaignLevel = level;
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface GemSwapCampaignLevel {
     readonly id: string;
     readonly number: number;
@@ -23,6 +45,17 @@ export interface GemSwapCampaignLevel {
     readonly proofStatus: 'engine-witness-verified';
     readonly reviewStatus: GemSwapReviewStatus;
 }
+/** One bilingual native lesson instruction and the corresponding action or tick step.
+ *
+ * @example
+ * ```ts
+ * import type { GemSwapLessonStep } from "@johnmorrisdotca/houseki/gem-swap";
+ * import { GEM_SWAP_LESSONS } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const value: GemSwapLessonStep = GEM_SWAP_LESSONS[0].steps[0];
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export type GemSwapLessonStep = {
     readonly kind: 'action';
     readonly id: string;
@@ -47,6 +80,17 @@ export type GemSwapLessonStep = {
         readonly ja: string;
     };
 };
+/** One bilingual native lesson with its authored setup, teaching steps and winning witness.
+ *
+ * @example
+ * ```ts
+ * import type { GemSwapLesson } from "@johnmorrisdotca/houseki/gem-swap";
+ * import { GEM_SWAP_LESSONS } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * const value: GemSwapLesson = GEM_SWAP_LESSONS[0];
+ * console.log(value == null ? value : typeof value === "object" ? Object.keys(value).slice(0,6) : value);
+ * ```
+ */
 export interface GemSwapLesson {
     readonly id: string;
     readonly title: {
@@ -58,9 +102,45 @@ export interface GemSwapLesson {
     readonly witness: readonly ReplayOperation[];
     readonly reviewStatus: GemSwapReviewStatus;
 }
+/** The stored Gem Swap campaign generation revision.
+ *
+ * @example
+ * ```ts
+ * import { GENERATION_REVISION } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * console.log(GENERATION_REVISION);
+ * ```
+ */
 export declare const GENERATION_REVISION = "gem-swap-campaign-1.3.0";
+/** The measurement/normalization revision used to grade Gem Swap challenges.
+ *
+ * @example
+ * ```ts
+ * import { GRADING_VERSION } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * console.log(GRADING_VERSION);
+ * ```
+ */
 export declare const GRADING_VERSION = "swap-choice-forgiveness-1";
+/** The fixed number of seeded playout samples used in the stored Gem Swap grading.
+ *
+ * @example
+ * ```ts
+ * import { SAMPLE_BUDGET } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * console.log(SAMPLE_BUDGET);
+ * ```
+ */
 export declare const SAMPLE_BUDGET = 24;
+/** The bounded Gem Swap metric weights used in the recorded grading formula.
+ *
+ * @example
+ * ```ts
+ * import { GRADING_WEIGHTS } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * console.log(Object.keys(GRADING_WEIGHTS));
+ * ```
+ */
 export declare const GRADING_WEIGHTS: {
     seededPlayoutDifficulty: number;
     choiceDifficulty: number;
@@ -69,7 +149,43 @@ export declare const GRADING_WEIGHTS: {
     witnessLength: number;
     specialCombination: number;
 };
+/** The stored Gem Swap campaign content fingerprint.
+ *
+ * @example
+ * ```ts
+ * import { CAMPAIGN_CHECKSUM } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * console.log(CAMPAIGN_CHECKSUM);
+ * ```
+ */
 export declare const CAMPAIGN_CHECKSUM = "eb7c54a583db428d596b8fbdab0d63a9ad39ad5b9e39948dc4ccab84ba1196aa";
+/** The number of stored Gem Swap campaign challenges.
+ *
+ * @example
+ * ```ts
+ * import { CAMPAIGN_COUNT } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * console.log(CAMPAIGN_COUNT);
+ * ```
+ */
 export declare const CAMPAIGN_COUNT = 50;
+/** The frozen measured Gem Swap challenges with stable ids, setups, witnesses and review status.
+ *
+ * @example
+ * ```ts
+ * import { GEM_SWAP_CAMPAIGN } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * console.log(GEM_SWAP_CAMPAIGN.length);
+ * ```
+ */
 export declare const GEM_SWAP_CAMPAIGN: readonly GemSwapCampaignLevel[];
+/** The frozen bilingual Gem Swap lessons with setup, teaching steps and witnesses.
+ *
+ * @example
+ * ```ts
+ * import { GEM_SWAP_LESSONS } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * console.log(GEM_SWAP_LESSONS.length);
+ * ```
+ */
 export declare const GEM_SWAP_LESSONS: readonly GemSwapLesson[];

package/dist/gem-swap/content.js

@@ -3,12 +3,75 @@ function freezeContent(value) { if (value && typeof value === 'object' && !Objec
     for (const item of Object.values(value))
         freezeContent(item);
 } return value; }
+/** The stored Gem Swap campaign generation revision.
+ *
+ * @example
+ * ```ts
+ * import { GENERATION_REVISION } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * console.log(GENERATION_REVISION);
+ * ```
+ */
 export const GENERATION_REVISION = "gem-swap-campaign-1.3.0";
+/** The measurement/normalization revision used to grade Gem Swap challenges.
+ *
+ * @example
+ * ```ts
+ * import { GRADING_VERSION } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * console.log(GRADING_VERSION);
+ * ```
+ */
 export const GRADING_VERSION = "swap-choice-forgiveness-1";
+/** The fixed number of seeded playout samples used in the stored Gem Swap grading.
+ *
+ * @example
+ * ```ts
+ * import { SAMPLE_BUDGET } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * console.log(SAMPLE_BUDGET);
+ * ```
+ */
 export const SAMPLE_BUDGET = 24;
+/** The bounded Gem Swap metric weights used in the recorded grading formula.
+ *
+ * @example
+ * ```ts
+ * import { GRADING_WEIGHTS } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * console.log(Object.keys(GRADING_WEIGHTS));
+ * ```
+ */
 export const GRADING_WEIGHTS = freezeContent({ "seededPlayoutDifficulty": 30, "choiceDifficulty": 18, "objectiveCoordination": 12, "chainDepth": 10, "witnessLength": 25, "specialCombination": 5 });
+/** The stored Gem Swap campaign content fingerprint.
+ *
+ * @example
+ * ```ts
+ * import { CAMPAIGN_CHECKSUM } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * console.log(CAMPAIGN_CHECKSUM);
+ * ```
+ */
 export const CAMPAIGN_CHECKSUM = "eb7c54a583db428d596b8fbdab0d63a9ad39ad5b9e39948dc4ccab84ba1196aa";
+/** The number of stored Gem Swap campaign challenges.
+ *
+ * @example
+ * ```ts
+ * import { CAMPAIGN_COUNT } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * console.log(CAMPAIGN_COUNT);
+ * ```
+ */
 export const CAMPAIGN_COUNT = 50;
+/** The frozen measured Gem Swap challenges with stable ids, setups, witnesses and review status.
+ *
+ * @example
+ * ```ts
+ * import { GEM_SWAP_CAMPAIGN } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * console.log(GEM_SWAP_CAMPAIGN.length);
+ * ```
+ */
 export const GEM_SWAP_CAMPAIGN = freezeContent([
     { "id": "swap-03d5fd388b09", "number": 1, "title": { "en": "Clear Horizon", "ja": "晴れた地平" }, "options": { "mode": "challenge", "preset": "compact", "seed": 11, "challenge": { "moveLimit": 1, "goals": [{ "kind": "score", "target": 30 }] } }, "width": 6, "height": 6, "colourCount": 5, "seed": 11, "challenge": { "moveLimit": 1, "goals": [{ "kind": "score", "target": 30 }] }, "witness": [{ "kind": "action", "action": { "kind": "swap", "from": 26, "to": 27 } }, { "kind": "ticks", "count": 3600 }], "canonicalKeyHash": "25637ca705ea4e9aef83f2b58b5944c49cb8fa5dee8f3f3a3cc7b00bd45d5a1d", "tags": ["score"], "rawMetrics": { "legalSwapCount": 8, "initiallyProgressingSwaps": 8, "initialProgressingShare": 1, "seededPlayoutSamples": 24, "seededPlayoutSuccessRate": 1, "objectiveCount": 1, "requiredChainDepth": 1, "sealLayers": 0, "witnessMoves": 1, "planningLength": 1, "specialCreations": 0, "specialActivations": 0, "specialCombinations": 0, "difficultyScore": 0 }, "difficultyScore": 0, "difficultyMarks": 1, "gradingVersion": "swap-choice-forgiveness-1", "proofStatus": "engine-witness-verified", "reviewStatus": "human-review-pending" },
     { "id": "swap-a0f21f37725a", "number": 2, "title": { "en": "Quiet Current", "ja": "静かな流れ" }, "options": { "mode": "challenge", "preset": "compact", "seed": 0, "challenge": { "moveLimit": 1, "goals": [{ "kind": "score", "target": 30 }] } }, "width": 6, "height": 6, "colourCount": 5, "seed": 0, "challenge": { "moveLimit": 1, "goals": [{ "kind": "score", "target": 30 }] }, "witness": [{ "kind": "action", "action": { "kind": "swap", "from": 22, "to": 23 } }, { "kind": "ticks", "count": 3600 }], "canonicalKeyHash": "18c1e827e012b7e7b86959c46cab081fa0ceec239ddc35d40bc23463c83d17c1", "tags": ["score"], "rawMetrics": { "legalSwapCount": 10, "initiallyProgressingSwaps": 10, "initialProgressingShare": 1, "seededPlayoutSamples": 24, "seededPlayoutSuccessRate": 1, "objectiveCount": 1, "requiredChainDepth": 1, "sealLayers": 0, "witnessMoves": 1, "planningLength": 1, "specialCreations": 0, "specialActivations": 0, "specialCombinations": 0, "difficultyScore": 0 }, "difficultyScore": 0, "difficultyMarks": 1, "gradingVersion": "swap-choice-forgiveness-1", "proofStatus": "engine-witness-verified", "reviewStatus": "human-review-pending" },
@@ -61,6 +124,15 @@ export const GEM_SWAP_CAMPAIGN = freezeContent([
     { "id": "swap-454ad7e8d1bd", "number": 49, "title": { "en": "Final Echo", "ja": "最後の反響" }, "options": { "mode": "challenge", "preset": "compact", "seed": 57, "challenge": { "moveLimit": 6, "goals": [{ "kind": "chain", "target": 6 }] } }, "width": 6, "height": 6, "colourCount": 5, "seed": 57, "challenge": { "moveLimit": 6, "goals": [{ "kind": "chain", "target": 6 }] }, "witness": [{ "kind": "action", "action": { "kind": "swap", "from": 20, "to": 21 } }, { "kind": "ticks", "count": 3600 }, { "kind": "action", "action": { "kind": "swap", "from": 16, "to": 17 } }, { "kind": "ticks", "count": 3600 }, { "kind": "action", "action": { "kind": "swap", "from": 27, "to": 28 } }, { "kind": "ticks", "count": 3600 }, { "kind": "action", "action": { "kind": "swap", "from": 22, "to": 23 } }, { "kind": "ticks", "count": 3600 }, { "kind": "action", "action": { "kind": "swap", "from": 18, "to": 24 } }, { "kind": "ticks", "count": 3600 }, { "kind": "action", "action": { "kind": "swap", "from": 20, "to": 26 } }, { "kind": "ticks", "count": 3600 }], "canonicalKeyHash": "72cd52768321ddfa4ac2b40a347fd8597f157dba1c3e961c946e60a8ac2795e9", "tags": ["chain", "multi-move-planning", "cascade", "special-creation", "special-combination"], "rawMetrics": { "legalSwapCount": 8, "initiallyProgressingSwaps": 8, "initialProgressingShare": 1, "seededPlayoutSamples": 24, "seededPlayoutSuccessRate": 0.041667, "objectiveCount": 1, "requiredChainDepth": 6, "sealLayers": 0, "witnessMoves": 6, "planningLength": 6, "specialCreations": 4, "specialActivations": 1, "specialCombinations": 1, "difficultyScore": 68.75 }, "difficultyScore": 68.75, "difficultyMarks": 4, "gradingVersion": "swap-choice-forgiveness-1", "proofStatus": "engine-witness-verified", "reviewStatus": "human-review-pending" },
     { "id": "swap-4c6462480f21", "number": 50, "title": { "en": "Final Marks", "ja": "最後の印" }, "options": { "mode": "challenge", "preset": "compact", "seed": 18, "challenge": { "moveLimit": 5, "goals": [{ "kind": "seals" }], "seals": [{ "cell": 26, "layers": 1 }, { "cell": 32, "layers": 1 }, { "cell": 33, "layers": 1 }] } }, "width": 6, "height": 6, "colourCount": 5, "seed": 18, "challenge": { "moveLimit": 5, "goals": [{ "kind": "seals" }], "seals": [{ "cell": 26, "layers": 1 }, { "cell": 32, "layers": 1 }, { "cell": 33, "layers": 1 }] }, "witness": [{ "kind": "action", "action": { "kind": "swap", "from": 18, "to": 19 } }, { "kind": "ticks", "count": 3600 }, { "kind": "action", "action": { "kind": "swap", "from": 2, "to": 8 } }, { "kind": "ticks", "count": 3600 }, { "kind": "action", "action": { "kind": "swap", "from": 31, "to": 32 } }, { "kind": "ticks", "count": 3600 }, { "kind": "action", "action": { "kind": "swap", "from": 1, "to": 2 } }, { "kind": "ticks", "count": 3600 }, { "kind": "action", "action": { "kind": "swap", "from": 19, "to": 20 } }, { "kind": "ticks", "count": 3600 }], "canonicalKeyHash": "db177c8ae220211fc4624a140687c5f1dc1f4b128d2c958123de3d564ce98904", "tags": ["seals", "multi-move-planning", "cascade", "special-creation"], "rawMetrics": { "legalSwapCount": 11, "initiallyProgressingSwaps": 1, "initialProgressingShare": 0.09090909090909091, "seededPlayoutSamples": 24, "seededPlayoutSuccessRate": 0.041667, "objectiveCount": 1, "requiredChainDepth": 1, "sealLayers": 3, "witnessMoves": 5, "planningLength": 5, "specialCreations": 2, "specialActivations": 0, "specialCombinations": 0, "difficultyScore": 71.11 }, "difficultyScore": 71.11, "difficultyMarks": 4, "gradingVersion": "swap-choice-forgiveness-1", "proofStatus": "engine-witness-verified", "reviewStatus": "human-review-pending" }
 ]);
+/** The frozen bilingual Gem Swap lessons with setup, teaching steps and witnesses.
+ *
+ * @example
+ * ```ts
+ * import { GEM_SWAP_LESSONS } from "@johnmorrisdotca/houseki/gem-swap";
+ *
+ * console.log(GEM_SWAP_LESSONS.length);
+ * ```
+ */
 export const GEM_SWAP_LESSONS = freezeContent([
     { "id": "gem-swap-lesson-basics", "title": { "en": "Make a match", "ja": "マッチを作る" }, "initial": { "preset": "compact", "seed": 8001 }, "steps": [{ "kind": "action", "id": "invalid-return", "action": { "kind": "swap", "from": 0, "to": 1 }, "accepted": false, "reason": "swap-makes-no-match", "text": { "en": "This pair makes no line of three, so it returns unchanged.", "ja": "3つ並ばないため、この交換は元に戻ります。" } }, { "kind": "action", "id": "first-match", "action": { "kind": "swap", "from": 1, "to": 7 }, "accepted": true, "event": "match-marked", "text": { "en": "Swap neighbouring gems to make a line of three.", "ja": "隣り合う宝石を交換して、3つ並べましょう。" } }, { "kind": "ticks", "id": "watch-refill", "count": 3600, "text": { "en": "Watch the cleared cells refill before the next turn.", "ja": "次の手の前に、消えた場所が補充される様子を見ましょう。" } }], "witness": [{ "kind": "action", "action": { "kind": "swap", "from": 1, "to": 7 } }, { "kind": "ticks", "count": 3600 }], "reviewStatus": "human-review-pending" },
     { "id": "gem-swap-lesson-beam", "title": { "en": "Create and use a beam", "ja": "ビームを作って使う" }, "initial": { "preset": "compact", "seed": 1 }, "steps": [{ "kind": "action", "id": "plan-beam", "action": { "kind": "swap", "from": 26, "to": 32 }, "accepted": true, "event": "special-planned", "text": { "en": "A line of four plans a beam at its marked anchor.", "ja": "4つの列がそろうと、印の位置にビームが作られます。" } }, { "kind": "ticks", "id": "create-beam", "count": 3600, "event": "special-created", "text": { "en": "Let the clear finish; the beam stays on the board.", "ja": "消去が終わると、ビームが盤面に残ります。" } }, { "kind": "action", "id": "activate-beam", "action": { "kind": "swap", "from": 15, "to": 21 }, "accepted": true, "event": "match-marked", "text": { "en": "Make a match that reaches the beam to clear its line.", "ja": "ビームに届くマッチを作り、その列を消しましょう。" } }, { "kind": "ticks", "id": "finish-beam", "count": 3600, "event": "special-activated", "text": { "en": "Watch the beam clear its line and the board refill.", "ja": "ビームが列を消し、盤面が補充される様子を見ましょう。" } }], "witness": [{ "kind": "action", "action": { "kind": "swap", "from": 26, "to": 32 } }, { "kind": "ticks", "count": 3600 }, { "kind": "action", "action": { "kind": "swap", "from": 15, "to": 21 } }, { "kind": "ticks", "count": 3600 }], "reviewStatus": "human-review-pending" },