@almadar/ui 2.10.0 → 2.11.1

package/dist/lib/index.d.ts

@@ -1,6 +1,179 @@
-export { C as ContentSegment, D as DEFAULT_CONFIG, a as DomEntityBox, b as DomLayoutData, c as DomOutputsBox, d as DomStateNode, e as DomTransitionLabel, f as DomTransitionPath, E as EntityDefinition, R as RenderOptions, S as StateDefinition, g as StateMachineDefinition, T as TransitionDefinition, V as VisualizerConfig, h as cn, i as extractOutputsFromTransitions, j as extractStateMachine, k as formatGuard, l as getEffectSummary, p as parseContentSegments, m as parseMarkdownWithCodeBlocks, r as renderStateMachineToDomData, n as renderStateMachineToSvg } from '../cn-BoBXsxuX.js';
+export { A as AssetLoadStatus, B as BridgeHealth, C as CheckStatus, a as ContentSegment, D as DEFAULT_CONFIG, b as DomEntityBox, c as DomLayoutData, d as DomOutputsBox, e as DomStateNode, f as DomTransitionLabel, g as DomTransitionPath, E as EffectTrace, h as EntityDefinition, i as EventLogEntry, R as RenderOptions, S as StateDefinition, j as StateMachineDefinition, T as TransitionDefinition, k as TransitionTrace, V as VerificationCheck, l as VerificationSnapshot, m as VerificationSummary, n as VisualizerConfig, o as bindCanvasCapture, p as bindEventBus, q as bindTraitStateGetter, r as clearVerification, s as cn, t as extractOutputsFromTransitions, u as extractStateMachine, v as formatGuard, w as getAllChecks, x as getBridgeHealth, y as getEffectSummary, z as getSnapshot, F as getSummary, G as getTransitions, H as getTransitionsForTrait, I as parseContentSegments, J as parseMarkdownWithCodeBlocks, K as recordTransition, L as registerCheck, M as renderStateMachineToDomData, N as renderStateMachineToSvg, O as subscribeToVerification, P as updateAssetStatus, Q as updateBridgeHealth, U as updateCheck, W as waitForTransition } from '../cn-C_ATNPvi.js';
 import 'clsx';
 
+/**
+ * Trait Registry - Tracks active traits and their state machines for debugging
+ *
+ * @packageDocumentation
+ */
+interface TraitTransition {
+    from: string;
+    to: string;
+    event: string;
+    guard?: string;
+}
+interface TraitGuard {
+    name: string;
+    lastResult?: boolean;
+}
+interface TraitDebugInfo {
+    id: string;
+    name: string;
+    currentState: string;
+    states: string[];
+    transitions: TraitTransition[];
+    guards: TraitGuard[];
+    transitionCount: number;
+}
+type ChangeListener$3 = () => void;
+declare function registerTrait(info: TraitDebugInfo): void;
+declare function updateTraitState(id: string, newState: string): void;
+declare function updateGuardResult(traitId: string, guardName: string, result: boolean): void;
+declare function unregisterTrait(id: string): void;
+declare function getAllTraits(): TraitDebugInfo[];
+declare function getTrait(id: string): TraitDebugInfo | undefined;
+declare function subscribeToTraitChanges(listener: ChangeListener$3): () => void;
+declare function clearTraits(): void;
+
+/**
+ * Tick Registry - Tracks scheduled tick executions for debugging
+ *
+ * @packageDocumentation
+ */
+interface TickExecution {
+    id: string;
+    traitName: string;
+    /** Tick name (display name) */
+    name: string;
+    /** Tick identifier */
+    tickName: string;
+    interval: number;
+    /** Last execution timestamp */
+    lastRun: number;
+    lastExecuted: number | null;
+    nextExecution: number | null;
+    /** Number of times this tick has run */
+    runCount: number;
+    executionCount: number;
+    /** Average execution time in ms */
+    executionTime: number;
+    /** Whether the tick is currently active */
+    active: boolean;
+    isActive: boolean;
+    /** Guard name if this tick has a guard */
+    guardName?: string;
+    /** Whether the guard passed on last evaluation */
+    guardPassed?: boolean;
+}
+type ChangeListener$2 = () => void;
+declare function registerTick(tick: TickExecution): void;
+declare function updateTickExecution(id: string, timestamp: number): void;
+declare function setTickActive(id: string, isActive: boolean): void;
+declare function unregisterTick(id: string): void;
+declare function getAllTicks(): TickExecution[];
+declare function getTick(id: string): TickExecution | undefined;
+declare function subscribeToTickChanges(listener: ChangeListener$2): () => void;
+declare function clearTicks(): void;
+
+/**
+ * Guard Registry - Tracks guard evaluations for debugging
+ *
+ * @packageDocumentation
+ */
+interface GuardContext {
+    traitName?: string;
+    type?: "transition" | "tick";
+    transitionFrom?: string;
+    transitionTo?: string;
+    tickName?: string;
+    [key: string]: unknown;
+}
+interface GuardEvaluation {
+    id: string;
+    traitName: string;
+    guardName: string;
+    expression: string;
+    result: boolean;
+    context: GuardContext;
+    timestamp: number;
+    /** Input values used in guard evaluation */
+    inputs: Record<string, unknown>;
+}
+type ChangeListener$1 = () => void;
+declare function recordGuardEvaluation(evaluation: Omit<GuardEvaluation, "id" | "timestamp">): void;
+declare function getGuardHistory(): GuardEvaluation[];
+declare function getRecentGuardEvaluations(count: number): GuardEvaluation[];
+declare function getGuardEvaluationsForTrait(traitName: string): GuardEvaluation[];
+declare function subscribeToGuardChanges(listener: ChangeListener$1): () => void;
+declare function clearGuardHistory(): void;
+
+/**
+ * Entity Debug - Provides entity state snapshots for debugging
+ *
+ * @packageDocumentation
+ */
+interface EntityState {
+    id: string;
+    type: string;
+    fields: Record<string, unknown>;
+    lastUpdated: number;
+}
+interface RuntimeEntity {
+    id: string;
+    type: string;
+    data: Record<string, unknown>;
+}
+interface PersistentEntityInfo {
+    loaded: boolean;
+    count: number;
+}
+interface EntitySnapshot {
+    entities: EntityState[];
+    timestamp: number;
+    totalCount: number;
+    /** Singleton entities by name */
+    singletons: Record<string, unknown>;
+    /** Runtime entities (in-memory) */
+    runtime: RuntimeEntity[];
+    /** Persistent entities info by type */
+    persistent: Record<string, PersistentEntityInfo>;
+}
+type EntityProvider = () => EntityState[];
+declare function setEntityProvider(provider: EntityProvider): void;
+declare function clearEntityProvider(): void;
+declare function getEntitySnapshot(): EntitySnapshot | null;
+declare function getEntityById(id: string): EntityState | undefined;
+declare function getEntitiesByType(type: string): EntityState[];
+
+/**
+ * Debug Registry - Central event log for debugging
+ *
+ * @packageDocumentation
+ */
+type DebugEventType = 'state-change' | 'event-fired' | 'effect-executed' | 'guard-evaluated' | 'error' | 'warning' | 'info';
+interface DebugEvent {
+    id: string;
+    type: DebugEventType;
+    source: string;
+    message: string;
+    data?: Record<string, unknown>;
+    timestamp: number;
+}
+type ChangeListener = () => void;
+declare function logDebugEvent(type: DebugEventType, source: string, message: string, data?: Record<string, unknown>): void;
+declare function logStateChange(source: string, from: string, to: string, event?: string): void;
+declare function logEventFired(source: string, eventName: string, payload?: unknown): void;
+declare function logEffectExecuted(source: string, effectType: string, details?: unknown): void;
+declare function logError(source: string, message: string, error?: unknown): void;
+declare function logWarning(source: string, message: string, data?: Record<string, unknown>): void;
+declare function logInfo(source: string, message: string, data?: Record<string, unknown>): void;
+declare function getDebugEvents(): DebugEvent[];
+declare function getRecentEvents(count: number): DebugEvent[];
+declare function getEventsByType(type: DebugEventType): DebugEvent[];
+declare function getEventsBySource(source: string): DebugEvent[];
+declare function subscribeToDebugEvents(listener: ChangeListener): () => void;
+declare function clearDebugEvents(): void;
+
 /**
  * API Client - HTTP client for backend API calls
  *
@@ -110,317 +283,6 @@ declare function onDebugToggle(listener: DebugToggleListener): () => void;
  */
 declare function initDebugShortcut(): () => void;
 
-/**
- * Entity Debug - Provides entity state snapshots for debugging
- *
- * @packageDocumentation
- */
-interface EntityState {
-    id: string;
-    type: string;
-    fields: Record<string, unknown>;
-    lastUpdated: number;
-}
-interface RuntimeEntity {
-    id: string;
-    type: string;
-    data: Record<string, unknown>;
-}
-interface PersistentEntityInfo {
-    loaded: boolean;
-    count: number;
-}
-interface EntitySnapshot {
-    entities: EntityState[];
-    timestamp: number;
-    totalCount: number;
-    /** Singleton entities by name */
-    singletons: Record<string, unknown>;
-    /** Runtime entities (in-memory) */
-    runtime: RuntimeEntity[];
-    /** Persistent entities info by type */
-    persistent: Record<string, PersistentEntityInfo>;
-}
-type EntityProvider = () => EntityState[];
-declare function setEntityProvider(provider: EntityProvider): void;
-declare function clearEntityProvider(): void;
-declare function getEntitySnapshot(): EntitySnapshot | null;
-declare function getEntityById(id: string): EntityState | undefined;
-declare function getEntitiesByType(type: string): EntityState[];
-
-/**
- * Debug Registry - Central event log for debugging
- *
- * @packageDocumentation
- */
-type DebugEventType = 'state-change' | 'event-fired' | 'effect-executed' | 'guard-evaluated' | 'error' | 'warning' | 'info';
-interface DebugEvent {
-    id: string;
-    type: DebugEventType;
-    source: string;
-    message: string;
-    data?: Record<string, unknown>;
-    timestamp: number;
-}
-type ChangeListener$4 = () => void;
-declare function logDebugEvent(type: DebugEventType, source: string, message: string, data?: Record<string, unknown>): void;
-declare function logStateChange(source: string, from: string, to: string, event?: string): void;
-declare function logEventFired(source: string, eventName: string, payload?: unknown): void;
-declare function logEffectExecuted(source: string, effectType: string, details?: unknown): void;
-declare function logError(source: string, message: string, error?: unknown): void;
-declare function logWarning(source: string, message: string, data?: Record<string, unknown>): void;
-declare function logInfo(source: string, message: string, data?: Record<string, unknown>): void;
-declare function getDebugEvents(): DebugEvent[];
-declare function getRecentEvents(count: number): DebugEvent[];
-declare function getEventsByType(type: DebugEventType): DebugEvent[];
-declare function getEventsBySource(source: string): DebugEvent[];
-declare function subscribeToDebugEvents(listener: ChangeListener$4): () => void;
-declare function clearDebugEvents(): void;
-
-/**
- * Guard Registry - Tracks guard evaluations for debugging
- *
- * @packageDocumentation
- */
-interface GuardContext {
-    traitName?: string;
-    type?: "transition" | "tick";
-    transitionFrom?: string;
-    transitionTo?: string;
-    tickName?: string;
-    [key: string]: unknown;
-}
-interface GuardEvaluation {
-    id: string;
-    traitName: string;
-    guardName: string;
-    expression: string;
-    result: boolean;
-    context: GuardContext;
-    timestamp: number;
-    /** Input values used in guard evaluation */
-    inputs: Record<string, unknown>;
-}
-type ChangeListener$3 = () => void;
-declare function recordGuardEvaluation(evaluation: Omit<GuardEvaluation, "id" | "timestamp">): void;
-declare function getGuardHistory(): GuardEvaluation[];
-declare function getRecentGuardEvaluations(count: number): GuardEvaluation[];
-declare function getGuardEvaluationsForTrait(traitName: string): GuardEvaluation[];
-declare function subscribeToGuardChanges(listener: ChangeListener$3): () => void;
-declare function clearGuardHistory(): void;
-
-/**
- * Tick Registry - Tracks scheduled tick executions for debugging
- *
- * @packageDocumentation
- */
-interface TickExecution {
-    id: string;
-    traitName: string;
-    /** Tick name (display name) */
-    name: string;
-    /** Tick identifier */
-    tickName: string;
-    interval: number;
-    /** Last execution timestamp */
-    lastRun: number;
-    lastExecuted: number | null;
-    nextExecution: number | null;
-    /** Number of times this tick has run */
-    runCount: number;
-    executionCount: number;
-    /** Average execution time in ms */
-    executionTime: number;
-    /** Whether the tick is currently active */
-    active: boolean;
-    isActive: boolean;
-    /** Guard name if this tick has a guard */
-    guardName?: string;
-    /** Whether the guard passed on last evaluation */
-    guardPassed?: boolean;
-}
-type ChangeListener$2 = () => void;
-declare function registerTick(tick: TickExecution): void;
-declare function updateTickExecution(id: string, timestamp: number): void;
-declare function setTickActive(id: string, isActive: boolean): void;
-declare function unregisterTick(id: string): void;
-declare function getAllTicks(): TickExecution[];
-declare function getTick(id: string): TickExecution | undefined;
-declare function subscribeToTickChanges(listener: ChangeListener$2): () => void;
-declare function clearTicks(): void;
-
-/**
- * Trait Registry - Tracks active traits and their state machines for debugging
- *
- * @packageDocumentation
- */
-interface TraitTransition {
-    from: string;
-    to: string;
-    event: string;
-    guard?: string;
-}
-interface TraitGuard {
-    name: string;
-    lastResult?: boolean;
-}
-interface TraitDebugInfo {
-    id: string;
-    name: string;
-    currentState: string;
-    states: string[];
-    transitions: TraitTransition[];
-    guards: TraitGuard[];
-    transitionCount: number;
-}
-type ChangeListener$1 = () => void;
-declare function registerTrait(info: TraitDebugInfo): void;
-declare function updateTraitState(id: string, newState: string): void;
-declare function updateGuardResult(traitId: string, guardName: string, result: boolean): void;
-declare function unregisterTrait(id: string): void;
-declare function getAllTraits(): TraitDebugInfo[];
-declare function getTrait(id: string): TraitDebugInfo | undefined;
-declare function subscribeToTraitChanges(listener: ChangeListener$1): () => void;
-declare function clearTraits(): void;
-
-/**
- * Verification Registry - Tracks runtime verification checks and transition traces
- *
- * Provides:
- * 1. A checklist of pass/fail checks (INIT has fetch, bridge connected, etc.)
- * 2. A full transition timeline with effect execution results
- * 3. ServerBridge health snapshot
- * 4. window.__orbitalVerification for Playwright/automation
- *
- * @packageDocumentation
- */
-type CheckStatus = "pass" | "fail" | "pending" | "warn";
-interface VerificationCheck {
-    id: string;
-    label: string;
-    status: CheckStatus;
-    details?: string;
-    /** Timestamp when status last changed */
-    updatedAt: number;
-}
-interface EffectTrace {
-    type: string;
-    args: unknown[];
-    status: "executed" | "failed" | "skipped";
-    error?: string;
-    durationMs?: number;
-}
-interface TransitionTrace {
-    id: string;
-    traitName: string;
-    from: string;
-    to: string;
-    event: string;
-    guardExpression?: string;
-    guardResult?: boolean;
-    effects: EffectTrace[];
-    timestamp: number;
-}
-interface BridgeHealth {
-    connected: boolean;
-    eventsForwarded: number;
-    eventsReceived: number;
-    lastError?: string;
-    lastHeartbeat: number;
-}
-interface VerificationSummary {
-    totalChecks: number;
-    passed: number;
-    failed: number;
-    warnings: number;
-    pending: number;
-}
-interface VerificationSnapshot {
-    checks: VerificationCheck[];
-    transitions: TransitionTrace[];
-    bridge: BridgeHealth | null;
-    summary: VerificationSummary;
-}
-type ChangeListener = () => void;
-declare function registerCheck(id: string, label: string, status?: CheckStatus, details?: string): void;
-declare function updateCheck(id: string, status: CheckStatus, details?: string): void;
-declare function getAllChecks(): VerificationCheck[];
-declare function recordTransition(trace: Omit<TransitionTrace, "id">): void;
-declare function getTransitions(): TransitionTrace[];
-declare function getTransitionsForTrait(traitName: string): TransitionTrace[];
-declare function updateBridgeHealth(health: BridgeHealth): void;
-declare function getBridgeHealth(): BridgeHealth | null;
-declare function getSummary(): VerificationSummary;
-declare function getSnapshot(): VerificationSnapshot;
-declare function subscribeToVerification(listener: ChangeListener): () => void;
-/** Asset load status for canvas verification */
-type AssetLoadStatus = "loaded" | "failed" | "pending";
-/** Event bus log entry for verification */
-interface EventLogEntry {
-    type: string;
-    payload?: Record<string, unknown>;
-    timestamp: number;
-}
-/** Exposed on window for Playwright to query */
-interface OrbitalVerificationAPI {
-    getSnapshot: () => VerificationSnapshot;
-    getChecks: () => VerificationCheck[];
-    getTransitions: () => TransitionTrace[];
-    getBridge: () => BridgeHealth | null;
-    getSummary: () => VerificationSummary;
-    /** Wait for a specific event to be processed */
-    waitForTransition: (event: string, timeoutMs?: number) => Promise<TransitionTrace | null>;
-    /** Send an event into the runtime (requires eventBus binding) */
-    sendEvent?: (event: string, payload?: Record<string, unknown>) => void;
-    /** Get current trait state */
-    getTraitState?: (traitName: string) => string | undefined;
-    /** Capture a canvas frame as PNG data URL. Registered by game organisms. */
-    captureFrame?: () => string | null;
-    /** Asset load status map. Registered by game organisms. */
-    assetStatus?: Record<string, AssetLoadStatus>;
-    /** Event bus log. Records all emit() calls for verification. */
-    eventLog?: EventLogEntry[];
-    /** Clear the event log. */
-    clearEventLog?: () => void;
-}
-declare global {
-    interface Window {
-        __orbitalVerification?: OrbitalVerificationAPI;
-    }
-}
-/**
- * Wait for a transition matching the given event to appear.
- * Returns the trace or null on timeout.
- */
-declare function waitForTransition(event: string, timeoutMs?: number): Promise<TransitionTrace | null>;
-/**
- * Bind the EventBus so automation can send events and log emissions.
- * Call this during app initialization.
- */
-declare function bindEventBus(eventBus: {
-    emit: (type: string, payload?: Record<string, unknown>) => void;
-    onAny?: (listener: (event: {
-        type: string;
-        payload?: Record<string, unknown>;
-    }) => void) => () => void;
-}): void;
-/**
- * Bind a trait state getter so automation can query current states.
- */
-declare function bindTraitStateGetter(getter: (traitName: string) => string | undefined): void;
-/**
- * Register a canvas frame capture function.
- * Called by game organisms (IsometricCanvas, PlatformerCanvas, SimulationCanvas)
- * so the verifier can snapshot canvas content at checkpoints.
- */
-declare function bindCanvasCapture(captureFn: () => string | null): void;
-/**
- * Update asset load status for canvas verification.
- * Game organisms call this when images load or fail.
- */
-declare function updateAssetStatus(url: string, status: AssetLoadStatus): void;
-declare function clearVerification(): void;
-
 /**
  * Get Nested Value Utility
  *
@@ -455,4 +317,4 @@ declare function getNestedValue(obj: Record<string, unknown> | null | undefined,
  */
 declare function formatNestedFieldLabel(path: string): string;
 
-export { ApiError, type AssetLoadStatus, type BridgeHealth, type CheckStatus, type DebugEvent, type DebugEventType, type EffectTrace, type EntitySnapshot, type EntityState, type EventLogEntry, type GuardContext, type GuardEvaluation, type PersistentEntityInfo, type RuntimeEntity, type TickExecution, type TraitDebugInfo, type TraitGuard, type TraitTransition, type TransitionTrace, type VerificationCheck, type VerificationSnapshot, type VerificationSummary, apiClient, bindCanvasCapture, bindEventBus, bindTraitStateGetter, clearDebugEvents, clearEntityProvider, clearGuardHistory, clearTicks, clearTraits, clearVerification, debug, debugCollision, debugError, debugGameState, debugGroup, debugGroupEnd, debugInput, debugPhysics, debugTable, debugTime, debugTimeEnd, debugWarn, formatNestedFieldLabel, getAllChecks, getAllTicks, getAllTraits, getBridgeHealth, getDebugEvents, getEntitiesByType, getEntityById, getEntitySnapshot, getEventsBySource, getEventsByType, getGuardEvaluationsForTrait, getGuardHistory, getNestedValue, getRecentEvents, getRecentGuardEvaluations, getSnapshot, getSummary, getTick, getTrait, getTransitions, getTransitionsForTrait, initDebugShortcut, isDebugEnabled, logDebugEvent, logEffectExecuted, logError, logEventFired, logInfo, logStateChange, logWarning, onDebugToggle, recordGuardEvaluation, recordTransition, registerCheck, registerTick, registerTrait, setDebugEnabled, setEntityProvider, setTickActive, subscribeToDebugEvents, subscribeToGuardChanges, subscribeToTickChanges, subscribeToTraitChanges, subscribeToVerification, toggleDebug, unregisterTick, unregisterTrait, updateAssetStatus, updateBridgeHealth, updateCheck, updateGuardResult, updateTickExecution, updateTraitState, waitForTransition };
+export { ApiError, type DebugEvent, type DebugEventType, type EntitySnapshot, type EntityState, type GuardContext, type GuardEvaluation, type PersistentEntityInfo, type RuntimeEntity, type TickExecution, type TraitDebugInfo, type TraitGuard, type TraitTransition, apiClient, clearDebugEvents, clearEntityProvider, clearGuardHistory, clearTicks, clearTraits, debug, debugCollision, debugError, debugGameState, debugGroup, debugGroupEnd, debugInput, debugPhysics, debugTable, debugTime, debugTimeEnd, debugWarn, formatNestedFieldLabel, getAllTicks, getAllTraits, getDebugEvents, getEntitiesByType, getEntityById, getEntitySnapshot, getEventsBySource, getEventsByType, getGuardEvaluationsForTrait, getGuardHistory, getNestedValue, getRecentEvents, getRecentGuardEvaluations, getTick, getTrait, initDebugShortcut, isDebugEnabled, logDebugEvent, logEffectExecuted, logError, logEventFired, logInfo, logStateChange, logWarning, onDebugToggle, recordGuardEvaluation, registerTick, registerTrait, setDebugEnabled, setEntityProvider, setTickActive, subscribeToDebugEvents, subscribeToGuardChanges, subscribeToTickChanges, subscribeToTraitChanges, toggleDebug, unregisterTick, unregisterTrait, updateGuardResult, updateTickExecution, updateTraitState };