@almadar/ui 5.71.0 → 5.72.0

package/dist/components/game/atoms/ScoreDisplay.d.ts

@@ -15,12 +15,10 @@ export interface ScoreDisplayProps {
     size?: 'sm' | 'md' | 'lg' | 'xl';
     /** Additional CSS classes */
     className?: string;
-    /** Animation on value change */
-    animated?: boolean;
     /** Number formatting locale */
     locale?: string;
 }
-export declare function ScoreDisplay({ assetUrl, value, score, label, icon, size, className, animated, locale, }: ScoreDisplayProps): import("react/jsx-runtime").JSX.Element;
+export declare function ScoreDisplay({ assetUrl, value, score, label, icon, size, className, locale, }: ScoreDisplayProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace ScoreDisplay {
     var displayName: string;
 }

package/dist/components/game/atoms/Sprite.d.ts

@@ -5,6 +5,7 @@
  */
 import React from 'react';
 import type { EventKey, AssetUrl } from "@almadar/core";
+import type { AnimationName } from '../organisms/types/spriteAnimation';
 export interface SpriteProps {
     /** Spritesheet image URL */
     spritesheet: AssetUrl;
@@ -32,6 +33,10 @@ export interface SpriteProps {
     zIndex?: number;
     /** Number of columns in spritesheet (for frame calculation) */
     columns?: number;
+    /** Animation state name — drives lolo-ui config knob for animation selection */
+    animState?: AnimationName;
+    /** Frames per second — drives lolo-ui config knob for animation speed */
+    frameRate?: number;
     /** Optional className */
     className?: string;
     /** Optional onClick handler */
@@ -56,7 +61,7 @@ export interface SpriteProps {
  * />
  * ```
  */
-export declare function Sprite({ spritesheet, frameWidth, frameHeight, frame, x, y, scale, flipX, flipY, rotation, opacity, zIndex, columns, className, onClick, action, }: SpriteProps): React.JSX.Element;
+export declare function Sprite({ spritesheet, frameWidth, frameHeight, frame, x, y, scale, flipX, flipY, rotation, opacity, zIndex, columns, animState: _animState, frameRate: _frameRate, className, onClick, action, }: SpriteProps): React.JSX.Element;
 /**
  * Canvas-based sprite renderer for better performance in game loops
  */

package/dist/components/game/atoms/XPBar.d.ts

@@ -9,7 +9,7 @@ export interface XPBarProps {
     showLabel?: boolean;
     /** Size variant */
     size?: 'sm' | 'md' | 'lg';
-    /** Animate the fill bar */
+    /** Animate the fill bar with a CSS transition */
     animated?: boolean;
     /** Additional CSS classes */
     className?: string;

package/dist/components/game/molecules/GameCanvas3D.d.ts

@@ -46,8 +46,6 @@ export interface GameCanvas3DProps {
     isLoading?: boolean;
     /** Error state */
     error?: string | null;
-    /** Entity name for schema-driven auto-fetch */
-    entity?: string;
     /** Array of tiles to render */
     tiles?: IsometricTile[];
     /** Array of units to render */

package/dist/components/game/molecules/IsometricCanvas.d.ts

@@ -25,7 +25,7 @@
  */
 import * as React from 'react';
 import type { AssetUrl, EventEmit } from '@almadar/core';
-import type { IsometricTile, IsometricUnit, IsometricFeature } from '../organisms/types/isometric';
+import type { IsometricTile, IsometricUnit, IsometricFeature, ActiveEffect } from '../organisms/types/isometric';
 import type { ResolvedFrame } from '../organisms/types/spriteAnimation';
 import type { TileLayout } from '../organisms/utils/isometric';
 import type { UiError } from '../../core/atoms/types';
@@ -52,6 +52,8 @@ export interface IsometricCanvasProps {
     units?: IsometricUnit[];
     /** Array of features (resources, portals, buildings, etc.) */
     features?: IsometricFeature[];
+    /** Active visual effects to draw after units. Sprite URLs resolved via assetManifest.effects[fx.key]. */
+    effects?: ActiveEffect[];
     /** Currently selected unit ID */
     selectedUnitId?: string | null;
     /** Valid move positions (shown as pulsing green highlights) */
@@ -132,7 +134,7 @@ export interface IsometricCanvasProps {
         effects?: Record<string, string>;
     };
 }
-export declare function IsometricCanvas({ className, isLoading, error, tiles: _tilesPropRaw, units: _unitsPropRaw, features: _featuresPropRaw, selectedUnitId, validMoves, attackTargets, hoveredTile, onTileClick, onUnitClick, onTileHover, onTileLeave, tileClickEvent, unitClickEvent, tileHoverEvent, tileLeaveEvent, tileLayout, scale, debug, backgroundImage, showMinimap, enableCamera, unitScale, spriteHeightRatio, spriteMaxWidthRatio, getTerrainSprite, getFeatureSprite, getUnitSprite, resolveUnitFrame, effectSpriteUrls, onDrawEffects, hasActiveEffects, diamondTopY: diamondTopYProp, assetBaseUrl, assetManifest, }: IsometricCanvasProps): React.JSX.Element;
+export declare function IsometricCanvas({ className, isLoading, error, tiles: _tilesPropRaw, units: _unitsPropRaw, features: _featuresPropRaw, effects: _effectsPropRaw, selectedUnitId, validMoves, attackTargets, hoveredTile, onTileClick, onUnitClick, onTileHover, onTileLeave, tileClickEvent, unitClickEvent, tileHoverEvent, tileLeaveEvent, tileLayout, scale, debug, backgroundImage, showMinimap, enableCamera, unitScale, spriteHeightRatio, spriteMaxWidthRatio, getTerrainSprite, getFeatureSprite, getUnitSprite, resolveUnitFrame, effectSpriteUrls, onDrawEffects, hasActiveEffects: _hasActiveEffects, diamondTopY: diamondTopYProp, assetBaseUrl, assetManifest, }: IsometricCanvasProps): React.JSX.Element;
 export declare namespace IsometricCanvas {
     var displayName: string;
 }

package/dist/components/game/molecules/PlatformerCanvas.d.ts

@@ -1,4 +1,5 @@
 import type { AssetUrl, EventEmit } from '@almadar/core';
+import type { ActiveEffect } from '../organisms/types/isometric';
 export interface PlatformerPlatform {
     x: number;
     y: number;
@@ -48,10 +49,12 @@ export interface PlatformerCanvasProps {
     }>;
     jumpEvent?: EventEmit<Record<string, never>>;
     stopEvent?: EventEmit<Record<string, never>>;
+    /** Active visual effects (key, world x/y, ttl) — drawn after the player */
+    effects?: ActiveEffect[];
     /** Additional CSS classes */
     className?: string;
 }
-export declare function PlatformerCanvas({ player, platforms, worldWidth, worldHeight, canvasWidth, canvasHeight, followCamera, bgColor, playerSprite, tileSprites, backgroundImage, assetBaseUrl, leftEvent, rightEvent, jumpEvent, stopEvent, className, }: PlatformerCanvasProps): import("react/jsx-runtime").JSX.Element;
+export declare function PlatformerCanvas({ player, platforms, worldWidth, worldHeight, canvasWidth, canvasHeight, followCamera, bgColor, playerSprite, tileSprites, backgroundImage, assetBaseUrl, leftEvent, rightEvent, jumpEvent, stopEvent, effects, className, }: PlatformerCanvasProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace PlatformerCanvas {
     var displayName: string;
 }

package/dist/components/game/molecules/StatBadge.d.ts

@@ -9,6 +9,8 @@ import type { AssetUrl } from '@almadar/core';
 export interface StatBadgeProps {
     /** Sprite image URL — takes precedence over icon when provided */
     assetUrl?: AssetUrl;
+    /** Asset-image icon URL (board ui/ PNG); takes precedence over the Lucide icon. */
+    iconUrl?: AssetUrl;
     /** Stat label */
     label: string;
     /** Current value (defaults to 0 if not provided) */
@@ -30,7 +32,7 @@ export interface StatBadgeProps {
     /** Additional CSS classes */
     className?: string;
 }
-export declare function StatBadge({ assetUrl, label, value, max, format, icon, size, variant, className, source: _source, field: _field, }: StatBadgeProps): import("react/jsx-runtime").JSX.Element;
+export declare function StatBadge({ assetUrl, iconUrl, label, value, max, format, icon, size, variant, className, source: _source, field: _field, }: StatBadgeProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace StatBadge {
     var displayName: string;
 }

package/dist/components/game/molecules/three/index.cjs

@@ -2293,13 +2293,6 @@ function preloadFeatures(urls) {
 }
 
 // components/game/organisms/utils/spriteAnimation.ts
-function inferDirection(dx, dy) {
-  if (dx === 0 && dy === 0) return "se";
-  if (dx >= 0 && dy >= 0) return "se";
-  if (dx <= 0 && dy >= 0) return "sw";
-  if (dx >= 0 && dy <= 0) return "ne";
-  return "nw";
-}
 function resolveSheetDirection(facing) {
   switch (facing) {
     case "se":
@@ -2320,22 +2313,8 @@ function frameRect(frame, row, columns, frameWidth, frameHeight) {
     sh: frameHeight
   };
 }
-function getCurrentFrameFromDef(def, elapsed) {
-  const frameDuration = 1e3 / def.frameRate;
-  const totalDuration = def.frames * frameDuration;
-  if (def.loop) {
-    const frame2 = Math.floor(elapsed % totalDuration / frameDuration);
-    return { frame: frame2, finished: false };
-  }
-  if (elapsed >= totalDuration) {
-    return { frame: def.frames - 1, finished: true };
-  }
-  const frame = Math.floor(elapsed / frameDuration);
-  return { frame, finished: false };
-}
 
 // components/game/molecules/useUnitSpriteAtlas.ts
-var WALK_HOLD_MS = 600;
 function unitAtlasUrl(unit) {
   if (unit.spriteSheet) return unit.spriteSheet;
   const sprite = unit.sprite;
@@ -2357,9 +2336,6 @@ function useUnitSpriteAtlas(units) {
   const loadingRef = React11.useRef(/* @__PURE__ */ new Set());
   const [pendingCount, setPendingCount] = React11.useState(0);
   const [, forceTick] = React11.useState(0);
-  const animStatesRef = React11.useRef(/* @__PURE__ */ new Map());
-  const lastTickRef = React11.useRef(0);
-  const rafRef = React11.useRef(0);
   const atlasUrls = React11.useMemo(() => {
     const set = /* @__PURE__ */ new Set();
     for (const unit of units) {
@@ -2405,54 +2381,6 @@ function useUnitSpriteAtlas(units) {
     }
     return [...urls];
   }, [units, pendingCount]);
-  React11.useEffect(() => {
-    const hasAtlasUnits = units.some((u) => unitAtlasUrl(u) !== null);
-    if (!hasAtlasUnits) return;
-    let running = true;
-    const tick = (ts) => {
-      if (!running) return;
-      const last = lastTickRef.current || ts;
-      const delta = ts - last;
-      lastTickRef.current = ts;
-      const states = animStatesRef.current;
-      const currentIds = /* @__PURE__ */ new Set();
-      for (const unit of units) {
-        if (unitAtlasUrl(unit) === null) continue;
-        currentIds.add(unit.id);
-        let state = states.get(unit.id);
-        if (!state) {
-          state = { animation: "idle", direction: "se", elapsed: 0, walkHold: 0, prev: null };
-          states.set(unit.id, state);
-        }
-        const posX = unit.position?.x ?? unit.x ?? 0;
-        const posY = unit.position?.y ?? unit.y ?? 0;
-        if (state.prev) {
-          const dx = posX - state.prev.x;
-          const dy = posY - state.prev.y;
-          if (dx !== 0 || dy !== 0) {
-            state.animation = "walk";
-            state.direction = inferDirection(dx, dy);
-            state.walkHold = WALK_HOLD_MS;
-          } else if (state.animation === "walk") {
-            state.walkHold -= delta;
-            if (state.walkHold <= 0) state.animation = "idle";
-          }
-        }
-        state.prev = { x: posX, y: posY };
-        state.elapsed += delta;
-      }
-      for (const id of states.keys()) {
-        if (!currentIds.has(id)) states.delete(id);
-      }
-      rafRef.current = requestAnimationFrame(tick);
-    };
-    rafRef.current = requestAnimationFrame(tick);
-    return () => {
-      running = false;
-      cancelAnimationFrame(rafRef.current);
-      lastTickRef.current = 0;
-    };
-  }, [units]);
   const resolveUnitFrame = React11.useCallback((unitId) => {
     const unit = units.find((u) => u.id === unitId);
     if (!unit) return null;
@@ -2460,18 +2388,14 @@ function useUnitSpriteAtlas(units) {
     if (!atlasUrl) return null;
     const atlas = atlasCacheRef.current.get(atlasUrl);
     if (!atlas) return null;
-    const state = animStatesRef.current.get(unitId);
-    const animation = state?.animation ?? "idle";
-    const direction = state?.direction ?? "se";
-    const elapsed = state?.elapsed ?? 0;
+    const animation = unit.animation ?? "idle";
+    const frame = unit.frame ?? 0;
     const def = atlas.animations[animation] ?? atlas.animations.idle;
     if (!def) return null;
-    const { sheetDir, flipX } = resolveSheetDirection(direction);
+    const { sheetDir, flipX } = resolveSheetDirection("se");
     const rel = atlas.sheets[sheetDir] ?? atlas.sheets.se ?? atlas.sheets.sw;
     if (!rel) return null;
     const sheetUrl = resolveSheetUrl(atlasUrl, rel);
-    const isIdle = animation === "idle";
-    const frame = isIdle ? 0 : getCurrentFrameFromDef(def, elapsed).frame;
     const rect = frameRect(frame, def.row, atlas.columns, atlas.frameWidth, atlas.frameHeight);
     return {
       sheetUrl,
@@ -2480,7 +2404,7 @@ function useUnitSpriteAtlas(units) {
       sw: rect.sw,
       sh: rect.sh,
       flipX,
-      applyBreathing: isIdle
+      applyBreathing: animation === "idle"
     };
   }, [units]);
   return { sheetUrls, resolveUnitFrame, pendingCount };
@@ -2576,7 +2500,6 @@ var GameCanvas3D = React11.forwardRef(
     className,
     isLoading: externalLoading,
     error: externalError,
-    entity,
     preloadAssets = [],
     tileClickEvent,
     unitClickEvent,

package/dist/components/game/molecules/three/index.js

@@ -2269,13 +2269,6 @@ function preloadFeatures(urls) {
 }
 
 // components/game/organisms/utils/spriteAnimation.ts
-function inferDirection(dx, dy) {
-  if (dx === 0 && dy === 0) return "se";
-  if (dx >= 0 && dy >= 0) return "se";
-  if (dx <= 0 && dy >= 0) return "sw";
-  if (dx >= 0 && dy <= 0) return "ne";
-  return "nw";
-}
 function resolveSheetDirection(facing) {
   switch (facing) {
     case "se":
@@ -2296,22 +2289,8 @@ function frameRect(frame, row, columns, frameWidth, frameHeight) {
     sh: frameHeight
   };
 }
-function getCurrentFrameFromDef(def, elapsed) {
-  const frameDuration = 1e3 / def.frameRate;
-  const totalDuration = def.frames * frameDuration;
-  if (def.loop) {
-    const frame2 = Math.floor(elapsed % totalDuration / frameDuration);
-    return { frame: frame2, finished: false };
-  }
-  if (elapsed >= totalDuration) {
-    return { frame: def.frames - 1, finished: true };
-  }
-  const frame = Math.floor(elapsed / frameDuration);
-  return { frame, finished: false };
-}
 
 // components/game/molecules/useUnitSpriteAtlas.ts
-var WALK_HOLD_MS = 600;
 function unitAtlasUrl(unit) {
   if (unit.spriteSheet) return unit.spriteSheet;
   const sprite = unit.sprite;
@@ -2333,9 +2312,6 @@ function useUnitSpriteAtlas(units) {
   const loadingRef = useRef(/* @__PURE__ */ new Set());
   const [pendingCount, setPendingCount] = useState(0);
   const [, forceTick] = useState(0);
-  const animStatesRef = useRef(/* @__PURE__ */ new Map());
-  const lastTickRef = useRef(0);
-  const rafRef = useRef(0);
   const atlasUrls = useMemo(() => {
     const set = /* @__PURE__ */ new Set();
     for (const unit of units) {
@@ -2381,54 +2357,6 @@ function useUnitSpriteAtlas(units) {
     }
     return [...urls];
   }, [units, pendingCount]);
-  useEffect(() => {
-    const hasAtlasUnits = units.some((u) => unitAtlasUrl(u) !== null);
-    if (!hasAtlasUnits) return;
-    let running = true;
-    const tick = (ts) => {
-      if (!running) return;
-      const last = lastTickRef.current || ts;
-      const delta = ts - last;
-      lastTickRef.current = ts;
-      const states = animStatesRef.current;
-      const currentIds = /* @__PURE__ */ new Set();
-      for (const unit of units) {
-        if (unitAtlasUrl(unit) === null) continue;
-        currentIds.add(unit.id);
-        let state = states.get(unit.id);
-        if (!state) {
-          state = { animation: "idle", direction: "se", elapsed: 0, walkHold: 0, prev: null };
-          states.set(unit.id, state);
-        }
-        const posX = unit.position?.x ?? unit.x ?? 0;
-        const posY = unit.position?.y ?? unit.y ?? 0;
-        if (state.prev) {
-          const dx = posX - state.prev.x;
-          const dy = posY - state.prev.y;
-          if (dx !== 0 || dy !== 0) {
-            state.animation = "walk";
-            state.direction = inferDirection(dx, dy);
-            state.walkHold = WALK_HOLD_MS;
-          } else if (state.animation === "walk") {
-            state.walkHold -= delta;
-            if (state.walkHold <= 0) state.animation = "idle";
-          }
-        }
-        state.prev = { x: posX, y: posY };
-        state.elapsed += delta;
-      }
-      for (const id of states.keys()) {
-        if (!currentIds.has(id)) states.delete(id);
-      }
-      rafRef.current = requestAnimationFrame(tick);
-    };
-    rafRef.current = requestAnimationFrame(tick);
-    return () => {
-      running = false;
-      cancelAnimationFrame(rafRef.current);
-      lastTickRef.current = 0;
-    };
-  }, [units]);
   const resolveUnitFrame = useCallback((unitId) => {
     const unit = units.find((u) => u.id === unitId);
     if (!unit) return null;
@@ -2436,18 +2364,14 @@ function useUnitSpriteAtlas(units) {
     if (!atlasUrl) return null;
     const atlas = atlasCacheRef.current.get(atlasUrl);
     if (!atlas) return null;
-    const state = animStatesRef.current.get(unitId);
-    const animation = state?.animation ?? "idle";
-    const direction = state?.direction ?? "se";
-    const elapsed = state?.elapsed ?? 0;
+    const animation = unit.animation ?? "idle";
+    const frame = unit.frame ?? 0;
     const def = atlas.animations[animation] ?? atlas.animations.idle;
     if (!def) return null;
-    const { sheetDir, flipX } = resolveSheetDirection(direction);
+    const { sheetDir, flipX } = resolveSheetDirection("se");
     const rel = atlas.sheets[sheetDir] ?? atlas.sheets.se ?? atlas.sheets.sw;
     if (!rel) return null;
     const sheetUrl = resolveSheetUrl(atlasUrl, rel);
-    const isIdle = animation === "idle";
-    const frame = isIdle ? 0 : getCurrentFrameFromDef(def, elapsed).frame;
     const rect = frameRect(frame, def.row, atlas.columns, atlas.frameWidth, atlas.frameHeight);
     return {
       sheetUrl,
@@ -2456,7 +2380,7 @@ function useUnitSpriteAtlas(units) {
       sw: rect.sw,
       sh: rect.sh,
       flipX,
-      applyBreathing: isIdle
+      applyBreathing: animation === "idle"
     };
   }, [units]);
   return { sheetUrls, resolveUnitFrame, pendingCount };
@@ -2552,7 +2476,6 @@ var GameCanvas3D = forwardRef(
     className,
     isLoading: externalLoading,
     error: externalError,
-    entity,
     preloadAssets = [],
     tileClickEvent,
     unitClickEvent,

package/dist/components/game/molecules/useUnitSpriteAtlas.d.ts

@@ -23,8 +23,9 @@ export interface UseUnitSpriteAtlasResult {
     pendingCount: number;
 }
 /**
- * Load per-unit sprite atlases and drive single-frame animation.
+ * Load per-unit sprite atlases and expose a pure frame resolver.
+ * Frame is computed from each unit's own `animation` + `frame` props — no internal clock.
  *
- * @param units - Units to animate. Only units with a `spriteSheet` URL participate.
+ * @param units - Units whose atlases should be loaded.
  */
 export declare function useUnitSpriteAtlas(units: IsometricUnit[]): UseUnitSpriteAtlasResult;

package/dist/components/game/organisms/types/isometric.d.ts

@@ -1,4 +1,5 @@
 import type { AssetUrl } from '@almadar/core';
+import type { AnimationName } from './spriteAnimation';
 /**
  * Isometric Game Types
  *
@@ -7,6 +8,17 @@ import type { AssetUrl } from '@almadar/core';
  *
  * @packageDocumentation
  */
+/** An active visual effect on the board. x,y are grid tile coords; ttl = remaining ticks. */
+export interface ActiveEffect {
+    /** Unique key — matched against assetManifest.effects for sprite lookup */
+    key: string;
+    /** Grid x coordinate */
+    x: number;
+    /** Grid y coordinate */
+    y: number;
+    /** Remaining ticks — used as a fade/scale hint (alpha = min(1, ttl/4)) */
+    ttl: number;
+}
 /** A single isometric tile on the grid */
 export interface IsometricTile {
     /** Optional unique identifier (required for 3D rendering) */
@@ -85,6 +97,10 @@ export type IsometricUnit = {
     };
     /** Elevation offset for 3D rendering */
     elevation?: number;
+    /** Animation name — driven by the LOLO state machine; renderer defaults to 'idle' */
+    animation?: AnimationName;
+    /** Frame index within the animation — driven by the LOLO state machine; renderer defaults to 0 */
+    frame?: number;
 };
 /** A map feature (resource, building, portal, etc.) */
 export type IsometricFeature = {