@useavalon/avalon 0.1.23 → 0.1.24

package/dist/src/client/framework-adapter.d.ts

@@ -0,0 +1,225 @@
+/**
+ * Framework HMR Adapter Interface
+ *
+ * Defines the contract for framework-specific HMR adapters.
+ * Each supported framework (React, Preact, Vue, Svelte, Solid, Lit) implements this interface
+ * to provide framework-specific hot module replacement behavior.
+ *
+ * Requirements: 2.1-2.7
+ */
+/**
+ * State snapshot for preserving component state across HMR updates
+ */
+export interface StateSnapshot {
+    /**
+     * Framework name (e.g., 'react', 'vue', 'svelte')
+     */
+    framework: string;
+    /**
+     * Timestamp when state was captured
+     */
+    timestamp: number;
+    /**
+     * Framework-specific state data
+     * - React: hooks state, context values
+     * - Vue: reactive data, computed properties
+     * - Svelte: component state, store subscriptions
+     * - Solid: signal values, reactive computations
+     * - Lit: element properties, attributes
+     */
+    data: Record<string, unknown>;
+    /**
+     * DOM state (scroll, focus, form values)
+     */
+    dom?: {
+        scrollPosition?: {
+            x: number;
+            y: number;
+        };
+        focusedElement?: string;
+        formValues?: Record<string, unknown>;
+    };
+}
+/**
+ * Framework-specific HMR adapter interface
+ *
+ * Each framework adapter implements this interface to provide:
+ * - Component identification (canHandle)
+ * - State preservation (preserveState, restoreState)
+ * - Hot updates (update)
+ * - Error handling (handleError)
+ */
+export interface FrameworkHMRAdapter {
+    /**
+     * Framework name (e.g., 'react', 'preact', 'vue', 'svelte', 'solid', 'lit')
+     */
+    readonly name: string;
+    /**
+     * Check if this adapter can handle HMR for a given component
+     *
+     * @param component - The component to check
+     * @returns true if this adapter can handle the component
+     *
+     * Example:
+     * - React: Check for React.Component or function with hooks
+     * - Vue: Check for Vue component options object
+     * - Svelte: Check for Svelte component class
+     */
+    canHandle(component: unknown): boolean;
+    /**
+     * Preserve component state before HMR update
+     *
+     * Captures the current state of the component so it can be restored after update.
+     * Returns null if state preservation is not supported or fails.
+     *
+     * @param island - The island DOM element containing the component
+     * @returns State snapshot or null if preservation fails
+     *
+     * Requirements: 1.3, 4.1-4.5
+     */
+    preserveState(island: HTMLElement): StateSnapshot | null;
+    /**
+     * Update the component with a new module
+     *
+     * Performs the actual hot module replacement:
+     * - Unmounts old component (if needed)
+     * - Mounts new component with same props
+     * - Integrates with framework-specific HMR APIs
+     *
+     * @param island - The island DOM element
+     * @param newComponent - The new component class/function
+     * @param props - Component props
+     *
+     * Requirements: 2.1-2.6
+     */
+    update(island: HTMLElement, newComponent: unknown, props: Record<string, unknown>): Promise<void>;
+    /**
+     * Restore component state after HMR update
+     *
+     * Applies the previously captured state to the updated component.
+     * Should handle cases where state structure has changed.
+     *
+     * @param island - The island DOM element
+     * @param state - Previously captured state snapshot
+     *
+     * Requirements: 1.3, 4.1-4.5
+     */
+    restoreState(island: HTMLElement, state: StateSnapshot): void;
+    /**
+     * Handle errors during HMR update
+     *
+     * Provides framework-specific error handling:
+     * - Display error overlay
+     * - Preserve SSR HTML as fallback
+     * - Log diagnostic information
+     *
+     * @param island - The island DOM element
+     * @param error - The error that occurred
+     *
+     * Requirements: 1.4, 7.1-7.5
+     */
+    handleError(island: HTMLElement, error: Error): void;
+}
+/**
+ * Adapter registry for managing framework-specific HMR adapters
+ */
+export declare class AdapterRegistry {
+    private adapters;
+    /**
+     * Register a framework-specific HMR adapter
+     *
+     * @param framework - Framework name (case-insensitive)
+     * @param adapter - The adapter implementation
+     * @throws Error if adapter is invalid or already registered
+     *
+     * Requirements: 2.1-2.7
+     */
+    register(framework: string, adapter: FrameworkHMRAdapter): void;
+    /**
+     * Get an adapter for a specific framework
+     *
+     * @param framework - Framework name (case-insensitive)
+     * @returns The adapter or undefined if not found
+     */
+    get(framework: string): FrameworkHMRAdapter | undefined;
+    /**
+     * Check if an adapter is registered for a framework
+     *
+     * @param framework - Framework name (case-insensitive)
+     * @returns true if adapter is registered
+     */
+    has(framework: string): boolean;
+    /**
+     * Get all registered framework names
+     *
+     * @returns Array of registered framework names
+     */
+    getRegisteredFrameworks(): string[];
+    /**
+     * Find an adapter that can handle a specific component
+     *
+     * Iterates through all registered adapters and returns the first one
+     * that can handle the component.
+     *
+     * @param component - The component to check
+     * @returns The adapter that can handle the component, or undefined
+     */
+    findAdapter(component: unknown): FrameworkHMRAdapter | undefined;
+    /**
+     * Unregister an adapter
+     *
+     * @param framework - Framework name (case-insensitive)
+     * @returns true if adapter was removed, false if not found
+     */
+    unregister(framework: string): boolean;
+    /**
+     * Clear all registered adapters
+     */
+    clear(): void;
+    /**
+     * Get the number of registered adapters
+     */
+    get size(): number;
+}
+/**
+ * Base adapter class with common functionality
+ *
+ * Framework-specific adapters can extend this class to inherit common behavior
+ * and only override framework-specific methods.
+ */
+export declare abstract class BaseFrameworkAdapter implements FrameworkHMRAdapter {
+    abstract readonly name: string;
+    abstract canHandle(component: unknown): boolean;
+    abstract update(island: HTMLElement, newComponent: unknown, props: Record<string, unknown>): Promise<void>;
+    /**
+     * Default state preservation implementation
+     * Captures DOM state (scroll, focus, form values)
+     *
+     * Subclasses should override to add framework-specific state
+     */
+    preserveState(island: HTMLElement): StateSnapshot | null;
+    /**
+     * Default state restoration implementation
+     * Restores DOM state (scroll, focus, form values)
+     *
+     * Subclasses should override to add framework-specific state restoration
+     */
+    restoreState(island: HTMLElement, state: StateSnapshot): void;
+    /**
+     * Default error handling implementation
+     * Shows error indicator and preserves SSR HTML
+     */
+    handleError(island: HTMLElement, error: Error): void;
+    /**
+     * Capture DOM state (scroll, focus, form values)
+     */
+    protected captureDOMState(island: HTMLElement): StateSnapshot['dom'];
+    /**
+     * Restore DOM state (scroll, focus, form values)
+     */
+    protected restoreDOMState(island: HTMLElement, dom: StateSnapshot['dom']): void;
+    /**
+     * Get a CSS selector for an element
+     */
+    protected getElementSelector(element: HTMLElement): string | null;
+}

package/dist/src/client/hmr-coordinator.d.ts

@@ -0,0 +1,88 @@
+/**
+ * HMR Coordinator
+ *
+ * Central orchestrator for all HMR operations in Avalon.
+ * Integrates with Vite's HMR API and coordinates island updates across frameworks.
+ */
+import { type FrameworkHMRAdapter, AdapterRegistry } from './framework-adapter.ts';
+/**
+ * Vite HMR types (defined locally to avoid import issues)
+ */
+export interface HMRPayload {
+    type: string;
+    updates?: Update[];
+    timestamp?: number;
+}
+export interface ErrorPayload {
+    type: 'error';
+    err: {
+        message: string;
+        stack: string;
+        id?: string;
+        frame?: string;
+        plugin?: string;
+        pluginCode?: string;
+        loc?: {
+            file?: string;
+            line: number;
+            column: number;
+        };
+    };
+}
+export interface Update {
+    type: 'js-update' | 'css-update';
+    path: string;
+    acceptedPath: string;
+    timestamp: number;
+    explicitImportRequired?: boolean;
+}
+/**
+ * HMR update payload from Vite
+ */
+export interface HMRUpdatePayload extends HMRPayload {
+    type: 'update' | 'full-reload' | 'prune' | 'error';
+    updates?: ModuleUpdate[];
+    timestamp?: number;
+    err?: ErrorPayload;
+}
+/**
+ * Individual module update information
+ */
+export interface ModuleUpdate {
+    type: 'js-update' | 'css-update';
+    path: string;
+    acceptedPath: string;
+    timestamp: number;
+}
+export type { FrameworkHMRAdapter, StateSnapshot } from './framework-adapter.ts';
+/**
+ * HMR Coordinator class
+ * Manages HMR lifecycle and coordinates updates across islands
+ */
+export declare class HMRCoordinator {
+    private readonly registry;
+    private readonly stateSnapshots;
+    private readonly updateQueue;
+    private isProcessing;
+    /**
+     * Initialize the HMR coordinator
+     * Sets up Vite HMR listeners and accepts updates
+     */
+    initialize(): void;
+    registerAdapter(framework: string, adapter: FrameworkHMRAdapter): void;
+    getRegistry(): AdapterRegistry;
+    handleUpdate(payload: HMRUpdatePayload): Promise<void>;
+    private processCSSUpdates;
+    private queueJSUpdates;
+    private processUpdateQueue;
+    findAffectedIslands(modulePath: string): HTMLElement[];
+    updateIsland(island: HTMLElement): Promise<void>;
+    private resolveComponent;
+    private handleBeforeFullReload;
+    private handleError;
+    private normalizePath;
+    private isIslandModule;
+    private getIslandId;
+}
+export declare function getHMRCoordinator(): HMRCoordinator;
+export declare function initializeHMR(): void;

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

@@ -0,0 +1,61 @@
+/**
+ * Image Component for Avalon
+ *
+ * A responsive image component that works with vite-imagetools to provide
+ * optimized images with automatic srcset generation.
+ *
+ * Usage:
+ * ```tsx
+ * import { Image } from '@useavalon/avalon/client';
+ * import heroSrc from './hero.jpg?w=400;800;1200&format=webp&as=srcset';
+ *
+ * <Image
+ *   src={heroSrc}
+ *   alt="Hero image"
+ *   sizes="(max-width: 600px) 400px, (max-width: 1200px) 800px, 1200px"
+ * />
+ * ```
+ *
+ * Or with the simpler single-image approach:
+ * ```tsx
+ * import heroSrc from './hero.jpg?w=800&format=webp';
+ *
+ * <Image src={heroSrc} alt="Hero image" width={800} height={600} />
+ * ```
+ */
+import type { JSX } from "preact";
+export interface ImageProps {
+    /**
+     * Image source - can be:
+     * - A string URL (single image)
+     * - A srcset string from ?as=srcset (contains " Xw" width descriptors)
+     * - An object with src/srcset/width/height from vite-imagetools
+     */
+    src: string | {
+        src: string;
+        srcset?: string;
+        width?: number;
+        height?: number;
+    };
+    /** Alt text for accessibility (required) */
+    alt: string;
+    /** Sizes attribute for responsive images (required when using srcset) */
+    sizes?: string;
+    /** Loading strategy */
+    loading?: "lazy" | "eager";
+    /** Decoding hint */
+    decoding?: "async" | "sync" | "auto";
+    /** Optional width (auto-detected from srcset if available) */
+    width?: number | string;
+    /** Optional height (auto-detected from srcset if available) */
+    height?: number | string;
+    /** CSS class name */
+    className?: string;
+    /** Inline styles */
+    style?: string | Record<string, string | number>;
+}
+/**
+ * Responsive image component with built-in optimization support
+ */
+export declare function Image({ src, alt, sizes, loading, decoding, width, height, className, style, }: Readonly<ImageProps>): JSX.Element;
+export default Image;

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

@@ -0,0 +1,37 @@
+import { Component, ComponentChildren, ComponentType } from 'preact';
+import type { LayoutErrorInfo } from '../types/layout.ts';
+export interface IslandErrorBoundaryProps {
+    children: ComponentChildren;
+    islandId: string;
+    onError?: (error: Error, errorInfo: LayoutErrorInfo) => void;
+    fallback?: (error: Error, islandId: string) => ComponentChildren;
+    isolateError?: boolean;
+}
+export interface IslandErrorBoundaryState {
+    hasError: boolean;
+    error: Error | null;
+    errorInfo: LayoutErrorInfo | null;
+}
+/**
+ * Specialized error boundary for island components
+ * Provides error isolation to prevent island errors from affecting the main layout
+ */
+export declare class IslandErrorBoundary extends Component<IslandErrorBoundaryProps, IslandErrorBoundaryState> {
+    constructor(props: IslandErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): Partial<IslandErrorBoundaryState>;
+    componentDidCatch(error: Error, errorInfo: {
+        componentStack?: string;
+    }): void;
+    private handleRemoveIsland;
+    private handleReloadIsland;
+    private renderFallback;
+    render(): ComponentChildren;
+}
+/**
+ * Higher-order component to wrap islands with error boundaries
+ */
+export declare function withIslandErrorBoundary<P extends object>(WrappedComponent: ComponentType<P>, islandId: string, options?: {
+    fallback?: (error: Error, islandId: string) => ComponentChildren;
+    isolateError?: boolean;
+    onError?: (error: Error, errorInfo: LayoutErrorInfo) => void;
+}): (props: P) => import("preact").JSX.Element;

package/dist/src/components/IslandErrorBoundary.js

@@ -1 +1 @@
-import{Component as e}from"preact";import{jsx as t,jsxs as n}from"preact/jsx-runtime";export class IslandErrorBoundary extends e{constructor(e){super(e),this.state={hasError:!1,error:null,errorInfo:null}}static getDerivedStateFromError(e){return{hasError:!0,error:e}}componentDidCatch(e,t){let n={layoutPath:`island:${this.props.islandId}`,errorType:`island`,timestamp:Date.now(),componentStack:t.componentStack,errorBoundary:`IslandErrorBoundary`};if(this.setState({errorInfo:n}),this.props.onError&&this.props.onError(e,n),typeof Deno<`u`&&Deno.env.get(`NODE_ENV`)===`development`&&console.error(`Island Error [${this.props.islandId}]:`,e),!this.props.isolateError)throw e}handleRemoveIsland=()=>{let e=document.querySelector(`[data-island-id="${this.props.islandId}"]`);e&&e.remove()};handleReloadIsland=()=>{this.setState({hasError:!1,error:null,errorInfo:null})};renderFallback(){let{error:e}=this.state,{fallback:r,islandId:i}=this.props;if(r&&e)return r(e,i);let a=typeof Deno<`u`&&Deno.env.get(`NODE_ENV`)===`development`;return t(`div`,{class:`island-error-boundary`,"data-island-error":i,children:n(`div`,{class:`island-error-container`,children:[n(`div`,{class:`island-error-header`,children:[t(`span`,{class:`island-error-icon`,children:`⚠️`}),t(`span`,{class:`island-error-title`,children:`Island Error`})]}),n(`p`,{class:`island-error-message`,children:[`An error occurred in island "`,i,`". The rest of the page should work normally.`]}),n(`div`,{class:`island-error-actions`,children:[t(`button`,{onClick:this.handleReloadIsland,class:`island-reload-button`,children:`Reload Island`}),t(`button`,{onClick:this.handleRemoveIsland,class:`island-remove-button`,children:`Remove Island`})]}),a&&e&&n(`details`,{class:`island-error-details`,children:[t(`summary`,{children:`Error Details (Development)`}),n(`div`,{class:`island-error-info`,children:[n(`p`,{children:[t(`strong`,{children:`Island ID:`}),` `,i]}),n(`p`,{children:[t(`strong`,{children:`Error:`}),` `,e.message]})]}),t(`pre`,{class:`island-error-stack`,children:e.stack})]})]})})}render(){return this.state.hasError?this.renderFallback():this.props.children}}export function withIslandErrorBoundary(e,n,i){return function(a){return t(IslandErrorBoundary,{islandId:n,fallback:i?.fallback,isolateError:i?.isolateError??!0,onError:i?.onError,children:t(e,{...a})})}}
+import{Component as e}from"preact";import{jsx as t,jsxs as n}from"preact/jsx-runtime";export class IslandErrorBoundary extends e{constructor(e){super(e),this.state={hasError:!1,error:null,errorInfo:null}}static getDerivedStateFromError(e){return{hasError:!0,error:e}}componentDidCatch(e,t){let n={layoutPath:`island:${this.props.islandId}`,errorType:`island`,timestamp:Date.now(),componentStack:t.componentStack,errorBoundary:`IslandErrorBoundary`};if(this.setState({errorInfo:n}),this.props.onError&&this.props.onError(e,n),typeof process<`u`&&process.env?.NODE_ENV===`development`&&console.error(`Island Error [${this.props.islandId}]:`,e),!this.props.isolateError)throw e}handleRemoveIsland=()=>{let e=document.querySelector(`[data-island-id="${this.props.islandId}"]`);e&&e.remove()};handleReloadIsland=()=>{this.setState({hasError:!1,error:null,errorInfo:null})};renderFallback(){let{error:e}=this.state,{fallback:r,islandId:i}=this.props;if(r&&e)return r(e,i);let a=typeof process<`u`&&process.env?.NODE_ENV===`development`;return t(`div`,{class:`island-error-boundary`,"data-island-error":i,children:n(`div`,{class:`island-error-container`,children:[n(`div`,{class:`island-error-header`,children:[t(`span`,{class:`island-error-icon`,children:`⚠️`}),t(`span`,{class:`island-error-title`,children:`Island Error`})]}),n(`p`,{class:`island-error-message`,children:[`An error occurred in island "`,i,`". The rest of the page should work normally.`]}),n(`div`,{class:`island-error-actions`,children:[t(`button`,{onClick:this.handleReloadIsland,class:`island-reload-button`,children:`Reload Island`}),t(`button`,{onClick:this.handleRemoveIsland,class:`island-remove-button`,children:`Remove Island`})]}),a&&e&&n(`details`,{class:`island-error-details`,children:[t(`summary`,{children:`Error Details (Development)`}),n(`div`,{class:`island-error-info`,children:[n(`p`,{children:[t(`strong`,{children:`Island ID:`}),` `,i]}),n(`p`,{children:[t(`strong`,{children:`Error:`}),` `,e.message]})]}),t(`pre`,{class:`island-error-stack`,children:e.stack})]})]})})}render(){return this.state.hasError?this.renderFallback():this.props.children}}export function withIslandErrorBoundary(e,n,i){return function(a){return t(IslandErrorBoundary,{islandId:n,fallback:i?.fallback,isolateError:i?.isolateError??!0,onError:i?.onError,children:t(e,{...a})})}}

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

@@ -0,0 +1,34 @@
+import { Component, ComponentChildren } from 'preact';
+import type { LayoutErrorInfo, LayoutContext, LayoutData } from '../types/layout.ts';
+export interface LayoutDataErrorBoundaryProps {
+    children: ComponentChildren;
+    layoutPath: string;
+    context: LayoutContext;
+    onError?: (error: Error, errorInfo: LayoutErrorInfo) => void;
+    fallbackData?: LayoutData;
+    retryLoader?: () => Promise<LayoutData>;
+}
+export interface LayoutDataErrorBoundaryState {
+    hasError: boolean;
+    error: Error | null;
+    errorInfo: LayoutErrorInfo | null;
+    retryCount: number;
+    isRetrying: boolean;
+    fallbackData: LayoutData | null;
+}
+/**
+ * Specialized error boundary for layout data loading errors
+ * Provides specific handling for data loader failures with retry and fallback mechanisms
+ */
+export declare class LayoutDataErrorBoundary extends Component<LayoutDataErrorBoundaryProps, LayoutDataErrorBoundaryState> {
+    private maxRetries;
+    constructor(props: LayoutDataErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): Partial<LayoutDataErrorBoundaryState>;
+    componentDidCatch(error: Error, errorInfo: {
+        componentStack?: string;
+    }): void;
+    private handleRetry;
+    private handleUseFallback;
+    private renderErrorUI;
+    render(): ComponentChildren;
+}

package/dist/src/components/LayoutDataErrorBoundary.js

@@ -1 +1 @@
-import{Component as e}from"preact";import{jsx as t,jsxs as n}from"preact/jsx-runtime";export class LayoutDataErrorBoundary extends e{maxRetries=3;constructor(e){super(e),this.state={hasError:!1,error:null,errorInfo:null,retryCount:0,isRetrying:!1,fallbackData:e.fallbackData||null}}static getDerivedStateFromError(e){return{hasError:!0,error:e}}componentDidCatch(e,t){let n={layoutPath:this.props.layoutPath,errorType:`loader`,timestamp:Date.now(),componentStack:t.componentStack,errorBoundary:`LayoutDataErrorBoundary`};this.setState({errorInfo:n}),this.props.onError&&this.props.onError(e,n)}handleRetry=async()=>{if(!(this.state.retryCount>=this.maxRetries||!this.props.retryLoader)){this.setState({isRetrying:!0});try{let e=await this.props.retryLoader();this.setState({hasError:!1,error:null,errorInfo:null,retryCount:this.state.retryCount+1,isRetrying:!1,fallbackData:e})}catch(e){this.setState({retryCount:this.state.retryCount+1,isRetrying:!1,error:e instanceof Error?e:Error(String(e))})}}};handleUseFallback=()=>{this.state.fallbackData&&this.setState({hasError:!1,error:null,errorInfo:null})};renderErrorUI(){let{error:e,retryCount:r,isRetrying:i,fallbackData:a}=this.state,o=r<this.maxRetries&&this.props.retryLoader,s=a!==null,c=typeof Deno<`u`&&Deno.env.get(`NODE_ENV`)===`development`;return t(`div`,{class:`layout-data-error-boundary`,children:n(`div`,{class:`error-container`,children:[t(`h3`,{children:`Data Loading Error`}),n(`p`,{children:[`Failed to load data for layout: `,this.props.layoutPath]}),n(`div`,{class:`error-actions`,children:[o&&t(`button`,{onClick:this.handleRetry,disabled:i,class:`retry-button`,children:i?`Retrying...`:`Retry (${this.maxRetries-r} left)`}),s&&t(`button`,{onClick:this.handleUseFallback,class:`fallback-button`,children:`Use Cached Data`})]}),c&&e&&n(`details`,{class:`error-details`,children:[t(`summary`,{children:`Error Details (Development)`}),n(`div`,{class:`error-info`,children:[n(`p`,{children:[t(`strong`,{children:`Error:`}),` `,e.message]}),n(`p`,{children:[t(`strong`,{children:`Layout:`}),` `,this.props.layoutPath]}),n(`p`,{children:[t(`strong`,{children:`Retry Count:`}),` `,r]})]}),t(`pre`,{class:`error-stack`,children:e.stack})]})]})})}render(){return this.state.hasError?this.renderErrorUI():this.props.children}}
+import{Component as e}from"preact";import{jsx as t,jsxs as n}from"preact/jsx-runtime";export class LayoutDataErrorBoundary extends e{maxRetries=3;constructor(e){super(e),this.state={hasError:!1,error:null,errorInfo:null,retryCount:0,isRetrying:!1,fallbackData:e.fallbackData||null}}static getDerivedStateFromError(e){return{hasError:!0,error:e}}componentDidCatch(e,t){let n={layoutPath:this.props.layoutPath,errorType:`loader`,timestamp:Date.now(),componentStack:t.componentStack,errorBoundary:`LayoutDataErrorBoundary`};this.setState({errorInfo:n}),this.props.onError&&this.props.onError(e,n)}handleRetry=async()=>{if(!(this.state.retryCount>=this.maxRetries||!this.props.retryLoader)){this.setState({isRetrying:!0});try{let e=await this.props.retryLoader();this.setState({hasError:!1,error:null,errorInfo:null,retryCount:this.state.retryCount+1,isRetrying:!1,fallbackData:e})}catch(e){this.setState({retryCount:this.state.retryCount+1,isRetrying:!1,error:e instanceof Error?e:Error(String(e))})}}};handleUseFallback=()=>{this.state.fallbackData&&this.setState({hasError:!1,error:null,errorInfo:null})};renderErrorUI(){let{error:e,retryCount:r,isRetrying:i,fallbackData:a}=this.state,o=r<this.maxRetries&&this.props.retryLoader,s=a!==null,c=typeof process<`u`&&process.env?.NODE_ENV===`development`;return t(`div`,{class:`layout-data-error-boundary`,children:n(`div`,{class:`error-container`,children:[t(`h3`,{children:`Data Loading Error`}),n(`p`,{children:[`Failed to load data for layout: `,this.props.layoutPath]}),n(`div`,{class:`error-actions`,children:[o&&t(`button`,{onClick:this.handleRetry,disabled:i,class:`retry-button`,children:i?`Retrying...`:`Retry (${this.maxRetries-r} left)`}),s&&t(`button`,{onClick:this.handleUseFallback,class:`fallback-button`,children:`Use Cached Data`})]}),c&&e&&n(`details`,{class:`error-details`,children:[t(`summary`,{children:`Error Details (Development)`}),n(`div`,{class:`error-info`,children:[n(`p`,{children:[t(`strong`,{children:`Error:`}),` `,e.message]}),n(`p`,{children:[t(`strong`,{children:`Layout:`}),` `,this.props.layoutPath]}),n(`p`,{children:[t(`strong`,{children:`Retry Count:`}),` `,r]})]}),t(`pre`,{class:`error-stack`,children:e.stack})]})]})})}render(){return this.state.hasError?this.renderErrorUI():this.props.children}}

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

@@ -0,0 +1,25 @@
+import { Component, ComponentChildren } from 'preact';
+import type { LayoutErrorInfo, ErrorRecoveryStrategy } from '../types/layout.ts';
+export interface LayoutErrorBoundaryProps {
+    children: ComponentChildren;
+    fallback?: (error: Error, retry: () => void) => ComponentChildren;
+    onError?: (error: Error, errorInfo: LayoutErrorInfo) => void;
+    recoveryStrategy?: ErrorRecoveryStrategy;
+    layoutPath?: string;
+    errorType?: 'component' | 'loader' | 'rendering' | 'island';
+}
+export interface LayoutErrorBoundaryState {
+    hasError: boolean;
+    error: Error | null;
+    errorInfo: LayoutErrorInfo | null;
+    retryCount: number;
+}
+export declare class LayoutErrorBoundary extends Component<LayoutErrorBoundaryProps, LayoutErrorBoundaryState> {
+    private maxRetries;
+    constructor(props: LayoutErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): Partial<LayoutErrorBoundaryState>;
+    componentDidCatch(error: Error, errorInfo: any): void;
+    private handleRetry;
+    private renderFallback;
+    render(): ComponentChildren;
+}

package/dist/src/components/LayoutErrorBoundary.js

@@ -1 +1 @@
-import{Component as e}from"preact";import{jsxs as t,jsx as n}from"preact/jsx-runtime";export class LayoutErrorBoundary extends e{maxRetries=3;constructor(e){super(e),this.state={hasError:!1,error:null,errorInfo:null,retryCount:0}}static getDerivedStateFromError(e){return{hasError:!0,error:e}}componentDidCatch(e,t){let n={layoutPath:this.props.layoutPath||`unknown`,errorType:this.props.errorType||`component`,timestamp:Date.now(),componentStack:t.componentStack,errorBoundary:this.constructor.name};this.setState({errorInfo:n}),this.props.onError&&this.props.onError(e,n),typeof Deno<`u`&&Deno.env.get(`NODE_ENV`)===`development`&&(console.error(`Layout Error Boundary caught an error:`,e),console.error(`Error Info:`,n),console.error(`Component Stack:`,t.componentStack))}handleRetry=()=>{this.state.retryCount<this.maxRetries&&this.setState({hasError:!1,error:null,errorInfo:null,retryCount:this.state.retryCount+1})};renderFallback(){let{error:e}=this.state,{fallback:r}=this.props;return r&&e?r(e,this.handleRetry):n(`div`,{class:`layout-error-boundary`,children:t(`div`,{class:`error-container`,children:[n(`h2`,{children:`Something went wrong`}),n(`p`,{children:`An error occurred while rendering this layout.`}),this.state.retryCount<this.maxRetries&&t(`button`,{onClick:this.handleRetry,class:`retry-button`,children:[`Try Again (`,this.maxRetries-this.state.retryCount,` attempts left)`]}),typeof Deno<`u`&&Deno.env.get(`NODE_ENV`)===`development`&&t(`details`,{class:`error-details`,children:[n(`summary`,{children:`Error Details (Development)`}),n(`pre`,{children:e?.stack}),this.state.errorInfo&&t(`div`,{children:[t(`p`,{children:[n(`strong`,{children:`Layout Path:`}),` `,this.state.errorInfo.layoutPath]}),t(`p`,{children:[n(`strong`,{children:`Error Type:`}),` `,this.state.errorInfo.errorType]}),t(`p`,{children:[n(`strong`,{children:`Timestamp:`}),` `,new Date(this.state.errorInfo.timestamp).toISOString()]})]})]})]})})}render(){return this.state.hasError?this.renderFallback():this.props.children}}
+import{Component as e}from"preact";import{jsxs as t,jsx as n}from"preact/jsx-runtime";export class LayoutErrorBoundary extends e{maxRetries=3;constructor(e){super(e),this.state={hasError:!1,error:null,errorInfo:null,retryCount:0}}static getDerivedStateFromError(e){return{hasError:!0,error:e}}componentDidCatch(e,t){let n={layoutPath:this.props.layoutPath||`unknown`,errorType:this.props.errorType||`component`,timestamp:Date.now(),componentStack:t.componentStack,errorBoundary:this.constructor.name};this.setState({errorInfo:n}),this.props.onError&&this.props.onError(e,n),typeof process<`u`&&process.env?.NODE_ENV===`development`&&(console.error(`Layout Error Boundary caught an error:`,e),console.error(`Error Info:`,n),console.error(`Component Stack:`,t.componentStack))}handleRetry=()=>{this.state.retryCount<this.maxRetries&&this.setState({hasError:!1,error:null,errorInfo:null,retryCount:this.state.retryCount+1})};renderFallback(){let{error:e}=this.state,{fallback:r}=this.props;return r&&e?r(e,this.handleRetry):n(`div`,{class:`layout-error-boundary`,children:t(`div`,{class:`error-container`,children:[n(`h2`,{children:`Something went wrong`}),n(`p`,{children:`An error occurred while rendering this layout.`}),this.state.retryCount<this.maxRetries&&t(`button`,{onClick:this.handleRetry,class:`retry-button`,children:[`Try Again (`,this.maxRetries-this.state.retryCount,` attempts left)`]}),typeof process<`u`&&process.env?.NODE_ENV===`development`&&t(`details`,{class:`error-details`,children:[n(`summary`,{children:`Error Details (Development)`}),n(`pre`,{children:e?.stack}),this.state.errorInfo&&t(`div`,{children:[t(`p`,{children:[n(`strong`,{children:`Layout Path:`}),` `,this.state.errorInfo.layoutPath]}),t(`p`,{children:[n(`strong`,{children:`Error Type:`}),` `,this.state.errorInfo.errorType]}),t(`p`,{children:[n(`strong`,{children:`Timestamp:`}),` `,new Date(this.state.errorInfo.timestamp).toISOString()]})]})]})]})})}render(){return this.state.hasError?this.renderFallback():this.props.children}}

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

@@ -0,0 +1,36 @@
+/** @jsxImportSource preact */
+import type { ComponentChildren } from 'preact';
+import { type IslandPersistence } from '../core/islands/island-persistence.ts';
+interface PersistentIslandProps {
+    /** Unique ID used as the storage key for this island's state */
+    persistentId: string;
+    /** The island component(s) to wrap with persistence context */
+    children: ComponentChildren;
+    /** Custom persistence instance (defaults to sessionStorage-backed) */
+    persistence?: IslandPersistence;
+}
+/**
+ * PersistentIsland — provides automatic state persistence context to child islands.
+ *
+ * Wrap any island with this component and use `usePersistentIslandContext()` inside
+ * the island to get `saveState`, `loadState`, and `clearState` functions.
+ *
+ * Usage in a page:
+ * ```tsx
+ * <PersistentIsland persistentId="my-counter" island={{ condition: 'on:client' }}>
+ *   <MyCounter />
+ * </PersistentIsland>
+ * ```
+ *
+ * Usage inside the island:
+ * ```tsx
+ * import { usePersistentIslandContext } from '@useavalon/avalon';
+ *
+ * function MyCounter() {
+ *   const { saveState, loadState, clearState } = usePersistentIslandContext();
+ *   // ...
+ * }
+ * ```
+ */
+export declare function PersistentIsland({ persistentId, children, persistence, }: Readonly<PersistentIslandProps>): import("preact").JSX.Element;
+export default PersistentIsland;

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

@@ -0,0 +1,42 @@
+/**
+ * StreamingErrorBoundary - Error boundary component for streaming contexts
+ *
+ * This component provides error isolation for Suspense boundaries in streaming SSR.
+ * It ensures that errors in one component don't break the entire page.
+ */
+import { Component, type ComponentChildren } from 'preact';
+export interface StreamingErrorBoundaryProps {
+    children: ComponentChildren;
+    fallback?: (error: Error, retry: () => void) => ComponentChildren;
+    onError?: (error: Error, errorInfo: any) => void;
+    componentId?: string;
+    isolateError?: boolean;
+}
+export interface StreamingErrorBoundaryState {
+    hasError: boolean;
+    error: Error | null;
+    errorInfo: any;
+}
+/**
+ * Error boundary component for streaming contexts
+ *
+ * Wraps Suspense boundaries to provide error isolation and recovery.
+ * Prevents errors in one component from breaking the entire page.
+ */
+export declare class StreamingErrorBoundary extends Component<StreamingErrorBoundaryProps, StreamingErrorBoundaryState> {
+    constructor(props: StreamingErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): Partial<StreamingErrorBoundaryState>;
+    componentDidCatch(error: Error, errorInfo: any): void;
+    private handleRetry;
+    private renderFallback;
+    render(): ComponentChildren;
+}
+/**
+ * Higher-order component to wrap components with streaming error boundaries
+ */
+export declare function withStreamingErrorBoundary<P extends object>(WrappedComponent: (props: P) => ComponentChildren, options?: {
+    fallback?: (error: Error, retry: () => void) => ComponentChildren;
+    componentId?: string;
+    isolateError?: boolean;
+    onError?: (error: Error, errorInfo: any) => void;
+}): (props: P) => import("preact").JSX.Element;

package/dist/src/components/StreamingErrorBoundary.js

@@ -1 +1 @@
-import{Component as e}from"preact";import{jsx as t,jsxs as n}from"preact/jsx-runtime";export class StreamingErrorBoundary extends e{constructor(e){super(e),this.state={hasError:!1,error:null,errorInfo:null}}static getDerivedStateFromError(e){return{hasError:!0,error:e}}componentDidCatch(e,t){if(this.setState({errorInfo:t}),console.error(`[StreamingErrorBoundary] Caught error:`,{componentId:this.props.componentId,error:e.message,stack:e.stack,componentStack:t.componentStack}),this.props.onError&&this.props.onError(e,t),!this.props.isolateError)throw e}handleRetry=()=>{this.setState({hasError:!1,error:null,errorInfo:null})};renderFallback(){let{error:e}=this.state,{fallback:r,componentId:i}=this.props;if(r&&e)return r(e,this.handleRetry);let a=typeof Deno<`u`&&Deno.env.get(`DENO_ENV`)!==`production`;return n(`div`,{class:`streaming-error-boundary`,"data-error-boundary":`true`,"data-component-id":i,style:{background:`#fff3cd`,border:`2px solid #ffc107`,borderRadius:`8px`,padding:`20px`,margin:`20px 0`,fontFamily:`system-ui, -apple-system, sans-serif`},children:[n(`div`,{class:`error-boundary-header`,style:{display:`flex`,alignItems:`center`,gap:`10px`,marginBottom:`10px`},children:[t(`span`,{style:{fontSize:`24px`},children:`⚠️`}),t(`h3`,{style:{margin:0,color:`#856404`},children:`Component Error`})]}),t(`p`,{style:{margin:`10px 0`,color:`#856404`},children:`An error occurred while rendering this component. The rest of the page should work normally.`}),t(`button`,{onClick:this.handleRetry,style:{background:`#ffc107`,border:`none`,borderRadius:`4px`,padding:`8px 16px`,cursor:`pointer`,fontWeight:`bold`,color:`#856404`,marginTop:`10px`},children:`Retry`}),a&&e&&n(`details`,{style:{marginTop:`15px`},children:[t(`summary`,{style:{cursor:`pointer`,color:`#856404`,fontWeight:`bold`},children:`Error Details (Development Mode)`}),n(`div`,{style:{marginTop:`10px`},children:[i&&n(`p`,{children:[t(`strong`,{children:`Component ID:`}),` `,i]}),n(`p`,{children:[t(`strong`,{children:`Error:`}),` `,e.message]}),e.stack&&t(`pre`,{style:{background:`#f5f5f5`,padding:`10px`,borderRadius:`4px`,overflowX:`auto`,fontSize:`12px`,marginTop:`10px`},children:e.stack}),this.state.errorInfo?.componentStack&&n(`div`,{children:[t(`p`,{children:t(`strong`,{children:`Component Stack:`})}),t(`pre`,{style:{background:`#f5f5f5`,padding:`10px`,borderRadius:`4px`,overflowX:`auto`,fontSize:`12px`,marginTop:`10px`},children:this.state.errorInfo.componentStack})]})]})]})]})}render(){return this.state.hasError?this.renderFallback():this.props.children}}export function withStreamingErrorBoundary(e,n){return function(i){return t(StreamingErrorBoundary,{componentId:n?.componentId,fallback:n?.fallback,isolateError:n?.isolateError??!0,onError:n?.onError,children:t(e,{...i})})}}
+import{Component as e}from"preact";import{jsx as t,jsxs as n}from"preact/jsx-runtime";export class StreamingErrorBoundary extends e{constructor(e){super(e),this.state={hasError:!1,error:null,errorInfo:null}}static getDerivedStateFromError(e){return{hasError:!0,error:e}}componentDidCatch(e,t){if(this.setState({errorInfo:t}),console.error(`[StreamingErrorBoundary] Caught error:`,{componentId:this.props.componentId,error:e.message,stack:e.stack,componentStack:t.componentStack}),this.props.onError&&this.props.onError(e,t),!this.props.isolateError)throw e}handleRetry=()=>{this.setState({hasError:!1,error:null,errorInfo:null})};renderFallback(){let{error:e}=this.state,{fallback:r,componentId:i}=this.props;if(r&&e)return r(e,this.handleRetry);let a=typeof process<`u`&&process.env?.NODE_ENV!==`production`;return n(`div`,{class:`streaming-error-boundary`,"data-error-boundary":`true`,"data-component-id":i,style:{background:`#fff3cd`,border:`2px solid #ffc107`,borderRadius:`8px`,padding:`20px`,margin:`20px 0`,fontFamily:`system-ui, -apple-system, sans-serif`},children:[n(`div`,{class:`error-boundary-header`,style:{display:`flex`,alignItems:`center`,gap:`10px`,marginBottom:`10px`},children:[t(`span`,{style:{fontSize:`24px`},children:`⚠️`}),t(`h3`,{style:{margin:0,color:`#856404`},children:`Component Error`})]}),t(`p`,{style:{margin:`10px 0`,color:`#856404`},children:`An error occurred while rendering this component. The rest of the page should work normally.`}),t(`button`,{onClick:this.handleRetry,style:{background:`#ffc107`,border:`none`,borderRadius:`4px`,padding:`8px 16px`,cursor:`pointer`,fontWeight:`bold`,color:`#856404`,marginTop:`10px`},children:`Retry`}),a&&e&&n(`details`,{style:{marginTop:`15px`},children:[t(`summary`,{style:{cursor:`pointer`,color:`#856404`,fontWeight:`bold`},children:`Error Details (Development Mode)`}),n(`div`,{style:{marginTop:`10px`},children:[i&&n(`p`,{children:[t(`strong`,{children:`Component ID:`}),` `,i]}),n(`p`,{children:[t(`strong`,{children:`Error:`}),` `,e.message]}),e.stack&&t(`pre`,{style:{background:`#f5f5f5`,padding:`10px`,borderRadius:`4px`,overflowX:`auto`,fontSize:`12px`,marginTop:`10px`},children:e.stack}),this.state.errorInfo?.componentStack&&n(`div`,{children:[t(`p`,{children:t(`strong`,{children:`Component Stack:`})}),t(`pre`,{style:{background:`#f5f5f5`,padding:`10px`,borderRadius:`4px`,overflowX:`auto`,fontSize:`12px`,marginTop:`10px`},children:this.state.errorInfo.componentStack})]})]})]})]})}render(){return this.state.hasError?this.renderFallback():this.props.children}}export function withStreamingErrorBoundary(e,n){return function(i){return t(StreamingErrorBoundary,{componentId:n?.componentId,fallback:n?.fallback,isolateError:n?.isolateError??!0,onError:n?.onError,children:t(e,{...i})})}}