@johnmorrisdotca/houseki 0.0.0-stage → 0.1.1

package/dist/stone-collapse/persistence.js

@@ -0,0 +1,230 @@
+import { advanceTicks, applyAction, createChallenge, createGame, requestHint, undo } from './engine.js';
+const RULES = 'collapse-2';
+const MAX_RECORDED_ACTIONS = 100_000;
+const MAX_RECORDED_TICKS = 10_000_000;
+function groupScore(size) { return 5 * size * (size - 1); }
+function indexOfId(board, id) { return board.findIndex(stone => stone?.id === id); }
+function groupAt(board, settings, start) {
+    const stone = board[start];
+    if (!stone)
+        return [];
+    const width = settings.width;
+    const height = settings.height;
+    const mask = settings.mask;
+    const neighbors = (index) => {
+        const x = index % width;
+        const y = Math.floor(index / width);
+        const out = [];
+        if (x > 0 && mask[index - 1])
+            out.push(index - 1);
+        if (x + 1 < width && mask[index + 1])
+            out.push(index + 1);
+        if (y > 0 && mask[index - width])
+            out.push(index - width);
+        if (y + 1 < height && mask[index + width])
+            out.push(index + width);
+        return out;
+    };
+    const found = new Set([start]);
+    const pending = [start];
+    while (pending.length)
+        for (const next of neighbors(pending.pop()))
+            if (!found.has(next) && board[next]?.colour === stone.colour) {
+                found.add(next);
+                pending.push(next);
+            }
+    return [...found].sort((a, b) => a - b);
+}
+/** Starts a fresh attempt from the identical seeded board or preserved challenge definition. */
+export function restartGame(state) {
+    if (state.settings.mode === 'challenge')
+        return createChallenge(state.challenge);
+    if (state.settings.mode === 'daily')
+        return createGame({ mode: 'daily', dailyDate: state.settings.dailyDate });
+    const { settings } = state;
+    const mode = settings.mode === 'arcade' ? 'arcade' : 'relaxed';
+    return createGame({ mode, colourCount: settings.colourCount, seed: settings.seed, tools: settings.tools, ...(settings.shape ? { shape: settings.shape } : { width: settings.width, height: settings.height, ...(settings.mask.every(Boolean) ? {} : { mask: settings.mask }) }) });
+}
+/** Encodes the canonical initial configuration, accepted replay actions, and a derived checkpoint. */
+export function encodeGame(state) {
+    // Undo frames are derived by replaying committed actions; storing their full board snapshots scales poorly on deep boards.
+    const { history: _history, ...checkpoint } = state;
+    const encoded = JSON.stringify({ format: 1, game: state.game, rules: state.rules, settings: state.settings, challenge: state.challenge, actions: state.recording, checkpoint });
+    if (new TextEncoder().encode(encoded).length > 2 * 1024 * 1024)
+        throw new RangeError('Save exceeds 2 MiB');
+    return encoded;
+}
+function stable(value, depth = 0) {
+    if (depth > 50)
+        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 applyUiSelection(state, stoneId) {
+    if (stoneId === null)
+        return { ...state, selectedId: null, selectedIds: Object.freeze([]), previewScore: 0 };
+    const at = indexOfId(state.board, stoneId);
+    if (at < 0)
+        throw new TypeError('Checkpoint selection names an unknown stone');
+    const cells = groupAt(state.board, state.settings, at);
+    if (cells.length < 2)
+        throw new TypeError('Checkpoint selection is not a legal group');
+    const ids = cells.map(cell => state.board[cell].id);
+    return { ...state, selectedId: stoneId, selectedIds: Object.freeze(ids), previewScore: groupScore(ids.length), selectedTool: null, toolTarget: null, toolPreview: Object.freeze([]) };
+}
+function stateFromInitial(settings, challenge) {
+    if (!settings || typeof settings !== 'object' || Array.isArray(settings))
+        throw new TypeError('Save has invalid initial settings');
+    const settingsKeys = ['mode', 'width', 'height', 'colourCount', 'seed', 'shape', 'mask', 'dailyDate', 'challengeId', 'goal', 'moveLimit', 'tools'];
+    if (Object.keys(settings).some(key => !settingsKeys.includes(key)))
+        throw new TypeError('Initial settings contain unsupported fields');
+    if (settings.mode === 'challenge') {
+        if (!challenge)
+            throw new TypeError('Challenge save has no initial challenge definition');
+        const state = createChallenge(challenge);
+        if (stable(state.settings) !== stable(settings))
+            throw new TypeError('Challenge settings do not match the initial definition');
+        return state;
+    }
+    if (challenge !== null)
+        throw new TypeError('Score-game save cannot contain a challenge definition');
+    const options = settings.mode === 'daily'
+        ? { mode: 'daily', dailyDate: settings.dailyDate }
+        : { mode: settings.mode, colourCount: settings.colourCount, seed: settings.seed, tools: settings.tools, ...(settings.shape ? { shape: settings.shape } : { width: settings.width, height: settings.height, ...(settings.mask.every(Boolean) ? {} : { mask: settings.mask }) }) };
+    const state = createGame(options);
+    if (stable(state.settings) !== stable(settings))
+        throw new TypeError('Initial settings are not canonical');
+    return state;
+}
+/** Reconstructs and validates a bounded replay before accepting its checkpoint. */
+export function decodeGame(text) {
+    if (typeof text !== 'string' || new TextEncoder().encode(text).length > 2 * 1024 * 1024)
+        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 !== 'stone-collapse' || value.rules !== RULES || !value.settings || !Array.isArray(value.actions) || !value.checkpoint)
+        throw new TypeError('Unsupported or invalid Stone Collapse save');
+    if (Object.keys(value).some(key => !['format', 'game', 'rules', 'settings', 'challenge', 'actions', 'checkpoint'].includes(key)))
+        throw new TypeError('Save contains unsupported fields');
+    if (value.actions.length > MAX_RECORDED_ACTIONS)
+        throw new RangeError('Save exceeds 100,000 replay entries');
+    let state = stateFromInitial(value.settings, value.challenge ?? null);
+    let totalTicks = 0;
+    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 replay entry ${index + 1}`);
+        const entry = raw;
+        if (entry.kind === 'remove') {
+            if (Object.keys(entry).some(key => !['kind', 'move', 'stoneId'].includes(key)))
+                throw new TypeError(`Removal record ${index + 1} contains unsupported fields`);
+            if (!Number.isSafeInteger(entry.move) || entry.move !== state.moves + 1 || !Number.isSafeInteger(entry.stoneId))
+                throw new TypeError(`Invalid removal record ${index + 1}`);
+            const at = indexOfId(state.board, entry.stoneId);
+            if (at < 0)
+                throw new TypeError(`Illegal removal record ${index + 1}: unknown stone`);
+            const groupIds = groupAt(state.board, state.settings, at).map(cell => state.board[cell].id);
+            const alreadySelected = state.selectedIds.length === groupIds.length && groupIds.every(id => state.selectedIds.includes(id));
+            const selected = alreadySelected ? { state, accepted: true } : applyAction(state, { kind: 'select', stoneId: entry.stoneId });
+            if (!selected.accepted)
+                throw new TypeError(`Illegal removal record ${index + 1}: ${selected.reason}`);
+            const committed = applyAction(selected.state, { kind: 'confirm' });
+            if (!committed.accepted || committed.state.moves !== entry.move)
+                throw new TypeError(`Illegal removal record ${index + 1}: ${committed.reason ?? 'wrong move number'}`);
+            state = committed.state;
+        }
+        else if (entry.kind === 'select-tool') {
+            if (Object.keys(entry).some(key => !['kind', 'tool'].includes(key)) || !['bomb', 'pick'].includes(entry.tool))
+                throw new TypeError(`Invalid tool selection record ${index + 1}`);
+            const result = applyAction(state, { kind: 'select-tool', tool: entry.tool });
+            if (!result.accepted)
+                throw new TypeError(`Illegal tool selection record ${index + 1}: ${result.reason}`);
+            state = result.state;
+        }
+        else if (entry.kind === 'target-tool') {
+            if (Object.keys(entry).some(key => !['kind', 'cell'].includes(key)) || !Number.isSafeInteger(entry.cell))
+                throw new TypeError(`Invalid tool target record ${index + 1}`);
+            const result = applyAction(state, { kind: 'target-tool', cell: entry.cell });
+            if (!result.accepted)
+                throw new TypeError(`Illegal tool target record ${index + 1}: ${result.reason}`);
+            state = result.state;
+        }
+        else if (entry.kind === 'confirm-tool') {
+            if (Object.keys(entry).some(key => !['kind', 'move'].includes(key)) || !Number.isSafeInteger(entry.move) || entry.move !== state.moves + 1)
+                throw new TypeError(`Invalid tool-use record ${index + 1}`);
+            const result = applyAction(state, { kind: 'confirm-tool' });
+            if (!result.accepted || result.state.moves !== entry.move)
+                throw new TypeError(`Illegal tool-use record ${index + 1}: ${result.reason ?? 'wrong move number'}`);
+            state = result.state;
+        }
+        else if (entry.kind === 'cancel-tool') {
+            if (Object.keys(entry).some(key => key !== 'kind'))
+                throw new TypeError(`Tool cancellation record ${index + 1} contains unsupported fields`);
+            const result = applyAction(state, { kind: 'cancel-tool' });
+            if (!result.accepted)
+                throw new TypeError(`Illegal tool cancellation record ${index + 1}: ${result.reason}`);
+            state = result.state;
+        }
+        else if (entry.kind === 'undo') {
+            if (Object.keys(entry).some(key => !['kind', 'move'].includes(key)))
+                throw new TypeError(`Undo record ${index + 1} contains unsupported fields`);
+            if (!Number.isSafeInteger(entry.move) || entry.move !== state.moves - 1)
+                throw new TypeError(`Invalid undo record ${index + 1}`);
+            const result = undo(state);
+            if (!result.accepted || result.state.moves !== entry.move)
+                throw new TypeError(`Illegal undo record ${index + 1}`);
+            state = result.state;
+        }
+        else if (entry.kind === 'hint') {
+            if (Object.keys(entry).some(key => !['kind', 'witnessIndex'].includes(key)))
+                throw new TypeError(`Hint record ${index + 1} contains unsupported fields`);
+            if (!Number.isSafeInteger(entry.witnessIndex) || entry.witnessIndex !== state.witnessIndex)
+                throw new TypeError(`Invalid hint record ${index + 1}`);
+            const result = requestHint(state);
+            if (!result.accepted)
+                throw new TypeError(`Illegal hint record ${index + 1}: ${result.reason}`);
+            state = result.state;
+        }
+        else if (entry.kind === 'ticks') {
+            if (Object.keys(entry).some(key => !['kind', 'count'].includes(key)))
+                throw new TypeError(`Tick record ${index + 1} contains unsupported fields`);
+            if (!Number.isSafeInteger(entry.count) || entry.count < 1 || (totalTicks += entry.count) > MAX_RECORDED_TICKS)
+                throw new RangeError(`Invalid tick record ${index + 1}`);
+            let remaining = entry.count;
+            while (remaining > 0) {
+                const amount = Math.min(3600, remaining);
+                const prior = state.elapsedTicks;
+                state = advanceTicks(state, amount).state;
+                const advanced = state.elapsedTicks - prior;
+                if (advanced !== amount)
+                    throw new TypeError(`Ticks continue after the run stopped at replay entry ${index + 1}`);
+                remaining -= amount;
+            }
+        }
+        else
+            throw new TypeError(`Unknown replay entry ${index + 1}`);
+    }
+    const checkpoint = value.checkpoint;
+    try {
+        if (checkpoint.selectedId !== state.selectedId)
+            state = applyUiSelection(state, checkpoint.selectedId ?? null);
+        const checkpointHasHistory = Object.hasOwn(checkpoint, 'history');
+        const { history: _history, ...derivedCheckpoint } = state;
+        if (stable(checkpointHasHistory ? state : derivedCheckpoint) !== stable(checkpoint))
+            throw new TypeError('Save checkpoint does not match its action recording');
+    }
+    catch (error) {
+        if (error instanceof TypeError && error.message.startsWith('Save checkpoint'))
+            throw error;
+        throw new TypeError('Save checkpoint is invalid or does not match its action recording');
+    }
+    return state;
+}

package/dist/stone-collapse/types.d.ts

@@ -0,0 +1,216 @@
+/** A colour used by a stone. */
+export type StoneColour = 'red' | 'blue' | 'green' | 'gold' | 'purple' | 'teal';
+/** A stone keeps its run-local identity as it falls or changes column. */
+export interface Stone {
+    readonly id: number;
+    readonly colour: StoneColour;
+}
+export type BoardPreset = 'compact' | 'standard' | 'wide' | 'tall' | 'extraWide' | 'deep' | 'large';
+export type BoardShape = 'heart' | 'star' | 'hexagon';
+export type GameMode = 'relaxed' | 'arcade' | 'daily' | 'challenge';
+export type StoredTool = 'bomb' | 'pick';
+export interface ToolInventory {
+    readonly bomb: number;
+    readonly pick: number;
+}
+export type GamePhase = 'ready' | 'clear-mark' | 'clear-remove' | 'gravity' | 'won' | 'lost' | 'finished';
+export type ChallengeGoal = {
+    readonly kind: 'clear-all';
+} | {
+    readonly kind: 'clear-targets';
+    readonly targetIds: readonly number[];
+} | {
+    readonly kind: 'score-target';
+    readonly minimumScore: number;
+};
+export interface Settings {
+    readonly mode: GameMode;
+    readonly width: number;
+    readonly height: number;
+    readonly colourCount: 4 | 5 | 6;
+    readonly seed: string | number;
+    readonly shape?: BoardShape;
+    readonly mask: readonly boolean[];
+    readonly dailyDate?: string;
+    readonly challengeId?: string;
+    readonly goal?: ChallengeGoal;
+    readonly moveLimit?: number;
+    readonly tools: boolean;
+}
+export interface ChallengeDefinition {
+    readonly id: string;
+    readonly width: number;
+    readonly height: number;
+    readonly colourCount: 4 | 5 | 6;
+    readonly seed: string | number;
+    readonly mask: readonly boolean[];
+    readonly initialBoard: readonly (Stone | null)[];
+    readonly goal: ChallengeGoal;
+    readonly moveLimit?: number;
+    /** Each entry is the complete stable-ID set of the next witnessed group. */
+    readonly witness: readonly (readonly number[])[];
+}
+/** Data sufficient to restore the complete game immediately before a committed move. */
+export interface UndoFrame {
+    readonly board: readonly (Stone | null)[];
+    readonly score: number;
+    readonly moves: number;
+    readonly removed: number;
+    readonly randomState: number;
+    readonly nextId: number;
+    readonly usedFallback: boolean;
+    readonly finishAdjustmentApplied: boolean;
+    readonly selectedId: number | null;
+    readonly selectedIds: readonly number[];
+    readonly previewScore: number;
+    readonly witnessIndex: number;
+    readonly inventory: ToolInventory;
+    readonly toolProgress: number;
+    readonly toolAwardCursor: 0 | 1;
+    readonly selectedTool: StoredTool | null;
+    readonly toolTarget: number | null;
+    readonly toolPreview: readonly number[];
+}
+export type RecordedAction = {
+    readonly kind: 'remove';
+    readonly move: number;
+    readonly stoneId: number;
+} | {
+    readonly kind: 'select-tool';
+    readonly tool: StoredTool;
+} | {
+    readonly kind: 'target-tool';
+    readonly cell: number;
+} | {
+    readonly kind: 'confirm-tool';
+    readonly move: number;
+} | {
+    readonly kind: 'cancel-tool';
+} | {
+    readonly kind: 'undo';
+    readonly move: number;
+} | {
+    readonly kind: 'hint';
+    readonly witnessIndex: number;
+} | {
+    readonly kind: 'ticks';
+    readonly count: number;
+};
+export interface GameState {
+    readonly game: 'stone-collapse';
+    readonly rules: 'collapse-2';
+    readonly settings: Settings;
+    readonly challenge: ChallengeDefinition | null;
+    readonly initialBoard: readonly (Stone | null)[];
+    /** Row-major; masked and currently empty cells contain null. */
+    readonly board: readonly (Stone | null)[];
+    readonly phase: GamePhase;
+    readonly selectedId: number | null;
+    readonly selectedIds: readonly number[];
+    readonly previewScore: number;
+    readonly score: number;
+    readonly moves: number;
+    readonly removed: number;
+    readonly randomState: number;
+    readonly nextId: number;
+    readonly usedFallback: boolean;
+    readonly resolutionTick: number;
+    readonly pendingIds: readonly number[];
+    /** Settled destination board held during the gravity animation. */
+    readonly gravityBoard: readonly (Stone | null)[] | null;
+    readonly finishAdjustmentApplied: boolean;
+    readonly assisted: boolean;
+    readonly history: readonly UndoFrame[];
+    /** -1 means the player's current board has left the supplied witness path. */
+    readonly witnessIndex: number;
+    readonly elapsedTicks: number;
+    readonly reason?: string;
+    readonly recording: readonly RecordedAction[];
+    readonly inventory: ToolInventory;
+    /** Ordinary removed stones carried toward the next tool award; always 0–11. */
+    readonly toolProgress: number;
+    /** 0 awards Bomb next; 1 awards Pick next. */
+    readonly toolAwardCursor: 0 | 1;
+    readonly selectedTool: StoredTool | null;
+    readonly toolTarget: number | null;
+    /** Exact row-major cells affected by the current target. */
+    readonly toolPreview: readonly number[];
+}
+export type Action = {
+    readonly kind: 'select';
+    readonly stoneId: number;
+} | {
+    readonly kind: 'confirm';
+} | {
+    readonly kind: 'cancel';
+} | {
+    readonly kind: 'undo';
+} | {
+    readonly kind: 'hint';
+} | {
+    readonly kind: 'select-tool';
+    readonly tool: StoredTool;
+} | {
+    readonly kind: 'target-tool';
+    readonly cell: number;
+} | {
+    readonly kind: 'confirm-tool';
+} | {
+    readonly kind: 'cancel-tool';
+};
+export interface GameEvent {
+    readonly type: string;
+    readonly [key: string]: unknown;
+}
+export interface Transition {
+    readonly state: GameState;
+    readonly events: readonly GameEvent[];
+    readonly accepted: boolean;
+    readonly reason?: string;
+}
+export interface CreateOptions {
+    readonly mode?: Exclude<GameMode, 'challenge'>;
+    readonly preset?: BoardPreset;
+    readonly width?: number;
+    readonly height?: number;
+    readonly colourCount?: 4 | 5 | 6;
+    readonly seed?: string | number;
+    readonly shape?: BoardShape;
+    /** Row-major custom active-cell mask. Supply width and height with a custom mask. */
+    readonly mask?: readonly boolean[];
+    /** Required for Daily; supplied by the host in UTC. */
+    readonly dailyDate?: string;
+    /** Optional Bomb and Pick tray; available only in Relaxed and Arcade. */
+    readonly tools?: boolean;
+}
+export interface ChallengeOptions {
+    readonly id: string;
+    readonly width: number;
+    readonly height: number;
+    readonly colourCount: 4 | 5 | 6;
+    readonly seed?: string | number;
+    readonly mask?: readonly boolean[];
+    readonly initialBoard: readonly (Stone | null)[];
+    readonly goal: ChallengeGoal;
+    readonly moveLimit?: number;
+    readonly witness: readonly (readonly number[])[];
+}
+export interface GameStatus {
+    readonly mode: GameMode;
+    readonly phase: GamePhase;
+    readonly score: number;
+    readonly moves: number;
+    readonly removed: number;
+    readonly remaining: number;
+    readonly previewScore: number;
+    readonly usedFallback: boolean;
+    readonly assisted: boolean;
+    readonly goal?: ChallengeGoal;
+    readonly reason?: string;
+    readonly inventory: ToolInventory;
+    readonly toolProgress: number;
+    readonly toolAwardCursor: 0 | 1;
+    readonly selectedTool: StoredTool | null;
+    readonly toolTarget: number | null;
+    readonly toolPreview: readonly number[];
+}

package/dist/stone-collapse/types.js

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

package/dist/stone-collapse/validation.d.ts

@@ -0,0 +1,21 @@
+import type { BoardShape, CreateOptions, GameMode } from './types.js';
+/** Typed public-settings validation error. */
+export declare class StoneCollapseOptionsError extends RangeError {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export interface NormalizedOptions {
+    readonly mode: Exclude<GameMode, 'challenge'>;
+    readonly dailyDate?: string;
+    readonly width: number;
+    readonly height: number;
+    readonly colourCount: 4 | 5 | 6;
+    readonly seed: string | number;
+    readonly tools: boolean;
+    readonly shape?: BoardShape;
+    readonly mask: readonly boolean[];
+}
+/** Returns orthogonal active neighbors in deterministic row-major order. */
+export declare function neighbors(index: number, width: number, height: number, mask: readonly boolean[]): number[];
+/** Validates all public score-game options before any random draw occurs. */
+export declare function optionsFor(options: CreateOptions): NormalizedOptions;

package/dist/stone-collapse/validation.js

@@ -0,0 +1,134 @@
+const PRESETS = {
+    compact: [6, 8], standard: [8, 10], wide: [10, 8], tall: [6, 12], extraWide: [16, 10], deep: [8, 32], large: [12, 32],
+};
+/** Typed public-settings validation error. */
+export class StoneCollapseOptionsError extends RangeError {
+    code;
+    constructor(code, message) { super(message); this.name = 'StoneCollapseOptionsError'; this.code = code; }
+}
+function shapeMask(shape) {
+    if (shape === 'heart') {
+        const width = 10;
+        const rows = [
+            [1, 3, 6, 8], [0, 4, 5, 9], [0, 9], [0, 9], [1, 8], [2, 7], [3, 6], [4, 5], [4, 5], [4, 5],
+        ];
+        return [width, rows.length, rows.flatMap(([a, b, c, d]) => Array.from({ length: width }, (_, x) => x >= a && x <= b || c !== undefined && x >= c && x <= d))];
+    }
+    if (shape === 'star') {
+        const width = 12;
+        const rowRanges = [
+            [5, 6], [5, 6], [4, 7], [4, 7], [0, 11], [0, 11], [2, 9], [2, 9], [3, 8], [3, 8], [4, 7], [4, 7],
+        ];
+        return [width, rowRanges.length, rowRanges.flatMap(([a, b]) => Array.from({ length: width }, (_, x) => x >= a && x <= b))];
+    }
+    const width = 10;
+    const rowRanges = [
+        [2, 7], [1, 8], [0, 9], [0, 9], [0, 9], [0, 9], [0, 9], [0, 9], [1, 8], [2, 7],
+    ];
+    return [width, rowRanges.length, rowRanges.flatMap(([a, b]) => Array.from({ length: width }, (_, x) => x >= a && x <= b))];
+}
+/** Returns orthogonal active neighbors in deterministic row-major order. */
+export function neighbors(index, width, height, mask) {
+    const x = index % width;
+    const y = Math.floor(index / width);
+    const out = [];
+    if (x > 0 && mask[index - 1])
+        out.push(index - 1);
+    if (x + 1 < width && mask[index + 1])
+        out.push(index + 1);
+    if (y > 0 && mask[index - width])
+        out.push(index - width);
+    if (y + 1 < height && mask[index + width])
+        out.push(index + width);
+    return out;
+}
+function validateMask(mask, width, height) {
+    if (!Array.isArray(mask))
+        throw new StoneCollapseOptionsError('invalid-mask', 'Mask must be a boolean array');
+    if (mask.length !== width * height || Array.from(mask).some(value => typeof value !== 'boolean'))
+        throw new StoneCollapseOptionsError('invalid-mask-size', 'Mask must contain one boolean per board cell');
+    const active = mask.flatMap((on, i) => on ? [i] : []);
+    if (active.length < 16 || active.length > 512)
+        throw new StoneCollapseOptionsError('invalid-active-count', 'A board must have 16–512 active cells');
+    if (active.some(index => neighbors(index, width, height, mask).length === 0))
+        throw new StoneCollapseOptionsError('isolated-mask-cell', 'Mask cannot contain an isolated active cell');
+    const visited = new Set([active[0]]);
+    const pending = [active[0]];
+    while (pending.length)
+        for (const next of neighbors(pending.pop(), width, height, mask))
+            if (!visited.has(next)) {
+                visited.add(next);
+                pending.push(next);
+            }
+    if (visited.size !== active.length)
+        throw new StoneCollapseOptionsError('disconnected-mask', 'Active mask cells must be orthogonally connected');
+}
+function isUtcDate(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;
+}
+/** Validates all public score-game options before any random draw occurs. */
+export function optionsFor(options) {
+    if (!options || typeof options !== 'object' || Array.isArray(options))
+        throw new StoneCollapseOptionsError('invalid-options', 'Options must be an object');
+    const allowedKeys = ['mode', 'preset', 'width', 'height', 'colourCount', 'seed', 'shape', 'mask', 'dailyDate', 'tools'];
+    if (Object.keys(options).some(key => !allowedKeys.includes(key)))
+        throw new StoneCollapseOptionsError('unknown-option', 'Create options contain an unsupported field');
+    const mode = options.mode === undefined ? 'relaxed' : options.mode;
+    if (!['relaxed', 'arcade', 'daily'].includes(mode))
+        throw new StoneCollapseOptionsError('invalid-mode', 'Create options support Relaxed, Arcade, or Daily score play');
+    if (options.tools !== undefined && typeof options.tools !== 'boolean')
+        throw new StoneCollapseOptionsError('invalid-tools-option', 'tools must be a boolean');
+    if (mode === 'daily') {
+        if (options.tools === true)
+            throw new StoneCollapseOptionsError('daily-tools-disabled', 'Daily does not allow stored tools');
+        if (typeof options.dailyDate !== 'string' || !isUtcDate(options.dailyDate))
+            throw new StoneCollapseOptionsError('invalid-daily-date', 'Daily requires a valid UTC YYYY-MM-DD date from the host');
+        if (options.preset !== undefined || options.width !== undefined || options.height !== undefined || options.colourCount !== undefined || options.seed !== undefined || options.shape !== undefined || options.mask !== undefined)
+            throw new StoneCollapseOptionsError('noncanonical-daily-settings', 'Daily uses the fixed standard 8×10 rectangular board and four colours');
+        return { mode, dailyDate: options.dailyDate, width: 8, height: 10, colourCount: 4, seed: `stone-collapse:daily:${options.dailyDate}`, tools: false, mask: Array(80).fill(true) };
+    }
+    if (options.dailyDate !== undefined)
+        throw new StoneCollapseOptionsError('daily-date-outside-daily', 'dailyDate is supported only in Daily mode');
+    const hasDimensions = options.width !== undefined || options.height !== undefined;
+    let width;
+    let height;
+    const shape = options.shape;
+    let mask = options.mask;
+    if (shape !== undefined) {
+        if (options.preset !== undefined || hasDimensions || mask !== undefined || !['heart', 'star', 'hexagon'].includes(shape))
+            throw new StoneCollapseOptionsError('conflicting-board-options', 'Choose one shape or one rectangular preset/custom size');
+        [width, height, mask] = shapeMask(shape);
+    }
+    else if (mask !== undefined) {
+        if (options.preset !== undefined || options.width === undefined || options.height === undefined)
+            throw new StoneCollapseOptionsError('custom-mask-dimensions-required', 'A custom mask requires explicit width and height and cannot use a preset');
+        width = options.width;
+        height = options.height;
+    }
+    else {
+        const presetName = options.preset === undefined ? 'standard' : options.preset;
+        if (!Object.hasOwn(PRESETS, presetName))
+            throw new StoneCollapseOptionsError('invalid-preset', 'Unknown board preset');
+        const preset = PRESETS[presetName];
+        if (hasDimensions && options.preset !== undefined)
+            throw new StoneCollapseOptionsError('conflicting-board-options', 'Choose a preset or custom dimensions');
+        width = options.width ?? preset[0];
+        height = options.height ?? preset[1];
+        if (!Number.isInteger(width) || !Number.isInteger(height) || width < 4 || width > 16 || height < 4 || height > 32 || width * height > 512)
+            throw new StoneCollapseOptionsError('invalid-board-size', 'Board dimensions must be 4–16 columns by 4–32 rows, with at most 512 cells');
+        mask = Array(width * height).fill(true);
+    }
+    if (!Number.isInteger(width) || !Number.isInteger(height) || width < 4 || width > 16 || height < 4 || height > 32 || width * height > 512)
+        throw new StoneCollapseOptionsError('invalid-board-size', 'Board dimensions must be 4–16 columns by 4–32 rows, with at most 512 cells');
+    validateMask(mask, width, height);
+    const colourCount = options.colourCount ?? 4;
+    if (colourCount !== 4 && colourCount !== 5 && colourCount !== 6)
+        throw new StoneCollapseOptionsError('invalid-colour-count', 'Colour count must be 4, 5, or 6');
+    const seed = options.seed === undefined ? 'houseki-stone-collapse' : options.seed;
+    if (typeof seed !== 'string' && (!Number.isInteger(seed) || seed < 0 || seed > 0xffff_ffff))
+        throw new StoneCollapseOptionsError('invalid-seed', 'Numeric seed must be an unsigned 32-bit integer');
+    return { mode, width: width, height: height, colourCount, seed, tools: options.tools ?? false, ...(shape ? { shape } : {}), mask: [...mask] };
+}

package/dist/stone-collapse.d.ts

@@ -0,0 +1,6 @@
+export { StoneCollapseOptionsError } from './stone-collapse/validation.js';
+export { createGame, createChallenge, applyAction, advanceTicks, legalActions, requestHint, undo, statusOf } from './stone-collapse/engine.js';
+export { restartGame, encodeGame, decodeGame } from './stone-collapse/persistence.js';
+export { campaignManifest, levelManifest, tutorialManifest, getLevel, createLevel, getTutorial } from './stone-collapse/content.js';
+export type { Action, BoardPreset, BoardShape, ChallengeDefinition, ChallengeGoal, ChallengeOptions, CreateOptions, GameEvent, GameMode, GamePhase, GameState, GameStatus, RecordedAction, Settings, Stone, StoneColour, StoredTool, ToolInventory, Transition, UndoFrame } from './stone-collapse/types.js';
+export type { CollapseCampaignLevel, CollapseCampaignManifest, CollapseDifficultyMetrics, CollapseTutorialDefinition, CollapseTutorialStep, LocalizedText } from './stone-collapse/content-types.js';

package/dist/stone-collapse.js

@@ -0,0 +1,4 @@
+export { StoneCollapseOptionsError } from './stone-collapse/validation.js';
+export { createGame, createChallenge, applyAction, advanceTicks, legalActions, requestHint, undo, statusOf } from './stone-collapse/engine.js';
+export { restartGame, encodeGame, decodeGame } from './stone-collapse/persistence.js';
+export { campaignManifest, levelManifest, tutorialManifest, getLevel, createLevel, getTutorial } from './stone-collapse/content.js';