@almadar/cli 0.3.1 → 0.3.3

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

@@ -0,0 +1,17 @@
+/**
+ * Loaders Module
+ *
+ * Asset and resource loading utilities for games.
+ */
+
+export {
+    AssetLoader,
+    loadAsset,
+    loadTileset,
+    type LoadedAsset,
+    type SpritesheetMetadata,
+    type TileRect,
+    type AnimationConfig,
+    type AssetManifestEntry,
+    type AssetManifest,
+} from './AssetLoader';

package/shells/typescript-shell/packages/client/src/main.tsx

@@ -0,0 +1,24 @@
+/**
+ * Application Entry Point
+ *
+ * Uses unified ThemeProvider with data-theme="name-light/dark" attribute.
+ * Theme configuration is loaded from generated/theme-config.ts
+ */
+
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { AuthProvider } from './features/auth';
+import { ThemeProvider } from './context';
+import { THEMES, DEFAULT_THEME, DEFAULT_MODE } from './generated/theme-config';
+import { App } from './App';
+import './index.css';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <ThemeProvider themes={THEMES} defaultTheme={DEFAULT_THEME} defaultMode={DEFAULT_MODE}>
+      <AuthProvider>
+        <App />
+      </AuthProvider>
+    </ThemeProvider>
+  </React.StrictMode>
+);

package/shells/typescript-shell/packages/client/src/pages/index.ts

@@ -0,0 +1,2 @@
+// Graph-generated pages will be exported here
+// Example: export { DashboardPage } from './DashboardPage';

package/shells/typescript-shell/packages/client/src/providers/EventBusProvider.tsx

@@ -0,0 +1,212 @@
+/**
+ * EventBusProvider - React context provider for the event bus
+ *
+ * Provides a page-scoped event bus for trait communication.
+ * Each page has its own event bus instance.
+ *
+ * NOTE: Selection state has been moved to SelectionProvider.
+ * Use SelectionProvider for tracking selected entities.
+ *
+ * @packageDocumentation
+ */
+
+import React, { createContext, useCallback, useRef, useMemo, type ReactNode } from 'react';
+import type { KFlowEvent, EventListener, Unsubscribe, EventBusContextType } from '../hooks/event-bus-types';
+
+// ============================================================================
+// Context
+// ============================================================================
+
+/**
+ * Extended context type for backward compatibility.
+ *
+ * @deprecated getSelectedEntity and clearSelectedEntity are deprecated.
+ * Use SelectionProvider and useSelection hook instead.
+ */
+export interface EventBusContextTypeExtended extends EventBusContextType {
+  /**
+   * @deprecated Use useSelection from SelectionProvider instead.
+   * This method now returns null - selection state moved to SelectionProvider.
+   */
+  getSelectedEntity: () => unknown | null;
+  /**
+   * @deprecated Use useSelection from SelectionProvider instead.
+   * This method is now a no-op - selection state moved to SelectionProvider.
+   */
+  clearSelectedEntity: () => void;
+}
+
+export const EventBusContext = createContext<EventBusContextTypeExtended | null>(null);
+
+// ============================================================================
+// Provider Component
+// ============================================================================
+
+interface EventBusProviderProps {
+  children: ReactNode;
+  /** Enable debug logging in development */
+  debug?: boolean;
+}
+
+/**
+ * Provider component for the page event bus.
+ *
+ * This is a pure pub/sub event bus. For selection state,
+ * use SelectionProvider which listens to events and maintains state.
+ *
+ * @example
+ * ```tsx
+ * function TaskDetailPage() {
+ *   return (
+ *     <EventBusProvider debug={process.env.NODE_ENV === 'development'}>
+ *       <SelectionProvider>
+ *         <TaskHeader />
+ *         <TaskForm />
+ *         <TaskActions />
+ *       </SelectionProvider>
+ *     </EventBusProvider>
+ *   );
+ * }
+ * ```
+ */
+export function EventBusProvider({ children, debug = false }: EventBusProviderProps) {
+  // Store listeners by event type
+  const listenersRef = useRef<Map<string, Set<EventListener>>>(new Map());
+
+  // Track if deprecation warning has been shown
+  const deprecationWarningShown = useRef(false);
+
+  /**
+   * @deprecated Use useSelection from SelectionProvider instead.
+   */
+  const getSelectedEntity = useCallback(() => {
+    if (!deprecationWarningShown.current) {
+      console.warn(
+        '[EventBus] getSelectedEntity is deprecated. ' +
+        'Use SelectionProvider and useSelection hook instead. ' +
+        'See SelectionProvider.tsx for migration guide.'
+      );
+      deprecationWarningShown.current = true;
+    }
+    return null;
+  }, []);
+
+  /**
+   * @deprecated Use useSelection from SelectionProvider instead.
+   */
+  const clearSelectedEntity = useCallback(() => {
+    if (!deprecationWarningShown.current) {
+      console.warn(
+        '[EventBus] clearSelectedEntity is deprecated. ' +
+        'Use SelectionProvider and useSelection hook instead. ' +
+        'See SelectionProvider.tsx for migration guide.'
+      );
+      deprecationWarningShown.current = true;
+    }
+  }, []);
+
+  /**
+   * Emit an event to all listeners of that type.
+   */
+  const emit = useCallback((type: string, payload?: Record<string, unknown>) => {
+    const event: KFlowEvent = {
+      type,
+      payload,
+      timestamp: Date.now(),
+    };
+
+    const listeners = listenersRef.current.get(type);
+    const listenerCount = listeners?.size ?? 0;
+
+    if (debug) {
+      if (listenerCount > 0) {
+        console.log(`[EventBus] Emit: ${type} → ${listenerCount} listener(s)`, payload);
+      } else {
+        console.warn(`[EventBus] Emit: ${type} (NO LISTENERS - event may be lost!)`, payload);
+      }
+    }
+
+    if (listeners) {
+      // Create a copy to avoid issues if listener modifies the set
+      const listenersCopy = Array.from(listeners);
+      for (const listener of listenersCopy) {
+        try {
+          listener(event);
+        } catch (error) {
+          console.error(`[EventBus] Error in listener for '${type}':`, error);
+        }
+      }
+    }
+  }, [debug]);
+
+  /**
+   * Subscribe to an event type.
+   * Returns an unsubscribe function.
+   */
+  const on = useCallback((type: string, listener: EventListener): Unsubscribe => {
+    if (!listenersRef.current.has(type)) {
+      listenersRef.current.set(type, new Set());
+    }
+
+    const listeners = listenersRef.current.get(type)!;
+    listeners.add(listener);
+
+    if (debug) {
+      console.log(`[EventBus] Subscribed to '${type}', total: ${listeners.size}`);
+    }
+
+    // Return unsubscribe function
+    return () => {
+      listeners.delete(listener);
+      if (debug) {
+        console.log(`[EventBus] Unsubscribed from '${type}', remaining: ${listeners.size}`);
+      }
+      // Clean up empty sets
+      if (listeners.size === 0) {
+        listenersRef.current.delete(type);
+      }
+    };
+  }, [debug]);
+
+  /**
+   * Subscribe to an event type, but only fire once.
+   */
+  const once = useCallback((type: string, listener: EventListener): Unsubscribe => {
+    const wrappedListener: EventListener = (event) => {
+      // Remove self before calling listener
+      listenersRef.current.get(type)?.delete(wrappedListener);
+      listener(event);
+    };
+
+    return on(type, wrappedListener);
+  }, [on]);
+
+  /**
+   * Check if there are any listeners for an event type.
+   */
+  const hasListeners = useCallback((type: string): boolean => {
+    const listeners = listenersRef.current.get(type);
+    return listeners !== undefined && listeners.size > 0;
+  }, []);
+
+  // Memoize context value
+  const contextValue = useMemo(
+    () => ({
+      emit,
+      on,
+      once,
+      hasListeners,
+      getSelectedEntity,
+      clearSelectedEntity,
+    }),
+    [emit, on, once, hasListeners, getSelectedEntity, clearSelectedEntity]
+  );
+
+  return (
+    <EventBusContext.Provider value={contextValue}>
+      {children}
+    </EventBusContext.Provider>
+  );
+}
+
+export type { EventBusContextType };

package/shells/typescript-shell/packages/client/src/providers/FetchedDataProvider.tsx

@@ -0,0 +1,280 @@
+/**
+ * FetchedDataProvider
+ *
+ * Provides server-fetched entity data to the client runtime.
+ * This context stores data returned from compiled event handlers
+ * via the `data` field in EventResponse.
+ *
+ * Data Flow:
+ * 1. Client sends event to server
+ * 2. Server executes compiled handler with fetch effects
+ * 3. Server returns { data: { EntityName: [...records] }, clientEffects: [...] }
+ * 4. Provider stores data in this context
+ * 5. Pattern components access data via useFetchedData hook
+ *
+ * Used by both Builder preview and compiled shell.
+ *
+ * @packageDocumentation
+ */
+
+import React, { createContext, useContext, useState, useCallback, useMemo } from 'react';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface EntityRecord {
+  id: string;
+  [key: string]: unknown;
+}
+
+export interface FetchedDataState {
+  /** Entity data by entity name (e.g., { Task: [...], User: [...] }) */
+  data: Record<string, EntityRecord[]>;
+  /** Timestamp of last fetch per entity */
+  fetchedAt: Record<string, number>;
+  /** Whether data is currently being fetched */
+  loading: boolean;
+  /** Last error message */
+  error: string | null;
+}
+
+export interface FetchedDataContextValue {
+  /** Get all records for an entity */
+  getData: (entityName: string) => EntityRecord[];
+  /** Get a single record by ID */
+  getById: (entityName: string, id: string) => EntityRecord | undefined;
+  /** Check if entity data exists */
+  hasData: (entityName: string) => boolean;
+  /** Get fetch timestamp for entity */
+  getFetchedAt: (entityName: string) => number | undefined;
+  /** Update data from server response */
+  setData: (data: Record<string, unknown[]>) => void;
+  /** Clear all fetched data */
+  clearData: () => void;
+  /** Clear data for specific entity */
+  clearEntity: (entityName: string) => void;
+  /** Current loading state */
+  loading: boolean;
+  /** Set loading state */
+  setLoading: (loading: boolean) => void;
+  /** Current error */
+  error: string | null;
+  /** Set error */
+  setError: (error: string | null) => void;
+}
+
+// ============================================================================
+// Context
+// ============================================================================
+
+export const FetchedDataContext = createContext<FetchedDataContextValue | null>(null);
+
+// ============================================================================
+// Provider
+// ============================================================================
+
+export interface FetchedDataProviderProps {
+  /** Initial data (optional) */
+  initialData?: Record<string, unknown[]>;
+  /** Children */
+  children: React.ReactNode;
+}
+
+/**
+ * FetchedDataProvider - Provides server-fetched entity data
+ *
+ * @example
+ * ```tsx
+ * <FetchedDataProvider>
+ *   <OrbitalProvider>
+ *     <App />
+ *   </OrbitalProvider>
+ * </FetchedDataProvider>
+ * ```
+ */
+export function FetchedDataProvider({
+  initialData,
+  children,
+}: FetchedDataProviderProps): React.ReactElement {
+  const [state, setState] = useState<FetchedDataState>(() => ({
+    data: (initialData as Record<string, EntityRecord[]>) || {},
+    fetchedAt: {},
+    loading: false,
+    error: null,
+  }));
+
+  const getData = useCallback(
+    (entityName: string): EntityRecord[] => {
+      return state.data[entityName] || [];
+    },
+    [state.data]
+  );
+
+  const getById = useCallback(
+    (entityName: string, id: string): EntityRecord | undefined => {
+      const records = state.data[entityName];
+      return records?.find((r) => r.id === id);
+    },
+    [state.data]
+  );
+
+  const hasData = useCallback(
+    (entityName: string): boolean => {
+      return entityName in state.data && state.data[entityName].length > 0;
+    },
+    [state.data]
+  );
+
+  const getFetchedAt = useCallback(
+    (entityName: string): number | undefined => {
+      return state.fetchedAt[entityName];
+    },
+    [state.fetchedAt]
+  );
+
+  const setData = useCallback((data: Record<string, unknown[]>): void => {
+    const now = Date.now();
+    setState((prev) => ({
+      ...prev,
+      data: {
+        ...prev.data,
+        ...(data as Record<string, EntityRecord[]>),
+      },
+      fetchedAt: {
+        ...prev.fetchedAt,
+        ...Object.keys(data).reduce(
+          (acc, key) => ({ ...acc, [key]: now }),
+          {}
+        ),
+      },
+      loading: false,
+      error: null,
+    }));
+  }, []);
+
+  const clearData = useCallback((): void => {
+    setState((prev) => ({
+      ...prev,
+      data: {},
+      fetchedAt: {},
+    }));
+  }, []);
+
+  const clearEntity = useCallback((entityName: string): void => {
+    setState((prev) => {
+      const newData = { ...prev.data };
+      const newFetchedAt = { ...prev.fetchedAt };
+      delete newData[entityName];
+      delete newFetchedAt[entityName];
+      return {
+        ...prev,
+        data: newData,
+        fetchedAt: newFetchedAt,
+      };
+    });
+  }, []);
+
+  const setLoading = useCallback((loading: boolean): void => {
+    setState((prev) => ({ ...prev, loading }));
+  }, []);
+
+  const setError = useCallback((error: string | null): void => {
+    setState((prev) => ({ ...prev, error, loading: false }));
+  }, []);
+
+  const contextValue = useMemo<FetchedDataContextValue>(
+    () => ({
+      getData,
+      getById,
+      hasData,
+      getFetchedAt,
+      setData,
+      clearData,
+      clearEntity,
+      loading: state.loading,
+      setLoading,
+      error: state.error,
+      setError,
+    }),
+    [
+      getData,
+      getById,
+      hasData,
+      getFetchedAt,
+      setData,
+      clearData,
+      clearEntity,
+      state.loading,
+      setLoading,
+      state.error,
+      setError,
+    ]
+  );
+
+  return (
+    <FetchedDataContext.Provider value={contextValue}>
+      {children}
+    </FetchedDataContext.Provider>
+  );
+}
+
+// ============================================================================
+// Hooks
+// ============================================================================
+
+/**
+ * Access the fetched data context.
+ * Returns null if not within a FetchedDataProvider.
+ */
+export function useFetchedDataContext(): FetchedDataContextValue | null {
+  return useContext(FetchedDataContext);
+}
+
+/**
+ * Access fetched data with fallback behavior.
+ * If not in a provider, returns empty data.
+ */
+export function useFetchedData(): FetchedDataContextValue {
+  const context = useContext(FetchedDataContext);
+  if (!context) {
+    // Return a no-op implementation when not wrapped in provider
+    return {
+      getData: () => [],
+      getById: () => undefined,
+      hasData: () => false,
+      getFetchedAt: () => undefined,
+      setData: () => {},
+      clearData: () => {},
+      clearEntity: () => {},
+      loading: false,
+      setLoading: () => {},
+      error: null,
+      setError: () => {},
+    };
+  }
+  return context;
+}
+
+/**
+ * Access fetched data for a specific entity.
+ * Provides a convenient API for entity-specific operations.
+ */
+export function useFetchedEntity(entityName: string) {
+  const context = useFetchedData();
+
+  return {
+    /** All fetched records for this entity */
+    records: context.getData(entityName),
+    /** Get a record by ID */
+    getById: (id: string) => context.getById(entityName, id),
+    /** Whether data has been fetched for this entity */
+    hasData: context.hasData(entityName),
+    /** When data was last fetched */
+    fetchedAt: context.getFetchedAt(entityName),
+    /** Whether data is loading */
+    loading: context.loading,
+    /** Current error */
+    error: context.error,
+  };
+}

package/shells/typescript-shell/packages/client/src/providers/OrbitalProvider.tsx

@@ -0,0 +1,136 @@
+/**
+ * OrbitalProvider
+ *
+ * Unified provider that combines all required contexts for Almadar applications.
+ * Provides a single import for both Builder preview and compiled shell.
+ *
+ * Combines:
+ * - ThemeProvider - Theme and color mode management
+ * - EventBusProvider - Page-scoped event pub/sub
+ * - UISlotProvider - UI slot management for render_ui effects
+ * - SelectionProvider - Selected entity tracking
+ * - FetchedDataProvider - Server-fetched entity data
+ *
+ * @packageDocumentation
+ */
+
+import React, { type ReactNode } from 'react';
+import { ThemeProvider, type ThemeProviderProps, type ThemeDefinition } from '../context/ThemeContext';
+import { UISlotProvider } from '../context/UISlotContext';
+import { EventBusProvider } from './EventBusProvider';
+import { SelectionProvider } from './SelectionProvider';
+import { FetchedDataProvider } from './FetchedDataProvider';
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface OrbitalProviderProps {
+  children: ReactNode;
+
+  // Theme options
+  /** Custom themes (merged with built-in themes) */
+  themes?: ThemeDefinition[];
+  /** Default theme name */
+  defaultTheme?: string;
+  /** Default color mode */
+  defaultMode?: 'light' | 'dark' | 'system';
+
+  // Debug options
+  /** Enable debug logging for all providers */
+  debug?: boolean;
+
+  // Data options
+  /** Initial fetched data */
+  initialData?: Record<string, unknown[]>;
+}
+
+// ============================================================================
+// Provider Component
+// ============================================================================
+
+/**
+ * OrbitalProvider - Unified context provider for Almadar applications
+ *
+ * Wraps your application with all required providers in the correct order.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * function App() {
+ *   return (
+ *     <OrbitalProvider>
+ *       <Router>
+ *         <Routes />
+ *       </Router>
+ *     </OrbitalProvider>
+ *   );
+ * }
+ *
+ * // With configuration
+ * function App() {
+ *   return (
+ *     <OrbitalProvider
+ *       defaultTheme="minimalist"
+ *       defaultMode="dark"
+ *       debug={process.env.NODE_ENV === 'development'}
+ *     >
+ *       <Router>
+ *         <Routes />
+ *       </Router>
+ *     </OrbitalProvider>
+ *   );
+ * }
+ *
+ * // With custom themes from schema
+ * import { THEMES } from './generated/theme-manifest';
+ *
+ * function App() {
+ *   return (
+ *     <OrbitalProvider themes={THEMES} defaultTheme="ocean">
+ *       <Router>
+ *         <Routes />
+ *       </Router>
+ *     </OrbitalProvider>
+ *   );
+ * }
+ * ```
+ */
+export function OrbitalProvider({
+  children,
+  themes,
+  defaultTheme = 'wireframe',
+  defaultMode = 'system',
+  debug = false,
+  initialData,
+}: OrbitalProviderProps): React.ReactElement {
+  return (
+    <ThemeProvider
+      themes={themes}
+      defaultTheme={defaultTheme}
+      defaultMode={defaultMode}
+    >
+      <FetchedDataProvider initialData={initialData}>
+        <EventBusProvider debug={debug}>
+          <UISlotProvider>
+            <SelectionProvider debug={debug}>
+              {children}
+            </SelectionProvider>
+          </UISlotProvider>
+        </EventBusProvider>
+      </FetchedDataProvider>
+    </ThemeProvider>
+  );
+}
+
+OrbitalProvider.displayName = 'OrbitalProvider';
+
+// ============================================================================
+// Re-exports for convenience
+// ============================================================================
+
+export { ThemeProvider } from '../context/ThemeContext';
+export { UISlotProvider } from '../context/UISlotContext';
+export { EventBusProvider } from './EventBusProvider';
+export { SelectionProvider } from './SelectionProvider';
+export { FetchedDataProvider } from './FetchedDataProvider';