@johnmorrisdotca/houseki 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,17 @@
+import type { CreateOptions, GameState, ReplayOperation } from './types.js';
+export declare class ReplayError extends TypeError {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+/** Encodes the initial rules plus accepted actions and logical inputs in canonical JSON. */
+export declare function encodeGame(state: GameState): string;
+/** Validates and reconstructs a state by replay; serialized board snapshots are never trusted. */
+export declare function decodeGame(serialized: string): GameState;
+/** Starts the exact initial ruleset and seed again, discarding all run progress. */
+export declare function restartGame(state: GameState): GameState;
+/** Checks a complete authored witness through the public deterministic rules API. */
+export declare function validateChallengeWitness(options: CreateOptions, witness: readonly ReplayOperation[]): {
+    readonly valid: boolean;
+    readonly state?: GameState;
+    readonly reason?: string;
+};

package/dist/gem-swap/persistence.js

@@ -0,0 +1,107 @@
+import { advanceTime, advanceTicks, applyAction, createGame } from './engine.js';
+const FORMAT = 'gem-swap-replay-1';
+const MAX_BYTES = 262_144;
+const MAX_OPERATIONS = 5_000;
+const MAX_TICKS = 100_000;
+const byteLength = (value) => new TextEncoder().encode(value).byteLength;
+export class ReplayError extends TypeError {
+    code;
+    constructor(code, message) { super(message); this.name = 'ReplayError'; this.code = code; }
+}
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(',')}]`;
+    if (value && typeof value === 'object') {
+        const object = value;
+        return `{${Object.keys(object).sort().map(key => `${JSON.stringify(key)}:${canonical(object[key])}`).join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+function validateOperation(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new ReplayError('invalid-operation', 'Replay operation must be an object');
+    const input = value;
+    if (input.kind === 'action' && Object.keys(input).every(key => ['kind', 'action'].includes(key)) && input.action && typeof input.action === 'object' && !Array.isArray(input.action))
+        return { kind: 'action', action: input.action };
+    if (input.kind === 'ticks' && Object.keys(input).every(key => ['kind', 'count'].includes(key)) && Number.isInteger(input.count) && input.count > 0 && input.count <= 3600)
+        return { kind: 'ticks', count: input.count };
+    if (input.kind === 'time' && Object.keys(input).every(key => ['kind', 'milliseconds'].includes(key)) && Number.isInteger(input.milliseconds) && input.milliseconds > 0 && input.milliseconds <= 180_000)
+        return { kind: 'time', milliseconds: input.milliseconds };
+    throw new ReplayError('invalid-operation', 'Replay operation is malformed or unsupported');
+}
+function execute(initial, operations) {
+    let state = createGame(initial);
+    let ticks = 0;
+    for (let index = 0; index < operations.length; index++) {
+        const operation = operations[index];
+        if (operation.kind === 'action') {
+            const result = applyAction(state, operation.action);
+            if (!result.accepted)
+                throw new ReplayError('rejected-action', `Replay action ${index} was rejected: ${result.reason ?? 'unknown reason'}`);
+            state = result.state;
+        }
+        else if (operation.kind === 'ticks') {
+            ticks += operation.count;
+            if (ticks > MAX_TICKS)
+                throw new ReplayError('replay-too-long', 'Replay exceeds the tick work limit');
+            state = advanceTicks(state, operation.count).state;
+        }
+        else {
+            const result = advanceTime(state, operation.milliseconds);
+            if (!result.accepted)
+                throw new ReplayError('invalid-time-step', `Replay time step ${index} was rejected`);
+            state = result.state;
+        }
+    }
+    return state;
+}
+/** Encodes the initial rules plus accepted actions and logical inputs in canonical JSON. */
+export function encodeGame(state) {
+    if (!state || state.game !== 'gem-swap' || state.history.length > MAX_OPERATIONS)
+        throw new ReplayError('invalid-state', 'State is invalid or exceeds the operation limit');
+    const operations = state.history.map(validateOperation);
+    const replayed = execute(state.initialOptions, operations);
+    if (canonical(replayed) !== canonical(state))
+        throw new ReplayError('checkpoint-mismatch', 'State does not match its recorded inputs');
+    const result = canonical({ format: FORMAT, initial: state.initialOptions, operations });
+    if (byteLength(result) > MAX_BYTES)
+        throw new ReplayError('save-too-large', 'Replay exceeds the 256 KiB size limit');
+    return result;
+}
+/** Validates and reconstructs a state by replay; serialized board snapshots are never trusted. */
+export function decodeGame(serialized) {
+    if (typeof serialized !== 'string' || byteLength(serialized) > MAX_BYTES)
+        throw new ReplayError('save-too-large', 'Replay must be a string no larger than 256 KiB');
+    let parsed;
+    try {
+        parsed = JSON.parse(serialized);
+    }
+    catch {
+        throw new ReplayError('invalid-json', 'Replay is not valid JSON');
+    }
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        throw new ReplayError('invalid-recording', 'Replay root must be an object');
+    const value = parsed;
+    if (Object.keys(value).length !== 3 || Object.keys(value).some(key => !['format', 'initial', 'operations'].includes(key)) || value.format !== FORMAT || !Array.isArray(value.operations) || value.operations.length > MAX_OPERATIONS || !value.initial || typeof value.initial !== 'object' || Array.isArray(value.initial))
+        throw new ReplayError('invalid-recording', 'Replay envelope is malformed or unsupported');
+    if (canonical(parsed) !== serialized)
+        throw new ReplayError('noncanonical-recording', 'Replay JSON must use canonical key order and encoding');
+    const operations = value.operations.map(validateOperation);
+    return execute(value.initial, operations);
+}
+/** Starts the exact initial ruleset and seed again, discarding all run progress. */
+export function restartGame(state) { return createGame(state.initialOptions); }
+/** Checks a complete authored witness through the public deterministic rules API. */
+export function validateChallengeWitness(options, witness) {
+    try {
+        if (options.mode !== 'challenge' || !Array.isArray(witness) || witness.length > MAX_OPERATIONS)
+            throw new ReplayError('invalid-witness', 'Challenge witness or settings are invalid');
+        const state = execute(options, witness.map(validateOperation));
+        if (state.outcome !== 'won')
+            throw new ReplayError('witness-does-not-win', 'Challenge witness does not complete every goal');
+        return Object.freeze({ valid: true, state });
+    }
+    catch (error) {
+        return Object.freeze({ valid: false, reason: error instanceof Error ? error.message : 'invalid-witness' });
+    }
+}

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

@@ -0,0 +1,4 @@
+import type { GameState, ReplayOperation, Transition } from './types.js';
+export declare function undoTransition(state: GameState, replay: (options: GameState['initialOptions'], operations: readonly ReplayOperation[]) => GameState): Transition;
+export declare function hintTransition(state: GameState): Transition;
+export declare function reshuffleTransition(state: GameState): Transition;

package/dist/gem-swap/practice.js

@@ -0,0 +1,57 @@
+import { findMatches, listLegalSwaps } from './board.js';
+import { nextInt } from './random.js';
+function rejected(state, reason) { return { state, events: Object.freeze([]), accepted: false, reason }; }
+function onReady(state) { return state.phase === 'ready' && findMatches(state.board, state.settings).length === 0; }
+export function undoTransition(state, replay) {
+    if (!['relaxed', 'challenge'].includes(state.mode) || state.phase !== 'ready' || state.selectedTool)
+        return rejected(state, 'undo-unavailable');
+    const outstanding = [];
+    state.history.forEach((operation, index) => { if (operation.kind !== 'action')
+        return; if (operation.action.kind === 'swap')
+        outstanding.push(index);
+    else if (operation.action.kind === 'undo')
+        outstanding.pop(); });
+    const lastSwap = outstanding.at(-1) ?? -1;
+    if (lastSwap < 0)
+        return rejected(state, 'nothing-to-undo');
+    let restored;
+    try {
+        restored = replay(state.initialOptions, state.history.slice(0, lastSwap));
+    }
+    catch {
+        return rejected(state, 'undo-unavailable');
+    }
+    return { state: Object.freeze({ ...restored, assisted: true, history: state.history }), events: Object.freeze([{ type: 'move-undone', moves: restored.moves, assisted: true }]), accepted: true };
+}
+export function hintTransition(state) {
+    if (!onReady(state) || state.selectedTool)
+        return rejected(state, 'hint-unavailable');
+    const witness = listLegalSwaps(state)[0];
+    if (!witness)
+        return rejected(state, 'no-legal-swap');
+    return { state: Object.freeze({ ...state, assisted: true }), events: Object.freeze([{ type: 'hint', action: witness, guarantee: 'legal-only' }]), accepted: true };
+}
+export function reshuffleTransition(state) {
+    const finishedRelaxed = state.mode === 'relaxed' && state.phase === 'finished' && state.outcome === 'finished' && !findMatches(state.board, state.settings).length;
+    if (state.mode !== 'relaxed' || (!onReady(state) && !finishedRelaxed) || state.selectedTool)
+        return rejected(state, 'reshuffle-unavailable');
+    const gems = state.board.filter((item) => item !== null);
+    let randomState = state.randomState;
+    for (let attempt = 0; attempt < 128; attempt++) {
+        const shuffled = [...gems];
+        for (let index = shuffled.length - 1; index > 0; index--) {
+            const [pick, next] = nextInt(randomState, index + 1);
+            randomState = next;
+            [shuffled[index], shuffled[pick]] = [shuffled[pick], shuffled[index]];
+        }
+        const board = [...state.board];
+        let at = 0;
+        for (let index = 0; index < board.length; index++)
+            if (state.settings.mask[index])
+                board[index] = shuffled[at++];
+        if (!findMatches(board, state.settings).length && listLegalSwaps({ ...state, board }).length) {
+            return { state: Object.freeze({ ...state, board: Object.freeze(board), randomState, assisted: true, phase: 'ready', outcome: null, selectedTool: null, toolTarget: null, toolPreview: Object.freeze([]) }), events: Object.freeze([{ type: 'board-reshuffled', attempts: attempt + 1, assisted: true }]), accepted: true };
+        }
+    }
+    return rejected(state, 'reshuffle-failed');
+}

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

@@ -0,0 +1,9 @@
+import type { GemColour } from './types.js';
+/** Hashes a seed with FNV-1a, scoped to this game and its rule identity. */
+export declare function seedState(seed: string | number): number;
+/** Advances the reference xorshift32 random source. */
+export declare function nextUint32(state: number): number;
+/** Draws an unbiased integer and its following random state. */
+export declare function nextInt(state: number, size: number): readonly [number, number];
+/** Draws one uniformly selected configured normal-gem colour. */
+export declare function drawColour(state: number, colourCount: number): readonly [GemColour, number];

package/dist/gem-swap/random.js

@@ -0,0 +1,32 @@
+import { COLOURS } from './board.js';
+/** Hashes a seed with FNV-1a, scoped to this game and its rule identity. */
+export function seedState(seed) {
+    let hash = 0x811c9dc5;
+    for (const byte of new TextEncoder().encode(`gem-swap|swap-1|${String(seed)}`))
+        hash = Math.imul(hash ^ byte, 0x01000193) >>> 0;
+    return hash || 0x6d2b79f5;
+}
+/** Advances the reference xorshift32 random source. */
+export function nextUint32(state) {
+    let next = state >>> 0;
+    next ^= next << 13;
+    next ^= next >>> 17;
+    next ^= next << 5;
+    return next >>> 0;
+}
+/** Draws an unbiased integer and its following random state. */
+export function nextInt(state, size) {
+    const limit = Math.floor(0x1_0000_0000 / size) * size;
+    let current = state >>> 0;
+    for (;;) {
+        const value = nextUint32(current);
+        current = value;
+        if (value < limit)
+            return [value % size, current];
+    }
+}
+/** Draws one uniformly selected configured normal-gem colour. */
+export function drawColour(state, colourCount) {
+    const [index, next] = nextInt(state, colourCount);
+    return [COLOURS[index], next];
+}

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

@@ -0,0 +1,13 @@
+import type { GameEvent, GameState, Gem, PlannedSpecial } from './types.js';
+interface ResolutionPlan {
+    readonly cells: readonly number[];
+    readonly specials: readonly PlannedSpecial[];
+    readonly events: readonly GameEvent[];
+}
+/** Returns whether a swap is legal under ordinary-run and explicit-combination rules. */
+export declare function isValidSpecialSwap(first: Gem, second: Gem, hasNaturalMatch: boolean): boolean;
+/** Resolves one normal/special match wave into a unique clear set and protected creations. */
+export declare function planWave(state: GameState, naturalCells: readonly number[], p: number | null, q: number | null, extraClearCells?: readonly number[]): ResolutionPlan;
+/** Materializes newly planned powers on surviving anchor gems after a wave's removal. */
+export declare function materializeSpecials(board: readonly (Gem | null)[], specials: readonly PlannedSpecial[]): readonly (Gem | null)[];
+export {};

package/dist/gem-swap/specials.js

@@ -0,0 +1,300 @@
+function runsOf(state) {
+    const { width, height, mask } = state.settings;
+    const runs = [];
+    const scan = (cells, axis) => {
+        let at = 0;
+        while (at < cells.length) {
+            const gem = state.board[cells[at]];
+            if (!gem) {
+                at++;
+                continue;
+            }
+            let end = at + 1;
+            while (end < cells.length && state.board[cells[end]]?.colour === gem.colour)
+                end++;
+            if (end - at >= 3)
+                runs.push({ cells: cells.slice(at, end), axis });
+            at = end;
+        }
+    };
+    for (let y = 0; y < height; y++) {
+        let segment = [];
+        for (let x = 0; x <= width; x++) {
+            const index = y * width + x;
+            if (x < width && mask[index])
+                segment.push(index);
+            else {
+                scan(segment, 'horizontal');
+                segment = [];
+            }
+        }
+    }
+    for (let x = 0; x < width; x++) {
+        let segment = [];
+        for (let y = 0; y <= height; y++) {
+            const index = y * width + x;
+            if (y < height && mask[index])
+                segment.push(index);
+            else {
+                scan(segment, 'vertical');
+                segment = [];
+            }
+        }
+    }
+    return runs;
+}
+function compareRun(a, b, p, q, width) {
+    const hasQ = Number(b.cells.includes(q ?? -1)) - Number(a.cells.includes(q ?? -1));
+    if (hasQ)
+        return hasQ;
+    const hasP = Number(b.cells.includes(p ?? -1)) - Number(a.cells.includes(p ?? -1));
+    if (hasP)
+        return hasP;
+    const maxY = (run) => Math.max(...run.cells.map(cell => Math.floor(cell / width)));
+    const byMaxY = maxY(b) - maxY(a);
+    if (byMaxY)
+        return byMaxY;
+    const minX = (run) => Math.min(...run.cells.map(cell => cell % width));
+    const byMinX = minX(a) - minX(b);
+    if (byMinX)
+        return byMinX;
+    if (a.axis !== b.axis)
+        return a.axis === 'horizontal' ? -1 : 1;
+    return a.cells[0] - b.cells[0];
+}
+function chooseAnchor(cells, state, p, q) {
+    const eligible = cells.filter(cell => state.board[cell] && !state.board[cell].kind);
+    eligible.sort((a, b) => {
+        const aQ = a === q ? 0 : 1;
+        const bQ = b === q ? 0 : 1;
+        if (aQ !== bQ)
+            return aQ - bQ;
+        const aP = a === p ? 0 : 1;
+        const bP = b === p ? 0 : 1;
+        if (aP !== bP)
+            return aP - bP;
+        const yDiff = Math.floor(b / state.settings.width) - Math.floor(a / state.settings.width);
+        if (yDiff)
+            return yDiff;
+        return a % state.settings.width - b % state.settings.width;
+    });
+    return eligible[0] ?? null;
+}
+function planCreations(state, runs, p, q) {
+    const parents = runs.map((_, index) => index);
+    const root = (value) => parents[value] === value ? value : (parents[value] = root(parents[value]));
+    const join = (a, b) => { const ra = root(a); const rb = root(b); if (ra !== rb)
+        parents[rb] = ra; };
+    const owner = new Map();
+    for (let i = 0; i < runs.length; i++)
+        for (const cell of runs[i].cells) {
+            const prior = owner.get(cell);
+            if (prior === undefined)
+                owner.set(cell, i);
+            else
+                join(i, prior);
+        }
+    const groups = new Map();
+    for (let i = 0; i < runs.length; i++) {
+        const key = root(i);
+        const group = groups.get(key) ?? [];
+        group.push(runs[i]);
+        groups.set(key, group);
+    }
+    const planned = [];
+    for (const group of groups.values()) {
+        const burstRuns = group.filter(run => run.cells.length >= 5).sort((a, b) => b.cells.length - a.cells.length || compareRun(a, b, p, q, state.settings.width));
+        if (burstRuns.length) {
+            const run = burstRuns[0];
+            const anchor = chooseAnchor(run.cells, state, p, q);
+            if (anchor !== null)
+                planned.push({ cell: anchor, kind: 'colour-burst' });
+            continue;
+        }
+        const horizontal = group.filter(run => run.axis === 'horizontal');
+        const vertical = group.filter(run => run.axis === 'vertical');
+        const intersections = [...new Set(horizontal.flatMap(h => vertical.flatMap(v => h.cells.filter(cell => v.cells.includes(cell)))))].sort((a, b) => a - b);
+        if (intersections.length) {
+            const anchor = chooseAnchor(intersections, state, p, q);
+            if (anchor !== null)
+                planned.push({ cell: anchor, kind: 'bomb' });
+            continue;
+        }
+        const fourRuns = group.filter(run => run.cells.length === 4).sort((a, b) => compareRun(a, b, p, q, state.settings.width));
+        if (fourRuns.length) {
+            const run = fourRuns[0];
+            const anchor = chooseAnchor(run.cells, state, p, q);
+            if (anchor !== null)
+                planned.push({ cell: anchor, kind: run.axis === 'horizontal' ? 'row-beam' : 'column-beam' });
+        }
+    }
+    return Object.freeze(planned.sort((a, b) => a.cell - b.cell));
+}
+function isBurst(kind) { return kind === 'colour-burst'; }
+function isSpecial(gem) { return Boolean(gem?.kind); }
+/** Returns whether a swap is legal under ordinary-run and explicit-combination rules. */
+export function isValidSpecialSwap(first, second, hasNaturalMatch) {
+    if (isSpecial(first) && isSpecial(second))
+        return true;
+    if (isBurst(first.kind) || isBurst(second.kind))
+        return true;
+    return first.colour !== second.colour && hasNaturalMatch;
+}
+function activeCells(state) { return state.settings.mask.flatMap((on, index) => on && state.board[index] ? [index] : []); }
+function comboPlan(state, p, q, protectedCells, pairIds) {
+    const a = state.board[p];
+    const b = state.board[q];
+    const ak = a.kind;
+    const bk = b.kind;
+    if (!ak && !bk)
+        return null;
+    const centre = q;
+    const { width, height } = state.settings;
+    const direct = new Set([p, q]);
+    const conversions = [];
+    const row = (y) => activeCells(state).filter(cell => Math.floor(cell / width) === y);
+    const column = (x) => activeCells(state).filter(cell => cell % width === x);
+    const burst = ak === 'colour-burst' ? a : bk === 'colour-burst' ? b : null;
+    if (ak && bk) {
+        if (ak === 'colour-burst' && bk === 'colour-burst')
+            return { name: 'burst-burst', direct: activeCells(state), conversions };
+        if (ak === 'colour-burst' || bk === 'colour-burst') {
+            const power = ak === 'colour-burst' ? bk : ak;
+            if (power !== 'row-beam' && power !== 'column-beam' && power !== 'bomb')
+                return null;
+            const targetColour = ak === 'colour-burst' ? b.colour : a.colour;
+            const conversionKind = power;
+            for (const cell of activeCells(state)) {
+                const gem = state.board[cell];
+                if (gem.colour === targetColour && !pairIds.has(gem.id) && !protectedCells.has(cell))
+                    conversions.push({ cell, kind: conversionKind });
+            }
+            return { name: `burst-${power}`, direct: [...direct, ...conversions.map(item => item.cell)], conversions };
+        }
+        if (ak === 'bomb' && bk === 'bomb') {
+            const x = centre % width;
+            const y = Math.floor(centre / width);
+            for (const cell of activeCells(state))
+                if (Math.abs(cell % width - x) <= 2 && Math.abs(Math.floor(cell / width) - y) <= 2)
+                    direct.add(cell);
+            return { name: 'bomb-bomb', direct: [...direct], conversions };
+        }
+        if ((ak === 'row-beam' || ak === 'column-beam') && (bk === 'row-beam' || bk === 'column-beam')) {
+            for (const cell of row(Math.floor(centre / width)))
+                direct.add(cell);
+            for (const cell of column(centre % width))
+                direct.add(cell);
+            return { name: 'beam-beam', direct: [...direct], conversions };
+        }
+        const beam = ak === 'bomb' ? bk : bk === 'bomb' ? ak : null;
+        if (beam === 'row-beam' || beam === 'column-beam') {
+            const x = centre % width;
+            const y = Math.floor(centre / width);
+            for (let rowY = Math.max(0, y - 1); rowY <= Math.min(height - 1, y + 1); rowY++)
+                for (const cell of row(rowY))
+                    direct.add(cell);
+            for (let columnX = Math.max(0, x - 1); columnX <= Math.min(width - 1, x + 1); columnX++)
+                for (const cell of column(columnX))
+                    direct.add(cell);
+            return { name: 'beam-bomb', direct: [...direct], conversions };
+        }
+        if (ak === 'bomb' && bk === 'bomb')
+            return { name: 'bomb-bomb', direct: [...direct], conversions };
+    }
+    if (burst) {
+        const target = ak === 'colour-burst' ? b : a;
+        for (const cell of activeCells(state))
+            if (state.board[cell].colour === target.colour)
+                direct.add(cell);
+        return { name: 'burst-normal', direct: [...direct], conversions };
+    }
+    return null;
+}
+function effectCells(state, cell, kind) {
+    const { width, height } = state.settings;
+    const x = cell % width;
+    const y = Math.floor(cell / width);
+    if (kind === 'row-beam')
+        return activeCells(state).filter(index => Math.floor(index / width) === y);
+    if (kind === 'column-beam')
+        return activeCells(state).filter(index => index % width === x);
+    if (kind === 'bomb')
+        return activeCells(state).filter(index => Math.abs(index % width - x) <= 1 && Math.abs(Math.floor(index / width) - y) <= 1);
+    const colour = state.board[cell].colour;
+    return activeCells(state).filter(index => state.board[index].colour === colour);
+}
+/** Resolves one normal/special match wave into a unique clear set and protected creations. */
+export function planWave(state, naturalCells, p, q, extraClearCells = []) {
+    const runs = runsOf(state);
+    const specials = planCreations(state, runs, p, q);
+    const protectedCells = new Set(specials.map(item => item.cell));
+    const pairIds = new Set(p === null || q === null ? [] : [state.board[p].id, state.board[q].id]);
+    const combo = p === null || q === null ? null : comboPlan(state, p, q, protectedCells, pairIds);
+    const consumedPairIds = combo ? pairIds : new Set();
+    const conversionKinds = new Map((combo?.conversions ?? []).map(item => [state.board[item.cell].id, item.kind]));
+    const cleared = new Set();
+    const activations = [];
+    const activationIds = new Set();
+    const events = [];
+    const activationEvents = [];
+    const addActivation = (cell, kind) => {
+        const gem = state.board[cell];
+        if (!gem || protectedCells.has(cell) || consumedPairIds.has(gem.id) || activationIds.has(gem.id))
+            return;
+        activationIds.add(gem.id);
+        activations.push({ cell, gemId: gem.id, kind });
+    };
+    const addCell = (cell) => {
+        const gem = state.board[cell];
+        if (!gem || protectedCells.has(cell))
+            return;
+        cleared.add(cell);
+        if (isSpecial(gem))
+            addActivation(cell, conversionKinds.get(gem.id) ?? gem.kind);
+    };
+    for (const cell of naturalCells)
+        addCell(cell);
+    for (const cell of extraClearCells)
+        addCell(cell);
+    if (combo) {
+        events.push({ type: 'special-combination', combo: combo.name, centre: q });
+        const convertedCells = new Set(combo.conversions.map(item => item.cell));
+        for (const cell of combo.direct) {
+            const gem = state.board[cell];
+            if (gem && !protectedCells.has(cell) && (pairIds.has(gem.id) || convertedCells.has(cell)))
+                cleared.add(cell);
+            else
+                addCell(cell);
+        }
+        for (const converted of combo.conversions) {
+            const gem = state.board[converted.cell];
+            if (!gem || protectedCells.has(converted.cell))
+                continue;
+            cleared.add(converted.cell);
+            addActivation(converted.cell, converted.kind);
+        }
+    }
+    while (activations.length) {
+        activations.sort((a, b) => a.cell - b.cell || a.gemId - b.gemId);
+        const current = activations.shift();
+        const kind = current.kind;
+        activationEvents.push({ type: 'special-activated', id: current.gemId, cell: current.cell, kind });
+        for (const cell of effectCells(state, current.cell, kind))
+            addCell(cell);
+    }
+    activationEvents.sort((a, b) => Number(a.cell) - Number(b.cell) || Number(a.id) - Number(b.id));
+    events.push(...activationEvents);
+    for (const special of specials)
+        events.push({ type: 'special-planned', cell: special.cell, kind: special.kind, id: state.board[special.cell].id });
+    return { cells: Object.freeze([...cleared].sort((a, b) => a - b)), specials, events: Object.freeze(events) };
+}
+/** Materializes newly planned powers on surviving anchor gems after a wave's removal. */
+export function materializeSpecials(board, specials) {
+    const next = [...board];
+    for (const planned of specials) {
+        const gem = next[planned.cell];
+        if (gem)
+            next[planned.cell] = Object.freeze({ ...gem, kind: planned.kind });
+    }
+    return Object.freeze(next);
+}

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

@@ -0,0 +1,3 @@
+import type { GameState, ToolKind } from './types.js';
+/** Computes the occupied cells affected by a tool and all special activations it causes. */
+export declare function previewTool(state: GameState, tool: ToolKind, target: number): readonly number[];

package/dist/gem-swap/tools.js

@@ -0,0 +1,20 @@
+import { planWave } from './specials.js';
+/** Computes the occupied cells affected by a tool and all special activations it causes. */
+export function previewTool(state, tool, target) {
+    const { width, height, mask } = state.settings;
+    if (!Number.isInteger(target) || target < 0 || target >= state.board.length || !mask[target] || !state.board[target])
+        return Object.freeze([]);
+    const x = target % width;
+    const y = Math.floor(target / width);
+    const targetGem = state.board[target];
+    const direct = state.board.flatMap((gem, cell) => {
+        if (!gem || !mask[cell])
+            return [];
+        if (tool === 'colour-clear')
+            return gem.colour === targetGem.colour ? [cell] : [];
+        if (tool === 'row-clear')
+            return Math.floor(cell / width) === y ? [cell] : [];
+        return Math.abs(cell % width - x) <= 1 && Math.abs(Math.floor(cell / width) - y) <= 1 ? [cell] : [];
+    });
+    return planWave(state, [], null, null, direct).cells;
+}