@ecopages/lit 0.2.1 → 0.3.0

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

@@ -0,0 +1,145 @@
+import path from 'node:path';
+import { ensureLitDomShim } from './dom-shim.js';
+import { CUSTOM_ELEMENT_SSR_PRELOAD_CACHE_SCOPES, CustomElementScriptPreloader, } from '@ecopages/core/integration';
+import { LIT_PLUGIN_NAME } from './lit.constants.js';
+import { createCustomElementSsrPipelineImporter } from '@ecopages/core/integration';
+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;
+    getInvalidationVersion;
+    workerInvalidationVersion = 0;
+    renderChain = Promise.resolve();
+    constructor(options) {
+        this.getInvalidationVersion = options.getInvalidationVersion ?? (() => 0);
+        this.preloader = new CustomElementScriptPreloader({
+            cacheScope: CUSTOM_ELEMENT_SSR_PRELOAD_CACHE_SCOPES.lit,
+            preloadScopes: options.preloadScopes,
+            logLabel: 'lit',
+            requireLazyScriptEntry: true,
+            resolveDependencyPath: options.resolveDependencyPath,
+            importServerModule: createCustomElementSsrPipelineImporter({
+                integration: options.integration,
+                processDependencies: options.processDependencies,
+            }),
+        });
+        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();
+        this.workerInvalidationVersion = this.getInvalidationVersion();
+    }
+    async preloadStaticRoutes(context) {
+        await this.preloadLitRoutes(context);
+    }
+    async preloadSsrScripts(components) {
+        ensureLitDomShim();
+        await this.preloader.preloadSsrScripts(components);
+    }
+    collectSsrPreloadScripts(components) {
+        return this.preloader.collectSsrPreloadScripts(components);
+    }
+    async renderPageInWorker(input) {
+        if (!this.workerClient) {
+            throw new Error('Lit static render worker is not active');
+        }
+        const render = this.renderChain.then(async () => {
+            const version = this.getInvalidationVersion();
+            if (version !== this.workerInvalidationVersion && this.workerIdentity) {
+                const identity = this.workerIdentity;
+                await this.dispose();
+                await this.ensureWorker(identity);
+            }
+            if (!this.workerClient)
+                throw new Error('Lit static render worker is not active');
+            return this.workerClient.renderPage(input);
+        });
+        this.renderChain = render.then(() => undefined, () => undefined);
+        return render;
+    }
+    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.preloadSsrScripts(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));
+    }
+}

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

@@ -0,0 +1,26 @@
+import type { PageParams, PageQuery } from '@ecopages/core';
+import type { LitStaticRenderResult } from './lit-static-render-protocol.js';
+export declare class LitStaticRenderWorkerClient {
+    private readonly configModulePath;
+    private readonly runtimeOrigin;
+    private worker;
+    private workerExitPromise;
+    private workerExitCode;
+    private readyPromise;
+    private pending;
+    private nextRenderId;
+    private shutdownHandler;
+    constructor({ configModulePath, runtimeOrigin }: {
+        configModulePath: string;
+        runtimeOrigin: string;
+    });
+    private rejectPending;
+    start(): Promise<void>;
+    renderPage(input: {
+        filePath: string;
+        params: PageParams;
+        query?: PageQuery;
+    }): Promise<LitStaticRenderResult>;
+    dispose(): Promise<void>;
+}
+export declare const litStaticRenderWorkerEntryPath: string;

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

@@ -0,0 +1,181 @@
+import { Worker } from 'node:worker_threads';
+import { fileURLToPath } from 'node:url';
+const workerShutdownTimeoutMs = 30_000;
+const workerExitTimeoutMs = 1_000;
+export class LitStaticRenderWorkerClient {
+    configModulePath;
+    runtimeOrigin;
+    worker = null;
+    workerExitPromise = null;
+    workerExitCode = null;
+    readyPromise = null;
+    pending = new Map();
+    nextRenderId = 0;
+    shutdownHandler = null;
+    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;
+            this.workerExitCode = null;
+            this.workerExitPromise = new Promise((resolveExit) => {
+                worker.once('exit', resolveExit);
+            });
+            worker.on('message', (message) => {
+                if (message.type === 'ready') {
+                    resolveReady();
+                    return;
+                }
+                if (message.type === 'shutdown-complete') {
+                    this.shutdownHandler?.resolve();
+                    this.shutdownHandler = null;
+                    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;
+                    }
+                    const error = new Error(message.message);
+                    this.shutdownHandler?.reject(error);
+                    this.shutdownHandler = null;
+                    rejectReady(error);
+                    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,
+                        sourceDependencyPaths: message.sourceDependencyPaths,
+                        metadata: message.metadata,
+                    });
+                }
+            });
+            worker.on('error', (error) => {
+                rejectReady(error instanceof Error ? error : new Error(String(error)));
+            });
+            worker.on('exit', (code) => {
+                this.workerExitCode = code;
+                const exitError = new Error(code === 0
+                    ? 'Lit static render worker exited'
+                    : `Lit static render worker exited with code ${code}`);
+                this.rejectPending(exitError);
+                this.shutdownHandler?.reject(exitError);
+                this.shutdownHandler = null;
+                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;
+        const workerExit = this.workerExitPromise ?? Promise.resolve(this.workerExitCode ?? 0);
+        this.worker = null;
+        this.workerExitPromise = null;
+        this.readyPromise = null;
+        if (this.workerExitCode !== null) {
+            if (this.workerExitCode !== 0) {
+                throw new Error(`Lit static render worker exited with code ${this.workerExitCode}`);
+            }
+            return;
+        }
+        let shutdownTimeout;
+        const shutdownComplete = new Promise((resolve, reject) => {
+            shutdownTimeout = setTimeout(() => reject(new Error('Lit static render worker shutdown timed out')), workerShutdownTimeoutMs);
+            this.shutdownHandler = {
+                resolve: () => {
+                    if (shutdownTimeout)
+                        clearTimeout(shutdownTimeout);
+                    resolve();
+                },
+                reject: (error) => {
+                    if (shutdownTimeout)
+                        clearTimeout(shutdownTimeout);
+                    reject(error);
+                },
+            };
+        });
+        worker.postMessage({ type: 'shutdown' });
+        let shutdownError;
+        try {
+            await shutdownComplete;
+        }
+        catch (error) {
+            shutdownError = error instanceof Error ? error : new Error(String(error));
+        }
+        if (shutdownTimeout)
+            clearTimeout(shutdownTimeout);
+        const exitResult = await new Promise((resolve) => {
+            const exitTimeout = setTimeout(() => resolve({ timedOut: true }), workerExitTimeoutMs);
+            void workerExit.then((code) => {
+                clearTimeout(exitTimeout);
+                resolve({ code });
+            });
+        });
+        if ('timedOut' in exitResult) {
+            await worker.terminate();
+        }
+        else if (exitResult.code !== 0) {
+            shutdownError ??= new Error(`Lit static render worker exited with code ${exitResult.code}`);
+        }
+        if (shutdownError)
+            throw shutdownError;
+    }
+}
+export const litStaticRenderWorkerEntryPath = fileURLToPath(new URL('./lit-static-render-worker.js', import.meta.url));

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,111 @@
+import { parentPort } from 'node:worker_threads';
+import { loadEcoPagesConfig } from '@ecopages/core/config';
+import { setupAppRuntimeIntegrations, setupAppRuntimePlugins, teardownAppRuntimeIntegrations, } from '@ecopages/core/build';
+import { installBuildQueue } from '@ecopages/core/build';
+import { requireAppRuntime } from '@ecopages/core/integration';
+import { RouteRendererFactory } from '@ecopages/core/integration';
+import { toLitStaticRenderResult } from './lit-static-render-result.js';
+import './dom-shim.js';
+let appConfig = null;
+let routeRendererFactory = null;
+let activeRenders = 0;
+let shutdownRequested = false;
+let resolveRendersIdle;
+/**
+ * Loads app config in the worker isolate and bootstraps rendering.
+ *
+ * @remarks
+ * Processor `.setup()` is skipped here because the main thread already prepared disk artifacts
+ * before the Lit worker started (`ECOPAGES_LIT_STATIC_RENDER_WORKER`). Integrations still need
+ * setup in this isolate before route renderers are created.
+ */
+async function initializeWorker(configModulePath, runtimeOrigin) {
+    appConfig = await loadEcoPagesConfig({ configFile: configModulePath });
+    const runtime = requireAppRuntime(appConfig);
+    runtime.origin = runtimeOrigin;
+    await setupAppRuntimePlugins({
+        appConfig,
+    });
+    await setupAppRuntimeIntegrations({ appConfig });
+    installBuildQueue(appConfig);
+    routeRendererFactory = new RouteRendererFactory({
+        appConfig,
+        runtime,
+    });
+}
+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,
+    });
+    return toLitStaticRenderResult(result);
+}
+async function shutdownWorker() {
+    shutdownRequested = true;
+    if (activeRenders > 0) {
+        await new Promise((resolve) => {
+            resolveRendersIdle = resolve;
+        });
+    }
+    try {
+        if (appConfig) {
+            await teardownAppRuntimeIntegrations({ appConfig });
+        }
+        postMessage({ type: 'shutdown-complete' });
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        postMessage({ type: 'error', message: errorMessage });
+    }
+    finally {
+        parentPort?.close();
+    }
+}
+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') {
+            await shutdownWorker();
+            return;
+        }
+        if (message.type === 'render') {
+            if (shutdownRequested) {
+                throw new Error('Lit static render worker is shutting down');
+            }
+            activeRenders += 1;
+            try {
+                const result = await renderPage(message.filePath, message.params, message.query);
+                postMessage({ type: 'result', id: message.id, ...result });
+            }
+            finally {
+                activeRenders -= 1;
+                if (activeRenders === 0) {
+                    resolveRendersIdle?.();
+                    resolveRendersIdle = undefined;
+                }
+            }
+        }
+    }
+    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.constants.d.ts

@@ -0,0 +1 @@
+export declare const LIT_PLUGIN_NAME = "lit";

package/src/lit.constants.js

@@ -0,0 +1 @@
+export const LIT_PLUGIN_NAME = 'lit';

package/src/lit.plugin.d.ts

@@ -3,8 +3,8 @@
  * @module
  */
 import './console.js';
-import { IntegrationPlugin, type IntegrationPluginConfig } from '@ecopages/core/plugins/integration-plugin';
-import { type AssetDefinition } from '@ecopages/core/services/asset-processing-service';
+import { IntegrationPlugin, type IntegrationRendererBase, type IntegrationRuntimeContext, type IntegrationPluginConfig, type StaticExportContext, type StaticExportRelease } from '@ecopages/core/integration';
+import { type AssetDefinition } from '@ecopages/core/integration';
 import { LitRenderer } from './lit-renderer.js';
 /**
  * The name of the Lit plugin
@@ -13,11 +13,44 @@ 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;
+    renderer: new (options: import("@ecopages/core/integration").IntegrationRendererOptions) => import("@ecopages/core/integration").IntegrationRenderer<import("@ecopages/core").EcoPagesElement> & {
+        name: string;
+    };
+    private renderSession;
     constructor(options?: Omit<IntegrationPluginConfig, 'name'>);
+    /**
+     * Returns the global integration dependencies required in the browser.
+     *
+     * @remarks
+     * Injects Lit's hydration support script into the document head before any
+     * custom element connects. While `@lit-labs/ssr-client/lit-element-hydrate-support.js`
+     * can be resolved directly in modern Bun and Node environments, an inline self-contained
+     * script is currently emitted to ensure synchronous availability before custom-element
+     * registration without requiring an import map for `@lit-labs/ssr-client` subpath imports.
+     */
     getDependencies(): AssetDefinition[];
+    private createRenderSession;
+    createRenderer(base: IntegrationRendererBase): LitRenderer;
+    hmr(context: IntegrationRuntimeContext): void;
+    setup(context: IntegrationRuntimeContext): Promise<void>;
+    teardown(): Promise<void>;
+    /**
+     * Reconciles the render worker with the export origin and preloads Lit routes.
+     *
+     * @remarks
+     * `setup()` can start the session with the runtime origin before static export resolves its own base URL. The
+     * session reuses the worker when the identities match and restarts it when the export origin differs. The returned
+     * release stops the worker once the export ends, so an in-process export leaves no worker thread running. A later
+     * render in the same process falls back to rendering in-process.
+     */
+    staticExport(context: StaticExportContext): Promise<StaticExportRelease>;
 }
 /**
  * Factory function to create a Lit plugin instance