evolit 0.1.6 → 0.1.7

package/README.md

@@ -140,12 +140,18 @@ export default function CollectionControls() {
 }
 ```
 
-The hook returns `{ status, url, pendingUrl, error, push, replace, refresh, createHref }`:
+The hook returns
+`{ status, url, pendingUrl, error, context, push, replace, replaceContext, refresh, createHref }`:
 
 - `push(target, { scroll: false })` adds a browser-history entry. Pass
   `scroll: false` to keep the current viewport position.
 - `replace(target, { scroll: false })` updates the current entry, useful for
   visual-only query state. It accepts the same scroll option.
+- `push(target, { context })` and `replace(target, { context })` attach JSON-safe transient state
+  to that history entry and make it available to the destination page and layouts as their
+  `navigationContext` prop during SSR.
+- `replaceContext(contextOrUpdater)` updates only the current history entry and hook state. It does
+  not change the URL or fetch a route delta.
 - `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`.
@@ -154,6 +160,12 @@ The hook returns `{ status, url, pendingUrl, error, push, replace, refresh, crea
 share with server-evaluated route code. `useNavigation()` itself is browser-only and must only run
 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.
+
 Client components can also read the active route state with browser-only hooks:
 
 ```jsx

package/package.json

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

package/src/navigation-client.js

@@ -7,6 +7,11 @@ import {
   registerHydrationModules,
 } from "@litsx/ssr/hydration";
 import { createHref as createBaseHref } from "./navigation-url.js";
+import {
+  EVOLIT_NAVIGATION_CONTEXT_HEADER,
+  encodeNavigationContext,
+  normalizeNavigationContext,
+} from "./navigation-context.js";
 import {
   getNavigationExtensions,
   registerNavigationExtensions,
@@ -305,10 +310,18 @@ function toHref(target, location) {
   return new URL(target, location.href).href;
 }
 
-function toCacheKey(href) {
+function toCacheKey(href, encodedContext = null) {
   const url = new URL(href);
   url.hash = "";
-  return url.href;
+  return `${url.href}\ncontext:${encodedContext ?? ""}`;
+}
+
+function readStoredNavigationContext(value) {
+  try {
+    return normalizeNavigationContext(value ?? null);
+  } catch {
+    return null;
+  }
 }
 
 function getDeltaExpiry(delta, now = Date.now()) {
@@ -406,7 +419,15 @@ export function createBrowserNavigation(options = {}) {
   const historyEntries = new Map();
   let controller = null;
   let navigationSequence = 0;
-  let state = { status: "idle", url: windowRef.location.href, pendingUrl: null, error: null };
+  let state = {
+    status: "idle",
+    url: windowRef.location.href,
+    pendingUrl: null,
+    error: null,
+    context: readStoredNavigationContext(
+      windowRef.history.state?.__evolitNavigationContext ?? null,
+    ),
+  };
   const emit = () => listeners.forEach((listener) => listener(state));
   const notifyLocationChange = () => {
     const EventConstructor = windowRef.CustomEvent ?? globalThis.CustomEvent;
@@ -445,7 +466,17 @@ export function createBrowserNavigation(options = {}) {
 
   function ensureHistoryEntry(entryId = windowRef.history.state?.__evolitNavigationEntry) {
     const id = typeof entryId === "string" ? entryId : createHistoryEntryId();
-    if (!historyEntries.has(id)) historyEntries.set(id, { parentId: null, url: null, delta: null, expiresAt: null });
+    if (!historyEntries.has(id)) {
+      historyEntries.set(id, {
+        parentId: null,
+        url: null,
+        delta: null,
+        expiresAt: null,
+        context: readStoredNavigationContext(
+          windowRef.history.state?.__evolitNavigationContext ?? null,
+        ),
+      });
+    }
     if (windowRef.history.state?.__evolitNavigationEntry !== id) {
       windowRef.history.replaceState(
         { ...(windowRef.history.state ?? {}), __evolitNavigationEntry: id },
@@ -490,6 +521,7 @@ export function createBrowserNavigation(options = {}) {
 
   async function navigate(target, mode = "push", fromPopState = false, options = {}) {
     const previousHref = windowRef.location.href;
+    const previousContext = state.context;
     const requestedHref = toHref(target, windowRef.location);
     const initialHref = toHref(transformNavigationUrl(requestedHref, { type: "navigation" }), windowRef.location);
     const navigationExtensions = getNavigationExtensions();
@@ -502,7 +534,11 @@ export function createBrowserNavigation(options = {}) {
       : { url: initialHref, cancelled: false };
     if (beforeNavigation.cancelled) return null;
     const href = toHref(beforeNavigation.url, windowRef.location);
-    const cacheKey = toCacheKey(href);
+    const navigationContext = normalizeNavigationContext(
+      options.context === undefined ? null : options.context,
+    );
+    const encodedContext = encodeNavigationContext(navigationContext);
+    const cacheKey = toCacheKey(href, encodedContext);
     const scrollPosition = options.scroll === false
       ? currentScrollPosition(windowRef)
       : options.scrollPosition;
@@ -513,17 +549,33 @@ export function createBrowserNavigation(options = {}) {
     const isCurrent = () => navigationId === navigationSequence && !navigationController.signal.aborted;
     const currentEntryId = ensureHistoryEntry();
     let entryId = options.historyEntryId;
+    let createdEntry = false;
     if (fromPopState) {
       entryId = ensureHistoryEntry(entryId);
     } else if (mode === "push") {
       saveCurrentScrollPosition();
       removeForwardHistoryEntries(currentEntryId);
       entryId = createHistoryEntryId();
-      historyEntries.set(entryId, { parentId: currentEntryId, url: null, delta: null, expiresAt: null });
+      createdEntry = true;
+      historyEntries.set(entryId, {
+        parentId: currentEntryId,
+        url: null,
+        delta: null,
+        expiresAt: null,
+        context: navigationContext,
+      });
     } else {
       entryId = currentEntryId;
+      const entry = historyEntries.get(entryId);
+      if (entry) entry.context = navigationContext;
     }
-    state = { ...state, status: "pending", pendingUrl: href, error: null };
+    state = {
+      ...state,
+      status: "pending",
+      pendingUrl: href,
+      error: null,
+      context: navigationContext,
+    };
     emit();
     try {
       const cached = getCachedDelta(entryId, cacheKey, options.force);
@@ -531,7 +583,12 @@ export function createBrowserNavigation(options = {}) {
         ? cached
         : await (async () => {
           const response = await windowRef.fetch(href, {
-            headers: { accept: "application/vnd.evolit.navigation+json" },
+            headers: {
+              accept: "application/vnd.evolit.navigation+json",
+              ...(encodedContext
+                ? { [EVOLIT_NAVIGATION_CONTEXT_HEADER]: encodedContext }
+                : {}),
+            },
             // A document response may already be fresh in the browser HTTP cache.
             // Navigation is a different representation of that URL, so it must
             // reach the server rather than reusing the cached HTML document.
@@ -558,7 +615,9 @@ export function createBrowserNavigation(options = {}) {
           return nextDelta;
         })();
       if (!delta || !isCurrent()) return null;
-      if (delta.type === "redirect") return navigate(delta.location, "replace", false);
+      if (delta.type === "redirect") {
+        return navigate(delta.location, "replace", false, { context: navigationContext });
+      }
       const applied = await applyDelta(delta, {
         signal: navigationController.signal,
         moduleVersion: options.moduleVersion,
@@ -576,19 +635,26 @@ export function createBrowserNavigation(options = {}) {
             ...(mode === "replace" ? windowRef.history.state : {}),
             __evolitNavigationEntry: entryId,
             __evolitScroll: scrollPosition ?? { x: 0, y: 0 },
+            __evolitNavigationContext: navigationContext,
           },
           "",
           canonicalHref,
         );
       }
-      cacheDelta(entryId, toCacheKey(canonicalHref), delta);
+      cacheDelta(entryId, toCacheKey(canonicalHref, encodedContext), delta);
       restoreScrollAndFocus(
         windowRef,
         canonicalHref,
         scrollPosition,
         options.scroll === false,
       );
-      state = { status: "idle", url: canonicalHref, pendingUrl: null, error: null };
+      state = {
+        status: "idle",
+        url: canonicalHref,
+        pendingUrl: null,
+        error: null,
+        context: navigationContext,
+      };
       emit();
       notifyLocationChange();
       if (navigationExtensions.length > 0) {
@@ -603,16 +669,53 @@ export function createBrowserNavigation(options = {}) {
       return delta;
     } catch (error) {
       if (error?.name === "AbortError" || !isCurrent()) return null;
-      state = { ...state, status: "error", pendingUrl: null, error };
+      if (!fromPopState) {
+        if (createdEntry) historyEntries.delete(entryId);
+        else {
+          const entry = historyEntries.get(entryId);
+          if (entry) entry.context = previousContext;
+        }
+      }
+      state = {
+        ...state,
+        status: "error",
+        pendingUrl: null,
+        error,
+        context: fromPopState ? navigationContext : previousContext,
+      };
       emit();
       throw error;
     }
   }
 
+  async function replaceContext(nextContext) {
+    const currentContext = normalizeNavigationContext(state.context);
+    const resolvedContext = normalizeNavigationContext(
+      typeof nextContext === "function" ? nextContext(currentContext) : nextContext,
+    );
+    const entryId = ensureHistoryEntry();
+    const entry = historyEntries.get(entryId);
+
+    if (entry) entry.context = resolvedContext;
+    windowRef.history.replaceState(
+      {
+        ...(windowRef.history.state ?? {}),
+        __evolitNavigationEntry: entryId,
+        __evolitNavigationContext: resolvedContext,
+      },
+      "",
+      windowRef.location.href,
+    );
+    state = { ...state, context: resolvedContext };
+    emit();
+    return resolvedContext;
+  }
+
   windowRef.addEventListener("popstate", (event) => {
     void navigate(windowRef.location.href, "replace", true, {
       historyEntryId: event.state?.__evolitNavigationEntry,
       scrollPosition: event.state?.__evolitScroll ?? null,
+      context: readStoredNavigationContext(event.state?.__evolitNavigationContext),
     });
   });
   windowRef.addEventListener(DEVELOPMENT_REFRESH_EVENT, (event) => {
@@ -635,7 +738,13 @@ export function createBrowserNavigation(options = {}) {
       requireSegmentChange: true,
     }).then((applied) => {
       if (applied === false || refreshController.signal.aborted) return false;
-      state = { status: "idle", url: windowRef.location.href, pendingUrl: null, error: null };
+      state = {
+        status: "idle",
+        url: windowRef.location.href,
+        pendingUrl: null,
+        error: null,
+        context: state.context,
+      };
       emit();
       return true;
     }).catch((error) => {
@@ -667,7 +776,12 @@ export function createBrowserNavigation(options = {}) {
     subscribe(listener) { listeners.add(listener); return () => listeners.delete(listener); },
     push: (target, options) => navigate(target, "push", false, options),
     replace: (target, options) => navigate(target, "replace", false, options),
-    refresh: (options) => navigate(windowRef.location.href, "replace", false, { ...options, force: true }),
+    replaceContext,
+    refresh: (options = {}) => navigate(windowRef.location.href, "replace", false, {
+      ...options,
+      context: options.context ?? state.context,
+      force: true,
+    }),
     createHref,
   };
 }
@@ -686,6 +800,7 @@ export function useNavigation() {
     ...state,
     push: navigation.push,
     replace: navigation.replace,
+    replaceContext: navigation.replaceContext,
     refresh: navigation.refresh,
     createHref: navigation.createHref,
   };

package/src/navigation-context.js

@@ -0,0 +1,87 @@
+export const EVOLIT_NAVIGATION_CONTEXT_HEADER = "x-evolit-navigation-context";
+export const MAX_NAVIGATION_CONTEXT_BYTES = 8 * 1024;
+
+function assertJsonSafe(value, path, seen, depth) {
+  if (depth > 32) {
+    throw new TypeError(`Navigation context at ${path} is not JSON-safe.`);
+  }
+  if (value === null || typeof value === "string" || typeof value === "boolean") {
+    return;
+  }
+  if (typeof value === "number") {
+    if (Number.isFinite(value)) return;
+    throw new TypeError(`Navigation context at ${path} is not JSON-safe.`);
+  }
+  if (typeof value !== "object") {
+    throw new TypeError(`Navigation context at ${path} is not JSON-safe.`);
+  }
+  if (seen.has(value)) {
+    throw new TypeError(`Navigation context at ${path} is not JSON-safe.`);
+  }
+
+  const prototype = Object.getPrototypeOf(value);
+  if (!Array.isArray(value) && prototype !== Object.prototype && prototype !== null) {
+    throw new TypeError(`Navigation context at ${path} is not JSON-safe.`);
+  }
+
+  seen.add(value);
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => assertJsonSafe(item, `${path}[${index}]`, seen, depth + 1));
+  } else {
+    for (const [key, item] of Object.entries(value)) {
+      assertJsonSafe(item, `${path}.${key}`, seen, depth + 1);
+    }
+  }
+  seen.delete(value);
+}
+
+function serializeNavigationContext(context) {
+  if (context === null || context === undefined) return null;
+  if (typeof context !== "object" || Array.isArray(context)) {
+    throw new TypeError("Navigation context must be a JSON-safe object.");
+  }
+
+  assertJsonSafe(context, "context", new Set(), 0);
+  const serialized = JSON.stringify(context);
+  const bytes = new TextEncoder().encode(serialized);
+
+  if (bytes.byteLength > MAX_NAVIGATION_CONTEXT_BYTES) {
+    throw new RangeError("Navigation context cannot exceed 8 KiB when serialized.");
+  }
+
+  return { serialized, bytes };
+}
+
+export function normalizeNavigationContext(context) {
+  const result = serializeNavigationContext(context);
+  return result ? JSON.parse(result.serialized) : null;
+}
+
+export function encodeNavigationContext(context) {
+  const result = serializeNavigationContext(context);
+  if (!result) return null;
+  const base64 = btoa(String.fromCharCode(...result.bytes));
+  return base64.replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/u, "");
+}
+
+export function decodeNavigationContext(encoded) {
+  if (typeof encoded !== "string" || encoded.length === 0) return null;
+  if (encoded.length > Math.ceil(MAX_NAVIGATION_CONTEXT_BYTES * 4 / 3) + 4) return null;
+
+  try {
+    const base64 = encoded.replaceAll("-", "+").replaceAll("_", "/");
+    const padded = base64.padEnd(Math.ceil(base64.length / 4) * 4, "=");
+    const binary = atob(padded);
+    const bytes = Uint8Array.from(binary, (character) => character.charCodeAt(0));
+    const context = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+    return normalizeNavigationContext(context);
+  } catch {
+    return null;
+  }
+}
+
+export function readNavigationContext(request) {
+  return decodeNavigationContext(
+    request?.headers?.get?.(EVOLIT_NAVIGATION_CONTEXT_HEADER) ?? null,
+  );
+}

package/src/render.js

@@ -206,6 +206,7 @@ async function renderComponentTree(
         await component({
           params: requestContext.params,
           searchParams: requestContext.searchParams,
+          navigationContext: requestContext.navigationContext,
           request,
           ...extraProps,
         }, incomingRef),
@@ -221,6 +222,7 @@ async function renderComponentTree(
     return wrapRouteSegment(segment, await layoutComponents[index]({
       params: requestContext.params,
       searchParams: requestContext.searchParams,
+      navigationContext: requestContext.navigationContext,
       request,
       children,
     }, incomingRef));
@@ -292,7 +294,14 @@ function createTrackedRouteValues(values) {
   };
 }
 
-function createSegmentCacheKey(segment, idPrefix, profile, params, searchParams) {
+function createSegmentCacheKey(
+  segment,
+  idPrefix,
+  profile,
+  params,
+  searchParams,
+  navigationContext,
+) {
   const select = (values) => Object.fromEntries(
     (profile.all ? Object.keys(values) : profile.keys)
       .sort()
@@ -303,10 +312,11 @@ function createSegmentCacheKey(segment, idPrefix, profile, params, searchParams)
     idPrefix,
     params: select(params),
     searchParams: select(searchParams),
+    navigationContext: navigationContext ?? null,
   });
 }
 
-function createSegmentInputKey(profile, params, searchParams) {
+function createSegmentInputKey(profile, params, searchParams, navigationContext) {
   const select = (values) => Object.fromEntries(
     (profile.all ? Object.keys(values) : profile.keys)
       .sort()
@@ -315,6 +325,7 @@ function createSegmentInputKey(profile, params, searchParams) {
   return JSON.stringify({
     params: select(params),
     searchParams: select(searchParams),
+    navigationContext: navigationContext ?? null,
   });
 }
 
@@ -331,13 +342,20 @@ function createSegmentRenderCache(projectRoot, onDevelopmentEvent) {
   const profiles = new Map();
 
   return {
-    get(segment, idPrefix, params, searchParams) {
+    get(segment, idPrefix, params, searchParams, navigationContext) {
       const profile = profiles.get(segment.modulePath);
       if (!profile) {
         onDevelopmentEvent?.({ type: "segment-cache-miss", modulePath: segment.modulePath, reason: "cold" });
         return null;
       }
-      const key = createSegmentCacheKey(segment, idPrefix, profile, params, searchParams);
+      const key = createSegmentCacheKey(
+        segment,
+        idPrefix,
+        profile,
+        params,
+        searchParams,
+        navigationContext,
+      );
       const entry = entries.get(key);
       if (!entry || entry.expiresAt <= Date.now()) {
         if (entry) entries.delete(key);
@@ -354,11 +372,27 @@ function createSegmentRenderCache(projectRoot, onDevelopmentEvent) {
     getProfile(segment) {
       return profiles.get(segment.modulePath) ?? null;
     },
-    set(segment, idPrefix, params, searchParams, profile, result, cachePolicy) {
+    set(
+      segment,
+      idPrefix,
+      params,
+      searchParams,
+      navigationContext,
+      profile,
+      result,
+      cachePolicy,
+    ) {
       const expiresAt = getSegmentCacheExpiry(cachePolicy);
       if (expiresAt == null) return;
       profiles.set(segment.modulePath, profile);
-      const key = createSegmentCacheKey(segment, idPrefix, profile, params, searchParams);
+      const key = createSegmentCacheKey(
+        segment,
+        idPrefix,
+        profile,
+        params,
+        searchParams,
+        navigationContext,
+      );
       entries.set(key, { result, expiresAt, modulePath: segment.modulePath });
       if (entries.size > 256) entries.delete(entries.keys().next().value);
     },
@@ -425,6 +459,7 @@ async function renderSegmentedComponentTree(
       const pageValue = await component({
         params: requestContext.params,
         searchParams: requestContext.searchParams,
+        navigationContext: requestContext.navigationContext,
         request,
         ...extraProps,
       }, incomingRef);
@@ -445,6 +480,7 @@ async function renderSegmentedComponentTree(
       idPrefix,
       requestContext.params,
       requestContext.searchParams,
+      requestContext.navigationContext,
     ) ?? null;
     if (!layoutResult) {
       const trackedParams = createTrackedRouteValues(requestContext.params);
@@ -453,6 +489,7 @@ async function renderSegmentedComponentTree(
       const layoutValue = await layoutComponents[index]({
         params: trackedParams.value,
         searchParams: trackedSearchParams.value,
+        navigationContext: requestContext.navigationContext,
         request,
         children: withForwardedChildRef(html`${unsafeHTML(childrenMarker)}`, childRef),
       }, incomingRef);
@@ -474,6 +511,7 @@ async function renderSegmentedComponentTree(
           idPrefix,
           requestContext.params,
           requestContext.searchParams,
+          requestContext.navigationContext,
           profile,
           layoutResult,
           options.cachePolicy,
@@ -485,6 +523,7 @@ async function renderSegmentedComponentTree(
         profile,
         requestContext.params,
         requestContext.searchParams,
+        requestContext.navigationContext,
       );
     }
     results.push(layoutResult);

package/src/request-context.js

@@ -1,4 +1,5 @@
 import { AsyncLocalStorage } from "node:async_hooks";
+import { readNavigationContext } from "./navigation-context.js";
 
 const REQUEST_CONTEXT_STORAGE = Symbol.for("evolit.request-context.storage");
 const HTTP_SIGNAL_CLASS = Symbol.for("evolit.request-context.http-signal");
@@ -106,6 +107,7 @@ export function createRequestContext({
   request,
   params = {},
   searchParams = {},
+  navigationContext = readNavigationContext(request),
   extensionValues = {},
   didUseDynamicRequestData = false,
 }) {
@@ -113,6 +115,7 @@ export function createRequestContext({
     request,
     params: Object.freeze({ ...params }),
     searchParams: Object.freeze({ ...searchParams }),
+    navigationContext,
     responseHeaders: new Headers(),
     responseCookies: [],
     didUseDynamicRequestData: didUseDynamicRequestData === true,

package/src/response-cache.js

@@ -3,6 +3,7 @@ import crypto from "node:crypto";
 import path from "node:path";
 import { BUILD_DIRECTORY, INTERNAL_DIRECTORY, ROUTE_CACHE_DIRECTORY } from "./constants.js";
 import { ensureDirectory, pathExists, readJson, writeJson } from "./fs-utils.js";
+import { encodeNavigationContext, readNavigationContext } from "./navigation-context.js";
 
 function createCacheFileName(cacheKey) {
   return `${crypto.createHash("sha1").update(cacheKey).digest("hex")}.json`;
@@ -160,7 +161,8 @@ export class ObjectStorageResponseCacheStore {
 
 export function createDefaultRouteCacheKey(request) {
   const url = new URL(request.url);
-  return `${url.pathname}${url.search}`;
+  const context = encodeNavigationContext(readNavigationContext(request));
+  return `${url.pathname}${url.search}${context ? `\ncontext:${context}` : ""}`;
 }
 
 export function getRouteCacheArtifactFileName(cacheKey) {