evolit 0.1.0-alpha.20 → 0.1.0-alpha.22

package/README.md

@@ -76,6 +76,70 @@ The current runtime is split into a few small layers:
 - `src/scaffold.js`: creates new site projects from templates
 - `src/cli.js`: framework entrypoint
 
+## Client Navigation
+
+Evolit hydrates a small browser router automatically for SSR page documents. It requests a route
+delta, replaces only the changed route segment, and keeps parent layouts mounted when possible.
+Plain `<a>` elements remain valid SSR HTML; same-origin links are progressively intercepted after
+hydration.
+
+Use `useNavigation()` inside a LitSX browser component for imperative navigation and pending UI:
+
+```jsx
+import { useNavigation } from "evolit/navigation";
+
+export default function CollectionControls() {
+  const navigation = useNavigation();
+
+  function changeSort(event) {
+    const searchParams = new URLSearchParams(window.location.search);
+    searchParams.delete("page");
+    searchParams.delete("skip");
+    searchParams.set("sort", event.target.value);
+    navigation.push(navigation.createHref("/explore/home-garden", searchParams));
+  }
+
+  return <select onChange={changeSort} disabled={navigation.status === "pending"}>…</select>;
+}
+```
+
+The hook returns `{ status, url, pendingUrl, error, push, replace, refresh, createHref }`:
+
+- `push(target)` adds a browser-history entry.
+- `replace(target)` updates the current entry, useful for visual-only query state.
+- `refresh()` bypasses the client delta cache for the current URL.
+- `createHref(pathname, searchParams)` creates a relative internal URL. It accepts standard
+  `URLSearchParams`, preserving repeated keys such as `facet=brand&facet=material`.
+
+`createHref` can also be imported directly from `evolit/navigation`; it is browser-free and safe to
+share with server-evaluated route code. `useNavigation()` itself is browser-only and must only run
+from a connected client component.
+
+### Progressive links and forms
+
+Links work without JavaScript. With JavaScript, Evolit intercepts ordinary same-origin left-clicks.
+Set `data-evolit-navigation="false"` on a link to keep native navigation.
+
+Internal `<form method="get">` elements are treated the same way: their successful controls become
+`URLSearchParams` and navigate through a delta. Without JavaScript the browser submits the exact
+same GET form normally. Evolit intentionally does not intercept `POST`, file-upload, external,
+targeted, or opted-out forms.
+
+### Navigation cache and document updates
+
+The browser cache is scoped to browser-history entries, not a global URL map. Going back or forward
+can reuse the delta for that exact entry; opening a new branch after going back discards its known
+forward branch. This avoids an unbounded catalog cache in a long-lived tab.
+
+- `dynamic` routes are never cached in the browser.
+- `revalidate` entries remain reusable only until their route TTL expires.
+- `static` entries remain reusable while their history entry exists in the current tab session.
+
+Each delta also synchronizes route `<title>`, route-specific `<head>` markup, managed styles and
+module preloads, `html`/`body` attributes, scroll position, hash targets, and focus. If a response
+cannot be represented as an Evolit delta —for example a 404 from another adapter— navigation falls
+back to a normal document load.
+
 ## Route Cache Policies
 
 Route modules can export a `routeConfig` object with a `cache` policy:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "evolit",
-  "version": "0.1.0-alpha.20",
+  "version": "0.1.0-alpha.22",
   "description": "A convention-driven application framework for LitSX and web components.",
   "type": "module",
   "packageManager": "yarn@4.10.3",
@@ -20,6 +20,10 @@
   "main": "./src/index.js",
   "exports": {
     ".": "./src/index.js",
+    "./navigation": {
+      "browser": "./src/navigation-client.js",
+      "default": "./src/navigation-server.js"
+    },
     "./server": {
       "browser": "./src/request-context-browser.js",
       "default": "./src/server-api.js"
@@ -29,7 +33,8 @@
     "dev": "node ./src/cli.js dev",
     "build": "node ./src/cli.js build",
     "start": "node ./src/cli.js start",
-    "test": "node --test",
+    "test": "node --test test/*.test.js",
+    "test:browser": "playwright test",
     "typecheck": "litsx-tsc -p jsconfig.json --noEmit",
     "release:check": "yarn test && yarn typecheck && yarn pack --dry-run"
   },
@@ -58,7 +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"],
@@ -247,12 +249,18 @@ export async function buildProject(projectRoot) {
         ...(Array.isArray(result.clientImports) ? result.clientImports : []),
         ...resolveRouteClientImports(routeResult, projectRoot, clientAssets),
       ];
-      const urls = collectTransitiveAssetPreloads(clientImports, clientAssets);
+      const hydratedClientImports = Array.isArray(result.clientImports) ? result.clientImports : [];
+      const urls = hydratedClientImports.length > 0
+        ? [...new Set([
+          ...hydratedClientImports,
+          ...collectTransitiveAssetPreloads(hydratedClientImports, clientAssets),
+        ])]
+        : [];
       const styleUrls = collectTransitiveStyleUrls(clientImports, clientAssets);
 
       return [
-        ...urls.map((href) => `<link rel="modulepreload" href="${href}">`),
-        ...styleUrls.map((href) => `<link rel="stylesheet" href="${href}">`),
+        ...urls.map((href) => `<link rel="modulepreload" href="${href}" data-evolit-route-asset="preload">`),
+        ...styleUrls.map((href) => `<link rel="stylesheet" href="${href}" data-evolit-route-asset="style">`),
       ].join("\n");
     },
     resolveBootstrap({ routeResult, result }) {
@@ -282,7 +290,10 @@ export async function buildProject(projectRoot) {
         normalizeHydrationDataForClient(
           result.hydrationData,
           projectRoot,
-          routeClientImports,
+          [
+            ...routeClientImports,
+            ...resolveHydrationRootClientImports(result.hydrationData, assetResolver),
+          ],
         ),
       );
     },
@@ -331,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

@@ -3,6 +3,7 @@ import { existsSync, realpathSync } from "node:fs";
 import crypto from "node:crypto";
 import path from "node:path";
 import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
 import MagicString from "magic-string";
 import { rollup } from "rollup";
 import { nodeResolve } from "@rollup/plugin-node-resolve";
@@ -24,10 +25,12 @@ const MODULE_SPECIFIER_PATTERN =
   /\b(?:import|export)\s*[^"']*?from\s*["']([^"']+)["']|\bimport\s*["']([^"']+)["']|\bimport\s*\(\s*["']([^"']+)["']\s*\)/g;
 
 const requireFromHere = createRequire(import.meta.url);
+const EVOLIT_NAVIGATION_BROWSER_ENTRY = fileURLToPath(new URL("./navigation-client.js", import.meta.url));
 const SHARED_VENDOR_SPECIFIERS = [
   "@litsx/core",
   "@litsx/core/elements",
   "@litsx/ssr/hydration",
+  "evolit/navigation",
   "lit",
 ];
 const browserSpecifierFilePathCache = new Map();
@@ -516,6 +519,15 @@ export async function buildSharedVendorRuntime(
     const bundle = await rollup({
       input: inputEntries,
       plugins: [
+        {
+          name: "evolit-browser-exports",
+          resolveId(source) {
+            // A consuming application does not normally have an `evolit`
+            // package nested in its node_modules. Resolve Evolit's own
+            // browser-only public entry before node-resolve marks it external.
+            return source === "evolit/navigation" ? EVOLIT_NAVIGATION_BROWSER_ENTRY : null;
+          },
+        },
         nodeResolve({
           browser: true,
           exportConditions: ["browser", "import", "default"],
@@ -1084,6 +1096,7 @@ export function createHydrationBootstrap({
   hydrationData,
   assetResolver,
   hydrationModuleUrl = "@litsx/ssr/hydration",
+  navigationModuleUrl = null,
 }) {
   const normalizedHydrationData = normalizeHydrationDataForClient(hydrationData);
   const rootModuleUrls = [...new Set([
@@ -1113,6 +1126,7 @@ export function createHydrationBootstrap({
 
   const source = `
 import { hydratePage, registerHydrationModules } from ${JSON.stringify(hydrationModuleUrl)};
+${navigationModuleUrl ? `import { getNavigation } from ${JSON.stringify(navigationModuleUrl)};` : ""}
 
 await hydratePage({
   clientImports: ${JSON.stringify(clientImports)},
@@ -1120,6 +1134,7 @@ await hydratePage({
 ${moduleLoaders}
   ])
 });
+${navigationModuleUrl ? "getNavigation();" : ""}
 `;
 
   return escapeInlineScriptText(source);
@@ -2017,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,
@@ -32,6 +33,8 @@ import {
   resolveResponseCacheRuntime,
 } 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"],
@@ -232,6 +235,11 @@ export async function createRequestRenderer({
     mode,
     "@litsx/ssr/hydration",
   );
+  let currentNavigationModuleUrl = await resolveSharedVendorModuleUrl(
+    projectRoot,
+    mode,
+    "evolit/navigation",
+  );
   const devBundledEntries = new Set();
   const devPreparedClientModules = new Set();
   const devClientModuleDependencies = new Map();
@@ -244,6 +252,7 @@ export async function createRequestRenderer({
     selectivelyInvalidatedClientEntries: 0,
   };
   const usesFrameworkRouteResolver = !routeResolver;
+  let sharedSegmentRenderCache = null;
 
   function enqueueDevClientAssetWork(work) {
     const nextWork = devClientAssetWork.then(work, work);
@@ -261,12 +270,18 @@ export async function createRequestRenderer({
     return path.resolve(projectRoot, clientModule);
   }
   async function createFrameworkRouteResolver() {
-    return createRouteResolver(projectRoot, mode, {
+    const resolver = await createRouteResolver(projectRoot, mode, {
       onDevelopmentEvent,
+      segmentRenderCache: sharedSegmentRenderCache,
       getStaticAssetPublicUrls() {
         return createStaticAssetPublicUrlMap(currentAssetManifest);
       },
+      assetResolver(moduleId) {
+        return currentAssetResolver(moduleId);
+      },
     });
+    sharedSegmentRenderCache ??= resolver.segmentRenderCache;
+    return resolver;
   }
   let effectiveRouteResolver = routeResolver ?? await createFrameworkRouteResolver();
   const ssrAdapter = createSsrAdapter({
@@ -278,8 +293,12 @@ export async function createRequestRenderer({
         ...(Array.isArray(result.clientImports) ? result.clientImports : []),
         ...resolveRouteClientImports(routeResult, projectRoot, currentAssetManifest),
       ];
-      const urls = currentAssetManifest
-        ? collectTransitiveAssetPreloads(clientImports, currentAssetManifest)
+      const hydratedClientImports = Array.isArray(result.clientImports) ? result.clientImports : [];
+      const urls = currentAssetManifest && hydratedClientImports.length > 0
+        ? [...new Set([
+          ...hydratedClientImports,
+          ...collectTransitiveAssetPreloads(hydratedClientImports, currentAssetManifest),
+        ])]
         : [];
       const styleUrls = currentAssetManifest
         ? collectTransitiveStyleUrls(clientImports, currentAssetManifest)
@@ -289,8 +308,8 @@ export async function createRequestRenderer({
       }
 
       return [
-        ...urls.map((href) => `<link rel="modulepreload" href="${href}">`),
-        ...styleUrls.map((href) => `<link rel="stylesheet" href="${href}">`),
+        ...urls.map((href) => `<link rel="modulepreload" href="${href}" data-evolit-route-asset="preload">`),
+        ...styleUrls.map((href) => `<link rel="stylesheet" href="${href}" data-evolit-route-asset="style">`),
       ].join("\n");
     },
     resolveBootstrap({ routeResult, result }) {
@@ -309,6 +328,7 @@ export async function createRequestRenderer({
           return currentAssetResolver(moduleId);
         },
         hydrationModuleUrl: currentHydrationModuleUrl,
+        navigationModuleUrl: currentNavigationModuleUrl,
       });
     },
     transformDocument({ routeResult, result, document }) {
@@ -322,7 +342,13 @@ export async function createRequestRenderer({
         normalizeHydrationDataForClient(
           result.hydrationData,
           projectRoot,
-          routeClientImports,
+          [
+            ...routeClientImports,
+            ...resolveHydrationRootClientImports(
+              result.hydrationData,
+              currentAssetResolver,
+            ),
+          ],
         ),
       );
     },
@@ -380,6 +406,8 @@ export async function createRequestRenderer({
         });
 
         if (usesFrameworkRouteResolver) {
+          const segmentEntryCount = effectiveRouteResolver.invalidateSegmentCache?.(changedPaths) ?? 0;
+          reportDevelopmentEvent({ type: "segment-cache-invalidated", entryCount: segmentEntryCount });
           effectiveRouteResolver = await createFrameworkRouteResolver();
         }
       });
@@ -475,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;
@@ -536,6 +569,16 @@ export async function createDeploymentRuntime({
   const runtimeState = {
     assetManifest: mode === "development" ? null : normalizeClientAssetManifest(assetManifest),
   };
+
+  function formatResponseForRequest(request, response) {
+    const representation = request.headers.get("accept")?.includes("application/vnd.evolit.navigation+json")
+      ? createNavigationResponseFromDocument(response)
+      : response;
+    // The same URL has an HTML document representation and a navigation
+    // delta representation. Tell intermediary HTTP caches that Accept selects
+    // between them.
+    return addNavigationVaryHeader(representation);
+  }
   const assets = createPublicAssetOrigin({
     projectRoot,
     mode,
@@ -579,7 +622,7 @@ export async function createDeploymentRuntime({
       const cachedResponse = await renderer.responseCacheController.read(request, routePolicyResult);
       if (cachedResponse) {
         if (cachedResponse.fresh) {
-          return cachedResponse.response;
+          return formatResponseForRequest(request, cachedResponse.response);
         }
 
         if (
@@ -603,12 +646,15 @@ export async function createDeploymentRuntime({
           revalidationTasks.set(cachedResponse.cacheKey, revalidationTask);
         }
 
-        return cachedResponse.response;
+        return formatResponseForRequest(request, cachedResponse.response);
       }
 
       const { routeResult, response } = await renderer.renderRoute(request, routePolicyResult);
       runtimeState.assetManifest = normalizeClientAssetManifest(renderer.assetManifest);
-      return renderer.responseCacheController.write(request, routeResult, response);
+      return formatResponseForRequest(
+        request,
+        await renderer.responseCacheController.write(request, routeResult, response),
+      );
     },
     async close() {
       const revalidationTasks = this.revalidationTasks;
@@ -618,3 +664,16 @@ export async function createDeploymentRuntime({
     },
   };
 }
+
+function addNavigationVaryHeader(response) {
+  if (!response?.headers) return response;
+  const fields = String(response.headers.vary ?? "")
+    .split(",")
+    .map((field) => field.trim())
+    .filter(Boolean);
+  if (!fields.some((field) => field.toLowerCase() === "accept")) fields.push("accept");
+  return {
+    ...response,
+    headers: { ...response.headers, vary: fields.join(", ") },
+  };
+}

package/src/development-events.js

@@ -37,6 +37,15 @@ export function createDevelopmentEventReporter() {
       case "client-assets-cache-hit":
         console.log(`${terminal.cyan("[evolit]")} ${terminal.blue("●")} Client assets served from cache.`);
         break;
+      case "segment-cache-hit":
+        console.log(`${terminal.cyan("[evolit]")} ${terminal.blue("●")} Reused route segment ${terminal.dim(event.modulePath)}.`);
+        break;
+      case "segment-cache-miss":
+        console.log(`${terminal.cyan("[evolit]")} ${terminal.magenta("○")} Rendering route segment ${terminal.dim(event.modulePath)} ${terminal.dim(`(${event.reason})`)}.`);
+        break;
+      case "segment-cache-invalidated":
+        console.log(`${terminal.cyan("[evolit]")} ${terminal.yellow("△")} Invalidated ${event.entryCount} cached route segments.`);
+        break;
       case "invalidated":
         console.log(
           `${terminal.cyan("[evolit]")} ${terminal.yellow("△")} Source change detected${event.changedPathCount == null ? "" : ` (${event.changedPathCount} files)`}; invalidated ${event.affectedClientEntryCount} client entries.`,