@bleedingdev/modern-js-federation-runtime 3.9.0-ultramodern.9 → 3.9.3-ultramodern.2

package/dist/types/module-federation/renderer-runtime-plugin.d.ts

@@ -0,0 +1,98 @@
+import { type RendererFederationCompatibility } from './renderer-contract.js';
+type Snapshot = Record<string, unknown>;
+type SnapshotArgs = {
+    remoteSnapshot: Snapshot;
+    from: 'global' | 'manifest';
+    manifestJson?: unknown;
+};
+type Shared = Record<string, unknown> & {
+    version?: string;
+};
+type ShareResolution = {
+    shared: Shared;
+    useTreesShaking?: boolean;
+} | undefined;
+type ResolveShareArgs = {
+    pkgName: string;
+    shareScopeMap: Record<string, Record<string, Record<string, Shared>>>;
+    resolver: () => ShareResolution;
+};
+/**
+ * Exact versions every shared copy of the consuming renderer tuple must carry.
+ * React keeps its established package set; native renderers derive theirs from
+ * the tuple's runtime, hydration, bootstrap and router owners.
+ */
+export declare function rendererShareVersions(expected: RendererFederationCompatibility): ReadonlyMap<string, string>;
+/** Gate the native snapshot and share lifecycles before executing component factories. */
+export declare function createRendererFederationRuntimePlugin(options: RendererFederationCompatibility): {
+    name: string;
+    beforeRegisterRemote(args: {
+        remote: unknown;
+    }): {
+        remote: unknown;
+    };
+    afterMatchRemote(args: {
+        remote?: unknown;
+        error?: unknown;
+    }): Promise<{
+        remote?: unknown;
+        error?: unknown;
+    }>;
+    loadRemoteSnapshot(args: SnapshotArgs): Promise<SnapshotArgs>;
+    afterLoadSnapshot(args: {
+        remoteSnapshot: Snapshot;
+        moduleInfo?: {
+            name: string;
+        };
+    }): Promise<{
+        remoteSnapshot: Snapshot;
+        moduleInfo?: {
+            name: string;
+        };
+    }>;
+    afterResolve(args: {
+        remote: {
+            name: string;
+        };
+        remoteInfo: Record<string, unknown>;
+        remoteSnapshot?: Snapshot;
+        origin: {
+            moduleCache: Map<string, {
+                remoteInfo: Record<string, unknown>;
+            }>;
+        };
+    }): Promise<{
+        remote: {
+            name: string;
+        };
+        remoteInfo: Record<string, unknown>;
+        remoteSnapshot?: Snapshot;
+        origin: {
+            moduleCache: Map<string, {
+                remoteInfo: Record<string, unknown>;
+            }>;
+        };
+    }>;
+    loadEntry(args: {
+        remoteInfo: Record<string, unknown>;
+    }): void;
+    afterLoadEntry(args: {
+        remoteInfo: Record<string, unknown>;
+        remoteEntryExports?: unknown;
+        cached?: boolean;
+        error?: unknown;
+        recovered?: boolean;
+    }): Promise<{
+        remoteInfo: Record<string, unknown>;
+        remoteEntryExports?: unknown;
+        cached?: boolean;
+        error?: unknown;
+        recovered?: boolean;
+    }>;
+    resolveShare(args: ResolveShareArgs): ResolveShareArgs;
+    afterLoadShare(args: {
+        pkgName: string;
+        selectedShared?: Shared;
+    }): void;
+};
+export default createRendererFederationRuntimePlugin;

package/dist/types/module-federation/telemetry.d.ts

@@ -0,0 +1,71 @@
+export declare const MODULE_FEDERATION_FALLBACK_SIGNAL_EVENT = "modernjs:mf-runtime-fallback";
+export declare const MODULE_FEDERATION_RECOVERY_SIGNAL_EVENT = "modernjs:mf-runtime-recovery";
+export declare const DEFAULT_RUNTIME_FALLBACK_SIGNAL_ENDPOINT = "/_modern/contract-gates/runtime-fallback";
+export declare const DEFAULT_RUNTIME_FALLBACK_SIGNAL_AUTH_HEADER = "x-modernjs-runtime-signal-token";
+export type ModuleFederationFallbackClassification = 'timeout' | 'network' | 'contract' | 'version-skew' | 'remote-unavailable';
+export type ModuleFederationFallbackStatus = 'degraded' | 'failed' | 'recovered';
+export type ModuleFederationFallbackTelemetryInput = {
+    appName: string;
+    classification: ModuleFederationFallbackClassification;
+    entry?: string;
+    error?: unknown;
+    eventName?: string;
+    exportName?: string;
+    metadata?: Record<string, unknown>;
+    phase: 'discovery' | 'load' | 'mount' | 'hydrate' | 'recover';
+    remote: string;
+    runtimeDigest?: string;
+    status?: ModuleFederationFallbackStatus;
+};
+export type ModuleFederationFallbackTelemetryPayload = {
+    appName: string;
+    entry?: string;
+    eventName: string;
+    phase: ModuleFederationFallbackTelemetryInput['phase'];
+    reason: ModuleFederationFallbackClassification;
+    runtimeDigest?: string;
+    schemaVersion: 1;
+    metadata: {
+        classification: ModuleFederationFallbackClassification;
+        errorMessage?: string;
+        errorName?: string;
+        exportName?: string;
+        remote: string;
+        runtimeDigest?: string;
+        status: ModuleFederationFallbackStatus;
+    } & Record<string, unknown>;
+};
+export type ModuleFederationFallbackTelemetryEmitOptions = {
+    authHeaderName?: string;
+    authToken?: string;
+    endpoint?: string;
+    fetchImpl?: typeof fetch;
+    postSignal?: boolean;
+    /** Positive reporting deadline; defaults to one second. */
+    timeoutMs?: number;
+    /** Observe the exact payload and await delivery explicitly in tests. */
+    observe?: (payload: ModuleFederationFallbackTelemetryPayload, delivery: Promise<ModuleFederationFallbackTelemetryEmitResult>) => void;
+};
+export type ModuleFederationFallbackTelemetryEmitResult = {
+    dispatched: boolean;
+    posted: boolean;
+    postStatus?: number;
+};
+export declare class ModuleFederationRemoteLoadTimeoutError extends Error {
+    constructor(remote: string, timeoutMs: number);
+}
+export declare class ModuleFederationRemoteLoadError extends Error {
+    readonly remote: string;
+    readonly attempts: number;
+    readonly causeError: Error;
+    constructor(remote: string, attempts: number, causeError: Error);
+}
+export declare class ModuleFederationRemoteComponentContractError extends Error {
+    constructor(remote: string, exportName: string);
+}
+export declare function classifyModuleFederationFallback(error: unknown): ModuleFederationFallbackClassification;
+export declare function createModuleFederationFallbackTelemetry(input: ModuleFederationFallbackTelemetryInput): ModuleFederationFallbackTelemetryPayload;
+export declare function toModuleFederationFallbackAttributes(payload: ModuleFederationFallbackTelemetryPayload): Record<string, string>;
+export declare function emitModuleFederationFallbackTelemetry(input: ModuleFederationFallbackTelemetryInput, options?: ModuleFederationFallbackTelemetryEmitOptions): Promise<ModuleFederationFallbackTelemetryEmitResult>;
+/** Dispatch once locally; remote delivery is bounded and best effort. */
+export declare function emitModuleFederationFallbackPayload(payload: ModuleFederationFallbackTelemetryPayload, options?: ModuleFederationFallbackTelemetryEmitOptions): Promise<ModuleFederationFallbackTelemetryEmitResult>;

package/package.json

@@ -1,15 +1,15 @@
 {
   "name": "@bleedingdev/modern-js-federation-runtime",
-  "version": "3.9.0-ultramodern.9",
+  "version": "3.9.3-ultramodern.2",
   "description": "Federated surface consumption, distributed SSR, and bounded manifest recovery.",
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/BleedingDev/ultramodern.js.git",
+    "url": "git+https://github.com/ultramodernjs/ultramodern.js.git",
     "directory": "packages/runtime/federation-runtime"
   },
   "engines": {
-    "node": ">=26.7.0"
+    "node": ">=26.10.0"
   },
   "types": "./dist/types/module-federation/index.d.ts",
   "main": "./dist/cjs/module-federation/index.js",
@@ -23,6 +23,22 @@
       },
       "default": "./dist/esm/module-federation/index.mjs"
     },
+    "./renderer-contract": {
+      "types": "./dist/types/module-federation/renderer-contract.d.ts",
+      "node": {
+        "import": "./dist/esm-node/module-federation/renderer-contract.mjs",
+        "require": "./dist/cjs/module-federation/renderer-contract.js"
+      },
+      "default": "./dist/esm/module-federation/renderer-contract.mjs"
+    },
+    "./renderer-runtime-plugin": {
+      "types": "./dist/types/module-federation/renderer-runtime-plugin.d.ts",
+      "node": {
+        "import": "./dist/esm-node/module-federation/renderer-runtime-plugin.mjs",
+        "require": "./dist/cjs/module-federation/renderer-runtime-plugin.js"
+      },
+      "default": "./dist/esm/module-federation/renderer-runtime-plugin.mjs"
+    },
     "./distributed-ssr": {
       "types": "./dist/types/module-federation/distributed-ssr.d.ts",
       "node": {
@@ -46,6 +62,14 @@
         "./dist/types/module-federation/index.d.ts",
         "./src/module-federation/index.ts"
       ],
+      "renderer-contract": [
+        "./dist/types/module-federation/renderer-contract.d.ts",
+        "./src/module-federation/renderer-contract.ts"
+      ],
+      "renderer-runtime-plugin": [
+        "./dist/types/module-federation/renderer-runtime-plugin.d.ts",
+        "./src/module-federation/renderer-runtime-plugin.ts"
+      ],
       "distributed-ssr": [
         "./dist/types/module-federation/distributed-ssr.d.ts",
         "./src/module-federation/distributed-ssr.tsx"
@@ -62,26 +86,35 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "@modern-js/surface-resolution": "npm:@bleedingdev/modern-js-surface-resolution@3.9.0-ultramodern.9"
+    "@modern-js/backend-federation-contracts": "npm:@bleedingdev/modern-js-backend-federation-contracts@3.9.3-ultramodern.2",
+    "@modern-js/surface-resolution": "npm:@bleedingdev/modern-js-surface-resolution@3.9.3-ultramodern.2",
+    "@module-federation/sdk": "2.9.2"
   },
   "peerDependencies": {
-    "@modern-js/runtime": "3.9.0-ultramodern.9",
+    "@modern-js/runtime": "3.9.3-ultramodern.2",
     "react": "^19.2.8"
   },
+  "peerDependenciesMeta": {
+    "@modern-js/runtime": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    }
+  },
   "devDependencies": {
-    "@modern-js/runtime": "npm:@bleedingdev/modern-js-runtime@3.9.0-ultramodern.9",
-    "@modern-js/tsconfig": "npm:@bleedingdev/modern-js-tsconfig@3.9.0-ultramodern.9",
-    "@rsbuild/core": "2.2.3",
-    "@rslib/core": "1.0.0",
+    "@modern-js/runtime": "npm:@bleedingdev/modern-js-runtime@3.9.3-ultramodern.2",
+    "@modern-js/tsconfig": "npm:@bleedingdev/modern-js-tsconfig@3.9.3-ultramodern.2",
+    "@rsbuild/core": "2.2.11",
+    "@rslib/core": "1.0.3",
     "@scripts/rstest-config": "2.66.0",
-    "@types/node": "^26.4.1",
-    "@types/react": "^19.2.18",
-    "@types/react-dom": "^19.2.7",
-    "@typescript/native-preview": "7.0.0-dev.20260707.2",
+    "@types/node": "^26.6.3",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
     "esbuild": "^0.28.2",
-    "react": "^19.2.8",
-    "react-dom": "^19.2.8",
-    "typescript": "^7.0.2"
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "typescript": "7.0.2"
   },
   "publishConfig": {
     "access": "public"
@@ -91,8 +124,11 @@
     "build": "rslib build",
     "test": "rstest run"
   },
-  "homepage": "https://github.com/BleedingDev/ultramodern.js#readme",
+  "homepage": "https://github.com/ultramodernjs/ultramodern.js#readme",
   "bugs": {
-    "url": "https://github.com/BleedingDev/ultramodern.js/issues"
+    "url": "https://github.com/ultramodernjs/ultramodern.js/issues"
+  },
+  "ultramodern": {
+    "sourceName": "@modern-js/federation-runtime"
   }
 }

package/src/module-federation/consume-surface.ts

@@ -23,14 +23,7 @@
  * consumption during a rollout window should be driven by expand/contract, not
  * by silent degrade.
  */
-import {
-  classifyModuleFederationFallback,
-  createModuleFederationFallbackTelemetry,
-  emitModuleFederationFallbackTelemetry,
-  type ModuleFederationFallbackClassification,
-  type ModuleFederationFallbackTelemetryEmitOptions,
-  type ModuleFederationFallbackTelemetryPayload,
-} from './index';
+
 import {
   createDiscoveryError,
   type DiscoveryError,
@@ -44,6 +37,15 @@ import {
   type SurfaceResolutionProvider,
   validateSurfaceRef,
 } from './surface-resolution-types';
+import {
+  classifyModuleFederationFallback,
+  createModuleFederationFallbackTelemetry,
+  emitModuleFederationFallbackPayload,
+  emitModuleFederationFallbackTelemetry,
+  type ModuleFederationFallbackClassification,
+  type ModuleFederationFallbackTelemetryEmitOptions,
+  type ModuleFederationFallbackTelemetryPayload,
+} from './telemetry';
 
 /** Where in the consumption lifecycle a failure was raised. */
 export type SurfaceConsumptionPhase = 'discovery' | 'load' | 'mount';
@@ -100,7 +102,7 @@ export type SurfaceConsumerOptions<T> = {
    * omitted.
    *
    * - `'noncritical'`: the degraded handler's result is returned and the
-   *   failure is swallowed — the promise never rejects.
+   *   failure is swallowed — a failed degraded handler resolves undefined.
    * - `'critical'`: the degraded handler still runs (telemetry + fallback-UI
    *   obligations hold), but the returned promise then REJECTS with the typed
    *   failure so callers / rollout machinery observe it. Prefer expand/contract
@@ -154,7 +156,7 @@ async function reportFailure<T>(
     error?: unknown;
     resolved?: ResolvedDeliveryUnit;
   },
-): Promise<T> {
+): Promise<T | undefined> {
   const remote = toRemoteString(ref);
   const telemetry = createModuleFederationFallbackTelemetry({
     appName: options.appName,
@@ -173,24 +175,7 @@ async function reportFailure<T>(
     status: 'degraded',
   });
 
-  // Fire-and-forget style, but awaited so tests can assert emission. Emission
-  // failures must never mask the degraded path.
-  try {
-    await emitModuleFederationFallbackTelemetry(
-      {
-        appName: options.appName,
-        classification: base.classification,
-        error: base.error ?? base.discoveryError,
-        metadata: telemetry.metadata,
-        phase: base.phase,
-        remote,
-        status: 'degraded',
-      },
-      options.telemetry ?? {},
-    );
-  } catch {
-    // Telemetry sink failure is itself a degraded condition; swallow it.
-  }
+  void emitModuleFederationFallbackPayload(telemetry, options.telemetry);
 
   const failure: SurfaceConsumptionFailure = {
     ref,
@@ -234,7 +219,7 @@ async function reportFailure<T>(
     // telemetry, then for noncritical resolve undefined; for critical reject
     // with the ORIGINAL typed error (never the handler's).
     try {
-      await emitModuleFederationFallbackTelemetry(
+      void emitModuleFederationFallbackTelemetry(
         {
           appName: options.appName,
           classification: base.classification,
@@ -252,7 +237,7 @@ async function reportFailure<T>(
     if (critical) {
       throw reason;
     }
-    return undefined as T;
+    return undefined;
   }
 
   if (critical) {
@@ -266,14 +251,14 @@ async function reportFailure<T>(
  * load failure the required degraded handler runs (telemetry + fallback UI).
  *
  * For a `noncritical` consumption (see {@link SurfaceConsumerOptions.classification})
- * this resolves to the degraded value and never rejects, so a failing
+ * this resolves to the degraded value (or undefined if the handler fails), so a failing
  * consumption is isolated from any sibling. For a `critical` consumption (the
  * default) it rejects with the typed failure AFTER the degraded handler has
  * run, so callers / rollout machinery observe the failure.
  */
 export async function consumeSurface<T>(
   options: SurfaceConsumerOptions<T>,
-): Promise<T> {
+): Promise<T | undefined> {
   let ref: ParsedSurfaceRef;
   if (typeof options.ref === 'string') {
     const parsed = parseSurfaceRef(options.ref);
@@ -360,7 +345,7 @@ export function createSurfaceConsumer(
   return function consume<T>(
     options: Omit<SurfaceConsumerOptions<T>, keyof typeof base> &
       Partial<Pick<SurfaceConsumerOptions<T>, keyof typeof base>>,
-  ): Promise<T> {
+  ): Promise<T | undefined> {
     return consumeSurface<T>({
       ...base,
       ...options,

package/src/module-federation/distributed-ssr.tsx

@@ -51,8 +51,28 @@ export type DistributedSsrBoundaryProps<
   remote: string;
 };
 
+/**
+ * The Module Federation `createLazyComponent` options the distributed boundary
+ * owns. `injectLink` is always false: the boundary owns remote CSS (the
+ * fragment CSS inventory in workerd, the MF manifest in the browser), so the
+ * bridge must not render a second `<link>` in SSR HTML.
+ */
+export type DistributedSsrLazyComponentOptions = {
+  export: 'default';
+  fallback: ReactNode;
+  injectLink: false;
+  loading: null;
+};
+
 export type CreateDistributedSsrComponentOptions<Props extends object> = {
-  createComponent: () => ComponentType<Props>;
+  /**
+   * Creates the native remote on first render. Spread `options` into
+   * Module Federation's `createLazyComponent` and add the instance and
+   * loader.
+   */
+  createComponent: (
+    options: DistributedSsrLazyComponentOptions,
+  ) => ComponentType<Props>;
   expose: string;
   fallback: ReactNode;
   remote: string;
@@ -221,7 +241,12 @@ export function createDistributedSsrComponent<Props extends object>({
   let RemoteComponent: ComponentType<Props> | undefined;
 
   function DeferredRemoteComponent(props: Props) {
-    RemoteComponent ??= createComponent();
+    RemoteComponent ??= createComponent({
+      export: 'default',
+      fallback,
+      injectLink: false,
+      loading: null,
+    });
     return <RemoteComponent {...props} />;
   }