@ecopages/lit 0.3.0 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/lit",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Ecopages lit integration",
   "keywords": [
     "ecopages",
@@ -42,7 +42,7 @@
     "directory": "packages/integrations/lit"
   },
   "peerDependencies": {
-    "@ecopages/core": "0.3.0",
+    "@ecopages/core": "0.3.1",
     "@lit-labs/ssr": "^3.3.0",
     "@lit-labs/ssr-client": "^1.1.7",
     "lit": "^3.2.1"

package/src/lit-renderer.d.ts

@@ -1,7 +1,3 @@
-/**
- * This module contains the Lit renderer hooks.
- * @module
- */
 /**
  * This module contains the Lit renderer hooks.
  * @module
@@ -10,7 +6,6 @@ import type { EcoPagesElement } from '@ecopages/core';
 import { createIntegrationRenderer } from '@ecopages/core/integration';
 import type { LitStaticRenderSession } from './lit-static-render-session.js';
 export type LitRenderer = InstanceType<ReturnType<typeof createLitRenderer>>;
-export type LitRendererOptions = ConstructorParameters<ReturnType<typeof createLitRenderer>>[0];
 /**
  * Creates the Lit renderer class with a lazy worker-session lookup.
  *

package/src/lit-renderer.js

@@ -1,7 +1,3 @@
-/**
- * This module contains the Lit renderer hooks.
- * @module
- */
 import { createIntegrationRenderer } from '@ecopages/core/integration';
 import { resolveQueuedTokens } from '@ecopages/core/integration';
 import { CUSTOM_ELEMENT_SSR_PRELOAD_CACHE_SCOPES, CustomElementScriptPreloader, } from '@ecopages/core/integration';

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

@@ -0,0 +1,17 @@
+import type { LitStaticRenderWorkerErrorMessage } from './lit-static-render-protocol.js';
+/**
+ * Turns an error thrown in the Lit worker into the message posted to the main thread.
+ *
+ * @remarks
+ * `postMessage` cannot carry an `Error` with its class, so the status of an `HttpError` travels as a field.
+ * Without it a page that throws `HttpError.NotFound()` would reach the main thread as a plain error and render as a 500.
+ */
+export declare function toLitStaticRenderErrorMessage(error: unknown, id?: string): LitStaticRenderWorkerErrorMessage;
+/**
+ * Rebuilds the error a Lit worker reported, as an `HttpError` when the worker's error carried a status.
+ *
+ * @remarks
+ * The worker-side name, message and stack are kept on `cause` because the rebuilt error's own stack points at the
+ * message handler, not at the page that threw.
+ */
+export declare function fromLitStaticRenderErrorMessage(message: LitStaticRenderWorkerErrorMessage): Error;

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

@@ -0,0 +1,34 @@
+import { HttpError } from '@ecopages/core/errors';
+/**
+ * Turns an error thrown in the Lit worker into the message posted to the main thread.
+ *
+ * @remarks
+ * `postMessage` cannot carry an `Error` with its class, so the status of an `HttpError` travels as a field.
+ * Without it a page that throws `HttpError.NotFound()` would reach the main thread as a plain error and render as a 500.
+ */
+export function toLitStaticRenderErrorMessage(error, id) {
+    if (!(error instanceof Error) && !HttpError.isHttpError(error)) {
+        return { type: 'error', id, message: String(error) };
+    }
+    const { message, name, stack } = error;
+    return {
+        type: 'error',
+        id,
+        message,
+        name,
+        stack,
+        status: HttpError.isHttpError(error) ? error.status : undefined,
+    };
+}
+/**
+ * Rebuilds the error a Lit worker reported, as an `HttpError` when the worker's error carried a status.
+ *
+ * @remarks
+ * The worker-side name, message and stack are kept on `cause` because the rebuilt error's own stack points at the
+ * message handler, not at the page that threw.
+ */
+export function fromLitStaticRenderErrorMessage(message) {
+    const error = message.status === undefined ? new Error(message.message) : new HttpError(message.status, message.message);
+    error.cause = { name: message.name, message: message.message, stack: message.stack };
+    return error;
+}

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

@@ -33,6 +33,12 @@ export type LitStaticRenderWorkerErrorMessage = {
     type: 'error';
     id?: string;
     message: string;
+    /** Worker-side error name, kept as the rebuilt error's cause. */
+    name?: string;
+    /** Worker-side stack, kept as the rebuilt error's cause. */
+    stack?: string;
+    /** Present when the thrown error was an `HttpError`, so the main thread can rebuild one with the same status. */
+    status?: number;
 };
 export type LitStaticRenderWorkerShutdownCompleteMessage = {
     type: 'shutdown-complete';

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

@@ -51,13 +51,11 @@ export declare class LitStaticRenderSession {
     }): Promise<void>;
     preloadStaticRoutes(context: StaticExportContext): Promise<void>;
     preloadSsrScripts(components: Array<CustomElementSsrPreloadComponent | undefined>): Promise<void>;
-    collectSsrPreloadScripts(components: Array<CustomElementSsrPreloadComponent | undefined>): string[];
     renderPageInWorker(input: {
         filePath: string;
         params: PageParams;
         query?: PageQuery;
     }): Promise<LitStaticRenderResult>;
-    isExpectedSsrPreloadError(error: unknown): boolean;
     dispose(): Promise<void>;
     private preloadLitRoutes;
     private isLitRoute;

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

@@ -79,9 +79,6 @@ export class LitStaticRenderSession {
         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');
@@ -100,9 +97,6 @@ export class LitStaticRenderSession {
         this.renderChain = render.then(() => undefined, () => undefined);
         return render;
     }
-    isExpectedSsrPreloadError(error) {
-        return this.preloader.isExpectedSsrPreloadError(error);
-    }
     async dispose() {
         await this.workerClient?.dispose();
         this.workerClient = null;

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

@@ -1,5 +1,6 @@
 import { Worker } from 'node:worker_threads';
 import { fileURLToPath } from 'node:url';
+import { fromLitStaticRenderErrorMessage } from './lit-static-render-error.js';
 const workerShutdownTimeoutMs = 30_000;
 const workerExitTimeoutMs = 1_000;
 export class LitStaticRenderWorkerClient {
@@ -53,7 +54,7 @@ export class LitStaticRenderWorkerClient {
                     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));
+                        pending.reject(fromLitStaticRenderErrorMessage(message));
                         return;
                     }
                     const error = new Error(message.message);

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

@@ -1,9 +1,9 @@
 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 { toLitStaticRenderErrorMessage } from './lit-static-render-error.js';
 import { toLitStaticRenderResult } from './lit-static-render-result.js';
 import './dom-shim.js';
 let appConfig = null;
@@ -27,10 +27,8 @@ async function initializeWorker(configModulePath, runtimeOrigin) {
         appConfig,
     });
     await setupAppRuntimeIntegrations({ appConfig });
-    installBuildQueue(appConfig);
     routeRendererFactory = new RouteRendererFactory({
         appConfig,
-        runtime,
     });
 }
 async function renderPage(filePath, params, query) {
@@ -101,11 +99,6 @@ parentPort.on('message', async (message) => {
         }
     }
     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 });
+        postMessage(toLitStaticRenderErrorMessage(error, message.type === 'render' ? message.id : undefined));
     }
 });

package/src/STATIC_RENDER.md

@@ -1,75 +0,0 @@
-# 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()
-                                     setupAppRuntimeIntegrations()
-                                     installBuildQueue()
-                                     RouteRendererFactory
-
-LitPlugin.getRenderer()  (creates it through createRenderer(base) on first use after setup(ctx))
-  └─ createLitRenderer(() => renderSession)  hook factory closes over lazy accessor
-
-IntegrationRenderer.execute() (main)
-  └─ ensureIntegrationRuntimeActivated()
-  └─ getRenderSession()
-       ├─ locals or explicit props ─► remote hook declines; core renders in-process
-       └─ session.renderPageInWorker()
-            └─ postMessage(render) ─────► RouteRendererFactory.execute()
-                                          (no active session in worker)
-                                          Lit's preload hook uses
-                                          importServerModule (no entrypoint resolver)
-
-staticExport
-  └─ ensureWorker() with the export base URL; matching identity is reused
-       └─ a different origin restarts the worker
-  └─ preloadStaticRoutes()
-       └─ preload SSR lazy scripts for Lit pages
-  └─ returns a release that disposes the session once the export ends
-```
-
-`ECOPAGES_LIT_STATIC_RENDER_WORKER=true` in the worker environment prevents nested worker creation during `LitPlugin.setup()` and skips processor `.setup()` inside `setupAppRuntimePlugins` (the main thread already prepared artifacts). Integration setup still runs in the worker isolate before `RouteRendererFactory` creates route renderers.
-
-## Ownership
-
-| Concern                    | Owner                                                                                                                                                                  |
-| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Session + worker lifecycle | `LitPlugin` (`renderSession`)                                                                                                                                          |
-| Lazy session lookup        | `createLitRenderer()` hook factory 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.
-
-`staticExport` calls `ensureWorker` with `context.baseUrl` even when setup already created the session. A matching identity is reused; a different export origin replaces the worker before routes are preloaded. Its release disposes the session and clears `renderSession`, so an in-process export leaves no worker thread; renders after the export run in-process.
-
-## Locals policy
-
-When `RouteRendererOptions.locals` or `RouteRendererOptions.props` is present, the Lit remote-render hook declines the worker path and core continues in-process. Request locals are not sent through the worker protocol (structured-clone risk and request-scoped data), and explicit props are not passed because the worker re-imports the route module. Static export uses the worker only for eligible Lit page routes without locals or explicit props; explicit static views continue in-process.
-
-## 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`, `sourceDependencyPaths` and resolved `metadata`, or an error message |
-| `shutdown`          | main → worker | Wait for active renders, tear down activated Integrations, and close the worker message port                  |
-| `shutdown-complete` | worker → main | Confirm Integration teardown completed; the client waits for worker exit and force-terminates after timeout   |