@bleedingdev/modern-js-runtime-extensions 3.9.0-ultramodern.11 → 3.9.0-ultramodern.12

package/src/routerState.ts

@@ -3,7 +3,6 @@ import { createRuntimeContextExtension } from './contextExtensions';
 import type {
   InternalRouterRuntimeState,
   InternalRouterServerSnapshot,
-  RouterRouteMatchSnapshot,
   RouterServerPrepareResult,
 } from './routerStateTypes';
 
@@ -13,6 +12,9 @@ export type {
   InternalRouterServerSnapshot,
   RouterFramework,
   RouterLifecyclePhase,
+  RouterLinkTarget,
+  RouterNavigationCapability,
+  RouterNavigationSnapshot,
   RouterRouteMatchSnapshot,
   RouterServerPrepareResult,
 } from './routerStateTypes';
@@ -50,99 +52,49 @@ export function getRouterServerSnapshot(
   return routerServerSnapshotExtension.get(runtimeContext);
 }
 
-type RouterSnapshotLike = Partial<InternalRouterServerSnapshot>;
-
-function toHydrationScripts(state: {
-  hydrationScript?: string;
-  hydrationScripts?: string[];
-}) {
-  if (state.hydrationScripts?.length) {
-    return state.hydrationScripts;
-  }
-
-  return state.hydrationScript ? [state.hydrationScript] : undefined;
-}
-
-function getMatchedRouteIdsFromMatches(matches?: RouterRouteMatchSnapshot[]) {
-  const routeIds = matches
-    ?.map(match => match.assetRouteId ?? match.routeId)
-    .filter((routeId): routeId is string => typeof routeId === 'string');
-
-  return routeIds?.length ? routeIds : undefined;
-}
-
+/** Capture prepared metadata once; live router updates cannot rewrite it. */
 export function createRouterServerSnapshot(
-  state: RouterSnapshotLike,
+  snapshot: InternalRouterServerSnapshot,
 ): InternalRouterServerSnapshot {
-  const hydrationScripts = toHydrationScripts(state);
+  const matches = snapshot.matches?.map(match =>
+    Object.freeze({
+      ...match,
+      ...(match.params ? { params: Object.freeze({ ...match.params }) } : {}),
+    }),
+  );
   const matchedRouteIds =
-    state.matchedRouteIds ?? getMatchedRouteIdsFromMatches(state.matches);
-
-  return {
-    ...state,
-    ...(hydrationScripts?.length
-      ? {
-          hydrationScript: state.hydrationScript ?? hydrationScripts[0],
-          hydrationScripts,
-        }
+    snapshot.matchedRouteIds ??
+    matches?.map(match => match.assetRouteId ?? match.routeId);
+  return Object.freeze({
+    ...snapshot,
+    ...(snapshot.hydrationScripts
+      ? { hydrationScripts: Object.freeze([...snapshot.hydrationScripts]) }
       : {}),
-    ...(matchedRouteIds ? { matchedRouteIds } : {}),
-  };
-}
-
-export function createRouterRuntimeState(
-  state: InternalRouterRuntimeState,
-): InternalRouterRuntimeState {
-  const hasSnapshotState =
-    Boolean(state.serverSnapshot) ||
-    Boolean(state.hydrationScript) ||
-    Boolean(state.hydrationScripts?.length) ||
-    Boolean(state.matchedRouteIds?.length) ||
-    Boolean(state.matches?.length);
-  const serverSnapshot = state.serverSnapshot
-    ? createRouterServerSnapshot({
-        ...state.serverSnapshot,
-        framework: state.serverSnapshot.framework ?? state.framework,
-        basename: state.serverSnapshot.basename ?? state.basename,
-        hydrationScript:
-          state.serverSnapshot.hydrationScript ?? state.hydrationScript,
-        hydrationScripts:
-          state.serverSnapshot.hydrationScripts ?? state.hydrationScripts,
-        matchedRouteIds:
-          state.serverSnapshot.matchedRouteIds ?? state.matchedRouteIds,
-        matches: state.serverSnapshot.matches ?? state.matches,
-      })
-    : hasSnapshotState
-      ? createRouterServerSnapshot({
-          framework: state.framework,
-          basename: state.basename,
-          hydrationScript: state.hydrationScript,
-          hydrationScripts: state.hydrationScripts,
-          matchedRouteIds: state.matchedRouteIds,
-          matches: state.matches,
-        })
-      : undefined;
-  const hydrationScripts = toHydrationScripts({
-    hydrationScript: state.hydrationScript ?? serverSnapshot?.hydrationScript,
-    hydrationScripts:
-      state.hydrationScripts ?? serverSnapshot?.hydrationScripts,
-  });
-  const matchedRouteIds =
-    state.matchedRouteIds ??
-    serverSnapshot?.matchedRouteIds ??
-    getMatchedRouteIdsFromMatches(state.matches);
-
-  return {
-    ...state,
-    ...(hydrationScripts?.length
+    ...(matchedRouteIds
+      ? { matchedRouteIds: Object.freeze([...matchedRouteIds]) }
+      : {}),
+    ...(matches ? { matches: Object.freeze(matches) } : {}),
+    ...(snapshot.errors
+      ? { errors: Object.freeze({ ...snapshot.errors }) }
+      : {}),
+    ...(snapshot.routerData
       ? {
-          hydrationScript: state.hydrationScript ?? hydrationScripts[0],
-          hydrationScripts,
+          routerData: Object.freeze({
+            ...snapshot.routerData,
+            ...(snapshot.routerData.loaderData
+              ? {
+                  loaderData: Object.freeze({
+                    ...snapshot.routerData.loaderData,
+                  }),
+                }
+              : {}),
+            ...(snapshot.routerData.errors
+              ? { errors: Object.freeze({ ...snapshot.routerData.errors }) }
+              : {}),
+          }),
         }
       : {}),
-    ...(matchedRouteIds ? { matchedRouteIds } : {}),
-    ...(serverSnapshot ? { serverSnapshot } : {}),
-  };
+  });
 }
 
 /**
@@ -223,19 +175,13 @@ export function applyRouterRuntimeState<Context extends object>(
   state: InternalRouterRuntimeState,
 ) {
   const previous = routerRuntimeStateExtension.get(runtimeContext);
-  const normalized = createRouterRuntimeState(state);
-  routerRuntimeStateExtension.set(runtimeContext, normalized);
-  if (normalized.serverSnapshot) {
-    routerServerSnapshotExtension.set(
-      runtimeContext,
-      normalized.serverSnapshot,
-    );
-  }
+  routerRuntimeStateExtension.set(runtimeContext, state);
   // Only a change of identity is worth a re-render; `RouterWrapper` reapplies
   // the same instance on every render of the app.
   if (
-    previous?.instance !== normalized.instance ||
-    previous?.framework !== normalized.framework
+    previous?.instance !== state.instance ||
+    previous?.framework !== state.framework ||
+    previous?.navigation !== state.navigation
   ) {
     notifyRouterRuntimeState(runtimeContext);
   }
@@ -247,40 +193,24 @@ export function applyRouterServerPrepareResult<Context extends object>(
   runtimeContext: Context,
   result: RouterServerPrepareResult,
 ) {
-  const state = createRouterRuntimeState({
+  if (result.snapshot) {
+    routerServerSnapshotExtension.set(
+      runtimeContext,
+      createRouterServerSnapshot(result.snapshot),
+    );
+  }
+  return applyRouterRuntimeState(runtimeContext, {
     ...result.state,
     cleanup: result.cleanup ?? result.state.cleanup,
-    serverSnapshot: result.snapshot ?? result.state.serverSnapshot,
   });
-  applyRouterRuntimeState(runtimeContext, state);
-  return runtimeContext;
 }
 
 export function getRouterHydrationScripts(runtimeContext: object) {
-  const serverSnapshot = getRouterServerSnapshot(runtimeContext);
-  const runtimeState = getRouterRuntimeState(runtimeContext);
-  return (
-    serverSnapshot?.hydrationScripts ??
-    toHydrationScripts({
-      hydrationScript: serverSnapshot?.hydrationScript,
-    }) ??
-    runtimeState?.hydrationScripts ??
-    toHydrationScripts({
-      hydrationScript: runtimeState?.hydrationScript,
-    }) ??
-    []
-  );
+  return getRouterServerSnapshot(runtimeContext)?.hydrationScripts ?? [];
 }
 
 export function getRouterMatchedRouteIds(runtimeContext: object) {
-  const serverSnapshot = getRouterServerSnapshot(runtimeContext);
-  const runtimeState = getRouterRuntimeState(runtimeContext);
-  return (
-    serverSnapshot?.matchedRouteIds ??
-    getMatchedRouteIdsFromMatches(serverSnapshot?.matches) ??
-    runtimeState?.matchedRouteIds ??
-    getMatchedRouteIdsFromMatches(runtimeState?.matches)
-  );
+  return getRouterServerSnapshot(runtimeContext)?.matchedRouteIds;
 }
 
 export async function cleanupRouterRuntimeState(runtimeContext: object) {

package/src/routerStatePlugin.ts

@@ -1,8 +1,13 @@
+import type { createMemoryRouter } from '@modern-js/runtime-utils/router';
 import { createRouterPrefetchPolicy } from './routerPrefetchPolicy';
 import {
   applyRouterRuntimeState,
-  createRouterServerSnapshot,
+  applyRouterServerPrepareResult,
 } from './routerState';
+import type {
+  RouterNavigationCapability,
+  RouterNavigationSnapshot,
+} from './routerStateTypes';
 
 type ReactRouterServerContext = {
   statusCode: number;
@@ -19,6 +24,32 @@ type RouterLifecycleEvent = {
   router?: unknown;
 };
 
+function createReactRouterNavigation(
+  router: ReturnType<typeof createMemoryRouter>,
+  Link: RouterNavigationCapability['Link'],
+): RouterNavigationCapability {
+  let state: typeof router.state | undefined;
+  let snapshot: RouterNavigationSnapshot;
+  return {
+    Link,
+    getSnapshot() {
+      if (state !== router.state) {
+        state = router.state;
+        snapshot = {
+          location: state.location,
+          params: Object.assign(
+            {},
+            ...state.matches.map(match => match.params),
+          ),
+        };
+      }
+      return snapshot;
+    },
+    subscribe: listener => router.subscribe(listener),
+    navigate: (href, options) => router.navigate(href, options),
+  };
+}
+
 /** Install fork policy through lifecycle hooks supplied by the native owner. */
 export function createRouterStatePlugin<Hooks extends Record<string, unknown>>({
   registryHooks,
@@ -51,7 +82,7 @@ export function createRouterStatePlugin<Hooks extends Record<string, unknown>>({
           if (!routerContext) {
             return;
           }
-          const serverSnapshot = createRouterServerSnapshot({
+          const snapshot = {
             framework: event.framework,
             basename: event.basename,
             statusCode: routerContext.statusCode,
@@ -65,19 +96,27 @@ export function createRouterStatePlugin<Hooks extends Record<string, unknown>>({
                 ? [{ routeId: match.route.id }]
                 : [],
             ),
-          });
-          applyRouterRuntimeState(event.runtimeContext, {
-            framework: event.framework,
-            basename: event.basename,
-            instance: event.router,
-            matchedRouteIds: serverSnapshot.matchedRouteIds,
-            serverSnapshot,
+          };
+          applyRouterServerPrepareResult(event.runtimeContext, {
+            snapshot,
+            state: {
+              framework: event.framework,
+              basename: event.basename,
+              instance: event.router,
+            },
           });
         } else if (event.phase === 'client-create') {
+          const router = event.router as ReturnType<typeof createMemoryRouter>;
+          const { router: api } = event.runtimeContext as {
+            router?: { Link?: RouterNavigationCapability['Link'] };
+          };
           applyRouterRuntimeState(event.runtimeContext, {
             framework: event.framework,
             basename: event.basename,
-            instance: event.router,
+            instance: router,
+            ...(api?.Link
+              ? { navigation: createReactRouterNavigation(router, api.Link) }
+              : {}),
           });
         }
       });

package/src/routerStateTypes.ts

@@ -1,3 +1,5 @@
+import type React from 'react';
+
 export type BuiltInRouterFramework = 'react-router' | 'tanstack';
 
 export type RouterFramework = BuiltInRouterFramework | (string & {});
@@ -10,37 +12,65 @@ export interface RouterRouteMatchSnapshot {
 }
 
 export interface InternalRouterServerSnapshot {
-  framework?: RouterFramework;
-  basename?: string;
-  statusCode?: number;
-  errors?: Record<string, unknown>;
-  routerData?: {
-    loaderData?: Record<string, unknown>;
-    errors?: Record<string, unknown>;
+  readonly framework?: RouterFramework;
+  readonly basename?: string;
+  readonly statusCode?: number;
+  readonly errors?: Record<string, unknown>;
+  readonly routerData?: {
+    readonly loaderData?: Record<string, unknown>;
+    readonly errors?: Record<string, unknown>;
   };
-  hydrationScript?: string;
-  hydrationScripts?: string[];
-  matchedRouteIds?: string[];
-  matches?: RouterRouteMatchSnapshot[];
+  readonly hydrationScripts?: readonly string[];
+  readonly matchedRouteIds?: readonly string[];
+  readonly matches?: readonly RouterRouteMatchSnapshot[];
 }
 
 export interface InternalRouterRuntimeState {
   framework: RouterFramework;
   basename?: string;
   instance?: unknown;
-  hydrationScript?: string;
-  hydrationScripts?: string[];
-  matchedRouteIds?: string[];
-  matches?: RouterRouteMatchSnapshot[];
-  serverSnapshot?: InternalRouterServerSnapshot;
+  navigation?: RouterNavigationCapability;
   cleanup?: () => void | Promise<void>;
 }
 
 export interface RouterServerPrepareResult {
   state: InternalRouterRuntimeState;
   snapshot?: InternalRouterServerSnapshot;
-  redirect?: Response;
   cleanup?: () => void | Promise<void>;
 }
 
 export type RouterLifecyclePhase = 'ssr-prepare' | 'client-create' | 'hydrate';
+
+/** Provider-owned browser navigation. Consumers never inspect router internals. */
+export interface RouterNavigationSnapshot {
+  location: { pathname: string; search: string; hash: string };
+  params: Record<string, string>;
+}
+
+export interface RouterLinkTarget {
+  pathname: string;
+  href: string;
+  search?: Record<string, unknown>;
+  hash?: string;
+  hashScrollIntoView?: boolean | ScrollIntoViewOptions;
+  prefetch?: 'intent' | 'render' | 'viewport' | 'none';
+  preload?: unknown;
+}
+
+export interface RouterNavigationCapability {
+  getSnapshot: () => RouterNavigationSnapshot;
+  subscribe: (listener: () => void) => () => void;
+  navigate: (
+    href: string,
+    options?: { replace?: boolean; state?: unknown },
+  ) => void | Promise<void>;
+  Link: React.ComponentType<{
+    to: string;
+    children?: React.ReactNode;
+    [key: string]: unknown;
+  }>;
+  createLinkProps?: (target: RouterLinkTarget) => {
+    to: string;
+    [key: string]: unknown;
+  };
+}