Tobiishi API reference: every export, with its signature

`@johnmorrisdotca/tobiishi`

Board boardOf Cell Challenge ChallengeDifficulty challengeOf ChallengePack classicEnglish classicTriangle Game gameCode gameFromCode generate generateTobiishiChallenge GoalChallenge GoalHole isGameSolved isGameStuck Jump jumpAt legalJumps makeBoard markHelped newGame pegCount rectangleBoard restart seededRandom Shape SHAPES Solution solve SQUARE_STEPS TOBIISHI_CHALLENGE_PACKS TRIANGLE_STEPS undo VERSION

type Board

type Board = Readonly<{ name: string; lattice: "square" | "triangle"; cells: readonly Cell[]; jumps: readonly Jump[]; }>;

Immutable hole lattice and all legal jump triples for a board.

function boardOf

boardOf(shape?: Shape): Board

A familiar lattice or a shaped outline. Shapes describe holes, never a different capture rule.

type Cell

type Cell = Readonly<{ x: number; y: number }>;

A hole's stable coordinate within a board shape, independent of its drawing.

type Challenge

type Challenge = Readonly<{ game: Game; answer: readonly Jump[]; seed: string }>;

A starting position paired with its complete legal witness and seed.

type ChallengeDifficulty

type ChallengeDifficulty = "easy" | "medium" | "hard";

Requested witness length category; this is not a measured human rating.

function challengeOf

challengeOf(shape: Shape, seed?: string, jumps?: number, goal?: Cell): Challenge

Generates a seeded challenge on a built-in shape, optionally fixing its final hole.

type ChallengePack

type ChallengePack = Readonly<{ title: Readonly<Record<"en" | "ja", string>>; shape: Shape; goals: readonly GoalHole[]; }>;

Curated goal choices for one supported board shape.

function classicEnglish

classicEnglish(): Challenge

Returns the classic centre-empty English game with its complete solution.

function classicTriangle

classicTriangle(): Challenge

Returns the full triangle with the apex empty and any final hole accepted.

type Game

type Game = Readonly<{ board: Board; start: readonly boolean[]; pegs: readonly boolean[]; target: number | null; history: readonly Jump[]; /** Whether a proved hint has been shown during this run. */ helped: boolean; }>;

Immutable peg position, target, move history, and assistance marker.

function gameCode

gameCode(game: Game): string

Versioned save: replay, rather than accepting a claimed final position.

function gameFromCode

gameFromCode(code: string): Game | null

Validates and replays a versioned save string, returning null if invalid.

function generate

generate(board: Board, seed: string, jumps?: number, goal?: number): Challenge

Grow backward from one peg. The reversed jumps are a proof, even on unusual boards.

function generateTobiishiChallenge

generateTobiishiChallenge(packKey: Shape, goalId: string, difficulty: ChallengeDifficulty): GoalChallenge

Creates one fixed-goal puzzle with a complete, replayable legal answer.

type GoalChallenge

type GoalChallenge = Challenge & Readonly<{ pack: Shape; packTitle: string; difficulty: ChallengeDifficulty; goal: GoalHole; }>;

Generated puzzle augmented with its pack, goal, and requested length category.

type GoalHole

type GoalHole = Readonly<{ id: string; names: Readonly<Record<"en" | "ja", string>>; x: number; y: number }>;

Named goal hole and its localized menu labels.

function isGameSolved

isGameSolved(game: Game): boolean

Checks whether one peg remains at the required target, if any.

function isGameStuck

isGameStuck(game: Game): boolean

Checks whether no legal continuation remains before the goal is reached.

type Jump

type Jump = Readonly<{ from: number; over: number; to: number }>;

A legal solitaire jump from an occupied hole over a peg to an empty hole.

function jumpAt

jumpAt(game: Game, from: number, to: number): Game

Invalid jumps leave a game unchanged; a valid jump removes exactly one peg.

function legalJumps

legalJumps(game: Game): Jump[]

Lists legal jumps from the current position.

function makeBoard

makeBoard(name: string, cells: readonly Cell[], lattice?: Board["lattice"]): Board

Make a board from holes and a lattice; absent holes cannot be crossed.

function markHelped

markHelped(game: Game): Game

Mark an assisted run without changing pieces or history. Undo keeps this flag.

function newGame

newGame(board: Board, pegs: readonly boolean[], target?: number | null): Game

Creates a validated immutable position with the given target hole, if any.

function pegCount

pegCount(game: Game): number

Counts pegs remaining on the board.

function rectangleBoard

rectangleBoard(width: number, height: number): Board

Creates a square-lattice rectangle, including supported wide and tall boards.

function restart

restart(game: Game): Game

Restores the original peg arrangement and clears moves and assistance.

function seededRandom

seededRandom(seed: string): () => number

Creates a deterministic pseudo-random stream from a text seed.

type Shape

type Shape = "english" | "european" | "triangle" | "diamond" | "heart" | "star" | "hexagon" | "wide" | "tall";

Built-in board outlines supported by the player and challenge packs.

const SHAPES

SHAPES: readonly Shape[]

Built-in shape names in player-menu order.

type Solution

type Solution = { status: "solved" | "impossible" | "limit"; jumps: Jump[]; visited: number };

Bounded search result; limit distinguishes unfinished search from proof.

function solve

solve(game: Game, maxNodes?: number): Solution

A bounded depth-first proof search. A limit is never reported as impossibility.

const SQUARE_STEPS

SQUARE_STEPS: readonly [readonly [1, 0], readonly [-1, 0], readonly [0, 1], readonly [0, -1]]

Orthogonal direction steps used by square-lattice boards.

const TOBIISHI_CHALLENGE_PACKS

TOBIISHI_CHALLENGE_PACKS: Readonly<Record<Shape, Readonly<{ title: Readonly<Record<"en" | "ja", string>>; shape: Shape; goals: readonly GoalHole[]; }>>>

Named challenge pack metadata; each goal is a distinct hole with a legal witness.

const TRIANGLE_STEPS

TRIANGLE_STEPS: readonly [readonly [1, 0], readonly [-1, 0], readonly [0, 1], readonly [0, -1], readonly [1, 1], readonly [-1, -1]]

Six jump directions used by the triangular lattice.

function undo

undo(game: Game): Game

Returns the previous position, or the same game when history is empty.

const VERSION

VERSION: "0.2.2"

Current package API version.

`@johnmorrisdotca/tobiishi/draw`

boundsOf draw escapeXml Material MATERIALS pointOf Theme THEMES

function boundsOf

boundsOf(game: Game): { width: number; height: number; }

Returns the SVG view box size for the board.

function draw

draw(game: Game, options?: { material?: Material; theme?: Partial<Theme>; selected?: number | null; title?: string; }): string

A self-contained board drawing; no browser globals and no random SVG ids.

function escapeXml

escapeXml(value: string): string

Escapes text for safe inclusion in XML attributes and content.

type Material

type Material = "stone" | "wood" | "glass";

Built-in board and peg palettes.

const MATERIALS

MATERIALS: readonly Material[]

Built-in palette names in player-menu order.

function pointOf

pointOf(game: Game, cell: number): { x: number; y: number; }

Maps a board cell index to its SVG centre point.

type Theme

type Theme = { board: string; hole: string; peg: string; edge: string; accent: string };

SVG color properties that can be partially overridden by a caller.

const THEMES

THEMES: Record<Material, Theme>

Palette values used by the SVG renderer.

`@johnmorrisdotca/tobiishi/play`

Language mount MountOptions Player STRINGS

type Language

type Language = keyof typeof STRINGS;

Supported player interface languages.

function mount

mount(host: HTMLElement, options?: MountOptions): Player

Mount one independent player. The host owns persistence through onChange and setGame.

type MountOptions

type MountOptions = { game?: Game; challenge?: Challenge; shape?: Shape; seed?: string; challengeJumps?: number; language?: Language; material?: Material; theme?: Partial<Theme>; justBoard?: boolean; settingsHost?: HTMLElement; onChange?: (game: Game, code: string) => void; };

Initial puzzle, display choices, optional settings host, and persistence callback.

type Player

type Player = { getGame: () => Game; setGame: (game: Game) => void; destroy: () => void };

Controls for reading, replacing, or unmounting one player instance.

const STRINGS

STRINGS: { readonly en: { readonly title: "Peg Solitaire"; readonly instructions: "Choose a peg, then an empty hole two spaces away. Jump over one peg to remove it. Leave one peg; if a hole is marked, finish there."; readonly newChallenge: "New challenge"; readonly undo: "Undo"; readonly restart: "Restart"; readonly hint: "Hint"; readonly remaining: "pegs left"; readonly won: "Solved — one peg remains!"; readonly st…

Localized English and Japanese labels used by the player.

`@johnmorrisdotca/tobiishi/element`

defineTobiishi

function defineTobiishi

defineTobiishi(tag?: string): void

Registers a custom element on explicit browser calls; importing this module alone is inert.

@johnmorrisdotca/tobiishi