@almadar/ui 5.78.0 → 5.79.1

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

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

@@ -1,4 +0,0 @@
-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

@@ -1,4 +0,0 @@
-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

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

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

@@ -1,5 +0,0 @@
-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

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

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

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

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

@@ -1,16 +0,0 @@
-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 {};