@almadar/ui 5.79.0 → 5.79.1

package/dist/components/game/3d/templates/GameCanvas3DBattleTemplate.d.ts

@@ -1,82 +0,0 @@
-/**
- * GameCanvas3DBattleTemplate
- *
- * Declarative template for 3D battle/tactical combat.
- * Delegates all interaction state (selectedUnitId, validMoves, attackTargets)
- * to <GameBoard3D> so the model (not this template) owns gameplay state.
- *
- * Page: Battle3DPage
- * Entity: Battle3D / GameBoard3DItem
- * ViewType: detail
- *
- * Events Emitted:
- * - TILE_CLICK - When a tile is clicked
- * - UNIT_CLICK - When a unit is clicked
- * - END_TURN   - When ending turn
- * - EXIT_BATTLE - When exiting battle
- *
- * @packageDocumentation
- */
-import React from 'react';
-import type { IsometricTile, IsometricFeature } from '../../shared/isometricTypes';
-import type { TemplateProps } from '../../../core/templates/types';
-import { type Game3DAssetManifest } from '../../shared/lib/game3dAssetManifest';
-export interface GameCanvas3DBattleTemplateProps extends TemplateProps {
-    /** Fallback tile data when no entity is present (layout only — model URLs resolve from assetManifest) */
-    tiles?: IsometricTile[];
-    /** Fallback feature data when no entity is present */
-    features?: IsometricFeature[];
-    /** GLB model URLs keyed by terrain — owns all asset choice (no hardcoded URLs in this template). */
-    assetManifest?: Game3DAssetManifest;
-    /** 3D camera mode - defaults to perspective for dramatic effect */
-    cameraMode?: 'isometric' | 'perspective' | 'top-down';
-    /** Show grid helper */
-    showGrid?: boolean;
-    /** Enable shadows */
-    shadows?: boolean;
-    /** Background color - darker for battle atmosphere */
-    backgroundColor?: string;
-    /** Event name for tile clicks — forwarded to the model */
-    tileClickEvent?: string;
-    /** Event name for unit clicks — forwarded to the model */
-    unitClickEvent?: string;
-    /** Event name for ending turn */
-    endTurnEvent?: string;
-    /** Event name for cancel/deselect */
-    cancelEvent?: string;
-    /** Event name for attack emission */
-    attackEvent?: string;
-    /** Event name for play again / reset */
-    playAgainEvent?: string;
-    /** Event name for game end detection */
-    gameEndEvent?: string;
-    /** Event name for exiting battle */
-    exitEvent?: string;
-    /** Show turn indicator overlay */
-    showTurnIndicator?: boolean;
-    /** Unit draw-size multiplier forwarded to GameBoard3D. Default 1. */
-    unitScale?: number;
-    /** Board zoom/group scale forwarded to GameBoard3D. Default 0.45. */
-    scale?: number;
-}
-/**
- * GameCanvas3DBattleTemplate Component
- *
- * Template for 3D battle/tactical combat view.
- * Interaction state lives in the entity (model), not in this component.
- *
- * @example
- * ```tsx
- * <GameCanvas3DBattleTemplate
- *     entity={battleEntity}
- *     cameraMode="perspective"
- *     tileClickEvent="TILE_CLICK"
- *     unitClickEvent="UNIT_CLICK"
- * />
- * ```
- */
-export declare function GameCanvas3DBattleTemplate({ entity, tiles: propTiles, features: propFeatures, assetManifest, cameraMode, backgroundColor, tileClickEvent, unitClickEvent, endTurnEvent, cancelEvent, attackEvent, playAgainEvent, gameEndEvent, unitScale, scale, className, }: GameCanvas3DBattleTemplateProps): React.JSX.Element | null;
-export declare namespace GameCanvas3DBattleTemplate {
-    var displayName: string;
-}
-export default GameCanvas3DBattleTemplate;

package/dist/components/game/3d/templates/GameCanvas3DCastleTemplate.d.ts

@@ -1,87 +0,0 @@
-/**
- * GameCanvas3DCastleTemplate
- *
- * Declarative template for 3D castle/settlement view.
- * Delegates interaction state (selectedUnitId, validMoves, attackTargets)
- * to <GameBoard3D> so the model owns all gameplay state.
- *
- * Page: Castle3DPage, Settlement3DPage
- * Entity: Castle3D / GameBoard3DItem
- * ViewType: detail
- *
- * Events Emitted:
- * - BUILDING_SELECTED - When a building is clicked
- * - UNIT_SELECTED     - When a garrison unit is clicked
- * - BUILD             - When building/upgrading
- * - RECRUIT           - When recruiting units
- * - EXIT              - When exiting castle view
- *
- * @packageDocumentation
- */
-import React from 'react';
-import type { IsometricTile, IsometricFeature } from '../../shared/isometricTypes';
-import type { TemplateProps } from '../../../core/templates/types';
-import { type Game3DAssetManifest } from '../../shared/lib/game3dAssetManifest';
-export interface GameCanvas3DCastleTemplateProps extends TemplateProps {
-    /** Fallback tile data when no entity is present (layout only — model URLs resolve from assetManifest) */
-    tiles?: IsometricTile[];
-    /** Fallback feature data when no entity is present */
-    features?: IsometricFeature[];
-    /** GLB model URLs keyed by terrain — owns all asset choice (no hardcoded URLs in this template). */
-    assetManifest?: Game3DAssetManifest;
-    /** 3D camera mode */
-    cameraMode?: 'isometric' | 'perspective' | 'top-down';
-    /** Show grid helper */
-    showGrid?: boolean;
-    /** Enable shadows */
-    shadows?: boolean;
-    /** Background color */
-    backgroundColor?: string;
-    /** Event name for building (feature) clicks */
-    buildingClickEvent?: string;
-    /** Event name for unit clicks */
-    unitClickEvent?: string;
-    /** Event name for ending turn */
-    endTurnEvent?: string;
-    /** Event name for cancel/deselect */
-    cancelEvent?: string;
-    /** Event name for attack emission */
-    attackEvent?: string;
-    /** Event name for play again / reset */
-    playAgainEvent?: string;
-    /** Event name for game end detection */
-    gameEndEvent?: string;
-    /** Event name for build action */
-    buildEvent?: string;
-    /** Event name for recruit action */
-    recruitEvent?: string;
-    /** Event name for exit */
-    exitEvent?: string;
-    /** Show castle name header */
-    showHeader?: boolean;
-    /** Unit draw-size multiplier forwarded to GameBoard3D. Default 1. */
-    unitScale?: number;
-    /** Board zoom/group scale forwarded to GameBoard3D. Default 0.45. */
-    scale?: number;
-}
-/**
- * GameCanvas3DCastleTemplate Component
- *
- * Template for 3D castle/settlement management view.
- * Interaction state lives in the entity (model), not in this component.
- *
- * @example
- * ```tsx
- * <GameCanvas3DCastleTemplate
- *     entity={castleEntity}
- *     cameraMode="isometric"
- *     showHeader={true}
- *     buildingClickEvent="UNIT_CLICK"
- * />
- * ```
- */
-export declare function GameCanvas3DCastleTemplate({ entity, tiles: propTiles, features: propFeatures, assetManifest, cameraMode, backgroundColor, buildingClickEvent, unitClickEvent, endTurnEvent, cancelEvent, attackEvent, playAgainEvent, gameEndEvent, showHeader, unitScale, scale, className, }: GameCanvas3DCastleTemplateProps): React.JSX.Element | null;
-export declare namespace GameCanvas3DCastleTemplate {
-    var displayName: string;
-}
-export default GameCanvas3DCastleTemplate;

package/dist/components/game/3d/templates/GameCanvas3DWorldMapTemplate.d.ts

@@ -1,95 +0,0 @@
-/**
- * GameCanvas3DWorldMapTemplate
- *
- * Declarative template for 3D world map.
- * Delegates interaction state (selectedUnitId, validMoves, attackTargets)
- * to <GameBoard3D> so the model owns all gameplay state.
- *
- * Page: WorldMap3DPage
- * Entity: WorldMap3D / GameBoard3DItem
- * ViewType: detail
- *
- * Events Emitted:
- * - TILE_CLICK    - When a tile is clicked ({ tileId, x, z, type })
- * - UNIT_CLICK    - When a unit is clicked ({ unitId, x, z, name })
- * - FEATURE_CLICK - When a feature is clicked ({ featureId, x, z, type })
- * - TILE_HOVER    - When hovering over a tile ({ tileId, x, z })
- * - TILE_LEAVE    - When leaving a tile ({})
- * - CAMERA_CHANGE - When camera position changes ({ position })
- *
- * @packageDocumentation
- */
-import React from 'react';
-import type { IsometricTile, IsometricFeature } from '../../shared/isometricTypes';
-import type { TemplateProps } from '../../../core/templates/types';
-import { type Game3DAssetManifest } from '../../shared/lib/game3dAssetManifest';
-export interface GameCanvas3DWorldMapTemplateProps extends TemplateProps {
-    /** Fallback tile data when no entity is present (layout only — model URLs resolve from assetManifest) */
-    tiles?: IsometricTile[];
-    /** Fallback feature data when no entity is present */
-    features?: IsometricFeature[];
-    /** GLB model URLs keyed by terrain — owns all asset choice (no hardcoded URLs in this template). */
-    assetManifest?: Game3DAssetManifest;
-    /** 3D camera mode */
-    cameraMode?: 'isometric' | 'perspective' | 'top-down';
-    /** Show grid helper */
-    showGrid?: boolean;
-    /** Show coordinate overlay */
-    showCoordinates?: boolean;
-    /** Show tile info on hover */
-    showTileInfo?: boolean;
-    /** Enable shadows */
-    shadows?: boolean;
-    /** Background color */
-    backgroundColor?: string;
-    /** Event name for tile clicks — forwarded to the model */
-    tileClickEvent?: string;
-    /** Event name for unit clicks — forwarded to the model */
-    unitClickEvent?: string;
-    /** Event name for ending turn */
-    endTurnEvent?: string;
-    /** Event name for cancel/deselect */
-    cancelEvent?: string;
-    /** Event name for attack emission */
-    attackEvent?: string;
-    /** Event name for play again / reset */
-    playAgainEvent?: string;
-    /** Event name for game end detection */
-    gameEndEvent?: string;
-    /** Event name for feature clicks */
-    featureClickEvent?: string;
-    /** Event name for tile hover */
-    tileHoverEvent?: string;
-    /** Event name for tile leave */
-    tileLeaveEvent?: string;
-    /** Event name for camera changes */
-    cameraChangeEvent?: string;
-    /** Exit/back event name */
-    exitEvent?: string;
-    /** Unit draw-size multiplier forwarded to GameBoard3D. Default 1. */
-    unitScale?: number;
-    /** Board zoom/group scale forwarded to GameBoard3D. Default 0.45. */
-    scale?: number;
-}
-/**
- * GameCanvas3DWorldMapTemplate Component
- *
- * Template for 3D world map view.
- * Interaction state lives in the entity (model), not in this component.
- *
- * @example
- * ```tsx
- * <GameCanvas3DWorldMapTemplate
- *     entity={worldMapEntity}
- *     cameraMode="isometric"
- *     tileClickEvent="TILE_CLICK"
- *     unitClickEvent="UNIT_CLICK"
- *     showCoordinates={true}
- * />
- * ```
- */
-export declare function GameCanvas3DWorldMapTemplate({ entity, tiles: propTiles, features: propFeatures, assetManifest, cameraMode, backgroundColor, tileClickEvent, unitClickEvent, endTurnEvent, cancelEvent, attackEvent, playAgainEvent, gameEndEvent, unitScale, scale, className, }: GameCanvas3DWorldMapTemplateProps): React.JSX.Element | null;
-export declare namespace GameCanvas3DWorldMapTemplate {
-    var displayName: string;
-}
-export default GameCanvas3DWorldMapTemplate;

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

@@ -1,44 +0,0 @@
-/**
- * boardEntity — tiny coercion helpers for reading `EntityRow` data inside game
- * boards.
- *
- * The single entity type is `@almadar/core`'s `EntityRow`
- * (`{ id?: string } & Record<string, FieldValue | undefined>`). Boards read
- * deeply-nested, weakly-typed fields off it; these helpers narrow scalars,
- * arrays, and small positional objects without reintroducing private entity
- * interfaces. None of these are entity types — they are pure value coercers.
- *
- * @packageDocumentation
- */
-import type { EntityRow, FieldValue } from '@almadar/core';
-/** A 2D grid position read off an entity row. */
-export interface Vec2 {
-    x: number;
-    y: number;
-}
-/** Lightweight trait-display shape carried on unit-like rows (UI value DTO). */
-export interface TeamUnitTraits {
-    name: string;
-    currentState: string;
-    states: string[];
-    cooldown?: number;
-}
-/** Resolve the single board-state entity row from a prop that may be a row,
- *  an array of rows, or undefined. Boards operate on one board state. */
-export declare function boardEntity(entity: EntityRow | readonly EntityRow[] | undefined): EntityRow | undefined;
-/** Coerce a field value to a string (empty string when absent). */
-export declare function str(v: FieldValue | undefined): string;
-/** Coerce a field value to a number (0 when absent / non-numeric). */
-export declare function num(v: FieldValue | undefined, fallback?: number): number;
-/** Coerce a field value to a boolean. */
-export declare function bool(v: FieldValue | undefined): boolean;
-/** Coerce a nested array field to a readonly array of entity rows. */
-export declare function rows(v: FieldValue | undefined): readonly EntityRow[];
-/** Read an `{ x, y }` position off an entity row's named field. */
-export declare function vec2(v: FieldValue | undefined): Vec2;
-/** Read a unit row's `position` as a `Vec2`. */
-export declare function unitPosition(u: EntityRow): Vec2;
-/** Read a unit row's `team` ('player' | 'enemy' | string). */
-export declare function unitTeam(u: EntityRow): string;
-/** Read a unit row's `health`. */
-export declare function unitHealth(u: EntityRow): number;

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

@@ -1,50 +0,0 @@
-/**
- * Canvas Effect Engine
- *
- * Pure functions for spawning, updating, and drawing canvas effects.
- * No React dependencies — called from the RAF loop via useCanvasEffects hook.
- *
- * Ported from trait-wars and generalized for any almadar-ui client.
- */
-import type { CanvasParticle, CanvasSequence, CanvasOverlay, CanvasEffectState, ParticleEmitterConfig, SequenceConfig, OverlayConfig } from './effects';
-/**
- * Draw a sprite tinted with an RGB color onto the main canvas.
- * Uses offscreen canvas with `source-atop` compositing to recolor
- * white-on-transparent sprites.
- */
-export declare function drawTintedImage(ctx: CanvasRenderingContext2D, img: HTMLImageElement | ImageBitmap, x: number, y: number, w: number, h: number, tint: {
-    r: number;
-    g: number;
-    b: number;
-}, alpha: number, blendMode?: GlobalCompositeOperation): void;
-/**
- * Spawn a burst of particles from an emitter config.
- */
-export declare function spawnParticles(config: ParticleEmitterConfig, animTime: number): CanvasParticle[];
-/**
- * Spawn a frame sequence animation.
- */
-export declare function spawnSequence(config: SequenceConfig, animTime: number): CanvasSequence;
-/**
- * Spawn an overlay effect.
- */
-export declare function spawnOverlay(config: OverlayConfig, animTime: number): CanvasOverlay;
-/**
- * Advance effect state by one frame. Returns new state with expired effects removed.
- */
-export declare function updateEffectState(state: CanvasEffectState, animTime: number, deltaMs: number): CanvasEffectState;
-type GetImageFn = (url: string) => HTMLImageElement | undefined;
-/**
- * Draw all active effects onto the canvas.
- */
-export declare function drawEffectState(ctx: CanvasRenderingContext2D, state: CanvasEffectState, animTime: number, getImage: GetImageFn): void;
-export declare function hasActiveEffects(state: CanvasEffectState): boolean;
-/**
- * Collect all sprite URLs from an EffectAssetManifest for preloading.
- */
-export declare function getAllEffectSpriteUrls(manifest: {
-    baseUrl: string;
-    particles?: Record<string, string[] | string | undefined>;
-    animations?: Record<string, string[] | undefined>;
-}): string[];
-export {};

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

@@ -1,15 +0,0 @@
-/**
- * Combat Presets
- *
- * Maps combat actions to composed effect layers (particles + sequences + overlays).
- * Each preset factory takes a screen-space origin and returns a CombatPreset.
- *
- * Generalized from trait-wars: uses EffectAssetManifest instead of TraitWarsAssetManifest.
- */
-import type { CombatActionType, CombatPreset, EffectAssetManifest } from './effects';
-type PresetFactory = (originX: number, originY: number) => CombatPreset;
-/**
- * Create combat preset factories from an effect asset manifest.
- */
-export declare function createCombatPresets(manifest: EffectAssetManifest): Record<CombatActionType, PresetFactory>;
-export {};

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

@@ -1,253 +0,0 @@
-/**
- * Canvas Effect Types
- *
- * Type definitions for the canvas-based particle, sequence, and overlay
- * effect system. Used by canvasEffects engine and combat presets.
- *
- * Ported from trait-wars and generalized for any almadar-ui client.
- */
-/**
- * A single particle in flight — rendered as a tinted sprite each frame.
- */
-export interface CanvasParticle {
-    /** Sprite URL (white-on-transparent particle) */
-    spriteUrl: string;
-    /** Current position in screen pixels */
-    x: number;
-    y: number;
-    /** Velocity in pixels per second */
-    vx: number;
-    vy: number;
-    /** Downward acceleration in px/s² (positive = down) */
-    gravity: number;
-    /** Current rotation in radians */
-    rotation: number;
-    /** Rotation speed in radians per second */
-    rotationSpeed: number;
-    /** Current scale (1.0 = original size) */
-    scale: number;
-    /** Scale change per second (negative = shrink) */
-    scaleSpeed: number;
-    /** Current alpha (0-1) */
-    alpha: number;
-    /** Alpha change per second (negative = fade out) */
-    fadeRate: number;
-    /** RGB tint color (applied via offscreen canvas compositing) */
-    tint: {
-        r: number;
-        g: number;
-        b: number;
-    };
-    /** Canvas blend mode */
-    blendMode: GlobalCompositeOperation;
-    /** Time this particle was spawned (ms) */
-    spawnTime: number;
-    /** Maximum lifetime in ms (particle removed after) */
-    lifetime: number;
-}
-/**
- * Configuration for spawning a burst of particles.
- */
-export interface ParticleEmitterConfig {
-    /** Array of sprite URLs to randomly pick from */
-    spriteUrls: string[];
-    /** Number of particles to spawn */
-    count: number;
-    /** Spawn origin in screen pixels */
-    originX: number;
-    originY: number;
-    /** Random spread radius from origin (px) */
-    spread: number;
-    /** Velocity range (px/s) */
-    velocityMin: number;
-    velocityMax: number;
-    /** Emission angle range (radians, 0 = right, PI/2 = down) */
-    angleMin: number;
-    angleMax: number;
-    /** Gravity (px/s²) */
-    gravity: number;
-    /** RGB tint */
-    tint: {
-        r: number;
-        g: number;
-        b: number;
-    };
-    /** Scale range */
-    scaleMin: number;
-    scaleMax: number;
-    /** Scale speed (per second) */
-    scaleSpeed?: number;
-    /** Particle lifetime range (ms) */
-    lifetimeMin: number;
-    lifetimeMax: number;
-    /** Fade rate (alpha per second, negative = fade out) */
-    fadeRate?: number;
-    /** Starting alpha */
-    alpha?: number;
-    /** Canvas blend mode */
-    blendMode?: GlobalCompositeOperation;
-    /** Rotation speed range (radians/s) */
-    rotationSpeedMin?: number;
-    rotationSpeedMax?: number;
-}
-/**
- * A frame-sequence animation (e.g., explosion, smoke puff).
- */
-export interface CanvasSequence {
-    /** Ordered array of frame sprite URLs */
-    frameUrls: string[];
-    /** Position in screen pixels (top-left of sprite) */
-    x: number;
-    y: number;
-    /** Duration per frame in ms */
-    frameDuration: number;
-    /** Time this sequence started (ms) */
-    startTime: number;
-    /** Whether to loop the animation */
-    loop: boolean;
-    /** Render scale */
-    scale: number;
-    /** RGB tint (null = no tinting) */
-    tint: {
-        r: number;
-        g: number;
-        b: number;
-    } | null;
-    /** Alpha (0-1) */
-    alpha: number;
-    /** Canvas blend mode */
-    blendMode: GlobalCompositeOperation;
-}
-/**
- * Configuration for spawning a frame sequence.
- */
-export interface SequenceConfig {
-    frameUrls: string[];
-    originX: number;
-    originY: number;
-    frameDuration: number;
-    loop?: boolean;
-    scale?: number;
-    tint?: {
-        r: number;
-        g: number;
-        b: number;
-    } | null;
-    alpha?: number;
-    blendMode?: GlobalCompositeOperation;
-}
-/**
- * A static/fading overlay image (e.g., ground scorch mark, shield circle).
- */
-export interface CanvasOverlay {
-    /** Sprite URL */
-    spriteUrl: string;
-    /** Center position in screen pixels */
-    x: number;
-    y: number;
-    /** Current alpha (0-1) */
-    alpha: number;
-    /** Alpha change per second (negative = fade out) */
-    fadeRate: number;
-    /** Pulse amplitude (0 = no pulse, 0.3 = alpha oscillates ±0.3) */
-    pulseAmplitude: number;
-    /** Pulse frequency in Hz */
-    pulseFrequency: number;
-    /** Render scale */
-    scale: number;
-    /** Canvas blend mode */
-    blendMode: GlobalCompositeOperation;
-    /** Time this overlay was spawned (ms) */
-    spawnTime: number;
-    /** Maximum lifetime in ms */
-    lifetime: number;
-}
-/**
- * Configuration for spawning an overlay.
- */
-export interface OverlayConfig {
-    spriteUrl: string;
-    originX: number;
-    originY: number;
-    alpha?: number;
-    fadeRate?: number;
-    pulseAmplitude?: number;
-    pulseFrequency?: number;
-    scale?: number;
-    blendMode?: GlobalCompositeOperation;
-    lifetime?: number;
-}
-/**
- * Full state of all active effects on the canvas.
- */
-export interface CanvasEffectState {
-    particles: CanvasParticle[];
-    sequences: CanvasSequence[];
-    overlays: CanvasOverlay[];
-}
-/**
- * Combat action types that map to effect compositions.
- * Superset of trait-wars types + almadar-ui originals.
- */
-export type CombatActionType = 'melee' | 'ranged' | 'magic' | 'heal' | 'defend' | 'hit' | 'death' | 'buff' | 'debuff' | 'shield' | 'aoe' | 'critical';
-/**
- * A combat preset composes multiple effect layers.
- */
-export interface CombatPreset {
-    /** Particle emitter configs to spawn */
-    particles: ParticleEmitterConfig[];
-    /** Sequence configs to spawn */
-    sequences: SequenceConfig[];
-    /** Overlay configs to spawn */
-    overlays: OverlayConfig[];
-    /** Screen shake intensity in pixels (0 = none) */
-    screenShake: number;
-    /** Screen flash color and duration */
-    screenFlash: {
-        r: number;
-        g: number;
-        b: number;
-        duration: number;
-    } | null;
-}
-/**
- * Effect asset manifest — the sprites and animation frames available for
- * the particle engine. This is the `assetManifest.effects` section.
- */
-export interface EffectAssetManifest {
-    /** Base URL for all asset paths */
-    baseUrl: string;
-    /** Particle sprite groups (white-on-transparent, tinted at runtime) */
-    particles?: {
-        slash?: string[];
-        magic?: string[];
-        fire?: string[];
-        flame?: string[];
-        smoke?: string[];
-        scorch?: string[];
-        circle?: string[];
-        flare?: string;
-        spark?: string[];
-        muzzle?: string[];
-        star?: string[];
-        trace?: string[];
-        twirl?: string[];
-        light?: string[];
-        dirt?: string[];
-        scratch?: string[];
-        symbol?: string[];
-    };
-    /** Frame-sequence animations (array of frame image paths) */
-    animations?: {
-        explosion?: string[];
-        smokePuff?: string[];
-        flash?: string[];
-        blackSmoke?: string[];
-        gasSmoke?: string[];
-        smokeExplosion?: string[];
-    };
-}
-/**
- * Empty effect state constant.
- */
-export declare const EMPTY_EFFECT_STATE: CanvasEffectState;