@almadar/ui 5.111.0 → 5.113.0

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

@@ -1,60 +0,0 @@
-/**
- * Camera3D
- *
- * Three.js camera component with orbit controls.
- * Supports isometric, perspective, and top-down camera modes.
- *
- * @packageDocumentation
- */
-import React from 'react';
-import * as THREE from 'three';
-export type CameraMode = 'isometric' | 'perspective' | 'top-down';
-export interface Camera3DProps {
-    /** Camera mode */
-    mode?: CameraMode;
-    /** Initial camera position */
-    position?: [number, number, number];
-    /** Target to look at */
-    target?: [number, number, number];
-    /** Zoom level */
-    zoom?: number;
-    /** Field of view (perspective mode only) */
-    fov?: number;
-    /** Enable orbit controls */
-    enableOrbit?: boolean;
-    /** Minimum zoom distance */
-    minDistance?: number;
-    /** Maximum zoom distance */
-    maxDistance?: number;
-    /** Called when camera changes */
-    onChange?: (camera: THREE.Camera) => void;
-}
-export interface Camera3DHandle {
-    /** Get current camera */
-    getCamera: () => THREE.Camera;
-    /** Set camera position */
-    setPosition: (x: number, y: number, z: number) => void;
-    /** Look at target */
-    lookAt: (x: number, y: number, z: number) => void;
-    /** Reset to initial position */
-    reset: () => void;
-    /** Get current view bounds */
-    getViewBounds: () => {
-        min: THREE.Vector3;
-        max: THREE.Vector3;
-    };
-}
-/**
- * Camera3D Component
- *
- * Configurable camera with orbit controls and multiple modes.
- *
- * @example
- * ```tsx
- * <Canvas>
- *     <Camera3D mode="isometric" position={[10, 10, 10]} target={[0, 0, 0]} />
- * </Canvas>
- * ```
- */
-export declare const Camera3D: React.ForwardRefExoticComponent<Camera3DProps & React.RefAttributes<Camera3DHandle>>;
-export default Camera3D;

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

@@ -1,51 +0,0 @@
-/**
- * Canvas3DErrorBoundary
- *
- * Error boundary for 3D canvas components.
- * Catches Three.js and React Three Fiber errors gracefully.
- *
- * @packageDocumentation
- */
-import { Component, type ReactNode, type ErrorInfo } from 'react';
-import './Canvas3DErrorBoundary.css';
-export interface Canvas3DErrorBoundaryProps {
-    /** Child components */
-    children: ReactNode;
-    /** Custom fallback component */
-    fallback?: ReactNode;
-    /** Error callback */
-    onError?: (error: Error, errorInfo: ErrorInfo) => void;
-    /** Reset callback */
-    onReset?: () => void;
-}
-export interface Canvas3DErrorBoundaryState {
-    /** Whether an error has occurred */
-    hasError: boolean;
-    /** The error that occurred */
-    error: Error | null;
-    /** Error info from React */
-    errorInfo: ErrorInfo | null;
-}
-/**
- * Canvas3DErrorBoundary Component
- *
- * Catches errors in 3D canvas and displays a user-friendly fallback.
- *
- * @example
- * ```tsx
- * <Canvas3DErrorBoundary
- *     onError={(error) => console.error('3D Error:', error)}
- *     onReset={() => console.log('Resetting...')}
- * >
- *     <GameCanvas3D {...props} />
- * </Canvas3DErrorBoundary>
- * ```
- */
-export declare class Canvas3DErrorBoundary extends Component<Canvas3DErrorBoundaryProps, Canvas3DErrorBoundaryState> {
-    constructor(props: Canvas3DErrorBoundaryProps);
-    static getDerivedStateFromError(error: Error): Canvas3DErrorBoundaryState;
-    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
-    handleReset: () => void;
-    render(): ReactNode;
-}
-export default Canvas3DErrorBoundary;

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

@@ -1,178 +0,0 @@
-/**
- * Canvas3DHost — the thin 3D draw-host: the `canvas` host's 3D painter backend
- * (the R3F "vessel" behind the neutral drawables), the exact 3D analogue of the
- * 2D `Painter2D` seam. Reached only via the lazy `@almadar/ui/.../game/three`
- * subpath so three.js never enters a 2D bundle.
- *
- * 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 '../paintDispatch';
-import type { IsometricTile, IsometricUnit, IsometricFeature } from '../../isometricTypes';
-import './Canvas3DHost.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 Canvas3DHostProps {
-    /** 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 Canvas3DHostHandle {
-    /** 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;
-}
-/**
- * Canvas3DHost — thin 3D draw-host. Walks `drawables` through `Drawable3D`.
- */
-export declare const Canvas3DHost: React.ForwardRefExoticComponent<Canvas3DHostProps & React.RefAttributes<Canvas3DHostHandle>>;
-export default Canvas3DHost;

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

@@ -1,44 +0,0 @@
-/**
- * Canvas3DLoadingState
- *
- * Loading state component for 3D canvas with progress indicator.
- * Displays asset loading progress and estimated time remaining.
- *
- * @packageDocumentation
- */
-import React from 'react';
-import './Canvas3DLoadingState.css';
-export interface Canvas3DLoadingStateProps {
-    /** Current loading progress (0-100) */
-    progress?: number;
-    /** Number of assets loaded */
-    loaded?: number;
-    /** Total assets to load */
-    total?: number;
-    /** Loading message */
-    message?: string;
-    /** Secondary details message */
-    details?: string;
-    /** Whether to show spinner */
-    showSpinner?: boolean;
-    /** Custom className */
-    className?: string;
-}
-/**
- * Canvas3DLoadingState Component
- *
- * Displays loading progress for 3D assets.
- *
- * @example
- * ```tsx
- * <Canvas3DLoadingState
- *     progress={65}
- *     loaded={13}
- *     total={20}
- *     message="Loading 3D models..."
- *     details="character-knight.glb"
- * />
- * ```
- */
-export declare function Canvas3DLoadingState({ progress, loaded, total, message, details, showSpinner, className, }: Canvas3DLoadingStateProps): React.JSX.Element;
-export default Canvas3DLoadingState;

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

@@ -1,20 +0,0 @@
-/**
- * Drawable3D — the R3F dispatcher for neutral drawable descriptors.
- *
- * The 3D twin of `paintDrawable`: given ONE descriptor, it renders the matching
- * R3F element (mesh/billboard). ⚠ R3F throws if a plain descriptor object reaches
- * `<group>{children}` — the host must ALWAYS map descriptors through THIS
- * component first, never pass raw `DrawableNode`s as children. Consumes the same
- * `DrawSpriteProps`/`DrawShapeProps`/`DrawTextProps` descriptors as the 2D paint
- * dispatch — that is what makes canvas-2d and canvas-3d the same `children`
- * interface.
- */
-import React from 'react';
-import type { Projector3D } from '../projector3d';
-import type { DrawableNode } from '../paintDispatch';
-export interface Drawable3DProps {
-    node: DrawableNode;
-    projector: Projector3D;
-}
-export declare function Drawable3D({ node, projector }: Drawable3DProps): React.JSX.Element | null;
-export default Drawable3D;

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

@@ -1,16 +0,0 @@
-/** Reports the live camera position on every change (imperative handle integration). */
-export declare function CameraController3D({ onCameraChange, }: {
-    onCameraChange?: (pos: {
-        x: number;
-        y: number;
-        z: number;
-    }) => void;
-}): null;
-/**
- * Camera that smooth-tracks a world-space target (side-view player or selected unit).
- * OrbitControls is disabled while following — the camera is authoritative.
- */
-export declare function FollowCamera3D({ target, offset, }: {
-    target: [number, number, number];
-    offset: [number, number, number];
-}): null;

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

@@ -1,55 +0,0 @@
-/**
- * Lighting3D
- *
- * Default lighting setup for 3D game scenes.
- * Includes ambient, directional, and optional point lights.
- *
- * @packageDocumentation
- */
-import React from 'react';
-export interface Lighting3DProps {
-    /** Ambient light intensity */
-    ambientIntensity?: number;
-    /** Ambient light color */
-    ambientColor?: string;
-    /** Directional light intensity */
-    directionalIntensity?: number;
-    /** Directional light color */
-    directionalColor?: string;
-    /** Directional light position */
-    directionalPosition?: [number, number, number];
-    /** Enable shadows */
-    shadows?: boolean;
-    /** Shadow map size */
-    shadowMapSize?: number;
-    /** Shadow camera size (orthographic half-extent) */
-    shadowCameraSize?: number;
-    /** Shadow depth bias — reduces shadow acne */
-    shadowBias?: number;
-    /** Shadow normal bias — reduces acne on angled faces (undefined = three.js default 0) */
-    shadowNormalBias?: number;
-    /** Shadow camera near plane */
-    shadowCameraNear?: number;
-    /** Shadow camera far plane */
-    shadowCameraFar?: number;
-    /** Show helper for directional light */
-    showHelpers?: boolean;
-}
-/**
- * Lighting3D Component
- *
- * Pre-configured lighting setup for game scenes.
- *
- * @example
- * ```tsx
- * <Canvas>
- *     <Lighting3D
- *         ambientIntensity={0.6}
- *         directionalIntensity={1.0}
- *         shadows={true}
- *     />
- * </Canvas>
- * ```
- */
-export declare function Lighting3D({ ambientIntensity, ambientColor, directionalIntensity, directionalColor, directionalPosition, shadows, shadowMapSize, shadowCameraSize, shadowBias, shadowNormalBias, shadowCameraNear, shadowCameraFar, showHelpers, }: Lighting3DProps): React.JSX.Element;
-export default Lighting3D;

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

@@ -1,52 +0,0 @@
-/**
- * ModelLoader Component
- *
- * React Three Fiber component for loading and displaying GLB/GLTF models from URLs.
- * Handles loading states and errors without requiring React Suspense.
- *
- * @packageDocumentation
- */
-import React from 'react';
-export interface ModelLoaderProps {
-    /** URL to the GLB/GLTF model */
-    url: string;
-    /** Position [x, y, z] */
-    position?: [number, number, number];
-    /** Scale - either a single number or [x, y, z] */
-    scale?: number | [number, number, number];
-    /** Rotation in degrees [x, y, z] */
-    rotation?: [number, number, number];
-    /** Whether the model is selected */
-    isSelected?: boolean;
-    /** Whether the model is hovered */
-    isHovered?: boolean;
-    /** Click handler */
-    onClick?: () => void;
-    /** Hover handler */
-    onHover?: (hovered: boolean) => void;
-    /** Fallback geometry type */
-    fallbackGeometry?: 'box' | 'sphere' | 'cylinder' | 'none';
-    /**
-     * Named GLB animation clip to play (e.g. "idle", "walk") — the LOLO state machine
-     * drives this from the unit's `animation` field. Matched case-insensitively; an
-     * unknown or absent name leaves the model static (bind pose).
-     */
-    animation?: string;
-    /** Multiply the model's material colors by this CSS color (per-instance; e.g. team tint). */
-    tint?: string;
-    /** Enable shadows */
-    castShadow?: boolean;
-    /** Receive shadows */
-    receiveShadow?: boolean;
-    /**
-     * Base path for shared resources (textures, materials).
-     * If not provided, auto-detected from the URL by looking for a `/3d/` segment.
-     * E.g. "https://host/3d/" so that "Textures/colormap.png" resolves correctly.
-     */
-    resourceBasePath?: string;
-}
-/**
- * ModelLoader component for rendering GLB models in React Three Fiber
- */
-export declare function ModelLoader({ url, position, scale, rotation, isSelected, isHovered, onClick, onHover, fallbackGeometry, castShadow, receiveShadow, resourceBasePath, animation, tint, }: ModelLoaderProps): React.JSX.Element;
-export default ModelLoader;

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

@@ -1,37 +0,0 @@
-/**
- * Scene3D
- *
- * Three.js scene wrapper component for React Three Fiber.
- * Manages the scene environment, fog, and background.
- *
- * @packageDocumentation
- */
-import React from 'react';
-export interface Scene3DProps {
-    /** Background color or URL */
-    background?: string;
-    /** Fog configuration */
-    fog?: {
-        color: string;
-        near: number;
-        far: number;
-    };
-    /** Children to render in scene */
-    children?: React.ReactNode;
-}
-/**
- * Scene3D Component
- *
- * Manages Three.js scene settings like background and fog.
- *
- * @example
- * ```tsx
- * <Canvas>
- *     <Scene3D background="#1a1a2e" fog={{ color: '#1a1a2e', near: 10, far: 50 }}>
- *         <GameObjects />
- *     </Scene3D>
- * </Canvas>
- * ```
- */
-export declare function Scene3D({ background, fog, children }: Scene3DProps): React.JSX.Element;
-export default Scene3D;

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

@@ -1,14 +0,0 @@
-/**
- * game3dTheme — DEFAULT palette constants for the 3D draw-host (`Canvas3DHost`).
- * No React deps — pure constants. Only the grid + background defaults remain live;
- * every per-item color/size comes from the drawable descriptors that `.lolo` computes.
- *
- * @packageDocumentation
- */
-/** Grid line colors for the drei `<Grid>`. */
-export declare const GRID_COLORS_3D: {
-    cell: string;
-    section: string;
-};
-/** Default scene background (Canvas3DHostProps.backgroundColor default). */
-export declare const DEFAULT_BACKGROUND_3D = "#1a1a2e";

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

@@ -1,58 +0,0 @@
-import * as THREE from 'three';
-import { AssetLoader, LoadedModel } from '../lib/AssetLoader';
-export interface UseAssetLoaderOptions {
-    /** URLs to preload on mount */
-    preloadUrls?: string[];
-    /** Asset loader instance (uses singleton if not provided) */
-    loader?: AssetLoader;
-}
-export interface AssetLoadingState {
-    /** Whether assets are currently loading */
-    isLoading: boolean;
-    /** Loading progress (0-100) */
-    progress: number;
-    /** Number of loaded assets */
-    loaded: number;
-    /** Total assets to load */
-    total: number;
-    /** Any loading errors */
-    errors: string[];
-}
-export interface UseAssetLoaderReturn extends AssetLoadingState {
-    /** Load a single model */
-    loadModel: (url: string) => Promise<LoadedModel>;
-    /** Load a single OBJ model */
-    loadOBJ: (url: string) => Promise<THREE.Group>;
-    /** Load a single texture */
-    loadTexture: (url: string) => Promise<THREE.Texture>;
-    /** Preload multiple assets */
-    preload: (urls: string[]) => Promise<void>;
-    /** Check if model is cached */
-    hasModel: (url: string) => boolean;
-    /** Check if texture is cached */
-    hasTexture: (url: string) => boolean;
-    /** Get cached model */
-    getModel: (url: string) => LoadedModel | undefined;
-    /** Get cached texture */
-    getTexture: (url: string) => THREE.Texture | undefined;
-    /** Clear all caches */
-    clearCache: () => void;
-}
-/**
- * Hook for managing 3D asset loading in React components
- *
- * @example
- * ```tsx
- * const { loadModel, isLoading, progress } = useAssetLoader({
- *     preloadUrls: ['/assets/model.glb']
- * });
- *
- * useEffect(() => {
- *     loadModel('/assets/character.glb').then((model) => {
- *         scene.add(model.scene);
- *     });
- * }, []);
- * ```
- */
-export declare function useAssetLoader(options?: UseAssetLoaderOptions): UseAssetLoaderReturn;
-export default useAssetLoader;