@bleedingdev/modern-js-runtime-extensions 3.9.0-ultramodern.2 → 3.9.0-ultramodern.21

package/package.json

@@ -11,7 +11,7 @@
     "directory": "packages/runtime/runtime-extensions"
   },
   "license": "MIT",
-  "version": "3.9.0-ultramodern.2",
+  "version": "3.9.0-ultramodern.21",
   "engines": {
     "node": ">=26.7.0"
   },
@@ -34,14 +34,6 @@
       },
       "default": "./dist/esm-node/node.mjs"
     },
-    "./rsc-html-stream": {
-      "types": "./dist/types/rscHtmlStream.d.ts",
-      "node": {
-        "import": "./dist/esm-node/rscHtmlStream.mjs",
-        "require": "./dist/cjs/rscHtmlStream.js"
-      },
-      "default": "./dist/esm-node/rscHtmlStream.mjs"
-    },
     "./safe-failure": {
       "types": "./dist/types/safeFailure.d.ts",
       "node": {
@@ -49,6 +41,151 @@
         "require": "./dist/cjs/safeFailure.js"
       },
       "default": "./dist/esm/safeFailure.mjs"
+    },
+    "./build-identity": {
+      "types": "./dist/types/buildIdentity.d.ts",
+      "node": {
+        "import": "./dist/esm-node/buildIdentity.mjs",
+        "require": "./dist/cjs/buildIdentity.js"
+      },
+      "default": "./dist/esm/buildIdentity.mjs"
+    },
+    "./workspace-events": {
+      "types": "./dist/types/workspaceEvents.d.ts",
+      "node": {
+        "import": "./dist/esm-node/workspaceEvents.mjs",
+        "require": "./dist/cjs/workspaceEvents.js"
+      },
+      "default": "./dist/esm/workspaceEvents.mjs"
+    },
+    "./rsc-disabled/*": {
+      "types": "./dist/types/rsc-disabled/*.d.ts",
+      "default": "./dist/esm/rsc-disabled/*.mjs"
+    },
+    "./localised-loader-identity": {
+      "types": "./dist/types/localisedLoaderIdentity.d.ts",
+      "node": {
+        "import": "./dist/esm-node/localisedLoaderIdentity.mjs",
+        "require": "./dist/cjs/localisedLoaderIdentity.js"
+      },
+      "default": "./dist/esm/localisedLoaderIdentity.mjs"
+    },
+    "./context-extensions": {
+      "types": "./dist/types/contextExtensions.d.ts",
+      "node": {
+        "import": "./dist/esm-node/contextExtensions.mjs",
+        "require": "./dist/cjs/contextExtensions.js"
+      },
+      "default": "./dist/esm/contextExtensions.mjs"
+    },
+    "./helmet-context": {
+      "types": "./dist/types/helmetContext.d.ts",
+      "node": {
+        "import": "./dist/esm-node/helmetContext.mjs",
+        "require": "./dist/cjs/helmetContext.js"
+      },
+      "default": "./dist/esm/helmetContext.mjs"
+    },
+    "./head-runtime": {
+      "types": "./dist/types/headRuntime.d.ts",
+      "node": {
+        "import": "./dist/esm-node/headRuntime.mjs",
+        "require": "./dist/cjs/headRuntime.js"
+      },
+      "default": "./dist/esm/headRuntime.mjs"
+    },
+    "./context-projection": {
+      "types": "./dist/types/runtimeContextProjection.d.ts",
+      "node": {
+        "import": "./dist/esm-node/runtimeContextProjection.mjs",
+        "require": "./dist/cjs/runtimeContextProjection.js"
+      },
+      "default": "./dist/esm/runtimeContextProjection.mjs"
+    },
+    "./server-config": {
+      "types": "./dist/types/server-config/index.d.ts",
+      "node": {
+        "import": "./dist/esm-node/server-config/index.mjs",
+        "require": "./dist/cjs/server-config/index.js"
+      },
+      "default": "./dist/esm/server-config/index.mjs"
+    },
+    "./router-state": {
+      "types": "./dist/types/routerState.d.ts",
+      "node": {
+        "import": "./dist/esm-node/routerState.mjs",
+        "require": "./dist/cjs/routerState.js"
+      },
+      "default": "./dist/esm/routerState.mjs"
+    },
+    "./request-policy": {
+      "types": "./dist/types/request-policy/browser.d.ts",
+      "node": {
+        "import": "./dist/esm-node/request-policy/node.mjs",
+        "require": "./dist/esm-node/request-policy/node.mjs",
+        "default": "./dist/esm-node/request-policy/node.mjs"
+      },
+      "import": "./dist/esm/request-policy/browser.mjs",
+      "require": "./dist/esm/request-policy/browser.mjs",
+      "default": "./dist/esm/request-policy/browser.mjs"
+    },
+    "./request-policy/client": {
+      "types": "./dist/types/request-policy/browser.d.ts",
+      "import": "./dist/esm/request-policy/browser.mjs",
+      "require": "./dist/esm/request-policy/browser.mjs",
+      "default": "./dist/esm/request-policy/browser.mjs"
+    },
+    "./request-policy/server": {
+      "types": "./dist/types/request-policy/node.d.ts",
+      "node": {
+        "import": "./dist/esm-node/request-policy/node.mjs",
+        "require": "./dist/esm-node/request-policy/node.mjs",
+        "default": "./dist/esm-node/request-policy/node.mjs"
+      }
+    },
+    "./request-context": {
+      "types": "./dist/types/request-policy/requestContext.d.ts",
+      "node": {
+        "import": "./dist/esm-node/request-policy/requestContext.mjs",
+        "require": "./dist/esm-node/request-policy/requestContext.mjs",
+        "default": "./dist/esm-node/request-policy/requestContext.mjs"
+      },
+      "import": "./dist/esm/request-policy/requestContext.mjs",
+      "require": "./dist/esm/request-policy/requestContext.mjs",
+      "default": "./dist/esm/request-policy/requestContext.mjs"
+    },
+    "./package.json": "./package.json",
+    "./router-state-plugin": {
+      "types": "./dist/types/routerStatePlugin.d.ts",
+      "node": {
+        "import": "./dist/esm-node/routerStatePlugin.mjs",
+        "require": "./dist/cjs/routerStatePlugin.js"
+      },
+      "default": "./dist/esm/routerStatePlugin.mjs"
+    },
+    "./router-provider": {
+      "types": "./dist/types/routerProvider.d.ts",
+      "node": {
+        "import": "./dist/esm-node/routerProvider.mjs",
+        "require": "./dist/cjs/routerProvider.js"
+      },
+      "default": "./dist/esm/routerProvider.mjs"
+    },
+    "./router-prefetch-policy": {
+      "types": "./dist/types/routerPrefetchPolicy.d.ts",
+      "node": {
+        "import": "./dist/esm-node/routerPrefetchPolicy.mjs",
+        "require": "./dist/cjs/routerPrefetchPolicy.js"
+      },
+      "default": "./dist/esm/routerPrefetchPolicy.mjs"
+    },
+    "./localised-urls": {
+      "types": "./dist/types/localisedUrls/index.d.ts",
+      "node": {
+        "import": "./dist/esm-node/localisedUrls/index.mjs",
+        "require": "./dist/cjs/localisedUrls/index.js"
+      },
+      "default": "./dist/esm/localisedUrls/index.mjs"
     }
   },
   "typesVersions": {
@@ -61,27 +198,115 @@
         "./dist/types/node.d.ts",
         "./src/node.ts"
       ],
-      "rsc-html-stream": [
-        "./dist/types/rscHtmlStream.d.ts",
-        "./src/rscHtmlStream.ts"
-      ],
       "safe-failure": [
         "./dist/types/safeFailure.d.ts",
         "./src/safeFailure.ts"
+      ],
+      "build-identity": [
+        "./dist/types/buildIdentity.d.ts",
+        "./src/buildIdentity.ts"
+      ],
+      "workspace-events": [
+        "./dist/types/workspaceEvents.d.ts",
+        "./src/workspaceEvents.ts"
+      ],
+      "localised-loader-identity": [
+        "./dist/types/localisedLoaderIdentity.d.ts",
+        "./src/localisedLoaderIdentity.ts"
+      ],
+      "context-extensions": [
+        "./dist/types/contextExtensions.d.ts",
+        "./src/contextExtensions.ts"
+      ],
+      "helmet-context": [
+        "./dist/types/helmetContext.d.ts",
+        "./src/helmetContext.ts"
+      ],
+      "head-runtime": [
+        "./dist/types/headRuntime.d.ts",
+        "./src/headRuntime.tsx"
+      ],
+      "context-projection": [
+        "./dist/types/runtimeContextProjection.d.ts",
+        "./src/runtimeContextProjection.ts"
+      ],
+      "server-config": [
+        "./dist/types/server-config/index.d.ts",
+        "./src/server-config/index.ts"
+      ],
+      "router-state": [
+        "./dist/types/routerState.d.ts",
+        "./src/routerState.ts"
+      ],
+      "request-policy": [
+        "./dist/types/request-policy/browser.d.ts",
+        "./src/request-policy/browser.ts"
+      ],
+      "request-policy/client": [
+        "./dist/types/request-policy/browser.d.ts",
+        "./src/request-policy/browser.ts"
+      ],
+      "request-policy/server": [
+        "./dist/types/request-policy/node.d.ts",
+        "./src/request-policy/node.ts"
+      ],
+      "request-context": [
+        "./dist/types/request-policy/requestContext.d.ts",
+        "./src/request-policy/requestContext.ts"
+      ],
+      "router-state-plugin": [
+        "./dist/types/routerStatePlugin.d.ts",
+        "./src/routerStatePlugin.ts"
+      ],
+      "router-provider": [
+        "./dist/types/routerProvider.d.ts",
+        "./src/routerProvider.ts"
+      ],
+      "router-prefetch-policy": [
+        "./dist/types/routerPrefetchPolicy.d.ts",
+        "./src/routerPrefetchPolicy.ts"
+      ],
+      "localised-urls": [
+        "./dist/types/localisedUrls/index.d.ts",
+        "./src/localisedUrls/index.ts"
       ]
     }
   },
   "devDependencies": {
-    "@rslib/core": "1.0.0",
+    "@loadable/component": "5.16.7",
+    "@modern-js/utils": "npm:@bleedingdev/modern-js-utils@3.9.0-ultramodern.21",
+    "@rsbuild/core": "2.2.10",
+    "@rslib/core": "1.0.2",
     "@scripts/rstest-config": "2.66.0",
-    "@types/node": "^26.4.1",
+    "@testing-library/dom": "^10.4.2",
+    "@testing-library/react": "^16.3.3",
+    "@types/node": "^26.6.2",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
     "@typescript/native-preview": "7.0.0-dev.20260707.2",
+    "esbuild": "^0.28.2",
+    "nock": "^14.0.17",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
     "typescript": "^7.0.2"
   },
   "sideEffects": false,
   "publishConfig": {
     "access": "public"
   },
+  "peerDependencies": {
+    "react": "^19.2.8"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@modern-js/create-request": "npm:@bleedingdev/modern-js-create-request@3.9.0-ultramodern.21",
+    "@modern-js/runtime-utils": "npm:@bleedingdev/modern-js-runtime-utils@3.9.0-ultramodern.21",
+    "react-helmet-async": "3.0.0"
+  },
   "scripts": {
     "dev": "rslib build --watch",
     "build": "rslib build",

package/rslib.config.mts

@@ -1,4 +1,19 @@
-import { rslibConfig } from '@modern-js/rslib';
+import { RSLIB_CODE_ENTRY_GLOB, rslibConfig } from '@modern-js/rslib';
 import { defineConfig } from '@rslib/core';
 
-export default defineConfig(rslibConfig);
+export default defineConfig({
+  ...rslibConfig,
+  lib: rslibConfig.lib.map(lib =>
+    lib.id === 'esm-web'
+      ? {
+          ...lib,
+          source: {
+            ...lib.source,
+            entry: {
+              index: [RSLIB_CODE_ENTRY_GLOB, '!./src/request-policy/node.ts'],
+            },
+          },
+        }
+      : lib,
+  ),
+});

package/rstest.config.mts

@@ -1,7 +1,38 @@
+import type { ProjectConfig } from '@rstest/core';
 import { withTestPreset } from '@scripts/rstest-config';
 
-export default withTestPreset({
+const commonConfig: ProjectConfig = {
   root: __dirname,
-  testEnvironment: 'node',
   globals: true,
+  setupFiles: ['@scripts/rstest-config/setup.ts'],
+  tools: {
+    swc: {
+      jsc: {
+        transform: {
+          react: {
+            runtime: 'automatic',
+          },
+        },
+      },
+    },
+  },
+};
+
+const browserPolicyProject = withTestPreset({
+  name: 'runtime-extensions-request-policy-browser',
+  testEnvironment: 'happy-dom',
+  extends: commonConfig,
+  include: ['tests/request-policy/browser-policy.test.ts'],
 });
+
+export default {
+  projects: [
+    withTestPreset({
+      name: 'runtime-extensions-node',
+      exclude: ['tests/request-policy/browser-policy.test.ts'],
+      testEnvironment: 'node',
+      extends: commonConfig,
+    }),
+    browserPolicyProject,
+  ],
+};

package/src/buildIdentity.ts

@@ -0,0 +1,61 @@
+interface BuildIdentity {
+  readonly build: string;
+  readonly buildMarker: string;
+  readonly sourceRevision: string;
+}
+
+interface BuildArtifact {
+  readonly deliveryUnit: BuildIdentity;
+  readonly surfaces: {
+    readonly api: BuildIdentity;
+    readonly ui: BuildIdentity;
+  };
+}
+
+interface BuildIdentityReaders {
+  readonly buildMarker: () => string;
+  readonly sourceRevision: () => string;
+}
+
+function readBuildValue(read: () => string, fallback: string): string {
+  try {
+    return read();
+  } catch (error) {
+    // An uncompiled generated module has no injected constants. Check the
+    // error tag across realms, since source validators may evaluate in a VM.
+    if (
+      error !== null &&
+      typeof error === 'object' &&
+      'name' in error &&
+      error.name === 'ReferenceError'
+    ) {
+      return fallback;
+    }
+    throw error;
+  }
+}
+
+/** Read compiler constants in the caller, even when this package is external. */
+export function resolveUltramodernBuildArtifact<Artifact extends BuildArtifact>(
+  artifact: Artifact,
+  readers?: BuildIdentityReaders,
+) {
+  const buildMarker = readers
+    ? readBuildValue(readers.buildMarker, artifact.deliveryUnit.buildMarker)
+    : artifact.deliveryUnit.buildMarker;
+  const sourceRevision = readers
+    ? readBuildValue(
+        readers.sourceRevision,
+        artifact.deliveryUnit.sourceRevision,
+      )
+    : artifact.deliveryUnit.sourceRevision;
+  const identity = { build: buildMarker, buildMarker, sourceRevision };
+  return {
+    ...artifact,
+    deliveryUnit: { ...artifact.deliveryUnit, ...identity },
+    surfaces: {
+      api: { ...artifact.surfaces.api, ...identity },
+      ui: { ...artifact.surfaces.ui, ...identity },
+    },
+  };
+}

package/src/contextExtensions.ts

@@ -0,0 +1,81 @@
+/**
+ * Fork-owned runtime-context extension mechanism.
+ *
+ * Plugins must not add ad-hoc fields to `TRuntimeContext` /
+ * `TInternalRuntimeContext`. Instead they store state in a single internal
+ * slot (a `Map` keyed by symbol) attached to the context object under a
+ * symbol property, so nothing leaks into string-key enumeration
+ * (`Object.keys`, `JSON.stringify`). Object spreads preserve the slot.
+ *
+ * `Symbol.for` is used for both the slot and the extension keys so that the
+ * mechanism stays coherent even if this module is instantiated twice
+ * (e.g. esm/cjs interop in test runners).
+ */
+
+const EXTENSIONS_SLOT: unique symbol = Symbol.for(
+  '@modern-js/runtime:context-extensions',
+);
+
+type ExtensionStore = Map<symbol, unknown>;
+
+type ExtensibleContext = {
+  [EXTENSIONS_SLOT]?: ExtensionStore;
+};
+
+export interface RuntimeContextExtension<T> {
+  /** Stable identity of this extension. */
+  readonly key: symbol;
+  get(context: object): T | undefined;
+  set(context: object, value: T): void;
+  remove(context: object): void;
+}
+
+function getStore(context: object): ExtensionStore | undefined {
+  return (context as ExtensibleContext)[EXTENSIONS_SLOT];
+}
+
+function ensureStore(context: object): ExtensionStore {
+  const target = context as ExtensibleContext;
+  const store = target[EXTENSIONS_SLOT] ?? new Map();
+  Object.defineProperty(target, EXTENSIONS_SLOT, {
+    configurable: true,
+    enumerable: true,
+    value: store,
+  });
+  return store;
+}
+
+/**
+ * Removes the extension slot from a context object.
+ *
+ * The symbol slot crosses object spreads while remaining absent from string-key
+ * enumeration and JSON. Callers can still explicitly clear the original context.
+ */
+export function stripRuntimeContextExtensions(context: object): void {
+  delete (context as ExtensibleContext)[EXTENSIONS_SLOT];
+}
+
+/**
+ * Creates a typed accessor pair over the shared extension slot.
+ *
+ * The `id` must be globally unique (it is interned via `Symbol.for`); use a
+ * package-prefixed name such as `@modern-js/plugin-tanstack:router-state`.
+ */
+export function createRuntimeContextExtension<T>(
+  id: string,
+): RuntimeContextExtension<T> {
+  const key = Symbol.for(`@modern-js/runtime:context-extension:${id}`);
+
+  return {
+    key,
+    get(context: object): T | undefined {
+      return getStore(context)?.get(key) as T | undefined;
+    },
+    set(context: object, value: T): void {
+      ensureStore(context).set(key, value);
+    },
+    remove(context: object): void {
+      getStore(context)?.delete(key);
+    },
+  };
+}

package/src/headRuntime.tsx

@@ -0,0 +1,77 @@
+import React from 'react';
+import {
+  Helmet as AsyncHelmet,
+  type HelmetProps,
+  HelmetProvider,
+  type HelmetServerState,
+} from 'react-helmet-async';
+import type { HelmetContextSlot } from './helmetContext';
+import * as runtimeHead from './rendererHead';
+
+export interface HeadRenderContext {
+  runtimeContext: object;
+  helmetContext: HelmetContextSlot;
+}
+
+// Keep one adapter per plugin setup. Its component/provider identity is stable;
+// each HTML render supplies its own original context and captured helmet slot.
+export function createHeadRuntime() {
+  const HeadContext = React.createContext<HeadRenderContext | undefined>(
+    undefined,
+  );
+
+  const collectServerHelmet = (
+    { runtimeContext, helmetContext }: HeadRenderContext,
+    props: React.PropsWithChildren<HelmetProps>,
+  ) => {
+    const createRecord = () => runtimeHead.createHelmetRecord(React, props);
+    const deriveState = (records: runtimeHead.HelmetCompatRecord[]) =>
+      runtimeHead.deriveHelmetServerState(React, records) as HelmetServerState;
+    const marker = runtimeHead.collectHeadState(
+      runtimeContext,
+      createRecord,
+      deriveState,
+      helmetContext,
+    );
+    if (marker !== undefined) return marker;
+    helmetContext.helmet = runtimeHead.collectImmediateHelmetState(
+      React,
+      helmetContext,
+      createRecord(),
+    ) as HelmetServerState;
+  };
+
+  const Head = (props: React.PropsWithChildren<HelmetProps>) => {
+    const state = React.useContext(HeadContext);
+    if (state !== undefined) {
+      return runtimeHead.renderHeadMarker(
+        React,
+        collectServerHelmet(state, props),
+      );
+    }
+    return React.createElement(AsyncHelmet, props);
+  };
+
+  const ClientRoot = ({ children }: { children: React.ReactNode }) => {
+    const state = React.useContext(HeadContext);
+    return state === undefined ? (
+      <HelmetProvider>{children}</HelmetProvider>
+    ) : (
+      children
+    );
+  };
+
+  return {
+    Head,
+    wrapServerRoot(root: React.ReactNode, state: HeadRenderContext) {
+      return (
+        <HeadContext.Provider value={state}>
+          <HelmetProvider context={state.helmetContext}>{root}</HelmetProvider>
+        </HeadContext.Provider>
+      );
+    },
+    wrapClientRoot(root: React.ReactNode) {
+      return <ClientRoot>{root}</ClientRoot>;
+    },
+  };
+}

package/src/helmetCompat.ts

@@ -149,7 +149,7 @@ const createElementFactory = <Element>(react: ElementFactory<Element>) =>
 
 export const renderHeadMarker = <Element>(
   react: ElementFactory<Element>,
-  marker: MarkerProps | null | undefined,
+  marker: MarkerProps | undefined,
 ): Element | null =>
   marker ? createElementFactory(react)('template', marker) : null;
 

package/src/helmetContext.ts

@@ -0,0 +1,31 @@
+/**
+ * Fork-owned helmet state, stored via the runtime-context extension slot
+ * instead of an ad-hoc `_helmetContext` field on `TInternalRuntimeContext`.
+ */
+import type { HelmetServerState } from 'react-helmet-async';
+import { createRuntimeContextExtension } from './contextExtensions';
+
+export interface HelmetContextSlot {
+  helmet?: HelmetServerState | null;
+}
+
+const helmetContextExtension = createRuntimeContextExtension<HelmetContextSlot>(
+  '@modern-js/runtime:helmet-context',
+);
+
+export function getHelmetContext(
+  context: object,
+): HelmetContextSlot | undefined {
+  return helmetContextExtension.get(context);
+}
+
+export function ensureHelmetContext(context: object): HelmetContextSlot {
+  const existing = helmetContextExtension.get(context);
+  if (existing !== undefined) {
+    return existing;
+  }
+
+  const created: HelmetContextSlot = {};
+  helmetContextExtension.set(context, created);
+  return created;
+}

package/src/index.ts

@@ -1,4 +1,6 @@
 export * from './html';
 export * from './navigationWarmup';
+export * from './prefetchPolicy';
 export * from './rendererHead';
+export * from './routeHydration';
 export * from './shellStream';

package/src/localisedLoaderIdentity.ts

@@ -0,0 +1,30 @@
+interface RouteNode {
+  id?: string;
+  children?: RouteNode[];
+  modernLocalisedRoute?: { id?: string };
+}
+
+/** Map a source loader ID only to its own alias already matched by the router. */
+export function resolveLocalisedLoaderRouteId(
+  routes: RouteNode[],
+  requestedId: string,
+  matchedIds: (string | undefined)[] = [],
+): string {
+  if (matchedIds.includes(requestedId)) return requestedId;
+  const matched = new Set(matchedIds);
+  const visit = (nodes: RouteNode[]): string | undefined => {
+    for (const route of nodes) {
+      if (
+        route.id &&
+        matched.has(route.id) &&
+        route.modernLocalisedRoute?.id === requestedId
+      ) {
+        return route.id;
+      }
+      const child = route.children && visit(route.children);
+      if (child) return child;
+    }
+    return undefined;
+  };
+  return visit(routes) ?? requestedId;
+}

package/src/localisedUrls/config.ts

@@ -0,0 +1,18 @@
+import type { LocalisedUrlsOption, ResolvedLocalisedUrlsConfig } from './types';
+
+/**
+ * Localised URLs are strictly opt-in: only an explicit, non-empty map enables
+ * route expansion and validation. `true`, `false`, an empty map and absence
+ * all resolve to disabled, so upstream-style configs (`localePathRedirect` +
+ * `languages` without a map) keep plain locale-prefix behavior instead of
+ * failing the build for every route missing from a map they never wrote.
+ */
+export const resolveLocalisedUrlsConfig = (
+  option: LocalisedUrlsOption | undefined,
+): ResolvedLocalisedUrlsConfig => {
+  if (option && typeof option === 'object' && Object.keys(option).length > 0) {
+    return { enabled: true, map: option };
+  }
+
+  return { enabled: false, map: {} };
+};