@almadar/cli 0.3.2 → 1.0.3

package/shells/typescript-shell/packages/client/src/hooks/useUISlots.ts

@@ -0,0 +1,320 @@
+/**
+ * useUISlots Hook
+ *
+ * Core hook for managing UI slot rendering in the trait-driven architecture.
+ * Traits use render_ui effects to dynamically render content into slots.
+ *
+ * Slots:
+ * - main: Primary content area
+ * - sidebar: Left/right sidebar
+ * - modal: Modal overlay
+ * - drawer: Slide-in drawer
+ * - overlay: Full-screen overlay
+ * - center: Centered popup
+ * - toast: Toast notifications
+ * - hud-top: Game HUD top bar
+ * - hud-bottom: Game HUD bottom bar
+ * - floating: Draggable floating panel
+ *
+ * @packageDocumentation
+ */
+
+import { useState, useCallback, useRef, useEffect } from 'react';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+/**
+ * Valid UI slot names
+ */
+export type UISlot =
+  | 'main'
+  | 'sidebar'
+  | 'modal'
+  | 'drawer'
+  | 'overlay'
+  | 'center'
+  | 'toast'
+  | 'hud-top'
+  | 'hud-bottom'
+  | 'floating';
+
+/**
+ * Animation types for slot transitions
+ */
+export type SlotAnimation = 'fade' | 'slide' | 'scale' | 'none';
+
+/**
+ * Content rendered in a slot
+ */
+export interface SlotContent {
+  /** Unique ID for this content */
+  id: string;
+  /** Pattern/component type to render */
+  pattern: string;
+  /** Props to pass to the pattern component */
+  props: Record<string, unknown>;
+  /** Priority for conflict resolution (higher wins) */
+  priority: number;
+  /** Animation for showing/hiding */
+  animation?: SlotAnimation;
+  /** Auto-dismiss timestamp (for toasts) */
+  autoDismissAt?: number;
+  /** Callback when dismissed */
+  onDismiss?: () => void;
+  /** Source trait that rendered this content */
+  sourceTrait?: string;
+}
+
+/**
+ * Configuration for render_ui effect
+ */
+export interface RenderUIConfig {
+  /** Target slot */
+  target: UISlot;
+  /** Pattern/component to render */
+  pattern: string;
+  /** Props for the pattern */
+  props?: Record<string, unknown>;
+  /** Priority (default: 0) */
+  priority?: number;
+  /** Animation type */
+  animation?: SlotAnimation;
+  /** Auto-dismiss after ms (for toasts) */
+  autoDismissMs?: number;
+  /** Callback on dismiss */
+  onDismiss?: () => void;
+  /** Source trait name */
+  sourceTrait?: string;
+}
+
+/**
+ * Callback for slot changes
+ */
+export type SlotChangeCallback = (slot: UISlot, content: SlotContent | null) => void;
+
+/**
+ * UI Slot Manager interface
+ */
+export interface UISlotManager {
+  /** Current content for each slot */
+  slots: Record<UISlot, SlotContent | null>;
+  /** Render content to a slot */
+  render: (config: RenderUIConfig) => string;
+  /** Clear a specific slot */
+  clear: (slot: UISlot) => void;
+  /** Clear content by ID */
+  clearById: (id: string) => void;
+  /** Clear all slots */
+  clearAll: () => void;
+  /** Subscribe to slot changes */
+  subscribe: (callback: SlotChangeCallback) => () => void;
+  /** Check if a slot has content */
+  hasContent: (slot: UISlot) => boolean;
+  /** Get content for a slot */
+  getContent: (slot: UISlot) => SlotContent | null;
+}
+
+// ============================================================================
+// Default Slots State
+// ============================================================================
+
+const DEFAULT_SLOTS: Record<UISlot, SlotContent | null> = {
+  main: null,
+  sidebar: null,
+  modal: null,
+  drawer: null,
+  overlay: null,
+  center: null,
+  toast: null,
+  'hud-top': null,
+  'hud-bottom': null,
+  floating: null,
+};
+
+// ============================================================================
+// ID Generator
+// ============================================================================
+
+let idCounter = 0;
+function generateId(): string {
+  return `slot-content-${++idCounter}-${Date.now()}`;
+}
+
+// ============================================================================
+// Hook Implementation
+// ============================================================================
+
+/**
+ * Create a UI Slot Manager instance.
+ *
+ * This is the internal hook that creates the manager.
+ * Use `useUISlots()` from context in components.
+ */
+export function useUISlotManager(): UISlotManager {
+  const [slots, setSlots] = useState<Record<UISlot, SlotContent | null>>(DEFAULT_SLOTS);
+  const subscribersRef = useRef<Set<SlotChangeCallback>>(new Set());
+  const timersRef = useRef<Map<string, NodeJS.Timeout>>(new Map());
+
+  // Clean up timers on unmount
+  useEffect(() => {
+    return () => {
+      timersRef.current.forEach((timer) => clearTimeout(timer));
+      timersRef.current.clear();
+    };
+  }, []);
+
+  // Notify subscribers of slot changes
+  const notifySubscribers = useCallback((slot: UISlot, content: SlotContent | null) => {
+    subscribersRef.current.forEach((callback) => {
+      try {
+        callback(slot, content);
+      } catch (error) {
+        console.error('[UISlots] Subscriber error:', error);
+      }
+    });
+  }, []);
+
+  // Render content to a slot
+  const render = useCallback((config: RenderUIConfig): string => {
+    const id = generateId();
+    const content: SlotContent = {
+      id,
+      pattern: config.pattern,
+      props: config.props ?? {},
+      priority: config.priority ?? 0,
+      animation: config.animation ?? 'fade',
+      onDismiss: config.onDismiss,
+      sourceTrait: config.sourceTrait,
+    };
+
+    // Set auto-dismiss timer if specified
+    if (config.autoDismissMs && config.autoDismissMs > 0) {
+      content.autoDismissAt = Date.now() + config.autoDismissMs;
+      const timer = setTimeout(() => {
+        setSlots((prev) => {
+          if (prev[config.target]?.id === id) {
+            // Call onDismiss callback
+            content.onDismiss?.();
+            notifySubscribers(config.target, null);
+            return { ...prev, [config.target]: null };
+          }
+          return prev;
+        });
+        timersRef.current.delete(id);
+      }, config.autoDismissMs);
+      timersRef.current.set(id, timer);
+    }
+
+    setSlots((prev) => {
+      const existing = prev[config.target];
+
+      // Priority-based conflict resolution
+      if (existing && existing.priority > content.priority) {
+        console.warn(
+          `[UISlots] Slot "${config.target}" already has higher priority content (${existing.priority} > ${content.priority})`
+        );
+        return prev;
+      }
+
+      notifySubscribers(config.target, content);
+      return { ...prev, [config.target]: content };
+    });
+
+    return id;
+  }, [notifySubscribers]);
+
+  // Clear a specific slot
+  const clear = useCallback((slot: UISlot) => {
+    setSlots((prev) => {
+      const content = prev[slot];
+      if (content) {
+        // Clear any auto-dismiss timer
+        const timer = timersRef.current.get(content.id);
+        if (timer) {
+          clearTimeout(timer);
+          timersRef.current.delete(content.id);
+        }
+        // Call onDismiss callback
+        content.onDismiss?.();
+        notifySubscribers(slot, null);
+      }
+      return { ...prev, [slot]: null };
+    });
+  }, [notifySubscribers]);
+
+  // Clear content by ID
+  const clearById = useCallback((id: string) => {
+    setSlots((prev) => {
+      const entry = Object.entries(prev).find(([, content]) => content?.id === id);
+      if (entry) {
+        const [slot, content] = entry as [UISlot, SlotContent];
+        // Clear any auto-dismiss timer
+        const timer = timersRef.current.get(id);
+        if (timer) {
+          clearTimeout(timer);
+          timersRef.current.delete(id);
+        }
+        // Call onDismiss callback
+        content.onDismiss?.();
+        notifySubscribers(slot, null);
+        return { ...prev, [slot]: null };
+      }
+      return prev;
+    });
+  }, [notifySubscribers]);
+
+  // Clear all slots
+  const clearAll = useCallback(() => {
+    // Clear all timers
+    timersRef.current.forEach((timer) => clearTimeout(timer));
+    timersRef.current.clear();
+
+    setSlots((prev) => {
+      // Call onDismiss for all content
+      Object.entries(prev).forEach(([slot, content]) => {
+        if (content) {
+          content.onDismiss?.();
+          notifySubscribers(slot as UISlot, null);
+        }
+      });
+      return DEFAULT_SLOTS;
+    });
+  }, [notifySubscribers]);
+
+  // Subscribe to slot changes
+  const subscribe = useCallback((callback: SlotChangeCallback): (() => void) => {
+    subscribersRef.current.add(callback);
+    return () => {
+      subscribersRef.current.delete(callback);
+    };
+  }, []);
+
+  // Check if slot has content
+  const hasContent = useCallback((slot: UISlot): boolean => {
+    return slots[slot] !== null;
+  }, [slots]);
+
+  // Get content for a slot
+  const getContent = useCallback((slot: UISlot): SlotContent | null => {
+    return slots[slot];
+  }, [slots]);
+
+  return {
+    slots,
+    render,
+    clear,
+    clearById,
+    clearAll,
+    subscribe,
+    hasContent,
+    getContent,
+  };
+}
+
+// ============================================================================
+// Exports
+// ============================================================================
+
+export { DEFAULT_SLOTS };

package/shells/typescript-shell/packages/client/src/index.css

@@ -0,0 +1,15 @@
+/**
+ * Application Styles
+ *
+ * Themes use unified data-theme attribute:
+ *   data-theme="themename-light" or data-theme="themename-dark"
+ */
+
+/* Built-in design themes */
+@import './themes/wireframe.css';
+@import './themes/minimalist.css';
+@import './themes/almadar.css';
+
+@tailwind base;
+@tailwind components;
+@tailwind utilities;

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

@@ -0,0 +1,134 @@
+/**
+ * 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
+ */
+
+const API_BASE_URL = typeof import.meta !== 'undefined' && import.meta.env?.VITE_API_URL
+  ? import.meta.env.VITE_API_URL
+  : '/api';
+
+/**
+ * API Error class for handling HTTP errors
+ */
+export class ApiError extends Error {
+  constructor(
+    public status: number,
+    public statusText: string,
+    message?: string
+  ) {
+    super(message || `API Error: ${status} ${statusText}`);
+    this.name = 'ApiError';
+  }
+}
+
+/**
+ * Handle response and parse JSON
+ */
+async function handleResponse<T>(response: Response): Promise<T> {
+  if (!response.ok) {
+    let message: string | undefined;
+    try {
+      const errorData = await response.json();
+      message = errorData.message || errorData.error;
+    } catch {
+      // Ignore JSON parse errors
+    }
+    throw new ApiError(response.status, response.statusText, message);
+  }
+
+  // Handle empty responses (e.g., 204 No Content)
+  const text = await response.text();
+  if (!text) {
+    return undefined as T;
+  }
+
+  return JSON.parse(text) as T;
+}
+
+/**
+ * Get default headers for requests
+ */
+function getHeaders(): HeadersInit {
+  const headers: HeadersInit = {
+    'Content-Type': 'application/json',
+  };
+
+  // Add auth token if available (from localStorage or session)
+  const token = typeof localStorage !== 'undefined'
+    ? localStorage.getItem('authToken')
+    : null;
+  if (token) {
+    headers['Authorization'] = `Bearer ${token}`;
+  }
+
+  return headers;
+}
+
+/**
+ * API client with typed methods
+ */
+export const apiClient = {
+  /**
+   * GET request
+   */
+  async get<T>(endpoint: string): Promise<T> {
+    const response = await fetch(`${API_BASE_URL}${endpoint}`, {
+      method: 'GET',
+      headers: getHeaders(),
+    });
+    return handleResponse<T>(response);
+  },
+
+  /**
+   * POST request
+   */
+  async post<T>(endpoint: string, data?: unknown): Promise<T> {
+    const response = await fetch(`${API_BASE_URL}${endpoint}`, {
+      method: 'POST',
+      headers: getHeaders(),
+      body: data ? JSON.stringify(data) : undefined,
+    });
+    return handleResponse<T>(response);
+  },
+
+  /**
+   * PUT request
+   */
+  async put<T>(endpoint: string, data?: unknown): Promise<T> {
+    const response = await fetch(`${API_BASE_URL}${endpoint}`, {
+      method: 'PUT',
+      headers: getHeaders(),
+      body: data ? JSON.stringify(data) : undefined,
+    });
+    return handleResponse<T>(response);
+  },
+
+  /**
+   * PATCH request
+   */
+  async patch<T>(endpoint: string, data?: unknown): Promise<T> {
+    const response = await fetch(`${API_BASE_URL}${endpoint}`, {
+      method: 'PATCH',
+      headers: getHeaders(),
+      body: data ? JSON.stringify(data) : undefined,
+    });
+    return handleResponse<T>(response);
+  },
+
+  /**
+   * DELETE request
+   */
+  async delete<T = void>(endpoint: string): Promise<T> {
+    const response = await fetch(`${API_BASE_URL}${endpoint}`, {
+      method: 'DELETE',
+      headers: getHeaders(),
+    });
+    return handleResponse<T>(response);
+  },
+};
+
+export default apiClient;

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

@@ -0,0 +1,10 @@
+import { clsx, type ClassValue } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+/**
+ * Utility function to merge Tailwind CSS classes
+ * Combines clsx for conditional classes with tailwind-merge to handle conflicts
+ */
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

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

@@ -0,0 +1,114 @@
+/**
+ * Debug utilities for development
+ */
+
+const DEBUG_ENABLED = typeof window !== 'undefined' &&
+  (localStorage.getItem('debug') === 'true' || process.env.NODE_ENV === 'development');
+
+export function isDebugEnabled(): boolean {
+  return DEBUG_ENABLED;
+}
+
+export function debug(...args: unknown[]): void {
+  if (DEBUG_ENABLED) {
+    console.log('[DEBUG]', ...args);
+  }
+}
+
+export function debugGroup(label: string): void {
+  if (DEBUG_ENABLED) {
+    console.group(`[DEBUG] ${label}`);
+  }
+}
+
+export function debugGroupEnd(): void {
+  if (DEBUG_ENABLED) {
+    console.groupEnd();
+  }
+}
+
+export function debugWarn(...args: unknown[]): void {
+  if (DEBUG_ENABLED) {
+    console.warn('[DEBUG]', ...args);
+  }
+}
+
+export function debugError(...args: unknown[]): void {
+  if (DEBUG_ENABLED) {
+    console.error('[DEBUG]', ...args);
+  }
+}
+
+export function debugTable(data: unknown): void {
+  if (DEBUG_ENABLED) {
+    console.table(data);
+  }
+}
+
+export function debugTime(label: string): void {
+  if (DEBUG_ENABLED) {
+    console.time(`[DEBUG] ${label}`);
+  }
+}
+
+export function debugTimeEnd(label: string): void {
+  if (DEBUG_ENABLED) {
+    console.timeEnd(`[DEBUG] ${label}`);
+  }
+}
+
+// =============================================================================
+// Game-specific debug utilities
+// =============================================================================
+
+/**
+ * Debug input events (keyboard, mouse, touch)
+ * @param inputType - Type of input (e.g., 'keydown', 'keyup', 'mouse')
+ * @param data - Input data to log
+ */
+export function debugInput(inputType: string, data: unknown): void {
+  if (DEBUG_ENABLED) {
+    console.log(`[DEBUG:INPUT] ${inputType}:`, data);
+  }
+}
+
+/**
+ * Debug collision events between entities
+ * @param entityA - First entity in collision
+ * @param entityB - Second entity in collision
+ * @param details - Additional collision details
+ */
+export function debugCollision(
+  entityA: { id?: string; type?: string },
+  entityB: { id?: string; type?: string },
+  details?: unknown
+): void {
+  if (DEBUG_ENABLED) {
+    console.log(
+      `[DEBUG:COLLISION] ${entityA.type || entityA.id} <-> ${entityB.type || entityB.id}`,
+      details ?? ''
+    );
+  }
+}
+
+/**
+ * Debug physics updates (position, velocity)
+ * @param entityId - Entity identifier
+ * @param physics - Physics data to log
+ */
+export function debugPhysics(entityId: string, physics: unknown): void {
+  if (DEBUG_ENABLED) {
+    console.log(`[DEBUG:PHYSICS] ${entityId}:`, physics);
+  }
+}
+
+/**
+ * Debug game state changes
+ * @param stateName - Name of the state that changed
+ * @param value - New state value
+ */
+export function debugGameState(stateName: string, value: unknown): void {
+  if (DEBUG_ENABLED) {
+    console.log(`[DEBUG:GAME_STATE] ${stateName}:`, value);
+  }
+}

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

@@ -0,0 +1,108 @@
+/**
+ * Debug Registry - Central event log for debugging
+ *
+ * @packageDocumentation
+ */
+
+export type DebugEventType =
+  | 'state-change'
+  | 'event-fired'
+  | 'effect-executed'
+  | 'guard-evaluated'
+  | 'error'
+  | 'warning'
+  | 'info';
+
+export interface DebugEvent {
+  id: string;
+  type: DebugEventType;
+  source: string;
+  message: string;
+  data?: Record<string, unknown>;
+  timestamp: number;
+}
+
+type ChangeListener = () => void;
+
+const events: DebugEvent[] = [];
+const listeners = new Set<ChangeListener>();
+const MAX_EVENTS = 500;
+
+function notifyListeners(): void {
+  listeners.forEach(listener => listener());
+}
+
+export function logDebugEvent(
+  type: DebugEventType,
+  source: string,
+  message: string,
+  data?: Record<string, unknown>
+): void {
+  const event: DebugEvent = {
+    id: `event-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`,
+    type,
+    source,
+    message,
+    data,
+    timestamp: Date.now(),
+  };
+
+  events.unshift(event);
+
+  // Keep events bounded
+  if (events.length > MAX_EVENTS) {
+    events.pop();
+  }
+
+  notifyListeners();
+}
+
+export function logStateChange(source: string, from: string, to: string, event?: string): void {
+  logDebugEvent('state-change', source, `${from} → ${to}`, { from, to, event });
+}
+
+export function logEventFired(source: string, eventName: string, payload?: unknown): void {
+  logDebugEvent('event-fired', source, eventName, { eventName, payload });
+}
+
+export function logEffectExecuted(source: string, effectType: string, details?: unknown): void {
+  logDebugEvent('effect-executed', source, effectType, { effectType, details });
+}
+
+export function logError(source: string, message: string, error?: unknown): void {
+  logDebugEvent('error', source, message, { error });
+}
+
+export function logWarning(source: string, message: string, data?: Record<string, unknown>): void {
+  logDebugEvent('warning', source, message, data);
+}
+
+export function logInfo(source: string, message: string, data?: Record<string, unknown>): void {
+  logDebugEvent('info', source, message, data);
+}
+
+export function getDebugEvents(): DebugEvent[] {
+  return [...events];
+}
+
+export function getRecentEvents(count: number): DebugEvent[] {
+  return events.slice(0, count);
+}
+
+export function getEventsByType(type: DebugEventType): DebugEvent[] {
+  return events.filter(e => e.type === type);
+}
+
+export function getEventsBySource(source: string): DebugEvent[] {
+  return events.filter(e => e.source === source);
+}
+
+export function subscribeToDebugEvents(listener: ChangeListener): () => void {
+  listeners.add(listener);
+  return () => listeners.delete(listener);
+}
+
+export function clearDebugEvents(): void {
+  events.length = 0;
+  notifyListeners();
+}