@almadar/ui 1.0.0

package/dist/lib/index.d.ts

@@ -0,0 +1,291 @@
+import { ClassValue } from 'clsx';
+
+/**
+ * Utility function to merge Tailwind CSS classes
+ * Combines clsx for conditional classes with tailwind-merge to handle conflicts
+ */
+declare function cn(...inputs: ClassValue[]): string;
+
+/**
+ * API Client - HTTP client for backend API calls
+ *
+ * Provides typed methods for making API requests.
+ * All requests go through the backend server, NOT directly to Firestore.
+ *
+ * @packageDocumentation
+ */
+/**
+ * API Error class for handling HTTP errors
+ */
+declare class ApiError extends Error {
+    status: number;
+    statusText: string;
+    constructor(status: number, statusText: string, message?: string);
+}
+/**
+ * API client with typed methods
+ */
+declare const apiClient: {
+    /**
+     * GET request
+     */
+    get<T>(endpoint: string): Promise<T>;
+    /**
+     * POST request
+     */
+    post<T>(endpoint: string, data?: unknown): Promise<T>;
+    /**
+     * PUT request
+     */
+    put<T>(endpoint: string, data?: unknown): Promise<T>;
+    /**
+     * PATCH request
+     */
+    patch<T>(endpoint: string, data?: unknown): Promise<T>;
+    /**
+     * DELETE request
+     */
+    delete<T = void>(endpoint: string): Promise<T>;
+};
+
+/**
+ * Debug utilities for development
+ */
+declare function isDebugEnabled(): boolean;
+declare function debug(...args: unknown[]): void;
+declare function debugGroup(label: string): void;
+declare function debugGroupEnd(): void;
+declare function debugWarn(...args: unknown[]): void;
+declare function debugError(...args: unknown[]): void;
+declare function debugTable(data: unknown): void;
+declare function debugTime(label: string): void;
+declare function debugTimeEnd(label: string): void;
+/**
+ * Debug input events (keyboard, mouse, touch)
+ * @param inputType - Type of input (e.g., 'keydown', 'keyup', 'mouse')
+ * @param data - Input data to log
+ */
+declare function debugInput(inputType: string, data: unknown): void;
+/**
+ * Debug collision events between entities
+ * @param entityA - First entity in collision
+ * @param entityB - Second entity in collision
+ * @param details - Additional collision details
+ */
+declare function debugCollision(entityA: {
+    id?: string;
+    type?: string;
+}, entityB: {
+    id?: string;
+    type?: string;
+}, details?: unknown): void;
+/**
+ * Debug physics updates (position, velocity)
+ * @param entityId - Entity identifier
+ * @param physics - Physics data to log
+ */
+declare function debugPhysics(entityId: string, physics: unknown): void;
+/**
+ * Debug game state changes
+ * @param stateName - Name of the state that changed
+ * @param value - New state value
+ */
+declare function debugGameState(stateName: string, value: unknown): void;
+
+/**
+ * Debug Utilities - Functions for toggling and checking debug mode
+ *
+ * @packageDocumentation
+ */
+type DebugToggleListener = (enabled: boolean) => void;
+/**
+ * Enable or disable debug mode
+ */
+declare function setDebugEnabled(enabled: boolean): void;
+/**
+ * Toggle debug mode
+ */
+declare function toggleDebug(): boolean;
+/**
+ * Subscribe to debug mode changes
+ */
+declare function onDebugToggle(listener: DebugToggleListener): () => void;
+/**
+ * Initialize debug mode from keyboard shortcut (Ctrl+Shift+D)
+ */
+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$3 = () => 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$3): () => 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$2 = () => 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$2): () => 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$1 = () => 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$1): () => 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 = () => 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): () => void;
+declare function clearTraits(): void;
+
+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, cn, debug, debugCollision, debugError, debugGameState, debugGroup, debugGroupEnd, debugInput, debugPhysics, debugTable, debugTime, debugTimeEnd, debugWarn, getAllTicks, getAllTraits, getDebugEvents, getEntitiesByType, getEntityById, getEntitySnapshot, getEventsBySource, getEventsByType, getGuardEvaluationsForTrait, getGuardHistory, 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 };

package/dist/lib/index.js

@@ -0,0 +1,431 @@
+import { clsx } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+// lib/cn.ts
+function cn(...inputs) {
+  return twMerge(clsx(inputs));
+}
+
+// lib/api-client.ts
+var API_BASE_URL = typeof import.meta !== "undefined" && import.meta.env?.VITE_API_URL ? import.meta.env.VITE_API_URL : "/api";
+var ApiError = class extends Error {
+  constructor(status, statusText, message) {
+    super(message || `API Error: ${status} ${statusText}`);
+    this.status = status;
+    this.statusText = statusText;
+    this.name = "ApiError";
+  }
+};
+async function handleResponse(response) {
+  if (!response.ok) {
+    let message;
+    try {
+      const errorData = await response.json();
+      message = errorData.message || errorData.error;
+    } catch {
+    }
+    throw new ApiError(response.status, response.statusText, message);
+  }
+  const text = await response.text();
+  if (!text) {
+    return void 0;
+  }
+  return JSON.parse(text);
+}
+function getHeaders() {
+  const headers = {
+    "Content-Type": "application/json"
+  };
+  const token = typeof localStorage !== "undefined" ? localStorage.getItem("authToken") : null;
+  if (token) {
+    headers["Authorization"] = `Bearer ${token}`;
+  }
+  return headers;
+}
+var apiClient = {
+  /**
+   * GET request
+   */
+  async get(endpoint) {
+    const response = await fetch(`${API_BASE_URL}${endpoint}`, {
+      method: "GET",
+      headers: getHeaders()
+    });
+    return handleResponse(response);
+  },
+  /**
+   * POST request
+   */
+  async post(endpoint, data) {
+    const response = await fetch(`${API_BASE_URL}${endpoint}`, {
+      method: "POST",
+      headers: getHeaders(),
+      body: data ? JSON.stringify(data) : void 0
+    });
+    return handleResponse(response);
+  },
+  /**
+   * PUT request
+   */
+  async put(endpoint, data) {
+    const response = await fetch(`${API_BASE_URL}${endpoint}`, {
+      method: "PUT",
+      headers: getHeaders(),
+      body: data ? JSON.stringify(data) : void 0
+    });
+    return handleResponse(response);
+  },
+  /**
+   * PATCH request
+   */
+  async patch(endpoint, data) {
+    const response = await fetch(`${API_BASE_URL}${endpoint}`, {
+      method: "PATCH",
+      headers: getHeaders(),
+      body: data ? JSON.stringify(data) : void 0
+    });
+    return handleResponse(response);
+  },
+  /**
+   * DELETE request
+   */
+  async delete(endpoint) {
+    const response = await fetch(`${API_BASE_URL}${endpoint}`, {
+      method: "DELETE",
+      headers: getHeaders()
+    });
+    return handleResponse(response);
+  }
+};
+
+// lib/debug.ts
+var DEBUG_ENABLED = typeof window !== "undefined" && (localStorage.getItem("debug") === "true" || process.env.NODE_ENV === "development");
+function isDebugEnabled() {
+  return DEBUG_ENABLED;
+}
+function debug(...args) {
+  if (DEBUG_ENABLED) {
+    console.log("[DEBUG]", ...args);
+  }
+}
+function debugGroup(label) {
+  if (DEBUG_ENABLED) {
+    console.group(`[DEBUG] ${label}`);
+  }
+}
+function debugGroupEnd() {
+  if (DEBUG_ENABLED) {
+    console.groupEnd();
+  }
+}
+function debugWarn(...args) {
+  if (DEBUG_ENABLED) {
+    console.warn("[DEBUG]", ...args);
+  }
+}
+function debugError(...args) {
+  if (DEBUG_ENABLED) {
+    console.error("[DEBUG]", ...args);
+  }
+}
+function debugTable(data) {
+  if (DEBUG_ENABLED) {
+    console.table(data);
+  }
+}
+function debugTime(label) {
+  if (DEBUG_ENABLED) {
+    console.time(`[DEBUG] ${label}`);
+  }
+}
+function debugTimeEnd(label) {
+  if (DEBUG_ENABLED) {
+    console.timeEnd(`[DEBUG] ${label}`);
+  }
+}
+function debugInput(inputType, data) {
+  if (DEBUG_ENABLED) {
+    console.log(`[DEBUG:INPUT] ${inputType}:`, data);
+  }
+}
+function debugCollision(entityA, entityB, details) {
+  if (DEBUG_ENABLED) {
+    console.log(
+      `[DEBUG:COLLISION] ${entityA.type || entityA.id} <-> ${entityB.type || entityB.id}`,
+      details ?? ""
+    );
+  }
+}
+function debugPhysics(entityId, physics) {
+  if (DEBUG_ENABLED) {
+    console.log(`[DEBUG:PHYSICS] ${entityId}:`, physics);
+  }
+}
+function debugGameState(stateName, value) {
+  if (DEBUG_ENABLED) {
+    console.log(`[DEBUG:GAME_STATE] ${stateName}:`, value);
+  }
+}
+
+// lib/debugUtils.ts
+var DEBUG_STORAGE_KEY = "orbital-debug";
+var listeners = /* @__PURE__ */ new Set();
+function isDebugEnabled2() {
+  if (typeof window === "undefined") return false;
+  return localStorage.getItem(DEBUG_STORAGE_KEY) === "true";
+}
+function setDebugEnabled(enabled) {
+  if (typeof window === "undefined") return;
+  localStorage.setItem(DEBUG_STORAGE_KEY, String(enabled));
+  listeners.forEach((listener) => listener(enabled));
+}
+function toggleDebug() {
+  const newValue = !isDebugEnabled2();
+  setDebugEnabled(newValue);
+  return newValue;
+}
+function onDebugToggle(listener) {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+function initDebugShortcut() {
+  if (typeof window === "undefined") return () => {
+  };
+  const handleKeyDown = (e) => {
+    if (e.ctrlKey && e.shiftKey && e.key === "D") {
+      e.preventDefault();
+      toggleDebug();
+    }
+  };
+  window.addEventListener("keydown", handleKeyDown);
+  return () => window.removeEventListener("keydown", handleKeyDown);
+}
+
+// lib/entityDebug.ts
+var entityProvider = null;
+function setEntityProvider(provider) {
+  entityProvider = provider;
+}
+function clearEntityProvider() {
+  entityProvider = null;
+}
+function getEntitySnapshot() {
+  if (!entityProvider) {
+    return null;
+  }
+  const entities = entityProvider();
+  return {
+    entities,
+    timestamp: Date.now(),
+    totalCount: entities.length,
+    singletons: {},
+    runtime: entities.map((e) => ({ id: e.id, type: e.type, data: e.fields })),
+    persistent: {}
+  };
+}
+function getEntityById(id) {
+  if (!entityProvider) {
+    return void 0;
+  }
+  return entityProvider().find((e) => e.id === id);
+}
+function getEntitiesByType(type) {
+  if (!entityProvider) {
+    return [];
+  }
+  return entityProvider().filter((e) => e.type === type);
+}
+
+// lib/debugRegistry.ts
+var events = [];
+var listeners2 = /* @__PURE__ */ new Set();
+var MAX_EVENTS = 500;
+function notifyListeners() {
+  listeners2.forEach((listener) => listener());
+}
+function logDebugEvent(type, source, message, data) {
+  const event = {
+    id: `event-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`,
+    type,
+    source,
+    message,
+    data,
+    timestamp: Date.now()
+  };
+  events.unshift(event);
+  if (events.length > MAX_EVENTS) {
+    events.pop();
+  }
+  notifyListeners();
+}
+function logStateChange(source, from, to, event) {
+  logDebugEvent("state-change", source, `${from} \u2192 ${to}`, { from, to, event });
+}
+function logEventFired(source, eventName, payload) {
+  logDebugEvent("event-fired", source, eventName, { eventName, payload });
+}
+function logEffectExecuted(source, effectType, details) {
+  logDebugEvent("effect-executed", source, effectType, { effectType, details });
+}
+function logError(source, message, error) {
+  logDebugEvent("error", source, message, { error });
+}
+function logWarning(source, message, data) {
+  logDebugEvent("warning", source, message, data);
+}
+function logInfo(source, message, data) {
+  logDebugEvent("info", source, message, data);
+}
+function getDebugEvents() {
+  return [...events];
+}
+function getRecentEvents(count) {
+  return events.slice(0, count);
+}
+function getEventsByType(type) {
+  return events.filter((e) => e.type === type);
+}
+function getEventsBySource(source) {
+  return events.filter((e) => e.source === source);
+}
+function subscribeToDebugEvents(listener) {
+  listeners2.add(listener);
+  return () => listeners2.delete(listener);
+}
+function clearDebugEvents() {
+  events.length = 0;
+  notifyListeners();
+}
+
+// lib/guardRegistry.ts
+var guardHistory = [];
+var listeners3 = /* @__PURE__ */ new Set();
+var MAX_HISTORY = 100;
+function notifyListeners2() {
+  listeners3.forEach((listener) => listener());
+}
+function recordGuardEvaluation(evaluation) {
+  const entry = {
+    ...evaluation,
+    id: `guard-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`,
+    timestamp: Date.now()
+  };
+  guardHistory.unshift(entry);
+  if (guardHistory.length > MAX_HISTORY) {
+    guardHistory.pop();
+  }
+  notifyListeners2();
+}
+function getGuardHistory() {
+  return [...guardHistory];
+}
+function getRecentGuardEvaluations(count) {
+  return guardHistory.slice(0, count);
+}
+function getGuardEvaluationsForTrait(traitName) {
+  return guardHistory.filter((g) => g.traitName === traitName);
+}
+function subscribeToGuardChanges(listener) {
+  listeners3.add(listener);
+  return () => listeners3.delete(listener);
+}
+function clearGuardHistory() {
+  guardHistory.length = 0;
+  notifyListeners2();
+}
+
+// lib/tickRegistry.ts
+var ticks = /* @__PURE__ */ new Map();
+var listeners4 = /* @__PURE__ */ new Set();
+function notifyListeners3() {
+  listeners4.forEach((listener) => listener());
+}
+function registerTick(tick) {
+  ticks.set(tick.id, tick);
+  notifyListeners3();
+}
+function updateTickExecution(id, timestamp) {
+  const tick = ticks.get(id);
+  if (tick) {
+    tick.lastExecuted = timestamp;
+    tick.nextExecution = timestamp + tick.interval;
+    tick.executionCount++;
+    notifyListeners3();
+  }
+}
+function setTickActive(id, isActive) {
+  const tick = ticks.get(id);
+  if (tick) {
+    tick.isActive = isActive;
+    notifyListeners3();
+  }
+}
+function unregisterTick(id) {
+  ticks.delete(id);
+  notifyListeners3();
+}
+function getAllTicks() {
+  return Array.from(ticks.values());
+}
+function getTick(id) {
+  return ticks.get(id);
+}
+function subscribeToTickChanges(listener) {
+  listeners4.add(listener);
+  return () => listeners4.delete(listener);
+}
+function clearTicks() {
+  ticks.clear();
+  notifyListeners3();
+}
+
+// lib/traitRegistry.ts
+var traits = /* @__PURE__ */ new Map();
+var listeners5 = /* @__PURE__ */ new Set();
+function notifyListeners4() {
+  listeners5.forEach((listener) => listener());
+}
+function registerTrait(info) {
+  traits.set(info.id, info);
+  notifyListeners4();
+}
+function updateTraitState(id, newState) {
+  const trait = traits.get(id);
+  if (trait) {
+    trait.currentState = newState;
+    trait.transitionCount++;
+    notifyListeners4();
+  }
+}
+function updateGuardResult(traitId, guardName, result) {
+  const trait = traits.get(traitId);
+  if (trait) {
+    const guard = trait.guards.find((g) => g.name === guardName);
+    if (guard) {
+      guard.lastResult = result;
+      notifyListeners4();
+    }
+  }
+}
+function unregisterTrait(id) {
+  traits.delete(id);
+  notifyListeners4();
+}
+function getAllTraits() {
+  return Array.from(traits.values());
+}
+function getTrait(id) {
+  return traits.get(id);
+}
+function subscribeToTraitChanges(listener) {
+  listeners5.add(listener);
+  return () => listeners5.delete(listener);
+}
+function clearTraits() {
+  traits.clear();
+  notifyListeners4();
+}
+
+export { ApiError, apiClient, clearDebugEvents, clearEntityProvider, clearGuardHistory, clearTicks, clearTraits, cn, debug, debugCollision, debugError, debugGameState, debugGroup, debugGroupEnd, debugInput, debugPhysics, debugTable, debugTime, debugTimeEnd, debugWarn, getAllTicks, getAllTraits, getDebugEvents, getEntitiesByType, getEntityById, getEntitySnapshot, getEventsBySource, getEventsByType, getGuardEvaluationsForTrait, getGuardHistory, 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 };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map