@bleedingdev/modern-js-runtime 3.5.0-ultramodern.6 → 3.5.0-ultramodern.76

package/dist/types/core/context/index.d.ts

@@ -1,13 +1,29 @@
-import type { InternalRuntimeContext } from '@modern-js/plugin';
-import type { NestedRoute, PageRoute } from '@modern-js/types';
 import type React from 'react';
-import type { RuntimeExtends } from '../plugin/types';
 import type { ServerPayload } from './serverPayload/index';
+export type RuntimeRoute = {
+    children?: RuntimeRoute[];
+    routes?: RuntimeRoute[];
+    [key: string]: any;
+};
+type RuntimeHookCaller = {
+    call: (...args: any[]) => any;
+    [key: string]: unknown;
+};
+type RuntimeHooks = Record<string, RuntimeHookCaller>;
+type RuntimePluginAPI = {
+    updateRuntimeContext?: (context: unknown) => unknown;
+    [key: string]: any;
+};
+type InternalRuntimeContextLike = {
+    hooks: RuntimeHooks;
+    pluginAPI?: RuntimePluginAPI;
+    [key: string]: any;
+};
 export { DefaultNotFound } from '../../router/runtime/DefaultNotFound';
 export { modifyRoutes, onAfterCreateRouter, onAfterHydrateRouter, onBeforeCreateRouter, onBeforeCreateRoutes, onBeforeHydrateRouter, type RouterExtendsHooks, } from '../../router/runtime/hooks';
 export { applyRouterRuntimeState, applyRouterServerPrepareResult, cleanupRouterRuntimeState, createRouterRuntimeState, createRouterServerSnapshot, getRouterHydrationScripts, getRouterMatchedRouteIds, getRouterRuntimeState, getRouterServerSnapshot, type RouterLifecycleContext, type RouterLifecyclePhase, } from '../../router/runtime/lifecycle';
-export { type RouterProviderFactory, type RouterProviderPlugin, registerRouterProvider, resolveRouterProvider, routerProviderRegistryHooks, } from '../../router/runtime/provider';
-export type { BuiltInRouterFramework, InternalRouterRuntimeState, InternalRouterServerSnapshot, RouterFramework, RouterRouteMatchSnapshot, RouterServerPrepareResult, } from '../../router/runtime/types';
+export { createRouterProviderRealm, type RouterProviderFactory, type RouterProviderPlugin, type RouterProviderRealm, type RouterProviderRegistration, registerRouterProvider, resolveRouterProvider, routerProviderRegistryHooks, } from '../../router/runtime/provider';
+export type { BuiltInRouterFramework, InternalRouterRuntimeState, InternalRouterServerSnapshot, LoaderFunction, LoaderFunctionArgs, ModernRoute, RouterFramework, RouterRouteMatchSnapshot, RouterServerPrepareResult, } from '../../router/runtime/types';
 export { createRuntimeContextExtension, type RuntimeContextExtension, } from './extensions';
 export { getInitialContext, InternalRuntimeContext, RuntimeContext, type TInternalRuntimeContext, type TRuntimeContext, } from './runtime';
 export type { PayloadRoute, ServerPayload } from './serverPayload/index';
@@ -20,7 +36,7 @@ interface GlobalContext {
     /**
      * nest router and page router config
      */
-    routes?: (NestedRoute | PageRoute)[];
+    routes?: RuntimeRoute[];
     /**
      * nest router init function
      */
@@ -33,7 +49,7 @@ interface GlobalContext {
      * Entry basename for routing
      */
     basename?: string;
-    internalRuntimeContext?: InternalRuntimeContext<RuntimeExtends>;
+    internalRuntimeContext?: InternalRuntimeContextLike;
     /**
      * RSCRoot
      */
@@ -48,9 +64,9 @@ export declare function getGlobalEnableRsc(): boolean | undefined;
 export declare function setGlobalContext(context: Omit<GlobalContext, 'internalRuntimeContext'>): void;
 export declare function getCurrentEntryName(): string | undefined;
 export declare function getGlobalRSCRoot(): React.ComponentType<{}> | undefined;
-export declare function setGlobalInternalRuntimeContext(context: InternalRuntimeContext<RuntimeExtends>): void;
-export declare function getGlobalInternalRuntimeContext(): InternalRuntimeContext<Required<import("@modern-js/plugin").RuntimePluginExtends<import("../plugin/types").RuntimeConfig, import("./runtime").TInternalRuntimeContext, {}, {}>>>;
+export declare function setGlobalInternalRuntimeContext(context: InternalRuntimeContextLike): void;
+export declare function getGlobalInternalRuntimeContext(): InternalRuntimeContextLike;
 export declare function getGlobalApp(): React.ComponentType<{}> | undefined;
-export declare function getGlobalRoutes(): undefined | (NestedRoute | PageRoute)[];
+export declare function getGlobalRoutes(): undefined | RuntimeRoute[];
 export declare function getGlobalLayoutApp(): React.ComponentType<{}> | undefined;
 export declare function getGlobalBasename(): string | undefined;

package/dist/types/core/context/monitors/default.d.ts

@@ -1,2 +1,10 @@
-import type { Monitors } from '@modern-js/types';
-export declare const defaultMonitors: Omit<Monitors, 'push'>;
+export type RuntimeMonitors = {
+    counter: (name: string, ...args: any[]) => void;
+    info: (...args: any[]) => void;
+    debug: (...args: any[]) => void;
+    trace: (...args: any[]) => void;
+    warn: (...args: any[]) => void;
+    error: (...args: any[]) => void;
+    timing: (name: string, dur: number, ...args: any[]) => void;
+};
+export declare const defaultMonitors: RuntimeMonitors;

package/dist/types/core/context/monitors/index.d.ts

@@ -1 +1 @@
-export declare const getMonitors: () => Omit<import("@modern-js/types").Monitors, "push">;
+export declare const getMonitors: () => import("./default").RuntimeMonitors;

package/dist/types/core/context/monitors/index.server.d.ts

@@ -1,2 +1,2 @@
-import type { Monitors } from '@modern-js/types';
-export declare const getMonitors: () => Omit<Monitors, 'push'>;
+import { type RuntimeMonitors } from './default';
+export declare const getMonitors: () => RuntimeMonitors;

package/dist/types/core/context/public.d.ts

@@ -0,0 +1,27 @@
+type RuntimeRequest = Record<string, unknown>;
+type RuntimeResponse = Record<string, unknown>;
+export type RequestContext = {
+    request: RuntimeRequest;
+    response: RuntimeResponse;
+};
+export interface TRuntimeContext {
+    initialData?: Record<string, unknown>;
+    isBrowser: boolean;
+    routes?: unknown[];
+    requestContext: RequestContext;
+    /**
+     * @deprecated Use `requestContext` instead
+     */
+    context: RequestContext;
+    [key: string]: unknown;
+}
+export declare const RuntimeContext: import("react").Context<TRuntimeContext>;
+/**
+ * deprecated, use RuntimeContext instead
+ */
+export declare const ReactRuntimeContext: import("react").Context<TRuntimeContext>;
+/**
+ * @deprecated use use(RuntimeContext) instead
+ */
+export declare const useRuntimeContext: () => TRuntimeContext;
+export {};

package/dist/types/core/context/runtime.d.ts

@@ -1,36 +1,26 @@
 import type { RouteObject, StaticHandlerContext } from '@modern-js/runtime-utils/router';
+import type { BaseSSRServerContext } from '@modern-js/types';
 import type { RouteManifest } from '../../router/runtime/types';
-import type { RequestContext, SSRServerContext } from '../types';
-export interface TRuntimeContext {
-    initialData?: Record<string, unknown>;
-    isBrowser: boolean;
-    routes?: RouteObject[];
-    requestContext: RequestContext;
-    /**
-     * @deprecated Use `requestContext` instead
-     */
-    context: RequestContext;
-    [key: string]: unknown;
-}
+import { type TRuntimeContext } from './public';
+export type InternalSSRContext = {
+    request: BaseSSRServerContext['request'] & {
+        raw?: Request;
+    };
+    response: BaseSSRServerContext['response'];
+    [key: string]: any;
+};
+export { ReactRuntimeContext, RuntimeContext, type TRuntimeContext, useRuntimeContext, } from './public';
 /**
  * InternalRuntimeContext used internally and by plugins
  */
 export interface TInternalRuntimeContext extends TRuntimeContext {
     routeManifest?: RouteManifest;
+    routes?: RouteObject[];
     routerContext?: StaticHandlerContext;
     unstable_getBlockNavState?: () => boolean;
-    ssrContext?: SSRServerContext;
+    ssrContext?: InternalSSRContext;
     _internalContext?: any;
     _internalRouterBaseName?: any;
 }
 export declare const InternalRuntimeContext: import("react").Context<TInternalRuntimeContext>;
-export declare const RuntimeContext: import("react").Context<TRuntimeContext>;
-/**
- * deprecated, use RuntimeContext instead
- */
-export declare const ReactRuntimeContext: import("react").Context<TRuntimeContext>;
 export declare const getInitialContext: (isBrowser?: boolean, routeManifest?: RouteManifest) => TInternalRuntimeContext;
-/**
- * @deprecated use use(RuntimeContext) instead
- */
-export declare const useRuntimeContext: () => TRuntimeContext;

package/dist/types/core/react/index.d.ts

@@ -1,2 +1,2 @@
 import type React from 'react';
-export declare function createRoot(UserApp?: React.ComponentType | null): React.ComponentType<any>;
+export declare function createRoot(UserApp?: React.ComponentType | null): any;

package/dist/types/core/server/requestResponse.d.ts

@@ -0,0 +1,15 @@
+import type { OnError } from '@modern-js/app-tools';
+import type { TInternalRuntimeContext } from '../context';
+import type { RouterCleanup } from './routerCleanup';
+export type ResponseProxy = {
+    headers: Record<string, string>;
+    status: number;
+};
+export type RedirectContext = {
+    enableRsc: boolean;
+    isRSCNavigation: boolean;
+    basename: string;
+};
+export declare const applyRouterSnapshotResult: (context: TInternalRuntimeContext, onError: OnError) => void;
+export declare const createLoaderRedirectResponse: (beforeRenderResult: Response | undefined, redirectCtx: RedirectContext) => Response | undefined;
+export declare const finalizeRenderResponse: (response: Response, responseProxy: ResponseProxy, redirectCtx: RedirectContext, routerCleanup: RouterCleanup) => Response;

package/dist/types/core/server/routerCleanup.d.ts

@@ -24,5 +24,6 @@ export type RouterCleanup = {
      */
     deferUntilBodyDone: (response: Response) => Response;
 };
-export declare function withRouterCleanup<T>(runtimeContext: TInternalRuntimeContext, onError: OnError, callback: (routerCleanup: RouterCleanup) => Promise<T>): Promise<T>;
+export declare function runWithRouterCleanupOnError<T>(routerCleanup: RouterCleanup, callback: () => Promise<T> | T): Promise<T>;
+export declare function finishWithRouterCleanup<T>(routerCleanup: RouterCleanup, callback: () => Promise<T> | T): Promise<T>;
 export declare function createRouterCleanup(runtimeContext: TInternalRuntimeContext, onError: OnError): RouterCleanup;

package/dist/types/core/server/scriptOrder.d.ts

@@ -9,7 +9,7 @@ type ScriptChunkLike = {
     filename?: string;
     url?: string;
 };
-export declare function getMatchedRouteAssets(runtimeContext: TInternalRuntimeContext, routeManifest?: RouteManifestLike): string[];
+export declare function getMatchedRouteChunks<T>(runtimeContext: TInternalRuntimeContext, routeManifest: RouteManifestLike | undefined, routeAssetToChunk: (asset: string) => T): T[];
 export declare const orderHydrationScriptChunks: <T extends ScriptChunkLike>({ asyncEntryChunks, collectedChunks, matchedRouteChunks, entryName, }: {
     asyncEntryChunks: T[];
     collectedChunks: T[];

package/dist/types/core/server/stream/shared.d.ts

@@ -1,7 +1,7 @@
 import type { OnError } from '@modern-js/app-tools';
 import type { ClientManifest as RscClientManifest, ServerManifest as RscServerManifest, SSRManifest as RscSSRManifest } from '@modern-js/types/server';
 import type React from 'react';
-import type { TRuntimeContext } from '../../context';
+import type { TInternalRuntimeContext } from '../../context';
 import type { HandleRequestConfig } from '../requestHandler';
 import type { RenderStreaming, SSRConfig } from '../shared';
 export type RscManifest = {
@@ -11,7 +11,7 @@ export type RscManifest = {
     entryCssFiles?: Record<string, string[]>;
 };
 export type CreateReadableStreamFromElementOptions = {
-    runtimeContext: TRuntimeContext;
+    runtimeContext: TInternalRuntimeContext;
     config: HandleRequestConfig;
     ssrConfig: SSRConfig;
     htmlTemplate: string;

package/dist/types/core/server/string/loadable.d.ts

@@ -1,7 +1,6 @@
 import type { ReactElement } from 'react';
 import type { TInternalRuntimeContext } from '../../context';
 import type { ChunkSet, Collector } from './types';
-export { orderHydrationScriptChunks } from '../scriptOrder';
 declare module '@loadable/server' {
     interface ChunkExtractor {
         chunks: string[];
@@ -30,7 +29,6 @@ export declare class LoadableCollector implements Collector {
     private options;
     private extractor?;
     constructor(options: LoadableCollectorOptions);
-    private getMatchedRouteChunks;
     collect(comopnent: ReactElement): ReactElement;
     effect(): Promise<void>;
     private emitLoadableScripts;

package/dist/types/exports/head.d.ts

@@ -2,7 +2,7 @@ import React from 'react';
 import { Helmet as AsyncHelmet, HelmetData as AsyncHelmetData, type HelmetDatum, type HelmetHTMLBodyDatum, type HelmetHTMLElementDatum, type HelmetProps, HelmetProvider, type HelmetServerState, type HelmetTags } from 'react-helmet-async';
 export declare const Helmet: (props: React.PropsWithChildren<HelmetProps>) => React.CElement<React.PropsWithChildren<HelmetProps>, AsyncHelmet> | null;
 declare const head: {
-    Helmet: (props: React.PropsWithChildren<HelmetProps>) => React.CElement<React.PropsWithChildren<HelmetProps>, AsyncHelmet> | null;
+    Helmet: typeof Helmet;
     HelmetData: typeof AsyncHelmetData;
     HelmetProvider: typeof HelmetProvider;
 };

package/dist/types/index.d.ts

@@ -1,10 +1,10 @@
-import type { RouterConfig } from './router/internal';
-export type { RuntimeConfig } from './common';
+import type { RouterConfig } from './router/runtime/types';
+export type { RuntimeConfig, RuntimePlugin } from './common';
 export { isBrowser } from './common';
-export type { RuntimePlugin } from './core';
-export { defineRuntimeConfig, RuntimeContext, useRuntimeContext, } from './core';
+export { defineRuntimeConfig } from './core/config';
 export { getMonitors } from './core/context/monitors';
+export type { TRuntimeContext } from './core/context/public';
+export { RuntimeContext, useRuntimeContext, } from './core/context/public';
 export { getRequest } from './core/context/request';
 export { redirect, setHeaders, setStatus } from './core/context/response';
-export type { TRuntimeContext } from './core/context/runtime';
 export type { RouterConfig };

package/dist/types/internal.d.ts

@@ -1,2 +1 @@
 export { InternalRuntimeContext, type TInternalRuntimeContext, } from './core/context/runtime';
-export type { SSRServerContext } from './core/types';

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';
+import { type DiscoveryError, type EnvironmentId, type ParsedSurfaceRef, type ResolvedDeliveryUnit, type SurfaceResolutionProvider } from './surface-resolution-types';
+/** 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 = {
+    children: ReactNode;
+    expose: string;
+    fallback: ReactNode;
+    fragmentProps?: Record<string, unknown>;
+    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({ children, expose, fallback, fragmentProps, remote, }: DistributedSsrBoundaryProps): 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

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

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

@@ -0,0 +1,72 @@
+/**
+ * G24a/b — last-known-good (LKG) provider wrapper.
+ *
+ * RESOLUTION-0001 §2.2: the LKG cache "wraps any provider; serves the last
+ * complete record on provider failure, marked `compatibility: 'degraded'`". It
+ * is universal — no DOM/fetch/framework coupling — so the same wrapper works in
+ * the browser, Node, and Cloudflare.
+ *
+ * Rollback semantics (ADR-0019 / CONTEXT.md Rollback): the delivery UNIT is
+ * the unit of rollback. The cache stores exactly ONE whole
+ * {@link ResolvedDeliveryUnit} per (unitId, env) key — never per (ref, env) —
+ * so every surface of a unit shares one snapshot and a fresh success swaps that
+ * snapshot atomically for all of them (two surfaces can never be served from
+ * different cached build markers). It never stores or serves a partial record,
+ * and it never mixes locations across build markers — a served degraded record
+ * is a byte-for-byte prior success with only its compatibility verdict flipped
+ * to `degraded`. An `incompatible` record is never good: it is neither cached
+ * as the last-known-good snapshot nor ever served. The ref's external-major
+ * participates in lookup validation but not in the storage key.
+ */
+import { type ResolvedDeliveryUnit, type SurfaceResolutionProvider } from './surface-resolution-types';
+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<any>;
+};
+export default createModuleFederationManifestRecoveryPlugin;

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

@@ -0,0 +1,23 @@
+/**
+ * Surface-resolution types for the module-federation runtime.
+ *
+ * Thin re-export of the canonical module in `@modern-js/utils/universal`
+ * (`packages/toolkit/utils/src/universal/surface-resolution/`,
+ * RESOLUTION-0001). Kept as a file so existing `./surface-resolution-types`
+ * imports stay stable. Only helpers the canonical module deliberately does not
+ * ship (the (ref, env) cache key) live here, implemented against canonical
+ * types.
+ */
+import { type EnvironmentId, type ParsedSurfaceRef } from '@modern-js/utils/universal';
+export { type CompatibilityStatus, type CompatibilityVerdict, createDiscoveryError, type DiscoveryError, type DiscoveryErrorCode, type DiscoveryResult, type EnvironmentId, formatSurfaceRef, type ParsedSurfaceRef, parseSurfaceRef, type ResolvedDeliveryUnit, type ResolvedSurface, type ResolvedSurfaceKind, type ResolvedSurfaceLocation, type ResolvedSurfaceLocationPlatform, type SurfaceRefParseError, type SurfaceRefParseResult, type SurfaceResolutionProvider, validateSurfaceRef, } from '@modern-js/utils/universal';
+/** Stable cache/identity key for a (ref, env) pair. */
+export declare function surfaceResolutionKey(ref: ParsedSurfaceRef, env: EnvironmentId): string;
+/**
+ * Stable cache key for a (deliveryUnit, env) pair — ONE record per unit per
+ * env (ADR-0019 atomicity). All surfaces of a unit share this key so a refresh
+ * replaces the whole unit snapshot atomically for every surface, and two
+ * surfaces of the same unit can never be served from different cached
+ * snapshots. The ref's external-major participates in lookup validation (see
+ * the LKG provider), not in this key.
+ */
+export declare function deliveryUnitResolutionKey(unitId: string, env: EnvironmentId): string;

package/dist/types/router/cli/constants.d.ts

@@ -18,6 +18,7 @@ export declare const NESTED_ROUTE: {
     PAGE_FILE: string;
     PAGE_CONFIG_FILE: string;
     PAGE_LOADER_FILE: string;
+    PAGE_SEARCH_FILE: string;
     PAGE_DATA_FILE: string;
     PAGE_CLIENT_LOADER: string;
     SPLATE_FILE: string;

package/dist/types/router/runtime/hooks.d.ts

@@ -1,12 +1,16 @@
 import type { RouteObject } from '@modern-js/runtime-utils/router';
 import type { TRuntimeContext } from '../../core/context/runtime';
 import type { RouterLifecycleContext } from './lifecycle';
-declare const modifyRoutes: import("@modern-js/plugin").SyncHook<(routes: RouteObject[]) => RouteObject[]>;
-declare const onBeforeCreateRoutes: import("@modern-js/plugin").SyncHook<(context: TRuntimeContext) => void>;
-declare const onBeforeCreateRouter: import("@modern-js/plugin").SyncHook<(context: RouterLifecycleContext) => void>;
-declare const onAfterCreateRouter: import("@modern-js/plugin").SyncHook<(context: RouterLifecycleContext) => void>;
-declare const onBeforeHydrateRouter: import("@modern-js/plugin").SyncHook<(context: RouterLifecycleContext) => void>;
-declare const onAfterHydrateRouter: import("@modern-js/plugin").SyncHook<(context: RouterLifecycleContext) => void>;
+export type RouterSyncHook<Handler extends (...args: any[]) => any> = {
+    call: (...args: Parameters<Handler>) => ReturnType<Handler>;
+    [key: string]: unknown;
+};
+declare const modifyRoutes: RouterSyncHook<(routes: RouteObject[]) => RouteObject[]>;
+declare const onBeforeCreateRoutes: RouterSyncHook<(context: TRuntimeContext) => void>;
+declare const onBeforeCreateRouter: RouterSyncHook<(context: RouterLifecycleContext) => void>;
+declare const onAfterCreateRouter: RouterSyncHook<(context: RouterLifecycleContext) => void>;
+declare const onBeforeHydrateRouter: RouterSyncHook<(context: RouterLifecycleContext) => void>;
+declare const onAfterHydrateRouter: RouterSyncHook<(context: RouterLifecycleContext) => void>;
 export { modifyRoutes, onAfterCreateRouter, onAfterHydrateRouter, onBeforeCreateRouter, onBeforeCreateRoutes, onBeforeHydrateRouter, };
 export type RouterExtendsHooks = {
     modifyRoutes: typeof modifyRoutes;

package/dist/types/router/runtime/internal.d.ts

@@ -1,12 +1,22 @@
-import type { RuntimePlugin } from '../../core';
+import type { RuntimePlugin } from '../../common';
 import type { RouterExtendsHooks } from './hooks';
+import type { RouterProviderRegistration } from './provider';
 import type { RouterConfig, SingleRouteConfig } from './types';
-export declare const routerPlugin: (userConfig?: Partial<RouterConfig>) => RuntimePlugin<{
+type LocalRouterProvider = Omit<RouterProviderRegistration, 'isDefault'>;
+export type RouterPluginFactory = (userConfig?: Partial<RouterConfig>) => RuntimePlugin<{
     extendHooks: RouterExtendsHooks;
 }>;
+/**
+ * Create one router wrapper and its provider realm for a runtime entry. Optional
+ * providers are supplied by the entry-owning integration (for example the
+ * TanStack runtime/router module), so independently bundled apps never resolve
+ * factories from another app's module graph.
+ */
+export declare const createRouterPlugin: (localProviders?: readonly LocalRouterProvider[]) => RouterPluginFactory;
+export declare const routerPlugin: RouterPluginFactory;
 export default routerPlugin;
 export type { RouterExtendsHooks } from './hooks';
 export { modifyRoutes } from './plugin';
-export { type RouterProviderFactory, type RouterProviderPlugin, registerRouterProvider, resolveRouterProvider, } from './provider';
+export { createRouterProviderRealm, type RouterProviderFactory, type RouterProviderPlugin, type RouterProviderRealm, type RouterProviderRegistration, registerRouterProvider, resolveRouterProvider, } from './provider';
 export { renderRoutes } from './utils';
 export type { RouterConfig, SingleRouteConfig };