@useavalon/avalon 0.1.23 → 0.1.25

package/dist/src/schemas/routing.d.ts

@@ -0,0 +1,388 @@
+import { z } from 'zod';
+import type { ComponentType } from 'preact/compat';
+/**
+ * Route Type Schema - Defines the different types of routes supported
+ */
+export declare const RouteTypeSchema: z.ZodEnum<{
+    static: "static";
+    index: "index";
+    group: "group";
+    dynamic: "dynamic";
+    "catch-all": "catch-all";
+}>;
+/**
+ * File System Route Schema - Represents a discovered route from the file system
+ */
+export declare const FileSystemRouteSchema: z.ZodObject<{
+    pattern: z.ZodAny;
+    filePath: z.ZodString;
+    routeType: z.ZodEnum<{
+        static: "static";
+        index: "index";
+        group: "group";
+        dynamic: "dynamic";
+        "catch-all": "catch-all";
+    }>;
+    dynamicSegments: z.ZodArray<z.ZodString>;
+    priority: z.ZodNumber;
+    isPrivate: z.ZodBoolean;
+    routeGroup: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Route Page Module Schema - Represents the exports from a page file in routing context
+ */
+export declare const RoutePageModuleSchema: z.ZodObject<{
+    default: z.ZodAny;
+    layoutConfig: z.ZodOptional<z.ZodAny>;
+    generateMetadata: z.ZodOptional<z.ZodAny>;
+    loader: z.ZodOptional<z.ZodAny>;
+    frontmatter: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+}, z.core.$strip>;
+/**
+ * Route Parameters Schema - Parameters extracted from dynamic routes
+ */
+export declare const RouteParamsSchema: z.ZodRecord<z.ZodString, z.ZodString>;
+/**
+ * Loader Context Schema - Context passed to page loaders
+ */
+export declare const LoaderContextSchema: z.ZodObject<{
+    request: z.ZodCustom<Request, Request>;
+    url: z.ZodCustom<URL, URL>;
+    params: z.ZodRecord<z.ZodString, z.ZodString>;
+    query: z.ZodCustom<URLSearchParams, URLSearchParams>;
+    state: z.ZodCustom<Map<unknown, unknown>, Map<unknown, unknown>>;
+}, z.core.$strip>;
+/**
+ * Page Props Schema - Props passed to page components
+ */
+export declare const PagePropsSchema: z.ZodObject<{
+    params: z.ZodRecord<z.ZodString, z.ZodString>;
+    query: z.ZodCustom<URLSearchParams, URLSearchParams>;
+    data: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strip>;
+/**
+ * Metadata Schema - SEO and meta information
+ */
+export declare const MetadataSchema: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    openGraph: z.ZodOptional<z.ZodObject<{
+        title: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodURL>;
+        url: z.ZodOptional<z.ZodURL>;
+        type: z.ZodOptional<z.ZodString>;
+        siteName: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    twitter: z.ZodOptional<z.ZodObject<{
+        card: z.ZodOptional<z.ZodEnum<{
+            summary: "summary";
+            summary_large_image: "summary_large_image";
+            app: "app";
+            player: "player";
+        }>>;
+        title: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodURL>;
+        site: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    schema: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    canonical: z.ZodOptional<z.ZodURL>;
+    robots: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * Resolved Metadata Schema - Final merged metadata for a route
+ */
+export declare const ResolvedMetadataSchema: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    openGraph: z.ZodOptional<z.ZodObject<{
+        title: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodURL>;
+        url: z.ZodOptional<z.ZodURL>;
+        type: z.ZodOptional<z.ZodString>;
+        siteName: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    twitter: z.ZodOptional<z.ZodObject<{
+        card: z.ZodOptional<z.ZodEnum<{
+            summary: "summary";
+            summary_large_image: "summary_large_image";
+            app: "app";
+            player: "player";
+        }>>;
+        title: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        image: z.ZodOptional<z.ZodURL>;
+        site: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    schema: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    canonical: z.ZodOptional<z.ZodURL>;
+    robots: z.ZodOptional<z.ZodString>;
+    sources: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    resolvedAt: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * Metadata Chain Schema - Hierarchical metadata from multiple sources
+ */
+export declare const MetadataChainSchema: z.ZodObject<{
+    global: z.ZodOptional<z.ZodObject<{
+        title: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        openGraph: z.ZodOptional<z.ZodObject<{
+            title: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+            image: z.ZodOptional<z.ZodURL>;
+            url: z.ZodOptional<z.ZodURL>;
+            type: z.ZodOptional<z.ZodString>;
+            siteName: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        twitter: z.ZodOptional<z.ZodObject<{
+            card: z.ZodOptional<z.ZodEnum<{
+                summary: "summary";
+                summary_large_image: "summary_large_image";
+                app: "app";
+                player: "player";
+            }>>;
+            title: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+            image: z.ZodOptional<z.ZodURL>;
+            site: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        schema: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        canonical: z.ZodOptional<z.ZodURL>;
+        robots: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    sections: z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        metadata: z.ZodObject<{
+            title: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+            keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            openGraph: z.ZodOptional<z.ZodObject<{
+                title: z.ZodOptional<z.ZodString>;
+                description: z.ZodOptional<z.ZodString>;
+                image: z.ZodOptional<z.ZodURL>;
+                url: z.ZodOptional<z.ZodURL>;
+                type: z.ZodOptional<z.ZodString>;
+                siteName: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            twitter: z.ZodOptional<z.ZodObject<{
+                card: z.ZodOptional<z.ZodEnum<{
+                    summary: "summary";
+                    summary_large_image: "summary_large_image";
+                    app: "app";
+                    player: "player";
+                }>>;
+                title: z.ZodOptional<z.ZodString>;
+                description: z.ZodOptional<z.ZodString>;
+                image: z.ZodOptional<z.ZodURL>;
+                site: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+            schema: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+            canonical: z.ZodOptional<z.ZodURL>;
+            robots: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>>;
+    page: z.ZodOptional<z.ZodObject<{
+        title: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        keywords: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        openGraph: z.ZodOptional<z.ZodObject<{
+            title: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+            image: z.ZodOptional<z.ZodURL>;
+            url: z.ZodOptional<z.ZodURL>;
+            type: z.ZodOptional<z.ZodString>;
+            siteName: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        twitter: z.ZodOptional<z.ZodObject<{
+            card: z.ZodOptional<z.ZodEnum<{
+                summary: "summary";
+                summary_large_image: "summary_large_image";
+                app: "app";
+                player: "player";
+            }>>;
+            title: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+            image: z.ZodOptional<z.ZodURL>;
+            site: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+        schema: z.ZodOptional<z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+        canonical: z.ZodOptional<z.ZodURL>;
+        robots: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * Route Discovery Options Schema - Configuration for route discovery
+ */
+export declare const RouteDiscoveryOptionsSchema: z.ZodObject<{
+    pagesDirectory: z.ZodDefault<z.ZodString>;
+    apiDirectory: z.ZodDefault<z.ZodString>;
+    extensions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    excludeDirectories: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    enableWatching: z.ZodDefault<z.ZodBoolean>;
+    developmentMode: z.ZodDefault<z.ZodBoolean>;
+    quietMode: z.ZodDefault<z.ZodBoolean>;
+}, z.core.$strip>;
+/**
+ * File System Router Configuration Schema
+ */
+export declare const FileSystemRouterConfigSchema: z.ZodObject<{
+    discovery: z.ZodOptional<z.ZodObject<{
+        pagesDirectory: z.ZodDefault<z.ZodString>;
+        apiDirectory: z.ZodDefault<z.ZodString>;
+        extensions: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        excludeDirectories: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        enableWatching: z.ZodDefault<z.ZodBoolean>;
+        developmentMode: z.ZodDefault<z.ZodBoolean>;
+        quietMode: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    fallbackToManual: z.ZodDefault<z.ZodBoolean>;
+    enableCaching: z.ZodDefault<z.ZodBoolean>;
+    cacheTTL: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * Page File Schema - Information about a discovered page file
+ */
+export declare const PageFileSchema: z.ZodObject<{
+    filePath: z.ZodString;
+    relativePath: z.ZodString;
+    extension: z.ZodString;
+    isPrivate: z.ZodBoolean;
+    routeGroup: z.ZodOptional<z.ZodString>;
+    mtime: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * Route Handler Schema - Complete route handler information
+ */
+export declare const RouteHandlerSchema: z.ZodObject<{
+    pattern: z.ZodAny;
+    handler: z.ZodAny;
+    metadata: z.ZodObject<{
+        filePath: z.ZodString;
+        routeType: z.ZodEnum<{
+            static: "static";
+            index: "index";
+            group: "group";
+            dynamic: "dynamic";
+            "catch-all": "catch-all";
+        }>;
+        priority: z.ZodNumber;
+        dynamicSegments: z.ZodArray<z.ZodString>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+/**
+ * Route Cache Entry Schema - Cached route information
+ */
+export declare const RouteCacheEntrySchema: z.ZodObject<{
+    routes: z.ZodArray<z.ZodObject<{
+        pattern: z.ZodAny;
+        filePath: z.ZodString;
+        routeType: z.ZodEnum<{
+            static: "static";
+            index: "index";
+            group: "group";
+            dynamic: "dynamic";
+            "catch-all": "catch-all";
+        }>;
+        dynamicSegments: z.ZodArray<z.ZodString>;
+        priority: z.ZodNumber;
+        isPrivate: z.ZodBoolean;
+        routeGroup: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    timestamp: z.ZodNumber;
+    fileMtimes: z.ZodRecord<z.ZodString, z.ZodNumber>;
+}, z.core.$strip>;
+/**
+ * File System API Route Schema - Represents an API endpoint route discovered from file system
+ */
+export declare const FileSystemApiRouteSchema: z.ZodObject<{
+    pattern: z.ZodAny;
+    filePath: z.ZodString;
+    methods: z.ZodArray<z.ZodEnum<{
+        GET: "GET";
+        POST: "POST";
+        PUT: "PUT";
+        DELETE: "DELETE";
+        PATCH: "PATCH";
+        HEAD: "HEAD";
+        OPTIONS: "OPTIONS";
+    }>>;
+    priority: z.ZodNumber;
+    dynamicSegments: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+/**
+ * File System API Module Schema - Exports from an API route file
+ */
+export declare const FileSystemApiModuleSchema: z.ZodObject<{
+    GET: z.ZodOptional<z.ZodAny>;
+    POST: z.ZodOptional<z.ZodAny>;
+    PUT: z.ZodOptional<z.ZodAny>;
+    DELETE: z.ZodOptional<z.ZodAny>;
+    PATCH: z.ZodOptional<z.ZodAny>;
+    HEAD: z.ZodOptional<z.ZodAny>;
+    OPTIONS: z.ZodOptional<z.ZodAny>;
+}, z.core.$strip>;
+export type RouteType = z.infer<typeof RouteTypeSchema>;
+export type FileSystemRoute = z.infer<typeof FileSystemRouteSchema>;
+export type RoutePageModule = z.infer<typeof RoutePageModuleSchema>;
+export type RouteParams = z.infer<typeof RouteParamsSchema>;
+export type LoaderContext = z.infer<typeof LoaderContextSchema>;
+export type PageProps = z.infer<typeof PagePropsSchema>;
+export type Metadata = z.infer<typeof MetadataSchema>;
+export type ResolvedMetadata = z.infer<typeof ResolvedMetadataSchema>;
+export type MetadataChain = z.infer<typeof MetadataChainSchema>;
+export type RouteDiscoveryOptions = z.infer<typeof RouteDiscoveryOptionsSchema>;
+export type FileSystemRouterConfig = z.infer<typeof FileSystemRouterConfigSchema>;
+export type PageFile = z.infer<typeof PageFileSchema>;
+export type RouteHandler = z.infer<typeof RouteHandlerSchema>;
+export type RouteCacheEntry = z.infer<typeof RouteCacheEntrySchema>;
+export type FileSystemApiRoute = z.infer<typeof FileSystemApiRouteSchema>;
+export type FileSystemApiModule = z.infer<typeof FileSystemApiModuleSchema>;
+/**
+ * Page Component Type
+ */
+export type PageComponent<P extends PageProps = PageProps> = ComponentType<P>;
+/**
+ * Metadata Generator Function Type
+ */
+export type MetadataGenerator = (params: RouteParams) => Promise<Metadata>;
+/**
+ * Page Loader Function Type
+ */
+export type PageLoader = (context: LoaderContext) => Promise<unknown>;
+/**
+ * Route Handler Function Type
+ */
+export type RouteHandlerFunction = (request: Request, context: LoaderContext) => Promise<Response>;
+/**
+ * File System API Handler Function Type
+ */
+export type FileSystemApiHandler = (request: Request, context: LoaderContext) => Promise<Response>;
+/**
+ * Type guard for FileSystemRoute
+ */
+export declare function isFileSystemRoute(data: unknown): data is FileSystemRoute;
+/**
+ * Type guard for RoutePageModule
+ */
+export declare function isRoutePageModule(data: unknown): data is RoutePageModule;
+/**
+ * Type guard for Metadata
+ */
+export declare function isMetadata(data: unknown): data is Metadata;
+/**
+ * Type guard for RouteParams
+ */
+export declare function isRouteParams(data: unknown): data is RouteParams;
+/**
+ * Type guard for FileSystemApiModule
+ */
+export declare function isFileSystemApiModule(data: unknown): data is FileSystemApiModule;
+export type { ExtractRouteParams, ExtractOptionalParams, RouteParameters, TypedPageComponent, TypedPageComponentWithData, TypedMetadataGenerator, TypedPageLoader, TypedApiHandler, TypedApiModule, HasDynamicSegments, HasCatchAllSegments, HasOptionalSegments, CountDynamicSegments, ValidRoutePattern, ValidRouteExtension, PageComponentProps, } from '../types/routing.ts';
+export { isValidRouteParams, isValidPageProps, isValidRoutePattern, validatePageComponent, createTypedPageComponent, createTypedMetadataGenerator, createTypedPageLoader, createTypedApiHandler, } from '../types/routing.ts';

package/dist/src/types/as-island.d.ts

@@ -0,0 +1,17 @@
+import type { IslandDirective } from './island-prop.d.ts';
+import type { ComponentType } from 'preact';
+/**
+ * Cast a cross-framework component (Vue, Svelte, Lit, Solid) to be usable
+ * in Preact JSX with the `island` prop and correct prop types.
+ *
+ * The Vite transform handles these components at build time — this cast is
+ * purely for TypeScript's benefit.
+ *
+ * @example
+ * import _VueCounter from '../islands/VueCounter.vue';
+ * const VueCounter = asIsland<{ initialCount?: number }>(_VueCounter);
+ * // Now usable as: <VueCounter island={{ condition: 'on:visible' }} initialCount={0} />
+ */
+export declare function asIsland<P extends Record<string, unknown> = Record<string, unknown>>(_component: unknown): ComponentType<P & {
+    island?: IslandDirective;
+}>;

package/dist/src/types/layout.d.ts

@@ -0,0 +1,177 @@
+import type { LayoutContext, LayoutRoute, LayoutHandler, LayoutProps, LayoutDiscoveryOptions, RouteInfo, LayoutRule, LayoutConfig, IslandState, PersistentIslandProps, LayoutErrorInfo, LayoutErrorBoundaryProps, ErrorRecoveryStrategy, StreamingLayoutProps, StreamingComponent, ResolvedLayout, LayoutLoader } from '../schemas/layout.ts';
+import type { ComponentType, ComponentChildren } from 'preact';
+export type { LayoutContext, LayoutData, LayoutRoute, LayoutHandler, LayoutProps, LayoutDiscoveryOptions, RouteInfo, LayoutRule, LayoutConfig, IslandState, PersistentIslandProps, PersistentIslandContext, LayoutErrorInfo, LayoutErrorBoundaryProps, ErrorRecoveryStrategy, StreamingLayoutProps, StreamingComponent, ResolvedLayout, LayoutCache, EnhancedLayoutContext, LayoutLoader, LayoutMatcherFunction, LayoutErrorHandler, LayoutRetryFunction, LayoutFallbackRenderer, IslandStateSaver, IslandStateLoader, IslandStateClearer, StreamingReadyCheck, } from '../schemas/layout.ts';
+export type { ComponentType, ComponentChildren } from 'preact';
+export { LayoutDiscovery } from '../core/layout/layout-discovery.ts';
+export { LayoutDataLoader } from '../core/layout/layout-data-loader.ts';
+export { LayoutMatcher as LayoutMatcherClass } from '../core/layout/layout-matcher.ts';
+export { LayoutComposer } from '../core/layout/layout-composer.ts';
+export { IslandPersistence, defaultIslandPersistence } from '../core/islands/island-persistence.ts';
+export { IslandStateSerializer } from '../core/islands/island-state-serializer.ts';
+export { createPersistentIslandContext, usePersistentIslandContext, PersistentIslandProvider, } from '../core/islands/persistent-island-context.tsx';
+export { PersistentIsland } from '../components/PersistentIsland.tsx';
+export { LayoutErrorBoundary } from '../components/LayoutErrorBoundary.tsx';
+export { LayoutDataErrorBoundary } from '../components/LayoutDataErrorBoundary.tsx';
+export { IslandErrorBoundary, withIslandErrorBoundary } from '../components/IslandErrorBoundary.tsx';
+export { StreamingLayout, StreamingSuspense, withStreaming, useStreamingState, } from '../components/StreamingLayout.tsx';
+export { EnhancedLayoutResolver, createEnhancedLayoutResolver, EnhancedLayoutResolverUtils, type EnhancedLayoutResolverOptions, } from '../core/layout/enhanced-layout-resolver.ts';
+export { LayoutCacheManager, type CacheEntry, type CacheStats, type CacheConfig, } from '../core/layout/layout-cache-manager.ts';
+/**
+ * Layout Discovery Interface
+ */
+export interface ILayoutDiscovery {
+    discoverLayouts(routePath: string): Promise<LayoutRoute[]>;
+    buildLayoutChain(url: URL): Promise<LayoutHandler[]>;
+    setWatching(enabled: boolean): void;
+    getOptions(): LayoutDiscoveryOptions;
+}
+/**
+ * Layout Matcher Interface
+ */
+export interface ILayoutMatcher {
+    addRule(rule: LayoutRule): void;
+    removeRule(rule: LayoutRule): void;
+    shouldApplyLayout(layoutPath: string, route: RouteInfo): boolean;
+    getRules(): LayoutRule[];
+    clearRules(): void;
+}
+/**
+ * Layout Composer Interface
+ */
+export interface ILayoutComposer {
+    resolveLayouts(routePath: string, pageModule: PageModule): Promise<LayoutHandler[]>;
+    applyConfiguration(layouts: LayoutHandler[], config: LayoutConfig): Promise<LayoutHandler[]>;
+    validateLayoutConfig(config: LayoutConfig): {
+        valid: boolean;
+        errors: string[];
+    };
+    clearCache(): void;
+    getCompositionStats(): {
+        customLayoutCacheSize: number;
+        discoveryStats: {
+            layoutCount: number;
+            routeCacheCount: number;
+        };
+    };
+}
+/**
+ * Island Persistence Interface
+ */
+export interface IIslandPersistence {
+    saveState(id: string, state: IslandState): void;
+    loadState(id: string): IslandState | null;
+    clearState(id: string): void;
+    hasState(id: string): boolean;
+    getStoredIds(): string[];
+    clearAllStates(): void;
+}
+/**
+ * Layout Error Recovery Interface
+ */
+export interface ILayoutErrorRecovery {
+    handleLayoutError(error: Error, context: LayoutContext): Promise<Response>;
+    registerStrategy(errorType: string, strategy: ErrorRecoveryStrategy): void;
+    getStrategy(error: Error): ErrorRecoveryStrategy | null;
+}
+/**
+ * Layout Streaming Interface
+ */
+export interface ILayoutStreaming {
+    renderWithStreaming(layout: LayoutHandler, props: LayoutProps): Promise<ReadableStream>;
+    isStreamingSupported(): boolean;
+    createStreamingResponse(components: StreamingComponent[]): ReadableStream;
+    generateSkeleton(component: StreamingComponent): string;
+}
+/**
+ * Enhanced Layout Resolver Interface
+ */
+export interface IEnhancedLayoutResolver {
+    resolveAndRender(routePath: string, pageModule: PageModule, context: LayoutContext): Promise<ResolvedLayout>;
+    getCachedResolution(routePath: string): ResolvedLayout | null;
+    clearCache(): void;
+    setCaching(enabled: boolean): void;
+}
+export interface ILayoutComponent {
+    props: LayoutProps;
+    layoutLoader?: LayoutLoader;
+    layoutConfig?: LayoutConfig;
+}
+export interface IPersistentIslandComponent {
+    props: PersistentIslandProps;
+    saveState(): void;
+    loadState(): void;
+    clearState(): void;
+    hasState(): boolean;
+}
+export interface ILayoutErrorBoundaryComponent {
+    props: LayoutErrorBoundaryProps;
+    handleRetry(): void;
+    getErrorState(): {
+        hasError: boolean;
+        error?: Error;
+    };
+    resetErrorState(): void;
+}
+export interface IStreamingLayoutComponent {
+    props: StreamingLayoutProps;
+    isReady(): Promise<boolean>;
+    renderFallback(): ComponentChildren;
+    getPriority(): number;
+}
+export interface LayoutModule {
+    default: ComponentType<LayoutProps>;
+    layoutLoader?: LayoutLoader;
+    layoutConfig?: LayoutConfig;
+    ErrorBoundary?: ComponentType<LayoutErrorBoundaryProps>;
+}
+export interface PageModule {
+    default: ComponentType<Record<string, unknown>>;
+    layoutConfig?: LayoutConfig;
+    frontmatter?: Record<string, unknown>;
+    loader?: (ctx: LayoutContext) => Promise<Record<string, unknown>>;
+}
+export interface LayoutResolutionContext {
+    route: RouteInfo;
+    pageModule: PageModule;
+    layoutContext: LayoutContext;
+    cachingEnabled: boolean;
+    streamingEnabled: boolean;
+    developmentMode: boolean;
+}
+export interface LayoutPerformanceMetrics {
+    discoveryTime: number;
+    dataLoadingTime: number;
+    renderingTime: number;
+    totalTime: number;
+    layoutCount: number;
+    cacheHit: boolean;
+    memoryUsage?: number;
+}
+export interface LayoutDebugInfo {
+    resolutionChain: string[];
+    appliedRules: LayoutRule[];
+    skippedLayouts: string[];
+    errors: LayoutErrorInfo[];
+    metrics: LayoutPerformanceMetrics;
+    cacheInfo: {
+        hit: boolean;
+        key: string;
+        size: number;
+    };
+}
+export type LayoutEventType = 'layout-discovered' | 'layout-loaded' | 'layout-rendered' | 'layout-error' | 'layout-cached' | 'island-state-saved' | 'island-state-loaded' | 'streaming-started' | 'streaming-completed';
+export interface LayoutEventData {
+    type: LayoutEventType;
+    timestamp: number;
+    layoutPath?: string;
+    error?: Error;
+    metrics?: LayoutPerformanceMetrics;
+    data?: Record<string, unknown>;
+}
+export type LayoutEventHandler = (event: LayoutEventData) => void;
+export interface ILayoutEventEmitter {
+    on(event: LayoutEventType, handler: LayoutEventHandler): void;
+    off(event: LayoutEventType, handler: LayoutEventHandler): void;
+    emit(event: LayoutEventType, data?: Record<string, unknown>): void;
+    removeAllListeners(): void;
+}