@almadar/ui 1.0.0

package/dist/hooks/index.d.ts

@@ -0,0 +1,1006 @@
+import { OrbitalSchema } from '@almadar/core';
+import { E as EventBusContextType, a as EventListener } from '../event-bus-types-8-cjyMxw.js';
+export { K as KFlowEvent, U as Unsubscribe } from '../event-bus-types-8-cjyMxw.js';
+export { D as DEFAULT_SLOTS, R as RenderUIConfig, b as SlotAnimation, c as SlotChangeCallback, S as SlotContent, a as UISlot, U as UISlotManager, u as useUISlotManager } from '../useUISlots-mnggE9X9.js';
+import * as _tanstack_react_query from '@tanstack/react-query';
+import { Entity, getEntity, getByType, getAllEntities, getSingleton, spawnEntity, updateEntity, updateSingleton, removeEntity, clearEntities } from '../stores/index.js';
+
+/**
+ * useOrbitalHistory Hook
+ *
+ * Provides version control timeline for OrbitalSchema changes.
+ * Tracks changesets and snapshots, supports reverting to previous versions.
+ */
+
+interface ChangeSummary {
+    added: number;
+    modified: number;
+    removed: number;
+}
+interface HistoryTimelineItem {
+    id: string;
+    type: 'changeset' | 'snapshot';
+    version: number;
+    timestamp: number;
+    description: string;
+    source?: string;
+    summary?: ChangeSummary;
+    reason?: string;
+}
+interface RevertResult {
+    success: boolean;
+    error?: string;
+    restoredSchema?: OrbitalSchema;
+}
+interface UseOrbitalHistoryOptions {
+    appId: string | null;
+    /** Firebase auth token for authenticated API requests */
+    authToken?: string | null;
+    /** User ID for x-user-id header (required for Firestore path) */
+    userId?: string | null;
+    onHistoryChange?: (timeline: HistoryTimelineItem[]) => void;
+    onRevertSuccess?: (restoredSchema: OrbitalSchema) => void;
+}
+interface UseOrbitalHistoryResult {
+    timeline: HistoryTimelineItem[];
+    currentVersion: number;
+    isLoading: boolean;
+    error: string | null;
+    revertToSnapshot: (snapshotId: string) => Promise<RevertResult>;
+    refresh: () => Promise<void>;
+}
+declare function useOrbitalHistory(options: UseOrbitalHistoryOptions): UseOrbitalHistoryResult;
+
+/**
+ * useFileSystem Hook
+ *
+ * Provides file system operations for WebContainer-based file management.
+ * Handles booting, mounting files, reading/writing, and tree operations.
+ */
+interface FileNode {
+    path: string;
+    name: string;
+    type: 'file' | 'directory';
+    children?: FileNode[];
+}
+type FileSystemStatus = 'idle' | 'booting' | 'ready' | 'running' | 'error';
+interface FileSystemFile {
+    path: string;
+    content: string;
+}
+interface SelectedFile {
+    path: string;
+    content: string;
+    language?: string;
+    isDirty?: boolean;
+}
+interface UseFileSystemResult {
+    status: FileSystemStatus;
+    error: string | null;
+    isLoading: boolean;
+    files: FileNode[];
+    selectedFile: SelectedFile | null;
+    selectedPath: string | null;
+    previewUrl: string | null;
+    boot: () => Promise<void>;
+    mountFiles: (files: FileSystemFile[] | Record<string, unknown>) => Promise<void>;
+    readFile: (path: string) => Promise<string>;
+    writeFile: (path: string, content: string) => Promise<void>;
+    selectFile: (path: string) => Promise<void>;
+    updateContent: (pathOrContent: string, content?: string) => void;
+    updateSelectedContent: (content: string) => void;
+    refreshTree: () => Promise<void>;
+    runCommand: (command: string) => Promise<{
+        exitCode: number;
+        output: string;
+    }>;
+    startDevServer: () => Promise<void>;
+}
+declare function useFileSystem(): UseFileSystemResult;
+
+/**
+ * useExtensions Hook
+ *
+ * Manages loading and accessing language/editor extensions.
+ */
+interface Extension {
+    id: string;
+    name: string;
+    language?: string;
+    loaded: boolean;
+}
+interface ExtensionEntry {
+    file: string;
+    language?: string;
+}
+interface ExtensionManifest {
+    languages: Record<string, {
+        extensions: string[];
+        icon?: string;
+        color?: string;
+    }>;
+    extensions: ExtensionEntry[];
+}
+interface UseExtensionsOptions {
+    appId: string;
+    loadOnMount?: boolean;
+}
+interface UseExtensionsResult {
+    extensions: Extension[];
+    manifest: ExtensionManifest;
+    isLoading: boolean;
+    error: string | null;
+    loadExtension: (extensionId: string) => Promise<void>;
+    loadExtensions: () => Promise<void>;
+    getExtensionForFile: (filename: string) => Extension | null;
+}
+declare function useExtensions(options: UseExtensionsOptions): UseExtensionsResult;
+
+/**
+ * useFileEditor Hook
+ *
+ * Manages file editing state and operations.
+ */
+
+interface OpenFile {
+    path: string;
+    content: string;
+    isDirty: boolean;
+    language?: string;
+}
+interface UseFileEditorOptions {
+    extensions: UseExtensionsResult;
+    fileSystem: UseFileSystemResult;
+    onSchemaUpdate?: (schema: OrbitalSchema) => Promise<void>;
+}
+interface FileEditResult {
+    success: boolean;
+    action?: 'updated_schema' | 'converted_extension' | 'saved_extension' | 'saved';
+    error?: string;
+}
+interface UseFileEditorResult {
+    openFiles: OpenFile[];
+    activeFile: OpenFile | null;
+    isSaving: boolean;
+    openFile: (path: string) => Promise<void>;
+    closeFile: (path: string) => void;
+    setActiveFile: (path: string) => void;
+    updateFileContent: (path: string, content: string) => void;
+    handleFileEdit: (path: string, content: string) => Promise<FileEditResult>;
+    saveFile: (path: string) => Promise<void>;
+    saveAllFiles: () => Promise<void>;
+}
+declare function useFileEditor(options: UseFileEditorOptions): UseFileEditorResult;
+
+/**
+ * useCompile Hook
+ *
+ * Handles schema compilation to generate application files.
+ */
+interface SchemaLike {
+    name: string;
+    version?: string;
+    [key: string]: unknown;
+}
+type CompileStage = 'idle' | 'compiling' | 'done' | 'error';
+interface CompileResult {
+    success: boolean;
+    files?: Array<{
+        path: string;
+        content: string;
+    }>;
+    errors?: string[];
+}
+interface UseCompileResult {
+    isCompiling: boolean;
+    stage: CompileStage;
+    lastResult: CompileResult | null;
+    error: string | null;
+    compileSchema: (schema: SchemaLike) => Promise<CompileResult | null>;
+}
+declare function useCompile(): UseCompileResult;
+
+/**
+ * usePreview Hook
+ *
+ * Stub implementation for app preview state management.
+ * Actual API calls should be implemented by the consuming client.
+ */
+
+interface PreviewApp {
+    id: string;
+    name: string;
+    status: 'loading' | 'ready' | 'error';
+    schema?: OrbitalSchema;
+    graphView: {
+        version: string;
+    };
+}
+interface Notification {
+    id: string;
+    type: 'info' | 'warning' | 'error' | 'success';
+    title: string;
+    message: string;
+    timestamp: number;
+    read?: boolean;
+    actionLabel?: string;
+    onAction?: () => void;
+    autoDismiss?: boolean;
+    dismissAfter?: number;
+}
+interface NotificationsState {
+    notifications: Notification[];
+    isPanelOpen: boolean;
+    closePanel: () => void;
+    dismissNotification: (id: string) => void;
+    markAsRead: (id: string) => void;
+    clearAll: () => void;
+}
+interface ErrorToast {
+    message: string;
+}
+interface UsePreviewResult {
+    previewUrl: string | null;
+    isLoading: boolean;
+    error: string | null;
+    loadError: string | null;
+    app: PreviewApp | null;
+    isFullscreen: boolean;
+    isExecutingEvent: boolean;
+    errorToast: ErrorToast | null;
+    currentStateName: string | null;
+    notifications: NotificationsState;
+    startPreview: () => Promise<void>;
+    stopPreview: () => Promise<void>;
+    refresh: () => Promise<void>;
+    handleRefresh: () => Promise<void>;
+    handleReset: () => Promise<void>;
+    toggleFullscreen: () => void;
+    setErrorToast: (toast: ErrorToast | null) => void;
+    dismissErrorToast: () => void;
+}
+interface UsePreviewOptions {
+    appId?: string;
+}
+declare function usePreview(options?: UsePreviewOptions): UsePreviewResult;
+
+/**
+ * useDeepAgentGeneration Hook
+ *
+ * Stub implementation for deep agent generation functionality.
+ */
+
+interface DeepAgentActionRequest {
+    id: string;
+    type: string;
+    tool: string;
+    args: Record<string, unknown>;
+    description?: string;
+    allowedDecisions: ('approve' | 'edit' | 'reject')[];
+    status: 'pending' | 'approved' | 'rejected' | 'edited';
+}
+interface DeepAgentInterrupt {
+    id: string;
+    type: 'tool_calls' | 'confirmation' | 'error';
+    message?: string;
+    actionRequests: DeepAgentActionRequest[];
+    timestamp: number;
+    threadId?: string;
+}
+interface GenerationRequest {
+    id: string;
+    prompt: string;
+    status: 'pending' | 'running' | 'completed' | 'failed';
+    result?: OrbitalSchema;
+    error?: string;
+}
+interface GenerationProgress {
+    stage: string;
+    percent: number;
+    message: string;
+}
+interface UseDeepAgentGenerationResult {
+    requests: GenerationRequest[];
+    currentRequest: GenerationRequest | null;
+    isGenerating: boolean;
+    isLoading: boolean;
+    isComplete: boolean;
+    progress: GenerationProgress;
+    error: string | null;
+    interrupt: DeepAgentInterrupt | null;
+    generate: (prompt: string) => Promise<OrbitalSchema | null>;
+    startGeneration: (skill: string, prompt: string, options?: Record<string, unknown>) => Promise<void>;
+    cancelGeneration: () => void;
+    clearRequests: () => void;
+    submitInterruptDecisions: (decisions: unknown[]) => void;
+}
+declare function useDeepAgentGeneration(): UseDeepAgentGenerationResult;
+
+/**
+ * useAgentChat Hook
+ *
+ * Stub implementation for agent chat functionality.
+ */
+
+interface ChatMessage {
+    id: string;
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+    timestamp: number;
+}
+type AvatarRole = 'user' | 'assistant' | 'system';
+type FileOperation = 'ls' | 'read_file' | 'write_file' | 'edit_file';
+type Activity = {
+    type: 'message';
+    role: AvatarRole;
+    content: string;
+    timestamp: number;
+    isStreaming?: boolean;
+} | {
+    type: 'tool_call';
+    tool: string;
+    args: Record<string, unknown>;
+    timestamp: number;
+    isExecuting?: boolean;
+} | {
+    type: 'tool_result';
+    tool: string;
+    result: unknown;
+    success: boolean;
+    timestamp: number;
+} | {
+    type: 'file_operation';
+    operation: FileOperation;
+    path: string;
+    success?: boolean;
+    timestamp: number;
+} | {
+    type: 'schema_diff';
+    filePath: string;
+    hunks: DiffHunk[];
+    timestamp: number;
+} | {
+    type: 'error';
+    message: string;
+    code?: string;
+    timestamp: number;
+};
+interface TodoActivity {
+    type: 'thinking' | 'tool_call' | 'tool_result' | 'code_change';
+    content: string;
+    timestamp: number;
+    tool?: string;
+    success?: boolean;
+    filePath?: string;
+    diff?: string;
+}
+interface Todo {
+    id: string;
+    task: string;
+    status: 'pending' | 'in_progress' | 'completed';
+    latestActivity?: TodoActivity;
+    activityHistory?: TodoActivity[];
+}
+interface DiffHunk {
+    oldStart: number;
+    oldLines: number;
+    newStart: number;
+    newLines: number;
+    lines: Array<{
+        type: 'add' | 'remove' | 'context';
+        content: string;
+    }>;
+}
+interface SchemaDiff {
+    id: string;
+    filePath: string;
+    hunks: DiffHunk[];
+    timestamp: number;
+    addedLines: number;
+    removedLines: number;
+}
+type AgentStatus = 'idle' | 'running' | 'complete' | 'error' | 'interrupted';
+interface UseAgentChatOptions {
+    appId?: string;
+    onComplete?: (schema?: unknown) => void;
+    onSchemaChange?: (diff?: unknown) => void;
+    onError?: (error: Error | string) => void;
+}
+interface UseAgentChatResult {
+    messages: ChatMessage[];
+    status: AgentStatus;
+    activities: Activity[];
+    todos: Todo[];
+    schemaDiffs: SchemaDiff[];
+    isLoading: boolean;
+    error: string | null;
+    threadId: string | null;
+    interrupt: DeepAgentInterrupt | null;
+    sendMessage: (content: string) => Promise<void>;
+    startGeneration: (skill: string | string[], prompt: string, options?: Record<string, unknown>) => Promise<void>;
+    continueConversation: (message: string | string[]) => Promise<void>;
+    resumeWithDecision: (decisions: unknown[]) => Promise<void>;
+    cancel: () => void;
+    clearMessages: () => void;
+    clearHistory: () => void;
+}
+declare function useAgentChat(options?: UseAgentChatOptions): UseAgentChatResult;
+
+/**
+ * useValidation Hook
+ *
+ * Stub implementation for schema validation.
+ */
+interface LLMErrorContext {
+    rawValuePreview?: string;
+    expectedType?: string;
+    actualType?: string;
+    source?: {
+        agent: 'requirements' | 'builder' | 'view-planner';
+        operation: string;
+        promptHash?: string;
+    };
+    tokenUsage?: {
+        prompt: number;
+        completion: number;
+    };
+}
+interface ValidationError {
+    code: string;
+    message: string;
+    path?: string;
+    severity: 'error' | 'warning';
+    suggestion?: string;
+    validValues?: string[];
+    expectedShape?: string;
+    fixGuidance?: string;
+    llmContext?: LLMErrorContext;
+}
+interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+    warnings: ValidationError[];
+}
+type ValidationStage = 'idle' | 'validating' | 'fixing' | 'complete';
+interface UseValidationResult {
+    result: ValidationResult | null;
+    isValidating: boolean;
+    error: string | null;
+    stage: ValidationStage;
+    isFixing: boolean;
+    progressMessage: string | null;
+    errors: ValidationError[];
+    warnings: ValidationError[];
+    isValid: boolean;
+    validate: (appId: string) => Promise<ValidationResult>;
+    clearResult: () => void;
+    reset: () => void;
+}
+declare function useValidation(): UseValidationResult;
+
+/**
+ * useEventBus Hook
+ *
+ * Provides event bus utilities for component communication.
+ * This connects to the EventBusProvider for real applications
+ * or provides a simple in-memory bus for design system / Storybook.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Hook for accessing the event bus.
+ *
+ * Uses EventBusProvider context if available, otherwise falls back to
+ * a simple in-memory event bus (for design system / Storybook).
+ *
+ * @returns Event bus instance with emit, on, once, and hasListeners methods
+ *
+ * @example
+ * ```tsx
+ * const eventBus = useEventBus();
+ *
+ * // Emit an event
+ * eventBus.emit('UI:CLICK', { id: '123' });
+ *
+ * // Subscribe to an event
+ * useEffect(() => {
+ *   return eventBus.on('UI:CLICK', (event) => {
+ *     console.log('Clicked:', event.payload);
+ *   });
+ * }, []);
+ * ```
+ */
+declare function useEventBus(): EventBusContextType;
+/**
+ * Hook for subscribing to a specific event.
+ * Automatically cleans up subscription on unmount.
+ *
+ * @param event - Event name to subscribe to
+ * @param handler - Event handler function
+ *
+ * @example
+ * ```tsx
+ * useEventListener('UI:CLICK', (event) => {
+ *   console.log('Clicked:', event.payload);
+ * });
+ * ```
+ */
+declare function useEventListener(event: string, handler: EventListener): void;
+/**
+ * Hook for emitting events.
+ * Returns a memoized emit function.
+ *
+ * @returns Function to emit events
+ *
+ * @example
+ * ```tsx
+ * const emit = useEmitEvent();
+ *
+ * const handleClick = () => {
+ *   emit('UI:CLICK', { id: '123' });
+ * };
+ * ```
+ */
+declare function useEmitEvent(): (type: string, payload?: Record<string, unknown>) => void;
+
+/**
+ * useUIEvents - UI Event to State Machine Bridge
+ *
+ * Listens for UI events from the event bus and dispatches
+ * corresponding state machine events.
+ *
+ * Components emit events like `UI:VIEW`, `UI:SAVE`, `UI:CANCEL`
+ * This hook translates them to state machine dispatch calls.
+ */
+
+/**
+ * Hook to bridge UI events to state machine dispatch
+ *
+ * @param dispatch - The state machine dispatch function
+ * @param validEvents - Optional array of valid event names (filters which events to handle)
+ * @param eventBusInstance - Optional event bus instance (for testing, uses hook if not provided)
+ */
+declare function useUIEvents<E extends string>(dispatch: (event: E, payload?: unknown) => void, validEvents?: readonly E[], eventBusInstance?: ReturnType<typeof useEventBus>): void;
+/**
+ * Hook for selected entity tracking
+ * Many list UIs need to track which item is selected.
+ *
+ * This hook uses SelectionProvider if available (preferred),
+ * otherwise falls back to listening to events directly.
+ *
+ * @example Using with SelectionProvider (recommended)
+ * ```tsx
+ * function MyPage() {
+ *   return (
+ *     <EventBusProvider>
+ *       <SelectionProvider>
+ *         <MyComponent />
+ *       </SelectionProvider>
+ *     </EventBusProvider>
+ *   );
+ * }
+ *
+ * function MyComponent() {
+ *   const [selected, setSelected] = useSelectedEntity<Order>();
+ *   // selected is automatically updated when UI:VIEW/UI:SELECT events fire
+ * }
+ * ```
+ */
+declare function useSelectedEntity<T>(eventBusInstance?: ReturnType<typeof useEventBus>): [T | null, (entity: T | null) => void];
+
+/**
+ * useEntityData Hook
+ *
+ * Provides data fetching utilities for entity lists.
+ * This is a stub implementation for the design system that returns mock data.
+ * In a real application, this would connect to a backend API.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Query key factory for entity data queries.
+ * Used with React Query for cache invalidation.
+ */
+declare const entityDataKeys: {
+    all: readonly ["entities"];
+    lists: () => readonly ["entities", "list"];
+    list: (entity: string, filters?: Record<string, unknown>) => readonly ["entities", "list", string, Record<string, unknown> | undefined];
+    details: () => readonly ["entities", "detail"];
+    detail: (entity: string, id: string) => readonly ["entities", "detail", string, string];
+};
+/**
+ * Generic entity data record type
+ */
+type EntityDataRecord = Record<string, unknown>;
+interface UseEntityListOptions {
+    /** Skip fetching */
+    skip?: boolean;
+}
+interface UseEntityListResult<T = Record<string, unknown>> {
+    /** Fetched data */
+    data: T[];
+    /** Loading state */
+    isLoading: boolean;
+    /** Error state */
+    error: Error | null;
+    /** Refetch function */
+    refetch: () => void;
+}
+/**
+ * Hook for fetching entity list data
+ *
+ * @param entity - Entity name to fetch
+ * @param options - Fetch options
+ * @returns Entity list data and loading states
+ *
+ * @example
+ * ```tsx
+ * const { data, isLoading, error } = useEntityList('tasks');
+ * ```
+ */
+declare function useEntityList<T = Record<string, unknown>>(entity: string | undefined, options?: UseEntityListOptions): UseEntityListResult<T>;
+/**
+ * Hook for fetching a single entity by ID
+ *
+ * @param entity - Entity name
+ * @param id - Entity ID
+ * @returns Single entity data and loading states
+ */
+declare function useEntity$1<T = Record<string, unknown>>(entity: string | undefined, id: string | undefined): {
+    data: T | null;
+    isLoading: boolean;
+    error: Error | null;
+};
+/**
+ * Result type for useEntityDetail hook
+ */
+interface UseEntityDetailResult<T = Record<string, unknown>> {
+    /** Fetched entity data */
+    data: T | null;
+    /** Loading state */
+    isLoading: boolean;
+    /** Error state */
+    error: Error | null;
+    /** Refetch function */
+    refetch: () => void;
+}
+/**
+ * Hook for fetching entity detail by ID (alias for useEntity with refetch)
+ *
+ * @param entity - Entity name
+ * @param id - Entity ID
+ * @returns Entity detail data and loading states
+ *
+ * @example
+ * ```tsx
+ * const { data, isLoading, error, refetch } = useEntityDetail('tasks', taskId);
+ * ```
+ */
+declare function useEntityDetail<T = Record<string, unknown>>(entity: string | undefined, id: string | undefined): UseEntityDetailResult<T>;
+
+/**
+ * useQuerySingleton Hook
+ *
+ * Provides query state management for search/filter components.
+ * This is a stub implementation for the design system.
+ * In a real application, this would connect to the orbital query singleton.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Query state for filters and search
+ */
+interface QueryState {
+    search?: string;
+    filters?: Record<string, unknown>;
+    sortField?: string;
+    sortDirection?: 'asc' | 'desc';
+}
+/**
+ * Query singleton entity reference
+ */
+interface QuerySingletonEntity {
+    name: string;
+    fields: Record<string, unknown>;
+}
+/**
+ * Query singleton result type
+ */
+interface QuerySingletonResult {
+    state: QueryState;
+    setState: (state: Partial<QueryState>) => void;
+    reset: () => void;
+}
+interface QuerySingletonState {
+    /** Current search term */
+    search: string;
+    /** Set search term */
+    setSearch: (value: string) => void;
+    /** Current filters */
+    filters: Record<string, unknown>;
+    /** Set a filter value */
+    setFilter: (key: string, value: unknown) => void;
+    /** Clear all filters */
+    clearFilters: () => void;
+    /** Current sort field */
+    sortField?: string;
+    /** Current sort direction */
+    sortDirection?: 'asc' | 'desc';
+    /** Set sort */
+    setSort: (field: string, direction: 'asc' | 'desc') => void;
+}
+/**
+ * Hook for accessing a query singleton by name
+ *
+ * @param query - Query singleton name (e.g., "@TaskQuery")
+ * @returns Query singleton state or null if no query provided
+ *
+ * @example
+ * ```tsx
+ * const queryState = useQuerySingleton('@TaskQuery');
+ *
+ * // Use search state
+ * queryState?.search
+ * queryState?.setSearch('new search term')
+ * ```
+ */
+declare function useQuerySingleton(query?: string): QuerySingletonState | null;
+/**
+ * Parse a query binding string to extract the query singleton name
+ *
+ * @param binding - Binding string like "@TaskQuery.search" or "@TaskQuery"
+ * @returns Object with query name and optional field path
+ *
+ * @example
+ * ```tsx
+ * parseQueryBinding('@TaskQuery.search')
+ * // { query: 'TaskQuery', field: 'search' }
+ *
+ * parseQueryBinding('@TaskQuery')
+ * // { query: 'TaskQuery', field: undefined }
+ * ```
+ */
+declare function parseQueryBinding(binding: string): {
+    query: string;
+    field?: string;
+};
+
+/**
+ * useOrbitalMutations - Event-based entity mutations via orbital events route
+ *
+ * This hook provides entity mutations that go through the orbital events route
+ * instead of direct CRUD API calls. This ensures all mutations:
+ * 1. Go through trait state machines
+ * 2. Enforce guards
+ * 3. Execute all trait effects (including persist)
+ *
+ * This is the Phase 7 replacement for direct CRUD mutations.
+ *
+ * @example
+ * ```tsx
+ * const { createEntity, updateEntity, deleteEntity } = useOrbitalMutations('Task', 'TaskManager');
+ *
+ * // Create - sends ENTITY_CREATE event to orbital
+ * await createEntity({ title: 'New Task', status: 'pending' });
+ *
+ * // Update - sends ENTITY_UPDATE event to orbital
+ * await updateEntity(taskId, { status: 'completed' });
+ *
+ * // Delete - sends ENTITY_DELETE event to orbital
+ * await deleteEntity(taskId);
+ * ```
+ *
+ * @packageDocumentation
+ */
+/**
+ * Standard events for entity mutations
+ * These are handled by orbitals with CRUD-capable traits
+ */
+declare const ENTITY_EVENTS: {
+    readonly CREATE: "ENTITY_CREATE";
+    readonly UPDATE: "ENTITY_UPDATE";
+    readonly DELETE: "ENTITY_DELETE";
+};
+interface OrbitalEventPayload {
+    event: string;
+    payload?: Record<string, unknown>;
+    entityId?: string;
+}
+interface OrbitalEventResponse {
+    success: boolean;
+    transitioned: boolean;
+    states: Record<string, string>;
+    emittedEvents: Array<{
+        event: string;
+        payload?: unknown;
+    }>;
+    error?: string;
+}
+/**
+ * Hook for event-based entity mutations via orbital events route
+ *
+ * @param entityName - The entity type name (for cache invalidation)
+ * @param orbitalName - The orbital to send events to
+ * @param options - Optional configuration
+ */
+declare function useOrbitalMutations(entityName: string, orbitalName: string, options?: {
+    /** Custom event names for create/update/delete */
+    events?: {
+        create?: string;
+        update?: string;
+        delete?: string;
+    };
+    /** Enable debug logging */
+    debug?: boolean;
+}): {
+    createEntity: (data: Record<string, unknown>) => Promise<OrbitalEventResponse>;
+    updateEntity: (id: string | undefined, data: Record<string, unknown>) => Promise<OrbitalEventResponse | undefined>;
+    deleteEntity: (id: string | undefined) => Promise<OrbitalEventResponse | undefined>;
+    createMutation: _tanstack_react_query.UseMutationResult<OrbitalEventResponse, Error, Record<string, unknown>, unknown>;
+    updateMutation: _tanstack_react_query.UseMutationResult<OrbitalEventResponse, Error, {
+        id: string;
+        data: Record<string, unknown>;
+    }, unknown>;
+    deleteMutation: _tanstack_react_query.UseMutationResult<OrbitalEventResponse, Error, string, unknown>;
+    isCreating: boolean;
+    isUpdating: boolean;
+    isDeleting: boolean;
+    isMutating: boolean;
+    createError: Error | null;
+    updateError: Error | null;
+    deleteError: Error | null;
+};
+/**
+ * Send a custom event to an orbital
+ * For non-CRUD operations that go through trait state machines
+ */
+declare function useSendOrbitalEvent(orbitalName: string): {
+    sendEvent: (event: string, payload?: Record<string, unknown>, entityId?: string) => Promise<OrbitalEventResponse>;
+    isPending: boolean;
+    error: Error | null;
+    data: OrbitalEventResponse | undefined;
+};
+
+interface EntityMutationResult {
+    id: string;
+    [key: string]: unknown;
+}
+/**
+ * Hook for creating entities
+ */
+declare function useCreateEntity(entityName: string): _tanstack_react_query.UseMutationResult<EntityMutationResult, Error, Record<string, unknown>, unknown>;
+/**
+ * Hook for updating entities
+ */
+declare function useUpdateEntity(entityName: string): _tanstack_react_query.UseMutationResult<EntityMutationResult, Error, {
+    id: string;
+    data: Record<string, unknown>;
+}, unknown>;
+/**
+ * Hook for deleting entities
+ */
+declare function useDeleteEntity(entityName: string): _tanstack_react_query.UseMutationResult<{
+    id: string;
+}, Error, string, unknown>;
+interface UseEntityMutationsOptions {
+    /**
+     * If provided, mutations go through orbital events route instead of direct CRUD.
+     * This is the recommended approach for Phase 7+ compliance.
+     */
+    orbitalName?: string;
+    /**
+     * Custom event names when using orbital-based mutations
+     */
+    events?: {
+        create?: string;
+        update?: string;
+        delete?: string;
+    };
+}
+/**
+ * Combined hook that provides all entity mutations
+ * Used by trait hooks for persist_data effects
+ *
+ * @param entityName - The entity type name
+ * @param options - Optional configuration including orbital-based mutations
+ *
+ * @deprecated For new code, prefer useOrbitalMutations directly
+ */
+declare function useEntityMutations(entityName: string, options?: UseEntityMutationsOptions): {
+    createEntity: (entityOrData: string | Record<string, unknown>, data?: Record<string, unknown>) => Promise<OrbitalEventResponse | EntityMutationResult | undefined>;
+    updateEntity: (id: string | undefined, data: Record<string, unknown>) => Promise<OrbitalEventResponse | EntityMutationResult | undefined>;
+    deleteEntity: (id: string | undefined) => Promise<OrbitalEventResponse | {
+        id: string;
+    } | undefined>;
+    isCreating: boolean;
+    isUpdating: boolean;
+    isDeleting: boolean;
+    createError: Error | null;
+    updateError: Error | null;
+    deleteError: Error | null;
+};
+
+/**
+ * useEntities Hook
+ *
+ * React hook to access the entity store.
+ * Uses useSyncExternalStore for efficient updates.
+ */
+
+/**
+ * Hook to access all entities
+ */
+declare function useEntities(): {
+    entities: Map<string, Entity>;
+    getEntity: typeof getEntity;
+    getByType: typeof getByType;
+    getAllEntities: typeof getAllEntities;
+    getSingleton: typeof getSingleton;
+    spawnEntity: typeof spawnEntity;
+    updateEntity: typeof updateEntity;
+    updateSingleton: typeof updateSingleton;
+    removeEntity: typeof removeEntity;
+    clearEntities: typeof clearEntities;
+};
+/**
+ * Hook to access a specific entity by ID
+ */
+declare function useEntity(id: string): Entity | undefined;
+/**
+ * Hook to access entities of a specific type
+ */
+declare function useEntitiesByType(type: string): Entity[];
+/**
+ * Hook to access a singleton entity by type
+ */
+declare function useSingletonEntity<T extends Entity = Entity>(type: string): T | undefined;
+/**
+ * Hook for Player entity (convenience)
+ */
+declare function usePlayer(): {
+    player: Entity | undefined;
+    updatePlayer: (updates: Partial<Entity>) => void;
+};
+/**
+ * Hook for Physics entity (convenience)
+ */
+declare function usePhysics(): {
+    physics: Entity | undefined;
+    updatePhysics: (updates: Partial<Entity>) => void;
+};
+/**
+ * Hook for Input entity (convenience)
+ */
+declare function useInput(): {
+    input: Entity | undefined;
+    updateInput: (updates: Partial<Entity>) => void;
+};
+
+/**
+ * Auth Context Hook Stub
+ *
+ * Provides a placeholder auth context for the design system.
+ * Applications should provide their own AuthContext provider
+ * that implements this interface.
+ */
+interface AuthUser {
+    uid: string;
+    email: string | null;
+    displayName: string | null;
+    photoURL: string | null;
+}
+interface AuthContextValue {
+    user: AuthUser | null;
+    loading: boolean;
+    signIn?: () => Promise<void>;
+    signOut?: () => Promise<void>;
+}
+/**
+ * Stub hook that returns empty auth context.
+ * Applications should wrap their app with an AuthProvider
+ * that supplies real auth state.
+ */
+declare function useAuthContext(): AuthContextValue;
+
+export { type AuthContextValue, type AuthUser, type ChangeSummary, type CompileResult, type CompileStage, ENTITY_EVENTS, Entity, type EntityDataRecord, type EntityMutationResult, EventBusContextType, EventListener, type Extension, type ExtensionManifest, type FileSystemFile, type FileSystemStatus, type HistoryTimelineItem, type OpenFile, type OrbitalEventPayload, type OrbitalEventResponse, type QuerySingletonEntity, type QuerySingletonResult, type QuerySingletonState, type QueryState, type RevertResult, type SelectedFile, type UseCompileResult, type UseEntityDetailResult, type UseEntityListOptions, type UseEntityListResult, type UseEntityMutationsOptions, type UseExtensionsOptions, type UseExtensionsResult, type UseFileEditorOptions, type UseFileEditorResult, type UseFileSystemResult, type UseOrbitalHistoryOptions, type UseOrbitalHistoryResult, clearEntities, entityDataKeys, getAllEntities, getByType, getEntity, getSingleton, parseQueryBinding, removeEntity, spawnEntity, updateEntity, updateSingleton, useAgentChat, useAuthContext, useCompile, useCreateEntity, useDeepAgentGeneration, useDeleteEntity, useEmitEvent, useEntities, useEntitiesByType, useEntity$1 as useEntity, useEntity as useEntityById, useEntityDetail, useEntityList, useEntityMutations, useEventBus, useEventListener, useExtensions, useFileEditor, useFileSystem, useInput, useOrbitalHistory, useOrbitalMutations, usePhysics, usePlayer, usePreview, useQuerySingleton, useSelectedEntity, useSendOrbitalEvent, useSingletonEntity, useUIEvents, useUpdateEntity, useValidation };