@bleedingdev/modern-js-runtime-extensions 3.8.3-ultramodern.6 → 3.9.0-ultramodern.10

package/src/routeHydration.ts

@@ -0,0 +1,208 @@
+import { escapeHtmlAttribute } from './html';
+
+type RouteAssetManifest = {
+  assets?: string[];
+};
+
+export type RouteManifestLike = {
+  routeAssets?: Record<string, RouteAssetManifest | undefined>;
+};
+
+type ScriptTagMatch = {
+  index: number;
+  tag: string;
+  src: string;
+};
+
+export type ScriptChunkLike = {
+  filename?: string;
+  url?: string;
+};
+
+function getScriptTags(template: string): ScriptTagMatch[] {
+  const scriptRegExp = /<script\b[^>]*\bsrc=(["'])(.*?)\1[^>]*><\/script>/g;
+  return Array.from(template.matchAll(scriptRegExp)).map(match => ({
+    index: match.index ?? 0,
+    tag: match[0],
+    src: match[2],
+  }));
+}
+
+function getAssetBasename(src: string) {
+  const withoutQuery = src.split(/[?#]/)[0];
+  return withoutQuery.split('/').pop() || withoutQuery;
+}
+
+function isEntryScript(src: string, entryName: string, asyncEntry: boolean) {
+  const basename = getAssetBasename(src);
+  const prefix = asyncEntry ? `async-${entryName}` : entryName;
+  return (
+    basename === `${prefix}.js` ||
+    basename.startsWith(`${prefix}.`) ||
+    basename.startsWith(`${prefix}-`)
+  );
+}
+
+const dedupeByUrl = <T extends ScriptChunkLike>(chunks: T[]) => {
+  const seen = new Set<string>();
+  return chunks.filter(chunk => {
+    if (chunk.url === undefined || chunk.url === '' || seen.has(chunk.url)) {
+      return false;
+    }
+    seen.add(chunk.url);
+    return true;
+  });
+};
+
+const isAsyncEntryScriptChunk = (chunk: ScriptChunkLike, entryName: string) => {
+  if (chunk.url === undefined || !chunk.url.endsWith('.js')) {
+    return false;
+  }
+
+  const asyncEntryName = `async-${entryName}`;
+  const filename = chunk.filename ?? chunk.url;
+  const basename = filename.split('/').pop() ?? filename;
+  return (
+    basename === `${asyncEntryName}.js` ||
+    basename.startsWith(`${asyncEntryName}.`) ||
+    basename.startsWith(`${asyncEntryName}-`)
+  );
+};
+
+export function getMatchedRouteChunks<T>(
+  routeManifest: RouteManifestLike | undefined,
+  matchedRouteIds: string[],
+  routeAssetToChunk: (asset: string) => T,
+): T[] {
+  const routeAssets = routeManifest?.routeAssets;
+  if (routeAssets === undefined) {
+    return [];
+  }
+
+  return matchedRouteIds
+    .flatMap(routeId => routeAssets[routeId]?.assets ?? [])
+    .map(routeAssetToChunk);
+}
+
+export const orderHydrationScriptChunks = <T extends ScriptChunkLike>({
+  asyncEntryChunks,
+  collectedChunks,
+  matchedRouteChunks,
+  entryName,
+}: {
+  asyncEntryChunks: T[];
+  collectedChunks: T[];
+  matchedRouteChunks: T[];
+  entryName: string;
+}) => {
+  const asyncEntryScriptChunks: T[] = [];
+  const asyncEntryDependencyChunks: T[] = [];
+
+  for (const chunk of asyncEntryChunks) {
+    if (isAsyncEntryScriptChunk(chunk, entryName)) {
+      asyncEntryScriptChunks.push(chunk);
+    } else {
+      asyncEntryDependencyChunks.push(chunk);
+    }
+  }
+
+  return dedupeByUrl([
+    ...asyncEntryDependencyChunks,
+    ...collectedChunks,
+    ...matchedRouteChunks,
+    ...asyncEntryScriptChunks,
+  ]);
+};
+
+export function injectBeforeHydrationEntryScript(
+  template: string,
+  scripts: string,
+  entryName = 'index',
+) {
+  if (scripts === '') {
+    return template;
+  }
+
+  const scriptTags = getScriptTags(template);
+  const target =
+    scriptTags.find(match => isEntryScript(match.src, entryName, false)) ??
+    scriptTags.find(match => isEntryScript(match.src, entryName, true));
+
+  if (target === undefined) {
+    return template;
+  }
+
+  return `${template.slice(0, target.index)}${scripts}${template.slice(
+    target.index,
+  )}`;
+}
+
+export function replaceChunkJsPlaceholder(
+  template: string,
+  scripts: string,
+  entryName: string | undefined,
+  placeholder: string,
+) {
+  if (!template.includes(placeholder)) {
+    return template;
+  }
+
+  if (scripts === '') {
+    return template.replace(placeholder, () => '');
+  }
+
+  const withoutPlaceholder = template.replace(placeholder, () => '');
+  const withEarlyScripts = injectBeforeHydrationEntryScript(
+    withoutPlaceholder,
+    scripts,
+    entryName,
+  );
+
+  if (withEarlyScripts !== withoutPlaceholder) {
+    return withEarlyScripts;
+  }
+
+  return template.replace(placeholder, () => scripts);
+}
+
+export function createRouteHydrationScriptTags(
+  routeManifest: RouteManifestLike | undefined,
+  matchedRouteIds: string[],
+  entryName: string,
+  options: {
+    nonce?: string;
+    template?: string;
+  } = {},
+) {
+  const { nonce, template } = options;
+  const routeAssets = routeManifest?.routeAssets;
+  if (routeAssets === undefined) {
+    return '';
+  }
+  const existingScriptSrcs =
+    template === undefined
+      ? new Set<string>()
+      : new Set(getScriptTags(template).map(({ src }) => src));
+
+  const jsAssets = Array.from(
+    new Set(
+      [
+        ...getMatchedRouteChunks(
+          routeManifest,
+          matchedRouteIds,
+          asset => asset,
+        ),
+        ...(routeAssets[`async-${entryName}`]?.assets ?? []),
+      ].filter((asset: string) => asset.endsWith('.js')),
+    ),
+  );
+  return jsAssets
+    .filter(asset => !existingScriptSrcs.has(asset))
+    .map(
+      asset =>
+        `<script src="${escapeHtmlAttribute(asset)}"${
+          nonce ? ` nonce="${escapeHtmlAttribute(nonce)}"` : ''
+        }></script>`,
+    )
+    .join(' ');
+}

package/src/routerPrefetchPolicy.ts

@@ -0,0 +1,195 @@
+import { getNavigationWarmupCacheKey } from './navigationWarmup';
+import { normalizePreloadBehavior } from './prefetchPolicy';
+
+type PrefetchBehavior = 'intent' | 'render' | 'viewport' | 'none';
+type PrefetchState = { code: boolean; data: boolean };
+
+type NetworkInformationLike = {
+  saveData?: boolean;
+  effectiveType?: string;
+};
+
+type WarmupTask = {
+  key: string;
+  run: () => Promise<unknown>;
+  cancelled: boolean;
+};
+
+const INTENT_DELAY = 100;
+const VIEWPORT_ROOT_MARGIN = '200px';
+const MAX_CONCURRENT_WARMUPS = 4;
+const WARMUP_TTL = 30_000;
+
+/** Policy-only contract: native links supply elements, route inputs and loads. */
+export function createRouterPrefetchPolicy() {
+  const cache = new Map<string, number>();
+  const queue: WarmupTask[] = [];
+  let activeWarmups = 0;
+
+  const canWarmup = () => {
+    const navigator = globalThis.navigator as
+      | (Navigator & {
+          connection?: NetworkInformationLike;
+          mozConnection?: NetworkInformationLike;
+          webkitConnection?: NetworkInformationLike;
+        })
+      | undefined;
+    const connection =
+      navigator?.connection ||
+      navigator?.mozConnection ||
+      navigator?.webkitConnection;
+    return (
+      !connection?.saveData &&
+      connection?.effectiveType !== 'slow-2g' &&
+      connection?.effectiveType !== '2g'
+    );
+  };
+
+  const runNext = () => {
+    while (activeWarmups < MAX_CONCURRENT_WARMUPS && queue.length > 0) {
+      const task = queue.shift()!;
+      if (task.cancelled) {
+        continue;
+      }
+      activeWarmups += 1;
+      task
+        .run()
+        .catch(() => {
+          cache.delete(task.key);
+        })
+        .finally(() => {
+          activeWarmups -= 1;
+          runNext();
+        });
+    }
+  };
+
+  return {
+    canWarmup,
+    allowData(route: unknown) {
+      return (
+        (route as { handle?: { navigationWarmup?: { data?: boolean } } })
+          ?.handle?.navigationWarmup?.data !== false
+      );
+    },
+    observe({
+      element,
+      prefetch: inputPrefetch,
+      preload: inputPreload,
+      notify,
+    }: {
+      element: HTMLAnchorElement | null;
+      prefetch?: PrefetchBehavior;
+      preload?: PrefetchBehavior | false;
+      notify: (state: PrefetchState) => void;
+    }) {
+      const prefetch = inputPrefetch ?? 'render';
+      const preload = normalizePreloadBehavior(inputPreload, prefetch);
+      let state: PrefetchState = {
+        code: prefetch === 'render' || preload === 'render',
+        data: prefetch === 'render',
+      };
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      let observer: IntersectionObserver | undefined;
+      const update = (next: PrefetchState) => {
+        state = next;
+        notify(state);
+      };
+      const cancelTimer = () => {
+        if (timer !== undefined) {
+          clearTimeout(timer);
+          timer = undefined;
+        }
+      };
+      notify(state);
+
+      if (
+        element &&
+        (prefetch === 'viewport' || preload === 'viewport') &&
+        typeof IntersectionObserver !== 'undefined'
+      ) {
+        observer = new IntersectionObserver(
+          entries => {
+            if (!entries.some(entry => entry.isIntersecting)) {
+              return;
+            }
+            update({
+              code: true,
+              data: state.data || prefetch === 'viewport',
+            });
+            observer?.disconnect();
+          },
+          { rootMargin: VIEWPORT_ROOT_MARGIN },
+        );
+        observer.observe(element);
+      }
+
+      return {
+        onIntent() {
+          if (prefetch !== 'intent' && preload !== 'intent') {
+            return;
+          }
+          if (timer !== undefined) {
+            return;
+          }
+          timer = setTimeout(() => {
+            timer = undefined;
+            update({ code: true, data: state.data || prefetch === 'intent' });
+          }, INTENT_DELAY);
+        },
+        onCancel() {
+          if (prefetch === 'intent' || preload === 'intent') {
+            cancelTimer();
+            update({ code: false, data: false });
+          }
+        },
+        dispose() {
+          cancelTimer();
+          observer?.disconnect();
+        },
+      };
+    },
+    schedule({
+      runtimeContext,
+      chunkLoader,
+      publicPath,
+      key: operationKey,
+      run,
+    }: {
+      runtimeContext: object;
+      chunkLoader: object;
+      publicPath: string;
+      key: string;
+      run: () => Promise<unknown>;
+    }) {
+      if (!canWarmup()) {
+        return () => {};
+      }
+      const now = performance.now();
+      for (const [key, timestamp] of cache) {
+        if (now - timestamp > WARMUP_TTL) {
+          cache.delete(key);
+        }
+      }
+      const key = getNavigationWarmupCacheKey(
+        runtimeContext,
+        chunkLoader,
+        publicPath,
+        operationKey,
+      );
+      if (cache.has(key)) {
+        return () => {};
+      }
+      cache.set(key, now);
+      const task: WarmupTask = { key, run, cancelled: false };
+      queue.push(task);
+      runNext();
+      return () => {
+        task.cancelled = true;
+        if (queue.includes(task)) {
+          cache.delete(key);
+        }
+      };
+    },
+  };
+}

package/src/routerProvider.ts

@@ -0,0 +1,160 @@
+// @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,
+  });
+}
+
+export function resolveRouterProvider(
+  framework: string | undefined,
+  options: { realm: RouterProviderRealm },
+): RouterProviderFactory {
+  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)'
+        }.`,
+    );
+  }
+
+  return factory;
+}
+
+/** 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'>[];
+}) {
+  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);
+    },
+  });
+}