@rangojs/router 0.0.0-experimental.13 → 0.0.0-experimental.130

package/src/browser/react/location-state-shared.ts

@@ -1,16 +1,98 @@
-/**
- * Shared location state utilities - works in both RSC and client contexts
- * No "use client" directive so it can be imported from RSC
- */
+import type { ReactElement } from "react";
 
 /**
- * Internal entry representing a state value with its unique key
+ * Internal entry representing a state value with its unique key.
+ * When __rsc_ls_lazy is true, __rsc_ls_value holds a getter function
+ * that is called at navigation time (not at entry creation time).
  */
 export interface LocationStateEntry {
   readonly __rsc_ls_key: string;
   readonly __rsc_ls_value: unknown;
+  readonly __rsc_ls_lazy?: boolean;
+}
+
+/**
+ * Options for createLocationState
+ */
+export interface LocationStateOptions {
+  /** When true, the state is cleared from history after first read (flash message pattern) */
+  flash?: boolean;
 }
 
+type LocationStateUnsafeFn = (...args: never[]) => unknown;
+
+type LocationStateUnsafeCtor = abstract new (...args: never[]) => unknown;
+
+type IsAny<T> = 0 extends 1 & T ? true : false;
+type IsUnknown<T> =
+  IsAny<T> extends true ? false : unknown extends T ? true : false;
+
+/**
+ * Branded error surfaced when a value that cannot live in location state is
+ * used. Location state is written into `history.state`, which uses the
+ * structured clone algorithm; React elements, functions, and symbols throw a
+ * `DataCloneError` at runtime. Carries a human-readable reason so the compile
+ * error explains the fix.
+ */
+export type LocationStateUnsafe<Reason extends string> = {
+  readonly __rango_location_state_unsafe: Reason;
+};
+
+/**
+ * Maps `T` to itself when it is safe to store in location state, or to a branded
+ * {@link LocationStateUnsafe} error for the disallowed parts: `unknown`, React
+ * elements (RSC/JSX content), functions, class constructors, and symbols.
+ * Recurses through arrays, `Map`, `Set`, and plain objects; structured-clone
+ * built-ins (`Date`, `RegExp`, typed arrays, `Blob`, `File`, `FormData`) pass
+ * through. Consumed by {@link ValidateLocationState}, which is intersected into a
+ * definition's value parameter so posting RSC content is a COMPILE error, not a
+ * runtime `DataCloneError`. (`any` is unguardable and remains an escape hatch.)
+ */
+export type LocationStateSafe<T> =
+  IsUnknown<T> extends true
+    ? LocationStateUnsafe<"location state needs an explicit, concrete type; `unknown` cannot be verified as serializable">
+    : T extends LocationStateUnsafeFn
+      ? LocationStateUnsafe<"functions cannot be stored in location state">
+      : T extends LocationStateUnsafeCtor
+        ? LocationStateUnsafe<"class constructors cannot be stored in location state">
+        : T extends symbol
+          ? LocationStateUnsafe<"symbols cannot be stored in location state">
+          : T extends ReactElement
+            ? LocationStateUnsafe<"React/RSC content cannot be stored in location state; store plain data and render it on arrival">
+            : T extends string | number | boolean | bigint | null | undefined
+              ? T
+              : T extends
+                    | Date
+                    | RegExp
+                    | ArrayBuffer
+                    | ArrayBufferView
+                    | Blob
+                    | File
+                    | FormData
+                ? T
+                : T extends ReadonlyMap<infer K, infer V>
+                  ? ReadonlyMap<LocationStateSafe<K>, LocationStateSafe<V>>
+                  : T extends ReadonlySet<infer V>
+                    ? ReadonlySet<LocationStateSafe<V>>
+                    : T extends readonly unknown[]
+                      ? { [K in keyof T]: LocationStateSafe<T[K]> }
+                      : T extends object
+                        ? { [K in keyof T]: LocationStateSafe<T[K]> }
+                        : T;
+
+/**
+ * `unknown` (a no-op) when `T` is safe to store in location state, otherwise a
+ * branded {@link LocationStateUnsafe} object. Intersected into the value
+ * parameter of a definition's call and `write()` so POSTING RSC content (or any
+ * non-serializable value) is a compile error whose text carries the reason —
+ * without a `TState extends ...` self-constraint, which TypeScript rejects as
+ * circular (TS2313). For safe `T`, `value & unknown` collapses back to `value`,
+ * so valid usage is unchanged.
+ */
+export type ValidateLocationState<T> = [T] extends [LocationStateSafe<T>]
+  ? unknown
+  : LocationStateUnsafe<"location state must be serializable: React/RSC content, functions, and symbols cannot be stored — pass plain data and render it on arrival">;
+
 /**
  * Type-safe location state definition
  *
@@ -19,84 +101,200 @@ export interface LocationStateEntry {
  */
 export interface LocationStateDefinition<TArgs extends unknown[], TState> {
   (...args: TArgs): LocationStateEntry;
-  readonly __rsc_ls_key: string;
+  /** Injected by Vite plugin - do not set manually */
+  __rsc_ls_key: string;
+  /** Whether this state auto-clears after first read */
+  readonly __rsc_ls_flash: boolean;
+  /**
+   * Read the current value from history.state.
+   *
+   * Returns undefined during SSR (no `window`). To stay hydration-safe, do
+   * NOT call read() inline during the initial render — the server returns
+   * undefined while the client may have a value preserved in history.state
+   * (e.g. after a hard reload of an entry that earlier called write()),
+   * which causes a hydration mismatch. Call read() inside an event handler
+   * or a useEffect post-mount instead, or use useLocationState() if you
+   * want React to manage subscription/hydration for you.
+   */
+  read(): TState | undefined;
+  /**
+   * Statically write the value into the current history entry under this
+   * definition's key, preserving any other keys already on history.state
+   * (e.g. router bookkeeping, other LocationState slots).
+   *
+   * This is the non-reactive counterpart to read(): it does not dispatch any
+   * event, so components reading via useLocationState() will NOT re-render
+   * until the next navigation/popstate. Use it when you only need the value
+   * to be there on the next read() or on the next mount (including after
+   * back/forward and hard refresh of the same entry).
+   *
+   * Client-only: throws when called on the server (no history available).
+   */
+  write(value: TState & ValidateLocationState<TState>): void;
+  /**
+   * Statically remove this definition's slot from the current history entry,
+   * leaving any other keys on history.state untouched. Idempotent: removing
+   * a slot that isn't present is a no-op.
+   *
+   * Same non-reactive semantics as write(): no event is dispatched, so
+   * useLocationState() readers will NOT re-render until the next navigation.
+   *
+   * Client-only: throws when called on the server (no history available).
+   */
+  delete(): void;
 }
 
-// Track used keys to detect duplicates in development
-const usedKeys = new Set<string>();
-
 /**
  * Create a type-safe location state definition
  *
- * The key is auto-generated by the Vite exposeInternalIds plugin based on
- * file path and export name. No manual key required.
+ * The key is auto-injected by the Vite exposeInternalIds plugin as a property
+ * based on file path and export name. No manual key required.
  *
- * @param key Auto-injected by Vite plugin, do not provide manually
+ * @param options Optional configuration
  * @returns A typed state definition for use with Link and useLocationState
  *
  * @example
  * ```typescript
- * // Define typed state (key auto-generated from file + export)
+ * // Persistent state (survives back/forward)
  * export const ProductState = createLocationState<{ name: string; price: number }>();
  *
- * // Use in Link - state is captured at click time
- * <Link to="/product/123" state={[ProductState({ name: product.name, price: product.price })]}>
- *   View Product
- * </Link>
+ * // Flash state (cleared after first read)
+ * export const FlashMessage = createLocationState<{ text: string }>({ flash: true });
  *
- * // Multiple states
- * <Link to="/checkout" state={[ProductState(productData), CartState(cartData)]}>
- *   Checkout
- * </Link>
+ * // Use in Link
+ * <Link to="/product/123" state={[ProductState({ name: "Widget", price: 9.99 })]}>
  *
- * // For lazy evaluation (click-time), pass a getter
- * <Link to="/product" state={[ProductState(() => ({ name: product.name }))]}>
+ * // Just-in-time typed state (getter called at click time, not render time).
+ * // Must be in a client component — the getter function can't cross the RSC boundary.
+ * <Link
+ *   to="/product/123"
+ *   state={[ProductState(() => ({ name: product.name, price: product.price }))]}
+ * >
  *
- * // Read with type safety
- * const productState = useLocationState(ProductState);
- * // productState: { name: string; price: number } | undefined
+ * // Read with hook (reactive)
+ * const product = useLocationState(ProductState);
+ *
+ * // Read without hook (snapshot, client-side only)
+ * const snap = ProductState.read();
+ *
+ * // Static write to current history entry (non-reactive, client-side only).
+ * // Survives back/forward and hard refresh; useLocationState() readers will
+ * // NOT see the new value until the next navigation. Pair with .read() or a
+ * // fresh mount.
+ * ProductState.write({ name: "Widget", price: 9.99 });
+ *
+ * // Manually clear the slot (non-reactive, client-side only).
+ * ProductState.delete();
  * ```
  */
 export function createLocationState<TState>(
-  key?: string
-): LocationStateDefinition<[TState | (() => TState)], TState> {
-  if (!key && process.env.NODE_ENV !== "production") {
-    throw new Error(
-      "[rsc-router] createLocationState is missing a key. " +
-        "Make sure the exposeInternalIds Vite plugin is enabled and " +
-        "the state is exported with: export const MyState = createLocationState(...)"
-    );
-  }
-  const fullKey = `__rsc_ls_${key}`;
-
-  // Warn about duplicate keys in development
-  if (process.env.NODE_ENV !== "production" && usedKeys.has(fullKey)) {
-    console.warn(
-      `[rsc-router] Duplicate location state key "${key}". ` +
-        `Each createLocationState call should have a unique key.`
-    );
+  options?: LocationStateOptions,
+): LocationStateDefinition<
+  [(TState | (() => TState)) & ValidateLocationState<TState>],
+  TState
+> {
+  const flash = options?.flash ?? false;
+  let _key: string | undefined;
+
+  function getKey(): string {
+    if (!_key && process.env.NODE_ENV === "development") {
+      throw new Error(
+        "[rango] createLocationState key not set. " +
+          "Make sure the exposeInternalIds Vite plugin is enabled and " +
+          "the state is exported with: export const MyState = createLocationState(...)",
+      );
+    }
+    return _key!;
   }
-  usedKeys.add(fullKey);
-
-  const definition = Object.assign(
-    (stateOrGetter: TState | (() => TState)): LocationStateEntry => ({
-      __rsc_ls_key: fullKey,
-      // Resolve getter immediately - lazy evaluation happens via Link's stateRef pattern
-      __rsc_ls_value:
-        typeof stateOrGetter === "function"
-          ? (stateOrGetter as () => TState)()
-          : stateOrGetter,
-    }),
-    { __rsc_ls_key: fullKey }
-  );
 
-  return definition as LocationStateDefinition<[TState | (() => TState)], TState>;
+  const fn = (stateOrGetter: TState | (() => TState)): LocationStateEntry => {
+    if (typeof stateOrGetter === "function") {
+      // Store getter as-is; resolved at navigation time by resolveLocationStateEntries()
+      return {
+        __rsc_ls_key: getKey(),
+        __rsc_ls_value: stateOrGetter,
+        __rsc_ls_lazy: true,
+      };
+    }
+    return {
+      __rsc_ls_key: getKey(),
+      __rsc_ls_value: stateOrGetter,
+    };
+  };
+
+  // Use defineProperty for __rsc_ls_key to avoid Object.assign evaluating
+  // the getter during construction (before the Vite plugin sets the key).
+  Object.defineProperty(fn, "__rsc_ls_key", {
+    get: () => getKey(),
+    set: (k: string) => {
+      _key = k;
+    },
+    enumerable: true,
+    configurable: true,
+  });
+
+  Object.defineProperty(fn, "__rsc_ls_flash", {
+    value: flash,
+    enumerable: true,
+  });
+
+  Object.defineProperty(fn, "read", {
+    value: (): TState | undefined => {
+      if (typeof window === "undefined") return undefined;
+      return window.history.state?.[getKey()] as TState | undefined;
+    },
+    enumerable: true,
+  });
+
+  Object.defineProperty(fn, "write", {
+    value: (value: TState): void => {
+      if (typeof window === "undefined") {
+        throw new Error(
+          "[rango] LocationState.write() is client-only. " +
+            "It mutates window.history.state and cannot run on the server.",
+        );
+      }
+      const key = getKey();
+      const current = window.history.state ?? {};
+      window.history.replaceState(
+        { ...current, [key]: value },
+        "",
+        window.location.href,
+      );
+    },
+    enumerable: true,
+  });
+
+  Object.defineProperty(fn, "delete", {
+    value: (): void => {
+      if (typeof window === "undefined") {
+        throw new Error(
+          "[rango] LocationState.delete() is client-only. " +
+            "It mutates window.history.state and cannot run on the server.",
+        );
+      }
+      const key = getKey();
+      const current = window.history.state;
+      if (current == null || !(key in current)) return;
+      const next = { ...current };
+      delete next[key];
+      window.history.replaceState(next, "", window.location.href);
+    },
+    enumerable: true,
+  });
+
+  return fn as unknown as LocationStateDefinition<
+    [(TState | (() => TState)) & ValidateLocationState<TState>],
+    TState
+  >;
 }
 
 /**
  * Check if a value is a LocationStateEntry
  */
-export function isLocationStateEntry(value: unknown): value is LocationStateEntry {
+export function isLocationStateEntry(
+  value: unknown,
+): value is LocationStateEntry {
   return (
     value !== null &&
     typeof value === "object" &&
@@ -110,11 +308,13 @@ export function isLocationStateEntry(value: unknown): value is LocationStateEntr
  * Resolve state entries into a flat object for history.state
  */
 export function resolveLocationStateEntries(
-  entries: LocationStateEntry[]
+  entries: LocationStateEntry[],
 ): Record<string, unknown> {
   const result: Record<string, unknown> = {};
   for (const entry of entries) {
-    result[entry.__rsc_ls_key] = entry.__rsc_ls_value;
+    result[entry.__rsc_ls_key] = entry.__rsc_ls_lazy
+      ? (entry.__rsc_ls_value as () => unknown)()
+      : entry.__rsc_ls_value;
   }
   return result;
 }

package/src/browser/react/location-state.ts

@@ -1,62 +1,132 @@
 "use client";
 
-import { useState, useEffect } from "react";
+import { useState, useEffect, useRef } from "react";
 import type { LocationStateDefinition } from "./location-state-shared.js";
 
-// Re-export shared utilities and types
 export {
   createLocationState,
   isLocationStateEntry,
   resolveLocationStateEntries,
   type LocationStateEntry,
   type LocationStateDefinition,
+  type LocationStateOptions,
 } from "./location-state-shared.js";
 
+function readLocationStateValue<TState>(
+  key: string | undefined,
+): TState | undefined {
+  if (typeof window === "undefined") return undefined;
+  if (key) {
+    return window.history.state?.[key] as TState | undefined;
+  }
+  // Plain state: stored under history.state.state
+  return window.history.state?.state as TState | undefined;
+}
+
+function hasHydrated(): boolean {
+  return (
+    typeof document !== "undefined" &&
+    document.documentElement.hasAttribute("data-hydrated")
+  );
+}
+
 /**
  * Hook to read location state from history.state
  *
+ * Behavior depends on the definition:
+ * - Normal state: persists across navigations, reactive to popstate
+ * - Flash state (created with { flash: true }): read once, cleared after paint
+ *
  * Overloaded:
  * - With definition: Returns typed state from the specific key
- * - With type param only: Returns legacy state from history.state.state (backwards compat)
+ * - With type param only: Returns plain state from history.state.state
  *
  * @example
  * ```typescript
- * // Typed access with definition (recommended)
- * const ProductState = createLocationState<{ name: string }>("product");
+ * // Persistent state
+ * const ProductState = createLocationState<{ name: string }>();
  * const state = useLocationState(ProductState);
- * // state: { name: string } | undefined
  *
- * // Legacy typed access (backwards compatible)
- * const legacyState = useLocationState<{ from?: string }>();
+ * // Flash state (auto-clears after paint)
+ * const FlashMsg = createLocationState<{ text: string }>({ flash: true });
+ * const flash = useLocationState(FlashMsg);
+ *
+ * // Plain state access (reads from history.state.state)
+ * const state = useLocationState<{ from?: string }>();
  * ```
  */
 export function useLocationState<TArgs extends unknown[], TState>(
-  definition: LocationStateDefinition<TArgs, TState>
+  definition: LocationStateDefinition<TArgs, TState>,
 ): TState | undefined;
 export function useLocationState<T = unknown>(): T | undefined;
 export function useLocationState<TArgs extends unknown[], TState>(
-  definition?: LocationStateDefinition<TArgs, TState>
+  definition?: LocationStateDefinition<TArgs, TState>,
 ): TState | undefined {
+  const key = definition?.__rsc_ls_key;
+  const isFlash = definition?.__rsc_ls_flash ?? false;
+
+  // Track whether the initial render returned undefined because the page
+  // hadn't hydrated yet. If so, the mount effect catches up by reading
+  // history.state once. If not, we already have the right value and must
+  // not re-read on mount — under StrictMode, the flash-cleanup effect runs
+  // before the second setup pass, so a re-read would clobber the captured
+  // value with the now-cleared `undefined`.
+  const initialReadDeferredRef = useRef(false);
+
   const [state, setState] = useState<TState | undefined>(() => {
-    if (typeof window === "undefined") return undefined;
-    if (definition) {
-      return window.history.state?.[definition.__rsc_ls_key] as TState | undefined;
+    if (!hasHydrated()) {
+      initialReadDeferredRef.current = true;
+      return undefined;
     }
-    // Legacy: return history.state.state for backwards compatibility
-    return window.history.state?.state as TState | undefined;
+    return readLocationStateValue<TState>(key);
   });
 
+  // Subscribe to popstate and programmatic state changes
   useEffect(() => {
     const handlePopstate = () => {
-      if (definition) {
-        setState(window.history.state?.[definition.__rsc_ls_key] as TState | undefined);
+      setState(readLocationStateValue<TState>(key));
+    };
+
+    // Handle programmatic state changes (same-page navigation with
+    // ctx.setLocationState where components don't remount)
+    const handleLocationState = () => {
+      if (key) {
+        const val = readLocationStateValue<TState>(key);
+        if (isFlash) {
+          // For flash state, only update if there's a new value
+          if (val !== undefined) {
+            setState(val);
+          }
+        } else {
+          setState(val);
+        }
       } else {
-        setState(window.history.state?.state as TState | undefined);
+        setState(readLocationStateValue<TState>(key));
       }
     };
+
+    if (initialReadDeferredRef.current) {
+      initialReadDeferredRef.current = false;
+      setState(readLocationStateValue<TState>(key));
+    }
+
     window.addEventListener("popstate", handlePopstate);
-    return () => window.removeEventListener("popstate", handlePopstate);
-  }, [definition]);
+    window.addEventListener("__rsc_locationstate", handleLocationState);
+    return () => {
+      window.removeEventListener("popstate", handlePopstate);
+      window.removeEventListener("__rsc_locationstate", handleLocationState);
+    };
+  }, [key, isFlash]);
+
+  // Flash: clear from history.state after paint so subsequent navigations don't see it.
+  // Depends on `state` so it re-runs when state is set via the event listener.
+  useEffect(() => {
+    if (isFlash && key && state !== undefined) {
+      const cleaned = { ...window.history.state };
+      delete cleaned[key];
+      window.history.replaceState(cleaned, "", window.location.href);
+    }
+  }, [isFlash, key, state]);
 
   return state;
 }

package/src/browser/react/mount-context.ts

@@ -1,6 +1,11 @@
 "use client";
 
-import { createContext, createElement, type Context, type ReactNode } from "react";
+import {
+  createContext,
+  createElement,
+  type Context,
+  type ReactNode,
+} from "react";
 
 /**
  * Context for the current include() mount path.

package/src/browser/react/nonce-context.ts

@@ -0,0 +1,23 @@
+"use client";
+
+/**
+ * Context for CSP nonce propagation to client components during SSR.
+ *
+ * The SSR renderer wraps the tree with NonceContext.Provider so that
+ * client components (e.g. MetaTags) can apply nonces to inline scripts.
+ * On the browser side, no provider is needed — the default undefined
+ * is correct since CSP nonces are a server-side HTML concern.
+ */
+
+import { createContext, useContext, type Context } from "react";
+
+export const NonceContext: Context<string | undefined> = createContext<
+  string | undefined
+>(undefined);
+
+/**
+ * Read the CSP nonce during SSR. Returns undefined on the client.
+ */
+export function useNonce(): string | undefined {
+  return useContext(NonceContext);
+}

package/src/browser/react/shallow-equal.ts

@@ -0,0 +1,27 @@
+/**
+ * Shallow equality check for selector results.
+ * Uses Object.is for value comparison (handles NaN and +-0 correctly).
+ */
+export function shallowEqual<T>(a: T, b: T): boolean {
+  if (Object.is(a, b)) return true;
+  if (
+    typeof a !== "object" ||
+    a === null ||
+    typeof b !== "object" ||
+    b === null
+  ) {
+    return false;
+  }
+  const keysA = Object.keys(a);
+  const keysB = Object.keys(b);
+  if (keysA.length !== keysB.length) return false;
+  for (const key of keysA) {
+    if (
+      !Object.hasOwn(b, key) ||
+      !Object.is((a as any)[key], (b as any)[key])
+    ) {
+      return false;
+    }
+  }
+  return true;
+}