@almadar/ui 5.141.0 → 5.142.0

package/dist/{avl-schema-parser-B8Onmfsu.d.cts → avl-schema-parser-DAs12kxP.d.ts}

@@ -1,4 +1,7 @@
-import { AnimationName, Asset, JsonObject, JsonValue } from '@almadar/core';
+import { AnimationName, Asset, ScenePos, EventEmit, JsonObject, JsonValue } from '@almadar/core';
+import React__default from 'react';
+import * as THREE from 'three';
+import { D as DrawableNode } from './paintDispatch-BQn5Lyx1.js';
 
 /**
  * Sprite Sheet Animation Types
@@ -278,6 +281,230 @@ interface CameraState {
     zoom: number;
 }
 
+/**
+ * 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
+ */
+
+/** Camera mode for 3D view.
+ *  - `follow` tracks `followTarget` (the neutral `Camera.target`) from a fixed offset.
+ *  - `chase` sits behind + above the target. */
+type CameraMode = 'isometric' | 'perspective' | 'top-down' | 'follow' | 'chase';
+/** Map orientation */
+type MapOrientation = 'standard' | 'rotated';
+/** Overlay control */
+type OverlayControl = 'default' | 'hidden' | 'minimap';
+/** Single light's tunable knobs (ambient/directional share this shape). */
+interface CanvasLightConfig {
+    intensity?: number;
+    color?: string;
+    position?: [number, number, number];
+}
+/** Hemisphere (sky/ground) light config. */
+interface CanvasHemisphereConfig {
+    intensity?: number;
+    color?: string;
+    groundColor?: string;
+}
+/** Point light config — `position` is required since a point light has no
+ *  meaningful default placement. */
+interface CanvasPointLightConfig {
+    intensity?: number;
+    color?: string;
+    position: [number, number, number];
+    distance?: number;
+    decay?: number;
+}
+/** Canvas-level 3D light rig, authored as data. Every field is optional — an
+ *  omitted field falls back to today's fixed rig (the defaults live in `Lighting3D`). */
+interface CanvasLighting {
+    /** Default intensity 0.6, color '#ffffff'. */
+    ambient?: CanvasLightConfig;
+    /** Default intensity 0.8, color '#ffffff', position [10, 20, 10]. */
+    directional?: CanvasLightConfig;
+    /** Default intensity 0.3, color '#87ceeb', groundColor '#362d1d'. */
+    hemisphere?: CanvasHemisphereConfig;
+    /** Additional point lights. Default none. */
+    points?: CanvasPointLightConfig[];
+    /** Procedural environment for PBR reflection (metals/glass). 'room' uses three's
+     *  RoomEnvironment via PMREMGenerator — no network fetch. Default 'none' (today's
+     *  look). */
+    environment?: 'room' | 'none';
+}
+/** Canvas-level post-processing stack. Every field is optional — an omitted field
+ *  means that pass is not mounted. */
+interface CanvasPost {
+    bloom?: {
+        intensity?: number;
+        threshold?: number;
+        smoothing?: number;
+    };
+    vignette?: {
+        offset?: number;
+        darkness?: number;
+    };
+}
+/** Props for GameCanvas3D component */
+interface Canvas3DHostProps {
+    /** Additional CSS classes */
+    className?: string;
+    /** Declarative JSX drawable children — rendered in a hidden DOM mount where they
+     *  register their descriptors via DrawableRegistryContext (same contract as Canvas2D). */
+    children?: React__default.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 pixel-authored (side-view) scenes: world size =
+     *  scene size ÷ `pixelsPerUnit`. Omitted → 1 world unit per scene unit (grid boards). */
+    pixelsPerUnit?: number;
+    /** Perspective field of view in degrees — the neutral `Camera.fov`. Default 45. */
+    fov?: number;
+    /** 3D scene light rig as data — ambient/directional/hemisphere/point lights + optional
+     *  'room' environment. Omitted → the standard fixed rig (this host's current
+     *  hardcoded lights, unchanged). */
+    lighting?: CanvasLighting;
+    /** 3D post-processing stack — bloom + vignette. Omitted → no composer pass mounted. */
+    post?: CanvasPost;
+}
+/** Imperative handle for GameCanvas3D */
+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`.
+ */
+declare const Canvas3DHost: React__default.ForwardRefExoticComponent<Canvas3DHostProps & React__default.RefAttributes<Canvas3DHostHandle>>;
+
 /**
  * AVL Schema Parser
  *
@@ -390,4 +617,4 @@ interface TransitionLevelData {
     slotTargets: SlotTarget[];
 }
 
-export { type ApplicationLevelData as A, type BoardTile as B, type CameraState as C, type ExternalLink as E, type FacingDirection as F, type GameAction as G, type IsometricTile as I, type OrbitalLevelData as O, type Position as P, type ResolvedFrame as R, type SpriteSheetUrls as S, type TraitLevelData as T, type UnitAnimationState as U, type IsometricUnit as a, type IsometricFeature as b, type TransitionLevelData as c, type SpriteFrameDims as d, type FieldInfo as e, type OrbitalTraitInfo as f, type OrbitalPageInfo as g, type GamePhase as h, type GameState as i, type GameUnit as j, type UnitTrait as k, calculateAttackTargets as l, calculateValidMoves as m, createInitialGameState as n };
+export { type ApplicationLevelData as A, type BoardTile as B, type CanvasPointLightConfig as C, type ExternalLink as E, type FacingDirection as F, type GameAction as G, type IsometricTile as I, type OrbitalLevelData as O, type Position as P, type ResolvedFrame as R, type SpriteSheetUrls as S, type TraitLevelData as T, type UnitAnimationState as U, type IsometricUnit as a, type IsometricFeature as b, type TransitionLevelData as c, Canvas3DHost as d, type Canvas3DHostHandle as e, type Canvas3DHostProps as f, type SpriteFrameDims as g, type CanvasLighting as h, type CanvasPost as i, type CameraState as j, type FieldInfo as k, type OrbitalTraitInfo as l, type OrbitalPageInfo as m, type GamePhase as n, type GameState as o, type GameUnit as p, type UnitTrait as q, calculateAttackTargets as r, calculateValidMoves as s, createInitialGameState as t };

package/dist/{avl-schema-parser-B8Onmfsu.d.ts → avl-schema-parser-wOkfbwAh.d.cts}

@@ -1,4 +1,7 @@
-import { AnimationName, Asset, JsonObject, JsonValue } from '@almadar/core';
+import { AnimationName, Asset, ScenePos, EventEmit, JsonObject, JsonValue } from '@almadar/core';
+import React__default from 'react';
+import * as THREE from 'three';
+import { D as DrawableNode } from './paintDispatch-BQn5Lyx1.cjs';
 
 /**
  * Sprite Sheet Animation Types
@@ -278,6 +281,230 @@ interface CameraState {
     zoom: number;
 }
 
+/**
+ * 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
+ */
+
+/** Camera mode for 3D view.
+ *  - `follow` tracks `followTarget` (the neutral `Camera.target`) from a fixed offset.
+ *  - `chase` sits behind + above the target. */
+type CameraMode = 'isometric' | 'perspective' | 'top-down' | 'follow' | 'chase';
+/** Map orientation */
+type MapOrientation = 'standard' | 'rotated';
+/** Overlay control */
+type OverlayControl = 'default' | 'hidden' | 'minimap';
+/** Single light's tunable knobs (ambient/directional share this shape). */
+interface CanvasLightConfig {
+    intensity?: number;
+    color?: string;
+    position?: [number, number, number];
+}
+/** Hemisphere (sky/ground) light config. */
+interface CanvasHemisphereConfig {
+    intensity?: number;
+    color?: string;
+    groundColor?: string;
+}
+/** Point light config — `position` is required since a point light has no
+ *  meaningful default placement. */
+interface CanvasPointLightConfig {
+    intensity?: number;
+    color?: string;
+    position: [number, number, number];
+    distance?: number;
+    decay?: number;
+}
+/** Canvas-level 3D light rig, authored as data. Every field is optional — an
+ *  omitted field falls back to today's fixed rig (the defaults live in `Lighting3D`). */
+interface CanvasLighting {
+    /** Default intensity 0.6, color '#ffffff'. */
+    ambient?: CanvasLightConfig;
+    /** Default intensity 0.8, color '#ffffff', position [10, 20, 10]. */
+    directional?: CanvasLightConfig;
+    /** Default intensity 0.3, color '#87ceeb', groundColor '#362d1d'. */
+    hemisphere?: CanvasHemisphereConfig;
+    /** Additional point lights. Default none. */
+    points?: CanvasPointLightConfig[];
+    /** Procedural environment for PBR reflection (metals/glass). 'room' uses three's
+     *  RoomEnvironment via PMREMGenerator — no network fetch. Default 'none' (today's
+     *  look). */
+    environment?: 'room' | 'none';
+}
+/** Canvas-level post-processing stack. Every field is optional — an omitted field
+ *  means that pass is not mounted. */
+interface CanvasPost {
+    bloom?: {
+        intensity?: number;
+        threshold?: number;
+        smoothing?: number;
+    };
+    vignette?: {
+        offset?: number;
+        darkness?: number;
+    };
+}
+/** Props for GameCanvas3D component */
+interface Canvas3DHostProps {
+    /** Additional CSS classes */
+    className?: string;
+    /** Declarative JSX drawable children — rendered in a hidden DOM mount where they
+     *  register their descriptors via DrawableRegistryContext (same contract as Canvas2D). */
+    children?: React__default.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 pixel-authored (side-view) scenes: world size =
+     *  scene size ÷ `pixelsPerUnit`. Omitted → 1 world unit per scene unit (grid boards). */
+    pixelsPerUnit?: number;
+    /** Perspective field of view in degrees — the neutral `Camera.fov`. Default 45. */
+    fov?: number;
+    /** 3D scene light rig as data — ambient/directional/hemisphere/point lights + optional
+     *  'room' environment. Omitted → the standard fixed rig (this host's current
+     *  hardcoded lights, unchanged). */
+    lighting?: CanvasLighting;
+    /** 3D post-processing stack — bloom + vignette. Omitted → no composer pass mounted. */
+    post?: CanvasPost;
+}
+/** Imperative handle for GameCanvas3D */
+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`.
+ */
+declare const Canvas3DHost: React__default.ForwardRefExoticComponent<Canvas3DHostProps & React__default.RefAttributes<Canvas3DHostHandle>>;
+
 /**
  * AVL Schema Parser
  *
@@ -390,4 +617,4 @@ interface TransitionLevelData {
     slotTargets: SlotTarget[];
 }
 
-export { type ApplicationLevelData as A, type BoardTile as B, type CameraState as C, type ExternalLink as E, type FacingDirection as F, type GameAction as G, type IsometricTile as I, type OrbitalLevelData as O, type Position as P, type ResolvedFrame as R, type SpriteSheetUrls as S, type TraitLevelData as T, type UnitAnimationState as U, type IsometricUnit as a, type IsometricFeature as b, type TransitionLevelData as c, type SpriteFrameDims as d, type FieldInfo as e, type OrbitalTraitInfo as f, type OrbitalPageInfo as g, type GamePhase as h, type GameState as i, type GameUnit as j, type UnitTrait as k, calculateAttackTargets as l, calculateValidMoves as m, createInitialGameState as n };
+export { type ApplicationLevelData as A, type BoardTile as B, type CanvasPointLightConfig as C, type ExternalLink as E, type FacingDirection as F, type GameAction as G, type IsometricTile as I, type OrbitalLevelData as O, type Position as P, type ResolvedFrame as R, type SpriteSheetUrls as S, type TraitLevelData as T, type UnitAnimationState as U, type IsometricUnit as a, type IsometricFeature as b, type TransitionLevelData as c, Canvas3DHost as d, type Canvas3DHostHandle as e, type Canvas3DHostProps as f, type SpriteFrameDims as g, type CanvasLighting as h, type CanvasPost as i, type CameraState as j, type FieldInfo as k, type OrbitalTraitInfo as l, type OrbitalPageInfo as m, type GamePhase as n, type GameState as o, type GameUnit as p, type UnitTrait as q, calculateAttackTargets as r, calculateValidMoves as s, createInitialGameState as t };