@almadar/ui 5.70.0 → 5.72.0

package/dist/components/core/organisms/CustomPattern.d.ts

@@ -8,7 +8,7 @@
  * @packageDocumentation
  */
 import React from "react";
-import type { AssetUrl, EventKey, EventPayload } from "@almadar/core";
+import type { AssetUrl, EventKey, EventPayload, JsonValue } from "@almadar/core";
 import type { UiError } from "../atoms/types";
 /**
  * Allowed element types for custom patterns.
@@ -49,7 +49,7 @@ export interface CustomPatternProps {
     /** Disabled state */
     disabled?: boolean;
     /** Additional HTML attributes */
-    htmlProps?: Record<string, unknown>;
+    htmlProps?: React.HTMLAttributes<HTMLElement>;
     /** Loading state */
     isLoading?: boolean;
     /** Error state */
@@ -91,12 +91,11 @@ export interface CustomPatternConfig {
     href?: string;
     external?: boolean;
     disabled?: boolean;
-    [key: string]: unknown;
 }
 /**
  * Check if a pattern config is a custom pattern.
  */
-export declare function isCustomPatternConfig(config: unknown): config is CustomPatternConfig;
+export declare function isCustomPatternConfig(config: JsonValue | CustomPatternConfig): config is CustomPatternConfig;
 /**
  * Recursively render custom pattern configurations.
  *

package/dist/components/core/organisms/DataTable.d.ts

@@ -2,7 +2,7 @@ import React from "react";
 import type { EventKey } from "@almadar/core";
 import type { IconInput } from "../atoms/Icon";
 import { DisplayStateProps } from "./types";
-import type { EntityRow } from "@almadar/core";
+import type { EntityRow, FieldValue } from "@almadar/core";
 export type EntityTableLook = "dense" | "spacious" | "striped" | "borderless" | "card-rows";
 export interface Column<T> {
     key: keyof T | string;
@@ -13,7 +13,7 @@ export interface Column<T> {
     label?: string;
     width?: string;
     sortable?: boolean;
-    render?: (value: unknown, row: T, index: number) => React.ReactNode;
+    render?: (value: FieldValue | undefined, row: T, index: number) => React.ReactNode;
 }
 export interface RowAction<T> {
     label: string;

package/dist/components/core/organisms/DetailPanel.d.ts

@@ -65,7 +65,7 @@ export interface DetailPanelProps extends DisplayStateProps {
     /** Alias for fields - backwards compatibility */
     fieldNames?: readonly string[];
     /** Initial data for edit mode (passed by compiler) */
-    initialData?: Record<string, unknown> | unknown;
+    initialData?: EntityRow;
     /** Display mode (passed by compiler) */
     mode?: string;
     /** Panel position (for drawer/sidebar placement) */

package/dist/components/core/organisms/Form.d.ts

@@ -12,7 +12,7 @@
  * - Nested sections with collapsible support
  */
 import React from "react";
-import type { EventKey, FieldValue } from "@almadar/core";
+import type { EntityRow, EventKey, FieldValue, JsonObject } from "@almadar/core";
 import { type SelectOption } from "../atoms/Select";
 import { type RelationOption } from "../molecules/RelationSelect";
 import type { OrbitalEntity } from "@almadar/core";
@@ -27,10 +27,10 @@ export type SExpression = SExpr;
  * Form-specific evaluation context
  */
 export interface FormEvaluationContext {
-    formValues: Record<string, unknown>;
-    globalVariables: Record<string, unknown>;
-    localVariables?: Record<string, unknown>;
-    entity?: Record<string, unknown>;
+    formValues: EntityRow;
+    globalVariables: Record<string, FieldValue>;
+    localVariables?: Record<string, FieldValue>;
+    entity?: EntityRow;
 }
 /**
  * Hidden calculation definition
@@ -117,7 +117,7 @@ export interface SchemaField {
     /** Whether field is required */
     required?: boolean;
     /** Default value */
-    defaultValue?: unknown;
+    defaultValue?: FieldValue;
     /** Options for select/enum fields - accepts readonly for generated const arrays */
     options?: readonly SelectOption[];
     /** Enum values (alternative to options, just strings) - accepts readonly for generated const arrays */
@@ -131,7 +131,7 @@ export interface SchemaField {
     /** Pattern for validation */
     pattern?: string;
     /** Validation rules */
-    validation?: Record<string, unknown>;
+    validation?: JsonObject;
     /** Whether field is readonly (displays value but cannot edit) */
     readonly?: boolean;
     /** Whether field is disabled (alternative to readonly for compatibility) */
@@ -156,7 +156,7 @@ export interface FormProps extends Omit<React.FormHTMLAttributes<HTMLFormElement
     /** Additional CSS classes */
     className?: string;
     /** Entity type name or schema object. When OrbitalEntity, fields are auto-derived if not provided. */
-    entity?: string | OrbitalEntity | readonly Record<string, unknown>[];
+    entity?: string | OrbitalEntity | EntityRow | readonly EntityRow[];
     /**
      * Form mode — 'create' for new records, 'edit' for updating existing.
      * Accepts `string` so schema-driven callers (whose `config.mode` is typed
@@ -167,7 +167,7 @@ export interface FormProps extends Omit<React.FormHTMLAttributes<HTMLFormElement
     /** Fields definition (schema format) - accepts readonly for generated const arrays */
     fields: readonly Readonly<SchemaField>[];
     /** Initial form data */
-    initialData?: Record<string, unknown> | unknown;
+    initialData?: EntityRow;
     /** Loading state */
     isLoading?: boolean;
     /** Error state */
@@ -196,8 +196,8 @@ export interface FormProps extends Omit<React.FormHTMLAttributes<HTMLFormElement
     hiddenCalculations?: HiddenCalculation[] | boolean;
     /** Violation conditions that emit VIOLATION_DETECTED when met (boolean true means enabled but config loaded separately) */
     violationTriggers?: ViolationTrigger[] | boolean;
-    /** Context for S-expression evaluation - accepts flexible types from generated code */
-    evaluationContext?: FormEvaluationContext | Record<string, unknown>;
+    /** Context for S-expression evaluation */
+    evaluationContext?: FormEvaluationContext;
     /** Nested form sections with optional conditions */
     sections?: FormSection[];
     /** Callback when any field value changes */

package/dist/components/core/organisms/List.d.ts

@@ -17,11 +17,10 @@
  * - No internal search/filter state — trait provides filtered data
  */
 import React from "react";
-import type { AssetUrl, EventKey } from "@almadar/core";
+import type { AssetUrl, EventKey, FieldValue, EntityRow } from "@almadar/core";
 import type { IconInput } from "../atoms/Icon";
 import { type MenuItem } from "../molecules/Menu";
 import type { DisplayStateProps } from "./types";
-import type { EntityRow } from "@almadar/core";
 export type ListItem = {
     id: string;
     title?: string;
@@ -37,8 +36,7 @@ export type ListItem = {
     onClick?: () => void;
     disabled?: boolean;
     completed?: boolean;
-    [key: string]: unknown;
-    _fields?: Record<string, unknown>;
+    _fields?: Record<string, FieldValue | undefined>;
 };
 export interface SchemaItemAction {
     label: string;
@@ -51,7 +49,7 @@ export interface SchemaItemAction {
     action?: EventKey;
     variant?: "primary" | "secondary" | "ghost" | "danger" | "default";
     /** Click handler from generated code */
-    onClick?: (row: unknown) => void;
+    onClick?: (row: EntityRow) => void;
 }
 /**
  * Field definition - can be a simple string or object with key/header or name/label

package/dist/components/core/organisms/StatCard.d.ts

@@ -25,8 +25,8 @@ export interface StatCardProps extends DisplayStateProps {
     label?: string;
     /** Title (alias for label) */
     title?: string;
-    /** Primary value - accepts array/unknown from generated code (will use first element or length) */
-    value?: string | number | (string | number | undefined)[] | unknown;
+    /** Primary value - accepts array from generated code (will use first element or length) */
+    value?: string | number | (string | number | undefined)[];
     /** Previous value for comparison */
     previousValue?: number;
     /** Current value as number for trend calculation */

package/dist/components/core/organisms/book/types.d.ts

@@ -59,4 +59,4 @@ export declare function resolveFieldMap(fieldMap: BookFieldMap | string | undefi
  * chapter data come back as `EntityRow`s; the per-chapter `OrbitalSchema` is
  * lifted off into `schemaByChapterId`.
  */
-export declare function mapBookData(raw: Record<string, unknown>, fields?: BookFieldMap): NormalizedBook;
+export declare function mapBookData(raw: EntityRow, fields?: BookFieldMap): NormalizedBook;

package/dist/components/core/organisms/debug/RuntimeDebugger.d.ts

@@ -1,3 +1,4 @@
+import type { OrbitalSchema } from '@almadar/core';
 import './RuntimeDebugger.css';
 export interface RuntimeDebuggerProps {
     /** Initial position */
@@ -11,7 +12,7 @@ export interface RuntimeDebuggerProps {
     /** Default active tab id */
     defaultTab?: string;
     /** Raw schema for EventDispatcherTab payload extraction */
-    schema?: Record<string, unknown>;
+    schema?: OrbitalSchema;
 }
 export declare function RuntimeDebugger({ position, defaultCollapsed, className, mode, defaultTab, schema, }: RuntimeDebuggerProps): import("react/jsx-runtime").JSX.Element | null;
 export declare namespace RuntimeDebugger {

package/dist/components/core/organisms/debug/tabs/EventDispatcherTab.d.ts

@@ -4,10 +4,11 @@
  * Shows available transitions per trait based on current state,
  * lets users click to fire events, and displays a compact transition log.
  */
+import type { OrbitalSchema } from '@almadar/core';
 import type { TraitDebugInfo } from '../../../../../lib/traitRegistry';
 interface EventDispatcherTabProps {
     traits: TraitDebugInfo[];
-    schema?: Record<string, unknown>;
+    schema?: OrbitalSchema;
 }
 export declare function EventDispatcherTab({ traits, schema }: EventDispatcherTabProps): import("react/jsx-runtime").JSX.Element;
 export declare namespace EventDispatcherTab {

package/dist/components/core/organisms/layout/DashboardGrid.d.ts

@@ -17,8 +17,6 @@ export interface DashboardGridCell {
     colSpan?: 1 | 2 | 3 | 4;
     /** Number of rows this cell spans (1-2) */
     rowSpan?: 1 | 2;
-    /** Allow additional schema-driven properties */
-    [key: string]: unknown;
 }
 export interface DashboardGridProps extends DisplayStateProps {
     /** Number of columns */

package/dist/components/core/organisms/types.d.ts

@@ -7,6 +7,7 @@
  * Exception: Form manages local `formData` state for field input tracking.
  * This is the ONE allowed exception — documented here.
  */
+import type { FieldValue } from '@almadar/core';
 import type { UiError } from '../atoms/types';
 export type { UiError };
 export declare const EntityDisplayEvents: {
@@ -32,7 +33,7 @@ export interface SearchPayload {
 export interface FilterPayload {
     field: string;
     operator: string;
-    value: unknown;
+    value: FieldValue;
 }
 export interface SelectPayload {
     ids: (string | number)[];
@@ -65,7 +66,7 @@ export interface DisplayStateProps {
     /** Total number of items (for pagination display) */
     totalCount?: number;
     /** Active filters */
-    activeFilters?: Record<string, unknown>;
+    activeFilters?: Record<string, FieldValue>;
     /** Currently selected item IDs */
     selectedIds?: readonly (string | number)[];
 }

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

@@ -5,6 +5,8 @@ export interface ScoreDisplayProps {
     assetUrl?: AssetUrl;
     /** Current score value */
     value: number;
+    /** Alias for value — common schema binding name */
+    score?: number;
     /** Label to display before score */
     label?: string;
     /** Icon component or emoji */
@@ -13,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, label, icon, size, className, animated, locale, ...rest }: ScoreDisplayProps & Record<string, unknown>): 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/hooks/useSceneGraph.d.ts

@@ -1,4 +1,5 @@
 import * as THREE from 'three';
+import type { JsonObject } from '@almadar/core';
 export type NodeType = 'tile' | 'unit' | 'feature' | 'highlight' | 'effect';
 export interface SceneGraphNode {
     /** Unique node identifier */
@@ -19,7 +20,7 @@ export interface SceneGraphNode {
         z: number;
     };
     /** Optional metadata */
-    metadata?: Record<string, unknown>;
+    metadata?: JsonObject;
 }
 export interface UseSceneGraphReturn {
     /** Reference to the nodes map */