@bleedingdev/modern-js-runtime-extensions 3.9.0-ultramodern.9 → 3.9.3-ultramodern.10

package/src/localisedUrls/routes.ts

@@ -0,0 +1,451 @@
+import {
+  getLeadingLocaleParam,
+  normalisePathPattern,
+  normaliseRoutePath,
+  stripLeadingLocaleParam,
+} from './normalise';
+import {
+  doPathPatternsOverlap,
+  getOrderedPathParamSignature,
+  getPathParamSignature,
+  getPathPatternValidationIssue,
+  getPhysicalPathPattern,
+  haveEqualPatternSpecificity,
+} from './patterns';
+import type {
+  LocalisedRoute,
+  LocalisedUrlPathMap,
+  LocalisedUrlsMap,
+} from './types';
+
+const isLocalisableRoutePath = (path?: string): path is string => {
+  const pathWithoutLocale = stripLeadingLocaleParam(path);
+
+  if (
+    !pathWithoutLocale ||
+    pathWithoutLocale === '/' ||
+    pathWithoutLocale === '*'
+  ) {
+    return false;
+  }
+
+  return true;
+};
+
+const joinPath = (parentPath: string, routePath?: string): string => {
+  if (!isLocalisableRoutePath(routePath)) {
+    return parentPath;
+  }
+
+  const segment = normaliseRoutePath(stripLeadingLocaleParam(routePath) || '');
+  return normalisePathPattern(`${parentPath}/${segment}`);
+};
+
+const isFrameworkInternalRoutePath = (canonicalPath: string) =>
+  canonicalPath === '/_mf' || canonicalPath.startsWith('/_mf/');
+
+const legalRouteIdPart = (value: string): string =>
+  value.replace(/[^a-zA-Z0-9_$-]+/g, '_').replace(/^_+|_+$/g, '') || 'index';
+
+const formatParamSignature = (signature: string[]): string =>
+  signature.length > 0 ? signature.join(', ') : '(none)';
+
+const validateLocalisedUrlPatterns = (
+  languages: string[],
+  localisedUrls: LocalisedUrlsMap,
+) => {
+  const physicalPatterns = new Map<
+    string,
+    { canonicalPath: string; source: string }
+  >();
+  const claimedPatterns: Array<{
+    canonicalPath: string;
+    pattern: string;
+    source: string;
+  }> = [];
+
+  const claimPhysicalPattern = (
+    sourcePattern: string,
+    canonicalPath: string,
+    source: string,
+  ) => {
+    const physicalPattern = getPhysicalPathPattern(sourcePattern);
+    const existing = physicalPatterns.get(physicalPattern);
+    if (existing && existing.canonicalPath !== canonicalPath) {
+      throw new Error(
+        `localisedUrls["${existing.canonicalPath}"] ${existing.source} and localisedUrls["${canonicalPath}"] ${source} generate the same physical route pattern "${physicalPattern}". Localised route patterns must identify exactly one canonical route.`,
+      );
+    }
+
+    const overlapping = claimedPatterns.find(
+      claimed =>
+        claimed.canonicalPath !== canonicalPath &&
+        haveEqualPatternSpecificity(claimed.pattern, sourcePattern) &&
+        doPathPatternsOverlap(claimed.pattern, sourcePattern),
+    );
+    if (overlapping) {
+      throw new Error(
+        `localisedUrls["${overlapping.canonicalPath}"] ${overlapping.source} pattern "${overlapping.pattern}" and localisedUrls["${canonicalPath}"] ${source} pattern "${sourcePattern}" are equal-specificity overlapping route patterns. Localised route patterns must identify exactly one canonical route.`,
+      );
+    }
+
+    physicalPatterns.set(physicalPattern, { canonicalPath, source });
+    claimedPatterns.push({ canonicalPath, pattern: sourcePattern, source });
+  };
+
+  for (const [canonicalPath, entry] of Object.entries(localisedUrls).sort(
+    ([left], [right]) => (left < right ? -1 : left > right ? 1 : 0),
+  )) {
+    const canonicalIssue = getPathPatternValidationIssue(canonicalPath);
+    if (canonicalIssue) {
+      throw new Error(
+        `localisedUrls["${canonicalPath}"] canonical pattern has ${canonicalIssue}.`,
+      );
+    }
+    const expectedSignature = getPathParamSignature(canonicalPath);
+    const expectedOrderedSignature =
+      getOrderedPathParamSignature(canonicalPath);
+    claimPhysicalPattern(canonicalPath, canonicalPath, 'canonical pattern');
+
+    for (const language of languages) {
+      const localisedPattern = entry[language];
+      if (!localisedPattern) {
+        continue;
+      }
+
+      const localisedIssue = getPathPatternValidationIssue(localisedPattern);
+      if (localisedIssue) {
+        throw new Error(
+          `localisedUrls["${canonicalPath}"].${language} has ${localisedIssue}.`,
+        );
+      }
+
+      const actualSignature = getPathParamSignature(localisedPattern);
+      if (
+        actualSignature.length !== expectedSignature.length ||
+        actualSignature.some(
+          (parameter, index) => parameter !== expectedSignature[index],
+        )
+      ) {
+        throw new Error(
+          `localisedUrls["${canonicalPath}"].${language} must use the same parameter signature as "${canonicalPath}": expected ${formatParamSignature(
+            expectedSignature,
+          )}; received ${formatParamSignature(actualSignature)}.`,
+        );
+      }
+
+      const actualOrderedSignature =
+        getOrderedPathParamSignature(localisedPattern);
+      if (
+        expectedOrderedSignature.some(
+          parameter => parameter === '*' || parameter.endsWith('?'),
+        ) &&
+        actualOrderedSignature.some(
+          (parameter, index) => parameter !== expectedOrderedSignature[index],
+        )
+      ) {
+        throw new Error(
+          `localisedUrls["${canonicalPath}"].${language} must keep optional and splat parameters in canonical order: expected ${formatParamSignature(
+            expectedOrderedSignature,
+          )}; received ${formatParamSignature(actualOrderedSignature)}.`,
+        );
+      }
+
+      claimPhysicalPattern(localisedPattern, canonicalPath, `.${language}`);
+    }
+  }
+};
+
+const ensureLocalisedUrlsForPath = (
+  canonicalPath: string,
+  languages: string[],
+  localisedUrls: LocalisedUrlsMap,
+): LocalisedUrlPathMap => {
+  const entry = localisedUrls[canonicalPath];
+  if (!entry) {
+    throw new Error(
+      `localisedUrls is enabled, but route "${canonicalPath}" does not define localised URLs for languages: ${languages.join(
+        ', ',
+      )}. Add localisedUrls["${canonicalPath}"] or set localeDetection.localisedUrls to false.`,
+    );
+  }
+
+  const missingLanguages = languages.filter(language => !entry[language]);
+  if (missingLanguages.length > 0) {
+    throw new Error(
+      `localisedUrls["${canonicalPath}"] is missing languages: ${missingLanguages.join(
+        ', ',
+      )}. Every configured language must have a localised URL.`,
+    );
+  }
+
+  return entry;
+};
+
+export const validateLocalisedUrls = (
+  routes: LocalisedRoute[],
+  languages: string[],
+  localisedUrls: LocalisedUrlsMap,
+) => {
+  validateLocalisedUrlPatterns(languages, localisedUrls);
+
+  const visit = (route: LocalisedRoute, parentPath: string) => {
+    const canonicalPath = joinPath(parentPath, route.path);
+    if (
+      isLocalisableRoutePath(route.path) &&
+      !isFrameworkInternalRoutePath(canonicalPath)
+    ) {
+      ensureLocalisedUrlsForPath(canonicalPath, languages, localisedUrls);
+    }
+
+    if ('children' in route && route.children) {
+      route.children.forEach(child => visit(child, canonicalPath));
+    }
+  };
+
+  routes.forEach(route => visit(route, ''));
+};
+
+const getLocalisedRouteIdSuffixes = (
+  paths: string[],
+): Array<string | undefined> => {
+  const usedSuffixes = new Set<string>();
+
+  return paths.map((path, index) => {
+    if (index === 0) {
+      return undefined;
+    }
+
+    const baseSuffix = legalRouteIdPart(path);
+    let suffix = baseSuffix;
+    let disambiguator = 2;
+    while (usedSuffixes.has(suffix)) {
+      suffix = `${baseSuffix}_${disambiguator++}`;
+    }
+    usedSuffixes.add(suffix);
+    return suffix;
+  });
+};
+
+const getLocalisedRoutePaths = (
+  canonicalPath: string,
+  parentLocalisedPaths: Record<string, string>,
+  languages: string[],
+  entry: LocalisedUrlPathMap,
+): string[] => {
+  const paths = languages.map(language => {
+    const fullPath = normalisePathPattern(entry[language]);
+    const parentPath = normalisePathPattern(
+      parentLocalisedPaths[language] || '/',
+    );
+    if (parentPath === '/') {
+      return normaliseRoutePath(fullPath) || undefined;
+    }
+
+    const parentPrefix = `${parentPath}/`;
+    if (!fullPath.startsWith(parentPrefix)) {
+      throw new Error(
+        `localisedUrls["${canonicalPath}"].${language} must be nested under "${parentPath}" because its parent route is localised there.`,
+      );
+    }
+
+    return normaliseRoutePath(fullPath.slice(parentPath.length));
+  });
+
+  const uniquePaths = Array.from(new Set(paths.filter(Boolean) as string[]));
+  return uniquePaths;
+};
+
+const transformLocalisedRoute = (
+  route: LocalisedRoute,
+  parentCanonicalPath: string,
+  parentLocalisedPaths: Record<string, string>,
+  languages: string[],
+  localisedUrls: LocalisedUrlsMap,
+  projection: 'physical' | 'canonical',
+): LocalisedRoute[] => {
+  const isSplat = stripLeadingLocaleParam(route.path) === '*';
+  const canonicalPath = isSplat
+    ? normalisePathPattern(`${parentCanonicalPath}/*`)
+    : joinPath(parentCanonicalPath, route.path);
+  const localisedUrlEntry =
+    isLocalisableRoutePath(route.path) &&
+    !isFrameworkInternalRoutePath(canonicalPath)
+      ? ensureLocalisedUrlsForPath(canonicalPath, languages, localisedUrls)
+      : undefined;
+  const routeLocalisedPaths = localisedUrlEntry
+    ? languages.reduce<Record<string, string>>((acc, language) => {
+        acc[language] = normalisePathPattern(localisedUrlEntry[language]);
+        return acc;
+      }, {})
+    : isSplat
+      ? Object.fromEntries(
+          Object.entries(parentLocalisedPaths).map(([language, path]) => [
+            language,
+            normalisePathPattern(`${path}/*`),
+          ]),
+        )
+      : parentLocalisedPaths;
+
+  const children =
+    'children' in route && route.children
+      ? route.children.flatMap(child =>
+          transformLocalisedRoute(
+            child,
+            canonicalPath,
+            routeLocalisedPaths,
+            languages,
+            localisedUrls,
+            projection,
+          ),
+        )
+      : undefined;
+
+  const baseRoute = {
+    ...route,
+    ...(!isFrameworkInternalRoutePath(canonicalPath)
+      ? {
+          modernLocalisedRoute: {
+            id: route.id,
+            path: route.path,
+            canonicalPath,
+            paths:
+              localisedUrlEntry ?? (isSplat ? routeLocalisedPaths : undefined),
+          },
+        }
+      : {}),
+    ...(children ? { children } : {}),
+  } as LocalisedRoute;
+
+  if (!localisedUrlEntry) {
+    return [baseRoute];
+  }
+
+  const localisedPaths = getLocalisedRoutePaths(
+    canonicalPath,
+    parentLocalisedPaths,
+    languages,
+    localisedUrlEntry,
+  );
+  // Validate nesting for both adapters, but only React Router needs physical
+  // variants. TanStack consumes the source identity and native URL rewrites.
+  if (projection === 'canonical') return [baseRoute];
+
+  const leadingLocaleParam = getLeadingLocaleParam(route.path);
+  const routeIdPaths = leadingLocaleParam
+    ? localisedPaths.map(path =>
+        normaliseRoutePath(`${leadingLocaleParam}/${path}`),
+      )
+    : localisedPaths;
+  const routeIdSuffixes = getLocalisedRouteIdSuffixes(routeIdPaths);
+
+  return localisedPaths.map((localisedPath, index) =>
+    cloneRouteWithLocalisedPath(
+      baseRoute,
+      localisedPath,
+      routeIdSuffixes[index],
+      canonicalPath,
+    ),
+  );
+};
+
+const suffixRouteIds = <T extends LocalisedRoute>(
+  route: T,
+  suffix: string,
+): T => {
+  const children =
+    'children' in route && route.children
+      ? route.children.map(child => suffixRouteIds(child, suffix))
+      : undefined;
+
+  return {
+    ...route,
+    ...(route.id ? { id: `${route.id}__localised_${suffix}` } : {}),
+    ...(children ? { children } : {}),
+  };
+};
+
+const collectRouteIdCounts = (
+  routes: LocalisedRoute[],
+  counts = new Map<string, number>(),
+): Map<string, number> => {
+  for (const route of routes) {
+    if (route.id) {
+      counts.set(route.id, (counts.get(route.id) ?? 0) + 1);
+    }
+    if ('children' in route && route.children) {
+      collectRouteIdCounts(route.children, counts);
+    }
+  }
+  return counts;
+};
+
+const validateNoNewRouteIdCollisions = (
+  sourceRoutes: LocalisedRoute[],
+  localisedRoutes: LocalisedRoute[],
+) => {
+  const sourceCounts = collectRouteIdCounts(sourceRoutes);
+  const localisedCounts = collectRouteIdCounts(localisedRoutes);
+
+  for (const [routeId, count] of localisedCounts) {
+    if (count > 1 && count > (sourceCounts.get(routeId) ?? 0)) {
+      throw new Error(
+        `Localised route expansion generated duplicate route ID "${routeId}". Change the source route ID or localised path so every generated route remains identifiable.`,
+      );
+    }
+  }
+};
+
+const cloneRouteWithLocalisedPath = (
+  route: LocalisedRoute,
+  path: string,
+  routeIdSuffix: string | undefined,
+  canonicalPath: string,
+): LocalisedRoute => {
+  const leadingLocaleParam = getLeadingLocaleParam(route.path);
+  const localisedPath = leadingLocaleParam
+    ? normaliseRoutePath(`${leadingLocaleParam}/${path}`)
+    : path;
+  const routeWithPath = {
+    ...route,
+    path: localisedPath,
+  } as LocalisedRoute;
+  // Language-agnostic source pattern; lets downstream codegen collapse the
+  // localized physical variants back to one canonical route.
+  (routeWithPath as { modernCanonicalPath?: string }).modernCanonicalPath =
+    canonicalPath;
+
+  return routeIdSuffix
+    ? suffixRouteIds(routeWithPath, routeIdSuffix)
+    : routeWithPath;
+};
+
+export const applyLocalisedUrlsToRoutes = (
+  routes: LocalisedRoute[],
+  languages: string[],
+  localisedUrls: LocalisedUrlsMap,
+  projection: 'physical' | 'canonical' = 'physical',
+): LocalisedRoute[] => {
+  const rootLocalisedPaths = languages.reduce<Record<string, string>>(
+    (acc, language) => {
+      acc[language] = '/';
+      return acc;
+    },
+    {},
+  );
+
+  validateLocalisedUrls(routes, languages, localisedUrls);
+
+  const localisedRoutes = routes.flatMap(route =>
+    transformLocalisedRoute(
+      route,
+      '',
+      rootLocalisedPaths,
+      languages,
+      localisedUrls,
+      projection,
+    ),
+  );
+  validateNoNewRouteIdCollisions(routes, localisedRoutes);
+  return localisedRoutes;
+};

package/src/localisedUrls/types.ts

@@ -0,0 +1,18 @@
+export type LocalisedRoute = {
+  type: 'nested' | 'page';
+  path?: string;
+  id?: string;
+  children?: LocalisedRoute[];
+  [key: string]: any;
+};
+
+export type LocalisedUrlPathMap = Record<string, string>;
+
+export type LocalisedUrlsMap = Record<string, LocalisedUrlPathMap>;
+
+export type LocalisedUrlsOption = boolean | LocalisedUrlsMap;
+
+export interface ResolvedLocalisedUrlsConfig {
+  enabled: boolean;
+  map: LocalisedUrlsMap;
+}

package/src/rendererHead.ts

@@ -9,6 +9,10 @@ export type RendererHeadMarkerProps = Record<typeof MARKER_ATTRIBUTE, string>;
 export * from './helmetCompat';
 
 type PublishRecords = (records: unknown[]) => void;
+export type ReportLateHead = (message: string) => void;
+
+export const LATE_HEAD_MESSAGE =
+  "<Helmet> rendered in a boundary that completed after the shell; head tags dropped. Move it above the Suspense boundary or set server.ssrByEntries[entry].mode to 'string'.";
 
 type HeadTransaction = {
   recordsByToken: Map<string, unknown>;
@@ -18,6 +22,8 @@ type HeadTransaction = {
   nonce: string;
   previousRecords: unknown[];
   sealed: boolean;
+  reportLateHead: ReportLateHead;
+  lateHeadReported: boolean;
 };
 
 type HeadState = {
@@ -48,7 +54,16 @@ const createToken = (transaction: HeadTransaction): string => {
   return token;
 };
 
-export const beginHeadRender = (context: object): void => {
+const dropLateHead = (transaction: HeadTransaction): void => {
+  if (transaction.lateHeadReported) return;
+  transaction.lateHeadReported = true;
+  transaction.reportLateHead(LATE_HEAD_MESSAGE);
+};
+
+export const beginHeadRender = (
+  context: object,
+  reportLateHead: ReportLateHead,
+): void => {
   const state = getState(context);
   state.transaction = {
     recordsByToken: new Map(),
@@ -58,6 +73,8 @@ export const beginHeadRender = (context: object): void => {
     nonce: globalThis.crypto.randomUUID(),
     previousRecords: state.publishedRecords,
     sealed: false,
+    reportLateHead,
+    lateHeadReported: false,
   };
   state.publish?.([]);
 };
@@ -66,7 +83,7 @@ export const collectHeadRecord = <RecordType>(
   context: object,
   createRecord: () => RecordType,
   publish: (records: RecordType[]) => void,
-): RendererHeadMarkerProps | null | undefined => {
+): RendererHeadMarkerProps | undefined => {
   const state = getState(context);
   const transaction = state.transaction;
   if (transaction === undefined) {
@@ -78,10 +95,8 @@ export const collectHeadRecord = <RecordType>(
   if (!hadPublisher) {
     state.publish([]);
   }
-  if (transaction.sealed) {
-    return null;
-  }
-
+  // A Helmet rendered after the seal still gets a marker: it is dropped, and
+  // reported, only if its boundary actually commits to the output.
   const token = createToken(transaction);
   transaction.recordsByToken.set(token, createRecord());
   return { [MARKER_ATTRIBUTE]: token };
@@ -92,7 +107,7 @@ export const collectHeadState = <RecordType, StateType>(
   createRecord: () => RecordType,
   derive: (records: RecordType[]) => StateType,
   target: { helmet?: StateType },
-): RendererHeadMarkerProps | null | undefined =>
+): RendererHeadMarkerProps | undefined =>
   collectHeadRecord(context, createRecord, records => {
     target.helmet = derive(records);
   });
@@ -123,7 +138,9 @@ const consumeMarkers = (context: object, html: string): string => {
       stripped += html.slice(cursor, end + MARKER_SUFFIX.length);
     } else {
       stripped += html.slice(cursor, start);
-      if (!transaction.sealed && !transaction.committedTokens.has(token)) {
+      if (transaction.sealed) {
+        if (!transaction.committedTokens.has(token)) dropLateHead(transaction);
+      } else if (!transaction.committedTokens.has(token)) {
         transaction.committedTokens.add(token);
         transaction.committedRecords.push(
           transaction.recordsByToken.get(token),

package/src/request-policy/policyCore.ts

@@ -92,7 +92,7 @@ export const toOrigin = (value?: string) => {
   }
   try {
     return new URL(value).origin;
-  } catch (error) {
+  } catch {
     return undefined;
   }
 };

package/src/request-policy/transport.ts

@@ -131,7 +131,7 @@ const shouldRetry = (
   if (typeof retryOptions?.shouldRetry === 'function') {
     try {
       return retryOptions.shouldRetry(context);
-    } catch (error) {
+    } catch {
       return false;
     }
   }
@@ -176,7 +176,7 @@ const emitDegradedEvent = (
 
   try {
     transport.onDegraded(event);
-  } catch (error) {
+  } catch {
     // best-effort telemetry only
   }
 };

package/src/request-policy/types.ts

@@ -174,7 +174,7 @@ export type OperationContextSource =
   | 'client'
   | 'server'
   | 'generated-client'
-  | 'effect-adapter'
+  | 'effect-server'
   | 'data-platform'
   | 'unknown';
 

package/src/routeHydration.ts

@@ -71,7 +71,7 @@ const isAsyncEntryScriptChunk = (chunk: ScriptChunkLike, entryName: string) => {
 
 export function getMatchedRouteChunks<T>(
   routeManifest: RouteManifestLike | undefined,
-  matchedRouteIds: string[],
+  matchedRouteIds: readonly string[],
   routeAssetToChunk: (asset: string) => T,
 ): T[] {
   const routeAssets = routeManifest?.routeAssets;
@@ -167,7 +167,7 @@ export function replaceChunkJsPlaceholder(
 
 export function createRouteHydrationScriptTags(
   routeManifest: RouteManifestLike | undefined,
-  matchedRouteIds: string[],
+  matchedRouteIds: readonly string[],
   entryName: string,
   options: {
     nonce?: string;

package/src/routerProvider.ts

@@ -144,7 +144,7 @@ export function createRouterPlugin<Hooks extends Record<string, unknown>>({
     name: '@modern-js/plugin-router',
     registryHooks,
     setup(api: {
-      getRuntimeConfig: () => { router?: Record<string, unknown> };
+      getRuntimeConfig: () => Record<string, unknown>;
       [key: string]: any;
     }) {
       const mergedConfig = merge(