@energy8platform/game-engine 0.38.0 → 0.40.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. */
@@ -492,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
 // ─────────────────────────────────────────────────────────────────────────────
@@ -78,6 +92,10 @@ export type MotionStyle =
   | 'cascade-drop'; // symbols drop in from above (tumble-style boards)
 
 export type StopMode = 'sequential' | 'sync' | 'random';
+/** `cascade-drop` fill direction within one reel. */
+export type DropOrder = 'top-down' | 'bottom-up';
+/** How `cascade-drop` spaces reels: by formula, or one strictly after the other. */
+export type DropSequence = 'parallel' | 'chained' | 'chained-when-anticipated';
 export type StopOrder = 'ltr' | 'rtl';
 export type Intensity = 'full' | 'reduced' | 'minimal';
 
@@ -127,12 +145,47 @@ 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;
+  /**
+   * `cascade-drop`: which cell of a reel lands first. `'top-down'` (default, the engine's original
+   * behaviour) deals the reel like cards from the top; `'bottom-up'` fills it the way gravity
+   * would — the lowest cell arrives first and the rest stack on top of it.
+   */
+  dropOrder: DropOrder;
+  /**
+   * `cascade-drop`: how reels are spaced.
+   * - `'parallel'` (default) starts every reel at its own formula offset —
+   *   `reel * stopStagger * reelStaggerFactor` — so a reel can open while the previous one is
+   *   still dropping. Fast, and what a normal spin wants.
+   * - `'chained'` starts a reel only once the previous one has seated its LAST cell, plus that
+   *   same offset as the gap. One reel at a time, always — correct, but it makes every spin as
+   *   long as the sum of its reels.
+   * - `'chained-when-anticipated'` runs the un-armed reels in parallel and switches to the chain
+   *   from the first ANTICIPATED reel onwards. The base spin keeps its stop window; the hunt for
+   *   the last scatter goes strictly reel by reel, each slower than the last.
+   */
+  dropSequence: DropSequence;
 }
 
 // ─────────────────────────────────────────────────────────────────────────────
 // 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 +198,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 +487,11 @@ export const DEFAULT_REEL_CONFIG: ReelSystemConfig = {
     intensity: 'full',
     slamStop: true,
     symbolsPerReel: 6,
+    cellStagger: 24,
+    reelStaggerFactor: 0.4,
+    dropFallFactor: 0.6,
+    dropOrder: 'top-down',
+    dropSequence: 'parallel',
   },
   anticipation: {
     enabled: false,
@@ -427,6 +500,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 +631,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,11 @@ 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 },
+      { kind: 'select', path: 'motion.dropOrder', label: 'Drop order', options: ['top-down', 'bottom-up'] },
+      { kind: 'select', path: 'motion.dropSequence', label: 'Drop sequence', options: ['parallel', 'chained', 'chained-when-anticipated'] },
     ],
   },
   {
@@ -144,6 +149,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,
@@ -32,6 +33,8 @@ export type {
   MotionStyle,
   StopMode,
   StopOrder,
+  DropOrder,
+  DropSequence,
   Intensity,
   GridConfig,
   MotionConfig,
@@ -39,6 +42,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,17 @@ 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;
+  /**
+   * `cascade-drop` only: ms from spin start at which each cell of this reel seats, INDEXED BY ROW.
+   * The reel's fill direction lives in these numbers (`motion.dropOrder` decides which row is the
+   * smallest), as does its place in the chain (`motion.dropSequence`). `stopTime` is the largest
+   * of them — the frame the whole reel has landed.
+   */
+  cellStopTimes?: number[];
 }
 
 export class SpinEngine {
@@ -53,6 +85,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 +135,8 @@ 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 holds: number[] = [];
     const out: ReelStopPlan[] = [];
     for (let reel = 0; reel < cols; reel++) {
       const idx = order(reel);
@@ -116,7 +151,10 @@ 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;
+      const hold = isAnticipated ? perReelValue(opts?.anticipateHoldMs, reel, 0) * f : 0;
+      stopTime += hold;
+      holds[reel] = hold;
+      const speed = isAnticipated ? perReelValue(opts?.anticipateSlowdown, reel, 1) : 1;
 
       out.push({
         reel,
@@ -124,16 +162,68 @@ 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),
       });
     }
+    if (this._cfg.style === 'cascade-drop') this._planDrop(out, holds, f, order);
     return out;
   }
 
+  /**
+   * `cascade-drop` lays its reels out on a different clock from the tape styles: a reel is a
+   * sequence of per-cell arrivals, not one deceleration. Overwrite `stopTime` with the moment the
+   * reel has fully landed and fill in `cellStopTimes`, so `plan()` stays the single source of truth
+   * for WHEN anything happens — `_runDrop` below only executes these numbers.
+   */
+  private _planDrop(
+    out: ReelStopPlan[],
+    holds: number[],
+    f: number,
+    order: (reel: number) => number,
+  ): void {
+    const bottomUp = this._cfg.dropOrder === 'bottom-up';
+    // walk the reels in STOP order, so `stopOrder: 'rtl'` reverses the drop as well
+    const byPosition: number[] = [];
+    for (let reel = 0; reel < out.length; reel++) byPosition[order(reel)] = reel;
+    // the position from which reels stop overlapping and start queueing behind each other
+    const chainFrom =
+      this._cfg.dropSequence === 'chained'
+        ? 0
+        : this._cfg.dropSequence === 'chained-when-anticipated'
+          ? byPosition.findIndex((reel) => out[reel].anticipated)
+          : -1;
+
+    let previousEnd = 0;
+    for (let position = 0; position < byPosition.length; position++) {
+      const p = out[byPosition[position]];
+      const rows = this._grid.rowsOf(p.reel);
+      const scale = f * p.slowdown;
+      const gap = this._cfg.stopStagger * this._cfg.reelStaggerFactor * scale;
+      const fall = this._cfg.spinUp * this._cfg.dropFallFactor * scale;
+      // by formula while reels may overlap; queued behind the previous reel once the chain starts
+      const chained = chainFrom >= 0 && position > 0 && position >= chainFrom;
+      const start = (chained ? previousEnd + gap : position * gap) + (holds[p.reel] ?? 0);
+
+      const cells: number[] = [];
+      for (let i = 0; i < rows; i++) {
+        const row = bottomUp ? rows - 1 - i : i;
+        cells[row] = start + i * this._cfg.cellStagger * scale + fall;
+      }
+      p.cellStopTimes = cells;
+      p.stopTime = cells.length ? Math.max(...cells) : start;
+      previousEnd = p.stopTime;
+    }
+  }
+
   /** Execute the spin for every reel concurrently. */
   async run(data: SpinData, opts?: SpinRunOpts): Promise<void> {
     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 +247,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 +266,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 +274,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 +335,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 +355,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 +377,35 @@ 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
+    const fall = this._cfg.spinUp * this._cfg.dropFallFactor * f * slow;
+    const schedule = p.cellStopTimes ?? [];
     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;
+        // the plan says WHEN this cell seats; back off the fall to get when it must let go
+        const delay = Math.max(0, (schedule[r] ?? fall) - fall);
         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 Tween.to(cell, { 'position.y': to.y }, fall, 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 +493,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);
       }