@almadar/cli 1.0.5 → 1.0.7

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

@@ -1,17 +0,0 @@
-/**
- * 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

@@ -1,24 +0,0 @@
-/**
- * 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

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

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

@@ -1,212 +0,0 @@
-/**
- * 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

@@ -1,280 +0,0 @@
-/**
- * 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

@@ -1,136 +0,0 @@
-/**
- * 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';