@ecopages/lit 0.2.0-alpha.10 → 0.2.0-alpha.12

package/CHANGELOG.md

@@ -8,12 +8,13 @@ All notable changes to `@ecopages/lit` are documented here.
 
 ### Features
 
-- Aligned Lit with the unified orchestration pipeline and the shared lazy dependency and global injector flow.
+- Aligned Lit with the shared orchestration, lazy dependency, and global injector flow.
 
 ### Bug Fixes
 
-- Prevented the shared Lit hydrate-support bootstrap from re-running on every browser-router navigation.
-- Routed Lit renderer output through Lit's static SSR template pipeline so registered custom elements render declarative shadow DOM during SSR instead of staying as bare host tags.
+- Fixed mixed-template SSR composition, placeholder cleanup, lazy preload handling, and browser-router bootstrap reruns.
+- Routed Lit SSR through the static template pipeline so registered custom elements emit declarative shadow DOM.
+- Fixed component-boundary SSR to inject serialized children through both direct Lit interpolation and repeated Lit child slots when Lit is hosted by other integrations.
 
 ### Refactoring
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ecopages/lit",
-  "version": "0.2.0-alpha.10",
+  "version": "0.2.0-alpha.12",
   "description": "Ecopages lit integration",
   "keywords": [
     "ecopages",
@@ -31,7 +31,7 @@
     "directory": "packages/integrations/lit"
   },
   "peerDependencies": {
-    "@ecopages/core": "0.2.0-alpha.10",
+    "@ecopages/core": "0.2.0-alpha.12",
     "@lit-labs/ssr": "^3.3.0",
     "@lit-labs/ssr-client": "^1.1.7",
     "lit": "^3.2.1"

package/src/lit-renderer.d.ts

@@ -3,17 +3,28 @@
  * @module
  */
 import type { ComponentRenderInput, ComponentRenderResult, EcoComponent, EcoPagesElement, IntegrationRendererRenderOptions, RouteRendererBody } from '@ecopages/core';
+import '@lit-labs/ssr/lib/install-global-dom-shim.js';
 import { IntegrationRenderer, type RenderToResponseContext } from '@ecopages/core/route-renderer/integration-renderer';
 /**
  * A renderer for the Lit integration.
  */
 export declare class LitRenderer extends IntegrationRenderer<EcoPagesElement> {
     name: string;
+    private normalizeDeclarativeShadowRootMarkup;
     private createRenderableMarkup;
+    protected shouldRenderPageComponent(): boolean;
     private renderMarkupToString;
+    private renderValueToString;
+    private isLitManagedComponent;
+    private injectRenderedChildren;
+    private renderHtmlTemplate;
     /**
      * Renders a Lit component boundary for component-level orchestration.
      *
+     * SSR-eligible lazy scripts are preloaded first so custom elements registered
+     * by the component can render their server markup even when the Lit renderer is
+     * entered through cross-integration marker resolution.
+     *
      * Includes component-scoped dependency assets when declared.
      */
     renderComponent(input: ComponentRenderInput): Promise<ComponentRenderResult>;

package/src/lit-renderer.js

@@ -1,39 +1,110 @@
+import "@lit-labs/ssr/lib/install-global-dom-shim.js";
 import { IntegrationRenderer } from "@ecopages/core/route-renderer/integration-renderer";
 import { render } from "@lit-labs/ssr";
-import { RenderResultReadable } from "@lit-labs/ssr/lib/render-result-readable.js";
 import { html as staticHtml, unsafeStatic } from "lit/static-html.js";
 import { LitSsrLazyPreloader } from "./lit-ssr-lazy-preloader.js";
 import { PLUGIN_NAME } from "./lit.plugin.js";
+const HTML_TEMPLATE_SLOT_MARKER = "<--content-->";
+const 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;
 class LitRenderer extends IntegrationRenderer {
   name = PLUGIN_NAME;
+  normalizeDeclarativeShadowRootMarkup(markup) {
+    return markup.replace(DUPLICATE_DECLARATIVE_SHADOW_ROOT_ATTRIBUTE, "");
+  }
   createRenderableMarkup(markup) {
     return staticHtml`${unsafeStatic(markup)}`;
   }
+  shouldRenderPageComponent() {
+    return false;
+  }
   async renderMarkupToString(markup) {
     let renderedHtml = "";
     for (const chunk of render(this.createRenderableMarkup(markup))) {
       renderedHtml += chunk;
     }
-    return renderedHtml;
+    return this.normalizeDeclarativeShadowRootMarkup(renderedHtml);
+  }
+  async renderValueToString(value) {
+    if (typeof value === "string") {
+      return await this.renderMarkupToString(value);
+    }
+    let renderedHtml = "";
+    for (const chunk of render(value)) {
+      renderedHtml += chunk;
+    }
+    return this.normalizeDeclarativeShadowRootMarkup(renderedHtml);
+  }
+  isLitManagedComponent(component) {
+    return component?.config?.integration === this.name || component?.config?.__eco?.integration === this.name;
+  }
+  injectRenderedChildren(template, renderedChildren) {
+    for (const marker of [
+      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(HTML_TEMPLATE_SLOT_MARKER)) {
+      return template.split(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}`;
+  }
+  async renderHtmlTemplate(options) {
+    if (!options.isLitManagedHtmlTemplate) {
+      return String(
+        await options.HtmlTemplate({
+          metadata: options.metadata,
+          children: options.renderedChildren,
+          pageProps: options.pageProps
+        })
+      );
+    }
+    const template = await options.HtmlTemplate({
+      metadata: options.metadata,
+      children: HTML_TEMPLATE_SLOT_MARKER,
+      pageProps: options.pageProps
+    });
+    return this.injectRenderedChildren(String(template), options.renderedChildren);
   }
   /**
    * Renders a Lit component boundary for component-level orchestration.
    *
+   * SSR-eligible lazy scripts are preloaded first so custom elements registered
+   * by the component can render their server markup even when the Lit renderer is
+   * entered through cross-integration marker resolution.
+   *
    * Includes component-scoped dependency assets when declared.
    */
   async renderComponent(input) {
+    await this.preloadSsrLazyScripts([input.component]);
     const component = input.component;
-    const props = input.children === void 0 ? input.props : { ...input.props, children: input.children };
+    const renderedChildren = input.children === void 0 ? void 0 : typeof input.children === "string" ? input.children : await this.renderValueToString(input.children);
+    const props = renderedChildren === void 0 ? input.props : {
+      ...input.props,
+      children: COMPONENT_CHILDREN_SLOT_MARKER
+    };
     const content = await component(props);
-    const markup = String(content);
-    const html = await this.renderMarkupToString(markup);
+    const renderedHtml = await this.renderValueToString(content);
+    const html = renderedChildren === void 0 ? renderedHtml : this.injectRenderedChildren(renderedHtml, renderedChildren);
     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;
     return {
       html,
       canAttachAttributes: true,
-      rootTag: this.getRootTagName(markup),
+      rootTag: this.getRootTagName(html),
       integrationName: this.name,
       assets
     };
@@ -89,26 +160,24 @@ class LitRenderer extends IntegrationRenderer {
     try {
       await this.preloadSsrLazyScripts([Page, Layout]);
       const pageContent = await Page({ params, query, ...props, locals });
-      const children = Layout ? await Layout(
-        {
+      const pageHtml = await this.renderValueToString(pageContent);
+      const children = Layout ? this.isLitManagedComponent(Layout) ? await this.renderValueToString(
+        await Layout({
           children: pageContent,
           locals
-        }
-      ) : pageContent;
-      const template = await HtmlTemplate({
+        })
+      ) : await Layout({
+        children: pageHtml,
+        locals
+      }) : pageHtml;
+      const renderedChildren = this.normalizeDeclarativeShadowRootMarkup(String(children));
+      return this.DOC_TYPE + await this.renderHtmlTemplate({
+        HtmlTemplate,
         metadata,
-        children: "<--content-->",
-        pageProps: props || {}
+        pageProps: props || {},
+        renderedChildren,
+        isLitManagedHtmlTemplate: this.isLitManagedComponent(HtmlTemplate)
       });
-      const [templateStart, templateEnd] = template.split("<--content-->");
-      const DOC_TYPE = this.DOC_TYPE;
-      function* streamBody() {
-        yield DOC_TYPE;
-        yield templateStart;
-        yield* render(staticHtml`${unsafeStatic(children)}`);
-        yield templateEnd;
-      }
-      return new RenderResultReadable(streamBody());
     } catch (error) {
       throw this.createRenderError("Error rendering page", error);
     }
@@ -117,45 +186,42 @@ class LitRenderer extends IntegrationRenderer {
     try {
       const viewConfig = view.config;
       const Layout = viewConfig?.layout;
-      await this.preloadSsrLazyScripts([view, Layout]);
-      const viewFn = view;
-      const pageContent = await viewFn(props);
-      if (ctx.partial) {
-        function* streamBody2() {
-          yield* render(staticHtml`${unsafeStatic(pageContent)}`);
-        }
-        const readable = new RenderResultReadable(streamBody2());
-        return this.createHtmlResponse(readable, ctx);
-      }
-      const DOC_TYPE = this.DOC_TYPE;
-      const children = Layout ? await Layout({ children: pageContent }) : pageContent;
-      const HtmlTemplate = await this.getHtmlTemplate();
-      const metadata = view.metadata ? await view.metadata({
+      const HtmlTemplate = ctx.partial ? void 0 : await this.getHtmlTemplate();
+      const metadata = ctx.partial || !HtmlTemplate ? void 0 : view.metadata ? await view.metadata({
         params: {},
         query: {},
         props,
         appConfig: this.appConfig
       }) : this.appConfig.defaultMetadata;
-      await this.prepareViewDependencies(view, Layout);
-      const template = await HtmlTemplate({
-        metadata,
-        children: "<--content-->",
-        pageProps: props
-      });
-      const [templateStart, templateEnd] = template.split("<--content-->");
-      function* streamBody() {
-        yield DOC_TYPE;
-        yield templateStart;
-        yield* render(staticHtml`${unsafeStatic(children)}`);
-        yield templateEnd;
+      await this.preloadSsrLazyScripts([view, Layout]);
+      if (!ctx.partial) {
+        await this.prepareViewDependencies(view, Layout);
       }
-      const stream = new RenderResultReadable(streamBody());
-      const transformedResponse = await this.htmlTransformer.transform(
-        new Response(stream, {
-          headers: { "Content-Type": "text/html" }
-        })
-      );
-      return this.createHtmlResponse(transformedResponse.body, ctx);
+      const viewFn = view;
+      const renderExecution = await this.captureHtmlRender(async () => {
+        const pageContent = await viewFn(props);
+        const pageHtml = await this.renderValueToString(pageContent);
+        if (ctx.partial) {
+          return this.normalizeDeclarativeShadowRootMarkup(pageHtml);
+        }
+        const children = Layout ? this.isLitManagedComponent(Layout) ? await this.renderValueToString(await Layout({ children: pageContent })) : await Layout({ children: pageHtml }) : pageHtml;
+        const renderedChildren = this.normalizeDeclarativeShadowRootMarkup(String(children));
+        return this.DOC_TYPE + await this.renderHtmlTemplate({
+          HtmlTemplate,
+          metadata: metadata ?? this.appConfig.defaultMetadata,
+          pageProps: props ?? {},
+          renderedChildren,
+          isLitManagedHtmlTemplate: this.isLitManagedComponent(HtmlTemplate)
+        });
+      });
+      const componentsToResolve = ctx.partial ? [view] : [HtmlTemplate, Layout, view].filter(Boolean);
+      const body = await this.finalizeCapturedHtmlRender({
+        html: renderExecution.html,
+        componentsToResolve,
+        graphContext: renderExecution.graphContext,
+        partial: ctx.partial
+      });
+      return this.createHtmlResponse(body, ctx);
     } catch (error) {
       throw this.createRenderError("Error rendering view", error);
     }

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

@@ -6,6 +6,7 @@ type ProcessDependencies = (dependencies: AssetDefinition[], integrationName: st
 export interface LitSsrLazyPreloaderOptions {
     resolveDependencyPath: (componentDir: string, sourcePath: string) => string;
     processDependencies?: ProcessDependencies;
+    preferSourceImports?: boolean;
 }
 /**
  * Encapsulates SSR lazy script preload behavior for Lit components.
@@ -17,10 +18,11 @@ export interface LitSsrLazyPreloaderOptions {
 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 }: LitSsrLazyPreloaderOptions);
+    constructor({ resolveDependencyPath, processDependencies, preferSourceImports }: LitSsrLazyPreloaderOptions);
     /**
      * Detects preload failures that are expected for browser-only modules.
      */

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

@@ -4,12 +4,14 @@ 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 }) {
+  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.
@@ -87,7 +89,10 @@ class LitSsrLazyPreloader {
           return;
         }
         try {
-          await import(pathToFileURL(preloadEntrypoint).href);
+          await import(
+            /* @vite-ignore */
+            pathToFileURL(preloadEntrypoint).href
+          );
           this.ssrPreloadedScripts.add(scriptPath);
         } catch (error) {
           this.ssrPreloadFailedScripts.add(scriptPath);
@@ -112,7 +117,12 @@ class LitSsrLazyPreloader {
     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 {
@@ -140,6 +150,7 @@ class LitSsrLazyPreloader {
       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;
     }
   }

package/src/lit.plugin.d.ts

@@ -2,9 +2,8 @@
  * This module contains the Lit plugin
  * @module
  */
-import '@lit-labs/ssr/lib/install-global-dom-shim.js';
-import './console';
-import { IntegrationPlugin, type IntegrationPluginConfig } from '@ecopages/core/plugins/integration-plugin';
+import './console.js';
+import { IntegrationPlugin, type ComponentBoundaryPolicyInput, type IntegrationPluginConfig } from '@ecopages/core/plugins/integration-plugin';
 import { type AssetDefinition } from '@ecopages/core/services/asset-processing-service';
 import { LitRenderer } from './lit-renderer.js';
 /**
@@ -19,6 +18,17 @@ export declare class LitPlugin extends IntegrationPlugin {
     renderer: typeof LitRenderer;
     constructor(options?: Omit<IntegrationPluginConfig, 'name'>);
     getDependencies(): AssetDefinition[];
+    /**
+     * Declares Lit's cross-integration boundary deferral rule.
+     *
+     * When a non-Lit render pass enters a Lit component boundary, the boundary is
+     * deferred into marker-graph resolution so Lit SSR can render custom elements,
+     * declarative shadow DOM, and other Lit-owned output through the Lit renderer.
+     *
+     * @param input Boundary metadata for the active render pass.
+     * @returns `true` when the boundary should be deferred into the marker pass.
+     */
+    shouldDeferComponentBoundary(input: ComponentBoundaryPolicyInput): boolean;
 }
 /**
  * Factory function to create a Lit plugin instance

package/src/lit.plugin.js

@@ -1,6 +1,7 @@
-import "@lit-labs/ssr/lib/install-global-dom-shim.js";
-import "./console";
-import { IntegrationPlugin } from "@ecopages/core/plugins/integration-plugin";
+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";
@@ -40,6 +41,19 @@ class LitPlugin extends IntegrationPlugin {
       })
     ];
   }
+  /**
+   * Declares Lit's cross-integration boundary deferral rule.
+   *
+   * When a non-Lit render pass enters a Lit component boundary, the boundary is
+   * deferred into marker-graph resolution so Lit SSR can render custom elements,
+   * declarative shadow DOM, and other Lit-owned output through the Lit renderer.
+   *
+   * @param input Boundary metadata for the active render pass.
+   * @returns `true` when the boundary should be deferred into the marker pass.
+   */
+  shouldDeferComponentBoundary(input) {
+    return input.targetIntegration === this.name && input.currentIntegration !== this.name;
+  }
 }
 function litPlugin(options) {
   return new LitPlugin(options);