@almadar/ui 2.13.3 → 2.15.0

package/dist/components/organisms/game/TraitSlot.d.ts

@@ -0,0 +1,90 @@
+/**
+ * TraitSlot Component
+ *
+ * A generic equippable slot with drag-and-drop support.
+ * Shows a TraitStateViewer tooltip on hover for equipped items.
+ * Used across game tiers:
+ * - Sequencer (5-8): action slots in the sequence bar
+ * - Event Handler (9-12): rule slots on world objects
+ * - State Architect (13+): transition slots on state nodes
+ *
+ * **State categories (closed-circuit compliant):**
+ * - Data (equippedItem, slotNumber, locked, selected, feedback) → received via props
+ * - UI-transient (isHovered, isDragOver) → local only
+ * - Events → emitted via `useEventBus()` (click, remove)
+ *
+ * Local state is hover/drag-over detection only — rendering-only concerns.
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+import { type TraitStateMachineDefinition } from './TraitStateViewer';
+/** Data shape for a slot's equipped item */
+export interface SlotItemData {
+    id: string;
+    name: string;
+    category: string;
+    description?: string;
+    /** Emoji or text icon */
+    iconEmoji?: string;
+    /** Image URL icon (takes precedence over iconEmoji) */
+    iconUrl?: string;
+    /** Optional state machine for tooltip display */
+    stateMachine?: TraitStateMachineDefinition;
+}
+/** Event Contract:
+ *  Emits: UI:CLICK
+ *  Emits: UI:REMOVE
+ */
+export interface TraitSlotProps {
+    /** Slot index (1-based) */
+    slotNumber: number;
+    /** Currently equipped item, if any */
+    equippedItem?: SlotItemData;
+    /** Whether slot is locked */
+    locked?: boolean;
+    /** Label shown when locked */
+    lockLabel?: string;
+    /** Whether slot is selected */
+    selected?: boolean;
+    /** Size variant */
+    size?: 'sm' | 'md' | 'lg';
+    /** Show tooltip on hover */
+    showTooltip?: boolean;
+    /** Category → color mapping */
+    categoryColors?: Record<string, {
+        bg: string;
+        border: string;
+    }>;
+    /** Optional tooltip frame image URL */
+    tooltipFrameUrl?: string;
+    /** Additional CSS classes */
+    className?: string;
+    /** Loading state */
+    isLoading?: boolean;
+    /** Error state */
+    error?: Error | null;
+    /** Entity name for schema-driven auto-fetch */
+    entity?: string;
+    /** Called when an item is dropped on this slot */
+    onItemDrop?: (item: SlotItemData) => void;
+    /** Whether this slot's equipped item is draggable */
+    draggable?: boolean;
+    /** Called when drag starts from this slot */
+    onDragStart?: (item: SlotItemData) => void;
+    /** Per-slot correctness feedback after a failed attempt */
+    feedback?: 'correct' | 'wrong' | null;
+    /** Click handler */
+    onClick?: () => void;
+    /** Remove handler */
+    onRemove?: () => void;
+    /** Emits UI:{clickEvent} with { slotNumber } */
+    clickEvent?: string;
+    /** Emits UI:{removeEvent} with { slotNumber } */
+    removeEvent?: string;
+}
+export declare function TraitSlot({ slotNumber, equippedItem, locked, lockLabel, selected, size, showTooltip, categoryColors, tooltipFrameUrl, className, feedback, onItemDrop, draggable, onDragStart, onClick, onRemove, clickEvent, removeEvent, }: TraitSlotProps): React.JSX.Element;
+export declare namespace TraitSlot {
+    var displayName: string;
+}
+export default TraitSlot;

package/dist/components/organisms/game/TraitStateViewer.d.ts

@@ -0,0 +1,53 @@
+/**
+ * TraitStateViewer Component
+ *
+ * Displays a state machine visualization for a trait / behavior.
+ * Three variants for different complexity levels:
+ * - `linear`  — simple step progression (ages 5-8)
+ * - `compact` — current state + available actions (ages 9-12)
+ * - `full`    — all states, transitions, guards (ages 13+)
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+import { type StateStyle } from '../../atoms/game/StateIndicator';
+export interface TraitTransition {
+    from: string;
+    to: string;
+    event: string;
+    guardHint?: string;
+}
+export interface TraitStateMachineDefinition {
+    name: string;
+    states: string[];
+    currentState: string;
+    transitions: TraitTransition[];
+    description?: string;
+}
+export interface TraitStateViewerProps {
+    /** The trait / state machine to visualize */
+    trait: TraitStateMachineDefinition;
+    /** Display variant */
+    variant?: 'linear' | 'compact' | 'full';
+    /** Size variant */
+    size?: 'sm' | 'md' | 'lg';
+    /** Whether to show transition labels */
+    showTransitions?: boolean;
+    /** Click handler for states */
+    onStateClick?: (state: string) => void;
+    /** Custom state styles passed to StateIndicator */
+    stateStyles?: Record<string, StateStyle>;
+    /** Additional CSS classes */
+    className?: string;
+    /** Loading state */
+    isLoading?: boolean;
+    /** Error state */
+    error?: Error | null;
+    /** Entity name for schema-driven auto-fetch */
+    entity?: string;
+}
+export declare function TraitStateViewer({ trait, variant, size, showTransitions, onStateClick, stateStyles, className, }: TraitStateViewerProps): React.JSX.Element;
+export declare namespace TraitStateViewer {
+    var displayName: string;
+}
+export default TraitStateViewer;

package/dist/components/organisms/game/UncontrolledBattleBoard.d.ts

@@ -0,0 +1,26 @@
+/**
+ * UncontrolledBattleBoard
+ *
+ * Thin wrapper that composes `useBattleState` + `BattleBoard` for
+ * self-managing game state.  Accepts `initialUnits` instead of the
+ * controlled-mode fields and manages units, phase, turn, gameResult,
+ * and selectedUnitId internally via the hook.
+ *
+ * Use this component when you want the BattleBoard to manage its own
+ * game logic (e.g. in Storybook, prototypes, or simple integrations).
+ * For Orbital trait integration, use `BattleBoard` directly in
+ * controlled mode.
+ *
+ * @packageDocumentation
+ */
+import { type BattleBoardProps, type BattleUnit } from './BattleBoard';
+export interface UncontrolledBattleBoardProps extends Omit<BattleBoardProps, 'entity'> {
+    entity: Omit<BattleBoardProps['entity'], 'units' | 'phase' | 'turn' | 'gameResult' | 'selectedUnitId'> & {
+        initialUnits: BattleUnit[];
+    };
+}
+export declare function UncontrolledBattleBoard({ entity, ...rest }: UncontrolledBattleBoardProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace UncontrolledBattleBoard {
+    var displayName: string;
+}
+export default UncontrolledBattleBoard;

package/dist/components/organisms/game/WorldMapBoard.d.ts

@@ -0,0 +1,156 @@
+/**
+ * WorldMapBoard
+ *
+ * Organism for the strategic world-map view.  Renders an isometric hex/iso
+ * map with hero selection, movement animation, and encounter callbacks.
+ * Game-specific panels (hero detail, hero lists, resource bars) are injected
+ * via render-prop slots.
+ *
+ * **State categories (closed-circuit compliant):**
+ * - Game data (hexes, heroes, selectedHeroId, features) → received via
+ *   `entity` prop; the Orbital trait owns this state.
+ * - Rendering state (hoveredTile, movingPositions animation) → local only.
+ * - Events → emitted via `useEventBus()` for trait integration.
+ *
+ * This component is mostly prop-driven.  The only internal state is hover
+ * tracking and movement animation interpolation, both of which are
+ * rendering-only concerns that cannot (and should not) be externalised.
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+import type { EntityDisplayProps } from '../types';
+import type { IsometricFeature } from './types/isometric';
+import type { ResolvedFrame } from './types/spriteAnimation';
+/** A hero on the world map */
+export interface MapHero {
+    id: string;
+    name: string;
+    owner: 'player' | 'enemy' | string;
+    position: {
+        x: number;
+        y: number;
+    };
+    movement: number;
+    sprite?: string;
+    /** Optional sprite sheet for animation (null = use static sprite) */
+    spriteSheet?: {
+        se: string;
+        sw: string;
+        frameWidth: number;
+        frameHeight: number;
+    } | null;
+    level?: number;
+}
+/** A hex on the map */
+export interface MapHex {
+    x: number;
+    y: number;
+    terrain: string;
+    terrainSprite?: string;
+    feature?: string;
+    featureData?: Record<string, unknown>;
+    passable?: boolean;
+}
+/** Context exposed to render-prop slots */
+export interface WorldMapSlotContext {
+    /** Currently hovered tile */
+    hoveredTile: {
+        x: number;
+        y: number;
+    } | null;
+    /** Hex at the hovered tile */
+    hoveredHex: MapHex | null;
+    /** Hero at the hovered tile */
+    hoveredHero: MapHero | null;
+    /** Currently selected hero */
+    selectedHero: MapHero | null;
+    /** Valid move tiles for selected hero */
+    validMoves: Array<{
+        x: number;
+        y: number;
+    }>;
+    /** Selects a hero */
+    selectHero: (id: string) => void;
+    /** Resolve screen position of a tile for overlays */
+    tileToScreen: (x: number, y: number) => {
+        x: number;
+        y: number;
+    };
+    /** Canvas scale */
+    scale: number;
+}
+/** Entity shape for the WorldMapBoard */
+export interface WorldMapEntity {
+    id: string;
+    hexes: MapHex[];
+    heroes: MapHero[];
+    features?: IsometricFeature[];
+    selectedHeroId?: string | null;
+    assetManifest?: {
+        baseUrl: string;
+        terrains?: Record<string, string>;
+        units?: Record<string, string>;
+        features?: Record<string, string>;
+    };
+    backgroundImage?: string;
+}
+/** Event Contract:
+ *  Emits: UI:HERO_SELECT
+ *  Emits: UI:HERO_MOVE
+ *  Emits: UI:BATTLE_ENCOUNTER
+ *  Emits: UI:FEATURE_ENTER
+ *  Emits: UI:TILE_CLICK
+ */
+export interface WorldMapBoardProps extends EntityDisplayProps<WorldMapEntity> {
+    /** Canvas render scale */
+    scale?: number;
+    /** Unit draw-size multiplier */
+    unitScale?: number;
+    /** Allow selecting / moving ALL heroes (including enemy). For testing. */
+    allowMoveAllHeroes?: boolean;
+    /** Custom movement range validator */
+    isInRange?: (from: {
+        x: number;
+        y: number;
+    }, to: {
+        x: number;
+        y: number;
+    }, range: number) => boolean;
+    /** Emits UI:{heroSelectEvent} with { heroId } */
+    heroSelectEvent?: string;
+    /** Emits UI:{heroMoveEvent} with { heroId, toX, toY } */
+    heroMoveEvent?: string;
+    /** Emits UI:{battleEncounterEvent} with { attackerId, defenderId } */
+    battleEncounterEvent?: string;
+    /** Emits UI:{featureEnterEvent} with { heroId, feature, hex } */
+    featureEnterEvent?: string;
+    /** Emits UI:{tileClickEvent} with { x, y } */
+    tileClickEvent?: string;
+    /** Header / top bar */
+    header?: (ctx: WorldMapSlotContext) => React.ReactNode;
+    /** Side panel (hero detail, hero lists, etc.) */
+    sidePanel?: (ctx: WorldMapSlotContext) => React.ReactNode;
+    /** Canvas overlay (tooltips, popups) */
+    overlay?: (ctx: WorldMapSlotContext) => React.ReactNode;
+    /** Footer */
+    footer?: (ctx: WorldMapSlotContext) => React.ReactNode;
+    onHeroSelect?: (heroId: string) => void;
+    onHeroMove?: (heroId: string, toX: number, toY: number) => void;
+    /** Called when hero clicks an enemy hero tile */
+    onBattleEncounter?: (attackerId: string, defenderId: string) => void;
+    /** Called when hero enters a feature hex (castle, resource, etc.) */
+    onFeatureEnter?: (heroId: string, hex: MapHex) => void;
+    /** Override for the diamond-top Y offset within tile sprites (default: 374). */
+    diamondTopY?: number;
+    /** Disable pan/zoom camera (default: true). Set false for fixed maps where overlay labels need stable positions. */
+    enableCamera?: boolean;
+    effectSpriteUrls?: string[];
+    resolveUnitFrame?: (unitId: string) => ResolvedFrame | null;
+    className?: string;
+}
+export declare function WorldMapBoard({ entity, isLoading, scale, unitScale, allowMoveAllHeroes, isInRange, heroSelectEvent, heroMoveEvent, battleEncounterEvent, featureEnterEvent, tileClickEvent, header, sidePanel, overlay, footer, onHeroSelect, onHeroMove, onBattleEncounter, onFeatureEnter, diamondTopY, enableCamera, effectSpriteUrls, resolveUnitFrame, className, }: WorldMapBoardProps): React.JSX.Element;
+export declare namespace WorldMapBoard {
+    var displayName: string;
+}
+export default WorldMapBoard;

package/dist/components/organisms/game/editor/editorUtils.d.ts

@@ -0,0 +1,109 @@
+/**
+ * Shared Map Editor Utilities
+ *
+ * Reusable editor components for Storybook-based map editing.
+ * All composed from @almadar/ui atoms (Box, VStack, HStack, Typography, Button, Badge).
+ *
+ * NOTE: These are Storybook editor controls, NOT Orbital templates.
+ * They use native HTML inputs wrapped in Box for lightweight editor UX.
+ */
+import React from 'react';
+export type EditorMode = 'select' | 'paint' | 'unit' | 'feature' | 'erase';
+export declare const TERRAIN_COLORS: Record<string, string>;
+export declare const FEATURE_TYPES: readonly ["goldMine", "resonanceCrystal", "traitCache", "salvageYard", "portal", "battleMarker", "treasure", "castle"];
+export interface CollapsibleSectionProps {
+    title: string;
+    expanded: boolean;
+    onToggle: () => void;
+    children: React.ReactNode;
+    className?: string;
+}
+export declare function CollapsibleSection({ title, expanded, onToggle, children, className }: CollapsibleSectionProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace CollapsibleSection {
+    var displayName: string;
+}
+export interface EditorSliderProps {
+    label: string;
+    value: number;
+    min: number;
+    max: number;
+    step?: number;
+    onChange: (value: number) => void;
+    className?: string;
+}
+export declare function EditorSlider({ label, value, min, max, step, onChange, className }: EditorSliderProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace EditorSlider {
+    var displayName: string;
+}
+export interface EditorSelectProps {
+    label: string;
+    value: string;
+    options: Array<{
+        value: string;
+        label: string;
+    }>;
+    onChange: (value: string) => void;
+    className?: string;
+}
+export declare function EditorSelect({ label, value, options, onChange, className }: EditorSelectProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace EditorSelect {
+    var displayName: string;
+}
+export interface EditorCheckboxProps {
+    label: string;
+    checked: boolean;
+    onChange: (checked: boolean) => void;
+    className?: string;
+}
+export declare function EditorCheckbox({ label, checked, onChange, className }: EditorCheckboxProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace EditorCheckbox {
+    var displayName: string;
+}
+export interface EditorTextInputProps {
+    label: string;
+    value: string;
+    onChange: (value: string) => void;
+    placeholder?: string;
+    className?: string;
+}
+export declare function EditorTextInput({ label, value, onChange, placeholder, className }: EditorTextInputProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace EditorTextInput {
+    var displayName: string;
+}
+export interface StatusBarProps {
+    hoveredTile: {
+        x: number;
+        y: number;
+    } | null;
+    mode: EditorMode;
+    gridSize?: {
+        width: number;
+        height: number;
+    };
+    unitCount?: number;
+    featureCount?: number;
+    className?: string;
+}
+export declare function StatusBar({ hoveredTile, mode, gridSize, unitCount, featureCount, className }: StatusBarProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace StatusBar {
+    var displayName: string;
+}
+export interface TerrainPaletteProps {
+    terrains: string[];
+    selectedTerrain: string;
+    onSelect: (terrain: string) => void;
+    className?: string;
+}
+export declare function TerrainPalette({ terrains, selectedTerrain, onSelect, className }: TerrainPaletteProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace TerrainPalette {
+    var displayName: string;
+}
+export interface EditorToolbarProps {
+    mode: EditorMode;
+    onModeChange: (mode: EditorMode) => void;
+    className?: string;
+}
+export declare function EditorToolbar({ mode, onModeChange, className }: EditorToolbarProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace EditorToolbar {
+    var displayName: string;
+}

package/dist/components/organisms/game/editor/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Map Editor Utilities
+ *
+ * Reusable editor components for Storybook-based isometric map editing.
+ * All composed from @almadar/ui atoms.
+ *
+ * @packageDocumentation
+ */
+export { CollapsibleSection, EditorSlider, EditorSelect, EditorCheckbox, EditorTextInput, StatusBar, TerrainPalette, EditorToolbar, TERRAIN_COLORS, FEATURE_TYPES, type EditorMode, type CollapsibleSectionProps, type EditorSliderProps, type EditorSelectProps, type EditorCheckboxProps, type EditorTextInputProps, type StatusBarProps, type TerrainPaletteProps, type EditorToolbarProps, } from './editorUtils';

package/dist/components/organisms/game/hooks/useBattleState.d.ts

@@ -0,0 +1,35 @@
+import type { BattleUnit, BattlePhase } from '../BattleBoard';
+export interface BattleStateEventConfig {
+    tileClickEvent?: string;
+    unitClickEvent?: string;
+    endTurnEvent?: string;
+    cancelEvent?: string;
+    gameEndEvent?: string;
+    playAgainEvent?: string;
+    attackEvent?: string;
+}
+export interface BattleStateCallbacks {
+    /** Called when a unit attacks another */
+    onAttack?: (attacker: BattleUnit, target: BattleUnit, damage: number) => void;
+    /** Called when battle ends */
+    onGameEnd?: (result: 'victory' | 'defeat') => void;
+    /** Called after a unit moves */
+    onUnitMove?: (unit: BattleUnit, to: {
+        x: number;
+        y: number;
+    }) => void;
+    /** Custom combat damage calculator */
+    calculateDamage?: (attacker: BattleUnit, target: BattleUnit) => number;
+}
+export interface BattleStateResult {
+    units: BattleUnit[];
+    selectedUnitId: string | null;
+    phase: BattlePhase;
+    turn: number;
+    gameResult: 'victory' | 'defeat' | null;
+    handleTileClick: (x: number, y: number) => void;
+    handleUnitClick: (unitId: string) => void;
+    handleEndTurn: () => void;
+    handleRestart: () => void;
+}
+export declare function useBattleState(initialUnits: BattleUnit[], eventConfig?: BattleStateEventConfig, callbacks?: BattleStateCallbacks): BattleStateResult;

package/dist/components/organisms/game/hooks/useCamera.d.ts

@@ -0,0 +1,41 @@
+import type { CameraState } from '../types/isometric';
+interface CameraResult {
+    /** Mutable camera state ref (x, y, zoom) */
+    cameraRef: React.MutableRefObject<CameraState>;
+    /** Target camera position for smooth lerp centering. Set to null when reached. */
+    targetCameraRef: React.MutableRefObject<{
+        x: number;
+        y: number;
+    } | null>;
+    /** Whether the user is currently dragging */
+    isDragging: () => boolean;
+    /** Total drag distance — used to distinguish click from pan (threshold: 5px) */
+    dragDistance: () => number;
+    /** Mouse down handler — starts panning */
+    handleMouseDown: (e: React.MouseEvent) => void;
+    /** Mouse up handler — stops panning */
+    handleMouseUp: () => void;
+    /** Mouse move handler — pans camera if dragging, returns true if panning */
+    handleMouseMove: (e: React.MouseEvent, drawFn?: () => void) => boolean;
+    /** Mouse leave handler — cancels drag */
+    handleMouseLeave: () => void;
+    /** Wheel handler — zoom in/out */
+    handleWheel: (e: React.WheelEvent, drawFn?: () => void) => void;
+    /** Convert screen coordinates to world coordinates (inverse camera transform) */
+    screenToWorld: (clientX: number, clientY: number, canvas: HTMLCanvasElement, viewportSize: {
+        width: number;
+        height: number;
+    }) => {
+        x: number;
+        y: number;
+    };
+    /** Lerp camera toward target. Call in animation loop. Returns true if still animating. */
+    lerpToTarget: (t?: number) => boolean;
+}
+/**
+ * Camera hook for pan/zoom canvas rendering.
+ *
+ * @returns Camera state, event handlers, and coordinate conversion
+ */
+export declare function useCamera(): CameraResult;
+export {};

package/dist/components/organisms/game/hooks/useGameAudio.d.ts

@@ -0,0 +1,47 @@
+export interface SoundEntry {
+    /** Single path or array of paths — array picks randomly on each play */
+    path: string | string[];
+    /** Volume 0–1 (multiplied by masterVolume; default 1) */
+    volume?: number;
+    /** Whether this sound loops (background music) */
+    loop?: boolean;
+    /** Number of concurrent Audio instances in the pool (default 1) */
+    poolSize?: number;
+    /** Start automatically on first user interaction */
+    autostart?: boolean;
+    /** Use crossfade transitions when played via playMusic() */
+    crossfade?: boolean;
+    /** Crossfade duration in ms (default 1500) */
+    crossfadeDurationMs?: number;
+}
+export type AudioManifest = Record<string, SoundEntry>;
+export interface GameAudioControls {
+    /** Play a sound effect (instant, pooled) */
+    play: (key: string) => void;
+    /** Stop all instances of a sound effect */
+    stop: (key: string) => void;
+    /** Stop all sounds including music */
+    stopAll: () => void;
+    /** Crossfade to a new music track */
+    playMusic: (key: string) => void;
+    /** Fade out and stop the current music */
+    stopMusic: (fadeDurationMs?: number) => void;
+    muted: boolean;
+    setMuted: (muted: boolean) => void;
+    masterVolume: number;
+    setMasterVolume: (volume: number) => void;
+}
+export interface UseGameAudioOptions {
+    /** Sound definitions keyed by logical name */
+    manifest: AudioManifest;
+    /** Prefix prepended to all `path` values (default '') */
+    baseUrl?: string;
+    /** Start muted (default false) */
+    initialMuted?: boolean;
+    /** Master volume 0–1 (default 1) */
+    initialVolume?: number;
+}
+export declare function useGameAudio({ manifest, baseUrl, initialMuted, initialVolume, }: UseGameAudioOptions): GameAudioControls;
+export declare namespace useGameAudio {
+    var displayName: string;
+}

package/dist/components/organisms/game/hooks/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 {};

package/dist/components/organisms/game/hooks/usePhysics2D.d.ts

@@ -0,0 +1,45 @@
+import { Physics2DState, PhysicsConfig, PhysicsBounds } from '../managers/PhysicsManager';
+export interface UsePhysics2DOptions extends PhysicsConfig {
+    /** Enable physics debug visualization */
+    debug?: boolean;
+    /** Callback when collision occurs */
+    onCollision?: (entityIdA: string, entityIdB: string) => void;
+    /** Ground Y position (default: 500) */
+    groundY?: number;
+}
+export interface UsePhysics2DReturn {
+    /** Register a unit for physics simulation */
+    registerUnit: (unitId: string, options?: Partial<Physics2DState>) => void;
+    /** Unregister a unit from physics */
+    unregisterUnit: (unitId: string) => void;
+    /** Get current physics position for a unit */
+    getPosition: (unitId: string) => {
+        x: number;
+        y: number;
+    } | null;
+    /** Get full physics state for a unit */
+    getState: (unitId: string) => Physics2DState | undefined;
+    /** Apply force to a unit */
+    applyForce: (unitId: string, fx: number, fy: number) => void;
+    /** Set velocity directly */
+    setVelocity: (unitId: string, vx: number, vy: number) => void;
+    /** Set position directly (teleport) */
+    setPosition: (unitId: string, x: number, y: number) => void;
+    /** Run physics tick - call this in your RAF loop */
+    tick: (deltaTime?: number) => void;
+    /** Check collision between two units */
+    checkCollision: (unitIdA: string, unitIdB: string, boundsA: PhysicsBounds, boundsB: PhysicsBounds) => boolean;
+    /** Resolve collision between two units */
+    resolveCollision: (unitIdA: string, unitIdB: string) => void;
+    /** Freeze/unfreeze a unit */
+    setFrozen: (unitId: string, frozen: boolean) => void;
+    /** Get all physics-enabled units */
+    getAllUnits: () => Physics2DState[];
+    /** Reset all physics */
+    reset: () => void;
+}
+/**
+ * Hook for managing 2D physics simulation
+ */
+export declare function usePhysics2D(options?: UsePhysics2DOptions): UsePhysics2DReturn;
+export default usePhysics2D;

package/dist/components/organisms/game/hooks/useSpriteAnimations.d.ts

@@ -0,0 +1,43 @@
+import type { IsometricUnit } from '../types/isometric';
+import type { AnimationName, FacingDirection, ResolvedFrame, SpriteFrameDims, SpriteSheetUrls } from '../types/spriteAnimation';
+export interface UseSpriteAnimationsResult {
+    /**
+     * Sync unit list and advance all animation timers.
+     * Call once per animation frame. Auto-detects movement
+     * and infers direction from position deltas.
+     */
+    syncUnits: (units: IsometricUnit[], deltaMs: number) => void;
+    /**
+     * Explicitly set a unit's animation (for combat: attack, hit, death).
+     * Optionally override direction.
+     */
+    setUnitAnimation: (unitId: string, animation: AnimationName, direction?: FacingDirection) => void;
+    /**
+     * Resolve the current frame for a unit. Returns null if no sprite sheet
+     * is available for this unit (falls back to static sprite in canvas).
+     * Pass this to IsometricCanvas.resolveUnitFrame.
+     */
+    resolveUnitFrame: (unitId: string) => ResolvedFrame | null;
+}
+export interface UseSpriteAnimationsOptions {
+    /** Playback speed multiplier. 1.0 = baseline, 2.0 = double speed. Default: 1. */
+    speed?: number;
+}
+/**
+ * Resolve sprite sheet URLs for a unit. Return null if no sheet available.
+ * This is the project-agnostic callback version — projects pass manifest-specific logic.
+ */
+export type SheetUrlResolver = (unit: IsometricUnit) => SpriteSheetUrls | null;
+/**
+ * Resolve frame dimensions for a unit's sprite sheet.
+ * Projects pass manifest-specific logic.
+ */
+export type FrameDimsResolver = (unit: IsometricUnit) => SpriteFrameDims | null;
+/**
+ * Hook for managing per-unit sprite sheet animations.
+ *
+ * @param getSheetUrls - Callback to resolve sprite sheet URLs for a unit
+ * @param getFrameDims - Callback to resolve frame dimensions for a unit
+ * @param options - Playback speed options
+ */
+export declare function useSpriteAnimations(getSheetUrls: SheetUrlResolver, getFrameDims: FrameDimsResolver, options?: UseSpriteAnimationsOptions): UseSpriteAnimationsResult;