@almadar/ui 5.111.0 → 5.113.0

package/dist/hooks/index.d.ts

@@ -1,33 +1,995 @@
+import { OrbitalSchema, FieldValue, EventPayload, EntityFrameState, EntityFieldWrite } from '@almadar/core';
+export { BusEvent, BusEventListener, BusEventSource, BusEventListener as EventListener, UISlot, Unsubscribe } from '@almadar/core';
+import { a as useEventBus } from '../useEventBus-CQWyAWpK.js';
+export { u as useEmitEvent, b as useEventListener } from '../useEventBus-CQWyAWpK.js';
+export { E as EventBusContextType } from '../event-bus-types-Bl78kokd.js';
+export { D as DEFAULT_SLOTS, S as SlotAnimation, a as SlotChangeCallback, b as SlotContent, c as SlotRenderConfig, U as UISlotManager, u as useUISlotManager } from '../useUISlots-BesZYMks.js';
+import * as React$1 from 'react';
+import React__default from 'react';
+import * as _tanstack_react_query from '@tanstack/react-query';
+
+interface HistoryChangeSummary {
+    added: number;
+    modified: number;
+    removed: number;
+}
+interface HistoryTimelineItem {
+    id: string;
+    type: 'changeset' | 'snapshot';
+    version: number;
+    timestamp: number;
+    description: string;
+    source?: string;
+    summary?: HistoryChangeSummary;
+    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;
+
+interface FileSystemTree {
+    [name: string]: {
+        file: {
+            contents: string;
+        };
+    } | {
+        directory: FileSystemTree;
+    };
+}
+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[] | FileSystemTree) => 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;
+
+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;
+
+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;
+
+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: OrbitalSchema) => Promise<CompileResult | null>;
+}
+declare function useCompile(): UseCompileResult;
+
+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;
+
+interface DeepAgentActionRequest {
+    id: string;
+    type: string;
+    tool: string;
+    args: Record<string, FieldValue>;
+    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, FieldValue>) => Promise<void>;
+    cancelGeneration: () => void;
+    clearRequests: () => void;
+    submitInterruptDecisions: (decisions: FieldValue[]) => void;
+}
+declare function useDeepAgentGeneration(): UseDeepAgentGenerationResult;
+
+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, FieldValue>;
+    timestamp: number;
+    isExecuting?: boolean;
+} | {
+    type: 'tool_result';
+    tool: string;
+    result: FieldValue | null;
+    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?: OrbitalSchema) => void;
+    onSchemaChange?: (diff?: OrbitalSchema) => 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, FieldValue>) => Promise<void>;
+    continueConversation: (message: string | string[]) => Promise<void>;
+    resumeWithDecision: (decisions: FieldValue[]) => Promise<void>;
+    cancel: () => void;
+    clearMessages: () => void;
+    clearHistory: () => void;
+}
+declare function useAgentChat(options?: UseAgentChatOptions): UseAgentChatResult;
+
+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;
+
 /**
- * Hooks barrel export
- */
-export { useOrbitalHistory, type HistoryTimelineItem, type RevertResult, type HistoryChangeSummary, type UseOrbitalHistoryOptions, type UseOrbitalHistoryResult, } from './useOrbitalHistory';
-export { useFileSystem, type FileSystemStatus, type FileSystemFile, type SelectedFile, type UseFileSystemResult, } from './useFileSystem';
-export { useExtensions, type Extension, type ExtensionManifest, type UseExtensionsOptions, type UseExtensionsResult, } from './useExtensions';
-export { useFileEditor, type OpenFile, type UseFileEditorOptions, type UseFileEditorResult, } from './useFileEditor';
-export { useCompile, type CompileStage, type CompileResult, type UseCompileResult, } from './useCompile';
-export { usePreview } from './usePreview';
-export { useAgentChat } from './useAgentChat';
-export { useValidation } from './useValidation';
-export { useDeepAgentGeneration } from './useDeepAgentGeneration';
-export { useEventBus, useEventListener, useEmitEvent } from './useEventBus';
-export type { BusEvent, BusEventSource, BusEventListener, Unsubscribe, EventBusContextType, } from '../types/event-bus-types';
-/** @deprecated Use BusEventListener. */
-export type { BusEventListener as EventListener } from '../types/event-bus-types';
-export { useUISlotManager, DEFAULT_SLOTS, type UISlot, type SlotAnimation, type SlotContent, type SlotRenderConfig, type SlotChangeCallback, type UISlotManager, } from './useUISlots';
-export { useUIEvents, useTraitListens, type TraitListenSpec } from './useUIEvents';
-export { createSharedEntityStore, useSharedEntityStore, useSharedEntitySnapshot, runTickFrame, type SharedEntityStore, type SharedEntitySubscriber, type SharedEntityWriter, } from './useSharedEntityStore';
-export { useQuerySingleton, parseQueryBinding, type QueryState, type QuerySingletonEntity, type QuerySingletonResult, type QuerySingletonState, } from './useQuerySingleton';
-export { useTranslate, I18nProvider, createTranslate, type TranslateFunction, type I18nContextValue, } from './useTranslate';
-export { useAuthContext, type AuthUser, type AuthContextValue, } from './useAuthContext';
-export { useSwipeGesture, type SwipeGestureOptions, type SwipeGestureResult, type SwipeHandlers, } from './useSwipeGesture';
-export { useLongPress, type LongPressOptions, type LongPressHandlers, } from './useLongPress';
-export { useDragReorder, type DragReorderResult, } from './useDragReorder';
-export { useInfiniteScroll, type InfiniteScrollOptions, type InfiniteScrollResult, } from './useInfiniteScroll';
-export { usePullToRefresh, type PullToRefreshOptions, type PullToRefreshResult, } from './usePullToRefresh';
-export { useCanvasGestures, type UseCanvasGesturesOptions, type CanvasGestureCallbacks, type CanvasGestureHandlers, } from './useCanvasGestures';
-export { useTapReveal, type TapRevealOptions, type TapRevealResult, } from './useTapReveal';
-export { useDraggable, ALMADAR_DND_MIME, type DraggablePayload, type UseDraggableOptions, type UseDraggableResult, } from './useDraggable';
-export { useDropZone, type UseDropZoneOptions, type UseDropZoneResult, } from './useDropZone';
-export { useRenderInterpolation, type Positioned, type RenderInterpolationOptions, type RenderInterpolationHandle, } from './useRenderInterpolation';
-export { useGitHubStatus, useConnectGitHub, useDisconnectGitHub, useGitHubRepos, useGitHubRepo, useGitHubBranches, type GitHubStatus, type GitHubRepo, } from './useGitHub';
+ * Hook to bridge UI events to state machine dispatch.
+ *
+ * @param dispatch - The state machine dispatch function
+ * @param traitName - Owning trait name; used to construct the qualified
+ *   subscription key `UI:{traitName}.{event}`. Required — bare-key
+ *   subscriptions were removed when the bus namespace unified on the
+ *   listens grammar (gap #13, Phase 4 of the cross-orbital plan).
+ * @param validEvents - Local event names (transition triggers) the
+ *   trait reacts to. The hook subscribes to `UI:{traitName}.{event}`
+ *   for each entry.
+ * @param eventBusInstance - Optional event bus instance (for testing)
+ */
+declare function useUIEvents<E extends string>(dispatch: (event: E, payload?: EventPayload) => void, traitName: string, validEvents: readonly E[], eventBusInstance?: ReturnType<typeof useEventBus>): void;
+/**
+ * Hook to subscribe to cross-trait listens (gap #13, Phase 4 codegen).
+ *
+ * The schema's `listens { Source EVENT -> TRIGGER }` block resolves at
+ * lower-time to a typed `ListenSource` enum (intra-orbital `Trait` or
+ * cross-orbital `Orbital.Trait`). Codegen materializes one
+ * `useTraitListens` call per trait, listing every `(sourceTrait,
+ * sourceEvent, localTrigger)` tuple from the listens block. The hook
+ * subscribes to the qualified bus key — `UI:Trait.EVENT` (intra-orbital)
+ * or `UI:Orbital.Trait.EVENT` (cross-orbital) — and dispatches the
+ * local trigger when the source fires.
+ *
+ * Replaces the old bare-event cross-trait fan-out that lived inside
+ * `useUIEvents`. Pre-unification, `useUIEvents` subscribed to bare
+ * `EVENT` keys and matched on `source.trait !== own`; post-unification,
+ * the qualified bus key carries the source identity directly, no
+ * `source` filtering needed.
+ */
+interface TraitListenSpec<E extends string> {
+    /** Qualified `Trait.EVENT` or `Orbital.Trait.EVENT` source. */
+    sourceKey: string;
+    /** Local trigger event to dispatch when the source fires. */
+    trigger: E;
+}
+declare function useTraitListens<E extends string>(dispatch: (event: E, payload?: EventPayload) => void, listens: readonly TraitListenSpec<E>[], eventBusInstance?: ReturnType<typeof useEventBus>): void;
+
+/** Notification callback fired after a `commit()` for the subscribed entity id. */
+type SharedEntitySubscriber = () => void;
+/**
+ * One writer trait's per-frame step: reads the live running scratch
+ * (reflecting every earlier writer's writes this frame) and returns its own
+ * field writes. Pure — writers never call `store.commit`; only `runTickFrame`
+ * does, once per frame.
+ */
+type SharedEntityWriter = (scratch: EntityFrameState) => readonly EntityFieldWrite[];
+/** Manager surface, keyed by entity id. */
+interface SharedEntityStore {
+    getSnapshot: (entityId: string) => EntityFrameState;
+    subscribe: (entityId: string, callback: SharedEntitySubscriber) => () => void;
+    commit: (entityId: string, nextState: EntityFrameState) => void;
+    /**
+     * Set the initial state for an entity id, but ONLY if nothing is committed
+     * yet — idempotent, and (unlike `commit`) does NOT notify subscribers, so it
+     * is safe to call during render. Both execution paths seed from the entity's
+     * declared field defaults at init, so frame 0 reads the defaults on both.
+     */
+    seed: (entityId: string, initialState: EntityFrameState) => void;
+}
+/**
+ * Create a standalone shared-entity store. Plain factory — no React — so a
+ * clock owner (the interpreter's TickScheduler, or a codegen rAF
+ * `useEffect`) can hold one instance and pass it to `runTickFrame` without
+ * going through a hook.
+ */
+declare function createSharedEntityStore(): SharedEntityStore;
+/**
+ * React hook: one stable `SharedEntityStore` instance for this component's
+ * lifetime (useUISlotManager's ref-backed-instance pattern — no re-creation
+ * across re-renders). Callers own one store per running orbital instance and
+ * thread it to each writer trait plus the render trait via `runTickFrame` /
+ * `useSharedEntitySnapshot`.
+ */
+declare function useSharedEntityStore(): SharedEntityStore;
+/**
+ * Bridge one entity's snapshot into React via `useSyncExternalStore` (the
+ * codebase's established store->React bridge, see `lib/perf.ts`). The render
+ * trait re-renders exactly when `runTickFrame` commits this entity — never on
+ * an intermediate per-writer write, since those never call `store.commit`.
+ */
+declare function useSharedEntitySnapshot(store: SharedEntityStore, entityId: string): EntityFrameState;
+/**
+ * Run one frame for `entityId`: fold each writer's writes into a running
+ * scratch in binding order via `mergeEntityFrame` (field-level, so writer
+ * k+1 reads writer k's same-frame writes), then commit the merged result
+ * exactly ONCE. Clock-agnostic — the caller (a TickScheduler tick or a
+ * codegen rAF loop) invokes this once per frame; it owns no timer itself.
+ */
+declare function runTickFrame(entityId: string, orderedWriters: readonly SharedEntityWriter[], store: SharedEntityStore): EntityFrameState;
+
+/**
+ * Query state for filters and search
+ */
+interface QueryState {
+    search?: string;
+    filters?: Record<string, FieldValue>;
+    sortField?: string;
+    sortDirection?: 'asc' | 'desc';
+}
+/**
+ * Query singleton entity reference
+ */
+interface QuerySingletonEntity {
+    name: string;
+    fields: Record<string, FieldValue>;
+}
+/**
+ * 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, FieldValue>;
+    /** Set a filter value */
+    setFilter: (key: string, value: FieldValue) => 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;
+};
+
+type TranslateFunction = (key: string, params?: Record<string, string | number>) => string;
+interface I18nContextValue {
+    /** Current locale code (e.g. 'en', 'ar', 'sl') */
+    locale: string;
+    /** Text direction for the current locale */
+    direction: 'ltr' | 'rtl';
+    /** Translate a key, with optional interpolation params */
+    t: TranslateFunction;
+}
+/**
+ * Provider component — wrap your app or Storybook decorator with this.
+ *
+ * ```tsx
+ * <I18nProvider value={{ locale: 'ar', direction: 'rtl', t: createTranslate(arMessages) }}>
+ *   <App />
+ * </I18nProvider>
+ * ```
+ */
+declare const I18nProvider: React$1.Provider<I18nContextValue>;
+/**
+ * Hook to access the current locale and translate function.
+ * Safe to call without a provider — returns passthrough t().
+ */
+declare function useTranslate(): I18nContextValue;
+/**
+ * Create a translate function from a flat messages object.
+ *
+ * ```ts
+ * const t = createTranslate({ 'common.save': 'Save', 'table.showing': 'Showing {{count}} of {{total}}' });
+ * t('common.save') // → 'Save'
+ * t('table.showing', { count: 5, total: 20 }) // → 'Showing 5 of 20'
+ * t('missing.key') // → 'missing.key' (fallback)
+ * ```
+ */
+declare function createTranslate(messages: Record<string, string>): TranslateFunction;
+
+/**
+ * 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;
+
+interface SwipeGestureOptions {
+    /** Minimum distance in px to trigger a swipe (default: 50) */
+    threshold?: number;
+    /** Minimum velocity in px/ms to qualify (default: 0.3) */
+    velocityThreshold?: number;
+    /** Prevent default touch behavior during swipe (default: false) */
+    preventDefault?: boolean;
+}
+interface SwipeGestureResult {
+    onSwipeLeft?: () => void;
+    onSwipeRight?: () => void;
+    onSwipeUp?: () => void;
+    onSwipeDown?: () => void;
+}
+interface SwipeHandlers {
+    onPointerDown: (e: React__default.PointerEvent) => void;
+    onPointerMove: (e: React__default.PointerEvent) => void;
+    onPointerUp: (e: React__default.PointerEvent) => void;
+    onPointerCancel: (e: React__default.PointerEvent) => void;
+    /** Current horizontal offset during swipe (for animation) */
+    offsetX: number;
+    /** Whether a swipe gesture is in progress */
+    isSwiping: boolean;
+}
+
+declare function useSwipeGesture(callbacks: SwipeGestureResult, options?: SwipeGestureOptions): SwipeHandlers;
+
+interface LongPressOptions {
+    /** Hold duration in ms before triggering (default: 500) */
+    duration?: number;
+    /** Movement tolerance in px before canceling (default: 10) */
+    moveThreshold?: number;
+}
+interface LongPressHandlers {
+    onPointerDown: (e: React__default.PointerEvent) => void;
+    onPointerMove: (e: React__default.PointerEvent) => void;
+    onPointerUp: () => void;
+    onPointerCancel: () => void;
+    /** Whether the long press is currently active (held down, timer running) */
+    isPressed: boolean;
+}
+declare function useLongPress(onLongPress: () => void, options?: LongPressOptions): LongPressHandlers;
+
+interface DragReorderResult<T> {
+    /** The reordered items array */
+    items: T[];
+    /** Index of the item currently being dragged (-1 if not dragging) */
+    dragIndex: number;
+    /** Index of the drop target (-1 if not over any target) */
+    dragOverIndex: number;
+    /** Whether a drag is in progress */
+    isDragging: boolean;
+    /** Props to spread on the drag handle element for a given index */
+    getDragHandleProps: (index: number) => {
+        onPointerDown: (e: React__default.PointerEvent) => void;
+        style: React__default.CSSProperties;
+        'aria-grabbed': boolean;
+        role: string;
+    };
+    /** Props to spread on each list item for a given index */
+    getItemProps: (index: number) => {
+        onPointerMove: (e: React__default.PointerEvent) => void;
+        onPointerUp: () => void;
+        'aria-dropeffect': string;
+        style: React__default.CSSProperties;
+    };
+}
+declare function useDragReorder<T>(initialItems: T[], onReorder: (fromIndex: number, toIndex: number, item: T) => void): DragReorderResult<T>;
+
+interface InfiniteScrollOptions {
+    /** Root margin for IntersectionObserver (default: "200px") */
+    rootMargin?: string;
+    /** Whether more items are available to load */
+    hasMore?: boolean;
+    /** Whether a load is currently in progress */
+    isLoading?: boolean;
+}
+interface InfiniteScrollResult {
+    /** Ref to attach to the sentinel element */
+    sentinelRef: React.RefCallback<HTMLElement>;
+}
+declare function useInfiniteScroll(onLoadMore: () => void, options?: InfiniteScrollOptions): InfiniteScrollResult;
+
+interface PullToRefreshOptions {
+    /** Distance in px to pull before triggering refresh (default: 60) */
+    threshold?: number;
+    /** Maximum pull distance in px (default: 120) */
+    maxPull?: number;
+}
+interface PullToRefreshResult {
+    /** Current pull distance in px */
+    pullDistance: number;
+    /** Whether the user is actively pulling */
+    isPulling: boolean;
+    /** Whether a refresh was triggered and is in progress */
+    isRefreshing: boolean;
+    /** Props to spread on the scrollable container */
+    containerProps: {
+        onTouchStart: (e: React__default.TouchEvent) => void;
+        onTouchMove: (e: React__default.TouchEvent) => void;
+        onTouchEnd: () => void;
+        style: React__default.CSSProperties;
+    };
+    /** Call this when the refresh operation completes */
+    endRefresh: () => void;
+}
+declare function usePullToRefresh(onRefresh: () => void, options?: PullToRefreshOptions): PullToRefreshResult;
+
+/**
+ * Unified pointer/touch gesture detection for canvas surfaces (graph, isometric, etc.).
+ *
+ * It owns the hard part — pointer tracking + two-finger pinch (scale factor + centroid) —
+ * and DELEGATES application to the consumer via callbacks, so each canvas applies pan/zoom
+ * in its own coordinate convention (screen-offset vs world-camera). A single pointer is
+ * passed straight through to the consumer's domain handlers (pan / node-drag / tile-select);
+ * a second pointer takes over as a pinch and cancels any in-flight single-pointer action.
+ *
+ * Pointer Events cover mouse, touch and pen, so this REPLACES mouse handlers — no dual paths.
+ */
+interface CanvasGestureCallbacks {
+    /** Single-pointer down — start the consumer's pan / drag / select (domain-specific). */
+    onPointerDown?: (e: React.PointerEvent<HTMLCanvasElement>) => void;
+    /** Single-pointer move. */
+    onPointerMove?: (e: React.PointerEvent<HTMLCanvasElement>) => void;
+    /** Single-pointer up. */
+    onPointerUp?: (e: React.PointerEvent<HTMLCanvasElement>) => void;
+    /**
+     * Multiplicative zoom around a canvas-local point. Fired by wheel and by pinch.
+     * Consumer applies `newZoom = clamp(oldZoom * factor)` keeping (centerX,centerY) fixed.
+     */
+    onZoom?: (factor: number, centerX: number, centerY: number) => void;
+    /** Two-finger pan delta in canvas-local px (fired alongside pinch). */
+    onPanDelta?: (dx: number, dy: number) => void;
+    /** A second pointer arrived — cancel any single-pointer pan/drag the consumer started. */
+    onMultiTouchStart?: () => void;
+}
+interface UseCanvasGesturesOptions extends CanvasGestureCallbacks {
+    /** The canvas being gestured on (for coordinate translation). */
+    canvasRef: React.RefObject<HTMLCanvasElement | null>;
+    /** When false, all gestures are inert. Default true. */
+    enabled?: boolean;
+    /** Wheel zoom step per notch (>1). Default 1.1. */
+    wheelStep?: number;
+}
+interface CanvasGestureHandlers {
+    onPointerDown: (e: React.PointerEvent<HTMLCanvasElement>) => void;
+    onPointerMove: (e: React.PointerEvent<HTMLCanvasElement>) => void;
+    onPointerUp: (e: React.PointerEvent<HTMLCanvasElement>) => void;
+    onPointerCancel: (e: React.PointerEvent<HTMLCanvasElement>) => void;
+    onWheel: (e: React.WheelEvent<HTMLCanvasElement>) => void;
+}
+declare function useCanvasGestures(options: UseCanvasGesturesOptions): CanvasGestureHandlers;
+
+/**
+ * Hover-only reveals (tooltips, hover-popovers, submenus, `Box.hoverEvent`) have no hover on
+ * touch, so they're invisible/unreachable. This adds the tap-to-reveal fallback: on a touch/pen
+ * tap the surface reveals and fires the SAME event the hover path fires; a tap outside dismisses.
+ * Mouse is left to the component's existing hover handlers (`pointerType === 'mouse'` is ignored),
+ * so this is purely additive — no behavior change on desktop.
+ */
+interface TapRevealOptions {
+    /** Fired when a tap reveals — reuse to emit the component's existing hover event. */
+    onReveal?: () => void;
+    /** Fired when an outside tap (or a second trigger tap) dismisses. */
+    onDismiss?: () => void;
+    /**
+     * Elements considered "inside" for outside-tap detection. Pass the trigger and the surface
+     * (the surface may be portaled, so it isn't a DOM descendant of the trigger). A tap whose
+     * target is inside none of these dismisses.
+     */
+    refs?: ReadonlyArray<React.RefObject<HTMLElement | null>>;
+    /** When false, taps are ignored (hover-only). Default true. */
+    enabled?: boolean;
+}
+interface TapRevealResult {
+    /** Whether the surface is currently revealed via a tap. OR this with the hover state. */
+    revealed: boolean;
+    /** Spread on the trigger; toggles reveal on a touch/pen tap (ignores mouse). */
+    triggerProps: {
+        onPointerDown: (e: React.PointerEvent) => void;
+    };
+    reveal: () => void;
+    dismiss: () => void;
+}
+declare function useTapReveal(options?: TapRevealOptions): TapRevealResult;
+
+/** Discriminated payload carried by every drag operation. */
+interface DraggablePayload {
+    kind: 'pattern' | 'behavior' | 'tree-node' | 'event-wire';
+    data: EventPayload;
+}
+interface UseDraggableOptions {
+    /** The payload that will be serialised into dataTransfer. */
+    payload: DraggablePayload;
+    /** When true the element cannot be dragged. */
+    disabled?: boolean;
+}
+interface UseDraggableResult {
+    /** Spread these onto the draggable element. */
+    dragProps: {
+        draggable: boolean;
+        onDragStart: (e: React.DragEvent) => void;
+        onDragEnd: (e: React.DragEvent) => void;
+        'aria-grabbed': boolean;
+    };
+    /** True while the element is being dragged. */
+    isDragging: boolean;
+}
+declare const ALMADAR_DND_MIME = "application/x-almadar-dnd";
+declare function useDraggable({ payload, disabled }: UseDraggableOptions): UseDraggableResult;
+
+interface UseDropZoneOptions {
+    /** Which payload kinds this zone accepts. */
+    accepts: DraggablePayload['kind'][];
+    /** Called when a valid payload is dropped. */
+    onDrop: (payload: DraggablePayload, position: {
+        x: number;
+        y: number;
+    }) => void;
+    /** When true the zone rejects all drops. */
+    disabled?: boolean;
+}
+interface UseDropZoneResult {
+    /** Spread these onto the drop-target element. */
+    dropProps: {
+        onDragOver: (e: React.DragEvent) => void;
+        onDragLeave: (e: React.DragEvent) => void;
+        onDrop: (e: React.DragEvent) => void;
+    };
+    /** True while a valid drag payload is hovering over this zone. */
+    isOver: boolean;
+}
+declare function useDropZone({ accepts, onDrop, disabled }: UseDropZoneOptions): UseDropZoneResult;
+
+interface Positioned {
+    id: string;
+    x: number;
+    y: number;
+}
+interface RenderInterpolationOptions {
+    /** Expected tick interval in ms (default: 1000/30 ≈ 33.3ms) */
+    tickIntervalMs?: number;
+}
+interface RenderInterpolationHandle<T extends Positioned> {
+    /** Call when a new authoritative snapshot arrives from the model */
+    onSnapshot: (entities: readonly T[]) => void;
+    /** Returns interpolated positions for the current rAF timestamp; falls back to authoritative values */
+    getInterpolated: (now: number) => Map<string, {
+        x: number;
+        y: number;
+    }>;
+    /** Start the rAF loop; call the supplied draw fn on every frame */
+    startLoop: (draw: (positions: Map<string, {
+        x: number;
+        y: number;
+    }>) => void) => () => void;
+}
+/**
+ * Fixed-timestep render interpolation between the last two authoritative model snapshots.
+ *
+ * Buffers two snapshots. On each rAF frame computes
+ *   alpha = clamp((now - lastArrival) / tickIntervalMs, 0, 1)
+ * and lerps x/y between prev and curr, matched by entity id.
+ * New or removed entities fall back to their authoritative value directly.
+ * Never throws; never causes a React re-render per frame.
+ */
+declare function useRenderInterpolation<T extends Positioned>(options?: RenderInterpolationOptions): RenderInterpolationHandle<T>;
+
+/**
+ * GitHub connection status
+ */
+interface GitHubStatus {
+    connected: boolean;
+    username?: string;
+    avatarUrl?: string;
+    scopes?: string[];
+    connectedAt?: number;
+    lastUsedAt?: number;
+}
+/**
+ * GitHub repository
+ */
+interface GitHubRepo {
+    id: number;
+    name: string;
+    fullName: string;
+    owner: string;
+    isPrivate: boolean;
+    description: string | null;
+    defaultBranch: string;
+    url: string;
+}
+/**
+ * Hook to get GitHub connection status
+ */
+declare function useGitHubStatus(): _tanstack_react_query.UseQueryResult<NoInfer<GitHubStatus>, Error>;
+/**
+ * Hook to connect GitHub (initiate OAuth flow)
+ */
+declare function useConnectGitHub(): {
+    connectGitHub: () => void;
+};
+/**
+ * Hook to disconnect GitHub
+ */
+declare function useDisconnectGitHub(): _tanstack_react_query.UseMutationResult<unknown, Error, void, unknown>;
+/**
+ * Hook to list GitHub repositories
+ */
+declare function useGitHubRepos(page?: number, perPage?: number): _tanstack_react_query.UseQueryResult<NoInfer<{
+    repos: GitHubRepo[];
+    page: number;
+    perPage: number;
+}>, Error>;
+/**
+ * Hook to get repository details
+ */
+declare function useGitHubRepo(owner: string, repo: string, enabled?: boolean): _tanstack_react_query.UseQueryResult<NoInfer<{
+    repo: GitHubRepo;
+}>, Error>;
+/**
+ * Hook to list repository branches
+ */
+declare function useGitHubBranches(owner: string, repo: string, enabled?: boolean): _tanstack_react_query.UseQueryResult<NoInfer<{
+    branches: string[];
+}>, Error>;
+
+export { ALMADAR_DND_MIME, type AuthContextValue, type AuthUser, type CanvasGestureCallbacks, type CanvasGestureHandlers, type CompileResult, type CompileStage, type DragReorderResult, type DraggablePayload, type Extension, type ExtensionManifest, type FileSystemFile, type FileSystemStatus, type GitHubRepo, type GitHubStatus, type HistoryChangeSummary, type HistoryTimelineItem, type I18nContextValue, I18nProvider, type InfiniteScrollOptions, type InfiniteScrollResult, type LongPressHandlers, type LongPressOptions, type OpenFile, type Positioned, type PullToRefreshOptions, type PullToRefreshResult, type QuerySingletonEntity, type QuerySingletonResult, type QuerySingletonState, type QueryState, type RenderInterpolationHandle, type RenderInterpolationOptions, type RevertResult, type SelectedFile, type SharedEntityStore, type SharedEntitySubscriber, type SharedEntityWriter, type SwipeGestureOptions, type SwipeGestureResult, type SwipeHandlers, type TapRevealOptions, type TapRevealResult, type TraitListenSpec, type TranslateFunction, type UseCanvasGesturesOptions, type UseCompileResult, type UseDraggableOptions, type UseDraggableResult, type UseDropZoneOptions, type UseDropZoneResult, type UseExtensionsOptions, type UseExtensionsResult, type UseFileEditorOptions, type UseFileEditorResult, type UseFileSystemResult, type UseOrbitalHistoryOptions, type UseOrbitalHistoryResult, createSharedEntityStore, createTranslate, parseQueryBinding, runTickFrame, useAgentChat, useAuthContext, useCanvasGestures, useCompile, useConnectGitHub, useDeepAgentGeneration, useDisconnectGitHub, useDragReorder, useDraggable, useDropZone, useEventBus, useExtensions, useFileEditor, useFileSystem, useGitHubBranches, useGitHubRepo, useGitHubRepos, useGitHubStatus, useInfiniteScroll, useLongPress, useOrbitalHistory, usePreview, usePullToRefresh, useQuerySingleton, useRenderInterpolation, useSharedEntitySnapshot, useSharedEntityStore, useSwipeGesture, useTapReveal, useTraitListens, useTranslate, useUIEvents, useValidation };