@useavalon/avalon 0.1.9 → 0.1.11

package/src/client/adapters/vue-adapter.js

@@ -0,0 +1,278 @@
+/**
+* Vue HMR Adapter
+* 
+* Provides Hot Module Replacement support for Vue 3 components.
+* Integrates with @vitejs/plugin-vue to preserve reactive state during updates.
+* Uses Vue's __VUE_HMR_RUNTIME__ API for hot updates.
+* 
+* Requirements: 2.3
+*/
+/// <reference lib="dom" />
+import { BaseFrameworkAdapter } from "../framework-adapter.js";
+/**
+* Vue HMR Adapter
+* 
+* Leverages Vue's HMR capabilities (provided by @vitejs/plugin-vue) to:
+* - Preserve reactive state across updates
+* - Maintain computed properties
+* - Handle component updates without full remount
+* 
+* Vue HMR works through the __VUE_HMR_RUNTIME__ API:
+* 1. When a component module is updated, Vite sends an HMR event
+* 2. We use __VUE_HMR_RUNTIME__.reload() to hot-reload the component
+* 3. Vue preserves reactive state automatically through its reactivity system
+* 4. The component re-renders with preserved state
+*/
+export class VueHMRAdapter extends BaseFrameworkAdapter {
+	name = "vue";
+	/**
+	* Store Vue app instances for each island to enable proper updates
+	*/
+	apps = new WeakMap();
+	/**
+	* Store component IDs for HMR runtime
+	*/
+	componentIds = new WeakMap();
+	/**
+	* Check if a component is a Vue component
+	* 
+	* Vue components can be:
+	* - Component options objects (with setup, data, render, template, etc.)
+	* - Setup functions (Composition API)
+	* - SFC compiled components
+	*/
+	canHandle(component) {
+		if (!component) return false;
+		// Check if it's a function (setup function or render function)
+		if (typeof component === "function") {
+			// Vue setup functions or render functions
+			return true;
+		}
+		// Check if it's a component options object
+		if (typeof component !== "object") {
+			return false;
+		}
+		const obj = component;
+		// Check for Vue-specific properties
+		const hasVueProperties = "setup" in obj || "data" in obj || "render" in obj || "template" in obj || "props" in obj || "computed" in obj || "methods" in obj || "components" in obj || "emits" in obj || "mounted" in obj || "created" in obj || "beforeMount" in obj || "beforeCreate" in obj;
+		if (hasVueProperties) {
+			return true;
+		}
+		// Check for __vccOpts (Vue SFC compiled component marker)
+		if ("__vccOpts" in obj) {
+			return true;
+		}
+		return false;
+	}
+	/**
+	* Preserve Vue component state before HMR update
+	* 
+	* Vue's reactivity system handles most state preservation automatically.
+	* We capture additional DOM state and props for fallback.
+	*/
+	preserveState(island) {
+		try {
+			// Get base DOM state
+			const baseSnapshot = super.preserveState(island);
+			if (!baseSnapshot) return null;
+			// Get Vue-specific data
+			const propsAttr = island.getAttribute("data-props");
+			const capturedProps = propsAttr ? JSON.parse(propsAttr) : {};
+			// Try to get component name from the island
+			const src = island.getAttribute("data-src") || "";
+			const componentName = this.extractComponentName(src);
+			// Try to capture reactive data from the Vue instance
+			// Note: This is best-effort, as Vue's internal state is not easily accessible
+			// Vue's HMR runtime will handle most state preservation automatically
+			const reactiveData = this.captureReactiveData(island);
+			const vueSnapshot = {
+				...baseSnapshot,
+				framework: "vue",
+				data: {
+					componentName,
+					capturedProps,
+					reactiveData
+				}
+			};
+			return vueSnapshot;
+		} catch (error) {
+			console.warn("Failed to preserve Vue state:", error);
+			return null;
+		}
+	}
+	/**
+	* Update Vue component with HMR
+	* 
+	* This method integrates with Vue's HMR API:
+	* 1. Vue HMR is automatically enabled by @vitejs/plugin-vue
+	* 2. When a module updates, Vite sends an HMR event
+	* 3. We use __VUE_HMR_RUNTIME__ to reload the component
+	* 4. Vue preserves reactive state automatically
+	* 5. The component re-renders with preserved state
+	*/
+	async update(island, newComponent, props) {
+		if (!this.canHandle(newComponent)) {
+			throw new Error("Component is not a valid Vue component");
+		}
+		const Component = newComponent;
+		try {
+			// Dynamically import Vue at runtime
+			// This is resolved by Vite in the browser
+			const vueModule = await import("vue");
+			const { createApp } = vueModule;
+			// Check if we have an existing app
+			const existingApp = this.apps.get(island);
+			const componentId = this.componentIds.get(island);
+			// Try to use Vue HMR runtime if available
+			const hmrRuntime = globalThis.__VUE_HMR_RUNTIME__;
+			if (hmrRuntime && componentId) {
+				// Use Vue's HMR runtime for hot reload
+				// This preserves reactive state automatically
+				try {
+					hmrRuntime.reload(componentId, Component);
+					// If we have an existing app, we're done
+					// Vue HMR runtime handles the update
+					if (existingApp) {
+						return;
+					}
+				} catch (error) {
+					console.warn("Vue HMR runtime reload failed, falling back to full remount:", error);
+				}
+			}
+			if (existingApp) {
+				// Unmount existing app
+				try {
+					existingApp.unmount();
+				} catch (error) {
+					console.warn("Failed to unmount existing Vue app:", error);
+				}
+			}
+			// Create new app and mount
+			const app = createApp(Component, props);
+			// Configure error handling
+			app.config.errorHandler = (err, _instance, info) => {
+				console.error("Vue component error during HMR:", err, info);
+			};
+			// Mount with hydration
+			app.mount(island, true);
+			// Store app and component ID for future updates
+			this.apps.set(island, app);
+			// Generate component ID for HMR runtime
+			const src = island.getAttribute("data-src") || "";
+			const newComponentId = this.generateComponentId(src);
+			this.componentIds.set(island, newComponentId);
+			// Register with HMR runtime if available
+			if (hmrRuntime) {
+				hmrRuntime.createRecord(newComponentId, Component);
+			}
+			// Mark as hydrated
+			island.setAttribute("data-hydrated", "true");
+			island.setAttribute("data-hydration-status", "success");
+		} catch (error) {
+			console.error("Vue HMR update failed:", error);
+			island.setAttribute("data-hydration-status", "error");
+			throw error;
+		}
+	}
+	/**
+	* Restore Vue component state after HMR update
+	* 
+	* Vue's reactivity system handles most state restoration automatically.
+	* We restore DOM state (scroll, focus, form values) as a supplement.
+	*/
+	restoreState(island, state) {
+		try {
+			// Restore DOM state (scroll, focus, form values)
+			super.restoreState(island, state);
+		} catch (error) {
+			console.warn("Failed to restore Vue state:", error);
+		}
+	}
+	/**
+	* Handle errors during Vue HMR update
+	* 
+	* Provides Vue-specific error handling with helpful messages
+	*/
+	handleError(island, error) {
+		console.error("Vue HMR error:", error);
+		// Use base error handling
+		super.handleError(island, error);
+		// Add Vue-specific error information
+		const errorIndicator = island.querySelector(".hmr-error-indicator");
+		if (errorIndicator) {
+			const errorMessage = error.message;
+			// Provide helpful hints for common Vue errors
+			let hint = "";
+			if (errorMessage.includes("reactive") || errorMessage.includes("ref")) {
+				hint = " (Hint: Check reactive state usage - refs must be accessed with .value)";
+			} else if (errorMessage.includes("render")) {
+				hint = " (Hint: Check component render function or template for errors)";
+			} else if (errorMessage.includes("hydration") || errorMessage.includes("mismatch")) {
+				hint = " (Hint: Server and client render must match)";
+			} else if (errorMessage.includes("setup")) {
+				hint = " (Hint: Check setup function - it should return render function or object)";
+			}
+			errorIndicator.textContent = `Vue HMR Error: ${errorMessage}${hint}`;
+		}
+	}
+	/**
+	* Extract component name from source path
+	* Used for debugging and error messages
+	*/
+	extractComponentName(src) {
+		const parts = src.split("/");
+		const filename = parts[parts.length - 1];
+		return filename.replace(/\.(vue|tsx?|jsx?)$/, "");
+	}
+	/**
+	* Generate a unique component ID for HMR runtime
+	*/
+	generateComponentId(src) {
+		// Use the source path as the component ID
+		// This ensures consistency across HMR updates
+		return src.replace(/[^a-zA-Z0-9]/g, "_");
+	}
+	/**
+	* Attempt to capture reactive data from Vue instance
+	* This is best-effort and may not work in all cases
+	*/
+	captureReactiveData(island) {
+		try {
+			// Vue 3 stores instance data on the element's __vueParentComponent
+			// This is internal API and may change, so we wrap in try-catch
+			const vueInstance = island.__vueParentComponent;
+			if (vueInstance && typeof vueInstance === "object") {
+				// Try to extract data from the instance
+				// This is very fragile and depends on Vue internals
+				const data = vueInstance.data;
+				if (data && typeof data === "object") {
+					return { ...data };
+				}
+			}
+		} catch (error) {
+			// Silently fail - this is best-effort
+			console.debug("Could not capture Vue reactive data:", error);
+		}
+		return undefined;
+	}
+	/**
+	* Clean up Vue app when island is removed
+	* This should be called when an island is unmounted
+	*/
+	unmount(island) {
+		const app = this.apps.get(island);
+		if (app) {
+			try {
+				app.unmount();
+				this.apps.delete(island);
+				this.componentIds.delete(island);
+			} catch (error) {
+				console.warn("Failed to unmount Vue app:", error);
+			}
+		}
+	}
+}
+/**
+* Create and export a singleton instance of the Vue HMR adapter
+*/
+export const vueAdapter = new VueHMRAdapter();

package/src/client/components.js

@@ -0,0 +1,23 @@
+/**
+* Client-safe component exports for use in island components.
+*
+* Import from '@useavalon/avalon/client' instead of '@useavalon/avalon' when
+* you need framework components inside islands. The main entry point
+* re-exports server-only code (nitro, h3, vite plugins) that can't
+* be bundled for the browser.
+*/
+// Persistent islands
+export { PersistentIsland } from "../components/PersistentIsland.tsx";
+export { usePersistentIslandContext, PersistentIslandProvider, createPersistentIslandContext } from "../core/islands/persistent-island-context.tsx";
+export { usePersistentState } from "../core/islands/use-persistent-state.js";
+export { IslandPersistence, defaultIslandPersistence } from "../core/islands/island-persistence.js";
+export { IslandStateSerializer } from "../core/islands/island-state-serializer.js";
+// Error boundaries
+export { IslandErrorBoundary, withIslandErrorBoundary } from "../components/IslandErrorBoundary.tsx";
+export { LayoutErrorBoundary } from "../components/LayoutErrorBoundary.tsx";
+export { LayoutDataErrorBoundary } from "../components/LayoutDataErrorBoundary.tsx";
+export { StreamingErrorBoundary, withStreamingErrorBoundary } from "../components/StreamingErrorBoundary.tsx";
+// Streaming
+export { StreamingLayout, StreamingSuspense, withStreaming, useStreamingState } from "../components/StreamingLayout.tsx";
+// Image optimization
+export { Image } from "../components/Image.tsx";

package/src/client/css-hmr-handler.js

@@ -0,0 +1,263 @@
+/**
+* CSS HMR Handler class
+* Manages CSS hot updates without page reload
+*/
+export class CSSHMRHandler {
+	cssModuleMap = new Map();
+	styleElementMap = new Map();
+	/**
+	* Handle CSS update from Vite HMR
+	*/
+	handleCSSUpdate(update) {
+		const updateInfo = this.classifyCSSUpdate(update);
+		switch (updateInfo.type) {
+			case "global":
+				this.handleGlobalCSSUpdate(updateInfo);
+				break;
+			case "module":
+				this.handleCSSModuleUpdate(updateInfo);
+				break;
+			case "scoped":
+				this.handleScopedCSSUpdate(updateInfo);
+				break;
+		}
+	}
+	/**
+	* Classify the type of CSS update
+	*/
+	classifyCSSUpdate(update) {
+		const path = update.path || update.acceptedPath;
+		// Check if it's a CSS module
+		if (path.includes(".module.css") || path.includes(".module.scss")) {
+			return {
+				type: "module",
+				path,
+				timestamp: update.timestamp
+			};
+		}
+		// Check if it's a scoped style (Svelte or Vue)
+		if (path.includes(".svelte") || path.includes(".vue")) {
+			return {
+				type: "scoped",
+				path,
+				timestamp: update.timestamp
+			};
+		}
+		// Default to global CSS
+		return {
+			type: "global",
+			path,
+			timestamp: update.timestamp
+		};
+	}
+	/**
+	* Handle global CSS file update
+	* Injects updated styles without page reload
+	*/
+	handleGlobalCSSUpdate(info) {
+		try {
+			// Find existing style element for this CSS file
+			const existingStyle = this.styleElementMap.get(info.path);
+			if (existingStyle) {
+				// Remove old style element
+				existingStyle.remove();
+				this.styleElementMap.delete(info.path);
+			}
+			// Vite automatically injects the updated CSS via its HMR mechanism
+			// We just need to ensure old styles are removed
+			// The new styles will be injected by Vite's CSS handling
+			// Find the newly injected style element
+			// Vite adds a data-vite-dev-id attribute to style elements
+			const newStyle = document.querySelector(`style[data-vite-dev-id*="${this.getFileId(info.path)}"]`);
+			if (newStyle) {
+				this.styleElementMap.set(info.path, newStyle);
+			}
+			// Dispatch event for feedback
+			this.dispatchCSSUpdateEvent(info, true);
+		} catch (error) {
+			console.error(`Failed to update global CSS: ${info.path}`, error);
+			this.dispatchCSSUpdateEvent(info, false, error);
+			throw error;
+		}
+	}
+	/**
+	* Handle CSS module update
+	* Re-renders components using the updated CSS module
+	*/
+	handleCSSModuleUpdate(info) {
+		try {
+			const affectedIslands = this.findIslandsUsingCSSModule(info.path);
+			if (affectedIslands.length === 0) {
+				return;
+			}
+			for (const island of affectedIslands) {
+				this.triggerIslandRerender(island, info);
+			}
+			this.dispatchCSSUpdateEvent(info, true);
+		} catch (error) {
+			console.error(`[HMR] Failed to update CSS module: ${info.path}`, error);
+			this.dispatchCSSUpdateEvent(info, false, error);
+			throw error;
+		}
+	}
+	/**
+	* Handle scoped CSS update (Svelte/Vue)
+	* Updates only the affected component's styles
+	*/
+	handleScopedCSSUpdate(info) {
+		try {
+			const affectedIslands = this.findIslandsUsingComponent(info.path);
+			if (affectedIslands.length === 0) {
+				return;
+			}
+			this.dispatchCSSUpdateEvent(info, true);
+		} catch (error) {
+			console.error(`[HMR] Failed to update scoped CSS: ${info.path}`, error);
+			this.dispatchCSSUpdateEvent(info, false, error);
+			throw error;
+		}
+	}
+	/**
+	* Find islands that use a specific CSS module
+	*/
+	findIslandsUsingCSSModule(cssPath) {
+		const islands = [];
+		const normalizedPath = this.normalizePath(cssPath);
+		// Check cached mapping first
+		const cached = this.cssModuleMap.get(normalizedPath);
+		if (cached) {
+			return Array.from(cached);
+		}
+		// Find all islands
+		const allIslands = document.querySelectorAll("[data-src]");
+		for (const island of allIslands) {
+			const src = island.getAttribute("data-src");
+			if (!src) continue;
+			// Check if the island's component likely imports this CSS module
+			// This is a heuristic - we look for islands in the same directory
+			const componentDir = this.getDirectory(src);
+			const cssDir = this.getDirectory(cssPath);
+			if (componentDir === cssDir) {
+				islands.push(island);
+			}
+		}
+		// Cache the mapping
+		if (islands.length > 0) {
+			this.cssModuleMap.set(normalizedPath, new Set(islands));
+		}
+		return islands;
+	}
+	/**
+	* Find islands using a specific component file
+	*/
+	findIslandsUsingComponent(componentPath) {
+		const islands = [];
+		const normalizedPath = this.normalizePath(componentPath);
+		const allIslands = document.querySelectorAll("[data-src]");
+		for (const island of allIslands) {
+			const src = island.getAttribute("data-src");
+			if (!src) continue;
+			const normalizedSrc = this.normalizePath(src);
+			if (normalizedSrc === normalizedPath || normalizedSrc.includes(normalizedPath)) {
+				islands.push(island);
+			}
+		}
+		return islands;
+	}
+	/**
+	* Trigger re-render of an island to apply new CSS module classes
+	*/
+	triggerIslandRerender(island, info) {
+		// Dispatch event to trigger island re-render
+		// The HMR coordinator will handle the actual re-render
+		island.dispatchEvent(new CustomEvent("css-module-update", {
+			detail: {
+				cssPath: info.path,
+				timestamp: info.timestamp
+			},
+			bubbles: true
+		}));
+		// Also trigger a standard HMR update event
+		// This will be picked up by the HMR coordinator
+		const src = island.getAttribute("data-src");
+		if (src) {
+			island.dispatchEvent(new CustomEvent("hmr-update-required", {
+				detail: {
+					src,
+					reason: "css-module-update",
+					cssPath: info.path
+				},
+				bubbles: true
+			}));
+		}
+	}
+	/**
+	* Dispatch CSS update event for feedback
+	*/
+	dispatchCSSUpdateEvent(info, success, error) {
+		const event = new CustomEvent("css-hmr-update", {
+			detail: {
+				type: info.type,
+				path: info.path,
+				timestamp: info.timestamp,
+				success,
+				error: error?.message
+			},
+			bubbles: true
+		});
+		document.dispatchEvent(event);
+	}
+	/**
+	* Normalize a file path for comparison
+	*/
+	normalizePath(path) {
+		return path.replace(/\\/g, "/").replace(/^\//, "").replace(/\?.*$/, "").replace(/#.*$/, "");
+	}
+	/**
+	* Get directory from a file path
+	*/
+	getDirectory(path) {
+		const normalized = this.normalizePath(path);
+		const lastSlash = normalized.lastIndexOf("/");
+		return lastSlash >= 0 ? normalized.substring(0, lastSlash) : "";
+	}
+	/**
+	* Get file ID from path (for Vite's data-vite-dev-id)
+	*/
+	getFileId(path) {
+		const normalized = this.normalizePath(path);
+		// Vite uses the file path as the ID
+		return normalized;
+	}
+	/**
+	* Clear cached mappings
+	*/
+	clearCache() {
+		this.cssModuleMap.clear();
+		this.styleElementMap.clear();
+	}
+	/**
+	* Register an island as using a CSS module
+	* Useful for explicit tracking
+	*/
+	registerCSSModuleUsage(cssPath, island) {
+		const normalized = this.normalizePath(cssPath);
+		if (!this.cssModuleMap.has(normalized)) {
+			this.cssModuleMap.set(normalized, new Set());
+		}
+		this.cssModuleMap.get(normalized).add(island);
+	}
+}
+/**
+* Global CSS HMR handler instance
+*/
+let cssHandlerInstance = null;
+/**
+* Get or create the global CSS HMR handler instance
+*/
+export function getCSSHMRHandler() {
+	if (!cssHandlerInstance) {
+		cssHandlerInstance = new CSSHMRHandler();
+	}
+	return cssHandlerInstance;
+}