@useavalon/avalon 0.1.9 → 0.1.11

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@useavalon/avalon",
-	"version": "0.1.9",
+	"version": "0.1.11",
 	"description": "Multi-framework islands architecture for the modern web",
 	"license": "MIT",
 	"type": "module",
@@ -11,6 +11,10 @@
 	},
 	"homepage": "https://useavalon.dev",
 	"keywords": ["avalon", "islands", "ssr", "vite", "preact", "multi-framework", "hydration"],
+	"scripts": {
+		"build:client": "bun run scripts/build-client.ts",
+		"prepublishOnly": "bun run build:client"
+	},
 	"exports": {
 		".": "./mod.ts",
 		"./client": "./src/client/components.ts",

package/src/client/adapters/index.js

@@ -0,0 +1,12 @@
+/**
+* Framework HMR Adapters
+* 
+* Exports all framework-specific HMR adapters for easy registration
+*/
+export { ReactHMRAdapter, reactAdapter } from "./react-adapter.js";
+export { PreactHMRAdapter, preactAdapter } from "./preact-adapter.js";
+export { VueHMRAdapter, vueAdapter } from "./vue-adapter.js";
+export { SvelteHMRAdapter, svelteAdapter } from "./svelte-adapter.js";
+export { SolidHMRAdapter, solidAdapter } from "./solid-adapter.js";
+export { LitHMRAdapter, litAdapter } from "./lit-adapter.js";
+export { QwikHMRAdapter, qwikAdapter } from "./qwik-adapter.js";

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

@@ -0,0 +1,467 @@
+/**
+* Lit HMR Adapter
+* 
+* Provides Hot Module Replacement support for Lit components.
+* Handles custom element re-registration and updates all element instances.
+* Preserves element properties across updates.
+* 
+* Requirements: 2.6
+*/
+/// <reference lib="dom" />
+import { BaseFrameworkAdapter } from "../framework-adapter.js";
+/**
+* Lit HMR Adapter
+* 
+* Handles HMR for Lit components by:
+* 1. Re-registering the custom element with a new definition
+* 2. Updating all existing instances of the element
+* 3. Preserving element properties and attributes
+* 
+* Lit components are Web Components (custom elements), so HMR requires:
+* - Undefining the old custom element (if possible)
+* - Defining the new custom element
+* - Updating all instances in the DOM
+* - Preserving reactive properties
+*/
+export class LitHMRAdapter extends BaseFrameworkAdapter {
+	name = "lit";
+	/**
+	* Store element constructors for each island
+	*/
+	elementConstructors = new WeakMap();
+	/**
+	* Store tag names for each island
+	*/
+	tagNames = new WeakMap();
+	/**
+	* Check if a component is a Lit component
+	* 
+	* Lit components are:
+	* - Classes that extend LitElement
+	* - Typically decorated with @customElement
+	* - Have .lit.ts or .lit.js extension (but not always)
+	*/
+	canHandle(component) {
+		if (!component) return false;
+		// Check if it's a class (Lit components are classes)
+		if (typeof component === "function") {
+			const comp = component;
+			// Check for Lit-specific markers
+			// Lit elements may have __litElement marker
+			if (comp.__litElement) {
+				return true;
+			}
+			// Check if it extends LitElement by looking at the prototype chain
+			try {
+				const proto = component.prototype;
+				if (proto) {
+					// Check for Lit-specific methods on prototype
+					if ("render" in proto && "requestUpdate" in proto && "updateComplete" in proto) {
+						return true;
+					}
+					// Check for LitElement in prototype chain
+					let currentProto = proto;
+					while (currentProto && currentProto !== Object.prototype) {
+						const constructor = currentProto.constructor;
+						if (constructor && constructor.name === "LitElement") {
+							return true;
+						}
+						currentProto = Object.getPrototypeOf(currentProto);
+					}
+				}
+			} catch {}
+			// Check for @customElement decorator metadata
+			// The decorator adds metadata to the class
+			if (comp.elementName || comp.tagName) {
+				return true;
+			}
+			// Check function signature - Lit components typically have specific patterns
+			try {
+				const funcStr = component.toString();
+				// Look for Lit-specific patterns
+				if (funcStr.includes("LitElement") || funcStr.includes("customElement") || funcStr.includes("html`") || funcStr.includes("css`") || funcStr.includes("render()") || funcStr.includes("requestUpdate")) {
+					return true;
+				}
+			} catch {}
+		}
+		// Check if it's a Lit 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 Lit component markers
+		if (obj.__litElement) {
+			return true;
+		}
+		return false;
+	}
+	/**
+	* Preserve Lit element state before HMR update
+	* 
+	* Captures:
+	* - Element properties (reactive properties defined with @property)
+	* - Element attributes
+	* - DOM state (scroll, focus, form values)
+	*/
+	preserveState(island) {
+		try {
+			// Get base DOM state
+			const baseSnapshot = super.preserveState(island);
+			if (!baseSnapshot) return null;
+			// Get Lit-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 tag name
+			const tagName = island.getAttribute("data-tag-name") || this.tagNames.get(island);
+			// Find the Lit element inside the island
+			const litElement = tagName ? island.querySelector(tagName) : island.querySelector("[data-lit-element]");
+			// Capture element properties and attributes
+			const elementProperties = {};
+			const elementAttributes = {};
+			if (litElement) {
+				// Capture all properties
+				// Lit stores reactive properties on the element instance
+				for (const key in litElement) {
+					if (litElement.hasOwnProperty(key) && !key.startsWith("_")) {
+						try {
+							const value = litElement[key];
+							// Only capture serializable values
+							if (value !== undefined && value !== null && typeof value !== "function" && typeof value !== "symbol") {
+								elementProperties[key] = value;
+							}
+						} catch {}
+					}
+				}
+				// Capture all attributes
+				for (let i = 0; i < litElement.attributes.length; i++) {
+					const attr = litElement.attributes[i];
+					elementAttributes[attr.name] = attr.value;
+				}
+			}
+			const litSnapshot = {
+				...baseSnapshot,
+				framework: "lit",
+				data: {
+					componentName,
+					tagName: tagName || undefined,
+					capturedProps,
+					elementProperties,
+					elementAttributes
+				}
+			};
+			return litSnapshot;
+		} catch (error) {
+			console.warn("Failed to preserve Lit state:", error);
+			return null;
+		}
+	}
+	/**
+	* Update Lit component with HMR
+	* 
+	* This method handles custom element re-registration:
+	* 1. Extract the tag name from the component or island
+	* 2. Find all instances of the element in the DOM
+	* 3. Preserve their properties and attributes
+	* 4. Undefine the old custom element (if possible)
+	* 5. Define the new custom element
+	* 6. Update all instances with the new definition
+	* 7. Restore properties and attributes
+	*/
+	async update(island, newComponent, props) {
+		if (!this.canHandle(newComponent)) {
+			throw new Error("Component is not a valid Lit component");
+		}
+		// Extract the actual component class
+		let ElementClass;
+		if (typeof newComponent === "object" && newComponent !== null) {
+			const obj = newComponent;
+			if (obj.default && typeof obj.default === "function") {
+				ElementClass = obj.default;
+			} else {
+				throw new Error("Lit component object must have a default export");
+			}
+		} else if (typeof newComponent === "function") {
+			ElementClass = newComponent;
+		} else {
+			throw new Error("Invalid Lit component type");
+		}
+		try {
+			// Determine the tag name
+			// Priority: data-tag-name attribute > elementName property > derive from class name
+			let tagName = island.getAttribute("data-tag-name");
+			if (!tagName) {
+				// Try to get from the class
+				tagName = ElementClass.elementName;
+			}
+			if (!tagName) {
+				// Derive from class name (convert PascalCase to kebab-case)
+				tagName = ElementClass.name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+			}
+			if (!tagName || !tagName.includes("-")) {
+				throw new Error("Invalid custom element tag name: " + tagName);
+			}
+			// Store tag name for future updates
+			this.tagNames.set(island, tagName);
+			island.setAttribute("data-tag-name", tagName);
+			// Find all instances of this element in the island
+			const elements = Array.from(island.querySelectorAll(tagName));
+			// If no elements exist, create one
+			if (elements.length === 0) {
+				// Check if the custom element is already defined
+				const existingDefinition = customElements.get(tagName);
+				if (!existingDefinition) {
+					// Define the custom element
+					customElements.define(tagName, ElementClass);
+				} else if (existingDefinition !== ElementClass) {
+					// Element is already defined with a different class
+					// We need to re-register it
+					await this.reregisterCustomElement(tagName, ElementClass);
+				}
+				// Create a new element
+				const newElement = document.createElement(tagName);
+				// Set properties from props
+				Object.entries(props).forEach(([key, value]) => {
+					try {
+						newElement[key] = value;
+					} catch (error) {
+						console.warn(`Failed to set property ${key} on Lit element:`, error);
+					}
+				});
+				// Append to island
+				island.appendChild(newElement);
+				// Store constructor
+				this.elementConstructors.set(island, ElementClass);
+				// Mark as hydrated
+				island.setAttribute("data-hydrated", "true");
+				island.setAttribute("data-hydration-status", "success");
+				return;
+			}
+			// Update existing elements
+			// First, check if we need to re-register the custom element
+			const existingDefinition = customElements.get(tagName);
+			if (existingDefinition && existingDefinition !== ElementClass) {
+				// Re-register the custom element with the new definition
+				await this.reregisterCustomElement(tagName, ElementClass);
+				// After re-registration, we need to replace all existing elements
+				// because they're instances of the old class
+				for (const oldElement of elements) {
+					// Preserve state
+					const properties = {};
+					const attributes = {};
+					// Capture properties
+					for (const key in oldElement) {
+						if (oldElement.hasOwnProperty(key) && !key.startsWith("_")) {
+							try {
+								const value = oldElement[key];
+								if (value !== undefined && value !== null && typeof value !== "function" && typeof value !== "symbol") {
+									properties[key] = value;
+								}
+							} catch {}
+						}
+					}
+					// Capture attributes
+					for (let i = 0; i < oldElement.attributes.length; i++) {
+						const attr = oldElement.attributes[i];
+						attributes[attr.name] = attr.value;
+					}
+					// Create new element
+					const newElement = document.createElement(tagName);
+					// Restore attributes
+					Object.entries(attributes).forEach(([name, value]) => {
+						newElement.setAttribute(name, value);
+					});
+					// Restore properties
+					Object.entries(properties).forEach(([key, value]) => {
+						try {
+							newElement[key] = value;
+						} catch (error) {
+							console.warn(`Failed to restore property ${key}:`, error);
+						}
+					});
+					// Replace old element with new element
+					oldElement.parentNode?.replaceChild(newElement, oldElement);
+				}
+			} else if (!existingDefinition) {
+				// Define the custom element for the first time
+				customElements.define(tagName, ElementClass);
+				// Trigger update on all elements
+				for (const element of elements) {
+					if (element.requestUpdate) {
+						element.requestUpdate();
+					}
+				}
+			} else {
+				// Same class, just trigger updates
+				for (const element of elements) {
+					// Update properties from props
+					Object.entries(props).forEach(([key, value]) => {
+						try {
+							element[key] = value;
+						} catch (error) {
+							console.warn(`Failed to update property ${key}:`, error);
+						}
+					});
+					// Request update
+					if (element.requestUpdate) {
+						element.requestUpdate();
+					}
+				}
+			}
+			// Store constructor
+			this.elementConstructors.set(island, ElementClass);
+			// Mark as hydrated
+			island.setAttribute("data-hydrated", "true");
+			island.setAttribute("data-hydration-status", "success");
+		} catch (error) {
+			console.error("Lit HMR update failed:", error);
+			island.setAttribute("data-hydration-status", "error");
+			throw error;
+		}
+	}
+	/**
+	* Re-register a custom element with a new definition
+	* 
+	* Custom elements cannot be undefined once defined, so we need to:
+	* 1. Create a new tag name (with a version suffix)
+	* 2. Define the new element with the new tag name
+	* 3. Update all references to use the new tag name
+	* 
+	* Alternative approach (used here):
+	* 1. Use a wrapper element that delegates to the actual element
+	* 2. Update the wrapper to use the new element class
+	*/
+	async reregisterCustomElement(tagName, ElementClass) {
+		// Unfortunately, custom elements cannot be truly undefined once defined
+		// The best we can do is define a new version with a suffix
+		// However, for HMR purposes, we can use a different approach:
+		// We'll just replace all instances of the old element with new instances
+		// This is handled in the update() method above
+		// For now, we'll just log a warning
+		console.warn(`Custom element ${tagName} is already defined. ` + `Replacing all instances with new definition.`);
+		// Note: In a production HMR system, you might want to:
+		// 1. Use a versioned tag name (e.g., my-element-v2)
+		// 2. Use a proxy element that delegates to the actual element
+		// 3. Use a custom element registry that supports re-registration
+		// For this implementation, we rely on replacing element instances
+		// which is handled in the update() method
+	}
+	/**
+	* Restore Lit element state after HMR update
+	* 
+	* Restores:
+	* - Element properties
+	* - Element attributes
+	* - DOM state (scroll, focus, form values)
+	*/
+	restoreState(island, state) {
+		try {
+			// Restore DOM state (scroll, focus, form values)
+			super.restoreState(island, state);
+			// Restore Lit-specific state
+			const litState = state;
+			const tagName = litState.data.tagName;
+			if (tagName) {
+				const litElement = island.querySelector(tagName);
+				if (litElement) {
+					// Restore element properties
+					if (litState.data.elementProperties) {
+						Object.entries(litState.data.elementProperties).forEach(([key, value]) => {
+							try {
+								litElement[key] = value;
+							} catch (error) {
+								console.warn(`Failed to restore property ${key}:`, error);
+							}
+						});
+					}
+					// Restore element attributes
+					if (litState.data.elementAttributes) {
+						Object.entries(litState.data.elementAttributes).forEach(([name, value]) => {
+							try {
+								litElement.setAttribute(name, value);
+							} catch (error) {
+								console.warn(`Failed to restore attribute ${name}:`, error);
+							}
+						});
+					}
+					// Request update to apply changes
+					if (litElement.requestUpdate) {
+						litElement.requestUpdate();
+					}
+				}
+			}
+		} catch (error) {
+			console.warn("Failed to restore Lit state:", error);
+		}
+	}
+	/**
+	* Handle errors during Lit HMR update
+	* 
+	* Provides Lit-specific error handling with helpful messages
+	*/
+	handleError(island, error) {
+		console.error("Lit HMR error:", error);
+		// Use base error handling
+		super.handleError(island, error);
+		// Add Lit-specific error information
+		const errorIndicator = island.querySelector(".hmr-error-indicator");
+		if (errorIndicator) {
+			const errorMessage = error.message;
+			// Provide helpful hints for common Lit errors
+			let hint = "";
+			if (errorMessage.includes("custom element") || errorMessage.includes("define")) {
+				hint = " (Hint: Check that your element has a valid tag name with a hyphen)";
+			} else if (errorMessage.includes("tag name")) {
+				hint = " (Hint: Custom element tag names must contain a hyphen)";
+			} else if (errorMessage.includes("property") || errorMessage.includes("attribute")) {
+				hint = " (Hint: Check @property decorators and attribute names)";
+			} else if (errorMessage.includes("render")) {
+				hint = " (Hint: Check the render() method for errors)";
+			} else if (errorMessage.includes("shadow")) {
+				hint = " (Hint: Check Shadow DOM usage and styles)";
+			}
+			errorIndicator.textContent = `Lit 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(/\.lit\.(ts|js)$/, "").replace(/\.(ts|js)$/, "");
+	}
+	/**
+	* Clean up Lit element when island is removed
+	* This should be called when an island is unmounted
+	*/
+	unmount(island) {
+		try {
+			const tagName = this.tagNames.get(island);
+			if (tagName) {
+				// Find all elements and disconnect them
+				const elements = island.querySelectorAll(tagName);
+				elements.forEach((element) => {
+					// Lit elements clean up automatically when disconnected
+					// but we can help by removing them from the DOM
+					element.remove();
+				});
+				this.tagNames.delete(island);
+			}
+			this.elementConstructors.delete(island);
+		} catch (error) {
+			console.warn("Failed to unmount Lit element:", error);
+		}
+	}
+}
+/**
+* Create and export a singleton instance of the Lit HMR adapter
+*/
+export const litAdapter = new LitHMRAdapter();