@bleedingdev/modern-js-runtime-extensions 3.9.0-ultramodern.4 → 3.9.0-ultramodern.5

package/src/routerProvider.ts

@@ -0,0 +1,340 @@
+// @effect-diagnostics globalConsole:off
+import { merge } from '@modern-js/runtime-utils/merge';
+
+/** Structural plugin contract; the composing integration supplies native hooks. */
+export type RouterProviderPlugin = {
+  name?: string;
+  registryHooks?: Record<string, unknown>;
+  setup?: (api: any) => unknown;
+  [key: string]: unknown;
+};
+
+/**
+ * Guard for the wrapper plugin (`router/internal`): a resolved provider is
+ * only invoked through `setup`, so registry hooks outside the canonical
+ * router hook contract cannot be registered for it. Returns the offending
+ * hook names and warns once so they are surfaced instead of silently dropped.
+ */
+export function reportUnsupportedProviderRegistryHooks(
+  providerPlugin: {
+    name?: string;
+    registryHooks?: Record<string, unknown>;
+  },
+  routerProviderRegistryHooks: Record<string, unknown>,
+): string[] {
+  const unsupportedHookNames = Object.keys(
+    providerPlugin.registryHooks ?? {},
+  ).filter(hookName => !(hookName in routerProviderRegistryHooks));
+
+  if (unsupportedHookNames.length > 0) {
+    console.warn(
+      `[@modern-js/runtime] The router provider "${providerPlugin.name}" declares registry hooks outside the router hook contract: ${unsupportedHookNames.join(
+        ', ',
+      )}. These hooks are not registered when the provider is resolved through \`runtime.router.framework\` — declare them on a separate runtime plugin instead.`,
+    );
+  }
+
+  return unsupportedHookNames;
+}
+
+export type RouterProviderFactory = (userConfig?: any) => RouterProviderPlugin;
+
+export type RouterProviderRegistration = {
+  name: string;
+  factory: RouterProviderFactory;
+  isDefault?: boolean;
+};
+
+/**
+ * App-owned provider catalog. Provider factories close over their module graph,
+ * so they must be resolved from the runtime wrapper that owns the app instead
+ * of from a page-global first-registration winner.
+ */
+export type RouterProviderRealm = Readonly<{
+  defaultProvider?: string;
+  get: (name: string) => RouterProviderFactory | undefined;
+  names: () => readonly string[];
+}>;
+
+export function createRouterProviderRealm(
+  registrations: readonly RouterProviderRegistration[],
+): RouterProviderRealm {
+  const providers = new Map<string, RouterProviderFactory>();
+  let defaultProvider: string | undefined;
+
+  for (const registration of registrations) {
+    if (registration.name.length === 0) {
+      throw new Error(
+        '[@modern-js/runtime] A router provider realm cannot contain an unnamed provider.',
+      );
+    }
+    if (providers.has(registration.name)) {
+      throw new Error(
+        `[@modern-js/runtime] Router provider "${registration.name}" is declared more than once in the same runtime realm.`,
+      );
+    }
+    if (
+      registration.isDefault === true &&
+      defaultProvider !== undefined &&
+      defaultProvider !== registration.name
+    ) {
+      throw new Error(
+        `[@modern-js/runtime] Router provider realm declares both "${defaultProvider}" and "${registration.name}" as defaults.`,
+      );
+    }
+
+    providers.set(registration.name, registration.factory);
+    if (registration.isDefault === true) {
+      defaultProvider = registration.name;
+    }
+  }
+
+  const providerNames = Object.freeze([...providers.keys()]);
+  return Object.freeze({
+    ...(defaultProvider !== undefined ? { defaultProvider } : {}),
+    get: (name: string) => providers.get(name),
+    names: () => providerNames,
+  });
+}
+
+type RouterProviderRegistry = {
+  providers: Map<string, RouterProviderFactory>;
+  defaultProvider?: string;
+  /** Names that were registered by more than one module instance. */
+  duplicateProviders: Set<string>;
+  /** Duplicate names already reported when the compatibility fallback won. */
+  warnedDuplicates: Set<string>;
+};
+
+/**
+ * Versioned compatibility-registry key. The unsuffixed key
+ * ('@modern-js/runtime:router-providers') is owned by older published copies
+ * of this module whose `registerRouterProvider` *throws* on a same-name
+ * re-registration. `:v2` added keep-first registration but also enforced one
+ * non-default provider across the whole JavaScript realm. `:v3` removes that
+ * page-global app invariant: explicit runtime realms own provider selection,
+ * while this registry remains only a mixed-version fallback. New copies read
+ * but never mutate the v2 slot so older published copies remain compatible.
+ */
+const REGISTRY_SLOT: unique symbol = Symbol.for(
+  '@modern-js/runtime:router-providers:v3',
+);
+const LEGACY_V2_REGISTRY_SLOT: unique symbol = Symbol.for(
+  '@modern-js/runtime:router-providers:v2',
+);
+
+function getRegistry(): RouterProviderRegistry {
+  const host = globalThis as { [REGISTRY_SLOT]?: RouterProviderRegistry };
+  host[REGISTRY_SLOT] ??= {
+    providers: new Map(),
+    duplicateProviders: new Set(),
+    warnedDuplicates: new Set(),
+  };
+  // Defense in depth within the v3 key: if a future v3-keyed copy of this
+  // module ever predates a later-added field (mixed v3 minors in a Module
+  // Federation setup), heal the shape instead of crashing on `undefined`.
+  host[REGISTRY_SLOT].duplicateProviders ??= new Set();
+  host[REGISTRY_SLOT].warnedDuplicates ??= new Set();
+  return host[REGISTRY_SLOT];
+}
+
+function getLegacyV2Registry():
+  | Pick<RouterProviderRegistry, 'providers' | 'defaultProvider'>
+  | undefined {
+  const host = globalThis as {
+    [LEGACY_V2_REGISTRY_SLOT]?: Pick<
+      RouterProviderRegistry,
+      'providers' | 'defaultProvider'
+    >;
+  };
+  return host[LEGACY_V2_REGISTRY_SLOT];
+}
+
+export function registerRouterProvider(
+  name: string,
+  factory: RouterProviderFactory,
+  options: { isDefault?: boolean } = {},
+): void {
+  const registry = getRegistry();
+  const existing = registry.providers.get(name);
+
+  if (existing !== undefined) {
+    // Keep-first semantics. A same-name re-registration with a *different*
+    // factory is almost always two bundled copies of the same provider
+    // module — e.g. a Module Federation remote that does not share
+    // '@modern-js/plugin-tanstack/runtime' evaluates its own copy, which
+    // creates a fresh factory function per evaluation. That must not crash
+    // the app; the first registration remains available for compatibility.
+    // Merely loading independent app-owned realms is valid, so defer the
+    // warning until a caller actually consumes this ambiguous fallback.
+    if (existing !== factory) {
+      registry.duplicateProviders.add(name);
+    }
+    return;
+  }
+
+  if (options.isDefault === true) {
+    registry.defaultProvider = name;
+  }
+
+  registry.providers.set(name, factory);
+}
+
+export function resolveRouterProvider(
+  framework?: string,
+  options: {
+    /**
+     * Provider factories owned by the resolving app/runtime wrapper. A realm
+     * is the exclusive provider source when supplied because its factories
+     * close over the correct app module graph.
+     */
+    realm?: RouterProviderRealm;
+    /**
+     * Legacy single-provider override retained for published wrappers. New
+     * integrations should pass an app-owned `realm`, which supports every
+     * provider rather than only the default.
+     */
+    localDefault?: { name: string; factory: RouterProviderFactory };
+  } = {},
+): RouterProviderFactory {
+  if (options.realm !== undefined) {
+    const name = framework || options.realm.defaultProvider;
+    const realmProviderNames = options.realm.names();
+
+    if (name === undefined) {
+      throw new Error(
+        `[@modern-js/runtime] The app-owned router provider realm does not declare a default provider. Available realm providers: ${
+          realmProviderNames.join(', ') || '(none)'
+        }.`,
+      );
+    }
+
+    const factory = options.realm.get(name);
+    if (factory === undefined) {
+      throw new Error(
+        `[@modern-js/runtime] Router provider "${name}" is not registered in the app-owned router provider realm. ` +
+          `Available realm providers: ${
+            realmProviderNames.join(', ') || '(none)'
+          }. Compatibility registry fallback is disabled for app-owned realms.`,
+      );
+    }
+
+    return factory;
+  }
+
+  const registry = getRegistry();
+  const legacyV2Registry = getLegacyV2Registry();
+  // `||` on purpose: a falsy framework value (empty string from env
+  // templating, `false`, `undefined`) falls back to the default provider
+  // instead of erroring on an unknown framework "". Prefer the older
+  // localDefault contract before compatibility slots.
+  const name =
+    framework ||
+    options.localDefault?.name ||
+    registry.defaultProvider ||
+    legacyV2Registry?.defaultProvider;
+
+  if (name === undefined) {
+    throw new Error(
+      '[@modern-js/runtime] No default router provider is registered. This is a bug in the runtime setup.',
+    );
+  }
+
+  if (
+    options.localDefault !== undefined &&
+    name === options.localDefault.name
+  ) {
+    return options.localDefault.factory;
+  }
+
+  const factory = registry.providers.get(name);
+  if (factory !== undefined) {
+    if (
+      registry.duplicateProviders.has(name) &&
+      !registry.warnedDuplicates.has(name)
+    ) {
+      registry.warnedDuplicates.add(name);
+      console.warn(
+        `[@modern-js/runtime] The router provider "${name}" was registered more than once with different module instances, and a router wrapper without an app-owned provider realm is resolving the mixed-version compatibility fallback. The fallback is keeping the first registration. ` +
+          'Modern router wrappers isolate app-owned realms automatically. ' +
+          'For an older wrapper, share the provider runtime between Module Federation host and remotes or upgrade every app to a realm-aware runtime.',
+      );
+    }
+    return factory;
+  }
+
+  const legacyV2Factory = legacyV2Registry?.providers.get(name);
+  if (legacyV2Factory !== undefined) {
+    return legacyV2Factory;
+  }
+
+  if (name === 'tanstack') {
+    throw new Error(
+      '[@modern-js/runtime] `runtime.router.framework` is set to "tanstack", but no TanStack router provider is registered. ' +
+        'Install @modern-js/plugin-tanstack, add `tanstackRouterPlugin()` to the `plugins` array in modern.config.ts, ' +
+        "and make sure '@modern-js/plugin-tanstack/runtime' is imported (e.g. in modern.runtime.ts).",
+    );
+  }
+
+  throw new Error(
+    `[@modern-js/runtime] Unknown router framework "${name}". ` +
+      `Registered providers: ${
+        [
+          ...new Set([
+            ...registry.providers.keys(),
+            ...(legacyV2Registry?.providers.keys() ?? []),
+          ]),
+        ].join(', ') || '(none)'
+      }. Install and register the plugin that provides this router framework.`,
+  );
+}
+
+/**
+ * Test-only escape hatch: compatibility registries live on `globalThis`, so
+ * unit tests need a way to restore a pristine state between cases.
+ */
+export function unsafe_resetRouterProvidersForTesting(): void {
+  const host = globalThis as {
+    [REGISTRY_SLOT]?: RouterProviderRegistry;
+    [LEGACY_V2_REGISTRY_SLOT]?: unknown;
+  };
+  delete host[REGISTRY_SLOT];
+  delete host[LEGACY_V2_REGISTRY_SLOT];
+}
+
+/** Compose app-owned providers without importing the native runtime graph. */
+export function createRouterPlugin<Hooks extends Record<string, unknown>>({
+  defaultProvider,
+  registryHooks,
+  localProviders = [],
+}: {
+  defaultProvider: { name: string; factory: RouterProviderFactory };
+  registryHooks: Hooks;
+  localProviders?: readonly Omit<RouterProviderRegistration, 'isDefault'>[];
+}) {
+  registerRouterProvider(defaultProvider.name, defaultProvider.factory, {
+    isDefault: true,
+  });
+  const realm = createRouterProviderRealm([
+    { ...defaultProvider, isDefault: true },
+    ...localProviders,
+  ]);
+
+  return (userConfig: Record<string, any> = {}) => ({
+    name: '@modern-js/plugin-router',
+    registryHooks,
+    setup(api: {
+      getRuntimeConfig: () => { router?: Record<string, unknown> };
+      [key: string]: any;
+    }) {
+      const mergedConfig = merge(
+        api.getRuntimeConfig().router || {},
+        userConfig,
+      );
+      const factory = resolveRouterProvider(mergedConfig.framework, { realm });
+      const provider = factory(userConfig);
+      reportUnsupportedProviderRegistryHooks(provider, registryHooks);
+      provider.setup?.(api);
+    },
+  });
+}

package/src/routerState.ts

@@ -0,0 +1,208 @@
+// @effect-diagnostics asyncFunction:off strictBooleanExpressions:off
+import { createRuntimeContextExtension } from './contextExtensions';
+import type {
+  InternalRouterRuntimeState,
+  InternalRouterServerSnapshot,
+  RouterRouteMatchSnapshot,
+  RouterServerPrepareResult,
+} from './routerStateTypes';
+
+export type {
+  BuiltInRouterFramework,
+  InternalRouterRuntimeState,
+  InternalRouterServerSnapshot,
+  RouterFramework,
+  RouterLifecyclePhase,
+  RouterRouteMatchSnapshot,
+  RouterServerPrepareResult,
+} from './routerStateTypes';
+
+/**
+ * Router runtime state is shared by every router provider (react-router,
+ * @modern-js/plugin-tanstack, ...) and consumed by the SSR pipeline. It lives
+ * in the runtime-context extension slot instead of ad-hoc fields on
+ * `TInternalRuntimeContext`.
+ */
+const routerRuntimeStateExtension =
+  createRuntimeContextExtension<InternalRouterRuntimeState>(
+    '@modern-js/runtime:router-runtime-state',
+  );
+
+/**
+ * The server snapshot is tracked separately: a later
+ * `applyRouterRuntimeState` call without a snapshot must not clear a
+ * previously captured one.
+ */
+const routerServerSnapshotExtension =
+  createRuntimeContextExtension<InternalRouterServerSnapshot>(
+    '@modern-js/runtime:router-server-snapshot',
+  );
+
+export function getRouterRuntimeState(
+  runtimeContext: object,
+): InternalRouterRuntimeState | undefined {
+  return routerRuntimeStateExtension.get(runtimeContext);
+}
+
+export function getRouterServerSnapshot(
+  runtimeContext: object,
+): InternalRouterServerSnapshot | undefined {
+  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;
+}
+
+export function createRouterServerSnapshot(
+  state: RouterSnapshotLike,
+): InternalRouterServerSnapshot {
+  const hydrationScripts = toHydrationScripts(state);
+  const matchedRouteIds =
+    state.matchedRouteIds ?? getMatchedRouteIdsFromMatches(state.matches);
+
+  return {
+    ...state,
+    ...(hydrationScripts?.length
+      ? {
+          hydrationScript: state.hydrationScript ?? hydrationScripts[0],
+          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
+      ? {
+          hydrationScript: state.hydrationScript ?? hydrationScripts[0],
+          hydrationScripts,
+        }
+      : {}),
+    ...(matchedRouteIds ? { matchedRouteIds } : {}),
+    ...(serverSnapshot ? { serverSnapshot } : {}),
+  };
+}
+
+export function applyRouterRuntimeState<Context extends object>(
+  runtimeContext: Context,
+  state: InternalRouterRuntimeState,
+) {
+  const normalized = createRouterRuntimeState(state);
+  routerRuntimeStateExtension.set(runtimeContext, normalized);
+  if (normalized.serverSnapshot) {
+    routerServerSnapshotExtension.set(
+      runtimeContext,
+      normalized.serverSnapshot,
+    );
+  }
+
+  return runtimeContext;
+}
+
+export function applyRouterServerPrepareResult<Context extends object>(
+  runtimeContext: Context,
+  result: RouterServerPrepareResult,
+) {
+  const state = createRouterRuntimeState({
+    ...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,
+    }) ??
+    []
+  );
+}
+
+export function getRouterMatchedRouteIds(runtimeContext: object) {
+  const serverSnapshot = getRouterServerSnapshot(runtimeContext);
+  const runtimeState = getRouterRuntimeState(runtimeContext);
+  return (
+    serverSnapshot?.matchedRouteIds ??
+    getMatchedRouteIdsFromMatches(serverSnapshot?.matches) ??
+    runtimeState?.matchedRouteIds ??
+    getMatchedRouteIdsFromMatches(runtimeState?.matches)
+  );
+}
+
+export async function cleanupRouterRuntimeState(runtimeContext: object) {
+  try {
+    await getRouterRuntimeState(runtimeContext)?.cleanup?.();
+  } catch {}
+}

package/src/routerStatePlugin.ts

@@ -0,0 +1,86 @@
+import { createRouterPrefetchPolicy } from './routerPrefetchPolicy';
+import {
+  applyRouterRuntimeState,
+  createRouterServerSnapshot,
+} from './routerState';
+
+type ReactRouterServerContext = {
+  statusCode: number;
+  errors?: Record<string, unknown> | null;
+  loaderData: Record<string, unknown>;
+  matches: { route: { id?: string } }[];
+};
+
+type RouterLifecycleEvent = {
+  framework: string;
+  phase: string;
+  runtimeContext: object;
+  basename?: string;
+  router?: unknown;
+};
+
+/** Install fork policy through lifecycle hooks supplied by the native owner. */
+export function createRouterStatePlugin<Hooks extends Record<string, unknown>>({
+  registryHooks,
+}: {
+  registryHooks: Hooks;
+}) {
+  return {
+    name: '@modern-js/router-runtime-policy',
+    registryHooks,
+    setup(api: {
+      onBeforeRender: (callback: (context: object) => void) => unknown;
+      onAfterCreateRouter: (
+        callback: (event: RouterLifecycleEvent) => void,
+      ) => unknown;
+    }) {
+      api.onBeforeRender(context => {
+        const runtimeContext = context as {
+          linkPrefetchPolicy?: ReturnType<typeof createRouterPrefetchPolicy>;
+        };
+        runtimeContext.linkPrefetchPolicy ??= createRouterPrefetchPolicy();
+      });
+      api.onAfterCreateRouter(event => {
+        if (event.framework !== 'react-router') {
+          return;
+        }
+        if (event.phase === 'ssr-prepare') {
+          const { routerContext } = event.runtimeContext as {
+            routerContext?: ReactRouterServerContext;
+          };
+          if (!routerContext) {
+            return;
+          }
+          const serverSnapshot = createRouterServerSnapshot({
+            framework: event.framework,
+            basename: event.basename,
+            statusCode: routerContext.statusCode,
+            errors: routerContext.errors ?? undefined,
+            routerData: {
+              loaderData: routerContext.loaderData,
+              errors: routerContext.errors ?? undefined,
+            },
+            matches: routerContext.matches.flatMap(match =>
+              typeof match.route.id === 'string'
+                ? [{ routeId: match.route.id }]
+                : [],
+            ),
+          });
+          applyRouterRuntimeState(event.runtimeContext, {
+            framework: event.framework,
+            basename: event.basename,
+            instance: event.router,
+            matchedRouteIds: serverSnapshot.matchedRouteIds,
+            serverSnapshot,
+          });
+        } else if (event.phase === 'client-create') {
+          applyRouterRuntimeState(event.runtimeContext, {
+            framework: event.framework,
+            basename: event.basename,
+            instance: event.router,
+          });
+        }
+      });
+    },
+  };
+}

package/src/routerStateTypes.ts

@@ -0,0 +1,46 @@
+export type BuiltInRouterFramework = 'react-router' | 'tanstack';
+
+export type RouterFramework = BuiltInRouterFramework | (string & {});
+
+export interface RouterRouteMatchSnapshot {
+  routeId: string;
+  assetRouteId?: string;
+  pathname?: string;
+  params?: Record<string, string>;
+}
+
+export interface InternalRouterServerSnapshot {
+  framework?: RouterFramework;
+  basename?: string;
+  statusCode?: number;
+  errors?: Record<string, unknown>;
+  routerData?: {
+    loaderData?: Record<string, unknown>;
+    errors?: Record<string, unknown>;
+  };
+  hydrationScript?: string;
+  hydrationScripts?: string[];
+  matchedRouteIds?: string[];
+  matches?: RouterRouteMatchSnapshot[];
+}
+
+export interface InternalRouterRuntimeState {
+  framework: RouterFramework;
+  basename?: string;
+  instance?: unknown;
+  hydrationScript?: string;
+  hydrationScripts?: string[];
+  matchedRouteIds?: string[];
+  matches?: RouterRouteMatchSnapshot[];
+  serverSnapshot?: InternalRouterServerSnapshot;
+  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';