@useavalon/avalon 0.1.12 → 0.1.13

package/src/core/integrations/loader.ts

@@ -0,0 +1,125 @@
+import { registry } from "./registry.ts";
+import type { Integration } from "@useavalon/core";
+
+/**
+ * Cache for loaded integrations to avoid repeated dynamic imports
+ */
+const integrationCache = new Map<string, Integration>();
+
+/**
+ * Load an integration by name, using cache if available
+ */
+export async function loadIntegration(framework: string): Promise<Integration> {
+  // Check cache first
+  if (integrationCache.has(framework)) {
+    return integrationCache.get(framework)!;
+  }
+
+  // Load from registry (which handles dynamic imports)
+  const integration = await registry.load(framework);
+  
+  // Cache the loaded integration
+  integrationCache.set(framework, integration);
+  
+  return integration;
+}
+
+/**
+ * Detect framework from file path and load the appropriate integration
+ */
+export async function detectAndLoadIntegration(src: string): Promise<Integration> {
+  const framework = detectFrameworkFromPath(src);
+  return await loadIntegration(framework);
+}
+
+/**
+ * Detect framework from file path based on extension and naming conventions
+ */
+export function detectFrameworkFromPath(src: string): string {
+  // Vue files
+  if (src.endsWith(".vue")) {
+    return "vue";
+  }
+  
+  // Svelte files
+  if (src.endsWith(".svelte")) {
+    return "svelte";
+  }
+  
+  // Solid files (convention: .solid.tsx or .solid.jsx)
+  if (src.includes(".solid.")) {
+    return "solid";
+  }
+  
+  // Qwik files (convention: .qwik.tsx or .qwik.jsx)
+  if (src.includes(".qwik.")) {
+    return "qwik";
+  }
+  
+  // Default to Preact for .tsx and .jsx files
+  return "preact";
+}
+
+/**
+ * Detect framework from file content by analyzing imports and patterns
+ */
+export function detectFrameworkFromContent(
+  src: string,
+  content?: string
+): string {
+  // First try path-based detection
+  const pathFramework = detectFrameworkFromPath(src);
+  
+  // If we have a definitive answer from path, use it
+  if (pathFramework !== "preact" || !content) {
+    return pathFramework;
+  }
+  
+  // For .tsx/.jsx files, analyze content to distinguish between Preact and Solid
+  if (content.includes("solid-js")) {
+    return "solid";
+  }
+  
+  if (content.includes("@builder.io/qwik")) {
+    return "qwik";
+  }
+  
+  if (content.includes("preact")) {
+    return "preact";
+  }
+  
+  // Default to Preact
+  return "preact";
+}
+
+/**
+ * Preload integrations for the given frameworks
+ * Useful for warming up the cache during build or startup
+ */
+export async function preloadIntegrations(frameworks: string[]): Promise<void> {
+  await Promise.all(
+    frameworks.map(framework => loadIntegration(framework))
+  );
+}
+
+/**
+ * Get all currently loaded integrations
+ */
+export function getLoadedIntegrations(): Integration[] {
+  return Array.from(integrationCache.values());
+}
+
+/**
+ * Clear the integration cache
+ * Useful for testing or hot module replacement
+ */
+export function clearIntegrationCache(): void {
+  integrationCache.clear();
+}
+
+/**
+ * Check if an integration is loaded in cache
+ */
+export function isIntegrationLoaded(framework: string): boolean {
+  return integrationCache.has(framework);
+}

package/src/core/integrations/registry.ts

@@ -0,0 +1,175 @@
+import type { Integration } from "@useavalon/core";
+import { dirname, join } from "node:path";
+import { statSync } from "node:fs";
+
+/**
+ * Find the root of the Avalon monorepo by looking for packages/integrations
+ */
+function findMonorepoRoot(): string {
+  let currentDir = process.cwd();
+
+  // Walk up the directory tree looking for packages/integrations
+  for (let i = 0; i < 10; i++) {
+    try {
+      const integrationsPath = join(currentDir, "packages", "integrations");
+      const stat = statSync(integrationsPath);
+      if (stat.isDirectory()) {
+        return currentDir;
+      }
+    } catch {
+      // Directory doesn't exist, try parent
+    }
+
+    const parent = dirname(currentDir);
+    if (parent === currentDir) {
+      // Reached root, stop
+      break;
+    }
+    currentDir = parent;
+  }
+
+  // Fallback to cwd
+  return process.cwd();
+}
+
+/**
+ * IntegrationRegistry manages loaded framework integrations.
+ * It provides registration, retrieval, and dynamic loading of integrations.
+ */
+export class IntegrationRegistry {
+  private readonly integrations = new Map<string, Integration>();
+  private readonly loadingPromises = new Map<string, Promise<Integration>>();
+
+  /**
+   * Register an integration instance
+   */
+  register(integration: Integration): void {
+    if (!integration.name) {
+      throw new Error("Integration must have a name");
+    }
+    this.integrations.set(integration.name, integration);
+  }
+
+  /**
+   * Get a registered integration by name
+   */
+  get(name: string): Integration | undefined {
+    return this.integrations.get(name);
+  }
+
+  /**
+   * Check if an integration is registered
+   */
+  has(name: string): boolean {
+    return this.integrations.has(name);
+  }
+
+  /**
+   * Dynamically load an integration by name
+   * Returns cached integration if already loaded
+   */
+  async load(name: string): Promise<Integration> {
+    // Check if already loaded
+    const existing = this.integrations.get(name);
+    if (existing) {
+      return existing;
+    }
+
+    // Check if currently loading (prevent duplicate loads)
+    const loadingPromise = this.loadingPromises.get(name);
+    if (loadingPromise) {
+      return loadingPromise;
+    }
+
+    // Start loading
+    const promise = this.loadIntegration(name);
+    this.loadingPromises.set(name, promise);
+
+    try {
+      const integration = await promise;
+      this.register(integration);
+      return integration;
+    } finally {
+      this.loadingPromises.delete(name);
+    }
+  }
+
+  private async loadIntegration(name: string): Promise<Integration> {
+    const integrationKey = `${name}Integration`;
+
+    // 1. Try loading from the installed npm package first (@useavalon/<name>)
+    try {
+      const packageName = `@useavalon/${name}`;
+      const module = await import(/* @vite-ignore */ packageName);
+      const integration = module[integrationKey] || module.default;
+      if (integration) return integration as Integration;
+    } catch {
+      // Package not installed or import failed — try monorepo path
+    }
+
+    // 2. Monorepo fallback: resolve via packages/integrations/<name>/mod.ts
+    try {
+      const monorepoRoot = findMonorepoRoot();
+      const integrationPath = join(monorepoRoot, "packages", "integrations", name, "mod.ts");
+      const fileUrl = `file://${integrationPath}`;
+      const module = await import(/* @vite-ignore */ fileUrl);
+      const integration = module[integrationKey] || module.default;
+      if (integration) return integration as Integration;
+    } catch {
+      // Monorepo path also failed
+    }
+
+    throw new Error(
+      `Failed to load integration for framework '${name}'. ` +
+      `Make sure @useavalon/${name} is installed.\n` +
+      `Install it with: bun add @useavalon/${name}`,
+    );
+  }
+
+  /**
+   * Get all registered integrations
+   */
+  getAll(): Integration[] {
+    return Array.from(this.integrations.values());
+  }
+
+  /**
+   * Get all registered integration names
+   */
+  getAllNames(): string[] {
+    return Array.from(this.integrations.keys());
+  }
+
+  /**
+   * Unregister an integration
+   */
+  unregister(name: string): boolean {
+    return this.integrations.delete(name);
+  }
+
+  /**
+   * Clear all registered integrations
+   */
+  clear(): void {
+    this.integrations.clear();
+    this.loadingPromises.clear();
+  }
+
+  /**
+   * Get the count of registered integrations
+   */
+  get size(): number {
+    return this.integrations.size;
+  }
+}
+
+// Global singleton registry instance
+// Use globalThis to ensure the registry is shared across all module contexts
+// This is important because Vite's ssrLoadModule creates new module contexts
+declare global {
+  var __avalonIntegrationRegistry: IntegrationRegistry | undefined;
+}
+
+globalThis.__avalonIntegrationRegistry ??= new IntegrationRegistry();
+
+export const registry = globalThis.__avalonIntegrationRegistry;

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

@@ -0,0 +1,325 @@
+import type { IslandState } from '../../schemas/layout.ts';
+import type { IIslandPersistence } from '../../types/layout.ts';
+import { IslandStateSerializer } from './island-state-serializer.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 class IslandPersistence implements IIslandPersistence {
+	private storageType: 'session' | 'local';
+	private keyPrefix: string;
+	private storage: Storage | null = null;
+
+	constructor(
+		options: {
+			storageType?: 'session' | 'local';
+			keyPrefix?: string;
+		} = {}
+	) {
+		this.storageType = options.storageType || 'session';
+		this.keyPrefix = options.keyPrefix || 'island-state';
+
+		// Initialize storage if available (browser environment)
+		if (typeof window !== 'undefined') {
+			this.storage = this.storageType === 'session' ? sessionStorage : localStorage;
+		}
+	}
+
+	/**
+	 * Save island state to browser storage
+	 */
+	saveState(id: string, state: IslandState): void {
+		if (!this.storage) {
+			console.warn('Island persistence: Storage not available (server-side or unsupported browser)');
+			return;
+		}
+
+		try {
+			const key = this.getStorageKey(id);
+
+			// Use the IslandStateSerializer for proper serialization
+			const serializedState = IslandStateSerializer.serialize({
+				state,
+				timestamp: Date.now(),
+				version: '1.0',
+			});
+
+			this.storage.setItem(key, serializedState);
+			console.log(`Island state saved for ${id}`);
+		} catch (error) {
+			console.error(`Failed to save island state for ${id}:`, error);
+		}
+	}
+
+	/**
+	 * Load island state from browser storage
+	 */
+	loadState(id: string): IslandState | null {
+		if (!this.storage) {
+			console.warn('Island persistence: Storage not available (server-side or unsupported browser)');
+			return null;
+		}
+
+		try {
+			const key = this.getStorageKey(id);
+			const serializedState = this.storage.getItem(key);
+
+			if (!serializedState) {
+				return null;
+			}
+
+			// Use the IslandStateSerializer for proper deserialization
+			const parsed = IslandStateSerializer.deserialize(serializedState);
+
+			// Validate the stored data structure
+			if (!parsed.state || !parsed.timestamp || !parsed.version) {
+				console.warn(`Invalid island state format for ${id}, clearing...`);
+				this.clearState(id);
+				return null;
+			}
+
+			console.log(`Island state loaded for ${id}`);
+			return parsed.state as Record<string, unknown>;
+		} catch (error) {
+			console.error(`Failed to load island state for ${id}:`, error);
+			// Clear corrupted state
+			this.clearState(id);
+			return null;
+		}
+	}
+
+	/**
+	 * Clear island state from browser storage
+	 */
+	clearState(id: string): void {
+		if (!this.storage) {
+			return;
+		}
+
+		try {
+			const key = this.getStorageKey(id);
+			this.storage.removeItem(key);
+			console.log(`Island state cleared for ${id}`);
+		} catch (error) {
+			console.error(`Failed to clear island state for ${id}:`, error);
+		}
+	}
+
+	/**
+	 * Check if state exists for an island
+	 */
+	hasState(id: string): boolean {
+		if (!this.storage) {
+			return false;
+		}
+
+		try {
+			const key = this.getStorageKey(id);
+			return this.storage.getItem(key) !== null;
+		} catch (error) {
+			console.error(`Failed to check island state for ${id}:`, error);
+			return false;
+		}
+	}
+
+	/**
+	 * Get all stored island IDs
+	 */
+	getStoredIds(): string[] {
+		if (!this.storage) {
+			return [];
+		}
+
+		try {
+			const ids: string[] = [];
+			const prefixLength = this.keyPrefix.length + 1; // +1 for the separator
+
+			for (let i = 0; i < this.storage.length; i++) {
+				const key = this.storage.key(i);
+				if (key && key.startsWith(this.keyPrefix + ':')) {
+					ids.push(key.substring(prefixLength));
+				}
+			}
+
+			return ids;
+		} catch (error) {
+			console.error('Failed to get stored island IDs:', error);
+			return [];
+		}
+	}
+
+	/**
+	 * Clear all stored states
+	 */
+	clearAllStates(): void {
+		if (!this.storage) {
+			return;
+		}
+
+		try {
+			const keysToRemove: string[] = [];
+
+			for (let i = 0; i < this.storage.length; i++) {
+				const key = this.storage.key(i);
+				if (key && key.startsWith(this.keyPrefix + ':')) {
+					keysToRemove.push(key);
+				}
+			}
+
+			keysToRemove.forEach(key => this.storage!.removeItem(key));
+			console.log(`Cleared ${keysToRemove.length} island states`);
+		} catch (error) {
+			console.error('Failed to clear all island states:', error);
+		}
+	}
+
+	/**
+	 * Get the storage key for an island ID
+	 */
+	private getStorageKey(id: string): string {
+		return `${this.keyPrefix}:${id}`;
+	}
+
+	/**
+	 * Get current storage configuration
+	 */
+	getConfig(): { storageType: string; keyPrefix: string; available: boolean } {
+		return {
+			storageType: this.storageType,
+			keyPrefix: this.keyPrefix,
+			available: this.storage !== null,
+		};
+	}
+
+	/**
+	 * Get storage usage statistics
+	 */
+	getStorageStats(): { totalKeys: number; islandKeys: number; estimatedSize: number } {
+		if (!this.storage) {
+			return { totalKeys: 0, islandKeys: 0, estimatedSize: 0 };
+		}
+
+		try {
+			let islandKeys = 0;
+			let estimatedSize = 0;
+
+			for (let i = 0; i < this.storage.length; i++) {
+				const key = this.storage.key(i);
+				if (key && key.startsWith(this.keyPrefix + ':')) {
+					islandKeys++;
+					const value = this.storage.getItem(key);
+					if (value) {
+						estimatedSize += key.length + value.length;
+					}
+				}
+			}
+
+			return {
+				totalKeys: this.storage.length,
+				islandKeys,
+				estimatedSize,
+			};
+		} catch (error) {
+			console.error('Failed to get storage stats:', error);
+			return { totalKeys: 0, islandKeys: 0, estimatedSize: 0 };
+		}
+	}
+
+	/**
+	 * JSON.stringify replacer function to handle special types
+	 */
+	private replacer(key: string, value: unknown): unknown {
+		// Handle Date objects
+		if (value instanceof Date) {
+			return {
+				__type: 'Date',
+				__value: value.toISOString(),
+			};
+		}
+
+		// Handle RegExp objects
+		if (value instanceof RegExp) {
+			return {
+				__type: 'RegExp',
+				__value: {
+					source: value.source,
+					flags: value.flags,
+				},
+			};
+		}
+
+		// Handle Map objects
+		if (value instanceof Map) {
+			return {
+				__type: 'Map',
+				__value: Array.from(value.entries()),
+			};
+		}
+
+		// Handle Set objects
+		if (value instanceof Set) {
+			return {
+				__type: 'Set',
+				__value: Array.from(value.values()),
+			};
+		}
+
+		// Handle functions (convert to null - functions can't be serialized)
+		if (typeof value === 'function') {
+			console.warn(`Function found in island state at key "${key}", converting to null`);
+			return null;
+		}
+
+		// Handle undefined (convert to null)
+		if (value === undefined) {
+			return null;
+		}
+
+		return value;
+	}
+
+	/**
+	 * JSON.parse reviver function to restore special types
+	 */
+	private reviver(key: string, value: unknown): unknown {
+		// Check if this is a special type object
+		if (value && typeof value === 'object') {
+			const obj = value as Record<string, unknown>;
+			if (obj.__type && obj.__value !== undefined) {
+				switch (obj.__type) {
+					case 'Date':
+						return new Date(obj.__value as string);
+
+					case 'RegExp': {
+						const rv = obj.__value as { source: string; flags: string };
+						return new RegExp(rv.source, rv.flags);
+					}
+
+					case 'Map':
+						return new Map(obj.__value as Iterable<[unknown, unknown]>);
+
+					case 'Set':
+						return new Set(obj.__value as Iterable<unknown>);
+
+					default:
+						console.warn(`Unknown special type "${obj.__type}" in serialized state`);
+						return obj.__value;
+				}
+			}
+		}
+
+		return value;
+	}
+}
+
+/**
+ * Default island persistence instance
+ * Uses sessionStorage by default for better privacy and performance
+ */
+export const defaultIslandPersistence = new IslandPersistence({
+	storageType: 'session',
+	keyPrefix: 'island-state',
+});