@energy8platform/game-engine 0.20.0 → 0.22.0

package/dist/slot.cjs.js

@@ -9,9 +9,27 @@ var pixi_js = require('pixi.js');
  */
 const Easing = {
     linear: (t) => t,
+    easeInQuad: (t) => t * t,
     easeOutQuad: (t) => t * (2 - t),
+    easeInOutQuad: (t) => (t < 0.5 ? 2 * t * t : -1 + (4 - 2 * t) * t),
+    easeInCubic: (t) => t * t * t,
     easeOutCubic: (t) => --t * t * t + 1,
     easeInOutCubic: (t) => t < 0.5 ? 4 * t * t * t : (t - 1) * (2 * t - 2) * (2 * t - 2) + 1,
+    easeInQuart: (t) => t * t * t * t,
+    easeOutQuart: (t) => 1 - --t * t * t * t,
+    easeInOutQuart: (t) => t < 0.5 ? 8 * t * t * t * t : 1 - 8 * --t * t * t * t,
+    easeInSine: (t) => 1 - Math.cos((t * Math.PI) / 2),
+    easeOutSine: (t) => Math.sin((t * Math.PI) / 2),
+    easeInOutSine: (t) => -(Math.cos(Math.PI * t) - 1) / 2,
+    easeInExpo: (t) => (t === 0 ? 0 : Math.pow(2, 10 * t - 10)),
+    easeOutExpo: (t) => (t === 1 ? 1 : 1 - Math.pow(2, -10 * t)),
+    easeInOutExpo: (t) => t === 0
+        ? 0
+        : t === 1
+            ? 1
+            : t < 0.5
+                ? Math.pow(2, 20 * t - 10) / 2
+                : (2 - Math.pow(2, -20 * t + 10)) / 2,
     easeInBack: (t) => {
         const c1 = 1.70158;
         const c3 = c1 + 1;
@@ -22,6 +40,13 @@ const Easing = {
         const c3 = c1 + 1;
         return 1 + c3 * Math.pow(t - 1, 3) + c1 * Math.pow(t - 1, 2);
     },
+    easeInOutBack: (t) => {
+        const c1 = 1.70158;
+        const c2 = c1 * 1.525;
+        return t < 0.5
+            ? (Math.pow(2 * t, 2) * ((c2 + 1) * 2 * t - c2)) / 2
+            : (Math.pow(2 * t - 2, 2) * ((c2 + 1) * (t * 2 - 2) + c2) + 2) / 2;
+    },
     easeOutBounce: (t) => {
         const n1 = 7.5625;
         const d1 = 2.75;
@@ -32,7 +57,28 @@ const Easing = {
         if (t < 2.5 / d1)
             return n1 * (t -= 2.25 / d1) * t + 0.9375;
         return n1 * (t -= 2.625 / d1) * t + 0.984375;
-    }};
+    },
+    easeInBounce: (t) => 1 - Easing.easeOutBounce(1 - t),
+    easeInOutBounce: (t) => t < 0.5
+        ? (1 - Easing.easeOutBounce(1 - 2 * t)) / 2
+        : (1 + Easing.easeOutBounce(2 * t - 1)) / 2,
+    easeOutElastic: (t) => {
+        const c4 = (2 * Math.PI) / 3;
+        return t === 0
+            ? 0
+            : t === 1
+                ? 1
+                : Math.pow(2, -10 * t) * Math.sin((t * 10 - 0.75) * c4) + 1;
+    },
+    easeInElastic: (t) => {
+        const c4 = (2 * Math.PI) / 3;
+        return t === 0
+            ? 0
+            : t === 1
+                ? 1
+                : -Math.pow(2, 10 * t - 10) * Math.sin((t * 10 - 10.75) * c4);
+    },
+};
 
 /**
  * Lightweight tween system integrated with PixiJS Ticker.
@@ -65,6 +111,10 @@ class Tween {
      * @param onUpdate - Progress callback (0..1)
      */
     static to(target, props, duration, easing, onUpdate) {
+        // A destroyed (Pixi) target has null transform fields — skip rather than throw. This guards
+        // animations whose target is torn down mid-flight (e.g. a reel grid rebuilt during a spin).
+        if (target == null || target.destroyed)
+            return Promise.resolve();
         return new Promise((resolve) => {
             // Capture starting values
             const from = {};
@@ -90,6 +140,8 @@ class Tween {
      * Animate properties from given values to current values.
      */
     static from(target, props, duration, easing, onUpdate) {
+        if (target == null || target.destroyed)
+            return Promise.resolve();
         // Capture current values as "to"
         const to = {};
         for (const key of Object.keys(props)) {
@@ -102,6 +154,8 @@ class Tween {
      * Animate from one set of values to another.
      */
     static fromTo(target, fromProps, toProps, duration, easing, onUpdate) {
+        if (target == null || target.destroyed)
+            return Promise.resolve();
         // Set starting values
         for (const key of Object.keys(fromProps)) {
             Tween.setProperty(target, key, fromProps[key]);
@@ -175,6 +229,11 @@ class Tween {
         const dt = ticker.deltaMS;
         const completed = [];
         for (const tw of Tween._tweens) {
+            // target torn down mid-tween → finish it quietly
+            if (tw.target?.destroyed) {
+                completed.push(tw);
+                continue;
+            }
             tw.elapsed += dt;
             if (tw.elapsed < tw.delay)
                 continue;
@@ -212,9 +271,9 @@ class Tween {
         const parts = key.split('.');
         let obj = target;
         for (let i = 0; i < parts.length - 1; i++) {
-            obj = obj[parts[i]];
+            obj = obj?.[parts[i]];
         }
-        return obj[parts[parts.length - 1]] ?? 0;
+        return obj?.[parts[parts.length - 1]] ?? 0;
     }
     /**
      * Set a potentially nested property.
@@ -223,8 +282,10 @@ class Tween {
         const parts = key.split('.');
         let obj = target;
         for (let i = 0; i < parts.length - 1; i++) {
-            obj = obj[parts[i]];
+            obj = obj?.[parts[i]];
         }
+        if (obj == null)
+            return;
         obj[parts[parts.length - 1]] = value;
     }
 }
@@ -488,8 +549,12 @@ class SymbolCell extends pixi_js.Container {
         this.addChild(this._badges);
         this._drawFrame('idle');
     }
-    get view() { return this._view; }
+    get view() {
+        return this._view;
+    }
     setData(data) {
+        if (this.destroyed)
+            return; // a killed-tween chain may resume after the cell is gone
         // symbol view
         if (data.symbol == null) {
             if (this._view) {
@@ -514,7 +579,15 @@ class SymbolCell extends pixi_js.Container {
         this._setBonus(data.bonus);
     }
     setState(state) {
-        const key = state.winning ? 'winning' : state.removed ? 'removed' : state.fresh ? 'fresh' : 'idle';
+        if (this.destroyed)
+            return;
+        const key = state.winning
+            ? 'winning'
+            : state.removed
+                ? 'removed'
+                : state.fresh
+                    ? 'fresh'
+                    : 'idle';
         this.frameStyleKey = key;
         this._drawFrame(key);
     }
@@ -523,14 +596,17 @@ class SymbolCell extends pixi_js.Container {
             return this._view.playWin();
         // default: scale pop
         const target = this._view ?? this;
-        return Tween.to(target, { 'scale.x': 1.15, 'scale.y': 1.15 }, 160, Easing.easeOutBack)
-            .then(() => Tween.to(target, { 'scale.x': 1, 'scale.y': 1 }, 140, Easing.easeOutQuad));
+        return Tween.to(target, { 'scale.x': 1.15, 'scale.y': 1.15 }, 160, Easing.easeOutBack).then(() => Tween.to(target, { 'scale.x': 1, 'scale.y': 1 }, 140, Easing.easeOutQuad));
+    }
+    playIdle() {
+        this._view?.playIdle?.();
     }
-    playIdle() { this._view?.playIdle?.(); }
     hasBadge(kind) {
         return kind === 'multiplier' ? this._multBadge != null : this._bonusBadge != null;
     }
     _drawFrame(key) {
+        if (this.destroyed || this._frame.destroyed)
+            return;
         const s = this._style[key];
         this._frame.clear();
         this._frame
@@ -570,24 +646,38 @@ class SymbolCell extends pixi_js.Container {
     }
 }
 
+/**
+ * A grid of `SymbolCell`s. Supports uniform grids and variable-height reels (Megaways):
+ * when `rowsPerReel` is set each reel is vertically centred inside the tallest reel's envelope.
+ */
 class ReelGrid extends pixi_js.Container {
     __uiComponent = true;
     _cols;
-    _rows;
+    _rowsPerReel;
+    _maxRows;
     _cellSize;
     _gap;
     _cells = [];
     _cellLayer = new pixi_js.Container();
+    _resolve;
+    _frameStyle;
+    _mask = null;
     constructor(config) {
         super();
         this._cols = config.cols;
-        this._rows = config.rows;
+        this._rowsPerReel =
+            config.rowsPerReel && config.rowsPerReel.length === config.cols
+                ? config.rowsPerReel.slice()
+                : Array.from({ length: config.cols }, () => config.rows);
+        this._maxRows = Math.max(1, ...this._rowsPerReel);
         this._cellSize = config.cellSize;
         this._gap = config.gap ?? 0;
+        this._resolve = config.resolve;
+        this._frameStyle = config.frameStyle;
         if (config.decoration) {
             const pad = config.decoration.padding ?? 0;
             const w = this._cols * (this._cellSize + this._gap) - this._gap + pad * 2;
-            const h = this._rows * (this._cellSize + this._gap) - this._gap + pad * 2;
+            const h = this._maxRows * (this._cellSize + this._gap) - this._gap + pad * 2;
             if (config.decoration.texture) {
                 const deco = new pixi_js.Sprite(config.decoration.texture);
                 deco.width = w;
@@ -597,44 +687,87 @@ class ReelGrid extends pixi_js.Container {
             }
         }
         this.addChild(this._cellLayer);
+        this._buildCells();
+        if (config.mask)
+            this._applyMask();
+    }
+    _buildCells() {
         for (let c = 0; c < this._cols; c++) {
             this._cells[c] = [];
-            for (let r = 0; r < this._rows; r++) {
-                const cell = new SymbolCell({ size: this._cellSize, resolve: config.resolve, frameStyle: config.frameStyle });
+            for (let r = 0; r < this._rowsPerReel[c]; r++) {
+                const cell = new SymbolCell({
+                    size: this._cellSize,
+                    resolve: this._resolve,
+                    frameStyle: this._frameStyle,
+                });
                 const { x, y } = this.cellPosition(c, r);
                 cell.position.set(x, y);
                 this._cellLayer.addChild(cell);
                 this._cells[c][r] = cell;
             }
         }
-        if (config.mask) {
-            const w = this._cols * (this._cellSize + this._gap) - this._gap;
-            const h = this._rows * (this._cellSize + this._gap) - this._gap;
-            const m = new pixi_js.Graphics()
-                .rect(-this._cellSize / 2, -this._cellSize / 2, w, h)
-                .fill(0xffffff);
-            this._cellLayer.mask = m;
-            this.addChild(m);
-        }
     }
-    get cols() { return this._cols; }
-    get rows() { return this._rows; }
+    _applyMask() {
+        const w = this._cols * (this._cellSize + this._gap) - this._gap;
+        const h = this._maxRows * (this._cellSize + this._gap) - this._gap;
+        const m = new pixi_js.Graphics().rect(-this._cellSize / 2, -this._cellSize / 2, w, h).fill(0xffffff);
+        this._cellLayer.mask = m;
+        this.addChild(m);
+        this._mask = m;
+    }
+    get cols() {
+        return this._cols;
+    }
+    /** Tallest reel's row count (the grid's visual height in rows). */
+    get rows() {
+        return this._maxRows;
+    }
+    get cellSize() {
+        return this._cellSize;
+    }
+    rowsOf(col) {
+        return this._rowsPerReel[col] ?? 0;
+    }
+    get rowsPerReel() {
+        return this._rowsPerReel.slice();
+    }
+    /** Cell centre position. Variable-height reels are centred in the max-rows envelope. */
     cellPosition(col, row) {
         const step = this._cellSize + this._gap;
-        return { x: col * step, y: row * step };
+        const reelRows = this._rowsPerReel[col] ?? this._maxRows;
+        const yOffset = ((this._maxRows - reelRows) / 2) * step;
+        return { x: col * step, y: yOffset + row * step };
+    }
+    getCell(col, row) {
+        return this._cells[col][row];
     }
-    getCell(col, row) { return this._cells[col][row]; }
     setGrid(cells) {
         for (let c = 0; c < this._cols; c++) {
-            for (let r = 0; r < this._rows; r++) {
+            for (let r = 0; r < this._rowsPerReel[c]; r++) {
                 this._cells[c]?.[r]?.setData(cells[c]?.[r] ?? { symbol: null });
             }
         }
     }
+    /** Rebuild the grid with new per-reel row counts (Megaways re-roll / dynamic rows). */
+    reshape(rowsPerReel) {
+        if (rowsPerReel.length !== this._cols)
+            return;
+        this._cellLayer.removeChildren().forEach((c) => c.destroy());
+        this._cells = [];
+        this._rowsPerReel = rowsPerReel.slice();
+        this._maxRows = Math.max(1, ...this._rowsPerReel);
+        this._buildCells();
+        if (this._mask) {
+            this._mask.destroy();
+            this.removeChild(this._mask);
+            this._mask = null;
+            this._applyMask();
+        }
+    }
     resize(cellSize) {
         this._cellSize = cellSize;
         for (let c = 0; c < this._cols; c++) {
-            for (let r = 0; r < this._rows; r++) {
+            for (let r = 0; r < this._rowsPerReel[c]; r++) {
                 const { x, y } = this.cellPosition(c, r);
                 this._cells[c][r].position.set(x, y);
             }
@@ -646,13 +779,26 @@ class ReelGrid extends pixi_js.Container {
 /** Resolve a descriptor's string easing name to the engine's easing function. */
 const EASING_BY_NAME = {
     linear: Easing.linear,
+    easeInQuad: Easing.easeInQuad,
     easeOutQuad: Easing.easeOutQuad,
+    easeInOutQuad: Easing.easeInOutQuad,
+    easeInCubic: Easing.easeInCubic,
     easeOutCubic: Easing.easeOutCubic,
+    easeInOutCubic: Easing.easeInOutCubic,
+    easeInBack: Easing.easeInBack,
     easeOutBack: Easing.easeOutBack,
+    easeInOutBack: Easing.easeInOutBack,
     easeOutBounce: Easing.easeOutBounce,
-    easeInBack: Easing.easeInBack,
-    easeInOutCubic: Easing.easeInOutCubic,
+    easeInBounce: Easing.easeInBounce,
+    easeOutElastic: Easing.easeOutElastic,
+    easeInSine: Easing.easeInSine,
+    easeOutSine: Easing.easeOutSine,
+    easeInOutSine: Easing.easeInOutSine,
 };
+/** Resolve an easing name to a function, falling back to easeOutQuad. */
+function easingByName(name) {
+    return (name && EASING_BY_NAME[name]) || Easing.easeOutQuad;
+}
 
 // packages/game-engine/src/slot/anim/CascadeController.ts
 const DEFAULT_TIMINGS$1 = { reveal: 300, highlight: 400, remove: 250, drop: 200, refill: 220, wait: 150 };
@@ -793,6 +939,1684 @@ class ReelSpinController {
     skip() { this._killed = true; this._killOwnTweens(); }
 }
 
+// packages/game-engine/src/slot/config/ReelSystemConfig.ts
+//
+// The single, fully-typed configuration object for the configurable reel system.
+// Everything is optional with sensible defaults — `resolveReelConfig(partial)` deep-merges
+// a partial config onto DEFAULT_REEL_CONFIG so games (and the reel-lab playground) can
+// override only what they need.
+//
+// Design notes are in docs/reels-analysis-and-design.md.
+const FEATURE_KEYS = [
+    'reelModifier', // pre-spin
+    'giant',
+    'stacked',
+    'mystery', // post-spin reveal
+    'expandingWild',
+    'walkingWild',
+    'randomWild',
+    'transform',
+    'split',
+    'nudge',
+    'multiplier',
+    'sticky',
+    'holdAndSpin',
+];
+// ─────────────────────────────────────────────────────────────────────────────
+// Defaults
+// ─────────────────────────────────────────────────────────────────────────────
+const DEFAULT_REEL_CONFIG = {
+    grid: {
+        cols: 5,
+        rows: 3,
+        cellSize: 96,
+        gap: 6,
+        evaluation: 'lines',
+        minRows: 2,
+        maxRows: 7,
+        topReel: null,
+        mask: true,
+        decoration: { padding: 0 },
+    },
+    motion: {
+        style: 'swap',
+        spinUp: 500,
+        hold: 200,
+        stopStagger: 120,
+        stopMode: 'sequential',
+        stopOrder: 'ltr',
+        settle: { amp: 7, ms: 240, easing: 'easeOutBack' },
+        squash: { enabled: false, scaleX: 1.18, scaleY: 0.82, ms: 90 },
+        blur: { enabled: false, alpha: 0.85, strength: 8, streaks: false },
+        turboFactor: 0.5,
+        intensity: 'full',
+        slamStop: true,
+        symbolsPerReel: 6,
+    },
+    anticipation: {
+        enabled: false,
+        triggerSymbols: ['scatter'],
+        threshold: 2,
+        reels: 'trailing',
+        slowdownFactor: 0.3,
+        holdMs: 400,
+        zoom: { enabled: false, scale: 1.15, ms: 600 },
+    },
+    cascade: {
+        enabled: false,
+        gravity: true,
+        timings: { reveal: 300, highlight: 400, remove: 250, drop: 220, refill: 220, wait: 150 },
+        easings: { highlight: 'easeOutQuad', remove: 'easeInBack', drop: 'easeOutBounce' },
+        perStepDecel: 0.08,
+        perStepDecelCap: 1.5,
+        dimNonWinners: false,
+        dimAlpha: 0.35,
+        multiplier: {
+            enabled: false,
+            start: 1,
+            mode: 'add',
+            step: 1,
+            cap: null,
+            persistInFreeSpins: false,
+        },
+    },
+    win: {
+        highlightScale: 1.12,
+        glow: true,
+        frameShake: { enabled: false, amp: 3, ms: 180, onlyOnSymbols: null },
+    },
+    features: {
+        expandingWild: {
+            enabled: false,
+            symbol: 'wild',
+            reels: [],
+            toFullReel: true,
+            ms: 420,
+            easing: 'easeOutBack',
+            onlyInFreeSpins: false,
+        },
+        sticky: { enabled: false, symbols: ['wild'], durationSpins: 3, ringColor: 0xec4899 },
+        walkingWild: {
+            enabled: false,
+            symbol: 'wild',
+            direction: 'left',
+            stepPerSpin: 1,
+            awardsRespin: true,
+            asStacked: false,
+        },
+        multiplier: {
+            enabled: false,
+            symbol: null,
+            scope: 'perSymbol',
+            combine: 'additive',
+            attachedToWild: false,
+            max: 128,
+            accumulateAcrossFreeSpins: false,
+        },
+        mystery: { enabled: false, symbol: 'mystery', revealPool: [], canRevealWild: false, ms: 300 },
+        transform: {
+            enabled: false,
+            trigger: null,
+            source: 'randomLow',
+            target: 'wild',
+            allInstances: true,
+            upgradeOnly: false,
+            ms: 320,
+        },
+        giant: {
+            enabled: false,
+            width: 2,
+            height: 2,
+            symbols: [],
+            chosenPerSpin: false,
+            onlyInFreeSpins: false,
+        },
+        split: { enabled: false, symbol: 'split', factor: 2, reels: [], deferUntilRespinsEnd: true },
+        stacked: { enabled: false, symbols: [], height: 3 },
+        nudge: {
+            enabled: false,
+            reels: [],
+            step: 1,
+            toFullReel: false,
+            multiplierStart: 1,
+            multiplierPerNudge: 1,
+        },
+        reelModifier: { enabled: false, pool: [], appliesIn: 'both' },
+        holdAndSpin: {
+            enabled: false,
+            lockSymbols: ['coin'],
+            triggerThreshold: 6,
+            respinsAwarded: 3,
+            resetOnNewSymbol: true,
+            jackpotTiers: ['Mini', 'Minor', 'Major', 'Grand'],
+            fullGridAwardsGrand: true,
+        },
+        randomWild: {
+            enabled: false,
+            count: [1, 3],
+            sticky: false,
+            multiplier: 1,
+            trigger: 'onFreeSpins',
+            chance: 0.2,
+        },
+    },
+};
+/** Intensity → duration scale (accessibility). */
+const INTENSITY_SCALE = { full: 1, reduced: 0.7, minimal: 0.4 };
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/** Deep-merge `partial` onto `base` (arrays replace, objects merge). Returns a new object. */
+function mergeReelConfig(base, partial) {
+    if (partial == null)
+        return structuredCloneSafe(base);
+    const out = structuredCloneSafe(base);
+    for (const [k, v] of Object.entries(partial)) {
+        if (v === undefined)
+            continue;
+        const cur = out[k];
+        if (isPlainObject(v) && isPlainObject(cur))
+            out[k] = mergeReelConfig(cur, v);
+        else
+            out[k] = v;
+    }
+    return out;
+}
+/** Resolve a partial config to a fully-populated `ReelSystemConfig`. */
+function resolveReelConfig(partial) {
+    return mergeReelConfig(DEFAULT_REEL_CONFIG, partial);
+}
+function structuredCloneSafe(v) {
+    // structuredClone is available in modern browsers + Node 17+; fall back to JSON for safety.
+    if (typeof structuredClone === 'function')
+        return structuredClone(v);
+    return JSON.parse(JSON.stringify(v));
+}
+/** Effective per-reel row counts (resolves Megaways `rowsPerReel`, else uniform `rows`). */
+function effectiveRowsPerReel(grid) {
+    if (grid.rowsPerReel && grid.rowsPerReel.length === grid.cols)
+        return grid.rowsPerReel.slice();
+    return Array.from({ length: grid.cols }, () => grid.rows);
+}
+/** Total ways-to-win for a ways/megaways grid (product of per-reel heights). */
+function waysCount(grid) {
+    return effectiveRowsPerReel(grid).reduce((a, b) => a * b, 1);
+}
+
+// packages/game-engine/src/slot/config/presets.ts
+//
+// Reel presets distilled from our shipped games (see docs/reels-analysis-and-design.md §2).
+// Each is a DeepPartial override on DEFAULT_REEL_CONFIG.
+const PRESETS = {
+    classic: {
+        id: 'classic',
+        name: 'Classic 5×3 lines',
+        note: 'Plain spinning reels, sequential stops, settle bounce.',
+        config: {
+            grid: { cols: 5, rows: 3, evaluation: 'lines', cellSize: 96, gap: 6 },
+            motion: {
+                style: 'strip',
+                spinUp: 600,
+                stopStagger: 140,
+                blur: { enabled: true, alpha: 0.85, strength: 6, streaks: false },
+            },
+        },
+    },
+    'kitsune-wrath': {
+        id: 'kitsune-wrath',
+        name: 'Kitsune Wrath 7×7 cluster',
+        note: 'Tumble grid, sticky wilds, position multipliers, scatter anticipation.',
+        config: {
+            grid: { cols: 7, rows: 7, evaluation: 'cluster', cellSize: 66, gap: 0 },
+            motion: {
+                style: 'cascade-drop',
+                spinUp: 400,
+                squash: { enabled: true, scaleX: 1.12, scaleY: 0.88, ms: 90 },
+            },
+            cascade: {
+                enabled: true,
+                gravity: true,
+                dimNonWinners: true,
+                multiplier: {
+                    enabled: true,
+                    start: 1,
+                    mode: 'mul',
+                    step: 2,
+                    cap: 128,
+                    persistInFreeSpins: false,
+                },
+            },
+            anticipation: { enabled: true, triggerSymbols: ['scatter'], threshold: 4 },
+            features: {
+                sticky: { enabled: true, durationSpins: 3 },
+                multiplier: { enabled: true, scope: 'perSymbol', combine: 'multiplicative', max: 128 },
+            },
+        },
+    },
+    'moon-spice': {
+        id: 'moon-spice',
+        name: 'Moon Spice 5×4 ways',
+        note: 'Spin + cascade refill, frame shake on wild/scatter, 1024 ways.',
+        config: {
+            grid: { cols: 5, rows: 4, evaluation: 'ways', cellSize: 90, gap: 4 },
+            motion: {
+                style: 'strip',
+                spinUp: 1200,
+                stopStagger: 120,
+                settle: { amp: 6, ms: 220, easing: 'easeOutQuad' },
+            },
+            cascade: {
+                enabled: true,
+                gravity: true,
+                easings: { highlight: 'easeOutQuad', remove: 'easeInBack', drop: 'easeOutBounce' },
+            },
+            win: { frameShake: { enabled: true, amp: 2.2, ms: 180, onlyOnSymbols: ['wild', 'scatter'] } },
+            features: { multiplier: { enabled: true, scope: 'perSymbol', combine: 'additive' } },
+        },
+    },
+    'stone-rush': {
+        id: 'stone-rush',
+        name: 'Stone Rush 7×7 tumble',
+        note: 'Weighty gravity with squash/stretch, per-step deceleration, multiplier orbs.',
+        config: {
+            grid: { cols: 7, rows: 7, evaluation: 'cluster', cellSize: 66, gap: 8 },
+            motion: {
+                style: 'cascade-drop',
+                spinUp: 320,
+                squash: { enabled: true, scaleX: 1.3, scaleY: 0.7, ms: 110 },
+            },
+            cascade: {
+                enabled: true,
+                gravity: true,
+                perStepDecel: 0.08,
+                perStepDecelCap: 1.5,
+                multiplier: {
+                    enabled: true,
+                    start: 1,
+                    mode: 'add',
+                    step: 1,
+                    cap: 100,
+                    persistInFreeSpins: true,
+                },
+            },
+            features: {
+                multiplier: { enabled: true, scope: 'global', combine: 'additive', max: 100 },
+                expandingWild: { enabled: true, symbol: 'wild', toFullReel: false },
+            },
+        },
+    },
+    'hot-ross': {
+        id: 'hot-ross',
+        name: 'Hot Ross 5×5 lines',
+        note: 'Classic strip spin with motion blur, scatter tease, expanding wilds, sticky reels.',
+        config: {
+            grid: { cols: 5, rows: 5, evaluation: 'lines', cellSize: 88, gap: 4 },
+            motion: {
+                style: 'strip',
+                spinUp: 1650,
+                stopStagger: 210,
+                blur: { enabled: true, alpha: 0.82, strength: 8, streaks: true },
+                settle: { amp: 7, ms: 240, easing: 'easeOutBack' },
+            },
+            anticipation: {
+                enabled: true,
+                triggerSymbols: ['scatter'],
+                threshold: 2,
+                slowdownFactor: 0.28,
+                holdMs: 450,
+            },
+            features: {
+                expandingWild: { enabled: true, symbol: 'wild', reels: [1, 2, 3], toFullReel: true },
+                sticky: { enabled: true, durationSpins: 0 },
+            },
+        },
+    },
+    magnus: {
+        id: 'magnus',
+        name: 'Magnus 6×6 transmute',
+        note: 'Cascade with idle-breathing symbols, scatter anticipation + reel zoom, transform.',
+        config: {
+            grid: { cols: 6, rows: 6, evaluation: 'cluster', cellSize: 74, gap: 2 },
+            motion: {
+                style: 'cascade-drop',
+                spinUp: 400,
+                squash: { enabled: true, scaleX: 1.14, scaleY: 0.86, ms: 110 },
+            },
+            cascade: {
+                enabled: true,
+                gravity: true,
+                multiplier: {
+                    enabled: true,
+                    start: 1,
+                    mode: 'add',
+                    step: 1,
+                    cap: null,
+                    persistInFreeSpins: true,
+                },
+            },
+            anticipation: {
+                enabled: true,
+                triggerSymbols: ['scatter'],
+                threshold: 2,
+                holdMs: 280,
+                zoom: { enabled: true, scale: 1.3, ms: 600 },
+            },
+            features: {
+                transform: {
+                    enabled: true,
+                    source: 'randomLow',
+                    target: 'h1',
+                    allInstances: true,
+                    upgradeOnly: true,
+                },
+            },
+        },
+    },
+    megaways: {
+        id: 'megaways',
+        name: 'Megaways 6× (2–7)',
+        note: 'Variable per-reel heights, tumble + climbing multiplier, anticipation.',
+        config: {
+            grid: {
+                cols: 6,
+                rows: 4,
+                rowsPerReel: [4, 6, 3, 7, 5, 2],
+                evaluation: 'megaways',
+                cellSize: 74,
+                gap: 4,
+                minRows: 2,
+                maxRows: 7,
+            },
+            motion: { style: 'strip', spinUp: 900, stopStagger: 130 },
+            cascade: {
+                enabled: true,
+                gravity: true,
+                multiplier: {
+                    enabled: true,
+                    start: 1,
+                    mode: 'add',
+                    step: 1,
+                    cap: null,
+                    persistInFreeSpins: true,
+                },
+            },
+            anticipation: { enabled: true, triggerSymbols: ['scatter'], threshold: 3 },
+        },
+    },
+};
+const PRESET_LIST = Object.values(PRESETS);
+
+// packages/game-engine/src/slot/motion/SpinEngine.ts
+//
+// Configurable spin motion. Supports three styles — 'swap' (texture-swap ring),
+// 'strip' (a tape of symbols slides past a masked window) and 'cascade-drop'
+// (symbols drop in from above) — plus stop modes, turbo/intensity scaling, motion
+// blur, settle-bounce, squash-on-impact and slam (quick) stop.
+//
+// Presentation only: the landing grid is the already-resolved outcome. The engine
+// never re-rolls a result.
+class SpinEngine {
+    _grid;
+    _resolve;
+    _cfg;
+    _win = DEFAULT_REEL_CONFIG.win;
+    _killed = false;
+    _shaking = false;
+    _temp = [];
+    constructor(grid, resolve, cfg, win) {
+        this._grid = grid;
+        this._resolve = resolve;
+        this._cfg = cfg;
+        if (win)
+            this._win = win;
+    }
+    setConfig(cfg) {
+        this._cfg = cfg;
+    }
+    setWin(win) {
+        this._win = win;
+    }
+    /** Quick decaying frame shake when a landed reel carries a configured trigger symbol. */
+    async _frameShake(landing) {
+        const fs = this._win.frameShake;
+        if (!fs.enabled || this._shaking || this._killed)
+            return;
+        const triggers = fs.onlyOnSymbols;
+        if (triggers && !landing.some((c) => c.symbol && triggers.includes(c.symbol)))
+            return;
+        this._shaking = true;
+        const baseX = this._grid.x;
+        const amp = fs.amp * INTENSITY_SCALE[this._cfg.intensity];
+        const steps = 4;
+        for (let i = 0; i < steps && !this._killed; i++) {
+            const a = amp * (1 - i / steps) * (i % 2 ? -1 : 1);
+            await Tween.to(this._grid, { x: baseX + a }, fs.ms / (steps + 1), EASING_BY_NAME['easeOutQuad']);
+        }
+        if (!this._killed && !this._grid.destroyed)
+            this._grid.x = baseX;
+        this._shaking = false;
+    }
+    scale(opts) {
+        const turbo = opts?.turbo ? this._cfg.turboFactor : 1;
+        return turbo * INTENSITY_SCALE[this._cfg.intensity];
+    }
+    /** PURE: per-reel stop schedule. No Pixi mutation. */
+    plan(data, opts) {
+        const f = this.scale(opts);
+        const cols = this._grid.cols;
+        const order = (reel) => (this._cfg.stopOrder === 'rtl' ? cols - 1 - reel : reel);
+        const anticipate = new Set(opts?.anticipateReels ?? []);
+        const out = [];
+        for (let reel = 0; reel < cols; reel++) {
+            const idx = order(reel);
+            let stopTime;
+            if (this._cfg.stopMode === 'sync')
+                stopTime = (this._cfg.spinUp + this._cfg.hold) * f;
+            else if (this._cfg.stopMode === 'random')
+                stopTime =
+                    (this._cfg.spinUp +
+                        this._cfg.hold +
+                        idx * this._cfg.stopStagger * (0.4 + (reel % 3) * 0.3)) *
+                        f;
+            else
+                stopTime = (this._cfg.spinUp + this._cfg.hold + idx * this._cfg.stopStagger) * f;
+            const isAnticipated = anticipate.has(reel);
+            if (isAnticipated)
+                stopTime += (opts?.anticipateHoldMs ?? 0) * f;
+            out.push({
+                reel,
+                stopTime,
+                landing: data.targetGrid[reel] ?? [],
+                settle: { amp: this._cfg.settle.amp, ms: this._cfg.settle.ms * f },
+                anticipated: isAnticipated,
+            });
+        }
+        return out;
+    }
+    /** Execute the spin for every reel concurrently. */
+    async run(data, opts) {
+        this._killed = false;
+        this._temp = [];
+        const plan = this.plan(data, opts);
+        const f = this.scale(opts);
+        await Promise.all(plan.map((p) => this._runReel(p, data, opts, f)));
+        this._cleanupTemp();
+    }
+    async _runReel(p, data, opts, f) {
+        if (this._killed)
+            return;
+        switch (this._cfg.style) {
+            case 'strip':
+                return this._runStrip(p, data, opts, f);
+            case 'cascade-drop':
+                return this._runDrop(p, opts, f);
+            case 'swap':
+            default:
+                return this._runSwap(p, data, opts, f);
+        }
+    }
+    /** Anticipation time-stretch factor for a reel (>=1, longer = slower). */
+    slowOf(p, opts) {
+        return p.anticipated ? Math.max(1, 1 / (opts?.anticipateSlowdown ?? 1)) : 1;
+    }
+    // ── swap: cycle symbols quickly in the real cells, then land ──────────────
+    async _runSwap(p, data, opts, f) {
+        const rows = this._grid.rowsOf(p.reel);
+        const cells = Array.from({ length: rows }, (_, r) => this._grid.getCell(p.reel, r));
+        const strip = data.strip?.(p.reel) ?? p.landing.map((c) => c.symbol ?? '').filter(Boolean);
+        const tape = strip.length ? strip : ['?'];
+        const blur = this._applyBlur(cells, true);
+        const tickMs = 1000 / 30;
+        // anticipation makes the reel spin longer before it lands
+        const ticks = Math.max(6, Math.floor((p.stopTime * this.slowOf(p, opts)) / tickMs));
+        for (let i = 0; i < ticks; i++) {
+            if (this._killed)
+                break;
+            for (let r = 0; r < cells.length; r++)
+                cells[r].setData({ symbol: tape[(i + r) % tape.length] || null });
+            await Tween.delay(tickMs);
+        }
+        blur?.();
+        for (let r = 0; r < cells.length; r++)
+            cells[r].setData(p.landing[r] ?? { symbol: null });
+        await this._settle(p.reel, p.settle, f);
+        await this._frameShake(p.landing);
+    }
+    // ── strip: a tape Container slides down past the window, then lands ────────
+    async _runStrip(p, data, opts, f) {
+        const rows = this._grid.rowsOf(p.reel);
+        const realCells = Array.from({ length: rows }, (_, r) => this._grid.getCell(p.reel, r));
+        const base = this._grid.cellPosition(p.reel, 0);
+        const step = this._grid.cellPosition(p.reel, 1).y - base.y;
+        const tapeLen = Math.max(this._cfg.symbolsPerReel, rows + 4);
+        const strip = data.strip?.(p.reel) ?? p.landing.map((c) => c.symbol ?? '').filter(Boolean);
+        const pool = strip.length ? strip : ['?'];
+        // Tape cells laid out top→bottom at local y = i*step. The bottom `rows` cells carry the
+        // landing symbols; everything above is filler.
+        const tape = new pixi_js.Container();
+        tape.x = base.x;
+        const landingStart = tapeLen - rows;
+        for (let i = 0; i < tapeLen; i++) {
+            const cell = new SymbolCell({ size: this._grid.cellSize, resolve: this._resolve });
+            const sym = i >= landingStart
+                ? (p.landing[i - landingStart]?.symbol ?? null)
+                : (pool[i % pool.length] ?? null);
+            cell.setData({ symbol: sym });
+            cell.position.set(0, i * step);
+            tape.addChild(cell);
+        }
+        // At rest the bottom block aligns with the window; start shifted up by the whole tape.
+        const restY = base.y - landingStart * step;
+        const startY = restY - tapeLen * step;
+        tape.y = startY;
+        realCells.forEach((c) => (c.visible = false));
+        this._grid.addChild(tape);
+        this._temp.push(tape);
+        const clearBlur = this._applyBlur([tape], true);
+        const slow = this.slowOf(p, opts);
+        // overshoot/settle honour the configured settle (amp in px, easing)
+        const overshoot = p.settle.amp || step * 0.18;
+        await Tween.to(tape, { y: restY + overshoot }, p.stopTime * slow, easingByName('easeInOutQuad'));
+        if (this._killed) {
+            clearBlur?.();
+            return;
+        }
+        clearBlur?.();
+        await Tween.to(tape, { y: restY }, Math.max(120, p.settle.ms), easingByName(this._cfg.settle.easing));
+        // hand the result back to the real cells
+        for (let r = 0; r < rows; r++)
+            realCells[r].setData(p.landing[r] ?? { symbol: null });
+        realCells.forEach((c) => (c.visible = true));
+        tape.destroy();
+        this._temp = this._temp.filter((t) => t !== tape);
+        // squash the real cells on impact when enabled
+        if (this._cfg.squash.enabled)
+            await Promise.all(realCells.map((c) => this._squashCell(c, f)));
+        await this._frameShake(p.landing);
+    }
+    // ── cascade-drop: symbols drop in from above with stagger + bounce + squash ─
+    async _runDrop(p, opts, f) {
+        const rows = this._grid.rowsOf(p.reel);
+        const step = this._grid.cellPosition(p.reel, 1).y - this._grid.cellPosition(p.reel, 0).y;
+        const slow = this.slowOf(p, opts); // anticipation drops the reel in more slowly
+        await Promise.all(Array.from({ length: rows }, (_, r) => r).map(async (r) => {
+            if (this._killed)
+                return;
+            const cell = this._grid.getCell(p.reel, r);
+            const to = this._grid.cellPosition(p.reel, r);
+            cell.setData(p.landing[r] ?? { symbol: null });
+            cell.position.set(to.x, to.y - step * (rows + 1));
+            cell.alpha = 1;
+            const delay = (p.reel * this._cfg.stopStagger * 0.4 + r * 24) * f * slow;
+            if (delay)
+                await Tween.delay(delay);
+            await Tween.to(cell, { 'position.y': to.y }, this._cfg.spinUp * 0.6 * f * slow, easingByName(this._cfg.settle.easing));
+            await this._squashCell(cell, f);
+        }));
+        await this._frameShake(p.landing);
+    }
+    // ── shared helpers ────────────────────────────────────────────────────────
+    async _settle(reel, settle, f) {
+        if (this._killed || settle.amp <= 0)
+            return;
+        const cells = Array.from({ length: this._grid.rowsOf(reel) }, (_, r) => this._grid.getCell(reel, r));
+        const parent = cells[0]?.parent;
+        if (!parent)
+            return;
+        // bounce the whole reel column by moving each cell, then squash the impact
+        await Promise.all(cells.map((c) => {
+            const y = c.y;
+            return Tween.fromTo(c, { y: y - settle.amp }, { y }, settle.ms, EASING_BY_NAME[this._cfg.settle.easing] ?? EASING_BY_NAME['easeOutBack']);
+        }));
+        if (this._cfg.squash.enabled)
+            await Promise.all(cells.map((c) => this._squashCell(c, f)));
+    }
+    async _squashCell(cell, f) {
+        if (!this._cfg.squash.enabled || this._killed)
+            return;
+        const { scaleX, scaleY, ms } = this._cfg.squash;
+        await Tween.to(cell, { 'scale.x': scaleX, 'scale.y': scaleY }, ms * 0.5 * f, EASING_BY_NAME['easeOutQuad']);
+        await Tween.to(cell, { 'scale.x': 1, 'scale.y': 1 }, ms * 0.5 * f, EASING_BY_NAME['easeOutBack']);
+    }
+    /** Apply motion blur (alpha + optional BlurFilter) to targets; returns a disposer that clears it. */
+    _applyBlur(targets, _motion) {
+        if (!this._cfg.blur.enabled)
+            return null;
+        const filter = this._cfg.blur.strength > 0
+            ? new pixi_js.BlurFilter({ strength: this._cfg.blur.strength, quality: 2 })
+            : null;
+        for (const t of targets) {
+            t.alpha = this._cfg.blur.alpha;
+            if (filter)
+                t.filters = [filter];
+        }
+        return () => {
+            for (const t of targets) {
+                t.alpha = 1;
+                t.filters = [];
+            }
+            filter?.destroy();
+        };
+    }
+    _cleanupTemp() {
+        for (const t of this._temp) {
+            if (!t.destroyed)
+                t.destroy();
+        }
+        this._temp = [];
+    }
+    /** Slam / quick stop: snap everything to the target and stop animating. */
+    skip() {
+        if (!this._cfg.slamStop && !this._killed) ;
+        this._killed = true;
+        this._shaking = false;
+        this._cleanupTemp();
+        if (this._grid.destroyed)
+            return;
+        Tween.killTweensOf(this._grid);
+        this._grid.x = 0; // undo any in-flight frame shake
+        for (let c = 0; c < this._grid.cols; c++) {
+            for (let r = 0; r < this._grid.rowsOf(c); r++) {
+                const cell = this._grid.getCell(c, r);
+                if (cell.destroyed)
+                    continue;
+                Tween.killTweensOf(cell);
+                cell.visible = true;
+                cell.alpha = 1;
+                cell.filters = [];
+                cell.scale.set(1);
+            }
+        }
+        this._cleanupTemp();
+    }
+}
+
+// packages/game-engine/src/slot/motion/AnticipationController.ts
+//
+// Decides which trailing reels get the "anticipation" slow-down treatment, based purely on
+// the already-resolved landing grid (presentation only — never a secondary outcome decision).
+class AnticipationController {
+    _cfg;
+    constructor(cfg) {
+        this._cfg = cfg;
+    }
+    setConfig(cfg) {
+        this._cfg = cfg;
+    }
+    /** Count how many trigger symbols land on a given reel. */
+    countOnReel(reel) {
+        let n = 0;
+        for (const c of reel)
+            if (c?.symbol && this._cfg.triggerSymbols.includes(c.symbol))
+                n++;
+        return n;
+    }
+    /**
+     * Decide anticipation from the landing grid. Trigger symbols are counted left→right;
+     * once the running total reaches `threshold`, every still-spinning reel after that point
+     * is flagged for the slow treatment (this mirrors "searching for the last scatter").
+     */
+    decide(targetGrid) {
+        if (!this._cfg.enabled)
+            return { active: false, reels: [], slowdown: 1, holdMs: 0 };
+        if (Array.isArray(this._cfg.reels)) {
+            // explicit reel list — arm only if the threshold is met somewhere on the board
+            const total = targetGrid.reduce((sum, reel) => sum + this.countOnReel(reel), 0);
+            const active = total >= this._cfg.threshold;
+            return active
+                ? {
+                    active,
+                    reels: this._cfg.reels.slice(),
+                    slowdown: this._cfg.slowdownFactor,
+                    holdMs: this._cfg.holdMs,
+                }
+                : { active: false, reels: [], slowdown: 1, holdMs: 0 };
+        }
+        // 'trailing': find the reel where the cumulative count hits the threshold
+        let running = 0;
+        let armReel = -1;
+        for (let c = 0; c < targetGrid.length; c++) {
+            running += this.countOnReel(targetGrid[c] ?? []);
+            if (running >= this._cfg.threshold) {
+                armReel = c;
+                break;
+            }
+        }
+        if (armReel < 0)
+            return { active: false, reels: [], slowdown: 1, holdMs: 0 };
+        const reels = [];
+        for (let c = armReel + 1; c < targetGrid.length; c++)
+            reels.push(c);
+        if (reels.length === 0)
+            return { active: false, reels: [], slowdown: 1, holdMs: 0 };
+        return { active: true, reels, slowdown: this._cfg.slowdownFactor, holdMs: this._cfg.holdMs };
+    }
+    /** Optionally zoom the grid in while anticipating, then settle back. Returns a reset fn. */
+    async zoomIn(grid) {
+        if (!this._cfg.zoom.enabled)
+            return async () => { };
+        const sx = grid.scale.x;
+        const sy = grid.scale.y;
+        await Tween.to(grid, { 'scale.x': sx * this._cfg.zoom.scale, 'scale.y': sy * this._cfg.zoom.scale }, this._cfg.zoom.ms, easingByName('easeOutCubic'));
+        return async () => {
+            await Tween.to(grid, { 'scale.x': sx, 'scale.y': sy }, this._cfg.zoom.ms, easingByName('easeOutCubic'));
+        };
+    }
+}
+
+// packages/game-engine/src/slot/cascade/TumbleController.ts
+//
+// Richer cascade/tumble than the back-compat CascadeController: animates surviving symbols
+// sliding into the gaps (gravity), supports per-step deceleration (tension build), dimming of
+// non-winning symbols, and a running win multiplier (Pragmatic Tumble / NetEnt Avalanche style).
+//
+// Presentation only — the settled board is provided by the caller.
+class TumbleController {
+    _grid;
+    _cfg;
+    _win = DEFAULT_REEL_CONFIG.win;
+    _killed = false;
+    _mult;
+    constructor(grid, cfg, win) {
+        this._grid = grid;
+        this._cfg = cfg;
+        this._mult = cfg.multiplier.start;
+        if (win)
+            this._win = win;
+    }
+    setConfig(cfg) {
+        this._cfg = cfg;
+    }
+    setWin(win) {
+        this._win = win;
+    }
+    /** Killed, or the grid was torn down underneath us (rebuild during a cascade). */
+    get _dead() {
+        return this._killed || this._grid.destroyed;
+    }
+    get multiplier() {
+        return this._mult;
+    }
+    resetMultiplier() {
+        this._mult = this._cfg.multiplier.start;
+    }
+    advanceMultiplier() {
+        const m = this._cfg.multiplier;
+        if (!m.enabled)
+            return;
+        const next = m.mode === 'mul' ? this._mult * m.step : this._mult + m.step;
+        this._mult = m.cap != null ? Math.min(next, m.cap) : next;
+    }
+    /** Derive survivor slides for one column when explicit drops aren't supplied. */
+    deriveDrops(step) {
+        const removedByCol = new Map();
+        for (const r of step.removedCells) {
+            if (!removedByCol.has(r.col))
+                removedByCol.set(r.col, new Set());
+            removedByCol.get(r.col).add(r.row);
+        }
+        const out = [];
+        for (const [col, removed] of removedByCol) {
+            const rows = this._grid.rowsOf(col);
+            // survivors keep order and fall to the bottom; count holes below each survivor
+            const survivors = [];
+            for (let r = 0; r < rows; r++)
+                if (!removed.has(r))
+                    survivors.push(r);
+            const newCount = rows - survivors.length;
+            survivors.forEach((fromRow, i) => {
+                const toRow = newCount + i;
+                if (toRow !== fromRow)
+                    out.push({ col, fromRow, toRow });
+            });
+        }
+        return out;
+    }
+    /** Run a single cascade step. `stepIndex` drives per-step deceleration. */
+    async step(step, stepIndex = 0, opts) {
+        if (this._grid.destroyed)
+            return;
+        if (!this._cfg.enabled) {
+            this._grid.setGrid(step.settledGrid);
+            return;
+        }
+        this._killed = false;
+        const turbo = opts?.turbo ? 0.5 : 1;
+        const decel = Math.min(this._cfg.perStepDecelCap, 1 + stepIndex * this._cfg.perStepDecel);
+        const f = turbo * decel;
+        const t = this._cfg.timings;
+        // 1. highlight winners (+ dim others). win.highlightScale / win.glow drive the pop.
+        const winSet = new Set(step.winningCells.map((w) => `${w.col}:${w.row}`));
+        const dimmed = this._cfg.dimNonWinners && step.winningCells.length > 0;
+        if (dimmed)
+            this._dim(winSet);
+        const hs = this._win.highlightScale;
+        await Promise.all(step.winningCells.map((w) => {
+            const cell = this._grid.getCell(w.col, w.row);
+            if (this._win.glow)
+                cell.setState({ winning: true });
+            return Tween.to(cell, { 'scale.x': hs, 'scale.y': hs }, t.highlight * f, easingByName(this._cfg.easings.highlight));
+        }));
+        if (this._dead) {
+            if (dimmed)
+                this._undim();
+            return;
+        }
+        await Tween.delay(t.wait * f);
+        // 2. remove the cleared cells (removedCells, falling back to winningCells)
+        const cleared = step.removedCells.length ? step.removedCells : step.winningCells;
+        await Promise.all(cleared.map((w) => {
+            const cell = this._grid.getCell(w.col, w.row);
+            return Tween.to(cell, { 'scale.x': 0, 'scale.y': 0, alpha: 0 }, t.remove * f, easingByName(this._cfg.easings.remove));
+        }));
+        if (this._dead) {
+            if (dimmed)
+                this._undim();
+            return;
+        }
+        for (const w of cleared) {
+            const cell = this._grid.getCell(w.col, w.row);
+            cell.setData({ symbol: null });
+            cell.setState({});
+            cell.scale.set(1);
+            cell.alpha = 1;
+        }
+        this._undim();
+        // 3. gravity: survivors slide down, new cells drop from above
+        const rowStep = this._grid.cellPosition(0, 1).y - this._grid.cellPosition(0, 0).y;
+        const slides = this._cfg.gravity ? (step.drops ?? this.deriveDrops(step)) : [];
+        const anims = [];
+        for (const d of slides) {
+            const cell = this._grid.getCell(d.col, d.toRow);
+            const home = this._grid.cellPosition(d.col, d.toRow);
+            cell.setData(step.settledGrid[d.col]?.[d.toRow] ?? { symbol: null });
+            cell.alpha = 1;
+            cell.scale.set(1);
+            cell.position.set(home.x, this._grid.cellPosition(d.col, d.fromRow).y);
+            anims.push(Tween.to(cell, { 'position.y': home.y }, t.drop * f, easingByName(this._cfg.easings.drop)));
+        }
+        const perCol = {};
+        for (const n of step.newCells) {
+            const cell = this._grid.getCell(n.col, n.row);
+            const home = this._grid.cellPosition(n.col, n.row);
+            cell.setData({ symbol: n.symbol });
+            cell.setState({ fresh: true });
+            cell.alpha = 1;
+            cell.scale.set(1);
+            cell.position.set(home.x, home.y - rowStep * (this._grid.rowsOf(n.col) + 1));
+            const idx = (perCol[n.col] = (perCol[n.col] ?? 0) + 1);
+            anims.push((async () => {
+                await Tween.delay(idx * 28 * f);
+                if (this._dead)
+                    return;
+                await Tween.to(cell, { 'position.y': home.y }, t.refill * f, easingByName(this._cfg.easings.drop));
+                cell.setState({});
+            })());
+        }
+        await Promise.all(anims);
+        if (this._dead)
+            return;
+        // 4. normalise + advance multiplier
+        this._grid.setGrid(step.settledGrid);
+        this._resetPositions();
+        if (step.winningCells.length)
+            this.advanceMultiplier();
+    }
+    _dim(winSet) {
+        for (let c = 0; c < this._grid.cols; c++)
+            for (let r = 0; r < this._grid.rowsOf(c); r++)
+                if (!winSet.has(`${c}:${r}`))
+                    this._grid.getCell(c, r).alpha = this._cfg.dimAlpha;
+    }
+    _undim() {
+        for (let c = 0; c < this._grid.cols; c++)
+            for (let r = 0; r < this._grid.rowsOf(c); r++) {
+                const cell = this._grid.getCell(c, r);
+                if (cell.alpha !== 0)
+                    cell.alpha = 1;
+            }
+    }
+    _resetPositions() {
+        if (this._grid.destroyed)
+            return;
+        for (let c = 0; c < this._grid.cols; c++)
+            for (let r = 0; r < this._grid.rowsOf(c); r++) {
+                const cell = this._grid.getCell(c, r);
+                const { x, y } = this._grid.cellPosition(c, r);
+                cell.position.set(x, y);
+                cell.scale.set(1);
+                cell.alpha = 1;
+            }
+    }
+    skip() {
+        this._killed = true;
+        for (let c = 0; c < this._grid.cols; c++)
+            for (let r = 0; r < this._grid.rowsOf(c); r++)
+                Tween.killTweensOf(this._grid.getCell(c, r));
+        this._resetPositions();
+    }
+}
+
+// packages/game-engine/src/slot/features/types.ts
+//
+// Uniform interface for special reel feature mechanics. Each feature is a presentation module:
+// given the current board + its config (and optional per-spin data), it plays an animation that
+// visualises the mechanic. `demo()` is the self-contained showcase the reel-lab playground triggers.
+// ── shared animation helpers ────────────────────────────────────────────────
+/** Center position of a cell, in fx-layer coordinates (fx shares the grid's transform). */
+function cellCenter(grid, col, row) {
+    return grid.cellPosition(col, row);
+}
+function rowStepOf(grid) {
+    return grid.cellPosition(0, 1).y - grid.cellPosition(0, 0).y;
+}
+/** A glowing ring drawn around a cell. Returns a disposer. */
+function glowRing(fx, grid, col, row, color) {
+    if (fx.destroyed)
+        return () => { };
+    const { x, y } = cellCenter(grid, col, row);
+    const s = grid.cellSize;
+    const g = new pixi_js.Graphics()
+        .roundRect(x - s / 2, y - s / 2, s, s, 10)
+        .stroke({ color, width: 3, alpha: 0.9 });
+    fx.addChild(g);
+    return () => g.destroy();
+}
+/** Pulse a cell up and back. */
+async function pulseCell(cell, scale = 1.15, ms = 220) {
+    if (cell.destroyed)
+        return;
+    await Tween.to(cell, { 'scale.x': scale, 'scale.y': scale }, ms * 0.5, easingByName('easeOutBack'));
+    if (cell.destroyed)
+        return;
+    await Tween.to(cell, { 'scale.x': 1, 'scale.y': 1 }, ms * 0.5, easingByName('easeOutQuad'));
+}
+/** Floating label that rises and fades. */
+async function floatLabel(fx, x, y, text, color = 0xffd24a, ms = 700) {
+    if (fx.destroyed)
+        return;
+    const t = new pixi_js.Text({ text, style: { fontSize: 26, fill: color, fontWeight: '800' } });
+    t.anchor.set(0.5);
+    t.position.set(x, y);
+    t.scale.set(0.5);
+    fx.addChild(t);
+    await Tween.to(t, { 'scale.x': 1, 'scale.y': 1 }, ms * 0.25, easingByName('easeOutBack'));
+    await Tween.to(t, { y: y - 50, alpha: 0 }, ms * 0.75, easingByName('easeOutQuad'));
+    t.destroy();
+}
+/** Replace a cell's symbol with a quick morph (shrink → swap → pop). */
+async function morphSymbol(cell, data, ms = 280) {
+    if (cell.destroyed)
+        return;
+    await Tween.to(cell, { 'scale.x': 0.1, 'scale.y': 0.1 }, ms * 0.4, easingByName('easeInBack'));
+    if (cell.destroyed)
+        return;
+    cell.setData(data);
+    cell.scale.set(0.1);
+    await Tween.to(cell, { 'scale.x': 1, 'scale.y': 1 }, ms * 0.6, easingByName('easeOutBack'));
+}
+/** Drop a cell in from above its home position. */
+async function dropCell(grid, cell, col, row, ms = 280) {
+    if (cell.destroyed)
+        return;
+    const home = grid.cellPosition(col, row);
+    cell.position.set(home.x, home.y - rowStepOf(grid) * (row + 2));
+    cell.alpha = 1;
+    cell.scale.set(1);
+    await Tween.to(cell, { 'position.y': home.y }, ms, easingByName('easeOutBounce'));
+}
+function pickFromBoard(board, predicate) {
+    const out = [];
+    for (let c = 0; c < board.length; c++)
+        for (let r = 0; r < (board[c]?.length ?? 0); r++)
+            if (board[c][r] && predicate(board[c][r], c, r))
+                out.push({ col: c, row: r });
+    return out;
+}
+
+// packages/game-engine/src/slot/features/wilds.ts
+function reelsOf(cfg, cols) {
+    return cfg.length
+        ? cfg.filter((r) => r >= 0 && r < cols)
+        : Array.from({ length: cols }, (_, i) => i);
+}
+const randInt = (a, b, seed) => Math.min(b, a + Math.floor(((Math.sin(seed * 99.13) + 1) / 2) * (b - a + 1)));
+/** Expanding wild: a landed wild grows to fill its whole reel. */
+const ExpandingWild = {
+    key: 'expandingWild',
+    label: 'Expanding wild',
+    enabled: (c) => c.features.expandingWild.enabled,
+    async demo(ctx) {
+        const f = ctx.cfg.features.expandingWild;
+        if (f.onlyInFreeSpins && !ctx.freeSpins) {
+            ctx.log?.('Expanding wild: free-spins only');
+            return;
+        }
+        const cols = ctx.grid.cols;
+        const eligible = reelsOf(f.reels, cols);
+        const reel = eligible[randInt(0, eligible.length - 1, cols)];
+        const rows = ctx.grid.rowsOf(reel);
+        ctx.log?.(`Expanding wild on reel ${reel}`);
+        const disposers = [];
+        for (let r = 0; r < (f.toFullReel ? rows : Math.min(2, rows)); r++) {
+            const cell = ctx.grid.getCell(reel, r);
+            await morphSymbol(cell, { symbol: f.symbol }, f.ms / Math.max(1, rows));
+            disposers.push(glowRing(ctx.fx, ctx.grid, reel, r, 0xffd700));
+            if (ctx.board[reel])
+                ctx.board[reel][r] = { symbol: f.symbol };
+        }
+        await Tween.delay(500);
+        disposers.forEach((d) => d());
+    },
+};
+/** Sticky symbols: chosen symbols lock in place for N spins. */
+const StickySymbols = {
+    key: 'sticky',
+    label: 'Sticky symbols',
+    enabled: (c) => c.features.sticky.enabled,
+    async demo(ctx) {
+        const f = ctx.cfg.features.sticky;
+        const targets = pickFromBoard(ctx.board, (c) => !!c.symbol).slice(0, 3);
+        const picks = targets.filter((_, i) => i % 2 === 0);
+        ctx.log?.(`Sticky: locking ${picks.length} cell(s) for ${f.durationSpins || 'feature'} spins`);
+        await Promise.all(picks.map(async (p, i) => {
+            const cell = ctx.grid.getCell(p.col, p.row);
+            cell.setData({ symbol: f.symbols[0] ?? 'wild', sticky: { remaining: f.durationSpins } });
+            glowRing(ctx.fx, ctx.grid, p.col, p.row, f.ringColor);
+            await pulseCell(cell, 1.2, 260);
+            const { x, y } = cellCenter(ctx.grid, p.col, p.row);
+            await floatLabel(ctx.fx, x, y - ctx.grid.cellSize / 2, f.durationSpins ? `STICKY ${f.durationSpins}` : 'STICKY', f.ringColor, 600 + i * 50);
+        }));
+    },
+};
+/** Walking wild: a wild shifts one reel each spin until it leaves the grid. */
+const WalkingWild = {
+    key: 'walkingWild',
+    label: 'Walking wild',
+    enabled: (c) => c.features.walkingWild.enabled,
+    async demo(ctx) {
+        const f = ctx.cfg.features.walkingWild;
+        const cols = ctx.grid.cols;
+        const dir = f.direction === 'left' ? -1 : 1;
+        let col = dir === 1 ? 0 : cols - 1;
+        // clamp the row into each reel's own height (Megaways reels differ in length)
+        const rowIn = (c) => Math.min(Math.floor(ctx.grid.rowsOf(col) / 2), ctx.grid.rowsOf(c) - 1);
+        let row = rowIn(col);
+        await morphSymbol(ctx.grid.getCell(col, row), { symbol: f.symbol }, 240);
+        ctx.log?.(`Walking wild marching ${f.direction}`);
+        // walk across the grid
+        for (let step = 0; step < cols; step++) {
+            const next = col + dir * f.stepPerSpin;
+            if (next < 0 || next >= cols)
+                break;
+            const nextRow = rowIn(next);
+            const from = cellCenter(ctx.grid, col, row);
+            const to = cellCenter(ctx.grid, next, nextRow);
+            ctx.grid.getCell(col, row).setData({ symbol: null });
+            const ghost = ctx.grid.getCell(next, nextRow);
+            ghost.setData({ symbol: f.symbol });
+            ghost.position.set(from.x, from.y);
+            const ring = glowRing(ctx.fx, ctx.grid, next, nextRow, 0xff66cc);
+            await Tween.to(ghost, { 'position.x': to.x, 'position.y': to.y }, 260, easingByName('easeInOutQuad'));
+            ring();
+            col = next;
+            row = nextRow;
+        }
+    },
+};
+/** Random wild injection: a few wilds drop onto random positions. */
+const RandomWild = {
+    key: 'randomWild',
+    label: 'Random wild injection',
+    enabled: (c) => c.features.randomWild.enabled,
+    async demo(ctx) {
+        const f = ctx.cfg.features.randomWild;
+        const n = Array.isArray(f.count) ? randInt(f.count[0], f.count[1], ctx.grid.cols + 7) : f.count;
+        const spots = pickFromBoard(ctx.board, () => true);
+        const chosen = [];
+        for (let i = 0; i < n && spots.length; i++)
+            chosen.push(spots.splice(randInt(0, spots.length - 1, i + 3), 1)[0]);
+        ctx.log?.(`Injecting ${chosen.length} wild(s)${f.sticky ? ' (sticky)' : ''}${f.multiplier > 1 ? ` ×${f.multiplier}` : ''}`);
+        await Promise.all(chosen.map(async (p) => {
+            const cell = ctx.grid.getCell(p.col, p.row);
+            cell.setData({
+                symbol: 'wild',
+                multiplier: f.multiplier > 1 ? f.multiplier : undefined,
+                sticky: f.sticky ? { remaining: 0 } : undefined,
+            });
+            await dropCell(ctx.grid, cell, p.col, p.row, 300);
+            if (f.sticky)
+                glowRing(ctx.fx, ctx.grid, p.col, p.row, 0xec4899);
+        }));
+    },
+};
+
+// packages/game-engine/src/slot/features/symbols.ts
+const pick = (arr, seed) => arr[Math.floor(((Math.sin(seed * 12.9898) + 1) / 2) * arr.length) % arr.length];
+/** Mystery symbols: all mystery tiles reveal the SAME single random symbol per spin. */
+const MysterySymbols = {
+    key: 'mystery',
+    label: 'Mystery symbols',
+    enabled: (c) => c.features.mystery.enabled,
+    async demo(ctx) {
+        const f = ctx.cfg.features.mystery;
+        const spots = pickFromBoard(ctx.board, () => true)
+            .filter((_, i) => i % 3 === 0)
+            .slice(0, 5);
+        spots.forEach((p) => ctx.grid.getCell(p.col, p.row).setData({ symbol: f.symbol }));
+        await Promise.all(spots.map((p) => pulseCell(ctx.grid.getCell(p.col, p.row), 1.1, 200)));
+        const pool = f.revealPool.length ? f.revealPool : ['h1', 'h2', 'h3'];
+        const reveal = pick(pool, ctx.grid.cols + spots.length);
+        ctx.log?.(`Mystery: ${spots.length} tiles reveal "${reveal}"`);
+        await Promise.all(spots.map((p) => morphSymbol(ctx.grid.getCell(p.col, p.row), { symbol: reveal }, f.ms)));
+        spots.forEach((p) => {
+            if (ctx.board[p.col])
+                ctx.board[p.col][p.row] = { symbol: reveal };
+        });
+    },
+};
+/** Symbol transform / upgrade: every instance of one symbol type becomes another. */
+const SymbolTransform = {
+    key: 'transform',
+    label: 'Symbol transform / upgrade',
+    enabled: (c) => c.features.transform.enabled,
+    async demo(ctx) {
+        const f = ctx.cfg.features.transform;
+        const present = Array.from(new Set(pickFromBoard(ctx.board, (c) => !!c.symbol).map((p) => ctx.board[p.col][p.row].symbol)));
+        const lows = present.filter((s) => /^(l|o|a|k|q|j|t|10)/i.test(s));
+        const source = f.source === 'randomLow'
+            ? (pick(lows.length ? lows : present, ctx.grid.cols) ?? present[0])
+            : f.source;
+        if (!source) {
+            ctx.log?.('Transform: nothing to convert');
+            return;
+        }
+        const matches = pickFromBoard(ctx.board, (c) => c.symbol === source);
+        const targets = f.allInstances ? matches : matches.slice(0, 1);
+        ctx.log?.(`Transform: ${targets.length}× "${source}" → "${f.target}"`);
+        await Promise.all(targets.map(async (p, i) => {
+            await Tween.delay(i * 40);
+            await morphSymbol(ctx.grid.getCell(p.col, p.row), { symbol: f.target }, f.ms);
+            if (ctx.board[p.col])
+                ctx.board[p.col][p.row] = { symbol: f.target };
+        }));
+    },
+};
+/** Giant / colossal symbol spanning width×height cells. */
+const GiantSymbol = {
+    key: 'giant',
+    label: 'Giant / colossal symbol',
+    enabled: (c) => c.features.giant.enabled,
+    async demo(ctx) {
+        const f = ctx.cfg.features.giant;
+        if (f.onlyInFreeSpins && !ctx.freeSpins) {
+            ctx.log?.('Giant: free-spins only');
+            return;
+        }
+        const cols = ctx.grid.cols;
+        const w = Math.min(f.width, cols);
+        const anchorCol = Math.max(0, Math.floor((cols - w) / 2));
+        // span only as tall as the SHORTEST covered reel so every covered cell exists (Megaways-safe)
+        let minRows = ctx.grid.rowsOf(anchorCol);
+        for (let c = anchorCol; c < anchorCol + w; c++)
+            minRows = Math.min(minRows, ctx.grid.rowsOf(c));
+        const h = Math.min(f.height, minRows);
+        const sym = f.symbols.length ? pick(f.symbols, cols) : 'h1';
+        ctx.log?.(`Giant ${w}×${h} "${sym}"`);
+        const view = ctx.resolve(sym);
+        if (!view)
+            return;
+        const step = rowStepOf(ctx.grid);
+        const tl = cellCenter(ctx.grid, anchorCol, 0);
+        const giant = new pixi_js.Container();
+        giant.addChild(view);
+        view.resize?.(ctx.grid.cellSize * Math.max(w, h));
+        if (view.scale)
+            view.scale.set(((ctx.grid.cellSize * w) / (ctx.grid.cellSize * Math.max(w, h))) * view.scale.x, ((ctx.grid.cellSize * h) / (ctx.grid.cellSize * Math.max(w, h))) * view.scale.y);
+        giant.position.set(tl.x + ((w - 1) * step) / 2, tl.y + ((h - 1) * step) / 2);
+        // hide covered cells
+        for (let c = anchorCol; c < anchorCol + w; c++)
+            for (let r = 0; r < h; r++)
+                ctx.grid.getCell(c, r).visible = false;
+        giant.scale.set(0.2);
+        giant.alpha = 0;
+        ctx.fx.addChild(giant);
+        await Tween.to(giant, { 'scale.x': 1, 'scale.y': 1, alpha: 1 }, 420, easingByName('easeOutBack'));
+        await Tween.delay(600);
+        giant.destroy();
+        for (let c = anchorCol; c < anchorCol + w; c++)
+            for (let r = 0; r < h; r++)
+                ctx.grid.getCell(c, r).visible = true;
+    },
+};
+/** Split symbol (xSplit): doubles every symbol to its left. */
+const SplitSymbol = {
+    key: 'split',
+    label: 'Split symbol (xSplit)',
+    enabled: (c) => c.features.split.enabled,
+    async demo(ctx) {
+        const f = ctx.cfg.features.split;
+        const cols = ctx.grid.cols;
+        const splitReel = f.reels.length ? f.reels[0] : cols - 1;
+        const row = Math.floor(ctx.grid.rowsOf(splitReel) / 2);
+        await morphSymbol(ctx.grid.getCell(splitReel, row), { symbol: f.symbol }, 240);
+        ctx.log?.(`Split ×${f.factor}: doubling symbols left of reel ${splitReel}`);
+        const left = pickFromBoard(ctx.board, (_c, col) => col < splitReel);
+        await Promise.all(left.map(async (p, i) => {
+            await Tween.delay((i % 6) * 30);
+            const { x, y } = cellCenter(ctx.grid, p.col, p.row);
+            await pulseCell(ctx.grid.getCell(p.col, p.row), 1.12, 200);
+            await floatLabel(ctx.fx, x + ctx.grid.cellSize / 3, y - ctx.grid.cellSize / 3, `×${f.factor}`, 0x9b5cff, 600);
+        }));
+    },
+};
+/** Stacked symbols: a reel shows a full stack of one symbol. */
+const StackedSymbols = {
+    key: 'stacked',
+    label: 'Stacked symbols',
+    enabled: (c) => c.features.stacked.enabled,
+    async demo(ctx) {
+        const f = ctx.cfg.features.stacked;
+        const cols = ctx.grid.cols;
+        const reel = Math.floor(cols / 2);
+        const rows = ctx.grid.rowsOf(reel);
+        const sym = f.symbols.length ? pick(f.symbols, reel) : 'h1';
+        const height = Math.min(f.height, rows);
+        ctx.log?.(`Stacked "${sym}" ×${height} on reel ${reel}`);
+        const start = Math.floor((rows - height) / 2);
+        await Promise.all(Array.from({ length: height }, (_, i) => start + i).map(async (r, i) => {
+            await Tween.delay(i * 50);
+            const cell = ctx.grid.getCell(reel, r);
+            await morphSymbol(cell, { symbol: sym }, 220);
+            if (ctx.board[reel])
+                ctx.board[reel][r] = { symbol: sym };
+        }));
+    },
+};
+
+// packages/game-engine/src/slot/features/extra.ts
+const seeded = (a, b, seed) => Math.min(b, a + Math.floor(((Math.sin(seed * 53.17) + 1) / 2) * (b - a + 1)));
+/** Multiplier symbols: marked cells carry values that combine into the win. */
+const MultiplierSymbols = {
+    key: 'multiplier',
+    label: 'Multiplier symbols',
+    enabled: (c) => c.features.multiplier.enabled,
+    async demo(ctx) {
+        const f = ctx.cfg.features.multiplier;
+        const spots = pickFromBoard(ctx.board, () => true)
+            .filter((_, i) => i % 4 === 0)
+            .slice(0, 3);
+        const values = [2, 3, 5].slice(0, spots.length);
+        spots.forEach((p, i) => ctx.grid.getCell(p.col, p.row).setData({ symbol: f.symbol ?? 'wild', multiplier: values[i] }));
+        await Promise.all(spots.map((p) => pulseCell(ctx.grid.getCell(p.col, p.row), 1.2, 240)));
+        const total = f.combine === 'additive'
+            ? values.reduce((a, b) => a + b, 0)
+            : values.reduce((a, b) => a * b, 1);
+        const capped = Math.min(total, f.max);
+        ctx.log?.(`Multiplier (${f.combine}, ${f.scope}): ${values.join(f.combine === 'additive' ? ' + ' : ' × ')} = ×${capped}`);
+        // fly each value toward the centre, then show the combined total
+        await Promise.all(spots.map(async (p) => {
+            const { x, y } = cellCenter(ctx.grid, p.col, p.row);
+            await floatLabel(ctx.fx, x, y, `×${values[spots.indexOf(p)]}`, 0xffd24a, 500);
+        }));
+        const cx = (ctx.grid.cols * ctx.grid.cellSize) / 2 - ctx.grid.cellSize / 2;
+        const cy = (ctx.grid.rows * ctx.grid.cellSize) / 2 - ctx.grid.cellSize / 2;
+        await floatLabel(ctx.fx, cx, cy, `×${capped}`, 0xffe24a, 900);
+    },
+};
+/** Nudge / xNudge: a reel nudges one position (xNudge fills a stacked wild, +1 mult per nudge). */
+const NudgeReels = {
+    key: 'nudge',
+    label: 'Nudge / xNudge',
+    enabled: (c) => c.features.nudge.enabled,
+    async demo(ctx) {
+        const f = ctx.cfg.features.nudge;
+        const cols = ctx.grid.cols;
+        const reel = f.reels.length ? f.reels[0] : Math.floor(cols / 2);
+        const rows = ctx.grid.rowsOf(reel);
+        ctx.log?.(f.toFullReel ? `xNudge: filling reel ${reel} with wild` : `Nudge reel ${reel} by ${f.step}`);
+        if (f.toFullReel) {
+            let mult = f.multiplierStart;
+            for (let r = 0; r < rows; r++) {
+                const cell = ctx.grid.getCell(reel, r);
+                await morphSymbol(cell, { symbol: 'wild', multiplier: mult > 1 ? mult : undefined }, 160);
+                mult += f.multiplierPerNudge;
+            }
+            const { x, y } = cellCenter(ctx.grid, reel, Math.floor(rows / 2));
+            await floatLabel(ctx.fx, x, y, `×${mult - f.multiplierPerNudge}`, 0xff7a3c, 800);
+        }
+        else {
+            // shift the whole column down by `step` cells, then settle
+            const step = ctx.grid.cellPosition(reel, 1).y - ctx.grid.cellPosition(reel, 0).y;
+            const cells = Array.from({ length: rows }, (_, r) => ctx.grid.getCell(reel, r));
+            await Promise.all(cells.map((c) => Tween.to(c, { 'position.y': c.y + step * f.step }, 240, easingByName('easeOutBack'))));
+            cells.forEach((c, r) => c.position.set(ctx.grid.cellPosition(reel, r).x, ctx.grid.cellPosition(reel, r).y));
+        }
+    },
+};
+/** Hold-and-spin / Hold & Win: special symbols lock and respins reset on each new lock. */
+const HoldAndSpin = {
+    key: 'holdAndSpin',
+    label: 'Hold & Spin (respin)',
+    enabled: (c) => c.features.holdAndSpin.enabled,
+    async demo(ctx) {
+        const f = ctx.cfg.features.holdAndSpin;
+        const all = pickFromBoard(ctx.board, () => true);
+        const sym = f.lockSymbols[0] ?? 'coin';
+        const locked = new Set();
+        const lock = async (p, value) => {
+            const cell = ctx.grid.getCell(p.col, p.row);
+            cell.setData({ symbol: sym });
+            await dropCell(ctx.grid, cell, p.col, p.row, 240);
+            glowRing(ctx.fx, ctx.grid, p.col, p.row, 0xffcf5c);
+            const { x, y } = cellCenter(ctx.grid, p.col, p.row);
+            await floatLabel(ctx.fx, x, y, value, 0xffe24a, 500);
+            locked.add(`${p.col}:${p.row}`);
+        };
+        // trigger
+        const trigger = all.slice(0, f.triggerThreshold);
+        ctx.log?.(`Hold & Spin triggered with ${trigger.length} ${sym}`);
+        await Promise.all(trigger.map((p, i) => lock(p, `${(i + 1) * 5}`)));
+        let respins = f.respinsAwarded;
+        let round = 0;
+        while (respins > 0) {
+            round++;
+            const free = all.filter((p) => !locked.has(`${p.col}:${p.row}`));
+            const landed = free.filter((_, i) => seeded(0, 3, i + round * 3) === 0).slice(0, 2);
+            ctx.log?.(`Respin ${round}: ${respins} left` + (landed.length ? ` — ${landed.length} new lock` : ''));
+            if (landed.length && f.resetOnNewSymbol) {
+                respins = f.respinsAwarded;
+                await Promise.all(landed.map((p) => lock(p, 'JP')));
+            }
+            else
+                respins--;
+            if (locked.size >= all.length) {
+                ctx.log?.(f.fullGridAwardsGrand ? 'Full grid — GRAND!' : 'Full grid');
+                break;
+            }
+            await Tween.delay(120);
+        }
+        ctx.log?.(`Hold & Spin: ${locked.size} locked`);
+    },
+};
+/** Random pre-spin reel modifiers (add rows, inject wilds, set giant, guaranteed wilds). */
+const ReelModifier = {
+    key: 'reelModifier',
+    label: 'Random reel modifier',
+    enabled: (c) => c.features.reelModifier.enabled,
+    async demo(ctx) {
+        const f = ctx.cfg.features.reelModifier;
+        const pool = f.pool.length
+            ? f.pool
+            : [{ effect: 'addWilds', magnitude: 3, weight: 1 }];
+        const totalW = pool.reduce((a, m) => a + m.weight, 0);
+        let roll = ((Math.sin(ctx.grid.cols * 7.7) + 1) / 2) * totalW;
+        let mod = pool[0];
+        for (const m of pool) {
+            roll -= m.weight;
+            if (roll <= 0) {
+                mod = m;
+                break;
+            }
+        }
+        ctx.log?.(`Reel modifier: ${mod.effect} (+${mod.magnitude})`);
+        if (mod.effect === 'addRows') {
+            const next = ctx.grid.rowsPerReel.map((r) => r + mod.magnitude);
+            // grow the board (new cells on top) and keep the system config in sync so the new rows
+            // aren't blank and a later spin/rebuild doesn't revert the shape
+            for (let c = 0; c < ctx.board.length; c++) {
+                const col = ctx.board[c] ?? (ctx.board[c] = []);
+                const fill = col[0]?.symbol ?? 'h1';
+                for (let i = 0; i < mod.magnitude; i++)
+                    col.unshift({ symbol: fill });
+            }
+            ctx.cfg.grid.rowsPerReel = next;
+            ctx.grid.reshape(next);
+            ctx.grid.setGrid(ctx.board);
+        }
+        else if (mod.effect === 'addWilds' || mod.effect === 'guaranteedWilds') {
+            const spots = pickFromBoard(ctx.board, () => true);
+            const chosen = [];
+            for (let i = 0; i < mod.magnitude && spots.length; i++)
+                chosen.push(spots.splice(seeded(0, spots.length - 1, i), 1)[0]);
+            await Promise.all(chosen.map(async (p) => {
+                const cell = ctx.grid.getCell(p.col, p.row);
+                cell.setData({ symbol: 'wild' });
+                await dropCell(ctx.grid, cell, p.col, p.row, 280);
+            }));
+        }
+        else if (mod.effect === 'setGiant') {
+            const cell = ctx.grid.getCell(0, 0);
+            await pulseCell(cell, 1.3, 300);
+        }
+    },
+};
+
+/** All feature modules keyed by their FeatureKey. */
+const FEATURES = {
+    expandingWild: ExpandingWild,
+    sticky: StickySymbols,
+    walkingWild: WalkingWild,
+    randomWild: RandomWild,
+    mystery: MysterySymbols,
+    transform: SymbolTransform,
+    giant: GiantSymbol,
+    split: SplitSymbol,
+    stacked: StackedSymbols,
+    multiplier: MultiplierSymbols,
+    nudge: NudgeReels,
+    holdAndSpin: HoldAndSpin,
+    reelModifier: ReelModifier,
+};
+/** Features in canonical resolve order (see docs §3.4). */
+const FEATURE_LIST = FEATURE_KEYS.map((k) => FEATURES[k]);
+
+// packages/game-engine/src/slot/system/ReelSystem.ts
+//
+// The configurable reel system facade. `createReelSystem({ resolve, config })` builds a grid and
+// wires the spin engine, anticipation controller, tumble/cascade controller and the special-feature
+// registry — all driven by one `ReelSystemConfig`. Presentation only: it draws boards you feed it.
+/** Drop a `rowsPerReel` whose length no longer matches `cols` so geometry/ways stay consistent. */
+function normalizeGrid(cfg) {
+    if (cfg.grid.rowsPerReel && cfg.grid.rowsPerReel.length !== cfg.grid.cols) {
+        const next = { ...cfg, grid: { ...cfg.grid } };
+        delete next.grid.rowsPerReel;
+        return next;
+    }
+    return cfg;
+}
+function createReelSystem(opts) {
+    let config = normalizeGrid(resolveReelConfig(opts.config));
+    const resolve = opts.resolve;
+    const log = opts.log;
+    const view = new pixi_js.Container();
+    let grid;
+    let fx;
+    let spin;
+    let anticipation;
+    let tumble;
+    let board = opts.board ?? emptyBoard(config);
+    // custom features keyed by id; built-ins live in FEATURES/FEATURE_LIST
+    const custom = new Map();
+    for (const f of opts.features ?? [])
+        custom.set(f.key, f);
+    const allFeatures = () => {
+        const seen = new Set();
+        const out = [];
+        for (const f of [...FEATURE_LIST, ...custom.values()]) {
+            const eff = custom.get(f.key) ?? f; // a custom feature overrides a built-in with the same key
+            if (seen.has(eff.key))
+                continue;
+            seen.add(eff.key);
+            out.push(eff);
+        }
+        return out;
+    };
+    const findFeature = (key) => custom.get(key) ?? FEATURES[key];
+    function buildGrid() {
+        if (grid) {
+            spin?.skip();
+            tumble?.skip();
+            for (const child of fx?.children.slice() ?? [])
+                Tween.killTweensOf(child);
+            grid.destroy({ children: true });
+        }
+        grid = new ReelGrid({
+            cols: config.grid.cols,
+            rows: config.grid.rows,
+            rowsPerReel: config.grid.rowsPerReel ?? effectiveRowsPerReel(config.grid),
+            cellSize: config.grid.cellSize,
+            gap: config.grid.gap,
+            resolve,
+            frameStyle: config.grid.frameStyle,
+            mask: config.grid.mask,
+            decoration: config.grid.decoration?.padding
+                ? { padding: config.grid.decoration.padding }
+                : undefined,
+        });
+        fx = new pixi_js.Container();
+        grid.addChild(fx);
+        view.addChild(grid);
+        spin = new SpinEngine(grid, resolve, config.motion, config.win);
+        anticipation = new AnticipationController(config.anticipation);
+        tumble = new TumbleController(grid, config.cascade, config.win);
+        grid.setGrid(board);
+    }
+    function geometryChanged(next) {
+        const a = config.grid, b = next.grid;
+        return (a.cols !== b.cols ||
+            a.rows !== b.rows ||
+            a.cellSize !== b.cellSize ||
+            a.gap !== b.gap ||
+            a.mask !== b.mask ||
+            JSON.stringify(a.rowsPerReel) !== JSON.stringify(b.rowsPerReel) ||
+            (a.decoration?.padding ?? 0) !== (b.decoration?.padding ?? 0));
+    }
+    function ctx(freeSpins) {
+        return { grid, resolve, cfg: config, fx, board, freeSpins, log };
+    }
+    buildGrid();
+    const api = {
+        view,
+        get grid() {
+            return grid;
+        },
+        get fx() {
+            return fx;
+        },
+        get config() {
+            return config;
+        },
+        get board() {
+            return board;
+        },
+        get ways() {
+            return waysCount(config.grid);
+        },
+        setBoard(next) {
+            board = next;
+            // grow the board to the grid shape so feature code can index safely
+            grid.setGrid(next);
+        },
+        setConfig(next) {
+            const norm = normalizeGrid(next);
+            const rebuild = geometryChanged(norm);
+            config = norm;
+            if (rebuild)
+                buildGrid();
+            else {
+                spin.setConfig(config.motion);
+                spin.setWin(config.win);
+                anticipation.setConfig(config.anticipation);
+                tumble.setConfig(config.cascade);
+                tumble.setWin(config.win);
+            }
+        },
+        update(partial) {
+            api.setConfig(mergeReelConfig(config, partial));
+        },
+        async spin(target, runOpts) {
+            const data = { targetGrid: target };
+            const decision = anticipation.decide(target);
+            let resetZoom = null;
+            if (decision.active) {
+                log?.(`Anticipation on reels [${decision.reels.join(', ')}]`);
+                resetZoom = await anticipation.zoomIn(grid);
+            }
+            await spin.run(data, {
+                ...runOpts,
+                anticipateReels: decision.active ? decision.reels : undefined,
+                anticipateSlowdown: decision.slowdown,
+                anticipateHoldMs: decision.holdMs,
+            });
+            if (resetZoom)
+                await resetZoom();
+            board = target;
+        },
+        get multiplier() {
+            return tumble.multiplier;
+        },
+        async cascade(steps, cOpts) {
+            // keep the multiplier climbing across free-spins when configured; otherwise reset per spin
+            const persist = config.cascade.multiplier.persistInFreeSpins && !!cOpts?.freeSpins;
+            if (!persist)
+                tumble.resetMultiplier();
+            for (let i = 0; i < steps.length; i++) {
+                await tumble.step(steps[i], i, cOpts);
+                board = steps[i].settledGrid;
+            }
+            if (config.cascade.multiplier.enabled)
+                log?.(`Cascade multiplier ×${tumble.multiplier}`);
+        },
+        registerFeature(feature) {
+            custom.set(feature.key, feature);
+        },
+        features() {
+            return allFeatures();
+        },
+        enabledFeatures() {
+            return allFeatures().filter((f) => f.enabled(config));
+        },
+        featureContext(fOpts) {
+            return ctx(fOpts?.freeSpins);
+        },
+        async runFeature(key, fOpts) {
+            const feature = findFeature(key);
+            if (!feature) {
+                log?.(`Unknown feature "${key}"`);
+                return;
+            }
+            if (!feature.enabled(config)) {
+                log?.(`${feature.label} is disabled`);
+                return;
+            }
+            await feature.demo(ctx(fOpts?.freeSpins));
+        },
+        resize(cellSize) {
+            config = mergeReelConfig(config, { grid: { cellSize } });
+            grid.resize(cellSize);
+        },
+        skip() {
+            spin.skip();
+            tumble.skip();
+            // kill in-flight overlay tweens (labels/rings) so a rebuild never animates destroyed nodes
+            for (const child of fx.children.slice())
+                Tween.killTweensOf(child);
+            fx.removeChildren().forEach((c) => c.destroy());
+        },
+        destroy() {
+            api.skip();
+            grid.destroy({ children: true });
+            view.destroy({ children: true });
+        },
+    };
+    return api;
+}
+function emptyBoard(cfg) {
+    const rows = effectiveRowsPerReel(cfg.grid);
+    return Array.from({ length: cfg.grid.cols }, (_, c) => Array.from({ length: rows[c] }, () => ({ symbol: null })));
+}
+
 /** Highest tier whose minMultiplier <= win/bet, or null if below the lowest. */
 function pickTier(tiers, win, bet) {
     if (bet <= 0)
@@ -930,35 +2754,6 @@ class BigWinOverlay extends pixi_js.Container {
     hide() { this.visible = false; Tween.killTweensOf(this); }
 }
 
-/** Headless free-spins state machine. The scene drives it; rendering/HUD reflect it. */
-class FreeSpinsSession {
-    remaining;
-    total;
-    totalWin = 0;
-    cfg;
-    constructor(cfg) {
-        this.cfg = cfg;
-        this.remaining = cfg.initialSpins;
-        this.total = cfg.initialSpins;
-    }
-    award(extra) {
-        if (extra > 0) {
-            this.remaining += extra;
-            this.total += extra;
-        }
-    }
-    /** Convenience: award using the configured retrigger rule. */
-    applyRetrigger(result) {
-        this.award(this.cfg.retrigger?.(result) ?? 0);
-    }
-    addWin(amount) { this.totalWin += amount; }
-    consume() { if (this.remaining > 0)
-        this.remaining -= 1; }
-    get isComplete() {
-        return this.remaining <= 0 || (this.cfg.isMaxWin?.() ?? false);
-    }
-}
-
 // How long each policy survives: cascade (shortest) < spin < session (longest).
 const RANK = { cascade: 0, spin: 1, session: 2 };
 /**
@@ -984,15 +2779,31 @@ class MultiplierAccumulator {
 }
 
 exports.AnimatedSymbol = AnimatedSymbol;
+exports.AnticipationController = AnticipationController;
 exports.BigWinOverlay = BigWinOverlay;
 exports.CascadeController = CascadeController;
 exports.CountUpDisplay = CountUpDisplay;
-exports.FreeSpinsSession = FreeSpinsSession;
+exports.DEFAULT_REEL_CONFIG = DEFAULT_REEL_CONFIG;
+exports.EASING_BY_NAME = EASING_BY_NAME;
+exports.FEATURES = FEATURES;
+exports.FEATURE_KEYS = FEATURE_KEYS;
+exports.FEATURE_LIST = FEATURE_LIST;
+exports.INTENSITY_SCALE = INTENSITY_SCALE;
 exports.MultiplierAccumulator = MultiplierAccumulator;
+exports.PRESETS = PRESETS;
+exports.PRESET_LIST = PRESET_LIST;
 exports.ReelGrid = ReelGrid;
 exports.ReelSpinController = ReelSpinController;
+exports.SpinEngine = SpinEngine;
 exports.SymbolCell = SymbolCell;
+exports.TumbleController = TumbleController;
+exports.createReelSystem = createReelSystem;
+exports.easingByName = easingByName;
+exports.effectiveRowsPerReel = effectiveRowsPerReel;
+exports.mergeReelConfig = mergeReelConfig;
 exports.pickTier = pickTier;
+exports.resolveReelConfig = resolveReelConfig;
 exports.tierIndexAtValue = tierIndexAtValue;
 exports.valueAt = valueAt;
+exports.waysCount = waysCount;
 //# sourceMappingURL=slot.cjs.js.map