@johnmorrisdotca/houseki 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,24 @@
+import type { Action, GameState, HeldControl, Transition } from './types.js';
+type EdgeAction = Extract<Action, {
+    kind: 'rotate-clockwise' | 'rotate-anticlockwise' | 'hard-drop' | 'place' | 'pause' | 'resume';
+}>;
+/** Deterministic held-key snapshot. Counters measure logical ticks since each press. */
+export interface InputSchedulerState {
+    readonly held: Readonly<Partial<Record<HeldControl, number>>>;
+    readonly queued: readonly EdgeAction[];
+}
+/** Creates an empty held-input scheduler. */
+export declare function createInputScheduler(): InputSchedulerState;
+/** Starts or releases one held control. Repeated press edges do not reset its repeat counter. */
+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. */
+export declare function queueInputEdge(state: InputSchedulerState, action: EdgeAction): InputSchedulerState;
+/** Releases every held or queued control after focus loss, lock, resolution or pause. */
+export declare function releaseAllInput(state: InputSchedulerState): InputSchedulerState;
+/** Resolves this tick's inputs in lateral, rotation, drop, soft-drop, pause order. */
+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. */
+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. */
+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

@@ -0,0 +1,77 @@
+/** Creates an empty held-input scheduler. */
+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. */
+export function setHeldInput(state, control, pressed) {
+    const held = { ...state.held };
+    if (pressed) {
+        if (held[control] === undefined)
+            held[control] = 0;
+    }
+    else
+        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. */
+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. */
+export function releaseAllInput(state) { return createInputScheduler(); }
+/** Resolves this tick's inputs in lateral, rotation, drop, soft-drop, pause order. */
+export function actionsForTick(game, input) {
+    if (game.phase === 'paused') {
+        const resume = input.queued.filter(action => action.kind === 'resume');
+        return [resume, createInputScheduler()];
+    }
+    if (game.phase !== 'falling' || !game.active) {
+        const pause = input.queued.filter(action => action.kind === 'pause');
+        return [pause, createInputScheduler()];
+    }
+    const actions = [];
+    const held = { ...input.held };
+    const left = held.left;
+    const right = held.right;
+    if (left !== undefined && right === undefined && (left === 0 || left >= 10 && (left - 10) % 3 === 0))
+        actions.push({ kind: 'left' });
+    if (right !== undefined && left === undefined && (right === 0 || right >= 10 && (right - 10) % 3 === 0))
+        actions.push({ kind: 'right' });
+    const edges = [...input.queued];
+    actions.push(...edges.filter(action => action.kind === 'rotate-clockwise' || action.kind === 'rotate-anticlockwise'));
+    actions.push(...edges.filter(action => action.kind === 'hard-drop' || action.kind === 'place'));
+    const soft = held['soft-drop'];
+    if (soft !== undefined && (soft === 0 || soft % 2 === 0))
+        actions.push({ kind: 'down' });
+    actions.push(...edges.filter(action => action.kind === 'pause' || action.kind === 'resume'));
+    for (const control of Object.keys(held))
+        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. */
+export function applyScheduledActions(game, input, actions, applyAction) {
+    let state = game;
+    const transitions = [];
+    for (const action of actions) {
+        if (state.phase !== 'falling' && action.kind !== 'pause' && action.kind !== 'resume')
+            break;
+        if (state.phase === 'falling' && !state.active && action.kind !== 'pause')
+            break;
+        const result = applyAction(state, action);
+        transitions.push(result);
+        if (result.accepted)
+            state = result.state;
+        if (result.accepted && (action.kind === 'hard-drop' || action.kind === 'place' || action.kind === 'pause'))
+            break;
+    }
+    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. */
+export function processInputTick(game, input, apply, tick) {
+    const [actions, scheduled] = actionsForTick(game, input);
+    const [afterInput, retained, transitions] = applyScheduledActions(game, scheduled, actions, apply);
+    const clock = tick(afterInput, 1);
+    const nextGame = clock.state;
+    const pairId = (state) => state.active?.gems[0].id ?? null;
+    const pairChanged = pairId(game) !== pairId(nextGame);
+    const locked = transitions.some(result => result.events.some(event => event.type === 'pair-locked')) || clock.events.some(event => event.type === 'pair-locked');
+    const nextInput = locked || pairChanged || nextGame.phase !== 'falling' ? createInputScheduler() : retained;
+    return [nextGame, nextInput, [...transitions, clock]];
+}

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

@@ -0,0 +1,5 @@
+import type { Gem } from './types.js';
+/** Finds maximal orthogonally connected same-colour components of at least four stones. */
+export declare function findGroups(board: readonly (Gem | null)[], width: number, height: number): readonly (readonly number[])[];
+/** Compacts each column independently, preserving survivor order. */
+export declare function compactBoard(board: readonly (Gem | null)[], width: number, height: number): readonly (Gem | null)[];

package/dist/colour-chains/match.js

@@ -0,0 +1,48 @@
+/** Finds maximal orthogonally connected same-colour components of at least four stones. */
+export function findGroups(board, width, height) {
+    const seen = new Set();
+    const groups = [];
+    for (let start = 0; start < board.length; start++) {
+        const first = board[start];
+        if (!first || seen.has(start))
+            continue;
+        const colour = first.colour;
+        const stack = [start];
+        const group = [];
+        seen.add(start);
+        while (stack.length) {
+            const at = stack.pop();
+            group.push(at);
+            const x = at % width;
+            const y = Math.floor(at / width);
+            const neighbours = [[x - 1, y], [x + 1, y], [x, y - 1], [x, y + 1]];
+            for (const [nx, ny] of neighbours) {
+                if (nx < 0 || nx >= width || ny < 0 || ny >= height)
+                    continue;
+                const index = ny * width + nx;
+                if (!seen.has(index) && board[index]?.colour === colour) {
+                    seen.add(index);
+                    stack.push(index);
+                }
+            }
+        }
+        if (group.length >= 4)
+            groups.push(group.sort((a, b) => a - b));
+    }
+    return groups;
+}
+/** Compacts each column independently, preserving survivor order. */
+export function compactBoard(board, width, height) {
+    const result = Array(width * height).fill(null);
+    for (let x = 0; x < width; x++) {
+        const stack = [];
+        for (let y = 0; y < height; y++) {
+            const gem = board[y * width + x];
+            if (gem)
+                stack.push(gem);
+        }
+        for (let i = 0; i < stack.length; i++)
+            result[(height - stack.length + i) * width + x] = stack[i];
+    }
+    return result;
+}

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

@@ -0,0 +1,7 @@
+import type { GameState } from './types.js';
+/** Restarts the same seed/date or original witnessed challenge board and queue. */
+export declare function restartGame(state: GameState): GameState;
+/** Encodes canonical initial settings, accepted ordinal actions and a derived checkpoint. */
+export declare function encodeGame(state: GameState): string;
+/** Reconstructs a bounded action replay and rejects any checkpoint that differs from replay. */
+export declare function decodeGame(text: string): GameState;

package/dist/colour-chains/persistence.js

@@ -0,0 +1,96 @@
+import { createChallenge } from './challenge.js';
+import { advanceTicks, applyAction, createGame } from './engine.js';
+const RULES = 'chains-1';
+const MAX_SAVE_BYTES = 2 * 1024 * 1024;
+const MAX_ACTIONS = 100_000;
+const MAX_TICKS = 10_000_000;
+const ACTIONS = ['left', 'right', 'down', 'rotate-clockwise', 'rotate-anticlockwise', 'hard-drop', 'place', 'pause', 'resume', 'hint'];
+function stable(value, depth = 0) {
+    if (depth > 60)
+        throw new TypeError('Save checkpoint is nested too deeply');
+    if (Array.isArray(value))
+        return `[${value.map(item => stable(item, depth + 1)).join(',')}]`;
+    if (value && typeof value === 'object')
+        return `{${Object.entries(value).filter(([, item]) => item !== undefined).sort(([a], [b]) => a.localeCompare(b)).map(([key, item]) => `${JSON.stringify(key)}:${stable(item, depth + 1)}`).join(',')}}`;
+    return JSON.stringify(value) ?? 'null';
+}
+function challengeOptions(settings) {
+    if (settings.mode !== 'challenge' || !settings.challengeId || !settings.goal || !settings.initialBoard || !settings.queue || !settings.witness)
+        throw new TypeError('Challenge settings are incomplete');
+    return { id: settings.challengeId, width: settings.width, height: settings.height, colourCount: settings.colourCount, seed: settings.seed, board: settings.initialBoard, queue: settings.queue, goal: settings.goal, witness: settings.witness };
+}
+function createFromSettings(settings) {
+    if (!settings || typeof settings !== 'object' || Array.isArray(settings))
+        throw new TypeError('Save has invalid settings');
+    if (settings.mode === 'challenge')
+        return createChallenge(challengeOptions(settings));
+    const options = settings.mode === 'daily' ? { mode: 'daily', dailyDate: settings.date } : { mode: settings.mode, width: settings.width, height: settings.height, colourCount: settings.colourCount, seed: settings.seed, ...(settings.nature ? { nature: true } : {}), ...(settings.weather ? { weather: settings.weather } : {}) };
+    const state = createGame(options);
+    if (stable(state.settings) !== stable(settings))
+        throw new TypeError('Save settings are not canonical');
+    return state;
+}
+/** Restarts the same seed/date or original witnessed challenge board and queue. */
+export function restartGame(state) { return createFromSettings(state.settings); }
+/** Encodes canonical initial settings, accepted ordinal actions and a derived checkpoint. */
+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');
+    const text = JSON.stringify({ format: 1, game: state.game, rules: state.rules, settings: state.settings, elapsedTicks: state.elapsedTicks, actions: state.recording, checkpoint: state });
+    if (new TextEncoder().encode(text).byteLength > MAX_SAVE_BYTES)
+        throw new RangeError('Save exceeds 2 MiB');
+    return text;
+}
+/** Reconstructs a bounded action replay and rejects any checkpoint that differs from replay. */
+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');
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        throw new TypeError('Save is not valid JSON');
+    }
+    if (!value || value.format !== 1 || value.game !== 'colour-chains' || value.rules !== RULES || !value.settings || !Array.isArray(value.actions) || !value.checkpoint || Object.keys(value).some(key => !['format', 'game', 'rules', 'settings', 'elapsedTicks', 'actions', 'checkpoint'].includes(key)))
+        throw new TypeError('Unsupported or invalid Colour Chains save');
+    if (!Number.isSafeInteger(value.elapsedTicks) || value.elapsedTicks < 0 || value.elapsedTicks > MAX_TICKS || value.actions.length > MAX_ACTIONS)
+        throw new RangeError('Save exceeds replay limits');
+    let state = createFromSettings(value.settings);
+    let previousTick = -1;
+    let previousOrdinal = -1;
+    const recording = [];
+    for (let index = 0; index < value.actions.length; index++) {
+        const raw = value.actions[index];
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+            throw new TypeError(`Invalid action record ${index + 1}`);
+        const item = raw;
+        if (Object.keys(item).some(key => !['tick', 'ordinal', 'action'].includes(key)) || !Number.isSafeInteger(item.tick) || item.tick < 0 || item.tick > value.elapsedTicks || !Number.isSafeInteger(item.ordinal) || !item.action || typeof item.action !== 'object' || Array.isArray(item.action) || Object.keys(item.action).some(key => key !== 'kind') || !ACTIONS.includes(item.action.kind))
+            throw new TypeError(`Invalid action record ${index + 1}`);
+        if (item.tick < previousTick || item.ordinal !== (item.tick === previousTick ? previousOrdinal + 1 : 0))
+            throw new TypeError(`Invalid action ordering at record ${index + 1}`);
+        while (state.elapsedTicks < item.tick) {
+            const prior = state.elapsedTicks;
+            state = advanceTicks(state, Math.min(3600, item.tick - state.elapsedTicks)).state;
+            if (state.elapsedTicks === prior)
+                throw new TypeError(`Action occurs after the run stopped at record ${index + 1}`);
+        }
+        const result = applyAction(state, item.action);
+        if (!result.accepted)
+            throw new TypeError(`Illegal action at record ${index + 1}: ${result.reason ?? 'rejected'}`);
+        state = result.state;
+        recording.push({ tick: item.tick, ordinal: item.ordinal, action: item.action });
+        previousTick = item.tick;
+        previousOrdinal = item.ordinal;
+    }
+    while (state.elapsedTicks < value.elapsedTicks) {
+        const prior = state.elapsedTicks;
+        state = advanceTicks(state, Math.min(3600, value.elapsedTicks - state.elapsedTicks)).state;
+        if (state.elapsedTicks === prior)
+            throw new TypeError('Checkpoint time exceeds the logical game clock');
+    }
+    state = { ...state, recording };
+    if (stable(state) !== stable(value.checkpoint))
+        throw new TypeError('Save checkpoint does not match its action recording');
+    return state;
+}

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

@@ -0,0 +1,7 @@
+import type { Colour, GameState } from './types.js';
+/** Hashes a UTF-8 seed with FNV-1a, scoped to this game and rules version. */
+export declare function seedState(seed: string): number;
+/** Advances the package's reference xorshift32 source. */
+export declare function nextUint32(state: number): number;
+/** Draws one deterministic pair from a three-of-each-colour shuffled bag. */
+export declare function drawPair(state: Pick<GameState, 'bag' | 'randomState' | 'settings'>): readonly [readonly [Colour, Colour], readonly Colour[], number];

package/dist/colour-chains/random.js

@@ -0,0 +1,49 @@
+const COLOURS = ['red', 'blue', 'green', 'gold', 'purple', 'teal'];
+/** Hashes a UTF-8 seed with FNV-1a, scoped to this game and rules version. */
+export function seedState(seed) {
+    let hash = 0x811c9dc5;
+    for (const byte of new TextEncoder().encode(`colour-chains|chains-1|${seed}`))
+        hash = Math.imul(hash ^ byte, 0x01000193) >>> 0;
+    return hash || 0x6d2b79f5;
+}
+/** Advances the package's reference xorshift32 source. */
+export function nextUint32(state) {
+    let next = state >>> 0;
+    next ^= next << 13;
+    next ^= next >>> 17;
+    next ^= next << 5;
+    return next >>> 0;
+}
+function nextInt(state, n) {
+    const limit = Math.floor(0x100000000 / n) * n;
+    let current = state >>> 0;
+    for (;;) {
+        const next = nextUint32(current);
+        current = next;
+        if (next < limit)
+            return [next % n, current];
+    }
+}
+function refill(state, count) {
+    const values = [...COLOURS.slice(0, count), ...COLOURS.slice(0, count), ...COLOURS.slice(0, count)];
+    let randomState = state;
+    for (let i = values.length - 1; i > 0; i--) {
+        const [j, next] = nextInt(randomState, i + 1);
+        randomState = next;
+        [values[i], values[j]] = [values[j], values[i]];
+    }
+    return [values, randomState];
+}
+/** Draws one deterministic pair from a three-of-each-colour shuffled bag. */
+export function drawPair(state) {
+    let bag = state.bag;
+    let randomState = state.randomState;
+    const colours = [];
+    for (let i = 0; i < 2; i++) {
+        if (!bag.length)
+            [bag, randomState] = refill(randomState, state.settings.colourCount);
+        colours.push(bag[bag.length - 1]);
+        bag = bag.slice(0, -1);
+    }
+    return [[colours[0], colours[1]], bag, randomState];
+}

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

@@ -0,0 +1,191 @@
+/** A gem colour used by Colour Chains. */
+export type Colour = 'red' | 'blue' | 'green' | 'gold' | 'purple' | 'teal';
+/** A settled or active stone with a stable run-local identity. */
+export interface Gem {
+    readonly id: number;
+    readonly colour: Colour;
+    readonly magnetic?: true;
+}
+/** Authored Challenge layouts do not permit Shizen-marked stones. */
+export type ChallengeGem = Omit<Gem, 'magnetic'>;
+/** The pivot-to-satellite direction, in clockwise order. */
+export type Orientation = 'up' | 'right' | 'down' | 'left';
+/** A visible or hidden board coordinate. */
+export interface Cell {
+    readonly x: number;
+    readonly y: number;
+}
+/** The active rigid pair. The pivot always retains its own gem identity. */
+export interface Pair {
+    readonly pivot: Cell;
+    readonly orientation: Orientation;
+    readonly gems: readonly [Gem, Gem];
+    readonly level: number;
+    readonly gravityTicks: number;
+    readonly groundedTicks: number;
+    readonly resetCount: number;
+    readonly groundedStarted: boolean;
+}
+/** Supported well presets. */
+export type Preset = 'narrow' | 'standard' | 'wide' | 'tall' | 'extraWide' | 'deep' | 'large';
+export type Mode = 'relaxed' | 'arcade' | 'daily' | 'challenge';
+export type WeatherSchedule = 'frequent' | 'rare';
+export interface CreateOptions {
+    readonly mode?: Exclude<Mode, 'challenge'>;
+    readonly seed?: string;
+    readonly dailyDate?: string;
+    readonly preset?: Preset;
+    readonly width?: number;
+    readonly height?: number;
+    readonly colourCount?: 4 | 5 | 6;
+    readonly pairLimit?: number;
+    readonly nature?: boolean;
+    readonly weather?: WeatherSchedule;
+}
+/** Run settings fixed at game creation. */
+export interface Settings {
+    readonly mode: Mode;
+    readonly width: number;
+    readonly height: number;
+    readonly colourCount: 4 | 5 | 6;
+    readonly seed: string;
+    readonly date?: string;
+    readonly pairLimit?: number;
+    readonly nature?: true;
+    readonly weather?: WeatherSchedule;
+    readonly challengeId?: string;
+    readonly goal?: ChallengeGoal;
+    readonly initialBoard?: readonly (ChallengeGem | null)[];
+    readonly queue?: readonly (readonly [Colour, Colour])[];
+    readonly witness?: readonly WitnessStep[];
+}
+/** Challenge objective; target IDs refer to the visible starting board. */
+export type ChallengeGoal = {
+    readonly kind: 'clear-targets';
+    readonly targetIds: readonly number[];
+} | {
+    readonly kind: 'minimum-chain';
+    readonly chain: number;
+} | {
+    readonly kind: 'empty-board';
+};
+export interface WitnessStep {
+    readonly pivotX: number;
+    readonly orientation: Orientation;
+}
+export interface ChallengeOptions {
+    readonly id: string;
+    readonly width?: number;
+    readonly height?: number;
+    readonly colourCount?: 4 | 5 | 6;
+    readonly seed?: string;
+    readonly board: readonly (ChallengeGem | null)[];
+    readonly queue: readonly (readonly [Colour, Colour])[];
+    readonly goal: ChallengeGoal;
+    readonly witness?: readonly WitnessStep[];
+}
+/** Observable game phases. */
+export type Phase = 'falling' | 'clear-mark' | 'clear-remove' | 'gravity' | 'paused' | 'won' | 'lost' | 'finished';
+/** A scored simultaneous match wave. */
+export interface Wave {
+    readonly chain: number;
+    readonly cells: readonly number[];
+    readonly ids: readonly number[];
+    readonly points: number;
+}
+export type PlayAction = {
+    readonly kind: 'left';
+} | {
+    readonly kind: 'right';
+} | {
+    readonly kind: 'down';
+} | {
+    readonly kind: 'rotate-clockwise';
+} | {
+    readonly kind: 'rotate-anticlockwise';
+} | {
+    readonly kind: 'hard-drop';
+} | {
+    readonly kind: 'place';
+} | {
+    readonly kind: 'pause';
+} | {
+    readonly kind: 'resume';
+} | {
+    readonly kind: 'hint';
+};
+export type Action = PlayAction;
+export type HeldControl = 'left' | 'right' | 'soft-drop';
+export type InputCommand = {
+    readonly kind: 'hold';
+    readonly control: HeldControl;
+    readonly pressed: boolean;
+} | {
+    readonly kind: 'edge';
+    readonly action: Extract<PlayAction, {
+        kind: 'rotate-clockwise' | 'rotate-anticlockwise' | 'hard-drop' | 'place' | 'pause' | 'resume';
+    }>;
+};
+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. */
+export interface GameState {
+    readonly game: 'colour-chains';
+    readonly rules: 'chains-1';
+    readonly settings: Settings;
+    readonly board: readonly (Gem | null)[];
+    readonly phase: Phase;
+    readonly pausedPhase?: Exclude<Phase, 'paused'>;
+    readonly active: Pair | null;
+    readonly next: readonly (readonly [Colour, Colour])[];
+    readonly bag: readonly Colour[];
+    readonly randomState: number;
+    readonly nextMagnetic?: readonly (readonly [boolean, boolean])[];
+    readonly lastHorizontalDirection?: 'left' | 'right';
+    readonly naturePulsePending?: boolean;
+    readonly weatherResolvedPairs?: number;
+    readonly nextId: number;
+    readonly score: number;
+    readonly maxChain: number;
+    readonly allClears: number;
+    readonly completedPairs: number;
+    readonly resolutionTick: number;
+    readonly resolutionLevel?: number;
+    readonly waves: readonly Wave[];
+    readonly clearCells: readonly number[];
+    readonly gravityBoard: readonly (Gem | null)[] | null;
+    readonly resolutionHadClear: boolean;
+    readonly elapsedTicks: number;
+    readonly assisted: boolean;
+    readonly witnessIndex: number;
+    readonly recording: readonly RecordedAction[];
+    readonly reason?: string;
+}
+/** A deterministic transition; rejected actions retain the exact input state. */
+export interface Transition {
+    readonly state: GameState;
+    readonly events: readonly GameEvent[];
+    readonly accepted: boolean;
+    readonly reason?: string;
+}
+/** A domain event emitted by one transition. */
+export interface GameEvent {
+    readonly type: string;
+    readonly [key: string]: unknown;
+}
+/** Compact player status derived from the current state. */
+export interface GameStatus {
+    readonly mode: Mode;
+    readonly phase: Phase;
+    readonly score: number;
+    readonly maxChain: number;
+    readonly allClears: number;
+    readonly completedPairs: number;
+    readonly assisted: boolean;
+    readonly reason?: string;
+}
+/** Destination cells for the two independently settled ghost stones. */
+export type Landing = readonly [Cell, Cell];

package/dist/colour-chains/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -0,0 +1,16 @@
+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. */
+export declare class StoneChainsOptionsError extends RangeError {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export interface NormalizedOptions extends Settings {
+    readonly mode: Exclude<Mode, 'challenge'>;
+}
+declare function validateSize(width: number, height: number): void;
+/** Validates public modes and canonical category dimensions before a random draw. */
+export declare function normalizeOptions(options: CreateOptions): NormalizedOptions;
+export declare function validateChallengeGoal(goal: ChallengeGoal, ids: ReadonlySet<number>): ChallengeGoal;
+export { COLOURS, PRESETS, validateSize };

package/dist/colour-chains/validation.js

@@ -0,0 +1,80 @@
+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. */
+export class StoneChainsOptionsError extends RangeError {
+    code;
+    constructor(code, message) { super(message); this.name = 'StoneChainsOptionsError'; this.code = code; }
+}
+function validDate(value) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(value))
+        return false;
+    const time = Date.parse(`${value}T00:00:00.000Z`);
+    return Number.isFinite(time) && new Date(time).toISOString().slice(0, 10) === value;
+}
+function validateSize(width, height) {
+    if (!Number.isInteger(width) || !Number.isInteger(height) || width < 5 || width > 16 || height < 12 || height > 32 || width * height > 512)
+        throw new StoneChainsOptionsError('invalid-board-size', 'Board must be 5–16 columns by 12–32 visible rows, with at most 512 cells');
+}
+/** Validates public modes and canonical category dimensions before a random draw. */
+export function normalizeOptions(options) {
+    if (!options || typeof options !== 'object' || Array.isArray(options))
+        throw new StoneChainsOptionsError('invalid-options', 'Options must be an object');
+    const keys = ['mode', 'seed', 'dailyDate', 'preset', 'width', 'height', 'colourCount', 'pairLimit', 'nature', 'weather'];
+    if (Object.keys(options).some(key => !keys.includes(key)))
+        throw new StoneChainsOptionsError('unknown-option', 'Options contain an unsupported field');
+    const mode = options.mode ?? 'relaxed';
+    if (!['relaxed', 'arcade', 'daily'].includes(mode))
+        throw new StoneChainsOptionsError('invalid-mode', 'Use Relaxed, Arcade or Daily; Challenges use createChallenge');
+    const colourCount = options.colourCount ?? 4;
+    if (colourCount !== 4 && colourCount !== 5 && colourCount !== 6)
+        throw new StoneChainsOptionsError('invalid-colour-count', 'Colour count must be 4, 5 or 6');
+    if (mode === 'daily') {
+        if (options.nature !== undefined || options.weather !== undefined)
+            throw new StoneChainsOptionsError('noncanonical-daily-settings', 'Daily does not use optional nature rules');
+        if (typeof options.dailyDate !== 'string' || !validDate(options.dailyDate))
+            throw new StoneChainsOptionsError('invalid-daily-date', 'Daily requires a valid UTC YYYY-MM-DD date from the host');
+        if (options.seed !== undefined || options.preset !== undefined || options.width !== undefined || options.height !== undefined || options.colourCount !== undefined && options.colourCount !== 4 || options.pairLimit !== undefined && options.pairLimit !== 60)
+            throw new StoneChainsOptionsError('noncanonical-daily-settings', 'Daily uses the standard 6×12 four-colour well and 60 resolved pairs');
+        return { mode, width: 6, height: 12, colourCount: 4, date: options.dailyDate, seed: `colour-chains:daily:${options.dailyDate}`, pairLimit: 60 };
+    }
+    if (options.dailyDate !== undefined)
+        throw new StoneChainsOptionsError('daily-date-outside-daily', 'dailyDate is supported only in Daily mode');
+    if (options.nature !== undefined && typeof options.nature !== 'boolean')
+        throw new StoneChainsOptionsError('invalid-nature-option', 'nature must be a boolean');
+    if (options.weather !== undefined && options.weather !== 'frequent' && options.weather !== 'rare')
+        throw new StoneChainsOptionsError('invalid-weather-option', 'weather must be frequent or rare');
+    if (options.weather !== undefined && options.nature !== true)
+        throw new StoneChainsOptionsError('weather-requires-nature', 'Arashi weather requires nature:true');
+    if (options.preset !== undefined && !Object.hasOwn(PRESETS, options.preset))
+        throw new StoneChainsOptionsError('invalid-preset', 'Unsupported board preset');
+    if (options.preset !== undefined && (options.width !== undefined || options.height !== undefined))
+        throw new StoneChainsOptionsError('conflicting-board-options', 'Choose a preset or custom dimensions');
+    const [presetWidth, presetHeight] = PRESETS[options.preset ?? 'standard'];
+    const width = options.width ?? presetWidth;
+    const height = options.height ?? presetHeight;
+    validateSize(width, height);
+    const seed = options.seed ?? 'houseki-colour-chains';
+    if (typeof seed !== 'string' || seed.length < 1 || seed.length > 200)
+        throw new StoneChainsOptionsError('invalid-seed', 'Seed must contain 1–200 characters');
+    if (options.pairLimit !== undefined)
+        throw new StoneChainsOptionsError('unsupported-pair-limit', 'Pair limits are defined only for Daily and Challenges');
+    return { mode, width, height, colourCount, seed, ...(options.nature === true ? { nature: true } : {}), ...(options.weather ? { weather: options.weather } : {}) };
+}
+export function validateChallengeGoal(goal, ids) {
+    if (!goal || typeof goal !== 'object' || Array.isArray(goal))
+        throw new StoneChainsOptionsError('invalid-goal', 'Challenge goal must be an object');
+    if (goal.kind === 'clear-targets') {
+        if (Object.keys(goal).some(key => key !== 'kind' && key !== 'targetIds') || !Array.isArray(goal.targetIds) || goal.targetIds.length < 1 || goal.targetIds.length > 512 || goal.targetIds.some(id => !Number.isSafeInteger(id) || !ids.has(id)) || new Set(goal.targetIds).size !== goal.targetIds.length)
+            throw new StoneChainsOptionsError('invalid-target-ids', 'Target goal requires unique IDs from the starting board');
+        return Object.freeze({ kind: 'clear-targets', targetIds: Object.freeze([...goal.targetIds].sort((a, b) => a - b)) });
+    }
+    if (goal.kind === 'minimum-chain') {
+        if (Object.keys(goal).some(key => key !== 'kind' && key !== 'chain') || !Number.isInteger(goal.chain) || goal.chain < 1 || goal.chain > 12)
+            throw new StoneChainsOptionsError('invalid-chain-goal', 'Minimum chain must be 1–12');
+        return Object.freeze({ kind: 'minimum-chain', chain: goal.chain });
+    }
+    if (goal.kind === 'empty-board' && Object.keys(goal).length === 1)
+        return Object.freeze({ kind: 'empty-board' });
+    throw new StoneChainsOptionsError('invalid-goal', 'Unsupported challenge goal');
+}
+export { COLOURS, PRESETS, validateSize };

package/dist/colour-chains.d.ts

@@ -0,0 +1,8 @@
+export * from './colour-chains/types.js';
+export { StoneChainsOptionsError } from './colour-chains/validation.js';
+export { createGame, applyAction, advanceTicks, legalActions, statusOf, landingCells, powerDropPreview } from './colour-chains/engine.js';
+export { createChallenge } from './colour-chains/challenge.js';
+export { restartGame, encodeGame, decodeGame } from './colour-chains/persistence.js';
+export { createInputScheduler, setHeldInput, queueInputEdge, releaseAllInput, actionsForTick, applyScheduledActions, processInputTick } from './colour-chains/input.js';
+export { campaignManifest, levelManifest, tutorialManifest, getLevel, createLevel, getTutorial } from './colour-chains/content.js';
+export type { LocalizedText, ChainDifficultyMetrics, ChainCampaignLevel, ChainCampaignManifest, ChainTutorialStep, ChainTutorialDefinition, ChainContentData } from './colour-chains/content-types.js';

package/dist/colour-chains.js

@@ -0,0 +1,7 @@
+export * from './colour-chains/types.js';
+export { StoneChainsOptionsError } from './colour-chains/validation.js';
+export { createGame, applyAction, advanceTicks, legalActions, statusOf, landingCells, powerDropPreview } from './colour-chains/engine.js';
+export { createChallenge } from './colour-chains/challenge.js';
+export { restartGame, encodeGame, decodeGame } from './colour-chains/persistence.js';
+export { createInputScheduler, setHeldInput, queueInputEdge, releaseAllInput, actionsForTick, applyScheduledActions, processInputTick } from './colour-chains/input.js';
+export { campaignManifest, levelManifest, tutorialManifest, getLevel, createLevel, getTutorial } from './colour-chains/content.js';