evolit 0.1.8 → 0.2.0

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:
@@ -266,20 +266,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 +292,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.0",
   "description": "A convention-driven application framework for LitSX and web components.",
   "type": "module",
   "packageManager": "yarn@4.10.3",

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 {
@@ -486,16 +487,21 @@ async function renderSegmentedComponentTree(
       const trackedParams = createTrackedRouteValues(requestContext.params);
       const trackedSearchParams = createTrackedRouteValues(requestContext.searchParams);
       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 },
+      }, async () => {
+        const layoutValue = await layoutComponents[index]({
+          params: trackedParams.value,
+          searchParams: trackedSearchParams.value,
+          navigationContext: requestContext.navigationContext,
+          request,
+          children: withForwardedChildRef(html`${unsafeHTML(childrenMarker)}`, childRef),
+        }, incomingRef);
+        return renderToString(wrapRouteSegment(segment, layoutValue), {
+          assetResolver: options.assetResolver,
+          context: { idPrefix },
+        });
       });
       layoutResult.segmentModulePath = segment.modulePath;
       profile = {

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,53 @@ 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,
+      value: context.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";