@mfeflow/runtime 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sanjeev Sharma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,44 @@
-# Temporary Holding Version
+# @mfeflow/runtime
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Runtime for mfeflow shells. It reads the remote registry index and registers each remote with Module Federation, renders remotes inside `RemoteBoundary` (timeout, fallback, error reporting), checks that singletons are really shared, and composes the shell's providers.
+
+## Install
+
+```sh
+pnpm add @mfeflow/runtime @module-federation/enhanced react
+```
+
+`@module-federation/enhanced` (^2.9.0) and `react` (^19) are peer dependencies.
+
+## Usage
+
+```tsx
+import {
+  RemoteBoundary,
+  loadRegistryIndex,
+  registerRemotesFromIndex,
+  reportRemoteError,
+} from '@mfeflow/runtime';
+
+try {
+  registerRemotesFromIndex(await loadRegistryIndex(), { allowedOrigins: [location.origin] });
+} catch (error) {
+  reportRemoteError('shell', 'registry', error);
+}
+
+// A slow, missing or crashing remote shows its fallback; the rest of the page keeps working.
+<RemoteBoundary id="cart/App" timeoutMs={5000} loading={<p>Loading</p>} />;
+```
+
+`composeProviders([...])` nests providers (first is outermost) and `withProps` binds props to one. `checkSingletons` and `assertRequested` back the `?mfeflow-assert` check. Optional plugins are at `@mfeflow/runtime/plugins/report` and `@mfeflow/runtime/plugins/entry-retry`.
+
+## Module Federation sharing
+
+Bucket: **singleton**. This package keeps page-wide state, so the shell and every remote must use one copy. `@mfeflow/rsbuild` shares it as a Module Federation singleton by default (`createShellConfig` and `createRemoteConfig`); if you configure sharing by hand, mark it `singleton: true`.
+
+## Links
+
+- [mfeflow repository](https://github.com/mfeflow/mfeflow) and its README
+- [Documentation](https://mfeflow.github.io/mfeflow/)
+
+MIT licensed.

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+export { composeProviders, withProps, type ProviderComponent } from './providers.js';
+export { REMOTE_ERROR_EVENT, reportRemoteError, type RemoteErrorReport } from './report.js';
+export { DEFAULT_REGISTRY_URL, isRegistryIndex, loadRegistryIndex, REGISTRY_GLOBAL, registeredRemotes, registerRemotesFromIndex, type LoadRegistryOptions, type RegisterOptions, type RegistryIndex, type RegistryRemote, } from './registry.js';
+export { DefaultRemoteFallback, RemoteBoundary, remoteComponent, type FallbackProps, type RemoteBoundaryProps, type RemoteOptions, } from './remote.js';
+export { ASSERT_PARAM, assertRequested, checkSingletons, type SingletonCheck } from './singletons.js';
+export { applyDevOverrides, OVERRIDE_PARAM, OVERRIDE_STORAGE_KEY, type DevOverrideOptions, } from './overrides.js';
+export { DevOverlay, type DevOverlayProps } from './overlay.js';
+export { fetchRuntimeConfig, RUNTIME_CONFIG_KEY, RUNTIME_CONFIG_URL, type RuntimeConfigValues, } from './runtime-config.js';

package/dist/index.js

@@ -0,0 +1,8 @@
+export { composeProviders, withProps } from "./providers.js";
+export { REMOTE_ERROR_EVENT, reportRemoteError } from "./report.js";
+export { DEFAULT_REGISTRY_URL, REGISTRY_GLOBAL, isRegistryIndex, loadRegistryIndex, registerRemotesFromIndex, registeredRemotes } from "./registry.js";
+export { DefaultRemoteFallback, RemoteBoundary, remoteComponent } from "./remote.js";
+export { ASSERT_PARAM, assertRequested, checkSingletons } from "./singletons.js";
+export { OVERRIDE_PARAM, OVERRIDE_STORAGE_KEY, applyDevOverrides } from "./overrides.js";
+export { DevOverlay } from "./overlay.js";
+export { RUNTIME_CONFIG_KEY, RUNTIME_CONFIG_URL, fetchRuntimeConfig } from "./runtime-config.js";

package/dist/overlay.d.ts

@@ -0,0 +1,11 @@
+export interface DevOverlayProps {
+    /** Render nothing unless true (e.g. `import.meta.env.DEV`). */
+    enabled: boolean;
+    /** Start open. Default false; toggle with Alt+Shift+M. */
+    open?: boolean;
+}
+/**
+ * Dev-only panel: which remotes and versions the shell registered (overrides
+ * marked), and every remote error as it happens. Alt+Shift+M toggles it.
+ */
+export declare function DevOverlay({ enabled, open }: DevOverlayProps): import("react").JSX.Element | null;

package/dist/overlay.js

@@ -0,0 +1,100 @@
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import { useEffect, useState } from "react";
+import { registeredRemotes } from "./registry.js";
+import { REMOTE_ERROR_EVENT } from "./report.js";
+const box = {
+    position: 'fixed',
+    insetBlockEnd: '12px',
+    insetInlineEnd: '12px',
+    zIndex: 2147483647,
+    maxWidth: '420px',
+    maxHeight: '60vh',
+    overflow: 'auto',
+    padding: '12px',
+    borderRadius: '8px',
+    font: '12px/1.4 ui-monospace, monospace',
+    background: '#111827',
+    color: '#e5e7eb',
+    boxShadow: '0 8px 24px rgba(0,0,0,.35)'
+};
+function DevOverlay({ enabled, open = false }) {
+    const [visible, setVisible] = useState(open);
+    const [reports, setReports] = useState(()=>globalThis.mfeflowReports ?? []);
+    useEffect(()=>{
+        if (!enabled) return;
+        const onKey = (e)=>{
+            if (e.altKey && e.shiftKey && 'KeyM' === e.code) setVisible((v)=>!v);
+        };
+        const onReport = ()=>{
+            setReports([
+                ...globalThis.mfeflowReports ?? []
+            ]);
+        };
+        window.addEventListener('keydown', onKey);
+        window.addEventListener(REMOTE_ERROR_EVENT, onReport);
+        return ()=>{
+            window.removeEventListener('keydown', onKey);
+            window.removeEventListener(REMOTE_ERROR_EVENT, onReport);
+        };
+    }, [
+        enabled
+    ]);
+    if (!enabled || !visible) return null;
+    const remotes = registeredRemotes();
+    return /*#__PURE__*/ jsxs("aside", {
+        style: box,
+        "aria-label": "mfeflow dev overlay",
+        "data-mfeflow-overlay": "",
+        children: [
+            /*#__PURE__*/ jsx("strong", {
+                children: "mfeflow"
+            }),
+            " \xb7 ",
+            remotes.length,
+            " remotes",
+            /*#__PURE__*/ jsx("ul", {
+                style: {
+                    margin: '8px 0',
+                    paddingInlineStart: '16px'
+                },
+                children: remotes.map((r)=>/*#__PURE__*/ jsxs("li", {
+                        children: [
+                            r.name,
+                            " ",
+                            /*#__PURE__*/ jsx("span", {
+                                style: {
+                                    opacity: 0.7
+                                },
+                                children: r.version ?? 'unversioned'
+                            }),
+                            'override' === r.version ? ' (override)' : null
+                        ]
+                    }, r.name))
+            }),
+            reports.length > 0 ? /*#__PURE__*/ jsxs(Fragment, {
+                children: [
+                    /*#__PURE__*/ jsx("strong", {
+                        children: "errors"
+                    }),
+                    /*#__PURE__*/ jsx("ul", {
+                        style: {
+                            margin: '8px 0',
+                            paddingInlineStart: '16px',
+                            color: '#fca5a5'
+                        },
+                        children: reports.map((r)=>/*#__PURE__*/ jsxs("li", {
+                                children: [
+                                    r.mfe,
+                                    " \xb7 ",
+                                    r.where,
+                                    ": ",
+                                    r.message
+                                ]
+                            }, `${String(r.time)}-${r.mfe}-${r.where}`))
+                    })
+                ]
+            }) : null
+        ]
+    });
+}
+export { DevOverlay };

package/dist/overrides.d.ts

@@ -0,0 +1,22 @@
+import type { RegistryIndex } from './registry.js';
+export interface DevOverrideOptions {
+    /** Must be explicitly true, e.g. `import.meta.env.DEV` or a staging flag. Never on in production. */
+    enabled: boolean;
+    /** Hostnames overrides may point at. Default `localhost` and `127.0.0.1` (any port). */
+    allowedHosts?: readonly string[];
+    /** Defaults to `location.search`. */
+    search?: string;
+    /** Where overrides persist across navigations. Defaults to `sessionStorage`. */
+    storage?: Pick<Storage, 'getItem' | 'setItem' | 'removeItem'>;
+}
+export declare const OVERRIDE_PARAM = "mfe-override";
+export declare const OVERRIDE_STORAGE_KEY = "shell:mfe-overrides";
+/**
+ * Points chosen remotes at local or preview builds without touching the
+ * registry: `?mfe-override=cart@http://localhost:4312/mf-manifest.json`
+ * (comma-separate several). Overrides persist for the session;
+ * `?mfe-override=reset` clears them. Only allowlisted hosts are accepted.
+ * Needs the manifest loader, so it works in development builds only; when
+ * disabled and the parameter is present it reports that it was ignored.
+ */
+export declare function applyDevOverrides(index: RegistryIndex, options: DevOverrideOptions): RegistryIndex;

package/dist/overrides.js

@@ -0,0 +1,76 @@
+import { reportRemoteError } from "./report.js";
+const OVERRIDE_PARAM = 'mfe-override';
+const OVERRIDE_STORAGE_KEY = 'shell:mfe-overrides';
+function parse(value) {
+    const out = {};
+    for (const part of value.split(',')){
+        const at = part.indexOf('@');
+        if (!(at <= 0)) out[part.slice(0, at).trim()] = part.slice(at + 1).trim();
+    }
+    return out;
+}
+function isRecordOfStrings(value) {
+    return 'object' == typeof value && null !== value && !Array.isArray(value) && Object.values(value).every((v)=>'string' == typeof v);
+}
+function applyDevOverrides(index, options) {
+    const search = options.search ?? ("u" < typeof location ? '' : location.search);
+    if (!options.enabled) {
+        if (new URLSearchParams(search).has(OVERRIDE_PARAM)) reportRemoteError('shell', 'override', new Error('overrides are disabled in this build'));
+        return index;
+    }
+    const storage = options.storage ?? ("u" < typeof sessionStorage ? void 0 : sessionStorage);
+    const hosts = options.allowedHosts ?? [
+        'localhost',
+        '127.0.0.1'
+    ];
+    const param = new URLSearchParams(search).get(OVERRIDE_PARAM);
+    let overrides = {};
+    if ('reset' === param) storage?.removeItem(OVERRIDE_STORAGE_KEY);
+    else {
+        try {
+            const saved = JSON.parse(storage?.getItem(OVERRIDE_STORAGE_KEY) ?? '{}');
+            if (isRecordOfStrings(saved)) overrides = saved;
+        } catch  {}
+        if (param) overrides = {
+            ...overrides,
+            ...parse(param)
+        };
+    }
+    const accepted = {};
+    for (const [name, entry] of Object.entries(overrides)){
+        let host;
+        try {
+            host = new URL(entry).hostname;
+        } catch  {
+            reportRemoteError(name, 'override', new Error(`invalid override URL "${entry}"`));
+            continue;
+        }
+        if (!hosts.includes(host)) {
+            reportRemoteError(name, 'override', new Error(`override host ${host} is not allowed`));
+            continue;
+        }
+        accepted[name] = entry;
+    }
+    if (Object.keys(accepted).length > 0) storage?.setItem(OVERRIDE_STORAGE_KEY, JSON.stringify(accepted));
+    const known = new Set(index.remotes.map((r)=>r.name));
+    const remotes = index.remotes.map((r)=>{
+        const entry = accepted[r.name];
+        if (void 0 === entry) return r;
+        const { remoteEntry: _replaced, ...rest } = r;
+        return {
+            ...rest,
+            entry,
+            version: 'override'
+        };
+    });
+    for (const [name, entry] of Object.entries(accepted))if (!known.has(name)) remotes.push({
+        name,
+        entry,
+        version: 'override'
+    });
+    return {
+        ...index,
+        remotes
+    };
+}
+export { OVERRIDE_PARAM, OVERRIDE_STORAGE_KEY, applyDevOverrides };

package/dist/plugins/entry-retry.d.ts

@@ -0,0 +1,10 @@
+import type { ModuleFederationRuntimePlugin } from '@module-federation/enhanced/runtime';
+export interface EntryRetryOptions {
+    /** Retries after the first failure. Default 2. */
+    times?: number;
+    /** Wait before retry n is `delayMs * n`. Default 300. */
+    delayMs?: number;
+}
+/** Retries a failed remote entry with a growing delay and a `?retry=n` cache-buster. */
+export declare function createEntryRetryPlugin(options?: EntryRetryOptions): ModuleFederationRuntimePlugin;
+export default function mfeflowEntryRetryPlugin(): ModuleFederationRuntimePlugin;

package/dist/plugins/entry-retry.js

@@ -0,0 +1,64 @@
+const sleep = (ms)=>new Promise((resolve)=>{
+        setTimeout(resolve, ms);
+    });
+function createEntryRetryPlugin(options = {}) {
+    const times = options.times ?? 2;
+    const delayMs = options.delayMs ?? 300;
+    const inFlight = new Map();
+    async function attempts({ getRemoteEntry, origin, remoteInfo, remoteEntryExports, globalLoading, uniqueKey }, joinable) {
+        let failed = globalLoading[uniqueKey];
+        try {
+            for(let attempt = 1; attempt <= times; attempt++){
+                if (globalLoading[uniqueKey] === failed || void 0 === globalLoading[uniqueKey]) {
+                    globalLoading[uniqueKey] = joinable;
+                    failed = joinable;
+                }
+                await sleep(delayMs * attempt);
+                if (globalLoading[uniqueKey] === failed) delete globalLoading[uniqueKey];
+                try {
+                    const exports = await getRemoteEntry({
+                        origin,
+                        remoteInfo,
+                        remoteEntryExports,
+                        getEntryUrl: (url)=>`${url}${url.includes('?') ? '&' : '?'}retry=${String(attempt)}`
+                    });
+                    if (exports) return exports;
+                } catch  {}
+                failed = globalLoading[uniqueKey];
+            }
+            return;
+        } finally{
+            if (globalLoading[uniqueKey] === joinable) delete globalLoading[uniqueKey];
+        }
+    }
+    function retry(args) {
+        const running = inFlight.get(args.uniqueKey);
+        if (running) return running;
+        let settle;
+        const settled = new Promise((resolve)=>{
+            settle = resolve;
+        });
+        const joinable = settled.then((exports)=>{
+            if (!exports) throw new Error(`entry of "${args.remoteInfo.name}" failed to load after retries`);
+            return exports;
+        });
+        joinable.catch(()=>void 0);
+        const started = attempts(args, joinable).finally(()=>{
+            inFlight.delete(args.uniqueKey);
+        }).then((exports)=>{
+            settle(exports);
+            return exports;
+        });
+        inFlight.set(args.uniqueKey, started);
+        return started;
+    }
+    return {
+        name: 'mfeflow-entry-retry',
+        loadEntryError: retry
+    };
+}
+function mfeflowEntryRetryPlugin() {
+    return createEntryRetryPlugin();
+}
+export default mfeflowEntryRetryPlugin;
+export { createEntryRetryPlugin };

package/dist/plugins/report.d.ts

@@ -0,0 +1,11 @@
+import type { ModuleFederationRuntimePlugin } from '@module-federation/enhanced/runtime';
+declare global {
+    var mfeflowReports: {
+        mfe: string;
+        where: string;
+        message: string;
+        time: number;
+    }[] | undefined;
+}
+/** Reports every Module Federation load failure with the remote's name. */
+export default function mfeflowReportPlugin(): ModuleFederationRuntimePlugin;

package/dist/plugins/report.js

@@ -0,0 +1,20 @@
+const EVENT = 'mfeflow:remote-error';
+function mfeflowReportPlugin() {
+    return {
+        name: 'mfeflow-report',
+        errorLoadRemote (args) {
+            const mfe = args.id.split('/')[0] ?? args.id;
+            const report = {
+                mfe,
+                where: `errorLoadRemote:${args.lifecycle}`,
+                message: args.error instanceof Error ? args.error.message : String(args.error),
+                time: Date.now()
+            };
+            (globalThis.mfeflowReports ??= []).push(report);
+            if ("u" > typeof window && 'function' == typeof CustomEvent) window.dispatchEvent(new CustomEvent(EVENT, {
+                detail: report
+            }));
+        }
+    };
+}
+export default mfeflowReportPlugin;

package/dist/providers.d.ts

@@ -0,0 +1,13 @@
+import type { ComponentType, ReactNode } from 'react';
+export type ProviderComponent = ComponentType<{
+    children?: ReactNode;
+}>;
+/** Binds props to a provider so it fits in a `composeProviders` list. */
+export declare function withProps<P extends object>(Component: ComponentType<P & {
+    children?: ReactNode;
+}>, props: P): ProviderComponent;
+/**
+ * Nests providers so the first one in the list is the outermost. The shell and
+ * `renderWithPlatform` in tests use the same list, so tests see the real platform.
+ */
+export declare function composeProviders(providers: readonly ProviderComponent[]): ProviderComponent;

package/dist/providers.js

@@ -0,0 +1,26 @@
+import { jsx } from "react/jsx-runtime";
+function withProps(Component, props) {
+    function WithProps({ children }) {
+        return /*#__PURE__*/ jsx(Component, {
+            ...props,
+            children: children
+        });
+    }
+    WithProps.displayName = `withProps(${Component.displayName ?? Component.name})`;
+    return WithProps;
+}
+function composeProviders(providers) {
+    function ComposedProviders({ children }) {
+        let tree = children;
+        for(let i = providers.length - 1; i >= 0; i--){
+            const Provider = providers[i];
+            if (Provider) tree = /*#__PURE__*/ jsx(Provider, {
+                children: tree
+            });
+        }
+        return tree;
+    }
+    ComposedProviders.displayName = `composeProviders(${String(providers.length)})`;
+    return ComposedProviders;
+}
+export { composeProviders, withProps };

package/dist/registry.d.ts

@@ -0,0 +1,75 @@
+export interface RegistryRemote {
+    /** Module Federation name, e.g. `cart`. */
+    name: string;
+    /** `mf-manifest.json` URL of the version to load. Used when `remoteEntry` is absent. */
+    entry: string;
+    /**
+     * The remote's entry script. Registered in place of the manifest in
+     * production, so the shell fetches no manifest and ships no snapshot code.
+     */
+    remoteEntry?: string;
+    /** How `remoteEntry` loads (`module` for ESM). Passed to Module Federation with it. */
+    type?: string;
+    /** The global `remoteEntry` defines when it differs from `name`. */
+    entryGlobalName?: string;
+    version?: string;
+    routes?: string[];
+    owner?: string;
+}
+export interface RegistryIndex {
+    shell?: string;
+    env?: string;
+    generatedAt?: string;
+    remotes: RegistryRemote[];
+}
+/** Reported for a registry entry that has only a manifest URL in a shell built without the manifest loader. */
+export declare const NO_REMOTE_ENTRY = "MFE_NO_REMOTE_ENTRY";
+/** True for a valid registry remote. */
+export declare function isRegistryRemote(value: unknown): value is RegistryRemote;
+/**
+ * True for a registry index envelope (what the shell fetches at boot). Remotes
+ * are checked one by one in `loadRegistryIndex`, so one bad remote does not
+ * take the others down.
+ */
+export declare function isRegistryIndex(value: unknown): value is RegistryIndex;
+/** Reported for a registry remote that is skipped because a field is invalid. */
+export declare const INVALID_REMOTE = "MFE_INVALID_REMOTE";
+export interface LoadRegistryOptions {
+    timeoutMs?: number;
+    fetch?: typeof fetch;
+    /** Use an index the server or edge inlined as `window.__MFE_REGISTRY__`. Default true. */
+    inline?: boolean;
+    /** Allow the fallback fetch to leave the page's origin. Default false. */
+    allowCrossOrigin?: boolean;
+}
+/**
+ * Global the server or CDN edge writes into the shell's HTML (see
+ * `registryInjection` in `@mfeflow/contracts`), so the shell registers remotes
+ * without another request.
+ */
+export declare const REGISTRY_GLOBAL = "__MFE_REGISTRY__";
+export declare const DEFAULT_REGISTRY_URL = "/registry/index.json";
+/**
+ * Reads the registry index: `window.__MFE_REGISTRY__` when the edge inlined it,
+ * otherwise a same-origin fetch. Throws on HTTP errors, timeouts, invalid JSON
+ * and cross-origin URLs. A remote with an invalid field is skipped and reported
+ * (`MFE_INVALID_REMOTE`); the valid ones stay.
+ */
+export declare function loadRegistryIndex(url?: string, options?: LoadRegistryOptions): Promise<RegistryIndex>;
+/** Remotes registered by the last `registerRemotesFromIndex` call (for the dev overlay). */
+export declare function registeredRemotes(): readonly RegistryRemote[];
+export interface RegisterOptions {
+    /** Only remotes whose registered URL (`remoteEntry`, else `entry`) is on one of these origins are registered. */
+    allowedOrigins?: readonly string[];
+    /** Whether the shell can load a manifest URL. Default: what the shell build set. */
+    snapshot?: boolean;
+}
+/**
+ * Registers the index's remotes with Module Federation, by remote entry URL
+ * when the index has one. Call it once the shell's shared scope is set up
+ * (after the app entry runs, never from the build config), so Module Federation
+ * does not load every remote's entry while resolving shared modules.
+ * Remotes from origins outside `allowedOrigins` are skipped and reported.
+ * Returns the registered names.
+ */
+export declare function registerRemotesFromIndex(index: RegistryIndex, options?: RegisterOptions): string[];

package/dist/registry.js

@@ -0,0 +1,108 @@
+import { ENTRY_TYPES, GLOBAL_NAME, pickRegistryFields } from "@mfeflow/contracts/entry";
+import { registerRemotes } from "@module-federation/enhanced/runtime";
+import { reportRemoteError } from "./report.js";
+const NO_REMOTE_ENTRY = 'MFE_NO_REMOTE_ENTRY';
+function builtWithSnapshot() {
+    return 'boolean' == typeof __MFEFLOW_SNAPSHOT__ ? __MFEFLOW_SNAPSHOT__ : true;
+}
+function isStringArray(value) {
+    return Array.isArray(value) && value.every((v)=>'string' == typeof v);
+}
+function remoteProblem(value) {
+    if ('object' != typeof value || null === value) return 'not an object';
+    if (!('name' in value) || 'string' != typeof value.name || !GLOBAL_NAME.test(value.name)) return 'name';
+    if (!('entry' in value) || 'string' != typeof value.entry) return 'entry';
+    if ('remoteEntry' in value && 'string' != typeof value.remoteEntry) return 'remoteEntry';
+    if ('type' in value && ('string' != typeof value.type || !ENTRY_TYPES.includes(value.type))) return 'type';
+    if ('entryGlobalName' in value && ('string' != typeof value.entryGlobalName || !GLOBAL_NAME.test(value.entryGlobalName))) return 'entryGlobalName';
+    if ('version' in value && 'string' != typeof value.version) return 'version';
+    if ('owner' in value && 'string' != typeof value.owner) return 'owner';
+    if ('routes' in value && !isStringArray(value.routes)) return 'routes';
+}
+function isRegistryRemote(value) {
+    return void 0 === remoteProblem(value);
+}
+function isRegistryIndex(value) {
+    return 'object' == typeof value && null !== value && 'remotes' in value && Array.isArray(value.remotes);
+}
+const INVALID_REMOTE = 'MFE_INVALID_REMOTE';
+function withoutInvalidRemotes(index) {
+    const remotes = index.remotes.filter((remote)=>{
+        const problem = remoteProblem(remote);
+        if (void 0 === problem) return true;
+        const name = 'string' == typeof remote?.name ? remote.name : '(unnamed)';
+        reportRemoteError(name, 'registry', new Error(`${INVALID_REMOTE}: "${name}" is skipped, its ${problem} is invalid`));
+        return false;
+    });
+    return remotes.length === index.remotes.length ? index : {
+        ...index,
+        remotes
+    };
+}
+const REGISTRY_GLOBAL = '__MFE_REGISTRY__';
+const DEFAULT_REGISTRY_URL = '/registry/index.json';
+function sameOrigin(url) {
+    if ("u" < typeof location) return true;
+    return new URL(url, location.href).origin === location.origin;
+}
+async function loadRegistryIndex(url = DEFAULT_REGISTRY_URL, options = {}) {
+    const inlined = Reflect.get(globalThis, REGISTRY_GLOBAL);
+    if (false !== options.inline && isRegistryIndex(inlined)) return withoutInvalidRemotes(inlined);
+    if (true !== options.allowCrossOrigin && !sameOrigin(url)) throw new Error(`registry index ${url}: must be same-origin`);
+    const doFetch = options.fetch ?? fetch;
+    const res = await doFetch(url, {
+        signal: AbortSignal.timeout(options.timeoutMs ?? 5000)
+    });
+    if (!res.ok) throw new Error(`registry index ${url}: HTTP ${String(res.status)}`);
+    const body = await res.json();
+    if (!isRegistryIndex(body)) throw new Error(`registry index ${url}: not a valid index`);
+    return withoutInvalidRemotes(body);
+}
+function toMfRemote(r) {
+    if (void 0 === r.remoteEntry) return {
+        name: r.name,
+        entry: r.entry
+    };
+    return {
+        name: r.name,
+        entry: r.remoteEntry,
+        ...void 0 === r.type ? {} : {
+            type: r.type
+        },
+        ...void 0 === r.entryGlobalName ? {} : {
+            entryGlobalName: r.entryGlobalName
+        }
+    };
+}
+let registered = [];
+function registeredRemotes() {
+    return registered;
+}
+function registerRemotesFromIndex(index, options = {}) {
+    const allowed = options.allowedOrigins?.map((o)=>new URL(o).origin);
+    const snapshot = options.snapshot ?? builtWithSnapshot();
+    const ok = [];
+    for (const remote of index.remotes){
+        if (!snapshot && void 0 === remote.remoteEntry) {
+            reportRemoteError(remote.name, 'registry', new Error(`${NO_REMOTE_ENTRY}: "${remote.name}" has only a manifest URL (${remote.entry}) and this shell was built without the manifest loader; publish its remoteEntry or build the shell with snapshot: true`));
+            continue;
+        }
+        const url = remote.remoteEntry ?? remote.entry;
+        let origin;
+        try {
+            origin = new URL(url).origin;
+        } catch  {
+            reportRemoteError(remote.name, 'registry', new Error(`invalid entry URL "${url}"`));
+            continue;
+        }
+        if (allowed && !allowed.includes(origin)) {
+            reportRemoteError(remote.name, 'registry', new Error(`origin ${origin} is not allowed`));
+            continue;
+        }
+        ok.push(remote);
+    }
+    registerRemotes(ok.map(toMfRemote));
+    registered = ok.map((r)=>pickRegistryFields(r));
+    return ok.map((r)=>r.name);
+}
+export { DEFAULT_REGISTRY_URL, INVALID_REMOTE, NO_REMOTE_ENTRY, REGISTRY_GLOBAL, isRegistryIndex, isRegistryRemote, loadRegistryIndex, registerRemotesFromIndex, registeredRemotes };

package/dist/remote.d.ts

@@ -0,0 +1,29 @@
+import { type ComponentType, type ReactNode } from 'react';
+export interface FallbackProps {
+    /** Remote name, e.g. `cart`. */
+    name: string;
+}
+export declare function DefaultRemoteFallback({ name }: FallbackProps): import("react").JSX.Element;
+export interface RemoteOptions {
+    /** Give up and show the fallback after this long. Module Federation has no timeout of its own. Default 5000. */
+    timeoutMs?: number | undefined;
+    fallback?: ComponentType<FallbackProps> | undefined;
+}
+/**
+ * A lazy component for `remote/expose` (e.g. `cart/App`). It never throws: load
+ * failures and timeouts render the fallback and are reported. Cached per id.
+ */
+export declare function remoteComponent(id: string, options?: RemoteOptions): ComponentType;
+export interface RemoteBoundaryProps extends RemoteOptions {
+    /** `remote/expose`, e.g. `cart/App`. */
+    id: string;
+    /** Shown while the remote loads. */
+    loading?: ReactNode | undefined;
+}
+/**
+ * Renders a remote module. A missing manifest, a timeout or a render error
+ * shows the fallback for that remote only; the rest of the page keeps working.
+ */
+export declare function RemoteBoundary({ id, loading, timeoutMs, fallback }: RemoteBoundaryProps): import("react").JSX.Element;
+/** Only for tests. */
+export declare function clearRemoteCacheForTests(): void;

package/dist/remote.js

@@ -0,0 +1,98 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Component, Suspense, lazy } from "react";
+import { loadRemote } from "@module-federation/enhanced/runtime";
+import { reportRemoteError } from "./report.js";
+function DefaultRemoteFallback({ name }) {
+    return /*#__PURE__*/ jsxs("div", {
+        role: "alert",
+        "data-mfeflow-fallback": name,
+        children: [
+            name,
+            " is unavailable right now."
+        ]
+    });
+}
+function withTimeout(promise, ms) {
+    return new Promise((resolve, reject)=>{
+        const timer = setTimeout(()=>{
+            reject(new Error(`timed out after ${String(ms)} ms`));
+        }, ms);
+        promise.then((value)=>{
+            clearTimeout(timer);
+            resolve(value);
+        }, (error)=>{
+            clearTimeout(timer);
+            reject(error instanceof Error ? error : new Error(String(error)));
+        });
+    });
+}
+function hasDefaultComponent(mod) {
+    return 'object' == typeof mod && null !== mod && 'default' in mod && 'function' == typeof mod.default;
+}
+const cache = new Map();
+function remoteComponent(id, options = {}) {
+    const hit = cache.get(id);
+    if (hit) return hit;
+    const name = id.split('/')[0] ?? id;
+    const Fallback = options.fallback ?? DefaultRemoteFallback;
+    const C = /*#__PURE__*/ lazy(async ()=>{
+        try {
+            const mod = await withTimeout(loadRemote(id), options.timeoutMs ?? 5000);
+            if (!hasDefaultComponent(mod)) throw new Error(`${id} has no default export component`);
+            return {
+                default: mod.default
+            };
+        } catch (error) {
+            reportRemoteError(name, 'load', error);
+            cache.delete(id);
+            return {
+                default: function() {
+                    return /*#__PURE__*/ jsx(Fallback, {
+                        name: name
+                    });
+                }
+            };
+        }
+    });
+    cache.set(id, C);
+    return C;
+}
+class RemoteErrorBoundary extends Component {
+    state = {
+        failed: false
+    };
+    static getDerivedStateFromError() {
+        return {
+            failed: true
+        };
+    }
+    componentDidCatch(error, _info) {
+        reportRemoteError(this.props.name, 'render', error);
+    }
+    render() {
+        const Fallback = this.props.fallback;
+        return this.state.failed ? /*#__PURE__*/ jsx(Fallback, {
+            name: this.props.name
+        }) : this.props.children;
+    }
+}
+function RemoteBoundary({ id, loading, timeoutMs, fallback }) {
+    const name = id.split('/')[0] ?? id;
+    const Fallback = fallback ?? DefaultRemoteFallback;
+    const C = remoteComponent(id, {
+        timeoutMs,
+        fallback: Fallback
+    });
+    return /*#__PURE__*/ jsx(RemoteErrorBoundary, {
+        name: name,
+        fallback: Fallback,
+        children: /*#__PURE__*/ jsx(Suspense, {
+            fallback: loading ?? null,
+            children: /*#__PURE__*/ jsx(C, {})
+        })
+    });
+}
+function clearRemoteCacheForTests() {
+    cache.clear();
+}
+export { DefaultRemoteFallback, RemoteBoundary, clearRemoteCacheForTests, remoteComponent };

package/dist/report.d.ts

@@ -0,0 +1,14 @@
+export interface RemoteErrorReport {
+    /** Remote name, e.g. `cart`. */
+    mfe: string;
+    /** Where it failed: `load`, `render`, `registry`, or `errorLoadRemote:<lifecycle>`. */
+    where: string;
+    message: string;
+    time: number;
+}
+/** Fired on `window` for every report; telemetry and the dev overlay listen to it. */
+export declare const REMOTE_ERROR_EVENT = "mfeflow:remote-error";
+declare global {
+    var mfeflowReports: RemoteErrorReport[] | undefined;
+}
+export declare function reportRemoteError(mfe: string, where: string, error: unknown): RemoteErrorReport;

package/dist/report.js

@@ -0,0 +1,16 @@
+const REMOTE_ERROR_EVENT = 'mfeflow:remote-error';
+function reportRemoteError(mfe, where, error) {
+    const report = {
+        mfe,
+        where,
+        message: error instanceof Error ? error.message : String(error),
+        time: Date.now()
+    };
+    (globalThis.mfeflowReports ??= []).push(report);
+    if ("u" > typeof window && 'function' == typeof CustomEvent) window.dispatchEvent(new CustomEvent(REMOTE_ERROR_EVENT, {
+        detail: report
+    }));
+    console.error(`[mfeflow] ${mfe} ${where}: ${report.message}`);
+    return report;
+}
+export { REMOTE_ERROR_EVENT, reportRemoteError };

package/dist/runtime-config.d.ts

@@ -0,0 +1,15 @@
+/** Where the shell keeps the runtime config once loaded: `globalThis[RUNTIME_CONFIG_KEY]`. */
+export declare const RUNTIME_CONFIG_KEY = "__MFE_RUNTIME_CONFIG__";
+/** The file the shell fetches: `public/config/runtime-config.json`, or the one for the environment in a deployment. */
+export declare const RUNTIME_CONFIG_URL = "/config/runtime-config.json";
+export type RuntimeConfigValues = Record<string, unknown>;
+/**
+ * The runtime config: the one already on `globalThis`, else the file, fetched once. Every caller
+ * (the typed `loadRuntimeConfig` of env-t3, analytics, telemetry) gets the same promise, so the
+ * file is requested once however many features read it. It rejects if the file cannot be loaded
+ * (the same rejection for every caller; there is no retry), so each caller decides what to do
+ * without it.
+ */
+export declare function fetchRuntimeConfig(url?: string): Promise<RuntimeConfigValues>;
+/** Forgets the loaded config and the fetch. For tests. */
+export declare function resetRuntimeConfigForTests(): void;

package/dist/runtime-config.js

@@ -0,0 +1,29 @@
+const RUNTIME_CONFIG_KEY = '__MFE_RUNTIME_CONFIG__';
+const RUNTIME_CONFIG_URL = '/config/runtime-config.json';
+const PENDING = Symbol.for('mfeflow.runtime-config');
+const isConfig = (value)=>'object' == typeof value && null !== value && !Array.isArray(value);
+const isPending = (value)=>'object' == typeof value && null !== value && Reflect.get(value, 'promise') instanceof Promise;
+async function load(url) {
+    const response = await fetch(url);
+    if (!response.ok) throw new Error(`${url} answered ${String(response.status)}`);
+    const json = await response.json();
+    if (!isConfig(json)) throw new Error(`${url} is not a JSON object`);
+    Reflect.set(globalThis, RUNTIME_CONFIG_KEY, json);
+    return json;
+}
+function fetchRuntimeConfig(url = RUNTIME_CONFIG_URL) {
+    const loaded = Reflect.get(globalThis, RUNTIME_CONFIG_KEY);
+    if (isConfig(loaded)) return Promise.resolve(loaded);
+    const existing = Reflect.get(globalThis, PENDING);
+    if (isPending(existing)) return existing.promise;
+    const pending = {
+        promise: load(url)
+    };
+    Reflect.set(globalThis, PENDING, pending);
+    return pending.promise;
+}
+function resetRuntimeConfigForTests() {
+    Reflect.deleteProperty(globalThis, RUNTIME_CONFIG_KEY);
+    Reflect.deleteProperty(globalThis, PENDING);
+}
+export { RUNTIME_CONFIG_KEY, RUNTIME_CONFIG_URL, fetchRuntimeConfig, resetRuntimeConfigForTests };

package/dist/singletons.d.ts

@@ -0,0 +1,20 @@
+export interface SingletonCheck {
+    /** Expected shared packages that are not in the share scope at all (e.g. a workspace package without a `version`). */
+    missing: string[];
+    /** Packages with more than one loaded version. */
+    duplicated: string[];
+}
+/**
+ * Checks the Module Federation share scope for the given singletons. Run in
+ * the shell after remotes load; the spike found a shared package without a
+ * `version` silently loaded once per app.
+ */
+export declare function checkSingletons(expected: readonly string[]): SingletonCheck;
+/** Query parameter that turns the singleton check on, e.g. `/catalog?mfeflow-assert`. */
+export declare const ASSERT_PARAM = "mfeflow-assert";
+/**
+ * Whether the page asked for the singleton check. The check reads the share
+ * scope of every loaded remote, so shells run it only in dev, tests and on
+ * request, never on a normal page load.
+ */
+export declare function assertRequested(search?: string): boolean;

package/dist/singletons.js

@@ -0,0 +1,26 @@
+function isRecord(value) {
+    return 'object' == typeof value && null !== value;
+}
+function shareScopes() {
+    const federation = Reflect.get(globalThis, '__FEDERATION__');
+    if (!isRecord(federation)) return;
+    const share = Reflect.get(federation, '__SHARE__');
+    return isRecord(share) ? share : void 0;
+}
+function checkSingletons(expected) {
+    const scopes = shareScopes() ?? {};
+    const loadedVersions = new Map();
+    for (const instance of Object.values(scopes))for (const scope of Object.values(instance))for (const [pkg, versions] of Object.entries(scope))for (const [version, entry] of Object.entries(versions)){
+        if (!loadedVersions.has(pkg)) loadedVersions.set(pkg, new Set());
+        if (true === entry.loaded || void 0 !== entry.lib) loadedVersions.get(pkg)?.add(version);
+    }
+    return {
+        missing: expected.filter((p)=>!loadedVersions.has(p)),
+        duplicated: expected.filter((p)=>(loadedVersions.get(p)?.size ?? 0) > 1)
+    };
+}
+const ASSERT_PARAM = 'mfeflow-assert';
+function assertRequested(search = "u" < typeof location ? '' : location.search) {
+    return new URLSearchParams(search).has(ASSERT_PARAM);
+}
+export { ASSERT_PARAM, assertRequested, checkSingletons };

package/package.json

@@ -1,6 +1,86 @@
 {
   "name": "@mfeflow/runtime",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Runtime for mfeflow micro-frontends: remotes from a registry index, RemoteBoundary with timeout and fallback, error reporting, singleton checks, composeProviders.",
+  "keywords": [
+    "micro-frontend",
+    "mfe",
+    "module-federation",
+    "react",
+    "providers",
+    "runtime",
+    "rsbuild"
+  ],
+  "homepage": "https://mfeflow.github.io/mfeflow/",
+  "bugs": "https://github.com/mfeflow/mfeflow/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mfeflow/mfeflow.git",
+    "directory": "packages/runtime"
+  },
+  "license": "MIT",
+  "author": "Sanjeev Sharma <speedsharma.ai@gmail.com>",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./providers": {
+      "types": "./dist/providers.d.ts",
+      "import": "./dist/providers.js",
+      "default": "./dist/providers.js"
+    },
+    "./plugins/report": {
+      "types": "./dist/plugins/report.d.ts",
+      "import": "./dist/plugins/report.js",
+      "default": "./dist/plugins/report.js"
+    },
+    "./plugins/entry-retry": {
+      "types": "./dist/plugins/entry-retry.d.ts",
+      "import": "./dist/plugins/entry-retry.js",
+      "default": "./dist/plugins/entry-retry.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.12"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "@mfeflow/contracts": "0.1.0"
+  },
+  "peerDependencies": {
+    "@module-federation/enhanced": "^2.9.0",
+    "react": "^19.0.0"
+  },
+  "peerDependenciesMeta": {},
+  "devDependencies": {
+    "@module-federation/enhanced": "2.9.2",
+    "@rsbuild/plugin-react": "2.1.1",
+    "@rslib/core": "1.0.5",
+    "@testing-library/dom": "10.4.2",
+    "@testing-library/react": "16.3.3",
+    "@types/node": "26.6.6",
+    "@types/react": "19.3.0",
+    "@types/react-dom": "19.3.0",
+    "jsdom": "30.1.3",
+    "react": "19.3.1",
+    "react-dom": "19.3.1",
+    "typescript": "7.0.2"
+  },
+  "mfeflow": {
+    "bucket": "singleton"
+  },
+  "scripts": {
+    "build": "rslib build",
+    "typecheck": "tsc --noEmit"
+  }
 }