@almadar/ui 1.0.34 → 2.0.1

package/dist/hooks/useAgentChat.d.ts

@@ -0,0 +1,104 @@
+import type { DeepAgentInterrupt } from './useDeepAgentGeneration';
+export interface ChatMessage {
+    id: string;
+    role: 'user' | 'assistant' | 'system';
+    content: string;
+    timestamp: number;
+}
+export type AvatarRole = 'user' | 'assistant' | 'system';
+export type FileOperation = 'ls' | 'read_file' | 'write_file' | 'edit_file';
+export 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;
+};
+export interface TodoActivity {
+    type: 'thinking' | 'tool_call' | 'tool_result' | 'code_change';
+    content: string;
+    timestamp: number;
+    tool?: string;
+    success?: boolean;
+    filePath?: string;
+    diff?: string;
+}
+export interface Todo {
+    id: string;
+    task: string;
+    status: 'pending' | 'in_progress' | 'completed';
+    latestActivity?: TodoActivity;
+    activityHistory?: TodoActivity[];
+}
+export interface DiffHunk {
+    oldStart: number;
+    oldLines: number;
+    newStart: number;
+    newLines: number;
+    lines: Array<{
+        type: 'add' | 'remove' | 'context';
+        content: string;
+    }>;
+}
+export interface SchemaDiff {
+    id: string;
+    filePath: string;
+    hunks: DiffHunk[];
+    timestamp: number;
+    addedLines: number;
+    removedLines: number;
+}
+export type AgentStatus = 'idle' | 'running' | 'complete' | 'error' | 'interrupted';
+export interface UseAgentChatOptions {
+    appId?: string;
+    onComplete?: (schema?: unknown) => void;
+    onSchemaChange?: (diff?: unknown) => void;
+    onError?: (error: Error | string) => void;
+}
+export 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;
+}
+export declare function useAgentChat(options?: UseAgentChatOptions): UseAgentChatResult;

package/dist/hooks/useAuthContext.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Auth Context Hook Stub
+ *
+ * Provides a placeholder auth context for the design system.
+ * Applications should provide their own AuthContext provider
+ * that implements this interface.
+ */
+export interface AuthUser {
+    uid: string;
+    email: string | null;
+    displayName: string | null;
+    photoURL: string | null;
+}
+export 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.
+ */
+export declare function useAuthContext(): AuthContextValue;

package/dist/hooks/useCompile.d.ts

@@ -0,0 +1,22 @@
+export interface SchemaLike {
+    name: string;
+    version?: string;
+    [key: string]: unknown;
+}
+export type CompileStage = 'idle' | 'compiling' | 'done' | 'error';
+export interface CompileResult {
+    success: boolean;
+    files?: Array<{
+        path: string;
+        content: string;
+    }>;
+    errors?: string[];
+}
+export interface UseCompileResult {
+    isCompiling: boolean;
+    stage: CompileStage;
+    lastResult: CompileResult | null;
+    error: string | null;
+    compileSchema: (schema: SchemaLike) => Promise<CompileResult | null>;
+}
+export declare function useCompile(): UseCompileResult;

package/dist/hooks/useDeepAgentGeneration.d.ts

@@ -0,0 +1,46 @@
+import type { OrbitalSchema } from '@almadar/core';
+export interface DeepAgentActionRequest {
+    id: string;
+    type: string;
+    tool: string;
+    args: Record<string, unknown>;
+    description?: string;
+    allowedDecisions: ('approve' | 'edit' | 'reject')[];
+    status: 'pending' | 'approved' | 'rejected' | 'edited';
+}
+export interface DeepAgentInterrupt {
+    id: string;
+    type: 'tool_calls' | 'confirmation' | 'error';
+    message?: string;
+    actionRequests: DeepAgentActionRequest[];
+    timestamp: number;
+    threadId?: string;
+}
+export interface GenerationRequest {
+    id: string;
+    prompt: string;
+    status: 'pending' | 'running' | 'completed' | 'failed';
+    result?: OrbitalSchema;
+    error?: string;
+}
+export interface GenerationProgress {
+    stage: string;
+    percent: number;
+    message: string;
+}
+export 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;
+}
+export declare function useDeepAgentGeneration(): UseDeepAgentGenerationResult;

package/dist/hooks/useEntities.d.ts

@@ -0,0 +1,52 @@
+import { getEntity, getByType, getAllEntities, getSingleton, spawnEntity, updateEntity, updateSingleton, removeEntity, clearEntities } from '../stores/entityStore';
+import type { Entity } from '../stores/entityStore';
+export type { Entity };
+/**
+ * Hook to access all entities
+ */
+export 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
+ */
+export declare function useEntity(id: string): Entity | undefined;
+/**
+ * Hook to access entities of a specific type
+ */
+export declare function useEntitiesByType(type: string): Entity[];
+/**
+ * Hook to access a singleton entity by type
+ */
+export declare function useSingletonEntity<T extends Entity = Entity>(type: string): T | undefined;
+/**
+ * Hook for Player entity (convenience)
+ */
+export declare function usePlayer(): {
+    player: Entity | undefined;
+    updatePlayer: (updates: Partial<Entity>) => void;
+};
+/**
+ * Hook for Physics entity (convenience)
+ */
+export declare function usePhysics(): {
+    physics: Entity | undefined;
+    updatePhysics: (updates: Partial<Entity>) => void;
+};
+/**
+ * Hook for Input entity (convenience)
+ */
+export declare function useInput(): {
+    input: Entity | undefined;
+    updateInput: (updates: Partial<Entity>) => void;
+};
+export { spawnEntity, updateEntity, updateSingleton, removeEntity, clearEntities, getEntity, getByType, getAllEntities, getSingleton, };

package/dist/hooks/useEntityData.d.ts

@@ -0,0 +1,155 @@
+import type { ReactNode } from "react";
+import React from "react";
+export interface EntityDataAdapter {
+    /** Get all records for an entity */
+    getData: (entity: string) => Record<string, unknown>[];
+    /** Get a single record by entity name and ID */
+    getById: (entity: string, id: string) => Record<string, unknown> | undefined;
+    /** Whether data is currently loading */
+    isLoading: boolean;
+    /** Current error */
+    error: string | null;
+}
+/**
+ * Provider that bridges a host app's data source to useEntityList/useEntity hooks.
+ *
+ * @example
+ * ```tsx
+ * // In builder runtime
+ * const fetchedData = useFetchedData();
+ * const adapter = {
+ *   getData: fetchedData.getData,
+ *   getById: fetchedData.getById,
+ *   isLoading: fetchedData.loading,
+ *   error: fetchedData.error,
+ * };
+ * <EntityDataProvider adapter={adapter}>
+ *   {children}
+ * </EntityDataProvider>
+ * ```
+ */
+export declare function EntityDataProvider({ adapter, children, }: {
+    adapter: EntityDataAdapter;
+    children: ReactNode;
+}): React.FunctionComponentElement<React.ProviderProps<EntityDataAdapter | null>>;
+/**
+ * Access the entity data adapter (null if no provider).
+ */
+export declare function useEntityDataAdapter(): EntityDataAdapter | null;
+export 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];
+};
+export type EntityDataRecord = Record<string, unknown>;
+export interface UseEntityListOptions {
+    /** Skip fetching */
+    skip?: boolean;
+}
+export interface UseEntityListResult<T = Record<string, unknown>> {
+    data: T[];
+    isLoading: boolean;
+    error: Error | null;
+    refetch: () => void;
+}
+export interface UseEntityDetailResult<T = Record<string, unknown>> {
+    data: T | null;
+    isLoading: boolean;
+    error: Error | null;
+    refetch: () => void;
+}
+export interface PaginationParams {
+    page: number;
+    pageSize: number;
+    search?: string;
+    sortBy?: string;
+    sortDirection?: "asc" | "desc";
+    filters?: Record<string, unknown>;
+}
+export interface UsePaginatedEntityListResult<T = Record<string, unknown>> {
+    data: T[];
+    isLoading: boolean;
+    error: Error | null;
+    totalCount: number;
+    totalPages: number;
+    hasNextPage: boolean;
+    hasPreviousPage: boolean;
+    refetch: () => void;
+}
+/**
+ * Hook for fetching entity list data.
+ * Uses EntityDataContext if available, otherwise falls back to stub.
+ */
+export declare function useEntityList<T = Record<string, unknown>>(entity: string | undefined, options?: UseEntityListOptions): UseEntityListResult<T>;
+/**
+ * Hook for fetching a single entity by ID.
+ * Uses EntityDataContext if available, otherwise falls back to stub.
+ */
+export declare function useEntity<T = Record<string, unknown>>(entity: string | undefined, id: string | undefined): {
+    data: T | null;
+    isLoading: boolean;
+    error: Error | null;
+};
+/**
+ * Hook for fetching entity detail by ID (alias for useEntity with refetch).
+ * Uses EntityDataContext if available, otherwise falls back to stub.
+ */
+export declare function useEntityDetail<T = Record<string, unknown>>(entity: string | undefined, id: string | undefined): UseEntityDetailResult<T>;
+/**
+ * Hook for fetching paginated entity list data.
+ * Uses EntityDataContext if available (client-side pagination), otherwise falls back to stub.
+ */
+export declare function usePaginatedEntityList<T = Record<string, unknown>>(entity: string | undefined, params: PaginationParams, options?: UseEntityListOptions): UsePaginatedEntityListResult<T>;
+/**
+ * Suspense-compatible hook for fetching entity list data.
+ *
+ * Instead of returning `isLoading`/`error`, this hook **suspends** (throws a Promise)
+ * when data is not ready. Use inside a `<Suspense>` boundary.
+ *
+ * Falls back to the adapter when available; otherwise suspends briefly for stub data.
+ *
+ * @example
+ * ```tsx
+ * <Suspense fallback={<Skeleton variant="table" />}>
+ *   <ErrorBoundary>
+ *     <TaskList entity="Task" />
+ *   </ErrorBoundary>
+ * </Suspense>
+ *
+ * function TaskList({ entity }: { entity: string }) {
+ *   const { data } = useEntityListSuspense<Task>(entity);
+ *   // No loading check needed — Suspense handles it
+ *   return <DataTable data={data} ... />;
+ * }
+ * ```
+ */
+export declare function useEntityListSuspense<T = Record<string, unknown>>(entity: string): {
+    data: T[];
+    refetch: () => void;
+};
+/**
+ * Suspense-compatible hook for fetching a single entity by ID.
+ *
+ * Suspends when data is not ready. Use inside a `<Suspense>` boundary.
+ *
+ * @example
+ * ```tsx
+ * <Suspense fallback={<Skeleton variant="form" />}>
+ *   <ErrorBoundary>
+ *     <TaskDetail entity="Task" id={taskId} />
+ *   </ErrorBoundary>
+ * </Suspense>
+ *
+ * function TaskDetail({ entity, id }: { entity: string; id: string }) {
+ *   const { data } = useEntitySuspense<Task>(entity, id);
+ *   return <DetailPanel data={data} ... />;
+ * }
+ * ```
+ */
+export declare function useEntitySuspense<T = Record<string, unknown>>(entity: string, id: string): {
+    data: T | null;
+    refetch: () => void;
+};
+export default useEntityList;

package/dist/hooks/useEntityMutations.d.ts

@@ -0,0 +1,80 @@
+/**
+ * useEntityMutations - Entity CRUD mutation hooks
+ *
+ * Provides create, update, and delete mutations for entities.
+ * Used by trait hooks for persist_data effects.
+ *
+ * @deprecated For new code, prefer useOrbitalMutations which sends mutations
+ * through the orbital events route. This ensures all mutations go through
+ * trait state machines and enforce guards/effects.
+ *
+ * Migration:
+ * ```tsx
+ * // Old (deprecated):
+ * const { createEntity } = useEntityMutations('Task');
+ *
+ * // New (recommended):
+ * const { createEntity } = useOrbitalMutations('Task', 'TaskManager');
+ * ```
+ *
+ * @see useOrbitalMutations
+ */
+import { type OrbitalEventResponse } from './useOrbitalMutations';
+export interface EntityMutationResult {
+    id: string;
+    [key: string]: unknown;
+}
+/**
+ * Hook for creating entities
+ */
+export declare function useCreateEntity(entityName: string): import("@tanstack/react-query").UseMutationResult<EntityMutationResult, Error, Record<string, unknown>, unknown>;
+/**
+ * Hook for updating entities
+ */
+export declare function useUpdateEntity(entityName: string): import("@tanstack/react-query").UseMutationResult<EntityMutationResult, Error, {
+    id: string;
+    data: Record<string, unknown>;
+}, unknown>;
+/**
+ * Hook for deleting entities
+ */
+export declare function useDeleteEntity(entityName: string): import("@tanstack/react-query").UseMutationResult<{
+    id: string;
+}, Error, string, unknown>;
+export 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
+ */
+export 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;
+};

package/dist/hooks/useEventBus.d.ts

@@ -0,0 +1,96 @@
+import type { KFlowEvent, EventListener, Unsubscribe, EventBusContextType } from './event-bus-types';
+export type { KFlowEvent, EventListener, Unsubscribe, EventBusContextType };
+declare global {
+    interface Window {
+        __kflowEventBus?: EventBusContextType | null;
+    }
+}
+/**
+ * Global event bus reference for bridging between packages.
+ *
+ * Uses window-level global to enable cross-package communication.
+ * This allows @almadar/ui components to emit events to the same bus
+ * that the consuming app's trait state machine listens to.
+ *
+ * When the EventBusProvider mounts, it sets window.__kflowEventBus.
+ * Components in any package can then use this shared event bus.
+ *
+ * SSR Safety: All window access is guarded by `typeof window !== 'undefined'`.
+ * React Compiler Safety: The global bus reference is set once at provider mount
+ * and is stable — no render-path side effects. In practice, the React context
+ * path (priority 1) is used in real apps; the window global (priority 2) is
+ * only reached when no EventBusProvider is in the tree (e.g., Storybook).
+ */
+/**
+ * Set the global event bus reference.
+ * Called by EventBusProvider when it mounts.
+ *
+ * @param bus - The event bus context to set as global, or null to clear
+ */
+export declare function setGlobalEventBus(bus: EventBusContextType | null): void;
+/**
+ * Get the global event bus reference.
+ *
+ * @returns The global event bus if set, null otherwise
+ */
+export declare function getGlobalEventBus(): EventBusContextType | null;
+/**
+ * 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);
+ *   });
+ * }, []);
+ * ```
+ */
+export 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);
+ * });
+ * ```
+ */
+export declare function useEventListener(event: string, handler: EventListener): void;
+/**
+ * Alias for useEventListener for backward compatibility
+ */
+export declare const useEventSubscription: typeof useEventListener;
+/**
+ * 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' });
+ * };
+ * ```
+ */
+export declare function useEmitEvent(): (type: string, payload?: Record<string, unknown>) => void;
+export default useEventBus;

package/dist/hooks/useExtensions.d.ts

@@ -0,0 +1,32 @@
+export interface Extension {
+    id: string;
+    name: string;
+    language?: string;
+    loaded: boolean;
+}
+export interface ExtensionEntry {
+    file: string;
+    language?: string;
+}
+export interface ExtensionManifest {
+    languages: Record<string, {
+        extensions: string[];
+        icon?: string;
+        color?: string;
+    }>;
+    extensions: ExtensionEntry[];
+}
+export interface UseExtensionsOptions {
+    appId: string;
+    loadOnMount?: boolean;
+}
+export interface UseExtensionsResult {
+    extensions: Extension[];
+    manifest: ExtensionManifest;
+    isLoading: boolean;
+    error: string | null;
+    loadExtension: (extensionId: string) => Promise<void>;
+    loadExtensions: () => Promise<void>;
+    getExtensionForFile: (filename: string) => Extension | null;
+}
+export declare function useExtensions(options: UseExtensionsOptions): UseExtensionsResult;

package/dist/hooks/useFileEditor.d.ts

@@ -0,0 +1,32 @@
+import type { UseExtensionsResult } from './useExtensions';
+import type { UseFileSystemResult } from './useFileSystem';
+import type { OrbitalSchema } from '@almadar/core';
+export interface OpenFile {
+    path: string;
+    content: string;
+    isDirty: boolean;
+    language?: string;
+}
+export interface UseFileEditorOptions {
+    extensions: UseExtensionsResult;
+    fileSystem: UseFileSystemResult;
+    onSchemaUpdate?: (schema: OrbitalSchema) => Promise<void>;
+}
+export interface FileEditResult {
+    success: boolean;
+    action?: 'updated_schema' | 'converted_extension' | 'saved_extension' | 'saved';
+    error?: string;
+}
+export 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>;
+}
+export declare function useFileEditor(options: UseFileEditorOptions): UseFileEditorResult;

package/dist/hooks/useFileSystem.d.ts

@@ -0,0 +1,40 @@
+export interface FileNode {
+    path: string;
+    name: string;
+    type: 'file' | 'directory';
+    children?: FileNode[];
+}
+export type FileSystemStatus = 'idle' | 'booting' | 'ready' | 'running' | 'error';
+export interface FileSystemFile {
+    path: string;
+    content: string;
+}
+export interface SelectedFile {
+    path: string;
+    content: string;
+    language?: string;
+    isDirty?: boolean;
+}
+export 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>;
+}
+export declare function useFileSystem(): UseFileSystemResult;