@almadar/ui 5.78.0 → 5.79.1

package/dist/hooks/useAgentChat.d.ts

@@ -1,105 +0,0 @@
-import type { DeepAgentInterrupt } from './useDeepAgentGeneration';
-import type { FieldValue, OrbitalSchema } from '@almadar/core';
-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, 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;
-};
-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?: OrbitalSchema) => void;
-    onSchemaChange?: (diff?: OrbitalSchema) => 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, FieldValue>) => Promise<void>;
-    continueConversation: (message: string | string[]) => Promise<void>;
-    resumeWithDecision: (decisions: FieldValue[]) => Promise<void>;
-    cancel: () => void;
-    clearMessages: () => void;
-    clearHistory: () => void;
-}
-export declare function useAgentChat(options?: UseAgentChatOptions): UseAgentChatResult;

package/dist/hooks/useAlmadarDndCollision.d.ts

@@ -1,34 +0,0 @@
-/**
- * Shared DnD primitives — sensor config + collision waterfall.
- *
- * Both the row-reorder primitive (`useDataDnd` in DataList/DataGrid) and the
- * canvas-insert primitive (`useCanvasDnd` in AVL OrbPreviewNode) need
- * identical pointer activation behavior and the same multi-container
- * collision strategy. Centralizing them here keeps the two hooks from
- * drifting and gives a single tunable spot when DnD ergonomics need a tweak.
- *
- * Activation: `distance: 5` on the PointerSensor so a small accidental
- * tremor doesn't fire a drag — matches the threshold dnd-kit's own examples
- * use for grab-and-drag interactions.
- *
- * Collision waterfall (run in order, first non-empty wins):
- *   1. pointerWithin     — catches the empty zones + clean hover-over-zone case
- *   2. rectIntersection  — falls back when the pointer is in margin/padding
- *   3. closestCorners    — last resort over the items in whichever zone won
- */
-import { type CollisionDetection, type SensorDescriptor, type SensorOptions } from '@dnd-kit/core';
-export declare const ALMADAR_DND_ACTIVATION_DISTANCE = 5;
-/**
- * Returns the canonical sensor stack used by every Almadar DnD primitive.
- *
- * @param withSortableKeyboard - when true, the KeyboardSensor uses
- *   `sortableKeyboardCoordinates` (correct for sortable lists). Defaults to
- *   true so `useDataDnd` keeps its current behavior; `useCanvasDnd` doesn't
- *   need it (no sortable rows) so it can pass false.
- */
-export declare function useAlmadarDndSensors(withSortableKeyboard?: boolean): SensorDescriptor<SensorOptions>[];
-/**
- * Multi-container collision waterfall.
- * pointerWithin → rectIntersection → closestCorners.
- */
-export declare const almadarDndCollisionDetection: CollisionDetection;

package/dist/hooks/useAuthContext.d.ts

@@ -1,25 +0,0 @@
-/**
- * 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/useCanvasGestures.d.ts

@@ -1,44 +0,0 @@
-/**
- * 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.
- */
-export 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;
-}
-export 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;
-}
-export 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;
-}
-export declare function useCanvasGestures(options: UseCanvasGesturesOptions): CanvasGestureHandlers;

package/dist/hooks/useClientEffects.d.ts

@@ -1,88 +0,0 @@
-import type { ClientEffect, ClientEffectExecutorConfig } from '../types/renderer-types';
-/**
- * Options for the useClientEffects hook
- */
-export interface UseClientEffectsOptions extends ClientEffectExecutorConfig {
-    /**
-     * Whether to execute effects. Defaults to true.
-     * Set to false to temporarily disable effect execution.
-     */
-    enabled?: boolean;
-    /**
-     * Debug mode - logs effect execution details.
-     */
-    debug?: boolean;
-}
-/**
- * Result of useClientEffects hook
- */
-export interface UseClientEffectsResult {
-    /**
-     * Number of effects executed in the last batch.
-     */
-    executedCount: number;
-    /**
-     * Whether effects are currently being executed.
-     */
-    executing: boolean;
-    /**
-     * Manually trigger effect execution.
-     * Useful for imperative control.
-     */
-    execute: (effects: ClientEffect[]) => void;
-}
-/**
- * Execute client effects from server response.
- *
- * This hook automatically executes effects when they change,
- * tracking which effects have been executed to prevent duplicates.
- *
- * @param effects - Array of client effects to execute (from server response)
- * @param options - Configuration including effect implementations
- * @returns Hook result with execution state and manual trigger
- *
- * @example
- * ```typescript
- * function useMyTrait() {
- *   const [state, setState] = useState({ pendingEffects: [] });
- *   const effectConfig = useClientEffectConfig();
- *
- *   useClientEffects(state.pendingEffects, {
- *     ...effectConfig,
- *     onComplete: () => setState(s => ({ ...s, pendingEffects: [] }))
- *   });
- *
- *   // ...
- * }
- * ```
- */
-export declare function useClientEffects(effects: ClientEffect[] | undefined, options: UseClientEffectsOptions): UseClientEffectsResult;
-declare const ClientEffectConfigContext: import("react").Context<ClientEffectExecutorConfig | null>;
-/**
- * Provider for client effect configuration.
- */
-export declare const ClientEffectConfigProvider: import("react").Provider<ClientEffectExecutorConfig | null>;
-/**
- * Hook to get the client effect configuration from context.
- *
- * @throws Error if used outside of ClientEffectConfigProvider
- *
- * @example
- * ```typescript
- * function MyTraitHook() {
- *   const effectConfig = useClientEffectConfig();
- *
- *   useClientEffects(pendingEffects, {
- *     ...effectConfig,
- *     onComplete: () => clearPendingEffects()
- *   });
- * }
- * ```
- */
-export declare function useClientEffectConfig(): ClientEffectExecutorConfig;
-/**
- * Hook to get client effect configuration, returning null if not available.
- * Use this for optional integration where effects may not be configured.
- */
-export declare function useClientEffectConfigOptional(): ClientEffectExecutorConfig | null;
-export { ClientEffectConfigContext };

package/dist/hooks/useCompile.d.ts

@@ -1,18 +0,0 @@
-import type { OrbitalSchema } from '@almadar/core';
-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: OrbitalSchema) => Promise<CompileResult | null>;
-}
-export declare function useCompile(): UseCompileResult;

package/dist/hooks/useDeepAgentGeneration.d.ts

@@ -1,46 +0,0 @@
-import type { OrbitalSchema, FieldValue } from '@almadar/core';
-export interface DeepAgentActionRequest {
-    id: string;
-    type: string;
-    tool: string;
-    args: Record<string, FieldValue>;
-    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, FieldValue>) => Promise<void>;
-    cancelGeneration: () => void;
-    clearRequests: () => void;
-    submitInterruptDecisions: (decisions: FieldValue[]) => void;
-}
-export declare function useDeepAgentGeneration(): UseDeepAgentGenerationResult;

package/dist/hooks/useDragReorder.d.ts

@@ -1,26 +0,0 @@
-import type React from 'react';
-export 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.PointerEvent) => void;
-        style: React.CSSProperties;
-        'aria-grabbed': boolean;
-        role: string;
-    };
-    /** Props to spread on each list item for a given index */
-    getItemProps: (index: number) => {
-        onPointerMove: (e: React.PointerEvent) => void;
-        onPointerUp: () => void;
-        'aria-dropeffect': string;
-        style: React.CSSProperties;
-    };
-}
-export declare function useDragReorder<T>(initialItems: T[], onReorder: (fromIndex: number, toIndex: number, item: T) => void): DragReorderResult<T>;

package/dist/hooks/useDraggable.d.ts

@@ -1,25 +0,0 @@
-import type { EventPayload } from '@almadar/core';
-/** Discriminated payload carried by every drag operation. */
-export interface DraggablePayload {
-    kind: 'pattern' | 'behavior' | 'tree-node' | 'event-wire';
-    data: EventPayload;
-}
-export interface UseDraggableOptions {
-    /** The payload that will be serialised into dataTransfer. */
-    payload: DraggablePayload;
-    /** When true the element cannot be dragged. */
-    disabled?: boolean;
-}
-export 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;
-}
-export declare const ALMADAR_DND_MIME = "application/x-almadar-dnd";
-export declare function useDraggable({ payload, disabled }: UseDraggableOptions): UseDraggableResult;

package/dist/hooks/useDropZone.d.ts

@@ -1,23 +0,0 @@
-import { type DraggablePayload } from './useDraggable';
-export 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;
-}
-export 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;
-}
-export declare function useDropZone({ accepts, onDrop, disabled }: UseDropZoneOptions): UseDropZoneResult;

package/dist/hooks/useEventBus.d.ts

@@ -1,99 +0,0 @@
-import type { BusEvent, BusEventSource, BusEventListener, Unsubscribe, EventBusContextType } from '../types/event-bus-types';
-import type { EventPayload } from '@almadar/core';
-export type { BusEvent, BusEventSource, BusEventListener, Unsubscribe, EventBusContextType };
-/** @deprecated Use BusEventListener from @almadar/core. */
-export type { BusEventListener as EventListener };
-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: BusEventListener): 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?: EventPayload, source?: BusEventSource) => void;
-export default useEventBus;

package/dist/hooks/useExtensions.d.ts

@@ -1,32 +0,0 @@
-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

@@ -1,32 +0,0 @@
-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

@@ -1,50 +0,0 @@
-interface FileSystemTree {
-    [name: string]: {
-        file: {
-            contents: string;
-        };
-    } | {
-        directory: FileSystemTree;
-    };
-}
-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[] | 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>;
-}
-export declare function useFileSystem(): UseFileSystemResult;
-export {};