@useavalon/avalon 0.1.11 → 0.1.13

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

@@ -1,524 +0,0 @@
-/**
- * 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, type StateSnapshot } from '../framework-adapter.ts';
-
-/**
- * Svelte component class type
- * Svelte components are compiled to classes with specific methods
- */
-interface SvelteComponent {
-  /**
-   * Create a new component instance
-   */
-  new (options: SvelteComponentOptions): SvelteComponentInstance;
-
-  /**
-   * Svelte component marker
-   */
-  $render?: unknown;
-}
-
-/**
- * Svelte component constructor options
- */
-interface SvelteComponentOptions {
-  /** Target DOM element */
-  target: HTMLElement;
-  /** Component props */
-  props?: Record<string, unknown>;
-  /** Hydration mode */
-  hydrate?: boolean;
-  /** Intro animations */
-  intro?: boolean;
-  /** Anchor element for insertion */
-  anchor?: Element | null;
-  /** Context for component */
-  context?: Map<unknown, unknown>;
-}
-
-/**
- * Svelte component instance interface
- */
-interface SvelteComponentInstance {
-  /** Update component props */
-  $set(props: Record<string, unknown>): void;
-  /** Destroy component instance */
-  $destroy(): void;
-  /** Subscribe to component events */
-  $on?(event: string, handler: (...args: unknown[]) => void): () => void;
-  /** Access to component state (internal) */
-  $$?: {
-    ctx?: unknown[];
-    props?: Record<string, unknown>;
-    bound?: Record<string, unknown>;
-  };
-}
-
-/**
- * Svelte store interface
- */
-interface SvelteStore<T = unknown> {
-  subscribe(subscriber: (value: T) => void): () => void;
-  set?(value: T): void;
-  update?(updater: (value: T) => T): void;
-}
-
-/**
- * Svelte-specific state snapshot
- * Extends base snapshot with Svelte-specific state like local state and stores
- */
-interface SvelteStateSnapshot extends StateSnapshot {
-  framework: 'svelte';
-  data: {
-    /**
-     * Svelte component local state
-     * Captured from component instance
-     */
-    localState?: Record<string, unknown>;
-    
-    /**
-     * Store subscriptions and values
-     * Captured from active stores
-     */
-    storeValues?: Record<string, unknown>;
-    
-    /**
-     * Component display name for debugging
-     */
-    componentName?: string;
-    
-    /**
-     * Props at time of state capture
-     */
-    capturedProps?: Record<string, unknown>;
-    
-    /**
-     * Reactive statement dependencies
-     */
-    reactiveDependencies?: string[];
-  };
-}
-
-/**
- * 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 {
-  readonly name = 'svelte';
-  
-  /**
-   * Store Svelte component instances for each island to enable proper cleanup
-   */
-  private readonly instances: WeakMap<HTMLElement, SvelteComponentInstance> = new WeakMap();
-  
-  /**
-   * Store component IDs for tracking
-   */
-  private readonly componentIds: WeakMap<HTMLElement, string> = new WeakMap();
-  
-  /**
-   * Store active store subscriptions for cleanup
-   */
-  private readonly storeSubscriptions: WeakMap<HTMLElement, Array<() => void>> = new WeakMap();
-
-  /**
-   * Check if a function/class has Svelte component markers
-   */
-  private isSvelteFunction(component: Function): boolean {
-    const comp = component as unknown as Record<string, unknown>;
-
-    if (comp.$$render) {
-      return true;
-    }
-
-    const proto = (component as { prototype?: Record<string, unknown> }).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 {
-      // Ignore errors from toString()
-    }
-
-    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: unknown): boolean {
-    if (!component) return false;
-
-    if (typeof component === 'function') {
-      return this.isSvelteFunction(component);
-    }
-
-    if (typeof component !== 'object') {
-      return false;
-    }
-
-    const obj = component as Record<string, unknown>;
-
-    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.
-   */
-  override preserveState(island: HTMLElement): SvelteStateSnapshot | null {
-    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: SvelteStateSnapshot = {
-        ...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
-   */
-  private extractComponent(newComponent: unknown): SvelteComponent {
-    if (typeof newComponent === 'object' && newComponent !== null) {
-      const obj = newComponent as Record<string, unknown>;
-      if (obj.default && typeof obj.default === 'function') {
-        return obj.default as SvelteComponent;
-      }
-      throw new Error('Svelte component object must have a default export');
-    }
-    if (typeof newComponent === 'function') {
-      return newComponent as SvelteComponent;
-    }
-    throw new TypeError('Invalid Svelte component type');
-  }
-
-  /**
-   * Clean up an existing Svelte component instance
-   */
-  private async cleanupInstance(island: HTMLElement, instance: SvelteComponentInstance): Promise<void> {
-    try {
-      const subscriptions = this.storeSubscriptions.get(island);
-      if (subscriptions) {
-        subscriptions.forEach(unsubscribe => unsubscribe());
-        this.storeSubscriptions.delete(island);
-      }
-
-      const svelteModule = await import('svelte') as Record<string, unknown>;
-      const svelteUnmount = svelteModule.unmount as ((component: unknown) => void) | undefined;
-      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
-   */
-  private async mountComponent(
-    Component: SvelteComponent,
-    island: HTMLElement,
-    props: Record<string, unknown>
-  ): Promise<SvelteComponentInstance> {
-    try {
-      const svelteModule = await import('svelte') as Record<string, unknown>;
-      const svelteMount = svelteModule.mount as ((component: unknown, options: { target: HTMLElement; props: Record<string, unknown> }) => unknown) | undefined;
-
-      if (svelteMount) {
-        return svelteMount(Component as any, { target: island, props }) as SvelteComponentInstance;
-      }
-
-      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: HTMLElement,
-    newComponent: unknown,
-    props: Record<string, unknown>
-  ): Promise<void> {
-    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).
-   */
-  override restoreState(island: HTMLElement, state: StateSnapshot): void {
-    try {
-      // Restore DOM state (scroll, focus, form values)
-      super.restoreState(island, state);
-      
-      // Note: Svelte 5 does NOT preserve local state during HMR
-      // This is by design - see https://github.com/sveltejs/vite-plugin-svelte/blob/main/docs/faq.md
-      // CSS-only changes DO preserve state 100%
-      
-    } catch (error) {
-      console.warn('Failed to restore Svelte state:', error);
-    }
-  }
-
-  /**
-   * Handle errors during Svelte HMR update
-   * 
-   * Provides Svelte-specific error handling with helpful messages
-   */
-  override handleError(island: HTMLElement, error: Error): void {
-    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
-   */
-  private extractComponentName(src: string): string {
-    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
-   */
-  private detectSSRContent(island: HTMLElement): boolean {
-    // 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
-   */
-  private generateComponentId(src: string): string {
-    // 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
-   */
-  private captureLocalState(island: HTMLElement): Record<string, unknown> | undefined {
-    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
-   */
-  private captureStoreValues(_island: HTMLElement): Record<string, unknown> | undefined {
-    // 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: HTMLElement): Promise<void> {
-    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();