evolit 0.1.0-alpha.2 → 0.1.0-alpha.21

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:
@@ -104,12 +168,18 @@ export const routeConfig = {
 - `static`: prerender in `build` and serve from the response cache in `start`
 - `revalidate`: cache the HTML response for `N` seconds and regenerate on expiry
 
+Pages without `routeConfig.cache` default to `{ revalidate: 60 }`. This caches a normal SSR
+render by pathname and query string while keeping content fresh without requiring a cache
+declaration on every catalog or CMS page. Declare `cache: "static"` for fully static pages or
+`cache: "dynamic"` when a page must always render per request.
+
 The same semantics work in local development and in production runtimes. Only the backing cache
 store changes.
 
-The default cache key includes the pathname and query string. Reading the `request` prop, request
-headers, cookies, or `requestUrl()` makes the completed render dynamic; it is never stored in the
-HTML response cache. `routeConfig.cache` is the sole authority for HTML caching; setting a
+The default cache key includes the pathname and query string, so `params` and `searchParams` are
+cacheable by URL. Reading the `request` prop, request headers, cookies, or `requestUrl()` makes
+the completed render dynamic; it is never stored in the HTML response cache. `routeConfig.cache`
+is the sole authority for HTML caching; setting a
 `Cache-Control` response header does not alter that policy.
 
 ## Request APIs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "evolit",
-  "version": "0.1.0-alpha.2",
+  "version": "0.1.0-alpha.21",
   "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"
   },
@@ -47,17 +52,19 @@
   },
   "dependencies": {
     "@jridgewell/remapping": "^2.3.5",
-    "@litsx/compiler": "0.9.5-canary-feat-ssr-20260726130435",
-    "@litsx/core": "0.17.0-canary-feat-ssr-20260726130435",
-    "@litsx/ssr": "0.2.0-canary-feat-ssr-20260726130435",
+    "@litsx/compiler": "0.9.5-canary-feat-ssr-20260726184312",
+    "@litsx/core": "0.17.0-canary-feat-ssr-20260726184312",
+    "@litsx/ssr": "0.2.0-canary-feat-ssr-20260726184312",
     "@litsx/typescript": "^0.9.0",
     "@rollup/plugin-node-resolve": "^16.0.3",
     "lit": "^3.3.3",
     "magic-string": "^1.1.0",
     "rollup": "^4.46.1",
-    "typescript": "^6.0.0"
+    "typescript": "^6.0.0",
+    "ws": "^8.18.3"
   },
   "devDependencies": {
+    "@playwright/test": "^1.62.0",
     "vite": "^8.1.5"
   }
 }

package/src/build.js

@@ -15,6 +15,7 @@ import {
   emitBundledClientAssets,
   emitHashedClientAssets,
   normalizeHydrationDataForClient,
+  resolveRouteClientImports,
   resolveSharedVendorModuleUrl,
   rewriteHydrationDataScript,
   rewriteServerAssetPlaceholders,
@@ -241,27 +242,54 @@ export async function buildProject(projectRoot) {
   );
   const ssrAdapter = createSsrAdapter({
     assetResolver,
-    async resolveAdditionalHead({ result }) {
-      const clientImports = Array.isArray(result.clientImports) ? result.clientImports : [];
-      const urls = collectTransitiveAssetPreloads(clientImports, clientAssets);
+    async resolveAdditionalHead({ routeResult, result }) {
+      const clientImports = [
+        ...(Array.isArray(result.clientImports) ? result.clientImports : []),
+        ...resolveRouteClientImports(routeResult, projectRoot, 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({ result }) {
+    resolveBootstrap({ routeResult, result }) {
+      const routeClientImports = resolveRouteClientImports(
+        routeResult,
+        projectRoot,
+        clientAssets,
+      );
       return createHydrationBootstrap({
-        hydrationData: normalizeHydrationDataForClient(result.hydrationData, projectRoot),
+        hydrationData: normalizeHydrationDataForClient(
+          result.hydrationData,
+          projectRoot,
+          routeClientImports,
+        ),
         assetResolver,
         hydrationModuleUrl,
       });
     },
-    transformDocument({ result, document }) {
+    transformDocument({ routeResult, result, document }) {
+      const routeClientImports = resolveRouteClientImports(
+        routeResult,
+        projectRoot,
+        clientAssets,
+      );
       return rewriteHydrationDataScript(
         document,
-        normalizeHydrationDataForClient(result.hydrationData, projectRoot),
+        normalizeHydrationDataForClient(
+          result.hydrationData,
+          projectRoot,
+          routeClientImports,
+        ),
       );
     },
   });

package/src/cli.js

@@ -3,6 +3,9 @@
 import path from "node:path";
 import process from "node:process";
 import { scaffoldSite } from "./scaffold.js";
+import { createDevelopmentEventReporter } from "./development-events.js";
+
+const reportEvent = createDevelopmentEventReporter();
 
 function parseArguments(argv) {
   const [command, ...rest] = argv;
@@ -24,9 +27,7 @@ function parseArguments(argv) {
 }
 
 function printUsage() {
-  console.log("Usage: evolit <directory>");
-  console.log("       evolit init <directory>");
-  console.log("       evolit <dev|build|start> [--port 3000]");
+  reportEvent({ type: "usage" });
 }
 
 async function createSite(projectRoot, targetDirectory) {
@@ -35,7 +36,7 @@ async function createSite(projectRoot, targetDirectory) {
   }
 
   const createdDirectory = await scaffoldSite(path.resolve(projectRoot, targetDirectory));
-  console.log(`Created evolit site: ${createdDirectory}`);
+  reportEvent({ type: "site-created", directory: createdDirectory });
 }
 
 async function run() {
@@ -55,23 +56,29 @@ async function run() {
   if (command === "build") {
     const { buildProject } = await import("./build.js");
     const manifestPath = await buildProject(projectRoot);
-    console.log(`Built evolit app: ${path.relative(projectRoot, manifestPath)}`);
+    reportEvent({
+      type: "build-ready",
+      manifestPath: path.relative(projectRoot, manifestPath),
+    });
     return;
   }
 
   if (command === "start") {
     const { createStartServer } = await import("./server.js");
+    reportEvent({ type: "server-starting", mode: "start" });
     const server = await createStartServer(projectRoot, options);
     await server.listen();
-    console.log(`evolit start listening on http://localhost:${server.port}`);
+    reportEvent({ type: "server-ready", port: server.port });
     return;
   }
 
   if (command === "dev") {
     const { createDevServer } = await import("./server.js");
-    const server = await createDevServer(projectRoot, options);
+    const server = await createDevServer(projectRoot, {
+      ...options,
+      onDevelopmentEvent: reportEvent,
+    });
     await server.listen();
-    console.log(`evolit dev listening on http://localhost:${server.port}`);
     return;
   }
 
@@ -79,6 +86,6 @@ async function run() {
 }
 
 run().catch((error) => {
-  console.error(error instanceof Error ? error.stack ?? error.message : String(error));
+  reportEvent({ type: "fatal-error", error });
   process.exitCode = 1;
 });