@almadar/cli 0.3.2 → 0.3.3

package/shells/typescript-shell/packages/client/src/lib/debugUtils.ts

@@ -0,0 +1,62 @@
+/**
+ * Debug Utilities - Functions for toggling and checking debug mode
+ *
+ * @packageDocumentation
+ */
+
+const DEBUG_STORAGE_KEY = 'orbital-debug';
+
+type DebugToggleListener = (enabled: boolean) => void;
+
+const listeners = new Set<DebugToggleListener>();
+
+/**
+ * Check if debug mode is enabled
+ */
+export function isDebugEnabled(): boolean {
+  if (typeof window === 'undefined') return false;
+  return localStorage.getItem(DEBUG_STORAGE_KEY) === 'true';
+}
+
+/**
+ * Enable or disable debug mode
+ */
+export function setDebugEnabled(enabled: boolean): void {
+  if (typeof window === 'undefined') return;
+  localStorage.setItem(DEBUG_STORAGE_KEY, String(enabled));
+  listeners.forEach(listener => listener(enabled));
+}
+
+/**
+ * Toggle debug mode
+ */
+export function toggleDebug(): boolean {
+  const newValue = !isDebugEnabled();
+  setDebugEnabled(newValue);
+  return newValue;
+}
+
+/**
+ * Subscribe to debug mode changes
+ */
+export function onDebugToggle(listener: DebugToggleListener): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+/**
+ * Initialize debug mode from keyboard shortcut (Ctrl+Shift+D)
+ */
+export function initDebugShortcut(): () => void {
+  if (typeof window === 'undefined') return () => {};
+
+  const handleKeyDown = (e: KeyboardEvent) => {
+    if (e.ctrlKey && e.shiftKey && e.key === 'D') {
+      e.preventDefault();
+      toggleDebug();
+    }
+  };
+
+  window.addEventListener('keydown', handleKeyDown);
+  return () => window.removeEventListener('keydown', handleKeyDown);
+}

package/shells/typescript-shell/packages/client/src/lib/entityDebug.ts

@@ -0,0 +1,79 @@
+/**
+ * Entity Debug - Provides entity state snapshots for debugging
+ *
+ * @packageDocumentation
+ */
+
+export interface EntityState {
+  id: string;
+  type: string;
+  fields: Record<string, unknown>;
+  lastUpdated: number;
+}
+
+export interface RuntimeEntity {
+  id: string;
+  type: string;
+  data: Record<string, unknown>;
+}
+
+export interface PersistentEntityInfo {
+  loaded: boolean;
+  count: number;
+}
+
+export 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[];
+
+let entityProvider: EntityProvider | null = null;
+
+export function setEntityProvider(provider: EntityProvider): void {
+  entityProvider = provider;
+}
+
+export function clearEntityProvider(): void {
+  entityProvider = null;
+}
+
+export function getEntitySnapshot(): EntitySnapshot | null {
+  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: {},
+  };
+}
+
+export function getEntityById(id: string): EntityState | undefined {
+  if (!entityProvider) {
+    return undefined;
+  }
+
+  return entityProvider().find((e) => e.id === id);
+}
+
+export function getEntitiesByType(type: string): EntityState[] {
+  if (!entityProvider) {
+    return [];
+  }
+
+  return entityProvider().filter((e) => e.type === type);
+}

package/shells/typescript-shell/packages/client/src/lib/guardRegistry.ts

@@ -0,0 +1,79 @@
+/**
+ * Guard Registry - Tracks guard evaluations for debugging
+ *
+ * @packageDocumentation
+ */
+
+export interface GuardContext {
+  traitName?: string;
+  type?: "transition" | "tick";
+  transitionFrom?: string;
+  transitionTo?: string;
+  tickName?: string;
+  [key: string]: unknown;
+}
+
+export 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 = () => void;
+
+const guardHistory: GuardEvaluation[] = [];
+const listeners = new Set<ChangeListener>();
+const MAX_HISTORY = 100;
+
+function notifyListeners(): void {
+  listeners.forEach((listener) => listener());
+}
+
+export function recordGuardEvaluation(
+  evaluation: Omit<GuardEvaluation, "id" | "timestamp">,
+): void {
+  const entry: GuardEvaluation = {
+    ...evaluation,
+    id: `guard-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`,
+    timestamp: Date.now(),
+  };
+
+  guardHistory.unshift(entry);
+
+  // Keep history bounded
+  if (guardHistory.length > MAX_HISTORY) {
+    guardHistory.pop();
+  }
+
+  notifyListeners();
+}
+
+export function getGuardHistory(): GuardEvaluation[] {
+  return [...guardHistory];
+}
+
+export function getRecentGuardEvaluations(count: number): GuardEvaluation[] {
+  return guardHistory.slice(0, count);
+}
+
+export function getGuardEvaluationsForTrait(
+  traitName: string,
+): GuardEvaluation[] {
+  return guardHistory.filter((g) => g.traitName === traitName);
+}
+
+export function subscribeToGuardChanges(listener: ChangeListener): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function clearGuardHistory(): void {
+  guardHistory.length = 0;
+  notifyListeners();
+}

package/shells/typescript-shell/packages/client/src/lib/tickRegistry.ts

@@ -0,0 +1,86 @@
+/**
+ * Tick Registry - Tracks scheduled tick executions for debugging
+ *
+ * @packageDocumentation
+ */
+
+export 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 = () => void;
+
+const ticks = new Map<string, TickExecution>();
+const listeners = new Set<ChangeListener>();
+
+function notifyListeners(): void {
+  listeners.forEach((listener) => listener());
+}
+
+export function registerTick(tick: TickExecution): void {
+  ticks.set(tick.id, tick);
+  notifyListeners();
+}
+
+export function updateTickExecution(id: string, timestamp: number): void {
+  const tick = ticks.get(id);
+  if (tick) {
+    tick.lastExecuted = timestamp;
+    tick.nextExecution = timestamp + tick.interval;
+    tick.executionCount++;
+    notifyListeners();
+  }
+}
+
+export function setTickActive(id: string, isActive: boolean): void {
+  const tick = ticks.get(id);
+  if (tick) {
+    tick.isActive = isActive;
+    notifyListeners();
+  }
+}
+
+export function unregisterTick(id: string): void {
+  ticks.delete(id);
+  notifyListeners();
+}
+
+export function getAllTicks(): TickExecution[] {
+  return Array.from(ticks.values());
+}
+
+export function getTick(id: string): TickExecution | undefined {
+  return ticks.get(id);
+}
+
+export function subscribeToTickChanges(listener: ChangeListener): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function clearTicks(): void {
+  ticks.clear();
+  notifyListeners();
+}

package/shells/typescript-shell/packages/client/src/lib/traitRegistry.ts

@@ -0,0 +1,84 @@
+/**
+ * Trait Registry - Tracks active traits and their state machines for debugging
+ *
+ * @packageDocumentation
+ */
+
+export interface TraitTransition {
+  from: string;
+  to: string;
+  event: string;
+  guard?: string;
+}
+
+export interface TraitGuard {
+  name: string;
+  lastResult?: boolean;
+}
+
+export interface TraitDebugInfo {
+  id: string;
+  name: string;
+  currentState: string;
+  states: string[];
+  transitions: TraitTransition[];
+  guards: TraitGuard[];
+  transitionCount: number;
+}
+
+type ChangeListener = () => void;
+
+const traits = new Map<string, TraitDebugInfo>();
+const listeners = new Set<ChangeListener>();
+
+function notifyListeners(): void {
+  listeners.forEach(listener => listener());
+}
+
+export function registerTrait(info: TraitDebugInfo): void {
+  traits.set(info.id, info);
+  notifyListeners();
+}
+
+export function updateTraitState(id: string, newState: string): void {
+  const trait = traits.get(id);
+  if (trait) {
+    trait.currentState = newState;
+    trait.transitionCount++;
+    notifyListeners();
+  }
+}
+
+export function updateGuardResult(traitId: string, guardName: string, result: boolean): void {
+  const trait = traits.get(traitId);
+  if (trait) {
+    const guard = trait.guards.find(g => g.name === guardName);
+    if (guard) {
+      guard.lastResult = result;
+      notifyListeners();
+    }
+  }
+}
+
+export function unregisterTrait(id: string): void {
+  traits.delete(id);
+  notifyListeners();
+}
+
+export function getAllTraits(): TraitDebugInfo[] {
+  return Array.from(traits.values());
+}
+
+export function getTrait(id: string): TraitDebugInfo | undefined {
+  return traits.get(id);
+}
+
+export function subscribeToTraitChanges(listener: ChangeListener): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function clearTraits(): void {
+  traits.clear();
+  notifyListeners();
+}

package/shells/typescript-shell/packages/client/src/loaders/AssetLoader.ts

@@ -0,0 +1,315 @@
+/**
+ * Asset Loader
+ *
+ * Loads and caches game assets (images, spritesheets, audio).
+ * Provides tile extraction for tileset-based assets.
+ */
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface LoadedAsset {
+    type: 'image' | 'spritesheet' | 'audio';
+    src: string;
+    data: HTMLImageElement | HTMLAudioElement;
+    metadata?: SpritesheetMetadata;
+}
+
+export interface SpritesheetMetadata {
+    tileSize: number;
+    columns: number;
+    rows: number;
+    totalTiles: number;
+}
+
+export interface TileRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+
+export interface AnimationConfig {
+    frames: number[];
+    fps: number;
+    loop: boolean;
+}
+
+export interface AssetManifestEntry {
+    key: string;
+    entityName: string;
+    basePath: string;
+    path: string;
+    tiles?: number[];
+    tileSize?: number;
+    files?: string[];
+    animations?: Record<string, AnimationConfig>;
+}
+
+export interface AssetManifest {
+    gameType: string;
+    style: string;
+    assets: Record<string, AssetManifestEntry>;
+}
+
+// ============================================================================
+// Asset Loader Class
+// ============================================================================
+
+class AssetLoaderClass {
+    private imageCache: Map<string, HTMLImageElement> = new Map();
+    private audioCache: Map<string, HTMLAudioElement> = new Map();
+    private metadataCache: Map<string, SpritesheetMetadata> = new Map();
+    private loadingPromises: Map<string, Promise<HTMLImageElement | HTMLAudioElement>> = new Map();
+
+    /**
+     * Load an image asset.
+     * Returns cached image if already loaded.
+     */
+    async loadImage(src: string): Promise<HTMLImageElement> {
+        // Return cached image
+        const cached = this.imageCache.get(src);
+        if (cached) return cached;
+
+        // Return pending promise if already loading
+        const pending = this.loadingPromises.get(src);
+        if (pending) return pending as Promise<HTMLImageElement>;
+
+        // Load image
+        const promise = new Promise<HTMLImageElement>((resolve, reject) => {
+            const img = new Image();
+            img.crossOrigin = 'anonymous';
+
+            img.onload = () => {
+                this.imageCache.set(src, img);
+                this.loadingPromises.delete(src);
+                resolve(img);
+            };
+
+            img.onerror = (e) => {
+                this.loadingPromises.delete(src);
+                reject(new Error(`Failed to load image: ${src}`));
+            };
+
+            img.src = src;
+        });
+
+        this.loadingPromises.set(src, promise);
+        return promise;
+    }
+
+    /**
+     * Load a tileset/spritesheet with metadata.
+     */
+    async loadTileset(
+        src: string,
+        config: { tileSize: number; tiles?: number[]; animations?: Record<string, AnimationConfig> }
+    ): Promise<{ image: HTMLImageElement; metadata: SpritesheetMetadata }> {
+        const image = await this.loadImage(src);
+
+        // Calculate metadata
+        const columns = Math.floor(image.width / config.tileSize);
+        const rows = Math.floor(image.height / config.tileSize);
+        const metadata: SpritesheetMetadata = {
+            tileSize: config.tileSize,
+            columns,
+            rows,
+            totalTiles: columns * rows,
+        };
+
+        this.metadataCache.set(src, metadata);
+
+        return { image, metadata };
+    }
+
+    /**
+     * Load an audio asset.
+     */
+    async loadAudio(src: string): Promise<HTMLAudioElement> {
+        const cached = this.audioCache.get(src);
+        if (cached) return cached;
+
+        const pending = this.loadingPromises.get(src);
+        if (pending) return pending as Promise<HTMLAudioElement>;
+
+        const promise = new Promise<HTMLAudioElement>((resolve, reject) => {
+            const audio = new Audio();
+
+            audio.oncanplaythrough = () => {
+                this.audioCache.set(src, audio);
+                this.loadingPromises.delete(src);
+                resolve(audio);
+            };
+
+            audio.onerror = () => {
+                this.loadingPromises.delete(src);
+                reject(new Error(`Failed to load audio: ${src}`));
+            };
+
+            audio.src = src;
+            audio.load();
+        });
+
+        this.loadingPromises.set(src, promise);
+        return promise;
+    }
+
+    /**
+     * Get tile rectangle for a specific tile index.
+     */
+    getTileRect(src: string, tileIndex: number): TileRect | null {
+        const metadata = this.metadataCache.get(src);
+        if (!metadata) return null;
+
+        const col = tileIndex % metadata.columns;
+        const row = Math.floor(tileIndex / metadata.columns);
+
+        return {
+            x: col * metadata.tileSize,
+            y: row * metadata.tileSize,
+            width: metadata.tileSize,
+            height: metadata.tileSize,
+        };
+    }
+
+    /**
+     * Get tile rectangle from metadata directly.
+     */
+    getTileRectFromMetadata(metadata: SpritesheetMetadata, tileIndex: number): TileRect {
+        const col = tileIndex % metadata.columns;
+        const row = Math.floor(tileIndex / metadata.columns);
+
+        return {
+            x: col * metadata.tileSize,
+            y: row * metadata.tileSize,
+            width: metadata.tileSize,
+            height: metadata.tileSize,
+        };
+    }
+
+    /**
+     * Check if an image is already loaded.
+     */
+    isLoaded(src: string): boolean {
+        return this.imageCache.has(src);
+    }
+
+    /**
+     * Get cached image (synchronous, returns null if not loaded).
+     */
+    getCachedImage(src: string): HTMLImageElement | null {
+        return this.imageCache.get(src) ?? null;
+    }
+
+    /**
+     * Get cached metadata for a tileset.
+     */
+    getMetadata(src: string): SpritesheetMetadata | null {
+        return this.metadataCache.get(src) ?? null;
+    }
+
+    /**
+     * Preload multiple assets.
+     */
+    async preload(srcs: string[]): Promise<void> {
+        await Promise.all(srcs.map((src) => this.loadImage(src)));
+    }
+
+    /**
+     * Load all assets from a manifest.
+     */
+    async loadManifest(manifest: AssetManifest): Promise<Map<string, LoadedAsset>> {
+        const loaded = new Map<string, LoadedAsset>();
+
+        for (const [entityName, entry] of Object.entries(manifest.assets)) {
+            const src = `${entry.basePath}/${entry.path}`;
+
+            if (entry.tiles && entry.tileSize) {
+                // Tileset-based asset
+                const { image, metadata } = await this.loadTileset(src, {
+                    tileSize: entry.tileSize,
+                    tiles: entry.tiles,
+                    animations: entry.animations,
+                });
+
+                loaded.set(entityName, {
+                    type: 'spritesheet',
+                    src,
+                    data: image,
+                    metadata,
+                });
+            } else if (entry.files) {
+                // File-based asset - load first file as representative
+                const firstFile = entry.files[0]?.replace('*', '1') ?? '';
+                const fileSrc = `${entry.basePath}/${entry.path}/${firstFile}`;
+                const image = await this.loadImage(fileSrc);
+
+                loaded.set(entityName, {
+                    type: 'image',
+                    src: fileSrc,
+                    data: image,
+                });
+            }
+        }
+
+        return loaded;
+    }
+
+    /**
+     * Clear all caches.
+     */
+    clear(): void {
+        this.imageCache.clear();
+        this.audioCache.clear();
+        this.metadataCache.clear();
+        this.loadingPromises.clear();
+    }
+
+    /**
+     * Clear specific asset from cache.
+     */
+    unload(src: string): void {
+        this.imageCache.delete(src);
+        this.audioCache.delete(src);
+        this.metadataCache.delete(src);
+    }
+
+    /**
+     * Get cache statistics.
+     */
+    getStats(): { images: number; audio: number; loading: number } {
+        return {
+            images: this.imageCache.size,
+            audio: this.audioCache.size,
+            loading: this.loadingPromises.size,
+        };
+    }
+}
+
+// ============================================================================
+// Singleton Export
+// ============================================================================
+
+/**
+ * Global asset loader instance.
+ * Use this for all asset loading operations.
+ */
+export const AssetLoader = new AssetLoaderClass();
+
+/**
+ * Load an asset (convenience function).
+ */
+export async function loadAsset(src: string): Promise<HTMLImageElement> {
+    return AssetLoader.loadImage(src);
+}
+
+/**
+ * Load a tileset (convenience function).
+ */
+export async function loadTileset(
+    src: string,
+    config: { tileSize: number; tiles?: number[]; animations?: Record<string, AnimationConfig> }
+): Promise<{ image: HTMLImageElement; metadata: SpritesheetMetadata }> {
+    return AssetLoader.loadTileset(src, config);
+}