@ecopages/lit 0.2.0-beta.6 → 0.2.0-beta.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/lit",
-  "version": "0.2.0-beta.6",
+  "version": "0.2.0-beta.8",
   "description": "Ecopages lit integration",
   "keywords": [
     "ecopages",
@@ -20,9 +20,17 @@
       "default": "./src/styled-mixin.js",
       "types": "./src/styled-mixin.d.ts"
     },
+    "./static-render-worker": {
+      "default": "./src/lit-static-render-worker.js",
+      "types": "./src/lit-static-render-worker.d.ts"
+    },
     "./styled-mixin.ts": {
       "default": "./src/styled-mixin.js",
       "types": "./src/styled-mixin.d.ts"
+    },
+    "./static-render-worker.ts": {
+      "default": "./src/lit-static-render-worker.js",
+      "types": "./src/lit-static-render-worker.d.ts"
     }
   },
   "repository": {
@@ -31,7 +39,7 @@
     "directory": "packages/integrations/lit"
   },
   "peerDependencies": {
-    "@ecopages/core": "0.2.0-beta.6",
+    "@ecopages/core": "0.2.0-beta.8",
     "@lit-labs/ssr": "^3.3.0",
     "@lit-labs/ssr-client": "^1.1.7",
     "lit": "^3.2.1"

package/src/STATIC_RENDER.md

@@ -0,0 +1,47 @@
+# Lit static render worker
+
+Lit-first page routes (`.lit.tsx`) render through a dedicated worker thread during static export and runtime when the Lit plugin is active.
+
+## Flow
+
+```
+Main thread                          Worker thread
+───────────                          ─────────────
+LitPlugin.setup()
+  └─ LitStaticRenderSession.ensureWorker()
+       └─ LitStaticRenderWorkerClient.start()
+            └─ postMessage(init) ──► setupAppRuntimePlugins()
+                                     installAppRuntimeBuildExecutor()
+                                     RouteRendererFactory
+
+LitRenderer.execute() (main)
+  └─ session.renderPageInWorker()
+       └─ postMessage(render) ─────► RouteRendererFactory.execute()
+                                     (no active session in worker)
+
+beforeStaticExport
+  └─ preloadStaticRoutes()
+       └─ preload SSR lazy scripts for Lit pages
+```
+
+`ECOPAGES_LIT_STATIC_RENDER_WORKER=true` in the worker environment prevents nested worker creation during `LitPlugin.setup()`.
+
+## Files
+
+| File                                 | Role                                                            |
+| ------------------------------------ | --------------------------------------------------------------- |
+| `lit-static-render-session.ts`       | Build-scoped session: worker lifecycle + SSR preload            |
+| `lit-static-render-worker-client.ts` | Message protocol client                                         |
+| `lit-static-render-worker.ts`        | Worker entry (exported as `@ecopages/lit/static-render-worker`) |
+| `lit-static-render-protocol.ts`      | Request/response message types                                  |
+| `lit-static-render-coordinator.ts`   | Active session pointer for `LitRenderer`                        |
+
+## Protocol
+
+| Message            | Direction     | Purpose                                 |
+| ------------------ | ------------- | --------------------------------------- |
+| `init`             | main → worker | Load `eco.config.ts`, bootstrap runtime |
+| `ready`            | worker → main | Worker initialized                      |
+| `render`           | main → worker | Render one Lit page route to HTML       |
+| `result` / `error` | worker → main | Render outcome                          |
+| `shutdown`         | main → worker | Exit worker thread                      |

package/src/lit-renderer.d.ts

@@ -2,7 +2,7 @@
  * This module contains the Lit renderer
  * @module
  */
-import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, EcoPagesElement, IntegrationRendererRenderOptions, RouteRendererBody } from '@ecopages/core';
+import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, EcoPagesElement, IntegrationRendererRenderOptions, RouteRenderResult, RouteRendererBody, RouteRendererOptions } from '@ecopages/core';
 import './dom-shim.js';
 import { IntegrationRenderer, type RenderToResponseContext } from '@ecopages/core/route-renderer/integration-renderer';
 /**
@@ -10,6 +10,7 @@ import { IntegrationRenderer, type RenderToResponseContext } from '@ecopages/cor
  */
 export declare class LitRenderer extends IntegrationRenderer<EcoPagesElement> {
     name: string;
+    execute(options: RouteRendererOptions): Promise<RouteRenderResult>;
     private isFunctionComponent;
     private resolveQueuedForeignSubtreeChildren;
     private resolveQueuedForeignSubtreeHtml;

package/src/lit-renderer.js

@@ -1,5 +1,6 @@
 import "./dom-shim.js";
 import { IntegrationRenderer } from "@ecopages/core/route-renderer/integration-renderer";
+import { getActiveLitStaticRenderSession } from "./lit-static-render-coordinator.js";
 import { LitSsrLazyPreloader } from "./lit-ssr-lazy-preloader.js";
 import { LIT_PLUGIN_NAME } from "./lit.constants.js";
 import {
@@ -10,6 +11,19 @@ import {
 } from "./utils/lit-html-rendering.js";
 class LitRenderer extends IntegrationRenderer {
   name = LIT_PLUGIN_NAME;
+  async execute(options) {
+    const session = getActiveLitStaticRenderSession();
+    if (session) {
+      const html = await session.renderPageInWorker({
+        filePath: options.file,
+        params: options.params ?? {}
+      });
+      return {
+        body: html
+      };
+    }
+    return super.execute(options);
+  }
   isFunctionComponent(component) {
     return typeof component === "function";
   }
@@ -140,6 +154,11 @@ class LitRenderer extends IntegrationRenderer {
    * Preloads SSR-eligible lazy scripts to register custom elements before render.
    */
   async preloadSsrLazyScripts(components) {
+    const session = getActiveLitStaticRenderSession();
+    if (session) {
+      await session.preloadSsrLazyScripts(components);
+      return;
+    }
     await this.ssrLazyPreloader.preloadSsrLazyScripts(components);
   }
   /**

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

@@ -0,0 +1,3 @@
+import type { LitStaticRenderSession } from './lit-static-render-session.js';
+export declare function setActiveLitStaticRenderSession(session: LitStaticRenderSession | null): void;
+export declare function getActiveLitStaticRenderSession(): LitStaticRenderSession | null;

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

@@ -0,0 +1,11 @@
+let activeSession = null;
+function setActiveLitStaticRenderSession(session) {
+  activeSession = session;
+}
+function getActiveLitStaticRenderSession() {
+  return activeSession;
+}
+export {
+  getActiveLitStaticRenderSession,
+  setActiveLitStaticRenderSession
+};

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

@@ -0,0 +1,29 @@
+export type LitStaticRenderWorkerInitMessage = {
+    type: 'init';
+    configModulePath: string;
+    runtimeOrigin: string;
+};
+export type LitStaticRenderWorkerRenderMessage = {
+    type: 'render';
+    id: string;
+    filePath: string;
+    params: Record<string, string>;
+};
+export type LitStaticRenderWorkerShutdownMessage = {
+    type: 'shutdown';
+};
+export type LitStaticRenderWorkerRequestMessage = LitStaticRenderWorkerInitMessage | LitStaticRenderWorkerRenderMessage | LitStaticRenderWorkerShutdownMessage;
+export type LitStaticRenderWorkerReadyMessage = {
+    type: 'ready';
+};
+export type LitStaticRenderWorkerResultMessage = {
+    type: 'result';
+    id: string;
+    html: string;
+};
+export type LitStaticRenderWorkerErrorMessage = {
+    type: 'error';
+    id?: string;
+    message: string;
+};
+export type LitStaticRenderWorkerResponseMessage = LitStaticRenderWorkerReadyMessage | LitStaticRenderWorkerResultMessage | LitStaticRenderWorkerErrorMessage;

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

@@ -0,0 +1,37 @@
+import type { EcoComponent } from '@ecopages/core';
+import type { StaticExportContext } from '@ecopages/core/plugins/integration-plugin';
+import type { AssetDefinition } from '@ecopages/core/services/asset-processing-service';
+type LitStaticRenderSessionOptions = {
+    resolveDependencyPath: (componentDir: string, sourcePath: string) => string;
+    processDependencies?: (dependencies: AssetDefinition[], integrationName: string) => Promise<Array<{
+        filepath?: string;
+    }>>;
+    preferSourceImports?: boolean;
+};
+/**
+ * Build-scoped Lit server render session.
+ *
+ * Preloads SSR-eligible lazy scripts and renders Lit page routes through a
+ * dedicated worker thread for both static export and runtime/dev requests.
+ */
+export declare class LitStaticRenderSession {
+    private readonly preloader;
+    private workerClient;
+    constructor(options: LitStaticRenderSessionOptions);
+    ensureWorker(input: {
+        configModulePath: string;
+        runtimeOrigin: string;
+    }): Promise<void>;
+    preloadStaticRoutes(context: StaticExportContext): Promise<void>;
+    preloadSsrLazyScripts(components: Array<EcoComponent | undefined>): Promise<void>;
+    collectSsrPreloadScripts(components: Array<EcoComponent | undefined>): string[];
+    renderPageInWorker(input: {
+        filePath: string;
+        params: Record<string, string>;
+    }): Promise<string>;
+    isExpectedSsrPreloadError(error: unknown): boolean;
+    dispose(): Promise<void>;
+    private preloadLitRoutes;
+    private isLitRoute;
+}
+export {};

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

@@ -0,0 +1,84 @@
+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;
+    }
+    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");
+    }
+    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;
+    }
+    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);
+        }
+        for (const nestedComponent of page.config?.dependencies?.components ?? []) {
+          components.push(nestedComponent);
+        }
+      }
+    }
+    await this.preloadSsrLazyScripts(components);
+  }
+  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));
+  }
+}
+export {
+  LitStaticRenderSession
+};

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

@@ -0,0 +1,20 @@
+export declare class LitStaticRenderWorkerClient {
+    private readonly configModulePath;
+    private readonly runtimeOrigin;
+    private worker;
+    private readyPromise;
+    private pending;
+    private nextRenderId;
+    constructor({ configModulePath, runtimeOrigin }: {
+        configModulePath: string;
+        runtimeOrigin: string;
+    });
+    private rejectPending;
+    start(): Promise<void>;
+    renderPage(input: {
+        filePath: string;
+        params: Record<string, string>;
+    }): Promise<string>;
+    dispose(): Promise<void>;
+}
+export declare const litStaticRenderWorkerEntryPath: string;

package/src/lit-static-render-worker-client.js

@@ -0,0 +1,115 @@
+import { Worker } from "node:worker_threads";
+import { fileURLToPath } from "node:url";
+class LitStaticRenderWorkerClient {
+  configModulePath;
+  runtimeOrigin;
+  worker = null;
+  readyPromise = null;
+  pending = /* @__PURE__ */ new Map();
+  nextRenderId = 0;
+  constructor({ configModulePath, runtimeOrigin }) {
+    this.configModulePath = configModulePath;
+    this.runtimeOrigin = runtimeOrigin;
+  }
+  rejectPending(error) {
+    for (const pending of this.pending.values()) {
+      pending.reject(error);
+    }
+    this.pending.clear();
+  }
+  async start() {
+    if (this.readyPromise) {
+      return this.readyPromise;
+    }
+    this.readyPromise = new Promise((resolveReady, rejectReady) => {
+      const worker = new Worker(new URL("./lit-static-render-worker.js", import.meta.url), {
+        execArgv: [...process.execArgv],
+        env: {
+          ...process.env,
+          ECOPAGES_LIT_STATIC_RENDER_WORKER: "true"
+        }
+      });
+      this.worker = worker;
+      worker.on("message", (message) => {
+        if (message.type === "ready") {
+          resolveReady();
+          return;
+        }
+        if (message.type === "error") {
+          if (message.id && this.pending.has(message.id)) {
+            const pending = this.pending.get(message.id);
+            this.pending.delete(message.id);
+            pending.reject(new Error(message.message));
+            return;
+          }
+          rejectReady(new Error(message.message));
+          return;
+        }
+        if (message.type === "result") {
+          const pending = this.pending.get(message.id);
+          if (!pending) {
+            return;
+          }
+          this.pending.delete(message.id);
+          pending.resolve(message.html);
+        }
+      });
+      worker.on("error", (error) => {
+        rejectReady(error instanceof Error ? error : new Error(String(error)));
+      });
+      worker.on("exit", (code) => {
+        const exitError = new Error(
+          code === 0 ? "Lit static render worker exited" : `Lit static render worker exited with code ${code}`
+        );
+        this.rejectPending(exitError);
+        if (code !== 0) {
+          rejectReady(exitError);
+        }
+      });
+      const initMessage = {
+        type: "init",
+        configModulePath: this.configModulePath,
+        runtimeOrigin: this.runtimeOrigin
+      };
+      worker.postMessage(initMessage);
+    });
+    return this.readyPromise;
+  }
+  async renderPage(input) {
+    await this.start();
+    if (!this.worker) {
+      throw new Error("Lit static render worker is not available");
+    }
+    const id = String(++this.nextRenderId);
+    const worker = this.worker;
+    if (!worker) {
+      throw new Error("Lit static render worker is not available");
+    }
+    return new Promise((resolve, reject) => {
+      this.pending.set(id, { resolve, reject });
+      const renderMessage = {
+        type: "render",
+        id,
+        filePath: input.filePath,
+        params: input.params
+      };
+      worker.postMessage(renderMessage);
+    });
+  }
+  async dispose() {
+    if (!this.worker) {
+      return;
+    }
+    this.rejectPending(new Error("Lit static render worker was disposed"));
+    const worker = this.worker;
+    this.worker = null;
+    this.readyPromise = null;
+    worker.postMessage({ type: "shutdown" });
+    await worker.terminate();
+  }
+}
+const litStaticRenderWorkerEntryPath = fileURLToPath(new URL("./lit-static-render-worker.js", import.meta.url));
+export {
+  LitStaticRenderWorkerClient,
+  litStaticRenderWorkerEntryPath
+};

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

@@ -0,0 +1 @@
+import './dom-shim.js';

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

@@ -0,0 +1,74 @@
+import { parentPort } from "node:worker_threads";
+import { pathToFileURL } from "node:url";
+import { setupAppRuntimePlugins } from "@ecopages/core/build/build-adapter";
+import { installAppRuntimeBuildExecutor } from "@ecopages/core/build/runtime-build-executor";
+import { RouteRendererFactory } from "@ecopages/core/route-renderer/route-renderer";
+import "./dom-shim.js";
+let appConfig = null;
+let routeRendererFactory = null;
+async function initializeWorker(configModulePath, runtimeOrigin) {
+  const configModule = await import(
+    /* @vite-ignore */
+    pathToFileURL(configModulePath).href
+  );
+  appConfig = configModule.default ?? configModule;
+  await setupAppRuntimePlugins({
+    appConfig,
+    runtimeOrigin
+  });
+  installAppRuntimeBuildExecutor(appConfig);
+  routeRendererFactory = new RouteRendererFactory({
+    appConfig,
+    runtimeOrigin
+  });
+}
+async function renderPage(filePath, params) {
+  if (!routeRendererFactory) {
+    throw new Error("Lit static render worker is not initialized");
+  }
+  const result = await routeRendererFactory.getPageRenderer(filePath).execute({
+    file: filePath,
+    params
+  });
+  const body = result.body;
+  if (typeof body === "string") {
+    return body;
+  }
+  if (Buffer.isBuffer(body)) {
+    return body.toString("utf8");
+  }
+  if (body instanceof ReadableStream) {
+    return new Response(body).text();
+  }
+  throw new TypeError(`Unsupported Lit static render body type: ${typeof body}`);
+}
+function postMessage(message) {
+  parentPort?.postMessage(message);
+}
+if (!parentPort) {
+  throw new Error("Lit static render worker must be started as a worker thread");
+}
+parentPort.on("message", async (message) => {
+  try {
+    if (message.type === "init") {
+      await initializeWorker(message.configModulePath, message.runtimeOrigin);
+      postMessage({ type: "ready" });
+      return;
+    }
+    if (message.type === "shutdown") {
+      process.exit(0);
+      return;
+    }
+    if (message.type === "render") {
+      const html = await renderPage(message.filePath, message.params);
+      postMessage({ type: "result", id: message.id, html });
+    }
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    if (message.type === "render") {
+      postMessage({ type: "error", id: message.id, message: errorMessage });
+      return;
+    }
+    postMessage({ type: "error", message: errorMessage });
+  }
+});

package/src/lit.plugin.d.ts

@@ -3,7 +3,7 @@
  * @module
  */
 import './console.js';
-import { IntegrationPlugin, type IntegrationPluginConfig } from '@ecopages/core/plugins/integration-plugin';
+import { IntegrationPlugin, type IntegrationPluginConfig, type StaticExportContext } from '@ecopages/core/plugins/integration-plugin';
 import { type AssetDefinition } from '@ecopages/core/services/asset-processing-service';
 import { LitRenderer } from './lit-renderer.js';
 /**
@@ -16,8 +16,13 @@ export declare const PLUGIN_NAME = "lit";
  */
 export declare class LitPlugin extends IntegrationPlugin {
     renderer: typeof LitRenderer;
+    private renderSession;
     constructor(options?: Omit<IntegrationPluginConfig, 'name'>);
     getDependencies(): AssetDefinition[];
+    private createRenderSession;
+    setup(): Promise<void>;
+    teardown(): Promise<void>;
+    beforeStaticExport(context: StaticExportContext): Promise<void>;
 }
 /**
  * Factory function to create a Lit plugin instance

package/src/lit.plugin.js

@@ -1,17 +1,22 @@
 import "./console.js";
-import { IntegrationPlugin } from "@ecopages/core/plugins/integration-plugin";
+import {
+  IntegrationPlugin
+} from "@ecopages/core/plugins/integration-plugin";
+import path from "node:path";
 import { AssetFactory } from "@ecopages/core/services/asset-processing-service";
 import { litElementHydrateScript } from "./lit-element-hydrate.js";
 import { LIT_PLUGIN_NAME } from "./lit.constants.js";
 import { LitRenderer } from "./lit-renderer.js";
+import { setActiveLitStaticRenderSession } from "./lit-static-render-coordinator.js";
+import { LitStaticRenderSession } from "./lit-static-render-session.js";
 const PLUGIN_NAME = LIT_PLUGIN_NAME;
 class LitPlugin extends IntegrationPlugin {
   renderer = LitRenderer;
+  renderSession = null;
   constructor(options) {
     super({
       name: PLUGIN_NAME,
       extensions: [".lit.tsx"],
-      staticBuildStep: "fetch",
       ...options
     });
     this.integrationDependencies.unshift(...this.getDependencies());
@@ -40,6 +45,48 @@ class LitPlugin extends IntegrationPlugin {
       })
     ];
   }
+  createRenderSession() {
+    if (!this.appConfig || !this.assetProcessingService) {
+      throw new Error("Lit plugin must be initialized before starting the render worker");
+    }
+    return new LitStaticRenderSession({
+      resolveDependencyPath: (componentDir, sourcePath) => path.join(componentDir, sourcePath),
+      processDependencies: this.assetProcessingService.processDependencies.bind(this.assetProcessingService),
+      preferSourceImports: typeof Bun !== "undefined"
+    });
+  }
+  async setup() {
+    await super.setup();
+    if (!this.appConfig?.absolutePaths?.config) {
+      throw new Error("[ecopages][lit] Lit server rendering requires appConfig.absolutePaths.config");
+    }
+    if (process.env.ECOPAGES_LIT_STATIC_RENDER_WORKER === "true") {
+      return;
+    }
+    this.renderSession = this.createRenderSession();
+    await this.renderSession.ensureWorker({
+      configModulePath: this.appConfig.absolutePaths.config,
+      runtimeOrigin: this.runtimeOrigin
+    });
+    setActiveLitStaticRenderSession(this.renderSession);
+  }
+  async teardown() {
+    await this.renderSession?.dispose();
+    this.renderSession = null;
+    setActiveLitStaticRenderSession(null);
+    await super.teardown();
+  }
+  async beforeStaticExport(context) {
+    if (!this.renderSession) {
+      this.renderSession = this.createRenderSession();
+      await this.renderSession.ensureWorker({
+        configModulePath: context.appConfig.absolutePaths.config,
+        runtimeOrigin: context.baseUrl
+      });
+      setActiveLitStaticRenderSession(this.renderSession);
+    }
+    await this.renderSession.preloadStaticRoutes(context);
+  }
 }
 function litPlugin(options) {
   return new LitPlugin(options);