@energy8platform/game-engine 0.37.0 → 0.39.0

package/src/host/shellConfig.ts

@@ -66,6 +66,11 @@ export interface ShellRuntime {
   /** Jurisdiction flags from initData (`config.jurisdiction`). Restrict shell features — applied
    *  OVER the author's features so a jurisdiction restriction always wins. */
   jurisdiction?: JurisdictionRestrictions;
+  /** The client the platform launched us on (`initData.device`; both bridges read it off the launch
+   *  URL). `'mobile'` turns the whole keyboard surface off — the shortcuts and the Hotkeys section
+   *  that documents them. Left unset the shell measures the client itself (shell's core/device.ts);
+   *  the host only speaks when the platform told it outright. */
+  device?: 'desktop' | 'mobile' | string;
   /** Bet ladder from `/wallet/authenticate` (`initData.config.betLevels`, major units). Stake ladders
    *  are CURRENCY-SPECIFIC (us_/non_us_/social_), so this overrides the spec's static `betLevels` on a
    *  Stake launch; falls back to the spec on dev/devBridge. */
@@ -201,6 +206,9 @@ export function toBonusOptions(model: GameModel, t: (s: string) => string = (s)
       // Hero art (SSOT) → card thumbnail. Passed verbatim: the shell loads it as-is, so no URL
       // resolver is needed (matches a static buyBonus `thumbnail`). Keeps i18n/price/accent/social.
       ...(action.art ? { thumbnail: action.art } : {}),
+      // Variant grouping (SSOT): actions sharing the key share one card in the pixi shell, flipped
+      // through with arrows. Each stays its own action, so the id on activate/buy is unambiguous.
+      ...(action.groupedBy ? { groupedBy: action.groupedBy } : {}),
     });
   }
   return out;
@@ -489,6 +497,10 @@ export function buildShellConfig(
     ...(opts.features ?? {}),
   } as ShellFeatures;
   applyJurisdiction(features, runtime.jurisdiction);
+  // A phone has no keys to press: no Spacebar-to-spin, and no keycap chart advertising it. Applied
+  // after the author's features for the same reason a jurisdiction restriction is — the platform
+  // knows what it launched us on, and a game can't opt out of the hardware.
+  if (runtime.device === 'mobile') features.hotkeys = false;
   return {
     language: runtime.language ?? 'en',
     isSocial,

package/src/slot/config/ReelSystemConfig.ts

@@ -7,7 +7,7 @@
 //
 // Design notes are in docs/reels-analysis-and-design.md.
 
-import type { CellFrameStyle } from '../grid/SymbolCell';
+import type { CellData, CellFrameStyle } from '../grid/SymbolCell';
 import { resolveGeometry, type CellSizeSpec, type ResolvedGeometry } from '../grid/geometry';
 
 export type { CellSizeSpec, ResolvedGeometry };
@@ -31,6 +31,20 @@ export type EasingName =
   | 'easeOutSine'
   | 'easeInOutSine';
 
+/**
+ * A value that is either flat across the board, or per-reel: an array indexed by REEL INDEX
+ * (holes fall back to the scalar default). Used for anticipation timings so a game can make
+ * each successive reel slower than the last.
+ */
+export type PerReel<T> = T | (T | undefined)[];
+
+/** Resolve a `PerReel<T>` for one reel. `undefined` (or a hole in the array) yields `fallback`. */
+export function perReelValue<T>(value: PerReel<T> | undefined, reel: number, fallback: T): T {
+  if (value === undefined) return fallback;
+  if (Array.isArray(value)) return (value[reel] as T | undefined) ?? fallback;
+  return value;
+}
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Grid
 // ─────────────────────────────────────────────────────────────────────────────
@@ -127,12 +141,28 @@ export interface MotionConfig {
   slamStop: boolean;
   /** Symbols visible on a reel tape while spinning (swap/strip). */
   symbolsPerReel: number;
+  /** `cascade-drop`: ms between consecutive cells of ONE reel (top→bottom). Default 24. */
+  cellStagger: number;
+  /** `cascade-drop`: multiplier on `stopStagger` for the per-reel offset. Default 0.4. */
+  reelStaggerFactor: number;
+  /** `cascade-drop`: fall duration as a fraction of `spinUp`. Default 0.6. */
+  dropFallFactor: number;
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Anticipation
 // ─────────────────────────────────────────────────────────────────────────────
 
+/** What a game-supplied `AnticipationConfig.decide` may return instead of a bare reel list. */
+export interface AnticipationOverride {
+  /** Reels to anticipate, in the order the progression should ramp. Empty = no anticipation. */
+  reels: number[];
+  /** Speed factor (lower = slower). Scalar, or per-reel indexed by reel index. */
+  slowdown?: PerReel<number>;
+  /** Extra hold before landing. Scalar, or per-reel indexed by reel index. */
+  holdMs?: PerReel<number>;
+}
+
 export interface AnticipationConfig {
   enabled: boolean;
   /** Symbols that count toward the anticipation threshold (scatter/bonus). */
@@ -145,6 +175,21 @@ export interface AnticipationConfig {
   slowdownFactor: number;
   /** Extra hold (ms) before the final anticipation reel lands (300–500 typical). */
   holdMs: number;
+  /**
+   * Game-supplied decision, REPLACING the built-in `triggerSymbols`/`threshold` counting.
+   * Return the reels to anticipate (or an `AnticipationOverride`); `null` / `[]` = no anticipation.
+   * Use this when the trigger is not expressible as "N of symbol X landed" — e.g. "the round is
+   * still alive on every reel so far", or "reel 3 missed its symbol, so let 4 and 5 stop normally".
+   */
+  decide?: ((targetGrid: CellData[][]) => number[] | AnticipationOverride | null) | null;
+  /**
+   * Ramp the slowdown across successive anticipated reels: reel #i of the decision gets
+   * `slowdownFactor * progressiveSlowdown ** i`. 1 = flat (default); < 1 = each reel slower
+   * than the last.
+   */
+  progressiveSlowdown: number;
+  /** Extra hold (ms) added per successive anticipated reel: reel #i gets `holdMs + i * this`. */
+  progressiveHoldMs: number;
   /** Optional grid zoom while anticipating (magnum-opus uses 1.3×). */
   zoom: { enabled: boolean; scale: number; ms: number };
 }
@@ -419,6 +464,9 @@ export const DEFAULT_REEL_CONFIG: ReelSystemConfig = {
     intensity: 'full',
     slamStop: true,
     symbolsPerReel: 6,
+    cellStagger: 24,
+    reelStaggerFactor: 0.4,
+    dropFallFactor: 0.6,
   },
   anticipation: {
     enabled: false,
@@ -427,6 +475,9 @@ export const DEFAULT_REEL_CONFIG: ReelSystemConfig = {
     reels: 'trailing',
     slowdownFactor: 0.3,
     holdMs: 400,
+    decide: null,
+    progressiveSlowdown: 1,
+    progressiveHoldMs: 0,
     zoom: { enabled: false, scale: 1.15, ms: 600 },
   },
   cascade: {
@@ -555,10 +606,26 @@ export function resolveReelConfig(partial?: DeepPartial<ReelSystemConfig>): Reel
   return mergeReelConfig(DEFAULT_REEL_CONFIG, partial);
 }
 
+/** True only for `{}`-shaped objects — a class instance or a Date is NOT one. */
+function isCloneableRecord(v: unknown): v is Record<string, unknown> {
+  if (typeof v !== 'object' || v === null || Array.isArray(v)) return false;
+  const proto = Object.getPrototypeOf(v) as object | null;
+  return proto === Object.prototype || proto === null;
+}
+
+/**
+ * Deep-clone a config. Hand-rolled rather than `structuredClone` because a config may carry
+ * functions (`anticipation.decide`), which `structuredClone` refuses to copy. Functions and
+ * anything that is not a plain object/array pass through by reference.
+ */
 function structuredCloneSafe<T>(v: T): T {
-  // 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)) as T;
+  if (Array.isArray(v)) return v.map((item) => structuredCloneSafe(item)) as unknown as T;
+  if (isCloneableRecord(v)) {
+    const out: Record<string, unknown> = {};
+    for (const [k, val] of Object.entries(v)) out[k] = structuredCloneSafe(val);
+    return out as T;
+  }
+  return v;
 }
 
 /** Effective per-reel row counts (resolves Megaways `rowsPerReel`, else uniform `rows`). */

package/src/slot/devtools/fieldSchema.ts

@@ -134,6 +134,9 @@ export const REEL_FIELD_SCHEMA: Section[] = [
       { kind: 'select', path: 'motion.intensity', label: 'Intensity', options: ['full', 'reduced', 'minimal'] },
       { kind: 'toggle', path: 'motion.slamStop', label: 'Slam stop' },
       { kind: 'range', path: 'motion.symbolsPerReel', label: 'Tape length', min: 3, max: 24, step: 1 },
+      { kind: 'range', path: 'motion.cellStagger', label: 'Cell stagger (ms)', min: 0, max: 700, step: 5 },
+      { kind: 'range', path: 'motion.reelStaggerFactor', label: 'Reel stagger ×', min: 0, max: 3, step: 0.05 },
+      { kind: 'range', path: 'motion.dropFallFactor', label: 'Drop fall ×', min: 0.1, max: 3, step: 0.05 },
     ],
   },
   {
@@ -144,6 +147,8 @@ export const REEL_FIELD_SCHEMA: Section[] = [
       { kind: 'range', path: 'anticipation.threshold', label: 'Threshold (N−1)', min: 1, max: 6, step: 1 },
       { kind: 'range', path: 'anticipation.slowdownFactor', label: 'Slowdown', min: 0.1, max: 1, step: 0.05 },
       { kind: 'range', path: 'anticipation.holdMs', label: 'Hold (ms)', min: 0, max: 1200, step: 50 },
+      { kind: 'range', path: 'anticipation.progressiveSlowdown', label: 'Slowdown ramp ×/reel', min: 0.3, max: 1, step: 0.05 },
+      { kind: 'range', path: 'anticipation.progressiveHoldMs', label: 'Hold ramp (ms/reel)', min: 0, max: 600, step: 25 },
       { kind: 'toggle', path: 'anticipation.zoom.enabled', label: 'Reel zoom' },
       { kind: 'range', path: 'anticipation.zoom.scale', label: 'Zoom scale', min: 1, max: 1.6, step: 0.05 },
       { kind: 'range', path: 'anticipation.zoom.ms', label: 'Zoom (ms)', min: 200, max: 1200, step: 50 },

package/src/slot/index.ts

@@ -23,6 +23,7 @@ export {
   effectiveRowsPerReel,
   resolveGridGeometry,
   waysCount,
+  perReelValue,
 } from './config/ReelSystemConfig';
 export type {
   ReelSystemConfig,
@@ -39,6 +40,8 @@ export type {
   SquashConfig,
   BlurConfig,
   AnticipationConfig,
+  AnticipationOverride,
+  PerReel,
   CascadeConfig,
   WinConfig,
   FeaturesConfig,

package/src/slot/motion/AnticipationController.ts

@@ -7,16 +7,22 @@ import { Tween } from '../../animation';
 import { easingByName } from '../anim/easing-map';
 import type { ReelGrid } from '../grid/ReelGrid';
 import type { CellData } from '../grid/SymbolCell';
-import type { AnticipationConfig } from '../config/ReelSystemConfig';
+import type { AnticipationConfig, AnticipationOverride, PerReel } from '../config/ReelSystemConfig';
 
 export interface AnticipationDecision {
   active: boolean;
-  /** Reel indices that should spin slower / longer. */
+  /** Reel indices that should spin slower / longer, in the order the ramp applies. */
   reels: number[];
-  slowdown: number;
-  holdMs: number;
+  /** Speed factor. A scalar when flat; a per-reel array when the decision ramps (see
+   *  `progressiveSlowdown` / a game-supplied `decide`). Resolve with `perReelValue`. */
+  slowdown: PerReel<number>;
+  /** Extra hold before landing. Scalar or per-reel array, same as `slowdown`. */
+  holdMs: PerReel<number>;
 }
 
+/** Fresh "nothing to anticipate" decision (fresh, so callers may mutate `reels` freely). */
+const none = (): AnticipationDecision => ({ active: false, reels: [], slowdown: 1, holdMs: 0 });
+
 export class AnticipationController {
   private _cfg: AnticipationConfig;
   constructor(cfg: AnticipationConfig) {
@@ -39,20 +45,22 @@ export class AnticipationController {
    * is flagged for the slow treatment (this mirrors "searching for the last scatter").
    */
   decide(targetGrid: CellData[][]): AnticipationDecision {
-    if (!this._cfg.enabled) return { active: false, reels: [], slowdown: 1, holdMs: 0 };
+    if (!this._cfg.enabled) return none();
+
+    // A game-supplied predicate replaces the symbol counting entirely.
+    if (this._cfg.decide) {
+      const custom = this._cfg.decide(targetGrid);
+      if (!custom) return none();
+      const o: AnticipationOverride = Array.isArray(custom) ? { reels: custom } : custom;
+      if (!o.reels?.length) return none();
+      return this.build(o.reels.slice(), o.slowdown, o.holdMs);
+    }
 
     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 };
+      if (total < this._cfg.threshold) return none();
+      return this.build(this._cfg.reels.slice());
     }
 
     // 'trailing': find the reel where the cumulative count hits the threshold
@@ -65,12 +73,49 @@ export class AnticipationController {
         break;
       }
     }
-    if (armReel < 0) return { active: false, reels: [], slowdown: 1, holdMs: 0 };
+    if (armReel < 0) return none();
 
     const reels: number[] = [];
     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 };
+    if (reels.length === 0) return none();
+    return this.build(reels);
+  }
+
+  /** Assemble a decision, applying the configured progression unless the caller pinned values. */
+  private build(
+    reels: number[],
+    slowdown?: PerReel<number>,
+    holdMs?: PerReel<number>,
+  ): AnticipationDecision {
+    return {
+      active: true,
+      reels,
+      slowdown:
+        slowdown ??
+        this.ramp(reels, this._cfg.slowdownFactor, (base, i) =>
+          i === 0 ? base : base * Math.pow(this._cfg.progressiveSlowdown, i),
+        ),
+      holdMs:
+        holdMs ??
+        this.ramp(reels, this._cfg.holdMs, (base, i) => base + this._cfg.progressiveHoldMs * i),
+    };
+  }
+
+  /**
+   * A flat scalar when the progression is a no-op, else an array INDEXED BY REEL so the engine can
+   * read a per-reel value straight out of `plan()`.
+   */
+  private ramp(
+    reels: number[],
+    base: number,
+    at: (base: number, i: number) => number,
+  ): PerReel<number> {
+    if (at(base, 1) === base) return base;
+    const out: (number | undefined)[] = [];
+    reels.forEach((reel, i) => {
+      out[reel] = at(base, i);
+    });
+    return out;
   }
 
   /** Optionally zoom the grid in while anticipating, then settle back. Returns a reset fn. */

package/src/slot/motion/SpinEngine.ts

@@ -17,7 +17,9 @@ import type { SymbolResolver } from '../grid/SymbolView';
 import {
   DEFAULT_REEL_CONFIG,
   INTENSITY_SCALE,
+  perReelValue,
   type MotionConfig,
+  type PerReel,
   type WinConfig,
 } from '../config/ReelSystemConfig';
 
@@ -32,8 +34,27 @@ export interface SpinRunOpts {
   turbo?: boolean;
   /** Reels to slow for anticipation (computed by the ReelSystem from config + targetGrid). */
   anticipateReels?: number[];
-  anticipateSlowdown?: number;
-  anticipateHoldMs?: number;
+  /** Speed factor for anticipated reels (lower = slower). Scalar, or per-reel indexed by reel. */
+  anticipateSlowdown?: PerReel<number>;
+  /** Extra hold (ms) for anticipated reels. Scalar, or per-reel indexed by reel. */
+  anticipateHoldMs?: PerReel<number>;
+  /**
+   * Reels whose tape runs normally but whose landing is NOT handed back. The engine stops and
+   * disposes of the tape as usual and leaves the real cells hidden and unseated; the caller owns
+   * their data and visibility from that point (and `skip()` will not reveal them either).
+   */
+  deferReveal?: number[];
+
+  // ── lifecycle ────────────────────────────────────────────────────────────
+  /** The resolved schedule, handed over before the first frame runs. Schedule against THESE
+   *  numbers rather than re-deriving `plan()`'s formula. */
+  onPlan?: (plan: ReelStopPlan[]) => void;
+  /** Fires on the frame a reel lands — after its cells are seated, before settle/squash/shake.
+   *  For a deferred reel it still fires (the reel DID stop); nothing was seated. */
+  onReelStop?: (reel: number, plan: ReelStopPlan) => void;
+  /** Fires as each cell takes its landing symbol. In `cascade-drop` this is the per-cell impact
+   *  frame (after the fall, before the squash) — the hook for a per-cell sound or shake. */
+  onCellSeated?: (reel: number, row: number, data: CellData) => void;
 }
 
 export interface ReelStopPlan {
@@ -43,6 +64,10 @@ export interface ReelStopPlan {
   landing: CellData[];
   settle: { amp: number; ms: number };
   anticipated: boolean;
+  /** Time-stretch applied to this reel's tape (>= 1, longer = slower). 1 when not anticipated. */
+  slowdown: number;
+  /** True when `deferReveal` withheld this reel's landing (see `SpinRunOpts.deferReveal`). */
+  deferred: boolean;
 }
 
 export class SpinEngine {
@@ -53,6 +78,7 @@ export class SpinEngine {
   private _killed = false;
   private _shaking = false;
   private _temp: Container[] = [];
+  private _deferred = new Set<number>();
 
   constructor(grid: ReelGrid, resolve: SymbolResolver, cfg: MotionConfig, win?: WinConfig) {
     this._grid = grid;
@@ -102,6 +128,7 @@ export class SpinEngine {
     const cols = this._grid.cols;
     const order = (reel: number) => (this._cfg.stopOrder === 'rtl' ? cols - 1 - reel : reel);
     const anticipate = new Set(opts?.anticipateReels ?? []);
+    const defer = new Set(opts?.deferReveal ?? []);
     const out: ReelStopPlan[] = [];
     for (let reel = 0; reel < cols; reel++) {
       const idx = order(reel);
@@ -116,7 +143,8 @@ export class SpinEngine {
       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;
+      if (isAnticipated) stopTime += perReelValue(opts?.anticipateHoldMs, reel, 0) * f;
+      const speed = isAnticipated ? perReelValue(opts?.anticipateSlowdown, reel, 1) : 1;
 
       out.push({
         reel,
@@ -124,6 +152,8 @@ export class SpinEngine {
         landing: data.targetGrid[reel] ?? [],
         settle: { amp: this._cfg.settle.amp, ms: this._cfg.settle.ms * f },
         anticipated: isAnticipated,
+        slowdown: Math.max(1, 1 / (speed || 1)),
+        deferred: defer.has(reel),
       });
     }
     return out;
@@ -134,6 +164,9 @@ export class SpinEngine {
     this._killed = false;
     this._temp = [];
     const plan = this.plan(data, opts);
+    // remembered for skip(): a deferred reel's cells belong to the caller, not to us
+    this._deferred = new Set(plan.filter((p) => p.deferred).map((p) => p.reel));
+    opts?.onPlan?.(plan);
     const f = this.scale(opts);
     await Promise.all(plan.map((p) => this._runReel(p, data, opts, f)));
     this._cleanupTemp();
@@ -157,9 +190,9 @@ export class SpinEngine {
     }
   }
 
-  /** Anticipation time-stretch factor for a reel (>=1, longer = slower). */
-  private slowOf(p: ReelStopPlan, opts?: SpinRunOpts): number {
-    return p.anticipated ? Math.max(1, 1 / (opts?.anticipateSlowdown ?? 1)) : 1;
+  /** Anticipation time-stretch factor for a reel (>=1, longer = slower). Resolved in `plan()`. */
+  private slowOf(p: ReelStopPlan): number {
+    return p.slowdown;
   }
 
   // ── swap: cycle symbols quickly in the real cells, then land ──────────────
@@ -176,7 +209,7 @@ export class SpinEngine {
     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));
+    const ticks = Math.max(6, Math.floor((p.stopTime * this.slowOf(p)) / tickMs));
     for (let i = 0; i < ticks; i++) {
       if (this._killed) break;
       for (let r = 0; r < cells.length; r++)
@@ -184,7 +217,24 @@ export class SpinEngine {
       await Tween.delay(tickMs);
     }
     blur?.();
-    for (let r = 0; r < cells.length; r++) cells[r].setData(p.landing[r] ?? { symbol: null });
+    if (p.deferred) {
+      // the caller owns this reel's result — go dark and unseated instead of handing it back.
+      // NB 'swap' cycles the tape THROUGH the real cells, so a deferred reel only truly withholds
+      // its result when `SpinData.strip` supplies filler for it; otherwise the tape is built from
+      // the landing symbols. 'strip' and 'cascade-drop' have no such caveat.
+      cells.forEach((c) => {
+        c.setData({ symbol: null });
+        c.visible = false;
+      });
+      opts?.onReelStop?.(p.reel, p);
+      return;
+    }
+    for (let r = 0; r < cells.length; r++) {
+      const cell = p.landing[r] ?? { symbol: null };
+      cells[r].setData(cell);
+      opts?.onCellSeated?.(p.reel, r, cell);
+    }
+    opts?.onReelStop?.(p.reel, p);
     await this._settle(p.reel, p.settle, f);
     await this._frameShake(p.landing);
   }
@@ -228,7 +278,7 @@ export class SpinEngine {
     this._temp.push(tape);
     const clearBlur = this._applyBlur([tape], true);
 
-    const slow = this.slowOf(p, opts);
+    const slow = this.slowOf(p);
     // overshoot/settle honour the configured settle (amp in px, easing)
     const overshoot = p.settle.amp || step * 0.18;
     await Tween.to(
@@ -248,11 +298,20 @@ export class SpinEngine {
       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));
+    // hand the result back to the real cells — unless the caller deferred the reveal, in which
+    // case the tape simply goes away and the reel is left dark, unseated and owned by the caller
+    if (!p.deferred) {
+      for (let r = 0; r < rows; r++) {
+        const cell = p.landing[r] ?? { symbol: null };
+        realCells[r].setData(cell);
+        opts?.onCellSeated?.(p.reel, r, cell);
+      }
+      realCells.forEach((c) => (c.visible = true));
+    }
     tape.destroy();
     this._temp = this._temp.filter((t) => t !== tape);
+    opts?.onReelStop?.(p.reel, p);
+    if (p.deferred) return;
     // 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);
@@ -261,27 +320,41 @@ export class SpinEngine {
   // ── cascade-drop: symbols drop in from above with stagger + bounce + squash ─
   private async _runDrop(p: ReelStopPlan, opts: SpinRunOpts | undefined, f: number): Promise<void> {
     const rows = this._grid.rowsOf(p.reel);
+    if (p.deferred) {
+      // nothing to drop — the caller brings this reel in itself
+      for (let r = 0; r < rows; r++) this._grid.getCell(p.reel, r).visible = false;
+      opts?.onReelStop?.(p.reel, p);
+      return;
+    }
     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
+    const slow = this.slowOf(p); // 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 });
+        const data = p.landing[r] ?? { symbol: null };
+        cell.setData(data);
         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;
+        const delay =
+          (p.reel * this._cfg.stopStagger * this._cfg.reelStaggerFactor +
+            r * this._cfg.cellStagger) *
+          f *
+          slow;
         if (delay) await Tween.delay(delay);
         await Tween.to(
           cell,
           { 'position.y': to.y },
-          this._cfg.spinUp * 0.6 * f * slow,
+          this._cfg.spinUp * this._cfg.dropFallFactor * f * slow,
           easingByName(this._cfg.settle.easing),
         );
+        // the impact frame — fired before the squash so a game can sync its own hit feedback
+        opts?.onCellSeated?.(p.reel, r, data);
         await this._squashCell(cell, f);
       }),
     );
+    opts?.onReelStop?.(p.reel, p);
     await this._frameShake(p.landing);
   }
 
@@ -369,12 +442,16 @@ export class SpinEngine {
     Tween.killTweensOf(this._grid);
     this._grid.x = 0; // undo any in-flight frame shake
     for (let c = 0; c < this._grid.cols; c++) {
+      // a deferred reel's visibility belongs to the caller — a slam stop must not reveal it
+      const deferred = this._deferred.has(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;
+        if (!deferred) {
+          cell.visible = true;
+          cell.alpha = 1;
+        }
         cell.filters = [];
         cell.scale.set(1);
       }

package/src/slot/system/ReelSystem.ts

@@ -9,8 +9,16 @@ import { Tween } from '../../animation';
 import { ReelGrid } from '../grid/ReelGrid';
 import type { CellData } from '../grid/SymbolCell';
 import type { SymbolResolver } from '../grid/SymbolView';
-import { SpinEngine, type SpinData, type SpinRunOpts } from '../motion/SpinEngine';
-import { AnticipationController } from '../motion/AnticipationController';
+import {
+  SpinEngine,
+  type ReelStopPlan,
+  type SpinData,
+  type SpinRunOpts,
+} from '../motion/SpinEngine';
+import {
+  AnticipationController,
+  type AnticipationDecision,
+} from '../motion/AnticipationController';
 import { TumbleController, type TumbleStep } from '../cascade/TumbleController';
 import { ReelStepController, type ReelStepData } from '../cascade/ReelStepController';
 import { FEATURES, FEATURE_LIST, type FeatureContext, type ReelFeature } from '../features';
@@ -65,6 +73,14 @@ export interface ReelSystem {
   /** Replace the whole config. */
   setConfig(config: ReelSystemConfig): void;
   spin(target: CellData[][], opts?: SpinRunOpts): Promise<void>;
+  /**
+   * The schedule `spin(target, opts)` WOULD run, without running it — same anticipation decision,
+   * same numbers. Schedule landing sounds / camera moves against this instead of re-deriving the
+   * engine's formula. (`spin`'s `onPlan` hands you the same array once the spin is under way.)
+   */
+  planSpin(target: CellData[][], opts?: SpinRunOpts): ReelStopPlan[];
+  /** The anticipation decision `spin(target, opts)` would use (run options override the config). */
+  anticipationFor(target: CellData[][], opts?: SpinRunOpts): AnticipationDecision;
   /** Run a cascade chain. With `freeSpins` + `cascade.multiplier.persistInFreeSpins`, the multiplier
    *  carries over instead of resetting. Generic in the step type, so `onStep` hands back the game's
    *  own step (with its per-step win) rather than the bare TumbleStep. */
@@ -191,6 +207,36 @@ export function createReelSystem(opts: CreateReelSystemOptions): ReelSystem {
     return { grid, resolve, cfg: config, fx, board, freeSpins, log };
   }
 
+  /**
+   * Which reels get the anticipation treatment for this spin. An explicit `anticipateReels` on the
+   * run options WINS over the configured decision — passing it is how a game drives anticipation
+   * from its own logic. Omit it and the configured `AnticipationController` decides.
+   */
+  function resolveAnticipation(target: CellData[][], runOpts?: SpinRunOpts): AnticipationDecision {
+    const explicit = runOpts?.anticipateReels;
+    if (!explicit) return anticipation.decide(target);
+    if (!explicit.length) return { active: false, reels: [], slowdown: 1, holdMs: 0 };
+    return {
+      active: true,
+      reels: explicit.slice(),
+      slowdown: runOpts?.anticipateSlowdown ?? config.anticipation.slowdownFactor,
+      holdMs: runOpts?.anticipateHoldMs ?? config.anticipation.holdMs,
+    };
+  }
+
+  /** Fold a resolved decision back onto the caller's run options (everything else passes through). */
+  function mergeAnticipation(
+    runOpts: SpinRunOpts | undefined,
+    decision: AnticipationDecision,
+  ): SpinRunOpts {
+    return {
+      ...runOpts,
+      anticipateReels: decision.active ? decision.reels : undefined,
+      anticipateSlowdown: decision.slowdown,
+      anticipateHoldMs: decision.holdMs,
+    };
+  }
+
   buildGrid();
 
   const api: ReelSystem = {
@@ -237,20 +283,24 @@ export function createReelSystem(opts: CreateReelSystemOptions): ReelSystem {
       api.setConfig(mergeReelConfig(config, partial));
     },
 
+    anticipationFor(target, runOpts) {
+      return resolveAnticipation(target, runOpts);
+    },
+
+    planSpin(target, runOpts) {
+      const decision = resolveAnticipation(target, runOpts);
+      return spin.plan({ targetGrid: target }, mergeAnticipation(runOpts, decision));
+    },
+
     async spin(target, runOpts) {
       const data: SpinData = { targetGrid: target };
-      const decision = anticipation.decide(target);
+      const decision = resolveAnticipation(target, runOpts);
       let resetZoom: (() => Promise<void>) | null = 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,
-      });
+      await spin.run(data, mergeAnticipation(runOpts, decision));
       if (resetZoom) await resetZoom();
       board = target;
     },