@almadar/shell-web 0.0.0-stage → 1.0.0

package/dist/hooks/index.d.ts

@@ -0,0 +1,971 @@
+import { OrbitalSchema, FieldValue, EventPayload, BusEventSource, EntityFrameState, EntityFieldWrite, PageMeta, PageAccess, PageIndexing, LocaleAlternate } from '@almadar/core';
+export { BusEvent, BusEventListener, BusEventSource, BusEventListener as EventListener, UISlot, Unsubscribe } from '@almadar/core';
+export { D as DEFAULT_SLOTS, S as SlotChangeCallback, a as SlotContent, b as SlotRenderConfig, U as UISlotManager, u as useUISlotManager } from '../useUISlots-CiobNFGb.js';
+import { useEventBus } from '../core.js';
+import * as React$1 from 'react';
+import React__default from 'react';
+import * as _tanstack_react_query from '@tanstack/react-query';
+
+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;
+
+interface KeyCaptureEntry {
+    mode: string;
+    keys: ReadonlySet<string>;
+}
+/** keyed by editorId, or the literal 'shell' for chrome-level bindings */
+type KeyCaptureTable = Readonly<Record<string, KeyCaptureEntry>>;
+interface EditorKeyEvent {
+    editorId: string;
+    key: string;
+    code: string;
+    ctrl: boolean;
+    alt: boolean;
+    shift: boolean;
+    meta: boolean;
+    repeat: boolean;
+}
+/**
+ * Merges several plugins' capture tables into one, per target: keys UNION
+ * across every table that declares the target; `mode` is `'any'` if any
+ * input says so, else the shared mode when every input agrees, else the
+ * distinct modes sorted and `|`-joined. A target present in only one table
+ * passes through unchanged. Pure, deterministic — no heuristics.
+ */
+declare function mergeCaptureTables(tables: readonly KeyCaptureTable[]): KeyCaptureTable;
+/** `"Control+Shift+P"`-style spelling of a keydown: modifiers in the fixed order Control, Alt, Shift, Meta, then `event.key`. */
+declare function keyChord(event: Pick<KeyboardEvent, 'key' | 'ctrlKey' | 'altKey' | 'shiftKey' | 'metaKey'>): string;
+interface UseKeyboardRouterOptions {
+    /** declared data; caller owns it; re-read on every keydown (kept in a ref) */
+    captureTable: KeyCaptureTable;
+    /** default 'KEY' -> emits UI:KEY */
+    keyEvent?: string;
+    /** default true */
+    enabled?: boolean;
+}
+declare function useKeyboardRouter(options: UseKeyboardRouterOptions): void;
+
+/**
+ * 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 | Promise<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;
+
+/**
+ * At-most-once delivery: one physical emit reaches a trait once per triggered
+ * event. Every key one emit fans to (scope-chain bubbling, a listen route)
+ * carries the same `source` object, so the first delivery to a (trait, event)
+ * claims it and the rest are the same event again. A sourceless emit is never
+ * deduplicated. Shared by the runtime ingress (`useBusIngress`), `useUIEvents`
+ * and compiled listens.
+ */
+
+declare function claimDelivery(source: BusEventSource | undefined, trait: string, event: string): boolean;
+
+/** 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 kernel's tick clock, 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;
+/**
+ * Cross-component access to ONE `SharedEntityStore` instance. `useSharedEntityStore`
+ * is `useRef`-scoped to its own call site — correct for a single owner (the JS
+ * runtime path's `useTraitStateMachine` interprets a whole orbital in one hook
+ * call), but the compiled path (`orbital-rust`'s TS-shell codegen) generates one
+ * hook + component PER TRAIT, so several independent trait hooks bound to the
+ * SAME `[shared]` entity need the SAME store instance. A page-level owner calls
+ * `useSharedEntityStore()` once and provides it here; every trait hook on that
+ * page reads it back via `useSharedEntityStoreContext()` instead of creating its
+ * own disconnected store. Not used by the JS runtime path today — purely
+ * additive, zero effect on `useSharedEntityStore`'s existing single-caller
+ * behavior.
+ */
+declare const SharedEntityStoreContext: React$1.Context<SharedEntityStore | null>;
+/** Read the page-level `SharedEntityStore` provided by `SharedEntityStoreContext`. */
+declare function useSharedEntityStoreContext(): 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 kernel-clock 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;
+};
+
+/**
+ * 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: 'button';
+    };
+    /** 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 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: WheelEvent) => void;
+}
+declare function useCanvasGestures(options: UseCanvasGesturesOptions): CanvasGestureHandlers;
+
+/** 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<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<{
+    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<{
+    repo: GitHubRepo;
+}, Error>;
+/**
+ * Hook to list repository branches
+ */
+declare function useGitHubBranches(owner: string, repo: string, enabled?: boolean): _tanstack_react_query.UseQueryResult<{
+    branches: string[];
+}, Error>;
+
+/**
+ * The active page's document head on client navigation — the same declared
+ * contract the build writes into each route document: title, description,
+ * canonical, social tags and the robots directive, with `i18n/t` metadata
+ * resolved from the active locale's catalog. The tags it writes are marked
+ * and replaced on every page change; entering an `authenticated` or
+ * `noindex` page drops the public tags and declares `noindex`.
+ *
+ * @packageDocumentation
+ */
+
+interface PageHeadInput {
+    title?: PageMeta;
+    description?: PageMeta;
+    access?: PageAccess;
+    indexing?: PageIndexing;
+    /** The app's `origin:`, for the canonical URL. */
+    origin?: string;
+    /** The app's `siteName:` — the document title of a page that declares none. */
+    siteName?: string;
+    /** The concrete path on screen. */
+    path: string;
+    /** The page's translations (`localeAlternates`), written as hreflang links. */
+    alternates?: readonly LocaleAlternate[];
+    /** The app's first locale, the `x-default` alternate. */
+    defaultLocale?: string;
+}
+/** Writes `input`'s head into the document; `null` writes nothing. */
+declare function usePageHead(input: PageHeadInput | null): void;
+
+/**
+ * Whether a `[visible]` tick may fire now: its trait group is not off screen (LOLO §11).
+ * Watches the group while mounted so `TraitScopeProvider` tracks the group's output.
+ */
+declare function useTickVisibility(traits: readonly string[]): () => boolean;
+
+export { ALMADAR_DND_MIME, SharedEntityStoreContext, claimDelivery, createSharedEntityStore, keyChord, mergeCaptureTables, parseQueryBinding, runTickFrame, useAgentChat, useAuthContext, useCanvasGestures, useCompile, useConnectGitHub, useDeepAgentGeneration, useDisconnectGitHub, useDragReorder, useDraggable, useDropZone, useExtensions, useFileEditor, useFileSystem, useGitHubBranches, useGitHubRepo, useGitHubRepos, useGitHubStatus, useKeyboardRouter, useLongPress, usePageHead, usePreview, usePullToRefresh, useQuerySingleton, useRenderInterpolation, useSharedEntitySnapshot, useSharedEntityStore, useSharedEntityStoreContext, useSwipeGesture, useTickVisibility, useTraitListens, useUIEvents, useValidation };
+export type { AuthContextValue, AuthUser, CanvasGestureCallbacks, CanvasGestureHandlers, CompileResult, CompileStage, DragReorderResult, DraggablePayload, EditorKeyEvent, Extension, ExtensionManifest, FileSystemFile, FileSystemStatus, GitHubRepo, GitHubStatus, KeyCaptureEntry, KeyCaptureTable, LongPressHandlers, LongPressOptions, OpenFile, PageHeadInput, Positioned, PullToRefreshOptions, PullToRefreshResult, QuerySingletonEntity, QuerySingletonResult, QuerySingletonState, QueryState, RenderInterpolationHandle, RenderInterpolationOptions, SelectedFile, SharedEntityStore, SharedEntitySubscriber, SharedEntityWriter, SwipeGestureOptions, SwipeGestureResult, SwipeHandlers, TraitListenSpec, UseCanvasGesturesOptions, UseCompileResult, UseDraggableOptions, UseDraggableResult, UseDropZoneOptions, UseDropZoneResult, UseExtensionsOptions, UseExtensionsResult, UseFileEditorOptions, UseFileEditorResult, UseFileSystemResult, UseKeyboardRouterOptions };