@ecopages/lit 0.2.0-rc.3 → 0.2.0-rc.5

package/README.md

@@ -55,6 +55,12 @@ When a non-Lit render pass reaches a Lit-owned foreign child, Ecopages hands tha
 
 Important:
 
-- Components that may render foreign children must declare those children in `config.dependencies.components`.
+- Direct local imports of declared Eco Components contribute their Dependencies automatically, including Foreign Children and named `export { X } from` barrels. Use `dependencies.components` for `export *` barrels and package imports.
 - Ecopages validates ownership from declared dependencies during render preparation instead of relying on post-render HTML discovery.
 - Lit keeps slot transport, shadow-root handling, and SSR preload behavior inside the Lit renderer.
+
+## Discovered assets and lazy custom elements
+
+A Lit Component can import a relative stylesheet with `import './counter.css'`; core extracts it into the shared asset pipeline. Direct local imports of that Component make its Dependencies available to the Lit SSR preloader, including through Foreign Child rendering.
+
+Keep custom-element registration explicit with `scripts: [{ src: './counter.script.ts', ssr: true, lazy: { 'on:visible': true } }]`. The module executes before server rendering and loads in the browser on visibility. `ssr: true` no longer emits an additional eager browser script. Omit `lazy` when eager browser loading is intended. SSR preload artifacts are excluded from HTML, and hydration support must be available before the browser registers the element.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/lit",
-  "version": "0.2.0-rc.3",
+  "version": "0.2.0-rc.5",
   "description": "Ecopages lit integration",
   "keywords": [
     "ecopages",
@@ -11,6 +11,9 @@
   "main": "./src/lit.plugin.js",
   "types": "./src/lit.plugin.d.ts",
   "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
   "exports": {
     ".": {
       "default": "./src/lit.plugin.js",
@@ -39,9 +42,9 @@
     "directory": "packages/integrations/lit"
   },
   "peerDependencies": {
-    "@ecopages/core": "0.2.0-rc.3",
+    "@ecopages/core": "0.2.0-rc.5",
     "@lit-labs/ssr": "^3.3.0",
     "@lit-labs/ssr-client": "^1.1.7",
     "lit": "^3.2.1"
   }
-}
+}

package/src/console.d.ts

@@ -1,4 +1,5 @@
 declare const originalConsoleWarn: {
+    (...data: any[]): void;
     (...data: any[]): void;
     (...data: any[]): void;
     (message?: any, ...optionalParams: any[]): void;

package/src/dom-shim.d.ts

@@ -1 +1,3 @@
 import '@lit-labs/ssr/lib/install-global-dom-shim.js';
+/** Repairs the minimal Lit DOM surface after another Integration installs its SSR globals. */
+export declare function ensureLitDomShim(): void;

package/src/dom-shim.js

@@ -1,14 +1,18 @@
 import { installWindowOnGlobal } from '@lit-labs/ssr/lib/dom-shim.js';
 import '@lit-labs/ssr/lib/install-global-dom-shim.js';
-if (typeof globalThis.document?.createTreeWalker !== 'function') {
-    if (typeof globalThis.window === 'undefined') {
-        installWindowOnGlobal();
-    }
-    else {
-        Object.defineProperty(globalThis.document, 'createTreeWalker', {
-            configurable: true,
-            writable: true,
-            value: () => ({}),
-        });
+/** Repairs the minimal Lit DOM surface after another Integration installs its SSR globals. */
+export function ensureLitDomShim() {
+    if (typeof globalThis.document?.createTreeWalker !== 'function') {
+        if (typeof globalThis.window === 'undefined') {
+            installWindowOnGlobal();
+        }
+        else {
+            Object.defineProperty(globalThis.document, 'createTreeWalker', {
+                configurable: true,
+                writable: true,
+                value: () => ({}),
+            });
+        }
     }
 }
+ensureLitDomShim();

package/src/lit-renderer.js

@@ -1,7 +1,4 @@
-/**
- * This module contains the Lit renderer
- * @module
- */
+import { createLitServerModuleImporter } from './lit-server-module-loader.js';
 import './dom-shim.js';
 import { IntegrationRenderer, } from '@ecopages/core/route-renderer/orchestration/integration-renderer';
 import { resolveDocumentShellLayouts } from '@ecopages/core/route-renderer/orchestration/document-shell/layout-shell-props.service';
@@ -137,6 +134,7 @@ export class LitRenderer extends IntegrationRenderer {
         });
     }
     ssrLazyPreloader = new LitSsrLazyPreloader({
+        importServerModule: createLitServerModuleImporter(this.appConfig),
         resolveDependencyPath: this.resolveDependencyPath.bind(this),
         processDependencies: this.assetProcessingService?.processDependencies?.bind(this.assetProcessingService),
     });

package/src/lit-server-module-loader.d.ts

@@ -0,0 +1,6 @@
+import type { EcoPagesAppConfig } from '@ecopages/core';
+/**
+ * Uses server export conditions and isolates module evaluation by custom-element
+ * registry. Browser asset output must never be evaluated as the SSR implementation.
+ */
+export declare function createLitServerModuleImporter(appConfig: EcoPagesAppConfig): (filePath: string, registryKey: string) => Promise<unknown>;

package/src/lit-server-module-loader.js

@@ -0,0 +1,18 @@
+import path from 'node:path';
+/**
+ * Uses server export conditions and isolates module evaluation by custom-element
+ * registry. Browser asset output must never be evaluated as the SSR implementation.
+ */
+export function createLitServerModuleImporter(appConfig) {
+    return async (filePath, registryKey) => {
+        const loader = appConfig.runtime?.appModuleLoader;
+        if (!loader)
+            throw new Error('Lit SSR requires the app server module loader');
+        return loader.importModule({
+            filePath,
+            rootDir: appConfig.rootDir,
+            outdir: path.join(appConfig.absolutePaths.workDir, '.lit-ssr', registryKey),
+            forceBuild: true,
+        });
+    };
+}

package/src/lit-ssr-lazy-preloader.d.ts

@@ -7,6 +7,7 @@ export interface LitSsrLazyPreloaderOptions {
     resolveDependencyPath: (componentDir: string, sourcePath: string) => string;
     processDependencies?: ProcessDependencies;
     preferSourceImports?: boolean;
+    importServerModule?: (scriptPath: string, registryKey: string) => Promise<unknown>;
 }
 /**
  * Encapsulates SSR lazy script preload behavior for Lit components.
@@ -19,10 +20,12 @@ export declare class LitSsrLazyPreloader {
     private readonly resolveDependencyPath;
     private readonly processDependencies?;
     private readonly preferSourceImports;
+    private readonly importServerModule?;
+    private activeRegistry;
     private readonly ssrPreloadedScripts;
     private readonly ssrPreloadFailedScripts;
     private readonly ssrPreloadEntrypointCache;
-    constructor({ resolveDependencyPath, processDependencies, preferSourceImports }: LitSsrLazyPreloaderOptions);
+    constructor({ resolveDependencyPath, processDependencies, preferSourceImports, importServerModule, }: LitSsrLazyPreloaderOptions);
     private getErrorCode;
     /**
      * Detects preload failures that are expected for browser-only modules.

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

@@ -1,7 +1,18 @@
+import { ensureLitDomShim } from './dom-shim.js';
 import { getComponentIdentity } from '@ecopages/core';
 import { AssetFactory } from '@ecopages/core/services/asset-processing-service';
 import path from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { randomUUID } from 'node:crypto';
+const registryKeys = new WeakMap();
+function getRegistryKey(registry) {
+    let key = registryKeys.get(registry);
+    if (!key) {
+        key = randomUUID();
+        registryKeys.set(registry, key);
+    }
+    return key;
+}
 /**
  * Encapsulates SSR lazy script preload behavior for Lit components.
  *
@@ -13,10 +24,13 @@ export class LitSsrLazyPreloader {
     resolveDependencyPath;
     processDependencies;
     preferSourceImports;
+    importServerModule;
+    activeRegistry;
     ssrPreloadedScripts = new Set();
     ssrPreloadFailedScripts = new Set();
     ssrPreloadEntrypointCache = new Map();
-    constructor({ resolveDependencyPath, processDependencies, preferSourceImports }) {
+    constructor({ resolveDependencyPath, processDependencies, preferSourceImports, importServerModule, }) {
+        this.importServerModule = importServerModule;
         this.resolveDependencyPath = resolveDependencyPath;
         this.processDependencies = processDependencies;
         this.preferSourceImports = preferSourceImports ?? typeof Bun !== 'undefined';
@@ -87,6 +101,13 @@ export class LitSsrLazyPreloader {
      * Preloads SSR-eligible lazy scripts to register custom elements before render.
      */
     async preloadSsrLazyScripts(components) {
+        ensureLitDomShim();
+        const registry = globalThis.customElements;
+        if (this.activeRegistry !== registry) {
+            this.ssrPreloadedScripts.clear();
+            this.ssrPreloadFailedScripts.clear();
+            this.activeRegistry = registry;
+        }
         const scripts = this.collectSsrPreloadScripts(components);
         if (scripts.length === 0) {
             return;
@@ -102,13 +123,20 @@ export class LitSsrLazyPreloader {
             return true;
         })
             .map(async (scriptPath) => {
-            const preloadEntrypoint = await this.resolveSsrPreloadEntrypoint(scriptPath);
-            if (!preloadEntrypoint) {
-                this.ssrPreloadFailedScripts.add(scriptPath);
-                return;
-            }
             try {
-                await import(/* @vite-ignore */ pathToFileURL(preloadEntrypoint).href);
+                const registryKey = registry ? getRegistryKey(registry) : 'default';
+                if (this.importServerModule) {
+                    await this.importServerModule(scriptPath, registryKey);
+                }
+                else {
+                    const preloadEntrypoint = await this.resolveSsrPreloadEntrypoint(scriptPath);
+                    if (!preloadEntrypoint)
+                        throw new Error(`Cannot resolve SSR entry ${scriptPath}`);
+                    const importUrl = pathToFileURL(preloadEntrypoint);
+                    if (registry && typeof Bun === 'undefined')
+                        importUrl.searchParams.set('eco-ssr-registry', registryKey);
+                    await import(/* @vite-ignore */ importUrl.href);
+                }
                 this.ssrPreloadedScripts.add(scriptPath);
             }
             catch (error) {
@@ -143,6 +171,7 @@ export class LitSsrLazyPreloader {
             const processed = await this.processDependencies([
                 AssetFactory.createInlineFileScript({
                     filepath: scriptPath,
+                    excludeFromHtml: true,
                     position: 'head',
                     bundle: true,
                     attributes: {

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

@@ -1,6 +1,7 @@
 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 { type LitSsrLazyPreloaderOptions } from './lit-ssr-lazy-preloader.js';
 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'>;
@@ -10,6 +11,8 @@ type LitStaticRenderSessionOptions = {
         filepath?: string;
     }>>;
     preferSourceImports?: boolean;
+    importServerModule?: LitSsrLazyPreloaderOptions['importServerModule'];
+    getInvalidationVersion?: () => number;
     createWorkerClient?: (input: {
         configModulePath: string;
         runtimeOrigin: string;
@@ -32,6 +35,9 @@ export declare class LitStaticRenderSession {
     private readonly createWorkerClient;
     private workerClient;
     private workerIdentity;
+    private readonly getInvalidationVersion;
+    private workerInvalidationVersion;
+    private renderChain;
     constructor(options: LitStaticRenderSessionOptions);
     /**
      * Ensures the static render worker is running for the given identity.

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

@@ -19,11 +19,16 @@ export class LitStaticRenderSession {
     createWorkerClient;
     workerClient = null;
     workerIdentity = null;
+    getInvalidationVersion;
+    workerInvalidationVersion = 0;
+    renderChain = Promise.resolve();
     constructor(options) {
+        this.getInvalidationVersion = options.getInvalidationVersion ?? (() => 0);
         this.preloader = new LitSsrLazyPreloader({
             resolveDependencyPath: options.resolveDependencyPath,
             processDependencies: options.processDependencies,
             preferSourceImports: options.preferSourceImports,
+            importServerModule: options.importServerModule,
         });
         this.createWorkerClient =
             options.createWorkerClient ??
@@ -58,6 +63,7 @@ export class LitStaticRenderSession {
             runtimeOrigin: input.runtimeOrigin,
         });
         await this.workerClient.start();
+        this.workerInvalidationVersion = this.getInvalidationVersion();
     }
     async preloadStaticRoutes(context) {
         await this.preloadLitRoutes(context);
@@ -72,7 +78,19 @@ export class LitStaticRenderSession {
         if (!this.workerClient) {
             throw new Error('Lit static render worker is not active');
         }
-        return this.workerClient.renderPage(input);
+        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);

package/src/lit.plugin.js

@@ -1,3 +1,4 @@
+import { createLitServerModuleImporter } from './lit-server-module-loader.js';
 /**
  * This module contains the Lit plugin
  * @module
@@ -66,6 +67,8 @@ export class LitPlugin extends IntegrationPlugin {
         return new LitStaticRenderSession({
             resolveDependencyPath: (componentDir, sourcePath) => path.join(componentDir, sourcePath),
             processDependencies: this.assetProcessingService.processDependencies.bind(this.assetProcessingService),
+            getInvalidationVersion: () => this.appConfig?.runtime?.serverInvalidationState?.getServerInvalidationVersion() ?? 0,
+            importServerModule: createLitServerModuleImporter(this.appConfig),
             preferSourceImports: typeof Bun !== 'undefined',
         });
     }