@bleedingdev/modern-js-runtime 3.9.0-ultramodern.1 → 3.9.0-ultramodern.11

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

@@ -1,104 +0,0 @@
-/**
- * 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

@@ -1,61 +0,0 @@
-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

@@ -1,71 +0,0 @@
-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

@@ -1,52 +0,0 @@
-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

@@ -1,25 +0,0 @@
-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;

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

@@ -1,23 +0,0 @@
-/**
- * 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/runtime/lifecycle.d.ts

@@ -1,27 +0,0 @@
-import type { RouteObject } from '@modern-js/runtime-utils/router';
-import type { TInternalRuntimeContext } from '../../core/context/runtime.js';
-import type { InternalRouterRuntimeState, InternalRouterServerSnapshot, RouterFramework, RouterRouteMatchSnapshot, RouterServerPrepareResult } from './types.js';
-export declare function getRouterRuntimeState(runtimeContext: object): InternalRouterRuntimeState | undefined;
-export declare function getRouterServerSnapshot(runtimeContext: object): InternalRouterServerSnapshot | undefined;
-export type RouterLifecyclePhase = 'ssr-prepare' | 'client-create' | 'hydrate';
-export type RouterLifecycleContext = {
-    framework: RouterFramework;
-    phase: RouterLifecyclePhase;
-    routes: RouteObject[];
-    runtimeContext: TInternalRuntimeContext;
-    basename?: string;
-    hydrationData?: unknown;
-    router?: unknown;
-    matches?: RouterRouteMatchSnapshot[];
-    cleanup?: () => void | Promise<void>;
-    serverSnapshot?: InternalRouterServerSnapshot;
-};
-type RouterSnapshotLike = Partial<InternalRouterServerSnapshot>;
-export declare function createRouterServerSnapshot(state: RouterSnapshotLike): InternalRouterServerSnapshot;
-export declare function createRouterRuntimeState(state: InternalRouterRuntimeState): InternalRouterRuntimeState;
-export declare function applyRouterRuntimeState(runtimeContext: TInternalRuntimeContext, state: InternalRouterRuntimeState): TInternalRuntimeContext;
-export declare function applyRouterServerPrepareResult(runtimeContext: TInternalRuntimeContext, result: RouterServerPrepareResult): TInternalRuntimeContext;
-export declare function getRouterHydrationScripts(runtimeContext: TInternalRuntimeContext): string[];
-export declare function getRouterMatchedRouteIds(runtimeContext: TInternalRuntimeContext): string[] | undefined;
-export declare function cleanupRouterRuntimeState(runtimeContext: TInternalRuntimeContext): Promise<void>;
-export {};

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

@@ -1,78 +0,0 @@
-/**
- * Fork-owned router-provider registry.
- *
- * `runtime.router.framework` selects the router implementation used by the
- * built-in router runtime plugin (`@modern-js/runtime/router/internal`).
- * Instead of hardcoding every implementation there, providers register
- * themselves here:
- *
- * - `react-router` registers itself as the default provider when the
- *   built-in router plugin module is loaded.
- * - `@modern-js/plugin-tanstack` registers the `tanstack` provider when its
- *   runtime entry is imported.
- */
-import type { RuntimePlugin } from '../../common.js';
-import type { RouterExtendsHooks } from './hooks.js';
-import type { RouterConfig } from './types.js';
-/**
- * The single declaration source for the router hook registry. Every router
- * provider (built-in react-router, @modern-js/plugin-tanstack, ...) and the
- * framework-resolving wrapper plugin register exactly these instances, so the
- * hook set is defined once and providers cannot drift apart.
- */
-export declare const routerProviderRegistryHooks: RouterExtendsHooks;
-export type RouterProviderPlugin = RuntimePlugin<{
-    extendHooks: RouterExtendsHooks;
-}>;
-/**
- * Guard for the wrapper plugin (`router/internal`): a resolved provider is
- * only invoked through `setup`, so registry hooks outside the canonical
- * router hook contract cannot be registered for it. Returns the offending
- * hook names and warns once so they are surfaced instead of silently dropped.
- */
-export declare function reportUnsupportedProviderRegistryHooks(providerPlugin: {
-    name?: string;
-    registryHooks?: Record<string, unknown>;
-}): string[];
-export type RouterProviderFactory = (userConfig: Partial<RouterConfig>) => RouterProviderPlugin;
-export type RouterProviderRegistration = {
-    name: string;
-    factory: RouterProviderFactory;
-    isDefault?: boolean;
-};
-/**
- * App-owned provider catalog. Provider factories close over their module graph,
- * so they must be resolved from the runtime wrapper that owns the app instead
- * of from a page-global first-registration winner.
- */
-export type RouterProviderRealm = Readonly<{
-    defaultProvider?: string;
-    get: (name: string) => RouterProviderFactory | undefined;
-    names: () => readonly string[];
-}>;
-export declare function createRouterProviderRealm(registrations: readonly RouterProviderRegistration[]): RouterProviderRealm;
-export declare function registerRouterProvider(name: string, factory: RouterProviderFactory, options?: {
-    isDefault?: boolean;
-}): void;
-export declare function resolveRouterProvider(framework?: RouterConfig['framework'], options?: {
-    /**
-     * Provider factories owned by the resolving app/runtime wrapper. A realm
-     * is the exclusive provider source when supplied because its factories
-     * close over the correct app module graph.
-     */
-    realm?: RouterProviderRealm;
-    /**
-     * Legacy single-provider override retained for published wrappers. New
-     * integrations should pass an app-owned `realm`, which supports every
-     * provider rather than only the default.
-     */
-    localDefault?: {
-        name: string;
-        factory: RouterProviderFactory;
-    };
-}): RouterProviderFactory;
-/**
- * Test-only escape hatch: compatibility registries live on `globalThis`, so
- * unit tests need a way to restore a pristine state between cases.
- */
-export declare function unsafe_resetRouterProvidersForTesting(): void;