@johnmorrisdotca/houseki 0.0.0-stage → 0.1.0

package/dist/nature/attraction.js

@@ -0,0 +1,136 @@
+import { validateState } from './validation.js';
+import { freezeNatureState } from './state.js';
+const indexOf = (x, y, width) => y * width + x;
+const coordinates = (index, width) => ({ x: index % width, y: Math.floor(index / width) });
+function deepFreeze(value) {
+    if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const child of Object.values(value))
+            deepFreeze(child);
+    }
+    return value;
+}
+function visiblePairCandidates(state) {
+    const magnets = state.cells.flatMap((entity, index) => entity?.kind === 'stone' && entity.magnetic ? [{ entity, index }] : []);
+    const pairs = [];
+    for (let i = 0; i < magnets.length; i++)
+        for (let j = i + 1; j < magnets.length; j++) {
+            const first = magnets[i], second = magnets[j];
+            if (first.entity.anchored && second.entity.anchored)
+                continue;
+            const p = coordinates(first.index, state.width), q = coordinates(second.index, state.width);
+            const axis = p.y === q.y ? 'horizontal' : p.x === q.x ? 'vertical' : null;
+            if (!axis)
+                continue;
+            const distance = Math.abs(p.x - q.x) + Math.abs(p.y - q.y);
+            if (distance <= 1)
+                continue;
+            const stepX = Math.sign(q.x - p.x), stepY = Math.sign(q.y - p.y);
+            let clear = true;
+            for (let offset = 1; offset < distance; offset++) {
+                const x = p.x + stepX * offset, y = p.y + stepY * offset, index = indexOf(x, y, state.width);
+                if (!state.activeCells[index] || state.cells[index] !== null) {
+                    clear = false;
+                    break;
+                }
+            }
+            if (clear)
+                pairs.push({ a: first.entity, b: second.entity, aIndex: first.index, bIndex: second.index, axis, gap: distance - 1 });
+        }
+    return pairs.sort((left, right) => left.gap - right.gap || Math.min(left.a.id, left.b.id) - Math.min(right.a.id, right.b.id) || Math.max(left.a.id, left.b.id) - Math.max(right.a.id, right.b.id));
+}
+function selectDisjoint(state) {
+    const used = new Set();
+    const result = [];
+    for (const pair of visiblePairCandidates(state))
+        if (!used.has(pair.a.id) && !used.has(pair.b.id)) {
+            result.push(pair);
+            used.add(pair.a.id);
+            used.add(pair.b.id);
+        }
+    return result;
+}
+function findIndex(board, id) { return board.findIndex(entity => entity?.id === id); }
+function relocate(board, from, to) {
+    const entity = board[from];
+    if (!entity || board[to] !== null)
+        return false;
+    board[to] = entity;
+    board[from] = null;
+    return true;
+}
+function stepMove(board, state, fromIndex, toX, toY) {
+    const entity = board[fromIndex];
+    const toIndex = indexOf(toX, toY, state.width);
+    if (!entity || toX < 0 || toX >= state.width || toY < 0 || toY >= state.height || !state.activeCells[toIndex] || board[toIndex] !== null)
+        return null;
+    const from = coordinates(fromIndex, state.width);
+    relocate(board, fromIndex, toIndex);
+    return { id: entity.id, from, to: { x: toX, y: toY } };
+}
+function movePair(board, state, pair) {
+    const localMoves = [];
+    const ids = [pair.a.id, pair.b.id].sort((a, b) => a - b);
+    let safety = state.width + state.height;
+    while (safety-- > 0) {
+        const aIndexCurrent = findIndex(board, pair.a.id), bIndexCurrent = findIndex(board, pair.b.id);
+        if (aIndexCurrent < 0 || bIndexCurrent < 0)
+            break;
+        const a = coordinates(aIndexCurrent, state.width), b = coordinates(bIndexCurrent, state.width);
+        const distance = Math.abs(a.x - b.x) + Math.abs(a.y - b.y);
+        if (distance <= 1)
+            break;
+        const vector = { x: Math.sign(b.x - a.x), y: Math.sign(b.y - a.y) };
+        const aEntity = board[aIndexCurrent], bEntity = board[bIndexCurrent];
+        if (aEntity.anchored || bEntity.anchored) {
+            const moverIsA = bEntity.anchored;
+            const from = moverIsA ? a : b;
+            const toward = moverIsA ? vector : { x: -vector.x, y: -vector.y };
+            const move = stepMove(board, state, moverIsA ? aIndexCurrent : bIndexCurrent, from.x + toward.x, from.y + toward.y);
+            if (!move)
+                break;
+            localMoves.push(move);
+            continue;
+        }
+        if (distance === 2) {
+            const moverId = Math.min(aEntity.id, bEntity.id);
+            const from = moverId === aEntity.id ? a : b;
+            const toward = moverId === aEntity.id ? vector : { x: -vector.x, y: -vector.y };
+            const move = stepMove(board, state, findIndex(board, moverId), from.x + toward.x, from.y + toward.y);
+            if (!move)
+                break;
+            localMoves.push(move);
+            break;
+        }
+        const moveA = { from: aIndexCurrent, to: indexOf(a.x + vector.x, a.y + vector.y, state.width), entity: aEntity, x: a.x + vector.x, y: a.y + vector.y };
+        const moveB = { from: bIndexCurrent, to: indexOf(b.x - vector.x, b.y - vector.y, state.width), entity: bEntity, x: b.x - vector.x, y: b.y - vector.y };
+        if (!state.activeCells[moveA.to] || !state.activeCells[moveB.to] || board[moveA.to] !== null || board[moveB.to] !== null || moveA.to === moveB.to)
+            break;
+        board[moveA.to] = moveA.entity;
+        board[moveA.from] = null;
+        board[moveB.to] = moveB.entity;
+        board[moveB.from] = null;
+        localMoves.push({ id: moveA.entity.id, from: a, to: { x: moveA.x, y: moveA.y } }, { id: moveB.entity.id, from: b, to: { x: moveB.x, y: moveB.y } });
+    }
+    const aIndex = findIndex(board, pair.a.id), bIndex = findIndex(board, pair.b.id);
+    const a = coordinates(aIndex, state.width), b = coordinates(bIndex, state.width);
+    return deepFreeze({ ids, axis: pair.axis, emptyGap: pair.gap, midpoint: { x: (a.x + b.x) / 2, y: (a.y + b.y) / 2 }, ...(pair.a.anchored || pair.b.anchored ? { anchoredId: pair.a.anchored ? pair.a.id : pair.b.id } : {}), moves: localMoves });
+}
+/** Preview one bounded deterministic attraction pulse without mutating the state. */
+export function previewMagneticPulse(state) {
+    validateState(state);
+    if (!state.rules.magneticEnabled)
+        return deepFreeze({ pairs: [], moves: [], cells: state.cells });
+    const board = [...state.cells];
+    const pairs = selectDisjoint(state).map(pair => movePair(board, state, pair));
+    const moves = pairs.flatMap(pair => pair.moves);
+    return deepFreeze({ pairs, moves, cells: board });
+}
+/** Apply one attraction pulse. Disabled nature rules preserve the exact state reference and consume no random state. */
+export function applyMagneticPulse(state) {
+    const preview = previewMagneticPulse(state);
+    if (!state.rules.magneticEnabled || preview.moves.length === 0)
+        return { state, accepted: true, events: [], preview };
+    const next = freezeNatureState({ ...state, cells: preview.cells });
+    return { state: next, accepted: true, events: [deepFreeze({ type: 'magnetic-pulse', pairs: preview.pairs, moves: preview.moves })], preview };
+}

package/dist/nature/environment.d.ts

@@ -0,0 +1,91 @@
+import type { NatureEntity, NatureMove, NatureState } from './types.js';
+export type EarthquakeKind = 'fault' | 'jumble' | 'combined';
+export type EnvironmentSchedule = {
+    readonly kind: 'frequent';
+} | {
+    readonly kind: 'rare';
+} | {
+    readonly kind: 'midlevel';
+    readonly turn: number;
+} | {
+    readonly kind: 'authored';
+    readonly turns: readonly number[];
+};
+export interface EarthquakeOptions {
+    readonly kind: EarthquakeKind;
+    readonly enabled?: boolean;
+}
+export interface LightningOptions {
+    readonly enabled?: boolean;
+    readonly columns?: readonly number[];
+    readonly columnCount?: 1 | 2 | 3;
+}
+export interface FaultPreview {
+    readonly path: readonly number[];
+    readonly fracturedCells: readonly number[];
+    readonly removedIds: readonly number[];
+    readonly cells: readonly (NatureEntity | null)[];
+    readonly activeCells: readonly boolean[];
+    readonly randomStateAfter: number;
+}
+export interface JumblePreview {
+    readonly patchCells: readonly number[];
+    readonly moves: readonly NatureMove[];
+    readonly changed: boolean;
+    readonly reason?: 'no-eligible-patch';
+    readonly cells: readonly (NatureEntity | null)[];
+    readonly randomStateAfter: number;
+}
+export interface EarthquakePreview {
+    readonly kind: EarthquakeKind;
+    readonly fault?: FaultPreview;
+    readonly jumble?: JumblePreview;
+    readonly cells: readonly (NatureEntity | null)[];
+    readonly activeCells: readonly boolean[];
+    readonly randomStateAfter: number;
+}
+export interface LightningPreview {
+    readonly columns: readonly number[];
+    readonly removedCells: readonly number[];
+    readonly removedIds: readonly number[];
+    readonly cells: readonly (NatureEntity | null)[];
+    readonly randomStateAfter: number;
+}
+export type EnvironmentPreview = EarthquakePreview | LightningPreview;
+export type EnvironmentEvent = {
+    readonly type: 'fault-opened';
+    readonly path: readonly number[];
+    readonly fracturedCells: readonly number[];
+    readonly removedIds: readonly number[];
+} | {
+    readonly type: 'jumble-completed';
+    readonly changed: boolean;
+    readonly reason?: 'no-eligible-patch';
+    readonly patchCells: readonly number[];
+    readonly moves: readonly NatureMove[];
+} | {
+    readonly type: 'lightning-struck';
+    readonly columns: readonly number[];
+    readonly removedCells: readonly number[];
+    readonly removedIds: readonly number[];
+};
+export interface EnvironmentTransition {
+    readonly state: NatureState;
+    readonly accepted: true;
+    readonly events: readonly EnvironmentEvent[];
+    readonly preview: EnvironmentPreview;
+}
+/** Pure one-based schedule lookup: frequent is every second turn; rare is every eighth turn. */
+export declare function isEnvironmentTurnScheduled(turn: number, schedule: EnvironmentSchedule): boolean;
+/** Preview a bounded top-to-bottom fracture. The path keeps at least one column active on each side. */
+export declare function previewFault(state: NatureState): FaultPreview;
+/** Preview one seeded, nontrivial stone permutation inside a fully active connected rectangle no larger than 3×3. */
+export declare function previewJumble(state: NatureState): JumblePreview;
+/** Preview an earthquake, with Combined always fracturing before its one jumble attempt. */
+export declare function previewEarthquake(state: NatureState, options: EarthquakeOptions): EarthquakePreview;
+/** Commit one bounded environmental resolution; matching, gravity and score remain the host game's job. */
+export declare function applyEarthquake(state: NatureState, options: EarthquakeOptions): EnvironmentTransition;
+/** Preview seeded or explicitly selected columns; a mask gap or obstacle blocks the strike below it. */
+export declare function previewLightning(state: NatureState, options?: LightningOptions): LightningPreview;
+/** Commit one lightning strike. It removes exposed stones only and consumes no scores or tools. */
+export declare function applyLightning(state: NatureState, options?: LightningOptions): EnvironmentTransition;

package/dist/nature/environment.js

@@ -0,0 +1,272 @@
+import { nextNatureUint32 } from './random.js';
+import { freezeNatureState } from './state.js';
+import { NatureOptionsError, validateState } from './validation.js';
+const at = (x, y, width) => y * width + x;
+function deepFreeze(value) {
+    if (value && typeof value === 'object' && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const child of Object.values(value))
+            deepFreeze(child);
+    }
+    return value;
+}
+function drawBelow(state, bound) {
+    const [next, value] = nextNatureUint32(state);
+    return [next, value % bound];
+}
+/** Pure one-based schedule lookup: frequent is every second turn; rare is every eighth turn. */
+export function isEnvironmentTurnScheduled(turn, schedule) {
+    if (!Number.isSafeInteger(turn) || turn < 1 || turn > 10_000_000 || !schedule || typeof schedule !== 'object' || Array.isArray(schedule))
+        throw new NatureOptionsError('invalid-nature-options', 'Schedule turn and policy must be valid');
+    if (schedule.kind === 'frequent' || schedule.kind === 'rare') {
+        noKeysExcept(schedule, ['kind'], 'Environment schedule');
+        return turn % (schedule.kind === 'frequent' ? 2 : 8) === 0;
+    }
+    if (schedule.kind === 'midlevel') {
+        noKeysExcept(schedule, ['kind', 'turn'], 'Environment schedule');
+        if (!Number.isSafeInteger(schedule.turn) || schedule.turn < 1 || schedule.turn > 10_000_000)
+            throw new NatureOptionsError('invalid-nature-options', 'Midlevel schedule turn is out of range');
+        return turn === schedule.turn;
+    }
+    if (schedule.kind === 'authored') {
+        noKeysExcept(schedule, ['kind', 'turns'], 'Environment schedule');
+        if (!Array.isArray(schedule.turns) || schedule.turns.length > 100_000 || schedule.turns.some((item, index) => !Number.isSafeInteger(item) || item < 1 || item > 10_000_000 || (index > 0 && item <= schedule.turns[index - 1])))
+            throw new NatureOptionsError('invalid-nature-options', 'Authored turns must be bounded, positive and strictly increasing');
+        let low = 0, high = schedule.turns.length - 1;
+        while (low <= high) {
+            const middle = (low + high) >> 1, candidate = schedule.turns[middle];
+            if (candidate === turn)
+                return true;
+            if (candidate < turn)
+                low = middle + 1;
+            else
+                high = middle - 1;
+        }
+        return false;
+    }
+    throw new NatureOptionsError('invalid-nature-options', 'Unsupported environment schedule');
+}
+function noKeysExcept(value, allowed, label) {
+    if (Object.keys(value).some(key => !allowed.includes(key)))
+        throw new NatureOptionsError('invalid-nature-options', `${label} contains an unsupported field`);
+}
+function validateEarthquakeOptions(options) {
+    if (!options || typeof options !== 'object' || Array.isArray(options))
+        throw new NatureOptionsError('invalid-nature-options', 'Earthquake options must be an object');
+    noKeysExcept(options, ['kind', 'enabled'], 'Earthquake options');
+    if (!['fault', 'jumble', 'combined'].includes(options.kind) || options.enabled !== undefined && typeof options.enabled !== 'boolean')
+        throw new NatureOptionsError('invalid-nature-options', 'Earthquake options are malformed');
+}
+function validateLightningOptions(options, width) {
+    if (!options || typeof options !== 'object' || Array.isArray(options))
+        throw new NatureOptionsError('invalid-nature-options', 'Lightning options must be an object');
+    noKeysExcept(options, ['enabled', 'columns', 'columnCount'], 'Lightning options');
+    if (options.enabled !== undefined && typeof options.enabled !== 'boolean')
+        throw new NatureOptionsError('invalid-nature-options', 'Lightning enabled must be boolean');
+    if (options.columns !== undefined && options.columnCount !== undefined)
+        throw new NatureOptionsError('invalid-nature-options', 'Choose explicit lightning columns or a seeded column count');
+    if (options.columnCount !== undefined && ![1, 2, 3].includes(options.columnCount))
+        throw new NatureOptionsError('invalid-nature-options', 'Lightning column count must be one, two or three');
+    if (options.columns !== undefined && (!Array.isArray(options.columns) || options.columns.length < 1 || options.columns.length > 3 || options.columns.some(column => !Number.isSafeInteger(column) || column < 0 || column >= width) || new Set(options.columns).size !== options.columns.length))
+        throw new NatureOptionsError('invalid-nature-options', 'Lightning columns must be one to three unique in-range column indexes');
+}
+function faultPath(state) {
+    if (state.width < 3)
+        throw new NatureOptionsError('invalid-grid-size', 'A fault needs at least three columns to preserve playable space on both sides');
+    let randomState = state.randomState;
+    let draw;
+    [randomState, draw] = drawBelow(randomState, state.width - 2);
+    let x = draw + 1;
+    const path = [at(x, 0, state.width)];
+    for (let y = 1; y < state.height; y++) {
+        let step;
+        [randomState, step] = drawBelow(randomState, 3);
+        x = Math.max(1, Math.min(state.width - 2, x + step - 1));
+        path.push(at(x, y, state.width));
+    }
+    if (state.height > 1 && state.width > 3 && path.every((index, y) => y === 0 || index % state.width === path[y - 1] % state.width)) {
+        const row = Math.min(state.height - 1, Math.floor(state.height / 2));
+        const priorX = path[row - 1] % state.width;
+        const bentX = priorX === state.width - 2 ? priorX - 1 : priorX + 1;
+        path[row] = at(bentX, row, state.width);
+    }
+    return [path, randomState];
+}
+/** Preview a bounded top-to-bottom fracture. The path keeps at least one column active on each side. */
+export function previewFault(state) {
+    validateState(state);
+    const [path, randomStateAfter] = faultPath(state);
+    const cells = [...state.cells], activeCells = [...state.activeCells];
+    const removedIds = [], fracturedCells = [];
+    for (const index of path) {
+        if (!activeCells[index])
+            continue;
+        activeCells[index] = false;
+        fracturedCells.push(index);
+        const entity = cells[index];
+        if (entity) {
+            removedIds.push(entity.id);
+            cells[index] = null;
+        }
+    }
+    return deepFreeze({ path, fracturedCells, removedIds, cells, activeCells, randomStateAfter });
+}
+const appearance = (entity) => `${entity.colour}|${Boolean(entity.magnetic)}`;
+function candidatePatches(state) {
+    const patches = [];
+    for (let height = 1; height <= Math.min(3, state.height); height++)
+        for (let width = 1; width <= Math.min(3, state.width); width++) {
+            if (width * height < 2)
+                continue;
+            for (let top = 0; top <= state.height - height; top++)
+                for (let left = 0; left <= state.width - width; left++) {
+                    const cells = [], stones = [];
+                    let allowed = true;
+                    for (let dy = 0; dy < height && allowed; dy++)
+                        for (let dx = 0; dx < width; dx++) {
+                            const index = at(left + dx, top + dy, state.width);
+                            const entity = state.cells[index];
+                            if (!state.activeCells[index] || entity?.kind === 'obstacle' || entity?.kind === 'stone' && entity.anchored) {
+                                allowed = false;
+                                break;
+                            }
+                            cells.push(index);
+                            if (entity?.kind === 'stone')
+                                stones.push(index);
+                        }
+                    if (allowed && stones.length >= 2 && new Set(stones.map(index => appearance(state.cells[index]))).size > 1)
+                        patches.push({ cells, stones });
+                }
+        }
+    return patches;
+}
+/** Preview one seeded, nontrivial stone permutation inside a fully active connected rectangle no larger than 3×3. */
+export function previewJumble(state) {
+    validateState(state);
+    const candidates = candidatePatches(state);
+    if (candidates.length === 0)
+        return deepFreeze({ patchCells: [], moves: [], changed: false, reason: 'no-eligible-patch', cells: state.cells, randomStateAfter: state.randomState });
+    let randomState, selectedIndex;
+    [randomState, selectedIndex] = drawBelow(state.randomState, candidates.length);
+    const patch = candidates[selectedIndex];
+    const shuffled = [...patch.stones];
+    for (let index = shuffled.length - 1; index > 0; index--) {
+        let chosen;
+        [randomState, chosen] = drawBelow(randomState, index + 1);
+        [shuffled[index], shuffled[chosen]] = [shuffled[chosen], shuffled[index]];
+    }
+    if (shuffled.every((index, indexInOrder) => appearance(state.cells[index]) === appearance(state.cells[patch.stones[indexInOrder]]))) {
+        // A swap within identical colours would not change the puzzle.
+        const first = 0;
+        const second = shuffled.findIndex(index => appearance(state.cells[index]) !== appearance(state.cells[shuffled[first]]));
+        [shuffled[first], shuffled[second]] = [shuffled[second], shuffled[first]];
+    }
+    const cells = [...state.cells], moves = [];
+    for (let index = 0; index < patch.stones.length; index++) {
+        const from = patch.stones[index], to = shuffled[index], entity = state.cells[from];
+        cells[to] = entity;
+        if (from !== to)
+            moves.push({ id: entity.id, from: { x: from % state.width, y: Math.floor(from / state.width) }, to: { x: to % state.width, y: Math.floor(to / state.width) } });
+    }
+    for (const index of patch.stones)
+        if (!shuffled.includes(index))
+            cells[index] = null;
+    return deepFreeze({ patchCells: patch.cells, moves, changed: moves.length > 0, cells, randomStateAfter: randomState });
+}
+/** Preview an earthquake, with Combined always fracturing before its one jumble attempt. */
+export function previewEarthquake(state, options) {
+    validateState(state);
+    validateEarthquakeOptions(options);
+    if (options.enabled === false)
+        return deepFreeze({ kind: options.kind, cells: state.cells, activeCells: state.activeCells, randomStateAfter: state.randomState });
+    let cells = state.cells, activeCells = state.activeCells, randomStateAfter = state.randomState;
+    let fault, jumble;
+    if (options.kind === 'fault' || options.kind === 'combined') {
+        fault = previewFault(state);
+        cells = fault.cells;
+        activeCells = fault.activeCells;
+        randomStateAfter = fault.randomStateAfter;
+    }
+    if (options.kind === 'jumble' || options.kind === 'combined') {
+        const jumbleState = fault ? freezeNatureState({ ...state, cells, activeCells, randomState: randomStateAfter }) : state;
+        jumble = previewJumble(jumbleState);
+        cells = jumble.cells;
+        randomStateAfter = jumble.randomStateAfter;
+    }
+    return deepFreeze({ kind: options.kind, ...(fault ? { fault } : {}), ...(jumble ? { jumble } : {}), cells, activeCells, randomStateAfter });
+}
+/** Commit one bounded environmental resolution; matching, gravity and score remain the host game's job. */
+export function applyEarthquake(state, options) {
+    const preview = previewEarthquake(state, options);
+    if (options.enabled === false)
+        return { state, accepted: true, events: [], preview };
+    const events = [];
+    if (preview.fault)
+        events.push(deepFreeze({ type: 'fault-opened', path: preview.fault.path, fracturedCells: preview.fault.fracturedCells, removedIds: preview.fault.removedIds }));
+    if (preview.jumble)
+        events.push(deepFreeze({ type: 'jumble-completed', changed: preview.jumble.changed, ...(preview.jumble.reason ? { reason: preview.jumble.reason } : {}), patchCells: preview.jumble.patchCells, moves: preview.jumble.moves }));
+    if (events.length === 0)
+        return { state, accepted: true, events: [], preview };
+    if (preview.cells === state.cells && preview.activeCells === state.activeCells && preview.randomStateAfter === state.randomState)
+        return { state, accepted: true, events: deepFreeze(events), preview };
+    const next = freezeNatureState({ ...state, cells: preview.cells, activeCells: preview.activeCells, randomState: preview.randomStateAfter });
+    return { state: next, accepted: true, events: deepFreeze(events), preview };
+}
+function chooseColumns(state, options) {
+    if (options.columns !== undefined) {
+        return [[...options.columns].sort((a, b) => a - b), state.randomState];
+    }
+    let randomState = state.randomState, count;
+    if (options.columnCount !== undefined)
+        count = options.columnCount;
+    else {
+        let draw;
+        [randomState, draw] = drawBelow(randomState, 3);
+        count = draw + 1;
+    }
+    count = Math.min(count, state.width);
+    const pool = Array.from({ length: state.width }, (_, column) => column);
+    for (let index = 0; index < count; index++) {
+        let offset;
+        [randomState, offset] = drawBelow(randomState, state.width - index);
+        const swap = index + offset;
+        [pool[index], pool[swap]] = [pool[swap], pool[index]];
+    }
+    return [pool.slice(0, count).sort((a, b) => a - b), randomState];
+}
+/** Preview seeded or explicitly selected columns; a mask gap or obstacle blocks the strike below it. */
+export function previewLightning(state, options = {}) {
+    validateState(state);
+    validateLightningOptions(options, state.width);
+    if (options.enabled === false)
+        return deepFreeze({ columns: [], removedCells: [], removedIds: [], cells: state.cells, randomStateAfter: state.randomState });
+    const [columns, randomStateAfter] = chooseColumns(state, options);
+    const cells = [...state.cells], removedCells = [], removedIds = [];
+    for (const column of columns) {
+        let hits = 0;
+        for (let y = 0; y < state.height && hits < 2; y++) {
+            const index = at(column, y, state.width);
+            if (!state.activeCells[index] || cells[index]?.kind === 'obstacle')
+                break;
+            const entity = cells[index];
+            if (entity?.kind === 'stone') {
+                cells[index] = null;
+                removedCells.push(index);
+                removedIds.push(entity.id);
+                hits++;
+            }
+        }
+    }
+    return deepFreeze({ columns, removedCells, removedIds, cells, randomStateAfter });
+}
+/** Commit one lightning strike. It removes exposed stones only and consumes no scores or tools. */
+export function applyLightning(state, options = {}) {
+    const preview = previewLightning(state, options);
+    if (options.enabled === false)
+        return { state, accepted: true, events: [], preview };
+    const event = deepFreeze({ type: 'lightning-struck', columns: preview.columns, removedCells: preview.removedCells, removedIds: preview.removedIds });
+    if (preview.randomStateAfter === state.randomState && preview.removedIds.length === 0)
+        return { state, accepted: true, events: [event], preview };
+    const next = freezeNatureState({ ...state, cells: preview.cells, randomState: preview.randomStateAfter });
+    return { state: next, accepted: true, events: [event], preview };
+}

package/dist/nature/marking.d.ts

@@ -0,0 +1,3 @@
+import type { MarkingOptions, NatureState, NatureTransition } from './types.js';
+/** Deterministically assign magnetic markings to settled stones without changing their IDs or colours. */
+export declare function markMagneticStones(state: NatureState, options: MarkingOptions): NatureTransition;

package/dist/nature/marking.js

@@ -0,0 +1,39 @@
+import { validateMarkingOptions, validateState } from './validation.js';
+import { freezeNatureState } from './state.js';
+import { nextNatureUnit } from './random.js';
+/** Deterministically assign magnetic markings to settled stones without changing their IDs or colours. */
+export function markMagneticStones(state, options) {
+    validateState(state);
+    validateMarkingOptions(options);
+    if (!state.rules.magneticEnabled || options.maximum === 0 || options.probability === 0)
+        return { state, accepted: true, events: [] };
+    const maximum = options.maximum ?? state.cells.length;
+    const anchoredProbability = options.anchoredProbability ?? 0;
+    let randomState = state.randomState;
+    let marked = 0;
+    const ids = [];
+    const cells = state.cells.map(entity => {
+        if (!entity || entity.kind !== 'stone' || entity.magnetic || marked >= maximum)
+            return entity;
+        let sample;
+        [randomState, sample] = nextNatureUnit(randomState);
+        if (sample >= options.probability)
+            return entity;
+        let anchored = false;
+        if (anchoredProbability > 0) {
+            let anchorSample;
+            [randomState, anchorSample] = nextNatureUnit(randomState);
+            anchored = anchorSample < anchoredProbability;
+        }
+        marked++;
+        ids.push(entity.id);
+        return { ...entity, magnetic: true, ...(anchored ? { anchored: true } : {}) };
+    });
+    if (ids.length === 0) {
+        const unchanged = randomState === state.randomState ? state : freezeNatureState({ ...state, randomState });
+        return { state: unchanged, accepted: true, events: [] };
+    }
+    const next = freezeNatureState({ ...state, cells, randomState });
+    const event = Object.freeze({ type: 'magnetic-stones-marked', ids: Object.freeze(ids), randomState });
+    return { state: next, accepted: true, events: [event] };
+}

package/dist/nature/random.d.ts

@@ -0,0 +1,3 @@
+export declare function seedNatureState(seed: string): number;
+export declare function nextNatureUint32(state: number): readonly [number, number];
+export declare function nextNatureUnit(state: number): readonly [number, number];

package/dist/nature/random.js

@@ -0,0 +1,19 @@
+export function seedNatureState(seed) {
+    let value = 0x811c_9dc5;
+    for (let index = 0; index < seed.length; index++) {
+        value ^= seed.charCodeAt(index);
+        value = Math.imul(value, 0x0100_0193) >>> 0;
+    }
+    return value || 0x6d2b_79f5;
+}
+export function nextNatureUint32(state) {
+    let next = state >>> 0;
+    next ^= next << 13;
+    next ^= next >>> 17;
+    next ^= next << 5;
+    return [next >>> 0, next >>> 0];
+}
+export function nextNatureUnit(state) {
+    const [next, value] = nextNatureUint32(state);
+    return [next, value / 0x1_0000_0000];
+}

package/dist/nature/rebound.d.ts

@@ -0,0 +1,5 @@
+import type { NatureState, NatureTransition, PowerDropPreview, PowerDropRequest } from './types.js';
+/** Preview a single normal landing and, for a power drop, at most one validated one-cell rebound. */
+export declare function previewPowerDrop(state: NatureState, request: PowerDropRequest): PowerDropPreview;
+/** Commit a previewed landing as one immutable operation. A failed preview leaves the original state untouched. */
+export declare function applyPowerDrop(state: NatureState, request: PowerDropRequest): NatureTransition;