@energy8platform/game-engine 0.23.0 → 0.24.0

package/src/host/createSlotGame.ts

@@ -6,7 +6,7 @@ import { loadFonts, applyTextureDefaults, bootGuard } from './preboot';
 import { showFatalError, installGlobalErrorHandlers } from './fatalError';
 import type { CreateSlotGameOptions, SlotGameHandle } from './types';
 import type { SlotSpinResultBase } from '@energy8platform/platform-core/slot-result';
-import type { ShellMode } from '@energy8platform/pixi-shell';
+import type { ShellMode } from '@energy8platform/shell/pixi';
 import type { SceneApi, SlotSceneController } from './sceneController';
 
 /**
@@ -143,7 +143,7 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
   });
 
   if (opts.shell) {
-    const { createPixiShell } = await import('@energy8platform/pixi-shell');
+    const { createPixiShell } = await import('@energy8platform/shell/pixi');
     const { buildShellConfig } = await import('./shellConfig');
     const { resolveReplayBonusId } = await import('./replay');
 
@@ -206,7 +206,10 @@ export async function createSlotGame<T extends SlotSpinResultBase = SlotSpinResu
     // pixi-shell mounts its root onto the engine's unscaled, screen-space UI layer (above the
     // scaled world/scene root) so the control bar fills the real screen, not the letterboxed game.
     // The host adds the mount target (`app`) + parent; buildShellConfig produces everything else.
-    shell = createPixiShell({ ...buildShellConfig(opts.shell, opts.model, runtime), app: game.app, parent: game.uiLayer });
+    const pixiShellCfg: import('@energy8platform/shell/pixi').PixiShellConfig = { ...buildShellConfig(opts.shell, opts.model, runtime), app: game.app, parent: game.uiLayer };
+    // The game may swap in its own shell (a custom renderer over the same core) via shellFactory;
+    // default is the built-in Pixi shell. The host drives whichever it gets through the Shell contract.
+    shell = (opts.shellFactory ?? createPixiShell)(pixiShellCfg);
     // Scope the bar to the slot scene: show only when a SlotSceneController scene is current
     // (hidden over the intro / non-slot scenes). Applies in BOTH base and replay modes.
     shell.setVisible(!!gameScene());

package/src/host/index.ts

@@ -6,7 +6,17 @@ export type {
   StakeIntegration,
   SceneRegistration,
   SceneNavData,
+  ShellFactory,
 } from './types';
+
+// Shell contract for authors plugging a custom renderer via createSlotGame({ shellFactory }).
+// Implement `ShellRenderer`, build the shell with `createShell({ renderer, ...config })`, and the
+// shell core drives bet/balance/overlays unchanged. `createPixiShell`/`PixiRenderer` are the built-in.
+export { createShell, createPixiShell, PixiRenderer } from '@energy8platform/shell/pixi';
+export type {
+  Shell, ShellRenderer, ShellSurface, SafeArea, ShellHost, ShellActions, ShellTokens,
+  ShellLayoutMode, OverlayRequest, OverlayHandle, ResolvedShellConfig, PixiShellConfig,
+} from '@energy8platform/shell/pixi';
 export { buildShellConfig, stakeForAction } from './shellConfig';
 export type { SlotShellOptions } from './shellConfig';
 export { resolveReplayBonusId } from './replay';
@@ -17,4 +27,4 @@ export type {
 } from './sceneController';
 // Social-casino word-swap. The shell auto-socializes all gameInfo/buyBonus text in social mode;
 // authors only need this to socialize strings they render themselves (e.g. inside a custom DOM node).
-export { socialize } from '@energy8platform/platform-core/shell';
+export { socialize } from '@energy8platform/shell';

package/src/host/shellConfig.ts

@@ -1,12 +1,14 @@
 // packages/game-engine/src/host/shellConfig.ts
-// `socialize` / `createI18n` are runtime helpers sourced from platform-core/shell;
-// pixi-shell re-exports only types so we import directly from platform-core.
-import { socialize, createI18n } from '@energy8platform/platform-core/shell';
-import type { Lang } from '@energy8platform/platform-core/shell';
+// `socialize` / `createI18n` / `Lang` are renderer-agnostic helpers from the shell core
+// (@energy8platform/shell). Renderer-agnostic types (GameInfoSection/Content, PaytableRow,
+// GameMode) and the pixi-specific surface types come from the @energy8platform/shell/pixi entry.
+import { socialize, createI18n } from '@energy8platform/shell';
+import type { Lang } from '@energy8platform/shell';
+import type { GameInfoContent, GameInfoSection, PaytableRow, GameMode } from '@energy8platform/shell/pixi';
 import type {
-  PixiShellConfig, ShellMode, CurrencyConfig, GameInfoContent, GameInfoSection, PaytableRow,
-  BonusOption, ShellFeatures, GameMode,
-} from '@energy8platform/pixi-shell';
+  PixiShellConfig, ShellMode, CurrencyConfig,
+  BonusOption, ShellFeatures,
+} from '@energy8platform/shell/pixi';
 import type { GameModel } from '@energy8platform/platform-core/game-spec';
 import type { WinTier } from '../slot';
 
@@ -276,20 +278,26 @@ function sectionKey(s: GameInfoSection): string {
  */
 export function mergeGameInfo(derived: GameInfoContent, override?: GameInfoContent): GameInfoContent {
   if (!override) return derived;
+  // `GameInfoContent.sections` is typed with the core GameInfoSection (node?: unknown) because
+  // shell/pixi re-exports GameInfoContent unchanged from core. Host-built sections never set `node`,
+  // so they are structurally compatible with pixi's GameInfoSection (node?: Container). Cast once
+  // here so the rest of the function works against the pixi-widened type.
+  const derivedSections = (derived.sections ?? []) as GameInfoSection[];
+  const overrideSections = (override.sections ?? []) as GameInfoSection[];
   const authorByKey = new Map<string, GameInfoSection>();
-  for (const s of override.sections ?? []) authorByKey.set(sectionKey(s), s);
+  for (const s of overrideSections) authorByKey.set(sectionKey(s), s);
 
   const out: GameInfoSection[] = [];
   const used = new Set<string>();
   // Keep derived order; swap in the author's version where identities collide.
-  for (const s of derived.sections ?? []) {
+  for (const s of derivedSections) {
     const k = sectionKey(s);
     const replacement = authorByKey.get(k);
     if (replacement) { out.push(replacement); used.add(k); }
     else out.push(s);
   }
   // Append author sections whose identity wasn't in the derived set, in author order.
-  for (const s of override.sections ?? []) {
+  for (const s of overrideSections) {
     const k = sectionKey(s);
     if (!used.has(k)) { out.push(s); used.add(k); }
   }
@@ -340,7 +348,7 @@ export function buildShellConfig(
   opts: SlotShellOptions,
   model: GameModel,
   runtime: ShellRuntime,
-): Omit<PixiShellConfig, 'app' | 'parent'> {
+): Omit<PixiShellConfig, 'app' | 'parent' | 'gameInfo'> & { gameInfo: GameInfoContent } {
   // Prefer the currency-specific ladder from /wallet/authenticate; fall back to the spec (dev/devBridge).
   const betLevels = runtime.betLevels?.length ? runtime.betLevels : model.spec.betLevels;
   // Stake requires the default to come from authenticate on every entry; spec default is the dev fallback.
@@ -360,7 +368,9 @@ export function buildShellConfig(
   const authored = typeof opts.gameInfo === 'function' ? opts.gameInfo(t) : opts.gameInfo;
   // Pass t() through to spec-derived sections so symbol names, mode titles, and descriptions are
   // pre-translated before they reach the shell renderer.
-  let gameInfo = mergeGameInfo(defaultGameInfo(model, runtime, t), authored);
+  // Cast to { sections?: GameInfoSection[] } (pixi-widened) so downstream map/filter calls work
+  // against the pixi section union. Host-derived sections never set `node`, so the widening is safe.
+  let gameInfo: { sections?: GameInfoSection[] } = mergeGameInfo(defaultGameInfo(model, runtime, t), authored) as { sections?: GameInfoSection[] };
   // The DISCLAIMER is required legal copy and must be shown VERBATIM — never socialized (its
   // wording is mandated, and word-swaps like "bet → play" would corrupt the legal text).
   if (isSocial) {

package/src/host/types.ts

@@ -2,7 +2,7 @@
 import type { ApplicationOptions } from 'pixi.js';
 import type { GameModel } from '@energy8platform/platform-core/game-spec';
 import type { AssetManifest, LoadingScreenConfig } from '@energy8platform/platform-core';
-import type { PixiGameShell } from '@energy8platform/pixi-shell';
+import type { Shell, PixiShellConfig } from '@energy8platform/shell/pixi';
 import type { AudioConfig, ScaleMode, Orientation, SceneConstructor } from '../types';
 import type { BookAdapter, AdapterModule, StakeBridge } from '@energy8platform/stake-bridge';
 import type { GameApplication } from '../core';
@@ -58,14 +58,25 @@ export interface CreateSlotGameOptions<T extends SlotSpinResultBase = SlotSpinRe
   dev?: boolean;
   stake?: StakeIntegration;
   shell?: SlotShellOptions;
+  /** Override how the control-bar shell is built. The host resolves the full shell config (theme,
+   *  features, gameInfo, currency, balance) and the Pixi mount (`app`/`parent`) and hands it to this
+   *  factory; return any `Shell` — e.g. `createShell({ renderer: new MyRenderer(...), ...config })`
+   *  to plug a custom renderer while the shell core still drives bet/balance/overlays. A custom
+   *  renderer can ignore `app`/`parent` and mount elsewhere (a DOM overlay, another canvas).
+   *  Default: the built-in Pixi shell (`createPixiShell`). */
+  shellFactory?: ShellFactory;
   /** Double-tap on the play area to skip the current spin animation. Default `true`. Set `false`
    *  to disable the gesture (e.g. games where a tap means something else). */
   skipGesture?: boolean;
   onFatalError?: (message: string) => void;
 }
 
+/** Builds the shell the host drives. Receives the fully-resolved Pixi shell config (a custom
+ *  renderer may ignore the `app`/`parent` mount fields). Must return a `Shell`. */
+export type ShellFactory = (config: PixiShellConfig) => Shell;
+
 export interface SlotGameHandle {
   game: GameApplication;
   stakeBridge: StakeBridge | null;
-  shell: PixiGameShell | null;
+  shell: Shell | null;
 }

package/src/shell/index.ts

@@ -1,10 +1,10 @@
-// Re-export the renderer-agnostic branded game shell from platform-core so
+// Re-export the renderer-agnostic branded game shell from @energy8platform/shell/html so
 // game-engine consumers can import it via @energy8platform/game-engine/shell.
 export {
   createGameShell,
   removeGameShell,
   GameShell,
-} from '@energy8platform/platform-core/shell';
+} from '@energy8platform/shell/html';
 export type {
   ShellConfig,
   ShellMode,
@@ -17,4 +17,5 @@ export type {
   GameInfoContent,
   AutoplayOptions,
   FreeSpinsState,
-} from '@energy8platform/platform-core/shell';
+  Lang,
+} from '@energy8platform/shell/html';

package/src/slot/cascade/TumbleController.ts

@@ -147,8 +147,11 @@ export class TumbleController {
     }
     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;
+    // 3. gravity: survivors slide down, new cells drop from above (per-reel row step)
+    const rowStepOf = (col: number): number =>
+      this._grid.rowsOf(col) > 1
+        ? this._grid.cellPosition(col, 1).y - this._grid.cellPosition(col, 0).y
+        : this._grid.cellSize(col).height;
     const slides = this._cfg.gravity ? (step.drops ?? this.deriveDrops(step)) : [];
     const anims: Promise<void>[] = [];
 
@@ -172,7 +175,7 @@ export class TumbleController {
       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));
+      cell.position.set(home.x, home.y - rowStepOf(n.col) * (this._grid.rowsOf(n.col) + 1));
       const idx = (perCol[n.col] = (perCol[n.col] ?? 0) + 1);
       anims.push(
         (async () => {

package/src/slot/config/ReelSystemConfig.ts

@@ -8,6 +8,9 @@
 // Design notes are in docs/reels-analysis-and-design.md.
 
 import type { CellFrameStyle } from '../grid/SymbolCell';
+import { resolveGeometry, type CellSizeSpec, type ResolvedGeometry } from '../grid/geometry';
+
+export type { CellSizeSpec, ResolvedGeometry };
 
 /** Names of easing functions available in the engine's `Easing` map (see anim/easing-map.ts). */
 export type EasingName =
@@ -41,8 +44,19 @@ export interface GridConfig {
   rows: number;
   /** Per-reel row counts (Megaways / variable-height reels). Length should equal `cols`. */
   rowsPerReel?: number[];
+  /** Square cell size (shorthand: same width & height, all reels). */
   cellSize: number;
+  /** Rectangular cells, uniform across reels. Override `cellSize` when set. */
+  cellWidth?: number;
+  cellHeight?: number;
+  /** Per-strip cell size (square scalar or {width,height}). Overrides the above for that reel. */
+  cellSizePerReel?: CellSizeSpec[];
+  /** Uniform gap (shorthand for both axes). */
   gap: number;
+  /** Horizontal gap between adjacent reels. Scalar, or per-boundary (length cols-1). Overrides `gap`. */
+  colGap?: number | number[];
+  /** Vertical gap between rows. Scalar, or per-reel (length cols). Overrides `gap`. */
+  rowGap?: number | number[];
   evaluation: EvaluationMode;
   /** For Megaways: clamp per-reel rows to [minRows, maxRows]. */
   minRows?: number;
@@ -553,6 +567,11 @@ export function effectiveRowsPerReel(grid: GridConfig): number[] {
   return Array.from({ length: grid.cols }, () => grid.rows);
 }
 
+/** Resolve a `GridConfig` into a fully-populated per-reel geometry (rectangular / per-strip aware). */
+export function resolveGridGeometry(grid: GridConfig): ResolvedGeometry {
+  return resolveGeometry(grid);
+}
+
 /** Total ways-to-win for a ways/megaways grid (product of per-reel heights). */
 export function waysCount(grid: GridConfig): number {
   return effectiveRowsPerReel(grid).reduce((a, b) => a * b, 1);

package/src/slot/features/extra.ts

@@ -46,8 +46,7 @@ export const MultiplierSymbols: ReelFeature = {
         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;
+    const { x: cx, y: cy } = ctx.grid.center();
     await floatLabel(ctx.fx, cx, cy, `×${capped}`, 0xffe24a, 900);
   },
 };

package/src/slot/features/symbols.ts

@@ -6,6 +6,7 @@ import {
   type FeatureContext,
   type ReelFeature,
   cellCenter,
+  colStepOf,
   floatLabel,
   morphSymbol,
   pickFromBoard,
@@ -96,17 +97,15 @@ export const GiantSymbol: ReelFeature = {
     ctx.log?.(`Giant ${w}×${h} "${sym}"`);
     const view = ctx.resolve(sym);
     if (!view) return;
-    const step = rowStepOf(ctx.grid);
+    const cs = ctx.grid.cellSize(anchorCol);
+    const stepX = colStepOf(ctx.grid, anchorCol);
+    const step = rowStepOf(ctx.grid, anchorCol);
     const tl = cellCenter(ctx.grid, anchorCol, 0);
     const giant = new 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);
+    // span w×h cells (footprint ignores gaps, matching the previous single-cell unit)
+    view.resize?.({ width: cs.width * w, height: cs.height * h });
+    giant.position.set(tl.x + ((w - 1) * stepX) / 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;
@@ -143,11 +142,12 @@ export const SplitSymbol: ReelFeature = {
       left.map(async (p, i) => {
         await Tween.delay((i % 6) * 30);
         const { x, y } = cellCenter(ctx.grid, p.col, p.row);
+        const cs = ctx.grid.cellSize(p.col);
         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,
+          x + cs.width / 3,
+          y - cs.height / 3,
           `×${f.factor}`,
           0x9b5cff,
           600,

package/src/slot/features/types.ts

@@ -43,8 +43,16 @@ export function cellCenter(grid: ReelGrid, col: number, row: number): { x: numbe
   return grid.cellPosition(col, row);
 }
 
-export function rowStepOf(grid: ReelGrid): number {
-  return grid.cellPosition(0, 1).y - grid.cellPosition(0, 0).y;
+/** Vertical row-to-row step for a reel (falls back to the reel's cell height for 1-row reels). */
+export function rowStepOf(grid: ReelGrid, col = 0): number {
+  if (grid.rowsOf(col) > 1) return grid.cellPosition(col, 1).y - grid.cellPosition(col, 0).y;
+  return grid.cellSize(col).height;
+}
+
+/** Horizontal reel-to-reel step at a boundary (falls back to the reel's cell width for 1-col grids). */
+export function colStepOf(grid: ReelGrid, col = 0): number {
+  if (col + 1 < grid.cols) return grid.cellPosition(col + 1, 0).x - grid.cellPosition(col, 0).x;
+  return grid.cellSize(col).width;
 }
 
 /** A glowing ring drawn around a cell. Returns a disposer. */
@@ -57,9 +65,9 @@ export function glowRing(
 ): () => void {
   if (fx.destroyed) return () => {};
   const { x, y } = cellCenter(grid, col, row);
-  const s = grid.cellSize;
+  const { width, height } = grid.cellSize(col);
   const g = new Graphics()
-    .roundRect(x - s / 2, y - s / 2, s, s, 10)
+    .roundRect(x - width / 2, y - height / 2, width, height, 10)
     .stroke({ color, width: 3, alpha: 0.9 });
   fx.addChild(g);
   return () => g.destroy();
@@ -118,7 +126,7 @@ export async function dropCell(
 ): Promise<void> {
   if (cell.destroyed) return;
   const home = grid.cellPosition(col, row);
-  cell.position.set(home.x, home.y - rowStepOf(grid) * (row + 2));
+  cell.position.set(home.x, home.y - rowStepOf(grid, col) * (row + 2));
   cell.alpha = 1;
   cell.scale.set(1);
   await Tween.to(cell, { 'position.y': home.y }, ms, easingByName('easeOutBounce'));

package/src/slot/features/wilds.ts

@@ -69,7 +69,7 @@ export const StickySymbols: ReelFeature = {
         await floatLabel(
           ctx.fx,
           x,
-          y - ctx.grid.cellSize / 2,
+          y - ctx.grid.cellSize(p.col).height / 2,
           f.durationSpins ? `STICKY ${f.durationSpins}` : 'STICKY',
           f.ringColor,
           600 + i * 50,

package/src/slot/grid/AnimatedSymbol.ts

@@ -3,25 +3,32 @@ import { SpriteAnimation } from '../../animation';
 import type { SymbolView } from './SymbolView';
 
 export interface SymbolTextures { base: Texture; idle?: Texture[]; win?: Texture[]; }
-export interface AnimatedSymbolConfig { textures: SymbolTextures; size: number; fps?: number; }
+export interface AnimatedSymbolConfig {
+  textures: SymbolTextures;
+  size: number | { width: number; height: number };
+  fps?: number;
+}
+
+const dims = (size: number | { width: number; height: number }) =>
+  typeof size === 'number' ? { width: size, height: size } : size;
 
 /** Built-in SymbolView: a static base sprite with optional idle/win spritesheet frames. */
 export class AnimatedSymbol extends Container implements SymbolView {
   private _base: Sprite;
   private _anim: AnimatedSprite | null = null;
   private _textures: SymbolTextures;
-  private _size: number;
+  private _w = 0;
+  private _h = 0;
   private _fps: number;
 
   constructor(config: AnimatedSymbolConfig) {
     super();
     this._textures = config.textures;
-    this._size = config.size;
     this._fps = config.fps ?? 24;
     this._base = new Sprite(config.textures.base);
     this._base.anchor.set(0.5);
     this.addChild(this._base);
-    this.resize(this._size);
+    this.resize(config.size);
   }
 
   setTextures(t: SymbolTextures): void {
@@ -30,11 +37,13 @@ export class AnimatedSymbol extends Container implements SymbolView {
     this.showStatic();
   }
 
-  resize(size: number): void {
-    this._size = size;
-    this._base.width = size;
-    this._base.height = size;
-    if (this._anim) { this._anim.width = size; this._anim.height = size; }
+  resize(size: number | { width: number; height: number }): void {
+    const { width, height } = dims(size);
+    this._w = width;
+    this._h = height;
+    this._base.width = width;
+    this._base.height = height;
+    if (this._anim) { this._anim.width = width; this._anim.height = height; }
   }
 
   showStatic(): void {
@@ -59,8 +68,8 @@ export class AnimatedSymbol extends Container implements SymbolView {
     this._base.visible = false;
     const a = SpriteAnimation.create(frames, { loop, autoPlay: true, onComplete });
     a.anchor.set(0.5);
-    a.width = this._size;
-    a.height = this._size;
+    a.width = this._w;
+    a.height = this._h;
     a.animationSpeed = this._fps / 60;
     this.addChild(a);
     this._anim = a;

package/src/slot/grid/ReelGrid.ts

@@ -1,6 +1,12 @@
 import { Container, Graphics, Sprite, type Texture } from 'pixi.js';
 import { SymbolCell, type CellData, type CellFrameStyle } from './SymbolCell';
 import type { SymbolResolver } from './SymbolView';
+import {
+  resolveGeometry,
+  cellPositionOf,
+  type CellSizeSpec,
+  type ResolvedGeometry,
+} from './geometry';
 
 export interface DecorationConfig {
   texture?: Texture;
@@ -12,8 +18,19 @@ export interface ReelGridConfig {
   rows: number;
   /** Per-reel row counts for Megaways / variable-height reels. Length must equal `cols`. */
   rowsPerReel?: number[];
+  /** Square cell size (shorthand: same width & height, all reels). */
   cellSize: number;
+  /** Rectangular cells, uniform across reels. Override `cellSize` when set. */
+  cellWidth?: number;
+  cellHeight?: number;
+  /** Per-strip cell size (square scalar or {width,height}). */
+  cellSizePerReel?: CellSizeSpec[];
+  /** Uniform gap (shorthand for both axes). */
   gap?: number;
+  /** Horizontal gap between adjacent reels. Scalar, or per-boundary (length cols-1). */
+  colGap?: number | number[];
+  /** Vertical gap between rows. Scalar, or per-reel (length cols). */
+  rowGap?: number | number[];
   resolve: SymbolResolver;
   frameStyle?: CellFrameStyle;
   decoration?: DecorationConfig;
@@ -21,17 +38,16 @@ export interface ReelGridConfig {
 }
 
 /**
- * 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.
+ * A grid of `SymbolCell`s. Supports uniform grids, variable-height reels (Megaways), and
+ * rectangular / per-strip cell sizes with per-strip gaps. All layout flows through a single
+ * resolved geometry (see grid/geometry.ts); every consumer reads positions via `cellPosition`
+ * and dimensions via `cellSize(col)` rather than assuming a square cell.
  */
 export class ReelGrid extends Container {
   readonly __uiComponent = true as const;
 
-  private _cols: number;
-  private _rowsPerReel: number[];
-  private _maxRows: number;
-  private _cellSize: number;
-  private _gap: number;
+  private _cfg: ReelGridConfig;
+  private _geom: ResolvedGeometry;
   private _cells: SymbolCell[][] = [];
   private _cellLayer = new Container();
   private _resolve: SymbolResolver;
@@ -40,28 +56,18 @@ export class ReelGrid extends Container {
 
   constructor(config: ReelGridConfig) {
     super();
-    this._cols = config.cols;
-    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._cfg = { ...config };
     this._resolve = config.resolve;
     this._frameStyle = config.frameStyle;
+    this._geom = resolveGeometry(config);
 
-    if (config.decoration) {
+    if (config.decoration?.texture) {
       const pad = config.decoration.padding ?? 0;
-      const w = this._cols * (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 Sprite(config.decoration.texture);
-        deco.width = w;
-        deco.height = h;
-        deco.position.set(-pad - this._cellSize / 2, -pad - this._cellSize / 2);
-        this.addChild(deco);
-      }
+      const deco = new Sprite(config.decoration.texture);
+      deco.width = this._geom.gridW + pad * 2;
+      deco.height = this._geom.gridH + pad * 2;
+      deco.position.set(this._geom.leftX - pad, this._geom.topY - pad);
+      this.addChild(deco);
     }
 
     this.addChild(this._cellLayer);
@@ -70,12 +76,19 @@ export class ReelGrid extends Container {
     if (config.mask) this._applyMask();
   }
 
+  private get _cols(): number {
+    return this._geom.cols;
+  }
+  private get _rowsPerReel(): number[] {
+    return this._geom.rowsPerReel;
+  }
+
   private _buildCells(): void {
     for (let c = 0; c < this._cols; c++) {
       this._cells[c] = [];
       for (let r = 0; r < this._rowsPerReel[c]; r++) {
         const cell = new SymbolCell({
-          size: this._cellSize,
+          size: this.cellSize(c),
           resolve: this._resolve,
           frameStyle: this._frameStyle,
         });
@@ -87,10 +100,19 @@ export class ReelGrid extends Container {
     }
   }
 
+  /** Per-strip mask: one window per reel sized to that reel's own cell width × column height. */
   private _applyMask(): void {
-    const w = this._cols * (this._cellSize + this._gap) - this._gap;
-    const h = this._maxRows * (this._cellSize + this._gap) - this._gap;
-    const m = new Graphics().rect(-this._cellSize / 2, -this._cellSize / 2, w, h).fill(0xffffff);
+    const g = this._geom;
+    const m = new Graphics();
+    for (let c = 0; c < this._cols; c++) {
+      const rows = this._rowsPerReel[c];
+      const w = g.cellW[c];
+      const h = rows * g.cellH[c] + Math.max(0, rows - 1) * g.rowGap[c];
+      const x = g.colX[c] - w / 2;
+      const y = g.yOff[c] - g.cellH[c] / 2;
+      m.rect(x, y, w, h);
+    }
+    m.fill(0xffffff);
     this._cellLayer.mask = m;
     this.addChild(m);
     this._mask = m;
@@ -101,10 +123,15 @@ export class ReelGrid extends Container {
   }
   /** Tallest reel's row count (the grid's visual height in rows). */
   get rows(): number {
-    return this._maxRows;
+    return this._geom.maxRows;
+  }
+  /** Cell dimensions (px) for a reel. Rectangular / per-strip aware. */
+  cellSize(col: number): { width: number; height: number } {
+    return { width: this._geom.cellW[col] ?? 0, height: this._geom.cellH[col] ?? 0 };
   }
-  get cellSize(): number {
-    return this._cellSize;
+  /** The fully-resolved grid geometry (read-only view). */
+  get geometry(): ResolvedGeometry {
+    return this._geom;
   }
   rowsOf(col: number): number {
     return this._rowsPerReel[col] ?? 0;
@@ -113,12 +140,14 @@ export class ReelGrid extends Container {
     return this._rowsPerReel.slice();
   }
 
-  /** Cell centre position. Variable-height reels are centred in the max-rows envelope. */
+  /** Cell centre position. Variable-height reels are centred about a shared centre line. */
   cellPosition(col: number, row: number): { x: number; y: number } {
-    const step = this._cellSize + this._gap;
-    const reelRows = this._rowsPerReel[col] ?? this._maxRows;
-    const yOffset = ((this._maxRows - reelRows) / 2) * step;
-    return { x: col * step, y: yOffset + row * step };
+    return cellPositionOf(this._geom, col, row);
+  }
+
+  /** Grid bounding-box centre in local coords. */
+  center(): { x: number; y: number } {
+    return { x: this._geom.centerX, y: this._geom.centerY };
   }
 
   getCell(col: number, row: number): SymbolCell {
@@ -138,8 +167,8 @@ export class ReelGrid extends Container {
     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._cfg = { ...this._cfg, rowsPerReel: rowsPerReel.slice() };
+    this._geom = resolveGeometry(this._cfg);
     this._buildCells();
     if (this._mask) {
       this._mask.destroy();
@@ -149,8 +178,18 @@ export class ReelGrid extends Container {
     }
   }
 
-  resize(cellSize: number): void {
-    this._cellSize = cellSize;
+  /**
+   * Re-resolve geometry after a base cell-size change and reposition cells. Accepts a square
+   * scalar (updates `cellSize`) or explicit `{width,height}`. Per-strip overrides still apply.
+   * (Cell frames are not re-drawn here — a geometry change routes through a full rebuild upstream.)
+   */
+  resize(size: number | { width: number; height: number }): void {
+    if (typeof size === 'number') {
+      this._cfg = { ...this._cfg, cellSize: size, cellWidth: undefined, cellHeight: undefined };
+    } else {
+      this._cfg = { ...this._cfg, cellWidth: size.width, cellHeight: size.height };
+    }
+    this._geom = resolveGeometry(this._cfg);
     for (let c = 0; c < this._cols; c++) {
       for (let r = 0; r < this._rowsPerReel[c]; r++) {
         const { x, y } = this.cellPosition(c, r);