@johnmorrisdotca/houseki 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,200 @@
+/** A colour used by a normal gem. */
+export type GemColour = 'red' | 'blue' | 'green' | 'gold' | 'purple' | 'teal';
+export type SpecialKind = 'row-beam' | 'column-beam' | 'bomb' | 'colour-burst';
+export type ToolKind = 'bomb' | 'row-clear' | 'colour-clear' | 'black-hole';
+export type OrdinaryToolKind = Exclude<ToolKind, 'black-hole'>;
+export type ToolInventory = Readonly<Record<OrdinaryToolKind, number>>;
+export interface BlackHolePortal {
+    readonly cell: number;
+    readonly capacityRemaining: number;
+    readonly movesRemaining: number;
+    readonly consumedIds: readonly number[];
+}
+/** A gem has a stable identity and stored colour until it is cleared. Missing kind means normal. */
+export interface Gem {
+    readonly id: number;
+    readonly colour: GemColour;
+    readonly kind?: SpecialKind;
+}
+export interface PlannedSpecial {
+    readonly cell: number;
+    readonly kind: SpecialKind;
+}
+export type BoardPreset = 'compact' | 'standard' | 'wide' | 'tall' | 'extraWide' | 'deep' | 'large';
+export type BoardShape = 'heart' | 'star' | 'hexagon';
+export type GamePhase = 'ready' | 'clear-mark' | 'clear-remove' | 'gravity' | 'refill' | 'finished';
+export type GameMode = 'relaxed' | 'arcade' | 'daily' | 'challenge';
+export type GameOutcome = 'won' | 'lost' | 'finished' | null;
+export type Goal = {
+    readonly kind: 'score';
+    readonly target: number;
+} | {
+    readonly kind: 'collect';
+    readonly colour: GemColour;
+    readonly target: number;
+} | {
+    readonly kind: 'chain';
+    readonly target: number;
+} | {
+    readonly kind: 'seals';
+};
+export interface Seal {
+    readonly cell: number;
+    readonly layers: number;
+}
+export interface ChallengeRules {
+    readonly goals: readonly Goal[];
+    readonly moveLimit?: number;
+    readonly seals?: readonly Seal[];
+}
+export type ReplayOperation = {
+    readonly kind: 'action';
+    readonly action: Action;
+} | {
+    readonly kind: 'ticks';
+    readonly count: number;
+} | {
+    readonly kind: 'time';
+    readonly milliseconds: number;
+};
+export interface Settings {
+    readonly width: number;
+    readonly height: number;
+    readonly colourCount: 4 | 5 | 6;
+    readonly seed: string | number;
+    readonly tools: boolean;
+    readonly advancedTools: boolean;
+    readonly shape?: BoardShape;
+    readonly mask: readonly boolean[];
+}
+export interface GameState {
+    readonly game: 'gem-swap';
+    readonly rules: 'swap-1';
+    readonly settings: Settings;
+    readonly initialOptions: CreateOptions;
+    readonly mode: GameMode;
+    readonly dailyDate: string | null;
+    readonly challenge: ChallengeRules | null;
+    readonly seals: readonly Seal[];
+    readonly sealsCleared: number;
+    readonly elapsedMs: number;
+    readonly outcome: GameOutcome;
+    readonly clearedByColour: Readonly<Record<GemColour, number>>;
+    readonly bestChain: number;
+    readonly history: readonly ReplayOperation[];
+    /** Row-major. Mask gaps and the holes in clear phases contain null. */
+    readonly board: readonly (Gem | null)[];
+    readonly phase: GamePhase;
+    readonly score: number;
+    readonly moves: number;
+    readonly swapCount: number;
+    readonly randomState: number;
+    readonly nextId: number;
+    readonly usedFallback: boolean;
+    readonly wave: number;
+    readonly resolutionTick: number;
+    readonly pendingCells: readonly number[];
+    readonly pendingSpecials: readonly PlannedSpecial[];
+    readonly gravityBoard: readonly (Gem | null)[] | null;
+    readonly inventory: ToolInventory;
+    readonly selectedTool: ToolKind | null;
+    readonly toolTarget: number | null;
+    readonly toolPreview: readonly number[];
+    readonly toolProgress: number;
+    readonly toolAwardCursor: number;
+    readonly assisted: boolean;
+    /** Remains true across cascades originating from one tool use. */
+    readonly toolWaveActive: boolean;
+    readonly blackHoleCharges: 0 | 1;
+    readonly blackHoleProgress: number;
+    readonly blackHole: BlackHolePortal | null;
+    readonly blackHoleMovePending: boolean;
+    readonly blackHoleContactPending: boolean;
+    readonly pendingBlackHole: boolean;
+}
+/** Swaps two row-major cell addresses. */
+export interface SwapAction {
+    readonly kind: 'swap';
+    readonly from: number;
+    readonly to: number;
+}
+export interface SelectToolAction {
+    readonly kind: 'select-tool';
+    readonly tool: ToolKind;
+}
+export interface TargetToolAction {
+    readonly kind: 'target-tool';
+    readonly cell: number;
+}
+export interface ConfirmToolAction {
+    readonly kind: 'confirm-tool';
+}
+export interface CancelToolAction {
+    readonly kind: 'cancel-tool';
+}
+export interface UndoAction {
+    readonly kind: 'undo';
+}
+export interface HintAction {
+    readonly kind: 'hint';
+}
+export interface ReshuffleAction {
+    readonly kind: 'reshuffle';
+}
+export type Action = SwapAction | SelectToolAction | TargetToolAction | ConfirmToolAction | CancelToolAction | UndoAction | HintAction | ReshuffleAction;
+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 preset?: BoardPreset;
+    readonly width?: number;
+    readonly height?: number;
+    readonly colourCount?: 4 | 5 | 6;
+    readonly seed?: string | number;
+    readonly tools?: boolean;
+    readonly advancedTools?: boolean;
+    readonly shape?: BoardShape;
+    /** Row-major active-cell mask. Requires explicit custom dimensions. */
+    readonly mask?: readonly boolean[];
+    readonly mode?: GameMode;
+    /** Required for Daily; a UTC calendar date in YYYY-MM-DD form. */
+    readonly dailyDate?: string;
+    /** Challenge-only finite goals and optional legal-swap budget. */
+    readonly challenge?: ChallengeRules;
+}
+export interface GameStatus {
+    readonly phase: GamePhase;
+    readonly score: number;
+    readonly moves: number;
+    readonly legalMoveCount: number;
+    readonly usedFallback: boolean;
+    readonly availableToolCount: number;
+    readonly inventory: ToolInventory;
+    readonly toolProgress: number;
+    readonly toolAwardCursor: number;
+    readonly assisted: boolean;
+    readonly blackHoleCharges: 0 | 1;
+    readonly blackHoleProgress: number;
+    readonly blackHole: BlackHolePortal | null;
+    readonly mode: GameMode;
+    readonly outcome: GameOutcome;
+    readonly remainingMoves: number | null;
+    readonly elapsedMs: number;
+    readonly remainingMs: number | null;
+    readonly goals: readonly Goal[];
+    readonly goalProgress: readonly {
+        readonly kind: Goal['kind'];
+        readonly current: number;
+        readonly target: number;
+        readonly colour?: GemColour;
+        readonly complete: boolean;
+    }[];
+    readonly bestChain: number;
+}

package/dist/gem-swap/types.js

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

package/dist/gem-swap.d.ts

@@ -0,0 +1,5 @@
+export type { Action, BlackHolePortal, BoardPreset, BoardShape, CancelToolAction, ChallengeRules, ConfirmToolAction, CreateOptions, GameEvent, GameMode, GameOutcome, GamePhase, GameState, GameStatus, Gem, GemColour, Goal, HintAction, OrdinaryToolKind, PlannedSpecial, ReplayOperation, ReshuffleAction, Seal, SelectToolAction, Settings, SpecialKind, SwapAction, TargetToolAction, ToolInventory, ToolKind, Transition, UndoAction } from './gem-swap/types.js';
+export { GemSwapOptionsError, createGame, applyAction, advanceTicks, advanceTime, legalActions, statusOf, hintGame, reshuffleGame, undoGame } from './gem-swap/engine.js';
+export { ReplayError, encodeGame, decodeGame, restartGame, validateChallengeWitness } from './gem-swap/persistence.js';
+export { CAMPAIGN_CHECKSUM, CAMPAIGN_COUNT, GENERATION_REVISION, GRADING_VERSION, GRADING_WEIGHTS, SAMPLE_BUDGET, GEM_SWAP_CAMPAIGN, GEM_SWAP_LESSONS } from './gem-swap/content.js';
+export type { GemSwapCampaignLevel, GemSwapLesson, GemSwapLessonStep, GemSwapReviewStatus } from './gem-swap/content.js';

package/dist/gem-swap.js

@@ -0,0 +1,3 @@
+export { GemSwapOptionsError, createGame, applyAction, advanceTicks, advanceTime, legalActions, statusOf, hintGame, reshuffleGame, undoGame } from './gem-swap/engine.js';
+export { ReplayError, encodeGame, decodeGame, restartGame, validateChallengeWitness } from './gem-swap/persistence.js';
+export { CAMPAIGN_CHECKSUM, CAMPAIGN_COUNT, GENERATION_REVISION, GRADING_VERSION, GRADING_WEIGHTS, SAMPLE_BUDGET, GEM_SWAP_CAMPAIGN, GEM_SWAP_LESSONS } from './gem-swap/content.js';

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+/** Original immutable game engines, grouped by game. */
+export * as fallingTriplets from './falling-triplets.js';
+export * as stoneCollapse from './stone-collapse.js';
+export * as colourChains from './colour-chains.js';
+export * as gemSwap from './gem-swap.js';
+export * as nature from './nature.js';
+export * as magneticBlocks from './magnetic-blocks.js';

package/dist/index.js

@@ -0,0 +1,7 @@
+/** Original immutable game engines, grouped by game. */
+export * as fallingTriplets from './falling-triplets.js';
+export * as stoneCollapse from './stone-collapse.js';
+export * as colourChains from './colour-chains.js';
+export * as gemSwap from './gem-swap.js';
+export * as nature from './nature.js';
+export * as magneticBlocks from './magnetic-blocks.js';

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

@@ -0,0 +1,11 @@
+import type { Action, GameState, GameStatus, Transition } from './types.js';
+/** Creates an immutable seeded 2×2-block game with a fixed queue and explicit floor schedule. */
+export declare function createGame(options?: import('./types.js').CreateOptions): GameState;
+/** Applies one movement, rotation, floor-switch or placement action without mutation. */
+export declare function applyAction(state: GameState, action: Action): Transition;
+/** Advances fixed 60 Hz time, resolving phases in all modes and falling/locking only in Arcade. */
+export declare function advanceTicks(state: GameState, ticks: number): Transition;
+/** Lists accepted controls for the current falling or resolution phase. */
+export declare function legalActions(state: GameState): readonly Action[];
+/** Returns a compact immutable status including current and upcoming floor state. */
+export declare function statusOf(state: GameState): GameStatus;

package/dist/magnetic-blocks/engine.js

@@ -0,0 +1,263 @@
+import { nextInt, seedState } from './random.js';
+import { allMatchedCells, blockBonds, blockCells, canPlace, impactSupportIds, landingY, matchGroups, removeIds, settle, MARK_TICKS, REMOVE_TICKS, GRAVITY_TICKS } from './physics.js';
+import { COLOURS, validateOptions } from './validation.js';
+function floorAt(schedule, placement) {
+    switch (schedule.kind) {
+        case 'frequent': return placement % 2 === 0 ? 'magnetic' : 'calm';
+        case 'occasional': return placement % 4 === 0 ? 'magnetic' : 'calm';
+        case 'infrequent': return placement % 8 === 0 ? 'magnetic' : 'calm';
+        case 'mid-level': return placement === schedule.placement ? 'magnetic' : 'calm';
+        case 'fixed': return schedule.floor;
+        case 'authored': return schedule.magneticPlacements.includes(placement) ? 'magnetic' : schedule.defaultFloor ?? 'calm';
+    }
+}
+function drawQueue(seed, count, colourCount) {
+    let randomState = seedState(`magnetic-blocks|magnetic-blocks-1|${String(seed)}`);
+    const queue = [];
+    for (let piece = 0; piece < count; piece++) {
+        const colours = [];
+        for (let i = 0; i < 4; i++) {
+            const [index, next] = nextInt(randomState, colourCount);
+            randomState = next;
+            colours.push(COLOURS[index]);
+        }
+        queue.push(Object.freeze(colours));
+    }
+    return { queue: Object.freeze(queue), randomState };
+}
+function freezeBlock(block) { return Object.freeze({ ...block, gems: Object.freeze(block.gems.map(gem => Object.freeze({ ...gem }))) }); }
+function freezeState(state) { return Object.freeze(state); }
+function freezeBonds(bonds) { return Object.freeze(bonds.map(edge => Object.freeze({ a: edge.a, b: edge.b })).sort((a, b) => a.a - b.a || a.b - b.b)); }
+function empty(state, reason) { return { state, events: Object.freeze([]), accepted: false, reason }; }
+function completeGoal(state) {
+    const goal = state.settings.goal;
+    if (!goal)
+        return false;
+    return goal.kind === 'clear-all' ? state.board.every(gem => gem === null) : goal.targetIds.every(id => !state.board.some(gem => gem?.id === id));
+}
+function spawn(state) {
+    if (completeGoal(state))
+        return [{ ...state, phase: 'won', active: null, reason: 'goal-complete' }, [{ type: 'run-ended', result: 'won', reason: 'goal-complete', score: state.score }]];
+    if (state.placements >= state.settings.pieceLimit || !state.queue.length)
+        return [{ ...state, phase: 'finished', active: null, reason: 'queue-exhausted' }, [{ type: 'run-ended', result: 'finished', reason: 'queue-exhausted', score: state.score }]];
+    const [colours, ...rest] = state.queue, gems = colours.map((colour, index) => ({ id: state.nextId + index, colour }));
+    const block = freezeBlock({ x: Math.floor(state.settings.width / 2) - 1, y: 0, orientation: 0, gems, descent: 0, lockTicks: 0, lockResets: 0, lockStarted: false });
+    const floor = floorAt(state.settings.schedule, state.placements + 1);
+    if (!canPlace(block, state.board, state.settings.width, state.settings.height, state.settings.mask))
+        return [{ ...state, queue: Object.freeze(rest), nextId: state.nextId + 4, active: null, phase: 'lost', floor, nextFloor: floorAt(state.settings.schedule, state.placements + 2), reason: 'top-out' }, [{ type: 'run-ended', result: 'lost', reason: 'top-out', score: state.score }]];
+    const next = { ...state, queue: Object.freeze(rest), nextId: state.nextId + 4, active: block, phase: 'falling', floor, nextFloor: floorAt(state.settings.schedule, state.placements + 2), chain: 0, reason: undefined };
+    return [next, [{ type: 'piece-spawned', ids: block.gems.map(gem => gem.id), x: block.x, y: block.y, floor, nextFloor: next.nextFloor }]];
+}
+function startMatchOrSpawn(state) {
+    const groups = matchGroups(state.board, state.settings.width, state.settings.height, state.settings.mask), cells = allMatchedCells(groups);
+    if (cells.length)
+        return [{ ...state, phase: 'clear-mark', pendingClear: Object.freeze([...cells]), resolutionTick: 0, chain: state.chain + 1, maxChain: Math.max(state.maxChain, state.chain + 1), gravityBoard: null }, [{ type: 'match-marked', chain: state.chain + 1, cells, ids: cells.map(index => state.board[index].id) }]];
+    if (completeGoal(state))
+        return [{ ...state, phase: 'won', active: null, reason: 'goal-complete' }, [{ type: 'run-ended', result: 'won', reason: 'goal-complete', score: state.score }]];
+    return spawn(state);
+}
+function place(state, action) {
+    const hardDrop = action.kind === 'hard-drop';
+    const active = state.active;
+    const { width, height, mask, magneticImpact } = state.settings;
+    const landing = { ...active, y: landingY(active, state.board, width, height, mask) };
+    const floor = state.pendingFloorOverride ?? state.floor;
+    let board = [...state.board], bonds = [...state.bonds], impactIds = Object.freeze([]);
+    const events = [];
+    if (floor === 'magnetic' && magneticImpact && hardDrop) {
+        impactIds = impactSupportIds(landing, board, width, height, mask);
+        if (impactIds.length) {
+            const remove = new Set(impactIds);
+            board = board.map(gem => gem && remove.has(gem.id) ? null : gem);
+            bonds = bonds.filter(edge => !remove.has(edge.a) && !remove.has(edge.b));
+            events.push({ type: 'magnetic-impact', floor, removedIds: impactIds, cells: impactIds.map(id => state.board.findIndex(gem => gem?.id === id)) });
+        }
+    }
+    for (const { index, gem } of blockCells(landing, width))
+        board[index] = gem;
+    bonds = floor === 'calm' ? [...bonds, ...blockBonds(landing)] : [];
+    const settled = settle(board, bonds, floor, width, height, mask);
+    const placements = state.placements + 1, charges = state.pendingFloorOverride && state.floorSwitchCharges ? 0 : state.floorSwitchCharges;
+    const next = { ...state, board: Object.freeze(board), bonds: freezeBonds(settled.bonds), active: null, phase: 'gravity', score: state.score, moves: state.moves + 1, placements, floor, nextFloor: floorAt(state.settings.schedule, placements + 1), floorSwitchCharges: charges, pendingFloorOverride: null, pendingClear: Object.freeze([]), gravityBoard: settled.board, resolutionTick: 0, impactRemovedIds: Object.freeze([...impactIds]), chain: 0 };
+    events.push({ type: 'piece-locked', ids: active.gems.map(gem => gem.id), cells: blockCells(landing, width).map(entry => entry.index), floor, hardDrop, consumedFloorSwitch: Boolean(state.pendingFloorOverride) });
+    return { state: next, events: Object.freeze(events), accepted: true };
+}
+function gravityResult(state) {
+    const board = state.gravityBoard ?? state.board;
+    const next = { ...state, board, gravityBoard: null, resolutionTick: 0 };
+    const [continued, events] = startMatchOrSpawn(next);
+    return [continued, [{ type: 'gravity-completed', floor: state.floor, board }, ...events]];
+}
+function core(state, action) {
+    if (!action || typeof action !== 'object' || !['left', 'right', 'soft-drop', 'rotate-clockwise', 'rotate-anticlockwise', 'hard-drop', 'land', 'pause', 'resume', 'set-floor-override', 'cancel-floor-override'].includes(action.kind ?? ''))
+        return empty(state, 'invalid-action');
+    const allowed = action.kind === 'set-floor-override' ? ['kind', 'floor'] : ['kind'];
+    if (Object.keys(action).some(key => !allowed.includes(key)) || action.kind === 'set-floor-override' && !['calm', 'magnetic'].includes(action.floor))
+        return empty(state, 'invalid-action');
+    if (action.kind === 'pause') {
+        if (!['falling', 'clear-mark', 'clear-remove', 'gravity'].includes(state.phase))
+            return empty(state, 'cannot-pause');
+        return { state: { ...state, phase: 'paused', pausedPhase: state.phase }, events: [{ type: 'paused' }], accepted: true };
+    }
+    if (action.kind === 'resume') {
+        if (state.phase !== 'paused')
+            return empty(state, 'not-paused');
+        const { pausedPhase, ...rest } = state;
+        return { state: { ...rest, phase: pausedPhase ?? 'falling' }, events: [{ type: 'resumed' }], accepted: true };
+    }
+    if (state.phase !== 'falling' || !state.active)
+        return empty(state, 'action-unavailable');
+    if (action.kind === 'set-floor-override') {
+        if (!state.settings.floorSwitch || !state.floorSwitchCharges)
+            return empty(state, 'floor-switch-unavailable');
+        const next = { ...state, pendingFloorOverride: action.floor };
+        return { state: next, events: [{ type: 'floor-override-selected', floor: action.floor, charges: state.floorSwitchCharges }], accepted: true };
+    }
+    if (action.kind === 'cancel-floor-override') {
+        if (!state.pendingFloorOverride)
+            return empty(state, 'no-floor-override');
+        return { state: { ...state, pendingFloorOverride: null }, events: [{ type: 'floor-override-cancelled', charges: state.floorSwitchCharges }], accepted: true };
+    }
+    const active = state.active, { width, height, mask } = state.settings;
+    if (action.kind === 'hard-drop') {
+        let landed = active;
+        while (canPlace({ ...landed, y: landed.y + 1 }, state.board, width, height, mask))
+            landed = { ...landed, y: landed.y + 1 };
+        return place({ ...state, active: freezeBlock(landed) }, action);
+    }
+    if (action.kind === 'land')
+        return place(state, action);
+    if (action.kind === 'soft-drop') {
+        if (!canPlace({ ...active, y: active.y + 1 }, state.board, width, height, mask))
+            return place(state, action);
+        const moved = { ...active, y: active.y + 1, descent: 0 };
+        const grounded = !canPlace({ ...moved, y: moved.y + 1 }, state.board, width, height, mask);
+        const next = { ...state, active: freezeBlock({ ...moved, ...(state.settings.mode === 'arcade' && grounded ? { lockStarted: true, lockTicks: 0 } : {}) }) };
+        return { state: next, events: [{ type: 'piece-moved', direction: 'down', y: next.active.y }], accepted: true };
+    }
+    if (action.kind === 'left' || action.kind === 'right') {
+        const x = active.x + (action.kind === 'left' ? -1 : 1), moved = { ...active, x };
+        if (!canPlace(moved, state.board, width, height, mask))
+            return empty(state, 'blocked');
+        const grounded = !canPlace({ ...active, y: active.y + 1 }, state.board, width, height, mask);
+        const reset = state.settings.mode === 'arcade' && grounded && active.lockResets < 8;
+        const nextGrounded = !canPlace({ ...moved, y: moved.y + 1 }, state.board, width, height, mask);
+        return { state: { ...state, active: freezeBlock({ ...moved, lockTicks: reset ? 0 : active.lockTicks, lockResets: active.lockResets + (reset ? 1 : 0), lockStarted: reset ? nextGrounded : nextGrounded || active.lockStarted, ...(state.settings.mode === 'arcade' && !nextGrounded && active.lockResets < 8 ? { lockTicks: 0, lockStarted: false } : {}) }) }, events: [{ type: 'piece-moved', direction: action.kind, x }], accepted: true };
+    }
+    const orientation = ((active.orientation + (action.kind === 'rotate-clockwise' ? 1 : 3)) % 4);
+    const rotated = { ...active, orientation };
+    if (!canPlace(rotated, state.board, width, height, mask))
+        return empty(state, 'blocked');
+    const grounded = !canPlace({ ...active, y: active.y + 1 }, state.board, width, height, mask);
+    const reset = state.settings.mode === 'arcade' && grounded && active.lockResets < 8;
+    return { state: { ...state, active: freezeBlock({ ...rotated, lockTicks: reset ? 0 : active.lockTicks, lockResets: active.lockResets + (reset ? 1 : 0), lockStarted: reset ? true : active.lockStarted }) }, events: [{ type: 'piece-rotated', orientation, ids: rotated.gems.map(gem => gem.id), cells: blockCells(rotated, width).map(item => item.index) }], accepted: true };
+}
+/** Creates an immutable seeded 2×2-block game with a fixed queue and explicit floor schedule. */
+export function createGame(options = {}) {
+    const valid = validateOptions(options);
+    let randomState, queue;
+    if (valid.queue) {
+        queue = valid.queue;
+        randomState = seedState(`magnetic-blocks|magnetic-blocks-1|${String(valid.seed)}`);
+    }
+    else {
+        const generated = drawQueue(valid.seed, valid.pieceLimit, valid.colourCount);
+        queue = generated.queue;
+        randomState = generated.randomState;
+    }
+    const nextId = Math.max(0, ...valid.initialBoard.flatMap(gem => gem ? [gem.id] : [])) + 1;
+    const settings = Object.freeze({ mode: valid.mode, width: valid.width, height: valid.height, colourCount: valid.colourCount, seed: valid.seed, mask: valid.mask, schedule: valid.schedule, floorSwitch: valid.floorSwitch, magneticImpact: valid.magneticImpact, pieceLimit: valid.pieceLimit, initialBoard: valid.initialBoard, bonds: valid.bonds, ...(valid.queue ? { initialQueue: valid.queue } : {}), ...(valid.goal ? { goal: valid.goal } : {}) });
+    const state = { game: 'magnetic-blocks', rules: 'magnetic-blocks-1', settings, board: valid.initialBoard, bonds: valid.bonds, active: null, queue, randomState, nextId, phase: 'falling', score: 0, moves: 0, placements: 0, chain: 0, maxChain: 0, floor: floorAt(valid.schedule, 1), nextFloor: floorAt(valid.schedule, 2), floorSwitchCharges: valid.floorSwitch ? 1 : 0, pendingFloorOverride: null, pendingClear: Object.freeze([]), gravityBoard: null, resolutionTick: 0, impactRemovedIds: Object.freeze([]), elapsedTicks: 0, recording: Object.freeze([]) };
+    if (matchGroups(state.board, valid.width, valid.height, valid.mask).length)
+        throw new RangeError('Initial board must not contain a clearable group');
+    const [started] = spawn(state);
+    return freezeState(started);
+}
+/** Applies one movement, rotation, floor-switch or placement action without mutation. */
+export function applyAction(state, action) {
+    const result = core(state, action);
+    if (!result.accepted)
+        return { ...result, state: freezeState(result.state) };
+    const previous = state.recording.at(-1);
+    const ordinal = previous?.tick === state.elapsedTicks ? previous.ordinal + 1 : 0;
+    const recorded = Object.freeze({ tick: state.elapsedTicks, ordinal, action: Object.freeze({ ...action }) });
+    const next = freezeState({ ...result.state, recording: Object.freeze([...state.recording, recorded]) });
+    return { ...result, state: next };
+}
+/** Advances fixed 60 Hz time, resolving phases in all modes and falling/locking only in Arcade. */
+export function advanceTicks(state, ticks) {
+    if (!Number.isInteger(ticks) || ticks < 0 || ticks > 3600)
+        throw new RangeError('ticks must be an integer from 0 to 3600');
+    let current = state;
+    const events = [];
+    for (let i = 0; i < ticks; i++) {
+        if (['paused', 'won', 'lost', 'finished'].includes(current.phase))
+            break;
+        if (current.phase === 'falling' && !current.active)
+            break;
+        current = { ...current, elapsedTicks: current.elapsedTicks + 1 };
+        if (current.phase === 'falling') {
+            if (current.settings.mode === 'relaxed' || !current.active)
+                continue;
+            const active = current.active, grounded = !canPlace({ ...active, y: active.y + 1 }, current.board, current.settings.width, current.settings.height, current.settings.mask);
+            if (grounded) {
+                const lockTicks = active.lockStarted ? active.lockTicks + 1 : 0;
+                current = { ...current, active: freezeBlock({ ...active, lockStarted: true, lockTicks }) };
+                if (lockTicks >= 24) {
+                    const result = place(current, { kind: 'land' });
+                    current = result.state;
+                    events.push(...result.events);
+                }
+                continue;
+            }
+            const interval = Math.max(6, Math.round(60 * 0.85 ** Math.floor(current.placements / 30)));
+            if (active.descent + 1 >= interval) {
+                const fallen = freezeBlock({ ...active, y: active.y + 1, descent: 0 });
+                const nowGrounded = !canPlace({ ...fallen, y: fallen.y + 1 }, current.board, current.settings.width, current.settings.height, current.settings.mask);
+                current = { ...current, active: freezeBlock({ ...fallen, lockStarted: nowGrounded ? true : active.lockResets < 8 ? false : active.lockStarted, lockTicks: nowGrounded || active.lockResets >= 8 ? active.lockTicks : 0 }) };
+                events.push({ type: 'piece-fell', id: active.gems[0].id, fromY: active.y, toY: active.y + 1, grounded: nowGrounded });
+            }
+            else
+                current = { ...current, active: freezeBlock({ ...active, descent: active.descent + 1, ...(active.lockResets < 8 ? { lockTicks: 0, lockStarted: false } : {}) }) };
+            continue;
+        }
+        const resolutionTick = current.resolutionTick + 1;
+        current = { ...current, resolutionTick };
+        if (current.phase === 'clear-mark' && resolutionTick >= MARK_TICKS) {
+            const removed = removeIds(current.board, current.bonds, current.pendingClear);
+            const remainingIds = new Set(removed.board.flatMap(gem => gem ? [gem.id] : []));
+            const gravity = settle(removed.board, removed.bonds, current.floor, current.settings.width, current.settings.height, current.settings.mask);
+            const points = removed.ids.length * 10 * Math.max(1, current.chain);
+            current = { ...current, board: removed.board, bonds: gravity.bonds, score: current.score + points, phase: 'clear-remove', resolutionTick: 0, gravityBoard: gravity.board, pendingClear: Object.freeze([]) };
+            events.push({ type: 'cells-removed', ids: removed.ids, board: current.board, points, remainingIds: [...remainingIds] }, { type: 'score-changed', score: current.score, points });
+        }
+        else if (current.phase === 'clear-remove' && resolutionTick >= REMOVE_TICKS) {
+            current = { ...current, phase: 'gravity', resolutionTick: 0 };
+            events.push({ type: 'gravity-started', floor: current.floor, board: current.board, settledBoard: current.gravityBoard });
+        }
+        else if (current.phase === 'gravity' && resolutionTick >= GRAVITY_TICKS) {
+            const result = gravityResult(current);
+            current = result[0];
+            events.push(...result[1]);
+        }
+    }
+    return { state: freezeState(current), events: Object.freeze(events), accepted: true };
+}
+/** Lists accepted controls for the current falling or resolution phase. */
+export function legalActions(state) {
+    if (state.phase === 'paused')
+        return Object.freeze([{ kind: 'resume' }]);
+    if (['clear-mark', 'clear-remove', 'gravity'].includes(state.phase))
+        return Object.freeze([{ kind: 'pause' }]);
+    if (state.phase === 'falling' && state.active)
+        return Object.freeze([
+            ...(canPlace({ ...state.active, x: state.active.x - 1 }, state.board, state.settings.width, state.settings.height, state.settings.mask) ? [{ kind: 'left' }] : []),
+            ...(canPlace({ ...state.active, x: state.active.x + 1 }, state.board, state.settings.width, state.settings.height, state.settings.mask) ? [{ kind: 'right' }] : []),
+            { kind: 'soft-drop' }, { kind: 'rotate-clockwise' }, { kind: 'rotate-anticlockwise' }, { kind: 'hard-drop' }, { kind: 'land' },
+            ...(state.settings.floorSwitch && state.floorSwitchCharges ? [{ kind: 'set-floor-override', floor: 'calm' }, { kind: 'set-floor-override', floor: 'magnetic' }] : []),
+            ...(state.pendingFloorOverride ? [{ kind: 'cancel-floor-override' }] : []), { kind: 'pause' }
+        ]);
+    return Object.freeze([]);
+}
+/** Returns a compact immutable status including current and upcoming floor state. */
+export function statusOf(state) { return Object.freeze({ phase: state.phase, score: state.score, moves: state.moves, placements: state.placements, floor: state.pendingFloorOverride ?? state.floor, nextFloor: state.nextFloor, floorSwitchCharges: state.floorSwitchCharges, pendingFloorOverride: state.pendingFloorOverride, maxChain: state.maxChain, ...(state.reason ? { reason: state.reason } : {}) }); }

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

@@ -0,0 +1,7 @@
+import type { GameState } from './types.js';
+/** Restarts the same seed, custom starting board, fixed queue, rules and floor options. */
+export declare function restartGame(state: GameState): GameState;
+/** Encodes canonical settings, accepted tick-stamped actions and a verified replay checkpoint. */
+export declare function encodeGame(state: GameState): string;
+/** Replays bounded canonical input and verifies every saved checkpoint field. */
+export declare function decodeGame(text: string): GameState;

package/dist/magnetic-blocks/persistence.js

@@ -0,0 +1,104 @@
+import { advanceTicks, applyAction, createGame } from './engine.js';
+const RULES = 'magnetic-blocks-1';
+const MAX_SAVE_BYTES = 2 * 1024 * 1024;
+const MAX_ACTIONS = 100_000;
+const MAX_TICKS = 600_000;
+const ACTIONS = ['left', 'right', 'soft-drop', 'rotate-clockwise', 'rotate-anticlockwise', 'hard-drop', 'land', 'pause', 'resume', 'set-floor-override', 'cancel-floor-override'];
+function stable(value, depth = 0) {
+    if (depth > 60)
+        throw new TypeError('Save data 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 optionsFromSettings(settings) {
+    return {
+        mode: settings.mode, width: settings.width, height: settings.height, colourCount: settings.colourCount,
+        seed: settings.seed, mask: settings.mask, initialBoard: settings.initialBoard, bonds: settings.bonds,
+        ...(settings.initialQueue ? { queue: settings.initialQueue } : {}), pieceLimit: settings.pieceLimit,
+        schedule: settings.schedule, floorSwitch: settings.floorSwitch, magneticImpact: settings.magneticImpact,
+        ...(settings.goal ? { goal: settings.goal } : {}),
+    };
+}
+function createFromSettings(settings) {
+    if (!settings || typeof settings !== 'object' || Array.isArray(settings))
+        throw new TypeError('Save has invalid settings');
+    const state = createGame(optionsFromSettings(settings));
+    if (stable(state.settings) !== stable(settings))
+        throw new TypeError('Save settings are not canonical');
+    return state;
+}
+function replay(settings, actions, elapsedTicks) {
+    let state = createFromSettings(settings);
+    let previousTick = -1, previousOrdinal = -1;
+    for (let index = 0; index < actions.length; index++) {
+        const raw = 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 > elapsedTicks || !Number.isSafeInteger(item.ordinal) || !item.action || typeof item.action !== 'object' || Array.isArray(item.action) || !ACTIONS.includes(item.action.kind))
+            throw new TypeError(`Invalid action record ${index + 1}`);
+        const actionKeys = item.action.kind === 'set-floor-override' ? ['kind', 'floor'] : ['kind'];
+        if (Object.keys(item.action).some(key => !actionKeys.includes(key)))
+            throw new TypeError(`Invalid action fields at record ${index + 1}`);
+        if (item.action.kind === 'set-floor-override' && item.action.floor !== 'calm' && item.action.floor !== 'magnetic')
+            throw new TypeError(`Invalid floor override at 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 before = state.elapsedTicks;
+            state = advanceTicks(state, Math.min(3600, item.tick - state.elapsedTicks)).state;
+            if (state.elapsedTicks === before)
+                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;
+        previousTick = item.tick;
+        previousOrdinal = item.ordinal;
+    }
+    while (state.elapsedTicks < elapsedTicks) {
+        const before = state.elapsedTicks;
+        state = advanceTicks(state, Math.min(3600, elapsedTicks - state.elapsedTicks)).state;
+        if (state.elapsedTicks === before)
+            throw new TypeError('Checkpoint time exceeds the running game clock');
+    }
+    return state;
+}
+/** Restarts the same seed, custom starting board, fixed queue, rules and floor options. */
+export function restartGame(state) { return createFromSettings(state.settings); }
+/** Encodes canonical settings, accepted tick-stamped actions and a verified replay 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 derived = replay(state.settings, state.recording, state.elapsedTicks);
+    if (stable(derived) !== stable(state))
+        throw new TypeError('State does not match its recorded actions and clock');
+    const text = JSON.stringify({ format: 1, game: state.game, rules: state.rules, settings: state.settings, actions: state.recording, elapsedTicks: state.elapsedTicks, checkpoint: state });
+    if (new TextEncoder().encode(text).byteLength > MAX_SAVE_BYTES)
+        throw new RangeError('Save exceeds 2 MiB');
+    return text;
+}
+/** Replays bounded canonical input and verifies every saved checkpoint field. */
+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 !== 'magnetic-blocks' || value.rules !== RULES || !value.settings || !Array.isArray(value.actions) || !value.checkpoint || Object.keys(value).some(key => !['format', 'game', 'rules', 'settings', 'actions', 'elapsedTicks', 'checkpoint'].includes(key)))
+        throw new TypeError('Unsupported or invalid Magnetic Blocks 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');
+    const state = replay(value.settings, value.actions, value.elapsedTicks);
+    if (state.game !== value.game || state.rules !== value.rules || stable(state) !== stable(value.checkpoint))
+        throw new TypeError('Save checkpoint does not match its action recording');
+    return state;
+}