@johnmorrisdotca/houseki 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,30 @@
+import type { Block, Bond, Floor, Gem } from './types.js';
+export declare const HIDDEN_ROWS = 0;
+export declare const MARK_TICKS = 7, REMOVE_TICKS = 6, GRAVITY_TICKS = 9;
+export declare const cell: (x: number, y: number, width: number) => number;
+/** Returns stable-gem addresses after rotating the square block around its centre. */
+export declare function blockCells(block: Block, width: number): readonly {
+    readonly index: number;
+    readonly gem: Gem;
+}[];
+export declare function canPlace(block: Block, board: readonly (Gem | null)[], width: number, height: number, mask: readonly boolean[]): boolean;
+export declare function landingY(block: Block, board: readonly (Gem | null)[], width: number, height: number, mask: readonly boolean[]): number;
+/** Computes deterministic orthogonal colour components of at least four gems. */
+export declare function matchGroups(board: readonly (Gem | null)[], width: number, height: number, mask: readonly boolean[]): readonly (readonly number[])[];
+export declare function allMatchedCells(groups: readonly (readonly number[])[]): readonly number[];
+export declare function removeIds(board: readonly (Gem | null)[], bonds: readonly Bond[], indices: readonly number[]): {
+    readonly board: readonly (Gem | null)[];
+    readonly bonds: readonly Bond[];
+    readonly ids: readonly number[];
+};
+/** Settles bonded connected components one cell per deterministic bottom/ID priority step. */
+export declare function calmGravity(initial: readonly (Gem | null)[], bonds: readonly Bond[], width: number, height: number, mask: readonly boolean[]): readonly (Gem | null)[];
+/** Magnetic floor removes all bonds and settles each column segment independently. */
+export declare function magneticGravity(initial: readonly (Gem | null)[], width: number, height: number, mask: readonly boolean[]): readonly (Gem | null)[];
+export declare function settle(initial: readonly (Gem | null)[], bonds: readonly Bond[], floor: Floor, width: number, height: number, mask: readonly boolean[]): {
+    readonly board: readonly (Gem | null)[];
+    readonly bonds: readonly Bond[];
+};
+/** Collects the occupied one-cell support layer under both block columns at first contact. */
+export declare function impactSupportIds(block: Block, board: readonly (Gem | null)[], width: number, height: number, mask: readonly boolean[]): readonly number[];
+export declare function blockBonds(block: Block): readonly Bond[];

package/dist/magnetic-blocks/physics.js

@@ -0,0 +1,155 @@
+export const HIDDEN_ROWS = 0;
+export const MARK_TICKS = 7, REMOVE_TICKS = 6, GRAVITY_TICKS = 9;
+export const cell = (x, y, width) => y * width + x;
+const BASE = [[0, 0], [1, 0], [1, 1], [0, 1]];
+/** Returns stable-gem addresses after rotating the square block around its centre. */
+export function blockCells(block, width) {
+    return block.gems.map((gem, corner) => {
+        let [x, y] = BASE[corner];
+        for (let turn = 0; turn < block.orientation; turn++)
+            [x, y] = [1 - y, x];
+        return { index: cell(block.x + x, block.y + y, width), gem };
+    });
+}
+export function canPlace(block, board, width, height, mask) {
+    if (block.x < 0 || block.x + 1 >= width || block.y < 0 || block.y + 1 >= height)
+        return false;
+    return blockCells(block, width).every(({ index }) => { const x = index % width, y = Math.floor(index / width); return x >= 0 && x < width && y >= 0 && y < height && mask[index] && !board[index]; });
+}
+export function landingY(block, board, width, height, mask) {
+    let y = block.y;
+    while (canPlace({ ...block, y: y + 1 }, board, width, height, mask))
+        y++;
+    return y;
+}
+/** Computes deterministic orthogonal colour components of at least four gems. */
+export function matchGroups(board, width, height, mask) {
+    const seen = new Set(), matches = [];
+    for (let start = 0; start < board.length; start++) {
+        const gem = board[start];
+        if (!gem || seen.has(start))
+            continue;
+        const group = [start], pending = [start];
+        seen.add(start);
+        while (pending.length) {
+            const at = pending.pop(), x = at % width, y = Math.floor(at / width);
+            for (const next of [x ? at - 1 : -1, x + 1 < width ? at + 1 : -1, y ? at - width : -1, y + 1 < height ? at + width : -1])
+                if (next >= 0 && mask[next] && !seen.has(next) && board[next]?.colour === gem.colour) {
+                    seen.add(next);
+                    group.push(next);
+                    pending.push(next);
+                }
+        }
+        if (group.length >= 4)
+            matches.push(group.sort((a, b) => a - b));
+    }
+    return matches;
+}
+export function allMatchedCells(groups) { return [...new Set(groups.flat())].sort((a, b) => a - b); }
+export function removeIds(board, bonds, indices) {
+    const removed = new Set(indices), ids = indices.flatMap(index => board[index] ? [board[index].id] : []), remaining = board.map((gem, index) => removed.has(index) ? null : gem), alive = new Set(remaining.flatMap(gem => gem ? [gem.id] : []));
+    return { board: Object.freeze(remaining), bonds: Object.freeze(bonds.filter(edge => alive.has(edge.a) && alive.has(edge.b))), ids: Object.freeze(ids) };
+}
+function connectedComponents(board, bonds) {
+    const indices = new Map();
+    board.forEach((gem, index) => { if (gem)
+        indices.set(gem.id, index); });
+    const edges = new Map();
+    for (const id of indices.keys())
+        edges.set(id, []);
+    for (const edge of bonds)
+        if (edges.has(edge.a) && edges.has(edge.b)) {
+            edges.get(edge.a).push(edge.b);
+            edges.get(edge.b).push(edge.a);
+        }
+    const seen = new Set(), groups = [];
+    for (const id of indices.keys()) {
+        if (seen.has(id))
+            continue;
+        const pending = [id], cells = [];
+        seen.add(id);
+        while (pending.length) {
+            const next = pending.pop();
+            cells.push(indices.get(next));
+            for (const neighbour of edges.get(next))
+                if (!seen.has(neighbour)) {
+                    seen.add(neighbour);
+                    pending.push(neighbour);
+                }
+        }
+        groups.push(cells);
+    }
+    return groups;
+}
+/** Settles bonded connected components one cell per deterministic bottom/ID priority step. */
+export function calmGravity(initial, bonds, width, height, mask) {
+    let board = [...initial], moved = true, guard = width * height * height;
+    while (moved && guard-- > 0) {
+        moved = false;
+        const groups = connectedComponents(board, bonds).map(cells => ({ cells, bottom: Math.max(...cells.map(index => Math.floor(index / width))), id: Math.min(...cells.map(index => board[index].id)) })).sort((a, b) => b.bottom - a.bottom || a.id - b.id);
+        for (const group of groups) {
+            const own = new Set(group.cells), destinations = group.cells.map(index => index + width);
+            const canMove = group.cells.every((index, i) => { const y = Math.floor(index / width), dest = destinations[i]; return y + 1 < height && mask[dest] && (!board[dest] || own.has(dest)); });
+            if (!canMove)
+                continue;
+            const next = [...board];
+            for (const index of group.cells)
+                next[index] = null;
+            for (const index of group.cells)
+                next[index + width] = board[index];
+            board = next;
+            moved = true;
+            break;
+        }
+    }
+    if (guard <= 0)
+        throw new RangeError('Calm gravity did not converge within its board-derived step bound');
+    return Object.freeze(board);
+}
+/** Magnetic floor removes all bonds and settles each column segment independently. */
+export function magneticGravity(initial, width, height, mask) {
+    const board = [...initial];
+    for (let x = 0; x < width; x++) {
+        let y = 0;
+        while (y < height) {
+            while (y < height && !mask[cell(x, y, width)])
+                y++;
+            const start = y;
+            while (y < height && mask[cell(x, y, width)])
+                y++;
+            const end = y, survivors = [];
+            for (let row = start; row < end; row++) {
+                const gem = board[cell(x, row, width)];
+                if (gem)
+                    survivors.push(gem);
+            }
+            for (let row = start; row < end; row++)
+                board[cell(x, row, width)] = null;
+            for (let i = 0; i < survivors.length; i++)
+                board[cell(x, end - survivors.length + i, width)] = survivors[i];
+        }
+    }
+    return Object.freeze(board);
+}
+export function settle(initial, bonds, floor, width, height, mask) {
+    return floor === 'magnetic' ? { board: magneticGravity(initial, width, height, mask), bonds: Object.freeze([]) } : { board: calmGravity(initial, bonds, width, height, mask), bonds };
+}
+/** Collects the occupied one-cell support layer under both block columns at first contact. */
+export function impactSupportIds(block, board, width, height, mask) {
+    const byColumn = new Map();
+    for (const { index } of blockCells(block, width)) {
+        const x = index % width, y = Math.floor(index / width);
+        byColumn.set(x, Math.max(byColumn.get(x) ?? -1, y));
+    }
+    const ids = new Set();
+    for (const [x, y] of byColumn) {
+        const supportY = y + 1;
+        if (supportY >= 0 && supportY < height) {
+            const index = cell(x, supportY, width);
+            if (mask[index] && board[index])
+                ids.add(board[index].id);
+        }
+    }
+    return Object.freeze([...ids].sort((a, b) => a - b));
+}
+export function blockBonds(block) { return Object.freeze([[0, 1], [1, 2], [2, 3], [3, 0]].map(([a, b]) => { const ids = [block.gems[a].id, block.gems[b].id].sort((x, y) => x - y); return Object.freeze({ a: ids[0], b: ids[1] }); }).sort((a, b) => a.a - b.a || a.b - b.b)); }

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

@@ -0,0 +1,6 @@
+/** Hashes a numeric or string seed into the engine's non-zero xorshift state. */
+export declare function seedState(seed: string | number): number;
+/** Advances the fixed 32-bit xorshift source. */
+export declare function nextUint32(state: number): number;
+/** Draws an unbiased integer in [0, bound). */
+export declare function nextInt(state: number, bound: number): readonly [number, number];

package/dist/magnetic-blocks/random.js

@@ -0,0 +1,19 @@
+/** Hashes a numeric or string seed into the engine's non-zero xorshift state. */
+export function seedState(seed) {
+    let hash = 0x811c9dc5;
+    for (const byte of new TextEncoder().encode(String(seed)))
+        hash = Math.imul(hash ^ byte, 0x01000193) >>> 0;
+    return hash || 0x6d2b79f5;
+}
+/** Advances the fixed 32-bit xorshift source. */
+export function nextUint32(state) { let value = state >>> 0; value ^= value << 13; value ^= value >>> 17; value ^= value << 5; return value >>> 0; }
+/** Draws an unbiased integer in [0, bound). */
+export function nextInt(state, bound) {
+    const limit = Math.floor(0x1_0000_0000 / bound) * bound;
+    let current = state >>> 0;
+    for (;;) {
+        current = nextUint32(current);
+        if (current < limit)
+            return [current % bound, current];
+    }
+}

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

@@ -0,0 +1,158 @@
+/** A standard gem colour used by a magnetic block. */
+export type Colour = 'red' | 'blue' | 'green' | 'gold' | 'purple' | 'teal';
+export type Floor = 'calm' | 'magnetic';
+export type FloorSchedule = {
+    readonly kind: 'frequent';
+} | {
+    readonly kind: 'occasional';
+} | {
+    readonly kind: 'infrequent';
+} | {
+    readonly kind: 'mid-level';
+    readonly placement: number;
+} | {
+    readonly kind: 'fixed';
+    readonly floor: Floor;
+} | {
+    readonly kind: 'authored';
+    readonly magneticPlacements: readonly number[];
+    readonly defaultFloor?: Floor;
+};
+export type Mode = 'relaxed' | 'arcade';
+export type Phase = 'falling' | 'clear-mark' | 'clear-remove' | 'gravity' | 'paused' | 'won' | 'lost' | 'finished';
+export interface Gem {
+    readonly id: number;
+    readonly colour: Colour;
+}
+export interface Bond {
+    readonly a: number;
+    readonly b: number;
+}
+export interface Block {
+    readonly x: number;
+    readonly y: number;
+    readonly orientation: 0 | 1 | 2 | 3;
+    readonly gems: readonly [Gem, Gem, Gem, Gem];
+    readonly descent: number;
+    readonly lockTicks: number;
+    readonly lockResets: number;
+    readonly lockStarted: boolean;
+}
+export type Goal = {
+    readonly kind: 'clear-all';
+} | {
+    readonly kind: 'clear-targets';
+    readonly targetIds: readonly number[];
+};
+export interface CreateOptions {
+    readonly mode?: Mode;
+    readonly width?: number;
+    readonly height?: number;
+    readonly colourCount?: 4 | 5 | 6;
+    readonly seed?: string | number;
+    readonly mask?: readonly boolean[];
+    readonly initialBoard?: readonly (Gem | null)[];
+    readonly bonds?: readonly Bond[];
+    readonly queue?: readonly (readonly [Colour, Colour, Colour, Colour])[];
+    readonly pieceLimit?: number;
+    readonly schedule?: FloorSchedule;
+    readonly floorSwitch?: boolean;
+    readonly magneticImpact?: boolean;
+    readonly goal?: Goal;
+}
+export interface Settings {
+    readonly mode: Mode;
+    readonly width: number;
+    readonly height: number;
+    readonly colourCount: 4 | 5 | 6;
+    readonly seed: string | number;
+    readonly mask: readonly boolean[];
+    readonly schedule: FloorSchedule;
+    readonly floorSwitch: boolean;
+    readonly magneticImpact: boolean;
+    readonly pieceLimit: number;
+    readonly initialBoard: readonly (Gem | null)[];
+    readonly bonds: readonly Bond[];
+    readonly initialQueue?: readonly (readonly [Colour, Colour, Colour, Colour])[];
+    readonly goal?: Goal;
+}
+export interface GameState {
+    readonly game: 'magnetic-blocks';
+    readonly rules: 'magnetic-blocks-1';
+    readonly settings: Settings;
+    readonly board: readonly (Gem | null)[];
+    readonly bonds: readonly Bond[];
+    readonly active: Block | null;
+    readonly queue: readonly (readonly [Colour, Colour, Colour, Colour])[];
+    readonly randomState: number;
+    readonly nextId: number;
+    readonly phase: Phase;
+    readonly pausedPhase?: Exclude<Phase, 'paused'>;
+    readonly score: number;
+    readonly moves: number;
+    readonly placements: number;
+    readonly chain: number;
+    readonly maxChain: number;
+    readonly floor: Floor;
+    readonly nextFloor: Floor;
+    readonly floorSwitchCharges: 0 | 1;
+    readonly pendingFloorOverride: Floor | null;
+    readonly pendingClear: readonly number[];
+    readonly gravityBoard: readonly (Gem | null)[] | null;
+    readonly resolutionTick: number;
+    readonly impactRemovedIds: readonly number[];
+    readonly elapsedTicks: number;
+    readonly recording: readonly RecordedAction[];
+    readonly reason?: string;
+}
+export type Action = {
+    readonly kind: 'left';
+} | {
+    readonly kind: 'right';
+} | {
+    readonly kind: 'soft-drop';
+} | {
+    readonly kind: 'rotate-clockwise';
+} | {
+    readonly kind: 'rotate-anticlockwise';
+} | {
+    readonly kind: 'hard-drop';
+} | {
+    readonly kind: 'land';
+} | {
+    readonly kind: 'pause';
+} | {
+    readonly kind: 'resume';
+} | {
+    readonly kind: 'set-floor-override';
+    readonly floor: Floor;
+} | {
+    readonly kind: 'cancel-floor-override';
+};
+export interface RecordedAction {
+    readonly tick: number;
+    readonly ordinal: number;
+    readonly action: Action;
+}
+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 GameStatus {
+    readonly phase: Phase;
+    readonly score: number;
+    readonly moves: number;
+    readonly placements: number;
+    readonly floor: Floor;
+    readonly nextFloor: Floor;
+    readonly floorSwitchCharges: number;
+    readonly pendingFloorOverride: Floor | null;
+    readonly maxChain: number;
+    readonly reason?: string;
+}

package/dist/magnetic-blocks/types.js

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

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

@@ -0,0 +1,23 @@
+import type { Bond, Colour, CreateOptions, FloorSchedule, Gem, Goal, Mode } from './types.js';
+export declare class MagneticBlocksOptionsError extends RangeError {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare const COLOURS: readonly Colour[];
+export interface ValidatedOptions {
+    readonly mode: Mode;
+    readonly width: number;
+    readonly height: number;
+    readonly colourCount: 4 | 5 | 6;
+    readonly seed: string | number;
+    readonly mask: readonly boolean[];
+    readonly initialBoard: readonly (Gem | null)[];
+    readonly bonds: readonly Bond[];
+    readonly queue?: readonly (readonly [Colour, Colour, Colour, Colour])[];
+    readonly pieceLimit: number;
+    readonly schedule: FloorSchedule;
+    readonly floorSwitch: boolean;
+    readonly magneticImpact: boolean;
+    readonly goal?: Goal;
+}
+export declare function validateOptions(options?: CreateOptions): ValidatedOptions;

package/dist/magnetic-blocks/validation.js

@@ -0,0 +1,121 @@
+import { calmGravity } from './physics.js';
+export class MagneticBlocksOptionsError extends RangeError {
+    code;
+    constructor(code, message) { super(message); this.name = 'MagneticBlocksOptionsError'; this.code = code; }
+}
+export const COLOURS = ['red', 'blue', 'green', 'gold', 'purple', 'teal'];
+const floor = (value) => value === 'calm' || value === 'magnetic';
+function validateSchedule(value) {
+    const schedule = value ?? { kind: 'occasional' };
+    if (!schedule || typeof schedule !== 'object' || Array.isArray(schedule))
+        throw new MagneticBlocksOptionsError('invalid-schedule', 'Floor schedule must be an object');
+    if (schedule.kind === 'frequent' || schedule.kind === 'occasional' || schedule.kind === 'infrequent') {
+        if (Object.keys(schedule).length !== 1)
+            throw new MagneticBlocksOptionsError('invalid-schedule', 'Floor schedule contains unsupported fields');
+    }
+    else if (schedule.kind === 'mid-level') {
+        if (Object.keys(schedule).some(key => key !== 'kind' && key !== 'placement') || !Number.isInteger(schedule.placement) || schedule.placement < 1 || schedule.placement > 1000)
+            throw new MagneticBlocksOptionsError('invalid-schedule', 'Mid-level pulse requires a placement number from 1 to 1000');
+    }
+    else if (schedule.kind === 'fixed') {
+        if (Object.keys(schedule).some(key => key !== 'kind' && key !== 'floor') || !floor(schedule.floor))
+            throw new MagneticBlocksOptionsError('invalid-schedule', 'Fixed floor must be calm or magnetic');
+    }
+    else if (schedule.kind === 'authored') {
+        if (Object.keys(schedule).some(key => !['kind', 'magneticPlacements', 'defaultFloor'].includes(key)) || !Array.isArray(schedule.magneticPlacements) || schedule.magneticPlacements.length > 1000 || schedule.magneticPlacements.some((n, i) => !Number.isInteger(n) || n < 1 || n > 1000 || i > 0 && n <= schedule.magneticPlacements[i - 1]) || schedule.defaultFloor !== undefined && !floor(schedule.defaultFloor))
+            throw new MagneticBlocksOptionsError('invalid-schedule', 'Authored magnetic placements must be sorted unique positive placement numbers');
+    }
+    else
+        throw new MagneticBlocksOptionsError('invalid-schedule', 'Unknown floor schedule');
+    return Object.freeze({ ...schedule, ...('magneticPlacements' in schedule ? { magneticPlacements: Object.freeze([...schedule.magneticPlacements]) } : {}) });
+}
+function validateGoal(value, ids) {
+    if (value === undefined)
+        return undefined;
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new MagneticBlocksOptionsError('invalid-goal', 'Goal must be an object');
+    if (value.kind === 'clear-all') {
+        if (Object.keys(value).length !== 1)
+            throw new MagneticBlocksOptionsError('invalid-goal', 'Clear-all goal has unsupported fields');
+        return Object.freeze({ kind: 'clear-all' });
+    }
+    if (value.kind === 'clear-targets' && Object.keys(value).every(key => key === 'kind' || key === 'targetIds') && Array.isArray(value.targetIds) && value.targetIds.length > 0 && value.targetIds.every(id => Number.isSafeInteger(id) && ids.has(id)) && new Set(value.targetIds).size === value.targetIds.length)
+        return Object.freeze({ kind: 'clear-targets', targetIds: Object.freeze([...value.targetIds].sort((a, b) => a - b)) });
+    throw new MagneticBlocksOptionsError('invalid-goal', 'Goal must clear all gems or name unique initial gem IDs');
+}
+export function validateOptions(options = {}) {
+    if (!options || typeof options !== 'object' || Array.isArray(options))
+        throw new MagneticBlocksOptionsError('invalid-options', 'Options must be an object');
+    const allowed = ['mode', 'width', 'height', 'colourCount', 'seed', 'mask', 'initialBoard', 'bonds', 'queue', 'pieceLimit', 'schedule', 'floorSwitch', 'magneticImpact', 'goal'];
+    if (Object.keys(options).some(key => !allowed.includes(key)))
+        throw new MagneticBlocksOptionsError('unknown-option', 'Create options contain an unsupported field');
+    const mode = options.mode ?? 'relaxed';
+    if (mode !== 'relaxed' && mode !== 'arcade')
+        throw new MagneticBlocksOptionsError('invalid-mode', 'Mode must be relaxed or arcade');
+    const width = options.width ?? 10, height = options.height ?? 20;
+    if (!Number.isInteger(width) || width < 4 || width > 16 || !Number.isInteger(height) || height < 4 || height > 32 || width * height > 512)
+        throw new MagneticBlocksOptionsError('invalid-board-size', 'Board width must be 4–16, height 4–32, with at most 512 cells');
+    const colourCount = options.colourCount ?? 4;
+    if (![4, 5, 6].includes(colourCount))
+        throw new MagneticBlocksOptionsError('invalid-colour-count', 'Colour count must be 4, 5, or 6');
+    const seed = options.seed ?? 'houseki-magnetic-blocks';
+    if (typeof seed !== 'string' && (!Number.isInteger(seed) || seed < 0 || seed > 0xffff_ffff))
+        throw new MagneticBlocksOptionsError('invalid-seed', 'Numeric seed must be an unsigned 32-bit integer');
+    const mask = options.mask === undefined ? Array(width * height).fill(true) : options.mask;
+    if (!Array.isArray(mask) || mask.length !== width * height || mask.some(value => typeof value !== 'boolean') || mask.filter(Boolean).length < 16 || mask.filter(Boolean).length > 512)
+        throw new MagneticBlocksOptionsError('invalid-mask', 'Mask must contain 16–512 active cells');
+    const active = mask.flatMap((on, i) => on ? [i] : []), connected = new Set([active[0]]), pending = [active[0]];
+    while (pending.length) {
+        const at = pending.pop(), x = at % width, y = Math.floor(at / width);
+        for (const next of [x ? at - 1 : -1, x + 1 < width ? at + 1 : -1, y ? at - width : -1, y + 1 < height ? at + width : -1])
+            if (next >= 0 && mask[next] && !connected.has(next)) {
+                connected.add(next);
+                pending.push(next);
+            }
+    }
+    if (connected.size !== active.length)
+        throw new MagneticBlocksOptionsError('disconnected-mask', 'Mask active cells must be connected');
+    if (active.some(at => { const x = at % width, y = Math.floor(at / width); return ![x ? at - 1 : -1, x + 1 < width ? at + 1 : -1, y ? at - width : -1, y + 1 < height ? at + width : -1].some(next => next >= 0 && mask[next]); }))
+        throw new MagneticBlocksOptionsError('isolated-mask-cell', 'Every active mask cell must have an orthogonal neighbour');
+    const initialBoard = options.initialBoard ?? Array(width * height).fill(null);
+    if (!Array.isArray(initialBoard) || initialBoard.length !== width * height)
+        throw new MagneticBlocksOptionsError('invalid-board', 'Initial board must contain one entry per cell');
+    const ids = new Set();
+    const board = initialBoard.map((gem, at) => {
+        if (!mask[at]) {
+            if (gem !== null)
+                throw new MagneticBlocksOptionsError('gem-in-masked-cell', 'Masked cells must be empty');
+            return null;
+        }
+        if (gem === null)
+            return null;
+        if (!gem || typeof gem !== 'object' || Array.isArray(gem) || Object.keys(gem).some(key => key !== 'id' && key !== 'colour') || !Number.isSafeInteger(gem.id) || gem.id < 1 || ids.has(gem.id) || !COLOURS.slice(0, colourCount).includes(gem.colour))
+            throw new MagneticBlocksOptionsError('invalid-gem', 'Gems need unique positive IDs and a configured colour');
+        ids.add(gem.id);
+        return Object.freeze({ id: gem.id, colour: gem.colour });
+    });
+    const bonds = options.bonds ?? [];
+    if (!Array.isArray(bonds) || bonds.some(edge => !edge || typeof edge !== 'object' || Object.keys(edge).some(key => key !== 'a' && key !== 'b') || !Number.isSafeInteger(edge.a) || !Number.isSafeInteger(edge.b) || edge.a === edge.b || !ids.has(edge.a) || !ids.has(edge.b)))
+        throw new MagneticBlocksOptionsError('invalid-bonds', 'Bond edges must connect two unique occupied gem IDs');
+    const bondKeys = bonds.map(edge => `${Math.min(edge.a, edge.b)}:${Math.max(edge.a, edge.b)}`);
+    if (new Set(bondKeys).size !== bondKeys.length)
+        throw new MagneticBlocksOptionsError('duplicate-bond', 'Bond edges must be unique');
+    const idCells = new Map();
+    board.forEach((gem, index) => { if (gem)
+        idCells.set(gem.id, index); });
+    if (bonds.some(edge => { const a = idCells.get(edge.a), b = idCells.get(edge.b); return Math.abs(a % width - b % width) + Math.abs(Math.floor(a / width) - Math.floor(b / width)) !== 1; }))
+        throw new MagneticBlocksOptionsError('nonadjacent-bond', 'Bond edges must connect orthogonally adjacent gems');
+    const stableBonds = bonds.map(edge => ({ a: Math.min(edge.a, edge.b), b: Math.max(edge.a, edge.b) }));
+    const settledInitial = calmGravity(board, stableBonds, width, height, mask);
+    if (settledInitial.some((gem, index) => gem?.id !== board[index]?.id))
+        throw new MagneticBlocksOptionsError('unstable-initial-board', 'Initial gems must be settled under calm gravity and their declared bonds');
+    const queue = options.queue;
+    if (queue !== undefined && (!Array.isArray(queue) || queue.length < 1 || queue.length > 1000 || queue.some(piece => !Array.isArray(piece) || piece.length !== 4 || piece.some(colour => !COLOURS.slice(0, colourCount).includes(colour)))))
+        throw new MagneticBlocksOptionsError('invalid-queue', 'Queue must contain 1–1000 four-colour blocks');
+    const pieceLimit = options.pieceLimit ?? queue?.length ?? 200;
+    if (!Number.isInteger(pieceLimit) || pieceLimit < 1 || pieceLimit > 1000 || queue && queue.length < pieceLimit)
+        throw new MagneticBlocksOptionsError('invalid-piece-limit', 'Piece limit must fit the fixed queue and be 1–1000');
+    if (options.floorSwitch !== undefined && typeof options.floorSwitch !== 'boolean' || options.magneticImpact !== undefined && typeof options.magneticImpact !== 'boolean')
+        throw new MagneticBlocksOptionsError('invalid-option-flag', 'Floor Switch and Magnetic Impact settings must be booleans');
+    return { mode, width, height, colourCount: colourCount, seed, mask: Object.freeze([...mask]), initialBoard: Object.freeze(board), bonds: Object.freeze(stableBonds.map(edge => Object.freeze(edge)).sort((a, b) => a.a - b.a || a.b - b.b)), ...(queue ? { queue: Object.freeze(queue.map(piece => Object.freeze([...piece]))) } : {}), pieceLimit, schedule: validateSchedule(options.schedule), floorSwitch: options.floorSwitch ?? false, magneticImpact: options.magneticImpact ?? false, ...(options.goal === undefined ? {} : { goal: validateGoal(options.goal, ids) }) };
+}

package/dist/magnetic-blocks.d.ts

@@ -0,0 +1,5 @@
+export { MagneticBlocksOptionsError } from './magnetic-blocks/validation.js';
+export { createGame, applyAction, advanceTicks, legalActions, statusOf } from './magnetic-blocks/engine.js';
+export { encodeGame, decodeGame, restartGame } from './magnetic-blocks/persistence.js';
+export { blockCells, canPlace, landingY, matchGroups, removeIds, calmGravity, magneticGravity, settle, impactSupportIds, blockBonds, MARK_TICKS, REMOVE_TICKS, GRAVITY_TICKS } from './magnetic-blocks/physics.js';
+export type { Action, Block, Bond, Colour, CreateOptions, Floor, FloorSchedule, GameEvent, GameState, GameStatus, Gem, Goal, Mode, Phase, RecordedAction, Settings, Transition } from './magnetic-blocks/types.js';

package/dist/magnetic-blocks.js

@@ -0,0 +1,4 @@
+export { MagneticBlocksOptionsError } from './magnetic-blocks/validation.js';
+export { createGame, applyAction, advanceTicks, legalActions, statusOf } from './magnetic-blocks/engine.js';
+export { encodeGame, decodeGame, restartGame } from './magnetic-blocks/persistence.js';
+export { blockCells, canPlace, landingY, matchGroups, removeIds, calmGravity, magneticGravity, settle, impactSupportIds, blockBonds, MARK_TICKS, REMOVE_TICKS, GRAVITY_TICKS } from './magnetic-blocks/physics.js';

package/dist/nature/attraction.d.ts

@@ -0,0 +1,5 @@
+import type { MagneticPreview, NatureState, NatureTransition } from './types.js';
+/** Preview one bounded deterministic attraction pulse without mutating the state. */
+export declare function previewMagneticPulse(state: NatureState): MagneticPreview;
+/** Apply one attraction pulse. Disabled nature rules preserve the exact state reference and consume no random state. */
+export declare function applyMagneticPulse(state: NatureState): NatureTransition;