@almadar/ui 5.105.0 → 5.107.0

package/dist/components/game/{shared → three}/lib/game3dAssetManifest.d.ts

@@ -10,7 +10,7 @@
  * @packageDocumentation
  */
 import type { Asset, EntityRow } from '@almadar/core';
-import type { IsometricTile, IsometricFeature } from '../isometricTypes';
+import type { IsometricTile, IsometricFeature } from '../../lib/isometricTypes';
 /** GLB model assets for a 3D board, keyed by terrain "kind" and (optionally) feature type. */
 export interface Game3DAssetManifest {
     /** Floor model assets by terrain kind ('wall' | 'dirt' | 'open'). */

package/dist/components/game/three/molecules/GameCanvas3D.d.ts

@@ -0,0 +1,175 @@
+/**
+ * GameCanvas3D — the thin 3D draw-host (Drawable Canvas, P6 closing).
+ *
+ * The 3D twin of Canvas2D: the board authors a `drawables` list (the neutral
+ * `draw-*` children) and this host maps each descriptor through `Drawable3D` to a
+ * three.js mesh (a raw descriptor NEVER reaches `<group>{children}` — R3F throws).
+ * It owns NO game data — tiles, units, features, selection, health bars and labels
+ * are all `draw-*` children composed in `.lolo`, not props here. Only view state
+ * (camera, error boundary) is local.
+ *
+ * Camera: `isometric`/`perspective`/`top-down` frame the scene bounds (derived from
+ * the drawn descriptors); `follow`/`chase` track the neutral core `Camera.target`
+ * (forwarded as `followTarget`), falling back to the scene centre.
+ *
+ * Interaction: keyboard maps to semantic events (device-agnostic input). Pointer
+ * click/hover on neutral drawables needs a per-entity id + a scene-space raycast
+ * the descriptors don't yet carry — that hit-test is a tracked fork
+ * (docs/Almadar_Std_Game_V2_PLAN.md); the click/hover event props are accepted but
+ * not yet emitted from a raycast.
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+import type { EventEmit, Asset, ScenePos } from '@almadar/core';
+import * as THREE from 'three';
+import type { DrawableNode } from '../../../../lib/drawable/paintDispatch';
+import type { IsometricTile, IsometricUnit, IsometricFeature } from '../../lib/isometricTypes';
+import './GameCanvas3D.css';
+export type { IsometricTile, IsometricUnit, IsometricFeature };
+/** Camera mode for 3D view.
+ *  - `follow` tracks `followTarget` (the neutral `Camera.target`) from a fixed offset.
+ *  - `chase` sits behind + above the target. */
+export type CameraMode = 'isometric' | 'perspective' | 'top-down' | 'follow' | 'chase';
+/** Per-role model manifest (retained type export; the thin host no longer resolves
+ *  models from a manifest — a `draw-sprite` carries its own `Asset`). */
+export interface GameCanvas3DAssetManifest {
+    terrains?: Record<string, Asset>;
+    units?: Record<string, Asset>;
+    features?: Record<string, Asset>;
+    effects?: Record<string, Asset>;
+}
+/** Map orientation */
+export type MapOrientation = 'standard' | 'rotated';
+/** Overlay control */
+export type OverlayControl = 'default' | 'hidden' | 'minimap';
+/** Props for GameCanvas3D component */
+export interface GameCanvas3DProps {
+    /** Additional CSS classes */
+    className?: string;
+    /** Children to render inside the 3D canvas (e.g., physics objects, custom meshes) */
+    children?: React.ReactNode;
+    /** Neutral drawable descriptors — the same `children` vocabulary as Canvas2D. The
+     *  host maps each through `Drawable3D` to a mesh. */
+    drawables?: DrawableNode[];
+    /** Loading state indicator */
+    isLoading?: boolean;
+    /** Error state */
+    error?: string | null;
+    /** Fog of war data (accepted for API parity; presentation-only). */
+    fogOfWar?: boolean[][];
+    /** Map orientation (data attribute). */
+    orientation?: MapOrientation;
+    /** Camera mode */
+    cameraMode?: CameraMode;
+    /** Follow-camera target in scene space (the neutral core `Camera.target`). */
+    followTarget?: ScenePos;
+    /** Show grid */
+    showGrid?: boolean;
+    /** Show coordinates overlay (accepted for API parity). */
+    showCoordinates?: boolean;
+    /** Show tile information (accepted for API parity). */
+    showTileInfo?: boolean;
+    /** Overlay control mode (data attribute). */
+    overlay?: OverlayControl;
+    /** Enable shadows */
+    shadows?: boolean;
+    /** Background color */
+    backgroundColor?: string;
+    /** Declarative event: tile click. Emitted from a ground-plane raycast → scene cell
+     *  `{ x, z }` (the FSM validates the cell). `tileId` is optional — the neutral host
+     *  has no per-tile id, and the board FSMs key off the coordinate. */
+    tileClickEvent?: EventEmit<{
+        x: number;
+        z: number;
+        tileId?: string;
+        type?: string;
+        terrain?: string;
+        elevation?: number;
+    }>;
+    /** Declarative event: unit click. Emitted `{ unitId, x, z }` when the raycast lands on a
+     *  cell whose descriptor carries an `id` (a tagged unit sprite). */
+    unitClickEvent?: EventEmit<{
+        unitId: string;
+        x: number;
+        z: number;
+        unitType?: string;
+        name?: string;
+        team?: string;
+        faction?: string;
+        health?: number;
+        maxHealth?: number;
+    }>;
+    /** Declarative event: feature click. Accepted; not yet emitted (see `tileClickEvent`). */
+    featureClickEvent?: EventEmit<{
+        featureId: string;
+        x: number;
+        z: number;
+        type?: string;
+        elevation?: number;
+    }>;
+    /** Declarative event: canvas (background) click. */
+    canvasClickEvent?: EventEmit<{
+        clientX: number;
+        clientY: number;
+        button: number;
+    }>;
+    /** Declarative event: tile hover. Accepted; not yet emitted (see `tileClickEvent`). */
+    tileHoverEvent?: EventEmit<{
+        tileId: string;
+        x: number;
+        z: number;
+        type?: string;
+    }>;
+    /** Declarative event: tile leave. */
+    tileLeaveEvent?: EventEmit<Record<string, never>>;
+    /** Declarative event: unit animation. */
+    unitAnimationEvent?: EventEmit<{
+        unitId: string;
+        state: string;
+        timestamp: number;
+    }>;
+    /** Declarative event: camera change. */
+    cameraChangeEvent?: EventEmit<{
+        position: {
+            x: number;
+            y: number;
+            z: number;
+        };
+        timestamp: number;
+    }>;
+    /** Loading message */
+    loadingMessage?: string;
+    /** Unit draw-size multiplier (accepted for API parity; sizing is drawable-authored). */
+    unitScale?: number;
+    /** Board zoom (accepted for API parity; 3D zoom is camera-driven, not group-scaled). */
+    scale?: number;
+    /** Maps a keydown `e.code` → the board's SEMANTIC event (device-agnostic input). */
+    keyMap?: Record<string, string>;
+    /** Maps a keyup `e.code` → the board's SEMANTIC event. */
+    keyUpMap?: Record<string, string>;
+    /** Side-view world size in pixels (accepted for API parity). */
+    worldWidth?: number;
+    /** Side-view world size in pixels (accepted for API parity). */
+    worldHeight?: number;
+    /** Pixel→world-unit divisor for side view (accepted for API parity). */
+    pixelsPerUnit?: number;
+}
+/** Imperative handle for GameCanvas3D */
+export interface GameCanvas3DHandle {
+    /** Get current camera position */
+    getCameraPosition: () => THREE.Vector3 | null;
+    /** Set camera position */
+    setCameraPosition: (x: number, y: number, z: number) => void;
+    /** Look at a specific point */
+    lookAt: (x: number, y: number, z: number) => void;
+    /** Reset camera to default position */
+    resetCamera: () => void;
+    /** Take a screenshot */
+    screenshot: () => string | null;
+}
+/**
+ * GameCanvas3D — thin 3D draw-host. Walks `drawables` through `Drawable3D`.
+ */
+export declare const GameCanvas3D: React.ForwardRefExoticComponent<GameCanvas3DProps & React.RefAttributes<GameCanvas3DHandle>>;
+export default GameCanvas3D;

package/dist/components/game/{3d → three}/molecules/index.d.ts

@@ -12,18 +12,15 @@ export { Lighting3D, type Lighting3DProps } from './Lighting3D';
 export { Canvas3DLoadingState, type Canvas3DLoadingStateProps, } from './Canvas3DLoadingState';
 export { Canvas3DErrorBoundary, type Canvas3DErrorBoundaryProps, type Canvas3DErrorBoundaryState, } from './Canvas3DErrorBoundary';
 export { ModelLoader, type ModelLoaderProps, } from './ModelLoader';
-export { useThree, type UseThreeOptions, type UseThreeReturn, } from '../../shared/hooks/useThree';
-export { useAssetLoader, type UseAssetLoaderOptions, type UseAssetLoaderReturn, type AssetLoadingState, } from '../../shared/hooks/useAssetLoader';
-export { useSceneGraph, type UseSceneGraphReturn, type SceneGraphNode, type NodeType, } from '../../shared/hooks/useSceneGraph';
-export { useRaycaster, type UseRaycasterOptions, type UseRaycasterReturn, type RaycastHit, type GridHit, } from '../../shared/hooks/useRaycaster';
-export { useGameCanvas3DEvents, type UseGameCanvas3DEventsOptions, type UseGameCanvas3DEventsReturn, type GameCanvas3DEventConfig, } from '../../shared/hooks/useGameCanvas3DEvents';
-export { AssetLoader, assetLoader, type LoadedModel, } from '../../shared/lib/AssetLoader';
-export type { UnitAnimationState } from '../../shared/spriteAnimationTypes';
+export { useThree, type UseThreeOptions, type UseThreeReturn, } from '../hooks/useThree';
+export { useAssetLoader, type UseAssetLoaderOptions, type UseAssetLoaderReturn, type AssetLoadingState, } from '../hooks/useAssetLoader';
+export { useSceneGraph, type UseSceneGraphReturn, type SceneGraphNode, type NodeType, } from '../hooks/useSceneGraph';
+export { useRaycaster, type UseRaycasterOptions, type UseRaycasterReturn, type RaycastHit, type GridHit, } from '../hooks/useRaycaster';
+export { useGameCanvas3DEvents, type UseGameCanvas3DEventsOptions, type UseGameCanvas3DEventsReturn, type GameCanvas3DEventConfig, } from '../hooks/useGameCanvas3DEvents';
+export { AssetLoader, assetLoader, type LoadedModel, } from '../lib/AssetLoader';
+export type { UnitAnimationState } from '../../lib/spriteAnimationTypes';
 export { GameCanvas3D, type GameCanvas3DProps } from './GameCanvas3D';
-export { GameCanvas3DBattleTemplate, type GameCanvas3DBattleTemplateProps } from '../templates/GameCanvas3DBattleTemplate';
-export { GameCanvas3DCastleTemplate, type GameCanvas3DCastleTemplateProps } from '../templates/GameCanvas3DCastleTemplate';
-export { GameCanvas3DWorldMapTemplate, type GameCanvas3DWorldMapTemplateProps } from '../templates/GameCanvas3DWorldMapTemplate';
-export { gridToWorld, worldToGrid, raycastToPlane, raycastToObjects, gridDistance, gridManhattanDistance, getNeighbors, isInBounds, getCellsInRadius, createGridHighlight, normalizeMouseCoordinates, type Grid3DConfig, type GridCoordinate, } from '../../shared/lib/grid3D';
+export { gridToWorld, worldToGrid, raycastToPlane, raycastToObjects, gridDistance, gridManhattanDistance, getNeighbors, isInBounds, getCellsInRadius, createGridHighlight, normalizeMouseCoordinates, type Grid3DConfig, type GridCoordinate, } from '../lib/grid3D';
 export { Avl3DViewer, type Avl3DViewerProps } from '../../../avl/organisms/Avl3DViewer';
 export { Avl3DApplicationScene, type Avl3DApplicationSceneProps } from '../../../avl/organisms/Avl3DApplicationScene';
 export { Avl3DOrbitalScene, type Avl3DOrbitalSceneProps } from '../../../avl/organisms/Avl3DOrbitalScene';
@@ -32,4 +29,4 @@ export { Avl3DTransitionScene, type Avl3DTransitionSceneProps } from '../../../a
 export { Avl3DEffects, type Avl3DEffectsProps } from '../../../avl/organisms/Avl3DEffects';
 export { Avl3DContext, useAvl3DConfig, type Avl3DModelOverrides, type Avl3DConfig } from '../../../avl/providers/avl-3d-context';
 export { AVL_3D_COLORS, CAMERA_POSITIONS, goldenSpiralPositions, fibonacciSpherePositions, orbitRingPositions, arcCurve3D, selfLoopCurve3D, treeLayout3D, type Position3D, } from '../../../avl/lib/avl-3d-layout';
-export { isInFrustum, filterByFrustum, getVisibleIndices, calculateLODLevel, updateInstanceLOD, cullInstancedMesh, SpatialHashGrid, type CullingOptions, type LODLevel, type LODConfig, } from '../../shared/lib/culling';
+export { isInFrustum, filterByFrustum, getVisibleIndices, calculateLODLevel, updateInstanceLOD, cullInstancedMesh, SpatialHashGrid, type CullingOptions, type LODLevel, type LODConfig, } from '../lib/culling';

package/dist/components/game/{3d → three}/patterns.d.ts

@@ -14,7 +14,3 @@
  * @packageDocumentation
  */
 export { GameCanvas3D } from './molecules/GameCanvas3D';
-export { GameBoard3D } from './organisms/GameBoard3D';
-export { GameCanvas3DBattleTemplate } from './templates/GameCanvas3DBattleTemplate';
-export { GameCanvas3DCastleTemplate } from './templates/GameCanvas3DCastleTemplate';
-export { GameCanvas3DWorldMapTemplate } from './templates/GameCanvas3DWorldMapTemplate';