@johnmorrisdotca/kazu 1.1.0 → 1.3.0

package/dist/rippleBoard.js

@@ -0,0 +1,99 @@
+import { RIPPLE_MAX_SIDE, RIPPLE_MIN_SIDE } from "./ripple.constants.js";
+export function isRippleBoard(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const board = value;
+    if (!Number.isInteger(board.width) || board.width < RIPPLE_MIN_SIDE || board.width > RIPPLE_MAX_SIDE
+        || !Number.isInteger(board.height) || board.height < RIPPLE_MIN_SIDE || board.height > RIPPLE_MAX_SIDE
+        || !Array.isArray(board.rooms) || !Array.isArray(board.clues)
+        || board.rooms.length !== board.width * board.height || board.clues.length !== board.rooms.length
+        || board.rooms.some(id => !Number.isInteger(id) || id < 0))
+        return false;
+    const members = new Map();
+    board.rooms.forEach((id, cell) => members.set(id, [...(members.get(id) ?? []), cell]));
+    const ids = [...members.keys()].sort((a, b) => a - b);
+    if (ids.some((id, index) => id !== index))
+        return false;
+    const sizes = new Map([...members].map(([id, cells]) => [id, cells.length]));
+    if (board.clues.some((clue, cell) => clue !== null && (!Number.isInteger(clue) || clue < 1 || clue > sizes.get(board.rooms[cell]))))
+        return false;
+    return [...members].every(([id, cells]) => connected(board, id, cells));
+}
+function connected(board, room, cells) {
+    const reached = new Set([cells[0]]);
+    const queue = [cells[0]];
+    while (queue.length) {
+        const cell = queue.pop();
+        for (const next of [cell - board.width, cell + board.width, cell - 1, cell + 1]) {
+            if (next < 0 || next >= board.rooms.length || (Math.abs(next - cell) === 1 && Math.floor(next / board.width) !== Math.floor(cell / board.width)))
+                continue;
+            if (board.rooms[next] === room && !reached.has(next)) {
+                reached.add(next);
+                queue.push(next);
+            }
+        }
+    }
+    return reached.size === cells.length;
+}
+export function rippleRoomSizes(board) {
+    const sizes = [];
+    board.rooms.forEach(id => { sizes[id] = (sizes[id] ?? 0) + 1; });
+    return sizes;
+}
+/** Checks room permutations and the at-least-N-cell gap between equal N clues in a line. */
+export function checkRipple(board, values) {
+    if (!isRippleBoard(board))
+        throw new RangeError("Invalid Ripple Effect board");
+    if (values.length !== board.rooms.length)
+        throw new RangeError("Invalid Ripple Effect values");
+    const errors = new Set();
+    const sizes = rippleRoomSizes(board);
+    const seen = new Map();
+    values.forEach((value, cell) => {
+        const clue = board.clues[cell];
+        if (!Number.isInteger(value) || value < 0 || value > sizes[board.rooms[cell]]
+            || clue !== null && value !== clue) {
+            errors.add(cell);
+            return;
+        }
+        if (value > 0)
+            seen.set(board.rooms[cell], [...(seen.get(board.rooms[cell]) ?? []), value]);
+    });
+    for (const room of seen.keys()) {
+        const cells = values.flatMap((value, cell) => board.rooms[cell] === room && value > 0 ? [value] : []);
+        const duplicates = new Set(cells.filter((value, index) => cells.indexOf(value) !== index));
+        if (duplicates.size)
+            values.forEach((value, cell) => { if (board.rooms[cell] === room && duplicates.has(value))
+                errors.add(cell); });
+    }
+    const lines = [...Array.from({ length: board.height }, (_, y) => Array.from({ length: board.width }, (_, x) => y * board.width + x)),
+        ...Array.from({ length: board.width }, (_, x) => Array.from({ length: board.height }, (_, y) => y * board.width + x))];
+    for (const line of lines)
+        for (let a = 0; a < line.length; a += 1) {
+            const cell = line[a], value = values[cell];
+            if (!value)
+                continue;
+            for (let b = a + 1; b < line.length; b += 1) {
+                const other = line[b];
+                if (values[other] === value && b - a <= value) {
+                    errors.add(cell);
+                    errors.add(other);
+                }
+            }
+        }
+    const complete = values.every(value => value > 0);
+    if (complete) {
+        for (let room = 0; room < sizes.length; room += 1) {
+            const list = values.flatMap((value, cell) => board.rooms[cell] === room ? [value] : []).sort((a, b) => a - b);
+            if (list.some((value, index) => value !== index + 1))
+                board.rooms.forEach((id, cell) => { if (id === room)
+                    errors.add(cell); });
+        }
+    }
+    return { ok: errors.size === 0 && complete, errors: [...errors].sort((a, b) => a - b), complete };
+}
+/** Partial progress check; missing entries are allowed, but impossible room/ripple pairs are flagged. */
+export function progressRipple(board, values) {
+    const result = checkRipple(board, values);
+    return { ...result, ok: result.errors.length === 0 };
+}

package/dist/rippleDraw.d.ts

@@ -0,0 +1,3 @@
+import type { RippleBoard } from "./ripple.types.ts";
+import type { RippleDrawOptions } from "./ripplePlay.types.ts";
+export declare function drawRipple(board: RippleBoard, options?: RippleDrawOptions): string;

package/dist/rippleDraw.js

@@ -0,0 +1,32 @@
+import { rippleRoomSizes } from "./rippleBoard.js";
+export function drawRipple(board, options = {}) {
+    const size = 56, margin = 8, width = board.width * size, height = board.height * size;
+    const ink = options.material === "slate" ? "#f1eee5" : options.material === "wood" ? "#382d20" : "#252824";
+    const line = options.material === "slate" ? "#899697" : options.material === "wood" ? "#80613c" : "#8b8578";
+    const surface = options.material === "slate" ? "#354247" : options.material === "wood" ? "#dfc18f" : "#faf7ef";
+    const values = options.values ?? board.clues.map(clue => clue ?? 0);
+    const notes = options.notes ?? board.rooms.map(() => []);
+    const sizes = rippleRoomSizes(board);
+    const cells = Array.from({ length: board.rooms.length }, (_, cell) => {
+        const x = cell % board.width * size, y = Math.floor(cell / board.width) * size;
+        const room = board.rooms[cell];
+        const clue = board.clues[cell];
+        const value = values[cell] ?? 0;
+        const text = clue !== null ? `<text class="rp-clue" x="${x + size / 2}" y="${y + size * .64}">${clue}</text>`
+            : value ? `<text class="rp-value" x="${x + size / 2}" y="${y + size * .64}">${value}</text>`
+                : (notes[cell] ?? []).map((note, i) => `<text class="rp-note" x="${x + 14 + i % 3 * 14}" y="${y + 18 + Math.floor(i / 3) * 14}">${note}</text>`).join("");
+        const selected = options.selected === cell;
+        const piece = options.pieces === "tiles" ? `<rect class="rp-piece" x="${x + 9}" y="${y + 9}" width="${size - 18}" height="${size - 18}" rx="6"/>` : "";
+        const error = options.errors?.includes(cell) ?? false;
+        return `<rect x="${x}" y="${y}" width="${size}" height="${size}" fill="${selected ? "#dce9c9" : surface}" stroke="${error ? "#c34b3e" : line}" stroke-width="1"/>${piece}${text}<title>${Math.floor(cell / board.width) + 1}, ${cell % board.width + 1}: ${clue !== null ? `clue ${clue}` : value ? `entry ${value}` : `room of ${sizes[room]}`}</title>`;
+    }).join("");
+    const walls = board.rooms.flatMap((room, cell) => {
+        const x = cell % board.width, y = Math.floor(cell / board.width), edges = [];
+        if (x + 1 < board.width && board.rooms[cell + 1] !== room)
+            edges.push(`<path d="M${(x + 1) * size} ${y * size}v${size}"/>`);
+        if (y + 1 < board.height && board.rooms[cell + board.width] !== room)
+            edges.push(`<path d="M${x * size} ${(y + 1) * size}h${size}"/>`);
+        return edges;
+    }).join("");
+    return `<svg xmlns="http://www.w3.org/2000/svg" role="img" aria-label="Ripple Effect ${board.width} by ${board.height}" viewBox="-${margin} -${margin} ${width + margin * 2} ${height + margin * 2}" style="color:${ink}"><style>.rp-clue,.rp-value{font:500 27px system-ui;text-anchor:middle;fill:${ink}}.rp-clue{font-weight:700}.rp-note{font:12px system-ui;text-anchor:middle;fill:${ink}}.rp-piece{fill:none;stroke:${line};stroke-width:2}</style>${cells}<g fill="none" stroke="${ink}" stroke-width="3">${walls}</g></svg>`;
+}

package/dist/rippleGame.d.ts

@@ -0,0 +1,13 @@
+import type { RippleBoard, RippleGame } from "./ripple.types.ts";
+export declare function newRipple(board: RippleBoard): RippleGame;
+export declare function setRippleValue(game: RippleGame, cell: number, value: number): RippleGame;
+export declare function toggleRippleNote(game: RippleGame, cell: number, value: number): RippleGame;
+export declare function undoRipple(game: RippleGame): RippleGame;
+export declare function rippleFinished(game: RippleGame): boolean;
+/** Offers a cell only when the current public entries leave one proved completion. */
+export declare function hintRipple(game: RippleGame): {
+    cell: number;
+    value: number;
+} | null;
+export declare function encodeRipple(game: RippleGame): string;
+export declare function decodeRipple(code: string): RippleGame | null;

package/dist/rippleGame.js

@@ -0,0 +1,85 @@
+import { isRippleBoard, checkRipple, rippleRoomSizes } from "./rippleBoard.js";
+import { solveRipple } from "./rippleSolve.js";
+export function newRipple(board) {
+    if (!isRippleBoard(board))
+        throw new RangeError("Invalid Ripple Effect board");
+    return { board: { width: board.width, height: board.height, rooms: [...board.rooms], clues: [...board.clues] },
+        values: board.clues.map(clue => clue ?? 0), notes: board.rooms.map(() => []), history: [], helped: false };
+}
+export function setRippleValue(game, cell, value) {
+    if (!Number.isInteger(cell) || cell < 0 || cell >= game.values.length || game.board.clues[cell] !== null
+        || !Number.isInteger(value) || value < 0 || value > rippleRoomSizes(game.board)[game.board.rooms[cell]])
+        return game;
+    if (game.values[cell] === value)
+        return game;
+    const values = [...game.values];
+    values[cell] = value;
+    const notes = game.notes.map((list, index) => index === cell ? [] : [...list]);
+    return { ...game, values, notes, history: [...game.history, snapshot(game)] };
+}
+export function toggleRippleNote(game, cell, value) {
+    if (!Number.isInteger(cell) || cell < 0 || cell >= game.values.length || game.board.clues[cell] !== null || game.values[cell] !== 0
+        || !Number.isInteger(value) || value < 1 || value > rippleRoomSizes(game.board)[game.board.rooms[cell]])
+        return game;
+    const notes = game.notes.map(list => [...list]);
+    const current = new Set(notes[cell]);
+    if (current.has(value))
+        current.delete(value);
+    else
+        current.add(value);
+    notes[cell] = [...current].sort((a, b) => a - b);
+    return { ...game, notes, history: [...game.history, snapshot(game)] };
+}
+export function undoRipple(game) {
+    const previous = game.history.at(-1);
+    return previous ? { ...game, values: [...previous.values], notes: previous.notes.map(list => [...list]), history: game.history.slice(0, -1) } : game;
+}
+export function rippleFinished(game) { return checkRipple(game.board, game.values).ok; }
+/** Offers a cell only when the current public entries leave one proved completion. */
+export function hintRipple(game) {
+    const clues = game.values.map((value, cell) => game.board.clues[cell] ?? (value || null));
+    const solved = solveRipple({ ...game.board, clues });
+    if (!solved.complete || solved.count !== 1 || !solved.solution)
+        return null;
+    const cell = solved.solution.findIndex((value, index) => game.values[index] === 0 && value > 0);
+    return cell < 0 ? null : { cell, value: solved.solution[cell] };
+}
+export function encodeRipple(game) {
+    return JSON.stringify({ version: 1, board: game.board, values: game.values, notes: game.notes, helped: game.helped });
+}
+export function decodeRipple(code) {
+    try {
+        if (code.length > 40000)
+            return null;
+        const data = JSON.parse(code);
+        if (data.version !== 1 || !isRippleBoard(data.board) || !Array.isArray(data.values)
+            || data.values.length !== data.board.rooms.length || !Array.isArray(data.notes)
+            || data.notes.length !== data.board.rooms.length || typeof data.helped !== "boolean")
+            return null;
+        let game = newRipple(data.board);
+        for (let cell = 0; cell < data.values.length; cell += 1) {
+            const value = data.values[cell];
+            if (game.board.clues[cell] !== null && value !== game.board.clues[cell])
+                return null;
+            if (game.board.clues[cell] === null && value) {
+                const next = setRippleValue(game, cell, value);
+                if (next === game)
+                    return null;
+                game = next;
+            }
+            const list = data.notes[cell];
+            if (!Array.isArray(list) || new Set(list).size !== list.length
+                || list.some(note => !Number.isInteger(note) || note < 1 || note > rippleRoomSizes(game.board)[game.board.rooms[cell]]))
+                return null;
+            for (const note of list)
+                game = toggleRippleNote(game, cell, note);
+        }
+        return { ...game, history: [], helped: data.helped };
+    }
+    catch {
+        return null;
+    }
+}
+function snapshot(game) {
+    return { values: [...game.values], notes: game.notes.map(list => [...list]) };
+}

package/dist/rippleGenerate.d.ts

@@ -0,0 +1,3 @@
+import type { RipplePuzzle } from "./ripple.types.ts";
+/** Builds a seeded block-room family and accepts it only after a bounded uniqueness proof. */
+export declare function generateRipple(width?: number, height?: number, seed?: number): RipplePuzzle;

package/dist/rippleGenerate.js

@@ -0,0 +1,57 @@
+import { RIPPLE_MAX_ATTEMPTS } from "./ripple.constants.js";
+import { checkRipple } from "./rippleBoard.js";
+import { solveRipple } from "./rippleSolve.js";
+import { isKazuSeed, seededRandom } from "./random.js";
+/** Builds a seeded block-room family and accepts it only after a bounded uniqueness proof. */
+export function generateRipple(width = 9, height = width, seed = 1) {
+    if (width !== 9 || height !== 9 || !isKazuSeed(seed)) {
+        throw new RangeError("Ripple Effect currently supports original 9×9 boards and valid integer seeds.");
+    }
+    const random = seededRandom(seed);
+    for (let attempt = 0; attempt < RIPPLE_MAX_ATTEMPTS; attempt += 1) {
+        const rooms = Array.from({ length: 81 }, (_, cell) => Math.floor(Math.floor(cell / 9) / 3) * 3 + Math.floor(cell % 9 / 3));
+        const solution = blockSolution(random);
+        const clues = [...solution];
+        const order = Array.from({ length: clues.length }, (_, cell) => cell);
+        order.splice(0, order.length, ...shuffled(order, random));
+        const target = 42 + Math.floor(random() * 7);
+        let clueCount = clues.length;
+        for (const cell of order) {
+            if (clueCount <= target)
+                break;
+            const previous = clues[cell];
+            clues[cell] = null;
+            const board = { width, height, rooms, clues };
+            const proof = solveRipple(board, { limit: 2 });
+            if (!proof.complete || proof.count !== 1) {
+                clues[cell] = previous;
+                continue;
+            }
+            clueCount -= 1;
+        }
+        if (clueCount > 58 || clueCount >= clues.length)
+            continue;
+        const board = { width, height, rooms, clues };
+        const proof = solveRipple(board, { limit: 2 });
+        if (proof.complete && proof.count === 1 && proof.solution && checkRipple(board, proof.solution).ok) {
+            return { ...board, seed, solution: proof.solution };
+        }
+    }
+    throw new Error("No uniquely solvable Ripple Effect board was proved within the generation budget.");
+}
+function blockSolution(random) {
+    const bands = shuffled([0, 1, 2], random);
+    const stacks = shuffled([0, 1, 2], random);
+    const rows = bands.flatMap(band => shuffled([0, 1, 2], random).map(row => band * 3 + row));
+    const columns = stacks.flatMap(stack => shuffled([0, 1, 2], random).map(column => stack * 3 + column));
+    const digits = shuffled([1, 2, 3, 4, 5, 6, 7, 8, 9], random);
+    return rows.flatMap(row => columns.map(column => digits[(row * 3 + Math.floor(row / 3) + column) % 9]));
+}
+function shuffled(items, random) {
+    const result = [...items];
+    for (let i = result.length - 1; i > 0; i -= 1) {
+        const j = Math.floor(random() * (i + 1));
+        [result[i], result[j]] = [result[j], result[i]];
+    }
+    return result;
+}

package/dist/rippleMount.d.ts

@@ -0,0 +1,2 @@
+import type { RippleMount, RippleMountOptions } from "./ripplePlay.types.ts";
+export declare function mountRipple(host: HTMLElement, initial: RippleMountOptions): RippleMount;

package/dist/rippleMount.js

@@ -0,0 +1,179 @@
+import { KAZU_STYLE } from "./style.js";
+import { checkRipple, progressRipple, rippleRoomSizes } from "./rippleBoard.js";
+import { decodeRipple, encodeRipple, hintRipple, newRipple, rippleFinished, setRippleValue, toggleRippleNote, undoRipple } from "./rippleGame.js";
+import { RIPPLE_PLAY_STYLE } from "./rippleStyle.js";
+import { rippleWords } from "./rippleStrings.js";
+export function mountRipple(host, initial) {
+    const doc = host.ownerDocument;
+    let options = { ...initial };
+    let game = initial.progress ? decodeRipple(initial.progress) : null;
+    game ?? (game = newRipple(initial.board));
+    let selected = game.values.findIndex((value, cell) => game.board.clues[cell] === null);
+    if (selected < 0)
+        selected = 0;
+    let pencil = false, errors = [], message = "", dead = false;
+    const root = doc.createElement("section");
+    root.className = "rp-root";
+    const style = doc.createElement("style");
+    style.textContent = KAZU_STYLE.replace(/\.kazu/g, ".rp-palette") + RIPPLE_PLAY_STYLE;
+    const board = doc.createElement("div");
+    board.className = "rp-board";
+    board.setAttribute("role", "grid");
+    const status = doc.createElement("p");
+    status.className = "rp-status";
+    status.setAttribute("role", "status");
+    const help = doc.createElement("p");
+    help.className = "rp-help";
+    const controls = doc.createElement("div");
+    controls.className = "rp-controls";
+    const numpad = doc.createElement("div");
+    numpad.className = "rp-numpad";
+    numpad.setAttribute("aria-label", "Numbers");
+    root.append(style, board, status, help, numpad, controls);
+    host.append(root);
+    const words = () => rippleWords(options.language);
+    const copy = () => ({ ...game, board: { ...game.board, rooms: [...game.board.rooms], clues: [...game.board.clues] }, values: [...game.values], notes: game.notes.map(list => [...list]), history: game.history.map(turn => ({ values: [...turn.values], notes: turn.notes.map(list => [...list]) })) });
+    const changed = () => {
+        errors = [];
+        message = "";
+        render();
+        const snapshot = copy();
+        options.onChange?.(snapshot);
+        root.dispatchEvent(new CustomEvent("ripple-change", { detail: snapshot, bubbles: true }));
+        if (rippleFinished(game)) {
+            options.onFinish?.(snapshot);
+            root.dispatchEvent(new CustomEvent("ripple-finish", { detail: snapshot, bubbles: true }));
+        }
+    };
+    const enter = (value) => {
+        if (game.board.clues[selected] !== null)
+            return;
+        game = pencil ? toggleRippleNote(game, selected, value) : setRippleValue(game, selected, value);
+        changed();
+    };
+    const button = (label, action, disabled = false) => {
+        const item = doc.createElement("button");
+        item.type = "button";
+        item.className = "rp-tool";
+        item.textContent = label;
+        item.disabled = disabled;
+        item.onclick = action;
+        controls.append(item);
+        return item;
+    };
+    const render = () => {
+        if (dead)
+            return;
+        const focused = board.contains(doc.activeElement);
+        const w = words(), current = game.board, sizes = rippleRoomSizes(current), validation = progressRipple(current, game.values);
+        root.dataset.material = options.material ?? "ivory";
+        root.dataset.pieces = options.pieces ?? "ink";
+        root.classList.toggle("rp-tiles", options.pieces === "tiles");
+        root.style.setProperty("--rp-width", String(current.width));
+        board.setAttribute("aria-label", w.title);
+        board.replaceChildren();
+        for (let cell = 0; cell < current.rooms.length; cell += 1) {
+            const x = cell % current.width, y = Math.floor(cell / current.width), room = current.rooms[cell];
+            const control = doc.createElement("button");
+            control.type = "button";
+            control.className = "rp-cell";
+            if (x + 1 < current.width && current.rooms[cell + 1] !== room)
+                control.classList.add("rp-room-right");
+            if (y + 1 < current.height && current.rooms[cell + current.width] !== room)
+                control.classList.add("rp-room-bottom");
+            const clue = current.clues[cell] !== null, value = game.values[cell];
+            control.dataset.cell = String(cell);
+            control.dataset.clue = String(clue);
+            control.dataset.error = String(errors.includes(cell));
+            control.dataset.selected = String(cell === selected);
+            control.setAttribute("aria-disabled", String(clue));
+            control.tabIndex = cell === selected ? 0 : -1;
+            control.setAttribute("role", "gridcell");
+            control.setAttribute("aria-label", `${w.cell.replace("{row}", String(y + 1)).replace("{column}", String(x + 1))}, ${clue ? w.clue.replace("{value}", String(current.clues[cell])) : value ? w.entry.replace("{value}", String(value)) : game.notes[cell].length ? w.note.replace("{values}", game.notes[cell].join(", ")) : w.empty}`);
+            if (clue)
+                control.textContent = String(current.clues[cell]);
+            else if (value)
+                control.textContent = String(value);
+            else if (game.notes[cell].length) {
+                const mini = doc.createElement("span");
+                mini.className = "rp-notes";
+                for (let digit = 1; digit <= sizes[room]; digit += 1) {
+                    const span = doc.createElement("span");
+                    span.textContent = game.notes[cell].includes(digit) ? String(digit) : "";
+                    mini.append(span);
+                }
+                control.append(mini);
+            }
+            control.onclick = () => { selected = cell; render(); };
+            control.onkeydown = event => {
+                if (["ArrowLeft", "ArrowRight", "ArrowUp", "ArrowDown"].includes(event.key)) {
+                    event.preventDefault();
+                    move(cell, event.key);
+                }
+                else if (/^[1-9]$/.test(event.key)) {
+                    event.preventDefault();
+                    enter(Number(event.key));
+                }
+                else if (event.key === "Backspace" || event.key === "Delete") {
+                    event.preventDefault();
+                    enter(0);
+                }
+                else if (event.key.toLowerCase() === "p") {
+                    event.preventDefault();
+                    pencil = !pencil;
+                    render();
+                }
+            };
+            board.append(control);
+        }
+        if (focused)
+            board.querySelector(`[data-cell="${selected}"]`)?.focus({ preventScroll: true });
+        numpad.replaceChildren();
+        for (let digit = 1; digit <= Math.max(...sizes); digit += 1) {
+            const key = doc.createElement("button");
+            key.type = "button";
+            key.className = "rp-key";
+            key.textContent = String(digit);
+            key.disabled = digit > sizes[current.rooms[selected]];
+            key.onclick = () => enter(digit);
+            numpad.append(key);
+        }
+        status.textContent = rippleFinished(game) ? (game.helped ? `${w.won} · ${w.hint}` : w.won) : message || (validation.ok ? w.won : w.checked);
+        help.textContent = w.help;
+        controls.replaceChildren();
+        button(w.undo, () => { game = undoRipple(game); changed(); }, !game.history.length);
+        button(w.check, () => { errors = [...checkRipple(current, game.values).errors]; message = checkRipple(current, game.values).ok ? w.won : w.wrong; render(); });
+        button(w.hint, () => { const hint = hintRipple(game); if (!hint) {
+            message = w.noHint;
+            render();
+            return;
+        } game = { ...setRippleValue(game, hint.cell, hint.value), helped: true }; selected = hint.cell; changed(); message = w.hintWhy; render(); });
+        button(pencil ? `${w.pencil} ✓` : w.pencil, () => { pencil = !pencil; render(); });
+        button(w.restart, restart);
+        button(w.view, expand);
+    };
+    function move(cell, direction) {
+        const dx = direction === "ArrowLeft" ? -1 : direction === "ArrowRight" ? 1 : 0;
+        const dy = direction === "ArrowUp" ? -1 : direction === "ArrowDown" ? 1 : 0;
+        const x = cell % game.board.width, y = Math.floor(cell / game.board.width);
+        const nx = Math.min(game.board.width - 1, Math.max(0, x + dx)), ny = Math.min(game.board.height - 1, Math.max(0, y + dy));
+        selected = ny * game.board.width + nx;
+        render();
+        board.querySelector(`[data-cell="${selected}"]`)?.focus();
+    }
+    function restart() { game = newRipple(game.board); selected = game.values.findIndex((value, cell) => game.board.clues[cell] === null); changed(); }
+    function expand() {
+        const dialog = doc.createElement("dialog"), close = doc.createElement("button");
+        dialog.className = "rp-dialog";
+        close.type = "button";
+        close.className = "rp-tool rp-close";
+        close.textContent = words().close;
+        close.onclick = () => dialog.close();
+        dialog.append(close, root);
+        host.append(dialog);
+        dialog.onclose = () => { host.append(root); dialog.remove(); };
+        dialog.showModal();
+    }
+    render();
+    return { game: copy, progress: () => encodeRipple(game), restart, set: (next) => { options = { ...options, ...next }; render(); }, destroy: () => { dead = true; root.remove(); root.closest("dialog")?.remove(); } };
+}

package/dist/ripplePlay.types.d.ts

@@ -0,0 +1,23 @@
+import type { RippleBoard, RippleGame, RippleLanguage, RippleMaterial, RipplePieces } from "./ripple.types.ts";
+export type RippleDrawOptions = {
+    values?: readonly number[];
+    notes?: readonly (readonly number[])[];
+    errors?: readonly number[];
+    selected?: number | null;
+    material?: RippleMaterial;
+    pieces?: RipplePieces;
+    language?: RippleLanguage;
+};
+export type RippleMountOptions = RippleDrawOptions & {
+    board: RippleBoard;
+    progress?: string;
+    onChange?: (game: RippleGame) => void;
+    onFinish?: (game: RippleGame) => void;
+};
+export type RippleMount = {
+    game: () => RippleGame;
+    progress: () => string;
+    set: (options: RippleDrawOptions) => void;
+    restart: () => void;
+    destroy: () => void;
+};

package/dist/ripplePlay.types.js

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

package/dist/rippleSolve.d.ts

@@ -0,0 +1,6 @@
+import type { RippleBoard, RippleSolve } from "./ripple.types.ts";
+/** Counts rule-valid fillings within an explicit node budget. */
+export declare function solveRipple(board: RippleBoard, options?: {
+    limit?: number;
+    nodes?: number;
+}): RippleSolve;

package/dist/rippleSolve.js

@@ -0,0 +1,83 @@
+import { RIPPLE_MAX_NODES } from "./ripple.constants.js";
+import { isRippleBoard, rippleRoomSizes } from "./rippleBoard.js";
+/** Counts rule-valid fillings within an explicit node budget. */
+export function solveRipple(board, options = {}) {
+    if (!isRippleBoard(board))
+        throw new RangeError("Invalid Ripple Effect board");
+    const limit = options.limit ?? 2, budget = options.nodes ?? RIPPLE_MAX_NODES;
+    if (!Number.isInteger(limit) || limit < 1 || !Number.isInteger(budget) || budget < 1)
+        throw new RangeError("Invalid search bounds");
+    const sizes = rippleRoomSizes(board);
+    const values = board.clues.map(clue => clue ?? 0);
+    const roomUsed = sizes.map(() => new Set());
+    let count = 0, nodes = 0, complete = true, solution = null;
+    for (let cell = 0; cell < values.length; cell += 1) {
+        const value = values[cell];
+        if (!value)
+            continue;
+        const room = board.rooms[cell];
+        if (roomUsed[room].has(value) || conflicts(cell, value, values, board)) {
+            return { count: 0, solution: null, complete: true, nodes: 0 };
+        }
+        roomUsed[room].add(value);
+    }
+    const visit = () => {
+        if (count >= limit || !complete) {
+            complete = false;
+            return;
+        }
+        if (++nodes > budget) {
+            complete = false;
+            return;
+        }
+        let bestCell = -1, bestValues = [];
+        for (let cell = 0; cell < values.length; cell += 1) {
+            if (values[cell])
+                continue;
+            const room = board.rooms[cell];
+            const candidates = [];
+            for (let value = 1; value <= sizes[room]; value += 1) {
+                if (!roomUsed[room].has(value) && !conflicts(cell, value, values, board))
+                    candidates.push(value);
+            }
+            if (!candidates.length)
+                return;
+            if (bestCell < 0 || candidates.length < bestValues.length) {
+                bestCell = cell;
+                bestValues = candidates;
+                if (candidates.length === 1)
+                    break;
+            }
+        }
+        if (bestCell < 0) {
+            count += 1;
+            solution ?? (solution = [...values]);
+            return;
+        }
+        const room = board.rooms[bestCell];
+        for (const value of bestValues) {
+            values[bestCell] = value;
+            roomUsed[room].add(value);
+            visit();
+            roomUsed[room].delete(value);
+            values[bestCell] = 0;
+            if (!complete || count >= limit) {
+                complete = false;
+                return;
+            }
+        }
+    };
+    visit();
+    return { count, solution, complete, nodes };
+}
+function conflicts(cell, value, values, board) {
+    const x = cell % board.width, y = Math.floor(cell / board.width);
+    for (let other = 0; other < values.length; other += 1) {
+        if (values[other] !== value || other === cell)
+            continue;
+        const ox = other % board.width, oy = Math.floor(other / board.width);
+        if ((oy === y && Math.abs(ox - x) <= value) || (ox === x && Math.abs(oy - y) <= value))
+            return true;
+    }
+    return false;
+}