@almadar/ui 5.21.11 → 5.22.2

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

@@ -0,0 +1,44 @@
+/**
+ * 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 } 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: unknown): string;
+/** Coerce a field value to a number (0 when absent / non-numeric). */
+export declare function num(v: unknown, fallback?: number): number;
+/** Coerce a field value to a boolean. */
+export declare function bool(v: unknown): boolean;
+/** Coerce a nested array field to a readonly array of entity rows. */
+export declare function rows(v: unknown): readonly EntityRow[];
+/** Read an `{ x, y }` position off an entity row's named field. */
+export declare function vec2(v: unknown): 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/organisms/hooks/useBattleState.d.ts

@@ -1,5 +1,5 @@
-import type { EventEmit } from '@almadar/core';
-import type { BattleUnit, BattlePhase } from '../BattleBoard';
+import type { EventEmit, EntityRow } from '@almadar/core';
+import type { BattlePhase } from '../BattleBoard';
 export interface BattleStateEventConfig {
     tileClickEvent?: EventEmit<{
         x: number;
@@ -22,19 +22,19 @@ export interface BattleStateEventConfig {
 }
 export interface BattleStateCallbacks {
     /** Called when a unit attacks another */
-    onAttack?: (attacker: BattleUnit, target: BattleUnit, damage: number) => void;
+    onAttack?: (attacker: EntityRow, target: EntityRow, damage: number) => void;
     /** Called when battle ends */
     onGameEnd?: (result: 'victory' | 'defeat') => void;
     /** Called after a unit moves */
-    onUnitMove?: (unit: BattleUnit, to: {
+    onUnitMove?: (unit: EntityRow, to: {
         x: number;
         y: number;
     }) => void;
     /** Custom combat damage calculator */
-    calculateDamage?: (attacker: BattleUnit, target: BattleUnit) => number;
+    calculateDamage?: (attacker: EntityRow, target: EntityRow) => number;
 }
 export interface BattleStateResult {
-    units: BattleUnit[];
+    units: EntityRow[];
     selectedUnitId: string | null;
     phase: BattlePhase;
     turn: number;
@@ -44,4 +44,4 @@ export interface BattleStateResult {
     handleEndTurn: () => void;
     handleRestart: () => void;
 }
-export declare function useBattleState(initialUnits: BattleUnit[], eventConfig?: BattleStateEventConfig, callbacks?: BattleStateCallbacks): BattleStateResult;
+export declare function useBattleState(initialUnits: EntityRow[], eventConfig?: BattleStateEventConfig, callbacks?: BattleStateCallbacks): BattleStateResult;

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

@@ -27,11 +27,11 @@ export { GameMenu, type GameMenuProps, type MenuOption } from './GameMenu';
 export { GameOverScreen, type GameOverScreenProps, type GameOverStat, type GameOverAction } from './GameOverScreen';
 export { InventoryPanel, type InventoryPanelProps, type InventoryItem } from './InventoryPanel';
 export { DialogueBox, type DialogueBoxProps, type DialogueNode, type DialogueChoice } from './DialogueBox';
-export { BattleBoard, type BattleBoardProps, type BattleEntity, type BattlePhase, type BattleUnit, type BattleTile, type BattleSlotContext, } from './BattleBoard';
+export { BattleBoard, type BattleBoardProps, type BattlePhase, type BattleSlotContext, } from './BattleBoard';
 export { UncontrolledBattleBoard, type UncontrolledBattleBoardProps, } from './UncontrolledBattleBoard';
 export { useBattleState, type BattleStateEventConfig, type BattleStateCallbacks, type BattleStateResult, } from './hooks/useBattleState';
-export { WorldMapBoard, type WorldMapBoardProps, type WorldMapEntity, type MapHero, type MapHex, type WorldMapSlotContext, } from './WorldMapBoard';
-export { CastleBoard, type CastleBoardProps, type CastleEntity, type CastleSlotContext, } from './CastleBoard';
+export { WorldMapBoard, type WorldMapBoardProps, type WorldMapSlotContext, } from './WorldMapBoard';
+export { CastleBoard, type CastleBoardProps, type CastleSlotContext, } from './CastleBoard';
 export { TraitStateViewer, type TraitStateViewerProps, type TraitStateMachineDefinition, type TraitTransition, } from './TraitStateViewer';
 export { TraitSlot, type TraitSlotProps, type SlotItemData, } from './TraitSlot';
 export { CollapsibleSection, EditorSlider, EditorSelect, EditorCheckbox, EditorTextInput, StatusBar, TerrainPalette, EditorToolbar, TERRAIN_COLORS, FEATURE_TYPES, type EditorMode, type CollapsibleSectionProps, type EditorSliderProps, type EditorSelectProps, type EditorCheckboxProps, type EditorTextInputProps, type StatusBarProps, type TerrainPaletteProps, type EditorToolbarProps, } from './editor';

package/dist/components/game/organisms/puzzles/builder/BuilderBoard.d.ts

@@ -10,7 +10,8 @@
  */
 import React from 'react';
 import type { EventEmit, EntityRow } from '@almadar/core';
-import type { EntityDisplayProps } from '../../../../core/organisms/types';
+import type { DisplayStateProps } from '../../../../core/organisms/types';
+/** A draggable build component (UI value DTO read off the entity). */
 export interface BuilderComponent {
     id: string;
     label: string;
@@ -20,31 +21,17 @@ export interface BuilderComponent {
     iconUrl?: string;
     category?: string;
 }
+/** A blueprint slot accepting a component (UI value DTO read off the entity). */
 export interface BuilderSlot {
     id: string;
     label: string;
     description?: string;
     acceptsComponentId: string;
 }
-export interface BuilderPuzzleEntity {
-    id: string;
-    title: string;
-    description: string;
-    components: BuilderComponent[];
-    slots: BuilderSlot[];
-    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 BuilderBoardProps extends Omit<EntityDisplayProps, 'entity'> {
-    entity?: BuilderPuzzleEntity | EntityRow | readonly (BuilderPuzzleEntity | EntityRow)[];
+export interface BuilderBoardProps extends DisplayStateProps {
+    /** Puzzle board-state entity (single row or array). The board reads
+     *  `components` / `slots` arrays plus title/description/hint off the row. */
+    entity?: EntityRow | readonly EntityRow[];
     completeEvent?: EventEmit<{
         success: boolean;
         attempts: number;

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

@@ -1,2 +1,2 @@
 export { BuilderBoard } from './BuilderBoard';
-export type { BuilderBoardProps, BuilderPuzzleEntity, BuilderComponent, BuilderSlot } from './BuilderBoard';
+export type { BuilderBoardProps, BuilderComponent, BuilderSlot } from './BuilderBoard';

package/dist/components/game/organisms/puzzles/classifier/ClassifierBoard.d.ts

@@ -11,7 +11,8 @@
  */
 import React from 'react';
 import type { EventEmit, EntityRow } from '@almadar/core';
-import type { EntityDisplayProps } from '../../../../core/organisms/types';
+import type { DisplayStateProps } from '../../../../core/organisms/types';
+/** A sortable item (UI value DTO read off the entity). */
 export interface ClassifierItem {
     id: string;
     label: string;
@@ -20,6 +21,7 @@ export interface ClassifierItem {
     /** Image URL icon for story-specific visual skin */
     iconUrl?: string;
 }
+/** A category bucket (UI value DTO read off the entity). */
 export interface ClassifierCategory {
     id: string;
     label: string;
@@ -27,25 +29,10 @@ export interface ClassifierCategory {
     /** Image URL for story-specific category header */
     imageUrl?: string;
 }
-export interface ClassifierPuzzleEntity {
-    id: string;
-    title: string;
-    description: string;
-    items: ClassifierItem[];
-    categories: ClassifierCategory[];
-    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 ClassifierBoardProps extends Omit<EntityDisplayProps, 'entity'> {
-    entity?: ClassifierPuzzleEntity | EntityRow | readonly (ClassifierPuzzleEntity | EntityRow)[];
+export interface ClassifierBoardProps extends DisplayStateProps {
+    /** Puzzle board-state entity (single row or array). The board reads
+     *  `items` / `categories` arrays plus title/description/hint off the row. */
+    entity?: EntityRow | readonly EntityRow[];
     completeEvent?: EventEmit<{
         success: boolean;
         attempts: number;

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

@@ -1,2 +1,2 @@
 export { ClassifierBoard } from './ClassifierBoard';
-export type { ClassifierBoardProps, ClassifierPuzzleEntity, ClassifierItem, ClassifierCategory } from './ClassifierBoard';
+export type { ClassifierBoardProps, ClassifierItem, ClassifierCategory } from './ClassifierBoard';

package/dist/components/game/organisms/puzzles/debugger/DebuggerBoard.d.ts

@@ -10,34 +10,18 @@
  */
 import React from 'react';
 import type { EventEmit, EntityRow } from '@almadar/core';
-import type { EntityDisplayProps } from '../../../../core/organisms/types';
+import type { DisplayStateProps } from '../../../../core/organisms/types';
+/** A reviewable code line (UI value DTO read off the entity). */
 export interface DebuggerLine {
     id: string;
     content: string;
     isBug: boolean;
     explanation?: string;
 }
-export interface DebuggerPuzzleEntity {
-    id: string;
-    title: string;
-    description: string;
-    language?: string;
-    lines: DebuggerLine[];
-    /** How many bugs the player should find */
-    bugCount: 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 DebuggerBoardProps extends Omit<EntityDisplayProps, 'entity'> {
-    entity?: DebuggerPuzzleEntity | EntityRow | readonly (DebuggerPuzzleEntity | EntityRow)[];
+export interface DebuggerBoardProps extends DisplayStateProps {
+    /** Puzzle board-state entity (single row or array). The board reads
+     *  `lines` array plus title/description/bugCount/hint off the row. */
+    entity?: EntityRow | readonly EntityRow[];
     completeEvent?: EventEmit<{
         success: boolean;
         attempts: number;

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

@@ -1,2 +1,2 @@
 export { DebuggerBoard } from './DebuggerBoard';
-export type { DebuggerBoardProps, DebuggerPuzzleEntity, DebuggerLine } from './DebuggerBoard';
+export type { DebuggerBoardProps, DebuggerLine } from './DebuggerBoard';

package/dist/components/game/organisms/puzzles/event-handler/EventHandlerBoard.d.ts

@@ -12,39 +12,12 @@
  */
 import React from 'react';
 import type { EventEmit, EntityRow } from '@almadar/core';
-import type { EntityDisplayProps } from '../../../../core/organisms/types';
-import { type PuzzleObjectDef } from './ObjectRulePanel';
-export interface EventHandlerPuzzleEntity {
-    id: string;
-    title: string;
-    description: string;
-    /** Objects the kid can configure */
-    objects: PuzzleObjectDef[];
-    /** Goal condition description */
-    goalCondition: string;
-    /** Event that represents goal completion */
-    goalEvent: string;
-    /** Sequence of events that auto-fire to start the simulation */
-    triggerEvents?: string[];
-    /** Feedback */
-    successMessage?: string;
-    failMessage?: string;
-    /** Progressive hint shown after 3 failures */
-    hint?: string;
-    /** Header image URL displayed above the title */
-    headerImage?: string;
-    /** Visual theme overrides */
-    theme?: {
-        background?: string;
-        accentColor?: string;
-    };
-}
-export interface EventHandlerBoardProps extends Omit<EntityDisplayProps, 'entity'> {
-    /** Puzzle data. The compiler binds the generic `EntityRow`, so the inlet
-     *  accepts it (and arrays) as union members; the component narrows to its
-     *  curated `EventHandlerPuzzleEntity` read-shape below (a valid
-     *  union-narrow) and renders nothing until a puzzle entity is present. */
-    entity?: EventHandlerPuzzleEntity | EntityRow | readonly (EventHandlerPuzzleEntity | EntityRow)[];
+import type { DisplayStateProps } from '../../../../core/organisms/types';
+export interface EventHandlerBoardProps extends DisplayStateProps {
+    /** Puzzle board-state entity (single row or array). The board reads
+     *  `objects` / `triggerEvents` / `goalEvent` etc. off the row; the editable
+     *  puzzle objects are themselves `EntityRow`s carried under `objects`. */
+    entity?: EntityRow | readonly EntityRow[];
     /** Playback speed in ms per event */
     stepDurationMs?: number;
     /** Emits UI:{playEvent} */

package/dist/components/game/organisms/puzzles/event-handler/ObjectRulePanel.d.ts

@@ -8,29 +8,11 @@
  * @packageDocumentation
  */
 import React from 'react';
+import type { EntityRow } from '@almadar/core';
 import { type RuleDefinition } from './RuleEditor';
-export type PuzzleObjectDef = {
-    id: string;
-    name: string;
-    icon: string;
-    states: string[];
-    initialState: string;
-    currentState: string;
-    availableEvents: Array<{
-        value: string;
-        label: string;
-    }>;
-    availableActions: Array<{
-        value: string;
-        label: string;
-    }>;
-    rules: RuleDefinition[];
-    /** Max rules allowed on this object */
-    maxRules?: number;
-};
 export interface ObjectRulePanelProps {
-    /** The selected object */
-    object: PuzzleObjectDef;
+    /** The selected puzzle-object row (`EntityRow` carrying the editable object data) */
+    object: EntityRow;
     /** Called when rules change */
     onRulesChange: (objectId: string, rules: RuleDefinition[]) => void;
     /** Whether editing is disabled */

package/dist/components/game/organisms/puzzles/event-handler/index.d.ts

@@ -3,6 +3,6 @@ export type { RuleEditorProps, RuleDefinition } from './RuleEditor';
 export { EventLog } from './EventLog';
 export type { EventLogProps, EventLogEntry } from './EventLog';
 export { ObjectRulePanel } from './ObjectRulePanel';
-export type { ObjectRulePanelProps, PuzzleObjectDef } from './ObjectRulePanel';
+export type { ObjectRulePanelProps } from './ObjectRulePanel';
 export { EventHandlerBoard } from './EventHandlerBoard';
-export type { EventHandlerBoardProps, EventHandlerPuzzleEntity } from './EventHandlerBoard';
+export type { EventHandlerBoardProps } from './EventHandlerBoard';

package/dist/components/game/organisms/puzzles/event-handler/puzzleObject.d.ts

@@ -0,0 +1,21 @@
+/**
+ * puzzleObject — field accessors for reading Event-Handler puzzle-object data
+ * off an `EntityRow`.
+ *
+ * The puzzle objects the kid configures arrive as `entity.objects` (an array of
+ * `EntityRow`). These helpers narrow the weakly-typed fields the panel reads.
+ * `RuleDefinition` / `RuleOption` remain plain UI value DTOs (see `RuleEditor`).
+ *
+ * @packageDocumentation
+ */
+import type { EntityRow } from '@almadar/core';
+import type { RuleDefinition, RuleOption } from './RuleEditor';
+export declare function objId(o: EntityRow): string;
+export declare function objName(o: EntityRow): string;
+export declare function objIcon(o: EntityRow): string;
+export declare function objStates(o: EntityRow): string[];
+export declare function objCurrentState(o: EntityRow): string;
+export declare function objAvailableEvents(o: EntityRow): RuleOption[];
+export declare function objAvailableActions(o: EntityRow): RuleOption[];
+export declare function objRules(o: EntityRow): RuleDefinition[];
+export declare function objMaxRules(o: EntityRow): number;

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

@@ -12,41 +12,25 @@
  */
 import React from 'react';
 import type { EventEmit, EntityRow } from '@almadar/core';
-import type { EntityDisplayProps } from '../../../../core/organisms/types';
+import type { DisplayStateProps } from '../../../../core/organisms/types';
+/** A selectable round action (UI value DTO read off the entity). */
 export interface NegotiatorAction {
     id: string;
     label: string;
     description?: string;
 }
+/** A payoff-matrix cell (UI value DTO read off the entity). */
 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 | EntityRow | readonly (NegotiatorPuzzleEntity | EntityRow)[];
+export interface NegotiatorBoardProps extends DisplayStateProps {
+    /** Puzzle board-state entity (single row or array). The board reads
+     *  `actions` / `payoffMatrix` arrays plus title/description/rounds/hint off
+     *  the row. */
+    entity?: EntityRow | readonly EntityRow[];
     completeEvent?: EventEmit<{
         success: boolean;
         score: number;

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

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

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

@@ -8,9 +8,9 @@
  * @packageDocumentation
  */
 import React from 'react';
-import type { EntityDisplayProps } from '../../../../core/organisms/types';
+import type { DisplayStateProps } from '../../../../core/organisms/types';
 import type { SlotItemData } from '../../TraitSlot';
-export interface ActionTileProps extends Omit<EntityDisplayProps, 'entity'> {
+export interface ActionTileProps extends DisplayStateProps {
     /** The action data */
     action: SlotItemData;
     /** Size variant */

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

@@ -19,42 +19,13 @@
  */
 import React from 'react';
 import type { EventEmit, EntityRow } from '@almadar/core';
-import type { SlotItemData } from '../../TraitSlot';
-import type { EntityDisplayProps } from '../../../../core/organisms/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. Also accepts the canonical `EntityRow` the compiler binds
-     *  (and arrays); narrowed to `SequencerPuzzleEntity` internally. */
-    entity?: SequencerPuzzleEntity | EntityRow | readonly (SequencerPuzzleEntity | EntityRow)[];
+import type { DisplayStateProps } from '../../../../core/organisms/types';
+export interface SequencerBoardProps extends DisplayStateProps {
+    /** Puzzle board-state entity (single row or array). The board reads
+     *  `availableActions` / `maxSlots` / `solutions` etc. off the row.
+     *  `availableActions` carries `SlotItemData[]` (a UI drag-DTO, not entity
+     *  data — it holds a non-FieldValue `stateMachine` member). */
+    entity?: EntityRow | readonly EntityRow[];
     /** Category → color mapping */
     categoryColors?: Record<string, {
         bg: string;

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

@@ -5,4 +5,4 @@ export type { ActionPaletteProps } from './ActionPalette';
 export { SequenceBar } from './SequenceBar';
 export type { SequenceBarProps } from './SequenceBar';
 export { SequencerBoard } from './SequencerBoard';
-export type { SequencerBoardProps, SequencerPuzzleEntity } from './SequencerBoard';
+export type { SequencerBoardProps } from './SequencerBoard';

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

@@ -11,7 +11,8 @@
  */
 import React from 'react';
 import type { EventEmit, EntityRow } from '@almadar/core';
-import type { EntityDisplayProps } from '../../../../core/organisms/types';
+import type { DisplayStateProps } from '../../../../core/organisms/types';
+/** A tunable simulation parameter (UI value DTO read off the entity). */
 export interface SimulatorParameter {
     id: string;
     label: string;
@@ -23,30 +24,10 @@ export interface SimulatorParameter {
     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 | EntityRow | readonly (SimulatorPuzzleEntity | EntityRow)[];
+export interface SimulatorBoardProps extends DisplayStateProps {
+    /** Puzzle board-state entity (single row or array). The board reads the
+     *  `parameters` array plus title/description/target/hint off the row. */
+    entity?: EntityRow | readonly EntityRow[];
     completeEvent?: EventEmit<{
         success: boolean;
         attempts: number;

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

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

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

@@ -9,8 +9,8 @@
  */
 import React from 'react';
 import type { EventEmit, EntityRow } from '@almadar/core';
-import type { EntityDisplayProps } from '../../../../core/organisms/types';
-import { type VariableDef } from './VariablePanel';
+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;
@@ -18,6 +18,7 @@ export interface StateArchitectTransition {
     event: string;
     guardHint?: string;
 }
+/** A puzzle test case (UI value DTO). */
 export interface TestCase {
     /** Sequence of events to fire */
     events: string[];
@@ -26,44 +27,10 @@ export interface TestCase {
     /** 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. Also accepts the canonical `EntityRow` the compiler binds
-     *  (and arrays); narrowed to `StateArchitectPuzzleEntity` internally. */
-    entity?: StateArchitectPuzzleEntity | EntityRow | readonly (StateArchitectPuzzleEntity | EntityRow)[];
+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} */

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

@@ -6,18 +6,12 @@
  * @packageDocumentation
  */
 import React from 'react';
-export interface VariableDef {
-    name: string;
-    value: number;
-    min?: number;
-    max?: number;
-    unit?: string;
-}
+import type { EntityRow } from '@almadar/core';
 export interface VariablePanelProps {
     /** Entity name */
     entityName: string;
-    /** Variables to display */
-    variables: VariableDef[];
+    /** Variable rows to display (`EntityRow` carrying name/value/min/max/unit) */
+    variables: readonly EntityRow[];
     /** Additional CSS classes */
     className?: string;
 }

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

@@ -3,8 +3,8 @@ 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 type { VariablePanelProps } from './VariablePanel';
 export { CodeView } from './CodeView';
 export type { CodeViewProps } from './CodeView';
 export { StateArchitectBoard } from './StateArchitectBoard';
-export type { StateArchitectBoardProps, StateArchitectPuzzleEntity, StateArchitectTransition, TestCase, } from './StateArchitectBoard';
+export type { StateArchitectBoardProps, StateArchitectTransition, TestCase, } from './StateArchitectBoard';