@almadar/ui 5.105.0 → 5.108.0

package/dist/{components/game/shared/hooks → hooks}/useCamera.d.ts

@@ -1,4 +1,4 @@
-import type { CameraState } from '../isometricTypes';
+import type { CameraState } from '../lib/isometricTypes';
 interface CameraResult {
     /** Mutable camera state ref (x, y, zoom) */
     cameraRef: React.MutableRefObject<CameraState>;

package/dist/{components/game/shared/hooks → hooks}/useUnitSpriteAtlas.d.ts

@@ -1,5 +1,5 @@
-import type { IsometricUnit } from '../isometricTypes';
-import type { ResolvedFrame } from '../spriteAnimationTypes';
+import type { IsometricUnit } from '../lib/isometricTypes';
+import type { ResolvedFrame } from '../lib/spriteAnimationTypes';
 /**
  * Resolve the sprite-sheet atlas-JSON URL for a unit.
  *

package/dist/lib/drawable/contract.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Drawable contract — the shared vocabulary every neutral drawable primitive
+ * (the `draw-sprite`/`draw-shape`/`draw-text` atoms, `draw-sprite-layer`/
+ * `draw-shape-layer` molecules) is authored against. A drawable is a pure
+ * descriptor the canvas HOST walks and paints via the portable {@link Painter2D}
+ * seam — no `CanvasRenderingContext2D`, no DOM. Genre (a "unit"/"tile"/
+ * "highlight") is a `.lolo` COMPOSITION of these, never its own primitive.
+ *
+ * A position is a core `ScenePos` (logical scene space). The host's {@link Projector}
+ * maps it to pixels; primitives never do projection math themselves. Because the
+ * `ScenePos` type identity is what pattern-sync stamps as the `drawable`
+ * capability, every drawable descriptor's `position` MUST be a core `ScenePos`.
+ */
+import type { ScenePos } from '@almadar/core';
+import type { Painter2D, PainterPoint } from '../painter2d';
+/**
+ * How a drawable aligns to its projected position.
+ * - `top-left` — the cell's top-left corner (tiles).
+ * - `ground`   — the cell's ground point, bottom-center of the drawable (units/features).
+ * - `center`   — the cell's visual center (effects).
+ */
+export type DrawableAnchor = 'top-left' | 'ground' | 'center';
+/**
+ * Maps logical scene coordinates to pixel space for one projection (iso/hex/flat/free).
+ * Owns ALL projection geometry so the primitives stay projection-agnostic. The host
+ * applies the camera transform on the painter around the walk; the projector is
+ * pre-camera (logical→cell-pixel).
+ */
+export interface Projector {
+    /** Cell top-left in pixels. */
+    project(pos: ScenePos): PainterPoint;
+    /** The pixel reference point for an anchor (see {@link DrawableAnchor}). */
+    anchorPoint(pos: ScenePos, anchor: DrawableAnchor): PainterPoint;
+    /** The cell footprint polygon — a rect (square grids) or a diamond (iso/hex). */
+    cellPath(pos: ScenePos): PainterPoint[];
+    /** Scaled cell width in px (`TILE_WIDTH * scale`). */
+    readonly tileWidth: number;
+    /** Scaled floor/diamond height in px (`FLOOR_HEIGHT * scale`). */
+    readonly floorHeight: number;
+    /** Scaled diamond-top offset in px (`DIAMOND_TOP_Y * scale`). */
+    readonly diamondTopY: number;
+    /** Render scale factor. */
+    readonly scale: number;
+    /** True for square-pitch grids (`flat`/`free`); false for diamond (iso/hex). */
+    readonly squareGrid: boolean;
+}
+/** Per-frame context handed to every paint fn. */
+export interface DrawContext {
+    projector: Projector;
+    /** Animation clock in ms (0 when static). Reserved for a LOLO-driven pulse/breathe input. */
+    time: number;
+    /** Force a host re-draw once an async resource (image / atlas JSON) has loaded. */
+    invalidate: () => void;
+}
+/** Common shape of every drawable descriptor. `type` keys the host's paint dispatch. */
+export interface DrawableBase {
+    type: string;
+    /**
+     * Optional hit-test handle. When a board authors a per-entity id here (e.g.
+     * `id: (object/get @u id)` on a unit sprite), the canvas host indexes the
+     * descriptor's `ScenePos → id` and resolves a pointer/raycast at that cell to
+     * this id — the source of `unitClickEvent {unitId}`. A source-tagged handle,
+     * NOT a heuristic: no id → the host emits only the coordinate (tile click).
+     */
+    id?: string;
+}
+/** A paint function: draws one descriptor of type `T` to the painter. */
+export type PaintFn<T extends DrawableBase> = (painter: Painter2D, node: T, dctx: DrawContext) => void;

package/dist/lib/drawable/hitTest.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Drawable click hit-test — the shared walk both canvas hosts (2D + 3D) use to
+ * resolve a pointer/raycast at a scene cell to a per-entity id.
+ *
+ * A drawable descriptor carries an optional source-tagged `id` (see
+ * {@link DrawableBase.id}); a board tags its unit sprites (`id: (@u id)`). The
+ * host collects every drawn descriptor's `ScenePos` + `id`, builds a
+ * `"x,y" → id` index (later descriptors win, so a unit drawn over its tile takes
+ * the cell), and a click that lands on a tagged cell becomes `unitClick {unitId}`.
+ * No id → the host emits only the coordinate (tile click). One owner, both hosts —
+ * no per-host duplicate walker.
+ */
+import type { ScenePos } from '@almadar/core';
+import type { DrawableNode } from './paintDispatch';
+/** One drawn descriptor's scene position + optional hit-test id. */
+export interface DrawnItem {
+    pos: ScenePos;
+    id?: string;
+}
+/** Collect every drawable's scene position + hit id (atoms directly; layers via `items`). */
+export declare function collectDrawnItems(nodes: DrawableNode[]): DrawnItem[];
+/** Build the `"x,y" → id` cell index from the tagged descriptors (later wins). */
+export declare function buildHitIndex(items: DrawnItem[]): Map<string, string>;

package/dist/lib/drawable/paintDispatch.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Drawable paint dispatch (2D) + the `DrawableNode` union.
+ *
+ * `paintDrawable` routes ONE descriptor to its 2D painter; the host walks its
+ * `children` through it. The "drawable" designation itself is NOT recorded here —
+ * it is DERIVED from the core `ScenePos` type each descriptor's `position` uses
+ * and stamped into `patterns-registry.json` by pattern-sync (mirroring how `Asset`
+ * is tagged), then read by the orbital-rust validator. So this module is pure
+ * paint routing; the capability is the registry's, not a hand-list.
+ */
+import type { Painter2D } from '../painter2d';
+import type { DrawContext } from './contract';
+import { type DrawSpriteProps } from '../../components/game/atoms/DrawSprite';
+import { type DrawShapeProps } from '../../components/game/atoms/DrawShape';
+import { type DrawTextProps } from '../../components/game/atoms/DrawText';
+import { type DrawSpriteLayerProps } from '../../components/game/molecules/DrawSpriteLayer';
+import { type DrawShapeLayerProps } from '../../components/game/molecules/DrawShapeLayer';
+import { type DrawTextLayerProps } from '../../components/game/molecules/DrawTextLayer';
+/** Every drawable descriptor. The host's `children` are a `DrawableNode[]`. */
+export type DrawableNode = DrawSpriteProps | DrawShapeProps | DrawTextProps | DrawSpriteLayerProps | DrawShapeLayerProps | DrawTextLayerProps;
+/** Dispatch a drawable descriptor to its 2D painter. Unknown types are skipped — never throws. */
+export declare function paintDrawable(painter: Painter2D, node: DrawableNode, dctx: DrawContext): void;

package/dist/lib/drawable/projector.d.ts

@@ -0,0 +1,14 @@
+import type { Projector } from './contract';
+import { type TileLayout } from '../isometric';
+/** Projection modes the 2D host supports. `side` is handled by the side host, not here. */
+export type Projection2D = TileLayout | 'free';
+export interface Projector2DOptions {
+    scale: number;
+    /** Horizontal offset that centers the grid (0 for `flat`/`free`). */
+    baseOffsetX: number;
+    layout: Projection2D;
+    /** Override the measured diamond-top offset (default `DIAMOND_TOP_Y`). */
+    diamondTopY?: number;
+}
+/** Build a {@link Projector} for a 2D projection. */
+export declare function create2DProjector(opts: Projector2DOptions): Projector;

package/dist/lib/drawable/projector3d.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 3D projector — maps a core `ScenePos` to an R3F world position, mirroring the
+ * `gridToWorld` convention in `grid3D.ts` (grid X → world X, grid Y → world Z on
+ * the ground plane, scene Z → world Y as height). The 3D twin of `create2DProjector`;
+ * the SAME drawable descriptors flow to both, only the renderer differs (mesh vs paint).
+ */
+import type { ScenePos } from '@almadar/core';
+export interface Projector3D {
+    /** Scene position → `[x, y, z]` world position (y is up). */
+    toWorld(pos: ScenePos): [number, number, number];
+    /** World units per grid cell. */
+    readonly cellSize: number;
+}
+export interface Projector3DOptions {
+    cellSize?: number;
+    offsetX?: number;
+    offsetZ?: number;
+}
+/** Build a {@link Projector3D}. */
+export declare function create3DProjector(opts?: Projector3DOptions): Projector3D;

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

@@ -0,0 +1,178 @@
+/**
+ * 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/Drawable3D.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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

@@ -0,0 +1,16 @@
+/** 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/game3dTheme.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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/{components/game/shared → lib/drawable/three}/hooks/useGameCanvas3DEvents.d.ts

@@ -1,11 +1,12 @@
 import type { EventEmit } from '@almadar/core';
-import type { IsometricTile, IsometricUnit, IsometricFeature } from '../isometricTypes';
+import type { IsometricTile, IsometricUnit, IsometricFeature } from '../../../isometricTypes';
 export interface GameCanvas3DEventConfig {
-    /** Event name for tile clicks */
+    /** 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<{
-        tileId: string;
         x: number;
         z: number;
+        tileId?: string;
         type?: string;
         terrain?: string;
         elevation?: number;