@ecopages/lit 0.2.0-alpha.11 → 0.2.0-alpha.13

package/CHANGELOG.md

@@ -6,19 +6,14 @@ All notable changes to `@ecopages/lit` are documented here.
 
 ## [UNRELEASED] — TBD
 
-### Features
-
-- Aligned Lit with the shared orchestration, lazy dependency, and global injector flow.
-
 ### Bug Fixes
 
-- 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 Lit document-shell composition, declarative shadow DOM SSR, nested child serialization, lazy preload handling, explicit render paths, and mixed-renderer boundary resolution.
 
-### Refactoring
+### Documentation
 
-- Cleaned up ambient module declarations.
+- Updated the README to document `.lit.tsx` route ownership, standalone setup, and mixed-renderer Lit boundary handling.
 
 ### Tests
 
-- Updated integration coverage for the orchestration pipeline and Node and esbuild compatibility.
+- Updated integration coverage for explicit boundary composition and Node and esbuild compatibility.

package/README.md

@@ -1,8 +1,6 @@
 # @ecopages/lit
 
-Integration plugin for [Lit](https://lit.dev/) web components in Ecopages.
-
-This integration is optimized for use alongside `@ecopages/kitajs` (or another HTML JSX engine), allowing you to author your pages in Kitajs JSX templates while embedding interactive Lit components where needed.
+Integration plugin for [Lit](https://lit.dev/) in Ecopages. Use it when Lit should own `.lit.tsx` routes or when another integration needs Lit to render nested custom-element boundaries.
 
 ## Installation
 
@@ -12,7 +10,21 @@ bunx jsr add @ecopages/lit
 
 ## Usage
 
-It is recommended to use `@ecopages/lit` in conjunction with `@ecopages/kitajs`. Configure your project to include both integrations in your `eco.config.ts`:
+Register `litPlugin()` in your `eco.config.ts`.
+
+```ts
+import { ConfigBuilder } from '@ecopages/core/config-builder';
+import { litPlugin } from '@ecopages/lit';
+
+const config = await new ConfigBuilder()
+	.setBaseUrl(import.meta.env.ECOPAGES_BASE_URL)
+	.setIntegrations([litPlugin()])
+	.build();
+
+export default config;
+```
+
+Lit also works well alongside an HTML-first renderer such as `@ecopages/kitajs` when you want Lit to own only the nested custom elements:
 
 ```ts
 import { ConfigBuilder } from '@ecopages/core/config-builder';
@@ -27,4 +39,14 @@ const config = await new ConfigBuilder()
 export default config;
 ```
 
-This setup enables server-rendered KitaJS pages that embed and hydrate Lit custom elements on the client.
+This setup lets Kita own the page shell while Lit owns the nested Lit component boundaries.
+
+## What This Integration Owns
+
+- `.lit.tsx` route files.
+- Nested Lit component boundaries rendered inside pages owned by other integrations.
+- The Lit hydration support script required for SSR custom elements and declarative shadow DOM.
+
+## Mixed Rendering
+
+When a non-Lit render pass enters a Lit-owned component boundary, Ecopages hands that boundary to the Lit renderer. That keeps Lit SSR in charge of custom elements, declarative shadow DOM, and Lit-managed child content.

package/package.json

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

package/src/lit-renderer.d.ts

@@ -3,14 +3,18 @@
  * @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;
-    protected shouldRenderPageComponent(): boolean;
+    private resolveQueuedBoundaryChildren;
+    private resolveQueuedBoundaryHtml;
+    private normalizeDeclarativeShadowRootMarkup;
     private createRenderableMarkup;
+    protected shouldRenderPageComponent(): boolean;
     private renderMarkupToString;
     private renderValueToString;
     private isLitManagedComponent;
@@ -21,11 +25,15 @@ export declare class LitRenderer extends IntegrationRenderer<EcoPagesElement> {
      *
      * 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.
+     * entered through cross-integration boundary handoff.
      *
      * Includes component-scoped dependency assets when declared.
      */
     renderComponent(input: ComponentRenderInput): Promise<ComponentRenderResult>;
+    protected createComponentBoundaryRuntime(options: {
+        boundaryInput: ComponentRenderInput;
+        rendererCache: Map<string, IntegrationRenderer<any>>;
+    }): import("@ecopages/core").ComponentBoundaryRuntime;
     private readonly ssrLazyPreloader;
     /**
      * Detects preload failures that are expected for browser-only modules.

package/src/lit-renderer.js

@@ -1,23 +1,65 @@
+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 { 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;
-  shouldRenderPageComponent() {
-    return false;
+  async resolveQueuedBoundaryChildren(children, queuedResolutionsByToken, resolveToken) {
+    if (children === void 0) {
+      return void 0;
+    }
+    let renderedChildren = typeof children === "string" ? children : await this.renderValueToString(children);
+    renderedChildren = await this.resolveQueuedBoundaryTokens(
+      renderedChildren,
+      queuedResolutionsByToken,
+      resolveToken
+    );
+    return renderedChildren;
+  }
+  async resolveQueuedBoundaryHtml(html, runtimeContext) {
+    const queuedBoundaryResolution = await this.resolveRendererOwnedQueuedBoundaryHtml({
+      html,
+      runtimeContext,
+      queueLabel: "Lit",
+      renderQueuedChildren: async (children, _runtimeContext, queuedResolutionsByToken, resolveToken) => {
+        const renderedChildren = await this.resolveQueuedBoundaryChildren(
+          children,
+          queuedResolutionsByToken,
+          resolveToken
+        );
+        return {
+          assets: [],
+          html: renderedChildren
+        };
+      }
+    });
+    return {
+      html: queuedBoundaryResolution.html,
+      assets: queuedBoundaryResolution.assets.length > 0 ? queuedBoundaryResolution.assets : void 0
+    };
+  }
+  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") {
@@ -27,14 +69,23 @@ class LitRenderer extends IntegrationRenderer {
     for (const chunk of render(value)) {
       renderedHtml += chunk;
     }
-    return renderedHtml;
+    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.replace(HTML_TEMPLATE_SLOT_MARKER, renderedChildren);
+      return template.split(HTML_TEMPLATE_SLOT_MARKER).join(renderedChildren);
     }
     if (template.includes("</body>")) {
       return template.replace("</body>", `${renderedChildren}</body>`);
@@ -66,27 +117,51 @@ class LitRenderer extends IntegrationRenderer {
    *
    * 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.
+   * entered through cross-integration boundary handoff.
    *
    * 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 };
+    let renderedChildren;
+    if (input.children !== void 0) {
+      renderedChildren = typeof input.children === "string" ? input.children : await this.renderValueToString(input.children);
+    }
+    let props = input.props;
+    if (renderedChildren !== void 0) {
+      props = {
+        ...input.props,
+        children: COMPONENT_CHILDREN_SLOT_MARKER
+      };
+    }
     const content = await component(props);
-    const html = await this.renderValueToString(content);
+    const renderedHtml = await this.renderValueToString(content);
+    const html = renderedChildren === void 0 ? renderedHtml : this.injectRenderedChildren(renderedHtml, renderedChildren);
+    const queuedBoundaryResolution = await this.resolveQueuedBoundaryHtml(
+      html,
+      this.getQueuedBoundaryRuntime(input)
+    );
     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,
+      html: queuedBoundaryResolution.html,
       canAttachAttributes: true,
-      rootTag: this.getRootTagName(html),
+      rootTag: this.getRootTagName(queuedBoundaryResolution.html),
       integrationName: this.name,
-      assets
+      assets: this.htmlTransformer.dedupeProcessedAssets([
+        ...assets ?? [],
+        ...queuedBoundaryResolution.assets ?? []
+      ])
     };
   }
+  createComponentBoundaryRuntime(options) {
+    return this.createQueuedBoundaryRuntime({
+      boundaryInput: options.boundaryInput,
+      rendererCache: options.rendererCache
+    });
+  }
   ssrLazyPreloader = new LitSsrLazyPreloader({
     resolveDependencyPath: this.resolveDependencyPath.bind(this),
     processDependencies: this.assetProcessingService?.processDependencies?.bind(this.assetProcessingService)
@@ -137,24 +212,24 @@ class LitRenderer extends IntegrationRenderer {
   }) {
     try {
       await this.preloadSsrLazyScripts([Page, Layout]);
-      const pageContent = await Page({ params, query, ...props, locals });
-      const pageHtml = await this.renderValueToString(pageContent);
-      const children = Layout ? this.isLitManagedComponent(Layout) ? await this.renderValueToString(
-        await Layout({
-          children: pageContent,
-          locals
-        })
-      ) : await Layout({
-        children: pageHtml,
-        locals
-      }) : pageHtml;
-      const renderedChildren = this.isLitManagedComponent(HtmlTemplate) ? await this.renderMarkupToString(String(children)) : String(children);
-      return this.DOC_TYPE + await this.renderHtmlTemplate({
-        HtmlTemplate,
+      return await this.renderPageWithDocumentShell({
+        page: {
+          component: Page,
+          props: {
+            params,
+            query,
+            ...props,
+            locals
+          }
+        },
+        layout: Layout ? {
+          component: Layout,
+          props: locals ? { locals } : {}
+        } : void 0,
+        htmlTemplate: HtmlTemplate,
         metadata,
         pageProps: props || {},
-        renderedChildren,
-        isLitManagedHtmlTemplate: this.isLitManagedComponent(HtmlTemplate)
+        transformDocumentHtml: (html) => this.normalizeDeclarativeShadowRootMarkup(html)
       });
     } catch (error) {
       throw this.createRenderError("Error rendering page", error);
@@ -162,42 +237,41 @@ class LitRenderer extends IntegrationRenderer {
   }
   async renderToResponse(view, props, ctx) {
     try {
+      if (ctx.partial) {
+        return this.renderPartialViewResponse({
+          view,
+          props,
+          ctx,
+          transformHtml: (html) => this.normalizeDeclarativeShadowRootMarkup(html)
+        });
+      }
       const viewConfig = view.config;
       const Layout = viewConfig?.layout;
-      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;
+      const HtmlTemplate = await this.getHtmlTemplate();
+      const metadata = await this.resolveViewMetadata(view, props);
       await this.preloadSsrLazyScripts([view, Layout]);
-      if (!ctx.partial) {
-        await this.prepareViewDependencies(view, Layout);
-      }
-      const viewFn = view;
-      const renderExecution = await this.captureHtmlRender(async () => {
-        const pageContent = await viewFn(props);
-        const pageHtml = await this.renderValueToString(pageContent);
-        if (ctx.partial) {
-          return await this.renderMarkupToString(pageHtml);
-        }
-        const children = Layout ? this.isLitManagedComponent(Layout) ? await this.renderValueToString(await Layout({ children: pageContent })) : await Layout({ children: pageHtml }) : pageHtml;
-        const renderedChildren = this.isLitManagedComponent(HtmlTemplate) ? await this.renderMarkupToString(String(children)) : String(children);
-        return this.DOC_TYPE + await this.renderHtmlTemplate({
-          HtmlTemplate,
-          metadata: metadata ?? this.appConfig.defaultMetadata,
-          pageProps: props ?? {},
-          renderedChildren,
-          isLitManagedHtmlTemplate: this.isLitManagedComponent(HtmlTemplate)
-        });
+      await this.prepareViewDependencies(view, Layout);
+      const pageRender = await this.renderComponentBoundary({
+        component: view,
+        props: props ?? {}
+      });
+      const layoutRender = Layout ? await this.renderComponentBoundary({
+        component: Layout,
+        props: {},
+        children: pageRender.html
+      }) : void 0;
+      const documentRender = await this.renderComponentBoundary({
+        component: HtmlTemplate,
+        props: {
+          metadata,
+          pageProps: props ?? {}
+        },
+        children: layoutRender?.html ?? pageRender.html
       });
-      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
+      this.appendProcessedDependencies(pageRender.assets, layoutRender?.assets, documentRender.assets);
+      const body = await this.finalizeResolvedHtml({
+        html: `${this.DOC_TYPE}${this.normalizeDeclarativeShadowRootMarkup(documentRender.html)}`,
+        partial: false
       });
       return this.createHtmlResponse(body, ctx);
     } catch (error) {

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.js';
-import { IntegrationPlugin, type ComponentBoundaryPolicyInput, type IntegrationPluginConfig } from '@ecopages/core/plugins/integration-plugin';
+import { IntegrationPlugin, 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,17 +18,6 @@ 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,8 +1,5 @@
-import "@lit-labs/ssr/lib/install-global-dom-shim.js";
 import "./console.js";
-import {
-  IntegrationPlugin
-} from "@ecopages/core/plugins/integration-plugin";
+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";
@@ -42,19 +39,6 @@ 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);