@ecopages/lit 0.2.1 → 0.3.1

package/src/lit.plugin.js

@@ -1,50 +1,141 @@
-import "./console.js";
-import { IntegrationPlugin } from "@ecopages/core/plugins/integration-plugin";
-import { AssetFactory } from "@ecopages/core/services/asset-processing-service";
-import { litElementHydrateScript } from "./lit-element-hydrate.js";
-import { LitRenderer } from "./lit-renderer.js";
-const PLUGIN_NAME = "lit";
-class LitPlugin extends IntegrationPlugin {
-  renderer = LitRenderer;
-  constructor(options) {
-    super({
-      name: PLUGIN_NAME,
-      extensions: [".lit.tsx"],
-      staticBuildStep: "fetch",
-      ...options
-    });
-    this.integrationDependencies.unshift(...this.getDependencies());
-  }
-  getDependencies() {
-    return [
-      /**
-       * BUG ALERT
-       * Due to an issue appeared in Bun 1.2.2, we need to use a workaround to import the hydrate script.
-       * This is a temporary solution until the issue is resolved.
-       * The litElementHydrateScript is the same file built on Bun 1.1.45.
-       * https://github.com/oven-sh/bun/issues/17180
-       *
-       * AssetFactory.createNodeModuleScript({
-       *    position: 'head',
-       *    importPath: '@lit-labs/ssr-client/lit-element-hydrate-support.js'
-       * })
-       */
-      AssetFactory.createInlineContentScript({
-        position: "head",
-        content: litElementHydrateScript,
-        bundle: false,
-        attributes: {
-          "data-eco-script-id": "lit-hydrate-support"
+import { CUSTOM_ELEMENT_SSR_PRELOAD_CACHE_SCOPES, invalidateCustomElementScriptPreload, } from '@ecopages/core/integration';
+/**
+ * This module contains the Lit plugin
+ * @module
+ */
+import './console.js';
+import { IntegrationPlugin, } from '@ecopages/core/integration';
+import { isLitStaticRenderWorkerThread } from '@ecopages/core/build';
+import path from 'node:path';
+import { AssetFactory } from '@ecopages/core/integration';
+import { litElementHydrateScript } from './lit-element-hydrate.js';
+import { LIT_PLUGIN_NAME } from './lit.constants.js';
+import { createLitRenderer, LitRenderer } from './lit-renderer.js';
+import { LitStaticRenderSession } from './lit-static-render-session.js';
+/**
+ * The name of the Lit plugin
+ */
+export const PLUGIN_NAME = LIT_PLUGIN_NAME;
+/**
+ * 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 class LitPlugin extends IntegrationPlugin {
+    renderer = LitRenderer;
+    renderSession = null;
+    constructor(options) {
+        super({
+            name: PLUGIN_NAME,
+            extensions: ['.lit.tsx'],
+            ...options,
+        });
+        this.integrationDependencies.unshift(...this.getDependencies());
+    }
+    /**
+     * 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() {
+        return [
+            AssetFactory.createInlineContentScript({
+                position: 'head',
+                content: `(() => {${litElementHydrateScript}})();`,
+                bundle: false,
+                attributes: {
+                    'data-eco-script-id': 'lit-hydrate-support',
+                },
+            }),
+        ];
+    }
+    createRenderSession() {
+        if (!this.appConfig || !this.runtime || !this.assetProcessingService) {
+            throw new Error('Lit plugin must be initialized before starting the render worker');
         }
-      })
-    ];
-  }
+        const assetProcessingService = this.assetProcessingService;
+        return new LitStaticRenderSession({
+            preloadScopes: this.runtime.customElementSsrPreloadScopes,
+            integration: this,
+            resolveDependencyPath: (componentDir, sourcePath) => path.join(componentDir, sourcePath),
+            processDependencies: (dependencies, integration) => assetProcessingService.processDependencies(dependencies, integration),
+            getInvalidationVersion: () => this.runtime?.moduleLoader.getDevelopmentGeneration() ?? 0,
+        });
+    }
+    createRenderer(base) {
+        const Renderer = this.renderer === LitRenderer ? createLitRenderer(() => this.renderSession ?? undefined) : this.renderer;
+        const renderer = new Renderer(base);
+        renderer.name ||= this.name;
+        return renderer;
+    }
+    hmr(context) {
+        super.hmr(context);
+        const manager = context.runtime.hmr;
+        if (!manager)
+            return;
+        const preloadScopes = context.runtime.customElementSsrPreloadScopes;
+        manager.onScriptEntrypointChanged?.((scriptPath) => {
+            invalidateCustomElementScriptPreload(preloadScopes, scriptPath, CUSTOM_ELEMENT_SSR_PRELOAD_CACHE_SCOPES.lit);
+        });
+    }
+    async setup(context) {
+        await super.setup(context);
+        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: context.runtime.origin,
+        });
+    }
+    async teardown() {
+        await this.renderSession?.dispose();
+        this.renderSession = null;
+        await super.teardown();
+    }
+    /**
+     * 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.
+     */
+    async staticExport(context) {
+        this.renderSession ??= this.createRenderSession();
+        await this.renderSession.ensureWorker({
+            configModulePath: context.appConfig.absolutePaths.config,
+            runtimeOrigin: context.baseUrl,
+        });
+        const session = this.renderSession;
+        await session.preloadStaticRoutes(context);
+        return async () => {
+            await session.dispose();
+            if (this.renderSession === session) {
+                this.renderSession = null;
+            }
+        };
+    }
 }
-function litPlugin(options) {
-  return new LitPlugin(options);
+/**
+ * Factory function to create a Lit plugin instance
+ * @param options Configuration options for the Lit plugin
+ * @returns A new LitPlugin instance
+ */
+export function litPlugin(options) {
+    return new LitPlugin(options);
 }
-export {
-  LitPlugin,
-  PLUGIN_NAME,
-  litPlugin
-};

package/src/styled-mixin.js

@@ -1,13 +1,21 @@
-import { unsafeCSS } from "lit";
-const StyledMixin = (superClass, css = []) => {
-  class StyledMixinClass extends superClass {
-    static styles = [
-      superClass.styles ?? [],
-      ...css.map((styles) => unsafeCSS(styles))
-    ];
-  }
-  return StyledMixinClass;
-};
-export {
-  StyledMixin
+/**
+ * This module contains StyledMixin
+ * It is used to add styles to a LitElement
+ * @module
+ */
+import { unsafeCSS } from 'lit';
+/**
+ * A mixin to add styles to a LitElement
+ * @param superClass - The class to mix into
+ * @param css - The styles to add
+ * @returns The class with the styles added
+ */
+export const StyledMixin = (superClass, css = []) => {
+    class StyledMixinClass extends superClass {
+        static styles = [
+            superClass.styles ?? [],
+            ...css.map((styles) => unsafeCSS(styles)),
+        ];
+    }
+    return StyledMixinClass;
 };

package/src/utils/lit-html-rendering.d.ts

@@ -0,0 +1,5 @@
+export declare const LIT_HTML_TEMPLATE_SLOT_MARKER = "<--content-->";
+export declare const LIT_COMPONENT_CHILDREN_SLOT_MARKER = "<!--eco-lit-component-children-->";
+export declare function normalizeLitHtml(markup: string): string;
+export declare function injectLitRenderedChildren(template: string, renderedChildren: string): string;
+export declare function renderLitValueToString(value: unknown): Promise<string>;

package/src/utils/lit-html-rendering.js

@@ -0,0 +1,45 @@
+import { render } from '@lit-labs/ssr';
+import { html as staticHtml, unsafeStatic } from 'lit/static-html.js';
+export const LIT_HTML_TEMPLATE_SLOT_MARKER = '<--content-->';
+export const LIT_COMPONENT_CHILDREN_SLOT_MARKER = '<!--eco-lit-component-children-->';
+const ESCAPED_COMPONENT_CHILDREN_SLOT_MARKER = '&lt;!--eco-lit-component-children--&gt;';
+const DOUBLE_ESCAPED_COMPONENT_CHILDREN_SLOT_MARKER = '&amp;lt;!--eco-lit-component-children--&amp;gt;';
+const DUPLICATE_DECLARATIVE_SHADOW_ROOT_ATTRIBUTE = /\sshadowroot=(['"])(open|closed)\1(?=\sshadowrootmode=\1\2\1)/g;
+export function normalizeLitHtml(markup) {
+    return markup.replace(DUPLICATE_DECLARATIVE_SHADOW_ROOT_ATTRIBUTE, '');
+}
+export function injectLitRenderedChildren(template, renderedChildren) {
+    for (const marker of [
+        LIT_COMPONENT_CHILDREN_SLOT_MARKER,
+        ESCAPED_COMPONENT_CHILDREN_SLOT_MARKER,
+        DOUBLE_ESCAPED_COMPONENT_CHILDREN_SLOT_MARKER,
+    ]) {
+        if (template.includes(marker)) {
+            return template.split(marker).join(renderedChildren);
+        }
+    }
+    if (template.includes(LIT_HTML_TEMPLATE_SLOT_MARKER)) {
+        return template.split(LIT_HTML_TEMPLATE_SLOT_MARKER).join(renderedChildren);
+    }
+    if (template.includes('</body>')) {
+        return template.replace('</body>', `${renderedChildren}</body>`);
+    }
+    if (template.includes('</html>')) {
+        return template.replace('</html>', `${renderedChildren}</html>`);
+    }
+    return `${template}${renderedChildren}`;
+}
+export async function renderLitValueToString(value) {
+    if (typeof value === 'string') {
+        let renderedHtml = '';
+        for (const chunk of render(staticHtml `${unsafeStatic(value)}`)) {
+            renderedHtml += chunk;
+        }
+        return normalizeLitHtml(renderedHtml);
+    }
+    let renderedHtml = '';
+    for (const chunk of render(value)) {
+        renderedHtml += chunk;
+    }
+    return normalizeLitHtml(renderedHtml);
+}

package/CHANGELOG.md

@@ -1,19 +0,0 @@
-# Changelog
-
-All notable changes to `@ecopages/lit` are documented here.
-
-> **Note:** Changelog tracking begins at version `0.2.0`. Changes prior to this release are not recorded here but are available in the git history.
-
-## [0.2.1] — 2026-04-16
-
-### Bug Fixes
-
-- Fixed Lit document-shell composition, declarative shadow DOM SSR, nested child serialization, lazy preload handling, explicit render paths, and mixed-renderer boundary resolution.
-
-### Documentation
-
-- Updated the README to document `.lit.tsx` route ownership, standalone setup, and mixed-renderer Lit boundary handling.
-
-### Tests
-
-- Updated integration coverage for explicit boundary composition and Node and esbuild compatibility.

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

@@ -1,43 +0,0 @@
-import type { EcoComponent } from '@ecopages/core';
-import type { AssetDefinition } from '@ecopages/core/services/asset-processing-service';
-type ProcessDependencies = (dependencies: AssetDefinition[], integrationName: string) => Promise<Array<{
-    filepath?: string;
-}>>;
-export interface LitSsrLazyPreloaderOptions {
-    resolveDependencyPath: (componentDir: string, sourcePath: string) => string;
-    processDependencies?: ProcessDependencies;
-    preferSourceImports?: boolean;
-}
-/**
- * Encapsulates SSR lazy script preload behavior for Lit components.
- *
- * Collects `dependencies.scripts` lazy entries with `ssr: true`, resolves the
- * processed entrypoint through the asset pipeline, and imports the module so
- * custom elements are registered before SSR rendering.
- */
-export declare class LitSsrLazyPreloader {
-    private readonly resolveDependencyPath;
-    private readonly processDependencies?;
-    private readonly preferSourceImports;
-    private readonly ssrPreloadedScripts;
-    private readonly ssrPreloadFailedScripts;
-    private readonly ssrPreloadEntrypointCache;
-    constructor({ resolveDependencyPath, processDependencies, preferSourceImports }: LitSsrLazyPreloaderOptions);
-    /**
-     * Detects preload failures that are expected for browser-only modules.
-     */
-    isExpectedSsrPreloadError(error: unknown): boolean;
-    /**
-     * Collects lazy script file paths eligible for SSR preloading.
-     */
-    collectSsrPreloadScripts(components: Array<EcoComponent | undefined>): string[];
-    /**
-     * Preloads SSR-eligible lazy scripts to register custom elements before render.
-     */
-    preloadSsrLazyScripts(components: Array<EcoComponent | undefined>): Promise<void>;
-    /**
-     * Resolves the concrete JS entrypoint used for SSR preloading.
-     */
-    resolveSsrPreloadEntrypoint(scriptPath: string): Promise<string | null>;
-}
-export {};

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

@@ -1,160 +0,0 @@
-import { AssetFactory } from "@ecopages/core/services/asset-processing-service";
-import path from "node:path";
-import { pathToFileURL } from "node:url";
-class LitSsrLazyPreloader {
-  resolveDependencyPath;
-  processDependencies;
-  preferSourceImports;
-  ssrPreloadedScripts = /* @__PURE__ */ new Set();
-  ssrPreloadFailedScripts = /* @__PURE__ */ new Set();
-  ssrPreloadEntrypointCache = /* @__PURE__ */ new Map();
-  constructor({ resolveDependencyPath, processDependencies, preferSourceImports }) {
-    this.resolveDependencyPath = resolveDependencyPath;
-    this.processDependencies = processDependencies;
-    this.preferSourceImports = preferSourceImports ?? typeof Bun !== "undefined";
-  }
-  /**
-   * Detects preload failures that are expected for browser-only modules.
-   */
-  isExpectedSsrPreloadError(error) {
-    const errorMessage = error instanceof Error ? error.message : String(error);
-    const errorCode = typeof error === "object" && error !== null && "code" in error ? String(error.code ?? "") : "";
-    if (errorCode === "ERR_UNKNOWN_FILE_EXTENSION") {
-      return true;
-    }
-    return errorMessage.includes(`reading 'Element'`) || errorMessage.includes("window is not defined") || errorMessage.includes("document is not defined") || errorMessage.includes("navigator is not defined");
-  }
-  /**
-   * Collects lazy script file paths eligible for SSR preloading.
-   */
-  collectSsrPreloadScripts(components) {
-    const scriptPaths = /* @__PURE__ */ new Set();
-    const visitedConfigs = /* @__PURE__ */ new Set();
-    const collect = (component) => {
-      const config = component?.config;
-      if (!config || visitedConfigs.has(config)) {
-        return;
-      }
-      visitedConfigs.add(config);
-      const scriptEntries = config.dependencies?.scripts ?? [];
-      const componentFile = config.__eco?.file;
-      if (componentFile) {
-        const componentDir = path.dirname(componentFile);
-        for (const script of scriptEntries) {
-          if (typeof script === "string") {
-            continue;
-          }
-          if (!script.lazy || script.ssr !== true) {
-            continue;
-          }
-          if (!script.src) {
-            continue;
-          }
-          scriptPaths.add(this.resolveDependencyPath(componentDir, script.src));
-        }
-      }
-      if (config.layout) {
-        collect(config.layout);
-      }
-      for (const nestedComponent of config.dependencies?.components || []) {
-        collect(nestedComponent);
-      }
-    };
-    for (const component of components) {
-      collect(component);
-    }
-    return Array.from(scriptPaths);
-  }
-  /**
-   * Preloads SSR-eligible lazy scripts to register custom elements before render.
-   */
-  async preloadSsrLazyScripts(components) {
-    const scripts = this.collectSsrPreloadScripts(components);
-    if (scripts.length === 0) {
-      return;
-    }
-    await Promise.all(
-      scripts.filter((scriptPath) => {
-        if (this.ssrPreloadedScripts.has(scriptPath)) {
-          return false;
-        }
-        if (this.ssrPreloadFailedScripts.has(scriptPath)) {
-          return false;
-        }
-        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
-          );
-          this.ssrPreloadedScripts.add(scriptPath);
-        } catch (error) {
-          this.ssrPreloadFailedScripts.add(scriptPath);
-          if (this.isExpectedSsrPreloadError(error)) {
-            if (process.env.ECOPAGES_DEBUG === "true") {
-              console.warn(
-                `[ecopages][lit] Skipping SSR preload for browser-only lazy script: ${scriptPath}`
-              );
-            }
-            return;
-          }
-          console.warn(`[ecopages][lit] Failed to preload lazy SSR script: ${scriptPath}`, error);
-        }
-      })
-    );
-  }
-  /**
-   * Resolves the concrete JS entrypoint used for SSR preloading.
-   */
-  async resolveSsrPreloadEntrypoint(scriptPath) {
-    const cachedEntrypoint = this.ssrPreloadEntrypointCache.get(scriptPath);
-    if (cachedEntrypoint) {
-      return cachedEntrypoint;
-    }
-    if (this.preferSourceImports) {
-      this.ssrPreloadEntrypointCache.set(scriptPath, scriptPath);
-      return scriptPath;
-    }
-    if (!this.processDependencies) {
-      this.ssrPreloadEntrypointCache.set(scriptPath, scriptPath);
-      return scriptPath;
-    }
-    try {
-      const processed = await this.processDependencies(
-        [
-          AssetFactory.createInlineFileScript({
-            filepath: scriptPath,
-            position: "head",
-            bundle: true,
-            attributes: {
-              type: "module",
-              defer: ""
-            }
-          })
-        ],
-        `lit-ssr-preload:${scriptPath}`
-      );
-      const entrypoint = processed[0]?.filepath;
-      if (!entrypoint) {
-        return scriptPath;
-      }
-      this.ssrPreloadEntrypointCache.set(scriptPath, entrypoint);
-      return entrypoint;
-    } catch (error) {
-      if (process.env.ECOPAGES_DEBUG === "true") {
-        console.warn(`[ecopages][lit] Failed to resolve SSR preload entrypoint for: ${scriptPath}`, error);
-      }
-      this.ssrPreloadEntrypointCache.set(scriptPath, scriptPath);
-      return scriptPath;
-    }
-  }
-}
-export {
-  LitSsrLazyPreloader
-};