@ecopages/lit 0.2.0-beta.9 → 0.2.0-rc.1

package/src/lit-ssr-lazy-preloader.js

@@ -1,167 +1,169 @@
-import { AssetFactory } from "@ecopages/core/services/asset-processing-service";
-import path from "node:path";
-import { pathToFileURL } from "node:url";
-class LitSsrLazyPreloader {
-  resolveDependencyPath;
-  processDependencies;
-  preferSourceImports;
-  ssrPreloadedScripts = /* @__PURE__ */ new Set();
-  ssrPreloadFailedScripts = /* @__PURE__ */ new Set();
-  ssrPreloadEntrypointCache = /* @__PURE__ */ new Map();
-  constructor({ resolveDependencyPath, processDependencies, preferSourceImports }) {
-    this.resolveDependencyPath = resolveDependencyPath;
-    this.processDependencies = processDependencies;
-    this.preferSourceImports = preferSourceImports ?? typeof Bun !== "undefined";
-  }
-  getErrorCode(error) {
-    if (typeof error !== "object" || error === null) {
-      return "";
+import { getComponentIdentity } from '@ecopages/core';
+import { AssetFactory } from '@ecopages/core/services/asset-processing-service';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+/**
+ * Encapsulates SSR lazy script preload behavior for Lit components.
+ *
+ * Collects `dependencies.scripts` lazy entries with `ssr: true`, resolves the
+ * processed entrypoint through the asset pipeline, and imports the module so
+ * custom elements are registered before SSR rendering.
+ */
+export class LitSsrLazyPreloader {
+    resolveDependencyPath;
+    processDependencies;
+    preferSourceImports;
+    ssrPreloadedScripts = new Set();
+    ssrPreloadFailedScripts = new Set();
+    ssrPreloadEntrypointCache = new Map();
+    constructor({ resolveDependencyPath, processDependencies, preferSourceImports }) {
+        this.resolveDependencyPath = resolveDependencyPath;
+        this.processDependencies = processDependencies;
+        this.preferSourceImports = preferSourceImports ?? typeof Bun !== 'undefined';
     }
-    const code = Reflect.get(error, "code");
-    return code === void 0 ? "" : String(code);
-  }
-  /**
-   * Detects preload failures that are expected for browser-only modules.
-   */
-  isExpectedSsrPreloadError(error) {
-    const errorMessage = error instanceof Error ? error.message : String(error);
-    const errorCode = this.getErrorCode(error);
-    if (errorCode === "ERR_UNKNOWN_FILE_EXTENSION") {
-      return true;
+    getErrorCode(error) {
+        if (typeof error !== 'object' || error === null) {
+            return '';
+        }
+        const code = Reflect.get(error, 'code');
+        return code === undefined ? '' : String(code);
     }
-    return errorMessage.includes(`reading 'Element'`) || errorMessage.includes("window is not defined") || errorMessage.includes("document is not defined") || errorMessage.includes("navigator is not defined");
-  }
-  /**
-   * Collects lazy script file paths eligible for SSR preloading.
-   */
-  collectSsrPreloadScripts(components) {
-    const scriptPaths = /* @__PURE__ */ new Set();
-    const visitedConfigs = /* @__PURE__ */ new Set();
-    const collect = (component) => {
-      const config = component?.config;
-      if (!config || visitedConfigs.has(config)) {
-        return;
-      }
-      visitedConfigs.add(config);
-      const scriptEntries = config.dependencies?.scripts ?? [];
-      const componentFile = config.__eco?.file;
-      if (componentFile) {
-        const componentDir = path.dirname(componentFile);
-        for (const script of scriptEntries) {
-          if (typeof script === "string") {
-            continue;
-          }
-          if (!script.lazy || script.ssr !== true) {
-            continue;
-          }
-          if (!script.src) {
-            continue;
-          }
-          scriptPaths.add(this.resolveDependencyPath(componentDir, script.src));
+    /**
+     * Detects preload failures that are expected for browser-only modules.
+     */
+    isExpectedSsrPreloadError(error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        const errorCode = this.getErrorCode(error);
+        if (errorCode === 'ERR_UNKNOWN_FILE_EXTENSION') {
+            return true;
         }
-      }
-      if (config.layout) {
-        collect(config.layout);
-      }
-      for (const nestedComponent of config.dependencies?.components || []) {
-        collect(nestedComponent);
-      }
-    };
-    for (const component of components) {
-      collect(component);
+        return (errorMessage.includes(`reading 'Element'`) ||
+            errorMessage.includes('window is not defined') ||
+            errorMessage.includes('document is not defined') ||
+            errorMessage.includes('navigator is not defined'));
     }
-    return Array.from(scriptPaths);
-  }
-  /**
-   * Preloads SSR-eligible lazy scripts to register custom elements before render.
-   */
-  async preloadSsrLazyScripts(components) {
-    const scripts = this.collectSsrPreloadScripts(components);
-    if (scripts.length === 0) {
-      return;
+    /**
+     * Collects lazy script file paths eligible for SSR preloading.
+     */
+    collectSsrPreloadScripts(components) {
+        const scriptPaths = new Set();
+        const visitedConfigs = new Set();
+        const collect = (component) => {
+            const config = component?.config;
+            if (!config || visitedConfigs.has(config)) {
+                return;
+            }
+            visitedConfigs.add(config);
+            const scriptEntries = config.dependencies?.scripts ?? [];
+            const componentFile = getComponentIdentity(component)?.file;
+            if (componentFile) {
+                const componentDir = path.dirname(componentFile);
+                for (const script of scriptEntries) {
+                    if (typeof script === 'string') {
+                        continue;
+                    }
+                    if (!script.lazy || script.ssr !== true) {
+                        continue;
+                    }
+                    if (!script.src) {
+                        continue;
+                    }
+                    scriptPaths.add(this.resolveDependencyPath(componentDir, script.src));
+                }
+            }
+            for (const layout of config.layouts ?? []) {
+                collect(layout);
+            }
+            for (const nestedComponent of config.dependencies?.components || []) {
+                collect(nestedComponent);
+            }
+        };
+        for (const component of components) {
+            collect(component);
+        }
+        return Array.from(scriptPaths);
     }
-    await Promise.all(
-      scripts.filter((scriptPath) => {
-        if (this.ssrPreloadedScripts.has(scriptPath)) {
-          return false;
+    /**
+     * Preloads SSR-eligible lazy scripts to register custom elements before render.
+     */
+    async preloadSsrLazyScripts(components) {
+        const scripts = this.collectSsrPreloadScripts(components);
+        if (scripts.length === 0) {
+            return;
         }
-        if (this.ssrPreloadFailedScripts.has(scriptPath)) {
-          return false;
+        await Promise.all(scripts
+            .filter((scriptPath) => {
+            if (this.ssrPreloadedScripts.has(scriptPath)) {
+                return false;
+            }
+            if (this.ssrPreloadFailedScripts.has(scriptPath)) {
+                return false;
+            }
+            return true;
+        })
+            .map(async (scriptPath) => {
+            const preloadEntrypoint = await this.resolveSsrPreloadEntrypoint(scriptPath);
+            if (!preloadEntrypoint) {
+                this.ssrPreloadFailedScripts.add(scriptPath);
+                return;
+            }
+            try {
+                await import(/* @vite-ignore */ pathToFileURL(preloadEntrypoint).href);
+                this.ssrPreloadedScripts.add(scriptPath);
+            }
+            catch (error) {
+                this.ssrPreloadFailedScripts.add(scriptPath);
+                if (this.isExpectedSsrPreloadError(error)) {
+                    if (process.env.ECOPAGES_DEBUG === 'true') {
+                        console.warn(`[ecopages][lit] Skipping SSR preload for browser-only lazy script: ${scriptPath}`);
+                    }
+                    return;
+                }
+                console.warn(`[ecopages][lit] Failed to preload lazy SSR script: ${scriptPath}`, error);
+            }
+        }));
+    }
+    /**
+     * Resolves the concrete JS entrypoint used for SSR preloading.
+     */
+    async resolveSsrPreloadEntrypoint(scriptPath) {
+        const cachedEntrypoint = this.ssrPreloadEntrypointCache.get(scriptPath);
+        if (cachedEntrypoint) {
+            return cachedEntrypoint;
         }
-        return true;
-      }).map(async (scriptPath) => {
-        const preloadEntrypoint = await this.resolveSsrPreloadEntrypoint(scriptPath);
-        if (!preloadEntrypoint) {
-          this.ssrPreloadFailedScripts.add(scriptPath);
-          return;
+        if (this.preferSourceImports) {
+            this.ssrPreloadEntrypointCache.set(scriptPath, scriptPath);
+            return scriptPath;
+        }
+        if (!this.processDependencies) {
+            this.ssrPreloadEntrypointCache.set(scriptPath, scriptPath);
+            return scriptPath;
         }
         try {
-          await import(
-            /* @vite-ignore */
-            pathToFileURL(preloadEntrypoint).href
-          );
-          this.ssrPreloadedScripts.add(scriptPath);
-        } catch (error) {
-          this.ssrPreloadFailedScripts.add(scriptPath);
-          if (this.isExpectedSsrPreloadError(error)) {
-            if (process.env.ECOPAGES_DEBUG === "true") {
-              console.warn(
-                `[ecopages][lit] Skipping SSR preload for browser-only lazy script: ${scriptPath}`
-              );
+            const processed = await this.processDependencies([
+                AssetFactory.createInlineFileScript({
+                    filepath: scriptPath,
+                    position: 'head',
+                    bundle: true,
+                    attributes: {
+                        type: 'module',
+                        defer: '',
+                    },
+                }),
+            ], `lit-ssr-preload:${scriptPath}`);
+            const entrypoint = processed[0]?.filepath;
+            if (!entrypoint) {
+                return scriptPath;
             }
-            return;
-          }
-          console.warn(`[ecopages][lit] Failed to preload lazy SSR script: ${scriptPath}`, error);
+            this.ssrPreloadEntrypointCache.set(scriptPath, entrypoint);
+            return entrypoint;
         }
-      })
-    );
-  }
-  /**
-   * Resolves the concrete JS entrypoint used for SSR preloading.
-   */
-  async resolveSsrPreloadEntrypoint(scriptPath) {
-    const cachedEntrypoint = this.ssrPreloadEntrypointCache.get(scriptPath);
-    if (cachedEntrypoint) {
-      return cachedEntrypoint;
-    }
-    if (this.preferSourceImports) {
-      this.ssrPreloadEntrypointCache.set(scriptPath, scriptPath);
-      return scriptPath;
-    }
-    if (!this.processDependencies) {
-      this.ssrPreloadEntrypointCache.set(scriptPath, scriptPath);
-      return scriptPath;
-    }
-    try {
-      const processed = await this.processDependencies(
-        [
-          AssetFactory.createInlineFileScript({
-            filepath: scriptPath,
-            position: "head",
-            bundle: true,
-            attributes: {
-              type: "module",
-              defer: ""
+        catch (error) {
+            if (process.env.ECOPAGES_DEBUG === 'true') {
+                console.warn(`[ecopages][lit] Failed to resolve SSR preload entrypoint for: ${scriptPath}`, error);
             }
-          })
-        ],
-        `lit-ssr-preload:${scriptPath}`
-      );
-      const entrypoint = processed[0]?.filepath;
-      if (!entrypoint) {
-        return scriptPath;
-      }
-      this.ssrPreloadEntrypointCache.set(scriptPath, entrypoint);
-      return entrypoint;
-    } catch (error) {
-      if (process.env.ECOPAGES_DEBUG === "true") {
-        console.warn(`[ecopages][lit] Failed to resolve SSR preload entrypoint for: ${scriptPath}`, error);
-      }
-      this.ssrPreloadEntrypointCache.set(scriptPath, scriptPath);
-      return scriptPath;
+            this.ssrPreloadEntrypointCache.set(scriptPath, scriptPath);
+            return scriptPath;
+        }
     }
-  }
 }
-export {
-  LitSsrLazyPreloader
-};

package/src/lit-static-render-protocol.d.ts

@@ -1,3 +1,5 @@
+import type { PageParams, PageQuery, RouteRenderResult } from '@ecopages/core';
+export type LitStaticRenderCacheStrategy = RouteRenderResult['cacheStrategy'];
 export type LitStaticRenderWorkerInitMessage = {
     type: 'init';
     configModulePath: string;
@@ -7,7 +9,10 @@ export type LitStaticRenderWorkerRenderMessage = {
     type: 'render';
     id: string;
     filePath: string;
-    params: Record<string, string>;
+    /** Route params; multi-value keys stay as `string[]`. */
+    params: PageParams;
+    /** Serializable route query; preserves multi-value keys as `string[]`. */
+    query?: PageQuery;
 };
 export type LitStaticRenderWorkerShutdownMessage = {
     type: 'shutdown';
@@ -20,6 +25,7 @@ export type LitStaticRenderWorkerResultMessage = {
     type: 'result';
     id: string;
     html: string;
+    cacheStrategy?: LitStaticRenderCacheStrategy;
 };
 export type LitStaticRenderWorkerErrorMessage = {
     type: 'error';

package/src/lit-static-render-protocol.js

@@ -0,0 +1 @@
+export {};

package/src/lit-static-render-session.d.ts

@@ -1,23 +1,45 @@
-import type { EcoComponent } from '@ecopages/core';
+import type { EcoComponent, PageParams, PageQuery } from '@ecopages/core';
 import type { StaticExportContext } from '@ecopages/core/plugins/integration-plugin';
 import type { AssetDefinition } from '@ecopages/core/services/asset-processing-service';
+import { LitStaticRenderWorkerClient } from './lit-static-render-worker-client.js';
+import type { LitStaticRenderCacheStrategy } from './lit-static-render-protocol.js';
+type LitStaticRenderWorkerClientContract = Pick<LitStaticRenderWorkerClient, 'start' | 'renderPage' | 'dispose'>;
 type LitStaticRenderSessionOptions = {
     resolveDependencyPath: (componentDir: string, sourcePath: string) => string;
     processDependencies?: (dependencies: AssetDefinition[], integrationName: string) => Promise<Array<{
         filepath?: string;
     }>>;
     preferSourceImports?: boolean;
+    createWorkerClient?: (input: {
+        configModulePath: string;
+        runtimeOrigin: string;
+    }) => LitStaticRenderWorkerClientContract;
 };
 /**
- * Build-scoped Lit server render session.
+ * Plugin-runtime-scoped Lit server render session.
+ *
+ * @remarks
+ * Owns worker lifecycle and SSR preload for Lit page routes during static export
+ * and runtime/dev requests. Injected into `LitRenderer` via a lazy accessor from
+ * `LitPlugin`; there is no process-global coordinator.
  *
- * Preloads SSR-eligible lazy scripts and renders Lit page routes through a
- * dedicated worker thread for both static export and runtime/dev requests.
+ * Worker init identity is sticky for the first `{ configModulePath, runtimeOrigin }`.
+ * Later `ensureWorker` calls with the same identity are no-ops; a different identity
+ * recreates the worker so stale config/origin is never silently reused.
  */
 export declare class LitStaticRenderSession {
     private readonly preloader;
+    private readonly createWorkerClient;
     private workerClient;
+    private workerIdentity;
     constructor(options: LitStaticRenderSessionOptions);
+    /**
+     * Ensures the static render worker is running for the given identity.
+     *
+     * @remarks
+     * First successful start sticks that identity. Matching re-entry is a no-op.
+     * A different `configModulePath` or `runtimeOrigin` disposes and recreates.
+     */
     ensureWorker(input: {
         configModulePath: string;
         runtimeOrigin: string;
@@ -27,8 +49,12 @@ export declare class LitStaticRenderSession {
     collectSsrPreloadScripts(components: Array<EcoComponent | undefined>): string[];
     renderPageInWorker(input: {
         filePath: string;
-        params: Record<string, string>;
-    }): Promise<string>;
+        params: PageParams;
+        query?: PageQuery;
+    }): Promise<{
+        html: string;
+        cacheStrategy?: LitStaticRenderCacheStrategy;
+    }>;
     isExpectedSsrPreloadError(error: unknown): boolean;
     dispose(): Promise<void>;
     private preloadLitRoutes;

package/src/lit-static-render-session.js

@@ -1,84 +1,119 @@
-import path from "node:path";
-import { LitSsrLazyPreloader } from "./lit-ssr-lazy-preloader.js";
-import { LIT_PLUGIN_NAME } from "./lit.constants.js";
-import { LitStaticRenderWorkerClient } from "./lit-static-render-worker-client.js";
-class LitStaticRenderSession {
-  preloader;
-  workerClient = null;
-  constructor(options) {
-    this.preloader = new LitSsrLazyPreloader({
-      resolveDependencyPath: options.resolveDependencyPath,
-      processDependencies: options.processDependencies,
-      preferSourceImports: options.preferSourceImports
-    });
-  }
-  async ensureWorker(input) {
-    if (this.workerClient) {
-      return;
+import path from 'node:path';
+import { LitSsrLazyPreloader } from './lit-ssr-lazy-preloader.js';
+import { LIT_PLUGIN_NAME } from './lit.constants.js';
+import { LitStaticRenderWorkerClient } from './lit-static-render-worker-client.js';
+/**
+ * Plugin-runtime-scoped Lit server render session.
+ *
+ * @remarks
+ * Owns worker lifecycle and SSR preload for Lit page routes during static export
+ * and runtime/dev requests. Injected into `LitRenderer` via a lazy accessor from
+ * `LitPlugin`; there is no process-global coordinator.
+ *
+ * Worker init identity is sticky for the first `{ configModulePath, runtimeOrigin }`.
+ * Later `ensureWorker` calls with the same identity are no-ops; a different identity
+ * recreates the worker so stale config/origin is never silently reused.
+ */
+export class LitStaticRenderSession {
+    preloader;
+    createWorkerClient;
+    workerClient = null;
+    workerIdentity = null;
+    constructor(options) {
+        this.preloader = new LitSsrLazyPreloader({
+            resolveDependencyPath: options.resolveDependencyPath,
+            processDependencies: options.processDependencies,
+            preferSourceImports: options.preferSourceImports,
+        });
+        this.createWorkerClient =
+            options.createWorkerClient ??
+                ((input) => new LitStaticRenderWorkerClient({
+                    configModulePath: input.configModulePath,
+                    runtimeOrigin: input.runtimeOrigin,
+                }));
     }
-    this.workerClient = new LitStaticRenderWorkerClient({
-      configModulePath: input.configModulePath,
-      runtimeOrigin: input.runtimeOrigin
-    });
-    await this.workerClient.start();
-  }
-  async preloadStaticRoutes(context) {
-    await this.preloadLitRoutes(context);
-  }
-  async preloadSsrLazyScripts(components) {
-    await this.preloader.preloadSsrLazyScripts(components);
-  }
-  collectSsrPreloadScripts(components) {
-    return this.preloader.collectSsrPreloadScripts(components);
-  }
-  async renderPageInWorker(input) {
-    if (!this.workerClient) {
-      throw new Error("Lit static render worker is not active");
+    /**
+     * Ensures the static render worker is running for the given identity.
+     *
+     * @remarks
+     * First successful start sticks that identity. Matching re-entry is a no-op.
+     * A different `configModulePath` or `runtimeOrigin` disposes and recreates.
+     */
+    async ensureWorker(input) {
+        if (this.workerClient &&
+            this.workerIdentity &&
+            this.workerIdentity.configModulePath === input.configModulePath &&
+            this.workerIdentity.runtimeOrigin === input.runtimeOrigin) {
+            return;
+        }
+        if (this.workerClient) {
+            await this.dispose();
+        }
+        this.workerIdentity = {
+            configModulePath: input.configModulePath,
+            runtimeOrigin: input.runtimeOrigin,
+        };
+        this.workerClient = this.createWorkerClient({
+            configModulePath: input.configModulePath,
+            runtimeOrigin: input.runtimeOrigin,
+        });
+        await this.workerClient.start();
+    }
+    async preloadStaticRoutes(context) {
+        await this.preloadLitRoutes(context);
     }
-    return this.workerClient.renderPage(input);
-  }
-  isExpectedSsrPreloadError(error) {
-    return this.preloader.isExpectedSsrPreloadError(error);
-  }
-  async dispose() {
-    await this.workerClient?.dispose();
-    this.workerClient = null;
-  }
-  async preloadLitRoutes(context) {
-    if (!context.routeRendererFactory) {
-      return;
+    async preloadSsrLazyScripts(components) {
+        await this.preloader.preloadSsrLazyScripts(components);
     }
-    const routes = await context.router.listStaticGenerationRoutes({ runtimeOrigin: context.baseUrl });
-    const components = [];
-    for (const route of routes) {
-      const filePath = route.templateRoute.filePath;
-      if (!this.isLitRoute(filePath, context.appConfig)) {
-        continue;
-      }
-      const pageRenderer = context.routeRendererFactory.getPageRenderer(filePath);
-      const pageModule = await pageRenderer.loadPageModule(filePath);
-      const page = pageModule.default;
-      if (page) {
-        components.push(page);
-        if (page.config?.layout) {
-          components.push(page.config.layout);
+    collectSsrPreloadScripts(components) {
+        return this.preloader.collectSsrPreloadScripts(components);
+    }
+    async renderPageInWorker(input) {
+        if (!this.workerClient) {
+            throw new Error('Lit static render worker is not active');
         }
-        for (const nestedComponent of page.config?.dependencies?.components ?? []) {
-          components.push(nestedComponent);
+        return this.workerClient.renderPage(input);
+    }
+    isExpectedSsrPreloadError(error) {
+        return this.preloader.isExpectedSsrPreloadError(error);
+    }
+    async dispose() {
+        await this.workerClient?.dispose();
+        this.workerClient = null;
+        this.workerIdentity = null;
+    }
+    async preloadLitRoutes(context) {
+        if (!context.routeRendererFactory) {
+            return;
         }
-      }
+        const routes = await context.router.listStaticGenerationRoutes({ runtimeOrigin: context.baseUrl });
+        const components = [];
+        for (const route of routes) {
+            const filePath = route.templateRoute.filePath;
+            if (!this.isLitRoute(filePath, context.appConfig)) {
+                continue;
+            }
+            const pageRenderer = context.routeRendererFactory.getPageRenderer(filePath);
+            const pageModule = await pageRenderer.loadPageModule(filePath);
+            const page = pageModule.default;
+            if (page) {
+                components.push(page);
+                for (const layout of page.config?.layouts ?? []) {
+                    components.push(layout);
+                }
+                for (const nestedComponent of page.config?.dependencies?.components ?? []) {
+                    components.push(nestedComponent);
+                }
+            }
+        }
+        await this.preloadSsrLazyScripts(components);
     }
-    await this.preloadSsrLazyScripts(components);
-  }
-  isLitRoute(filePath, appConfig) {
-    const litIntegration = appConfig.integrations.find((plugin) => plugin.name === LIT_PLUGIN_NAME);
-    if (!litIntegration) {
-      return false;
+    isLitRoute(filePath, appConfig) {
+        const litIntegration = appConfig.integrations.find((plugin) => plugin.name === LIT_PLUGIN_NAME);
+        if (!litIntegration) {
+            return false;
+        }
+        const normalizedPath = path.normalize(filePath);
+        return litIntegration.extensions.some((extension) => normalizedPath.endsWith(extension));
     }
-    const normalizedPath = path.normalize(filePath);
-    return litIntegration.extensions.some((extension) => normalizedPath.endsWith(extension));
-  }
 }
-export {
-  LitStaticRenderSession
-};

package/src/lit-static-render-worker-client.d.ts

@@ -1,3 +1,5 @@
+import type { PageParams, PageQuery } from '@ecopages/core';
+import type { LitStaticRenderCacheStrategy } from './lit-static-render-protocol.js';
 export declare class LitStaticRenderWorkerClient {
     private readonly configModulePath;
     private readonly runtimeOrigin;
@@ -13,8 +15,12 @@ export declare class LitStaticRenderWorkerClient {
     start(): Promise<void>;
     renderPage(input: {
         filePath: string;
-        params: Record<string, string>;
-    }): Promise<string>;
+        params: PageParams;
+        query?: PageQuery;
+    }): Promise<{
+        html: string;
+        cacheStrategy?: LitStaticRenderCacheStrategy;
+    }>;
     dispose(): Promise<void>;
 }
 export declare const litStaticRenderWorkerEntryPath: string;