evolit 0.1.0-alpha.21 → 0.1.0-alpha.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "evolit",
-  "version": "0.1.0-alpha.21",
+  "version": "0.1.0-alpha.22",
   "description": "A convention-driven application framework for LitSX and web components.",
   "type": "module",
   "packageManager": "yarn@4.10.3",
@@ -63,8 +63,17 @@
     "typescript": "^6.0.0",
     "ws": "^8.18.3"
   },
+  "peerDependencies": {
+    "@litsx/urql": "^0.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@litsx/urql": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@playwright/test": "^1.62.0",
+    "@webcomponents/scoped-custom-element-registry": "^0.0.10",
     "vite": "^8.1.5"
   }
 }

package/src/build.js

@@ -15,6 +15,7 @@ import {
   emitBundledClientAssets,
   emitHashedClientAssets,
   normalizeHydrationDataForClient,
+  resolveHydrationRootClientImports,
   resolveRouteClientImports,
   resolveSharedVendorModuleUrl,
   rewriteHydrationDataScript,
@@ -39,6 +40,7 @@ import {
 import { serializeRouteCachePolicy } from "./route-config.js";
 import { createSsrAdapter, renderRouteTreeWithAdapter } from "./ssr-adapter.js";
 import { ensureDirectory, writeJson } from "./fs-utils.js";
+import { appendSsrUrqlData, runWithOptionalSsrUrqlScope } from "./urql-ssr.js";
 
 const CONTENT_TYPE_BY_EXTENSION = new Map([
   [".css", "text/css; charset=utf-8"],
@@ -288,7 +290,10 @@ export async function buildProject(projectRoot) {
         normalizeHydrationDataForClient(
           result.hydrationData,
           projectRoot,
-          routeClientImports,
+          [
+            ...routeClientImports,
+            ...resolveHydrationRootClientImports(result.hydrationData, assetResolver),
+          ],
         ),
       );
     },
@@ -337,12 +342,23 @@ export async function buildProject(projectRoot) {
       seenPrerenderTargets.add(targetPathname);
 
       const targetRequest = new Request(`http://evolit.local${targetPathname}`);
-      const routeResult = await routeResolver.resolveRequest(targetRequest);
-      if (routeResult.type !== "route" || routeResult.cachePolicy.mode === "dynamic") {
+      const { routeResult, response } = await runWithOptionalSsrUrqlScope(async (urqlAdapter) => {
+        const resolvedRouteResult = await routeResolver.resolveRequest(targetRequest);
+        if (resolvedRouteResult.type !== "route" || resolvedRouteResult.cachePolicy.mode === "dynamic") {
+          return { routeResult: resolvedRouteResult, response: null };
+        }
+
+        const renderedResponse = await renderRouteTreeWithAdapter(resolvedRouteResult, ssrAdapter);
+        return {
+          routeResult: resolvedRouteResult,
+          response: urqlAdapter
+            ? appendSsrUrqlData(renderedResponse, await urqlAdapter.getUrqlSsrData())
+            : renderedResponse,
+        };
+      });
+      if (!response) {
         continue;
       }
-
-      const response = await renderRouteTreeWithAdapter(routeResult, ssrAdapter);
       if (response.status !== 200) {
         continue;
       }

package/src/client-assets.js

@@ -2032,6 +2032,25 @@ export function resolveRouteClientImports(routeResult, projectRoot, assetManifes
   }).filter((publicUrl) => typeof publicUrl === "string"))];
 }
 
+/**
+ * Resolve the client modules which define the hydrated custom-element roots.
+ *
+ * Route entry modules are not required to re-export their LitSX components.
+ * The document bootstrap has always loaded these root modules independently;
+ * navigation deltas need the same information in their hydration payload.
+ */
+export function resolveHydrationRootClientImports(hydrationData, assetResolver) {
+  if (!hydrationData || typeof hydrationData !== "object" || typeof assetResolver !== "function") {
+    return [];
+  }
+
+  return [...new Set(
+    (Array.isArray(hydrationData.roots) ? hydrationData.roots : [])
+      .map((root) => assetResolver(root?.moduleId))
+      .filter((publicUrl) => typeof publicUrl === "string" && publicUrl.length > 0),
+  )];
+}
+
 export function collectTransitiveStyleUrls(publicUrls, assetManifest) {
   const normalizedManifest = normalizeClientAssetManifest(assetManifest);
   if (!normalizedManifest) {

package/src/deployment-runtime.js

@@ -17,6 +17,7 @@ import {
   normalizeHydrationDataForClient,
   normalizeClientAssetManifest,
   resetDevelopmentAssetCaches,
+  resolveHydrationRootClientImports,
   resolveRouteClientImports,
   resolveSharedVendorModuleUrl,
   resolveBrowserPackageAssetFilePath,
@@ -33,6 +34,7 @@ import {
 } from "./response-cache.js";
 import { createSsrAdapter, renderRouteTreeWithAdapter } from "./ssr-adapter.js";
 import { createNavigationResponseFromDocument } from "./route-segments.js";
+import { appendSsrUrqlData, runWithOptionalSsrUrqlScope } from "./urql-ssr.js";
 const CONTENT_TYPE_BY_EXTENSION = new Map([
   [".css", "text/css; charset=utf-8"],
   [".svg", "image/svg+xml"],
@@ -340,7 +342,13 @@ export async function createRequestRenderer({
         normalizeHydrationDataForClient(
           result.hydrationData,
           projectRoot,
-          routeClientImports,
+          [
+            ...routeClientImports,
+            ...resolveHydrationRootClientImports(
+              result.hydrationData,
+              currentAssetResolver,
+            ),
+          ],
         ),
       );
     },
@@ -495,22 +503,27 @@ export async function createRequestRenderer({
       return effectiveRouteResolver.resolveRoutePolicy(request);
     },
     async renderRoute(request, routePolicyResult = null) {
-      const shouldPrepareBeforeResolve = mode === "development" && !currentAssetManifest;
-      let resolvedRoutePolicyResult = routePolicyResult;
-      if (shouldPrepareBeforeResolve) {
-        resolvedRoutePolicyResult ??= await effectiveRouteResolver.resolveRoutePolicy(request);
-        await this.prepareRouteClientArtifacts(resolvedRoutePolicyResult);
-      }
+      return runWithOptionalSsrUrqlScope(async (urqlAdapter) => {
+        const shouldPrepareBeforeResolve = mode === "development" && !currentAssetManifest;
+        let resolvedRoutePolicyResult = routePolicyResult;
+        if (shouldPrepareBeforeResolve) {
+          resolvedRoutePolicyResult ??= await effectiveRouteResolver.resolveRoutePolicy(request);
+          await this.prepareRouteClientArtifacts(resolvedRoutePolicyResult);
+        }
 
-      const routeResult = await effectiveRouteResolver.resolveRequest(request, resolvedRoutePolicyResult);
-      if (!shouldPrepareBeforeResolve || routeResult.boundaryModule) {
-        await this.prepareRouteClientArtifacts(routeResult);
-      }
-      const response = await renderRouteTreeWithAdapter(routeResult, ssrAdapter);
-      return {
-        routeResult,
-        response,
-      };
+        const routeResult = await effectiveRouteResolver.resolveRequest(request, resolvedRoutePolicyResult);
+        if (!shouldPrepareBeforeResolve || routeResult.boundaryModule) {
+          await this.prepareRouteClientArtifacts(routeResult);
+        }
+        const renderedResponse = await renderRouteTreeWithAdapter(routeResult, ssrAdapter);
+        const response = urqlAdapter
+          ? appendSsrUrqlData(renderedResponse, await urqlAdapter.getUrqlSsrData())
+          : renderedResponse;
+        return {
+          routeResult,
+          response,
+        };
+      });
     },
     get assetManifest() {
       return currentAssetManifest;

package/src/navigation-client.js

@@ -1,5 +1,9 @@
 import { useHost, useOnConnect, useState } from "@litsx/core";
-import { hydrateRoot, registerHydrationModules } from "@litsx/ssr/hydration";
+import {
+  applyHydrationPayload,
+  hydrateRoot,
+  registerHydrationModules,
+} from "@litsx/ssr/hydration";
 import { createHref } from "./navigation-url.js";
 
 export { createHref } from "./navigation-url.js";
@@ -162,11 +166,21 @@ async function applyRouteDelta(delta, documentRef = document, signal) {
   const nextSegments = delta.route?.segments ?? [];
   const currentSegments = current?.segments ?? [];
   let index = nextSegments.findIndex((segment, offset) => segment.id !== currentSegments[offset]?.id);
+  if (index < 0) {
+    index = nextSegments.findIndex(
+      (segment, offset) => segment.inputKey !== currentSegments[offset]?.inputKey,
+    );
+  }
   if (index < 0) index = Math.max(0, nextSegments.length - 1);
   const next = nextSegments[index];
   const previous = currentSegments[index] ?? currentSegments.at(-1);
   if (!next || !previous) return;
   const targets = findMarkers(documentRef, previous.id);
+  // A projection is positional: reusing projection zero for a second target
+  // duplicates DOM (and hydration roots) when a layout changes its children
+  // cardinality. A full document navigation is the only safe recovery when
+  // the live tree and delta disagree.
+  if (targets.length !== next.projections.length) return false;
   await syncRouteHeadAssets(delta.headAssets, documentRef);
   throwIfAborted(signal);
   syncRouteHeadMarkup(delta.head, documentRef);
@@ -184,6 +198,14 @@ async function applyRouteDelta(delta, documentRef = document, signal) {
       root,
       element: findHydrationElement(fragment, root.id),
     })).filter((entry) => entry.element);
+    // A custom element already defined by an earlier route is upgraded as
+    // soon as this fragment is connected. Apply its SSR data while it is
+    // still detached, otherwise Lit starts an update against its declarative
+    // shadow root without the properties used to render it on the server.
+    applyHydrationPayload(
+      roots.map(({ root, element }) => ({ ...root, element })),
+      delta.hydrationData,
+    );
     const range = documentRef.createRange();
     range.setStartAfter(target.start);
     range.setEndBefore(target.end);
@@ -201,13 +223,14 @@ async function applyRouteDelta(delta, documentRef = document, signal) {
     await Promise.all((delta.hydrationData?.clientImports ?? []).map((specifier) => import(specifier))),
   );
   for (const { root, element } of insertedRoots) {
-      throwIfAborted(signal);
-      await hydrateRoot(element, {
-        rootId: root.id,
-        hydrationData: delta.hydrationData,
-        clientImports: delta.hydrationData.clientImports,
-      });
+    throwIfAborted(signal);
+    await hydrateRoot(element, {
+      rootId: root.id,
+      hydrationData: delta.hydrationData,
+      clientImports: delta.hydrationData.clientImports,
+    });
   }
+  return true;
 }
 
 function toHref(target, location) {
@@ -440,7 +463,11 @@ export function createBrowserNavigation(options = {}) {
         })();
       if (!delta || !isCurrent()) return null;
       if (delta.type === "redirect") return navigate(delta.location, "replace", false);
-      await applyDelta(delta, { signal: navigationController.signal });
+      const applied = await applyDelta(delta, { signal: navigationController.signal });
+      if (applied === false) {
+        navigateDocument(href, mode);
+        return null;
+      }
       if (!isCurrent()) return null;
       const canonicalHref = toHref(delta.url ?? href, windowRef.location);
       if (!fromPopState) {

package/src/render.js

@@ -263,6 +263,18 @@ function createSegmentCacheKey(segment, idPrefix, profile, params, searchParams)
   });
 }
 
+function createSegmentInputKey(profile, params, searchParams) {
+  const select = (values) => Object.fromEntries(
+    (profile.all ? Object.keys(values) : profile.keys)
+      .sort()
+      .map((key) => [key, values[key]]),
+  );
+  return JSON.stringify({
+    params: select(params),
+    searchParams: select(searchParams),
+  });
+}
+
 function getSegmentCacheExpiry(cachePolicy) {
   if (cachePolicy?.mode === "static") return Number.POSITIVE_INFINITY;
   if (cachePolicy?.mode === "revalidate" && Number.isFinite(cachePolicy.ttlSeconds)) {
@@ -296,6 +308,9 @@ function createSegmentRenderCache(projectRoot, onDevelopmentEvent) {
       onDevelopmentEvent?.({ type: "segment-cache-hit", modulePath: segment.modulePath });
       return entry.result;
     },
+    getProfile(segment) {
+      return profiles.get(segment.modulePath) ?? null;
+    },
     set(segment, idPrefix, params, searchParams, profile, result, cachePolicy) {
       const expiresAt = getSegmentCacheExpiry(cachePolicy);
       if (expiresAt == null) return;
@@ -379,6 +394,7 @@ async function renderSegmentedComponentTree(
     }
 
     const childrenMarker = createSegmentChildrenMarker(segment);
+    let profile = options.segmentCache?.getProfile(segment) ?? null;
     let layoutResult = options.segmentCache?.get(
       segment,
       idPrefix,
@@ -399,24 +415,32 @@ async function renderSegmentedComponentTree(
         assetResolver: options.assetResolver,
         context: { idPrefix },
       });
+      profile = {
+        all: trackedParams.profile().all || trackedSearchParams.profile().all,
+        keys: [...new Set([
+          ...trackedParams.profile().keys,
+          ...trackedSearchParams.profile().keys,
+        ])].sort(),
+      };
       if (!didUseDynamicRequestData && !requestContext.didUseDynamicRequestData) {
         options.segmentCache?.set(
           segment,
           idPrefix,
           requestContext.params,
           requestContext.searchParams,
-          {
-            all: trackedParams.profile().all || trackedSearchParams.profile().all,
-            keys: [...new Set([
-              ...trackedParams.profile().keys,
-              ...trackedSearchParams.profile().keys,
-            ])].sort(),
-          },
+          profile,
           layoutResult,
           options.cachePolicy,
         );
       }
     }
+    if (profile) {
+      segment.inputKey = createSegmentInputKey(
+        profile,
+        requestContext.params,
+        requestContext.searchParams,
+      );
+    }
     results.push(layoutResult);
     const projectionCount = layoutResult.html.split(childrenMarker).length - 1;
     if (projectionCount === 0) return null;

package/src/route-segments.js

@@ -81,11 +81,12 @@ export function createRouteSegmentPayload(routeResult) {
           : {}),
       }
       : null,
-    segments: segments.map(({ id, kind, depth, modulePath }) => ({
+    segments: segments.map(({ id, kind, depth, modulePath, inputKey }) => ({
       id,
       kind,
       depth,
       modulePath,
+      ...(typeof inputKey === "string" ? { inputKey } : {}),
     })),
   };
 }

package/src/urql-ssr.js

@@ -0,0 +1,60 @@
+let adapterPromise = null;
+
+function isMissingUrqlAdapter(error) {
+  return error?.code === "ERR_MODULE_NOT_FOUND"
+    && String(error.message).includes("@litsx/urql");
+}
+
+async function loadSsrUrqlAdapter() {
+  try {
+    return await import("@litsx/urql");
+  } catch (error) {
+    if (isMissingUrqlAdapter(error)) {
+      return null;
+    }
+    throw error;
+  }
+}
+
+export async function getSsrUrqlAdapter() {
+  adapterPromise ??= loadSsrUrqlAdapter();
+  return adapterPromise;
+}
+
+/**
+ * Opens the optional @litsx/urql request scope around one complete SSR render.
+ * Evolit owns only lifecycle here; client creation and URQL configuration stay
+ * entirely in the application and @litsx/urql.
+ */
+export async function runWithOptionalSsrUrqlScope(callback, options = {}) {
+  const adapter = Object.hasOwn(options, "adapter")
+    ? options.adapter
+    : await getSsrUrqlAdapter();
+  if (!adapter) {
+    return callback(null);
+  }
+
+  return adapter.runWithUrqlScope(() => callback(adapter));
+}
+
+function escapeJsonForHtml(value) {
+  return JSON.stringify(value)
+    .replaceAll("<", "\\u003C")
+    .replaceAll(">", "\\u003E")
+    .replaceAll("&", "\\u0026");
+}
+
+/** Appends optional, application-defined URQL SSR data to an HTML response. */
+export function appendSsrUrqlData(response, data) {
+  if (data === undefined || typeof response?.body !== "string") {
+    return response;
+  }
+
+  const script = `<script type="application/json" id="__LITSX_URQL_DATA__">${escapeJsonForHtml(data)}</script>`;
+  return {
+    ...response,
+    body: response.body.includes("</body>")
+      ? response.body.replace("</body>", `${script}\n</body>`)
+      : `${response.body}${script}`,
+  };
+}