evolit 0.1.8 → 0.2.1

package/README.md

@@ -20,8 +20,8 @@ It focuses on the core contract that matters first:
 - route modules live in `app/**/page.*`
 - layout modules live in `app/**/layout.*`
 - page and layout modules export a default async function
-- pages receive `{ params, searchParams, request }`
-- layouts receive `{ children, params, searchParams, request }`
+- pages receive `{ params, searchParams, navigationContext, request }`
+- layouts receive `{ children, params, searchParams, navigationContext, request }`
 - SSR document rendering is delegated to `@litsx/ssr`
 
 Supported authored module extensions:
@@ -162,9 +162,10 @@ from a connected client component.
 
 Navigation context is intended for compact UI state that must survive back/forward navigation but
 does not belong in the public URL. It must be a JSON-safe object and is limited to 8 KiB after UTF-8
-serialization. Evolit includes it in browser, response, and segment cache identity so the same URL
-cannot reuse markup rendered for a different context. Invalid context is rejected at the client
-boundary; malformed context received by the server is ignored.
+serialization. Evolit includes it in browser and response-cache identity. Segment caching and delta
+identity track only the top-level context keys each layout or page reads, so unrelated context
+changes preserve mounted layouts while consumers still update. Invalid context is rejected at the
+client boundary; malformed context received by the server is ignored.
 
 Client components can also read the active route state with browser-only hooks:
 
@@ -266,20 +267,24 @@ Server pages and layouts can access the active Web Request context through `evol
 ```js
 import {
   cookies,
+  getRouteState,
   headers,
   notFound,
+  permanentRedirect,
   redirect,
   requestUrl,
   responseHeaders,
 } from "evolit/server";
 
 export default async function AccountPage() {
+  const { params, searchParams, navigationContext } = getRouteState();
+
   if (!cookies().has("session")) {
     redirect("/sign-in");
   }
 
   responseHeaders().set("x-account-page", "1");
-  return `<p>${headers().get("user-agent")} ${requestUrl().pathname}</p>`;
+  return `<p>${headers().get("user-agent")} ${requestUrl().pathname} ${params.account ?? ""}</p>`;
 }
 ```
 
@@ -288,6 +293,14 @@ headers. `redirect()` and `permanentRedirect()` end rendering with `307` and `30
 `notFound()` renders a `404`. Reading headers, cookies, or the request URL makes the completed
 render dynamic, so it is not stored by the route response cache.
 
+`getRouteState()` is the request-scoped server counterpart for reading the active route from nested
+server components and helpers that do not receive route props directly. It returns the current
+`{ url, params, searchParams, navigationContext }` as a read-only snapshot. It deliberately has no
+`push`, `replace`, `refresh`, pending state, or history mutation methods: those belong to the browser
+`useNavigation()` API. Redirects and `notFound()` remain separate server control-flow functions.
+Reading `getRouteState().url` has the same dynamic-rendering semantics as `requestUrl()`; reading
+`params` and `searchParams` participates in the normal segment-cache key tracking.
+
 ## Extensions
 
 Optional integrations are configured explicitly in `evolit.config.js`. Core only coordinates their

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "evolit",
-  "version": "0.1.8",
+  "version": "0.2.1",
   "description": "A convention-driven application framework for LitSX and web components.",
   "type": "module",
   "packageManager": "yarn@4.10.3",

package/src/navigation-client.js

@@ -194,6 +194,79 @@ function syncDocumentState(nextState, documentRef) {
   if (script) script.textContent = JSON.stringify(nextState);
 }
 
+function readElementAttributes(element) {
+  return Object.fromEntries([...element.attributes].map((attribute) => [
+    attribute.name,
+    attribute.value,
+  ]));
+}
+
+function isRootBodyProjection(segment, projection) {
+  return segment?.kind === "layout"
+    && segment?.depth === 0
+    && typeof projection?.html === "string"
+    && /<body(?:\s|>)/iu.test(projection.html);
+}
+
+function parseRootBodyProjection(projectionHtml, documentRef) {
+  const DOMParserConstructor = documentRef.defaultView?.DOMParser ?? globalThis.DOMParser;
+  if (typeof DOMParserConstructor !== "function") return null;
+  return new DOMParserConstructor().parseFromString(projectionHtml, "text/html").body;
+}
+
+function collectRouteRuntimeScripts(root) {
+  const scripts = [...root.querySelectorAll("script")];
+  return scripts.filter((script) =>
+    script.id === "__EVOLIT_ROUTE__"
+    || script.id === "__EVOLIT_DOCUMENT__"
+    || script.id === "__LITSX_HYDRATION__"
+    || script.hasAttribute("data-evolit-live-reload")
+    || (script.type === "module" && (
+      script.textContent?.includes("getNavigation")
+      || script.textContent?.includes("hydratePage")
+    )),
+  );
+}
+
+function replaceRootBodyProjection({
+  bodyProjection,
+  delta,
+  documentRef,
+  fragment,
+  target,
+}) {
+  const body = documentRef.body;
+  if (!body || !bodyProjection) return false;
+
+  const authoredAttributes = readElementAttributes(bodyProjection);
+  const managedAttributes = normalizeManagedAttributes(delta.document?.bodyAttributes);
+  syncElementAttributes(
+    body,
+    readElementAttributes(body),
+    { ...authoredAttributes, ...managedAttributes },
+  );
+
+  const runtimeScripts = collectRouteRuntimeScripts(documentRef);
+  body.replaceChildren(target.start, fragment, target.end, ...runtimeScripts);
+
+  // HTML parsing can leave nodes from an authored root <body> beside the live
+  // body. Once the stable body owns the committed projection and runtime
+  // scripts, discard only those invalid element siblings.
+  for (const element of [...documentRef.documentElement.children]) {
+    if (element !== documentRef.head && element !== body) element.remove();
+  }
+  return true;
+}
+
+function syncRouteStateScripts(delta, documentRef) {
+  const routeScript = documentRef.getElementById("__EVOLIT_ROUTE__");
+  if (routeScript) routeScript.textContent = JSON.stringify(delta.route);
+  const hydrationScript = documentRef.getElementById("__LITSX_HYDRATION__");
+  if (hydrationScript && delta.hydrationData) {
+    hydrationScript.textContent = JSON.stringify(delta.hydrationData);
+  }
+}
+
 function versionClientImport(specifier, version) {
   if (!version || typeof specifier !== "string") return specifier;
   const url = new URL(specifier, globalThis.location?.href ?? "http://evolit.local/");
@@ -260,9 +333,18 @@ async function applyRouteDelta(delta, documentRef = document, signal, options =
     throwIfAborted(signal);
     const projection = next.projections[offset] ?? next.projections[0];
     if (!projection) continue;
-    const template = documentRef.createElement("template");
-    template.innerHTML = projection.html;
-    const fragment = template.content;
+    const bodyProjection = isRootBodyProjection(next, projection)
+      ? parseRootBodyProjection(projection.html, documentRef)
+      : null;
+    const fragment = documentRef.createDocumentFragment();
+    if (bodyProjection) {
+      for (const script of collectRouteRuntimeScripts(bodyProjection)) script.remove();
+      fragment.append(...bodyProjection.childNodes);
+    } else {
+      const template = documentRef.createElement("template");
+      template.innerHTML = projection.html;
+      fragment.append(template.content);
+    }
     materializeDeclarativeShadowDom(fragment);
     // Restore opaque SSR forwarded refs while the fragment is detached, before
     // its custom elements upgrade on insertion.
@@ -279,11 +361,19 @@ async function applyRouteDelta(delta, documentRef = document, signal, options =
       roots.map(({ root, element }) => ({ ...root, element })),
       delta.hydrationData,
     );
-    const range = documentRef.createRange();
-    range.setStartAfter(target.start);
-    range.setEndBefore(target.end);
-    range.deleteContents();
-    range.insertNode(fragment);
+    if (!replaceRootBodyProjection({
+      bodyProjection,
+      delta,
+      documentRef,
+      fragment,
+      target,
+    })) {
+      const range = documentRef.createRange();
+      range.setStartAfter(target.start);
+      range.setEndBefore(target.end);
+      range.deleteContents();
+      range.insertNode(fragment);
+    }
     insertedRoots.push(...roots);
     target.start.data = `evolit:segment:start:${next.id}`;
     target.end.data = `evolit:segment:end:${next.id}`;
@@ -292,8 +382,7 @@ async function applyRouteDelta(delta, documentRef = document, signal, options =
   // document to point persistent layout refs at the new target, or clear them
   // when the replacement page no longer exposes one.
   prepareForwardedRefs(documentRef);
-  const script = documentRef.getElementById("__EVOLIT_ROUTE__");
-  if (script) script.textContent = JSON.stringify(delta.route);
+  syncRouteStateScripts(delta, documentRef);
   if (delta.title) documentRef.title = delta.title;
   for (const { root, element } of insertedRoots) {
     throwIfAborted(signal);

package/src/navigation-server.js

@@ -1,4 +1,3 @@
-export function getNavigation() { throw new Error("Navigation is only available in a browser context."); }
 export { createHref } from "./navigation-url.js";
 export function useNavigation() { throw new Error("useNavigation() is only available in a browser component."); }
 export function useParams() { throw new Error("useParams() is only available in a browser component."); }

package/src/render.js

@@ -14,6 +14,7 @@ import {
   getRequestContextResponse,
   isEvolitHttpSignal,
   runWithRequestContext,
+  runWithRouteState,
 } from "./request-context.js";
 import { createDevelopmentEventReporter } from "./development-events.js";
 import {
@@ -294,6 +295,67 @@ function createTrackedRouteValues(values) {
   };
 }
 
+function createTrackedNavigationContext(values) {
+  const tracked = createTrackedRouteValues(values ?? {});
+  let accessed = false;
+
+  return {
+    value: values == null ? null : tracked.value,
+    read() {
+      accessed = true;
+      return values == null ? null : tracked.value;
+    },
+    profile() {
+      return { accessed, ...tracked.profile() };
+    },
+  };
+}
+
+function createTrackedSegmentProps(
+  trackedParams,
+  trackedSearchParams,
+  trackedNavigationContext,
+  props,
+) {
+  const result = {
+    params: trackedParams.value,
+    searchParams: trackedSearchParams.value,
+    ...props,
+  };
+  Object.defineProperty(result, "navigationContext", {
+    enumerable: true,
+    get: () => trackedNavigationContext.read(),
+  });
+  return result;
+}
+
+function createSegmentDependencyProfile(
+  trackedParams,
+  trackedSearchParams,
+  trackedNavigationContext,
+) {
+  return {
+    params: trackedParams.profile(),
+    searchParams: trackedSearchParams.profile(),
+    navigationContext: trackedNavigationContext.profile(),
+  };
+}
+
+function selectTrackedValues(profile, values) {
+  const normalized = profile ?? { all: false, keys: [] };
+  return Object.fromEntries(
+    (normalized.all ? Object.keys(values ?? {}) : normalized.keys ?? [])
+      .sort()
+      .map((key) => [key, values?.[key]]),
+  );
+}
+
+function selectTrackedNavigationContext(profile, navigationContext) {
+  if (!profile?.accessed) return undefined;
+  if (navigationContext == null) return null;
+  return selectTrackedValues(profile, navigationContext);
+}
+
 function createSegmentCacheKey(
   segment,
   idPrefix,
@@ -302,30 +364,26 @@ function createSegmentCacheKey(
   searchParams,
   navigationContext,
 ) {
-  const select = (values) => Object.fromEntries(
-    (profile.all ? Object.keys(values) : profile.keys)
-      .sort()
-      .map((key) => [key, values[key]]),
-  );
   return JSON.stringify({
     modulePath: segment.modulePath,
     idPrefix,
-    params: select(params),
-    searchParams: select(searchParams),
-    navigationContext: navigationContext ?? null,
+    params: selectTrackedValues(profile.params, params),
+    searchParams: selectTrackedValues(profile.searchParams, searchParams),
+    navigationContext: selectTrackedNavigationContext(
+      profile.navigationContext,
+      navigationContext,
+    ),
   });
 }
 
 function createSegmentInputKey(profile, params, searchParams, navigationContext) {
-  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),
-    navigationContext: navigationContext ?? null,
+    params: selectTrackedValues(profile.params, params),
+    searchParams: selectTrackedValues(profile.searchParams, searchParams),
+    navigationContext: selectTrackedNavigationContext(
+      profile.navigationContext,
+      navigationContext,
+    ),
   });
 }
 
@@ -456,18 +514,37 @@ async function renderSegmentedComponentTree(
     const idPrefix = `${segment.id}-p${projectionPath.join("-") || "0"}`;
 
     if (index === layoutComponents.length) {
-      const pageValue = await component({
-        params: requestContext.params,
-        searchParams: requestContext.searchParams,
-        navigationContext: requestContext.navigationContext,
-        request,
-        ...extraProps,
-      }, incomingRef);
+      const trackedParams = createTrackedRouteValues(requestContext.params);
+      const trackedSearchParams = createTrackedRouteValues(requestContext.searchParams);
+      const trackedNavigationContext = createTrackedNavigationContext(
+        requestContext.navigationContext,
+      );
+      const pageValue = await runWithRouteState(requestContext, {
+        params: trackedParams.value,
+        searchParams: trackedSearchParams.value,
+        navigationContext: trackedNavigationContext.value,
+        trackNavigationContext: () => trackedNavigationContext.read(),
+      }, () => component(createTrackedSegmentProps(
+        trackedParams,
+        trackedSearchParams,
+        trackedNavigationContext,
+        { request, ...extraProps },
+      ), incomingRef));
       const pageResult = await renderToString(wrapRouteSegment(segment, pageValue), {
         assetResolver: options.assetResolver,
         context: { idPrefix },
       });
       pageResult.segmentModulePath = segment.modulePath;
+      segment.inputKey = createSegmentInputKey(
+        createSegmentDependencyProfile(
+          trackedParams,
+          trackedSearchParams,
+          trackedNavigationContext,
+        ),
+        requestContext.params,
+        requestContext.searchParams,
+        requestContext.navigationContext,
+      );
       results.push(pageResult);
       return pageResult.html;
     }
@@ -485,26 +562,36 @@ async function renderSegmentedComponentTree(
     if (!layoutResult) {
       const trackedParams = createTrackedRouteValues(requestContext.params);
       const trackedSearchParams = createTrackedRouteValues(requestContext.searchParams);
+      const trackedNavigationContext = createTrackedNavigationContext(
+        requestContext.navigationContext,
+      );
       const didUseDynamicRequestData = requestContext.didUseDynamicRequestData;
-      const layoutValue = await layoutComponents[index]({
+      layoutResult = await runWithRouteState(requestContext, {
         params: trackedParams.value,
         searchParams: trackedSearchParams.value,
-        navigationContext: requestContext.navigationContext,
-        request,
-        children: withForwardedChildRef(html`${unsafeHTML(childrenMarker)}`, childRef),
-      }, incomingRef);
-      layoutResult = await renderToString(wrapRouteSegment(segment, layoutValue), {
-        assetResolver: options.assetResolver,
-        context: { idPrefix },
+        navigationContext: trackedNavigationContext.value,
+        trackNavigationContext: () => trackedNavigationContext.read(),
+      }, async () => {
+        const layoutValue = await layoutComponents[index](createTrackedSegmentProps(
+          trackedParams,
+          trackedSearchParams,
+          trackedNavigationContext,
+          {
+            request,
+            children: withForwardedChildRef(html`${unsafeHTML(childrenMarker)}`, childRef),
+          },
+        ), incomingRef);
+        return renderToString(wrapRouteSegment(segment, layoutValue), {
+          assetResolver: options.assetResolver,
+          context: { idPrefix },
+        });
       });
       layoutResult.segmentModulePath = segment.modulePath;
-      profile = {
-        all: trackedParams.profile().all || trackedSearchParams.profile().all,
-        keys: [...new Set([
-          ...trackedParams.profile().keys,
-          ...trackedSearchParams.profile().keys,
-        ])].sort(),
-      };
+      profile = createSegmentDependencyProfile(
+        trackedParams,
+        trackedSearchParams,
+        trackedNavigationContext,
+      );
       if (!didUseDynamicRequestData && !requestContext.didUseDynamicRequestData) {
         options.segmentCache?.set(
           segment,

package/src/request-context-browser.js

@@ -10,3 +10,4 @@ export function redirect() { return throwServerOnlyApi("redirect"); }
 export function requestUrl() { return throwServerOnlyApi("requestUrl"); }
 export function responseHeaders() { return throwServerOnlyApi("responseHeaders"); }
 export function getRequestContext() { return throwServerOnlyApi("getRequestContext"); }
+export function getRouteState() { return throwServerOnlyApi("getRouteState"); }

package/src/request-context.js

@@ -2,9 +2,11 @@ import { AsyncLocalStorage } from "node:async_hooks";
 import { readNavigationContext } from "./navigation-context.js";
 
 const REQUEST_CONTEXT_STORAGE = Symbol.for("evolit.request-context.storage");
+const ROUTE_STATE_STORAGE = Symbol.for("evolit.route-state.storage");
 const HTTP_SIGNAL_CLASS = Symbol.for("evolit.request-context.http-signal");
 
 const requestContextStorage = globalThis[REQUEST_CONTEXT_STORAGE] ??= new AsyncLocalStorage();
+const routeStateStorage = globalThis[ROUTE_STATE_STORAGE] ??= new AsyncLocalStorage();
 const EvolitHttpSignal = globalThis[HTTP_SIGNAL_CLASS] ??= class EvolitHttpSignal extends Error {
   constructor(type, options = {}) {
     super(type);
@@ -111,11 +113,14 @@ export function createRequestContext({
   extensionValues = {},
   didUseDynamicRequestData = false,
 }) {
+  const routeNavigationContext = navigationContext == null
+    ? null
+    : Object.freeze({ ...navigationContext });
   const context = {
     request,
     params: Object.freeze({ ...params }),
     searchParams: Object.freeze({ ...searchParams }),
-    navigationContext,
+    navigationContext: routeNavigationContext,
     responseHeaders: new Headers(),
     responseCookies: [],
     didUseDynamicRequestData: didUseDynamicRequestData === true,
@@ -130,6 +135,56 @@ export function runWithRequestContext(context, callback) {
   return requestContextStorage.run(context, callback);
 }
 
+export function runWithRouteState(context, routeState, callback) {
+  return routeStateStorage.run({ context, ...routeState }, callback);
+}
+
+/**
+ * Returns a read-only snapshot of the active SSR route. Unlike the browser
+ * navigation controller, this state has no history or mutation methods.
+ * Reading `url` follows the same dynamic-rendering semantics as requestUrl().
+ *
+ * @returns {{
+ *   url: URL,
+ *   params: Readonly<Record<string, string | string[] | undefined>>,
+ *   searchParams: Readonly<Record<string, string | string[] | undefined>>,
+ *   navigationContext: Readonly<Record<string, unknown>> | null,
+ * }}
+ */
+export function getRouteState() {
+  const context = getActiveContext();
+  const trackedState = routeStateStorage.getStore();
+  const routeState = trackedState?.context === context ? trackedState : context;
+  const state = {};
+
+  Object.defineProperties(state, {
+    url: {
+      enumerable: true,
+      get() {
+        context.didUseDynamicRequestData = true;
+        return new URL(context.request.url);
+      },
+    },
+    params: {
+      enumerable: true,
+      value: routeState.params,
+    },
+    searchParams: {
+      enumerable: true,
+      value: routeState.searchParams,
+    },
+    navigationContext: {
+      enumerable: true,
+      get() {
+        trackedState?.trackNavigationContext?.();
+        return routeState.navigationContext;
+      },
+    },
+  });
+
+  return Object.freeze(state);
+}
+
 /**
  * Returns serializable values supplied by configured server extensions for
  * the active request. The object is isolated through AsyncLocalStorage and is

package/src/server-api.js

@@ -52,3 +52,10 @@ export { responseHeaders } from "./request-context.js";
 
 /** Returns the active request's extension-provided serializable values. */
 export { getRequestContext } from "./request-context.js";
+
+/**
+ * Returns a read-only snapshot of the active SSR route. This is the server
+ * counterpart for reading navigation state; redirects remain separate
+ * control-flow functions and browser history methods are intentionally absent.
+ */
+export { getRouteState } from "./request-context.js";