@useavalon/avalon 0.1.9 → 0.1.10

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

@@ -0,0 +1,223 @@
+/**
+* Preact HMR Adapter
+* 
+* Provides Hot Module Replacement support for Preact components.
+* Integrates with @preact/preset-vite to preserve hooks state and component tree during updates.
+* 
+* Requirements: 2.2
+*/
+/// <reference lib="dom" />
+import { BaseFrameworkAdapter } from "../framework-adapter.js";
+/**
+* Preact HMR Adapter
+* 
+* Leverages Preact's HMR capabilities (provided by @preact/preset-vite) to:
+* - Preserve hooks state across updates
+* - Maintain component tree structure
+* - Handle component updates without full remount
+* 
+* Preact HMR works similarly to React Fast Refresh:
+* 1. Detecting when a component module is updated
+* 2. Preserving the component tree (internal state representation)
+* 3. Re-rendering with the new component definition
+* 4. Restoring hooks state from the preserved tree
+*/
+export class PreactHMRAdapter extends BaseFrameworkAdapter {
+	name = "preact";
+	/**
+	* Store Preact component instances for each island to enable proper updates
+	*/
+	instances = new WeakMap();
+	/**
+	* Check if a component is a Preact component
+	* 
+	* Preact components can be:
+	* - Function components (including hooks)
+	* - Class components (extending Preact Component)
+	* - Forward refs
+	* - Memoized components
+	* 
+	* Preact is API-compatible with React, so detection is similar
+	*/
+	canHandle(component) {
+		if (!component) return false;
+		// Check if it's a function (function component or class)
+		if (typeof component === "function") {
+			// Check for Preact/React-specific properties on the function
+			const comp = component;
+			// Class components have isReactComponent on prototype
+			// (Preact uses the same marker for compatibility)
+			const proto = component.prototype;
+			if (proto && proto.isReactComponent) {
+				return true;
+			}
+			// Check for Preact element symbol (for wrapped components)
+			if (comp.$typeof) {
+				return true;
+			}
+			// Assume any function could be a Preact component
+			// Preact HMR will handle validation
+			return true;
+		}
+		// Check for Preact VNode types
+		if (typeof component !== "object") {
+			return false;
+		}
+		const obj = component;
+		// Check for Preact VNode symbol
+		if (obj.$typeof) {
+			return true;
+		}
+		// Check for wrapped components (HOCs, memo, forwardRef)
+		if (obj.type && typeof obj.type === "function") {
+			return true;
+		}
+		return false;
+	}
+	/**
+	* Preserve Preact component state before HMR update
+	* 
+	* Preact HMR handles most state preservation automatically through
+	* the component tree. 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 Preact-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);
+			const preactSnapshot = {
+				...baseSnapshot,
+				framework: "preact",
+				data: {
+					componentName,
+					capturedProps
+				}
+			};
+			return preactSnapshot;
+		} catch (error) {
+			console.warn("Failed to preserve Preact state:", error);
+			return null;
+		}
+	}
+	/**
+	* Update Preact component with HMR
+	* 
+	* This method integrates with Preact HMR:
+	* 1. Preact HMR is automatically enabled by @preact/preset-vite
+	* 2. When a module updates, Vite sends an HMR event
+	* 3. We re-hydrate the component with the new definition
+	* 4. Preact HMR preserves hooks 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 Preact component");
+		}
+		const Component = newComponent;
+		try {
+			// Dynamically import Preact at runtime
+			// This is resolved by Vite in the browser
+			const preactModule = await import("preact");
+			const { h, hydrate } = preactModule;
+			// Check if we have an existing instance
+			const existingInstance = this.instances.get(island);
+			if (existingInstance) {
+				// Update existing component
+				// Preact HMR will preserve hooks state automatically
+				const vnode = h(Component, props);
+				hydrate(vnode, island);
+			} else {
+				// Create new instance and hydrate
+				// This happens on first HMR update or if instance was lost
+				const vnode = h(Component, props);
+				hydrate(vnode, island);
+				// Store instance for future updates
+				this.instances.set(island, Component);
+			}
+			// Mark as hydrated
+			island.setAttribute("data-hydrated", "true");
+			island.setAttribute("data-hydration-status", "success");
+		} catch (error) {
+			console.error("Preact HMR update failed:", error);
+			island.setAttribute("data-hydration-status", "error");
+			throw error;
+		}
+	}
+	/**
+	* Restore Preact component state after HMR update
+	* 
+	* Preact HMR 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 Preact state:", error);
+		}
+	}
+	/**
+	* Handle errors during Preact HMR update
+	* 
+	* Provides Preact-specific error handling with helpful messages
+	*/
+	handleError(island, error) {
+		console.error("Preact HMR error:", error);
+		// Use base error handling
+		super.handleError(island, error);
+		// Add Preact-specific error information
+		const errorIndicator = island.querySelector(".hmr-error-indicator");
+		if (errorIndicator) {
+			const errorMessage = error.message;
+			// Provide helpful hints for common Preact errors
+			let hint = "";
+			if (errorMessage.includes("hooks")) {
+				hint = " (Hint: Check hooks usage - hooks must be called in the same order)";
+			} else if (errorMessage.includes("render")) {
+				hint = " (Hint: Check component render method for errors)";
+			} else if (errorMessage.includes("hydration") || errorMessage.includes("hydrate")) {
+				hint = " (Hint: Server and client render must match)";
+			}
+			errorIndicator.textContent = `Preact 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(/\.(tsx?|jsx?)$/, "");
+	}
+	/**
+	* Clean up Preact component when island is removed
+	* This should be called when an island is unmounted
+	*/
+	unmount(island) {
+		const instance = this.instances.get(island);
+		if (instance) {
+			try {
+				// Preact doesn't have an explicit unmount API like React
+				// We just clear the instance reference
+				this.instances.delete(island);
+				// Clear the island content to trigger cleanup
+				// Preact will handle component lifecycle cleanup
+				island.innerHTML = "";
+			} catch (error) {
+				console.warn("Failed to unmount Preact component:", error);
+			}
+		}
+	}
+}
+/**
+* Create and export a singleton instance of the Preact HMR adapter
+*/
+export const preactAdapter = new PreactHMRAdapter();

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

@@ -0,0 +1,259 @@
+/**
+* Qwik HMR Adapter
+*
+* Provides Hot Module Replacement support for Qwik components.
+* Qwik is fundamentally different from other frameworks — it uses resumability
+* instead of hydration. Components are serialized on the server and resumed
+* on the client without replaying application logic.
+*
+* Key Qwik concepts:
+* - Resumability: No hydration step — the app resumes from serialized state
+* - Lazy loading via $: Code is split at $ boundaries and loaded on demand
+* - Containers: Qwik apps run inside container elements with q:container attribute
+* - Qwikloader: A tiny (~1KB) script that sets up global event listeners
+*
+* Requirements: 2.1
+*/
+/// <reference lib="dom" />
+import { BaseFrameworkAdapter } from "../framework-adapter.js";
+/**
+* Qwik HMR Adapter
+*
+* Unlike other frameworks, Qwik doesn't hydrate — it resumes. This adapter
+* handles HMR by re-rendering the container rather than performing traditional
+* hydration-based hot updates.
+*
+* During development, Qwik's optimizer (via vite-plugin-qwik) handles most
+* of the HMR heavy lifting. This adapter provides the island-level integration
+* for Avalon's HMR coordinator.
+*/
+export class QwikHMRAdapter extends BaseFrameworkAdapter {
+	name = "qwik";
+	/**
+	* Track container elements for cleanup
+	*/
+	containers = new WeakMap();
+	/**
+	* Check if a component is a Qwik component
+	*
+	* Qwik components are created with component$() and have distinctive markers:
+	* - __brand or __qrl property from the Qwik optimizer
+	* - $ suffix convention in source
+	* - QRL (Qwik Resource Locator) references
+	*/
+	canHandle(component) {
+		if (!component) return false;
+		// Check if it's a function (Qwik components are functions)
+		if (typeof component === "function") {
+			const comp = component;
+			// Check for Qwik-specific markers set by the optimizer
+			if (comp.__brand === "QwikComponent" || comp.__qrl) {
+				return true;
+			}
+			// Check for QRL wrapper pattern
+			if (comp.getSymbol || comp.getHash) {
+				return true;
+			}
+			try {
+				const funcStr = component.toString();
+				// Look for Qwik-specific compiled patterns
+				if (funcStr.includes("component$") || funcStr.includes("qrl") || funcStr.includes("useSignal") || funcStr.includes("useStore") || funcStr.includes("useTask$") || funcStr.includes("useVisibleTask$") || funcStr.includes("_qrl") || funcStr.includes("qwik")) {
+					return true;
+				}
+			} catch {}
+		}
+		// Check if it's a Qwik component object (wrapped or exported)
+		if (typeof component === "object" && component !== null) {
+			const obj = component;
+			// Check for default export pattern
+			if (obj.default && typeof obj.default === "function") {
+				return this.canHandle(obj.default);
+			}
+			// Check for Qwik QRL markers
+			if (obj.__qrl || obj.__brand === "QwikComponent") {
+				return true;
+			}
+		}
+		return false;
+	}
+	/**
+	* Preserve Qwik component state before HMR update
+	*
+	* Qwik serializes state into the DOM via q:container attributes and
+	* inline <script type="qwik/json"> blocks. We capture this serialized
+	* state so it can be used during re-rendering.
+	*/
+	preserveState(island) {
+		try {
+			const baseSnapshot = super.preserveState(island);
+			if (!baseSnapshot) return null;
+			// Get props from the island
+			const propsAttr = island.getAttribute("data-props");
+			const capturedProps = propsAttr ? JSON.parse(propsAttr) : {};
+			const src = island.getAttribute("data-src") || "";
+			const componentName = this.extractComponentName(src);
+			// Capture Qwik container state — serialized in the DOM
+			const containerEl = island.closest("[q\\:container]") || island;
+			const containerState = containerEl.querySelector("script[type=\"qwik/json\"]")?.textContent || null;
+			// Capture q: attributes that hold container metadata
+			const qContainerAttrs = {};
+			const attrs = containerEl.attributes;
+			if (attrs) {
+				for (let i = 0; i < attrs.length; i++) {
+					const attr = attrs[i];
+					if (attr.name.startsWith("q:")) {
+						qContainerAttrs[attr.name] = attr.value;
+					}
+				}
+			}
+			return {
+				...baseSnapshot,
+				framework: "qwik",
+				data: {
+					componentName,
+					capturedProps,
+					containerState,
+					qContainerAttrs
+				}
+			};
+		} catch (error) {
+			console.warn("Failed to preserve Qwik state:", error);
+			return null;
+		}
+	}
+	/**
+	* Update Qwik component with HMR
+	*
+	* Qwik's resumability model means we don't hydrate in the traditional sense.
+	* Instead, during HMR:
+	* 1. The Qwik optimizer (vite-plugin-qwik) invalidates the affected QRLs
+	* 2. We re-render the component into the island container
+	* 3. Qwikloader picks up the new event bindings automatically
+	* 4. Serialized state is restored from the container
+	*/
+	async update(island, newComponent, props) {
+		if (!this.canHandle(newComponent)) {
+			throw new Error("Component is not a valid Qwik component");
+		}
+		// Extract the actual component function
+		let Component;
+		if (typeof newComponent === "object" && newComponent !== null) {
+			const obj = newComponent;
+			if (obj.default && typeof obj.default === "function") {
+				Component = obj.default;
+			} else {
+				throw new Error("Qwik component object must have a default export");
+			}
+		} else if (typeof newComponent === "function") {
+			Component = newComponent;
+		} else {
+			throw new Error("Invalid Qwik component type");
+		}
+		try {
+			// Clean up existing container tracking
+			const existing = this.containers.get(island);
+			if (existing?.cleanup) {
+				try {
+					existing.cleanup();
+				} catch (error) {
+					console.warn("Failed to clean up existing Qwik container:", error);
+				}
+			}
+			// Dynamically import Qwik's client render API
+			// In development, vite-plugin-qwik makes this available
+			// Use a variable to prevent Vite's static import analysis from resolving this at build time
+			const qwikId = "@builder.io/qwik";
+			const qwikModule = await import(
+				/* @vite-ignore */
+				qwikId
+);
+			if (qwikModule.render) {
+				// Use Qwik's client-side render to mount the component
+				// Qwik's render handles setting up the container and resumability
+				const jsxNode = typeof qwikModule.jsx === "function" ? qwikModule.jsx(Component, props) : Component(props);
+				await qwikModule.render(island, jsxNode);
+			} else {
+				// Fallback: replace innerHTML and let Qwikloader resume
+				// This works because Qwik's event listeners are declarative in the DOM
+				console.warn("Qwik render API not available, using innerHTML fallback");
+				const result = Component(props);
+				if (typeof result === "string") {
+					island.innerHTML = result;
+				}
+			}
+			// Track the container for future cleanup
+			this.containers.set(island, {});
+			// Mark as hydrated (resumed, in Qwik terms)
+			island.setAttribute("data-hydrated", "true");
+			island.setAttribute("data-hydration-status", "success");
+		} catch (error) {
+			console.error("Qwik HMR update failed:", error);
+			island.setAttribute("data-hydration-status", "error");
+			throw error;
+		}
+	}
+	/**
+	* Restore Qwik component state after HMR update
+	*
+	* Qwik's serialized state lives in the DOM, so restoring the container
+	* state script block and q: attributes is sufficient for the framework
+	* to resume correctly.
+	*/
+	restoreState(island, state) {
+		try {
+			// Restore DOM state (scroll, focus, form values)
+			super.restoreState(island, state);
+		} catch (error) {
+			console.warn("Failed to restore Qwik state:", error);
+		}
+	}
+	/**
+	* Handle errors during Qwik HMR update
+	*/
+	handleError(island, error) {
+		console.error("Qwik HMR error:", error);
+		super.handleError(island, error);
+		const errorIndicator = island.querySelector(".hmr-error-indicator");
+		if (errorIndicator) {
+			const errorMessage = error.message;
+			let hint = "";
+			if (errorMessage.includes("component$") || errorMessage.includes("component\\$")) {
+				hint = " (Hint: Ensure component is wrapped with component$())";
+			} else if (errorMessage.includes("useSignal") || errorMessage.includes("useStore")) {
+				hint = " (Hint: Qwik hooks must be called inside component$() body)";
+			} else if (errorMessage.includes("QRL") || errorMessage.includes("qrl")) {
+				hint = " (Hint: Check that lazy-loaded boundaries use $ correctly)";
+			} else if (errorMessage.includes("serialize") || errorMessage.includes("container")) {
+				hint = " (Hint: Ensure all state is serializable — Qwik serializes state to the DOM)";
+			} else if (errorMessage.includes("resumable") || errorMessage.includes("resume")) {
+				hint = " (Hint: Server and client container state must match for resumability)";
+			}
+			errorIndicator.textContent = `Qwik HMR Error: ${errorMessage}${hint}`;
+		}
+	}
+	/**
+	* Extract component name from source path
+	*/
+	extractComponentName(src) {
+		const parts = src.split("/");
+		const filename = parts[parts.length - 1];
+		return filename.replace(/\.qwik\.(tsx?|jsx?)$/, "").replace(/\.(tsx?|jsx?)$/, "");
+	}
+	/**
+	* Clean up Qwik component when island is removed
+	*/
+	unmount(island) {
+		const container = this.containers.get(island);
+		if (container) {
+			try {
+				if (container.cleanup) {
+					container.cleanup();
+				}
+				this.containers.delete(island);
+			} catch (error) {
+				console.warn("Failed to unmount Qwik component:", error);
+			}
+		}
+	}
+}
+export const qwikAdapter = new QwikHMRAdapter();

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

@@ -0,0 +1,220 @@
+/**
+* React HMR Adapter
+* 
+* Provides Hot Module Replacement support for React components using React Fast Refresh.
+* Integrates with @vitejs/plugin-react to preserve hooks state and component tree during updates.
+* 
+* Requirements: 2.1
+*/
+/// <reference lib="dom" />
+import { BaseFrameworkAdapter } from "../framework-adapter.js";
+/**
+* React HMR Adapter
+* 
+* Leverages React Fast Refresh (provided by @vitejs/plugin-react) to:
+* - Preserve hooks state across updates
+* - Maintain component tree structure
+* - Handle component updates without full remount
+* 
+* React Fast Refresh works by:
+* 1. Detecting when a component module is updated
+* 2. Preserving the React Fiber tree (internal state representation)
+* 3. Re-rendering with the new component definition
+* 4. Restoring hooks state from the preserved Fiber tree
+*/
+export class ReactHMRAdapter extends BaseFrameworkAdapter {
+	name = "react";
+	/**
+	* Store React roots for each island to enable proper updates
+	*/
+	roots = new WeakMap();
+	/**
+	* Check if a component is a React component
+	* 
+	* React components can be:
+	* - Function components (including hooks)
+	* - Class components (extending React.Component)
+	* - Forward refs
+	* - Memoized components
+	*/
+	canHandle(component) {
+		if (!component) return false;
+		// Check if it's a function (function component or class)
+		if (typeof component === "function") {
+			// Check for React-specific properties on the function
+			// Use unknown first to avoid type errors
+			const comp = component;
+			// Class components have isReactComponent on prototype
+			const proto = component.prototype;
+			if (proto && proto.isReactComponent) {
+				return true;
+			}
+			// Check for React element symbol (for wrapped components)
+			if (comp.$$typeof) {
+				return true;
+			}
+			// Assume any function could be a React component
+			// React Fast Refresh will handle validation
+			return true;
+		}
+		// Check for React element types
+		if (typeof component !== "object") {
+			return false;
+		}
+		const obj = component;
+		// Check for React element symbol
+		if (obj.$$typeof) {
+			return true;
+		}
+		// Check for wrapped components (HOCs, memo, forwardRef)
+		if (obj.type && typeof obj.type === "function") {
+			return true;
+		}
+		return false;
+	}
+	/**
+	* Preserve React component state before HMR update
+	* 
+	* React Fast Refresh handles most state preservation automatically through
+	* the React Fiber tree. 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 React-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);
+			const reactSnapshot = {
+				...baseSnapshot,
+				framework: "react",
+				data: {
+					componentName,
+					capturedProps
+				}
+			};
+			return reactSnapshot;
+		} catch (error) {
+			console.warn("Failed to preserve React state:", error);
+			return null;
+		}
+	}
+	/**
+	* Update React component with HMR
+	* 
+	* This method integrates with React Fast Refresh:
+	* 1. React Fast Refresh is automatically enabled by @vitejs/plugin-react
+	* 2. When a module updates, Vite sends an HMR event
+	* 3. We re-hydrate the component with the new definition
+	* 4. React Fast Refresh preserves hooks 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 React component");
+		}
+		const Component = newComponent;
+		try {
+			// Dynamically import React and ReactDOM at runtime
+			// These are resolved by Vite in the browser
+			const [reactModule, reactDOMModule] = await Promise.all([import("react"), import("react-dom/client")]);
+			const { createElement } = reactModule;
+			const { hydrateRoot } = reactDOMModule;
+			// Check if we have an existing root
+			const existingRoot = this.roots.get(island);
+			if (existingRoot) {
+				// Update existing root with new component
+				// React Fast Refresh will preserve hooks state automatically
+				const element = createElement(Component, props);
+				existingRoot.render(element);
+			} else {
+				// Create new root and hydrate
+				// This happens on first HMR update or if root was lost
+				const element = createElement(Component, props);
+				const newRoot = hydrateRoot(island, element, { onRecoverableError: (error) => {
+					console.warn("React hydration recoverable error during HMR:", error);
+				} });
+				// Store root for future updates
+				this.roots.set(island, newRoot);
+			}
+			// Mark as hydrated
+			island.setAttribute("data-hydrated", "true");
+			island.setAttribute("data-hydration-status", "success");
+		} catch (error) {
+			console.error("React HMR update failed:", error);
+			island.setAttribute("data-hydration-status", "error");
+			throw error;
+		}
+	}
+	/**
+	* Restore React component state after HMR update
+	* 
+	* React Fast Refresh 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 React state:", error);
+		}
+	}
+	/**
+	* Handle errors during React HMR update
+	* 
+	* Provides React-specific error handling with helpful messages
+	*/
+	handleError(island, error) {
+		console.error("React HMR error:", error);
+		// Use base error handling
+		super.handleError(island, error);
+		// Add React-specific error information
+		const errorIndicator = island.querySelector(".hmr-error-indicator");
+		if (errorIndicator) {
+			const errorMessage = error.message;
+			// Provide helpful hints for common React errors
+			let hint = "";
+			if (errorMessage.includes("hooks")) {
+				hint = " (Hint: Check hooks usage - hooks must be called in the same order)";
+			} else if (errorMessage.includes("render")) {
+				hint = " (Hint: Check component render method for errors)";
+			} else if (errorMessage.includes("hydration")) {
+				hint = " (Hint: Server and client render must match)";
+			}
+			errorIndicator.textContent = `React 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(/\.(tsx?|jsx?)$/, "");
+	}
+	/**
+	* Clean up React root when island is removed
+	* This should be called when an island is unmounted
+	*/
+	unmount(island) {
+		const root = this.roots.get(island);
+		if (root) {
+			try {
+				root.unmount();
+				this.roots.delete(island);
+			} catch (error) {
+				console.warn("Failed to unmount React root:", error);
+			}
+		}
+	}
+}
+/**
+* Create and export a singleton instance of the React HMR adapter
+*/
+export const reactAdapter = new ReactHMRAdapter();