@almadar/ui 5.79.1 → 5.80.0

package/dist/components/game/shared/lib/grid3D.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Grid 3D Utilities
+ *
+ * Utility functions for 3D grid coordinate transformations,
+ * raycasting, and spatial calculations for GameCanvas3D.
+ *
+ * @packageDocumentation
+ */
+import * as THREE from 'three';
+export interface Grid3DConfig {
+    /** Size of each grid cell */
+    cellSize: number;
+    /** Grid offset X */
+    offsetX?: number;
+    /** Grid offset Z */
+    offsetZ?: number;
+    /** Grid Y height (elevation) */
+    elevation?: number;
+}
+export interface GridCoordinate {
+    x: number;
+    y: number;
+    z: number;
+}
+/**
+ * Convert grid coordinates to world position
+ * @param gridX - Grid X coordinate
+ * @param gridZ - Grid Z coordinate
+ * @param config - Grid configuration
+ * @returns World position vector
+ */
+export declare function gridToWorld(gridX: number, gridZ: number, config?: Grid3DConfig): THREE.Vector3;
+/**
+ * Convert world position to grid coordinates
+ * @param worldX - World X position
+ * @param worldZ - World Z position
+ * @param config - Grid configuration
+ * @returns Grid coordinates
+ */
+export declare function worldToGrid(worldX: number, worldZ: number, config?: Grid3DConfig): {
+    x: number;
+    z: number;
+};
+/**
+ * Raycast from camera through mouse position to find grid intersection
+ * @param camera - Three.js camera
+ * @param mouseX - Mouse X position (normalized -1 to 1)
+ * @param mouseY - Mouse Y position (normalized -1 to 1)
+ * @param planeY - Y height of the intersection plane (default: 0)
+ * @returns Intersection point or null
+ */
+export declare function raycastToPlane(camera: THREE.Camera, mouseX: number, mouseY: number, planeY?: number): THREE.Vector3 | null;
+/**
+ * Raycast from camera through mouse position against a set of objects
+ * @param camera - Three.js camera
+ * @param mouseX - Mouse X position (normalized -1 to 1)
+ * @param mouseY - Mouse Y position (normalized -1 to 1)
+ * @param objects - Array of objects to test
+ * @returns First intersection or null
+ */
+export declare function raycastToObjects(camera: THREE.Camera, mouseX: number, mouseY: number, objects: THREE.Object3D[]): THREE.Intersection | null;
+/**
+ * Calculate distance between two grid coordinates
+ * @param a - First grid coordinate
+ * @param b - Second grid coordinate
+ * @returns Distance in grid units
+ */
+export declare function gridDistance(a: {
+    x: number;
+    z: number;
+}, b: {
+    x: number;
+    z: number;
+}): number;
+/**
+ * Calculate Manhattan distance between two grid coordinates
+ * @param a - First grid coordinate
+ * @param b - Second grid coordinate
+ * @returns Manhattan distance
+ */
+export declare function gridManhattanDistance(a: {
+    x: number;
+    z: number;
+}, b: {
+    x: number;
+    z: number;
+}): number;
+/**
+ * Get neighboring grid cells
+ * @param x - Center X coordinate
+ * @param z - Center Z coordinate
+ * @param includeDiagonal - Whether to include diagonal neighbors
+ * @returns Array of neighbor coordinates
+ */
+export declare function getNeighbors(x: number, z: number, includeDiagonal?: boolean): {
+    x: number;
+    z: number;
+}[];
+/**
+ * Check if a grid coordinate is within bounds
+ * @param x - X coordinate
+ * @param z - Z coordinate
+ * @param bounds - Bounds object
+ * @returns Whether the coordinate is within bounds
+ */
+export declare function isInBounds(x: number, z: number, bounds: {
+    minX: number;
+    maxX: number;
+    minZ: number;
+    maxZ: number;
+}): boolean;
+/**
+ * Get all grid cells within a circular radius
+ * @param centerX - Center X coordinate
+ * @param centerZ - Center Z coordinate
+ * @param radius - Radius in grid units
+ * @returns Array of coordinates within radius
+ */
+export declare function getCellsInRadius(centerX: number, centerZ: number, radius: number): {
+    x: number;
+    z: number;
+}[];
+/**
+ * Create a highlight mesh for grid cells
+ * @param color - Highlight color
+ * @param opacity - Opacity (0-1)
+ * @returns Mesh that can be positioned at grid cells
+ */
+export declare function createGridHighlight(color?: number, opacity?: number): THREE.Mesh;
+/**
+ * Normalize mouse coordinates to NDC (-1 to 1)
+ * @param clientX - Mouse client X
+ * @param clientY - Mouse client Y
+ * @param element - Canvas element
+ * @returns Normalized coordinates
+ */
+export declare function normalizeMouseCoordinates(clientX: number, clientY: number, element: HTMLElement): {
+    x: number;
+    y: number;
+};
+declare const _default: {
+    gridToWorld: typeof gridToWorld;
+    worldToGrid: typeof worldToGrid;
+    raycastToPlane: typeof raycastToPlane;
+    raycastToObjects: typeof raycastToObjects;
+    gridDistance: typeof gridDistance;
+    gridManhattanDistance: typeof gridManhattanDistance;
+    getNeighbors: typeof getNeighbors;
+    isInBounds: typeof isInBounds;
+    getCellsInRadius: typeof getCellsInRadius;
+    createGridHighlight: typeof createGridHighlight;
+    normalizeMouseCoordinates: typeof normalizeMouseCoordinates;
+};
+export default _default;

package/dist/components/game/shared/lib/mechanics.d.ts

@@ -0,0 +1,4 @@
+import type { PhysicsPreset } from './physicsTypes';
+export declare const projectileMotion: PhysicsPreset;
+export declare const pendulum: PhysicsPreset;
+export declare const springOscillator: PhysicsPreset;

package/dist/components/game/shared/lib/physicsPresets.d.ts

@@ -0,0 +1,4 @@
+export type { PhysicsPreset, PhysicsBody, PhysicsConstraint } from './physicsTypes';
+export { projectileMotion, pendulum, springOscillator } from './mechanics';
+import type { PhysicsPreset } from './physicsTypes';
+export declare const ALL_PRESETS: PhysicsPreset[];

package/dist/components/game/shared/lib/physicsTypes.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Physics Preset Types
+ *
+ * Configuration for physics simulation presets.
+ */
+export interface PhysicsBody {
+    id: string;
+    x: number;
+    y: number;
+    vx: number;
+    vy: number;
+    mass: number;
+    radius: number;
+    color: string;
+    fixed: boolean;
+}
+export interface PhysicsConstraint {
+    bodyA: number;
+    bodyB: number;
+    length: number;
+    stiffness: number;
+}
+export interface PhysicsPreset {
+    id: string;
+    name: string;
+    description: string;
+    domain: string;
+    gravity?: {
+        x: number;
+        y: number;
+    };
+    bodies: PhysicsBody[];
+    constraints?: PhysicsConstraint[];
+    backgroundColor?: string;
+    showVelocity?: boolean;
+    parameters: Record<string, {
+        value: number;
+        min: number;
+        max: number;
+        step: number;
+        label: string;
+    }>;
+}

package/dist/components/game/shared/lib/puzzleObject.d.ts

@@ -0,0 +1,32 @@
+/**
+ * puzzleObject — field accessors for reading Event-Handler puzzle-object data
+ * off an `EntityRow`.
+ *
+ * The puzzle objects the kid configures arrive as `entity.objects` (an array of
+ * `EntityRow`). These helpers narrow the weakly-typed fields the panel reads.
+ * `RuleDefinition` / `RuleOption` remain plain UI value DTOs (see `RuleEditor`).
+ *
+ * @packageDocumentation
+ */
+import type { EntityWith } from '@almadar/core';
+import type { RuleDefinition, RuleOption } from '../../2d/organisms/RuleEditor';
+type PuzzleObjectRow = EntityWith<{
+    name?: string;
+    icon?: string;
+    states?: string[];
+    currentState?: string;
+    availableEvents?: RuleOption[];
+    availableActions?: RuleOption[];
+    rules?: RuleDefinition[];
+    maxRules?: number;
+}>;
+export declare function objId(o: PuzzleObjectRow): string;
+export declare function objName(o: PuzzleObjectRow): string;
+export declare function objIcon(o: PuzzleObjectRow): string;
+export declare function objStates(o: PuzzleObjectRow): string[];
+export declare function objCurrentState(o: PuzzleObjectRow): string;
+export declare function objAvailableEvents(o: PuzzleObjectRow): RuleOption[];
+export declare function objAvailableActions(o: PuzzleObjectRow): RuleOption[];
+export declare function objRules(o: PuzzleObjectRow): RuleDefinition[];
+export declare function objMaxRules(o: PuzzleObjectRow): number;
+export {};

package/dist/components/game/shared/makeAsset.d.ts

@@ -0,0 +1,5 @@
+import type { Asset, EntityRole } from '@almadar/core';
+/** Build an Asset from a url + the slot's role. Slot-fixed defaults by role. */
+export declare function makeAsset(url: string, role: EntityRole, overrides?: Partial<Asset>): Asset;
+/** Map a name→url record to name→Asset. */
+export declare function makeAssetMap(record: Record<string, string>, role: EntityRole, overrides?: Partial<Asset>): Record<string, Asset>;

package/dist/components/game/shared/providers/GameAudioProvider.d.ts

@@ -0,0 +1,53 @@
+/**
+ * GameAudioProvider
+ *
+ * Context provider that wires the audio system to the Almadar event bus.
+ * Wrap your game organism with this provider, then emit:
+ *
+ *   emit('UI:PLAY_SOUND', { key: 'footstep' })
+ *
+ * from anywhere inside the tree and the corresponding sound will play.
+ *
+ * The provider also exposes `muted`/`setMuted` and `masterVolume`/
+ * `setMasterVolume` via the `GameAudioContext` for toggle buttons.
+ *
+ * Closed-circuit props (`className`, `isLoading`, `error`) are
+ * accepted but intentionally unused — the provider renders only its children.
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+import { type AudioManifest, type GameAudioControls } from '../hooks/useGameAudio';
+import type { UiError } from '../../../core/atoms/types';
+export type GameAudioContextValue = Pick<GameAudioControls, 'muted' | 'setMuted' | 'masterVolume' | 'setMasterVolume' | 'play' | 'playMusic' | 'stopMusic'>;
+export declare const GameAudioContext: React.Context<GameAudioContextValue | null>;
+/**
+ * Access the game audio context.
+ * Must be called from within a `<GameAudioProvider>` tree.
+ */
+export declare function useGameAudioContext(): GameAudioContextValue;
+/**
+ * Access the game audio context, or `null` when there is no `<GameAudioProvider>`
+ * ancestor. Lets a component stay self-contained (render standalone with a local
+ * fallback) — the provider is an implementation detail, never a hard precondition.
+ */
+export declare function useGameAudioContextOptional(): GameAudioContextValue | null;
+export interface GameAudioProviderProps {
+    /** Sound manifest — keys mapped to SoundEntry definitions */
+    manifest: AudioManifest;
+    /** Base URL prepended to all sound paths (default '') */
+    baseUrl?: string;
+    /** Children to render */
+    children: React.ReactNode;
+    /** Initial muted state */
+    initialMuted?: boolean;
+    /** Closed-circuit props (unused, accepted for runtime compatibility) */
+    className?: string;
+    isLoading?: boolean;
+    error?: UiError | null;
+}
+export declare function GameAudioProvider({ manifest, baseUrl, children, initialMuted, }: GameAudioProviderProps): React.JSX.Element;
+export declare namespace GameAudioProvider {
+    var displayName: string;
+}
+export default GameAudioProvider;

package/dist/components/game/shared/spriteAnimation.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Sprite Animation Engine
+ *
+ * Pure functions for sprite sheet animation: direction inference,
+ * frame computation, sheet resolution, and animation state management.
+ * No React dependencies — usable in any context.
+ *
+ * @packageDocumentation
+ */
+import type { AnimationDef, AnimationName, FacingDirection, SpriteDirection, ResolvedFrame, UnitAnimationState, SpriteFrameDims, SpriteSheetUrls } from './spriteAnimationTypes';
+/**
+ * Infer facing direction from a movement delta on the isometric grid.
+ * dx/dy are tile coordinate deltas (not screen pixels).
+ *
+ * Isometric grid:
+ *   NW ← (-x)    NE ← (-y)
+ *   SW ← (+y)    SE ← (+x)
+ */
+export declare function inferDirection(dx: number, dy: number): FacingDirection;
+/**
+ * Map a 4-direction facing to the actual sheet file direction + flipX flag.
+ * We only have SE and SW sheet images. NE/NW are rendered by flipping:
+ *   SE → SE sheet, no flip
+ *   SW → SW sheet, no flip
+ *   NE → SW sheet, flipX (mirror of SW gives NE)
+ *   NW → SE sheet, flipX (mirror of SE gives NW)
+ */
+export declare function resolveSheetDirection(facing: FacingDirection): {
+    sheetDir: SpriteDirection;
+    flipX: boolean;
+};
+/** A source rectangle into a sprite sheet for a single frame. */
+export interface FrameRect {
+    /** Source X in the sheet (pixel offset). */
+    sx: number;
+    /** Source Y in the sheet (pixel offset). */
+    sy: number;
+    /** Source width (frame width). */
+    sw: number;
+    /** Source height (frame height). */
+    sh: number;
+}
+/**
+ * Compute the source rect for a single frame within a grid sprite sheet.
+ * Single home for the `sx = (frame % columns) * frameWidth`, `sy = row * frameHeight`
+ * math shared by `Sprite.tsx`, `useUnitSpriteAtlas.ts`, and `resolveFrame`.
+ *
+ * Pass `row` explicitly for atlas-driven layouts (each animation occupies a row);
+ * pass `row = Math.floor(frame / columns)` for flat frame-index sheets.
+ */
+export declare function frameRect(frame: number, row: number, columns: number, frameWidth: number, frameHeight: number): FrameRect;
+/**
+ * Compute the current frame index from an animation definition.
+ * Atlas-driven and constant-driven callers share this one timing core.
+ */
+export declare function getCurrentFrameFromDef(def: AnimationDef, elapsed: number): {
+    frame: number;
+    finished: boolean;
+};
+/**
+ * Compute the current frame index and whether the animation has finished.
+ */
+export declare function getCurrentFrame(animName: AnimationName, elapsed: number): {
+    frame: number;
+    finished: boolean;
+};
+/**
+ * Resolve a complete frame descriptor for canvas drawing.
+ * Returns null if no sprite sheet URLs are available for this unit.
+ */
+export declare function resolveFrame(sheetUrls: SpriteSheetUrls | null, frameDims: SpriteFrameDims, animState: UnitAnimationState): ResolvedFrame | null;
+/**
+ * Create initial animation state for a unit (idle, facing SE).
+ */
+export declare function createUnitAnimationState(unitId: string): UnitAnimationState;
+/**
+ * Transition to a new animation. Resets elapsed time.
+ * Optionally updates direction. Death cannot be overridden.
+ */
+export declare function transitionAnimation(state: UnitAnimationState, newAnim: AnimationName, direction?: FacingDirection): UnitAnimationState;
+/**
+ * Advance animation state by deltaMs.
+ * Handles one-shot → queued/idle transitions automatically.
+ */
+export declare function tickAnimationState(state: UnitAnimationState, deltaMs: number): UnitAnimationState;

package/dist/components/game/shared/spriteAnimationTypes.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Sprite Sheet Animation Types
+ *
+ * Type definitions for frame-based sprite sheet animation system.
+ * Supports standard 8-column × 5-row character sheets.
+ *
+ * @packageDocumentation
+ */
+/** Animation names matching sprite sheet row layout */
+export type AnimationName = 'idle' | 'walk' | 'attack' | 'hit' | 'death';
+/** Sheet file directions (physical PNG files) */
+export type SpriteDirection = 'se' | 'sw';
+/** Unit facing direction on screen (4 isometric directions) */
+export type FacingDirection = 'se' | 'sw' | 'ne' | 'nw';
+/** Definition for a single animation row in the sprite sheet */
+export interface AnimationDef {
+    /** Row index in the sprite sheet (0-4) */
+    row: number;
+    /** Number of frames in this animation */
+    frames: number;
+    /** Frames per second */
+    frameRate: number;
+    /** Whether the animation loops */
+    loop: boolean;
+}
+/** A resolved frame ready to draw on canvas */
+export interface ResolvedFrame {
+    /** URL of the sprite sheet image */
+    sheetUrl: string;
+    /** Source X in the sheet (pixel offset) */
+    sx: number;
+    /** Source Y in the sheet (pixel offset) */
+    sy: number;
+    /** Source width (frame width) */
+    sw: number;
+    /** Source height (frame height) */
+    sh: number;
+    /** Whether to flip horizontally when drawing (for NE/NW directions) */
+    flipX: boolean;
+    /** When true, canvas should apply sine-bob breathing offset (frozen idle frame) */
+    applyBreathing?: boolean;
+}
+/** Per-unit animation state tracked in the animation system */
+export interface UnitAnimationState {
+    /** Unit identifier */
+    unitId: string;
+    /** Current animation playing */
+    animation: AnimationName;
+    /** Current facing direction */
+    direction: FacingDirection;
+    /** Current frame index within the animation */
+    frame: number;
+    /** Elapsed time in current animation (ms) */
+    elapsed: number;
+    /** Animation to play after current one-shot completes (null = idle) */
+    queuedAnimation: AnimationName | null;
+    /** Whether the current one-shot animation has finished its last frame */
+    finished: boolean;
+}
+/** Frame dimensions for a sprite sheet */
+export interface SpriteFrameDims {
+    /** Width of a single frame in pixels */
+    width: number;
+    /** Height of a single frame in pixels */
+    height: number;
+}
+/** Sheet URLs for both directions */
+export interface SpriteSheetUrls {
+    /** Southeast-facing sheet URL */
+    se: string;
+    /** Southwest-facing sheet URL */
+    sw: string;
+}
+/**
+ * Parsed sprite-sheet atlas JSON (e.g. `guardian-sprite-sheet.json`).
+ * Sits next to the `.png` sheets and drives the frame rect deterministically.
+ */
+export interface SpriteAtlas {
+    /** Unit archetype key */
+    unit?: string;
+    /** Visual type key */
+    type?: string;
+    /** Width of a single frame in pixels */
+    frameWidth: number;
+    /** Height of a single frame in pixels */
+    frameHeight: number;
+    /** Number of columns (frames per row) */
+    columns: number;
+    /** Number of rows (animations) */
+    rows: number;
+    /** Directions present as physical PNG files */
+    directions: SpriteDirection[];
+    /** Relative PNG sheet paths per direction */
+    sheets: Partial<Record<SpriteDirection, string>>;
+    /** Animation row layout keyed by animation name */
+    animations: Partial<Record<AnimationName, AnimationDef>>;
+}

package/dist/components/game/shared/spriteSheetConstants.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Sprite Sheet Constants
+ *
+ * Standard layout for 8-column × 5-row character sprite sheets.
+ * All characters share identical sheet geometry.
+ *
+ * @packageDocumentation
+ */
+import type { AnimationDef, AnimationName } from './spriteAnimationTypes';
+/** Number of columns in a sprite sheet (frames per row) */
+export declare const SHEET_COLUMNS = 8;
+/**
+ * Standard sprite sheet row layout.
+ * Row 0 = idle, Row 1 = walk, Row 2 = attack, Row 3 = hit, Row 4 = death.
+ */
+export declare const SPRITE_SHEET_LAYOUT: Record<AnimationName, AnimationDef>;

package/dist/components/game/shared/useImageCache.d.ts

@@ -0,0 +1,16 @@
+interface ImageCacheResult {
+    /** Get a cached image by URL. Returns undefined if not yet loaded. */
+    getImage: (url: string) => HTMLImageElement | undefined;
+    /** Whether all requested images have loaded */
+    isLoaded: boolean;
+    /** Number of images currently loading */
+    pendingCount: number;
+}
+/**
+ * Preload and cache images for canvas rendering.
+ *
+ * @param urls - Array of image URLs to preload
+ * @returns Cache getter, loading state, and pending count
+ */
+export declare function useImageCache(urls: string[]): ImageCacheResult;
+export {};