@useavalon/avalon 0.1.9 → 0.1.11

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

@@ -0,0 +1,295 @@
+/**
+* Solid HMR Adapter
+* 
+* Provides Hot Module Replacement support for Solid components using Solid Refresh.
+* Integrates with vite-plugin-solid to preserve signal subscriptions and reactive computations.
+* Handles Solid's fine-grained reactivity system during hot updates.
+* 
+* Requirements: 2.5
+*/
+/// <reference lib="dom" />
+import { BaseFrameworkAdapter } from "../framework-adapter.js";
+/**
+* Solid HMR Adapter
+* 
+* Leverages Solid Refresh (provided by vite-plugin-solid) to:
+* - Preserve signal subscriptions across updates
+* - Maintain reactive computations
+* - Handle component updates without full remount
+* 
+* Solid Refresh works through the __SOLID_HMR__ API:
+* 1. When a component module is updated, Vite sends an HMR event
+* 2. We use __SOLID_HMR__.reload() to hot-reload the component
+* 3. Solid Refresh preserves signal subscriptions automatically
+* 4. Reactive computations are maintained across updates
+* 5. The component re-renders with preserved reactive state
+*/
+export class SolidHMRAdapter extends BaseFrameworkAdapter {
+	name = "solid";
+	/**
+	* Store Solid dispose functions for each island to enable proper cleanup
+	*/
+	disposers = new WeakMap();
+	/**
+	* Store component IDs for HMR runtime
+	*/
+	componentIds = new WeakMap();
+	/**
+	* Check if a component is a Solid component
+	* 
+	* Solid components are:
+	* - Functions that return JSX
+	* - May use createSignal, createEffect, etc.
+	* - Typically have .solid.tsx extension (but not always)
+	*/
+	canHandle(component) {
+		if (!component) return false;
+		// Check if it's a function (Solid components are functions)
+		if (typeof component === "function") {
+			const comp = component;
+			// Check for Solid-specific markers
+			// Solid components may have __solid marker from vite-plugin-solid
+			if (comp.__solid) {
+				return true;
+			}
+			// Check function signature - Solid components typically accept props
+			// and return JSX (which is compiled to function calls)
+			try {
+				const funcStr = component.toString();
+				// Look for Solid-specific patterns
+				// - createSignal, createEffect, createMemo, etc.
+				// - JSX patterns (though this is less reliable after compilation)
+				if (funcStr.includes("createSignal") || funcStr.includes("createEffect") || funcStr.includes("createMemo") || funcStr.includes("createResource") || funcStr.includes("createStore") || funcStr.includes("_$") || funcStr.includes("_tmpl$")) {
+					return true;
+				}
+			} catch {}
+			// If we can't determine definitively, assume it could be a Solid component
+			// if it's a function (Solid components are just functions)
+			// This is a fallback - we'll let Solid's hydration handle validation
+			return true;
+		}
+		// Check if it's a Solid component object (wrapped or exported)
+		if (typeof component !== "object") {
+			return false;
+		}
+		const obj = component;
+		// Check for default export pattern
+		if (obj.default && typeof obj.default === "function") {
+			return this.canHandle(obj.default);
+		}
+		// Check for Solid component markers
+		if (obj.__solid) {
+			return true;
+		}
+		return false;
+	}
+	/**
+	* Preserve Solid component state before HMR update
+	* 
+	* Solid Refresh handles most state preservation automatically through
+	* its fine-grained reactivity system. We capture additional DOM state
+	* and props for fallback.
+	* 
+	* Note: Solid's signals are not easily accessible from outside the component,
+	* so we rely on Solid Refresh to preserve them.
+	*/
+	preserveState(island) {
+		try {
+			// Get base DOM state
+			const baseSnapshot = super.preserveState(island);
+			if (!baseSnapshot) return null;
+			// Get Solid-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);
+			// Get render ID for hydration
+			const renderId = island.dataset.solidRenderId || island.dataset.renderId;
+			const solidSnapshot = {
+				...baseSnapshot,
+				framework: "solid",
+				data: {
+					componentName,
+					capturedProps,
+					renderId
+				}
+			};
+			return solidSnapshot;
+		} catch (error) {
+			console.warn("Failed to preserve Solid state:", error);
+			return null;
+		}
+	}
+	/**
+	* Update Solid component with HMR
+	* 
+	* This method integrates with Solid Refresh:
+	* 1. Solid Refresh is automatically enabled by vite-plugin-solid
+	* 2. When a module updates, Vite sends an HMR event
+	* 3. We use __SOLID_HMR__ to reload the component
+	* 4. Solid Refresh preserves signal subscriptions automatically
+	* 5. Reactive computations are maintained
+	* 6. The component re-renders with preserved reactive state
+	*/
+	async update(island, newComponent, props) {
+		if (!this.canHandle(newComponent)) {
+			throw new Error("Component is not a valid Solid 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("Solid component object must have a default export");
+			}
+		} else if (typeof newComponent === "function") {
+			Component = newComponent;
+		} else {
+			throw new Error("Invalid Solid component type");
+		}
+		try {
+			// Check if we have an existing disposer
+			const existingDisposer = this.disposers.get(island);
+			const componentId = this.componentIds.get(island);
+			// Try to use Solid HMR runtime if available
+			const hmrRuntime = globalThis.__SOLID_HMR__;
+			if (hmrRuntime && componentId) {
+				// Use Solid's HMR runtime for hot reload
+				// This preserves signal subscriptions and reactive computations automatically
+				try {
+					hmrRuntime.reload(componentId, Component);
+					// If we have an existing component, Solid Refresh handles the update
+					// We don't need to do anything else
+					if (existingDisposer) {
+						return;
+					}
+				} catch (error) {
+					console.warn("Solid HMR runtime reload failed, falling back to full remount:", error);
+				}
+			}
+			// Clean up existing component if present
+			if (existingDisposer) {
+				try {
+					existingDisposer();
+					this.disposers.delete(island);
+				} catch (error) {
+					console.warn("Failed to dispose existing Solid component:", error);
+				}
+			}
+			// Dynamically import Solid at runtime
+			// This is resolved by Vite in the browser
+			const solidWebModule = await import("solid-js/web");
+			const { hydrate, createComponent } = solidWebModule;
+			// Get render ID for hydration
+			const renderId = island.dataset.solidRenderId || island.dataset.renderId;
+			// Check if we have SSR content to hydrate
+			// Hydrate or render the component
+			const dispose = hydrate(() => createComponent(Component, props), island, { renderId });
+			// Store disposer for future updates
+			this.disposers.set(island, dispose);
+			// 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) {
+				try {
+					hmrRuntime.createRecord(newComponentId, Component);
+				} catch (error) {
+					console.warn("Failed to register with Solid HMR runtime:", error);
+				}
+			}
+			// Mark as hydrated
+			island.setAttribute("data-hydrated", "true");
+			island.setAttribute("data-hydration-status", "success");
+		} catch (error) {
+			console.error("Solid HMR update failed:", error);
+			island.setAttribute("data-hydration-status", "error");
+			throw error;
+		}
+	}
+	/**
+	* Restore Solid component state after HMR update
+	* 
+	* Solid Refresh handles most state restoration automatically through
+	* its fine-grained reactivity system. 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 Solid state:", error);
+		}
+	}
+	/**
+	* Handle errors during Solid HMR update
+	* 
+	* Provides Solid-specific error handling with helpful messages
+	*/
+	handleError(island, error) {
+		console.error("Solid HMR error:", error);
+		// Use base error handling
+		super.handleError(island, error);
+		// Add Solid-specific error information
+		const errorIndicator = island.querySelector(".hmr-error-indicator");
+		if (errorIndicator) {
+			const errorMessage = error.message;
+			// Provide helpful hints for common Solid errors
+			let hint = "";
+			if (errorMessage.includes("signal") || errorMessage.includes("Signal")) {
+				hint = " (Hint: Check signal usage - signals must be called as functions)";
+			} else if (errorMessage.includes("effect") || errorMessage.includes("Effect")) {
+				hint = " (Hint: Check effect usage - effects run after render)";
+			} else if (errorMessage.includes("hydration") || errorMessage.includes("hydrate")) {
+				hint = " (Hint: Server and client render must match)";
+			} else if (errorMessage.includes("createSignal") || errorMessage.includes("createEffect")) {
+				hint = " (Hint: Solid primitives must be called inside component functions)";
+			} else if (errorMessage.includes("reactive")) {
+				hint = " (Hint: Check reactive dependencies - they must be accessed inside tracking scopes)";
+			}
+			errorIndicator.textContent = `Solid 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(/\.solid\.(tsx?|jsx?)$/, "").replace(/\.(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, "_");
+	}
+	/**
+	* Clean up Solid component when island is removed
+	* This should be called when an island is unmounted
+	*/
+	unmount(island) {
+		const disposer = this.disposers.get(island);
+		if (disposer) {
+			try {
+				disposer();
+				this.disposers.delete(island);
+				this.componentIds.delete(island);
+			} catch (error) {
+				console.warn("Failed to unmount Solid component:", error);
+			}
+		}
+	}
+}
+/**
+* Create and export a singleton instance of the Solid HMR adapter
+*/
+export const solidAdapter = new SolidHMRAdapter();

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

@@ -0,0 +1,368 @@
+/**
+* Svelte HMR Adapter
+*
+* Provides Hot Module Replacement support for Svelte 5 components.
+* Integrates with @sveltejs/vite-plugin-svelte for HMR updates.
+*
+* IMPORTANT: Svelte 5 HMR Behavior
+* - HMR is controlled via compilerOptions.hmr in the Vite plugin config
+* - Local state is NOT preserved during HMR (by design in Svelte 5)
+* - CSS-only changes DO preserve state (100% preserved)
+* - Store subscriptions are maintained across updates
+* - The component is remounted with fresh state on JS changes
+*
+* Requirements: 2.4
+*/
+/// <reference lib="dom" />
+import { BaseFrameworkAdapter } from "../framework-adapter.js";
+/**
+* Svelte HMR Adapter
+* 
+* Handles HMR for Svelte 5 components in the Avalon islands architecture.
+* 
+* Svelte 5 HMR Behavior:
+* - HMR is controlled via compilerOptions.hmr in the Vite plugin config
+* - Local state is NOT preserved during HMR (by design in Svelte 5)
+* - CSS-only changes DO preserve state (100% preserved)
+* - Store subscriptions are maintained across updates
+* - The component is remounted with fresh state on JS changes
+* 
+* How it works:
+* 1. When a component module is updated, Vite sends an HMR event
+* 2. Svelte's compiler-integrated HMR handles the update
+* 3. We clean up the old instance and mount the new component
+* 4. DOM state (scroll, focus, form values) is preserved where possible
+* 5. The component re-renders with fresh state
+*/
+export class SvelteHMRAdapter extends BaseFrameworkAdapter {
+	name = "svelte";
+	/**
+	* Store Svelte component instances for each island to enable proper cleanup
+	*/
+	instances = new WeakMap();
+	/**
+	* Store component IDs for tracking
+	*/
+	componentIds = new WeakMap();
+	/**
+	* Store active store subscriptions for cleanup
+	*/
+	storeSubscriptions = new WeakMap();
+	/**
+	* Check if a function/class has Svelte component markers
+	*/
+	isSvelteFunction(component) {
+		const comp = component;
+		if (comp.$$render) {
+			return true;
+		}
+		const proto = component.prototype;
+		if (proto && (proto.$set && proto.$destroy || proto.$$)) {
+			return true;
+		}
+		try {
+			const funcStr = component.toString();
+			if (funcStr.includes("$set") || funcStr.includes("$destroy") || funcStr.includes("$$")) {
+				return true;
+			}
+		} catch {}
+		return false;
+	}
+	/**
+	* Check if a component is a Svelte component
+	*
+	* Svelte components are compiled to classes with specific markers:
+	* - Constructor function
+	* - $$render method (SSR marker)
+	* - Prototype with $set, $destroy methods
+	*/
+	canHandle(component) {
+		if (!component) return false;
+		if (typeof component === "function") {
+			return this.isSvelteFunction(component);
+		}
+		if (typeof component !== "object") {
+			return false;
+		}
+		const obj = component;
+		if (obj.default && typeof obj.default === "function") {
+			return this.canHandle(obj.default);
+		}
+		return obj.$$render !== undefined;
+	}
+	/**
+	* Preserve Svelte component state before HMR update
+	* 
+	* Note: In Svelte 5, local state is NOT preserved during HMR (by design).
+	* We capture DOM state (scroll, focus, form values) which CAN be restored.
+	*/
+	preserveState(island) {
+		try {
+			// Get base DOM state
+			const baseSnapshot = super.preserveState(island);
+			if (!baseSnapshot) return null;
+			// Get Svelte-specific data
+			const propsAttr = island.dataset.props;
+			const capturedProps = propsAttr ? JSON.parse(propsAttr) : {};
+			// Try to get component name from the island
+			const src = island.dataset.src || "";
+			const componentName = this.extractComponentName(src);
+			// Note: In Svelte 5, local state is not preserved during HMR
+			// We still capture it for debugging purposes, but it won't be restored
+			const localState = this.captureLocalState(island);
+			// Store values are maintained by Svelte's reactivity system
+			const storeValues = this.captureStoreValues(island);
+			const svelteSnapshot = {
+				...baseSnapshot,
+				framework: "svelte",
+				data: {
+					componentName,
+					capturedProps,
+					localState,
+					storeValues
+				}
+			};
+			return svelteSnapshot;
+		} catch (error) {
+			console.warn("Failed to preserve Svelte state:", error);
+			return null;
+		}
+	}
+	/**
+	* Extract the Svelte component class from a module or function
+	*/
+	extractComponent(newComponent) {
+		if (typeof newComponent === "object" && newComponent !== null) {
+			const obj = newComponent;
+			if (obj.default && typeof obj.default === "function") {
+				return obj.default;
+			}
+			throw new Error("Svelte component object must have a default export");
+		}
+		if (typeof newComponent === "function") {
+			return newComponent;
+		}
+		throw new TypeError("Invalid Svelte component type");
+	}
+	/**
+	* Clean up an existing Svelte component instance
+	*/
+	async cleanupInstance(island, instance) {
+		try {
+			const subscriptions = this.storeSubscriptions.get(island);
+			if (subscriptions) {
+				subscriptions.forEach((unsubscribe) => unsubscribe());
+				this.storeSubscriptions.delete(island);
+			}
+			const svelteModule = await import("svelte");
+			const svelteUnmount = svelteModule.unmount;
+			if (svelteUnmount) {
+				svelteUnmount(instance);
+			} else if (instance.$destroy) {
+				instance.$destroy();
+			}
+		} catch {
+			if (instance.$destroy) {
+				instance.$destroy();
+			}
+		}
+	}
+	/**
+	* Mount a Svelte component, trying Svelte 5 API first then falling back to constructor
+	*/
+	async mountComponent(Component, island, props) {
+		try {
+			const svelteModule = await import("svelte");
+			const svelteMount = svelteModule.mount;
+			if (svelteMount) {
+				return svelteMount(Component, {
+					target: island,
+					props
+				});
+			}
+			return new Component({
+				target: island,
+				props,
+				hydrate: false,
+				intro: false
+			});
+		} catch (svelte5Error) {
+			console.debug("Svelte 5 API not available, using constructor API:", svelte5Error);
+			return new Component({
+				target: island,
+				props,
+				hydrate: false,
+				intro: false
+			});
+		}
+	}
+	/**
+	* Update Svelte component with HMR
+	*
+	* Svelte 5 HMR Behavior:
+	* - HMR is handled by the Svelte compiler via compilerOptions.hmr
+	* - Local state is NOT preserved (by design)
+	* - CSS-only changes preserve state 100%
+	* - We clean up the old instance and mount the new component
+	*/
+	async update(island, newComponent, props) {
+		if (!this.canHandle(newComponent)) {
+			throw new Error("Component is not a valid Svelte component");
+		}
+		const Component = this.extractComponent(newComponent);
+		try {
+			const existingInstance = this.instances.get(island);
+			if (existingInstance) {
+				await this.cleanupInstance(island, existingInstance).catch((error) => {
+					console.warn("Failed to destroy existing Svelte instance:", error);
+				});
+			}
+			island.innerHTML = "";
+			const instance = await this.mountComponent(Component, island, props);
+			this.instances.set(island, instance);
+			const src = island.dataset.src || "";
+			this.componentIds.set(island, this.generateComponentId(src));
+			island.dataset.hydrated = "true";
+			island.dataset.hydrationStatus = "success";
+		} catch (error) {
+			console.error("Svelte HMR update failed:", error);
+			island.dataset.hydrationStatus = "error";
+			throw error;
+		}
+	}
+	/**
+	* Restore Svelte component state after HMR update
+	* 
+	* Note: In Svelte 5, local state is NOT preserved during HMR (by design).
+	* We only restore DOM state (scroll, focus, form values).
+	*/
+	restoreState(island, state) {
+		try {
+			// Restore DOM state (scroll, focus, form values)
+			super.restoreState(island, state);
+		} catch (error) {
+			console.warn("Failed to restore Svelte state:", error);
+		}
+	}
+	/**
+	* Handle errors during Svelte HMR update
+	* 
+	* Provides Svelte-specific error handling with helpful messages
+	*/
+	handleError(island, error) {
+		console.error("Svelte HMR error:", error);
+		// Use base error handling
+		super.handleError(island, error);
+		// Add Svelte-specific error information
+		const errorIndicator = island.querySelector(".hmr-error-indicator");
+		if (errorIndicator) {
+			const errorMessage = error.message;
+			// Provide helpful hints for common Svelte errors
+			let hint = "";
+			if (errorMessage.includes("$:") || errorMessage.includes("reactive")) {
+				hint = " (Hint: Check reactive statements ($:) - they must be at component top level)";
+			} else if (errorMessage.includes("store")) {
+				hint = " (Hint: Check store usage - stores must be imported and subscribed correctly)";
+			} else if (errorMessage.includes("hydration") || errorMessage.includes("hydrate")) {
+				hint = " (Hint: Server and client render must match)";
+			} else if (errorMessage.includes("target")) {
+				hint = " (Hint: Check component target - it must be a valid DOM element)";
+			} else if (errorMessage.includes("props")) {
+				hint = " (Hint: Check component props - they must match the component definition)";
+			}
+			errorIndicator.textContent = `Svelte 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.at(-1) ?? "";
+		return filename.replace(/\.svelte$/, "");
+	}
+	/**
+	* Detect if an island has existing SSR content vs being an empty container
+	* 
+	* @param island - Island element to check
+	* @returns True if island has SSR content
+	*/
+	detectSSRContent(island) {
+		// Check if element has any meaningful content
+		const hasTextContent = island.textContent && island.textContent.trim().length > 0;
+		const hasChildElements = island.children && island.children.length > 0;
+		const hasAttributes = island.dataset.ssrContent !== undefined || island.dataset.svelteRendered !== undefined;
+		// Consider it SSR content if it has text, child elements, or explicit markers
+		return hasTextContent || hasChildElements || hasAttributes;
+	}
+	/**
+	* 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.replaceAll(/[^a-zA-Z0-9]/g, "_");
+	}
+	/**
+	* Attempt to capture local state from Svelte instance
+	* This is best-effort and may not work in all cases
+	*/
+	captureLocalState(island) {
+		try {
+			const instance = this.instances.get(island);
+			if (!instance) return undefined;
+			// Try to access Svelte's internal state
+			// This is internal API and may change, so we wrap in try-catch
+			const internalState = instance.$$;
+			if (internalState?.ctx) {
+				// ctx is an array of component state values
+				// We can't easily map these back to variable names,
+				// so we just store the raw values
+				return {
+					ctx: internalState.ctx,
+					props: internalState.props,
+					bound: internalState.bound
+				};
+			}
+			return undefined;
+		} catch (error) {
+			// Silently fail - this is best-effort
+			console.debug("Could not capture Svelte local state:", error);
+			return undefined;
+		}
+	}
+	/**
+	* Attempt to capture store values
+	* This is best-effort and may not work in all cases
+	*/
+	captureStoreValues(_island) {
+		// Svelte stores are typically imported at module level,
+		// so we can't easily access them from the component instance
+		// The HMR system should handle store subscriptions automatically
+		// We could potentially track stores if we intercept store.subscribe calls,
+		// but that would require modifying the Svelte runtime, which is not feasible
+		// For now, we rely on Svelte's HMR to preserve store subscriptions
+		return undefined;
+	}
+	/**
+	* Clean up Svelte component when island is removed
+	* This should be called when an island is unmounted
+	*/
+	async unmount(_island) {
+		const instance = this.instances.get(_island);
+		if (instance) {
+			try {
+				await this.cleanupInstance(_island, instance);
+				this.instances.delete(_island);
+				this.componentIds.delete(_island);
+			} catch (error) {
+				console.warn("Failed to unmount Svelte component:", error);
+			}
+		}
+	}
+}
+/**
+* Create and export a singleton instance of the Svelte HMR adapter
+*/
+export const svelteAdapter = new SvelteHMRAdapter();