pixi-reels 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # pixi-reels
 
+## 1.1.0
+
+### Minor Changes
+
+- [#158](https://github.com/schmooky/pixi-reels/pull/158) [`22f2b33`](https://github.com/schmooky/pixi-reels/commit/22f2b339a8b2f285a08678c080aaa854e988fde0) Thanks [@igaming-bulochka](https://github.com/igaming-bulochka)! - Add: `BoardGrid` — the generic "board of reels" primitive is now a public export. A grid of cells that each spin independently (`cells`, `spinCells`, `symbolAt`/`reelAt`, `cellBounds`/`cellCenter`, `setProfile`, `place`), with no game rules of its own. `HoldAndWinBoard` is one opinionated board built on it; build your own the same way. `spinCells`' per-cell `onLanded` callback may be async — return a promise and `spinCells` resolves only once every cell has landed and its after-land work has finished.
+
+- [#158](https://github.com/schmooky/pixi-reels/pull/158) [`22f2b33`](https://github.com/schmooky/pixi-reels/commit/22f2b339a8b2f285a08678c080aaa854e988fde0) Thanks [@igaming-bulochka](https://github.com/igaming-bulochka)! - Add: Hold & Win board. `HoldAndWinBuilder` builds a `HoldAndWinBoard` — a grid of independently spinning 1×1 cells with the full respin / lock / collect lifecycle (`enter`, `respin`, `release`, `setSymbolAt`, `skip`, `reset`), typed events (`coin:locked`, `board:full`, `feature:end`, …), per-cell geometry (`cellBounds`/`cellCenter`) and live symbol access (`symbolAt`/`reelAt`). Coins are opaque `{ cell, id, data }`, so value, multipliers, collectors and flights stay game-layer. Also exports `EmptySymbol` (a render-nothing symbol), plus `cellKey` and the `HwEffect` type so you can fork `HoldAndWinBoard` + `HoldAndWinState` and keep every import on public API.
+
+### Patch Changes
+
+- [#158](https://github.com/schmooky/pixi-reels/pull/158) [`22f2b33`](https://github.com/schmooky/pixi-reels/commit/22f2b339a8b2f285a08678c080aaa854e988fde0) Thanks [@igaming-bulochka](https://github.com/igaming-bulochka)! - Fix: harden and complete the Hold & Win board public surface. `HoldAndWinState` (the pure reducer) is now exported from the barrel, so the documented "fork `HoldAndWinBoard` + `HoldAndWinState` and keep every import on public API" path actually resolves. `beginWave`/`respin` now throws on a duplicate hit targeting the same cell in one wave instead of silently dropping the first coin (a malformed result fails loud, matching `enter`'s duplicate-seed guard). A failed `playWin()` reaction to `coin:locked` is now logged via `console.warn` instead of being swallowed silently, and `setSymbolAt`'s JSDoc documents that it must not be called mid-wave.
+
+- [#158](https://github.com/schmooky/pixi-reels/pull/158) [`22f2b33`](https://github.com/schmooky/pixi-reels/commit/22f2b339a8b2f285a08678c080aaa854e988fde0) Thanks [@igaming-bulochka](https://github.com/igaming-bulochka)! - Fix: harden `HoldAndWinBoard` recovery and mid-wave misuse. If `respin()` throws between starting and closing a wave — most plausibly a game-layer `respin:start` / `cell:landed` / `coin:locked` listener throwing — it now restores the reducer's phase and slams any still-spinning cells before rethrowing, so a failed wave no longer strands the board in `spinning` (where every later `respin()` threw "wave in flight") or leaves an orphaned reel (where the next `respin()` threw "already spinning"). The error still propagates to the caller. The reducer also ignores stray landings outside a wave, so a cell settling after a `reset()` or a recovered error can no longer re-lock a coin into a cleared ledger or flip a finished feature back to active. `release()` and `setSymbolAt()` still throw if called while a wave is in flight. `respin()` now returns a caller-owned `hits` array (a copy of the wave's landings) rather than a live reference into reducer state, so mutating the result can't reach back into the board.
+
+## 1.0.1
+
+### Patch Changes
+
+- [#150](https://github.com/schmooky/pixi-reels/pull/150) [`6a96d60`](https://github.com/schmooky/pixi-reels/commit/6a96d603cbc8b9f1b80176268850ad9157177c26) Thanks [@igaming-bulochka](https://github.com/igaming-bulochka)! - Fix: buffer-anchored big symbols no longer render empty, and big-symbol blocks no longer jitter, when falling through a tumble cascade. `CascadePlacePhase` now preserves `bufferAbove` target cells, so a "tail-visible" block (anchor above the viewport) keeps its anchor through the animated place path instead of being overwritten with a random symbol and leaving its visible cell empty. The place and drop-in phases now animate each block anchor exactly once instead of once per occupied visible row — previously the duplicate drop tweens fought over the anchor's position (the jitter) and could land it a row off target.
+
 ## 1.0.0
 
 ### Major Changes

package/dist/board/BoardGrid.d.ts

@@ -0,0 +1,129 @@
+import { Container, Graphics, Ticker } from 'pixi.js';
+import { ReelSet } from '../core/ReelSet.js';
+import { ReelSymbol } from '../symbols/ReelSymbol.js';
+import { SymbolRegistry } from '../symbols/SymbolRegistry.js';
+import { SpeedProfile, SymbolData } from '../config/types.js';
+import { Disposable } from '../utils/Disposable.js';
+/** A cell coordinate in the grid. */
+export interface BoardCell {
+    col: number;
+    row: number;
+}
+/** A landing target: spin `cell` and stop it showing `id`. */
+export interface BoardSpinTarget {
+    cell: BoardCell;
+    id: string;
+}
+/** A speed profile, or a per-cell function of one (e.g. a stagger wave). */
+export type BoardProfile = SpeedProfile | ((cell: BoardCell) => SpeedProfile);
+export interface BoardGridOptions {
+    /** Grid dimensions. */
+    cols: number;
+    rows: number;
+    /** Cell edge length in pixels. */
+    cellSize: number;
+    /** Gap between cells. Default 4. */
+    gap?: number;
+    /** Id a cell shows when blank — also placed in the off-window buffers. Default `'empty'`. */
+    emptyId?: string;
+    /** Register symbol classes, exactly like `ReelSetBuilder.symbols`. Applied to every cell. */
+    symbols: (registry: SymbolRegistry) => void;
+    /** Strip weights during the spin. */
+    weights?: Record<string, number>;
+    /** Per-symbol engine overrides, exactly like `ReelSetBuilder.symbolData`. */
+    symbolData?: Record<string, Partial<SymbolData>>;
+    /** Injected RNG for the spin strips (deterministic demos / tests). */
+    rng?: () => number;
+    /** Drives every cell's reel — required. */
+    ticker: Ticker;
+    /** Per-cell background, drawn behind each reel. */
+    chrome?: (g: Graphics, size: number) => void;
+    /**
+     * Named speed profiles, each registered on every cell and selected by name
+     * via {@link BoardGrid.setProfile}. A value may be a flat profile or a
+     * per-cell function (for stagger waves). Defaults to a single `'default'`
+     * profile, which is the active one until you `setProfile` otherwise.
+     */
+    profiles?: Record<string, BoardProfile>;
+}
+/**
+ * A grid of cells that each spin **independently** — the generic "board of
+ * reels" primitive. Every cell is its own 1×1 {@link ReelSet}, so it inherits
+ * the engine's phases, speed modes and pooling rather than a parallel lighter
+ * reel.
+ *
+ * Deliberately mechanism-only: it knows nothing about coins, locks, respins,
+ * value or any game rule. It lays the grid out, hands back per-cell geometry
+ * and live symbol instances, places symbols instantly, and spins a
+ * **caller-chosen** set of cells to caller-chosen results. Build your own
+ * feature on top by owning the rules in your own code; {@link HoldAndWinBoard}
+ * is one such opinionated layer, built entirely on this public surface.
+ *
+ * ```ts
+ * const grid = new BoardGrid({
+ *   cols: 3, rows: 3, cellSize: 80,
+ *   symbols: (r) => r.register('prize', PrizeSymbol, {}),
+ *   weights: { prize: 1, empty: 4 },
+ *   ticker: app.ticker,
+ * });
+ * app.stage.addChild(grid.container);
+ *
+ * await grid.spinCells(
+ *   grid.cells().map((cell) => ({ cell, id: pick() })),  // you decide each result
+ *   (cell, id) => console.log('landed', cell, id),       // react as each settles
+ * );
+ * ```
+ */
+export declare class BoardGrid implements Disposable {
+    readonly container: Container;
+    readonly cols: number;
+    readonly rows: number;
+    readonly cellSize: number;
+    readonly gap: number;
+    readonly emptyId: string;
+    private readonly _reels;
+    private readonly _cells;
+    private _destroyed;
+    constructor(opts: BoardGridOptions);
+    /** Every cell coordinate, row-major. */
+    cells(): BoardCell[];
+    /** Board-local bounds of a cell. `container.toGlobal` for stage space. */
+    cellBounds(cell: BoardCell): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    /** Board-local center of a cell — flight / trail start and end points. */
+    cellCenter(cell: BoardCell): {
+        x: number;
+        y: number;
+    };
+    /** Live symbol instance currently shown in a cell. */
+    symbolAt(cell: BoardCell): ReelSymbol;
+    /** The cell's underlying 1×1 ReelSet, for driving one cell directly. */
+    reelAt(cell: BoardCell): ReelSet;
+    /** Select a registered speed profile by name for one cell. */
+    setProfile(cell: BoardCell, name: string): void;
+    /** Place a symbol instantly (no spin), with blank off-window buffers. */
+    place(cell: BoardCell, id: string): void;
+    /**
+     * Spin each target cell and stop it showing its `id`; `onLanded` fires per
+     * cell as it settles, in stagger order. The caller selects which cells spin
+     * and to what — this layer applies no lock/free policy of its own. Set
+     * profiles via {@link setProfile} first.
+     *
+     * `onLanded` may be **async**: if it returns a promise, that cell's task
+     * awaits it, so the returned promise resolves only once every cell has landed
+     * *and* its after-land work has finished. Cells still run concurrently, so an
+     * early cell's reveal overlaps with later cells still spinning.
+     */
+    spinCells(targets: BoardSpinTarget[], onLanded?: (cell: BoardCell, id: string) => void | Promise<void>): Promise<void>;
+    /** Slam every in-flight cell to its landed position. Returns the count. */
+    skipSpinning(): number;
+    get isDestroyed(): boolean;
+    destroy(): void;
+    private _origin;
+    private _reel;
+}
+//# sourceMappingURL=BoardGrid.d.ts.map

package/dist/board/BoardGrid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BoardGrid.d.ts","sourceRoot":"","sources":["../../src/board/BoardGrid.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC9C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAEtC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAElD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAGnE,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEzD,qCAAqC;AACrC,MAAM,WAAW,SAAS;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;CACb;AAED,8DAA8D;AAC9D,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,SAAS,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,4EAA4E;AAC5E,MAAM,MAAM,YAAY,GAAG,YAAY,GAAG,CAAC,CAAC,IAAI,EAAE,SAAS,KAAK,YAAY,CAAC,CAAC;AAE9E,MAAM,WAAW,gBAAgB;IAC/B,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,oCAAoC;IACpC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,6FAA6F;IAC7F,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6FAA6F;IAC7F,OAAO,EAAE,CAAC,QAAQ,EAAE,cAAc,KAAK,IAAI,CAAC;IAC5C,qCAAqC;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,6EAA6E;IAC7E,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC,CAAC;IACjD,sEAAsE;IACtE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,MAAM,CAAC,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7C;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;CACzC;AAKD;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,qBAAa,SAAU,YAAW,UAAU;IAC1C,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA8B;IACrD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAC1C,OAAO,CAAC,UAAU,CAAS;gBAEf,IAAI,EAAE,gBAAgB;IA+DlC,wCAAwC;IACxC,KAAK,IAAI,SAAS,EAAE;IAIpB,0EAA0E;IAC1E,UAAU,CAAC,IAAI,EAAE,SAAS,GAAG;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE;IAKpF,0EAA0E;IAC1E,UAAU,CAAC,IAAI,EAAE,SAAS,GAAG;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE;IAKrD,sDAAsD;IACtD,QAAQ,CAAC,IAAI,EAAE,SAAS,GAAG,UAAU;IAIrC,wEAAwE;IACxE,MAAM,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO;IAIhC,8DAA8D;IAC9D,UAAU,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAI/C,yEAAyE;IACzE,KAAK,CAAC,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,GAAG,IAAI;IASxC;;;;;;;;;;OAUG;IACG,SAAS,CACb,OAAO,EAAE,eAAe,EAAE,EAC1B,QAAQ,GAAE,CAAC,IAAI,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAY,GACzE,OAAO,CAAC,IAAI,CAAC;IAehB,2EAA2E;IAC3E,YAAY,IAAI,MAAM;IAetB,IAAI,WAAW,IAAI,OAAO,CAEzB;IAED,OAAO,IAAI,IAAI;IASf,OAAO,CAAC,OAAO;IAOf,OAAO,CAAC,KAAK;CAOd"}

package/dist/board/HoldAndWinBoard.d.ts

@@ -0,0 +1,138 @@
+import { Container, Graphics, Ticker } from 'pixi.js';
+import { EventEmitter } from '../events/EventEmitter.js';
+import { ReelSet } from '../core/ReelSet.js';
+import { ReelSymbol } from '../symbols/ReelSymbol.js';
+import { SymbolRegistry } from '../symbols/SymbolRegistry.js';
+import { SpeedProfile, SymbolData } from '../config/types.js';
+import { Disposable } from '../utils/Disposable.js';
+import { HwPhase } from './HoldAndWinState.js';
+import { HoldAndWinBoardEvents, HwCell, HwCoin, HwRespinResult } from './HwTypes.js';
+/** Internal config produced by {@link HoldAndWinBuilder.build}. */
+export interface HoldAndWinBoardConfig<TData> {
+    cols: number;
+    rows: number;
+    cell: number;
+    gap: number;
+    emptyId: string;
+    respins: number;
+    configurator: (registry: SymbolRegistry) => void;
+    weights: Record<string, number> | null;
+    symbolData: Record<string, Partial<SymbolData>> | null;
+    baseProfile: SpeedProfile;
+    stagger: (col: number, row: number) => number;
+    anticipateWhen: ((state: {
+        locked: number;
+        capacity: number;
+        respinsLeft: number;
+    }) => boolean) | null;
+    chrome: ((g: Graphics, size: number) => void) | null;
+    ticker: Ticker;
+    rng: (() => number) | null;
+}
+/**
+ * A Hold & Win board: a grid of independently spinning cells plus the round
+ * choreography every H&W game repeats — spin the free cells, lock the hits,
+ * reset-or-decrement the respin counter, detect the full board.
+ *
+ * It composes two collaborators: a `BoardGrid` (the generic "board of reels"
+ * mechanism — geometry, instances, spinning) and a `HoldAndWinState` (the pure
+ * single-source reducer — ledger, counter, phase). The board is the
+ * mediator: it drives the reels, reports each landing to the reducer, and
+ * replays the reducer's decided effects onto {@link events}.
+ *
+ * It deliberately owns nothing about *value*. Coins are opaque `{ cell, id, data }`
+ * — `id` picks the registered art, `data` is the game layer's to read and mutate.
+ * Adders, doublers, collectors and flights are game design, expressed through
+ * three openings rather than board features: {@link events}, {@link symbolAt}
+ * (the live `ReelSymbol` instance) and {@link cellBounds}/{@link cellCenter}
+ * (pixel geometry for flights).
+ *
+ * ```ts
+ * const board = new HoldAndWinBuilder<{ value: number }>()
+ *   .grid(5, 3).cellSize(72, { gap: 4 })
+ *   .symbols((r) => r.register('coin', CoinSymbol, COIN_TRIGGER))
+ *   .weights({ coin: 1, empty: 3 }).respins(3).ticker(app.ticker)
+ *   .build();
+ *
+ * board.events.on('coin:locked', ({ coin }) => hud.add(coin.data.value));
+ * board.enter(triggerCoins);
+ * while (true) {
+ *   const round = await server.respin(board.lockedCoins);
+ *   const result = await board.respin(round.hits);
+ *   if (result.done) break;                  // game animates between rounds
+ * }
+ * ```
+ */
+export declare class HoldAndWinBoard<TData = unknown> implements Disposable {
+    readonly events: EventEmitter<HoldAndWinBoardEvents<TData>>;
+    readonly cols: number;
+    readonly rows: number;
+    private readonly _grid;
+    private readonly _state;
+    private readonly _emptyId;
+    private readonly _anticipateWhen;
+    constructor(cfg: HoldAndWinBoardConfig<TData>);
+    get container(): Container;
+    get capacity(): number;
+    get respinsLeft(): number;
+    get lockedCoins(): HwCoin<TData>[];
+    get isFull(): boolean;
+    get freeCells(): HwCell[];
+    /** Where the feature is right now: idle (no feature), active, or spinning. */
+    get phase(): HwPhase;
+    cellBounds(cell: HwCell): {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    cellCenter(cell: HwCell): {
+        x: number;
+        y: number;
+    };
+    /** Live symbol instance currently shown in a cell. */
+    symbolAt(cell: HwCell): ReelSymbol;
+    /** The cell's underlying 1×1 ReelSet, for driving one cell directly. */
+    reelAt(cell: HwCell): ReelSet;
+    /**
+     * Rewrite a **locked** cell's coin in place — coin → jackpot, mini → major,
+     * raise a tier — without disturbing any other cell. The ledger entry is
+     * rewritten so `lockedCoins` and totals stay correct. Throws on a free cell.
+     * Returns the new live symbol instance.
+     *
+     * Throws if called while a wave is in flight — `await respin()` first. To
+     * upgrade a coin in reaction to its own `coin:locked`, defer the swap until
+     * the awaited `respin()` resolves rather than swapping inside the listener.
+     */
+    setSymbolAt(cell: HwCell, id: string, data?: TData): ReelSymbol;
+    /** Activate the feature with the trigger coins. Seeds land locked, instantly. */
+    enter(seed: HwCoin<TData>[]): void;
+    /**
+     * Spin every free cell; `hits` land (and lock) their coins, all other spinning
+     * cells land empty. Resolves once the wave has landed and the counter is
+     * resolved. The game layer drives pacing between rounds.
+     */
+    respin(hits: HwCoin<TData>[]): Promise<HwRespinResult<TData>>;
+    /**
+     * Remove locked coins — the collect moment. Clears the cells (they become
+     * free again) and returns the released coins; the flight itself is game-layer
+     * animation, started from `cellCenter()` or the `coin:released` event.
+     */
+    release(cells: HwCell[]): HwCoin<TData>[];
+    /**
+     * Fast-forward whatever is spinning: every in-flight cell is slammed to its
+     * landed position, then `feature:skip` fires so the game layer can cut its own
+     * flights short. The normal landing → `coin:locked` → `feature:end` flow still
+     * resolves; this only removes the waiting. Returns the number of cells that
+     * were in flight.
+     */
+    skip(): number;
+    /** Clear the board back to idle. Fires `feature:reset` (not `coin:released`). */
+    reset(): void;
+    get isDestroyed(): boolean;
+    destroy(): void;
+    /** Emit each reducer-decided effect and fire the visual side effects. */
+    private _apply;
+    private _anticipating;
+}
+//# sourceMappingURL=HoldAndWinBoard.d.ts.map

package/dist/board/HoldAndWinBoard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HoldAndWinBoard.d.ts","sourceRoot":"","sources":["../../src/board/HoldAndWinBoard.ts"],"names":[],"mappings":"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"}

package/dist/board/HoldAndWinBuilder.d.ts

@@ -0,0 +1,79 @@
+import { Graphics, Ticker } from 'pixi.js';
+import { SpeedProfile, SymbolData } from '../config/types.js';
+import { SymbolRegistry } from '../symbols/SymbolRegistry.js';
+import { HoldAndWinBoard } from './HoldAndWinBoard.js';
+import { HwCellSizeOptions } from './HwTypes.js';
+/**
+ * Fluent builder for {@link HoldAndWinBoard}.
+ *
+ * A Hold & Win board is a W×H grid of cells that spin **independently** — the
+ * mechanic's atomic unit is the cell, the engine's is the column, so each cell
+ * is its own 1×1 ReelSet. This builder wires that grid plus the round
+ * choreography; everything value-shaped stays in the game layer (see
+ * {@link HoldAndWinBoard}).
+ *
+ * `TData` types the opaque payload carried on each coin's `data`.
+ */
+export declare class HoldAndWinBuilder<TData = unknown> {
+    private _cols;
+    private _rows;
+    private _cell;
+    private _gap;
+    private _emptyId;
+    private _respins;
+    private _configurator;
+    private _weights;
+    private _symbolData;
+    private _baseProfile;
+    private _stagger;
+    private _anticipateWhen;
+    private _chrome;
+    private _ticker;
+    private _rng;
+    grid(cols: number, rows: number): this;
+    cellSize(size: number, opts?: HwCellSizeOptions): this;
+    /**
+     * Register coin symbol classes, exactly like `ReelSetBuilder.symbols`. Applied
+     * to every cell. An {@link EmptySymbol} is auto-registered under {@link emptyId}
+     * unless the configurator registers one itself.
+     */
+    symbols(configurator: (registry: SymbolRegistry) => void): this;
+    /** Strip weights during the spin (how often coins flash past empties). */
+    weights(weights: Record<string, number>): this;
+    /** Symbol id a cell shows when it holds no coin. Default `'empty'`. */
+    emptyId(id: string): this;
+    /**
+     * Per-symbol engine overrides, exactly like `ReelSetBuilder.symbolData`. The
+     * headline use is `{ unmask: true }` for coins whose lock/reveal animations
+     * expand past the cell. Safe only for server-placed ids (weight 0): unmasked
+     * strip symbols mis-track vertically while the reel spins.
+     */
+    symbolData(overrides: Record<string, Partial<SymbolData>>): this;
+    /** Respins granted on enter and restored on every hit. Default 3. */
+    respins(count: number): this;
+    /** Base spin feel for every cell. Default: NORMAL with a 320ms floor. */
+    speedProfile(profile: SpeedProfile): this;
+    /**
+     * Extra milliseconds of spin per cell on top of the base minimum spin time.
+     * Default `(col + row) * 70` — the diagonal landing wave. Return 0 for
+     * simultaneous landings.
+     */
+    stagger(fn: (col: number, row: number) => number): this;
+    /**
+     * When the predicate returns true for a wave, **every** spinning cell uses a
+     * drawn-out tension profile — the "one cell left for Grand" moment. Evaluated
+     * once per wave for the whole board (not per cell), against the pre-wave state.
+     */
+    anticipateWhen(fn: (state: {
+        locked: number;
+        capacity: number;
+        respinsLeft: number;
+    }) => boolean): this;
+    /** Per-cell background, drawn behind each mini reel. */
+    cellChrome(draw: (g: Graphics, size: number) => void): this;
+    ticker(ticker: Ticker): this;
+    /** Injected RNG for the spin strips (deterministic demos / tests). */
+    rng(fn: () => number): this;
+    build(): HoldAndWinBoard<TData>;
+}
+//# sourceMappingURL=HoldAndWinBuilder.d.ts.map

package/dist/board/HoldAndWinBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HoldAndWinBuilder.d.ts","sourceRoot":"","sources":["../../src/board/HoldAndWinBuilder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,SAAS,CAAC;AAEhD,OAAO,KAAK,EAAE,YAAY,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACvD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEtD;;;;;;;;;;GAUG;AACH,qBAAa,iBAAiB,CAAC,KAAK,GAAG,OAAO;IAC5C,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,KAAK,CAAK;IAClB,OAAO,CAAC,KAAK,CAAM;IACnB,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,QAAQ,CAAW;IAC3B,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,aAAa,CAAqD;IAC1E,OAAO,CAAC,QAAQ,CAAuC;IACvD,OAAO,CAAC,WAAW,CAAoD;IACvE,OAAO,CAAC,YAAY,CAAkE;IACtF,OAAO,CAAC,QAAQ,CAAwE;IACxF,OAAO,CAAC,eAAe,CAEP;IAChB,OAAO,CAAC,OAAO,CAAsD;IACrE,OAAO,CAAC,OAAO,CAAuB;IACtC,OAAO,CAAC,IAAI,CAA+B;IAE3C,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI;IAMtC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,iBAAsB,GAAG,IAAI;IAM1D;;;;OAIG;IACH,OAAO,CAAC,YAAY,EAAE,CAAC,QAAQ,EAAE,cAAc,KAAK,IAAI,GAAG,IAAI;IAK/D,0EAA0E;IAC1E,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,IAAI;IAK9C,uEAAuE;IACvE,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAKzB;;;;;OAKG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,UAAU,CAAC,CAAC,GAAG,IAAI;IAKhE,qEAAqE;IACrE,OAAO,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAK5B,yEAAyE;IACzE,YAAY,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI;IAKzC;;;;OAIG;IACH,OAAO,CAAC,EAAE,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI;IAKvD;;;;OAIG;IACH,cAAc,CACZ,EAAE,EAAE,CAAC,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,GAChF,IAAI;IAKP,wDAAwD;IACxD,UAAU,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI;IAK3D,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAK5B,sEAAsE;IACtE,GAAG,CAAC,EAAE,EAAE,MAAM,MAAM,GAAG,IAAI;IAK3B,KAAK,IAAI,eAAe,CAAC,KAAK,CAAC;CAyBhC"}

package/dist/board/HoldAndWinState.d.ts

@@ -0,0 +1,89 @@
+import { HwCell, HwCoin, HwEffect } from './HwTypes.js';
+export type HwPhase = 'idle' | 'active' | 'spinning';
+/**
+ * The pure Hold & Win state machine — the single source of truth for board
+ * state, with **zero** PixiJS. It owns the locked-coin ledger, the respin
+ * counter, the round number and the feature {@link HwPhase}; every derived
+ * value (`freeCells`, `isFull`) is computed from the one ledger, never stored
+ * in parallel, so nothing can drift out of sync.
+ *
+ * It is a *reducer, not a cache*: {@link HoldAndWinBoard} drives the reels and
+ * reports each landing here; the methods mutate the ledger and **return the
+ * ordered list of {@link HwEffect}s to emit**, which the driver replays onto its
+ * event emitter (and uses to fire visual side effects like `playWin()`). Locks
+ * happen progressively as cells land in stagger order, so this is an
+ * *incremental* reducer ({@link beginWave} → N×{@link land} → {@link endWave}),
+ * not a one-shot `reduce(state, hits)`.
+ *
+ * Being PixiJS-free, it is fully unit-testable: assert the returned effect
+ * sequence for hit / miss / full / release / reset / error paths.
+ */
+export declare class HoldAndWinState<TData = unknown> {
+    private readonly _locked;
+    private readonly _cellSet;
+    private readonly _allCells;
+    private readonly _defaultRespins;
+    private _respinsLeft;
+    private _round;
+    private _phase;
+    private _waveLanded;
+    constructor(allCells: HwCell[], defaultRespins: number);
+    get phase(): HwPhase;
+    get respinsLeft(): number;
+    get round(): number;
+    get capacity(): number;
+    get isFull(): boolean;
+    lockedCoins(): HwCoin<TData>[];
+    freeCells(): HwCell[];
+    isLocked(cell: HwCell): boolean;
+    coinAt(cell: HwCell): HwCoin<TData> | undefined;
+    /** Seed the trigger coins and arm the counter. Idle → active. */
+    enter(seed: HwCoin<TData>[]): HwEffect<TData>[];
+    /**
+     * Open a wave: validate the hits, mark every free cell as spinning, bump the
+     * round. Returns the data the driver needs to emit `respin:start` and to land
+     * each cell. Active → spinning.
+     */
+    beginWave(hits: HwCoin<TData>[]): {
+        round: number;
+        spinning: HwCell[];
+        hitByKey: Map<string, HwCoin<TData>>;
+    };
+    /** Record one cell's landing. `coin` is null on a miss. */
+    land(cell: HwCell, coin: HwCoin<TData> | null): HwEffect<TData>[];
+    /** Close the wave: resolve the counter, detect full / feature end. */
+    endWave(): {
+        effects: HwEffect<TData>[];
+        landed: HwCoin<TData>[];
+    };
+    /**
+     * Abandon an in-flight wave after a driver error: restore the phase from
+     * `spinning` back to `active` so a thrown spin doesn't strand the board (every
+     * later `beginWave` would otherwise throw "wave in flight"). Cells that already
+     * landed stay locked; the caller decides whether to retry or `reset`.
+     */
+    abortWave(): void;
+    /** Remove locked coins — the collect moment. */
+    release(cells: HwCell[]): {
+        effects: HwEffect<TData>[];
+        released: HwCoin<TData>[];
+    };
+    /**
+     * Rewrite a **locked** cell's coin identity in place (coin → jackpot, mini →
+     * major). Throws on a free cell — placing a brand-new tracked coin out of a
+     * spin is `enter`/`respin`'s job; for purely decorative art on a free cell use
+     * the cell's reel directly.
+     */
+    swap(cell: HwCell, id: string, data: TData | undefined): void;
+    /** Hard clear back to idle. Fires `feature:reset`, never `coin:released`. */
+    reset(): HwEffect<TData>[];
+    private _setRespins;
+    /**
+     * Store a coin with a board-owned, frozen `cell` so the ledger key can never
+     * be corrupted by a game mutating the coin it was handed. `data` is left
+     * mutable by reference — that is the supported way to carry live value.
+     */
+    private _freeze;
+    private _assertInGrid;
+}
+//# sourceMappingURL=HoldAndWinState.d.ts.map

package/dist/board/HoldAndWinState.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HoldAndWinState.d.ts","sourceRoot":"","sources":["../../src/board/HoldAndWinState.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAkB,MAAM,cAAc,CAAC;AAG7E,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,QAAQ,GAAG,UAAU,CAAC;AAErD;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,eAAe,CAAC,KAAK,GAAG,OAAO;IAC1C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoC;IAC5D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAc;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAW;IACrC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IACzC,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,MAAM,CAAmB;IACjC,OAAO,CAAC,WAAW,CAAuB;gBAE9B,QAAQ,EAAE,MAAM,EAAE,EAAE,cAAc,EAAE,MAAM;IAQtD,IAAI,KAAK,IAAI,OAAO,CAEnB;IACD,IAAI,WAAW,IAAI,MAAM,CAExB;IACD,IAAI,KAAK,IAAI,MAAM,CAElB;IACD,IAAI,QAAQ,IAAI,MAAM,CAErB;IACD,IAAI,MAAM,IAAI,OAAO,CAEpB;IAED,WAAW,IAAI,MAAM,CAAC,KAAK,CAAC,EAAE;IAI9B,SAAS,IAAI,MAAM,EAAE;IAIrB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI/B,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,SAAS;IAM/C,iEAAiE;IACjE,KAAK,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,GAAG,QAAQ,CAAC,KAAK,CAAC,EAAE;IAuB/C;;;;OAIG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,GAAG;QAChC,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,MAAM,EAAE,CAAC;QACnB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;KACtC;IAuBD,2DAA2D;IAC3D,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,GAAG,QAAQ,CAAC,KAAK,CAAC,EAAE;IAoBjE,sEAAsE;IACtE,OAAO,IAAI;QAAE,OAAO,EAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAA;KAAE;IAiClE;;;;;OAKG;IACH,SAAS,IAAI,IAAI;IAMjB,gDAAgD;IAChD,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG;QAAE,OAAO,EAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC,KAAK,CAAC,EAAE,CAAA;KAAE;IAiBnF;;;;;OAKG;IACH,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,GAAG,SAAS,GAAG,IAAI;IAc7D,6EAA6E;IAC7E,KAAK,IAAI,QAAQ,CAAC,KAAK,CAAC,EAAE;IAY1B,OAAO,CAAC,WAAW;IAKnB;;;;OAIG;IACH,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,aAAa;CAKtB"}

package/dist/board/HwTypes.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Public types for the Hold & Win board. Kept in one leaf module so the
+ * reducer ({@link HoldAndWinState}), the driver ({@link HoldAndWinBoard}) and
+ * the builder can share them without import cycles.
+ */
+/** Grid coordinate of a board cell. */
+export interface HwCell {
+    col: number;
+    row: number;
+}
+/**
+ * A coin somewhere on the board. `id` selects the registered symbol art;
+ * `data` is an opaque game-layer payload the board never interprets.
+ *
+ * **Ownership contract:** `cell` and `id` belong to the board — treat them as
+ * read-only; the board keys its ledger by cell and mutating them is undefined.
+ * `data` is yours: mutate its contents freely (a doubler does `coin.data.value
+ * *= 2`), that is the intended way to carry live game state on a locked coin.
+ */
+export interface HwCoin<TData = unknown> {
+    readonly cell: HwCell;
+    readonly id: string;
+    data?: TData;
+}
+/** Why the respin counter changed — disambiguates a `respins:changed` event. */
+export type HwRespinReason = 'seed' | 'hit-reset' | 'miss';
+/** Resolution of one {@link HoldAndWinBoard.respin} wave. */
+export interface HwRespinResult<TData = unknown> {
+    round: number;
+    hits: HwCoin<TData>[];
+    respinsLeft: number;
+    full: boolean;
+    /** True when the feature is over (counter exhausted or board full). */
+    done: boolean;
+}
+export type HoldAndWinBoardEvents<TData = unknown> = {
+    'feature:enter': [{
+        seed: HwCoin<TData>[];
+        respins: number;
+    }];
+    'respin:start': [{
+        round: number;
+        respinsLeft: number;
+        spinning: HwCell[];
+    }];
+    /** Fires per cell, in landing (stagger) order. `coin` is null on a miss. */
+    'cell:landed': [{
+        cell: HwCell;
+        coin: HwCoin<TData> | null;
+    }];
+    'coin:locked': [{
+        coin: HwCoin<TData>;
+        locked: number;
+        capacity: number;
+    }];
+    /** Fired by `release()` — the collect / fly-away moment. */
+    'coin:released': [{
+        coin: HwCoin<TData>;
+        remaining: number;
+    }];
+    'respins:changed': [{
+        value: number;
+        reason: HwRespinReason;
+    }];
+    'respin:end': [{
+        round: number;
+        hits: HwCoin<TData>[];
+        respinsLeft: number;
+    }];
+    'board:full': [{
+        coins: HwCoin<TData>[];
+    }];
+    /** Fired by `skip()` so the game layer can cut its own flights / collect short. */
+    'feature:skip': [{
+        inFlight: number;
+    }];
+    /**
+     * Fired by `reset()` — a hard clear back to idle. Distinct from `coin:released`
+     * (which means "collect this coin"); listeners that maintain derived state
+     * from events (HUD totals, meters) clear it here without triggering collect.
+     */
+    'feature:reset': [{
+        clearedCoins: number;
+    }];
+    'feature:end': [{
+        coins: HwCoin<TData>[];
+        rounds: number;
+        full: boolean;
+    }];
+};
+/**
+ * One state-change the reducer ({@link HoldAndWinState}) decided, ready for the
+ * driver to emit. A tagged pair of `{ type, payload }` for every board event the
+ * reducer owns — the driver replays them onto its emitter and keys visual side
+ * effects (e.g. `playWin()` on `coin:locked`) off the type. `respin:start` and
+ * `feature:skip` are driver-owned (they describe in-flight reels, not ledger
+ * state) and are not produced here.
+ */
+export type HwEffect<TData = unknown> = {
+    [K in keyof HoldAndWinBoardEvents<TData>]: {
+        type: K;
+        payload: HoldAndWinBoardEvents<TData>[K][0];
+    };
+}[keyof HoldAndWinBoardEvents<TData>];
+export interface HwCellSizeOptions {
+    gap?: number;
+}
+/** `col,row` string key for the board's cell-indexed maps. */
+export declare const cellKey: (c: HwCell) => string;
+//# sourceMappingURL=HwTypes.d.ts.map

package/dist/board/HwTypes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"HwTypes.d.ts","sourceRoot":"","sources":["../../src/board/HwTypes.ts"],"names":[],"mappings":"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"}