@almadar/ui 5.111.0 → 5.113.0

package/dist/lib/drawable/three/hooks/useGameCanvas3DEvents.d.ts

@@ -1,124 +0,0 @@
-import type { EventEmit } from '@almadar/core';
-import type { IsometricTile, IsometricUnit, IsometricFeature } from '../../../isometricTypes';
-export interface GameCanvas3DEventConfig {
-    /** Event name for tile clicks. `tileId` is optional — the neutral draw-host emits
-     *  only the scene coordinate `{ x, z }` (the FSM keys off the cell, not an id). */
-    tileClickEvent?: EventEmit<{
-        x: number;
-        z: number;
-        tileId?: string;
-        type?: string;
-        terrain?: string;
-        elevation?: number;
-    }>;
-    /** Event name for unit clicks */
-    unitClickEvent?: EventEmit<{
-        unitId: string;
-        x: number;
-        z: number;
-        unitType?: string;
-        name?: string;
-        team?: string;
-        faction?: string;
-        health?: number;
-        maxHealth?: number;
-    }>;
-    /** Event name for feature clicks */
-    featureClickEvent?: EventEmit<{
-        featureId: string;
-        x: number;
-        z: number;
-        type?: string;
-        elevation?: number;
-    }>;
-    /** Event name for canvas clicks */
-    canvasClickEvent?: EventEmit<{
-        clientX: number;
-        clientY: number;
-        button: number;
-    }>;
-    /** Event name for tile hover */
-    tileHoverEvent?: EventEmit<{
-        tileId: string;
-        x: number;
-        z: number;
-        type?: string;
-    }>;
-    /** Event name for tile leave */
-    tileLeaveEvent?: EventEmit<Record<string, never>>;
-    /** Event name for unit animation changes */
-    unitAnimationEvent?: EventEmit<{
-        unitId: string;
-        state: string;
-        timestamp: number;
-    }>;
-    /** Event name for camera changes */
-    cameraChangeEvent?: EventEmit<{
-        position: {
-            x: number;
-            y: number;
-            z: number;
-        };
-        timestamp: number;
-    }>;
-}
-/** Minimal mouse event interface — satisfied by both React.MouseEvent and ThreeEvent<MouseEvent> */
-export interface MinimalMouseEvent {
-    clientX: number;
-    clientY: number;
-    button: number;
-}
-export interface UseGameCanvas3DEventsOptions extends GameCanvas3DEventConfig {
-    /** Callback for tile clicks (direct) */
-    onTileClick?: (tile: IsometricTile, event: MinimalMouseEvent) => void;
-    /** Callback for unit clicks (direct) */
-    onUnitClick?: (unit: IsometricUnit, event: MinimalMouseEvent) => void;
-    /** Callback for feature clicks (direct) */
-    onFeatureClick?: (feature: IsometricFeature, event: MinimalMouseEvent) => void;
-    /** Callback for canvas clicks (direct) */
-    onCanvasClick?: (event: MinimalMouseEvent) => void;
-    /** Callback for tile hover (direct) */
-    onTileHover?: (tile: IsometricTile | null, event: MinimalMouseEvent) => void;
-    /** Callback for unit animation changes (direct) */
-    onUnitAnimation?: (unitId: string, state: string) => void;
-}
-export interface UseGameCanvas3DEventsReturn {
-    /** Handle tile click - emits event and calls callback */
-    handleTileClick: (tile: IsometricTile, event: MinimalMouseEvent) => void;
-    /** Handle unit click - emits event and calls callback */
-    handleUnitClick: (unit: IsometricUnit, event: MinimalMouseEvent) => void;
-    /** Handle feature click - emits event and calls callback */
-    handleFeatureClick: (feature: IsometricFeature, event: MinimalMouseEvent) => void;
-    /** Handle canvas click - emits event and calls callback */
-    handleCanvasClick: (event: MinimalMouseEvent) => void;
-    /** Handle tile hover - emits event and calls callback */
-    handleTileHover: (tile: IsometricTile | null, event: MinimalMouseEvent) => void;
-    /** Handle unit animation - emits event and calls callback */
-    handleUnitAnimation: (unitId: string, state: string) => void;
-    /** Handle camera change - emits event */
-    handleCameraChange: (position: {
-        x: number;
-        y: number;
-        z: number;
-    }) => void;
-}
-/**
- * Hook for integrating GameCanvas3D with the event bus
- *
- * Supports both declarative event props (tileClickEvent) and
- * direct callback props (onTileClick).
- *
- * @example
- * ```tsx
- * const events = useGameCanvas3DEvents({
- *     tileClickEvent: 'TILE_SELECTED',
- *     unitClickEvent: 'UNIT_SELECTED',
- *     onTileClick: (tile) => console.log('Tile:', tile)
- * });
- *
- * // In component:
- * <TileRenderer onTileClick={events.handleTileClick} />
- * ```
- */
-export declare function useGameCanvas3DEvents(options: UseGameCanvas3DEventsOptions): UseGameCanvas3DEventsReturn;
-export default useGameCanvas3DEvents;

package/dist/lib/drawable/three/hooks/useRaycaster.d.ts

@@ -1,86 +0,0 @@
-import * as THREE from 'three';
-export interface RaycastHit {
-    /** Intersected object */
-    object: THREE.Object3D;
-    /** Intersection point */
-    point: THREE.Vector3;
-    /** Distance from camera */
-    distance: number;
-    /** UV coordinates (if available) */
-    uv?: THREE.Vector2;
-    /** Face normal */
-    face?: THREE.Face;
-    /** Face index */
-    faceIndex?: number;
-    /** Instance ID (for instanced meshes) */
-    instanceId?: number;
-}
-export interface GridHit {
-    /** Grid X coordinate */
-    gridX: number;
-    /** Grid Z coordinate */
-    gridZ: number;
-    /** World position */
-    worldPosition: THREE.Vector3;
-    /** Intersected object type */
-    objectType?: 'tile' | 'unit' | 'feature';
-    /** Object ID if available */
-    objectId?: string;
-}
-export interface UseRaycasterOptions {
-    /** Camera reference */
-    camera: THREE.Camera | null;
-    /** Canvas element for coordinate conversion */
-    canvas: HTMLCanvasElement | null;
-    /** Grid cell size */
-    cellSize?: number;
-    /** Grid offset X */
-    offsetX?: number;
-    /** Grid offset Z */
-    offsetZ?: number;
-}
-export interface UseRaycasterReturn {
-    /** Raycaster instance */
-    raycaster: React.MutableRefObject<THREE.Raycaster>;
-    /** Mouse vector instance */
-    mouse: React.MutableRefObject<THREE.Vector2>;
-    /** Get intersection at client coordinates */
-    getIntersection: (clientX: number, clientY: number, objects: THREE.Object3D[]) => RaycastHit | null;
-    /** Get all intersections at client coordinates */
-    getAllIntersections: (clientX: number, clientY: number, objects: THREE.Object3D[]) => RaycastHit[];
-    /** Get grid coordinates at client position */
-    getGridCoordinates: (clientX: number, clientY: number) => {
-        x: number;
-        z: number;
-    } | null;
-    /** Get tile at client position from scene */
-    getTileAtPosition: (clientX: number, clientY: number, scene: THREE.Scene) => GridHit | null;
-    /** Convert client coordinates to normalized device coordinates */
-    clientToNDC: (clientX: number, clientY: number) => {
-        x: number;
-        y: number;
-    };
-    /** Check if point is within canvas bounds */
-    isWithinCanvas: (clientX: number, clientY: number) => boolean;
-}
-/**
- * Hook for 3D raycasting operations
- *
- * @example
- * ```tsx
- * const { getIntersection, getGridCoordinates } = useRaycaster({
- *     camera,
- *     canvas: canvasRef.current
- * });
- *
- * const handleClick = (e: MouseEvent) => {
- *     const hit = getIntersection(e.clientX, e.clientY, tileMeshes);
- *     if (hit) {
- *         const grid = getGridCoordinates(e.clientX, e.clientY);
- *         console.log('Clicked grid:', grid);
- *     }
- * };
- * ```
- */
-export declare function useRaycaster(options: UseRaycasterOptions): UseRaycasterReturn;
-export default useRaycaster;

package/dist/lib/drawable/three/hooks/useSceneGraph.d.ts

@@ -1,67 +0,0 @@
-import * as THREE from 'three';
-import type { JsonObject } from '@almadar/core';
-export type NodeType = 'tile' | 'unit' | 'feature' | 'highlight' | 'effect';
-export interface SceneGraphNode {
-    /** Unique node identifier */
-    id: string;
-    /** Node type classification */
-    type: NodeType;
-    /** Three.js object */
-    mesh: THREE.Object3D;
-    /** World position */
-    position: {
-        x: number;
-        y: number;
-        z: number;
-    };
-    /** Grid position */
-    gridPosition: {
-        x: number;
-        z: number;
-    };
-    /** Optional metadata */
-    metadata?: JsonObject;
-}
-export interface UseSceneGraphReturn {
-    /** Reference to the nodes map */
-    nodesRef: React.MutableRefObject<Map<string, SceneGraphNode>>;
-    /** Add a node to the scene */
-    addNode: (node: SceneGraphNode) => void;
-    /** Remove a node from the scene */
-    removeNode: (id: string) => void;
-    /** Get a node by ID */
-    getNode: (id: string) => SceneGraphNode | undefined;
-    /** Update node position */
-    updateNodePosition: (id: string, x: number, y: number, z: number) => void;
-    /** Update node grid position */
-    updateNodeGridPosition: (id: string, gridX: number, gridZ: number) => void;
-    /** Get node at grid position */
-    getNodeAtGrid: (x: number, z: number, type?: NodeType) => SceneGraphNode | undefined;
-    /** Get all nodes of a specific type */
-    getNodesByType: (type: NodeType) => SceneGraphNode[];
-    /** Get all nodes within a bounding box */
-    getNodesInBounds: (minX: number, maxX: number, minZ: number, maxZ: number) => SceneGraphNode[];
-    /** Clear all nodes */
-    clearNodes: () => void;
-    /** Count nodes by type */
-    countNodes: (type?: NodeType) => number;
-}
-/**
- * Hook for managing the 3D scene graph
- *
- * @example
- * ```tsx
- * const { addNode, removeNode, getNodeAtGrid } = useSceneGraph();
- *
- * // Add a tile
- * addNode({
- *     id: 'tile-0-0',
- *     type: 'tile',
- *     mesh: tileMesh,
- *     position: { x: 0, y: 0, z: 0 },
- *     gridPosition: { x: 0, z: 0 }
- * });
- * ```
- */
-export declare function useSceneGraph(): UseSceneGraphReturn;
-export default useSceneGraph;

package/dist/lib/drawable/three/hooks/useThree.d.ts

@@ -1,58 +0,0 @@
-import * as THREE from 'three';
-import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
-import { AssetLoader } from '../lib/AssetLoader';
-export type CameraMode = 'isometric' | 'perspective' | 'top-down';
-export interface UseThreeOptions {
-    /** Camera mode for viewing the scene */
-    cameraMode?: CameraMode;
-    /** Initial camera position [x, y, z] */
-    cameraPosition?: [number, number, number];
-    /** Background color */
-    backgroundColor?: string;
-    /** Enable shadows */
-    shadows?: boolean;
-    /** Enable grid helper */
-    showGrid?: boolean;
-    /** Grid size */
-    gridSize?: number;
-    /** Asset loader instance */
-    assetLoader?: AssetLoader;
-}
-export interface UseThreeReturn {
-    /** Canvas element reference (for React Three Fiber) */
-    canvasRef: React.RefObject<HTMLCanvasElement | null>;
-    /** Three.js renderer */
-    renderer: THREE.WebGLRenderer | null;
-    /** Three.js scene */
-    scene: THREE.Scene | null;
-    /** Three.js camera */
-    camera: THREE.Camera | null;
-    /** Orbit controls */
-    controls: OrbitControls | null;
-    /** Is scene ready */
-    isReady: boolean;
-    /** Canvas dimensions */
-    dimensions: {
-        width: number;
-        height: number;
-    };
-    /** 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 initial position */
-    resetCamera: () => void;
-    /** Fit view to bounds */
-    fitView: (bounds: {
-        minX: number;
-        maxX: number;
-        minZ: number;
-        maxZ: number;
-    }) => void;
-}
-/**
- * Hook for managing a Three.js scene
- * This is a lower-level hook used by GameCanvas3D
- */
-export declare function useThree(options?: UseThreeOptions): UseThreeReturn;
-export default useThree;

package/dist/lib/drawable/three/lib/AssetLoader.d.ts

@@ -1,80 +0,0 @@
-/**
- * AssetLoader
- *
- * Three.js asset loading manager for 3D models and textures.
- * Supports GLB/GLTF (primary), OBJ (fallback), and texture loading.
- * Implements caching for performance.
- *
- * @packageDocumentation
- */
-import * as THREE from 'three';
-export interface LoadedModel {
-    scene: THREE.Group;
-    animations: THREE.AnimationClip[];
-}
-export declare class AssetLoader {
-    private objLoader;
-    private textureLoader;
-    private modelCache;
-    private textureCache;
-    private loadingPromises;
-    constructor();
-    /**
-     * Load a GLB/GLTF model
-     * @param url - URL to the .glb or .gltf file
-     * @returns Promise with loaded model scene and animations
-     */
-    loadModel(url: string): Promise<LoadedModel>;
-    /**
-     * Load an OBJ model (fallback for non-GLB assets)
-     * @param url - URL to the .obj file
-     * @returns Promise with loaded object group
-     */
-    loadOBJ(url: string): Promise<THREE.Group>;
-    /**
-     * Load a texture
-     * @param url - URL to the texture image
-     * @returns Promise with loaded texture
-     */
-    loadTexture(url: string): Promise<THREE.Texture>;
-    /**
-     * Preload multiple assets
-     * @param urls - Array of asset URLs to preload
-     * @returns Promise that resolves when all assets are loaded
-     */
-    preload(urls: string[]): Promise<void>;
-    /**
-     * Check if a model is cached
-     * @param url - Model URL
-     */
-    hasModel(url: string): boolean;
-    /**
-     * Check if a texture is cached
-     * @param url - Texture URL
-     */
-    hasTexture(url: string): boolean;
-    /**
-     * Get cached model (throws if not cached)
-     * @param url - Model URL
-     */
-    getModel(url: string): LoadedModel;
-    /**
-     * Get cached texture (throws if not cached)
-     * @param url - Texture URL
-     */
-    getTexture(url: string): THREE.Texture;
-    /**
-     * Clear all caches
-     */
-    clearCache(): void;
-    /**
-     * Get cache statistics
-     */
-    getStats(): {
-        models: number;
-        textures: number;
-        loading: number;
-    };
-}
-export declare const assetLoader: AssetLoader;
-export default AssetLoader;

package/dist/lib/drawable/three/lib/culling.d.ts

@@ -1,134 +0,0 @@
-/**
- * Culling Utilities
- *
- * Frustum culling and LOD (Level of Detail) management for 3D scene optimization.
- *
- * @packageDocumentation
- */
-import * as THREE from 'three';
-export interface CullingOptions {
-    /** Camera frustum for culling */
-    camera: THREE.Camera;
-    /** Optional padding around frustum */
-    padding?: number;
-}
-export interface LODLevel {
-    /** Distance threshold for this LOD level */
-    distance: number;
-    /** Geometry or mesh for this level */
-    geometry?: THREE.BufferGeometry;
-    /** Scale multiplier for this level */
-    scale?: number;
-    /** Whether to use simplified material */
-    simpleMaterial?: boolean;
-}
-export interface LODConfig {
-    /** LOD levels from closest to farthest */
-    levels: LODLevel[];
-    /** Transition smoothness (0-1) */
-    transitionSmoothness?: number;
-}
-/**
- * Frustum culling check for a position
- * @param position - World position to check
- * @param camera - Camera to check against
- * @param padding - Optional padding in world units
- * @returns Whether the position is within the frustum
- */
-export declare function isInFrustum(position: THREE.Vector3, camera: THREE.Camera, padding?: number): boolean;
-/**
- * Filter an array of positions to only those within the frustum
- * @param positions - Array of world positions
- * @param camera - Camera to check against
- * @param padding - Optional padding in world units
- * @returns Array of positions within frustum
- */
-export declare function filterByFrustum(positions: THREE.Vector3[], camera: THREE.Camera, padding?: number): THREE.Vector3[];
-/**
- * Get indices of visible items from an array
- * @param positions - Array of world positions
- * @param camera - Camera to check against
- * @param padding - Optional padding in world units
- * @returns Set of visible indices
- */
-export declare function getVisibleIndices(positions: THREE.Vector3[], camera: THREE.Camera, padding?: number): Set<number>;
-/**
- * Calculate LOD level based on distance from camera
- * @param position - Object position
- * @param camera - Camera position
- * @param lodLevels - Array of distance thresholds (sorted closest to farthest)
- * @returns Index of the LOD level to use
- */
-export declare function calculateLODLevel(position: THREE.Vector3, camera: THREE.Camera, lodLevels: number[]): number;
-/**
- * Create a distance-based LOD system for an instanced mesh
- * @param instancedMesh - The instanced mesh to manage
- * @param positions - Array of instance positions
- * @param camera - Camera to calculate distances from
- * @param lodDistances - Distance thresholds for LOD levels
- * @returns Array of LOD indices for each instance
- */
-export declare function updateInstanceLOD(instancedMesh: THREE.InstancedMesh, positions: THREE.Vector3[], camera: THREE.Camera, lodDistances: number[]): Uint8Array;
-/**
- * Create visibility data for instanced mesh culling
- * Updates the instance matrix to hide/show instances
- * @param instancedMesh - The instanced mesh
- * @param positions - Array of instance positions
- * @param visibleIndices - Set of visible indices
- * @returns Updated count of visible instances
- */
-export declare function cullInstancedMesh(instancedMesh: THREE.InstancedMesh, positions: THREE.Vector3[], visibleIndices: Set<number>): number;
-/**
- * Spatial hash grid for efficient object queries
- */
-export declare class SpatialHashGrid {
-    private cellSize;
-    private cells;
-    private objectPositions;
-    constructor(cellSize?: number);
-    /**
-     * Get cell key for a position
-     */
-    private getCellKey;
-    /**
-     * Insert an object into the grid
-     */
-    insert(id: string, position: THREE.Vector3): void;
-    /**
-     * Remove an object from the grid
-     */
-    remove(id: string): void;
-    /**
-     * Update an object's position
-     */
-    update(id: string, newPosition: THREE.Vector3): void;
-    /**
-     * Query objects within a radius of a position
-     */
-    queryRadius(center: THREE.Vector3, radius: number): string[];
-    /**
-     * Query objects within a bounding box
-     */
-    queryBox(minX: number, maxX: number, minZ: number, maxZ: number): string[];
-    /**
-     * Clear all objects from the grid
-     */
-    clear(): void;
-    /**
-     * Get statistics about the grid
-     */
-    getStats(): {
-        objects: number;
-        cells: number;
-    };
-}
-declare const _default: {
-    isInFrustum: typeof isInFrustum;
-    filterByFrustum: typeof filterByFrustum;
-    getVisibleIndices: typeof getVisibleIndices;
-    calculateLODLevel: typeof calculateLODLevel;
-    updateInstanceLOD: typeof updateInstanceLOD;
-    cullInstancedMesh: typeof cullInstancedMesh;
-    SpatialHashGrid: typeof SpatialHashGrid;
-};
-export default _default;