@useavalon/avalon 0.1.22 → 0.1.24

package/dist/src/components/StreamingLayout.d.ts

@@ -0,0 +1,83 @@
+import { ComponentChildren, ComponentType } from 'preact';
+import type { StreamingLayoutProps } from '../types/layout.ts';
+/**
+ * Streaming Layout Component Props
+ */
+export interface StreamingLayoutComponentProps extends StreamingLayoutProps {
+    /**
+     * Component to render when ready
+     */
+    component: ComponentType<any>;
+    /**
+     * Props to pass to the component
+     */
+    componentProps?: any;
+    /**
+     * Function to check if component is ready
+     */
+    isReady?: () => Promise<boolean>;
+    /**
+     * Timeout for loading (ms)
+     */
+    timeout?: number;
+    /**
+     * Error boundary fallback
+     */
+    onError?: (error: Error) => ComponentChildren;
+    /**
+     * Loading state callback
+     */
+    onLoadingChange?: (isLoading: boolean) => void;
+}
+/**
+ * Streaming Layout Component with Suspense-like behavior
+ */
+export declare function StreamingLayout(props: StreamingLayoutComponentProps): ComponentChildren;
+/**
+ * Suspense-like boundary for streaming components
+ */
+export interface StreamingSuspenseProps {
+    /**
+     * Fallback to show while loading
+     */
+    fallback?: ComponentChildren;
+    /**
+     * Children components
+     */
+    children: ComponentChildren;
+    /**
+     * Priority for this suspense boundary
+     */
+    priority?: 'high' | 'medium' | 'low';
+    /**
+     * Timeout for all children (ms)
+     */
+    timeout?: number;
+    /**
+     * Error boundary for failed components
+     */
+    onError?: (error: Error) => ComponentChildren;
+}
+/**
+ * Streaming Suspense Boundary Component
+ */
+export declare function StreamingSuspense(props: StreamingSuspenseProps): ComponentChildren;
+/**
+ * Higher-order component to add streaming capabilities
+ */
+export declare function withStreaming<P extends object>(WrappedComponent: ComponentType<P>, streamingOptions?: {
+    fallback?: ComponentChildren;
+    priority?: 'high' | 'medium' | 'low';
+    isReady?: () => Promise<boolean>;
+    timeout?: number;
+}): (props: P) => import("preact").JSX.Element;
+/**
+ * Hook for streaming component state
+ */
+export declare function useStreamingState(isReady?: () => Promise<boolean>, timeout?: number): {
+    retry: () => void;
+    isReady: boolean;
+    isLoading: boolean;
+    error: Error | null;
+    hasTimedOut: boolean;
+};

package/dist/src/components/StreamingLayout.js

@@ -26,4 +26,4 @@ import{Component as e}from"preact";import{useState as t,useEffect as n,useRef as
 					0% { background-position: 200% 0; }
 					100% { background-position: -200% 0; }
 				}
-			`})]})}export function StreamingSuspense(e){let{fallback:o,children:c,priority:u=`medium`,timeout:d=5e3,onError:f}=e,[p,m]=t(!0),[h,g]=t(null),[_,v]=t(!1),y=r(),b=r(!0);n(()=>()=>{b.current=!1},[]),n(()=>(d>0&&(y.current=setTimeout(()=>{b.current&&p&&(v(!0),m(!1))},d)),()=>{y.current&&clearTimeout(y.current)}),[d,p]);let x=e=>{g(e),m(!1),y.current&&clearTimeout(y.current)};return h?f?f(h):i(`div`,{class:`streaming-suspense-error`,"data-priority":u,children:[i(`p`,{children:[`Suspense boundary error: `,h.message]}),a(`button`,{onClick:()=>{g(null),m(!0),v(!1)},children:`Retry`})]}):_?a(`div`,{class:`streaming-suspense-timeout`,"data-priority":u,children:o||i(`div`,{class:`suspense-timeout-message`,children:[a(`p`,{children:`Suspense boundary timed out`}),a(`button`,{onClick:()=>{v(!1),m(!0)},children:`Retry`})]})}):p?a(`div`,{class:`streaming-suspense-loading`,"data-priority":u,children:o||a(s,{priority:u})}):a(`div`,{class:`streaming-suspense-ready`,"data-priority":u,children:a(l,{onError:x,children:c})})}class l extends e{constructor(e){super(e),this.state={hasError:!1}}static getDerivedStateFromError(e){return{hasError:!0,error:e}}componentDidCatch(e,t){console.error(`StreamingErrorBoundary caught an error:`,e,t),this.props.onError?.(e)}render(){return this.state.hasError?i(`div`,{class:`streaming-error-boundary`,children:[a(`p`,{children:`Something went wrong in streaming component.`}),a(`button`,{onClick:()=>this.setState({hasError:!1,error:void 0}),children:`Retry`})]}):this.props.children}}export function withStreaming(e,t={}){return function(n){return a(StreamingLayout,{component:e,componentProps:n,priority:`medium`,...t})}}export function useStreamingState(e,r=5e3){let[i,a]=t({isReady:!1,isLoading:!0,error:null,hasTimedOut:!1});n(()=>{if(!e){a(e=>({...e,isReady:!0,isLoading:!1}));return}let t=!1,n;return(async()=>{try{r>0&&(n=setTimeout(()=>{t||a(e=>({...e,hasTimedOut:!0,isLoading:!1}))},r));let i=await e();if(t)return;n&&clearTimeout(n),a(e=>({...e,isReady:i,isLoading:!1,hasTimedOut:!1}))}catch(e){if(t)return;n&&clearTimeout(n),a(t=>({...t,error:e,isLoading:!1}))}})(),()=>{t=!0,n&&clearTimeout(n)}},[e,r]);let o=()=>{a({isReady:!1,isLoading:!0,error:null,hasTimedOut:!1})};return{...i,retry:o}}
+			`})]})}export function StreamingSuspense(e){let{fallback:o,children:c,priority:u=`medium`,timeout:d=5e3,onError:f}=e,[p,m]=t(!0),[h,g]=t(null),[_,v]=t(!1),y=r(),b=r(!0);n(()=>()=>{b.current=!1},[]),n(()=>(d>0&&(y.current=setTimeout(()=>{b.current&&p&&(v(!0),m(!1))},d)),()=>{y.current&&clearTimeout(y.current)}),[d,p]);let x=e=>{g(e),m(!1),y.current&&clearTimeout(y.current)};return h?f?f(h):i(`div`,{class:`streaming-suspense-error`,"data-priority":u,children:[i(`p`,{children:[`Suspense boundary error: `,h.message]}),a(`button`,{onClick:()=>{g(null),m(!0),v(!1)},children:`Retry`})]}):_?a(`div`,{class:`streaming-suspense-timeout`,"data-priority":u,children:o||i(`div`,{class:`suspense-timeout-message`,children:[a(`p`,{children:`Suspense boundary timed out`}),a(`button`,{onClick:()=>{v(!1),m(!0)},children:`Retry`})]})}):p?a(`div`,{class:`streaming-suspense-loading`,"data-priority":u,children:o||a(s,{priority:u})}):a(`div`,{class:`streaming-suspense-ready`,"data-priority":u,children:a(l,{onError:x,children:c})})}class l extends e{constructor(e){super(e),this.state={hasError:!1}}static getDerivedStateFromError(e){return{hasError:!0,error:e}}componentDidCatch(e,t){console.error(`StreamingErrorBoundary caught an error:`,e,t),this.props.onError?.(e)}render(){return this.state.hasError?i(`div`,{class:`streaming-error-boundary`,children:[a(`p`,{children:`Something went wrong in streaming component.`}),a(`button`,{onClick:()=>this.setState({hasError:!1,error:void 0}),children:`Retry`})]}):this.props.children}}export function withStreaming(e,t={}){return function(n){return a(StreamingLayout,{component:e,componentProps:n,priority:`medium`,...t,children:null})}}export function useStreamingState(e,r=5e3){let[i,a]=t({isReady:!1,isLoading:!0,error:null,hasTimedOut:!1});n(()=>{if(!e){a(e=>({...e,isReady:!0,isLoading:!1}));return}let t=!1,n;return(async()=>{try{r>0&&(n=setTimeout(()=>{t||a(e=>({...e,hasTimedOut:!0,isLoading:!1}))},r));let i=await e();if(t)return;n&&clearTimeout(n),a(e=>({...e,isReady:i,isLoading:!1,hasTimedOut:!1}))}catch(e){if(t)return;n&&clearTimeout(n),a(t=>({...t,error:e,isLoading:!1}))}})(),()=>{t=!0,n&&clearTimeout(n)}},[e,r]);let o=()=>{a({isReady:!1,isLoading:!0,error:null,hasTimedOut:!1})};return{...i,retry:o}}

package/dist/src/core/components/component-analyzer.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Component Analyzer - High-level interface for component detection system
+ *
+ * This module provides a convenient interface for analyzing components
+ * and making hydration decisions in the SSR system.
+ */
+import { type ComponentAnalysis, type DetectionResult, type ComponentMetadata } from './component-detection.ts';
+export interface AnalyzerOptions {
+    forceSSROnly?: boolean;
+    detectScripts?: boolean;
+    suppressWarnings?: boolean;
+    logDecisions?: boolean;
+}
+export interface AnalysisReport {
+    metadata: ComponentMetadata;
+    decision: DetectionResult;
+    analysis: ComponentAnalysis;
+}
+/**
+ * Analyzes a component file and returns comprehensive analysis report
+ */
+export declare function analyzeComponentFile(filePath: string, options?: AnalyzerOptions): Promise<AnalysisReport>;
+/**
+ * Analyzes component content directly (for in-memory components)
+ */
+export declare function analyzeComponentContent(filePath: string, content: string, options?: AnalyzerOptions): AnalysisReport;
+/**
+ * Batch analyze multiple components
+ */
+export declare function analyzeComponents(filePaths: string[], options?: AnalyzerOptions): Promise<Map<string, AnalysisReport>>;
+/**
+ * Quick check if a component should be hydrated
+ */
+export declare function shouldHydrate(filePath: string, options?: AnalyzerOptions): Promise<boolean>;
+/**
+ * Get component framework type
+ */
+export declare function getComponentFramework(filePath: string): Promise<ComponentAnalysis['framework']>;
+/**
+ * Generate summary statistics for a batch of components
+ */
+export declare function generateAnalysisSummary(reports: Map<string, AnalysisReport>): {
+    total: number;
+    byFramework: Record<string, number>;
+    byStrategy: Record<string, number>;
+    withWarnings: number;
+};
+export type { ComponentAnalysis, DetectionResult, ComponentMetadata } from './component-detection.ts';

package/dist/src/core/components/component-detection.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Component Detection System
+ *
+ * This module provides utilities to analyze components and determine their
+ * hydration requirements based on script content and framework patterns.
+ */
+export interface ComponentAnalysis {
+    hasScript: boolean;
+    hasHydrateFunction: boolean;
+    framework: 'vue' | 'svelte' | 'solid' | 'preact' | 'react' | 'lit' | 'qwik' | 'unknown';
+    recommendedStrategy: 'hydrate' | 'ssr-only';
+}
+export interface DetectionResult {
+    shouldHydrate: boolean;
+    reason: string;
+    warnings?: string[];
+}
+export interface ComponentMetadata {
+    path: string;
+    framework: 'vue' | 'svelte' | 'solid' | 'preact' | 'react' | 'lit' | 'qwik';
+    hasScript: boolean;
+    hasHydrateFunction: boolean;
+    renderStrategy: 'hydrate' | 'ssr-only';
+    detectionConfidence: 'high' | 'medium' | 'low';
+}
+/**
+ * Detects the framework type based on file extension and content
+ */
+export declare function detectFramework(filePath: string, content: string): ComponentAnalysis['framework'];
+/**
+ * Detects if a component has script sections
+ */
+export declare function hasScriptSection(content: string, framework: ComponentAnalysis['framework']): boolean;
+/**
+ * Detects if a component has hydration functions
+ */
+export declare function hasHydrateFunction(content: string, framework: ComponentAnalysis['framework']): boolean;
+/**
+ * Extracts script content from Vue components
+ */
+export declare function extractVueScript(content: string): string;
+/**
+ * Extracts script content from Svelte components
+ */
+export declare function extractSvelteScript(content: string): string;
+/**
+ * Extracts script content from Solid components (JSX)
+ */
+export declare function extractSolidScript(content: string): string;
+/**
+ * Extracts script content from Preact components (JSX)
+ */
+export declare function extractPreactScript(content: string): string;
+/**
+ * Extracts script content from React components (JSX)
+ */
+export declare function extractReactScript(content: string): string;
+/**
+ * Analyzes a component and returns detailed analysis
+ */
+export declare function analyzeComponent(filePath: string, content: string): ComponentAnalysis;
+/**
+ * Determines if a component should be hydrated based on analysis
+ */
+export declare function shouldHydrateComponent(analysis: ComponentAnalysis, options?: {
+    forceSSROnly?: boolean;
+    detectScripts?: boolean;
+}): DetectionResult;
+/**
+ * Creates component metadata with confidence scoring
+ */
+export declare function createComponentMetadata(filePath: string, content: string, analysis: ComponentAnalysis): ComponentMetadata;

package/dist/src/core/components/enhanced-framework-detector.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Enhanced Framework Detection System
+ *
+ * This module provides advanced framework detection with multi-evidence analysis,
+ * confidence scoring, and JSX import source parsing to accurately identify
+ * component frameworks and prevent cross-framework conflicts.
+ */
+export interface FrameworkDetectionResult {
+    framework: 'preact' | 'solid' | 'vue' | 'svelte' | 'react' | 'lit' | 'qwik' | 'unknown';
+    confidence: 'high' | 'medium' | 'low';
+    evidence: string[];
+    warnings: string[];
+}
+export interface DetectionCriteria {
+    fileExtension: string;
+    jsxImportSource?: string;
+    imports: string[];
+    content: string;
+}
+export interface FrameworkConfig {
+    name: string;
+    fileExtensions: string[];
+    jsxImportSources: string[];
+    ssrModules: string[];
+    hydrationModules: string[];
+    detectionPatterns: {
+        imports: RegExp[];
+        content: RegExp[];
+        jsxPragmas: string[];
+    };
+}
+/**
+ * Enhanced Framework Detector with multi-evidence analysis
+ */
+export declare class EnhancedFrameworkDetector {
+    private readonly frameworkRegistry;
+    constructor(frameworkConfigs?: Record<string, FrameworkConfig>);
+    /**
+     * Detects framework with multi-evidence analysis
+     */
+    detectFramework(filePath: string, content: string): FrameworkDetectionResult;
+    /**
+     * Extracts detection criteria from file path and content
+     */
+    private extractDetectionCriteria;
+    /**
+     * Calculates framework score based on multiple evidence points
+     */
+    private calculateFrameworkScore;
+    /**
+     * Parses JSX import source from content
+     */
+    private parseJSXImportSource;
+    /**
+     * Extracts import statements from content
+     */
+    private extractImportStatements;
+    /**
+     * Gets file extension from path, handling framework-specific naming conventions
+     */
+    private getFileExtension;
+    /**
+     * Gets default framework configurations
+     */
+    private getDefaultFrameworkConfigs;
+    /**
+     * Adds or updates a framework configuration
+     */
+    addFrameworkConfig(name: string, config: FrameworkConfig): void;
+    /**
+     * Gets all registered framework configurations
+     */
+    getFrameworkConfigs(): Map<string, FrameworkConfig>;
+    /**
+     * Validates framework configuration completeness
+     */
+    validateFrameworkConfig(config: FrameworkConfig): string[];
+}

package/dist/src/core/components/framework-registry.d.ts

@@ -0,0 +1,114 @@
+/**
+ * Framework Registry and Configuration System
+ *
+ * This module provides a centralized registry for framework configurations,
+ * validation utilities, and management of framework-specific detection patterns.
+ */
+import type { FrameworkConfig } from './enhanced-framework-detector.ts';
+export interface FrameworkRegistryConfig {
+    enableValidation: boolean;
+    allowCustomFrameworks: boolean;
+    defaultFramework: string;
+}
+export interface FrameworkValidationResult {
+    isValid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+/**
+ * Centralized framework registry with validation and management
+ */
+export declare class FrameworkRegistry {
+    private readonly frameworks;
+    private readonly config;
+    constructor(config?: Partial<FrameworkRegistryConfig>);
+    /**
+     * Registers a new framework configuration
+     */
+    registerFramework(name: string, config: FrameworkConfig): FrameworkValidationResult;
+    /**
+     * Gets a framework configuration by name
+     */
+    getFramework(name: string): FrameworkConfig | undefined;
+    /**
+     * Gets all registered frameworks
+     */
+    getAllFrameworks(): Map<string, FrameworkConfig>;
+    /**
+     * Gets framework names that support a specific file extension
+     */
+    getFrameworksByExtension(extension: string): string[];
+    /**
+     * Gets frameworks that use a specific JSX import source
+     */
+    getFrameworksByJSXImportSource(importSource: string): string[];
+    /**
+     * Removes a framework from the registry
+     */
+    unregisterFramework(name: string): boolean;
+    /**
+     * Updates an existing framework configuration
+     */
+    updateFramework(name: string, updates: Partial<FrameworkConfig>): FrameworkValidationResult;
+    /**
+     * Validates a framework configuration
+     */
+    validateFrameworkConfig(config: FrameworkConfig): FrameworkValidationResult;
+    /** Validate required top-level fields on a framework config */
+    private validateRequiredFields;
+    /** Validate the detectionPatterns sub-object */
+    private validateDetectionPatterns;
+    /**
+     * Checks for potential conflicts with other registered frameworks
+     */
+    private validateCrossFrameworkConflicts;
+    /**
+     * Checks if a framework is a default framework
+     */
+    private isDefaultFramework;
+    /**
+     * Initializes the registry with default framework configurations
+     */
+    private initializeDefaultFrameworks;
+    /**
+     * Gets default framework configurations
+     */
+    private getDefaultFrameworkConfigs;
+    /**
+     * Exports the current registry configuration
+     */
+    exportConfig(): Record<string, FrameworkConfig>;
+    /**
+     * Imports a registry configuration
+     */
+    importConfig(config: Record<string, FrameworkConfig>): FrameworkValidationResult[];
+    /**
+     * Resets the registry to default frameworks only
+     */
+    reset(): void;
+    /**
+     * Gets registry statistics
+     */
+    getStats(): {
+        totalFrameworks: number;
+        defaultFrameworks: number;
+        customFrameworks: number;
+        supportedExtensions: string[];
+    };
+}
+/**
+ * Default framework registry instance
+ */
+export declare const defaultFrameworkRegistry: FrameworkRegistry;
+/**
+ * Utility function to create a framework configuration
+ */
+export declare function createFrameworkConfig(name: string, options: {
+    fileExtensions: string[];
+    jsxImportSources?: string[];
+    ssrModules: string[];
+    hydrationModules: string[];
+    importPatterns: (string | RegExp)[];
+    contentPatterns?: (string | RegExp)[];
+    jsxPragmas?: string[];
+}): FrameworkConfig;

package/dist/src/core/content/mdx-processor.d.ts

@@ -0,0 +1,14 @@
+import type { RoutePageModule } from '../../schemas/routing.ts';
+/**
+ * Server-side MDX processor for handling MDX files in the routing system
+ */
+export declare class MDXProcessor {
+    /**
+     * Process an MDX file and return a valid page module
+     */
+    processMDXFile(filePath: string): Promise<RoutePageModule>;
+    /**
+     * Check if a file is an MDX file
+     */
+    static isMDXFile(filePath: string): boolean;
+}

package/dist/src/core/integrations/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Integration system exports
+ * Central export point for all integration-related functionality
+ */
+export { IntegrationRegistry, registry } from "./registry.ts";
+export { loadIntegration, detectAndLoadIntegration, detectFrameworkFromPath, detectFrameworkFromContent, preloadIntegrations, getLoadedIntegrations, clearIntegrationCache, isIntegrationLoaded, } from "./loader.ts";

package/dist/src/core/integrations/loader.d.ts

@@ -0,0 +1,35 @@
+import type { Integration } from "@useavalon/core";
+/**
+ * Load an integration by name, using cache if available
+ */
+export declare function loadIntegration(framework: string): Promise<Integration>;
+/**
+ * Detect framework from file path and load the appropriate integration
+ */
+export declare function detectAndLoadIntegration(src: string): Promise<Integration>;
+/**
+ * Detect framework from file path based on extension and naming conventions
+ */
+export declare function detectFrameworkFromPath(src: string): string;
+/**
+ * Detect framework from file content by analyzing imports and patterns
+ */
+export declare function detectFrameworkFromContent(src: string, content?: string): string;
+/**
+ * Preload integrations for the given frameworks
+ * Useful for warming up the cache during build or startup
+ */
+export declare function preloadIntegrations(frameworks: string[]): Promise<void>;
+/**
+ * Get all currently loaded integrations
+ */
+export declare function getLoadedIntegrations(): Integration[];
+/**
+ * Clear the integration cache
+ * Useful for testing or hot module replacement
+ */
+export declare function clearIntegrationCache(): void;
+/**
+ * Check if an integration is loaded in cache
+ */
+export declare function isIntegrationLoaded(framework: string): boolean;

package/dist/src/core/integrations/registry.d.ts

@@ -0,0 +1,51 @@
+import type { Integration } from "@useavalon/core";
+/**
+ * IntegrationRegistry manages loaded framework integrations.
+ * It provides registration, retrieval, and dynamic loading of integrations.
+ */
+export declare class IntegrationRegistry {
+    private readonly integrations;
+    private readonly loadingPromises;
+    /**
+     * Register an integration instance
+     */
+    register(integration: Integration): void;
+    /**
+     * Get a registered integration by name
+     */
+    get(name: string): Integration | undefined;
+    /**
+     * Check if an integration is registered
+     */
+    has(name: string): boolean;
+    /**
+     * Dynamically load an integration by name
+     * Returns cached integration if already loaded
+     */
+    load(name: string): Promise<Integration>;
+    private loadIntegration;
+    /**
+     * Get all registered integrations
+     */
+    getAll(): Integration[];
+    /**
+     * Get all registered integration names
+     */
+    getAllNames(): string[];
+    /**
+     * Unregister an integration
+     */
+    unregister(name: string): boolean;
+    /**
+     * Clear all registered integrations
+     */
+    clear(): void;
+    /**
+     * Get the count of registered integrations
+     */
+    get size(): number;
+}
+declare global {
+    var __avalonIntegrationRegistry: IntegrationRegistry | undefined;
+}
+export declare const registry: IntegrationRegistry;

package/dist/src/core/islands/island-persistence.d.ts

@@ -0,0 +1,74 @@
+import type { IslandState } from '../../schemas/layout.ts';
+import type { IIslandPersistence } from '../../types/layout.ts';
+/**
+ * IslandPersistence class for state management across navigation
+ *
+ * Handles saving, loading, and clearing island state using browser storage
+ * with support for both sessionStorage and localStorage persistence strategies.
+ */
+export declare class IslandPersistence implements IIslandPersistence {
+    private storageType;
+    private keyPrefix;
+    private storage;
+    constructor(options?: {
+        storageType?: 'session' | 'local';
+        keyPrefix?: string;
+    });
+    /**
+     * Save island state to browser storage
+     */
+    saveState(id: string, state: IslandState): void;
+    /**
+     * Load island state from browser storage
+     */
+    loadState(id: string): IslandState | null;
+    /**
+     * Clear island state from browser storage
+     */
+    clearState(id: string): void;
+    /**
+     * Check if state exists for an island
+     */
+    hasState(id: string): boolean;
+    /**
+     * Get all stored island IDs
+     */
+    getStoredIds(): string[];
+    /**
+     * Clear all stored states
+     */
+    clearAllStates(): void;
+    /**
+     * Get the storage key for an island ID
+     */
+    private getStorageKey;
+    /**
+     * Get current storage configuration
+     */
+    getConfig(): {
+        storageType: string;
+        keyPrefix: string;
+        available: boolean;
+    };
+    /**
+     * Get storage usage statistics
+     */
+    getStorageStats(): {
+        totalKeys: number;
+        islandKeys: number;
+        estimatedSize: number;
+    };
+    /**
+     * JSON.stringify replacer function to handle special types
+     */
+    private replacer;
+    /**
+     * JSON.parse reviver function to restore special types
+     */
+    private reviver;
+}
+/**
+ * Default island persistence instance
+ * Uses sessionStorage by default for better privacy and performance
+ */
+export declare const defaultIslandPersistence: IslandPersistence;

package/dist/src/core/islands/island-state-serializer.d.ts

@@ -0,0 +1,53 @@
+import type { IslandState } from '../../schemas/layout.ts';
+/**
+ * Island State Serializer
+ *
+ * Handles serialization and deserialization of island state for browser storage.
+ * Supports complex data types including Dates, RegExp, and circular references.
+ */
+export declare class IslandStateSerializer {
+    /**
+     * Serialize island state to JSON string
+     */
+    static serialize(state: IslandState): string;
+    /**
+     * Deserialize JSON string to island state
+     */
+    static deserialize(serializedState: string): IslandState;
+    /**
+     * Transform state for serialization, handling special types
+     */
+    private static transformForSerialization;
+    /**
+     * JSON.parse reviver function to restore special types
+     */
+    private static reviver;
+    /**
+     * Validate that state can be safely serialized
+     */
+    static validate(state: IslandState): {
+        valid: boolean;
+        errors: string[];
+    };
+    /**
+     * Get size information for serialized state
+     */
+    static getSize(state: IslandState): {
+        bytes: number;
+        kilobytes: number;
+        megabytes: number;
+        readable: string;
+    };
+    /**
+     * Deep clone state object (useful for preventing mutations)
+     */
+    static clone(state: IslandState): IslandState;
+    /**
+     * Compare two states for equality
+     */
+    static equals(state1: IslandState, state2: IslandState): boolean;
+    /**
+     * Sanitize state by removing non-serializable values
+     */
+    static sanitize(state: IslandState): IslandState;
+}

package/dist/src/core/islands/persistent-island-context.d.ts

@@ -0,0 +1,36 @@
+import type { ComponentChildren } from 'preact';
+import type { IslandState } from '../../schemas/layout.ts';
+import { defaultIslandPersistence } from './island-persistence.ts';
+/**
+ * Explicit interface for persistent island context
+ * (Zod z.any() inference for function types is unreliable)
+ */
+export interface PersistentIslandContextType {
+    saveState: (state: IslandState) => void;
+    loadState: () => IslandState | null;
+    clearState: () => void;
+}
+/**
+ * Context for persistent island state operations
+ *
+ * Provides save, load, and clear operations for island state management
+ * across navigation and browser sessions.
+ */
+export declare const PersistentIslandContextProvider: import("preact").Context<PersistentIslandContextType>;
+/**
+ * Create a persistent island context for a specific island ID
+ */
+export declare function createPersistentIslandContext(persistentId: string, persistence?: import("./island-persistence.ts").IslandPersistence): PersistentIslandContextType;
+/**
+ * Hook to use persistent island context
+ * Must be used within a PersistentIsland component
+ */
+export declare function usePersistentIslandContext(): PersistentIslandContextType;
+/**
+ * Provider component for persistent island context
+ */
+export declare function PersistentIslandProvider({ persistentId, children, persistence, }: Readonly<{
+    persistentId: string;
+    children: ComponentChildren;
+    persistence?: typeof defaultIslandPersistence;
+}>): import("preact").JSX.Element;