@almadar/ui 5.110.0 → 5.112.0

package/dist/avl-schema-parser-DKRm-nyh.d.ts

@@ -0,0 +1,611 @@
+import { AnimationName, Asset, ScenePos, JsonObject, JsonValue } from '@almadar/core';
+
+/**
+ * Sprite Sheet Animation Types
+ *
+ * Type definitions for frame-based sprite sheet animation system.
+ * Supports standard 8-column × 5-row character sheets.
+ *
+ * `AnimationName`, `AnimationDef`, and `SpriteDirection` are canonically owned
+ * by `@almadar/core` (they travel with a `spriteSheet`-role `Asset.url`'s
+ * resolved atlas contract) — re-exported here so existing call sites in this
+ * package don't need to change their import path.
+ *
+ * @packageDocumentation
+ */
+
+/** Unit facing direction on screen (4 isometric directions) */
+type FacingDirection = 'se' | 'sw' | 'ne' | 'nw';
+/** A resolved frame ready to draw on canvas */
+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 */
+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 */
+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 */
+interface SpriteSheetUrls {
+    /** Southeast-facing sheet URL */
+    se: string;
+    /** Southwest-facing sheet URL */
+    sw: string;
+}
+
+/**
+ * Game Types — Generalized
+ *
+ * Core type definitions for tactical game state.
+ * Extracted from Trait Wars and generalized for any game project.
+ */
+interface Position {
+    x: number;
+    y: number;
+}
+interface GameUnit {
+    id: string;
+    name: string;
+    characterType: string;
+    team: 'player' | 'enemy' | 'neutral';
+    position: Position;
+    health: number;
+    maxHealth: number;
+    movement: number;
+    attack: number;
+    defense: number;
+    traits: UnitTrait[];
+}
+interface UnitTrait {
+    name: string;
+    currentState: string;
+    states: string[];
+    cooldown: number;
+}
+interface BoardTile {
+    terrain: string;
+    unitId?: string;
+    isBlocked?: boolean;
+}
+type GamePhase = 'observation' | 'planning' | 'execution' | 'tick';
+interface GameState {
+    board: BoardTile[][];
+    units: Record<string, GameUnit>;
+    currentPhase: GamePhase;
+    currentTurn: number;
+    activeTeam: 'player' | 'enemy' | 'neutral';
+    selectedUnitId?: string;
+    validMoves: Position[];
+    attackTargets: Position[];
+}
+type GameAction = {
+    type: 'SELECT_UNIT';
+    unitId: string;
+} | {
+    type: 'MOVE_UNIT';
+    from: Position;
+    to: Position;
+} | {
+    type: 'ATTACK';
+    attackerId: string;
+    targetId: string;
+} | {
+    type: 'END_TURN';
+} | {
+    type: 'EXECUTE_TRAITS';
+};
+/**
+ * Create the initial game state with board and units.
+ *
+ * @param {number} width - Board width in tiles
+ * @param {number} height - Board height in tiles
+ * @param {GameUnit[]} units - Initial units to place on the board
+ * @param {string} [defaultTerrain] - Default terrain type for empty tiles
+ * @returns {GameState} The initialized game state
+ */
+declare function createInitialGameState(width: number, height: number, units: GameUnit[], defaultTerrain?: string): GameState;
+/**
+ * Calculate valid movement positions for a unit.
+ *
+ * Returns all tiles within the unit's movement range that are
+ * not blocked and don't contain other units.
+ *
+ * @param {GameState} state - Current game state
+ * @param {string} unitId - ID of the unit to calculate moves for
+ * @returns {Position[]} Array of valid move positions
+ */
+declare function calculateValidMoves(state: GameState, unitId: string): Position[];
+/**
+ * Calculate valid attack targets for a unit.
+ *
+ * Returns adjacent positions containing enemy units that can be attacked.
+ *
+ * @param {GameState} state - Current game state
+ * @param {string} unitId - ID of the unit to calculate targets for
+ * @returns {Position[]} Array of valid attack target positions
+ */
+declare function calculateAttackTargets(state: GameState, unitId: string): Position[];
+
+/** A single isometric tile on the grid */
+interface IsometricTile {
+    /** Optional unique identifier (required for 3D rendering) */
+    id?: string;
+    /** Grid x coordinate */
+    x: number;
+    /** Grid y coordinate (2D) */
+    y: number;
+    /** Grid z coordinate (3D alternative to y) */
+    z?: number;
+    /** Terrain type key (e.g., 'grass', 'stone', 'water') - 2D */
+    terrain?: string;
+    /** Tile type for visual rendering (3D) */
+    type?: string;
+    /** Direct sprite URL override (bypasses getTerrainSprite resolver) */
+    terrainSprite?: Asset;
+    /** Fallback/override fill color (2D + 3D) — bypasses the terrain color map. `.lolo`-computed. */
+    color?: string;
+    /** Whether units can traverse this tile (default true) */
+    passable?: boolean;
+    /** Movement cost for pathfinding (default 1) */
+    movementCost?: number;
+    /** Optional tile type for visual variants */
+    tileType?: string;
+    /** Elevation offset for 3D rendering */
+    elevation?: number;
+    /** 3D model URL (GLB format) for GameCanvas3D — rendered via ModelLoader with box fallback */
+    modelUrl?: Asset;
+    /** Y-axis rotation in degrees (3D) — orients directional pieces (track corners, road bends) */
+    rotation?: number;
+}
+/** A unit positioned on the isometric grid */
+type IsometricUnit = {
+    /** Unique unit identifier */
+    id: string;
+    /** Current grid position (2D format) */
+    position?: {
+        x: number;
+        y: number;
+    };
+    /** Grid x coordinate (3D format) */
+    x?: number;
+    /** Grid y coordinate (3D format) */
+    y?: number;
+    /** Grid z coordinate (3D format) */
+    z?: number;
+    /** Static sprite URL (used when no sprite sheet animation) */
+    sprite?: Asset;
+    /** Sprite-sheet atlas JSON URL (e.g. `.../guardian-sprite-sheet.json`).
+     *  When set, the canvas loads the atlas and crops/animates a single frame
+     *  by animation state instead of drawing the whole sheet. */
+    spriteSheet?: Asset;
+    /** 3D model URL (GLB format) for GameCanvas3D — rendered via ModelLoader with box fallback */
+    modelUrl?: Asset;
+    /** Unit archetype key for sprite resolution */
+    unitType?: string;
+    /** Hero identifier for sprite sheet lookup */
+    heroId?: string;
+    /** Display name rendered below the unit */
+    name?: string;
+    /** Team affiliation for coloring */
+    team?: 'player' | 'enemy' | 'neutral';
+    /** Faction for 3D rendering (player/enemy/neutral) */
+    faction?: 'player' | 'enemy' | 'neutral';
+    /** Fallback/override tint color (2D + 3D) — bypasses the team/faction color map. `.lolo`-computed. */
+    tint?: string;
+    /** Current health */
+    health?: number;
+    /** Maximum health */
+    maxHealth?: number;
+    /** Trait attachments for state display */
+    traits?: UnitTrait[];
+    /** Previous position for movement trail ghost */
+    previousPosition?: {
+        x: number;
+        y: number;
+    };
+    /** 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;
+    /** Y-axis heading in radians (3D) — travel/facing direction. Orients the unit model and
+     *  drives the `chase` camera (behind + above, looking along heading). Driving boards set this. */
+    heading?: number;
+};
+/** A map feature (resource, building, portal, etc.) */
+type IsometricFeature = {
+    /** Optional unique identifier (required for 3D rendering) */
+    id?: string;
+    /** Grid x coordinate */
+    x: number;
+    /** Grid y coordinate (2D) */
+    y: number;
+    /** Grid z coordinate (3D alternative to y) */
+    z?: number;
+    /** Feature type key (e.g., 'goldMine', 'castle', 'portal') */
+    type: string;
+    /** Direct sprite URL override (bypasses getFeatureSprite resolver) */
+    sprite?: Asset;
+    /** 3D model URL (GLB format) for GameCanvas3D */
+    assetUrl?: Asset;
+    /** Color override for 3D rendering */
+    color?: string;
+    /** Elevation offset for 3D rendering */
+    elevation?: number;
+    /** Y-axis rotation in radians (3D) — orients directional features (arches, signs, docks). */
+    rotation?: number;
+};
+/** Camera state for pan/zoom */
+interface CameraState {
+    /** Camera X offset in pixels */
+    x: number;
+    /** Camera Y offset in pixels */
+    y: number;
+    /** Zoom level (1.0 = 100%) */
+    zoom: number;
+}
+
+/** Source sub-rectangle within a texture (an atlas frame). Omitted → whole texture. */
+interface BlitSrc {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+/** A polyline/polygon vertex in pixel space. */
+interface PainterPoint {
+    x: number;
+    y: number;
+}
+/** A drop shadow applied to subsequent draws until cleared. */
+interface PainterShadow {
+    color: string;
+    blur: number;
+}
+
+/**
+ * Drawable contract — the shared vocabulary every neutral drawable primitive
+ * (the `draw-sprite`/`draw-shape`/`draw-text` atoms, `draw-sprite-layer`/
+ * `draw-shape-layer` molecules) is authored against. A drawable is a pure
+ * descriptor the canvas HOST walks and paints via the portable {@link Painter2D}
+ * seam — no `CanvasRenderingContext2D`, no DOM. Genre (a "unit"/"tile"/
+ * "highlight") is a `.lolo` COMPOSITION of these, never its own primitive.
+ *
+ * A position is a core `ScenePos` (logical scene space). The host's {@link Projector}
+ * maps it to pixels; primitives never do projection math themselves. Because the
+ * `ScenePos` type identity is what pattern-sync stamps as the `drawable`
+ * capability, every drawable descriptor's `position` MUST be a core `ScenePos`.
+ */
+
+/**
+ * How a drawable aligns to its projected position.
+ * - `top-left` — the cell's top-left corner (tiles).
+ * - `ground`   — the cell's ground point, bottom-center of the drawable (units/features).
+ * - `center`   — the cell's visual center (effects).
+ */
+type DrawableAnchor = 'top-left' | 'ground' | 'center';
+/** Common shape of every drawable descriptor. `type` keys the host's paint dispatch. */
+interface DrawableBase {
+    type: string;
+    /**
+     * Optional hit-test handle. When a board authors a per-entity id here (e.g.
+     * `id: (object/get @u id)` on a unit sprite), the canvas host indexes the
+     * descriptor's `ScenePos → id` and resolves a pointer/raycast at that cell to
+     * this id — the source of `unitClickEvent {unitId}`. A source-tagged handle,
+     * NOT a heuristic: no id → the host emits only the coordinate (tile click).
+     */
+    id?: string;
+}
+
+/**
+ * `draw-sprite` — the neutral image/atlas-frame drawable atom (dimension-agnostic).
+ *
+ * ONE descriptor (`DrawSpriteProps`, grounded in core `ScenePos` + `Asset`) with
+ * TWO backends: `paintSprite` (2D, here — via the portable `Painter2D` seam) and
+ * an R3F mesh (`Sprite3D` in `lib/drawable/mesh3d`, kept OUT of this file so the
+ * 2D paint path never pulls `three`/`drei` into an app bundle — the codebase
+ * code-splits R3F). The canvas host picks the backend by `mode`; that is what
+ * makes canvas-2d and canvas-3d the same `children` interface. Genre uses (tile,
+ * unit body, feature, effect, movement ghost, background cover) are all this atom
+ * with different `anchor`/`size`/`frame`/`flip`/`shadow` — composed in `.lolo`,
+ * not here. The React component renders `null` (a drawable is painted by the host,
+ * not the DOM); it exists so the pattern pipeline registers a `draw-sprite`
+ * pattern and standalone pages stay inspectable.
+ */
+
+interface DrawSpriteProps extends DrawableBase {
+    type: 'draw-sprite';
+    /** Logical scene position; the projector maps it to pixels / world. */
+    position: ScenePos;
+    /** The image / atlas reference to blit. */
+    asset: Asset;
+    /** How the sprite aligns to its projected position. Default `'top-left'`. */
+    anchor?: DrawableAnchor;
+    /** Draw width in world units (fractions of `projector.tileWidth`); omitted → resolved source width in px. */
+    width?: number;
+    /** Draw height in world units (fractions of `projector.tileWidth`); omitted → resolved source height in px. */
+    height?: number;
+    /** Explicit atlas sub-rect override (px); omitted → resolved from `asset.atlas`/`asset.sprite`. */
+    frame?: BlitSrc;
+    /** Mirror horizontally (facing). */
+    flipX?: boolean;
+    /** Rotation in radians about the sprite's center. */
+    rotation?: number;
+    /** 0..1 opacity. */
+    opacity?: number;
+    /** Drop shadow (e.g. a team-colored glow). */
+    shadow?: PainterShadow;
+}
+
+/**
+ * `draw-shape` — the neutral vector-fill/stroke drawable atom (dimension-agnostic).
+ *
+ * ONE descriptor (`DrawShapeProps`, grounded in core `ScenePos`) with TWO
+ * backends: `paintShape` (2D, here) and an R3F ground-plane mesh (`Shape3D` in
+ * `lib/drawable/mesh3d`, kept OUT of this file so the 2D path never pulls R3F).
+ * Paints a cell footprint, an axis-aligned rect, an ellipse, or a poly at a scene
+ * position, fill and/or stroke. Genre uses (tile fallback, iso/hex diamond
+ * fallback, cell highlight, feature disc, unit selection ring, unit fallback
+ * circle, ground/ghost discs, solid backgrounds, side-view platform rects) are
+ * all this atom with different `shape`/`anchor`/geometry — composed in `.lolo`,
+ * not here. The React component renders `null`; it exists so the pattern pipeline
+ * registers a `draw-shape` pattern and standalone pages stay inspectable.
+ */
+
+type ShapeKind = 'cell' | 'rect' | 'ellipse' | 'poly';
+interface DrawShapeProps extends DrawableBase {
+    type: 'draw-shape';
+    shape: ShapeKind;
+    /** Logical scene position; the projector maps it to pixels / world. */
+    position: ScenePos;
+    /** How the shape aligns to its projected position. Default varies by `shape`. */
+    anchor?: DrawableAnchor;
+    /** Rect width in world units (fractions of `projector.tileWidth`). */
+    width?: number;
+    /** Rect height in world units (fractions of `projector.tileWidth`). */
+    height?: number;
+    /** Ellipse horizontal radius in world units (fractions of `projector.tileWidth`). */
+    radiusX?: number;
+    /** Ellipse vertical radius in world units; omitted → `radiusX` (a circle). */
+    radiusY?: number;
+    /** Fine nudge from the anchor point in world units. */
+    offsetX?: number;
+    offsetY?: number;
+    /** Poly vertices as world-unit offsets relative to the cell's projected top-left. */
+    points?: PainterPoint[];
+    fill?: string;
+    stroke?: string;
+    strokeWidth?: number;
+    /** 0..1 opacity. */
+    opacity?: number;
+}
+
+/**
+ * `draw-text` — the neutral text drawable atom (dimension-agnostic).
+ *
+ * ONE descriptor (`DrawTextProps`, grounded in core `ScenePos`) with TWO backends:
+ * `paintText` (2D, here) and an R3F billboarded `<Text>` (`Text3D` in
+ * `lib/drawable/mesh3d`, kept OUT of this file so the 2D path never pulls R3F).
+ * Paints a string at a scene position with font/color/alignment. The React
+ * component renders `null` (a drawable is painted by the host, not the DOM).
+ */
+
+interface DrawTextProps extends DrawableBase {
+    type: 'draw-text';
+    text: string;
+    /** Logical scene position; the projector maps it to pixels / world. */
+    position: ScenePos;
+    anchor?: DrawableAnchor;
+    offsetX?: number;
+    offsetY?: number;
+    color: string;
+    font?: string;
+    align?: CanvasTextAlign;
+    baseline?: CanvasTextBaseline;
+    opacity?: number;
+}
+
+/**
+ * `draw-sprite-layer` — batch multiple sprites in one descriptor for O(layers) rendering.
+ *
+ * Composes the `draw-sprite` atom; the layer itself carries no `position` — each
+ * item does. It is drawable-by-composition: its `items` are `draw-sprite`
+ * descriptors (each grounded in core `ScenePos`), which is what stamps the layer
+ * `drawable` at pattern-sync time.
+ */
+
+interface DrawSpriteLayerProps extends DrawableBase {
+    type: 'draw-sprite-layer';
+    /** Sprites painted in array order; z-ordering is the caller's responsibility. */
+    items: DrawSpriteProps[];
+}
+
+/**
+ * `draw-shape-layer` — batch of shapes in one descriptor for O(layers) perf.
+ *
+ * Composes the `draw-shape` atom; drawable-by-composition (its `items` are
+ * `draw-shape` descriptors, each grounded in core `ScenePos`). The React
+ * component renders `null` (a drawable is painted by the host, not the DOM).
+ */
+
+interface DrawShapeLayerProps extends DrawableBase {
+    type: 'draw-shape-layer';
+    items: DrawShapeProps[];
+}
+
+/**
+ * `draw-text-layer` — batch of text labels in one descriptor for O(layers) perf.
+ *
+ * Composes the `draw-text` atom; drawable-by-composition (its `items` are
+ * `draw-text` descriptors, each grounded in core `ScenePos`). Covers the batched
+ * world-space text pass — fx messages, damage numbers, unit labels — that a
+ * board maps from an entity array (`items: (array/map @entity.fx (fn ...))`),
+ * which a literal `children` array can't express. The React component renders
+ * `null` (a drawable is painted by the host, not the DOM).
+ */
+
+interface DrawTextLayerProps extends DrawableBase {
+    type: 'draw-text-layer';
+    items: DrawTextProps[];
+}
+
+/**
+ * Drawable paint dispatch (2D) + the `DrawableNode` union.
+ *
+ * `paintDrawable` routes ONE descriptor to its 2D painter; the host walks its
+ * `children` through it. The "drawable" designation itself is NOT recorded here —
+ * it is DERIVED from the core `ScenePos` type each descriptor's `position` uses
+ * and stamped into `patterns-registry.json` by pattern-sync (mirroring how `Asset`
+ * is tagged), then read by the orbital-rust validator. So this module is pure
+ * paint routing; the capability is the registry's, not a hand-list.
+ */
+
+/** Every drawable descriptor. The host's `children` are a `DrawableNode[]`. */
+type DrawableNode = DrawSpriteProps | DrawShapeProps | DrawTextProps | DrawSpriteLayerProps | DrawShapeLayerProps | DrawTextLayerProps;
+
+/**
+ * AVL Schema Parser
+ *
+ * Pure functions that transform an OrbitalSchema into structured data
+ * for each zoom level of the Cosmic Zoom visualization.
+ *
+ * Imports all types from @almadar/core.
+ *
+ * @packageDocumentation
+ */
+
+interface SerializedEffect extends JsonObject {
+    type: string;
+    args: JsonValue[];
+}
+interface ApplicationOrbitalData {
+    name: string;
+    entityName: string;
+    fieldCount: number;
+    persistence: string;
+    traitNames: string[];
+    pageNames: string[];
+    position: {
+        x: number;
+        y: number;
+    };
+}
+interface CrossLink {
+    emitterOrbital: string;
+    listenerOrbital: string;
+    eventName: string;
+    emitterTrait: string;
+    listenerTrait: string;
+}
+interface ApplicationLevelData {
+    orbitals: ApplicationOrbitalData[];
+    crossLinks: CrossLink[];
+}
+interface FieldInfo extends JsonObject {
+    name: string;
+    type: string;
+    required: boolean;
+    hasDefault: boolean;
+}
+interface OrbitalTraitInfo extends JsonObject {
+    name: string;
+    stateCount: number;
+    eventCount: number;
+    transitionCount: number;
+    emits: string[];
+    listens: string[];
+}
+interface OrbitalPageInfo extends JsonObject {
+    name: string;
+    route: string;
+}
+interface ExternalLink extends JsonObject {
+    targetOrbital: string;
+    eventName: string;
+    direction: string;
+    traitName: string;
+}
+interface OrbitalLevelData {
+    name: string;
+    entity: {
+        name: string;
+        fields: FieldInfo[];
+        persistence: string;
+    };
+    traits: OrbitalTraitInfo[];
+    pages: OrbitalPageInfo[];
+    externalLinks: ExternalLink[];
+}
+interface TraitStateInfo extends JsonObject {
+    name: string;
+    isInitial: boolean | null;
+    isTerminal: boolean | null;
+}
+interface TraitTransitionInfo extends JsonObject {
+    from: string;
+    to: string;
+    event: string;
+    guard: JsonValue | null;
+    effects: SerializedEffect[];
+    index: number;
+}
+interface TraitLevelData extends JsonObject {
+    name: string;
+    linkedEntity: string;
+    states: TraitStateInfo[];
+    transitions: TraitTransitionInfo[];
+    emittedEvents: string[];
+    listenedEvents: string[];
+}
+interface ExprTreeNode {
+    label: string;
+    type: 'operator' | 'literal' | 'binding';
+    children?: ExprTreeNode[];
+}
+interface SlotTarget {
+    name: string;
+    pattern: string;
+}
+interface TransitionLevelData {
+    from: string;
+    to: string;
+    event: string;
+    guard: ExprTreeNode | null;
+    effects: ExprTreeNode[];
+    slotTargets: SlotTarget[];
+}
+
+export { type ApplicationLevelData as A, type BoardTile as B, type CameraState as C, type DrawableNode as D, type ExternalLink as E, type FacingDirection as F, type GameAction as G, type IsometricTile as I, type OrbitalLevelData as O, type Position as P, type ResolvedFrame as R, type SpriteSheetUrls as S, type TraitLevelData as T, type UnitAnimationState as U, type IsometricUnit as a, type IsometricFeature as b, type TransitionLevelData as c, type SpriteFrameDims as d, type FieldInfo as e, type OrbitalTraitInfo as f, type OrbitalPageInfo as g, type GamePhase as h, type GameState as i, type GameUnit as j, type UnitTrait as k, calculateAttackTargets as l, calculateValidMoves as m, createInitialGameState as n };