@useavalon/avalon 0.1.22 → 0.1.24

package/dist/src/islands/discovery/validator.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Island Validator
+ *
+ * Validates island components and directory structure.
+ * Provides validation for exports, naming conventions, and circular dependencies.
+ */
+import type { IslandDirectory, DiscoveredIsland } from "./types.ts";
+/**
+ * Result of validating an island or directory
+ */
+export interface ValidationResult {
+    /** Whether validation passed (no errors) */
+    valid: boolean;
+    /** Validation errors (failures) */
+    errors: ValidationError[];
+    /** Validation warnings (non-fatal issues) */
+    warnings: ValidationWarning[];
+}
+/**
+ * A validation error (causes validation to fail)
+ */
+export interface ValidationError {
+    /** Type of error */
+    type: "invalid-export" | "circular-dependency" | "naming-convention";
+    /** Human-readable error message */
+    message: string;
+    /** Absolute file path where error occurred */
+    filePath: string;
+    /** Line number (1-indexed) if applicable */
+    line?: number;
+    /** Column number (1-indexed) if applicable */
+    column?: number;
+    /** Suggested fix for the error */
+    suggestion?: string;
+}
+/**
+ * A validation warning (non-fatal issue)
+ */
+export interface ValidationWarning {
+    /** Type of warning */
+    type: "empty-directory" | "naming-collision" | "deprecated-pattern";
+    /** Human-readable warning message */
+    message: string;
+    /** File path if applicable */
+    filePath?: string;
+    /** Suggested fix for the warning */
+    suggestion?: string;
+}
+/**
+ * Represents a circular dependency chain
+ */
+export interface CircularDependency {
+    /** The cycle as an array of file paths */
+    cycle: string[];
+    /** Human-readable description of the cycle */
+    description: string;
+}
+/**
+ * Island Validator class
+ */
+export declare class IslandValidator {
+    private _projectRoot;
+    constructor(projectRoot: string);
+    get projectRoot(): string;
+    private extractComponentName;
+    private toPascalCase;
+    private hasValidJsExport;
+    private isValidVueComponent;
+    private isValidSvelteComponent;
+    private createExportError;
+    private validateExports;
+    private extractJsImports;
+    private extractImports;
+    private resolveImportToIsland;
+    private buildImportGraph;
+    private cycleExists;
+    private findCycles;
+    private formatCycleDescription;
+    validateComponent(filePath: string): Promise<ValidationResult>;
+    validateDirectory(directory: IslandDirectory): Promise<ValidationResult>;
+    validateNamingConvention(name: string, filePath: string): ValidationResult;
+    detectCircularDependencies(islands: DiscoveredIsland[]): Promise<CircularDependency[]>;
+}
+export declare function formatValidationError(error: ValidationError, projectRoot: string): string;
+export declare function formatValidationWarning(warning: ValidationWarning, projectRoot: string): string;
+export declare function formatCircularDependency(circular: CircularDependency, projectRoot: string): string;
+export declare function formatValidationResult(result: ValidationResult, projectRoot: string): string;
+export declare function createIslandValidator(projectRoot: string): IslandValidator;
+export declare function validateAllIslands(islands: DiscoveredIsland[], projectRoot: string): Promise<ValidationResult>;

package/dist/src/islands/discovery/watcher.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Island File Watcher
+ *
+ * Watches all discovered island directories for file changes and emits
+ * change events with affected island information. Supports HMR for
+ * nested island directories.
+ */
+import type { IslandChangeEvent, IslandDiscoveryConfig } from "./types.ts";
+import { IslandRegistry } from "./registry.ts";
+/**
+ * Callback type for island change events
+ */
+export type IslandChangeCallback = (event: IslandChangeEvent) => void;
+/**
+ * Options for the island watcher
+ */
+export interface IslandWatcherOptions {
+    /** Debounce delay in milliseconds (default: 100) */
+    debounceMs?: number;
+    /** Whether to emit events for initial discovery (default: false) */
+    emitInitial?: boolean;
+}
+/**
+ * Island File Watcher
+ *
+ * Watches all discovered island directories for file changes.
+ * Emits change events with affected island information for HMR support.
+ */
+export declare class IslandWatcher {
+    private _projectRoot;
+    private _config;
+    private _options;
+    private _registry;
+    private _watchers;
+    private _callbacks;
+    private _isWatching;
+    private _debounceTimers;
+    constructor(projectRoot: string, registry: IslandRegistry, config?: IslandDiscoveryConfig, options?: IslandWatcherOptions);
+    /**
+     * Check if the watcher is currently active
+     */
+    get isWatching(): boolean;
+    /**
+     * Get the number of registered callbacks
+     */
+    get callbackCount(): number;
+    /**
+     * Start watching all discovered island directories.
+     *
+     * @param callback - Callback to invoke on file changes
+     * @returns Cleanup function to stop watching
+     */
+    watch(callback: IslandChangeCallback): Promise<() => void>;
+    /**
+     * Stop all file watchers and clear callbacks.
+     */
+    stop(): void;
+    /**
+     * Start watching all island directories.
+     */
+    private _startWatching;
+    /**
+     * Watch a single island directory for changes.
+     */
+    private _watchDirectory;
+    /**
+     * Debounce file change events to avoid duplicate processing.
+     */
+    private _debounceEvent;
+    /**
+     * Handle a file change event.
+     */
+    private _handleFileChange;
+    /**
+     * Get the qualified name for an island from its file path.
+     */
+    private _getQualifiedNameFromPath;
+    /**
+     * Extract component name from file name.
+     */
+    private _extractComponentName;
+    /**
+     * Emit an event to all registered callbacks.
+     */
+    private _emitEvent;
+    /**
+     * Refresh the watcher to pick up new directories.
+     * Call this after the registry is rebuilt.
+     */
+    refresh(): Promise<void>;
+}
+/**
+ * Create an island watcher for the given registry.
+ */
+export declare function createIslandWatcher(projectRoot: string, registry: IslandRegistry, config?: IslandDiscoveryConfig, options?: IslandWatcherOptions): IslandWatcher;

package/dist/src/islands/framework-detection.d.ts

@@ -0,0 +1,53 @@
+import type { Framework } from './types.ts';
+import { IslandRegistry } from './discovery/index.ts';
+/** Known synchronous framework types (excludes 'unknown') */
+type SyncFramework = 'solid' | 'vue' | 'svelte' | 'preact' | 'react' | 'lit' | 'qwik';
+/**
+ * Resolve Island component path for Vite SSR loading
+ * Converts /islands/* paths to /src/islands/* for proper resolution
+ * Also handles framework-specific naming conventions and nested islands.
+ * Uses async file operations and caching for better performance.
+ *
+ * @param src - The source path or component name
+ * @returns The resolved path
+ */
+export declare function resolveIslandPath(src: string): Promise<string>;
+/**
+ * Check if a path is a nested island path (not in default /src/islands/).
+ *
+ * @param path - The path to check
+ * @returns True if the path is a nested island path
+ */
+export declare function isNestedIslandPath(path: string): boolean;
+/**
+ * Get the island registry, initializing it if necessary.
+ *
+ * @param projectRoot - The project root directory
+ * @returns The island registry
+ */
+export declare function getOrCreateIslandRegistry(projectRoot?: string): Promise<IslandRegistry>;
+/**
+ * Set the global island registry.
+ * Useful for testing or when the registry is created elsewhere.
+ *
+ * @param registry - The registry to set
+ */
+export declare function setIslandRegistry(registry: IslandRegistry): void;
+/**
+ * Clear the global island registry.
+ * Useful for testing or hot module replacement.
+ */
+export declare function clearIslandRegistry(): void;
+/**
+ * Quick framework detection based on file extension and naming conventions
+ * Used for setting framework attributes without async file reading
+ *
+ * Updated to query integration configs for detection patterns
+ */
+export declare function detectFrameworkFromSrc(src: string): SyncFramework;
+/**
+ * Detect the framework used by a component file
+ * Updated to query integration configs for detection patterns
+ */
+export declare function detectFramework(src: string): Promise<Framework>;
+export {};

package/dist/src/islands/integration-loader.d.ts

@@ -0,0 +1,139 @@
+import type { Integration } from "@useavalon/core";
+/**
+ * Load an integration by framework name
+ * Uses cache to avoid repeated dynamic imports
+ *
+ * This function supports on-demand loading: if an integration hasn't been
+ * preloaded, it will be loaded and cached on first use. This enables
+ * lazy loading at server startup while ensuring fast subsequent renders.
+ */
+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.
+ *
+ * Updated to support nested island paths like:
+ * - /src/islands/Counter.tsx
+ * - /src/modules/auth/islands/Counter.tsx
+ * - /modules/dashboard/islands/Chart.vue
+ *
+ * @param src - The source path to detect framework from
+ * @returns The detected framework name
+ */
+export declare function detectFrameworkFromPath(src: string): "react" | "preact" | "vue" | "svelte" | "solid" | "lit" | "qwik";
+/**
+ * Check if a path is within any islands directory (including nested).
+ *
+ * Matches patterns like:
+ * - /islands/
+ * - /src/islands/
+ * - /src/modules/auth/islands/
+ * - /modules/dashboard/islands/
+ * - /src/features/user/islands/
+ *
+ * @param path - The path to check
+ * @returns True if the path is in an islands directory
+ */
+export declare function isInIslandsDirectory(path: string): boolean;
+/**
+ * Check if a path is a nested island path (not in default /src/islands/).
+ *
+ * @param path - The path to check
+ * @returns True if the path is a nested island path
+ */
+export declare function isNestedIslandPath(path: string): boolean;
+/**
+ * Extract the namespace from a nested island path.
+ *
+ * Examples:
+ * - /src/modules/auth/islands/Counter.tsx -> "modules/auth"
+ * - /src/features/user/islands/Profile.tsx -> "features/user"
+ * - /src/islands/Button.tsx -> ""
+ *
+ * @param path - The path to extract namespace from
+ * @returns The namespace or empty string for default islands
+ */
+export declare function extractNamespaceFromPath(path: string): string;
+/**
+ * Detect framework from file content by analyzing imports and patterns.
+ *
+ * Updated to support nested island paths.
+ *
+ * @param src - The source path
+ * @param content - The file content to analyze
+ * @returns The detected framework name
+ */
+export declare function detectFrameworkFromContent(src: string, content: string): "react" | "preact" | "vue" | "svelte" | "solid" | "lit" | "qwik";
+/**
+ * Get integration for a specific framework, with error handling
+ */
+export declare function getIntegration(framework: string): Promise<Integration>;
+/**
+ * Check if an integration is available for a framework
+ */
+export declare function hasIntegration(framework: string): Promise<boolean>;
+/**
+ * Get all loaded integrations from cache
+ */
+export declare function getLoadedIntegrations(): Integration[];
+/**
+ * Get all loaded framework names from cache
+ */
+export declare function getLoadedFrameworks(): string[];
+/**
+ * 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;
+/**
+ * Default frameworks to preload at server startup
+ * These are the most commonly used frameworks in island architecture
+ */
+export declare const DEFAULT_PRELOAD_FRAMEWORKS: readonly ["preact", "react", "vue", "svelte", "solid", "lit"];
+/**
+ * Options for preloading integrations
+ */
+export interface PreloadIntegrationsOptions {
+    /**
+     * When true, only preload integrations that are actually used on the page.
+     * This is determined by analyzing page components for framework usage.
+     * When false (default), preload all specified frameworks.
+     */
+    lazy?: boolean;
+    /**
+     * Array of framework names to preload.
+     * Defaults to DEFAULT_PRELOAD_FRAMEWORKS.
+     */
+    frameworks?: readonly string[];
+    /**
+     * Array of detected frameworks from page analysis.
+     * Only used when lazy=true to filter which frameworks to preload.
+     */
+    detectedFrameworks?: string[];
+}
+/**
+ * Preload integrations for multiple frameworks
+ * Useful for warming up the cache during build or startup
+ *
+ * Uses Promise.allSettled to load all integrations concurrently,
+ * ensuring that one failed integration doesn't block others.
+ *
+ * @param options - Preload options
+ * @returns Promise that resolves when all preloading attempts complete
+ */
+export declare function preloadIntegrations(options?: PreloadIntegrationsOptions): Promise<void>;
+/**
+ * Detect frameworks used in a page by analyzing component imports.
+ * This is used for lazy integration loading to only preload what's needed.
+ *
+ * @param pageContent - The content of the page file to analyze
+ * @returns Array of detected framework names
+ */
+export declare function detectFrameworksFromPageContent(pageContent: string): string[];

package/dist/src/islands/island.d.ts

@@ -0,0 +1,55 @@
+import type { JSX } from 'preact';
+import type { ViteDevServer } from 'vite';
+import type { AnalyzerOptions } from '../core/components/component-analyzer.ts';
+import type { Framework } from './types.ts';
+declare global {
+    var __viteDevServer: ViteDevServer | undefined;
+}
+/** Supported hydration conditions for island components */
+export type HydrationCondition = 'on:visible' | 'on:interaction' | 'on:idle' | 'on:client' | `media:${string}`;
+/** Supported framework identifiers (without "unknown") */
+export type FrameworkId = Exclude<Framework, 'unknown'>;
+export interface IslandProps {
+    /** Path to the island component (e.g., "/islands/Counter.tsx") */
+    src: string;
+    /** Hydration condition */
+    condition?: HydrationCondition;
+    /** Props to pass to the island component */
+    props?: Record<string, unknown>;
+    /** Children to render inside the island (for SSR) */
+    children?: import('preact').ComponentChildren;
+    /** Whether to render server-side (default: true unless condition is 'on:client') */
+    ssr?: boolean;
+    /** Framework hint for client hydration */
+    framework?: FrameworkId;
+    /** Force SSR-only rendering without hydration */
+    ssrOnly?: boolean;
+    /** Component render options for intelligent detection */
+    renderOptions?: AnalyzerOptions;
+    /** Hydration data from integration renderer */
+    hydrationData?: Record<string, unknown>;
+}
+/**
+ * Universal Island component – renders `<avalon-island>` custom elements for better DOM structure.
+ *
+ * Uses custom elements instead of div wrappers for cleaner, more semantic markup.
+ * Supports intelligent rendering strategy detection to skip hydration for SSR-only components.
+ */
+export default function Island({ src, condition, props, children, ssr, framework, ssrOnly, renderOptions, hydrationData, }: IslandProps): JSX.Element;
+/**
+ * Universal renderIsland function – auto-detects framework and handles SSR + hydration.
+ *
+ * This is the main function you should use – it automatically:
+ * - Detects the component framework (Vue, Solid.js, Preact/React)
+ * - Analyzes component for intelligent rendering strategy detection
+ * - Handles server-side rendering when possible
+ * - Falls back to client-only rendering when needed
+ * - Returns the appropriate Island component
+ *
+ * Performance tip: Providing an explicit `framework` prop skips component analysis
+ * and framework detection, significantly improving render performance.
+ *
+ * Error isolation: If SSR fails, returns an error placeholder instead of throwing,
+ * allowing the page to continue rendering other islands.
+ */
+export declare function renderIsland({ src, condition, props, children, ssr, framework, ssrOnly, renderOptions, }: IslandProps): Promise<JSX.Element>;

package/dist/src/islands/render-cache.d.ts

@@ -0,0 +1,203 @@
+/**
+ * Island Render Cache Module
+ *
+ * Provides caching for expensive operations in the island rendering pipeline:
+ * - Component analysis results
+ * - Resolved paths
+ * - Framework detection results
+ *
+ * This module helps optimize island rendering by avoiding repeated file I/O
+ * and analysis operations for the same components.
+ *
+ * @module render-cache
+ */
+import type { AnalysisReport } from "../core/components/component-analyzer.ts";
+import type { Framework } from "./types.ts";
+/**
+ * Cache entry for component analysis results
+ */
+export interface AnalysisCacheEntry {
+    /** The analysis result */
+    result: AnalysisReport;
+    /** Timestamp when the entry was cached */
+    timestamp: number;
+}
+/**
+ * Cache entry for resolved paths
+ */
+export interface PathCacheEntry {
+    /** The resolved path */
+    resolved: string;
+    /** Timestamp when the entry was cached */
+    timestamp: number;
+}
+/**
+ * Cache entry for framework detection results
+ */
+export interface FrameworkCacheEntry {
+    /** The detected framework */
+    framework: Framework;
+    /** Timestamp when the entry was cached */
+    timestamp: number;
+}
+/**
+ * Configuration options for the island render cache
+ */
+export interface CacheConfig {
+    /** TTL for analysis cache entries in milliseconds (default: 60000ms = 1 minute) */
+    analysisTTL: number;
+    /** TTL for path cache entries in milliseconds (default: 60000ms = 1 minute) */
+    pathTTL: number;
+    /** TTL for framework cache entries in milliseconds (default: 60000ms = 1 minute) */
+    frameworkTTL: number;
+    /** Maximum number of entries per cache (default: 1000) */
+    maxEntries: number;
+}
+/**
+ * Cache statistics for monitoring and debugging
+ */
+export interface CacheStats {
+    /** Number of analysis cache entries */
+    analysisSize: number;
+    /** Number of path cache entries */
+    pathsSize: number;
+    /** Number of framework cache entries */
+    frameworksSize: number;
+    /** Number of cache hits for analysis */
+    analysisHits: number;
+    /** Number of cache misses for analysis */
+    analysisMisses: number;
+    /** Number of cache hits for paths */
+    pathHits: number;
+    /** Number of cache misses for paths */
+    pathMisses: number;
+    /** Number of cache hits for frameworks */
+    frameworkHits: number;
+    /** Number of cache misses for frameworks */
+    frameworkMisses: number;
+}
+/**
+ * Island Render Cache interface
+ * Centralized cache for all expensive operations in island rendering
+ */
+export interface IslandRenderCache {
+    /** Analysis results by component path */
+    analysis: Map<string, AnalysisCacheEntry>;
+    /** Resolved paths by source path */
+    paths: Map<string, PathCacheEntry>;
+    /** Framework detection results by source path */
+    frameworks: Map<string, FrameworkCacheEntry>;
+    /** Cache configuration */
+    config: CacheConfig;
+    /** Cache statistics */
+    stats: CacheStats;
+}
+/**
+ * Get cached analysis result for a component path
+ *
+ * @param src - The component source path
+ * @returns The cached analysis result or null if not found/expired
+ */
+export declare function getCachedAnalysis(src: string): AnalysisReport | null;
+/**
+ * Store analysis result in cache
+ *
+ * @param src - The component source path
+ * @param result - The analysis result to cache
+ */
+export declare function setCachedAnalysis(src: string, result: AnalysisReport): void;
+/**
+ * Get cached resolved path for a source path
+ *
+ * @param src - The source path
+ * @returns The cached resolved path or null if not found/expired
+ */
+export declare function getCachedPath(src: string): string | null;
+/**
+ * Store resolved path in cache
+ *
+ * @param src - The source path
+ * @param resolved - The resolved path to cache
+ */
+export declare function setCachedPath(src: string, resolved: string): void;
+/**
+ * Get cached framework detection result for a source path
+ *
+ * @param src - The source path
+ * @returns The cached framework or null if not found/expired
+ */
+export declare function getCachedFramework(src: string): Framework | null;
+/**
+ * Store framework detection result in cache
+ *
+ * @param src - The source path
+ * @param framework - The detected framework to cache
+ */
+export declare function setCachedFramework(src: string, framework: Framework): void;
+/**
+ * Clear all caches
+ * Useful for testing or when file structure changes
+ */
+export declare function clearCache(): void;
+/**
+ * Clear cache for a specific component path
+ * Useful for HMR when a specific file changes
+ *
+ * @param src - The component source path to invalidate
+ */
+export declare function invalidateCacheForPath(src: string): void;
+/**
+ * Configure cache settings
+ *
+ * @param config - Partial configuration to merge with defaults
+ */
+export declare function configureCache(config: Partial<CacheConfig>): void;
+/**
+ * Get current cache configuration
+ *
+ * @returns The current cache configuration
+ */
+export declare function getCacheConfig(): CacheConfig;
+/**
+ * Get cache statistics for monitoring and debugging
+ * Only logs in development mode
+ *
+ * @returns Current cache statistics
+ */
+export declare function getCacheStats(): CacheStats;
+/**
+ * Log cache statistics to console (dev mode only)
+ * Useful for debugging and performance monitoring
+ */
+export declare function logCacheStats(): void;
+/**
+ * Get the raw cache instance (for testing purposes only)
+ * @internal
+ */
+export declare function _getCache(): IslandRenderCache;
+/**
+ * Invalidate cache entries for a specific file path
+ * Called when a component file changes during development
+ *
+ * @param filePath - The path of the changed file
+ * @returns Number of cache entries invalidated
+ */
+export declare function invalidateCacheForFile(filePath: string): number;
+/**
+ * Check if a file path is an island component file
+ * Used to determine if cache invalidation is needed
+ *
+ * @param filePath - The file path to check
+ * @returns True if the file is an island component
+ */
+export declare function isIslandComponentFile(filePath: string): boolean;
+/**
+ * Clear all caches when file structure changes significantly
+ * Called when files are added or removed
+ */
+export declare function clearPathCacheOnStructureChange(): void;
+/**
+ * Alias for clearCache - provides a more descriptive name for external use
+ * Clears all island render caches
+ */
+export declare function clearIslandCache(): void;