@almadar/ui 5.79.1 → 5.80.0

package/dist/components/game/2d/organisms/SimulatorBoard.d.ts

@@ -0,0 +1,58 @@
+/**
+ * SimulatorBoard
+ *
+ * Parameter-slider game board. The player adjusts two parameters (A and B)
+ * and observes the machine-derived output. Correct parameter values must
+ * bring the output within tolerance of the target to win.
+ *
+ * Good for: physics, economics, system design stories.
+ *
+ * Controlled-only: params, output, attempts, and result are owned by the
+ * gameplay machine and read off the bound entity. Slider/check/play-again
+ * interactions are emitted as events; the machine recomputes and re-renders.
+ */
+import React from 'react';
+import type { EventEmit, EntityRow, Asset } from '@almadar/core';
+import type { DisplayStateProps } from '../../../core/organisms/types';
+/** A tunable simulation parameter slider descriptor (UI value DTO read off the entity). */
+export interface SimulatorParameter {
+    id: string;
+    label: string;
+    unit: string;
+    min: number;
+    max: number;
+    step: number;
+    initial: number;
+    correct: number;
+    tolerance: number;
+}
+export interface SimulatorBoardProps extends DisplayStateProps {
+    /** Puzzle board-state entity (single row or array). The board reads the
+     *  `parameters` slider descriptors plus the machine-owned `paramA`/`paramB`/
+     *  `output`/`target`/`tolerance`/`attempts`/`result` fields off the row. */
+    entity?: EntityRow | readonly EntityRow[];
+    completeEvent?: EventEmit<{
+        success: boolean;
+        attempts: number;
+    }>;
+    /** Emits UI:{setAEvent} with { value } when parameter A's slider changes. */
+    setAEvent?: EventEmit<{
+        value: number;
+    }>;
+    /** Emits UI:{setBEvent} with { value } when parameter B's slider changes. */
+    setBEvent?: EventEmit<{
+        value: number;
+    }>;
+    /** Emits UI:{checkEvent} with {} on simulate / check. */
+    checkEvent?: EventEmit<Record<string, never>>;
+    /** Emits UI:{playAgainEvent} with {} on reset / play again. */
+    playAgainEvent?: EventEmit<Record<string, never>>;
+    /** Optional per-semantic-key asset overrides for icons (correct/incorrect/play/reset). */
+    assetManifest?: {
+        ui?: Record<string, Asset>;
+    };
+}
+export declare function SimulatorBoard({ entity, completeEvent, setAEvent, setBEvent, checkEvent, playAgainEvent, assetManifest, className, }: SimulatorBoardProps): React.JSX.Element | null;
+export declare namespace SimulatorBoard {
+    var displayName: string;
+}

package/dist/components/game/2d/organisms/SokobanBoard.d.ts

@@ -0,0 +1,37 @@
+import React from 'react';
+import type { AssetUrl, EventEmit } from '@almadar/core';
+import type { IsometricTile, IsometricUnit, IsometricFeature } from '../../shared/isometricTypes';
+import type { DisplayStateProps } from '../../../core/organisms/types';
+import type { Canvas2DProps } from '../molecules/Canvas2D';
+export interface SokobanBoardProps extends DisplayStateProps {
+    /** Grid tiles (floor, wall, target) */
+    tiles?: IsometricTile[];
+    /** Units on the board (the pusher character) */
+    units?: IsometricUnit[];
+    /** Features (crates) on the board */
+    features?: IsometricFeature[];
+    /** Asset sprite manifest (same shape as Canvas2D.assetManifest) */
+    assetManifest?: Canvas2DProps['assetManifest'];
+    /** Base URL prepended to manifest sprite paths */
+    assetBaseUrl?: AssetUrl;
+    /** Render scale */
+    scale?: number;
+    /** Show minimap overlay */
+    showMinimap?: boolean;
+    /** Enable camera pan/zoom controls */
+    enableCamera?: boolean;
+    /** Declarative event: emits UI:{tileClickEvent} with { x, y } on tile click */
+    tileClickEvent?: EventEmit<{
+        x: number;
+        y: number;
+    }>;
+    /** Declarative event: emits UI:{unitClickEvent} with { unitId } on unit click */
+    unitClickEvent?: EventEmit<{
+        unitId: string;
+    }>;
+}
+export declare function SokobanBoard({ tiles, units, features, assetManifest, assetBaseUrl, scale, showMinimap, enableCamera, tileClickEvent, unitClickEvent, isLoading, error, className, }: SokobanBoardProps): React.ReactElement;
+export declare namespace SokobanBoard {
+    var displayName: string;
+}
+export default SokobanBoard;

package/dist/components/game/2d/organisms/SpaceShmupBoard.d.ts

@@ -0,0 +1,44 @@
+import React from 'react';
+import type { Asset, AssetUrl, EventEmit } from '@almadar/core';
+import type { IsometricTile, IsometricUnit, IsometricFeature } from '../../shared/isometricTypes';
+import type { DisplayStateProps } from '../../../core/organisms/types';
+/** Asset manifest shape for SpaceShmupBoard. */
+type SpaceShmupAssetManifest = {
+    terrains?: Record<string, Asset>;
+    units?: Record<string, Asset>;
+    features?: Record<string, Asset>;
+    effects?: Record<string, Asset>;
+    ui?: Record<string, Asset>;
+};
+export interface SpaceShmupBoardProps extends DisplayStateProps {
+    /** Space terrain tiles filling the grid */
+    tiles?: IsometricTile[];
+    /** Player ship and enemy ships on the board */
+    units?: IsometricUnit[];
+    /** Features (asteroids, power-ups, etc.) on the board */
+    features?: IsometricFeature[];
+    /** Asset sprite manifest */
+    assetManifest?: SpaceShmupAssetManifest;
+    /** Base URL prepended to manifest sprite paths */
+    assetBaseUrl?: AssetUrl;
+    /** Render scale */
+    scale?: number;
+    /** Show minimap overlay */
+    showMinimap?: boolean;
+    /** Enable camera pan/zoom controls */
+    enableCamera?: boolean;
+    /** Declarative event: emits UI:{tileClickEvent} with { x, y } on tile click */
+    tileClickEvent?: EventEmit<{
+        x: number;
+        y: number;
+    }>;
+    /** Declarative event: emits UI:{unitClickEvent} with { unitId } on unit click */
+    unitClickEvent?: EventEmit<{
+        unitId: string;
+    }>;
+}
+export declare function SpaceShmupBoard({ tiles, units, features, assetManifest, assetBaseUrl, scale, showMinimap, enableCamera, tileClickEvent, unitClickEvent, isLoading, error, className, }: SpaceShmupBoardProps): React.ReactElement;
+export declare namespace SpaceShmupBoard {
+    var displayName: string;
+}
+export default SpaceShmupBoard;

package/dist/components/game/2d/organisms/SpaceStationBoard.d.ts

@@ -0,0 +1,37 @@
+import React from 'react';
+import type { AssetUrl, EventEmit } from '@almadar/core';
+import type { IsometricTile, IsometricUnit, IsometricFeature } from '../../shared/isometricTypes';
+import type { DisplayStateProps } from '../../../core/organisms/types';
+import type { Canvas2DProps } from '../molecules/Canvas2D';
+export interface SpaceStationBoardProps extends DisplayStateProps {
+    /** Isometric grid tiles */
+    tiles?: IsometricTile[];
+    /** Units on the board */
+    units?: IsometricUnit[];
+    /** Features (consoles, airlocks, etc.) on the board */
+    features?: IsometricFeature[];
+    /** Asset sprite manifest (same shape as Canvas2D.assetManifest) */
+    assetManifest?: Canvas2DProps['assetManifest'];
+    /** Base URL prepended to manifest sprite paths */
+    assetBaseUrl?: AssetUrl;
+    /** Render scale */
+    scale?: number;
+    /** Show minimap overlay */
+    showMinimap?: boolean;
+    /** Enable camera pan/zoom controls */
+    enableCamera?: boolean;
+    /** Declarative event: emits UI:{tileClickEvent} with { x, y } on tile click */
+    tileClickEvent?: EventEmit<{
+        x: number;
+        y: number;
+    }>;
+    /** Declarative event: emits UI:{unitClickEvent} with { unitId } on unit click */
+    unitClickEvent?: EventEmit<{
+        unitId: string;
+    }>;
+}
+export declare function SpaceStationBoard({ tiles, units, features, assetManifest, assetBaseUrl, scale, showMinimap, enableCamera, tileClickEvent, unitClickEvent, isLoading, error, className, }: SpaceStationBoardProps): React.ReactElement;
+export declare namespace SpaceStationBoard {
+    var displayName: string;
+}
+export default SpaceStationBoard;

package/dist/components/game/2d/organisms/SportsBoard.d.ts

@@ -0,0 +1,37 @@
+import React from 'react';
+import type { AssetUrl, EventEmit } from '@almadar/core';
+import type { IsometricTile, IsometricUnit, IsometricFeature } from '../../shared/isometricTypes';
+import type { DisplayStateProps } from '../../../core/organisms/types';
+import type { Canvas2DProps } from '../molecules/Canvas2D';
+export interface SportsBoardProps extends DisplayStateProps {
+    /** Court/field terrain tiles */
+    tiles?: IsometricTile[];
+    /** Player units on the board */
+    units?: IsometricUnit[];
+    /** Features (goals, markers, etc.) on the board */
+    features?: IsometricFeature[];
+    /** Asset sprite manifest (same shape as Canvas2D.assetManifest) */
+    assetManifest?: Canvas2DProps['assetManifest'];
+    /** Base URL prepended to asset paths */
+    assetBaseUrl?: AssetUrl;
+    /** Render scale */
+    scale?: number;
+    /** Show minimap overlay */
+    showMinimap?: boolean;
+    /** Enable camera pan/zoom controls */
+    enableCamera?: boolean;
+    /** Declarative event: emits UI:{tileClickEvent} with { x, y } on tile click */
+    tileClickEvent?: EventEmit<{
+        x: number;
+        y: number;
+    }>;
+    /** Declarative event: emits UI:{unitClickEvent} with { unitId } on unit click */
+    unitClickEvent?: EventEmit<{
+        unitId: string;
+    }>;
+}
+export declare function SportsBoard({ tiles, units, features, assetManifest, assetBaseUrl, scale, showMinimap, enableCamera, tileClickEvent, unitClickEvent, isLoading, error, className, }: SportsBoardProps): React.ReactElement;
+export declare namespace SportsBoard {
+    var displayName: string;
+}
+export default SportsBoard;

package/dist/components/game/2d/organisms/StateArchitectBoard.d.ts

@@ -0,0 +1,61 @@
+/**
+ * StateArchitectBoard Organism
+ *
+ * Contains ALL game logic for the State Architect tier (ages 13+).
+ * Kids design state machines via a visual graph editor, then run
+ * them to see if the behavior matches the puzzle goal.
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+import type { EventEmit, EntityRow } from '@almadar/core';
+import type { DisplayStateProps } from '../../../core/organisms/types';
+/** A kid-built transition in the visual graph editor (UI value DTO). */
+export interface StateArchitectTransition {
+    id: string;
+    from: string;
+    to: string;
+    event: string;
+    guardHint?: string;
+}
+/** A puzzle test case (UI value DTO). */
+export interface TestCase {
+    /** Sequence of events to fire */
+    events: string[];
+    /** Expected final state */
+    expectedState: string;
+    /** Description */
+    label: string;
+}
+export interface StateArchitectBoardProps extends DisplayStateProps {
+    /** Puzzle board-state entity (single row or array). The board reads
+     *  `variables` / `states` / `transitions` / `testCases` etc. off the row. */
+    entity?: EntityRow | readonly EntityRow[];
+    /** Playback speed */
+    stepDurationMs?: number;
+    /** Emits UI:{testEvent} */
+    testEvent?: EventEmit<Record<string, never>>;
+    /** Emits UI:{completeEvent} with { success, passedTests } */
+    completeEvent?: EventEmit<{
+        success: boolean;
+        passedTests: number;
+    }>;
+    /** Emits UI:{addTransitionEvent} — lolo handles ADD_TRANSITION */
+    addTransitionEvent?: EventEmit<{
+        id: string;
+        from: string;
+        to: string;
+        event: string;
+    }>;
+    /** Emits UI:{removeTransitionEvent} — lolo handles REMOVE_TRANSITION */
+    removeTransitionEvent?: EventEmit<{
+        id: string;
+    }>;
+    /** Emits UI:{playAgainEvent} — lolo handles PLAY_AGAIN */
+    playAgainEvent?: EventEmit<Record<string, never>>;
+}
+export declare function StateArchitectBoard({ entity, stepDurationMs, testEvent, completeEvent, addTransitionEvent, removeTransitionEvent, playAgainEvent, className, }: StateArchitectBoardProps): React.JSX.Element | null;
+export declare namespace StateArchitectBoard {
+    var displayName: string;
+}
+export default StateArchitectBoard;

package/dist/components/game/2d/organisms/StateJsonView.d.ts

@@ -0,0 +1,17 @@
+import React from 'react';
+import { JsonObject } from '@almadar/core';
+export interface StateJsonViewProps {
+    /** JSON data to display */
+    data: JsonObject;
+    /** Label */
+    label?: string;
+    /** Whether the code is expanded by default */
+    defaultExpanded?: boolean;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function StateJsonView({ data, label, defaultExpanded, className, }: StateJsonViewProps): React.JSX.Element;
+export declare namespace StateJsonView {
+    var displayName: string;
+}
+export default StateJsonView;

package/dist/components/game/2d/organisms/StateNode.d.ts

@@ -0,0 +1,31 @@
+/**
+ * StateNode Component
+ *
+ * A draggable state circle for the graph editor in the State Architect tier (ages 13+).
+ * Shows state name, highlights when current, and supports click to select.
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+import { type Point } from '../../../core/atoms/index';
+export interface StateNodeProps {
+    /** State name */
+    name: string;
+    /** Whether this is the current active state */
+    isCurrent?: boolean;
+    /** Whether this node is selected for editing */
+    isSelected?: boolean;
+    /** Whether this is the initial state */
+    isInitial?: boolean;
+    /** Position on the graph canvas */
+    position: Point;
+    /** Click handler */
+    onClick?: () => void;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function StateNode({ name, isCurrent, isSelected, isInitial, position, onClick, className, }: StateNodeProps): React.JSX.Element;
+export declare namespace StateNode {
+    var displayName: string;
+}
+export default StateNode;

package/dist/components/game/2d/organisms/TanksBoard.d.ts

@@ -0,0 +1,39 @@
+import React from 'react';
+import type { Asset, AssetUrl, EventEmit } from '@almadar/core';
+import type { IsometricTile, IsometricUnit, IsometricFeature } from '../../shared/isometricTypes';
+import type { DisplayStateProps } from '../../../core/organisms/types';
+import type { Canvas2DProps } from '../molecules/Canvas2D';
+export interface TanksBoardProps extends DisplayStateProps {
+    /** Ground/sand terrain tiles */
+    tiles?: IsometricTile[];
+    /** Tank units on the board */
+    units?: IsometricUnit[];
+    /** Features (obstacles, structures, etc.) on the board */
+    features?: IsometricFeature[];
+    /** Asset sprite manifest (same shape as Canvas2D.assetManifest) */
+    assetManifest?: Canvas2DProps['assetManifest'];
+    /** Base URL prepended to manifest sprite paths */
+    assetBaseUrl?: AssetUrl;
+    /** HUD chrome assets (panel backgrounds, stat icons, etc.) keyed by role. */
+    ui?: Record<string, Asset>;
+    /** Render scale */
+    scale?: number;
+    /** Show minimap overlay */
+    showMinimap?: boolean;
+    /** Enable camera pan/zoom controls */
+    enableCamera?: boolean;
+    /** Declarative event: emits UI:{tileClickEvent} with { x, y } on tile click */
+    tileClickEvent?: EventEmit<{
+        x: number;
+        y: number;
+    }>;
+    /** Declarative event: emits UI:{unitClickEvent} with { unitId } on unit click */
+    unitClickEvent?: EventEmit<{
+        unitId: string;
+    }>;
+}
+export declare function TanksBoard({ tiles, units, features, assetManifest, assetBaseUrl, ui: _ui, scale, showMinimap, enableCamera, tileClickEvent, unitClickEvent, isLoading, error, className, }: TanksBoardProps): React.ReactElement;
+export declare namespace TanksBoard {
+    var displayName: string;
+}
+export default TanksBoard;

package/dist/components/game/2d/organisms/TopDownShooterBoard.d.ts

@@ -0,0 +1,65 @@
+import * as React from 'react';
+import type { Asset, EventEmit, EntityRow } from '@almadar/core';
+/** Per-kind sprite maps (organism owns asset choice; UI value DTO). */
+type ShooterAssetManifest = {
+    units?: Record<string, Asset>;
+    features?: Record<string, Asset>;
+    background?: Asset;
+    /** HUD chrome assets (panel backgrounds, stat icons, etc.) keyed by role. */
+    ui?: Record<string, Asset>;
+};
+export interface ShooterPlayer {
+    x: number;
+    y: number;
+}
+export interface ShooterEnemy {
+    id: string;
+    x: number;
+    y: number;
+    hp: number;
+}
+export interface ShooterProjectile {
+    id: string;
+    x: number;
+    y: number;
+    vx: number;
+    vy: number;
+}
+export interface TopDownShooterBoardProps {
+    /** Entity carrying all board state (player, enemies, projectiles, score, wave, lives, result). */
+    entity?: EntityRow | readonly EntityRow[];
+    /** Direct state — each takes priority over its entity-derived value. */
+    player?: ShooterPlayer;
+    enemies?: ShooterEnemy[];
+    projectiles?: ShooterProjectile[];
+    score?: number;
+    wave?: number;
+    lives?: number;
+    result?: 'none' | 'won' | 'lost';
+    /** Asset base-url + unit/feature sprite maps + background. */
+    assetManifest?: ShooterAssetManifest;
+    /** Canvas / arena dimensions in pixels. */
+    width?: number;
+    height?: number;
+    /** Pixel draw-size of sprites. */
+    spriteSize?: number;
+    /** Closed-circuit event emits (UI:{event}). */
+    moveEvent?: EventEmit<{
+        dx: number;
+        dy: number;
+    }>;
+    fireEvent?: EventEmit<{
+        tx: number;
+        ty: number;
+    }>;
+    playAgainEvent?: EventEmit<Record<string, never>>;
+    gameEndEvent?: EventEmit<{
+        result: 'won' | 'lost';
+    }>;
+    className?: string;
+}
+export declare function TopDownShooterBoard({ entity, player: propPlayer, enemies: propEnemies, projectiles: propProjectiles, score: propScore, wave: propWave, lives: propLives, result: propResult, assetManifest: propAssetManifest, width, height, spriteSize, moveEvent, fireEvent, playAgainEvent, gameEndEvent, className, }: TopDownShooterBoardProps): React.JSX.Element;
+export declare namespace TopDownShooterBoard {
+    var displayName: string;
+}
+export default TopDownShooterBoard;

package/dist/components/game/2d/organisms/TowerDefenseBoard.d.ts

@@ -0,0 +1,87 @@
+import React from 'react';
+import type { Asset, AssetUrl, EventEmit, EntityRow } from '@almadar/core';
+import type { DisplayStateProps } from '../../../core/organisms/types';
+/** Manifest of per-kind sprite maps (UI value DTO). */
+type TowerDefenseAssetManifest = {
+    terrains?: Record<string, Asset>;
+    units?: Record<string, Asset>;
+    features?: Record<string, Asset>;
+    /** HUD chrome assets (panel backgrounds, stat icons, etc.) keyed by role. */
+    ui?: Record<string, Asset>;
+};
+export interface TowerDefenseTile {
+    x: number;
+    y: number;
+    terrain?: string;
+    terrainSprite?: AssetUrl;
+    passable?: boolean;
+}
+export interface TowerDefensePathPoint {
+    x: number;
+    y: number;
+}
+export interface TowerDefenseTower {
+    id: string;
+    x: number;
+    y: number;
+    range: number;
+    damage: number;
+    cooldown: number;
+    lastFiredAt?: number;
+}
+export interface TowerDefenseCreep {
+    id: string;
+    x: number;
+    y: number;
+    hp: number;
+    maxHp: number;
+    pathIndex: number;
+    speed: number;
+}
+export interface TowerDefenseHero {
+    id: string;
+    x: number;
+    y: number;
+}
+export interface TowerDefenseBoardProps extends DisplayStateProps {
+    entity?: EntityRow | readonly EntityRow[];
+    tiles?: TowerDefenseTile[];
+    path?: TowerDefensePathPoint[];
+    towers?: TowerDefenseTower[];
+    creeps?: TowerDefenseCreep[];
+    /** Asset base-url + terrain/unit/feature sprite maps (organism owns asset choice). */
+    assetManifest?: TowerDefenseAssetManifest;
+    gold?: number;
+    lives?: number;
+    wave?: number;
+    maxWaves?: number;
+    result?: 'none' | 'won' | 'lost';
+    waveActive?: boolean;
+    hero?: TowerDefenseHero;
+    towerCost?: number;
+    scale?: number;
+    unitScale?: number;
+    spriteHeightRatio?: number;
+    spriteMaxWidthRatio?: number;
+    placeTowerEvent?: EventEmit<{
+        x: number;
+        y: number;
+    }>;
+    startWaveEvent?: EventEmit<{
+        wave: number;
+    }>;
+    playAgainEvent?: EventEmit<Record<string, never>>;
+    gameEndEvent?: EventEmit<{
+        result: 'won' | 'lost';
+    }>;
+    moveHeroEvent?: EventEmit<{
+        dx: number;
+        dy: number;
+    }>;
+    className?: string;
+}
+export declare function TowerDefenseBoard({ entity, tiles: propTiles, path: propPath, towers: propTowers, creeps: propCreeps, assetManifest: propAssetManifest, hero: propHero, gold: propGold, lives: propLives, wave: propWave, maxWaves: propMaxWaves, result: propResult, waveActive: propWaveActive, towerCost, scale, unitScale, spriteHeightRatio, spriteMaxWidthRatio, placeTowerEvent, startWaveEvent, playAgainEvent, gameEndEvent, moveHeroEvent, className, }: TowerDefenseBoardProps): React.JSX.Element;
+export declare namespace TowerDefenseBoard {
+    var displayName: string;
+}
+export default TowerDefenseBoard;

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

@@ -0,0 +1,96 @@
+/**
+ * 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 { Asset, EventEmit } from '@almadar/core';
+import { type TraitStateMachineDefinition } from './TraitStateViewer';
+import type { UiError } from '../../../core/atoms/types';
+/** Data shape for a slot's equipped item */
+export type SlotItemData = {
+    id: string;
+    name: string;
+    category: string;
+    description?: string;
+    /** Emoji or text icon */
+    iconEmoji?: string;
+    /** Asset icon (takes precedence over iconEmoji); falls back to iconEmoji when absent. */
+    iconUrl?: Asset;
+    /** 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 asset */
+    tooltipFrameUrl?: Asset;
+    /** Additional CSS classes */
+    className?: string;
+    /** Loading state */
+    isLoading?: boolean;
+    /** Error state */
+    error?: UiError | 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?: EventEmit<{
+        slotNumber: number;
+    }>;
+    /** Emits UI:{removeEvent} with { slotNumber } */
+    removeEvent?: EventEmit<{
+        slotNumber: number;
+    }>;
+}
+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/game/2d/organisms/TraitStateViewer.d.ts

@@ -0,0 +1,54 @@
+/**
+ * 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/StateIndicator';
+import type { UiError } from '../../../core/atoms/types';
+export type TraitTransition = {
+    from: string;
+    to: string;
+    event: string;
+    guardHint?: string;
+};
+export type 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?: UiError | 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;