@ecopages/lit 0.2.0-beta.3 → 0.2.0-beta.31

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/lit",
-  "version": "0.2.0-beta.3",
+  "version": "0.2.0-beta.31",
   "description": "Ecopages lit integration",
   "keywords": [
     "ecopages",
@@ -20,18 +20,26 @@
       "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": {
     "type": "git",
-    "url": "https://github.com/ecopages/ecopages.git",
+    "url": "git+https://github.com/ecopages/ecopages.git",
     "directory": "packages/integrations/lit"
   },
   "peerDependencies": {
-    "@ecopages/core": "0.2.0-beta.3",
+    "@ecopages/core": "0.2.0-beta.31",
     "@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,69 @@
+# 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()
+                                     installBuildRuntime()
+                                     RouteRendererFactory
+
+LitPlugin.initializeRenderer()
+  └─ LitRenderer({ getRenderSession })   lazy accessor (not constructor snapshot)
+
+LitRenderer.execute() (main)
+  └─ ensureIntegrationRuntimeActivated()
+  └─ getRenderSession()
+       ├─ locals present ──────────► super.execute() (in-process)
+       └─ session.renderPageInWorker()
+            └─ postMessage(render) ─────► RouteRendererFactory.execute()
+                                          (no active session in worker)
+
+beforeStaticExport
+  └─ ensureWorker() only when `renderSession` is still null
+  └─ 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()` and skips processor `.setup()` inside `setupAppRuntimePlugins` (main thread already prepared artifacts).
+
+## Ownership
+
+| Concern                    | Owner                                                                                                                                                                  |
+| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Session + worker lifecycle | `LitPlugin` (`renderSession`)                                                                                                                                          |
+| Lazy session lookup        | `LitRenderer` via `getRenderSession`                                                                                                                                   |
+| Worker identity            | First `{ configModulePath, runtimeOrigin }` passed to `ensureWorker`; same identity is sticky; a later `ensureWorker` with a different identity disposes and recreates |
+
+Renderers created before plugin `setup()` still use the worker after setup assigns the session, because `execute` activates the integration runtime then reads the accessor.
+
+`beforeStaticExport` does not re-call `ensureWorker` when setup already created the session, so a different `context.baseUrl` at export time will not recreate an existing worker.
+
+## Locals policy
+
+When `RouteRendererOptions.locals` is present, `LitRenderer.execute` forces the in-process path (`super.execute`). Request locals are not sent through the worker protocol (structured-clone risk and request-scoped data). Static export and routes without locals continue through the worker.
+
+## Files
+
+| File                                 | Role                                                            |
+| ------------------------------------ | --------------------------------------------------------------- |
+| `lit-static-render-session.ts`       | Plugin-runtime-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                                  |
+
+## Protocol
+
+| Message            | Direction     | Purpose                                                                       |
+| ------------------ | ------------- | ----------------------------------------------------------------------------- |
+| `init`             | main → worker | Load `eco.config.ts`, bootstrap runtime (`configModulePath`, `runtimeOrigin`) |
+| `ready`            | worker → main | Worker initialized                                                            |
+| `render`           | main → worker | Render one Lit page route (`filePath`, `PageParams`, optional `PageQuery`)    |
+| `result` / `error` | worker → main | HTML body plus optional `cacheStrategy`, or an error message                  |
+| `shutdown`         | main → worker | Exit worker thread                                                            |

package/src/lit-renderer.d.ts

@@ -2,19 +2,41 @@
  * 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';
+import { IntegrationRenderer, type RenderToResponseContext } from '@ecopages/core/route-renderer/orchestration/integration-renderer';
+import type { LitStaticRenderSession } from './lit-static-render-session.js';
+export type LitRendererOptions = ConstructorParameters<typeof IntegrationRenderer>[0] & {
+    /**
+     * Lazy session lookup owned by {@link LitPlugin}.
+     *
+     * @remarks
+     * Must not snapshot the session at construction time. Plugin `setup()` may
+     * assign the session after the renderer is created; `execute` activates the
+     * integration runtime then reads this accessor so worker dispatch still works.
+     */
+    getRenderSession?: () => LitStaticRenderSession | undefined;
+};
 /**
  * A renderer for the Lit integration.
  */
 export declare class LitRenderer extends IntegrationRenderer<EcoPagesElement> {
     name: string;
+    private readonly getRenderSession?;
+    constructor(options: LitRendererOptions);
+    /**
+     * Renders a Lit page route, preferring the plugin worker when available.
+     *
+     * @remarks
+     * Activates the integration runtime before reading {@link getRenderSession}
+     * so a renderer constructed before plugin setup still sees the session.
+     * When `options.locals` is present, rendering stays in-process: request locals
+     * are not structured-cloned across the worker boundary.
+     */
+    execute(options: RouteRendererOptions): Promise<RouteRenderResult>;
     private isFunctionComponent;
     private resolveQueuedForeignSubtreeChildren;
-    private resolveQueuedForeignSubtreeHtml;
-    protected shouldRenderPageComponent(): boolean;
-    private isLitManagedComponent;
+    private renderLitQueuedForeignSubtreeChildren;
     /**
      * Renders a Lit component for component-level orchestration.
      *

package/src/lit-renderer.js

@@ -1,5 +1,11 @@
 import "./dom-shim.js";
-import { IntegrationRenderer } from "@ecopages/core/route-renderer/integration-renderer";
+import {
+  IntegrationRenderer
+} from "@ecopages/core/route-renderer/orchestration/integration-renderer";
+import {
+  getForeignSubtreeResolutionContextKey,
+  resolveOwningIntegrationRenderer
+} from "@ecopages/core/route-renderer/orchestration/foreign-child/owning-renderer-resolution";
 import { LitSsrLazyPreloader } from "./lit-ssr-lazy-preloader.js";
 import { LIT_PLUGIN_NAME } from "./lit.constants.js";
 import {
@@ -10,6 +16,38 @@ import {
 } from "./utils/lit-html-rendering.js";
 class LitRenderer extends IntegrationRenderer {
   name = LIT_PLUGIN_NAME;
+  getRenderSession;
+  constructor(options) {
+    const { getRenderSession, ...rendererOptions } = options;
+    super(rendererOptions);
+    this.getRenderSession = getRenderSession;
+  }
+  /**
+   * Renders a Lit page route, preferring the plugin worker when available.
+   *
+   * @remarks
+   * Activates the integration runtime before reading {@link getRenderSession}
+   * so a renderer constructed before plugin setup still sees the session.
+   * When `options.locals` is present, rendering stays in-process: request locals
+   * are not structured-cloned across the worker boundary.
+   */
+  async execute(options) {
+    await this.ensureIntegrationRuntimeActivated();
+    const renderSession = this.getRenderSession?.();
+    if (renderSession && options.locals === void 0) {
+      const params = options.params ?? {};
+      const result = await renderSession.renderPageInWorker({
+        filePath: options.file,
+        params,
+        query: options.query
+      });
+      return {
+        body: result.html,
+        cacheStrategy: result.cacheStrategy
+      };
+    }
+    return super.execute(options);
+  }
   isFunctionComponent(component) {
     return typeof component === "function";
   }
@@ -28,44 +66,23 @@ class LitRenderer extends IntegrationRenderer {
     );
     return renderedChildren;
   }
-  async resolveQueuedForeignSubtreeHtml(html, runtimeContext) {
-    const queuedForeignSubtreeResolution = await this.foreignSubtreeExecutionService.resolveQueuedHtml({
-      currentIntegrationName: this.name,
-      html,
-      runtimeContext,
-      queueLabel: "Lit",
-      getOwningRenderer: (integrationName, rendererCache) => this.getIntegrationRendererForName(integrationName, rendererCache),
-      applyAttributesToFirstElement: (resolvedHtml, attributes) => this.htmlTransformer.applyAttributesToFirstElement(resolvedHtml, attributes),
-      dedupeProcessedAssets: (assets) => this.htmlTransformer.dedupeProcessedAssets(assets),
-      renderQueuedChildren: async (children, _runtimeContext, queuedResolutionsByToken, resolveToken) => {
-        const renderedChildren = await this.resolveQueuedForeignSubtreeChildren(
-          children,
-          queuedResolutionsByToken,
-          resolveToken
-        );
-        if (typeof renderedChildren !== "string") {
-          return {
-            assets: [],
-            children: renderedChildren
-          };
-        }
-        return {
-          assets: [],
-          html: renderedChildren
-        };
-      }
-    });
+  async renderLitQueuedForeignSubtreeChildren(children, queuedResolutionsByToken, resolveToken) {
+    const renderedChildren = await this.resolveQueuedForeignSubtreeChildren(
+      children,
+      queuedResolutionsByToken,
+      resolveToken
+    );
+    if (typeof renderedChildren !== "string") {
+      return {
+        assets: [],
+        children: renderedChildren
+      };
+    }
     return {
-      html: queuedForeignSubtreeResolution.html,
-      assets: queuedForeignSubtreeResolution.assets.length > 0 ? queuedForeignSubtreeResolution.assets : void 0
+      assets: [],
+      html: renderedChildren
     };
   }
-  shouldRenderPageComponent() {
-    return false;
-  }
-  isLitManagedComponent(component) {
-    return component?.config?.integration === this.name || component?.config?.__eco?.integration === this.name;
-  }
   /**
    * Renders a Lit component for component-level orchestration.
    *
@@ -95,10 +112,26 @@ class LitRenderer extends IntegrationRenderer {
     const content = await component(props);
     const renderedHtml = await renderLitValueToString(content);
     const html = renderedChildren === void 0 ? renderedHtml : injectLitRenderedChildren(renderedHtml, renderedChildren);
-    const queuedForeignSubtreeResolution = await this.resolveQueuedForeignSubtreeHtml(
+    const queuedForeignSubtreeResolution = await this.foreignSubtreeExecutionService.resolveQueuedHtml({
+      currentIntegrationName: this.name,
       html,
-      this.getQueuedForeignSubtreeResolutionContext(input)
-    );
+      runtimeContext: this.foreignSubtreeExecutionService.getQueuedRuntimeContext(
+        input,
+        getForeignSubtreeResolutionContextKey(this.name)
+      ),
+      queueLabel: "Lit",
+      getOwningRenderer: (integrationName, rendererCache) => resolveOwningIntegrationRenderer({
+        appConfig: this.appConfig,
+        runtimeOrigin: this.runtimeOrigin,
+        currentIntegrationName: this.name,
+        currentRenderer: this,
+        integrationName,
+        cache: rendererCache
+      }),
+      applyAttributesToFirstElement: (resolvedHtml, attributes) => this.htmlTransformer.applyAttributesToFirstElement(resolvedHtml, attributes),
+      dedupeProcessedAssets: (assets2) => this.htmlTransformer.dedupeProcessedAssets(assets2),
+      renderQueuedChildren: (children, _runtimeContext, queuedResolutionsByToken, resolveToken) => this.renderLitQueuedForeignSubtreeChildren(children, queuedResolutionsByToken, resolveToken)
+    });
     const hasDependencies = Boolean(input.component.config?.dependencies);
     const canResolveAssets = typeof this.assetProcessingService?.processDependencies === "function";
     const assets = hasDependencies && canResolveAssets ? await this.processComponentDependencies([input.component]) : void 0;
@@ -109,7 +142,7 @@ class LitRenderer extends IntegrationRenderer {
       integrationName: this.name,
       assets: this.htmlTransformer.dedupeProcessedAssets([
         ...assets ?? [],
-        ...queuedForeignSubtreeResolution.assets ?? []
+        ...queuedForeignSubtreeResolution.assets
       ])
     };
   }
@@ -140,6 +173,11 @@ class LitRenderer extends IntegrationRenderer {
    * Preloads SSR-eligible lazy scripts to register custom elements before render.
    */
   async preloadSsrLazyScripts(components) {
+    const renderSession = this.getRenderSession?.();
+    if (renderSession) {
+      await renderSession.preloadSsrLazyScripts(components);
+      return;
+    }
     await this.ssrLazyPreloader.preloadSsrLazyScripts(components);
   }
   /**
@@ -188,44 +226,16 @@ class LitRenderer extends IntegrationRenderer {
   }
   async renderToResponse(view, props, ctx) {
     try {
-      if (ctx.partial) {
-        return this.renderPartialViewResponse({
-          view,
-          props,
-          ctx,
-          transformHtml: normalizeLitHtml
-        });
-      }
-      const viewConfig = view.config;
-      const Layout = viewConfig?.layout;
-      const HtmlTemplate = await this.getHtmlTemplate();
-      const metadata = await this.resolveViewMetadata(view, props);
-      const normalizedProps = props ?? {};
+      const layouts = view.config?.layouts;
+      const Layout = layouts?.[layouts.length - 1];
       await this.preloadSsrLazyScripts([view, Layout]);
-      await this.prepareViewDependencies(view, Layout);
-      const pageRender = await this.renderComponentWithForeignChildren({
-        component: view,
-        props: normalizedProps
-      });
-      const layoutRender = Layout ? await this.renderComponentWithForeignChildren({
-        component: Layout,
-        props: {},
-        children: pageRender.html
-      }) : void 0;
-      const documentRender = await this.renderComponentWithForeignChildren({
-        component: HtmlTemplate,
-        props: {
-          metadata,
-          pageProps: normalizedProps
-        },
-        children: layoutRender?.html ?? pageRender.html
-      });
-      this.appendProcessedDependencies(pageRender.assets, layoutRender?.assets, documentRender.assets);
-      const body = await this.finalizeResolvedHtml({
-        html: `${this.DOC_TYPE}${normalizeLitHtml(documentRender.html)}`,
-        partial: false
+      return await this.renderViewWithDocumentShell({
+        view,
+        props,
+        ctx,
+        layout: Layout,
+        transformDocumentHtml: normalizeLitHtml
       });
-      return this.createHtmlResponse(body, ctx);
     } catch (error) {
       throw this.createRenderError("Error rendering view", error);
     }

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

@@ -60,8 +60,8 @@ class LitSsrLazyPreloader {
           scriptPaths.add(this.resolveDependencyPath(componentDir, script.src));
         }
       }
-      if (config.layout) {
-        collect(config.layout);
+      for (const layout of config.layouts ?? []) {
+        collect(layout);
       }
       for (const nestedComponent of config.dependencies?.components || []) {
         collect(nestedComponent);

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

@@ -0,0 +1,35 @@
+import type { PageParams, PageQuery, RouteRenderResult } from '@ecopages/core';
+export type LitStaticRenderCacheStrategy = RouteRenderResult['cacheStrategy'];
+export type LitStaticRenderWorkerInitMessage = {
+    type: 'init';
+    configModulePath: string;
+    runtimeOrigin: string;
+};
+export type LitStaticRenderWorkerRenderMessage = {
+    type: 'render';
+    id: string;
+    filePath: 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';
+};
+export type LitStaticRenderWorkerRequestMessage = LitStaticRenderWorkerInitMessage | LitStaticRenderWorkerRenderMessage | LitStaticRenderWorkerShutdownMessage;
+export type LitStaticRenderWorkerReadyMessage = {
+    type: 'ready';
+};
+export type LitStaticRenderWorkerResultMessage = {
+    type: 'result';
+    id: string;
+    html: string;
+    cacheStrategy?: LitStaticRenderCacheStrategy;
+};
+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,63 @@
+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;
+};
+/**
+ * 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 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;
+    }): 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: PageParams;
+        query?: PageQuery;
+    }): Promise<{
+        html: string;
+        cacheStrategy?: LitStaticRenderCacheStrategy;
+    }>;
+    isExpectedSsrPreloadError(error: unknown): boolean;
+    dispose(): Promise<void>;
+    private preloadLitRoutes;
+    private isLitRoute;
+}
+export {};

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

@@ -0,0 +1,105 @@
+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;
+  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
+    }));
+  }
+  /**
+   * 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);
+  }
+  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;
+    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);
+  }
+  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,26 @@
+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;
+    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: PageParams;
+        query?: PageQuery;
+    }): Promise<{
+        html: string;
+        cacheStrategy?: LitStaticRenderCacheStrategy;
+    }>;
+    dispose(): Promise<void>;
+}
+export declare const litStaticRenderWorkerEntryPath: string;

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

@@ -0,0 +1,113 @@
+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({ html: message.html, cacheStrategy: message.cacheStrategy });
+        }
+      });
+      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();
+    const worker = this.worker;
+    if (!worker) {
+      throw new Error("Lit static render worker is not available");
+    }
+    const id = String(++this.nextRenderId);
+    return new Promise((resolve, reject) => {
+      this.pending.set(id, { resolve, reject });
+      const renderMessage = {
+        type: "render",
+        id,
+        filePath: input.filePath,
+        params: input.params,
+        query: input.query
+      };
+      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,75 @@
+import { parentPort } from "node:worker_threads";
+import { pathToFileURL } from "node:url";
+import { setupAppRuntimePlugins } from "@ecopages/core/build/build-adapter";
+import { installBuildRuntime } from "@ecopages/core/build/build-runtime";
+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
+  });
+  installBuildRuntime(appConfig);
+  routeRendererFactory = new RouteRendererFactory({
+    appConfig,
+    runtimeOrigin
+  });
+}
+async function renderPage(filePath, params, query) {
+  if (!routeRendererFactory) {
+    throw new Error("Lit static render worker is not initialized");
+  }
+  const result = await routeRendererFactory.getPageRenderer(filePath).execute({
+    file: filePath,
+    params,
+    query
+  });
+  const body = result.body;
+  if (typeof body === "string") {
+    return { html: body, cacheStrategy: result.cacheStrategy };
+  }
+  if (Buffer.isBuffer(body)) {
+    return { html: body.toString("utf8"), cacheStrategy: result.cacheStrategy };
+  }
+  if (body instanceof ReadableStream) {
+    return { html: await new Response(body).text(), cacheStrategy: result.cacheStrategy };
+  }
+  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 result = await renderPage(message.filePath, message.params, message.query);
+      postMessage({ type: "result", id: message.id, ...result });
+    }
+  } 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';
 /**
@@ -13,11 +13,24 @@ export declare const PLUGIN_NAME = "lit";
 /**
  * The Lit plugin class
  * This plugin provides support for Lit components in Ecopages
+ *
+ * @remarks
+ * Owns the {@link LitStaticRenderSession} for worker SSR. Renderers receive a
+ * lazy `getRenderSession` accessor so construction before {@link setup} still
+ * observes the session once setup assigns it.
  */
 export declare class LitPlugin extends IntegrationPlugin {
     renderer: typeof LitRenderer;
+    private renderSession;
     constructor(options?: Omit<IntegrationPluginConfig, 'name'>);
     getDependencies(): AssetDefinition[];
+    private createRenderSession;
+    initializeRenderer(options?: {
+        rendererModules?: unknown;
+    }): LitRenderer;
+    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 { isLitStaticRenderWorkerThread } from "@ecopages/core/build/lit-static-render-worker-context";
+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 { 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,52 @@ 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"
+    });
+  }
+  initializeRenderer(options) {
+    const renderer = new this.renderer({
+      ...this.createRendererOptions(options),
+      getRenderSession: () => this.renderSession ?? void 0
+    });
+    return this.attachRendererRuntimeServices(renderer);
+  }
+  async setup() {
+    await super.setup();
+    if (!this.appConfig?.absolutePaths?.config) {
+      throw new Error("[ecopages][lit] Lit server rendering requires appConfig.absolutePaths.config");
+    }
+    if (isLitStaticRenderWorkerThread()) {
+      return;
+    }
+    this.renderSession = this.createRenderSession();
+    await this.renderSession.ensureWorker({
+      configModulePath: this.appConfig.absolutePaths.config,
+      runtimeOrigin: this.runtimeOrigin
+    });
+  }
+  async teardown() {
+    await this.renderSession?.dispose();
+    this.renderSession = 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
+      });
+    }
+    await this.renderSession.preloadStaticRoutes(context);
+  }
 }
 function litPlugin(options) {
   return new LitPlugin(options);