@almadar/ui 2.14.0 → 2.15.0

package/dist/components/organisms/game/puzzles/negotiator/NegotiatorBoard.d.ts

@@ -0,0 +1,54 @@
+/**
+ * NegotiatorBoard
+ *
+ * Turn-based decision matrix game. The player makes choices
+ * over multiple rounds against an AI opponent. Each round
+ * both sides pick an action, and payoffs are determined by
+ * the combination.
+ *
+ * Good for: ethics, business, game theory, economics stories.
+ *
+ * Events emitted via completeEvent (default UI:PUZZLE_COMPLETE).
+ */
+import React from 'react';
+import type { EntityDisplayProps } from '../../../types';
+export interface NegotiatorAction {
+    id: string;
+    label: string;
+    description?: string;
+}
+export interface PayoffEntry {
+    playerAction: string;
+    opponentAction: string;
+    playerPayoff: number;
+    opponentPayoff: number;
+}
+export interface NegotiatorPuzzleEntity {
+    id: string;
+    title: string;
+    description: string;
+    actions: NegotiatorAction[];
+    payoffMatrix: PayoffEntry[];
+    totalRounds: number;
+    /** AI strategy: 'tit-for-tat' | 'always-cooperate' | 'always-defect' | 'random' */
+    opponentStrategy: string;
+    targetScore: number;
+    successMessage?: string;
+    failMessage?: string;
+    hint?: string;
+    /** Header image URL displayed above the title */
+    headerImage?: string;
+    /** Visual theme overrides */
+    theme?: {
+        background?: string;
+        accentColor?: string;
+    };
+}
+export interface NegotiatorBoardProps extends Omit<EntityDisplayProps, 'entity'> {
+    entity: NegotiatorPuzzleEntity;
+    completeEvent?: string;
+}
+export declare function NegotiatorBoard({ entity, completeEvent, className, }: NegotiatorBoardProps): React.JSX.Element;
+export declare namespace NegotiatorBoard {
+    var displayName: string;
+}

package/dist/components/organisms/game/puzzles/negotiator/index.d.ts

@@ -0,0 +1,2 @@
+export { NegotiatorBoard } from './NegotiatorBoard';
+export type { NegotiatorBoardProps, NegotiatorPuzzleEntity, NegotiatorAction, PayoffEntry } from './NegotiatorBoard';

package/dist/components/organisms/game/puzzles/sequencer/ActionPalette.d.ts

@@ -0,0 +1,34 @@
+/**
+ * ActionPalette Component
+ *
+ * Grid of draggable ActionTile components for the Sequencer tier.
+ * Kids pick from these to build their sequence.
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+import type { SlotItemData } from '../../TraitSlot';
+export interface ActionPaletteProps {
+    /** Available actions */
+    actions: SlotItemData[];
+    /** IDs of actions that are already used (shown as disabled) */
+    usedActionIds?: string[];
+    /** Whether each action can be used multiple times */
+    allowDuplicates?: boolean;
+    /** Category → color mapping */
+    categoryColors?: Record<string, {
+        bg: string;
+        border: string;
+    }>;
+    /** Size variant */
+    size?: 'sm' | 'md' | 'lg';
+    /** Label above the palette */
+    label?: string;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function ActionPalette({ actions, usedActionIds, allowDuplicates, categoryColors, size, label, className, }: ActionPaletteProps): React.JSX.Element;
+export declare namespace ActionPalette {
+    var displayName: string;
+}
+export default ActionPalette;

package/dist/components/organisms/game/puzzles/sequencer/ActionTile.d.ts

@@ -0,0 +1,30 @@
+/**
+ * ActionTile Component
+ *
+ * A draggable action tile for the Sequencer tier (ages 5-8).
+ * Kids drag these from the ActionPalette into SequenceBar slots.
+ * Sets SlotItemData on dataTransfer for TraitSlot compatibility.
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+import type { EntityDisplayProps } from '../../../types';
+import type { SlotItemData } from '../../TraitSlot';
+export interface ActionTileProps extends Omit<EntityDisplayProps, 'entity'> {
+    /** The action data */
+    action: SlotItemData;
+    /** Size variant */
+    size?: 'sm' | 'md' | 'lg';
+    /** Whether the tile is disabled / already used */
+    disabled?: boolean;
+    /** Category → color mapping */
+    categoryColors?: Record<string, {
+        bg: string;
+        border: string;
+    }>;
+}
+export declare function ActionTile({ action, size, disabled, categoryColors, className, }: ActionTileProps): React.JSX.Element;
+export declare namespace ActionTile {
+    var displayName: string;
+}
+export default ActionTile;

package/dist/components/organisms/game/puzzles/sequencer/SequenceBar.d.ts

@@ -0,0 +1,41 @@
+/**
+ * SequenceBar Component
+ *
+ * A row of TraitSlot components forming the action sequence for the
+ * Sequencer tier (ages 5-8). Kids drag ActionTiles from the palette
+ * into these slots to build their sequence.
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+import type { SlotItemData } from '../../TraitSlot';
+export interface SequenceBarProps {
+    /** The current sequence (sparse — undefined means empty slot) */
+    slots: Array<SlotItemData | undefined>;
+    /** Max number of slots */
+    maxSlots: number;
+    /** Called when an item is dropped into slot at index */
+    onSlotDrop: (index: number, item: SlotItemData) => void;
+    /** Called when a slot is cleared */
+    onSlotRemove: (index: number) => void;
+    /** Whether the sequence is currently playing (disable interaction) */
+    playing?: boolean;
+    /** Current step index during playback (-1 = not playing) */
+    currentStep?: number;
+    /** Category → color mapping */
+    categoryColors?: Record<string, {
+        bg: string;
+        border: string;
+    }>;
+    /** Per-slot correctness feedback shown after a failed attempt */
+    slotFeedback?: Array<'correct' | 'wrong' | null>;
+    /** Size variant */
+    size?: 'sm' | 'md' | 'lg';
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function SequenceBar({ slots, maxSlots, onSlotDrop, onSlotRemove, playing, currentStep, categoryColors, slotFeedback, size, className, }: SequenceBarProps): React.JSX.Element;
+export declare namespace SequenceBar {
+    var displayName: string;
+}
+export default SequenceBar;

package/dist/components/organisms/game/puzzles/sequencer/SequencerBoard.d.ts

@@ -0,0 +1,72 @@
+/**
+ * SequencerBoard Organism
+ *
+ * Contains ALL game logic for the Sequencer tier (ages 5-8).
+ * Manages the action sequence, validates it, and animates Kekec
+ * executing each step on the puzzle scene.
+ *
+ * Feedback-first UX:
+ * - On failure: slots stay in place, each slot gets a green or red
+ *   ring showing exactly which steps are correct and which need to change.
+ * - Modifying a slot clears its individual feedback so the kid can re-try.
+ * - After 3 failures a persistent hint appears above the sequence bar.
+ * - "Reset" clears everything including attempts / hint.
+ *
+ * TraitStateViewer states use indexed labels ("1. Walk", "2. Jump") so that
+ * repeated actions are correctly highlighted during playback.
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+import type { SlotItemData } from '../../TraitSlot';
+import type { EntityDisplayProps } from '../../../types';
+export interface SequencerPuzzleEntity {
+    id: string;
+    title: string;
+    description: string;
+    /** Available actions the kid can use */
+    availableActions: SlotItemData[];
+    /** How many slots in the sequence bar */
+    maxSlots: number;
+    /** Whether actions can be reused */
+    allowDuplicates?: boolean;
+    /** The correct sequence(s) — list of action IDs. First match wins. */
+    solutions: string[][];
+    /** Feedback messages */
+    successMessage?: string;
+    failMessage?: string;
+    /** Progressive hint shown after 3 failures */
+    hint?: string;
+    /** Hex coordinates for map animation — one per action + starting position */
+    path?: Array<{
+        x: number;
+        y: number;
+    }>;
+    /** Header image URL displayed above the title */
+    headerImage?: string;
+    /** Visual theme overrides */
+    theme?: {
+        background?: string;
+        accentColor?: string;
+    };
+}
+export interface SequencerBoardProps extends Omit<EntityDisplayProps, 'entity'> {
+    /** Puzzle data */
+    entity: SequencerPuzzleEntity;
+    /** Category → color mapping */
+    categoryColors?: Record<string, {
+        bg: string;
+        border: string;
+    }>;
+    /** Playback speed in ms per step */
+    stepDurationMs?: number;
+    /** Emits UI:{playEvent} with { sequence: string[] } */
+    playEvent?: string;
+    /** Emits UI:{completeEvent} with { success: boolean } */
+    completeEvent?: string;
+}
+export declare function SequencerBoard({ entity, categoryColors, stepDurationMs, playEvent, completeEvent, className, }: SequencerBoardProps): React.JSX.Element;
+export declare namespace SequencerBoard {
+    var displayName: string;
+}
+export default SequencerBoard;

package/dist/components/organisms/game/puzzles/sequencer/index.d.ts

@@ -0,0 +1,8 @@
+export { ActionTile } from './ActionTile';
+export type { ActionTileProps } from './ActionTile';
+export { ActionPalette } from './ActionPalette';
+export type { ActionPaletteProps } from './ActionPalette';
+export { SequenceBar } from './SequenceBar';
+export type { SequenceBarProps } from './SequenceBar';
+export { SequencerBoard } from './SequencerBoard';
+export type { SequencerBoardProps, SequencerPuzzleEntity } from './SequencerBoard';

package/dist/components/organisms/game/puzzles/simulator/SimulatorBoard.d.ts

@@ -0,0 +1,54 @@
+/**
+ * SimulatorBoard
+ *
+ * Parameter-slider game board. The player adjusts parameters
+ * and observes real-time output. Correct parameter values
+ * must bring the output within a target range to win.
+ *
+ * Good for: physics, economics, system design stories.
+ *
+ * Events emitted via completeEvent (default UI:PUZZLE_COMPLETE).
+ */
+import React from 'react';
+import type { EntityDisplayProps } from '../../../types';
+export interface SimulatorParameter {
+    id: string;
+    label: string;
+    unit: string;
+    min: number;
+    max: number;
+    step: number;
+    initial: number;
+    correct: number;
+    tolerance: number;
+}
+export interface SimulatorPuzzleEntity {
+    id: string;
+    title: string;
+    description: string;
+    parameters: SimulatorParameter[];
+    outputLabel: string;
+    outputUnit: string;
+    /** Pure function body as string: receives params object, returns number */
+    computeExpression: string;
+    targetValue: number;
+    targetTolerance: number;
+    successMessage?: string;
+    failMessage?: string;
+    hint?: string;
+    /** Header image URL displayed above the title */
+    headerImage?: string;
+    /** Visual theme overrides */
+    theme?: {
+        background?: string;
+        accentColor?: string;
+    };
+}
+export interface SimulatorBoardProps extends Omit<EntityDisplayProps, 'entity'> {
+    entity: SimulatorPuzzleEntity;
+    completeEvent?: string;
+}
+export declare function SimulatorBoard({ entity, completeEvent, className, }: SimulatorBoardProps): React.JSX.Element;
+export declare namespace SimulatorBoard {
+    var displayName: string;
+}

package/dist/components/organisms/game/puzzles/simulator/index.d.ts

@@ -0,0 +1,2 @@
+export { SimulatorBoard } from './SimulatorBoard';
+export type { SimulatorBoardProps, SimulatorPuzzleEntity, SimulatorParameter } from './SimulatorBoard';

package/dist/components/organisms/game/puzzles/state-architect/CodeView.d.ts

@@ -0,0 +1,24 @@
+/**
+ * CodeView Component
+ *
+ * Shows the JSON code representation of a state machine.
+ * Toggle between visual and code view in State Architect tier.
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+export interface CodeViewProps {
+    /** JSON data to display */
+    data: Record<string, unknown>;
+    /** Label */
+    label?: string;
+    /** Whether the code is expanded by default */
+    defaultExpanded?: boolean;
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function CodeView({ data, label, defaultExpanded, className, }: CodeViewProps): React.JSX.Element;
+export declare namespace CodeView {
+    var displayName: string;
+}
+export default CodeView;

package/dist/components/organisms/game/puzzles/state-architect/StateArchitectBoard.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 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 { EntityDisplayProps } from '../../../types';
+import { type VariableDef } from './VariablePanel';
+export interface StateArchitectTransition {
+    id: string;
+    from: string;
+    to: string;
+    event: string;
+    guardHint?: string;
+}
+export interface TestCase {
+    /** Sequence of events to fire */
+    events: string[];
+    /** Expected final state */
+    expectedState: string;
+    /** Description */
+    label: string;
+}
+export interface StateArchitectPuzzleEntity {
+    id: string;
+    title: string;
+    description: string;
+    hint: string;
+    /** Entity being designed */
+    entityName: string;
+    /** Variables with initial values */
+    variables: VariableDef[];
+    /** States provided (kid may need to add more) */
+    states: string[];
+    /** Initial state */
+    initialState: string;
+    /** Pre-existing transitions (puzzle may have some already) */
+    transitions: StateArchitectTransition[];
+    /** Events available to use */
+    availableEvents: string[];
+    /** States available to add */
+    availableStates?: string[];
+    /** Test cases to validate against */
+    testCases: TestCase[];
+    /** Show code view toggle */
+    showCodeView?: boolean;
+    /** Feedback */
+    successMessage?: string;
+    failMessage?: string;
+    /** Header image URL displayed above the title */
+    headerImage?: string;
+    /** Visual theme overrides */
+    theme?: {
+        background?: string;
+        accentColor?: string;
+    };
+}
+export interface StateArchitectBoardProps extends Omit<EntityDisplayProps, 'entity'> {
+    /** Puzzle data */
+    entity: StateArchitectPuzzleEntity;
+    /** Playback speed */
+    stepDurationMs?: number;
+    /** Emits UI:{testEvent} */
+    testEvent?: string;
+    /** Emits UI:{completeEvent} with { success, passedTests } */
+    completeEvent?: string;
+}
+export declare function StateArchitectBoard({ entity, stepDurationMs, testEvent, completeEvent, className, }: StateArchitectBoardProps): React.JSX.Element;
+export declare namespace StateArchitectBoard {
+    var displayName: string;
+}
+export default StateArchitectBoard;

package/dist/components/organisms/game/puzzles/state-architect/StateNode.d.ts

@@ -0,0 +1,33 @@
+/**
+ * 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';
+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: {
+        x: number;
+        y: number;
+    };
+    /** 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/organisms/game/puzzles/state-architect/TransitionArrow.d.ts

@@ -0,0 +1,36 @@
+/**
+ * TransitionArrow Component
+ *
+ * An SVG arrow connecting two state nodes in the graph editor.
+ * Shows the event name as a label on the arrow.
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+export interface TransitionArrowProps {
+    /** Start position (center of from-node) */
+    from: {
+        x: number;
+        y: number;
+    };
+    /** End position (center of to-node) */
+    to: {
+        x: number;
+        y: number;
+    };
+    /** Event label shown on the arrow */
+    eventLabel: string;
+    /** Guard hint shown below event */
+    guardHint?: string;
+    /** Whether this transition is currently active */
+    isActive?: boolean;
+    /** Click handler */
+    onClick?: () => void;
+    /** Additional CSS classes for the SVG group */
+    className?: string;
+}
+export declare function TransitionArrow({ from, to, eventLabel, guardHint, isActive, onClick, className, }: TransitionArrowProps): React.JSX.Element;
+export declare namespace TransitionArrow {
+    var displayName: string;
+}
+export default TransitionArrow;

package/dist/components/organisms/game/puzzles/state-architect/VariablePanel.d.ts

@@ -0,0 +1,28 @@
+/**
+ * VariablePanel Component
+ *
+ * Shows entity variables and their current values during State Architect playback.
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+export interface VariableDef {
+    name: string;
+    value: number;
+    min?: number;
+    max?: number;
+    unit?: string;
+}
+export interface VariablePanelProps {
+    /** Entity name */
+    entityName: string;
+    /** Variables to display */
+    variables: VariableDef[];
+    /** Additional CSS classes */
+    className?: string;
+}
+export declare function VariablePanel({ entityName, variables, className, }: VariablePanelProps): React.JSX.Element;
+export declare namespace VariablePanel {
+    var displayName: string;
+}
+export default VariablePanel;

package/dist/components/organisms/game/puzzles/state-architect/index.d.ts

@@ -0,0 +1,10 @@
+export { StateNode } from './StateNode';
+export type { StateNodeProps } from './StateNode';
+export { TransitionArrow } from './TransitionArrow';
+export type { TransitionArrowProps } from './TransitionArrow';
+export { VariablePanel } from './VariablePanel';
+export type { VariablePanelProps, VariableDef } from './VariablePanel';
+export { CodeView } from './CodeView';
+export type { CodeViewProps } from './CodeView';
+export { StateArchitectBoard } from './StateArchitectBoard';
+export type { StateArchitectBoardProps, StateArchitectPuzzleEntity, StateArchitectTransition, TestCase, } from './StateArchitectBoard';

package/dist/components/organisms/game/three/Camera3D.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Camera3D
+ *
+ * Three.js camera component with orbit controls.
+ * Supports isometric, perspective, and top-down camera modes.
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+import * as THREE from 'three';
+export type CameraMode = 'isometric' | 'perspective' | 'top-down';
+export interface Camera3DProps {
+    /** Camera mode */
+    mode?: CameraMode;
+    /** Initial camera position */
+    position?: [number, number, number];
+    /** Target to look at */
+    target?: [number, number, number];
+    /** Zoom level */
+    zoom?: number;
+    /** Field of view (perspective mode only) */
+    fov?: number;
+    /** Enable orbit controls */
+    enableOrbit?: boolean;
+    /** Minimum zoom distance */
+    minDistance?: number;
+    /** Maximum zoom distance */
+    maxDistance?: number;
+    /** Called when camera changes */
+    onChange?: (camera: THREE.Camera) => void;
+}
+export interface Camera3DHandle {
+    /** Get current camera */
+    getCamera: () => THREE.Camera;
+    /** Set camera position */
+    setPosition: (x: number, y: number, z: number) => void;
+    /** Look at target */
+    lookAt: (x: number, y: number, z: number) => void;
+    /** Reset to initial position */
+    reset: () => void;
+    /** Get current view bounds */
+    getViewBounds: () => {
+        min: THREE.Vector3;
+        max: THREE.Vector3;
+    };
+}
+/**
+ * Camera3D Component
+ *
+ * Configurable camera with orbit controls and multiple modes.
+ *
+ * @example
+ * ```tsx
+ * <Canvas>
+ *     <Camera3D mode="isometric" position={[10, 10, 10]} target={[0, 0, 0]} />
+ * </Canvas>
+ * ```
+ */
+export declare const Camera3D: React.ForwardRefExoticComponent<Camera3DProps & React.RefAttributes<Camera3DHandle>>;
+export default Camera3D;

package/dist/components/organisms/game/three/Lighting3D.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Lighting3D
+ *
+ * Default lighting setup for 3D game scenes.
+ * Includes ambient, directional, and optional point lights.
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+export interface Lighting3DProps {
+    /** Ambient light intensity */
+    ambientIntensity?: number;
+    /** Ambient light color */
+    ambientColor?: string;
+    /** Directional light intensity */
+    directionalIntensity?: number;
+    /** Directional light color */
+    directionalColor?: string;
+    /** Directional light position */
+    directionalPosition?: [number, number, number];
+    /** Enable shadows */
+    shadows?: boolean;
+    /** Shadow map size */
+    shadowMapSize?: number;
+    /** Shadow camera size */
+    shadowCameraSize?: number;
+    /** Show helper for directional light */
+    showHelpers?: boolean;
+}
+/**
+ * Lighting3D Component
+ *
+ * Pre-configured lighting setup for game scenes.
+ *
+ * @example
+ * ```tsx
+ * <Canvas>
+ *     <Lighting3D
+ *         ambientIntensity={0.6}
+ *         directionalIntensity={1.0}
+ *         shadows={true}
+ *     />
+ * </Canvas>
+ * ```
+ */
+export declare function Lighting3D({ ambientIntensity, ambientColor, directionalIntensity, directionalColor, directionalPosition, shadows, shadowMapSize, shadowCameraSize, showHelpers, }: Lighting3DProps): React.JSX.Element;
+export default Lighting3D;

package/dist/components/organisms/game/three/Scene3D.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Scene3D
+ *
+ * Three.js scene wrapper component for React Three Fiber.
+ * Manages the scene environment, fog, and background.
+ *
+ * @packageDocumentation
+ */
+import React from 'react';
+export interface Scene3DProps {
+    /** Background color or URL */
+    background?: string;
+    /** Fog configuration */
+    fog?: {
+        color: string;
+        near: number;
+        far: number;
+    };
+    /** Children to render in scene */
+    children?: React.ReactNode;
+}
+/**
+ * Scene3D Component
+ *
+ * Manages Three.js scene settings like background and fog.
+ *
+ * @example
+ * ```tsx
+ * <Canvas>
+ *     <Scene3D background="#1a1a2e" fog={{ color: '#1a1a2e', near: 10, far: 50 }}>
+ *         <GameObjects />
+ *     </Scene3D>
+ * </Canvas>
+ * ```
+ */
+export declare function Scene3D({ background, fog, children }: Scene3DProps): React.JSX.Element;
+export default Scene3D;