@bleedingdev/modern-js-federation-runtime 0.0.0 → 3.9.0-ultramodern.5

package/dist/esm-node/module-federation/index.mjs

@@ -0,0 +1,116 @@
+import "node:module";
+export * from "./consume-surface.mjs";
+export * from "./distributed-ssr.mjs";
+export * from "./last-known-good.mjs";
+export * from "./manifest-recovery-runtime-plugin.mjs";
+export * from "./surface-resolution-types.mjs";
+const MODULE_FEDERATION_FALLBACK_SIGNAL_EVENT = 'modernjs:mf-runtime-fallback';
+const MODULE_FEDERATION_RECOVERY_SIGNAL_EVENT = 'modernjs:mf-runtime-recovery';
+const DEFAULT_RUNTIME_FALLBACK_SIGNAL_ENDPOINT = '/_modern/contract-gates/runtime-fallback';
+const DEFAULT_RUNTIME_FALLBACK_SIGNAL_AUTH_HEADER = 'x-modernjs-runtime-signal-token';
+class ModuleFederationRemoteLoadTimeoutError extends Error {
+    constructor(remote, timeoutMs){
+        super(`Loading remote "${remote}" timed out after ${timeoutMs}ms`);
+        this.name = 'ModuleFederationRemoteLoadTimeoutError';
+    }
+}
+class ModuleFederationRemoteLoadError extends Error {
+    constructor(remote, attempts, causeError){
+        super(`Unable to load remote "${remote}" after ${attempts} attempt${attempts > 1 ? 's' : ''}: ${causeError.message}`);
+        this.name = 'ModuleFederationRemoteLoadError';
+        this.remote = remote;
+        this.attempts = attempts;
+        this.causeError = causeError;
+    }
+}
+class ModuleFederationRemoteComponentContractError extends Error {
+    constructor(remote, exportName){
+        super(`Remote "${remote}" export "${exportName}" is not a valid React component`);
+        this.name = 'ModuleFederationRemoteComponentContractError';
+    }
+}
+function toError(error) {
+    if (error instanceof Error) return error;
+    return new Error('string' == typeof error ? error : 'Unknown remote load error');
+}
+function classifyModuleFederationFallback(error) {
+    const normalizedError = toError(error);
+    if (normalizedError instanceof ModuleFederationRemoteLoadError) return classifyModuleFederationFallback(normalizedError.causeError);
+    if (normalizedError instanceof ModuleFederationRemoteLoadTimeoutError) return 'timeout';
+    if (normalizedError instanceof ModuleFederationRemoteComponentContractError) return 'contract';
+    const message = normalizedError.message;
+    if (/version|requiredVersion|singleton|share scope|shared module/i.test(message)) return 'version-skew';
+    if (/network|fetch|script|timeout|chunk|loading/i.test(message)) return 'network';
+    return 'remote-unavailable';
+}
+function createModuleFederationFallbackTelemetry(input) {
+    const error = void 0 !== input.error ? toError(input.error) : void 0;
+    const status = input.status ?? 'degraded';
+    const eventName = input.eventName ?? ('recovered' === status ? MODULE_FEDERATION_RECOVERY_SIGNAL_EVENT : MODULE_FEDERATION_FALLBACK_SIGNAL_EVENT);
+    const metadata = {
+        ...input.metadata ?? {},
+        classification: input.classification,
+        remote: input.remote,
+        status
+    };
+    if (void 0 !== input.exportName) metadata.exportName = input.exportName;
+    if (void 0 !== input.runtimeDigest) metadata.runtimeDigest = input.runtimeDigest;
+    if (void 0 !== error) {
+        metadata.errorName = error.name;
+        metadata.errorMessage = error.message;
+    }
+    const payload = {
+        appName: input.appName,
+        eventName,
+        metadata,
+        phase: input.phase,
+        reason: input.classification,
+        schemaVersion: 1
+    };
+    if (void 0 !== input.entry) payload.entry = input.entry;
+    if (void 0 !== input.runtimeDigest) payload.runtimeDigest = input.runtimeDigest;
+    return payload;
+}
+function toModuleFederationFallbackAttributes(payload) {
+    return {
+        'data-mf-fallback-app': payload.appName,
+        'data-mf-fallback-classification': payload.reason,
+        'data-mf-fallback-phase': payload.phase,
+        'data-mf-fallback-remote': String(payload.metadata.remote),
+        'data-mf-fallback-status': String(payload.metadata.status),
+        'data-mf-telemetry-event': payload.eventName
+    };
+}
+async function emitModuleFederationFallbackTelemetry(input, options = {}) {
+    const payload = createModuleFederationFallbackTelemetry(input);
+    if ("u" > typeof window && 'function' == typeof window.dispatchEvent && "u" > typeof CustomEvent) window.dispatchEvent(new CustomEvent(payload.eventName, {
+        detail: payload
+    }));
+    const shouldPost = true === options.postSignal || Boolean(options.endpoint);
+    if (!shouldPost) return {
+        dispatched: true,
+        posted: false
+    };
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    if ('function' != typeof fetchImpl) return {
+        dispatched: true,
+        posted: false
+    };
+    const headers = new Headers({
+        'content-type': 'application/json'
+    });
+    if (void 0 !== options.authToken && options.authToken.length > 0) headers.set(options.authHeaderName ?? DEFAULT_RUNTIME_FALLBACK_SIGNAL_AUTH_HEADER, options.authToken);
+    const response = await fetchImpl(options.endpoint ?? DEFAULT_RUNTIME_FALLBACK_SIGNAL_ENDPOINT, {
+        body: JSON.stringify(payload),
+        headers,
+        method: 'POST',
+        keepalive: true
+    });
+    return {
+        dispatched: true,
+        posted: true,
+        postStatus: response.status
+    };
+}
+export { DISTRIBUTED_SSR_FRAGMENT_REQUEST_LOCALS_KEY, useDistributedSsrFragmentProps } from "./distributed-ssr.mjs";
+export { DEFAULT_RUNTIME_FALLBACK_SIGNAL_AUTH_HEADER, DEFAULT_RUNTIME_FALLBACK_SIGNAL_ENDPOINT, MODULE_FEDERATION_FALLBACK_SIGNAL_EVENT, MODULE_FEDERATION_RECOVERY_SIGNAL_EVENT, ModuleFederationRemoteComponentContractError, ModuleFederationRemoteLoadError, ModuleFederationRemoteLoadTimeoutError, classifyModuleFederationFallback, createModuleFederationFallbackTelemetry, emitModuleFederationFallbackTelemetry, toModuleFederationFallbackAttributes };

package/dist/esm-node/module-federation/last-known-good.mjs

@@ -0,0 +1,114 @@
+import "node:module";
+import { selectResolvedSurface } from "@modern-js/surface-resolution";
+import { createDiscoveryError, deliveryUnitResolutionKey } from "./surface-resolution-types.mjs";
+const LAST_KNOWN_GOOD_PROVIDER_NAME = 'last-known-good';
+function createInMemoryLkgStorage() {
+    const map = new Map();
+    return {
+        read (key) {
+            return map.get(key);
+        },
+        write (key, record) {
+            map.set(key, record);
+        }
+    };
+}
+function markDegraded(resolved, reason) {
+    return {
+        ...resolved,
+        compatibility: {
+            ...resolved.compatibility,
+            status: 'degraded',
+            reason
+        }
+    };
+}
+function staleRecordResult(ref, env, ageMs, maxStaleMs) {
+    return {
+        ok: false,
+        error: createDiscoveryError('stale-record', ref, `Last-known-good record for surface is stale: age ${ageMs}ms exceeds maxStaleMs ${maxStaleMs}ms`, {
+            env,
+            ageMs,
+            maxStaleMs
+        })
+    };
+}
+function resolutionAnswersRef(resolved, ref) {
+    const selected = selectResolvedSurface(resolved, ref);
+    return selected.ok && selected.surface.servedMajor === ref.major;
+}
+function createLastKnownGoodProvider(options) {
+    const storage = options.storage ?? createInMemoryLkgStorage();
+    const now = options.now ?? (()=>Math.floor(performance.timeOrigin + performance.now()));
+    const maxStaleMs = options.freshness?.maxStaleMs;
+    let nextResolutionGeneration = 0;
+    const latestCacheableGenerationByKey = new Map();
+    const writeTailByKey = new Map();
+    async function cacheCompatibleResolution(key, generation, record) {
+        latestCacheableGenerationByKey.set(key, Math.max(latestCacheableGenerationByKey.get(key) ?? 0, generation));
+        const previous = writeTailByKey.get(key) ?? Promise.resolve();
+        const write = previous.catch(()=>void 0).then(async ()=>{
+            if (latestCacheableGenerationByKey.get(key) !== generation) return;
+            await storage.write(key, record);
+        });
+        writeTailByKey.set(key, write);
+        try {
+            await write;
+        } finally{
+            if (writeTailByKey.get(key) === write) writeTailByKey.delete(key);
+        }
+    }
+    async function serveFromCache(ref, env, fallback) {
+        const key = deliveryUnitResolutionKey(ref.unitId, env);
+        const cached = await storage.read(key);
+        if (!cached) return fallback();
+        if (cached.major !== ref.major) return fallback();
+        if (!resolutionAnswersRef(cached.resolved, ref)) return fallback();
+        if ('compatible' !== cached.resolved.compatibility.status) return fallback();
+        const ageMs = now() - cached.storedAt;
+        if (void 0 !== maxStaleMs && ageMs > maxStaleMs) return staleRecordResult(ref, env, ageMs, maxStaleMs);
+        return {
+            ok: true,
+            unit: markDegraded(cached.resolved, `served last-known-good record (age ${ageMs}ms) after provider failure`)
+        };
+    }
+    return {
+        name: LAST_KNOWN_GOOD_PROVIDER_NAME,
+        async resolve (ref, env) {
+            const key = deliveryUnitResolutionKey(ref.unitId, env);
+            const generation = ++nextResolutionGeneration;
+            let resolution;
+            try {
+                resolution = await options.provider.resolve(ref, env);
+            } catch (error) {
+                return serveFromCache(ref, env, ()=>({
+                        ok: false,
+                        error: createDiscoveryError('provider-unavailable', ref, error instanceof Error ? error.message : 'provider threw a non-error value', {
+                            env,
+                            provider: options.provider.name
+                        })
+                    }));
+            }
+            if (!resolution.ok) {
+                const failure = resolution;
+                return serveFromCache(ref, env, ()=>failure);
+            }
+            if (!resolutionAnswersRef(resolution.unit, ref)) return serveFromCache(ref, env, ()=>({
+                    ok: false,
+                    error: createDiscoveryError('identity-mismatch', ref, `Provider ${options.provider.name} returned a delivery unit that does not answer the requested surface.`, {
+                        env,
+                        provider: options.provider.name,
+                        recordUnitId: resolution.unit.unitId,
+                        availableSurfaces: resolution.unit.surfaces.map((surface)=>surface.surfaceId)
+                    })
+                }));
+            if ('compatible' === resolution.unit.compatibility.status) await cacheCompatibleResolution(key, generation, {
+                resolved: resolution.unit,
+                storedAt: now(),
+                major: ref.major
+            });
+            return resolution;
+        }
+    };
+}
+export { LAST_KNOWN_GOOD_PROVIDER_NAME, createInMemoryLkgStorage, createLastKnownGoodProvider };

package/dist/esm-node/module-federation/manifest-recovery-runtime-plugin.mjs

@@ -0,0 +1,91 @@
+import "node:module";
+const DEFAULT_ATTEMPTS = 3;
+const DEFAULT_RETRY_DELAY_MS = 100;
+const DEFAULT_TIMEOUT_MS = 1000;
+const MAX_ATTEMPTS = 5;
+const MAX_RETRY_DELAY_MS = 1000;
+const MAX_TIMEOUT_MS = 5000;
+const RETRYABLE_HTTP_STATUSES = new Set([
+    408,
+    425,
+    429,
+    500,
+    502,
+    503,
+    504
+]);
+const NON_RETRYABLE_ERROR_PATTERNS = [
+    /RUNTIME-013/i,
+    /invalid manifest/i,
+    /manifest (?:schema|contract|version|identity)/i,
+    /(?:incompatible|mismatch).*(?:manifest|remote)/i
+];
+const clampInteger = (value, fallback, minimum, maximum)=>{
+    if (void 0 === value || !Number.isFinite(value)) return fallback;
+    return Math.min(maximum, Math.max(minimum, Math.floor(value)));
+};
+const getErrorMessage = (error)=>{
+    if (error instanceof Error) return error.message;
+    return 'string' == typeof error ? error : '';
+};
+const getErrorStatus = (error)=>{
+    if ('object' == typeof error && null !== error && 'status' in error && 'number' == typeof error.status) return error.status;
+};
+const isRetryableError = (error)=>{
+    if (error instanceof SyntaxError) return false;
+    const message = getErrorMessage(error);
+    if (NON_RETRYABLE_ERROR_PATTERNS.some((pattern)=>pattern.test(message))) return false;
+    const status = getErrorStatus(error);
+    if (void 0 !== status) return RETRYABLE_HTTP_STATUSES.has(status);
+    if (error instanceof Error && [
+        'AbortError',
+        'TimeoutError'
+    ].includes(error.name)) return true;
+    return error instanceof TypeError || /(?:fetch failed|network|ECONNREFUSED|ECONNRESET|ETIMEDOUT|EAI_AGAIN)/i.test(message);
+};
+const isHttpManifestUrl = (id)=>{
+    if (void 0 === id || 0 === id.length) return false;
+    try {
+        const url = new URL(id);
+        return ('http:' === url.protocol || 'https:' === url.protocol) && url.pathname.endsWith('.json');
+    } catch  {
+        return false;
+    }
+};
+const defaultWait = (milliseconds)=>new Promise((resolve)=>{
+        setTimeout(resolve, milliseconds);
+    });
+const fetchWithTimeout = (fetchImpl, url, timeoutMs)=>fetchImpl(url, {
+        signal: AbortSignal.timeout(timeoutMs)
+    });
+const createModuleFederationManifestRecoveryPlugin = (options = {})=>{
+    const attempts = clampInteger(options.attempts, DEFAULT_ATTEMPTS, 1, MAX_ATTEMPTS);
+    const retryDelayMs = clampInteger(options.retryDelayMs, DEFAULT_RETRY_DELAY_MS, 0, MAX_RETRY_DELAY_MS);
+    const timeoutMs = clampInteger(options.timeoutMs, DEFAULT_TIMEOUT_MS, 1, MAX_TIMEOUT_MS);
+    const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+    const waitImpl = options.waitImpl ?? defaultWait;
+    const recoverManifest = (url, attempt)=>{
+        const fetchManifest = ()=>Promise.resolve().then(()=>fetchWithTimeout(fetchImpl, url, timeoutMs)).then((response)=>{
+                if (!response.ok) {
+                    if (!RETRYABLE_HTTP_STATUSES.has(response.status) || attempt === attempts - 1) return;
+                    return recoverManifest(url, attempt + 1);
+                }
+                return Promise.resolve().then(()=>response.json()).then((manifest)=>manifest, ()=>void 0);
+            }, (error)=>{
+                if (!isRetryableError(error) || attempt === attempts - 1) return;
+                return recoverManifest(url, attempt + 1);
+            });
+        if (attempt > 0 && retryDelayMs > 0) return waitImpl(retryDelayMs).then(fetchManifest);
+        return fetchManifest();
+    };
+    return {
+        name: 'modern-js-manifest-recovery-plugin',
+        errorLoadRemote (args) {
+            if ('afterResolve' !== args.lifecycle || !isHttpManifestUrl(args.id) || !isRetryableError(args.error) || 'function' != typeof fetchImpl) return Promise.resolve(void 0);
+            return recoverManifest(args.id, 0);
+        }
+    };
+};
+const manifest_recovery_runtime_plugin = createModuleFederationManifestRecoveryPlugin;
+export default manifest_recovery_runtime_plugin;
+export { createModuleFederationManifestRecoveryPlugin };

package/dist/esm-node/module-federation/surface-resolution-types.mjs

@@ -0,0 +1,9 @@
+import "node:module";
+import { createDiscoveryError, formatSurfaceRef, parseSurfaceRef, validateSurfaceRef } from "@modern-js/surface-resolution";
+function surfaceResolutionKey(ref, env) {
+    return `${env}::${formatSurfaceRef(ref)}`;
+}
+function deliveryUnitResolutionKey(unitId, env) {
+    return `${env}::${unitId}`;
+}
+export { createDiscoveryError, deliveryUnitResolutionKey, formatSurfaceRef, parseSurfaceRef, surfaceResolutionKey, validateSurfaceRef };

package/dist/types/module-federation/consume-surface.d.ts

@@ -0,0 +1,104 @@
+/**
+ * G22 — mandatory degraded consumption API.
+ *
+ * CONTEXT.md (Degraded State): "consuming a surface obliges the consumer to
+ * define a degraded state". This module turns that obligation into a
+ * compile-level one: {@link SurfaceConsumerOptions.degraded} is a REQUIRED
+ * field, so a call site that forgets its fallback does not type-check.
+ *
+ * The consumer wraps the loadRemote-ish flow (resolve a SurfaceRef through a
+ * provider, then load the execution artifact from the resolved record) and
+ * guarantees isolation: any discovery/load failure is caught, classified,
+ * reported through the existing MF fallback telemetry, and handed to the
+ * required degraded handler.
+ *
+ * Criticality (owner-default 5: unclassified consumption is `critical`). For a
+ * `noncritical` consumption the degraded handler's result is returned and the
+ * failure is swallowed, so one failing consumption can never propagate to a
+ * sibling (CONTEXT.md: faults isolate at the vertical boundary). For a
+ * `critical` consumption the degraded handler still runs — telemetry and
+ * fallback-UI obligations hold — but the returned promise then REJECTS with the
+ * typed failure so callers and rollout machinery observe it. Critical
+ * consumption during a rollout window should be driven by expand/contract, not
+ * by silent degrade.
+ */
+import { type ModuleFederationFallbackClassification, type ModuleFederationFallbackTelemetryEmitOptions, type ModuleFederationFallbackTelemetryPayload } from './index.js';
+import { type DiscoveryError, type EnvironmentId, type ParsedSurfaceRef, type ResolvedDeliveryUnit, type SurfaceResolutionProvider } from './surface-resolution-types.js';
+/** Where in the consumption lifecycle a failure was raised. */
+export type SurfaceConsumptionPhase = 'discovery' | 'load' | 'mount';
+/**
+ * The typed failure surfaced to the degraded handler. Exactly one of
+ * `discoveryError` (resolver returned a typed {@link DiscoveryError}) or
+ * `error` (something threw) is populated for a given failure.
+ */
+export type SurfaceConsumptionFailure = {
+    ref: ParsedSurfaceRef;
+    env: EnvironmentId;
+    phase: SurfaceConsumptionPhase;
+    classification: ModuleFederationFallbackClassification;
+    /** Present when discovery returned a typed error state. */
+    discoveryError?: DiscoveryError;
+    /** Present when a thrown error caused the failure. */
+    error?: unknown;
+    /** The resolved record, when discovery succeeded but load/mount failed. */
+    resolved?: ResolvedDeliveryUnit;
+    /** The fallback telemetry payload emitted for this failure. */
+    telemetry: ModuleFederationFallbackTelemetryPayload;
+};
+export type SurfaceLoadInput = {
+    resolved: ResolvedDeliveryUnit;
+    ref: ParsedSurfaceRef;
+    env: EnvironmentId;
+};
+export type SurfaceConsumerOptions<T> = {
+    /** The logical surface to consume (object or canonical string form). */
+    ref: ParsedSurfaceRef | string;
+    env: EnvironmentId;
+    /** The pluggable resolution seam (RESOLUTION-0001 §2.2). */
+    provider: SurfaceResolutionProvider;
+    /** Consumer app name, used for telemetry attribution. */
+    appName: string;
+    /**
+     * Loads the execution artifact from a resolved record — the loadRemote-ish
+     * flow. Receives the whole {@link ResolvedDeliveryUnit} so the adapter reads
+     * locations under one buildMarker (RESOLUTION-0001 §2.3).
+     */
+    load: (input: SurfaceLoadInput) => Promise<T> | T;
+    /**
+     * REQUIRED degraded handler (G22 compile-level obligation). There is no
+     * default and no way to opt out at the type level: omitting this field is a
+     * compile error. Return the value to serve while the surface is unavailable
+     * or incompatible.
+     */
+    degraded: (failure: SurfaceConsumptionFailure) => T | Promise<T>;
+    /**
+     * Consumption criticality (owner-default 5). Defaults to `'critical'` when
+     * omitted.
+     *
+     * - `'noncritical'`: the degraded handler's result is returned and the
+     *   failure is swallowed — the promise never rejects.
+     * - `'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
+     *   over silent degrade for critical surfaces during rollout windows.
+     */
+    classification?: 'critical' | 'noncritical';
+    /** Optional telemetry emission options (endpoint/auth/fetch overrides). */
+    telemetry?: ModuleFederationFallbackTelemetryEmitOptions;
+};
+/**
+ * Consume one surface with a mandatory degraded fallback. On any discovery or
+ * 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
+ * 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 declare function consumeSurface<T>(options: SurfaceConsumerOptions<T>): Promise<T>;
+/**
+ * Build a reusable consumer bound to a provider/env/app, still requiring a
+ * degraded handler per call. Per-call options override the bound base.
+ */
+export declare function createSurfaceConsumer(base: Pick<SurfaceConsumerOptions<unknown>, 'provider' | 'env' | 'appName' | 'telemetry'>): <T>(options: Omit<SurfaceConsumerOptions<T>, keyof typeof base> & Partial<Pick<SurfaceConsumerOptions<T>, keyof typeof base>>) => Promise<T>;

package/dist/types/module-federation/distributed-ssr.d.ts

@@ -0,0 +1,61 @@
+import type { ComponentType, ReactNode } from 'react';
+export declare const DISTRIBUTED_SSR_FRAGMENTS_LOCALS_KEY = "__modernDistributedSsrFragments";
+export declare const DISTRIBUTED_SSR_FRAGMENT_REQUEST_LOCALS_KEY = "__modernDistributedSsrFragmentRequest";
+export type DistributedSsrFragment = {
+    boundaryId: string;
+    buildMarker?: string;
+    digest?: string;
+    expose: string;
+    html: string;
+    remote: string;
+    status: 'ready';
+};
+export type DistributedSsrFragmentFailure = {
+    boundaryId: string;
+    expose: string;
+    reason: string;
+    remote: string;
+    status: 'degraded';
+};
+type DistributedSsrFragmentResult = DistributedSsrFragment | DistributedSsrFragmentFailure;
+export type DistributedSsrFragmentContext = {
+    fragments?: Record<string, DistributedSsrFragment | DistributedSsrFragmentFailure>;
+    required: true;
+    resolve?: (remote: string, expose: string, props: Record<string, unknown>) => DistributedSsrFragmentResult | PromiseLike<DistributedSsrFragmentResult>;
+};
+export type DistributedSsrBoundaryProps<Props extends object = Record<string, unknown>> = {
+    children: ReactNode;
+    expose: string;
+    fallback: ReactNode;
+    fragmentProps?: Props;
+    remote: string;
+};
+export type CreateDistributedSsrComponentOptions<Props extends object> = {
+    createComponent: () => ComponentType<Props>;
+    expose: string;
+    fallback: ReactNode;
+    remote: string;
+};
+export declare function distributedSsrFragmentKey(remote: string, expose: string): string;
+export declare function useDistributedSsrFragmentProps<Props extends object>({ boundaryId, expose, }: {
+    boundaryId: string;
+    expose: string;
+}): Props;
+/**
+ * Keeps the browser on the native Module Federation component while allowing
+ * servers that cannot execute remote code (notably workerd) to render a
+ * trusted fragment produced by the remote Worker itself.
+ *
+ * Node SSR has no distributed-fragment context and therefore renders the
+ * child normally, preserving Module Federation's in-process SSR path.
+ */
+export declare function DistributedSsrBoundary<Props extends object = Record<string, unknown>>({ children, expose, fallback, fragmentProps, remote, }: DistributedSsrBoundaryProps<Props>): import("react").JSX.Element;
+/**
+ * Defers creation of the native Module Federation component until React
+ * actually renders that child. A workerd request with a verified distributed
+ * fragment never constructs the native remote, so its module cannot perform
+ * forbidden global-scope network I/O. Browser and Node rendering keep using
+ * the native Module Federation component unchanged.
+ */
+export declare function createDistributedSsrComponent<Props extends object>({ createComponent, expose, fallback, remote, }: CreateDistributedSsrComponentOptions<Props>): (props: Props) => import("react").JSX.Element;
+export {};

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

@@ -0,0 +1,71 @@
+export * from './consume-surface.js';
+export * from './distributed-ssr.js';
+export { DISTRIBUTED_SSR_FRAGMENT_REQUEST_LOCALS_KEY, useDistributedSsrFragmentProps, } from './distributed-ssr.js';
+export * from './last-known-good.js';
+export * from './manifest-recovery-runtime-plugin.js';
+export * from './surface-resolution-types.js';
+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;
+};
+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>;

package/dist/types/module-federation/last-known-good.d.ts

@@ -0,0 +1,52 @@
+import { type ResolvedDeliveryUnit, type SurfaceResolutionProvider } from './surface-resolution-types.js';
+export declare const LAST_KNOWN_GOOD_PROVIDER_NAME = "last-known-good";
+/** One cached complete record plus the time it was stored. */
+export type LkgRecord = {
+    resolved: ResolvedDeliveryUnit;
+    storedAt: number;
+    /**
+     * External-major selector the record was resolved against. Participates in
+     * lookup validation — a cached record is only served for a matching major —
+     * but never in the storage key, which is (unitId, env) so all surfaces of a
+     * unit share one atomically-swapped record.
+     */
+    major?: number;
+};
+/**
+ * Pluggable storage hook. The default is an in-memory Map; callers may supply a
+ * durable store (KV, disk, etc). Reads/writes may be async. A store only ever
+ * receives whole records.
+ */
+export type LkgStorage = {
+    read(key: string): (LkgRecord | undefined) | Promise<LkgRecord | undefined>;
+    write(key: string, record: LkgRecord): void | Promise<void>;
+};
+export type LkgFreshnessPolicy = {
+    /**
+     * Maximum age, in ms, a stored record may be served after a provider
+     * failure. When omitted, a served record never expires by age. A record
+     * older than this yields a typed `stale-record` discovery error.
+     */
+    maxStaleMs?: number;
+};
+export type LastKnownGoodOptions = {
+    /** The wrapped provider (env/static, Zephyr, or any other). */
+    provider: SurfaceResolutionProvider;
+    /** Pluggable storage; defaults to a process-local in-memory Map. */
+    storage?: LkgStorage;
+    freshness?: LkgFreshnessPolicy;
+    /** Clock injection for deterministic freshness tests. */
+    now?: () => number;
+};
+/** Default process-local in-memory storage. */
+export declare function createInMemoryLkgStorage(): LkgStorage;
+/**
+ * Wrap a provider with a last-known-good cache. On success the whole record is
+ * cached (atomic swap). On provider failure (typed discovery error or a thrown
+ * error) the last complete record is served, marked degraded — unless it has
+ * expired per {@link LkgFreshnessPolicy}, in which case a typed `stale-record`
+ * error is returned. If there is no cached record, the original failure is
+ * passed through (a thrown error becomes a `provider-unavailable` discovery
+ * error).
+ */
+export declare function createLastKnownGoodProvider(options: LastKnownGoodOptions): SurfaceResolutionProvider;

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

@@ -0,0 +1,25 @@
+type ErrorLoadRemoteArgs = {
+    id?: string;
+    error?: unknown;
+    lifecycle?: string;
+};
+export type ModuleFederationManifestRecoveryPluginOptions = {
+    attempts?: number;
+    retryDelayMs?: number;
+    timeoutMs?: number;
+    fetchImpl?: typeof fetch;
+    waitImpl?: (milliseconds: number) => Promise<void>;
+};
+/**
+ * Gives server-side manifest loading a small, bounded recovery window.
+ *
+ * Returning `undefined` deliberately hands control back to Module Federation:
+ * its runtime preserves the original typed RUNTIME-003 error and invalidates
+ * the rejected manifest promise. Parsed manifests are returned without schema
+ * interpretation so runtime-core remains the authority for RUNTIME-013.
+ */
+export declare const createModuleFederationManifestRecoveryPlugin: (options?: ModuleFederationManifestRecoveryPluginOptions) => {
+    name: string;
+    errorLoadRemote(args: ErrorLoadRemoteArgs): Promise<unknown>;
+};
+export default createModuleFederationManifestRecoveryPlugin;