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

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/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/prefetchPolicy.ts

@@ -0,0 +1,33 @@
+type PrefetchBehavior = 'intent' | 'render' | 'viewport' | 'none';
+
+export function resolvePreloadFromPrefetch(
+  prefetch: PrefetchBehavior | undefined,
+  preload: unknown,
+) {
+  if (typeof preload !== 'undefined') {
+    return preload;
+  }
+
+  if (prefetch === 'none') {
+    return false;
+  }
+
+  if (
+    prefetch === 'intent' ||
+    prefetch === 'render' ||
+    prefetch === 'viewport'
+  ) {
+    return prefetch;
+  }
+
+  return 'viewport';
+}
+
+// React Router supplies its render default before calling this adapter.
+export function normalizePreloadBehavior(
+  preload: PrefetchBehavior | false | undefined,
+  prefetch: PrefetchBehavior,
+): PrefetchBehavior {
+  const resolved = resolvePreloadFromPrefetch(prefetch, preload);
+  return resolved === false ? 'none' : (resolved as PrefetchBehavior);
+}

package/src/reactContext.ts

@@ -0,0 +1,16 @@
+/**
+ * Federation can bundle a runtime subpath separately from its shared root.
+ * Share React context identity across those copies, leaving request values to
+ * React's providers. Public and internal contexts retain separate identities.
+ */
+export function getRuntimeReactContext<T>(
+  kind: 'public' | 'internal',
+  create: () => T,
+): T {
+  const key = Symbol.for(`@modern-js/runtime:react-context:v1:${kind}`);
+  const contexts = globalThis as typeof globalThis & {
+    [key: symbol]: unknown;
+  };
+  contexts[key] ??= create();
+  return contexts[key] as T;
+}

package/src/request-policy/browser.ts

@@ -0,0 +1,22 @@
+import { createClient as createNativeClient } from '@modern-js/create-request/client';
+import { createPolicyClient } from './client';
+
+/** Create a browser producer client with its own configuration and policy. */
+export const createClient = () =>
+  createPolicyClient(createNativeClient(), {
+    target: 'browser',
+    resolveSourceOrigin: () =>
+      typeof window !== 'undefined' ? window.location.origin : undefined,
+  });
+
+export const { configure, createRequest, createUploader } = createClient();
+
+export {
+  CrossOriginEnvelopePolicyError,
+  IdentityBindingViolationError,
+  OperationContractViolationError,
+  ProducerClientNotInitializedError,
+  ProducerDomainNotConfiguredError,
+} from './policyCore';
+export * from './requestContext';
+export * from './types';