@constela/runtime 0.19.6 → 0.19.7

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import { CompiledExpression, CompiledAction, CompiledNode, CompiledLocalAction, CompiledProgram } from '@constela/compiler';
+import { CompiledExpression, CompiledAction, CompiledNode, CompiledLocalAction, CompiledProgram, CompiledIslandNode } from '@constela/compiler';
+import { IslandStrategy, IslandStrategyOptions, ThemeConfig, ColorScheme, ThemeColors, ThemeFonts } from '@constela/core';
 
 interface Signal<T> {
     get(): T;
@@ -245,6 +246,187 @@ declare function createWebSocketConnection(url: string, handlers: WebSocketHandl
  */
 declare function createConnectionManager(): ConnectionManager;
 
+/**
+ * SSE (Server-Sent Events) Connection Module
+ *
+ * This file provides the interface definitions and implementations
+ * for SSE connection management in Constela runtime.
+ *
+ * SSE is a one-way communication protocol from server to client,
+ * making it ideal for real-time updates, notifications, and streaming data.
+ */
+/**
+ * SSE connection interface for managing server-sent events
+ * Note: SSE is one-way (server to client), so there is no send method
+ */
+interface SSEConnection {
+    /**
+     * Close the SSE connection
+     */
+    close(): void;
+    /**
+     * Get the current connection state
+     * @returns The connection state
+     */
+    getState(): 'connecting' | 'open' | 'closed';
+}
+/**
+ * Event handlers for SSE connection events
+ */
+interface SSEHandlers {
+    /** Called when connection is established */
+    onOpen?: () => Promise<void> | void;
+    /** Called when connection is closed */
+    onClose?: () => Promise<void> | void;
+    /** Called when an error occurs */
+    onError?: (error: Event) => Promise<void> | void;
+    /** Called when a message is received (JSON parsed if possible) */
+    onMessage?: (data: unknown, eventType: string) => Promise<void> | void;
+}
+/**
+ * SSE Connection manager for named connections
+ */
+interface SSEConnectionManager {
+    /**
+     * Create a new named SSE connection
+     * If a connection with the same name exists, it will be closed first
+     */
+    create(name: string, url: string, handlers: SSEHandlers, eventTypes?: string[]): void;
+    /**
+     * Get a connection by name
+     * @returns The connection or undefined if not found
+     */
+    get(name: string): SSEConnection | undefined;
+    /**
+     * Close a named connection
+     * No-op if connection not found
+     */
+    close(name: string): void;
+    /**
+     * Close all connections
+     */
+    closeAll(): void;
+}
+/**
+ * Create an SSE connection with event handlers
+ *
+ * @param url - The SSE endpoint URL (e.g., "https://api.example.com/events")
+ * @param handlers - Event handlers for connection lifecycle
+ * @param eventTypes - Optional array of custom event types to listen for
+ * @returns An SSEConnection interface for managing the connection
+ */
+declare function createSSEConnection(url: string, handlers: SSEHandlers, eventTypes?: string[]): SSEConnection;
+/**
+ * Create an SSE connection manager for managing multiple named connections
+ *
+ * @returns An SSEConnectionManager interface
+ */
+declare function createSSEConnectionManager(): SSEConnectionManager;
+
+/**
+ * OptimisticManager - Manages optimistic UI updates with rollback support.
+ *
+ * TDD Stub: This file contains only type definitions and stub implementations
+ * to allow tests to run and fail at assertion level (Red phase).
+ */
+/**
+ * Represents a pending optimistic update that can be confirmed or rejected.
+ */
+interface PendingUpdate {
+    /** Unique identifier for this update */
+    id: string;
+    /** The state target being updated */
+    target: string;
+    /** Optional path for nested updates (e.g., ['items', 0, 'liked']) */
+    path: (string | number)[] | undefined;
+    /** The original value before optimistic update */
+    originalValue: unknown;
+    /** The optimistically applied value */
+    optimisticValue: unknown;
+    /** Timestamp when the update was applied */
+    timestamp: number;
+}
+/**
+ * Manager for optimistic UI updates with automatic rollback support.
+ */
+interface OptimisticManager {
+    /**
+     * Apply an optimistic update immediately.
+     * @param target - The state target to update
+     * @param path - Optional path for nested updates
+     * @param value - The optimistic value to apply
+     * @param getState - Function to get current state
+     * @param setState - Function to set new state
+     * @returns Unique ID for this update
+     */
+    apply(target: string, path: (string | number)[] | undefined, value: unknown, getState: (target: string) => unknown, setState: (target: string, value: unknown) => void): string;
+    /**
+     * Confirm an optimistic update (server accepted).
+     * @param id - The update ID to confirm
+     * @returns true if update was found and confirmed, false otherwise
+     */
+    confirm(id: string): boolean;
+    /**
+     * Reject an optimistic update and rollback to original value.
+     * @param id - The update ID to reject
+     * @param getState - Function to get current state
+     * @param setState - Function to set new state
+     * @returns true if update was found and rejected, false otherwise
+     */
+    reject(id: string, getState: (target: string) => unknown, setState: (target: string, value: unknown) => void): boolean;
+    /**
+     * Get a pending update by ID.
+     * @param id - The update ID to look up
+     * @returns The pending update or undefined if not found
+     */
+    getPending(id: string): PendingUpdate | undefined;
+    /**
+     * Get all pending updates.
+     * @returns Array of all pending updates
+     */
+    getAllPending(): PendingUpdate[];
+    /**
+     * Set auto-rollback timeout for pending updates.
+     * @param ms - Timeout in milliseconds (0 to disable)
+     */
+    setAutoRollbackTimeout(ms: number): void;
+    /**
+     * Dispose the manager and clear all pending updates.
+     */
+    dispose(): void;
+}
+/**
+ * Create a new OptimisticManager instance.
+ */
+declare function createOptimisticManager(): OptimisticManager;
+
+/**
+ * Realtime Data Binding
+ *
+ * Automatically updates state when messages arrive from WebSocket/SSE connections.
+ */
+interface BindingConfig {
+    connection: string;
+    eventType?: string;
+    target: string;
+    path?: (string | number)[];
+    transform?: (data: unknown) => unknown;
+    patch?: boolean;
+}
+type SetStateFn = (target: string, value: unknown, pathOrOptions?: (string | number)[] | {
+    patch: boolean;
+}) => void;
+interface BindingManager {
+    bind(config: BindingConfig, setState: SetStateFn): string;
+    unbind(id: string): boolean;
+    unbindByConnection(connection: string): void;
+    unbindByTarget(target: string): void;
+    handleMessage(connection: string, data: unknown, eventType?: string): void;
+    getBindings(): BindingConfig[];
+    dispose(): void;
+}
+declare function createBindingManager(): BindingManager;
+
 /**
  * Action Executor - Executes compiled action steps
  *
@@ -286,6 +468,9 @@ interface ActionContext {
     };
     imports?: Record<string, unknown>;
     connections?: ConnectionManager;
+    sse?: SSEConnectionManager;
+    optimistic?: OptimisticManager;
+    binding?: BindingManager;
 }
 declare function executeAction(action: CompiledAction | ExtendedAction, ctx: ActionContext): Promise<void>;
 
@@ -392,6 +577,191 @@ interface HydrateOptions {
  * @returns AppInstance for controlling the hydrated application
  */
 declare function hydrateApp(options: HydrateOptions): AppInstance;
+/**
+ * Hydrates all islands in the application with their respective strategies.
+ * Returns a cleanup function that cleans up all island resources.
+ *
+ * @param program - The compiled program
+ * @param options - Options including the container element
+ * @returns Cleanup function to dispose all island hydrations
+ */
+declare function hydrateAppWithIslands(program: CompiledProgram, options?: {
+    container?: HTMLElement;
+}): () => void;
+
+/**
+ * Island Hydration - Runtime Partial Hydration
+ *
+ * This module provides selective hydration for Islands Architecture,
+ * enabling fine-grained control over when interactive components become active.
+ */
+
+interface IslandHydrationOptions {
+    element: HTMLElement;
+    id: string;
+    strategy: IslandStrategy;
+    strategyOptions?: IslandStrategyOptions;
+    state?: Record<string, unknown>;
+    program: CompiledProgram | CompiledIslandNode;
+}
+/**
+ * Hydrates an island based on the specified strategy.
+ * Returns a cleanup function to cancel pending hydration or cleanup resources.
+ */
+declare function hydrateIsland(options: IslandHydrationOptions): () => void;
+/**
+ * Detects islands in the DOM by looking for data attributes.
+ * Returns an array of island configurations extracted from the DOM.
+ */
+declare function detectIslandsInDOM(container: HTMLElement): Array<{
+    element: HTMLElement;
+    id: string;
+    strategy: IslandStrategy;
+    strategyOptions?: IslandStrategyOptions;
+    state?: Record<string, unknown>;
+}>;
+
+/**
+ * Island Loader - Dynamic module loading for Islands Architecture
+ *
+ * This module provides lazy loading and caching for island bundles,
+ * enabling efficient code splitting for interactive components.
+ */
+/**
+ * Options for creating an island loader.
+ */
+interface IslandLoaderOptions {
+    /** Base path for island bundles (default: "/_constela/islands/") */
+    basePath?: string;
+}
+/**
+ * Loaded island module structure.
+ */
+interface LoadedIslandModule {
+    /** The island definition */
+    island: unknown;
+    /** Island state definitions */
+    state: Record<string, {
+        type: string;
+        initial: unknown;
+    }>;
+    /** Island action definitions */
+    actions: Record<string, unknown>;
+    /** Default export (same as island) */
+    default: unknown;
+}
+/**
+ * Island loader interface.
+ */
+interface IslandLoader {
+    /**
+     * Load an island module by ID.
+     * Returns a promise that resolves with the loaded module.
+     */
+    load(id: string): Promise<LoadedIslandModule>;
+    /**
+     * Preload an island module in the background.
+     * Fire-and-forget operation for warming the cache.
+     */
+    preload(id: string): void;
+}
+/**
+ * Create an island loader for dynamically loading island bundles.
+ *
+ * The loader provides:
+ * - Dynamic import of island bundles
+ * - Caching of loaded modules
+ * - Deduplication of concurrent requests
+ * - Preloading for performance optimization
+ *
+ * @param options - Loader options
+ * @returns Island loader instance
+ *
+ * @example
+ * ```typescript
+ * const loader = createIslandLoader();
+ *
+ * // Load an island when needed
+ * const module = await loader.load('counter-island');
+ *
+ * // Preload islands for faster subsequent loads
+ * loader.preload('modal-island');
+ * ```
+ */
+declare function createIslandLoader(options?: IslandLoaderOptions): IslandLoader;
+
+/**
+ * Reconnection Manager Module
+ *
+ * Provides automatic reconnection logic for WebSocket and SSE connections
+ * with configurable backoff strategies (exponential, linear, or none).
+ *
+ * Features:
+ * - Exponential backoff: delay = min(baseDelay * 2^attempt, maxDelay)
+ * - Linear backoff: delay = min(baseDelay * (attempt + 1), maxDelay)
+ * - Max retries limit with callback
+ * - Retry count reset on successful reconnection
+ * - Manual trigger reconnection
+ * - Timer cleanup on dispose
+ */
+/**
+ * Reconnection policy configuration
+ */
+interface ReconnectionPolicy {
+    /** Whether automatic reconnection is enabled */
+    enabled: boolean;
+    /** Backoff strategy: 'exponential' doubles delay, 'linear' adds baseDelay, 'none' disables */
+    strategy: 'exponential' | 'linear' | 'none';
+    /** Maximum number of reconnection attempts */
+    maxRetries: number;
+    /** Initial delay in milliseconds */
+    baseDelay: number;
+    /** Maximum delay cap in milliseconds */
+    maxDelay: number;
+}
+/**
+ * Interface for reconnectable connections (WebSocket, SSE)
+ */
+interface Reconnectable {
+    /** Get current connection state */
+    getState(): string;
+    /** Close the connection */
+    close(): void;
+}
+/**
+ * Reconnection manager interface
+ */
+interface ReconnectionManager {
+    /**
+     * Wrap a connection with automatic reconnection logic
+     * @param connection - The connection to wrap
+     * @param reconnectFn - Function that creates a new connection
+     * @param policy - Reconnection policy configuration
+     * @param onReconnect - Optional callback when reconnection succeeds
+     * @param onMaxRetriesReached - Optional callback when max retries reached
+     * @returns The wrapped connection
+     */
+    wrap<T extends Reconnectable>(connection: T, reconnectFn: () => T, policy: ReconnectionPolicy, onReconnect?: () => void, onMaxRetriesReached?: () => void): T;
+    /**
+     * Manually trigger reconnection for a connection
+     * @param connection - The connection to reconnect
+     */
+    triggerReconnect(connection: Reconnectable): void;
+    /**
+     * Stop reconnection attempts and cleanup for a specific connection
+     * @param connection - The connection to dispose
+     */
+    dispose(connection: Reconnectable): void;
+    /**
+     * Stop all reconnection attempts and cleanup all connections
+     */
+    disposeAll(): void;
+}
+/**
+ * Create a reconnection manager that handles automatic reconnection
+ * for WebSocket and SSE connections with configurable backoff strategies.
+ */
+declare function createReconnectionManager(): ReconnectionManager;
 
 /**
  * HMR Client - WebSocket client for Hot Module Replacement
@@ -590,4 +960,116 @@ interface ErrorOverlay {
  */
 declare function createErrorOverlay(): ErrorOverlay;
 
-export { type ActionContext, type AppInstance, type Computed, type ConnectionManager, type ErrorInfo, type ErrorOverlay, type EvaluationContext, type HMRClient, type HMRClientOptions, type HMRHandler, type HMRHandlerOptions, type HydrateOptions, type RenderContext, type RouteContext, type Signal, type StateStore, type StylePreset, type TypedStateStore, type WebSocketConnection, type WebSocketHandlers, createApp, createComputed, createConnectionManager, createEffect, createErrorOverlay, createHMRClient, createHMRHandler, createSignal, createStateStore, createTypedStateStore, createWebSocketConnection, evaluate, evaluateStyle, executeAction, hydrateApp, render };
+/**
+ * ThemeProvider - Runtime theme management for Constela UI
+ *
+ * Provides reactive theme state management with:
+ * - System theme detection via prefers-color-scheme
+ * - CSS variable application to :root
+ * - Dark class management on document.documentElement
+ * - Persistence via localStorage (optional cookies)
+ * - Subscription-based notifications
+ */
+
+interface ThemeProviderOptions {
+    config?: ThemeConfig;
+    storageKey?: string;
+    useCookies?: boolean;
+    defaultMode?: ColorScheme;
+}
+interface ResolvedTheme {
+    resolvedMode: 'light' | 'dark';
+    selectedMode: ColorScheme;
+    colors: ThemeColors;
+    fonts: ThemeFonts;
+}
+interface ThemeProvider {
+    getTheme(): ResolvedTheme;
+    getMode(): ColorScheme;
+    setMode(mode: ColorScheme): void;
+    subscribe(fn: (theme: ResolvedTheme) => void): () => void;
+    setColors(colors: ThemeColors, mode?: 'light' | 'dark'): void;
+    destroy(): void;
+}
+/**
+ * Creates a ThemeProvider instance for managing application theme state.
+ */
+declare function createThemeProvider(options?: ThemeProviderOptions): ThemeProvider;
+
+/**
+ * Island Prefetching - Optimized preloading for Islands Architecture
+ *
+ * This module provides prefetching strategies for island bundles,
+ * enabling optimized loading based on user interaction patterns.
+ */
+
+declare const PREFETCH_STRATEGIES: readonly ["hover", "visible", "immediate"];
+type PrefetchStrategy = (typeof PREFETCH_STRATEGIES)[number];
+/**
+ * Options for configuring prefetch behavior.
+ */
+interface PrefetchOptions {
+    /** The prefetch strategy to use */
+    strategy: PrefetchStrategy;
+    /** Intersection threshold for visible strategy (0-1) */
+    threshold?: number;
+    /** Root margin for visible strategy */
+    rootMargin?: string;
+}
+/**
+ * Prefetcher interface returned by createPrefetcher.
+ */
+interface Prefetcher {
+    /**
+     * Prefetch an island when the element is hovered.
+     * Returns a cleanup function to remove the event listener.
+     */
+    prefetchOnHover(element: HTMLElement, id: string): () => void;
+    /**
+     * Prefetch an island when the element becomes visible.
+     * Returns a cleanup function to unobserve the element.
+     */
+    prefetchOnVisible(element: HTMLElement, id: string, options?: PrefetchOptions): () => void;
+}
+/**
+ * Checks if a value is a valid PrefetchOptions object.
+ */
+declare function isPrefetchOptions(value: unknown): value is PrefetchOptions;
+/**
+ * Set the global island loader for prefetchIsland.
+ * This is typically called during app initialization.
+ */
+declare function setGlobalLoader(loader: IslandLoader): void;
+/**
+ * Prefetch an island by ID.
+ * Uses the global loader if available.
+ *
+ * @param id - The island ID to prefetch
+ * @param options - Optional prefetch options
+ */
+declare function prefetchIsland(id: string, options?: PrefetchOptions): void;
+/**
+ * Create a prefetcher instance bound to a specific island loader.
+ *
+ * @param loader - The island loader to use for prefetching
+ * @returns Prefetcher instance with prefetchOnHover and prefetchOnVisible methods
+ *
+ * @example
+ * ```typescript
+ * const loader = createIslandLoader();
+ * const prefetcher = createPrefetcher(loader);
+ *
+ * // Prefetch on hover
+ * const cleanup = prefetcher.prefetchOnHover(element, 'counter-island');
+ *
+ * // Prefetch when visible
+ * const cleanup2 = prefetcher.prefetchOnVisible(element, 'chart-island', {
+ *   strategy: 'visible',
+ *   threshold: 0.5,
+ *   rootMargin: '100px',
+ * });
+ * ```
+ */
+declare function createPrefetcher(loader: IslandLoader): Prefetcher;
+
+export { type ActionContext, type AppInstance, type BindingConfig, type BindingManager, type Computed, type ConnectionManager, type ErrorInfo, type ErrorOverlay, type EvaluationContext, type HMRClient, type HMRClientOptions, type HMRHandler, type HMRHandlerOptions, type HydrateOptions, type IslandHydrationOptions, type IslandLoader, type IslandLoaderOptions, type LoadedIslandModule, type OptimisticManager, PREFETCH_STRATEGIES, type PendingUpdate, type PrefetchOptions, type PrefetchStrategy, type Prefetcher, type Reconnectable, type ReconnectionManager, type ReconnectionPolicy, type RenderContext, type ResolvedTheme, type RouteContext, type SSEConnection, type SSEConnectionManager, type SSEHandlers, type Signal, type StateStore, type StylePreset, type ThemeProvider, type ThemeProviderOptions, type TypedStateStore, type WebSocketConnection, type WebSocketHandlers, createApp, createBindingManager, createComputed, createConnectionManager, createEffect, createErrorOverlay, createHMRClient, createHMRHandler, createIslandLoader, createOptimisticManager, createPrefetcher, createReconnectionManager, createSSEConnection, createSSEConnectionManager, createSignal, createStateStore, createThemeProvider, createTypedStateStore, createWebSocketConnection, detectIslandsInDOM, evaluate, evaluateStyle, executeAction, hydrateApp, hydrateAppWithIslands, hydrateIsland, isPrefetchOptions, prefetchIsland, render, setGlobalLoader };