@almadar/ui 5.67.0 → 5.68.0

package/dist/components/game/molecules/IsometricCanvas.d.ts

@@ -80,7 +80,7 @@ export interface IsometricCanvasProps {
     }>;
     /** Declarative event: emits UI:{tileLeaveEvent} with {} on tile leave */
     tileLeaveEvent?: EventEmit<Record<string, never>>;
-    /** Tile layout projection: 'isometric' (default 2:1 diamond) or 'hex' (pointy-top offset rows) */
+    /** Tile layout projection: 'isometric' (default 2:1 diamond), 'hex' (pointy-top offset rows), or 'flat' (orthographic top-down square grid) */
     tileLayout?: TileLayout;
     /** Render scale (0.4 = 40% zoom) */
     scale?: number;

package/dist/components/game/organisms/BoardgameBoard.d.ts

@@ -0,0 +1,37 @@
+import React from 'react';
+import type { AssetUrl, EventEmit } from '@almadar/core';
+import type { IsometricTile, IsometricUnit, IsometricFeature } from './types/isometric';
+import type { DisplayStateProps } from '../../core/organisms/types';
+import type { IsometricCanvasProps } from '../molecules/IsometricCanvas';
+export interface BoardgameBoardProps extends DisplayStateProps {
+    /** Board squares (flat top-down grid tiles) */
+    tiles?: IsometricTile[];
+    /** Tokens/units on the board */
+    units?: IsometricUnit[];
+    /** Features (markers, structures, etc.) on the board */
+    features?: IsometricFeature[];
+    /** Asset sprite manifest (same shape as IsometricCanvas.assetManifest) */
+    assetManifest?: IsometricCanvasProps['assetManifest'];
+    /** Base URL prepended to asset paths */
+    assetBaseUrl?: AssetUrl;
+    /** Render scale */
+    scale?: number;
+    /** Show minimap overlay */
+    showMinimap?: boolean;
+    /** Enable camera pan/zoom controls */
+    enableCamera?: boolean;
+    /** Declarative event: emits UI:{tileClickEvent} with { x, y } on tile click */
+    tileClickEvent?: EventEmit<{
+        x: number;
+        y: number;
+    }>;
+    /** Declarative event: emits UI:{unitClickEvent} with { unitId } on unit click */
+    unitClickEvent?: EventEmit<{
+        unitId: string;
+    }>;
+}
+export declare function BoardgameBoard({ tiles, units, features, assetManifest, assetBaseUrl, scale, showMinimap, enableCamera, tileClickEvent, unitClickEvent, isLoading, error, className, }: BoardgameBoardProps): React.ReactElement;
+export declare namespace BoardgameBoard {
+    var displayName: string;
+}
+export default BoardgameBoard;

package/dist/components/game/organisms/FishingBoard.d.ts

@@ -0,0 +1,33 @@
+import React from 'react';
+import type { AssetUrl, EventEmit } from '@almadar/core';
+import type { DisplayStateProps } from '../../core/organisms/types';
+export interface FishingBoardProps extends DisplayStateProps {
+    /** Background image URL for the fishing scene */
+    backgroundImage?: AssetUrl;
+    /** Base URL prepended to asset paths */
+    assetBaseUrl?: AssetUrl;
+    /** Render scale */
+    scale?: number;
+    /** Show minimap overlay */
+    showMinimap?: boolean;
+    /** Enable camera pan/zoom controls */
+    enableCamera?: boolean;
+    /** Canvas width in pixels */
+    width?: number;
+    /** Canvas height in pixels */
+    height?: number;
+    /** Declarative event: emits UI:{tileClickEvent} with { x, y } on tile click */
+    tileClickEvent?: EventEmit<{
+        x: number;
+        y: number;
+    }>;
+    /** Declarative event: emits UI:{unitClickEvent} with { unitId } on unit click */
+    unitClickEvent?: EventEmit<{
+        unitId: string;
+    }>;
+}
+export declare function FishingBoard({ backgroundImage, assetBaseUrl, scale, showMinimap, enableCamera, width, height, isLoading, error, className, }: FishingBoardProps): React.ReactElement;
+export declare namespace FishingBoard {
+    var displayName: string;
+}
+export default FishingBoard;

package/dist/components/game/organisms/HolidayRunnerBoard.d.ts

@@ -0,0 +1,35 @@
+import React from 'react';
+import type { AssetUrl, EventEmit } from '@almadar/core';
+import type { DisplayStateProps } from '../../core/organisms/types';
+export interface HolidayRunnerBoardProps extends DisplayStateProps {
+    /** Background image URL for the runner level */
+    backgroundImage?: AssetUrl;
+    /** Base URL prefix for asset URLs */
+    assetBaseUrl?: AssetUrl;
+    /** Canvas width in pixels */
+    width?: number;
+    /** Canvas height in pixels */
+    height?: number;
+    /** Target frames per second */
+    fps?: number;
+    /** Render scale */
+    scale?: number;
+    /** Show minimap overlay */
+    showMinimap?: boolean;
+    /** Enable camera pan/zoom controls */
+    enableCamera?: boolean;
+    /** Declarative event: emits UI:{tickEvent} with { dt, frame } each tick */
+    tickEvent?: EventEmit<{
+        dt: number;
+        frame: number;
+    }>;
+    /** Declarative event: emits UI:{drawEvent} with { frame } each draw frame */
+    drawEvent?: EventEmit<{
+        frame: number;
+    }>;
+}
+export declare function HolidayRunnerBoard({ backgroundImage, assetBaseUrl, width, height, fps, isLoading, error, className, }: HolidayRunnerBoardProps): React.ReactElement;
+export declare namespace HolidayRunnerBoard {
+    var displayName: string;
+}
+export default HolidayRunnerBoard;

package/dist/components/game/organisms/MatchPuzzleBoard.d.ts

@@ -0,0 +1,37 @@
+import React from 'react';
+import type { AssetUrl, EventEmit } from '@almadar/core';
+import type { IsometricTile, IsometricUnit, IsometricFeature } from './types/isometric';
+import type { DisplayStateProps } from '../../core/organisms/types';
+import type { IsometricCanvasProps } from '../molecules/IsometricCanvas';
+export interface MatchPuzzleBoardProps extends DisplayStateProps {
+    /** Grid tiles for the match puzzle board */
+    tiles?: IsometricTile[];
+    /** Units on the board */
+    units?: IsometricUnit[];
+    /** Gem/feature items on the board */
+    features?: IsometricFeature[];
+    /** Asset sprite manifest (same shape as IsometricCanvas.assetManifest) */
+    assetManifest?: IsometricCanvasProps['assetManifest'];
+    /** Base URL prepended to manifest sprite paths */
+    assetBaseUrl?: AssetUrl;
+    /** Render scale */
+    scale?: number;
+    /** Show minimap overlay */
+    showMinimap?: boolean;
+    /** Enable camera pan/zoom controls */
+    enableCamera?: boolean;
+    /** Declarative event: emits UI:{tileClickEvent} with { x, y } on tile click */
+    tileClickEvent?: EventEmit<{
+        x: number;
+        y: number;
+    }>;
+    /** Declarative event: emits UI:{unitClickEvent} with { unitId } on unit click */
+    unitClickEvent?: EventEmit<{
+        unitId: string;
+    }>;
+}
+export declare function MatchPuzzleBoard({ tiles, units, features, assetManifest, assetBaseUrl, scale, showMinimap, enableCamera, tileClickEvent, unitClickEvent, isLoading, error, className, }: MatchPuzzleBoardProps): React.ReactElement;
+export declare namespace MatchPuzzleBoard {
+    var displayName: string;
+}
+export default MatchPuzzleBoard;

package/dist/components/game/organisms/MinigolfBoard.d.ts

@@ -0,0 +1,37 @@
+import React from 'react';
+import type { AssetUrl, EventEmit } from '@almadar/core';
+import type { IsometricTile, IsometricUnit, IsometricFeature } from './types/isometric';
+import type { DisplayStateProps } from '../../core/organisms/types';
+import type { IsometricCanvasProps } from '../molecules/IsometricCanvas';
+export interface MinigolfBoardProps extends DisplayStateProps {
+    /** Isometric grid tiles */
+    tiles?: IsometricTile[];
+    /** Units on the board */
+    units?: IsometricUnit[];
+    /** Features (holes, obstacles, etc.) on the board */
+    features?: IsometricFeature[];
+    /** Asset sprite manifest (same shape as IsometricCanvas.assetManifest) */
+    assetManifest?: IsometricCanvasProps['assetManifest'];
+    /** Base URL prepended to manifest sprite paths */
+    assetBaseUrl?: AssetUrl;
+    /** Render scale */
+    scale?: number;
+    /** Show minimap overlay */
+    showMinimap?: boolean;
+    /** Enable camera pan/zoom controls */
+    enableCamera?: boolean;
+    /** Declarative event: emits UI:{tileClickEvent} with { x, y } on tile click */
+    tileClickEvent?: EventEmit<{
+        x: number;
+        y: number;
+    }>;
+    /** Declarative event: emits UI:{unitClickEvent} with { unitId } on unit click */
+    unitClickEvent?: EventEmit<{
+        unitId: string;
+    }>;
+}
+export declare function MinigolfBoard({ tiles, units, features, assetManifest, assetBaseUrl, scale, showMinimap, enableCamera, tileClickEvent, unitClickEvent, isLoading, error, className, }: MinigolfBoardProps): React.ReactElement;
+export declare namespace MinigolfBoard {
+    var displayName: string;
+}
+export default MinigolfBoard;

package/dist/components/game/organisms/PinballBoard.d.ts

@@ -0,0 +1,35 @@
+import React from 'react';
+import type { AssetUrl, EventEmit } from '@almadar/core';
+import type { DisplayStateProps } from '../../core/organisms/types';
+export interface PinballBoardProps extends DisplayStateProps {
+    /** Playfield tiles */
+    tiles?: unknown[];
+    /** Ball units on the board */
+    units?: unknown[];
+    /** Features (bumpers, paddles, etc.) on the board */
+    features?: unknown[];
+    /** Asset sprite manifest */
+    assetManifest?: string;
+    /** Base URL prepended to manifest sprite paths */
+    assetBaseUrl?: AssetUrl;
+    /** Render scale */
+    scale?: number;
+    /** Show minimap overlay */
+    showMinimap?: boolean;
+    /** Enable camera pan/zoom controls */
+    enableCamera?: boolean;
+    /** Declarative event: emits UI:{tileClickEvent} with { x, y } on tile click */
+    tileClickEvent?: EventEmit<{
+        x: number;
+        y: number;
+    }>;
+    /** Declarative event: emits UI:{unitClickEvent} with { unitId } on unit click */
+    unitClickEvent?: EventEmit<{
+        unitId: string;
+    }>;
+}
+export declare function PinballBoard({ tiles: _tiles, units: _units, features: _features, assetManifest: _assetManifest, assetBaseUrl, scale, showMinimap: _showMinimap, enableCamera: _enableCamera, tileClickEvent: _tileClickEvent, unitClickEvent: _unitClickEvent, isLoading, error, className, }: PinballBoardProps): React.ReactElement;
+export declare namespace PinballBoard {
+    var displayName: string;
+}
+export default PinballBoard;

package/dist/components/game/organisms/PirateBoard.d.ts

@@ -0,0 +1,37 @@
+import React from 'react';
+import type { AssetUrl, EventEmit } from '@almadar/core';
+import type { IsometricTile, IsometricUnit, IsometricFeature } from './types/isometric';
+import type { DisplayStateProps } from '../../core/organisms/types';
+import type { IsometricCanvasProps } from '../molecules/IsometricCanvas';
+export interface PirateBoardProps extends DisplayStateProps {
+    /** Sea/island grid tiles */
+    tiles?: IsometricTile[];
+    /** Ship and crew units on the board */
+    units?: IsometricUnit[];
+    /** Features (ports, treasures, etc.) on the board */
+    features?: IsometricFeature[];
+    /** Asset sprite manifest (same shape as IsometricCanvas.assetManifest) */
+    assetManifest?: IsometricCanvasProps['assetManifest'];
+    /** Base URL prepended to manifest sprite paths */
+    assetBaseUrl?: AssetUrl;
+    /** Render scale */
+    scale?: number;
+    /** Show minimap overlay */
+    showMinimap?: boolean;
+    /** Enable camera pan/zoom controls */
+    enableCamera?: boolean;
+    /** Declarative event: emits UI:{tileClickEvent} with { x, y } on tile click */
+    tileClickEvent?: EventEmit<{
+        x: number;
+        y: number;
+    }>;
+    /** Declarative event: emits UI:{unitClickEvent} with { unitId } on unit click */
+    unitClickEvent?: EventEmit<{
+        unitId: string;
+    }>;
+}
+export declare function PirateBoard({ tiles, units, features, assetManifest, assetBaseUrl, scale, showMinimap, enableCamera, tileClickEvent, unitClickEvent, isLoading, error, className, }: PirateBoardProps): React.ReactElement;
+export declare namespace PirateBoard {
+    var displayName: string;
+}
+export default PirateBoard;

package/dist/components/game/organisms/RacingBoard.d.ts

@@ -0,0 +1,29 @@
+import React from 'react';
+import type { AssetUrl, EventEmit } from '@almadar/core';
+import type { DisplayStateProps } from '../../core/organisms/types';
+export interface RacingBoardProps extends DisplayStateProps {
+    /** Race track background image URL */
+    backgroundImage?: AssetUrl;
+    /** Base URL prepended to asset paths */
+    assetBaseUrl?: AssetUrl;
+    /** Canvas width in pixels */
+    width?: number;
+    /** Canvas height in pixels */
+    height?: number;
+    /** Target frames per second */
+    fps?: number;
+    /** Declarative event: emits UI:{tickEvent} with { dt, frame } each tick */
+    tickEvent?: EventEmit<{
+        dt: number;
+        frame: number;
+    }>;
+    /** Declarative event: emits UI:{drawEvent} with { frame } each draw frame */
+    drawEvent?: EventEmit<{
+        frame: number;
+    }>;
+}
+export declare function RacingBoard({ backgroundImage, assetBaseUrl, width, height, fps, tickEvent, drawEvent, className, }: RacingBoardProps): React.ReactElement;
+export declare namespace RacingBoard {
+    var displayName: string;
+}
+export default RacingBoard;

package/dist/components/game/organisms/SokobanBoard.d.ts

@@ -0,0 +1,37 @@
+import React from 'react';
+import type { AssetUrl, EventEmit } from '@almadar/core';
+import type { IsometricTile, IsometricUnit, IsometricFeature } from './types/isometric';
+import type { DisplayStateProps } from '../../core/organisms/types';
+import type { IsometricCanvasProps } from '../molecules/IsometricCanvas';
+export interface SokobanBoardProps extends DisplayStateProps {
+    /** Grid tiles (floor, wall, target) */
+    tiles?: IsometricTile[];
+    /** Units on the board (the pusher character) */
+    units?: IsometricUnit[];
+    /** Features (crates) on the board */
+    features?: IsometricFeature[];
+    /** Asset sprite manifest (same shape as IsometricCanvas.assetManifest) */
+    assetManifest?: IsometricCanvasProps['assetManifest'];
+    /** Base URL prepended to manifest sprite paths */
+    assetBaseUrl?: AssetUrl;
+    /** Render scale */
+    scale?: number;
+    /** Show minimap overlay */
+    showMinimap?: boolean;
+    /** Enable camera pan/zoom controls */
+    enableCamera?: boolean;
+    /** Declarative event: emits UI:{tileClickEvent} with { x, y } on tile click */
+    tileClickEvent?: EventEmit<{
+        x: number;
+        y: number;
+    }>;
+    /** Declarative event: emits UI:{unitClickEvent} with { unitId } on unit click */
+    unitClickEvent?: EventEmit<{
+        unitId: string;
+    }>;
+}
+export declare function SokobanBoard({ tiles, units, features, assetManifest, assetBaseUrl, scale, showMinimap, enableCamera, tileClickEvent, unitClickEvent, isLoading, error, className, }: SokobanBoardProps): React.ReactElement;
+export declare namespace SokobanBoard {
+    var displayName: string;
+}
+export default SokobanBoard;

package/dist/components/game/organisms/SpaceShmupBoard.d.ts

@@ -0,0 +1,20 @@
+import React from 'react';
+import type { AssetUrl } from '@almadar/core';
+import type { DisplayStateProps } from '../../core/organisms/types';
+export interface SpaceShmupBoardProps extends DisplayStateProps {
+    /** Background image URL (starfield / space scene) */
+    backgroundImage?: AssetUrl;
+    /** Base URL prefix for asset URLs */
+    assetBaseUrl?: AssetUrl;
+    /** Canvas width in pixels */
+    width?: number;
+    /** Canvas height in pixels */
+    height?: number;
+    /** Target frames per second */
+    fps?: number;
+}
+export declare function SpaceShmupBoard({ backgroundImage, assetBaseUrl, width, height, fps, isLoading, error, className, }: SpaceShmupBoardProps): React.ReactElement;
+export declare namespace SpaceShmupBoard {
+    var displayName: string;
+}
+export default SpaceShmupBoard;

package/dist/components/game/organisms/SpaceStationBoard.d.ts

@@ -0,0 +1,37 @@
+import React from 'react';
+import type { AssetUrl, EventEmit } from '@almadar/core';
+import type { IsometricTile, IsometricUnit, IsometricFeature } from './types/isometric';
+import type { DisplayStateProps } from '../../core/organisms/types';
+import type { IsometricCanvasProps } from '../molecules/IsometricCanvas';
+export interface SpaceStationBoardProps extends DisplayStateProps {
+    /** Isometric grid tiles */
+    tiles?: IsometricTile[];
+    /** Units on the board */
+    units?: IsometricUnit[];
+    /** Features (consoles, airlocks, etc.) on the board */
+    features?: IsometricFeature[];
+    /** Asset sprite manifest (same shape as IsometricCanvas.assetManifest) */
+    assetManifest?: IsometricCanvasProps['assetManifest'];
+    /** Base URL prepended to manifest sprite paths */
+    assetBaseUrl?: AssetUrl;
+    /** Render scale */
+    scale?: number;
+    /** Show minimap overlay */
+    showMinimap?: boolean;
+    /** Enable camera pan/zoom controls */
+    enableCamera?: boolean;
+    /** Declarative event: emits UI:{tileClickEvent} with { x, y } on tile click */
+    tileClickEvent?: EventEmit<{
+        x: number;
+        y: number;
+    }>;
+    /** Declarative event: emits UI:{unitClickEvent} with { unitId } on unit click */
+    unitClickEvent?: EventEmit<{
+        unitId: string;
+    }>;
+}
+export declare function SpaceStationBoard({ tiles, units, features, assetManifest, assetBaseUrl, scale, showMinimap, enableCamera, tileClickEvent, unitClickEvent, isLoading, error, className, }: SpaceStationBoardProps): React.ReactElement;
+export declare namespace SpaceStationBoard {
+    var displayName: string;
+}
+export default SpaceStationBoard;

package/dist/components/game/organisms/SportsBoard.d.ts

@@ -0,0 +1,37 @@
+import React from 'react';
+import type { AssetUrl, EventEmit } from '@almadar/core';
+import type { IsometricTile, IsometricUnit, IsometricFeature } from './types/isometric';
+import type { DisplayStateProps } from '../../core/organisms/types';
+import type { IsometricCanvasProps } from '../molecules/IsometricCanvas';
+export interface SportsBoardProps extends DisplayStateProps {
+    /** Court/field terrain tiles */
+    tiles?: IsometricTile[];
+    /** Player units on the board */
+    units?: IsometricUnit[];
+    /** Features (goals, markers, etc.) on the board */
+    features?: IsometricFeature[];
+    /** Asset sprite manifest (same shape as IsometricCanvas.assetManifest) */
+    assetManifest?: IsometricCanvasProps['assetManifest'];
+    /** Base URL prepended to asset paths */
+    assetBaseUrl?: AssetUrl;
+    /** Render scale */
+    scale?: number;
+    /** Show minimap overlay */
+    showMinimap?: boolean;
+    /** Enable camera pan/zoom controls */
+    enableCamera?: boolean;
+    /** Declarative event: emits UI:{tileClickEvent} with { x, y } on tile click */
+    tileClickEvent?: EventEmit<{
+        x: number;
+        y: number;
+    }>;
+    /** Declarative event: emits UI:{unitClickEvent} with { unitId } on unit click */
+    unitClickEvent?: EventEmit<{
+        unitId: string;
+    }>;
+}
+export declare function SportsBoard({ tiles, units, features, assetManifest, assetBaseUrl, scale, showMinimap, enableCamera, tileClickEvent, unitClickEvent, isLoading, error, className, }: SportsBoardProps): React.ReactElement;
+export declare namespace SportsBoard {
+    var displayName: string;
+}
+export default SportsBoard;

package/dist/components/game/organisms/TanksBoard.d.ts

@@ -0,0 +1,37 @@
+import React from 'react';
+import type { AssetUrl, EventEmit } from '@almadar/core';
+import type { IsometricTile, IsometricUnit, IsometricFeature } from './types/isometric';
+import type { DisplayStateProps } from '../../core/organisms/types';
+import type { IsometricCanvasProps } from '../molecules/IsometricCanvas';
+export interface TanksBoardProps extends DisplayStateProps {
+    /** Ground/sand terrain tiles */
+    tiles?: IsometricTile[];
+    /** Tank units on the board */
+    units?: IsometricUnit[];
+    /** Features (obstacles, structures, etc.) on the board */
+    features?: IsometricFeature[];
+    /** Asset sprite manifest (same shape as IsometricCanvas.assetManifest) */
+    assetManifest?: IsometricCanvasProps['assetManifest'];
+    /** Base URL prepended to manifest sprite paths */
+    assetBaseUrl?: AssetUrl;
+    /** Render scale */
+    scale?: number;
+    /** Show minimap overlay */
+    showMinimap?: boolean;
+    /** Enable camera pan/zoom controls */
+    enableCamera?: boolean;
+    /** Declarative event: emits UI:{tileClickEvent} with { x, y } on tile click */
+    tileClickEvent?: EventEmit<{
+        x: number;
+        y: number;
+    }>;
+    /** Declarative event: emits UI:{unitClickEvent} with { unitId } on unit click */
+    unitClickEvent?: EventEmit<{
+        unitId: string;
+    }>;
+}
+export declare function TanksBoard({ tiles, units, features, assetManifest, assetBaseUrl, scale, showMinimap, enableCamera, tileClickEvent, unitClickEvent, isLoading, error, className, }: TanksBoardProps): React.ReactElement;
+export declare namespace TanksBoard {
+    var displayName: string;
+}
+export default TanksBoard;

package/dist/components/game/organisms/index.d.ts

@@ -51,3 +51,16 @@ export { createInitialGameState, calculateValidMoves, calculateAttackTargets, }
 export type { Position, GameUnit, UnitTrait, BoardTile, GamePhase, GameState, GameAction, } from './types/game';
 export { combatAnimations, combatClasses, combatEffects, applyTemporaryEffect, calculateDamage, generateCombatMessage, } from './utils/combatEffects';
 export type { CombatEffect, DamageResult, CombatEventType, CombatEventData, } from './utils/combatEffects';
+export { RacingBoard, type RacingBoardProps } from './RacingBoard';
+export { TanksBoard, type TanksBoardProps } from './TanksBoard';
+export { SpaceShmupBoard, type SpaceShmupBoardProps } from './SpaceShmupBoard';
+export { SportsBoard, type SportsBoardProps } from './SportsBoard';
+export { SokobanBoard, type SokobanBoardProps } from './SokobanBoard';
+export { BoardgameBoard, type BoardgameBoardProps } from './BoardgameBoard';
+export { PirateBoard, type PirateBoardProps } from './PirateBoard';
+export { PinballBoard, type PinballBoardProps } from './PinballBoard';
+export { FishingBoard, type FishingBoardProps } from './FishingBoard';
+export { MatchPuzzleBoard, type MatchPuzzleBoardProps } from './MatchPuzzleBoard';
+export { HolidayRunnerBoard, type HolidayRunnerBoardProps } from './HolidayRunnerBoard';
+export { MinigolfBoard, type MinigolfBoardProps } from './MinigolfBoard';
+export { SpaceStationBoard, type SpaceStationBoardProps } from './SpaceStationBoard';

package/dist/components/game/organisms/utils/isometric.d.ts

@@ -30,6 +30,7 @@ export declare const FEATURE_COLORS: Record<string, string>;
 /**
  * Tile layout mode. 'isometric' = 2:1 diamond projection (default).
  * 'hex' = pointy-top offset-row hex grid.
+ * 'flat' = orthographic top-down square grid (sokoban/tanks/sports/etc.).
  *
  * Hex constants (at scale=1):
  *   w = TILE_WIDTH (256)   — horizontal cell width
@@ -37,13 +38,21 @@ export declare const FEATURE_COLORS: Record<string, string>;
  * Forward:  screenX = col*w + (row&1)*(w/2) + baseOffsetX
  *           screenY = row * (h * 0.75)
  * Inverse: row = round(screenY / (h*0.75)); col = round((screenX - (row&1)*(w/2) - baseOffsetX) / w)
+ *
+ * Flat constants (at scale=1):
+ *   cellW = TILE_WIDTH (256) — horizontal cell pitch
+ *   cellH = FLOOR_HEIGHT (128) — vertical cell pitch (= cellW/2; keeps same visual scale as hex rows)
+ * Forward:  screenX = col*cellW + baseOffsetX
+ *           screenY = row * cellH
+ * Inverse:  col = round((screenX - baseOffsetX) / cellW); row = round(screenY / cellH)
  */
-export type TileLayout = 'isometric' | 'hex';
+export type TileLayout = 'isometric' | 'hex' | 'flat';
 /**
  * Convert tile grid coordinates to screen pixel coordinates.
  *
  * For 'isometric' (default): 2:1 diamond projection.
  * For 'hex': pointy-top offset-row projection (odd rows shifted right by w/2).
+ * For 'flat': orthographic top-down square grid; col maps to X, row maps to Y.
  *
  * @param tileX - Grid X (col) coordinate
  * @param tileY - Grid Y (row) coordinate