@useavalon/avalon 0.1.0

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

@@ -0,0 +1,331 @@
+/**
+ * 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, type StateSnapshot } from '../framework-adapter.ts';
+
+/**
+ * Preact component type
+ * Can be a function component or class component
+ */
+type PreactComponent<P = Record<string, unknown>> = 
+  | ((props: P) => PreactVNode | null)
+  | (new (props: P) => PreactClassComponent);
+
+/**
+ * Preact class component interface
+ */
+interface PreactClassComponent {
+  render(): PreactVNode | null;
+  isReactComponent?: boolean; // Preact uses same marker as React
+}
+
+/**
+ * Preact VNode (Virtual Node) type
+ */
+interface PreactVNode {
+  type: string | PreactComponent;
+  props: Record<string, unknown>;
+  key: string | number | null;
+}
+
+/**
+ * Preact module interface
+ */
+interface PreactModule {
+  h<P = Record<string, unknown>>(
+    component: PreactComponent<P> | string,
+    props: P | null,
+    ...children: unknown[]
+  ): PreactVNode;
+  render(vnode: PreactVNode, container: HTMLElement): void;
+  hydrate(vnode: PreactVNode, container: HTMLElement): void;
+}
+
+/**
+ * Preact-specific state snapshot
+ * Extends base snapshot with Preact-specific state like hooks
+ */
+interface PreactStateSnapshot extends StateSnapshot {
+  framework: 'preact';
+  data: {
+    /**
+     * Preact component tree data (if accessible)
+     * Used by Preact HMR to preserve hooks state
+     */
+    componentData?: unknown;
+    
+    /**
+     * Component display name for debugging
+     */
+    componentName?: string;
+    
+    /**
+     * Props at time of state capture
+     */
+    capturedProps?: Record<string, unknown>;
+  };
+}
+
+/**
+ * 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 {
+  readonly name = 'preact';
+  
+  /**
+   * Store Preact component instances for each island to enable proper updates
+   */
+  private instances: WeakMap<HTMLElement, unknown> = 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: unknown): boolean {
+    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 as unknown as Record<string, unknown>;
+      
+      // Class components have isReactComponent on prototype
+      // (Preact uses the same marker for compatibility)
+      const proto = (component as { prototype?: Record<string, unknown> }).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 as Record<string, unknown>;
+    
+    // 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.
+   */
+  override preserveState(island: HTMLElement): PreactStateSnapshot | null {
+    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: PreactStateSnapshot = {
+        ...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: HTMLElement,
+    newComponent: unknown,
+    props: Record<string, unknown>
+  ): Promise<void> {
+    if (!this.canHandle(newComponent)) {
+      throw new Error('Component is not a valid Preact component');
+    }
+
+    const Component = newComponent as PreactComponent;
+
+    try {
+      // Dynamically import Preact at runtime
+      // This is resolved by Vite in the browser
+      const preactModule = await import('preact') as PreactModule;
+      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.
+   */
+  override restoreState(island: HTMLElement, state: StateSnapshot): void {
+    try {
+      // Restore DOM state (scroll, focus, form values)
+      super.restoreState(island, state);
+      
+      // Preact HMR handles hooks state restoration automatically
+      // through the component tree, so we don't need to do anything special here
+      
+    } catch (error) {
+      console.warn('Failed to restore Preact state:', error);
+    }
+  }
+
+  /**
+   * Handle errors during Preact HMR update
+   * 
+   * Provides Preact-specific error handling with helpful messages
+   */
+  override handleError(island: HTMLElement, error: Error): void {
+    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
+   */
+  private extractComponentName(src: string): string {
+    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: HTMLElement): void {
+    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.ts

@@ -0,0 +1,345 @@
+/**
+ * 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, type StateSnapshot } from '../framework-adapter.ts';
+
+/**
+ * Qwik component type
+ * Qwik components are created with component$() which returns a QRL-wrapped component
+ */
+type QwikComponent<P = Record<string, unknown>> = {
+	(props: P): unknown;
+	__brand?: 'QwikComponent';
+};
+
+/**
+ * Qwik module interface for SSR/client rendering
+ */
+interface QwikModule {
+	renderToString?: (opts: Record<string, unknown>) => Promise<string>;
+	render?: (parent: Element, jsxNode: unknown) => Promise<void>;
+}
+
+/**
+ * Qwik state snapshot extending base state
+ */
+interface QwikStateSnapshot extends StateSnapshot {
+	framework: 'qwik';
+	data: {
+		componentName: string;
+		capturedProps: Record<string, unknown>;
+		containerState: string | null;
+		qContainerAttrs: Record<string, string>;
+	};
+}
+
+/**
+ * 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 {
+  readonly name = 'qwik';
+
+  /**
+   * Track container elements for cleanup
+   */
+  private containers: WeakMap<HTMLElement, { cleanup?: () => void }> = 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: unknown): boolean {
+    if (!component) return false;
+
+    // Check if it's a function (Qwik components are functions)
+    if (typeof component === 'function') {
+      const comp = component as unknown as Record<string, unknown>;
+
+      // 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 {
+        // Ignore errors from toString()
+      }
+    }
+
+    // Check if it's a Qwik component object (wrapped or exported)
+    if (typeof component === 'object' && component !== null) {
+      const obj = component as Record<string, unknown>;
+
+      // 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.
+   */
+  override preserveState(island: HTMLElement): QwikStateSnapshot | null {
+    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: Record<string, string> = {};
+      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: HTMLElement,
+    newComponent: unknown,
+    props: Record<string, unknown>
+  ): Promise<void> {
+    if (!this.canHandle(newComponent)) {
+      throw new Error('Component is not a valid Qwik component');
+    }
+
+    // Extract the actual component function
+    let Component: QwikComponent;
+    if (typeof newComponent === 'object' && newComponent !== null) {
+      const obj = newComponent as Record<string, unknown>;
+      if (obj.default && typeof obj.default === 'function') {
+        Component = obj.default as QwikComponent;
+      } else {
+        throw new Error('Qwik component object must have a default export');
+      }
+    } else if (typeof newComponent === 'function') {
+      Component = newComponent as QwikComponent;
+    } 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) as QwikModule & Record<string, unknown>;
+
+      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.
+   */
+  override restoreState(island: HTMLElement, state: StateSnapshot): void {
+    try {
+      // Restore DOM state (scroll, focus, form values)
+      super.restoreState(island, state);
+
+      // Qwik's resumability handles reactive state automatically
+      // through its serialized container state in the DOM
+
+    } catch (error) {
+      console.warn('Failed to restore Qwik state:', error);
+    }
+  }
+
+  /**
+   * Handle errors during Qwik HMR update
+   */
+  override handleError(island: HTMLElement, error: Error): void {
+    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
+   */
+  private extractComponentName(src: string): string {
+    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: HTMLElement): void {
+    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();