@useavalon/avalon 0.1.9 → 0.1.10

package/src/client/framework-adapter.js

@@ -0,0 +1,283 @@
+/**
+* Adapter registry for managing framework-specific HMR adapters
+*/
+export class AdapterRegistry {
+	adapters = new Map();
+	/**
+	* Register a framework-specific HMR adapter
+	*
+	* @param framework - Framework name (case-insensitive)
+	* @param adapter - The adapter implementation
+	* @throws Error if adapter is invalid or already registered
+	*
+	* Requirements: 2.1-2.7
+	*/
+	register(framework, adapter) {
+		const normalizedName = framework.toLowerCase();
+		// Validate adapter
+		if (!adapter) {
+			throw new Error(`Cannot register null/undefined adapter for framework: ${framework}`);
+		}
+		if (!adapter.name) {
+			throw new Error(`Adapter for framework ${framework} must have a name property`);
+		}
+		if (typeof adapter.canHandle !== "function") {
+			throw new Error(`Adapter for framework ${framework} must implement canHandle method`);
+		}
+		if (typeof adapter.preserveState !== "function") {
+			throw new Error(`Adapter for framework ${framework} must implement preserveState method`);
+		}
+		if (typeof adapter.update !== "function") {
+			throw new Error(`Adapter for framework ${framework} must implement update method`);
+		}
+		if (typeof adapter.restoreState !== "function") {
+			throw new Error(`Adapter for framework ${framework} must implement restoreState method`);
+		}
+		if (typeof adapter.handleError !== "function") {
+			throw new Error(`Adapter for framework ${framework} must implement handleError method`);
+		}
+		// Check if already registered
+		if (this.adapters.has(normalizedName)) {
+			console.warn(`Overwriting existing HMR adapter for framework: ${framework}`);
+		}
+		this.adapters.set(normalizedName, adapter);
+	}
+	/**
+	* Get an adapter for a specific framework
+	*
+	* @param framework - Framework name (case-insensitive)
+	* @returns The adapter or undefined if not found
+	*/
+	get(framework) {
+		return this.adapters.get(framework.toLowerCase());
+	}
+	/**
+	* Check if an adapter is registered for a framework
+	*
+	* @param framework - Framework name (case-insensitive)
+	* @returns true if adapter is registered
+	*/
+	has(framework) {
+		return this.adapters.has(framework.toLowerCase());
+	}
+	/**
+	* Get all registered framework names
+	*
+	* @returns Array of registered framework names
+	*/
+	getRegisteredFrameworks() {
+		return Array.from(this.adapters.keys());
+	}
+	/**
+	* Find an adapter that can handle a specific component
+	*
+	* Iterates through all registered adapters and returns the first one
+	* that can handle the component.
+	*
+	* @param component - The component to check
+	* @returns The adapter that can handle the component, or undefined
+	*/
+	findAdapter(component) {
+		for (const adapter of this.adapters.values()) {
+			if (adapter.canHandle(component)) {
+				return adapter;
+			}
+		}
+		return undefined;
+	}
+	/**
+	* Unregister an adapter
+	*
+	* @param framework - Framework name (case-insensitive)
+	* @returns true if adapter was removed, false if not found
+	*/
+	unregister(framework) {
+		const normalizedName = framework.toLowerCase();
+		const removed = this.adapters.delete(normalizedName);
+		return removed;
+	}
+	/**
+	* Clear all registered adapters
+	*/
+	clear() {
+		this.adapters.clear();
+	}
+	/**
+	* Get the number of registered adapters
+	*/
+	get size() {
+		return this.adapters.size;
+	}
+}
+/**
+* Base adapter class with common functionality
+*
+* Framework-specific adapters can extend this class to inherit common behavior
+* and only override framework-specific methods.
+*/
+export class BaseFrameworkAdapter {
+	/**
+	* Default state preservation implementation
+	* Captures DOM state (scroll, focus, form values)
+	*
+	* Subclasses should override to add framework-specific state
+	*/
+	preserveState(island) {
+		try {
+			const snapshot = {
+				framework: this.name,
+				timestamp: Date.now(),
+				data: {},
+				dom: this.captureDOMState(island)
+			};
+			return snapshot;
+		} catch (error) {
+			console.warn(`Failed to preserve state for ${this.name}:`, error);
+			return null;
+		}
+	}
+	/**
+	* Default state restoration implementation
+	* Restores DOM state (scroll, focus, form values)
+	*
+	* Subclasses should override to add framework-specific state restoration
+	*/
+	restoreState(island, state) {
+		try {
+			if (state.dom) {
+				this.restoreDOMState(island, state.dom);
+			}
+		} catch (error) {
+			console.warn(`Failed to restore state for ${this.name}:`, error);
+		}
+	}
+	/**
+	* Default error handling implementation
+	* Shows error indicator and preserves SSR HTML
+	*/
+	handleError(island, error) {
+		console.error(`HMR error in ${this.name} island:`, error);
+		// Add error indicator
+		const errorIndicator = document.createElement("div");
+		errorIndicator.className = "hmr-error-indicator";
+		errorIndicator.style.cssText = `
+      position: absolute;
+      top: 0;
+      left: 0;
+      right: 0;
+      background: #ff4444;
+      color: white;
+      padding: 8px;
+      font-size: 12px;
+      font-family: monospace;
+      z-index: 10000;
+      border-bottom: 2px solid #cc0000;
+    `;
+		errorIndicator.textContent = `HMR Error: ${error.message}`;
+		// Remove existing error indicators
+		const existing = island.querySelector(".hmr-error-indicator");
+		if (existing) {
+			existing.remove();
+		}
+		island.style.position = "relative";
+		island.insertBefore(errorIndicator, island.firstChild);
+		// Mark island as having error
+		island.setAttribute("data-hmr-error", "true");
+		island.setAttribute("data-hmr-error-message", error.message);
+	}
+	/**
+	* Capture DOM state (scroll, focus, form values)
+	*/
+	captureDOMState(island) {
+		const dom = {};
+		// Capture scroll position
+		const scrollableElements = island.querySelectorAll("[data-preserve-scroll]");
+		if (scrollableElements.length > 0 || island.scrollTop > 0 || island.scrollLeft > 0) {
+			dom.scrollPosition = {
+				x: island.scrollLeft,
+				y: island.scrollTop
+			};
+		}
+		// Capture focused element
+		const activeElement = document.activeElement;
+		if (activeElement && island.contains(activeElement)) {
+			const selector = this.getElementSelector(activeElement);
+			if (selector) {
+				dom.focusedElement = selector;
+			}
+		}
+		// Capture form values
+		const formElements = island.querySelectorAll("input, textarea, select");
+		if (formElements.length > 0) {
+			dom.formValues = {};
+			formElements.forEach((element, index) => {
+				const input = element;
+				const name = input.name || input.id || `element-${index}`;
+				if (input.type === "checkbox" || input.type === "radio") {
+					dom.formValues[name] = input.checked;
+				} else {
+					dom.formValues[name] = input.value;
+				}
+			});
+		}
+		return dom;
+	}
+	/**
+	* Restore DOM state (scroll, focus, form values)
+	*/
+	restoreDOMState(island, dom) {
+		if (!dom) return;
+		// Restore scroll position
+		if (dom.scrollPosition) {
+			island.scrollLeft = dom.scrollPosition.x;
+			island.scrollTop = dom.scrollPosition.y;
+		}
+		// Restore focused element
+		if (dom.focusedElement) {
+			try {
+				const element = island.querySelector(dom.focusedElement);
+				if (element && typeof element.focus === "function") {
+					element.focus();
+				}
+			} catch (error) {
+				console.warn("Failed to restore focus:", error);
+			}
+		}
+		// Restore form values
+		if (dom.formValues) {
+			const formElements = island.querySelectorAll("input, textarea, select");
+			formElements.forEach((element, index) => {
+				const input = element;
+				const name = input.name || input.id || `element-${index}`;
+				const value = dom.formValues[name];
+				if (value !== undefined) {
+					if (input.type === "checkbox" || input.type === "radio") {
+						input.checked = value;
+					} else {
+						input.value = value;
+					}
+				}
+			});
+		}
+	}
+	/**
+	* Get a CSS selector for an element
+	*/
+	getElementSelector(element) {
+		if (element.id) {
+			return `#${element.id}`;
+		}
+		// Check if element has name attribute (for form elements)
+		const nameAttr = element.getAttribute("name");
+		if (nameAttr) {
+			return `[name="${nameAttr}"]`;
+		}
+		// Fallback to nth-child selector
+		const parent = element.parentElement;
+		if (parent) {
+			const index = Array.from(parent.children).indexOf(element);
+			return `${element.tagName.toLowerCase()}:nth-child(${index + 1})`;
+		}
+		return null;
+	}
+}

package/src/client/hmr-coordinator.js

@@ -0,0 +1,274 @@
+/**
+* HMR Coordinator
+*
+* Central orchestrator for all HMR operations in Avalon.
+* Integrates with Vite's HMR API and coordinates island updates across frameworks.
+*/
+/// <reference lib="dom" />
+/// <reference lib="dom.iterable" />
+import { AdapterRegistry } from "./framework-adapter.js";
+import { getCSSHMRHandler } from "./css-hmr-handler.js";
+/**
+* HMR Coordinator class
+* Manages HMR lifecycle and coordinates updates across islands
+*/
+export class HMRCoordinator {
+	registry = new AdapterRegistry();
+	stateSnapshots = new Map();
+	updateQueue = new Set();
+	isProcessing = false;
+	/**
+	* Initialize the HMR coordinator
+	* Sets up Vite HMR listeners and accepts updates
+	*/
+	initialize() {
+		// @ts-ignore - Vite HMR is available in browser context
+		if (!import.meta.hot) {
+			return;
+		}
+		// @ts-ignore - Vite HMR API
+		import.meta.hot.accept();
+		// @ts-ignore - Vite HMR event types
+		import.meta.hot.on("vite:beforeUpdate", (payload) => {
+			this.handleUpdate(payload);
+		});
+		// @ts-ignore - Vite HMR event types
+		import.meta.hot.on("vite:beforeFullReload", () => {
+			this.handleBeforeFullReload();
+		});
+		// @ts-ignore - Vite HMR event types
+		import.meta.hot.on("vite:error", (payload) => {
+			console.error("[HMR] error:", payload);
+			this.handleError(payload);
+		});
+		document.addEventListener("hmr-update-required", (event) => {
+			const customEvent = event;
+			const { src, reason } = customEvent.detail;
+			if (reason === "css-module-update") {
+				this.updateQueue.add(this.normalizePath(src));
+				if (!this.isProcessing) {
+					this.processUpdateQueue().catch((error) => {
+						console.error("[HMR] Failed to process CSS module update:", error);
+					});
+				}
+			}
+		});
+	}
+	registerAdapter(framework, adapter) {
+		this.registry.register(framework, adapter);
+	}
+	getRegistry() {
+		return this.registry;
+	}
+	async handleUpdate(payload) {
+		if (payload.type !== "update" || !payload.updates) {
+			return;
+		}
+		const cssUpdates = [];
+		const jsUpdates = [];
+		for (const update of payload.updates) {
+			if (update.type === "css-update") {
+				cssUpdates.push(update);
+			} else {
+				jsUpdates.push(update);
+			}
+		}
+		this.processCSSUpdates(cssUpdates);
+		this.queueJSUpdates(jsUpdates);
+		if (!this.isProcessing && this.updateQueue.size > 0) {
+			await this.processUpdateQueue();
+		}
+	}
+	processCSSUpdates(cssUpdates) {
+		if (cssUpdates.length === 0) return;
+		const cssHandler = getCSSHMRHandler();
+		for (const cssUpdate of cssUpdates) {
+			try {
+				cssHandler.handleCSSUpdate(cssUpdate);
+			} catch (error) {
+				console.error("[HMR] CSS update failed:", error);
+			}
+		}
+	}
+	queueJSUpdates(jsUpdates) {
+		for (const update of jsUpdates) {
+			const normalizedPath = this.normalizePath(update.path || update.acceptedPath);
+			if (this.isIslandModule(normalizedPath)) {
+				this.updateQueue.add(normalizedPath);
+			}
+		}
+	}
+	async processUpdateQueue() {
+		if (this.updateQueue.size === 0) return;
+		this.isProcessing = true;
+		try {
+			const paths = Array.from(this.updateQueue);
+			this.updateQueue.clear();
+			for (const path of paths) {
+				const islands = this.findAffectedIslands(path);
+				for (const island of islands) {
+					try {
+						await this.updateIsland(island);
+					} catch (error) {
+						console.error("[HMR] Failed to update island:", error);
+					}
+				}
+			}
+		} finally {
+			this.isProcessing = false;
+		}
+	}
+	findAffectedIslands(modulePath) {
+		const islands = [];
+		const normalizedPath = this.normalizePath(modulePath);
+		const allIslands = document.querySelectorAll("[data-src]");
+		for (const island of allIslands) {
+			const src = island.dataset.src;
+			if (!src) continue;
+			const normalizedSrc = this.normalizePath(src);
+			const isMatch = normalizedSrc === normalizedPath || normalizedSrc.endsWith(normalizedPath) || normalizedPath.endsWith(normalizedSrc) || normalizedSrc.split("/").pop() === normalizedPath.split("/").pop();
+			if (isMatch) {
+				islands.push(island);
+			}
+		}
+		return islands;
+	}
+	async updateIsland(island) {
+		const framework = island.dataset.framework;
+		const src = island.dataset.src;
+		const propsAttr = island.dataset.props;
+		if (!framework || !src) {
+			console.warn("[HMR] Island missing framework or src attribute", island);
+			return;
+		}
+		const adapter = this.registry.get(framework.toLowerCase());
+		if (!adapter) {
+			console.warn(`[HMR] No adapter registered for framework: ${framework}`);
+			return;
+		}
+		try {
+			const props = propsAttr ? JSON.parse(propsAttr) : {};
+			const state = adapter.preserveState(island);
+			if (state) {
+				this.stateSnapshots.set(this.getIslandId(island), state);
+			}
+			delete island.dataset.hydrated;
+			delete island.dataset.hydrationStatus;
+			island.querySelector(".hydration-error-indicator, .hmr-error-indicator")?.remove();
+			const timestamp = Date.now();
+			const freshSrc = src.includes("?") ? `${src}&t=${timestamp}` : `${src}?t=${timestamp}`;
+			const componentModule = await import(
+				/* @vite-ignore */
+				freshSrc
+);
+			const Component = this.resolveComponent(componentModule, src);
+			await adapter.update(island, Component, props);
+			if (state) {
+				adapter.restoreState(island, state);
+				this.stateSnapshots.delete(this.getIslandId(island));
+			}
+			island.dataset.hydrated = "true";
+			island.dispatchEvent(new CustomEvent("hmr-update", {
+				detail: {
+					framework,
+					src,
+					timestamp: Date.now(),
+					success: true
+				},
+				bubbles: true
+			}));
+		} catch (error) {
+			console.error(`[HMR] Failed to update ${framework} island ${src}:`, error);
+			adapter.handleError(island, error);
+			island.dispatchEvent(new CustomEvent("hmr-error", {
+				detail: {
+					framework,
+					src,
+					error: error.message,
+					timestamp: Date.now()
+				},
+				bubbles: true
+			}));
+			throw error;
+		}
+	}
+	resolveComponent(componentModule, src) {
+		if (componentModule.default) return componentModule.default;
+		for (const key of Object.keys(componentModule)) {
+			if (key === "default") continue;
+			const value = componentModule[key];
+			if (typeof value === "function" && value.prototype) {
+				return value;
+			}
+		}
+		throw new Error(`Component ${src} has no default export`);
+	}
+	handleBeforeFullReload() {
+		const islands = document.querySelectorAll("[data-hydrated=\"true\"]");
+		const states = {};
+		for (const island of islands) {
+			const framework = island.dataset.framework;
+			const src = island.dataset.src;
+			if (!framework || !src) continue;
+			const adapter = this.registry.get(framework.toLowerCase());
+			if (!adapter) continue;
+			const state = adapter.preserveState(island);
+			if (state) {
+				states[src] = state;
+			}
+		}
+		try {
+			sessionStorage.setItem("__avalon_hmr_states__", JSON.stringify(states));
+		} catch (error) {
+			console.warn("[HMR] Failed to save states:", error);
+		}
+	}
+	handleError(payload) {
+		const error = new Error(payload.err.message);
+		error.stack = payload.err.stack;
+		console.error("[HMR] Error:", error);
+		if (globalThis.window !== undefined) {
+			// @ts-ignore - dynamic import of JS file
+			import("./hmr-error-overlay.js").then(({ showHMRErrorOverlay }) => {
+				showHMRErrorOverlay({
+					framework: "unknown",
+					src: "unknown",
+					error,
+					filePath: payload.err.id || payload.err.loc?.file || "unknown",
+					line: payload.err.loc?.line,
+					column: payload.err.loc?.column
+				});
+			}).catch(() => {
+				console.error("[HMR] Failed to show error overlay");
+			});
+		}
+	}
+	normalizePath(path) {
+		return path.replaceAll("\\", "/").replace(/^\//, "").replace(/\?.*$/, "").replace(/#.*$/, "").replace(/^src\//, "");
+	}
+	isIslandModule(path) {
+		return path.includes("/islands/") || path.includes("\\islands\\");
+	}
+	getIslandId(island) {
+		const src = island.dataset.src ?? "";
+		const framework = island.dataset.framework ?? "";
+		const index = Array.from(document.querySelectorAll(`[data-src="${src}"]`)).indexOf(island);
+		return `${framework}:${src}:${index}`;
+	}
+}
+/**
+* Global HMR coordinator instance
+*/
+let coordinatorInstance = null;
+export function getHMRCoordinator() {
+	coordinatorInstance ??= new HMRCoordinator();
+	return coordinatorInstance;
+}
+export function initializeHMR() {
+	// @ts-ignore - Vite HMR is available in browser context
+	if (!import.meta.hot) {
+		return;
+	}
+	const coordinator = getHMRCoordinator();
+	coordinator.initialize();
+}

package/src/client/main.js

@@ -608,7 +608,7 @@ if (import.meta.hot) {
 	import.meta.hot.accept();
 
 	// Lazy HMR adapter registration - only load adapters for frameworks used on the page
-	import('./hmr-coordinator.ts')
+	import('./hmr-coordinator.js')
 		.then(async ({ initializeHMR, getHMRCoordinator }) => {
 			initializeHMR();
 
@@ -623,13 +623,13 @@ if (import.meta.hot) {
 
 			// Only register adapters for frameworks that are used
 			const adapterLoaders = {
-				react: () => import('./adapters/react-adapter.ts').then(m => m.reactAdapter),
-				preact: () => import('./adapters/preact-adapter.ts').then(m => m.preactAdapter),
-				vue: () => import('./adapters/vue-adapter.ts').then(m => m.vueAdapter),
-				svelte: () => import('./adapters/svelte-adapter.ts').then(m => m.svelteAdapter),
-				solid: () => import('./adapters/solid-adapter.ts').then(m => m.solidAdapter),
-				lit: () => import('./adapters/lit-adapter.ts').then(m => m.litAdapter),
-				qwik: () => import('./adapters/qwik-adapter.ts').then(m => m.qwikAdapter),
+				react: () => import('./adapters/react-adapter.js').then(m => m.reactAdapter),
+				preact: () => import('./adapters/preact-adapter.js').then(m => m.preactAdapter),
+				vue: () => import('./adapters/vue-adapter.js').then(m => m.vueAdapter),
+				svelte: () => import('./adapters/svelte-adapter.js').then(m => m.svelteAdapter),
+				solid: () => import('./adapters/solid-adapter.js').then(m => m.solidAdapter),
+				lit: () => import('./adapters/lit-adapter.js').then(m => m.litAdapter),
+				qwik: () => import('./adapters/qwik-adapter.js').then(m => m.qwikAdapter),
 			};
 
 			for (const framework of usedFrameworks) {

package/src/vite-plugin/plugin.ts

@@ -282,20 +282,16 @@ export async function avalon(config?: AvalonPluginConfig): Promise<PluginOption[
     enforce: "pre",
 
     config() {
-      // @useavalon packages ship raw .ts source.
-      // - noExternal: Vite processes them through the transform pipeline (SSR)
-      // - oxc.exclude: Prevent Vite's built-in OXC from processing them.
-      //   Integration plugins (react, preact, etc.) set jsx: 'automatic' which
-      //   OXC then applies to ALL files including plain .ts — causing
-      //   "Invalid jsx option: automatic" errors. Our transform hook below
-      //   strips TypeScript without applying any JSX config.
+      // @useavalon packages ship raw .ts source for SSR (handled by our
+      // transform hook below) and pre-compiled .js for client-side code.
+      // Client .js files are excluded from OXC by default (/\.js$/), so
+      // integration plugins' jsx: 'automatic' config doesn't affect them.
+      // noExternal ensures Vite processes @useavalon packages through the
+      // SSR transform pipeline instead of treating them as external CJS.
       return {
         ssr: {
           noExternal: [/^@useavalon\//],
         },
-        oxc: {
-          exclude: [/node_modules\/@useavalon\//],
-        },
       };
     },
 
@@ -325,11 +321,17 @@ export async function avalon(config?: AvalonPluginConfig): Promise<PluginOption[
     },
 
     async transform(code: string, id: string) {
-      // Strip TypeScript from @useavalon packages in node_modules.
-      // We exclude these from Vite's OXC (via oxc.exclude) because integration
-      // plugins set jsx: 'automatic' which OXC applies to all files, breaking
-      // plain .ts files. We handle TS stripping ourselves with no JSX config.
-      if (id.includes('node_modules/@useavalon/') && /\.tsx?$/.test(id)) {
+      // For SSR: strip TypeScript from @useavalon packages ourselves.
+      // Integration plugins (react, preact) set jsx: 'automatic' which Vite's
+      // OXC applies to all files — causing "Invalid jsx option" errors on
+      // plain .ts files during SSR. We intercept and strip TS without JSX config.
+      // For client-side: main.js imports pre-compiled .js files that OXC
+      // skips entirely (default exclude: /\.js$/), avoiding the jsx conflict.
+      if (
+        this.environment?.config?.consumer === 'server' &&
+        id.includes('@useavalon/') &&
+        /\.tsx?$/.test(id)
+      ) {
         const { transform: oxcTransform } = await import('oxc-transform');
         const result = await oxcTransform(id, code, {
           sourcemap: true,