From 569417826e8d08e4b690dc82667929ae187a6887 Mon Sep 17 00:00:00 2001
From: Shaoyu Meng <shaoyumeng@shaoyus-mbp-5.lan>
Date: Tue, 16 Jun 2026 14:08:08 -0700
Subject: [PATCH 01/34] docs(spec): add fetchOptions ESM remote loading design

Design for threading per-remote fetchOptions through registerRemotes so
auth/compliance headers reach every asset in the ESM module graph
(manifest, entry, chunks, shared deps, manifest CSS) via a fetch + blob
import-rewriting loader.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 ...-fetchoptions-esm-remote-loading-design.md | 205 ++++++++++++++++++
 1 file changed, 205 insertions(+)
 create mode 100644 docs/superpowers/specs/2026-06-16-fetchoptions-esm-remote-loading-design.md

diff --git a/docs/superpowers/specs/2026-06-16-fetchoptions-esm-remote-loading-design.md b/docs/superpowers/specs/2026-06-16-fetchoptions-esm-remote-loading-design.md
new file mode 100644
index 00000000000..54f6f95e7d1
--- /dev/null
+++ b/docs/superpowers/specs/2026-06-16-fetchoptions-esm-remote-loading-design.md
@@ -0,0 +1,205 @@
+# `fetchOptions` for header-authenticated ESM remote loading
+
+**Date:** 2026-06-16
+**Status:** Approved design — pending implementation plan
+**Related:** https://github.com/module-federation/enhanced/issues/15
+**PoC:** `js-module-import/index.html` (fetch + blob import-rewriting loader)
+
+## Problem
+
+Native `<script src>` and native `import()` cannot carry custom HTTP headers. A
+compliance use case requires an `Authorization: Bearer …` header (plus arbitrary
+`X-*` headers) on **every** asset request a remote pulls in: the manifest, the
+remote entry, split chunks, and shared dependencies.
+
+Today the Module Federation runtime:
+
+- fetches the **manifest** through the `loaderHook.lifecycle.fetch` hook — the
+  only place headers can already be injected — but passes `{}` as the request
+  options (`SnapshotHandler.ts:307`);
+- loads the **remote entry** via a native `<script>` tag
+  (`loadEntryScript` → `sdk/src/dom.ts`) or native `import()`
+  (`loadEsmEntry`), neither of which can carry headers;
+- loads **split chunks and shared deps** via the bundler runtime
+  (webpack/rspack `__webpack_require__.l`, or native `import()` for ESM output),
+  which the MF runtime does not intercept at all.
+
+There is therefore no way today — via plugin or config — to attach headers to
+the actual JS module graph. A runtime plugin alone is insufficient because
+(a) there is no channel to pass per-remote fetch options from the API down to
+the loader, and (b) the `fetch` hook is emitted only for the manifest.
+
+## Why the PoC works
+
+The PoC sidesteps the bundler's header-less loading entirely. It `fetch`es each
+module's **source text** (headers attached), rewrites every static and dynamic
+`import` to recursively-loaded **blob URLs**, then imports the blob. Because the
+whole graph becomes blob imports driven by an explicit `fetch`, the bundler
+never performs a native header-less load. This works when the remote is built as
+**ES modules** — where all loading is `import` / `import()`. It does not reach
+IIFE / webpack-JSONP chunk loads (`__webpack_require__.l`), so those remain out
+of scope for this iteration.
+
+## Scope
+
+**In scope (this iteration):**
+
+- A per-remote `fetchOptions: RequestInit` passed through `registerRemotes`.
+- Authenticated manifest fetch.
+- A fetch + blob ESM loader (hardened port of the PoC) used for `module` / `esm`
+  remotes that carry `fetchOptions`: entry + all chunks + shared deps.
+- Authenticated loading of **CSS assets declared in `mf-manifest.json`** (fetch
+  the CSS text with headers, inject as a blob `<link>`).
+
+**Out of scope (follow-ups):**
+
+- `loadSystemJsEntry` (`system`) and `loadEntryScript` (IIFE/global) remotes —
+  header-carrying chunk loads for these formats. For non-ESM remotes with
+  `fetchOptions`, only the manifest is authenticated this iteration.
+- CSS imported from inside JS (`import './x.css'`) — not exercised by the PoC
+  and not part of the ESM manifests we target.
+
+## Decisions
+
+- **ESM-only, inferred from the manifest.** The entry type comes from
+  `metaData.remoteEntry.type` in `mf-manifest.json` (flows to `remoteInfo.type`).
+  The fetch + blob loader is engaged only in the existing `case 'esm' / 'module'`
+  branch of `loadEntryDom`. Any non-ESM remote never reaches that branch and so
+  automatically falls back to today's loader unchanged.
+- **Per-remote `fetchOptions`.** Different headers for different remotes are
+  expressed by calling `registerRemotes([...], { fetchOptions })` multiple times
+  (e.g. `[remote1, remote2]` with one set, `[remote3, remote4]` with another).
+  `fetchOptions` is stamped onto each `Remote` in that call inside
+  `registerRemotes` (plural). There is no reliance on a singular public
+  `registerRemote`.
+- **Ported PoC code keeps its original comments.** The explanatory comments in
+  `js-module-import/index.html` are carried over verbatim where the code is
+  ported.
+- **Backward compatible.** Every new field is optional; with no `fetchOptions`,
+  all existing behavior is byte-for-byte unchanged.
+
+## Design
+
+### 1. API + type plumbing (`runtime-core`, `sdk`)
+
+- Extend the `registerRemotes` options:
+  `registerRemotes(remotes: Remote[], options?: { force?: boolean; fetchOptions?: RequestInit }): void`.
+  In the plural method, iterate the array and stamp `fetchOptions` onto each
+  remote before delegating to the existing internal registration.
+- Add `fetchOptions?: RequestInit` to the shared `Remote` type
+  (`RemoteInfoCommon`) and to `RemoteInfo` (`runtime-core/src/type/config.ts`).
+- Carry it through `getRemoteInfo` (`runtime-core/src/utils/load.ts:393`) so it
+  lands on `RemoteInfo`. Manifest-driven `assignRemoteInfo`
+  (`plugins/snapshot/index.ts`) must preserve it (it overwrites `type`, not
+  `fetchOptions`).
+
+### 2. Authenticated manifest fetch (`runtime-core`, tiny)
+
+In `SnapshotHandler.ts` (~line 307) `remoteInfo` is already in scope. Change the
+hook emit options `{}` → `remoteInfo.fetchOptions ?? {}`, and the native
+fallback `fetch(manifestUrl, {})` → `fetch(manifestUrl, remoteInfo.fetchOptions ?? {})`.
+The manifest is then authenticated with no plugin required.
+
+### 3. Fetch + blob ESM loader (`sdk` — new `packages/sdk/src/blobLoad.ts`)
+
+A hardened port of the PoC. Public surface:
+
+```ts
+loadEsmEntryWithFetch({
+  entry: string,
+  remoteInfo: RemoteInfo,          // supplies fetchOptions
+  loaderHook: ModuleFederation['loaderHook'],
+}): Promise<RemoteEntryExports>
+
+loadCssWithFetch({
+  href: string,
+  remoteInfo: RemoteInfo,
+  loaderHook: ModuleFederation['loaderHook'],
+}): Promise<void>
+```
+
+Internals (ported from the PoC, comments retained):
+
+- `fetcher(url)` — emits `loaderHook.lifecycle.fetch` (so existing fetch-hook
+  plugins still compose) with `remoteInfo.fetchOptions` merged in; falls back to
+  native `fetch(url, merged)`. Returns response text. Throws a descriptive
+  network error (mirroring the `ScriptNetworkError` messaging in `dom.ts`) on a
+  non-OK response.
+- `resolveSpec(spec, base)` — PoC logic verbatim (relative / absolute-path /
+  absolute-url; bare specifiers throw).
+- `loadModule(url)` — PoC logic: instance-scoped cache (`Map<url, Promise<blobUrl>>`),
+  rewrite `import.meta.url` → the real url, dynamic `import(` → `__mfDyn("<url>",`,
+  static `from`/`import '…'` relative/absolute specifiers → recursively-loaded
+  blob URLs, then `URL.createObjectURL`.
+- `globalThis.__mfDyn` — runtime dynamic-import shim, installed idempotently
+  (guard so repeated remote loads don't reinstall).
+- The `vite:preloadError` listener from the PoC is added once (idempotent) so
+  native preload hints fail quietly.
+
+Hardening over the raw PoC: idempotent global install, instance-scoped cache,
+and unified error messaging — but the regex-based rewriting is kept as-is, which
+is acceptable for the ESM build output we target.
+
+### 4. Routing + ESM gate (`runtime-core`)
+
+In `loadEntryDom` (`runtime-core/src/utils/load.ts:189`), the
+`case 'esm' / 'module'` branch becomes:
+
+```ts
+case 'esm':
+case 'module':
+  return remoteInfo.fetchOptions
+    ? loadEsmEntryWithFetch({ entry, remoteInfo, loaderHook })
+    : loadEsmEntry({ entry, remoteEntryExports });
+```
+
+`system` and the default (`loadEntryScript`) branches are untouched.
+
+### 5. Authenticated manifest CSS (`runtime-core`)
+
+CSS assets declared in the manifest are preloaded today via `createLink` in
+`runtime-core/src/utils/preload.ts` (`waitForLinkPreload`). When the owning
+remote carries `fetchOptions`, route those CSS loads through `loadCssWithFetch`
+instead of a native `<link href>` — fetch the CSS text with headers and inject a
+blob `<link>`. The exact injection point in `preload.ts` (and access to the
+remote's `fetchOptions` there) is confirmed during implementation; the loader
+helper itself lives in `sdk/blobLoad.ts`.
+
+### 6. Error handling
+
+`loadEsmEntryWithFetch` / `loadCssWithFetch` reject with descriptive errors.
+`getRemoteEntry`'s existing `loadEntryError` hook continues to apply, so retry
+plugins keep working.
+
+## Testing
+
+- **Unit (`sdk`):** the import rewriter (static, dynamic, `import.meta.url`
+  cases), `resolveSpec` (relative / absolute / bare-throws), cache reuse, and the
+  `fetcher` header-merge precedence.
+- **Integration:** register an ESM remote with `fetchOptions`, load it, assert
+  the headers reach the manifest fetch, the entry fetch, a dynamically-imported
+  chunk, and a shared dep.
+- **Fallback:** a non-ESM remote with `fetchOptions` is loaded via the original
+  path (loader untouched); an ESM remote without `fetchOptions` uses
+  `loadEsmEntry` unchanged.
+- **CSS:** a manifest-declared CSS asset on a `fetchOptions` remote is fetched
+  with headers and injected as a blob `<link>`.
+
+## Files touched (anticipated)
+
+- `packages/sdk/src/blobLoad.ts` — **new**; fetch + blob loader + CSS helper.
+- `packages/sdk/src/types/…` — `fetchOptions` on the shared remote types;
+  export the new loader.
+- `packages/runtime-core/src/type/config.ts` — `fetchOptions` on `Remote` /
+  `RemoteInfo`.
+- `packages/runtime-core/src/remote/index.ts` — `registerRemotes` options +
+  stamping.
+- `packages/runtime-core/src/utils/load.ts` — `getRemoteInfo` passthrough +
+  `loadEntryDom` routing gate.
+- `packages/runtime-core/src/plugins/snapshot/SnapshotHandler.ts` — manifest
+  fetch options.
+- `packages/runtime-core/src/plugins/snapshot/index.ts` — preserve `fetchOptions`
+  in `assignRemoteInfo`.
+- `packages/runtime-core/src/utils/preload.ts` — route manifest CSS through the
+  fetch + blob helper when `fetchOptions` present.
+- Tests alongside the above.

From 4fd6b31732d506ce2eabae55ff1572fd5eb2aba7 Mon Sep 17 00:00:00 2001
From: Shaoyu Meng <shaoyumeng@shaoyus-mbp-5.lan>
Date: Tue, 16 Jun 2026 14:22:22 -0700
Subject: [PATCH 02/34] docs(plan): add fetchOptions ESM remote loading
 implementation plan

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 ...6-06-16-fetchoptions-esm-remote-loading.md | 895 ++++++++++++++++++
 1 file changed, 895 insertions(+)
 create mode 100644 docs/superpowers/plans/2026-06-16-fetchoptions-esm-remote-loading.md

diff --git a/docs/superpowers/plans/2026-06-16-fetchoptions-esm-remote-loading.md b/docs/superpowers/plans/2026-06-16-fetchoptions-esm-remote-loading.md
new file mode 100644
index 00000000000..95e19e1f474
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-16-fetchoptions-esm-remote-loading.md
@@ -0,0 +1,895 @@
+# fetchOptions ESM Remote Loading — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Let `registerRemotes(remotes, { fetchOptions })` attach custom HTTP headers to every asset of an ESM remote (manifest, entry, chunks, shared deps, manifest CSS) via a fetch + blob import-rewriting loader, with zero change to non-ESM / no-`fetchOptions` paths.
+
+**Architecture:** A self-contained fetch+blob loader in `@module-federation/sdk` (hardened port of the PoC in `js-module-import/index.html`) fetches each module's source with headers, rewrites its static/dynamic imports to recursively-loaded blob URLs, and imports the blob. `runtime-core` threads a per-remote `fetchOptions` from the API down to `RemoteInfo`, routes ESM entries with `fetchOptions` to the new loader, authenticates the manifest fetch, and routes manifest CSS through the loader. Non-ESM remotes never reach the new branch and fall back to today's loaders.
+
+**Tech Stack:** TypeScript monorepo, pnpm, Jest (jsdom env, `@swc/jest`), packages `sdk` and `runtime-core`.
+
+---
+
+## Background the implementer needs
+
+- The PoC is `js-module-import/index.html` (read it first). Its comments are intentionally carried over into the ported code.
+- `sdk` does **not** import from `runtime-core` (one-way dependency: `runtime-core` → `sdk`). The sdk loader therefore takes plain primitives (`entry`, `fetchOptions`, an optional `customFetch`) — never `RemoteInfo` or `loaderHook`.
+- Why a blob loader at all: `<script src>` and native `import()` cannot carry headers, and the runtime does not intercept bundler chunk loads. Rewriting the whole ESM graph to blob imports is the only way headers reach chunks/shared deps. This only works for ESM output, hence the `module`/`esm` gate.
+- sdk tests live in `packages/sdk/__tests__/*.spec.ts`, run with jsdom. Run a single sdk test file with:
+  `pnpm --filter @module-federation/sdk exec jest --config jest.config.cjs <path> -t "<name>"`
+- runtime-core tests: `pnpm --filter @module-federation/runtime-core test` (check the package's own jest config for single-file invocation).
+
+## File structure
+
+- **Create** `packages/sdk/src/blobLoad.ts` — the fetch+blob loader (pure rewriter + `resolveSpec` + `fetchText` + `loadModule` + `__mfDyn` shim + `loadEsmEntryWithFetch` + `loadCssWithFetch`). One responsibility: header-authenticated ESM blob loading.
+- **Create** `packages/sdk/__tests__/blobLoad.spec.ts` — unit tests for the pure pieces.
+- **Modify** `packages/sdk/src/index.ts` — export the new module.
+- **Modify** `packages/runtime-core/src/type/config.ts` — add `fetchOptions` to `RemoteInfoCommon` and `RemoteInfo`.
+- **Modify** `packages/runtime-core/src/remote/index.ts` — `registerRemotes` options + per-remote stamping.
+- **Modify** `packages/runtime-core/src/core.ts` — public `registerRemotes` signature.
+- **Modify** `packages/runtime-core/src/utils/load.ts` — `loadEntryDom` routing gate + `customFetch` builder.
+- **Modify** `packages/runtime-core/src/plugins/snapshot/SnapshotHandler.ts` — authenticate manifest fetch.
+- **Modify** `packages/runtime-core/src/utils/preload.ts` — route manifest CSS through the loader when `fetchOptions` present.
+
+---
+
+## Task 1: Pure rewriter + `resolveSpec` in the sdk loader
+
+**Files:**
+- Create: `packages/sdk/src/blobLoad.ts`
+- Test: `packages/sdk/__tests__/blobLoad.spec.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+```ts
+// packages/sdk/__tests__/blobLoad.spec.ts
+import { resolveSpec, rewriteModuleCode } from '../src/blobLoad';
+
+describe('resolveSpec', () => {
+  it('returns absolute urls untouched', () => {
+    expect(resolveSpec('https://x.com/a.js', 'https://b.com/')).toBe('https://x.com/a.js');
+    expect(resolveSpec('blob:abc', 'https://b.com/')).toBe('blob:abc');
+    expect(resolveSpec('data:text/js,1', 'https://b.com/')).toBe('data:text/js,1');
+  });
+
+  it('resolves relative and absolute-path specifiers against the base', () => {
+    expect(resolveSpec('./dep.js', 'https://b.com/app/entry.js')).toBe('https://b.com/app/dep.js');
+    expect(resolveSpec('/root.js', 'https://b.com/app/entry.js')).toBe('https://b.com/root.js');
+  });
+
+  it('throws on bare specifiers', () => {
+    expect(() => resolveSpec('react', 'https://b.com/')).toThrow('bare specifier');
+  });
+});
+
+describe('rewriteModuleCode', () => {
+  const url = 'https://b.com/app/entry.js';
+
+  it('pins import.meta.url to the module url', () => {
+    const { code } = rewriteModuleCode('const u = import.meta.url;', url);
+    expect(code).toBe(`const u = ${JSON.stringify(url)};`);
+  });
+
+  it('routes dynamic import() through __mfDyn with the base url', () => {
+    const { code } = rewriteModuleCode('const m = import("./x.js");', url);
+    expect(code).toBe(`const m = __mfDyn(${JSON.stringify(url)},"./x.js");`);
+  });
+
+  it('collects static relative/absolute deps and leaves bare imports alone', () => {
+    const src = `import a from "./a.js";\nexport { b } from "/b.js";\nimport c from "react";`;
+    const { deps } = rewriteModuleCode(src, url);
+    expect(deps.map((d) => d.spec).sort()).toEqual(['./a.js', '/b.js']);
+    expect(deps.find((d) => d.spec === './a.js')!.depUrl).toBe('https://b.com/app/a.js');
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `pnpm --filter @module-federation/sdk exec jest --config jest.config.cjs __tests__/blobLoad.spec.ts`
+Expected: FAIL — cannot find module `../src/blobLoad`.
+
+- [ ] **Step 3: Write minimal implementation**
+
+```ts
+// packages/sdk/src/blobLoad.ts
+
+// Hardened port of the fetch + blob import-rewriting loader PoC
+// (js-module-import/index.html). Comments are retained from the PoC where the
+// logic is carried over verbatim.
+
+export interface BlobDep {
+  original: string;
+  spec: string;
+  quote: string;
+  depUrl: string;
+}
+
+// Resolve a specifier (relative, absolute-path, or already-absolute-url)
+// against a base url to a concrete fetchable url. The MF runtime resolves
+// shared deps to relative loadShare asset urls, so bare specifiers never reach
+// the loader; anything bare is unexpected and throws.
+export function resolveSpec(spec: string, base: string): string {
+  if (/^(blob:|https?:|data:)/.test(spec)) return spec;
+  if (spec.startsWith('.') || spec.startsWith('/')) return new URL(spec, base).href;
+  throw new Error(`[loader] cannot resolve bare specifier "${spec}" (from ${base})`);
+}
+
+// Rewrite a module's source: pin import.meta.url, route dynamic imports through
+// __mfDyn, and collect static relative/absolute specifiers (to be replaced with
+// recursively-loaded blob urls by the caller).
+export function rewriteModuleCode(
+  code: string,
+  url: string,
+): { code: string; deps: BlobDep[] } {
+  // import.meta.url -> the module's real url.
+  // In this case, modules with publicPath:"auto" can derive paths from it.
+  code = code.replace(/\bimport\.meta\.url\b/g, JSON.stringify(url));
+
+  // Dynamic import(...) -> __mfDyn("<url>", ...).
+  code = code.replace(/(?<![.\w$])import\s*\(/g, `__mfDyn(${JSON.stringify(url)},`);
+
+  // Static `import * from ...` and `import ...` -> recursively-loaded blob urls.
+  const specRe = /(?<![.\w$])(from|import)\s*(['"])([^'"]+)\2/g;
+  const deps: BlobDep[] = [];
+  for (const m of code.matchAll(specRe)) {
+    const spec = m[3];
+    if (spec.startsWith('.') || spec.startsWith('/')) {
+      deps.push({ original: m[0], spec, quote: m[2], depUrl: resolveSpec(spec, url) });
+    }
+  }
+  return { code, deps };
+}
+```
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `pnpm --filter @module-federation/sdk exec jest --config jest.config.cjs __tests__/blobLoad.spec.ts`
+Expected: PASS (all `resolveSpec` and `rewriteModuleCode` tests green).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add packages/sdk/src/blobLoad.ts packages/sdk/__tests__/blobLoad.spec.ts
+git commit -m "feat(sdk): add blob-loader import rewriter and resolveSpec"
+```
+
+---
+
+## Task 2: `fetchText`, `loadModule`, `__mfDyn`, and the public loader functions
+
+**Files:**
+- Modify: `packages/sdk/src/blobLoad.ts`
+- Modify: `packages/sdk/src/index.ts`
+- Test: `packages/sdk/__tests__/blobLoad.spec.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+Append to `packages/sdk/__tests__/blobLoad.spec.ts`:
+
+```ts
+import { fetchText, loadModule, loadEsmEntryWithFetch } from '../src/blobLoad';
+
+describe('fetchText', () => {
+  beforeEach(() => {
+    (global as any).fetch = jest.fn();
+  });
+
+  it('merges fetchOptions headers and returns response text', async () => {
+    (global.fetch as jest.Mock).mockResolvedValue({
+      ok: true,
+      text: () => Promise.resolve('CODE'),
+    });
+    const text = await fetchText('https://b.com/e.js', {
+      fetchOptions: { headers: { Authorization: 'Bearer t' } },
+    });
+    expect(text).toBe('CODE');
+    const init = (global.fetch as jest.Mock).mock.calls[0][1];
+    expect(init.headers).toEqual({ Authorization: 'Bearer t' });
+  });
+
+  it('prefers customFetch when it returns a Response', async () => {
+    const customFetch = jest.fn().mockResolvedValue({ ok: true, text: () => Promise.resolve('HOOKED') } as any);
+    // jsdom Response check: stub instanceof via a real Response-like guard is awkward,
+    // so the implementation treats any object with ok+text as usable when customFetch returns it.
+    const text = await fetchText('https://b.com/e.js', { customFetch });
+    expect(customFetch).toHaveBeenCalled();
+    expect(text).toBe('HOOKED');
+    expect((global.fetch as jest.Mock)).not.toHaveBeenCalled();
+  });
+
+  it('throws a descriptive error on non-ok responses', async () => {
+    (global.fetch as jest.Mock).mockResolvedValue({ ok: false, status: 401, statusText: 'Unauthorized', text: () => Promise.resolve('') });
+    await expect(fetchText('https://b.com/e.js', {})).rejects.toThrow('BlobLoaderNetworkError: 401');
+  });
+});
+
+describe('loadModule', () => {
+  beforeEach(() => {
+    (global as any).fetch = jest.fn();
+    (global.URL as any).createObjectURL = jest.fn((blob: Blob) => `blob:${(blob as any).__id || 'x'}`);
+    loadModule.clearCache();
+  });
+
+  it('rewrites a static dep to a recursively-loaded blob url and caches by url', async () => {
+    const files: Record<string, string> = {
+      'https://b.com/entry.js': `import dep from "./dep.js";`,
+      'https://b.com/dep.js': `export default 1;`,
+    };
+    (global.fetch as jest.Mock).mockImplementation((url: string) =>
+      Promise.resolve({ ok: true, text: () => Promise.resolve(files[url]) }),
+    );
+    const blobUrl = await loadModule('https://b.com/entry.js', {});
+    expect(blobUrl).toMatch(/^blob:/);
+    // dep fetched exactly once; entry fetched once
+    expect((global.fetch as jest.Mock).mock.calls.map((c) => c[0]).sort()).toEqual([
+      'https://b.com/dep.js',
+      'https://b.com/entry.js',
+    ]);
+    // second call for same url is served from cache (no extra fetch)
+    await loadModule('https://b.com/entry.js', {});
+    expect((global.fetch as jest.Mock).mock.calls.length).toBe(2);
+  });
+});
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `pnpm --filter @module-federation/sdk exec jest --config jest.config.cjs __tests__/blobLoad.spec.ts`
+Expected: FAIL — `fetchText` / `loadModule` not exported (and `loadModule.clearCache` missing).
+
+- [ ] **Step 3: Write minimal implementation**
+
+Append to `packages/sdk/src/blobLoad.ts`:
+
+```ts
+export type BlobFetcher = (
+  url: string,
+  init: RequestInit,
+) => Promise<Response | void | false> | Response | void | false;
+
+export interface BlobLoadContext {
+  fetchOptions?: RequestInit;
+  // Optional custom fetch (e.g. routed through the runtime loaderHook.fetch so
+  // existing fetch-hook plugins still compose). Falls back to native fetch.
+  customFetch?: BlobFetcher;
+}
+
+// absolute url -> Promise<blob url>
+const cache = new Map<string, Promise<string>>();
+// absolute url -> the context it was loaded with, so __mfDyn can reuse the
+// right headers for runtime dynamic imports of that module's chunks.
+const contexts = new Map<string, BlobLoadContext>();
+let dynImportInstalled = false;
+
+function isResponseLike(res: unknown): res is Response {
+  return (
+    !!res &&
+    typeof res === 'object' &&
+    typeof (res as Response).text === 'function' &&
+    'ok' in (res as Response)
+  );
+}
+
+export async function fetchText(url: string, ctx: BlobLoadContext): Promise<string> {
+  const { headers, ...rest } = ctx.fetchOptions || {};
+  const init: RequestInit = { ...rest, headers: { ...(headers as Record<string, string>) } };
+  let res: Response | void | false;
+  if (ctx.customFetch) {
+    res = await ctx.customFetch(url, init);
+  }
+  if (!isResponseLike(res)) {
+    res = await fetch(url, init);
+  }
+  if (!res.ok) {
+    throw new Error(`BlobLoaderNetworkError: ${res.status} ${res.statusText} for ${url}`);
+  }
+  return res.text();
+}
+
+// Fetch a module with headers, rewrite its imports.
+// Dynamic imports are handled lazily at runtime via __mfDyn,
+// Static relative imports are pre-loaded recursively.
+export function loadModule(url: string, ctx: BlobLoadContext): Promise<string> {
+  if (cache.has(url)) return cache.get(url)!;
+  contexts.set(url, ctx);
+
+  const promise = (async () => {
+    const raw = await fetchText(url, ctx);
+    const { code: rewritten, deps } = rewriteModuleCode(raw, url);
+    let code = rewritten;
+    const blobUrls = await Promise.all(deps.map((d) => loadModule(d.depUrl, ctx)));
+    deps.forEach((d, i) => {
+      const replaced = d.original.replace(
+        `${d.quote}${d.spec}${d.quote}`,
+        `${d.quote}${blobUrls[i]}${d.quote}`,
+      );
+      code = code.split(d.original).join(replaced);
+    });
+    return URL.createObjectURL(new Blob([code], { type: 'application/javascript' }));
+  })();
+
+  cache.set(url, promise);
+  return promise;
+}
+
+// Test seam: reset the module/context caches between cases.
+loadModule.clearCache = () => {
+  cache.clear();
+  contexts.clear();
+};
+
+function installDynImportShim(): void {
+  if (dynImportInstalled) return;
+  dynImportInstalled = true;
+
+  // Runtime dynamic-import shim: resolve url + fetch from cache or with headers + import as blob.
+  (globalThis as Record<string, unknown>).__mfDyn = async (base: string, spec: string) => {
+    const resolved = resolveSpec(spec, base);
+    if (/^(blob:|data:)/.test(resolved)) {
+      return import(/* webpackIgnore: true */ /* @vite-ignore */ resolved);
+    }
+    const ctx = contexts.get(base) || {};
+    return import(/* webpackIgnore: true */ /* @vite-ignore */ await loadModule(resolved, ctx));
+  };
+
+  // The vite preload helper creates native <link> preloads (no auth header) as a
+  // perf hint; let those 401 quietly instead of throwing — real loads go via __mfDyn.
+  if (typeof window !== 'undefined') {
+    window.addEventListener('vite:preloadError', (e) => e.preventDefault());
+  }
+}
+
+export async function loadEsmEntryWithFetch({
+  entry,
+  fetchOptions,
+  customFetch,
+}: {
+  entry: string;
+  fetchOptions?: RequestInit;
+  customFetch?: BlobFetcher;
+}): Promise<Record<string, unknown>> {
+  installDynImportShim();
+  const blobUrl = await loadModule(entry, { fetchOptions, customFetch });
+  return import(/* webpackIgnore: true */ /* @vite-ignore */ blobUrl);
+}
+
+export async function loadCssWithFetch({
+  href,
+  fetchOptions,
+  customFetch,
+}: {
+  href: string;
+  fetchOptions?: RequestInit;
+  customFetch?: BlobFetcher;
+}): Promise<void> {
+  const text = await fetchText(href, { fetchOptions, customFetch });
+  const blob = URL.createObjectURL(new Blob([text], { type: 'text/css' }));
+  const link = document.createElement('link');
+  link.rel = 'stylesheet';
+  link.href = blob;
+  document.head.appendChild(link);
+}
+```
+
+Add the `clearCache` member to the exported type by declaring it on the function. If TypeScript complains about assigning `clearCache` to a function, change the declaration to:
+
+```ts
+export const loadModule: ((url: string, ctx: BlobLoadContext) => Promise<string>) & {
+  clearCache: () => void;
+} = Object.assign(loadModuleImpl, { clearCache: () => { cache.clear(); contexts.clear(); } });
+```
+
+and rename the function body to `function loadModuleImpl(...)`. (Recursive calls inside the body must call `loadModule`, which is fine since it is in scope.)
+
+- [ ] **Step 4: Run test to verify it passes**
+
+Run: `pnpm --filter @module-federation/sdk exec jest --config jest.config.cjs __tests__/blobLoad.spec.ts`
+Expected: PASS.
+
+- [ ] **Step 5: Export from the sdk barrel**
+
+Modify `packages/sdk/src/index.ts` — add after the `export * from './dom';` line:
+
+```ts
+export * from './blobLoad';
+```
+
+- [ ] **Step 6: Type-check the sdk package**
+
+Run: `pnpm --filter @module-federation/sdk exec tsc -p tsconfig.lib.json --noEmit`
+Expected: no errors.
+
+- [ ] **Step 7: Commit**
+
+```bash
+git add packages/sdk/src/blobLoad.ts packages/sdk/src/index.ts packages/sdk/__tests__/blobLoad.spec.ts
+git commit -m "feat(sdk): add fetch+blob ESM loader (loadEsmEntryWithFetch, loadCssWithFetch)"
+```
+
+---
+
+## Task 3: Thread `fetchOptions` through types and `registerRemotes`
+
+**Files:**
+- Modify: `packages/runtime-core/src/type/config.ts:15-43`
+- Modify: `packages/runtime-core/src/remote/index.ts:502-509`
+- Modify: `packages/runtime-core/src/core.ts:458-460`
+
+- [ ] **Step 1: Add `fetchOptions` to the types**
+
+In `packages/runtime-core/src/type/config.ts`, add `fetchOptions?: RequestInit;` to `RemoteInfoCommon` (currently lines 15-20):
+
+```ts
+export interface RemoteInfoCommon {
+  alias?: string;
+  shareScope?: string | string[];
+  type?: RemoteEntryType;
+  entryGlobalName?: string;
+  fetchOptions?: RequestInit;
+}
+```
+
+And to `RemoteInfo` (currently lines 34-43):
+
+```ts
+export interface RemoteInfo {
+  alias?: string;
+  name: string;
+  version?: string;
+  buildVersion?: string;
+  entry: string;
+  type: RemoteEntryType;
+  entryGlobalName: string;
+  shareScope: string | string[];
+  fetchOptions?: RequestInit;
+}
+```
+
+`getRemoteInfo` (`utils/load.ts:393`) already spreads `...remote`, so `fetchOptions` flows onto `RemoteInfo` automatically — no change needed there.
+
+- [ ] **Step 2: Update `registerRemotes` to accept and stamp `fetchOptions`**
+
+In `packages/runtime-core/src/remote/index.ts`, replace the `registerRemotes` method (lines 502-509):
+
+```ts
+  registerRemotes(
+    remotes: Remote[],
+    options?: { force?: boolean; fetchOptions?: RequestInit },
+  ): void {
+    const { host } = this;
+    remotes.forEach((remote) => {
+      // fetchOptions passed to this call applies to each remote registered in
+      // it; an explicit per-remote fetchOptions on the remote object wins.
+      if (options?.fetchOptions && remote.fetchOptions === undefined) {
+        remote.fetchOptions = options.fetchOptions;
+      }
+      this.registerRemote(remote, host.options.remotes, {
+        force: options?.force,
+      });
+    });
+  }
+```
+
+- [ ] **Step 3: Update the public `registerRemotes` signature**
+
+In `packages/runtime-core/src/core.ts`, replace lines 458-460:
+
+```ts
+  registerRemotes(
+    remotes: Remote[],
+    options?: { force?: boolean; fetchOptions?: RequestInit },
+  ): void {
+    return this.remoteHandler.registerRemotes(remotes, options);
+  }
+```
+
+(The public wrapper in `packages/runtime/src/index.ts:94` uses `Parameters<ModuleFederation['registerRemotes']>`, so it updates automatically.)
+
+- [ ] **Step 4: Write the test**
+
+Create `packages/runtime-core/src/remote/__tests__/register-fetch-options.spec.ts` (match the package's existing test location/extension — if runtime-core uses a top-level `__tests__`, place it there instead):
+
+```ts
+import { ModuleFederation } from '../../core';
+
+describe('registerRemotes fetchOptions', () => {
+  it('stamps call-level fetchOptions onto each remote that lacks its own', () => {
+    const mf = new ModuleFederation({ name: 'host', remotes: [] });
+    const fetchOptions = { headers: { Authorization: 'Bearer t' } };
+    const r1: any = { name: 'a', entry: 'http://x/a.json' };
+    const r2: any = { name: 'b', entry: 'http://x/b.json', fetchOptions: { headers: { 'X-B': '1' } } };
+    mf.registerRemotes([r1, r2], { fetchOptions });
+    const stored = (mf as any).options.remotes;
+    expect(stored.find((r: any) => r.name === 'a').fetchOptions).toBe(fetchOptions);
+    expect(stored.find((r: any) => r.name === 'b').fetchOptions).toEqual({ headers: { 'X-B': '1' } });
+  });
+});
+```
+
+- [ ] **Step 5: Run test to verify it passes**
+
+Run: `pnpm --filter @module-federation/runtime-core test` (scope to the new file if the package's jest config supports a path argument).
+Expected: PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add packages/runtime-core/src/type/config.ts packages/runtime-core/src/remote/index.ts packages/runtime-core/src/core.ts packages/runtime-core/src/remote/__tests__/register-fetch-options.spec.ts
+git commit -m "feat(runtime-core): thread per-remote fetchOptions through registerRemotes"
+```
+
+---
+
+## Task 4: Route ESM entries with `fetchOptions` to the blob loader
+
+**Files:**
+- Modify: `packages/runtime-core/src/utils/load.ts:1-6` (import) and `:189-220` (`loadEntryDom`)
+- Test: `packages/runtime-core/src/utils/__tests__/load-entry-fetch-options.spec.ts`
+
+- [ ] **Step 1: Write the failing test**
+
+```ts
+// packages/runtime-core/src/utils/__tests__/load-entry-fetch-options.spec.ts
+jest.mock('@module-federation/sdk', () => {
+  const actual = jest.requireActual('@module-federation/sdk');
+  return { ...actual, loadEsmEntryWithFetch: jest.fn().mockResolvedValue({ ok: 1 }) };
+});
+
+import { loadEsmEntryWithFetch } from '@module-federation/sdk';
+import { __loadEntryDomForTest } from '../load';
+
+describe('loadEntryDom ESM fetchOptions gate', () => {
+  const loaderHook: any = { lifecycle: { fetch: { emit: jest.fn() } } };
+
+  it('uses the blob loader for module remotes carrying fetchOptions', async () => {
+    const remoteInfo: any = {
+      name: 'a', entry: 'http://x/e.js', type: 'module', entryGlobalName: 'a',
+      shareScope: 'default', fetchOptions: { headers: { Authorization: 'Bearer t' } },
+    };
+    await __loadEntryDomForTest({ remoteInfo, loaderHook });
+    expect(loadEsmEntryWithFetch).toHaveBeenCalledWith(
+      expect.objectContaining({ entry: 'http://x/e.js', fetchOptions: remoteInfo.fetchOptions }),
+    );
+  });
+});
+```
+
+If `loadEntryDom` is not exported, add a thin test-only export at the bottom of `load.ts`:
+
+```ts
+export const __loadEntryDomForTest = loadEntryDom;
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `pnpm --filter @module-federation/runtime-core test` (scoped to the new file).
+Expected: FAIL — blob loader not invoked (still calls `loadEsmEntry`), or `__loadEntryDomForTest` missing.
+
+- [ ] **Step 3: Add the import**
+
+In `packages/runtime-core/src/utils/load.ts`, extend the `@module-federation/sdk` import (lines 1-6):
+
+```ts
+import {
+  loadScript,
+  loadScriptNode,
+  composeKeyWithSeparator,
+  isBrowserEnvValue,
+  loadEsmEntryWithFetch,
+} from '@module-federation/sdk';
+```
+
+- [ ] **Step 4: Add the routing gate**
+
+In `loadEntryDom` (lines 202-219), replace the `esm`/`module` case so it routes to the blob loader when `fetchOptions` is present:
+
+```ts
+  const { entry, entryGlobalName: globalName, name, type } = remoteInfo;
+  switch (type) {
+    case 'esm':
+    case 'module':
+      return remoteInfo.fetchOptions
+        ? loadEsmEntryWithFetch({
+            entry,
+            fetchOptions: remoteInfo.fetchOptions,
+            // Route the loader's fetches through the runtime fetch hook so
+            // existing fetch-hook plugins still compose; merged headers are
+            // applied inside the sdk loader, native fetch is the fallback.
+            customFetch: (url, init) =>
+              loaderHook.lifecycle.fetch.emit(url, init, remoteInfo),
+          })
+        : loadEsmEntry({ entry, remoteEntryExports });
+    case 'system':
+      return loadSystemJsEntry({ entry, remoteEntryExports });
+    default:
+      return loadEntryScript({
+        entry,
+        globalName,
+        name,
+        remoteInfo,
+        loaderHook,
+        getEntryUrl,
+        resourceContext,
+      });
+  }
+```
+
+Add at the end of `load.ts`:
+
+```ts
+export const __loadEntryDomForTest = loadEntryDom;
+```
+
+- [ ] **Step 5: Run test to verify it passes**
+
+Run: `pnpm --filter @module-federation/runtime-core test` (scoped to the new file).
+Expected: PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add packages/runtime-core/src/utils/load.ts packages/runtime-core/src/utils/__tests__/load-entry-fetch-options.spec.ts
+git commit -m "feat(runtime-core): route ESM remotes with fetchOptions to blob loader"
+```
+
+---
+
+## Task 5: Authenticate the manifest fetch
+
+**Files:**
+- Modify: `packages/runtime-core/src/plugins/snapshot/SnapshotHandler.ts:306-321`
+- Test: extend an existing SnapshotHandler test or add `packages/runtime-core/src/plugins/snapshot/__tests__/manifest-fetch-options.spec.ts`
+
+- [ ] **Step 1: Apply the change**
+
+In `getManifestJson` (`SnapshotHandler.ts`), `remoteInfo` is already in scope (built at line 300 via `getRemoteInfo(moduleInfo)`). Replace the `{}` request options at lines 307-320:
+
+```ts
+        let res = await this.loaderHook.lifecycle.fetch.emit(
+          manifestUrl,
+          remoteInfo.fetchOptions ?? {},
+          remoteInfo,
+          resourceOptions
+            ? {
+                ...resourceOptions,
+                url: manifestUrl,
+                resourceType: 'manifest',
+              }
+            : undefined,
+        );
+        if (!res || !(res instanceof Response)) {
+          res = await fetch(manifestUrl, remoteInfo.fetchOptions ?? {});
+        }
+```
+
+- [ ] **Step 2: Write the test**
+
+```ts
+// packages/runtime-core/src/plugins/snapshot/__tests__/manifest-fetch-options.spec.ts
+import { ModuleFederation } from '../../../core';
+
+describe('manifest fetch carries fetchOptions', () => {
+  it('passes the remote fetchOptions to the fetch hook and native fallback', async () => {
+    const fetchOptions = { headers: { Authorization: 'Bearer t' } };
+    const manifest = {
+      id: 'sub', name: 'sub',
+      metaData: {
+        name: 'sub', type: 'app', buildInfo: { buildVersion: '1' }, globalName: 'sub',
+        remoteEntry: { name: 'remoteEntry.js', path: '', type: 'module' },
+        types: { path: '', name: '' }, buildVersion: '1', publicPath: 'http://x/',
+        ssrPublicPath: '', remotes: [], shared: [],
+      },
+      shared: [], remotes: [], exposes: [],
+    };
+    const fetchMock = jest.fn().mockResolvedValue(
+      new Response(JSON.stringify(manifest), { status: 200, headers: { 'content-type': 'application/json' } }),
+    );
+    (global as any).fetch = fetchMock;
+
+    const mf = new ModuleFederation({ name: 'host', remotes: [] });
+    mf.registerRemotes([{ name: 'sub', entry: 'http://x/mf-manifest.json' } as any], { fetchOptions });
+
+    // Trigger manifest load (errors past the fetch are fine for this assertion).
+    await mf.loadRemote('sub/thing').catch(() => undefined);
+
+    expect(fetchMock).toHaveBeenCalledWith('http://x/mf-manifest.json', fetchOptions);
+  });
+});
+```
+
+- [ ] **Step 3: Run test to verify it passes**
+
+Run: `pnpm --filter @module-federation/runtime-core test` (scoped to the new file).
+Expected: PASS — the native `fetch` fallback receives `fetchOptions`. (If a registered fetch-hook plugin short-circuits, assert on the hook emit args instead.)
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add packages/runtime-core/src/plugins/snapshot/SnapshotHandler.ts packages/runtime-core/src/plugins/snapshot/__tests__/manifest-fetch-options.spec.ts
+git commit -m "feat(runtime-core): authenticate manifest fetch with remote fetchOptions"
+```
+
+---
+
+## Task 6: Route manifest CSS through the blob loader when `fetchOptions` present
+
+**Files:**
+- Modify: `packages/runtime-core/src/utils/preload.ts` (imports, `preloadAssets` CSS loops ~lines 275-308, new `waitForCssFetch` helper)
+- Test: `packages/runtime-core/src/utils/__tests__/preload-css-fetch-options.spec.ts`
+
+- [ ] **Step 1: Add the import**
+
+At the top of `packages/runtime-core/src/utils/preload.ts`, add `loadCssWithFetch` to the existing `@module-federation/sdk` import (and `createLink`/`createScript` stay). Example:
+
+```ts
+import { createLink, createScript, loadCssWithFetch } from '@module-federation/sdk';
+```
+
+(Adjust to match the file's actual existing import statement.)
+
+- [ ] **Step 2: Add a header-authenticated CSS helper**
+
+Add near `waitForLinkPreload` in `preload.ts`:
+
+```ts
+// When the remote carries fetchOptions, CSS must be fetched WITH headers and
+// injected as a blob <link> — a native <link href> cannot carry headers, and a
+// rel=preload hint would 401. Mirrors loadCss in the loader PoC.
+function waitForCssFetch({
+  host,
+  remoteInfo,
+  url,
+  context,
+}: {
+  host: ModuleFederation;
+  remoteInfo: RemoteInfo;
+  url: string;
+  context: ResourceLoadContext;
+}): Promise<PreloadAssetResult> {
+  return loadCssWithFetch({
+    href: url,
+    fetchOptions: remoteInfo.fetchOptions,
+    customFetch: (u, init) => host.loaderHook.lifecycle.fetch.emit(u, init, remoteInfo),
+  })
+    .then(() => createAssetResult(context, url, 'success'))
+    .catch((error) =>
+      createAssetResult(context, url, isTimeoutError(error) ? 'timeout' : 'error', error),
+    );
+}
+```
+
+- [ ] **Step 3: Use it for CSS when `fetchOptions` present**
+
+In `preloadAssets`, gate the `cssAssets` handling. Replace the two `cssAssets.forEach(...)` blocks (lines ~280-307) so that when `remoteInfo.fetchOptions` is set, CSS goes through `waitForCssFetch`; otherwise the existing `waitForLinkPreload` paths are kept verbatim:
+
+```ts
+    if (remoteInfo.fetchOptions) {
+      cssAssets.forEach((cssUrl) => {
+        results.push(
+          waitForCssFetch({
+            host,
+            remoteInfo,
+            url: cssUrl,
+            context: createResourceContext(baseContext, 'css'),
+          }),
+        );
+      });
+    } else if (useLinkPreload) {
+      const defaultAttrs = { rel: 'preload', as: 'style' };
+      cssAssets.forEach((cssUrl) => {
+        results.push(
+          waitForLinkPreload({
+            host,
+            remoteInfo,
+            url: cssUrl,
+            attrs: defaultAttrs,
+            context: createResourceContext(baseContext, 'css'),
+          }),
+        );
+      });
+    } else {
+      const defaultAttrs = { rel: 'stylesheet', type: 'text/css' };
+      cssAssets.forEach((cssUrl) => {
+        results.push(
+          waitForLinkPreload({
+            host,
+            remoteInfo,
+            url: cssUrl,
+            attrs: defaultAttrs,
+            needDeleteLink: false,
+            context: createResourceContext(baseContext, 'css'),
+          }),
+        );
+      });
+    }
+```
+
+Leave the `jsAssetsWithoutEntry` blocks unchanged (those JS chunks are loaded through the blob graph via the entry's `__mfDyn`, so they already carry headers; preloading them as header-less hints is harmless and out of scope to change here).
+
+- [ ] **Step 4: Write the test**
+
+```ts
+// packages/runtime-core/src/utils/__tests__/preload-css-fetch-options.spec.ts
+const loadCssWithFetch = jest.fn().mockResolvedValue(undefined);
+jest.mock('@module-federation/sdk', () => {
+  const actual = jest.requireActual('@module-federation/sdk');
+  return { ...actual, loadCssWithFetch: (...args: any[]) => loadCssWithFetch(...args) };
+});
+
+import { preloadAssets } from '../preload';
+
+describe('preloadAssets CSS with fetchOptions', () => {
+  it('routes manifest CSS through the blob loader when fetchOptions is set', async () => {
+    const remoteInfo: any = {
+      name: 'a', entry: 'http://x/e.js', type: 'module', entryGlobalName: 'a',
+      shareScope: 'default', fetchOptions: { headers: { Authorization: 'Bearer t' } },
+    };
+    const host: any = {
+      options: { inBrowser: true },
+      loaderHook: { lifecycle: { fetch: { emit: jest.fn() } } },
+    };
+    const assets: any = { cssAssets: ['http://x/a.css'], jsAssetsWithoutEntry: [], entryAssets: [] };
+    await preloadAssets(remoteInfo, host, assets, false);
+    expect(loadCssWithFetch).toHaveBeenCalledWith(
+      expect.objectContaining({ href: 'http://x/a.css', fetchOptions: remoteInfo.fetchOptions }),
+    );
+  });
+});
+```
+
+- [ ] **Step 5: Run test to verify it passes**
+
+Run: `pnpm --filter @module-federation/runtime-core test` (scoped to the new file).
+Expected: PASS.
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add packages/runtime-core/src/utils/preload.ts packages/runtime-core/src/utils/__tests__/preload-css-fetch-options.spec.ts
+git commit -m "feat(runtime-core): fetch manifest CSS with headers for fetchOptions remotes"
+```
+
+---
+
+## Task 7: Full verification
+
+**Files:** none (verification only)
+
+- [ ] **Step 1: Confirm `fetchOptions` survives manifest resolution**
+
+Read `packages/runtime-core/src/plugins/snapshot/index.ts:18-38` (`assignRemoteInfo`). It mutates `remoteInfo` in place, setting only `type`, `entryGlobalName`, `entry`, `version`, `buildVersion` — it does NOT touch `fetchOptions`, so the field set in `getRemoteInfo` survives. No code change needed; this step just verifies the assumption still holds.
+
+- [ ] **Step 2: Build the two packages**
+
+Run: `pnpm exec turbo run build --filter=@module-federation/sdk --filter=@module-federation/runtime-core --concurrency=8`
+Expected: both build successfully.
+
+- [ ] **Step 3: Lint**
+
+Run: `pnpm --filter @module-federation/sdk lint && pnpm --filter @module-federation/runtime-core lint`
+Expected: no errors (fix any from the new files).
+
+- [ ] **Step 4: Run the full test suites for both packages**
+
+Run: `pnpm --filter @module-federation/sdk test && pnpm --filter @module-federation/runtime-core test`
+Expected: all green, including the new specs.
+
+- [ ] **Step 5: Add a changeset**
+
+Run: `pnpm changeset` and select `@module-federation/sdk` and `@module-federation/runtime-core` as `minor` (new feature, backward compatible). Describe: "Add per-remote `fetchOptions` to `registerRemotes` enabling header-authenticated ESM remote loading via a fetch+blob loader."
+
+- [ ] **Step 6: Commit**
+
+```bash
+git add .changeset
+git commit -m "chore: changeset for fetchOptions ESM remote loading"
+```
+
+---
+
+## Notes / follow-ups (out of scope here)
+
+- `system` (SystemJS) and IIFE/global remotes: only the manifest is authenticated for these; header-carrying chunk loads need separate work (SystemJS loader override / webpack publicPath interception).
+- CSS imported from inside JS (`import './x.css'`) is not handled by the rewriter (it only rewrites JS module specifiers); not exercised by the targeted ESM manifests.
+- The regex-based rewriter is kept as-is from the PoC — acceptable for bundler ESM output, but note it is not a full JS parser.

From bd362546ef56d192de1babb0dfdf45ffdf454adf Mon Sep 17 00:00:00 2001
From: Shaoyu Meng <shaoyumeng@shaoyus-mbp-5.lan>
Date: Tue, 16 Jun 2026 14:38:44 -0700
Subject: [PATCH 03/34] feat(sdk): add blob-loader import rewriter and
 resolveSpec

---
 packages/sdk/__tests__/blobLoad.spec.ts | 51 ++++++++++++++++++++++
 packages/sdk/src/blobLoad.ts            | 57 +++++++++++++++++++++++++
 2 files changed, 108 insertions(+)
 create mode 100644 packages/sdk/__tests__/blobLoad.spec.ts
 create mode 100644 packages/sdk/src/blobLoad.ts

diff --git a/packages/sdk/__tests__/blobLoad.spec.ts b/packages/sdk/__tests__/blobLoad.spec.ts
new file mode 100644
index 00000000000..d126fba80d5
--- /dev/null
+++ b/packages/sdk/__tests__/blobLoad.spec.ts
@@ -0,0 +1,51 @@
+import { resolveSpec, rewriteModuleCode } from '../src/blobLoad';
+
+describe('resolveSpec', () => {
+  it('returns absolute urls untouched', () => {
+    expect(resolveSpec('https://x.com/a.js', 'https://b.com/')).toBe(
+      'https://x.com/a.js',
+    );
+    expect(resolveSpec('blob:abc', 'https://b.com/')).toBe('blob:abc');
+    expect(resolveSpec('data:text/js,1', 'https://b.com/')).toBe(
+      'data:text/js,1',
+    );
+  });
+
+  it('resolves relative and absolute-path specifiers against the base', () => {
+    expect(resolveSpec('./dep.js', 'https://b.com/app/entry.js')).toBe(
+      'https://b.com/app/dep.js',
+    );
+    expect(resolveSpec('/root.js', 'https://b.com/app/entry.js')).toBe(
+      'https://b.com/root.js',
+    );
+  });
+
+  it('throws on bare specifiers', () => {
+    expect(() => resolveSpec('react', 'https://b.com/')).toThrow(
+      'bare specifier',
+    );
+  });
+});
+
+describe('rewriteModuleCode', () => {
+  const url = 'https://b.com/app/entry.js';
+
+  it('pins import.meta.url to the module url', () => {
+    const { code } = rewriteModuleCode('const u = import.meta.url;', url);
+    expect(code).toBe(`const u = ${JSON.stringify(url)};`);
+  });
+
+  it('routes dynamic import() through __mfDyn with the base url', () => {
+    const { code } = rewriteModuleCode('const m = import("./x.js");', url);
+    expect(code).toBe(`const m = __mfDyn(${JSON.stringify(url)},"./x.js");`);
+  });
+
+  it('collects static relative/absolute deps and leaves bare imports alone', () => {
+    const src = `import a from "./a.js";\nexport { b } from "/b.js";\nimport c from "react";`;
+    const { deps } = rewriteModuleCode(src, url);
+    expect(deps.map((d) => d.spec).sort()).toEqual(['./a.js', '/b.js']);
+    expect(deps.find((d) => d.spec === './a.js')!.depUrl).toBe(
+      'https://b.com/app/a.js',
+    );
+  });
+});
diff --git a/packages/sdk/src/blobLoad.ts b/packages/sdk/src/blobLoad.ts
new file mode 100644
index 00000000000..efddb12343c
--- /dev/null
+++ b/packages/sdk/src/blobLoad.ts
@@ -0,0 +1,57 @@
+// Hardened port of the fetch + blob import-rewriting loader PoC
+// (js-module-import/index.html). Comments are retained from the PoC where the
+// logic is carried over verbatim.
+
+export interface BlobDep {
+  original: string;
+  spec: string;
+  quote: string;
+  depUrl: string;
+}
+
+// Resolve a specifier (relative, absolute-path, or already-absolute-url)
+// against a base url to a concrete fetchable url. The MF runtime resolves
+// shared deps to relative loadShare asset urls, so bare specifiers never reach
+// the loader; anything bare is unexpected and throws.
+export function resolveSpec(spec: string, base: string): string {
+  if (/^(blob:|https?:|data:)/.test(spec)) return spec;
+  if (spec.startsWith('.') || spec.startsWith('/'))
+    return new URL(spec, base).href;
+  throw new Error(
+    `[loader] cannot resolve bare specifier "${spec}" (from ${base})`,
+  );
+}
+
+// Rewrite a module's source: pin import.meta.url, route dynamic imports through
+// __mfDyn, and collect static relative/absolute specifiers (to be replaced with
+// recursively-loaded blob urls by the caller).
+export function rewriteModuleCode(
+  code: string,
+  url: string,
+): { code: string; deps: BlobDep[] } {
+  // import.meta.url -> the module's real url.
+  // In this case, modules with publicPath:"auto" can derive paths from it.
+  code = code.replace(/\bimport\.meta\.url\b/g, JSON.stringify(url));
+
+  // Dynamic import(...) -> __mfDyn("<url>", ...).
+  code = code.replace(
+    /(?<![.\w$])import\s*\(/g,
+    `__mfDyn(${JSON.stringify(url)},`,
+  );
+
+  // Static `import * from ...` and `import ...` -> recursively-loaded blob urls.
+  const specRe = /(?<![.\w$])(from|import)\s*(['"])([^'"]+)\2/g;
+  const deps: BlobDep[] = [];
+  for (const m of code.matchAll(specRe)) {
+    const spec = m[3];
+    if (spec.startsWith('.') || spec.startsWith('/')) {
+      deps.push({
+        original: m[0],
+        spec,
+        quote: m[2],
+        depUrl: resolveSpec(spec, url),
+      });
+    }
+  }
+  return { code, deps };
+}

From 5265f3de8d3826ba791cf20fbf8fc2e25fec80e6 Mon Sep 17 00:00:00 2001
From: Shaoyu Meng <shaoyumeng@shaoyus-mbp-5.lan>
Date: Tue, 16 Jun 2026 14:43:55 -0700
Subject: [PATCH 04/34] test(sdk): cover BlobDep splice fields and side-effect
 imports

---
 packages/sdk/__tests__/blobLoad.spec.ts | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/packages/sdk/__tests__/blobLoad.spec.ts b/packages/sdk/__tests__/blobLoad.spec.ts
index d126fba80d5..86f545c68b3 100644
--- a/packages/sdk/__tests__/blobLoad.spec.ts
+++ b/packages/sdk/__tests__/blobLoad.spec.ts
@@ -47,5 +47,13 @@ describe('rewriteModuleCode', () => {
     expect(deps.find((d) => d.spec === './a.js')!.depUrl).toBe(
       'https://b.com/app/a.js',
     );
+    const aDep = deps.find((d) => d.spec === './a.js')!;
+    expect(aDep.original).toBe('from "./a.js"');
+    expect(aDep.quote).toBe('"');
+  });
+
+  it('collects side-effect imports', () => {
+    const { deps } = rewriteModuleCode('import "./side.js";', url);
+    expect(deps.map((d) => d.spec)).toEqual(['./side.js']);
   });
 });

From 8748e5a4bb831dc0113436b0124101e64c406dc4 Mon Sep 17 00:00:00 2001
From: Shaoyu Meng <shaoyumeng@shaoyus-mbp-5.lan>
Date: Tue, 16 Jun 2026 14:47:00 -0700
Subject: [PATCH 05/34] feat(sdk): add fetch+blob ESM loader
 (loadEsmEntryWithFetch, loadCssWithFetch)

---
 packages/sdk/__tests__/blobLoad.spec.ts |  71 +++++++++++
 packages/sdk/src/blobLoad.ts            | 155 ++++++++++++++++++++++++
 packages/sdk/src/index.ts               |   1 +
 3 files changed, 227 insertions(+)

diff --git a/packages/sdk/__tests__/blobLoad.spec.ts b/packages/sdk/__tests__/blobLoad.spec.ts
index 86f545c68b3..edd4e4cd30c 100644
--- a/packages/sdk/__tests__/blobLoad.spec.ts
+++ b/packages/sdk/__tests__/blobLoad.spec.ts
@@ -57,3 +57,74 @@ describe('rewriteModuleCode', () => {
     expect(deps.map((d) => d.spec)).toEqual(['./side.js']);
   });
 });
+
+import { fetchText, loadModule, loadEsmEntryWithFetch } from '../src/blobLoad';
+
+describe('fetchText', () => {
+  beforeEach(() => {
+    (global as any).fetch = jest.fn();
+  });
+
+  it('merges fetchOptions headers and returns response text', async () => {
+    (global.fetch as jest.Mock).mockResolvedValue({
+      ok: true,
+      text: () => Promise.resolve('CODE'),
+    });
+    const text = await fetchText('https://b.com/e.js', {
+      fetchOptions: { headers: { Authorization: 'Bearer t' } },
+    });
+    expect(text).toBe('CODE');
+    const init = (global.fetch as jest.Mock).mock.calls[0][1];
+    expect(init.headers).toEqual({ Authorization: 'Bearer t' });
+  });
+
+  it('prefers customFetch when it returns a Response', async () => {
+    const customFetch = jest.fn().mockResolvedValue({
+      ok: true,
+      text: () => Promise.resolve('HOOKED'),
+    } as any);
+    const text = await fetchText('https://b.com/e.js', { customFetch });
+    expect(customFetch).toHaveBeenCalled();
+    expect(text).toBe('HOOKED');
+    expect(global.fetch as jest.Mock).not.toHaveBeenCalled();
+  });
+
+  it('throws a descriptive error on non-ok responses', async () => {
+    (global.fetch as jest.Mock).mockResolvedValue({
+      ok: false,
+      status: 401,
+      statusText: 'Unauthorized',
+      text: () => Promise.resolve(''),
+    });
+    await expect(fetchText('https://b.com/e.js', {})).rejects.toThrow(
+      'BlobLoaderNetworkError: 401',
+    );
+  });
+});
+
+describe('loadModule', () => {
+  beforeEach(() => {
+    (global as any).fetch = jest.fn();
+    (global.URL as any).createObjectURL = jest.fn(
+      (blob: Blob) => `blob:${(blob as any).__id || 'x'}`,
+    );
+    loadModule.clearCache();
+  });
+
+  it('rewrites a static dep to a recursively-loaded blob url and caches by url', async () => {
+    const files: Record<string, string> = {
+      'https://b.com/entry.js': `import dep from "./dep.js";`,
+      'https://b.com/dep.js': `export default 1;`,
+    };
+    (global.fetch as jest.Mock).mockImplementation((url: string) =>
+      Promise.resolve({ ok: true, text: () => Promise.resolve(files[url]) }),
+    );
+    const blobUrl = await loadModule('https://b.com/entry.js', {});
+    expect(blobUrl).toMatch(/^blob:/);
+    expect(
+      (global.fetch as jest.Mock).mock.calls.map((c) => c[0]).sort(),
+    ).toEqual(['https://b.com/dep.js', 'https://b.com/entry.js']);
+    await loadModule('https://b.com/entry.js', {});
+    expect((global.fetch as jest.Mock).mock.calls.length).toBe(2);
+  });
+});
diff --git a/packages/sdk/src/blobLoad.ts b/packages/sdk/src/blobLoad.ts
index efddb12343c..975df7b2d6e 100644
--- a/packages/sdk/src/blobLoad.ts
+++ b/packages/sdk/src/blobLoad.ts
@@ -55,3 +55,158 @@ export function rewriteModuleCode(
   }
   return { code, deps };
 }
+
+export type BlobFetcher = (
+  url: string,
+  init: RequestInit,
+) => Promise<Response | void | false> | Response | void | false;
+
+export interface BlobLoadContext {
+  fetchOptions?: RequestInit;
+  // Optional custom fetch (e.g. routed through the runtime loaderHook.fetch so
+  // existing fetch-hook plugins still compose). Falls back to native fetch.
+  customFetch?: BlobFetcher;
+}
+
+// absolute url -> Promise<blob url>
+const cache = new Map<string, Promise<string>>();
+// absolute url -> the context it was loaded with, so __mfDyn can reuse the
+// right headers for runtime dynamic imports of that module's chunks.
+const contexts = new Map<string, BlobLoadContext>();
+let dynImportInstalled = false;
+
+function isResponseLike(res: unknown): res is Response {
+  return (
+    !!res &&
+    typeof res === 'object' &&
+    typeof (res as Response).text === 'function' &&
+    'ok' in (res as Response)
+  );
+}
+
+export async function fetchText(
+  url: string,
+  ctx: BlobLoadContext,
+): Promise<string> {
+  const { headers, ...rest } = ctx.fetchOptions || {};
+  const init: RequestInit = {
+    ...rest,
+    headers: { ...(headers as Record<string, string>) },
+  };
+  let res: Response | void | false = undefined;
+  if (ctx.customFetch) {
+    res = await ctx.customFetch(url, init);
+  }
+  if (!isResponseLike(res)) {
+    res = await fetch(url, init);
+  }
+  if (!res.ok) {
+    throw new Error(
+      `BlobLoaderNetworkError: ${res.status} ${res.statusText} for ${url}`,
+    );
+  }
+  return res.text();
+}
+
+// Fetch a module with headers, rewrite its imports.
+// Dynamic imports are handled lazily at runtime via __mfDyn,
+// Static relative imports are pre-loaded recursively.
+function loadModuleImpl(url: string, ctx: BlobLoadContext): Promise<string> {
+  if (cache.has(url)) return cache.get(url)!;
+  contexts.set(url, ctx);
+
+  const promise = (async () => {
+    const raw = await fetchText(url, ctx);
+    const { code: rewritten, deps } = rewriteModuleCode(raw, url);
+    let code = rewritten;
+    const blobUrls = await Promise.all(
+      deps.map((d) => loadModule(d.depUrl, ctx)),
+    );
+    deps.forEach((d, i) => {
+      const replaced = d.original.replace(
+        `${d.quote}${d.spec}${d.quote}`,
+        `${d.quote}${blobUrls[i]}${d.quote}`,
+      );
+      code = code.split(d.original).join(replaced);
+    });
+    return URL.createObjectURL(
+      new Blob([code], { type: 'application/javascript' }),
+    );
+  })();
+
+  cache.set(url, promise);
+  return promise;
+}
+
+// Exported with a clearCache test seam.
+export const loadModule: ((
+  url: string,
+  ctx: BlobLoadContext,
+) => Promise<string>) & {
+  clearCache: () => void;
+} = Object.assign(loadModuleImpl, {
+  clearCache: () => {
+    cache.clear();
+    contexts.clear();
+  },
+});
+
+function installDynImportShim(): void {
+  if (dynImportInstalled) return;
+  dynImportInstalled = true;
+
+  // Runtime dynamic-import shim: resolve url + fetch from cache or with headers + import as blob.
+  (globalThis as Record<string, unknown>)['__mfDyn'] = async (
+    base: string,
+    spec: string,
+  ) => {
+    const resolved = resolveSpec(spec, base);
+    if (/^(blob:|data:)/.test(resolved)) {
+      return import(/* webpackIgnore: true */ /* @vite-ignore */ resolved);
+    }
+    const ctx = contexts.get(base) || {};
+    return import(
+      /* webpackIgnore: true */ /* @vite-ignore */ await loadModule(
+        resolved,
+        ctx,
+      )
+    );
+  };
+
+  // The vite preload helper creates native <link> preloads (no auth header) as a
+  // perf hint; let those 401 quietly instead of throwing — real loads go via __mfDyn.
+  if (typeof window !== 'undefined') {
+    window.addEventListener('vite:preloadError', (e) => e.preventDefault());
+  }
+}
+
+export async function loadEsmEntryWithFetch({
+  entry,
+  fetchOptions,
+  customFetch,
+}: {
+  entry: string;
+  fetchOptions?: RequestInit;
+  customFetch?: BlobFetcher;
+}): Promise<Record<string, unknown>> {
+  installDynImportShim();
+  const blobUrl = await loadModule(entry, { fetchOptions, customFetch });
+  return import(/* webpackIgnore: true */ /* @vite-ignore */ blobUrl);
+}
+
+export async function loadCssWithFetch({
+  href,
+  fetchOptions,
+  customFetch,
+}: {
+  href: string;
+  fetchOptions?: RequestInit;
+  customFetch?: BlobFetcher;
+}): Promise<void> {
+  const text = await fetchText(href, { fetchOptions, customFetch });
+  const blob = URL.createObjectURL(new Blob([text], { type: 'text/css' }));
+  const link = document.createElement('link');
+  link.rel = 'stylesheet';
+  link.href = blob;
+  document.head.appendChild(link);
+}
diff --git a/packages/sdk/src/index.ts b/packages/sdk/src/index.ts
index 91408c4a527..0e433f78301 100644
--- a/packages/sdk/src/index.ts
+++ b/packages/sdk/src/index.ts
@@ -18,6 +18,7 @@ export {
 export type { Logger, InfrastructureLogger } from './logger';
 export * from './env';
 export * from './dom';
+export * from './blobLoad';
 export * from './node';
 export * from './normalizeOptions';
 export { createModuleFederationConfig } from './createModuleFederationConfig';

From f0e831ed4586b725336d84beb7820ae12116957a Mon Sep 17 00:00:00 2001
From: Shaoyu Meng <shaoyumeng@shaoyus-mbp-5.lan>
Date: Tue, 16 Jun 2026 15:00:54 -0700
Subject: [PATCH 06/34] fix(sdk): normalize headers, evict failed loads,
 refresh context, dedupe css

---
 packages/sdk/__tests__/blobLoad.spec.ts | 66 ++++++++++++++++++++++++-
 packages/sdk/src/blobLoad.ts            | 36 ++++++++++++--
 2 files changed, 96 insertions(+), 6 deletions(-)

diff --git a/packages/sdk/__tests__/blobLoad.spec.ts b/packages/sdk/__tests__/blobLoad.spec.ts
index edd4e4cd30c..3970b5f1d67 100644
--- a/packages/sdk/__tests__/blobLoad.spec.ts
+++ b/packages/sdk/__tests__/blobLoad.spec.ts
@@ -58,7 +58,12 @@ describe('rewriteModuleCode', () => {
   });
 });
 
-import { fetchText, loadModule, loadEsmEntryWithFetch } from '../src/blobLoad';
+import {
+  fetchText,
+  loadModule,
+  loadEsmEntryWithFetch,
+  loadCssWithFetch,
+} from '../src/blobLoad';
 
 describe('fetchText', () => {
   beforeEach(() => {
@@ -100,6 +105,18 @@ describe('fetchText', () => {
       'BlobLoaderNetworkError: 401',
     );
   });
+
+  it('normalizes a Headers instance into the request init', async () => {
+    (global.fetch as jest.Mock).mockResolvedValue({
+      ok: true,
+      text: () => Promise.resolve('CODE'),
+    });
+    await fetchText('https://b.com/e.js', {
+      fetchOptions: { headers: new Headers({ Authorization: 'Bearer t' }) },
+    });
+    const init = (global.fetch as jest.Mock).mock.calls[0][1];
+    expect(init.headers).toEqual({ authorization: 'Bearer t' });
+  });
 });
 
 describe('loadModule', () => {
@@ -127,4 +144,51 @@ describe('loadModule', () => {
     await loadModule('https://b.com/entry.js', {});
     expect((global.fetch as jest.Mock).mock.calls.length).toBe(2);
   });
+
+  it('evicts a failed load from the cache so a later call retries', async () => {
+    (global.fetch as jest.Mock)
+      .mockResolvedValueOnce({
+        ok: false,
+        status: 503,
+        statusText: 'Unavailable',
+        text: () => Promise.resolve(''),
+      })
+      .mockResolvedValueOnce({
+        ok: true,
+        text: () => Promise.resolve('export default 1;'),
+      });
+    await expect(loadModule('https://b.com/x.js', {})).rejects.toThrow(
+      'BlobLoaderNetworkError: 503',
+    );
+    const blobUrl = await loadModule('https://b.com/x.js', {});
+    expect(blobUrl).toMatch(/^blob:/);
+    expect((global.fetch as jest.Mock).mock.calls.length).toBe(2);
+  });
+});
+
+describe('loadCssWithFetch', () => {
+  beforeEach(() => {
+    (global as any).fetch = jest
+      .fn()
+      .mockResolvedValue({ ok: true, text: () => Promise.resolve('.a{}') });
+    (global.URL as any).createObjectURL = jest.fn(() => 'blob:css');
+    loadModule.clearCache();
+    document.head.innerHTML = '';
+  });
+
+  it('fetches css with headers and injects a single stylesheet, deduping repeat calls', async () => {
+    await loadCssWithFetch({
+      href: 'https://b.com/a.css',
+      fetchOptions: { headers: { Authorization: 'Bearer t' } },
+    });
+    await loadCssWithFetch({
+      href: 'https://b.com/a.css',
+      fetchOptions: { headers: { Authorization: 'Bearer t' } },
+    });
+    expect((global.fetch as jest.Mock).mock.calls.length).toBe(1);
+    const links = document.head.getElementsByTagName('link');
+    expect(links.length).toBe(1);
+    expect(links[0].rel).toBe('stylesheet');
+    expect(links[0].href).toContain('blob:css');
+  });
 });
diff --git a/packages/sdk/src/blobLoad.ts b/packages/sdk/src/blobLoad.ts
index 975df7b2d6e..2f23f6888b1 100644
--- a/packages/sdk/src/blobLoad.ts
+++ b/packages/sdk/src/blobLoad.ts
@@ -73,6 +73,8 @@ const cache = new Map<string, Promise<string>>();
 // absolute url -> the context it was loaded with, so __mfDyn can reuse the
 // right headers for runtime dynamic imports of that module's chunks.
 const contexts = new Map<string, BlobLoadContext>();
+// original css href -> blob url, so repeat calls don't re-fetch or double-inject.
+const cssCache = new Map<string, string>();
 let dynImportInstalled = false;
 
 function isResponseLike(res: unknown): res is Response {
@@ -84,15 +86,29 @@ function isResponseLike(res: unknown): res is Response {
   );
 }
 
+function toHeaderObject(
+  headers: RequestInit['headers'],
+): Record<string, string> {
+  if (!headers) return {};
+  if (typeof Headers !== 'undefined' && headers instanceof Headers) {
+    return Object.fromEntries(
+      (
+        headers as unknown as { entries(): IterableIterator<[string, string]> }
+      ).entries(),
+    );
+  }
+  if (Array.isArray(headers)) {
+    return Object.fromEntries(headers);
+  }
+  return { ...(headers as Record<string, string>) };
+}
+
 export async function fetchText(
   url: string,
   ctx: BlobLoadContext,
 ): Promise<string> {
   const { headers, ...rest } = ctx.fetchOptions || {};
-  const init: RequestInit = {
-    ...rest,
-    headers: { ...(headers as Record<string, string>) },
-  };
+  const init: RequestInit = { ...rest, headers: toHeaderObject(headers) };
   let res: Response | void | false = undefined;
   if (ctx.customFetch) {
     res = await ctx.customFetch(url, init);
@@ -112,8 +128,10 @@ export async function fetchText(
 // Dynamic imports are handled lazily at runtime via __mfDyn,
 // Static relative imports are pre-loaded recursively.
 function loadModuleImpl(url: string, ctx: BlobLoadContext): Promise<string> {
-  if (cache.has(url)) return cache.get(url)!;
+  // Register the context for this url on every call so __mfDyn uses the latest
+  // headers for that module's dynamic imports, even when the blob is cached.
   contexts.set(url, ctx);
+  if (cache.has(url)) return cache.get(url)!;
 
   const promise = (async () => {
     const raw = await fetchText(url, ctx);
@@ -135,6 +153,11 @@ function loadModuleImpl(url: string, ctx: BlobLoadContext): Promise<string> {
   })();
 
   cache.set(url, promise);
+  // Don't permanently cache a failed load — allow a later retry (e.g. via the
+  // runtime loadEntryError hook) to re-fetch instead of replaying the rejection.
+  promise.catch(() => {
+    if (cache.get(url) === promise) cache.delete(url);
+  });
   return promise;
 }
 
@@ -148,6 +171,7 @@ export const loadModule: ((
   clearCache: () => {
     cache.clear();
     contexts.clear();
+    cssCache.clear();
   },
 });
 
@@ -203,8 +227,10 @@ export async function loadCssWithFetch({
   fetchOptions?: RequestInit;
   customFetch?: BlobFetcher;
 }): Promise<void> {
+  if (cssCache.has(href)) return;
   const text = await fetchText(href, { fetchOptions, customFetch });
   const blob = URL.createObjectURL(new Blob([text], { type: 'text/css' }));
+  cssCache.set(href, blob);
   const link = document.createElement('link');
   link.rel = 'stylesheet';
   link.href = blob;

From 033ca3cb3a51ec61a54ad41699169adc867c546e Mon Sep 17 00:00:00 2001
From: Shaoyu Meng <shaoyumeng@shaoyus-mbp-5.lan>
Date: Tue, 16 Jun 2026 15:03:39 -0700
Subject: [PATCH 07/34] feat(runtime-core): thread per-remote fetchOptions
 through registerRemotes

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../__tests__/register-remotes.spec.ts        | 27 +++++++++++++++++++
 packages/runtime-core/src/core.ts             |  5 +++-
 packages/runtime-core/src/remote/index.ts     | 10 ++++++-
 packages/runtime-core/src/type/config.ts      |  2 ++
 4 files changed, 42 insertions(+), 2 deletions(-)

diff --git a/packages/runtime-core/__tests__/register-remotes.spec.ts b/packages/runtime-core/__tests__/register-remotes.spec.ts
index c7789536191..f65f83ab12d 100644
--- a/packages/runtime-core/__tests__/register-remotes.spec.ts
+++ b/packages/runtime-core/__tests__/register-remotes.spec.ts
@@ -209,4 +209,31 @@ describe('ModuleFederation', () => {
     expect(await nextAppModule()).toBe('hello world "@snapshot/remote2"');
     expect(manifestFetch).toHaveBeenCalledTimes(2);
   });
+  it('stamps call-level fetchOptions onto each remote that lacks its own', () => {
+    const FM = new ModuleFederation({
+      name: '@federation/instance',
+      version: '1.0.1',
+      remotes: [],
+    });
+    const fetchOptions: RequestInit = {
+      headers: { Authorization: 'Bearer t' },
+    };
+    const r1 = {
+      name: '@register-remotes/fetch-a',
+      entry: 'http://localhost:1111/resources/register-remotes/app1/a.js',
+    };
+    const r2 = {
+      name: '@register-remotes/fetch-b',
+      entry: 'http://localhost:1111/resources/register-remotes/app1/b.js',
+      fetchOptions: { headers: { 'X-B': '1' } } as RequestInit,
+    };
+    FM.registerRemotes([r1, r2], { fetchOptions });
+    const stored = FM.options.remotes;
+    expect(
+      stored.find((r) => r.name === '@register-remotes/fetch-a')!.fetchOptions,
+    ).toBe(fetchOptions);
+    expect(
+      stored.find((r) => r.name === '@register-remotes/fetch-b')!.fetchOptions,
+    ).toEqual({ headers: { 'X-B': '1' } });
+  });
 });
diff --git a/packages/runtime-core/src/core.ts b/packages/runtime-core/src/core.ts
index df09129a9a0..c8e45bc13f2 100644
--- a/packages/runtime-core/src/core.ts
+++ b/packages/runtime-core/src/core.ts
@@ -455,7 +455,10 @@ export class ModuleFederation {
       return res;
     }, pluginRes || []);
   }
-  registerRemotes(remotes: Remote[], options?: { force?: boolean }): void {
+  registerRemotes(
+    remotes: Remote[],
+    options?: { force?: boolean; fetchOptions?: RequestInit },
+  ): void {
     return this.remoteHandler.registerRemotes(remotes, options);
   }
 
diff --git a/packages/runtime-core/src/remote/index.ts b/packages/runtime-core/src/remote/index.ts
index 1704e41d5f7..8f1a02b464f 100644
--- a/packages/runtime-core/src/remote/index.ts
+++ b/packages/runtime-core/src/remote/index.ts
@@ -500,9 +500,17 @@ export class RemoteHandler {
     }
   }
 
-  registerRemotes(remotes: Remote[], options?: { force?: boolean }): void {
+  registerRemotes(
+    remotes: Remote[],
+    options?: { force?: boolean; fetchOptions?: RequestInit },
+  ): void {
     const { host } = this;
     remotes.forEach((remote) => {
+      // fetchOptions passed to this call applies to each remote registered in
+      // it; an explicit per-remote fetchOptions on the remote object wins.
+      if (options?.fetchOptions && remote.fetchOptions === undefined) {
+        remote.fetchOptions = options.fetchOptions;
+      }
       this.registerRemote(remote, host.options.remotes, {
         force: options?.force,
       });
diff --git a/packages/runtime-core/src/type/config.ts b/packages/runtime-core/src/type/config.ts
index 98c6c357bbf..1dcb3ac1d3a 100644
--- a/packages/runtime-core/src/type/config.ts
+++ b/packages/runtime-core/src/type/config.ts
@@ -17,6 +17,7 @@ export interface RemoteInfoCommon {
   shareScope?: string | string[];
   type?: RemoteEntryType;
   entryGlobalName?: string;
+  fetchOptions?: RequestInit;
 }
 
 export type RemoteInfoOptionalVersion = {
@@ -40,6 +41,7 @@ export interface RemoteInfo {
   type: RemoteEntryType;
   entryGlobalName: string;
   shareScope: string | string[];
+  fetchOptions?: RequestInit;
 }
 
 export type HostInfo = Pick<

From 1f23f1ea66db11c6084d9b850901f5875c0c0b3e Mon Sep 17 00:00:00 2001
From: Shaoyu Meng <shaoyumeng@shaoyus-mbp-5.lan>
Date: Tue, 16 Jun 2026 15:12:54 -0700
Subject: [PATCH 08/34] feat(runtime-core): route ESM remotes with fetchOptions
 to blob loader

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../load-entry-fetch-options.spec.ts          | 53 +++++++++++++++++++
 packages/runtime-core/src/utils/load.ts       | 17 +++++-
 2 files changed, 69 insertions(+), 1 deletion(-)
 create mode 100644 packages/runtime-core/__tests__/load-entry-fetch-options.spec.ts

diff --git a/packages/runtime-core/__tests__/load-entry-fetch-options.spec.ts b/packages/runtime-core/__tests__/load-entry-fetch-options.spec.ts
new file mode 100644
index 00000000000..1a0e0ca6813
--- /dev/null
+++ b/packages/runtime-core/__tests__/load-entry-fetch-options.spec.ts
@@ -0,0 +1,53 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import * as sdk from '@module-federation/sdk';
+import { __loadEntryDomForTest } from '../src/utils/load';
+
+describe('loadEntryDom ESM fetchOptions gate', () => {
+  const loaderHook: any = { lifecycle: { fetch: { emit: vi.fn() } } };
+  let loadEsmEntryWithFetch: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    // Spy on the sdk's blob loader. load.ts imports from the same module
+    // namespace, so spying here intercepts the call it makes.
+    loadEsmEntryWithFetch = vi
+      .spyOn(sdk, 'loadEsmEntryWithFetch')
+      .mockResolvedValue({ ok: 1 });
+  });
+
+  afterEach(() => {
+    loadEsmEntryWithFetch.mockRestore();
+  });
+
+  it('uses the blob loader for module remotes carrying fetchOptions', async () => {
+    const remoteInfo: any = {
+      name: 'a',
+      entry: 'http://x/e.js',
+      type: 'module',
+      entryGlobalName: 'a',
+      shareScope: 'default',
+      fetchOptions: { headers: { Authorization: 'Bearer t' } },
+    };
+    await __loadEntryDomForTest({ remoteInfo, loaderHook });
+    expect(loadEsmEntryWithFetch).toHaveBeenCalledWith(
+      expect.objectContaining({
+        entry: 'http://x/e.js',
+        fetchOptions: remoteInfo.fetchOptions,
+      }),
+    );
+  });
+
+  it('does NOT use the blob loader for module remotes without fetchOptions', async () => {
+    const remoteInfo: any = {
+      name: 'b',
+      entry: 'http://x/e2.js',
+      type: 'module',
+      entryGlobalName: 'b',
+      shareScope: 'default',
+    };
+    await __loadEntryDomForTest({ remoteInfo, loaderHook }).catch(
+      () => undefined,
+    );
+    expect(loadEsmEntryWithFetch).not.toHaveBeenCalled();
+  });
+});
diff --git a/packages/runtime-core/src/utils/load.ts b/packages/runtime-core/src/utils/load.ts
index 9452f82736e..50bd4346022 100644
--- a/packages/runtime-core/src/utils/load.ts
+++ b/packages/runtime-core/src/utils/load.ts
@@ -3,6 +3,7 @@ import {
   loadScriptNode,
   composeKeyWithSeparator,
   isBrowserEnvValue,
+  loadEsmEntryWithFetch,
 } from '@module-federation/sdk';
 import { DEFAULT_REMOTE_TYPE, DEFAULT_SCOPE } from '../constant';
 import { ModuleFederation } from '../core';
@@ -203,7 +204,19 @@ async function loadEntryDom({
   switch (type) {
     case 'esm':
     case 'module':
-      return loadEsmEntry({ entry, remoteEntryExports });
+      return remoteInfo.fetchOptions
+        ? (loadEsmEntryWithFetch({
+            entry,
+            fetchOptions: remoteInfo.fetchOptions,
+            // Route the loader's fetches through the runtime fetch hook so
+            // existing fetch-hook plugins still compose; merged headers are
+            // applied inside the sdk loader, native fetch is the fallback.
+            // The async arrow flattens the hook's nested-promise return to the
+            // Response | void | false shape the sdk loader expects.
+            customFetch: async (url, init) =>
+              loaderHook.lifecycle.fetch.emit(url, init, remoteInfo),
+          }) as Promise<RemoteEntryExports>)
+        : loadEsmEntry({ entry, remoteEntryExports });
     case 'system':
       return loadSystemJsEntry({ entry, remoteEntryExports });
     default:
@@ -399,3 +412,5 @@ export function getRemoteInfo(remote: Remote): RemoteInfo {
     shareScope: remote.shareScope || DEFAULT_SCOPE,
   };
 }
+
+export const __loadEntryDomForTest = loadEntryDom;

From 82b7e6e01ecd3e835cd72b62017dda7c4a38940e Mon Sep 17 00:00:00 2001
From: Shaoyu Meng <shaoyumeng@shaoyus-mbp-5.lan>
Date: Tue, 16 Jun 2026 15:18:35 -0700
Subject: [PATCH 09/34] feat(runtime-core): authenticate manifest fetch with
 remote fetchOptions

---
 .../__tests__/manifest-fetch-options.spec.ts  | 63 +++++++++++++++++++
 .../src/plugins/snapshot/SnapshotHandler.ts   |  4 +-
 2 files changed, 65 insertions(+), 2 deletions(-)
 create mode 100644 packages/runtime-core/__tests__/manifest-fetch-options.spec.ts

diff --git a/packages/runtime-core/__tests__/manifest-fetch-options.spec.ts b/packages/runtime-core/__tests__/manifest-fetch-options.spec.ts
new file mode 100644
index 00000000000..cd750039539
--- /dev/null
+++ b/packages/runtime-core/__tests__/manifest-fetch-options.spec.ts
@@ -0,0 +1,63 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { ModuleFederation } from '../src';
+import { resetFederationGlobalInfo } from '../src/global';
+
+// Uses the snapshot manifest fixtures served by the MSW mock server
+// (see __tests__/mock + __tests__/resources/snapshot). When a remote is
+// registered with fetchOptions, the manifest network request must carry
+// those fetchOptions.
+//
+// The production change lives in SnapshotHandler.getManifestJson, where the
+// fetch hook is invoked as:
+//   loaderHook.lifecycle.fetch.emit(manifestUrl, remoteInfo.fetchOptions ?? {}, ...)
+// and the native fallback as:
+//   fetch(manifestUrl, remoteInfo.fetchOptions ?? {})
+//
+// We assert on the fetch-hook emit arguments (the first network entry point),
+// which deterministically receive the fetchOptions regardless of whether a
+// plugin or the native fetch ultimately resolves the request.
+describe('manifest fetch carries fetchOptions', () => {
+  afterEach(() => {
+    resetFederationGlobalInfo();
+    vi.restoreAllMocks();
+  });
+
+  it('passes the remote fetchOptions to the manifest fetch hook', async () => {
+    const fetchOptions: RequestInit = {
+      headers: { Authorization: 'Bearer token-123' },
+    };
+    const manifestUrl =
+      'http://localhost:1111/resources/snapshot/remote1/federation-manifest.json';
+
+    const mf = new ModuleFederation({
+      name: '@manifest-fetch-options/host',
+      remotes: [],
+    });
+
+    const emitSpy = vi.spyOn(mf.loaderHook.lifecycle.fetch, 'emit');
+
+    mf.registerRemotes(
+      [
+        {
+          name: '@snapshot/remote1',
+          entry: manifestUrl,
+        },
+      ],
+      { fetchOptions },
+    );
+
+    await mf
+      .loadRemote<() => string>('@snapshot/remote1/say')
+      .catch(() => undefined);
+
+    const manifestCall = emitSpy.mock.calls.find(
+      (call) => typeof call[0] === 'string' && call[0] === manifestUrl,
+    );
+
+    expect(manifestCall).toBeTruthy();
+    // 2nd argument is the request options threaded from the remote.
+    expect(manifestCall?.[1]).toEqual(fetchOptions);
+    // remoteInfo (3rd argument) carries the fetchOptions too.
+    expect((manifestCall?.[2] as any)?.fetchOptions).toEqual(fetchOptions);
+  });
+});
diff --git a/packages/runtime-core/src/plugins/snapshot/SnapshotHandler.ts b/packages/runtime-core/src/plugins/snapshot/SnapshotHandler.ts
index e3661cfdbf7..24fad89c3c8 100644
--- a/packages/runtime-core/src/plugins/snapshot/SnapshotHandler.ts
+++ b/packages/runtime-core/src/plugins/snapshot/SnapshotHandler.ts
@@ -306,7 +306,7 @@ export class SnapshotHandler {
       try {
         let res = await this.loaderHook.lifecycle.fetch.emit(
           manifestUrl,
-          {},
+          remoteInfo.fetchOptions ?? {},
           remoteInfo,
           resourceOptions
             ? {
@@ -317,7 +317,7 @@ export class SnapshotHandler {
             : undefined,
         );
         if (!res || !(res instanceof Response)) {
-          res = await fetch(manifestUrl, {});
+          res = await fetch(manifestUrl, remoteInfo.fetchOptions ?? {});
         }
         manifestJson = (await res.json()) as Manifest;
       } catch (err) {

From b9c816a70571e58e7a7272a6f9670ff03931b331 Mon Sep 17 00:00:00 2001
From: Shaoyu Meng <shaoyumeng@shaoyus-mbp-5.lan>
Date: Tue, 16 Jun 2026 15:22:47 -0700
Subject: [PATCH 10/34] feat(runtime-core): fetch manifest CSS with headers for
 fetchOptions remotes

---
 .../preload-css-fetch-options.spec.ts         | 62 +++++++++++++++++++
 packages/runtime-core/src/utils/preload.ts    | 51 ++++++++++++++-
 2 files changed, 111 insertions(+), 2 deletions(-)
 create mode 100644 packages/runtime-core/__tests__/preload-css-fetch-options.spec.ts

diff --git a/packages/runtime-core/__tests__/preload-css-fetch-options.spec.ts b/packages/runtime-core/__tests__/preload-css-fetch-options.spec.ts
new file mode 100644
index 00000000000..c0bb166aaed
--- /dev/null
+++ b/packages/runtime-core/__tests__/preload-css-fetch-options.spec.ts
@@ -0,0 +1,62 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import * as sdk from '@module-federation/sdk';
+import { preloadAssets } from '../src/utils/preload';
+
+describe('preloadAssets CSS with fetchOptions', () => {
+  let spy: any;
+  beforeEach(() => {
+    spy = vi.spyOn(sdk, 'loadCssWithFetch').mockResolvedValue(undefined as any);
+  });
+  afterEach(() => {
+    spy.mockRestore();
+    vi.clearAllMocks();
+  });
+
+  it('routes manifest CSS through the blob loader when fetchOptions is set', async () => {
+    const remoteInfo: any = {
+      name: 'a',
+      entry: 'http://x/e.js',
+      type: 'module',
+      entryGlobalName: 'a',
+      shareScope: 'default',
+      fetchOptions: { headers: { Authorization: 'Bearer t' } },
+    };
+    const host: any = {
+      options: { inBrowser: true },
+      loaderHook: { lifecycle: { fetch: { emit: vi.fn() } } },
+    };
+    const assets: any = {
+      cssAssets: ['http://x/a.css'],
+      jsAssetsWithoutEntry: [],
+      entryAssets: [],
+    };
+    await preloadAssets(remoteInfo, host, assets, false);
+    expect(spy).toHaveBeenCalledWith(
+      expect.objectContaining({
+        href: 'http://x/a.css',
+        fetchOptions: remoteInfo.fetchOptions,
+      }),
+    );
+  });
+
+  it('does NOT use the blob loader when fetchOptions is absent', async () => {
+    const remoteInfo: any = {
+      name: 'b',
+      entry: 'http://x/e.js',
+      type: 'module',
+      entryGlobalName: 'b',
+      shareScope: 'default',
+    };
+    const host: any = {
+      options: { inBrowser: true },
+      loaderHook: { lifecycle: { fetch: { emit: vi.fn() } } },
+    };
+    const assets: any = {
+      cssAssets: ['http://x/b.css'],
+      jsAssetsWithoutEntry: [],
+      entryAssets: [],
+    };
+    await preloadAssets(remoteInfo, host, assets, false).catch(() => undefined);
+    expect(spy).not.toHaveBeenCalled();
+  });
+});
diff --git a/packages/runtime-core/src/utils/preload.ts b/packages/runtime-core/src/utils/preload.ts
index 9deb9810339..7119ee6ad42 100644
--- a/packages/runtime-core/src/utils/preload.ts
+++ b/packages/runtime-core/src/utils/preload.ts
@@ -1,4 +1,9 @@
-import { createLink, createScript, safeToString } from '@module-federation/sdk';
+import {
+  createLink,
+  createScript,
+  loadCssWithFetch,
+  safeToString,
+} from '@module-federation/sdk';
 import {
   PreloadAssets,
   PreloadAssetResult,
@@ -181,6 +186,37 @@ function waitForLinkPreload({
   });
 }
 
+// When the remote carries fetchOptions, CSS must be fetched WITH headers and
+// injected as a blob <link> — a native <link href> cannot carry headers, and a
+// rel=preload hint would 401. Mirrors loadCss in the loader PoC.
+function waitForCssFetch({
+  host,
+  remoteInfo,
+  url,
+  context,
+}: {
+  host: ModuleFederation;
+  remoteInfo: RemoteInfo;
+  url: string;
+  context: ResourceLoadContext;
+}): Promise<PreloadAssetResult> {
+  return loadCssWithFetch({
+    href: url,
+    fetchOptions: remoteInfo.fetchOptions,
+    customFetch: async (u, init) =>
+      host.loaderHook.lifecycle.fetch.emit(u, init, remoteInfo),
+  })
+    .then(() => createAssetResult(context, url, 'success'))
+    .catch((error) =>
+      createAssetResult(
+        context,
+        url,
+        isTimeoutError(error) ? 'timeout' : 'error',
+        error,
+      ),
+    );
+}
+
 function waitForScriptPreload({
   host,
   remoteInfo,
@@ -272,7 +308,18 @@ export function preloadAssets(
       );
     });
 
-    if (useLinkPreload) {
+    if (remoteInfo.fetchOptions) {
+      cssAssets.forEach((cssUrl) => {
+        results.push(
+          waitForCssFetch({
+            host,
+            remoteInfo,
+            url: cssUrl,
+            context: createResourceContext(baseContext, 'css'),
+          }),
+        );
+      });
+    } else if (useLinkPreload) {
       const defaultAttrs = {
         rel: 'preload',
         as: 'style',

From 0d1841b5162604afa6409eb6ebc0f234d47d887a Mon Sep 17 00:00:00 2001
From: Shaoyu Meng <shaoyumeng@shaoyus-mbp-5.lan>
Date: Tue, 16 Jun 2026 15:34:39 -0700
Subject: [PATCH 11/34] fix(sdk): dedupe in-flight css loads; harden preload
 css test

---
 .../preload-css-fetch-options.spec.ts         | 30 ++++++++++++++++--
 packages/sdk/__tests__/blobLoad.spec.ts       | 19 ++++++++++++
 packages/sdk/src/blobLoad.ts                  | 31 ++++++++++++-------
 3 files changed, 67 insertions(+), 13 deletions(-)

diff --git a/packages/runtime-core/__tests__/preload-css-fetch-options.spec.ts b/packages/runtime-core/__tests__/preload-css-fetch-options.spec.ts
index c0bb166aaed..48ae8224a76 100644
--- a/packages/runtime-core/__tests__/preload-css-fetch-options.spec.ts
+++ b/packages/runtime-core/__tests__/preload-css-fetch-options.spec.ts
@@ -49,14 +49,40 @@ describe('preloadAssets CSS with fetchOptions', () => {
     };
     const host: any = {
       options: { inBrowser: true },
-      loaderHook: { lifecycle: { fetch: { emit: vi.fn() } } },
+      loaderHook: {
+        lifecycle: {
+          fetch: { emit: vi.fn() },
+          createLink: { emit: vi.fn() },
+          createScript: { emit: vi.fn() },
+        },
+      },
     };
     const assets: any = {
       cssAssets: ['http://x/b.css'],
       jsAssetsWithoutEntry: [],
       entryAssets: [],
     };
-    await preloadAssets(remoteInfo, host, assets, false).catch(() => undefined);
+    // jsdom env (see vitest.config.ts) provides DOM, so the no-fetchOptions
+    // else-branch (waitForLinkPreload -> createLink) runs cleanly without a
+    // swallowing .catch. createLink resolves on the <link> load event, which
+    // jsdom does not dispatch on its own, so we fire it (as a real browser
+    // would) to let the branch settle. A genuine crash before/during the
+    // branch would still reject and fail the test.
+    const observer = new MutationObserver((mutations) => {
+      mutations.forEach((m) =>
+        m.addedNodes.forEach((node) => {
+          if (node instanceof HTMLLinkElement) {
+            node.dispatchEvent(new Event('load'));
+          }
+        }),
+      );
+    });
+    observer.observe(document.head, { childList: true });
+    try {
+      await preloadAssets(remoteInfo, host, assets, false);
+    } finally {
+      observer.disconnect();
+    }
     expect(spy).not.toHaveBeenCalled();
   });
 });
diff --git a/packages/sdk/__tests__/blobLoad.spec.ts b/packages/sdk/__tests__/blobLoad.spec.ts
index 3970b5f1d67..c02e8a4b4ac 100644
--- a/packages/sdk/__tests__/blobLoad.spec.ts
+++ b/packages/sdk/__tests__/blobLoad.spec.ts
@@ -191,4 +191,23 @@ describe('loadCssWithFetch', () => {
     expect(links[0].rel).toBe('stylesheet');
     expect(links[0].href).toContain('blob:css');
   });
+
+  it('dedupes concurrent loads of the same href (single fetch, single link)', async () => {
+    let resolveFetch: (v: any) => void;
+    (global as any).fetch = jest.fn().mockImplementation(
+      () =>
+        new Promise((r) => {
+          resolveFetch = r;
+        }),
+    );
+    (global.URL as any).createObjectURL = jest.fn(() => 'blob:css');
+    loadModule.clearCache();
+    document.head.innerHTML = '';
+    const p1 = loadCssWithFetch({ href: 'https://b.com/c.css' });
+    const p2 = loadCssWithFetch({ href: 'https://b.com/c.css' });
+    resolveFetch!({ ok: true, text: () => Promise.resolve('.c{}') });
+    await Promise.all([p1, p2]);
+    expect((global.fetch as jest.Mock).mock.calls.length).toBe(1);
+    expect(document.head.getElementsByTagName('link').length).toBe(1);
+  });
 });
diff --git a/packages/sdk/src/blobLoad.ts b/packages/sdk/src/blobLoad.ts
index 2f23f6888b1..7f6ec7441e4 100644
--- a/packages/sdk/src/blobLoad.ts
+++ b/packages/sdk/src/blobLoad.ts
@@ -73,8 +73,9 @@ const cache = new Map<string, Promise<string>>();
 // absolute url -> the context it was loaded with, so __mfDyn can reuse the
 // right headers for runtime dynamic imports of that module's chunks.
 const contexts = new Map<string, BlobLoadContext>();
-// original css href -> blob url, so repeat calls don't re-fetch or double-inject.
-const cssCache = new Map<string, string>();
+// original css href -> in-flight/settled load, so concurrent or repeat calls
+// don't re-fetch or double-inject the stylesheet.
+const cssCache = new Map<string, Promise<void>>();
 let dynImportInstalled = false;
 
 function isResponseLike(res: unknown): res is Response {
@@ -218,7 +219,7 @@ export async function loadEsmEntryWithFetch({
   return import(/* webpackIgnore: true */ /* @vite-ignore */ blobUrl);
 }
 
-export async function loadCssWithFetch({
+export function loadCssWithFetch({
   href,
   fetchOptions,
   customFetch,
@@ -227,12 +228,20 @@ export async function loadCssWithFetch({
   fetchOptions?: RequestInit;
   customFetch?: BlobFetcher;
 }): Promise<void> {
-  if (cssCache.has(href)) return;
-  const text = await fetchText(href, { fetchOptions, customFetch });
-  const blob = URL.createObjectURL(new Blob([text], { type: 'text/css' }));
-  cssCache.set(href, blob);
-  const link = document.createElement('link');
-  link.rel = 'stylesheet';
-  link.href = blob;
-  document.head.appendChild(link);
+  const cached = cssCache.get(href);
+  if (cached) return cached;
+  const promise = (async () => {
+    const text = await fetchText(href, { fetchOptions, customFetch });
+    const blob = URL.createObjectURL(new Blob([text], { type: 'text/css' }));
+    const link = document.createElement('link');
+    link.rel = 'stylesheet';
+    link.href = blob;
+    document.head.appendChild(link);
+  })();
+  cssCache.set(href, promise);
+  // Don't permanently cache a failed css load — allow a later retry.
+  promise.catch(() => {
+    if (cssCache.get(href) === promise) cssCache.delete(href);
+  });
+  return promise;
 }

From 5ae69d652c9db25ab2d9340296993e47c47cbc66 Mon Sep 17 00:00:00 2001
From: Shaoyu Meng <shaoyumeng@shaoyus-mbp-5.lan>
Date: Tue, 16 Jun 2026 15:36:37 -0700
Subject: [PATCH 12/34] chore: changeset + document deferred limitations for
 fetchOptions ESM loading

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .changeset/remote-fetch-options.md                    |  6 ++++++
 ...26-06-16-fetchoptions-esm-remote-loading-design.md | 11 +++++++++++
 2 files changed, 17 insertions(+)
 create mode 100644 .changeset/remote-fetch-options.md

diff --git a/.changeset/remote-fetch-options.md b/.changeset/remote-fetch-options.md
new file mode 100644
index 00000000000..0916124f8d7
--- /dev/null
+++ b/.changeset/remote-fetch-options.md
@@ -0,0 +1,6 @@
+---
+'@module-federation/runtime-core': minor
+'@module-federation/sdk': minor
+---
+
+Add per-remote `fetchOptions` to `registerRemotes`, enabling header-authenticated ESM remote loading. When a `module`/`esm` remote is registered with `registerRemotes(remotes, { fetchOptions })`, the manifest, remote entry, split chunks, and shared deps are loaded via a fetch + blob import-rewriting loader so custom HTTP headers (e.g. `Authorization`) reach every asset request. Manifest-declared CSS for such remotes is also fetched with headers and injected as a blob stylesheet. Non-ESM remotes and remotes without `fetchOptions` are unaffected.
diff --git a/docs/superpowers/specs/2026-06-16-fetchoptions-esm-remote-loading-design.md b/docs/superpowers/specs/2026-06-16-fetchoptions-esm-remote-loading-design.md
index 54f6f95e7d1..dd5a8b495ce 100644
--- a/docs/superpowers/specs/2026-06-16-fetchoptions-esm-remote-loading-design.md
+++ b/docs/superpowers/specs/2026-06-16-fetchoptions-esm-remote-loading-design.md
@@ -58,6 +58,17 @@ of scope for this iteration.
   `fetchOptions`, only the manifest is authenticated this iteration.
 - CSS imported from inside JS (`import './x.css'`) — not exercised by the PoC
   and not part of the ESM manifests we target.
+- **JS preload hints** (`jsAssetsWithoutEntry` in `preloadAssets`): these emit
+  header-less `<link rel="preload" as="script">` hints. For `fetchOptions`
+  remotes those hints will 401, but they are harmless — the actual chunk/shared
+  loads run through the authenticated blob graph (`__mfDyn`), exactly like the
+  PoC's suppressed `vite:preloadError` hints. Suppressing the wasted hints is a
+  possible future cleanup, not a correctness fix.
+- **`createLink` lifecycle hook for authenticated CSS:** `loadCssWithFetch`
+  injects the blob `<link>` directly and does not emit the `createLink` hook, so
+  plugins that add CSP `nonce`/SRI attributes do not run for `fetchOptions` CSS.
+  Threading the hook into the sdk loader is a follow-up; unauthenticated CSS
+  still uses the hook.
 
 ## Decisions
 

From 6c9b7a84e39024b5a72848f93d4f506568b344c9 Mon Sep 17 00:00:00 2001
From: Shaoyu Meng <shaoyumeng@shaoyus-mbp-5.lan>
Date: Tue, 16 Jun 2026 17:40:48 -0700
Subject: [PATCH 13/34] refactor(sdk): rename js module cache to jsCache for
 clarity

Distinguishes the JS module blob cache from cssCache.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/sdk/__tests__/blobLoad.spec.ts | 15 +++++++--------
 packages/sdk/src/blobLoad.ts            | 16 ++++++++--------
 2 files changed, 15 insertions(+), 16 deletions(-)

diff --git a/packages/sdk/__tests__/blobLoad.spec.ts b/packages/sdk/__tests__/blobLoad.spec.ts
index c02e8a4b4ac..7dd152362c7 100644
--- a/packages/sdk/__tests__/blobLoad.spec.ts
+++ b/packages/sdk/__tests__/blobLoad.spec.ts
@@ -44,10 +44,9 @@ describe('rewriteModuleCode', () => {
     const src = `import a from "./a.js";\nexport { b } from "/b.js";\nimport c from "react";`;
     const { deps } = rewriteModuleCode(src, url);
     expect(deps.map((d) => d.spec).sort()).toEqual(['./a.js', '/b.js']);
-    expect(deps.find((d) => d.spec === './a.js')!.depUrl).toBe(
-      'https://b.com/app/a.js',
-    );
+
     const aDep = deps.find((d) => d.spec === './a.js')!;
+    expect(aDep.depUrl).toBe('https://b.com/app/a.js');
     expect(aDep.original).toBe('from "./a.js"');
     expect(aDep.quote).toBe('"');
   });
@@ -79,8 +78,8 @@ describe('fetchText', () => {
       fetchOptions: { headers: { Authorization: 'Bearer t' } },
     });
     expect(text).toBe('CODE');
-    const init = (global.fetch as jest.Mock).mock.calls[0][1];
-    expect(init.headers).toEqual({ Authorization: 'Bearer t' });
+    const requestInit = (global.fetch as jest.Mock).mock.calls[0][1];
+    expect(requestInit.headers).toEqual({ Authorization: 'Bearer t' });
   });
 
   it('prefers customFetch when it returns a Response', async () => {
@@ -122,9 +121,7 @@ describe('fetchText', () => {
 describe('loadModule', () => {
   beforeEach(() => {
     (global as any).fetch = jest.fn();
-    (global.URL as any).createObjectURL = jest.fn(
-      (blob: Blob) => `blob:${(blob as any).__id || 'x'}`,
-    );
+    (global.URL as any).createObjectURL = jest.fn(() => `blob:`);
     loadModule.clearCache();
   });
 
@@ -138,9 +135,11 @@ describe('loadModule', () => {
     );
     const blobUrl = await loadModule('https://b.com/entry.js', {});
     expect(blobUrl).toMatch(/^blob:/);
+    // recursively loads all dependencies
     expect(
       (global.fetch as jest.Mock).mock.calls.map((c) => c[0]).sort(),
     ).toEqual(['https://b.com/dep.js', 'https://b.com/entry.js']);
+    // only fetches once and caches them, reload does not invoke more fetches
     await loadModule('https://b.com/entry.js', {});
     expect((global.fetch as jest.Mock).mock.calls.length).toBe(2);
   });
diff --git a/packages/sdk/src/blobLoad.ts b/packages/sdk/src/blobLoad.ts
index 7f6ec7441e4..85ae1be0902 100644
--- a/packages/sdk/src/blobLoad.ts
+++ b/packages/sdk/src/blobLoad.ts
@@ -68,10 +68,10 @@ export interface BlobLoadContext {
   customFetch?: BlobFetcher;
 }
 
-// absolute url -> Promise<blob url>
-const cache = new Map<string, Promise<string>>();
-// absolute url -> the context it was loaded with, so __mfDyn can reuse the
-// right headers for runtime dynamic imports of that module's chunks.
+// absolute url -> Promise<blob url> for JS modules (parallel to cssCache below)
+const jsCache = new Map<string, Promise<string>>();
+// absolute url -> fetcher and its options
+// __mfDyn should reuse the right load context for each module's chunks request.
 const contexts = new Map<string, BlobLoadContext>();
 // original css href -> in-flight/settled load, so concurrent or repeat calls
 // don't re-fetch or double-inject the stylesheet.
@@ -132,7 +132,7 @@ function loadModuleImpl(url: string, ctx: BlobLoadContext): Promise<string> {
   // Register the context for this url on every call so __mfDyn uses the latest
   // headers for that module's dynamic imports, even when the blob is cached.
   contexts.set(url, ctx);
-  if (cache.has(url)) return cache.get(url)!;
+  if (jsCache.has(url)) return jsCache.get(url)!;
 
   const promise = (async () => {
     const raw = await fetchText(url, ctx);
@@ -153,11 +153,11 @@ function loadModuleImpl(url: string, ctx: BlobLoadContext): Promise<string> {
     );
   })();
 
-  cache.set(url, promise);
+  jsCache.set(url, promise);
   // Don't permanently cache a failed load — allow a later retry (e.g. via the
   // runtime loadEntryError hook) to re-fetch instead of replaying the rejection.
   promise.catch(() => {
-    if (cache.get(url) === promise) cache.delete(url);
+    if (jsCache.get(url) === promise) jsCache.delete(url);
   });
   return promise;
 }
@@ -170,7 +170,7 @@ export const loadModule: ((
   clearCache: () => void;
 } = Object.assign(loadModuleImpl, {
   clearCache: () => {
-    cache.clear();
+    jsCache.clear();
     contexts.clear();
     cssCache.clear();
   },

From f5a3b2defd32a6941626c407eb528ce3ac97bc99 Mon Sep 17 00:00:00 2001
From: Shaoyu Meng <shaoyumeng@shaoyus-mbp-5.lan>
Date: Tue, 16 Jun 2026 17:46:16 -0700
Subject: [PATCH 14/34] refactor(sdk): simplify fetchText init construction to
 single spread

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/sdk/src/blobLoad.ts | 6 ++++--
 1 file changed, 4 insertions(+), 2 deletions(-)

diff --git a/packages/sdk/src/blobLoad.ts b/packages/sdk/src/blobLoad.ts
index 85ae1be0902..911f364009f 100644
--- a/packages/sdk/src/blobLoad.ts
+++ b/packages/sdk/src/blobLoad.ts
@@ -108,8 +108,10 @@ export async function fetchText(
   url: string,
   ctx: BlobLoadContext,
 ): Promise<string> {
-  const { headers, ...rest } = ctx.fetchOptions || {};
-  const init: RequestInit = { ...rest, headers: toHeaderObject(headers) };
+  const init: RequestInit = {
+    ...(ctx.fetchOptions || {}),
+    headers: toHeaderObject(ctx.fetchOptions?.headers),
+  };
   let res: Response | void | false = undefined;
   if (ctx.customFetch) {
     res = await ctx.customFetch(url, init);

From f56a462422816d118ae00e338177c9c7fda3f1fc Mon Sep 17 00:00:00 2001
From: Shaoyu Meng <shaoyumeng@shaoyus-mbp-5.lan>
Date: Tue, 16 Jun 2026 18:06:49 -0700
Subject: [PATCH 15/34] chore(ts): add dom.iterable to base lib; drop Headers
 cast in blobLoad

dom.iterable surfaces Headers.entries()/Symbol.iterator on the standard
DOM types, so toHeaderObject can use Object.fromEntries(headers.entries())
without the unknown-cast workaround. Verified: all 42 packages build,
sdk type-checks, sdk tests pass.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/sdk/src/blobLoad.ts | 6 +-----
 tsconfig.base.json           | 2 +-
 2 files changed, 2 insertions(+), 6 deletions(-)

diff --git a/packages/sdk/src/blobLoad.ts b/packages/sdk/src/blobLoad.ts
index 911f364009f..d75c1dbff55 100644
--- a/packages/sdk/src/blobLoad.ts
+++ b/packages/sdk/src/blobLoad.ts
@@ -92,11 +92,7 @@ function toHeaderObject(
 ): Record<string, string> {
   if (!headers) return {};
   if (typeof Headers !== 'undefined' && headers instanceof Headers) {
-    return Object.fromEntries(
-      (
-        headers as unknown as { entries(): IterableIterator<[string, string]> }
-      ).entries(),
-    );
+    return Object.fromEntries(headers.entries());
   }
   if (Array.isArray(headers)) {
     return Object.fromEntries(headers);
diff --git a/tsconfig.base.json b/tsconfig.base.json
index 579c154e785..8ac7ca390a8 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -12,7 +12,7 @@
     "target": "es2021",
     "allowJs": true,
     "module": "esnext",
-    "lib": ["es2021", "dom"],
+    "lib": ["es2021", "dom", "dom.iterable"],
     "skipLibCheck": true,
     "skipDefaultLibCheck": true,
     "baseUrl": ".",

From 60cfc38f6ccd6cf50a37bdca1642e94baca3a237 Mon Sep 17 00:00:00 2001
From: Shaoyu Meng <shaoyumeng@shaoyus-mbp-5.lan>
Date: Tue, 16 Jun 2026 19:02:41 -0700
Subject: [PATCH 16/34] refactor(sdk): clean up blobLoad (rename shim, clarify
 comments)

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/sdk/src/blobLoad.ts | 20 +++++++++-----------
 1 file changed, 9 insertions(+), 11 deletions(-)

diff --git a/packages/sdk/src/blobLoad.ts b/packages/sdk/src/blobLoad.ts
index d75c1dbff55..c9f8f8c7f12 100644
--- a/packages/sdk/src/blobLoad.ts
+++ b/packages/sdk/src/blobLoad.ts
@@ -1,7 +1,3 @@
-// Hardened port of the fetch + blob import-rewriting loader PoC
-// (js-module-import/index.html). Comments are retained from the PoC where the
-// logic is carried over verbatim.
-
 export interface BlobDep {
   original: string;
   spec: string;
@@ -68,13 +64,12 @@ export interface BlobLoadContext {
   customFetch?: BlobFetcher;
 }
 
-// absolute url -> Promise<blob url> for JS modules (parallel to cssCache below)
-const jsCache = new Map<string, Promise<string>>();
 // absolute url -> fetcher and its options
 // __mfDyn should reuse the right load context for each module's chunks request.
 const contexts = new Map<string, BlobLoadContext>();
-// original css href -> in-flight/settled load, so concurrent or repeat calls
-// don't re-fetch or double-inject the stylesheet.
+// absolute url -> Promise<blob url> for JS modules
+const jsCache = new Map<string, Promise<string>>();
+// absolute url -> in-flight/settled promise, used to prevent double-inject the stylesheet.
 const cssCache = new Map<string, Promise<void>>();
 let dynImportInstalled = false;
 
@@ -87,6 +82,7 @@ function isResponseLike(res: unknown): res is Response {
   );
 }
 
+// Create a const copy of headers, to avoid the case when the original headers are mutated by fetcher.
 function toHeaderObject(
   headers: RequestInit['headers'],
 ): Record<string, string> {
@@ -134,11 +130,13 @@ function loadModuleImpl(url: string, ctx: BlobLoadContext): Promise<string> {
 
   const promise = (async () => {
     const raw = await fetchText(url, ctx);
+    // Stage 1 rewrite: replace import.meta.url with url, and dynamic import(), collect static deps.
     const { code: rewritten, deps } = rewriteModuleCode(raw, url);
     let code = rewritten;
     const blobUrls = await Promise.all(
       deps.map((d) => loadModule(d.depUrl, ctx)),
     );
+    // Stage 2 rewrite: replace static deps with blob urls.
     deps.forEach((d, i) => {
       const replaced = d.original.replace(
         `${d.quote}${d.spec}${d.quote}`,
@@ -174,7 +172,7 @@ export const loadModule: ((
   },
 });
 
-function installDynImportShim(): void {
+function installMFDynImportShim(): void {
   if (dynImportInstalled) return;
   dynImportInstalled = true;
 
@@ -197,7 +195,7 @@ function installDynImportShim(): void {
   };
 
   // The vite preload helper creates native <link> preloads (no auth header) as a
-  // perf hint; let those 401 quietly instead of throwing — real loads go via __mfDyn.
+  // perf hint; those 401 errors should be ignored instead of throwing — real loads go via __mfDyn.
   if (typeof window !== 'undefined') {
     window.addEventListener('vite:preloadError', (e) => e.preventDefault());
   }
@@ -212,7 +210,7 @@ export async function loadEsmEntryWithFetch({
   fetchOptions?: RequestInit;
   customFetch?: BlobFetcher;
 }): Promise<Record<string, unknown>> {
-  installDynImportShim();
+  installMFDynImportShim();
   const blobUrl = await loadModule(entry, { fetchOptions, customFetch });
   return import(/* webpackIgnore: true */ /* @vite-ignore */ blobUrl);
 }

From af04afe582dcbc18b44c8d92b0e4790eb4e4d3c9 Mon Sep 17 00:00:00 2001
From: Shaoyu Meng <shaoyumeng@shaoyus-mbp-5.lan>
Date: Tue, 16 Jun 2026 19:28:01 -0700
Subject: [PATCH 17/34] feat(runtime-core): merge call-level and per-remote
 fetchOptions

Call-level fetchOptions now act as defaults that each remote's own
fetchOptions are merged on top of (remote wins on conflict), with headers
merged per-key so a remote adding one header no longer drops the
call-level ones. Exposes toHeaderObject from sdk to share the
header-normalization used by the merge.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../__tests__/manifest-fetch-options.spec.ts  | 16 +---------
 .../__tests__/register-remotes.spec.ts        | 21 ++++++++++---
 packages/runtime-core/src/remote/index.ts     | 30 ++++++++++++++++---
 packages/sdk/src/blobLoad.ts                  |  2 +-
 4 files changed, 45 insertions(+), 24 deletions(-)

diff --git a/packages/runtime-core/__tests__/manifest-fetch-options.spec.ts b/packages/runtime-core/__tests__/manifest-fetch-options.spec.ts
index cd750039539..5f98d681148 100644
--- a/packages/runtime-core/__tests__/manifest-fetch-options.spec.ts
+++ b/packages/runtime-core/__tests__/manifest-fetch-options.spec.ts
@@ -2,20 +2,6 @@ import { describe, it, expect, vi, afterEach } from 'vitest';
 import { ModuleFederation } from '../src';
 import { resetFederationGlobalInfo } from '../src/global';
 
-// Uses the snapshot manifest fixtures served by the MSW mock server
-// (see __tests__/mock + __tests__/resources/snapshot). When a remote is
-// registered with fetchOptions, the manifest network request must carry
-// those fetchOptions.
-//
-// The production change lives in SnapshotHandler.getManifestJson, where the
-// fetch hook is invoked as:
-//   loaderHook.lifecycle.fetch.emit(manifestUrl, remoteInfo.fetchOptions ?? {}, ...)
-// and the native fallback as:
-//   fetch(manifestUrl, remoteInfo.fetchOptions ?? {})
-//
-// We assert on the fetch-hook emit arguments (the first network entry point),
-// which deterministically receive the fetchOptions regardless of whether a
-// plugin or the native fetch ultimately resolves the request.
 describe('manifest fetch carries fetchOptions', () => {
   afterEach(() => {
     resetFederationGlobalInfo();
@@ -57,7 +43,7 @@ describe('manifest fetch carries fetchOptions', () => {
     expect(manifestCall).toBeTruthy();
     // 2nd argument is the request options threaded from the remote.
     expect(manifestCall?.[1]).toEqual(fetchOptions);
-    // remoteInfo (3rd argument) carries the fetchOptions too.
+    // 3rd argument is remoteInfo, and should carry the fetchOptions too.
     expect((manifestCall?.[2] as any)?.fetchOptions).toEqual(fetchOptions);
   });
 });
diff --git a/packages/runtime-core/__tests__/register-remotes.spec.ts b/packages/runtime-core/__tests__/register-remotes.spec.ts
index f65f83ab12d..5316fbbe222 100644
--- a/packages/runtime-core/__tests__/register-remotes.spec.ts
+++ b/packages/runtime-core/__tests__/register-remotes.spec.ts
@@ -209,7 +209,7 @@ describe('ModuleFederation', () => {
     expect(await nextAppModule()).toBe('hello world "@snapshot/remote2"');
     expect(manifestFetch).toHaveBeenCalledTimes(2);
   });
-  it('stamps call-level fetchOptions onto each remote that lacks its own', () => {
+  it('merges call-level fetchOptions with each remote (remote wins on conflict)', () => {
     const FM = new ModuleFederation({
       name: '@federation/instance',
       version: '1.0.1',
@@ -218,22 +218,35 @@ describe('ModuleFederation', () => {
     const fetchOptions: RequestInit = {
       headers: { Authorization: 'Bearer t' },
     };
+    // No own fetchOptions: gets the call-level defaults.
     const r1 = {
       name: '@register-remotes/fetch-a',
       entry: 'http://localhost:1111/resources/register-remotes/app1/a.js',
     };
+    // Own header added: merged on top of the call-level Authorization.
     const r2 = {
       name: '@register-remotes/fetch-b',
       entry: 'http://localhost:1111/resources/register-remotes/app1/b.js',
       fetchOptions: { headers: { 'X-B': '1' } } as RequestInit,
     };
-    FM.registerRemotes([r1, r2], { fetchOptions });
+    // Own header conflicts with the call-level one: remote wins.
+    const r3 = {
+      name: '@register-remotes/fetch-c',
+      entry: 'http://localhost:1111/resources/register-remotes/app1/c.js',
+      fetchOptions: {
+        headers: { Authorization: 'Bearer override' },
+      } as RequestInit,
+    };
+    FM.registerRemotes([r1, r2, r3], { fetchOptions });
     const stored = FM.options.remotes;
     expect(
       stored.find((r) => r.name === '@register-remotes/fetch-a')!.fetchOptions,
-    ).toBe(fetchOptions);
+    ).toEqual({ headers: { Authorization: 'Bearer t' } });
     expect(
       stored.find((r) => r.name === '@register-remotes/fetch-b')!.fetchOptions,
-    ).toEqual({ headers: { 'X-B': '1' } });
+    ).toEqual({ headers: { Authorization: 'Bearer t', 'X-B': '1' } });
+    expect(
+      stored.find((r) => r.name === '@register-remotes/fetch-c')!.fetchOptions,
+    ).toEqual({ headers: { Authorization: 'Bearer override' } });
   });
 });
diff --git a/packages/runtime-core/src/remote/index.ts b/packages/runtime-core/src/remote/index.ts
index 8f1a02b464f..9fb4145ab96 100644
--- a/packages/runtime-core/src/remote/index.ts
+++ b/packages/runtime-core/src/remote/index.ts
@@ -4,6 +4,7 @@ import {
   composeKeyWithSeparator,
   ModuleInfo,
   GlobalModuleInfo,
+  toHeaderObject,
 } from '@module-federation/sdk';
 import { RUNTIME_004, runtimeDescMap } from '@module-federation/error-codes';
 import {
@@ -49,6 +50,23 @@ import { formatPreloadArgs, preloadAssets } from '../utils/preload';
 import { getGlobalShareScope } from '../utils/share';
 import { getGlobalRemoteInfo } from '../plugins/snapshot/SnapshotHandler';
 
+// Merge call-level fetchOptions (defaults) with a remote's own (overrides).
+// Non-header fields shallow-merge with the remote winning; headers merge
+// per-key so a remote adding one header doesn't drop the call-level ones.
+function mergeFetchOptions(
+  base: RequestInit,
+  override: RequestInit | undefined,
+): RequestInit {
+  return {
+    ...base,
+    ...(override ?? {}),
+    headers: {
+      ...toHeaderObject(base.headers),
+      ...toHeaderObject(override?.headers),
+    },
+  };
+}
+
 export interface LoadRemoteMatch {
   id: string;
   pkgNameOrAlias: string;
@@ -506,10 +524,14 @@ export class RemoteHandler {
   ): void {
     const { host } = this;
     remotes.forEach((remote) => {
-      // fetchOptions passed to this call applies to each remote registered in
-      // it; an explicit per-remote fetchOptions on the remote object wins.
-      if (options?.fetchOptions && remote.fetchOptions === undefined) {
-        remote.fetchOptions = options.fetchOptions;
+      // Call-level fetchOptions act as defaults for every remote in this call;
+      // a remote's own fetchOptions are merged on top and win on conflict
+      // (headers are merged per-key, not replaced wholesale).
+      if (options?.fetchOptions) {
+        remote.fetchOptions = mergeFetchOptions(
+          options.fetchOptions,
+          remote.fetchOptions,
+        );
       }
       this.registerRemote(remote, host.options.remotes, {
         force: options?.force,
diff --git a/packages/sdk/src/blobLoad.ts b/packages/sdk/src/blobLoad.ts
index c9f8f8c7f12..be7054caec2 100644
--- a/packages/sdk/src/blobLoad.ts
+++ b/packages/sdk/src/blobLoad.ts
@@ -83,7 +83,7 @@ function isResponseLike(res: unknown): res is Response {
 }
 
 // Create a const copy of headers, to avoid the case when the original headers are mutated by fetcher.
-function toHeaderObject(
+export function toHeaderObject(
   headers: RequestInit['headers'],
 ): Record<string, string> {
   if (!headers) return {};

From 796aa05a408787c4be854db928f82308ed9c9b23 Mon Sep 17 00:00:00 2001
From: Shaoyu Meng <shaoyumeng@shaoyus-mbp-5.lan>
Date: Tue, 16 Jun 2026 19:44:03 -0700
Subject: [PATCH 18/34] docs(runtime-core): tidy comments in preload css fetch
 path

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../__tests__/preload-css-fetch-options.spec.ts           | 8 ++------
 packages/runtime-core/src/utils/preload.ts                | 2 +-
 2 files changed, 3 insertions(+), 7 deletions(-)

diff --git a/packages/runtime-core/__tests__/preload-css-fetch-options.spec.ts b/packages/runtime-core/__tests__/preload-css-fetch-options.spec.ts
index 48ae8224a76..fd2827a3881 100644
--- a/packages/runtime-core/__tests__/preload-css-fetch-options.spec.ts
+++ b/packages/runtime-core/__tests__/preload-css-fetch-options.spec.ts
@@ -62,12 +62,8 @@ describe('preloadAssets CSS with fetchOptions', () => {
       jsAssetsWithoutEntry: [],
       entryAssets: [],
     };
-    // jsdom env (see vitest.config.ts) provides DOM, so the no-fetchOptions
-    // else-branch (waitForLinkPreload -> createLink) runs cleanly without a
-    // swallowing .catch. createLink resolves on the <link> load event, which
-    // jsdom does not dispatch on its own, so we fire it (as a real browser
-    // would) to let the branch settle. A genuine crash before/during the
-    // branch would still reject and fail the test.
+    // We must fire the load event for the <link> created by createLink function,
+    // this mimics the browser behavior and let the branch settle.
     const observer = new MutationObserver((mutations) => {
       mutations.forEach((m) =>
         m.addedNodes.forEach((node) => {
diff --git a/packages/runtime-core/src/utils/preload.ts b/packages/runtime-core/src/utils/preload.ts
index 7119ee6ad42..bdaf43627f0 100644
--- a/packages/runtime-core/src/utils/preload.ts
+++ b/packages/runtime-core/src/utils/preload.ts
@@ -188,7 +188,7 @@ function waitForLinkPreload({
 
 // When the remote carries fetchOptions, CSS must be fetched WITH headers and
 // injected as a blob <link> — a native <link href> cannot carry headers, and a
-// rel=preload hint would 401. Mirrors loadCss in the loader PoC.
+// rel=preload hint would 401.
 function waitForCssFetch({
   host,
   remoteInfo,

From 2593a4de0fdf50c2428f2d9c22ea09e4aa181fa5 Mon Sep 17 00:00:00 2001
From: Shaoyu Meng <shaoyumeng@Shaoyus-MacBook-Pro-5.local>
Date: Tue, 16 Jun 2026 23:04:25 -0700
Subject: [PATCH 19/34] fix(runtime-core): forward fetchOptions to remoteEntry
 preload

The entry preload in preloadAssets used the snapshot-derived moduleInfo, which
does not carry the host remote's fetchOptions. The remoteEntry was therefore
preloaded unauthenticated and cached, so the later authenticated load was
skipped and no Authorization header reached the remoteEntry or its chunks.
Forward remoteInfo.fetchOptions to the entry preload (mirroring the css path).

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/runtime-core/src/utils/preload.ts | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/packages/runtime-core/src/utils/preload.ts b/packages/runtime-core/src/utils/preload.ts
index bdaf43627f0..7861998f835 100644
--- a/packages/runtime-core/src/utils/preload.ts
+++ b/packages/runtime-core/src/utils/preload.ts
@@ -298,11 +298,16 @@ export function preloadAssets(
   if (host.options.inBrowser) {
     entryAssets.forEach((asset) => {
       const { moduleInfo: entryRemoteInfo } = asset;
+      const entryRemoteInfoWithAuth =
+        // Respect fetchOptions added to entryRemoteInfo via generatePreloadAssetsPlugin.
+        !entryRemoteInfo.fetchOptions && remoteInfo.fetchOptions
+          ? { ...entryRemoteInfo, fetchOptions: remoteInfo.fetchOptions }
+          : entryRemoteInfo;
       results.push(
         waitForRemoteEntryPreload(
           host,
           remoteInfo,
-          entryRemoteInfo,
+          entryRemoteInfoWithAuth,
           createResourceContext(baseContext, 'remoteEntry'),
         ),
       );

From 220b94693d9f1298df72bc9aaab6a7d2bf6545ab Mon Sep 17 00:00:00 2001
From: Shaoyu Meng <shaoyumeng@shaoyus-mbp-5.lan>
Date: Wed, 17 Jun 2026 11:11:54 -0700
Subject: [PATCH 20/34] docs(runtime): document registerRemotes fetchOptions;
 remove scratch docs

Document the per-remote/call-level fetchOptions option on registerRemotes in
the runtime API reference (en + zh), and remove the internal superpowers
plan/spec scratch files under docs/.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../docs/en/guide/runtime/runtime-api.mdx     |  41 +-
 .../docs/zh/guide/runtime/runtime-api.mdx     |  41 +-
 ...6-06-16-fetchoptions-esm-remote-loading.md | 895 ------------------
 ...-fetchoptions-esm-remote-loading-design.md | 216 -----
 4 files changed, 80 insertions(+), 1113 deletions(-)
 delete mode 100644 docs/superpowers/plans/2026-06-16-fetchoptions-esm-remote-loading.md
 delete mode 100644 docs/superpowers/specs/2026-06-16-fetchoptions-esm-remote-loading-design.md

diff --git a/apps/website-new/docs/en/guide/runtime/runtime-api.mdx b/apps/website-new/docs/en/guide/runtime/runtime-api.mdx
index 0ebd522f3c6..57dfee66eb3 100644
--- a/apps/website-new/docs/en/guide/runtime/runtime-api.mdx
+++ b/apps/website-new/docs/en/guide/runtime/runtime-api.mdx
@@ -275,7 +275,10 @@ if (targetInstance) {
 <Collapse>
 
 ```typescript
-function registerRemotes(remotes: Remote[], options?: { force?: boolean }) {}
+function registerRemotes(
+  remotes: Remote[],
+  options?: { force?: boolean; fetchOptions?: RequestInit },
+) {}
 
 type Remote = (RemoteWithEntry | RemoteWithVersion) & RemoteInfoCommon;
 
@@ -284,6 +287,8 @@ interface RemoteInfoCommon {
   shareScope?: string;
   type?: RemoteEntryType;
   entryGlobalName?: string;
+  // Custom request options (e.g. `headers`) used when loading this remote.
+  fetchOptions?: RequestInit;
 }
 
 interface RemoteWithEntry {
@@ -305,6 +310,40 @@ When `force: true` is set, the newly registered modules will overwrite already-r
 
 :::
 
+### Loading remotes with custom headers (`fetchOptions`)
+
+`fetchOptions` (a standard [`RequestInit`](https://developer.mozilla.org/en-US/docs/Web/API/RequestInit)) attaches custom HTTP options — most commonly `headers` such as `Authorization` — to the requests used to load a remote. It can be set per remote, or at the call level where it applies to every remote in that call. A remote's own `fetchOptions` is merged on top of the call-level one, and its `headers` win on conflict.
+
+This is supported for **`module` / `esm`** remotes: their manifest, remote entry, split chunks, shared dependencies, and manifest-declared CSS are loaded through a `fetch` + blob loader so the headers reach every asset request. Remotes without `fetchOptions` (and non-ESM remotes) are loaded as before — note that `<script>` / `<link>`-based loading cannot carry custom headers.
+
+```ts
+import { createInstance } from '@module-federation/enhanced/runtime';
+
+const mf = createInstance({ name: 'mf_host', remotes: [] });
+
+// Per remote
+mf.registerRemotes([
+  {
+    name: 'sub1',
+    entry: 'https://localhost:2001/mf-manifest.json',
+    type: 'module',
+    fetchOptions: { headers: { Authorization: `Bearer ${token}` } },
+  },
+]);
+
+// Call level — applies to every remote in this call
+mf.registerRemotes(
+  [{ name: 'sub2', entry: 'https://localhost:2002/mf-manifest.json', type: 'module' }],
+  { fetchOptions: { headers: { Authorization: `Bearer ${token}` } } },
+);
+```
+
+:::info
+
+Native preload hints (`<link rel="modulepreload">` / `<link rel="preload">`) cannot carry headers, so they may fail on an authenticated origin; the actual module loads still go through the authenticated `fetch` loader. Authenticated CSS is injected directly and does not emit the `createLink` hook, so plugin-added `nonce`/SRI attributes are not applied to it.
+
+:::
+
 <Tabs>
   <Tab label="Build Plugin (Use build plugin)">
   ```tsx
diff --git a/apps/website-new/docs/zh/guide/runtime/runtime-api.mdx b/apps/website-new/docs/zh/guide/runtime/runtime-api.mdx
index 178ad9b4f4b..e8854eaf053 100644
--- a/apps/website-new/docs/zh/guide/runtime/runtime-api.mdx
+++ b/apps/website-new/docs/zh/guide/runtime/runtime-api.mdx
@@ -275,7 +275,10 @@ if (targetInstance) {
 <Collapse>
 
 ```typescript
-function registerRemotes(remotes: Remote[], options?: { force?: boolean }) {}
+function registerRemotes(
+  remotes: Remote[],
+  options?: { force?: boolean; fetchOptions?: RequestInit },
+) {}
 
 type Remote = (RemoteWithEntry | RemoteWithVersion) & RemoteInfoCommon;
 
@@ -284,6 +287,8 @@ interface RemoteInfoCommon {
   shareScope?: string;
   type?: RemoteEntryType;
   entryGlobalName?: string;
+  // 加载该 remote 时使用的自定义请求配置（如 `headers`）。
+  fetchOptions?: RequestInit;
 }
 
 interface RemoteWithEntry {
@@ -305,6 +310,40 @@ interface RemoteWithVersion {
 
 :::
 
+### 使用自定义请求头加载 remote（`fetchOptions`）
+
+`fetchOptions`（标准的 [`RequestInit`](https://developer.mozilla.org/zh-CN/docs/Web/API/RequestInit)）用于为加载 remote 的请求附加自定义 HTTP 配置——最常见的是 `Authorization` 等 `headers`。它既可以设置在单个 remote 上，也可以设置在调用级别（对本次调用的所有 remote 生效）。单个 remote 自身的 `fetchOptions` 会与调用级别的合并，且在 `headers` 冲突时以前者为准。
+
+该能力适用于 **`module` / `esm`** 类型的 remote：其 manifest、remote entry、分包 chunk、共享依赖以及 manifest 中声明的 CSS，都会通过 `fetch` + blob 加载器加载，从而让请求头能够作用到每一个资源请求上。未设置 `fetchOptions` 的 remote（以及非 ESM 的 remote）按原有方式加载——注意基于 `<script>` / `<link>` 的加载方式无法携带自定义请求头。
+
+```ts
+import { createInstance } from '@module-federation/enhanced/runtime';
+
+const mf = createInstance({ name: 'mf_host', remotes: [] });
+
+// 单个 remote
+mf.registerRemotes([
+  {
+    name: 'sub1',
+    entry: 'https://localhost:2001/mf-manifest.json',
+    type: 'module',
+    fetchOptions: { headers: { Authorization: `Bearer ${token}` } },
+  },
+]);
+
+// 调用级别——对本次调用的所有 remote 生效
+mf.registerRemotes(
+  [{ name: 'sub2', entry: 'https://localhost:2002/mf-manifest.json', type: 'module' }],
+  { fetchOptions: { headers: { Authorization: `Bearer ${token}` } } },
+);
+```
+
+:::info
+
+原生的预加载提示（`<link rel="modulepreload">` / `<link rel="preload">`）无法携带请求头，因此在需要鉴权的源上可能会失败；但真正的模块加载仍会走带鉴权的 `fetch` 加载器。带鉴权的 CSS 是直接注入的，不会触发 `createLink` 钩子，因此插件添加的 `nonce`/SRI 属性不会作用于这类 CSS。
+
+:::
+
 <Tabs>
   <Tab label="Build Plugin（使用构建插件）">
   ```tsx
diff --git a/docs/superpowers/plans/2026-06-16-fetchoptions-esm-remote-loading.md b/docs/superpowers/plans/2026-06-16-fetchoptions-esm-remote-loading.md
deleted file mode 100644
index 95e19e1f474..00000000000
--- a/docs/superpowers/plans/2026-06-16-fetchoptions-esm-remote-loading.md
+++ /dev/null
@@ -1,895 +0,0 @@
-# fetchOptions ESM Remote Loading — Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Let `registerRemotes(remotes, { fetchOptions })` attach custom HTTP headers to every asset of an ESM remote (manifest, entry, chunks, shared deps, manifest CSS) via a fetch + blob import-rewriting loader, with zero change to non-ESM / no-`fetchOptions` paths.
-
-**Architecture:** A self-contained fetch+blob loader in `@module-federation/sdk` (hardened port of the PoC in `js-module-import/index.html`) fetches each module's source with headers, rewrites its static/dynamic imports to recursively-loaded blob URLs, and imports the blob. `runtime-core` threads a per-remote `fetchOptions` from the API down to `RemoteInfo`, routes ESM entries with `fetchOptions` to the new loader, authenticates the manifest fetch, and routes manifest CSS through the loader. Non-ESM remotes never reach the new branch and fall back to today's loaders.
-
-**Tech Stack:** TypeScript monorepo, pnpm, Jest (jsdom env, `@swc/jest`), packages `sdk` and `runtime-core`.
-
----
-
-## Background the implementer needs
-
-- The PoC is `js-module-import/index.html` (read it first). Its comments are intentionally carried over into the ported code.
-- `sdk` does **not** import from `runtime-core` (one-way dependency: `runtime-core` → `sdk`). The sdk loader therefore takes plain primitives (`entry`, `fetchOptions`, an optional `customFetch`) — never `RemoteInfo` or `loaderHook`.
-- Why a blob loader at all: `<script src>` and native `import()` cannot carry headers, and the runtime does not intercept bundler chunk loads. Rewriting the whole ESM graph to blob imports is the only way headers reach chunks/shared deps. This only works for ESM output, hence the `module`/`esm` gate.
-- sdk tests live in `packages/sdk/__tests__/*.spec.ts`, run with jsdom. Run a single sdk test file with:
-  `pnpm --filter @module-federation/sdk exec jest --config jest.config.cjs <path> -t "<name>"`
-- runtime-core tests: `pnpm --filter @module-federation/runtime-core test` (check the package's own jest config for single-file invocation).
-
-## File structure
-
-- **Create** `packages/sdk/src/blobLoad.ts` — the fetch+blob loader (pure rewriter + `resolveSpec` + `fetchText` + `loadModule` + `__mfDyn` shim + `loadEsmEntryWithFetch` + `loadCssWithFetch`). One responsibility: header-authenticated ESM blob loading.
-- **Create** `packages/sdk/__tests__/blobLoad.spec.ts` — unit tests for the pure pieces.
-- **Modify** `packages/sdk/src/index.ts` — export the new module.
-- **Modify** `packages/runtime-core/src/type/config.ts` — add `fetchOptions` to `RemoteInfoCommon` and `RemoteInfo`.
-- **Modify** `packages/runtime-core/src/remote/index.ts` — `registerRemotes` options + per-remote stamping.
-- **Modify** `packages/runtime-core/src/core.ts` — public `registerRemotes` signature.
-- **Modify** `packages/runtime-core/src/utils/load.ts` — `loadEntryDom` routing gate + `customFetch` builder.
-- **Modify** `packages/runtime-core/src/plugins/snapshot/SnapshotHandler.ts` — authenticate manifest fetch.
-- **Modify** `packages/runtime-core/src/utils/preload.ts` — route manifest CSS through the loader when `fetchOptions` present.
-
----
-
-## Task 1: Pure rewriter + `resolveSpec` in the sdk loader
-
-**Files:**
-- Create: `packages/sdk/src/blobLoad.ts`
-- Test: `packages/sdk/__tests__/blobLoad.spec.ts`
-
-- [ ] **Step 1: Write the failing test**
-
-```ts
-// packages/sdk/__tests__/blobLoad.spec.ts
-import { resolveSpec, rewriteModuleCode } from '../src/blobLoad';
-
-describe('resolveSpec', () => {
-  it('returns absolute urls untouched', () => {
-    expect(resolveSpec('https://x.com/a.js', 'https://b.com/')).toBe('https://x.com/a.js');
-    expect(resolveSpec('blob:abc', 'https://b.com/')).toBe('blob:abc');
-    expect(resolveSpec('data:text/js,1', 'https://b.com/')).toBe('data:text/js,1');
-  });
-
-  it('resolves relative and absolute-path specifiers against the base', () => {
-    expect(resolveSpec('./dep.js', 'https://b.com/app/entry.js')).toBe('https://b.com/app/dep.js');
-    expect(resolveSpec('/root.js', 'https://b.com/app/entry.js')).toBe('https://b.com/root.js');
-  });
-
-  it('throws on bare specifiers', () => {
-    expect(() => resolveSpec('react', 'https://b.com/')).toThrow('bare specifier');
-  });
-});
-
-describe('rewriteModuleCode', () => {
-  const url = 'https://b.com/app/entry.js';
-
-  it('pins import.meta.url to the module url', () => {
-    const { code } = rewriteModuleCode('const u = import.meta.url;', url);
-    expect(code).toBe(`const u = ${JSON.stringify(url)};`);
-  });
-
-  it('routes dynamic import() through __mfDyn with the base url', () => {
-    const { code } = rewriteModuleCode('const m = import("./x.js");', url);
-    expect(code).toBe(`const m = __mfDyn(${JSON.stringify(url)},"./x.js");`);
-  });
-
-  it('collects static relative/absolute deps and leaves bare imports alone', () => {
-    const src = `import a from "./a.js";\nexport { b } from "/b.js";\nimport c from "react";`;
-    const { deps } = rewriteModuleCode(src, url);
-    expect(deps.map((d) => d.spec).sort()).toEqual(['./a.js', '/b.js']);
-    expect(deps.find((d) => d.spec === './a.js')!.depUrl).toBe('https://b.com/app/a.js');
-  });
-});
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `pnpm --filter @module-federation/sdk exec jest --config jest.config.cjs __tests__/blobLoad.spec.ts`
-Expected: FAIL — cannot find module `../src/blobLoad`.
-
-- [ ] **Step 3: Write minimal implementation**
-
-```ts
-// packages/sdk/src/blobLoad.ts
-
-// Hardened port of the fetch + blob import-rewriting loader PoC
-// (js-module-import/index.html). Comments are retained from the PoC where the
-// logic is carried over verbatim.
-
-export interface BlobDep {
-  original: string;
-  spec: string;
-  quote: string;
-  depUrl: string;
-}
-
-// Resolve a specifier (relative, absolute-path, or already-absolute-url)
-// against a base url to a concrete fetchable url. The MF runtime resolves
-// shared deps to relative loadShare asset urls, so bare specifiers never reach
-// the loader; anything bare is unexpected and throws.
-export function resolveSpec(spec: string, base: string): string {
-  if (/^(blob:|https?:|data:)/.test(spec)) return spec;
-  if (spec.startsWith('.') || spec.startsWith('/')) return new URL(spec, base).href;
-  throw new Error(`[loader] cannot resolve bare specifier "${spec}" (from ${base})`);
-}
-
-// Rewrite a module's source: pin import.meta.url, route dynamic imports through
-// __mfDyn, and collect static relative/absolute specifiers (to be replaced with
-// recursively-loaded blob urls by the caller).
-export function rewriteModuleCode(
-  code: string,
-  url: string,
-): { code: string; deps: BlobDep[] } {
-  // import.meta.url -> the module's real url.
-  // In this case, modules with publicPath:"auto" can derive paths from it.
-  code = code.replace(/\bimport\.meta\.url\b/g, JSON.stringify(url));
-
-  // Dynamic import(...) -> __mfDyn("<url>", ...).
-  code = code.replace(/(?<![.\w$])import\s*\(/g, `__mfDyn(${JSON.stringify(url)},`);
-
-  // Static `import * from ...` and `import ...` -> recursively-loaded blob urls.
-  const specRe = /(?<![.\w$])(from|import)\s*(['"])([^'"]+)\2/g;
-  const deps: BlobDep[] = [];
-  for (const m of code.matchAll(specRe)) {
-    const spec = m[3];
-    if (spec.startsWith('.') || spec.startsWith('/')) {
-      deps.push({ original: m[0], spec, quote: m[2], depUrl: resolveSpec(spec, url) });
-    }
-  }
-  return { code, deps };
-}
-```
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `pnpm --filter @module-federation/sdk exec jest --config jest.config.cjs __tests__/blobLoad.spec.ts`
-Expected: PASS (all `resolveSpec` and `rewriteModuleCode` tests green).
-
-- [ ] **Step 5: Commit**
-
-```bash
-git add packages/sdk/src/blobLoad.ts packages/sdk/__tests__/blobLoad.spec.ts
-git commit -m "feat(sdk): add blob-loader import rewriter and resolveSpec"
-```
-
----
-
-## Task 2: `fetchText`, `loadModule`, `__mfDyn`, and the public loader functions
-
-**Files:**
-- Modify: `packages/sdk/src/blobLoad.ts`
-- Modify: `packages/sdk/src/index.ts`
-- Test: `packages/sdk/__tests__/blobLoad.spec.ts`
-
-- [ ] **Step 1: Write the failing test**
-
-Append to `packages/sdk/__tests__/blobLoad.spec.ts`:
-
-```ts
-import { fetchText, loadModule, loadEsmEntryWithFetch } from '../src/blobLoad';
-
-describe('fetchText', () => {
-  beforeEach(() => {
-    (global as any).fetch = jest.fn();
-  });
-
-  it('merges fetchOptions headers and returns response text', async () => {
-    (global.fetch as jest.Mock).mockResolvedValue({
-      ok: true,
-      text: () => Promise.resolve('CODE'),
-    });
-    const text = await fetchText('https://b.com/e.js', {
-      fetchOptions: { headers: { Authorization: 'Bearer t' } },
-    });
-    expect(text).toBe('CODE');
-    const init = (global.fetch as jest.Mock).mock.calls[0][1];
-    expect(init.headers).toEqual({ Authorization: 'Bearer t' });
-  });
-
-  it('prefers customFetch when it returns a Response', async () => {
-    const customFetch = jest.fn().mockResolvedValue({ ok: true, text: () => Promise.resolve('HOOKED') } as any);
-    // jsdom Response check: stub instanceof via a real Response-like guard is awkward,
-    // so the implementation treats any object with ok+text as usable when customFetch returns it.
-    const text = await fetchText('https://b.com/e.js', { customFetch });
-    expect(customFetch).toHaveBeenCalled();
-    expect(text).toBe('HOOKED');
-    expect((global.fetch as jest.Mock)).not.toHaveBeenCalled();
-  });
-
-  it('throws a descriptive error on non-ok responses', async () => {
-    (global.fetch as jest.Mock).mockResolvedValue({ ok: false, status: 401, statusText: 'Unauthorized', text: () => Promise.resolve('') });
-    await expect(fetchText('https://b.com/e.js', {})).rejects.toThrow('BlobLoaderNetworkError: 401');
-  });
-});
-
-describe('loadModule', () => {
-  beforeEach(() => {
-    (global as any).fetch = jest.fn();
-    (global.URL as any).createObjectURL = jest.fn((blob: Blob) => `blob:${(blob as any).__id || 'x'}`);
-    loadModule.clearCache();
-  });
-
-  it('rewrites a static dep to a recursively-loaded blob url and caches by url', async () => {
-    const files: Record<string, string> = {
-      'https://b.com/entry.js': `import dep from "./dep.js";`,
-      'https://b.com/dep.js': `export default 1;`,
-    };
-    (global.fetch as jest.Mock).mockImplementation((url: string) =>
-      Promise.resolve({ ok: true, text: () => Promise.resolve(files[url]) }),
-    );
-    const blobUrl = await loadModule('https://b.com/entry.js', {});
-    expect(blobUrl).toMatch(/^blob:/);
-    // dep fetched exactly once; entry fetched once
-    expect((global.fetch as jest.Mock).mock.calls.map((c) => c[0]).sort()).toEqual([
-      'https://b.com/dep.js',
-      'https://b.com/entry.js',
-    ]);
-    // second call for same url is served from cache (no extra fetch)
-    await loadModule('https://b.com/entry.js', {});
-    expect((global.fetch as jest.Mock).mock.calls.length).toBe(2);
-  });
-});
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `pnpm --filter @module-federation/sdk exec jest --config jest.config.cjs __tests__/blobLoad.spec.ts`
-Expected: FAIL — `fetchText` / `loadModule` not exported (and `loadModule.clearCache` missing).
-
-- [ ] **Step 3: Write minimal implementation**
-
-Append to `packages/sdk/src/blobLoad.ts`:
-
-```ts
-export type BlobFetcher = (
-  url: string,
-  init: RequestInit,
-) => Promise<Response | void | false> | Response | void | false;
-
-export interface BlobLoadContext {
-  fetchOptions?: RequestInit;
-  // Optional custom fetch (e.g. routed through the runtime loaderHook.fetch so
-  // existing fetch-hook plugins still compose). Falls back to native fetch.
-  customFetch?: BlobFetcher;
-}
-
-// absolute url -> Promise<blob url>
-const cache = new Map<string, Promise<string>>();
-// absolute url -> the context it was loaded with, so __mfDyn can reuse the
-// right headers for runtime dynamic imports of that module's chunks.
-const contexts = new Map<string, BlobLoadContext>();
-let dynImportInstalled = false;
-
-function isResponseLike(res: unknown): res is Response {
-  return (
-    !!res &&
-    typeof res === 'object' &&
-    typeof (res as Response).text === 'function' &&
-    'ok' in (res as Response)
-  );
-}
-
-export async function fetchText(url: string, ctx: BlobLoadContext): Promise<string> {
-  const { headers, ...rest } = ctx.fetchOptions || {};
-  const init: RequestInit = { ...rest, headers: { ...(headers as Record<string, string>) } };
-  let res: Response | void | false;
-  if (ctx.customFetch) {
-    res = await ctx.customFetch(url, init);
-  }
-  if (!isResponseLike(res)) {
-    res = await fetch(url, init);
-  }
-  if (!res.ok) {
-    throw new Error(`BlobLoaderNetworkError: ${res.status} ${res.statusText} for ${url}`);
-  }
-  return res.text();
-}
-
-// Fetch a module with headers, rewrite its imports.
-// Dynamic imports are handled lazily at runtime via __mfDyn,
-// Static relative imports are pre-loaded recursively.
-export function loadModule(url: string, ctx: BlobLoadContext): Promise<string> {
-  if (cache.has(url)) return cache.get(url)!;
-  contexts.set(url, ctx);
-
-  const promise = (async () => {
-    const raw = await fetchText(url, ctx);
-    const { code: rewritten, deps } = rewriteModuleCode(raw, url);
-    let code = rewritten;
-    const blobUrls = await Promise.all(deps.map((d) => loadModule(d.depUrl, ctx)));
-    deps.forEach((d, i) => {
-      const replaced = d.original.replace(
-        `${d.quote}${d.spec}${d.quote}`,
-        `${d.quote}${blobUrls[i]}${d.quote}`,
-      );
-      code = code.split(d.original).join(replaced);
-    });
-    return URL.createObjectURL(new Blob([code], { type: 'application/javascript' }));
-  })();
-
-  cache.set(url, promise);
-  return promise;
-}
-
-// Test seam: reset the module/context caches between cases.
-loadModule.clearCache = () => {
-  cache.clear();
-  contexts.clear();
-};
-
-function installDynImportShim(): void {
-  if (dynImportInstalled) return;
-  dynImportInstalled = true;
-
-  // Runtime dynamic-import shim: resolve url + fetch from cache or with headers + import as blob.
-  (globalThis as Record<string, unknown>).__mfDyn = async (base: string, spec: string) => {
-    const resolved = resolveSpec(spec, base);
-    if (/^(blob:|data:)/.test(resolved)) {
-      return import(/* webpackIgnore: true */ /* @vite-ignore */ resolved);
-    }
-    const ctx = contexts.get(base) || {};
-    return import(/* webpackIgnore: true */ /* @vite-ignore */ await loadModule(resolved, ctx));
-  };
-
-  // The vite preload helper creates native <link> preloads (no auth header) as a
-  // perf hint; let those 401 quietly instead of throwing — real loads go via __mfDyn.
-  if (typeof window !== 'undefined') {
-    window.addEventListener('vite:preloadError', (e) => e.preventDefault());
-  }
-}
-
-export async function loadEsmEntryWithFetch({
-  entry,
-  fetchOptions,
-  customFetch,
-}: {
-  entry: string;
-  fetchOptions?: RequestInit;
-  customFetch?: BlobFetcher;
-}): Promise<Record<string, unknown>> {
-  installDynImportShim();
-  const blobUrl = await loadModule(entry, { fetchOptions, customFetch });
-  return import(/* webpackIgnore: true */ /* @vite-ignore */ blobUrl);
-}
-
-export async function loadCssWithFetch({
-  href,
-  fetchOptions,
-  customFetch,
-}: {
-  href: string;
-  fetchOptions?: RequestInit;
-  customFetch?: BlobFetcher;
-}): Promise<void> {
-  const text = await fetchText(href, { fetchOptions, customFetch });
-  const blob = URL.createObjectURL(new Blob([text], { type: 'text/css' }));
-  const link = document.createElement('link');
-  link.rel = 'stylesheet';
-  link.href = blob;
-  document.head.appendChild(link);
-}
-```
-
-Add the `clearCache` member to the exported type by declaring it on the function. If TypeScript complains about assigning `clearCache` to a function, change the declaration to:
-
-```ts
-export const loadModule: ((url: string, ctx: BlobLoadContext) => Promise<string>) & {
-  clearCache: () => void;
-} = Object.assign(loadModuleImpl, { clearCache: () => { cache.clear(); contexts.clear(); } });
-```
-
-and rename the function body to `function loadModuleImpl(...)`. (Recursive calls inside the body must call `loadModule`, which is fine since it is in scope.)
-
-- [ ] **Step 4: Run test to verify it passes**
-
-Run: `pnpm --filter @module-federation/sdk exec jest --config jest.config.cjs __tests__/blobLoad.spec.ts`
-Expected: PASS.
-
-- [ ] **Step 5: Export from the sdk barrel**
-
-Modify `packages/sdk/src/index.ts` — add after the `export * from './dom';` line:
-
-```ts
-export * from './blobLoad';
-```
-
-- [ ] **Step 6: Type-check the sdk package**
-
-Run: `pnpm --filter @module-federation/sdk exec tsc -p tsconfig.lib.json --noEmit`
-Expected: no errors.
-
-- [ ] **Step 7: Commit**
-
-```bash
-git add packages/sdk/src/blobLoad.ts packages/sdk/src/index.ts packages/sdk/__tests__/blobLoad.spec.ts
-git commit -m "feat(sdk): add fetch+blob ESM loader (loadEsmEntryWithFetch, loadCssWithFetch)"
-```
-
----
-
-## Task 3: Thread `fetchOptions` through types and `registerRemotes`
-
-**Files:**
-- Modify: `packages/runtime-core/src/type/config.ts:15-43`
-- Modify: `packages/runtime-core/src/remote/index.ts:502-509`
-- Modify: `packages/runtime-core/src/core.ts:458-460`
-
-- [ ] **Step 1: Add `fetchOptions` to the types**
-
-In `packages/runtime-core/src/type/config.ts`, add `fetchOptions?: RequestInit;` to `RemoteInfoCommon` (currently lines 15-20):
-
-```ts
-export interface RemoteInfoCommon {
-  alias?: string;
-  shareScope?: string | string[];
-  type?: RemoteEntryType;
-  entryGlobalName?: string;
-  fetchOptions?: RequestInit;
-}
-```
-
-And to `RemoteInfo` (currently lines 34-43):
-
-```ts
-export interface RemoteInfo {
-  alias?: string;
-  name: string;
-  version?: string;
-  buildVersion?: string;
-  entry: string;
-  type: RemoteEntryType;
-  entryGlobalName: string;
-  shareScope: string | string[];
-  fetchOptions?: RequestInit;
-}
-```
-
-`getRemoteInfo` (`utils/load.ts:393`) already spreads `...remote`, so `fetchOptions` flows onto `RemoteInfo` automatically — no change needed there.
-
-- [ ] **Step 2: Update `registerRemotes` to accept and stamp `fetchOptions`**
-
-In `packages/runtime-core/src/remote/index.ts`, replace the `registerRemotes` method (lines 502-509):
-
-```ts
-  registerRemotes(
-    remotes: Remote[],
-    options?: { force?: boolean; fetchOptions?: RequestInit },
-  ): void {
-    const { host } = this;
-    remotes.forEach((remote) => {
-      // fetchOptions passed to this call applies to each remote registered in
-      // it; an explicit per-remote fetchOptions on the remote object wins.
-      if (options?.fetchOptions && remote.fetchOptions === undefined) {
-        remote.fetchOptions = options.fetchOptions;
-      }
-      this.registerRemote(remote, host.options.remotes, {
-        force: options?.force,
-      });
-    });
-  }
-```
-
-- [ ] **Step 3: Update the public `registerRemotes` signature**
-
-In `packages/runtime-core/src/core.ts`, replace lines 458-460:
-
-```ts
-  registerRemotes(
-    remotes: Remote[],
-    options?: { force?: boolean; fetchOptions?: RequestInit },
-  ): void {
-    return this.remoteHandler.registerRemotes(remotes, options);
-  }
-```
-
-(The public wrapper in `packages/runtime/src/index.ts:94` uses `Parameters<ModuleFederation['registerRemotes']>`, so it updates automatically.)
-
-- [ ] **Step 4: Write the test**
-
-Create `packages/runtime-core/src/remote/__tests__/register-fetch-options.spec.ts` (match the package's existing test location/extension — if runtime-core uses a top-level `__tests__`, place it there instead):
-
-```ts
-import { ModuleFederation } from '../../core';
-
-describe('registerRemotes fetchOptions', () => {
-  it('stamps call-level fetchOptions onto each remote that lacks its own', () => {
-    const mf = new ModuleFederation({ name: 'host', remotes: [] });
-    const fetchOptions = { headers: { Authorization: 'Bearer t' } };
-    const r1: any = { name: 'a', entry: 'http://x/a.json' };
-    const r2: any = { name: 'b', entry: 'http://x/b.json', fetchOptions: { headers: { 'X-B': '1' } } };
-    mf.registerRemotes([r1, r2], { fetchOptions });
-    const stored = (mf as any).options.remotes;
-    expect(stored.find((r: any) => r.name === 'a').fetchOptions).toBe(fetchOptions);
-    expect(stored.find((r: any) => r.name === 'b').fetchOptions).toEqual({ headers: { 'X-B': '1' } });
-  });
-});
-```
-
-- [ ] **Step 5: Run test to verify it passes**
-
-Run: `pnpm --filter @module-federation/runtime-core test` (scope to the new file if the package's jest config supports a path argument).
-Expected: PASS.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add packages/runtime-core/src/type/config.ts packages/runtime-core/src/remote/index.ts packages/runtime-core/src/core.ts packages/runtime-core/src/remote/__tests__/register-fetch-options.spec.ts
-git commit -m "feat(runtime-core): thread per-remote fetchOptions through registerRemotes"
-```
-
----
-
-## Task 4: Route ESM entries with `fetchOptions` to the blob loader
-
-**Files:**
-- Modify: `packages/runtime-core/src/utils/load.ts:1-6` (import) and `:189-220` (`loadEntryDom`)
-- Test: `packages/runtime-core/src/utils/__tests__/load-entry-fetch-options.spec.ts`
-
-- [ ] **Step 1: Write the failing test**
-
-```ts
-// packages/runtime-core/src/utils/__tests__/load-entry-fetch-options.spec.ts
-jest.mock('@module-federation/sdk', () => {
-  const actual = jest.requireActual('@module-federation/sdk');
-  return { ...actual, loadEsmEntryWithFetch: jest.fn().mockResolvedValue({ ok: 1 }) };
-});
-
-import { loadEsmEntryWithFetch } from '@module-federation/sdk';
-import { __loadEntryDomForTest } from '../load';
-
-describe('loadEntryDom ESM fetchOptions gate', () => {
-  const loaderHook: any = { lifecycle: { fetch: { emit: jest.fn() } } };
-
-  it('uses the blob loader for module remotes carrying fetchOptions', async () => {
-    const remoteInfo: any = {
-      name: 'a', entry: 'http://x/e.js', type: 'module', entryGlobalName: 'a',
-      shareScope: 'default', fetchOptions: { headers: { Authorization: 'Bearer t' } },
-    };
-    await __loadEntryDomForTest({ remoteInfo, loaderHook });
-    expect(loadEsmEntryWithFetch).toHaveBeenCalledWith(
-      expect.objectContaining({ entry: 'http://x/e.js', fetchOptions: remoteInfo.fetchOptions }),
-    );
-  });
-});
-```
-
-If `loadEntryDom` is not exported, add a thin test-only export at the bottom of `load.ts`:
-
-```ts
-export const __loadEntryDomForTest = loadEntryDom;
-```
-
-- [ ] **Step 2: Run test to verify it fails**
-
-Run: `pnpm --filter @module-federation/runtime-core test` (scoped to the new file).
-Expected: FAIL — blob loader not invoked (still calls `loadEsmEntry`), or `__loadEntryDomForTest` missing.
-
-- [ ] **Step 3: Add the import**
-
-In `packages/runtime-core/src/utils/load.ts`, extend the `@module-federation/sdk` import (lines 1-6):
-
-```ts
-import {
-  loadScript,
-  loadScriptNode,
-  composeKeyWithSeparator,
-  isBrowserEnvValue,
-  loadEsmEntryWithFetch,
-} from '@module-federation/sdk';
-```
-
-- [ ] **Step 4: Add the routing gate**
-
-In `loadEntryDom` (lines 202-219), replace the `esm`/`module` case so it routes to the blob loader when `fetchOptions` is present:
-
-```ts
-  const { entry, entryGlobalName: globalName, name, type } = remoteInfo;
-  switch (type) {
-    case 'esm':
-    case 'module':
-      return remoteInfo.fetchOptions
-        ? loadEsmEntryWithFetch({
-            entry,
-            fetchOptions: remoteInfo.fetchOptions,
-            // Route the loader's fetches through the runtime fetch hook so
-            // existing fetch-hook plugins still compose; merged headers are
-            // applied inside the sdk loader, native fetch is the fallback.
-            customFetch: (url, init) =>
-              loaderHook.lifecycle.fetch.emit(url, init, remoteInfo),
-          })
-        : loadEsmEntry({ entry, remoteEntryExports });
-    case 'system':
-      return loadSystemJsEntry({ entry, remoteEntryExports });
-    default:
-      return loadEntryScript({
-        entry,
-        globalName,
-        name,
-        remoteInfo,
-        loaderHook,
-        getEntryUrl,
-        resourceContext,
-      });
-  }
-```
-
-Add at the end of `load.ts`:
-
-```ts
-export const __loadEntryDomForTest = loadEntryDom;
-```
-
-- [ ] **Step 5: Run test to verify it passes**
-
-Run: `pnpm --filter @module-federation/runtime-core test` (scoped to the new file).
-Expected: PASS.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add packages/runtime-core/src/utils/load.ts packages/runtime-core/src/utils/__tests__/load-entry-fetch-options.spec.ts
-git commit -m "feat(runtime-core): route ESM remotes with fetchOptions to blob loader"
-```
-
----
-
-## Task 5: Authenticate the manifest fetch
-
-**Files:**
-- Modify: `packages/runtime-core/src/plugins/snapshot/SnapshotHandler.ts:306-321`
-- Test: extend an existing SnapshotHandler test or add `packages/runtime-core/src/plugins/snapshot/__tests__/manifest-fetch-options.spec.ts`
-
-- [ ] **Step 1: Apply the change**
-
-In `getManifestJson` (`SnapshotHandler.ts`), `remoteInfo` is already in scope (built at line 300 via `getRemoteInfo(moduleInfo)`). Replace the `{}` request options at lines 307-320:
-
-```ts
-        let res = await this.loaderHook.lifecycle.fetch.emit(
-          manifestUrl,
-          remoteInfo.fetchOptions ?? {},
-          remoteInfo,
-          resourceOptions
-            ? {
-                ...resourceOptions,
-                url: manifestUrl,
-                resourceType: 'manifest',
-              }
-            : undefined,
-        );
-        if (!res || !(res instanceof Response)) {
-          res = await fetch(manifestUrl, remoteInfo.fetchOptions ?? {});
-        }
-```
-
-- [ ] **Step 2: Write the test**
-
-```ts
-// packages/runtime-core/src/plugins/snapshot/__tests__/manifest-fetch-options.spec.ts
-import { ModuleFederation } from '../../../core';
-
-describe('manifest fetch carries fetchOptions', () => {
-  it('passes the remote fetchOptions to the fetch hook and native fallback', async () => {
-    const fetchOptions = { headers: { Authorization: 'Bearer t' } };
-    const manifest = {
-      id: 'sub', name: 'sub',
-      metaData: {
-        name: 'sub', type: 'app', buildInfo: { buildVersion: '1' }, globalName: 'sub',
-        remoteEntry: { name: 'remoteEntry.js', path: '', type: 'module' },
-        types: { path: '', name: '' }, buildVersion: '1', publicPath: 'http://x/',
-        ssrPublicPath: '', remotes: [], shared: [],
-      },
-      shared: [], remotes: [], exposes: [],
-    };
-    const fetchMock = jest.fn().mockResolvedValue(
-      new Response(JSON.stringify(manifest), { status: 200, headers: { 'content-type': 'application/json' } }),
-    );
-    (global as any).fetch = fetchMock;
-
-    const mf = new ModuleFederation({ name: 'host', remotes: [] });
-    mf.registerRemotes([{ name: 'sub', entry: 'http://x/mf-manifest.json' } as any], { fetchOptions });
-
-    // Trigger manifest load (errors past the fetch are fine for this assertion).
-    await mf.loadRemote('sub/thing').catch(() => undefined);
-
-    expect(fetchMock).toHaveBeenCalledWith('http://x/mf-manifest.json', fetchOptions);
-  });
-});
-```
-
-- [ ] **Step 3: Run test to verify it passes**
-
-Run: `pnpm --filter @module-federation/runtime-core test` (scoped to the new file).
-Expected: PASS — the native `fetch` fallback receives `fetchOptions`. (If a registered fetch-hook plugin short-circuits, assert on the hook emit args instead.)
-
-- [ ] **Step 4: Commit**
-
-```bash
-git add packages/runtime-core/src/plugins/snapshot/SnapshotHandler.ts packages/runtime-core/src/plugins/snapshot/__tests__/manifest-fetch-options.spec.ts
-git commit -m "feat(runtime-core): authenticate manifest fetch with remote fetchOptions"
-```
-
----
-
-## Task 6: Route manifest CSS through the blob loader when `fetchOptions` present
-
-**Files:**
-- Modify: `packages/runtime-core/src/utils/preload.ts` (imports, `preloadAssets` CSS loops ~lines 275-308, new `waitForCssFetch` helper)
-- Test: `packages/runtime-core/src/utils/__tests__/preload-css-fetch-options.spec.ts`
-
-- [ ] **Step 1: Add the import**
-
-At the top of `packages/runtime-core/src/utils/preload.ts`, add `loadCssWithFetch` to the existing `@module-federation/sdk` import (and `createLink`/`createScript` stay). Example:
-
-```ts
-import { createLink, createScript, loadCssWithFetch } from '@module-federation/sdk';
-```
-
-(Adjust to match the file's actual existing import statement.)
-
-- [ ] **Step 2: Add a header-authenticated CSS helper**
-
-Add near `waitForLinkPreload` in `preload.ts`:
-
-```ts
-// When the remote carries fetchOptions, CSS must be fetched WITH headers and
-// injected as a blob <link> — a native <link href> cannot carry headers, and a
-// rel=preload hint would 401. Mirrors loadCss in the loader PoC.
-function waitForCssFetch({
-  host,
-  remoteInfo,
-  url,
-  context,
-}: {
-  host: ModuleFederation;
-  remoteInfo: RemoteInfo;
-  url: string;
-  context: ResourceLoadContext;
-}): Promise<PreloadAssetResult> {
-  return loadCssWithFetch({
-    href: url,
-    fetchOptions: remoteInfo.fetchOptions,
-    customFetch: (u, init) => host.loaderHook.lifecycle.fetch.emit(u, init, remoteInfo),
-  })
-    .then(() => createAssetResult(context, url, 'success'))
-    .catch((error) =>
-      createAssetResult(context, url, isTimeoutError(error) ? 'timeout' : 'error', error),
-    );
-}
-```
-
-- [ ] **Step 3: Use it for CSS when `fetchOptions` present**
-
-In `preloadAssets`, gate the `cssAssets` handling. Replace the two `cssAssets.forEach(...)` blocks (lines ~280-307) so that when `remoteInfo.fetchOptions` is set, CSS goes through `waitForCssFetch`; otherwise the existing `waitForLinkPreload` paths are kept verbatim:
-
-```ts
-    if (remoteInfo.fetchOptions) {
-      cssAssets.forEach((cssUrl) => {
-        results.push(
-          waitForCssFetch({
-            host,
-            remoteInfo,
-            url: cssUrl,
-            context: createResourceContext(baseContext, 'css'),
-          }),
-        );
-      });
-    } else if (useLinkPreload) {
-      const defaultAttrs = { rel: 'preload', as: 'style' };
-      cssAssets.forEach((cssUrl) => {
-        results.push(
-          waitForLinkPreload({
-            host,
-            remoteInfo,
-            url: cssUrl,
-            attrs: defaultAttrs,
-            context: createResourceContext(baseContext, 'css'),
-          }),
-        );
-      });
-    } else {
-      const defaultAttrs = { rel: 'stylesheet', type: 'text/css' };
-      cssAssets.forEach((cssUrl) => {
-        results.push(
-          waitForLinkPreload({
-            host,
-            remoteInfo,
-            url: cssUrl,
-            attrs: defaultAttrs,
-            needDeleteLink: false,
-            context: createResourceContext(baseContext, 'css'),
-          }),
-        );
-      });
-    }
-```
-
-Leave the `jsAssetsWithoutEntry` blocks unchanged (those JS chunks are loaded through the blob graph via the entry's `__mfDyn`, so they already carry headers; preloading them as header-less hints is harmless and out of scope to change here).
-
-- [ ] **Step 4: Write the test**
-
-```ts
-// packages/runtime-core/src/utils/__tests__/preload-css-fetch-options.spec.ts
-const loadCssWithFetch = jest.fn().mockResolvedValue(undefined);
-jest.mock('@module-federation/sdk', () => {
-  const actual = jest.requireActual('@module-federation/sdk');
-  return { ...actual, loadCssWithFetch: (...args: any[]) => loadCssWithFetch(...args) };
-});
-
-import { preloadAssets } from '../preload';
-
-describe('preloadAssets CSS with fetchOptions', () => {
-  it('routes manifest CSS through the blob loader when fetchOptions is set', async () => {
-    const remoteInfo: any = {
-      name: 'a', entry: 'http://x/e.js', type: 'module', entryGlobalName: 'a',
-      shareScope: 'default', fetchOptions: { headers: { Authorization: 'Bearer t' } },
-    };
-    const host: any = {
-      options: { inBrowser: true },
-      loaderHook: { lifecycle: { fetch: { emit: jest.fn() } } },
-    };
-    const assets: any = { cssAssets: ['http://x/a.css'], jsAssetsWithoutEntry: [], entryAssets: [] };
-    await preloadAssets(remoteInfo, host, assets, false);
-    expect(loadCssWithFetch).toHaveBeenCalledWith(
-      expect.objectContaining({ href: 'http://x/a.css', fetchOptions: remoteInfo.fetchOptions }),
-    );
-  });
-});
-```
-
-- [ ] **Step 5: Run test to verify it passes**
-
-Run: `pnpm --filter @module-federation/runtime-core test` (scoped to the new file).
-Expected: PASS.
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add packages/runtime-core/src/utils/preload.ts packages/runtime-core/src/utils/__tests__/preload-css-fetch-options.spec.ts
-git commit -m "feat(runtime-core): fetch manifest CSS with headers for fetchOptions remotes"
-```
-
----
-
-## Task 7: Full verification
-
-**Files:** none (verification only)
-
-- [ ] **Step 1: Confirm `fetchOptions` survives manifest resolution**
-
-Read `packages/runtime-core/src/plugins/snapshot/index.ts:18-38` (`assignRemoteInfo`). It mutates `remoteInfo` in place, setting only `type`, `entryGlobalName`, `entry`, `version`, `buildVersion` — it does NOT touch `fetchOptions`, so the field set in `getRemoteInfo` survives. No code change needed; this step just verifies the assumption still holds.
-
-- [ ] **Step 2: Build the two packages**
-
-Run: `pnpm exec turbo run build --filter=@module-federation/sdk --filter=@module-federation/runtime-core --concurrency=8`
-Expected: both build successfully.
-
-- [ ] **Step 3: Lint**
-
-Run: `pnpm --filter @module-federation/sdk lint && pnpm --filter @module-federation/runtime-core lint`
-Expected: no errors (fix any from the new files).
-
-- [ ] **Step 4: Run the full test suites for both packages**
-
-Run: `pnpm --filter @module-federation/sdk test && pnpm --filter @module-federation/runtime-core test`
-Expected: all green, including the new specs.
-
-- [ ] **Step 5: Add a changeset**
-
-Run: `pnpm changeset` and select `@module-federation/sdk` and `@module-federation/runtime-core` as `minor` (new feature, backward compatible). Describe: "Add per-remote `fetchOptions` to `registerRemotes` enabling header-authenticated ESM remote loading via a fetch+blob loader."
-
-- [ ] **Step 6: Commit**
-
-```bash
-git add .changeset
-git commit -m "chore: changeset for fetchOptions ESM remote loading"
-```
-
----
-
-## Notes / follow-ups (out of scope here)
-
-- `system` (SystemJS) and IIFE/global remotes: only the manifest is authenticated for these; header-carrying chunk loads need separate work (SystemJS loader override / webpack publicPath interception).
-- CSS imported from inside JS (`import './x.css'`) is not handled by the rewriter (it only rewrites JS module specifiers); not exercised by the targeted ESM manifests.
-- The regex-based rewriter is kept as-is from the PoC — acceptable for bundler ESM output, but note it is not a full JS parser.
diff --git a/docs/superpowers/specs/2026-06-16-fetchoptions-esm-remote-loading-design.md b/docs/superpowers/specs/2026-06-16-fetchoptions-esm-remote-loading-design.md
deleted file mode 100644
index dd5a8b495ce..00000000000
--- a/docs/superpowers/specs/2026-06-16-fetchoptions-esm-remote-loading-design.md
+++ /dev/null
@@ -1,216 +0,0 @@
-# `fetchOptions` for header-authenticated ESM remote loading
-
-**Date:** 2026-06-16
-**Status:** Approved design — pending implementation plan
-**Related:** https://github.com/module-federation/enhanced/issues/15
-**PoC:** `js-module-import/index.html` (fetch + blob import-rewriting loader)
-
-## Problem
-
-Native `<script src>` and native `import()` cannot carry custom HTTP headers. A
-compliance use case requires an `Authorization: Bearer …` header (plus arbitrary
-`X-*` headers) on **every** asset request a remote pulls in: the manifest, the
-remote entry, split chunks, and shared dependencies.
-
-Today the Module Federation runtime:
-
-- fetches the **manifest** through the `loaderHook.lifecycle.fetch` hook — the
-  only place headers can already be injected — but passes `{}` as the request
-  options (`SnapshotHandler.ts:307`);
-- loads the **remote entry** via a native `<script>` tag
-  (`loadEntryScript` → `sdk/src/dom.ts`) or native `import()`
-  (`loadEsmEntry`), neither of which can carry headers;
-- loads **split chunks and shared deps** via the bundler runtime
-  (webpack/rspack `__webpack_require__.l`, or native `import()` for ESM output),
-  which the MF runtime does not intercept at all.
-
-There is therefore no way today — via plugin or config — to attach headers to
-the actual JS module graph. A runtime plugin alone is insufficient because
-(a) there is no channel to pass per-remote fetch options from the API down to
-the loader, and (b) the `fetch` hook is emitted only for the manifest.
-
-## Why the PoC works
-
-The PoC sidesteps the bundler's header-less loading entirely. It `fetch`es each
-module's **source text** (headers attached), rewrites every static and dynamic
-`import` to recursively-loaded **blob URLs**, then imports the blob. Because the
-whole graph becomes blob imports driven by an explicit `fetch`, the bundler
-never performs a native header-less load. This works when the remote is built as
-**ES modules** — where all loading is `import` / `import()`. It does not reach
-IIFE / webpack-JSONP chunk loads (`__webpack_require__.l`), so those remain out
-of scope for this iteration.
-
-## Scope
-
-**In scope (this iteration):**
-
-- A per-remote `fetchOptions: RequestInit` passed through `registerRemotes`.
-- Authenticated manifest fetch.
-- A fetch + blob ESM loader (hardened port of the PoC) used for `module` / `esm`
-  remotes that carry `fetchOptions`: entry + all chunks + shared deps.
-- Authenticated loading of **CSS assets declared in `mf-manifest.json`** (fetch
-  the CSS text with headers, inject as a blob `<link>`).
-
-**Out of scope (follow-ups):**
-
-- `loadSystemJsEntry` (`system`) and `loadEntryScript` (IIFE/global) remotes —
-  header-carrying chunk loads for these formats. For non-ESM remotes with
-  `fetchOptions`, only the manifest is authenticated this iteration.
-- CSS imported from inside JS (`import './x.css'`) — not exercised by the PoC
-  and not part of the ESM manifests we target.
-- **JS preload hints** (`jsAssetsWithoutEntry` in `preloadAssets`): these emit
-  header-less `<link rel="preload" as="script">` hints. For `fetchOptions`
-  remotes those hints will 401, but they are harmless — the actual chunk/shared
-  loads run through the authenticated blob graph (`__mfDyn`), exactly like the
-  PoC's suppressed `vite:preloadError` hints. Suppressing the wasted hints is a
-  possible future cleanup, not a correctness fix.
-- **`createLink` lifecycle hook for authenticated CSS:** `loadCssWithFetch`
-  injects the blob `<link>` directly and does not emit the `createLink` hook, so
-  plugins that add CSP `nonce`/SRI attributes do not run for `fetchOptions` CSS.
-  Threading the hook into the sdk loader is a follow-up; unauthenticated CSS
-  still uses the hook.
-
-## Decisions
-
-- **ESM-only, inferred from the manifest.** The entry type comes from
-  `metaData.remoteEntry.type` in `mf-manifest.json` (flows to `remoteInfo.type`).
-  The fetch + blob loader is engaged only in the existing `case 'esm' / 'module'`
-  branch of `loadEntryDom`. Any non-ESM remote never reaches that branch and so
-  automatically falls back to today's loader unchanged.
-- **Per-remote `fetchOptions`.** Different headers for different remotes are
-  expressed by calling `registerRemotes([...], { fetchOptions })` multiple times
-  (e.g. `[remote1, remote2]` with one set, `[remote3, remote4]` with another).
-  `fetchOptions` is stamped onto each `Remote` in that call inside
-  `registerRemotes` (plural). There is no reliance on a singular public
-  `registerRemote`.
-- **Ported PoC code keeps its original comments.** The explanatory comments in
-  `js-module-import/index.html` are carried over verbatim where the code is
-  ported.
-- **Backward compatible.** Every new field is optional; with no `fetchOptions`,
-  all existing behavior is byte-for-byte unchanged.
-
-## Design
-
-### 1. API + type plumbing (`runtime-core`, `sdk`)
-
-- Extend the `registerRemotes` options:
-  `registerRemotes(remotes: Remote[], options?: { force?: boolean; fetchOptions?: RequestInit }): void`.
-  In the plural method, iterate the array and stamp `fetchOptions` onto each
-  remote before delegating to the existing internal registration.
-- Add `fetchOptions?: RequestInit` to the shared `Remote` type
-  (`RemoteInfoCommon`) and to `RemoteInfo` (`runtime-core/src/type/config.ts`).
-- Carry it through `getRemoteInfo` (`runtime-core/src/utils/load.ts:393`) so it
-  lands on `RemoteInfo`. Manifest-driven `assignRemoteInfo`
-  (`plugins/snapshot/index.ts`) must preserve it (it overwrites `type`, not
-  `fetchOptions`).
-
-### 2. Authenticated manifest fetch (`runtime-core`, tiny)
-
-In `SnapshotHandler.ts` (~line 307) `remoteInfo` is already in scope. Change the
-hook emit options `{}` → `remoteInfo.fetchOptions ?? {}`, and the native
-fallback `fetch(manifestUrl, {})` → `fetch(manifestUrl, remoteInfo.fetchOptions ?? {})`.
-The manifest is then authenticated with no plugin required.
-
-### 3. Fetch + blob ESM loader (`sdk` — new `packages/sdk/src/blobLoad.ts`)
-
-A hardened port of the PoC. Public surface:
-
-```ts
-loadEsmEntryWithFetch({
-  entry: string,
-  remoteInfo: RemoteInfo,          // supplies fetchOptions
-  loaderHook: ModuleFederation['loaderHook'],
-}): Promise<RemoteEntryExports>
-
-loadCssWithFetch({
-  href: string,
-  remoteInfo: RemoteInfo,
-  loaderHook: ModuleFederation['loaderHook'],
-}): Promise<void>
-```
-
-Internals (ported from the PoC, comments retained):
-
-- `fetcher(url)` — emits `loaderHook.lifecycle.fetch` (so existing fetch-hook
-  plugins still compose) with `remoteInfo.fetchOptions` merged in; falls back to
-  native `fetch(url, merged)`. Returns response text. Throws a descriptive
-  network error (mirroring the `ScriptNetworkError` messaging in `dom.ts`) on a
-  non-OK response.
-- `resolveSpec(spec, base)` — PoC logic verbatim (relative / absolute-path /
-  absolute-url; bare specifiers throw).
-- `loadModule(url)` — PoC logic: instance-scoped cache (`Map<url, Promise<blobUrl>>`),
-  rewrite `import.meta.url` → the real url, dynamic `import(` → `__mfDyn("<url>",`,
-  static `from`/`import '…'` relative/absolute specifiers → recursively-loaded
-  blob URLs, then `URL.createObjectURL`.
-- `globalThis.__mfDyn` — runtime dynamic-import shim, installed idempotently
-  (guard so repeated remote loads don't reinstall).
-- The `vite:preloadError` listener from the PoC is added once (idempotent) so
-  native preload hints fail quietly.
-
-Hardening over the raw PoC: idempotent global install, instance-scoped cache,
-and unified error messaging — but the regex-based rewriting is kept as-is, which
-is acceptable for the ESM build output we target.
-
-### 4. Routing + ESM gate (`runtime-core`)
-
-In `loadEntryDom` (`runtime-core/src/utils/load.ts:189`), the
-`case 'esm' / 'module'` branch becomes:
-
-```ts
-case 'esm':
-case 'module':
-  return remoteInfo.fetchOptions
-    ? loadEsmEntryWithFetch({ entry, remoteInfo, loaderHook })
-    : loadEsmEntry({ entry, remoteEntryExports });
-```
-
-`system` and the default (`loadEntryScript`) branches are untouched.
-
-### 5. Authenticated manifest CSS (`runtime-core`)
-
-CSS assets declared in the manifest are preloaded today via `createLink` in
-`runtime-core/src/utils/preload.ts` (`waitForLinkPreload`). When the owning
-remote carries `fetchOptions`, route those CSS loads through `loadCssWithFetch`
-instead of a native `<link href>` — fetch the CSS text with headers and inject a
-blob `<link>`. The exact injection point in `preload.ts` (and access to the
-remote's `fetchOptions` there) is confirmed during implementation; the loader
-helper itself lives in `sdk/blobLoad.ts`.
-
-### 6. Error handling
-
-`loadEsmEntryWithFetch` / `loadCssWithFetch` reject with descriptive errors.
-`getRemoteEntry`'s existing `loadEntryError` hook continues to apply, so retry
-plugins keep working.
-
-## Testing
-
-- **Unit (`sdk`):** the import rewriter (static, dynamic, `import.meta.url`
-  cases), `resolveSpec` (relative / absolute / bare-throws), cache reuse, and the
-  `fetcher` header-merge precedence.
-- **Integration:** register an ESM remote with `fetchOptions`, load it, assert
-  the headers reach the manifest fetch, the entry fetch, a dynamically-imported
-  chunk, and a shared dep.
-- **Fallback:** a non-ESM remote with `fetchOptions` is loaded via the original
-  path (loader untouched); an ESM remote without `fetchOptions` uses
-  `loadEsmEntry` unchanged.
-- **CSS:** a manifest-declared CSS asset on a `fetchOptions` remote is fetched
-  with headers and injected as a blob `<link>`.
-
-## Files touched (anticipated)
-
-- `packages/sdk/src/blobLoad.ts` — **new**; fetch + blob loader + CSS helper.
-- `packages/sdk/src/types/…` — `fetchOptions` on the shared remote types;
-  export the new loader.
-- `packages/runtime-core/src/type/config.ts` — `fetchOptions` on `Remote` /
-  `RemoteInfo`.
-- `packages/runtime-core/src/remote/index.ts` — `registerRemotes` options +
-  stamping.
-- `packages/runtime-core/src/utils/load.ts` — `getRemoteInfo` passthrough +
-  `loadEntryDom` routing gate.
-- `packages/runtime-core/src/plugins/snapshot/SnapshotHandler.ts` — manifest
-  fetch options.
-- `packages/runtime-core/src/plugins/snapshot/index.ts` — preserve `fetchOptions`
-  in `assignRemoteInfo`.
-- `packages/runtime-core/src/utils/preload.ts` — route manifest CSS through the
-  fetch + blob helper when `fetchOptions` present.
-- Tests alongside the above.

From b4d95c27c41f069569d69a909d124aa9c5008a70 Mon Sep 17 00:00:00 2001
From: Shaoyu Meng <shaoyumeng@shaoyus-mbp-5.lan>
Date: Wed, 17 Jun 2026 12:36:19 -0700
Subject: [PATCH 21/34] fix(runtime,sdk): address PR review on remote
 fetchOptions

- runtime-core/load: wrap blob-loader ESM entry failures as RUNTIME_008 so
  getRemoteEntry's loadEntryError recovery (token refresh, failover) still
  fires for authenticated ESM remotes
- runtime-core/preload: skip applying authenticated CSS during preload hints
  (useLinkPreload) so a remote's stylesheet no longer overrides host styles
  before the remote is loaded
- sdk/blobLoad: store dynamic-import contexts in a shared globalThis registry
  and stop clobbering an existing __mfDyn shim, so blob modules keep their
  fetch context when two bundled copies of the SDK coexist

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../load-entry-fetch-options.spec.ts          | 23 +++++++++
 .../preload-css-fetch-options.spec.ts         | 25 +++++++++
 packages/runtime-core/src/utils/load.ts       | 18 +++++++
 packages/runtime-core/src/utils/preload.ts    | 28 ++++++----
 packages/sdk/__tests__/blobLoad.spec.ts       | 37 ++++++++++++++
 packages/sdk/src/blobLoad.ts                  | 51 ++++++++++++-------
 6 files changed, 154 insertions(+), 28 deletions(-)

diff --git a/packages/runtime-core/__tests__/load-entry-fetch-options.spec.ts b/packages/runtime-core/__tests__/load-entry-fetch-options.spec.ts
index 1a0e0ca6813..145393a0d3d 100644
--- a/packages/runtime-core/__tests__/load-entry-fetch-options.spec.ts
+++ b/packages/runtime-core/__tests__/load-entry-fetch-options.spec.ts
@@ -37,6 +37,29 @@ describe('loadEntryDom ESM fetchOptions gate', () => {
     );
   });
 
+  it('wraps blob loader failures as RUNTIME_008 so loadEntryError recovery can fire', async () => {
+    loadEsmEntryWithFetch.mockRejectedValueOnce(
+      new Error('BlobLoaderNetworkError: 401 Unauthorized for http://x/e.js'),
+    );
+    const remoteInfo: any = {
+      name: 'a',
+      entry: 'http://x/e.js',
+      type: 'module',
+      entryGlobalName: 'a',
+      shareScope: 'default',
+      fetchOptions: { headers: { Authorization: 'Bearer t' } },
+    };
+    const err = await __loadEntryDomForTest({ remoteInfo, loaderHook }).then(
+      () => undefined,
+      (e: unknown) => e,
+    );
+    expect(err).toBeInstanceOf(Error);
+    // RUNTIME_008 = 'RUNTIME-008'; getRemoteEntry keys recovery off this code.
+    expect((err as Error).message).toContain('RUNTIME-008');
+    // The original failure is preserved for diagnostics.
+    expect((err as Error).message).toContain('401 Unauthorized');
+  });
+
   it('does NOT use the blob loader for module remotes without fetchOptions', async () => {
     const remoteInfo: any = {
       name: 'b',
diff --git a/packages/runtime-core/__tests__/preload-css-fetch-options.spec.ts b/packages/runtime-core/__tests__/preload-css-fetch-options.spec.ts
index fd2827a3881..00a508bd610 100644
--- a/packages/runtime-core/__tests__/preload-css-fetch-options.spec.ts
+++ b/packages/runtime-core/__tests__/preload-css-fetch-options.spec.ts
@@ -39,6 +39,31 @@ describe('preloadAssets CSS with fetchOptions', () => {
     );
   });
 
+  it('does NOT apply authenticated CSS during a preload hint (useLinkPreload)', async () => {
+    const remoteInfo: any = {
+      name: 'a',
+      entry: 'http://x/e.js',
+      type: 'module',
+      entryGlobalName: 'a',
+      shareScope: 'default',
+      fetchOptions: { headers: { Authorization: 'Bearer t' } },
+    };
+    const host: any = {
+      options: { inBrowser: true },
+      loaderHook: { lifecycle: { fetch: { emit: vi.fn() } } },
+    };
+    const assets: any = {
+      cssAssets: ['http://x/a.css'],
+      jsAssetsWithoutEntry: [],
+      entryAssets: [],
+    };
+    // useLinkPreload defaults to true (preloadRemote). The blob loader injects a
+    // rel=stylesheet that would apply the remote's CSS before it is loaded, so it
+    // must be skipped here rather than overriding host styles.
+    await preloadAssets(remoteInfo, host, assets);
+    expect(spy).not.toHaveBeenCalled();
+  });
+
   it('does NOT use the blob loader when fetchOptions is absent', async () => {
     const remoteInfo: any = {
       name: 'b',
diff --git a/packages/runtime-core/src/utils/load.ts b/packages/runtime-core/src/utils/load.ts
index 50bd4346022..96ce92607bd 100644
--- a/packages/runtime-core/src/utils/load.ts
+++ b/packages/runtime-core/src/utils/load.ts
@@ -215,6 +215,24 @@ async function loadEntryDom({
             // Response | void | false shape the sdk loader expects.
             customFetch: async (url, init) =>
               loaderHook.lifecycle.fetch.emit(url, init, remoteInfo),
+          }).catch((loadError: unknown) => {
+            // Mirror loadEntryScript: surface blob-loader fetch/exec failures
+            // (e.g. BlobLoaderNetworkError on a 401) as RUNTIME_008 so
+            // getRemoteEntry's loadEntryError recovery — token refresh,
+            // failover — still fires for authenticated ESM remotes.
+            const originalMsg =
+              loadError instanceof Error
+                ? loadError.message
+                : String(loadError);
+            error(
+              RUNTIME_008,
+              runtimeDescMap,
+              {
+                remoteName: name,
+                resourceUrl: entry,
+              },
+              originalMsg,
+            );
           }) as Promise<RemoteEntryExports>)
         : loadEsmEntry({ entry, remoteEntryExports });
     case 'system':
diff --git a/packages/runtime-core/src/utils/preload.ts b/packages/runtime-core/src/utils/preload.ts
index 7861998f835..b92bb7c0ece 100644
--- a/packages/runtime-core/src/utils/preload.ts
+++ b/packages/runtime-core/src/utils/preload.ts
@@ -314,16 +314,24 @@ export function preloadAssets(
     });
 
     if (remoteInfo.fetchOptions) {
-      cssAssets.forEach((cssUrl) => {
-        results.push(
-          waitForCssFetch({
-            host,
-            remoteInfo,
-            url: cssUrl,
-            context: createResourceContext(baseContext, 'css'),
-          }),
-        );
-      });
+      // Authenticated CSS must be fetched WITH headers and injected as a blob
+      // <link rel=stylesheet> — which *applies* it. Only do that during an
+      // actual load (useLinkPreload=false). During a preload hint we skip it:
+      // a native rel=preload can't carry headers (it would 401), and applying
+      // the remote's stylesheet now would override host styles before the
+      // remote is loaded. The stylesheet is fetched+applied later, on load.
+      if (!useLinkPreload) {
+        cssAssets.forEach((cssUrl) => {
+          results.push(
+            waitForCssFetch({
+              host,
+              remoteInfo,
+              url: cssUrl,
+              context: createResourceContext(baseContext, 'css'),
+            }),
+          );
+        });
+      }
     } else if (useLinkPreload) {
       const defaultAttrs = {
         rel: 'preload',
diff --git a/packages/sdk/__tests__/blobLoad.spec.ts b/packages/sdk/__tests__/blobLoad.spec.ts
index 7dd152362c7..5977d1d0312 100644
--- a/packages/sdk/__tests__/blobLoad.spec.ts
+++ b/packages/sdk/__tests__/blobLoad.spec.ts
@@ -210,3 +210,40 @@ describe('loadCssWithFetch', () => {
     expect(document.head.getElementsByTagName('link').length).toBe(1);
   });
 });
+
+describe('cross-instance dynamic-import context', () => {
+  const CONTEXTS_KEY = '__MF_BLOB_LOAD_CONTEXTS__';
+
+  beforeEach(() => {
+    (global as any).fetch = jest
+      .fn()
+      .mockResolvedValue({ ok: true, text: () => Promise.resolve('') });
+    (global.URL as any).createObjectURL = jest.fn(() => 'blob:m');
+    loadModule.clearCache();
+  });
+
+  it('stores load contexts in a shared globalThis registry', async () => {
+    const ctx = { fetchOptions: { headers: { Authorization: 'Bearer t' } } };
+    await loadModule('https://b.com/entry.js', ctx);
+    // A second bundled copy of the SDK reads the same global map, so a blob
+    // module from this copy keeps its fetch context regardless of which copy's
+    // __mfDyn shim is installed.
+    const registry = (globalThis as Record<string, unknown>)[
+      CONTEXTS_KEY
+    ] as Map<string, unknown>;
+    expect(registry).toBeInstanceOf(Map);
+    expect(registry.get('https://b.com/entry.js')).toBe(ctx);
+  });
+
+  it('does not clobber a __mfDyn shim already installed by another copy', async () => {
+    const existing = jest.fn();
+    (globalThis as Record<string, unknown>)['__mfDyn'] = existing;
+    // The shim installs synchronously before the (jsdom-unsupported) blob
+    // import, so swallow the import rejection; we only assert the shim survived.
+    await loadEsmEntryWithFetch({ entry: 'https://b.com/e.js' }).catch(
+      () => undefined,
+    );
+    expect((globalThis as Record<string, unknown>)['__mfDyn']).toBe(existing);
+    delete (globalThis as Record<string, unknown>)['__mfDyn'];
+  });
+});
diff --git a/packages/sdk/src/blobLoad.ts b/packages/sdk/src/blobLoad.ts
index be7054caec2..84b8bdfcd43 100644
--- a/packages/sdk/src/blobLoad.ts
+++ b/packages/sdk/src/blobLoad.ts
@@ -66,7 +66,19 @@ export interface BlobLoadContext {
 
 // absolute url -> fetcher and its options
 // __mfDyn should reuse the right load context for each module's chunks request.
-const contexts = new Map<string, BlobLoadContext>();
+// Stored on globalThis so that if two bundled copies/versions of the SDK exist,
+// a blob module created by one copy still resolves its fetch context through
+// whichever copy's __mfDyn shim happens to be installed — every copy reads and
+// writes the same shared registry, so contexts are never lost on overwrite.
+const CONTEXTS_KEY = '__MF_BLOB_LOAD_CONTEXTS__';
+const contexts: Map<string, BlobLoadContext> =
+  ((globalThis as Record<string, unknown>)[CONTEXTS_KEY] as
+    | Map<string, BlobLoadContext>
+    | undefined) ||
+  ((globalThis as Record<string, unknown>)[CONTEXTS_KEY] = new Map<
+    string,
+    BlobLoadContext
+  >());
 // absolute url -> Promise<blob url> for JS modules
 const jsCache = new Map<string, Promise<string>>();
 // absolute url -> in-flight/settled promise, used to prevent double-inject the stylesheet.
@@ -176,23 +188,26 @@ function installMFDynImportShim(): void {
   if (dynImportInstalled) return;
   dynImportInstalled = true;
 
-  // Runtime dynamic-import shim: resolve url + fetch from cache or with headers + import as blob.
-  (globalThis as Record<string, unknown>)['__mfDyn'] = async (
-    base: string,
-    spec: string,
-  ) => {
-    const resolved = resolveSpec(spec, base);
-    if (/^(blob:|data:)/.test(resolved)) {
-      return import(/* webpackIgnore: true */ /* @vite-ignore */ resolved);
-    }
-    const ctx = contexts.get(base) || {};
-    return import(
-      /* webpackIgnore: true */ /* @vite-ignore */ await loadModule(
-        resolved,
-        ctx,
-      )
-    );
-  };
+  const g = globalThis as Record<string, unknown>;
+  // Don't clobber a shim already installed by another bundled copy of the SDK:
+  // its closure resolves contexts through the same shared registry, so blob
+  // modules from either copy keep working through whichever shim wins.
+  if (typeof g['__mfDyn'] !== 'function') {
+    // Runtime dynamic-import shim: resolve url + fetch from cache or with headers + import as blob.
+    g['__mfDyn'] = async (base: string, spec: string) => {
+      const resolved = resolveSpec(spec, base);
+      if (/^(blob:|data:)/.test(resolved)) {
+        return import(/* webpackIgnore: true */ /* @vite-ignore */ resolved);
+      }
+      const ctx = contexts.get(base) || {};
+      return import(
+        /* webpackIgnore: true */ /* @vite-ignore */ await loadModule(
+          resolved,
+          ctx,
+        )
+      );
+    };
+  }
 
   // The vite preload helper creates native <link> preloads (no auth header) as a
   // perf hint; those 401 errors should be ignored instead of throwing — real loads go via __mfDyn.

From cd28a33051c601f355572c00bf6d3cdd73e79b4d Mon Sep 17 00:00:00 2001
From: Shaoyu Meng <shaoyumeng@shaoyus-mbp-5.lan>
Date: Wed, 17 Jun 2026 12:51:22 -0700
Subject: [PATCH 22/34] refactor(sdk): hang blob-load context registry off
 __mfDyn

Instead of adding a separate __MF_BLOB_LOAD_CONTEXTS__ global, attach the
shared dynamic-import context map as a property of the single global __mfDyn
shim. Avoids polluting globalThis with a second variable while keeping the
cross-SDK-copy guarantee: every copy reads/writes the same map through
whichever shim is installed.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/sdk/__tests__/blobLoad.spec.ts | 19 +++---
 packages/sdk/src/blobLoad.ts            | 87 ++++++++++++++-----------
 2 files changed, 58 insertions(+), 48 deletions(-)

diff --git a/packages/sdk/__tests__/blobLoad.spec.ts b/packages/sdk/__tests__/blobLoad.spec.ts
index 5977d1d0312..a1114333db7 100644
--- a/packages/sdk/__tests__/blobLoad.spec.ts
+++ b/packages/sdk/__tests__/blobLoad.spec.ts
@@ -212,8 +212,6 @@ describe('loadCssWithFetch', () => {
 });
 
 describe('cross-instance dynamic-import context', () => {
-  const CONTEXTS_KEY = '__MF_BLOB_LOAD_CONTEXTS__';
-
   beforeEach(() => {
     (global as any).fetch = jest
       .fn()
@@ -222,17 +220,16 @@ describe('cross-instance dynamic-import context', () => {
     loadModule.clearCache();
   });
 
-  it('stores load contexts in a shared globalThis registry', async () => {
+  it('stores load contexts on the shared __mfDyn shim', async () => {
     const ctx = { fetchOptions: { headers: { Authorization: 'Bearer t' } } };
     await loadModule('https://b.com/entry.js', ctx);
-    // A second bundled copy of the SDK reads the same global map, so a blob
-    // module from this copy keeps its fetch context regardless of which copy's
-    // __mfDyn shim is installed.
-    const registry = (globalThis as Record<string, unknown>)[
-      CONTEXTS_KEY
-    ] as Map<string, unknown>;
-    expect(registry).toBeInstanceOf(Map);
-    expect(registry.get('https://b.com/entry.js')).toBe(ctx);
+    // The registry hangs off the single global __mfDyn function, so a second
+    // bundled copy of the SDK reading the same shim keeps the fetch context
+    // regardless of which copy's shim is installed.
+    const shim = (globalThis as Record<string, any>)['__mfDyn'];
+    expect(typeof shim).toBe('function');
+    expect(shim.contexts).toBeInstanceOf(Map);
+    expect(shim.contexts.get('https://b.com/entry.js')).toBe(ctx);
   });
 
   it('does not clobber a __mfDyn shim already installed by another copy', async () => {
diff --git a/packages/sdk/src/blobLoad.ts b/packages/sdk/src/blobLoad.ts
index 84b8bdfcd43..beb9755d580 100644
--- a/packages/sdk/src/blobLoad.ts
+++ b/packages/sdk/src/blobLoad.ts
@@ -64,21 +64,31 @@ export interface BlobLoadContext {
   customFetch?: BlobFetcher;
 }
 
-// absolute url -> fetcher and its options
-// __mfDyn should reuse the right load context for each module's chunks request.
-// Stored on globalThis so that if two bundled copies/versions of the SDK exist,
-// a blob module created by one copy still resolves its fetch context through
-// whichever copy's __mfDyn shim happens to be installed — every copy reads and
-// writes the same shared registry, so contexts are never lost on overwrite.
-const CONTEXTS_KEY = '__MF_BLOB_LOAD_CONTEXTS__';
-const contexts: Map<string, BlobLoadContext> =
-  ((globalThis as Record<string, unknown>)[CONTEXTS_KEY] as
-    | Map<string, BlobLoadContext>
-    | undefined) ||
-  ((globalThis as Record<string, unknown>)[CONTEXTS_KEY] = new Map<
-    string,
-    BlobLoadContext
-  >());
+// The dynamic-import shim installed on globalThis as __mfDyn. Its context
+// registry (absolute url -> fetcher + options) hangs off the function itself
+// rather than living in a second global: if two bundled copies/versions of the
+// SDK coexist, every copy reads and writes the same map through whichever shim
+// is installed, so a blob module's dynamic imports never lose their fetch
+// context — and we don't pollute globalThis with an extra variable.
+type MFDynShim = ((base: string, spec: string) => Promise<unknown>) & {
+  contexts?: Map<string, BlobLoadContext>;
+};
+
+// Resolve the shared context registry, lazily installing the global __mfDyn
+// shim on first use (loadModule can run before the shim is formally installed).
+// An existing shim from another SDK copy is reused, never overwritten.
+function getContexts(): Map<string, BlobLoadContext> {
+  const g = globalThis as Record<string, unknown>;
+  let shim = g['__mfDyn'] as MFDynShim | undefined;
+  if (typeof shim !== 'function') {
+    shim = createDynImportShim();
+    g['__mfDyn'] = shim;
+  }
+  if (!shim.contexts) {
+    shim.contexts = new Map<string, BlobLoadContext>();
+  }
+  return shim.contexts;
+}
 // absolute url -> Promise<blob url> for JS modules
 const jsCache = new Map<string, Promise<string>>();
 // absolute url -> in-flight/settled promise, used to prevent double-inject the stylesheet.
@@ -137,7 +147,7 @@ export async function fetchText(
 function loadModuleImpl(url: string, ctx: BlobLoadContext): Promise<string> {
   // Register the context for this url on every call so __mfDyn uses the latest
   // headers for that module's dynamic imports, even when the blob is cached.
-  contexts.set(url, ctx);
+  getContexts().set(url, ctx);
   if (jsCache.has(url)) return jsCache.get(url)!;
 
   const promise = (async () => {
@@ -179,35 +189,38 @@ export const loadModule: ((
 } = Object.assign(loadModuleImpl, {
   clearCache: () => {
     jsCache.clear();
-    contexts.clear();
+    getContexts().clear();
     cssCache.clear();
   },
 });
 
+// Runtime dynamic-import shim: resolve url + fetch from cache or with headers +
+// import as blob. Reads its context off the shared registry (getContexts) so it
+// works for blob modules created by any bundled copy of the SDK.
+function createDynImportShim(): MFDynShim {
+  return (async (base: string, spec: string) => {
+    const resolved = resolveSpec(spec, base);
+    if (/^(blob:|data:)/.test(resolved)) {
+      return import(/* webpackIgnore: true */ /* @vite-ignore */ resolved);
+    }
+    const ctx = getContexts().get(base) || {};
+    return import(
+      /* webpackIgnore: true */ /* @vite-ignore */ await loadModule(
+        resolved,
+        ctx,
+      )
+    );
+  }) as MFDynShim;
+}
+
 function installMFDynImportShim(): void {
   if (dynImportInstalled) return;
   dynImportInstalled = true;
 
-  const g = globalThis as Record<string, unknown>;
-  // Don't clobber a shim already installed by another bundled copy of the SDK:
-  // its closure resolves contexts through the same shared registry, so blob
-  // modules from either copy keep working through whichever shim wins.
-  if (typeof g['__mfDyn'] !== 'function') {
-    // Runtime dynamic-import shim: resolve url + fetch from cache or with headers + import as blob.
-    g['__mfDyn'] = async (base: string, spec: string) => {
-      const resolved = resolveSpec(spec, base);
-      if (/^(blob:|data:)/.test(resolved)) {
-        return import(/* webpackIgnore: true */ /* @vite-ignore */ resolved);
-      }
-      const ctx = contexts.get(base) || {};
-      return import(
-        /* webpackIgnore: true */ /* @vite-ignore */ await loadModule(
-          resolved,
-          ctx,
-        )
-      );
-    };
-  }
+  // Ensure the single global __mfDyn shim (and its shared contexts map) exists.
+  // getContexts() installs the shim on first use and never clobbers one already
+  // installed by another bundled copy of the SDK.
+  getContexts();
 
   // The vite preload helper creates native <link> preloads (no auth header) as a
   // perf hint; those 401 errors should be ignored instead of throwing — real loads go via __mfDyn.

From 4afa878ec1ab301fcc738307b1046932d1e9f96b Mon Sep 17 00:00:00 2001
From: Shaoyu Meng <shaoyumeng@shaoyus-mbp-5.lan>
Date: Wed, 17 Jun 2026 14:02:03 -0700
Subject: [PATCH 23/34] refactor(sdk): drop dynImportInstalled flag from blob
 loader
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

getContexts() already installs the __mfDyn shim idempotently, so the only
thing the flag still guarded was duplicate vite:preloadError listeners. Use a
stable handler reference instead — addEventListener treats an identical
(callback, capture) pair as a no-op — and remove the flag.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/sdk/src/blobLoad.ts | 30 +++++++++++++++---------------
 1 file changed, 15 insertions(+), 15 deletions(-)

diff --git a/packages/sdk/src/blobLoad.ts b/packages/sdk/src/blobLoad.ts
index beb9755d580..40c89b805ee 100644
--- a/packages/sdk/src/blobLoad.ts
+++ b/packages/sdk/src/blobLoad.ts
@@ -6,9 +6,9 @@ export interface BlobDep {
 }
 
 // Resolve a specifier (relative, absolute-path, or already-absolute-url)
-// against a base url to a concrete fetchable url. The MF runtime resolves
-// shared deps to relative loadShare asset urls, so bare specifiers never reach
-// the loader; anything bare is unexpected and throws.
+// against a base url to a concrete fetchable url.
+// Shared dependencies should have already been resolved by the MF runtime
+// as relative loadShare asset urls, so anything bare is unexpected and throws.
 export function resolveSpec(spec: string, base: string): string {
   if (/^(blob:|https?:|data:)/.test(spec)) return spec;
   if (spec.startsWith('.') || spec.startsWith('/'))
@@ -74,12 +74,12 @@ type MFDynShim = ((base: string, spec: string) => Promise<unknown>) & {
   contexts?: Map<string, BlobLoadContext>;
 };
 
-// Resolve the shared context registry, lazily installing the global __mfDyn
+// Resolve the blob loader context registry, lazily installing the global __mfDyn
 // shim on first use (loadModule can run before the shim is formally installed).
-// An existing shim from another SDK copy is reused, never overwritten.
 function getContexts(): Map<string, BlobLoadContext> {
   const g = globalThis as Record<string, unknown>;
   let shim = g['__mfDyn'] as MFDynShim | undefined;
+  // If an existing shim from another SDK copy is installed, we reuse it instead of reinstalling.
   if (typeof shim !== 'function') {
     shim = createDynImportShim();
     g['__mfDyn'] = shim;
@@ -93,7 +93,6 @@ function getContexts(): Map<string, BlobLoadContext> {
 const jsCache = new Map<string, Promise<string>>();
 // absolute url -> in-flight/settled promise, used to prevent double-inject the stylesheet.
 const cssCache = new Map<string, Promise<void>>();
-let dynImportInstalled = false;
 
 function isResponseLike(res: unknown): res is Response {
   return (
@@ -104,7 +103,7 @@ function isResponseLike(res: unknown): res is Response {
   );
 }
 
-// Create a const copy of headers, to avoid the case when the original headers are mutated by fetcher.
+// Create and normalize a const copy of headers, to avoid the case when the original headers are mutated by fetcher.
 export function toHeaderObject(
   headers: RequestInit['headers'],
 ): Record<string, string> {
@@ -213,19 +212,20 @@ function createDynImportShim(): MFDynShim {
   }) as MFDynShim;
 }
 
-function installMFDynImportShim(): void {
-  if (dynImportInstalled) return;
-  dynImportInstalled = true;
+// The vite preload helper creates native <link> preloads (no auth header) as a
+// perf hint; those 401 errors should be ignored instead of throwing — real
+// loads go via __mfDyn. A stable handler ref lets addEventListener dedupe repeat
+// installs (identical callback + capture is a no-op per the DOM spec).
+const ignoreVitePreloadError = (e: Event) => e.preventDefault();
 
+function installMFDynImportShim(): void {
   // Ensure the single global __mfDyn shim (and its shared contexts map) exists.
-  // getContexts() installs the shim on first use and never clobbers one already
-  // installed by another bundled copy of the SDK.
+  // getContexts() is idempotent: it installs the shim on first use and never
+  // clobbers one already installed by another bundled copy of the SDK.
   getContexts();
 
-  // The vite preload helper creates native <link> preloads (no auth header) as a
-  // perf hint; those 401 errors should be ignored instead of throwing — real loads go via __mfDyn.
   if (typeof window !== 'undefined') {
-    window.addEventListener('vite:preloadError', (e) => e.preventDefault());
+    window.addEventListener('vite:preloadError', ignoreVitePreloadError);
   }
 }
 

From 89b99c402e3dfd788d5bf8fba8a0e36624339424 Mon Sep 17 00:00:00 2001
From: Shaoyu Meng <shaoyumeng@shaoyus-mbp-5.lan>
Date: Wed, 17 Jun 2026 14:16:02 -0700
Subject: [PATCH 24/34] refactor(sdk): rename blob loader symbols for clarity

- __mfDyn -> __mfDynImport (global dynamic-import shim)
- MFDynShim -> MFDynImportShim
- getContexts -> createOrGetBlobLoaderContexts
- shim.contexts -> shim.blobLoaderContexts
- BlobLoadContext -> BlobLoaderContext

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/sdk/__tests__/blobLoad.spec.ts | 26 +++++-----
 packages/sdk/src/blobLoad.ts            | 64 ++++++++++++-------------
 2 files changed, 46 insertions(+), 44 deletions(-)

diff --git a/packages/sdk/__tests__/blobLoad.spec.ts b/packages/sdk/__tests__/blobLoad.spec.ts
index a1114333db7..dbb9c141728 100644
--- a/packages/sdk/__tests__/blobLoad.spec.ts
+++ b/packages/sdk/__tests__/blobLoad.spec.ts
@@ -35,9 +35,11 @@ describe('rewriteModuleCode', () => {
     expect(code).toBe(`const u = ${JSON.stringify(url)};`);
   });
 
-  it('routes dynamic import() through __mfDyn with the base url', () => {
+  it('routes dynamic import() through __mfDynImport with the base url', () => {
     const { code } = rewriteModuleCode('const m = import("./x.js");', url);
-    expect(code).toBe(`const m = __mfDyn(${JSON.stringify(url)},"./x.js");`);
+    expect(code).toBe(
+      `const m = __mfDynImport(${JSON.stringify(url)},"./x.js");`,
+    );
   });
 
   it('collects static relative/absolute deps and leaves bare imports alone', () => {
@@ -220,27 +222,29 @@ describe('cross-instance dynamic-import context', () => {
     loadModule.clearCache();
   });
 
-  it('stores load contexts on the shared __mfDyn shim', async () => {
+  it('stores load contexts on the shared __mfDynImport shim', async () => {
     const ctx = { fetchOptions: { headers: { Authorization: 'Bearer t' } } };
     await loadModule('https://b.com/entry.js', ctx);
-    // The registry hangs off the single global __mfDyn function, so a second
+    // The registry hangs off the single global __mfDynImport function, so a second
     // bundled copy of the SDK reading the same shim keeps the fetch context
     // regardless of which copy's shim is installed.
-    const shim = (globalThis as Record<string, any>)['__mfDyn'];
+    const shim = (globalThis as Record<string, any>)['__mfDynImport'];
     expect(typeof shim).toBe('function');
-    expect(shim.contexts).toBeInstanceOf(Map);
-    expect(shim.contexts.get('https://b.com/entry.js')).toBe(ctx);
+    expect(shim.blobLoaderContexts).toBeInstanceOf(Map);
+    expect(shim.blobLoaderContexts.get('https://b.com/entry.js')).toBe(ctx);
   });
 
-  it('does not clobber a __mfDyn shim already installed by another copy', async () => {
+  it('does not clobber a __mfDynImport shim already installed by another copy', async () => {
     const existing = jest.fn();
-    (globalThis as Record<string, unknown>)['__mfDyn'] = existing;
+    (globalThis as Record<string, unknown>)['__mfDynImport'] = existing;
     // The shim installs synchronously before the (jsdom-unsupported) blob
     // import, so swallow the import rejection; we only assert the shim survived.
     await loadEsmEntryWithFetch({ entry: 'https://b.com/e.js' }).catch(
       () => undefined,
     );
-    expect((globalThis as Record<string, unknown>)['__mfDyn']).toBe(existing);
-    delete (globalThis as Record<string, unknown>)['__mfDyn'];
+    expect((globalThis as Record<string, unknown>)['__mfDynImport']).toBe(
+      existing,
+    );
+    delete (globalThis as Record<string, unknown>)['__mfDynImport'];
   });
 });
diff --git a/packages/sdk/src/blobLoad.ts b/packages/sdk/src/blobLoad.ts
index 40c89b805ee..a91b29b6577 100644
--- a/packages/sdk/src/blobLoad.ts
+++ b/packages/sdk/src/blobLoad.ts
@@ -19,7 +19,7 @@ export function resolveSpec(spec: string, base: string): string {
 }
 
 // Rewrite a module's source: pin import.meta.url, route dynamic imports through
-// __mfDyn, and collect static relative/absolute specifiers (to be replaced with
+// __mfDynImport, and collect static relative/absolute specifiers (to be replaced with
 // recursively-loaded blob urls by the caller).
 export function rewriteModuleCode(
   code: string,
@@ -29,10 +29,10 @@ export function rewriteModuleCode(
   // In this case, modules with publicPath:"auto" can derive paths from it.
   code = code.replace(/\bimport\.meta\.url\b/g, JSON.stringify(url));
 
-  // Dynamic import(...) -> __mfDyn("<url>", ...).
+  // Dynamic import(...) -> __mfDynImport("<url>", ...).
   code = code.replace(
     /(?<![.\w$])import\s*\(/g,
-    `__mfDyn(${JSON.stringify(url)},`,
+    `__mfDynImport(${JSON.stringify(url)},`,
   );
 
   // Static `import * from ...` and `import ...` -> recursively-loaded blob urls.
@@ -57,37 +57,35 @@ export type BlobFetcher = (
   init: RequestInit,
 ) => Promise<Response | void | false> | Response | void | false;
 
-export interface BlobLoadContext {
+export interface BlobLoaderContext {
   fetchOptions?: RequestInit;
   // Optional custom fetch (e.g. routed through the runtime loaderHook.fetch so
   // existing fetch-hook plugins still compose). Falls back to native fetch.
   customFetch?: BlobFetcher;
 }
 
-// The dynamic-import shim installed on globalThis as __mfDyn. Its context
+// The dynamic-import shim installed on globalThis as __mfDynImport. Its context
 // registry (absolute url -> fetcher + options) hangs off the function itself
-// rather than living in a second global: if two bundled copies/versions of the
-// SDK coexist, every copy reads and writes the same map through whichever shim
-// is installed, so a blob module's dynamic imports never lose their fetch
-// context — and we don't pollute globalThis with an extra variable.
-type MFDynShim = ((base: string, spec: string) => Promise<unknown>) & {
-  contexts?: Map<string, BlobLoadContext>;
+// rather than living in a second global, so two bundled copies/versions of the
+// SDK can coexist.
+type MFDynImportShim = ((base: string, spec: string) => Promise<unknown>) & {
+  blobLoaderContexts?: Map<string, BlobLoaderContext>;
 };
 
-// Resolve the blob loader context registry, lazily installing the global __mfDyn
+// Resolve the blob loader context registry, lazily installing the global __mfDynImport
 // shim on first use (loadModule can run before the shim is formally installed).
-function getContexts(): Map<string, BlobLoadContext> {
+function createOrGetBlobLoaderContexts(): Map<string, BlobLoaderContext> {
   const g = globalThis as Record<string, unknown>;
-  let shim = g['__mfDyn'] as MFDynShim | undefined;
+  let shim = g['__mfDynImport'] as MFDynImportShim | undefined;
   // If an existing shim from another SDK copy is installed, we reuse it instead of reinstalling.
   if (typeof shim !== 'function') {
     shim = createDynImportShim();
-    g['__mfDyn'] = shim;
+    g['__mfDynImport'] = shim;
   }
-  if (!shim.contexts) {
-    shim.contexts = new Map<string, BlobLoadContext>();
+  if (!shim.blobLoaderContexts) {
+    shim.blobLoaderContexts = new Map<string, BlobLoaderContext>();
   }
-  return shim.contexts;
+  return shim.blobLoaderContexts;
 }
 // absolute url -> Promise<blob url> for JS modules
 const jsCache = new Map<string, Promise<string>>();
@@ -119,7 +117,7 @@ export function toHeaderObject(
 
 export async function fetchText(
   url: string,
-  ctx: BlobLoadContext,
+  ctx: BlobLoaderContext,
 ): Promise<string> {
   const init: RequestInit = {
     ...(ctx.fetchOptions || {}),
@@ -141,12 +139,12 @@ export async function fetchText(
 }
 
 // Fetch a module with headers, rewrite its imports.
-// Dynamic imports are handled lazily at runtime via __mfDyn,
+// Dynamic imports are handled lazily at runtime via __mfDynImport,
 // Static relative imports are pre-loaded recursively.
-function loadModuleImpl(url: string, ctx: BlobLoadContext): Promise<string> {
-  // Register the context for this url on every call so __mfDyn uses the latest
+function loadModuleImpl(url: string, ctx: BlobLoaderContext): Promise<string> {
+  // Register the context for this url on every call so __mfDynImport uses the latest
   // headers for that module's dynamic imports, even when the blob is cached.
-  getContexts().set(url, ctx);
+  createOrGetBlobLoaderContexts().set(url, ctx);
   if (jsCache.has(url)) return jsCache.get(url)!;
 
   const promise = (async () => {
@@ -182,47 +180,47 @@ function loadModuleImpl(url: string, ctx: BlobLoadContext): Promise<string> {
 // Exported with a clearCache test seam.
 export const loadModule: ((
   url: string,
-  ctx: BlobLoadContext,
+  ctx: BlobLoaderContext,
 ) => Promise<string>) & {
   clearCache: () => void;
 } = Object.assign(loadModuleImpl, {
   clearCache: () => {
+    createOrGetBlobLoaderContexts().clear();
     jsCache.clear();
-    getContexts().clear();
     cssCache.clear();
   },
 });
 
 // Runtime dynamic-import shim: resolve url + fetch from cache or with headers +
-// import as blob. Reads its context off the shared registry (getContexts) so it
+// import as blob. Reads its context off the shared registry (createOrGetBlobLoaderContexts) so it
 // works for blob modules created by any bundled copy of the SDK.
-function createDynImportShim(): MFDynShim {
+function createDynImportShim(): MFDynImportShim {
   return (async (base: string, spec: string) => {
     const resolved = resolveSpec(spec, base);
     if (/^(blob:|data:)/.test(resolved)) {
       return import(/* webpackIgnore: true */ /* @vite-ignore */ resolved);
     }
-    const ctx = getContexts().get(base) || {};
+    const ctx = createOrGetBlobLoaderContexts().get(base) || {};
     return import(
       /* webpackIgnore: true */ /* @vite-ignore */ await loadModule(
         resolved,
         ctx,
       )
     );
-  }) as MFDynShim;
+  }) as MFDynImportShim;
 }
 
 // The vite preload helper creates native <link> preloads (no auth header) as a
 // perf hint; those 401 errors should be ignored instead of throwing — real
-// loads go via __mfDyn. A stable handler ref lets addEventListener dedupe repeat
+// loads go via __mfDynImport. A stable handler ref lets addEventListener dedupe repeat
 // installs (identical callback + capture is a no-op per the DOM spec).
 const ignoreVitePreloadError = (e: Event) => e.preventDefault();
 
 function installMFDynImportShim(): void {
-  // Ensure the single global __mfDyn shim (and its shared contexts map) exists.
-  // getContexts() is idempotent: it installs the shim on first use and never
+  // Ensure the single global __mfDynImport shim (and its shared contexts map) exists.
+  // createOrGetBlobLoaderContexts() is idempotent: it installs the shim on first use and never
   // clobbers one already installed by another bundled copy of the SDK.
-  getContexts();
+  createOrGetBlobLoaderContexts();
 
   if (typeof window !== 'undefined') {
     window.addEventListener('vite:preloadError', ignoreVitePreloadError);

From bb56552292fca9f78042a5efe9c7a91221f140db Mon Sep 17 00:00:00 2001
From: Shaoyu Meng <shaoyumeng@shaoyus-mbp-5.lan>
Date: Wed, 17 Jun 2026 14:20:51 -0700
Subject: [PATCH 25/34] refactor(runtime-core): collapse preload CSS branches
 into one helper

Extract pushCssAsset so the three CSS branches (authenticated fetch, rel=preload
hint, applied rel=stylesheet) share a single forEach instead of repeating the
cssAssets.forEach/results.push boilerplate. Behavior is unchanged:
needDeleteLink stays undefined for the preload hint and false for the applied
stylesheet.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 packages/runtime-core/src/utils/preload.ts | 79 ++++++++--------------
 1 file changed, 29 insertions(+), 50 deletions(-)

diff --git a/packages/runtime-core/src/utils/preload.ts b/packages/runtime-core/src/utils/preload.ts
index b92bb7c0ece..f9001b39d04 100644
--- a/packages/runtime-core/src/utils/preload.ts
+++ b/packages/runtime-core/src/utils/preload.ts
@@ -313,59 +313,38 @@ export function preloadAssets(
       );
     });
 
-    if (remoteInfo.fetchOptions) {
-      // Authenticated CSS must be fetched WITH headers and injected as a blob
-      // <link rel=stylesheet> — which *applies* it. Only do that during an
-      // actual load (useLinkPreload=false). During a preload hint we skip it:
-      // a native rel=preload can't carry headers (it would 401), and applying
-      // the remote's stylesheet now would override host styles before the
-      // remote is loaded. The stylesheet is fetched+applied later, on load.
-      if (!useLinkPreload) {
-        cssAssets.forEach((cssUrl) => {
+    // Push the preload/load task for a single CSS asset.
+    const pushCssAsset = (cssUrl: string) => {
+      const context = createResourceContext(baseContext, 'css');
+
+      // Authenticated CSS: fetch WITH headers and inject as a blob stylesheet
+      // We should only do that on an actual load because
+      // 1. native rel=preload can't carry headers so we must skip it
+      // 2. applying the remote's CSS in preload might override host styles before remote module is loaded
+      if (remoteInfo.fetchOptions) {
+        if (!useLinkPreload) {
           results.push(
-            waitForCssFetch({
-              host,
-              remoteInfo,
-              url: cssUrl,
-              context: createResourceContext(baseContext, 'css'),
-            }),
+            waitForCssFetch({ host, remoteInfo, url: cssUrl, context }),
           );
-        });
+        }
+        return;
       }
-    } else if (useLinkPreload) {
-      const defaultAttrs = {
-        rel: 'preload',
-        as: 'style',
-      };
-      cssAssets.forEach((cssUrl) => {
-        results.push(
-          waitForLinkPreload({
-            host,
-            remoteInfo,
-            url: cssUrl,
-            attrs: defaultAttrs,
-            context: createResourceContext(baseContext, 'css'),
-          }),
-        );
-      });
-    } else {
-      const defaultAttrs = {
-        rel: 'stylesheet',
-        type: 'text/css',
-      };
-      cssAssets.forEach((cssUrl) => {
-        results.push(
-          waitForLinkPreload({
-            host,
-            remoteInfo,
-            url: cssUrl,
-            attrs: defaultAttrs,
-            needDeleteLink: false,
-            context: createResourceContext(baseContext, 'css'),
-          }),
-        );
-      });
-    }
+
+      // Plain CSS via <link>: a rel=preload hint, or an applied rel=stylesheet.
+      results.push(
+        waitForLinkPreload({
+          host,
+          remoteInfo,
+          url: cssUrl,
+          attrs: useLinkPreload
+            ? { rel: 'preload', as: 'style' }
+            : { rel: 'stylesheet', type: 'text/css' },
+          needDeleteLink: useLinkPreload ? undefined : false,
+          context,
+        }),
+      );
+    };
+    cssAssets.forEach(pushCssAsset);
 
     if (useLinkPreload) {
       const defaultAttrs = {

From 7e65201dfccf4906db5506a409b900b36fe67c5b Mon Sep 17 00:00:00 2001
From: Shaoyu Meng <shaoyumeng@shaoyus-mbp-5.lan>
Date: Mon, 22 Jun 2026 17:40:22 -0700
Subject: [PATCH 26/34] refactor(runtime-core): drive remote header auth via
 fetch hook, not registerRemotes config

Address PR review (2heal1): header/auth customization is request behavior, so
configure it through the existing `fetch` hook (which already receives
`remoteInfo`) rather than a new `fetchOptions` field on remote registration.

- Remove `fetchOptions` from `RemoteInfoCommon`/`RemoteInfo`, the
  `registerRemotes` options, and the call-level merge helper; revert the
  manifest fetch to its prior `{}` init (it already passed `remoteInfo`).
- Gate the ESM remote-entry and manifest-CSS blob loaders on fetch-hook
  presence (`loaderHook.fetch.listeners.size > 0`) instead of `fetchOptions`,
  routing their requests through the hook with `remoteInfo`/`resourceContext`.
  With no fetch hook, remotes load via native import()/<link> as before.
- Rename/rewrite tests to cover the hook-presence gate; update EN/ZH docs to
  document the `fetch` hook approach and refresh the changeset.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .changeset/remote-fetch-options.md            |  2 +-
 .../docs/en/guide/runtime/runtime-api.mdx     | 54 +++++-----
 .../docs/en/guide/runtime/runtime-hooks.mdx   |  2 +-
 .../docs/zh/guide/runtime/runtime-api.mdx     | 54 +++++-----
 .../docs/zh/guide/runtime/runtime-hooks.mdx   |  2 +-
 .../__tests__/load-entry-fetch-hook.spec.ts   | 98 +++++++++++++++++++
 .../load-entry-fetch-options.spec.ts          | 76 --------------
 .../__tests__/manifest-fetch-hook.spec.ts     | 47 +++++++++
 .../__tests__/manifest-fetch-options.spec.ts  | 49 ----------
 ...spec.ts => preload-css-fetch-hook.spec.ts} | 87 +++++++---------
 .../__tests__/register-remotes.spec.ts        | 40 --------
 packages/runtime-core/src/core.ts             |  5 +-
 .../src/plugins/snapshot/SnapshotHandler.ts   |  4 +-
 packages/runtime-core/src/remote/index.ts     | 32 +-----
 packages/runtime-core/src/type/config.ts      |  2 -
 packages/runtime-core/src/utils/load.ts       | 15 ++-
 packages/runtime-core/src/utils/preload.ts    | 21 ++--
 17 files changed, 259 insertions(+), 331 deletions(-)
 create mode 100644 packages/runtime-core/__tests__/load-entry-fetch-hook.spec.ts
 delete mode 100644 packages/runtime-core/__tests__/load-entry-fetch-options.spec.ts
 create mode 100644 packages/runtime-core/__tests__/manifest-fetch-hook.spec.ts
 delete mode 100644 packages/runtime-core/__tests__/manifest-fetch-options.spec.ts
 rename packages/runtime-core/__tests__/{preload-css-fetch-options.spec.ts => preload-css-fetch-hook.spec.ts} (51%)

diff --git a/.changeset/remote-fetch-options.md b/.changeset/remote-fetch-options.md
index 0916124f8d7..824a93a9c78 100644
--- a/.changeset/remote-fetch-options.md
+++ b/.changeset/remote-fetch-options.md
@@ -3,4 +3,4 @@
 '@module-federation/sdk': minor
 ---
 
-Add per-remote `fetchOptions` to `registerRemotes`, enabling header-authenticated ESM remote loading. When a `module`/`esm` remote is registered with `registerRemotes(remotes, { fetchOptions })`, the manifest, remote entry, split chunks, and shared deps are loaded via a fetch + blob import-rewriting loader so custom HTTP headers (e.g. `Authorization`) reach every asset request. Manifest-declared CSS for such remotes is also fetched with headers and injected as a blob stylesheet. Non-ESM remotes and remotes without `fetchOptions` are unaffected.
+Enable header-authenticated ESM remote loading through the existing runtime `fetch` hook. When a `fetch` hook plugin is registered, `module`/`esm` remotes load their remote entry and manifest-declared CSS via a fetch + blob import-rewriting loader (instead of native `import()` / `<link>`), so custom HTTP headers (e.g. `Authorization`) be applied on every asset request. The hook receives `remoteInfo`, so headers can be decided per remote and support dynamic cases such as token refresh. Remote registration is unchanged and no new remote config is introduced; remotes load as before when no `fetch` hook is present.
diff --git a/apps/website-new/docs/en/guide/runtime/runtime-api.mdx b/apps/website-new/docs/en/guide/runtime/runtime-api.mdx
index 57dfee66eb3..ba9a6e986f2 100644
--- a/apps/website-new/docs/en/guide/runtime/runtime-api.mdx
+++ b/apps/website-new/docs/en/guide/runtime/runtime-api.mdx
@@ -275,10 +275,7 @@ if (targetInstance) {
 <Collapse>
 
 ```typescript
-function registerRemotes(
-  remotes: Remote[],
-  options?: { force?: boolean; fetchOptions?: RequestInit },
-) {}
+function registerRemotes(remotes: Remote[], options?: { force?: boolean }) {}
 
 type Remote = (RemoteWithEntry | RemoteWithVersion) & RemoteInfoCommon;
 
@@ -287,8 +284,6 @@ interface RemoteInfoCommon {
   shareScope?: string;
   type?: RemoteEntryType;
   entryGlobalName?: string;
-  // Custom request options (e.g. `headers`) used when loading this remote.
-  fetchOptions?: RequestInit;
 }
 
 interface RemoteWithEntry {
@@ -310,37 +305,42 @@ When `force: true` is set, the newly registered modules will overwrite already-r
 
 :::
 
-### Loading remotes with custom headers (`fetchOptions`)
+### Loading remotes with custom headers (the `fetch` hook)
 
-`fetchOptions` (a standard [`RequestInit`](https://developer.mozilla.org/en-US/docs/Web/API/RequestInit)) attaches custom HTTP options — most commonly `headers` such as `Authorization` — to the requests used to load a remote. It can be set per remote, or at the call level where it applies to every remote in that call. A remote's own `fetchOptions` is merged on top of the call-level one, and its `headers` win on conflict.
+Custom HTTP options — most commonly `headers` such as `Authorization` — are request behavior, so they are configured through the runtime [`fetch` hook](./runtime-hooks#fetch) rather than on remote registration. The hook receives the request URL, its `RequestInit`, and the target `remoteInfo`, so you can decide headers per remote and handle dynamic cases such as token refresh or per-request auth logic.
 
-This is supported for **`module` / `esm`** remotes: their manifest, remote entry, split chunks, shared dependencies, and manifest-declared CSS are loaded through a `fetch` + blob loader so the headers reach every asset request. Remotes without `fetchOptions` (and non-ESM remotes) are loaded as before — note that `<script>` / `<link>`-based loading cannot carry custom headers.
+For **`module` / `esm`** remotes, when a `fetch` hook is registered the remote entry and its manifest-declared CSS are loaded through a `fetch` + blob loader so the headers you add reach every asset request. The manifest request already flows through this hook. With no `fetch` hook registered, remotes load as before via native `import()` / `<link>` (which cannot carry custom headers).
 
 ```ts
 import { createInstance } from '@module-federation/enhanced/runtime';
 
-const mf = createInstance({ name: 'mf_host', remotes: [] });
-
-// Per remote
-mf.registerRemotes([
-  {
-    name: 'sub1',
-    entry: 'https://localhost:2001/mf-manifest.json',
-    type: 'module',
-    fetchOptions: { headers: { Authorization: `Bearer ${token}` } },
-  },
-]);
-
-// Call level — applies to every remote in this call
-mf.registerRemotes(
-  [{ name: 'sub2', entry: 'https://localhost:2002/mf-manifest.json', type: 'module' }],
-  { fetchOptions: { headers: { Authorization: `Bearer ${token}` } } },
-);
+const mf = createInstance({
+  name: 'mf_host',
+  remotes: [
+    {
+      name: 'sub1',
+      entry: 'https://localhost:2001/mf-manifest.json',
+      type: 'module',
+    },
+  ],
+  plugins: [
+    {
+      name: 'auth-fetch',
+      // `remoteInfo` lets you scope headers to specific remotes
+      fetch(url, init, remoteInfo) {
+        return fetch(url, {
+          ...init,
+          headers: { ...init.headers, Authorization: `Bearer ${token}` },
+        });
+      },
+    },
+  ],
+});
 ```
 
 :::info
 
-Native preload hints (`<link rel="modulepreload">` / `<link rel="preload">`) cannot carry headers, so they may fail on an authenticated origin; the actual module loads still go through the authenticated `fetch` loader. Authenticated CSS is injected directly and does not emit the `createLink` hook, so plugin-added `nonce`/SRI attributes are not applied to it.
+Native preload hints (`<link rel="modulepreload">` / `<link rel="preload">`) cannot carry headers, so they may fail on an authenticated origin; the actual module loads still go through the `fetch` hook. Authenticated CSS is injected directly and does not emit the `createLink` hook, so plugin-added `nonce`/SRI attributes are not applied to it.
 
 :::
 
diff --git a/apps/website-new/docs/en/guide/runtime/runtime-hooks.mdx b/apps/website-new/docs/en/guide/runtime/runtime-hooks.mdx
index f9a7d91a027..8242b379fcc 100644
--- a/apps/website-new/docs/en/guide/runtime/runtime-hooks.mdx
+++ b/apps/website-new/docs/en/guide/runtime/runtime-hooks.mdx
@@ -726,7 +726,7 @@ const changeScriptAttributePlugin: () => ModuleFederationRuntimePlugin =
 
 `AsyncHook`
 
-The `fetch` function allows customizing the request that fetches the manifest JSON. A successful `Response` must yield a valid JSON.
+The `fetch` function allows customizing the requests used to load a remote. It is always applied to the manifest JSON request (a successful `Response` must yield a valid JSON). If a `fetch` hook is registered, it is additionally applied to the remote entry and manifest-declared CSS of **`module` / `esm`** remotes, which are then loaded through a `fetch` + blob loader so custom `headers` (e.g. `Authorization`) can be applied those requests too.
 
 ```typescript
 function fetch(
diff --git a/apps/website-new/docs/zh/guide/runtime/runtime-api.mdx b/apps/website-new/docs/zh/guide/runtime/runtime-api.mdx
index e8854eaf053..3755b6833e6 100644
--- a/apps/website-new/docs/zh/guide/runtime/runtime-api.mdx
+++ b/apps/website-new/docs/zh/guide/runtime/runtime-api.mdx
@@ -275,10 +275,7 @@ if (targetInstance) {
 <Collapse>
 
 ```typescript
-function registerRemotes(
-  remotes: Remote[],
-  options?: { force?: boolean; fetchOptions?: RequestInit },
-) {}
+function registerRemotes(remotes: Remote[], options?: { force?: boolean }) {}
 
 type Remote = (RemoteWithEntry | RemoteWithVersion) & RemoteInfoCommon;
 
@@ -287,8 +284,6 @@ interface RemoteInfoCommon {
   shareScope?: string;
   type?: RemoteEntryType;
   entryGlobalName?: string;
-  // 加载该 remote 时使用的自定义请求配置（如 `headers`）。
-  fetchOptions?: RequestInit;
 }
 
 interface RemoteWithEntry {
@@ -310,37 +305,42 @@ interface RemoteWithVersion {
 
 :::
 
-### 使用自定义请求头加载 remote（`fetchOptions`）
+### 使用自定义请求头加载 remote（`fetch` 钩子）
 
-`fetchOptions`（标准的 [`RequestInit`](https://developer.mozilla.org/zh-CN/docs/Web/API/RequestInit)）用于为加载 remote 的请求附加自定义 HTTP 配置——最常见的是 `Authorization` 等 `headers`。它既可以设置在单个 remote 上，也可以设置在调用级别（对本次调用的所有 remote 生效）。单个 remote 自身的 `fetchOptions` 会与调用级别的合并，且在 `headers` 冲突时以前者为准。
+自定义 HTTP 配置——最常见的是 `Authorization` 等 `headers`——属于请求行为，因此通过运行时的 [`fetch` 钩子](./runtime-hooks#fetch) 配置，而不是在 remote 注册时配置。该钩子会接收请求 URL、对应的 `RequestInit` 以及目标 `remoteInfo`，因此你可以按 remote 决定请求头，并处理诸如 token 刷新、按请求鉴权等动态场景。
 
-该能力适用于 **`module` / `esm`** 类型的 remote：其 manifest、remote entry、分包 chunk、共享依赖以及 manifest 中声明的 CSS，都会通过 `fetch` + blob 加载器加载，从而让请求头能够作用到每一个资源请求上。未设置 `fetchOptions` 的 remote（以及非 ESM 的 remote）按原有方式加载——注意基于 `<script>` / `<link>` 的加载方式无法携带自定义请求头。
+对于 **`module` / `esm`** 类型的 remote：当注册了 `fetch` 钩子时，其 remote entry 以及 manifest 中声明的 CSS 会通过 `fetch` + blob 加载器加载，从而让你添加的请求头能够作用到每一个资源请求上。manifest 请求本身已经会走该钩子。未注册 `fetch` 钩子时，remote 仍按原有方式通过原生 `import()` / `<link>` 加载（这些方式无法携带自定义请求头）。
 
 ```ts
 import { createInstance } from '@module-federation/enhanced/runtime';
 
-const mf = createInstance({ name: 'mf_host', remotes: [] });
-
-// 单个 remote
-mf.registerRemotes([
-  {
-    name: 'sub1',
-    entry: 'https://localhost:2001/mf-manifest.json',
-    type: 'module',
-    fetchOptions: { headers: { Authorization: `Bearer ${token}` } },
-  },
-]);
-
-// 调用级别——对本次调用的所有 remote 生效
-mf.registerRemotes(
-  [{ name: 'sub2', entry: 'https://localhost:2002/mf-manifest.json', type: 'module' }],
-  { fetchOptions: { headers: { Authorization: `Bearer ${token}` } } },
-);
+const mf = createInstance({
+  name: 'mf_host',
+  remotes: [
+    {
+      name: 'sub1',
+      entry: 'https://localhost:2001/mf-manifest.json',
+      type: 'module',
+    },
+  ],
+  plugins: [
+    {
+      name: 'auth-fetch',
+      // 通过 `remoteInfo` 可将请求头限定到特定 remote
+      fetch(url, init, remoteInfo) {
+        return fetch(url, {
+          ...init,
+          headers: { ...init.headers, Authorization: `Bearer ${token}` },
+        });
+      },
+    },
+  ],
+});
 ```
 
 :::info
 
-原生的预加载提示（`<link rel="modulepreload">` / `<link rel="preload">`）无法携带请求头，因此在需要鉴权的源上可能会失败；但真正的模块加载仍会走带鉴权的 `fetch` 加载器。带鉴权的 CSS 是直接注入的，不会触发 `createLink` 钩子，因此插件添加的 `nonce`/SRI 属性不会作用于这类 CSS。
+原生的预加载提示（`<link rel="modulepreload">` / `<link rel="preload">`）无法携带请求头，因此在需要鉴权的源上可能会失败；但真正的模块加载仍会走 `fetch` 钩子。带鉴权的 CSS 是直接注入的，不会触发 `createLink` 钩子，因此插件添加的 `nonce`/SRI 属性不会作用于这类 CSS。
 
 :::
 
diff --git a/apps/website-new/docs/zh/guide/runtime/runtime-hooks.mdx b/apps/website-new/docs/zh/guide/runtime/runtime-hooks.mdx
index 9bcf3b87d6d..8efb156254c 100644
--- a/apps/website-new/docs/zh/guide/runtime/runtime-hooks.mdx
+++ b/apps/website-new/docs/zh/guide/runtime/runtime-hooks.mdx
@@ -687,7 +687,7 @@ const changeScriptAttributePlugin: () => ModuleFederationRuntimePlugin =
 
 `AsyncHook`
 
-`fetch` 函数允许自定义获取清单（manifest）JSON 的请求。成功的 `Response` 必须返回一个有效的 JSON。
+`fetch` 函数允许自定义加载 remote 时使用的请求。它始终会作用于清单（manifest）JSON 请求（成功的 `Response` 必须返回一个有效的 JSON）。当注册了 `fetch` 钩子时，它还会额外作用于 **`module` / `esm`** 类型 remote 的 remote entry 及 manifest 中声明的 CSS——这些资源会通过 `fetch` + blob 加载器加载，从而让自定义的 `headers`（如 `Authorization`）也能应用到这些请求上。
 
 ```typescript
 function fetch(
diff --git a/packages/runtime-core/__tests__/load-entry-fetch-hook.spec.ts b/packages/runtime-core/__tests__/load-entry-fetch-hook.spec.ts
new file mode 100644
index 00000000000..12704f74120
--- /dev/null
+++ b/packages/runtime-core/__tests__/load-entry-fetch-hook.spec.ts
@@ -0,0 +1,98 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import * as sdk from '@module-federation/sdk';
+import { __loadEntryDomForTest } from '../src/utils/load';
+
+// A loaderHook whose fetch lifecycle exposes a real `listeners` Set, matching
+// the runtime's SyncHook so load.ts can gate on `listeners.size`.
+function createLoaderHook(hasFetchListener: boolean) {
+  const listeners = new Set<any>();
+  if (hasFetchListener) {
+    listeners.add(() => undefined);
+  }
+  return {
+    lifecycle: {
+      fetch: { emit: vi.fn(), listeners },
+    },
+  } as any;
+}
+
+describe('loadEntryDom ESM fetch-hook gate', () => {
+  let loadEsmEntryWithFetch: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    // Spy on the sdk's blob loader. load.ts imports from the same module
+    // namespace, so spying here intercepts the call it makes.
+    loadEsmEntryWithFetch = vi
+      .spyOn(sdk, 'loadEsmEntryWithFetch')
+      .mockResolvedValue({ ok: 1 });
+  });
+
+  afterEach(() => {
+    loadEsmEntryWithFetch.mockRestore();
+  });
+
+  const remoteInfo = (name: string, entry: string): any => ({
+    name,
+    entry,
+    type: 'module',
+    entryGlobalName: name,
+    shareScope: 'default',
+  });
+
+  it('uses the blob loader for module remotes when a fetch hook is registered', async () => {
+    const loaderHook = createLoaderHook(true);
+    const resourceContext: any = {
+      initiator: 'loadRemote',
+      id: 'a/say',
+      resourceType: 'remoteEntry',
+    };
+    await __loadEntryDomForTest({
+      remoteInfo: remoteInfo('a', 'http://x/e.js'),
+      loaderHook,
+      resourceContext,
+    });
+    expect(loadEsmEntryWithFetch).toHaveBeenCalledWith(
+      expect.objectContaining({
+        entry: 'http://x/e.js',
+        customFetch: expect.any(Function),
+      }),
+    );
+    // The loader's customFetch routes through the fetch hook with remoteInfo and
+    // the resourceContext so the plugin can decide headers per remote/resource.
+    const { customFetch } = loadEsmEntryWithFetch.mock.calls[0][0] as any;
+    await customFetch('http://x/e.js', { headers: {} });
+    expect(loaderHook.lifecycle.fetch.emit).toHaveBeenCalledWith(
+      'http://x/e.js',
+      { headers: {} },
+      expect.objectContaining({ name: 'a' }),
+      resourceContext,
+    );
+  });
+
+  it('wraps blob loader failures as RUNTIME_008 so loadEntryError recovery can fire', async () => {
+    loadEsmEntryWithFetch.mockRejectedValueOnce(
+      new Error('BlobLoaderNetworkError: 401 Unauthorized for http://x/e.js'),
+    );
+    const err = await __loadEntryDomForTest({
+      remoteInfo: remoteInfo('a', 'http://x/e.js'),
+      loaderHook: createLoaderHook(true),
+    }).then(
+      () => undefined,
+      (e: unknown) => e,
+    );
+    expect(err).toBeInstanceOf(Error);
+    // RUNTIME_008 = 'RUNTIME-008'; getRemoteEntry keys recovery off this code.
+    expect((err as Error).message).toContain('RUNTIME-008');
+    // The original failure is preserved for diagnostics.
+    expect((err as Error).message).toContain('401 Unauthorized');
+  });
+
+  it('does NOT use the blob loader for module remotes when no fetch hook is registered', async () => {
+    await __loadEntryDomForTest({
+      remoteInfo: remoteInfo('b', 'http://x/e2.js'),
+      loaderHook: createLoaderHook(false),
+    }).catch(() => undefined);
+    expect(loadEsmEntryWithFetch).not.toHaveBeenCalled();
+  });
+});
diff --git a/packages/runtime-core/__tests__/load-entry-fetch-options.spec.ts b/packages/runtime-core/__tests__/load-entry-fetch-options.spec.ts
deleted file mode 100644
index 145393a0d3d..00000000000
--- a/packages/runtime-core/__tests__/load-entry-fetch-options.spec.ts
+++ /dev/null
@@ -1,76 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import * as sdk from '@module-federation/sdk';
-import { __loadEntryDomForTest } from '../src/utils/load';
-
-describe('loadEntryDom ESM fetchOptions gate', () => {
-  const loaderHook: any = { lifecycle: { fetch: { emit: vi.fn() } } };
-  let loadEsmEntryWithFetch: ReturnType<typeof vi.spyOn>;
-
-  beforeEach(() => {
-    vi.clearAllMocks();
-    // Spy on the sdk's blob loader. load.ts imports from the same module
-    // namespace, so spying here intercepts the call it makes.
-    loadEsmEntryWithFetch = vi
-      .spyOn(sdk, 'loadEsmEntryWithFetch')
-      .mockResolvedValue({ ok: 1 });
-  });
-
-  afterEach(() => {
-    loadEsmEntryWithFetch.mockRestore();
-  });
-
-  it('uses the blob loader for module remotes carrying fetchOptions', async () => {
-    const remoteInfo: any = {
-      name: 'a',
-      entry: 'http://x/e.js',
-      type: 'module',
-      entryGlobalName: 'a',
-      shareScope: 'default',
-      fetchOptions: { headers: { Authorization: 'Bearer t' } },
-    };
-    await __loadEntryDomForTest({ remoteInfo, loaderHook });
-    expect(loadEsmEntryWithFetch).toHaveBeenCalledWith(
-      expect.objectContaining({
-        entry: 'http://x/e.js',
-        fetchOptions: remoteInfo.fetchOptions,
-      }),
-    );
-  });
-
-  it('wraps blob loader failures as RUNTIME_008 so loadEntryError recovery can fire', async () => {
-    loadEsmEntryWithFetch.mockRejectedValueOnce(
-      new Error('BlobLoaderNetworkError: 401 Unauthorized for http://x/e.js'),
-    );
-    const remoteInfo: any = {
-      name: 'a',
-      entry: 'http://x/e.js',
-      type: 'module',
-      entryGlobalName: 'a',
-      shareScope: 'default',
-      fetchOptions: { headers: { Authorization: 'Bearer t' } },
-    };
-    const err = await __loadEntryDomForTest({ remoteInfo, loaderHook }).then(
-      () => undefined,
-      (e: unknown) => e,
-    );
-    expect(err).toBeInstanceOf(Error);
-    // RUNTIME_008 = 'RUNTIME-008'; getRemoteEntry keys recovery off this code.
-    expect((err as Error).message).toContain('RUNTIME-008');
-    // The original failure is preserved for diagnostics.
-    expect((err as Error).message).toContain('401 Unauthorized');
-  });
-
-  it('does NOT use the blob loader for module remotes without fetchOptions', async () => {
-    const remoteInfo: any = {
-      name: 'b',
-      entry: 'http://x/e2.js',
-      type: 'module',
-      entryGlobalName: 'b',
-      shareScope: 'default',
-    };
-    await __loadEntryDomForTest({ remoteInfo, loaderHook }).catch(
-      () => undefined,
-    );
-    expect(loadEsmEntryWithFetch).not.toHaveBeenCalled();
-  });
-});
diff --git a/packages/runtime-core/__tests__/manifest-fetch-hook.spec.ts b/packages/runtime-core/__tests__/manifest-fetch-hook.spec.ts
new file mode 100644
index 00000000000..b1a76c4b879
--- /dev/null
+++ b/packages/runtime-core/__tests__/manifest-fetch-hook.spec.ts
@@ -0,0 +1,47 @@
+import { describe, it, expect, vi, afterEach } from 'vitest';
+import { ModuleFederation } from '../src';
+import { resetFederationGlobalInfo } from '../src/global';
+
+describe('manifest fetch goes through the fetch hook with remoteInfo', () => {
+  afterEach(() => {
+    resetFederationGlobalInfo();
+    vi.restoreAllMocks();
+  });
+
+  // Header/auth customization is request behavior handled by the existing fetch
+  // hook: the manifest request is emitted through it with the remote's
+  // `remoteInfo`, so a plugin can attach headers (e.g. Authorization) per
+  // remote without any extra remote-registration config.
+  it('emits the manifest request with remoteInfo so a plugin can authenticate it', async () => {
+    const manifestUrl =
+      'http://localhost:1111/resources/snapshot/remote1/federation-manifest.json';
+
+    const mf = new ModuleFederation({
+      name: '@manifest-fetch-hook/host',
+      remotes: [],
+    });
+
+    const emitSpy = vi.spyOn(mf.loaderHook.lifecycle.fetch, 'emit');
+
+    mf.registerRemotes([
+      {
+        name: '@snapshot/remote1',
+        entry: manifestUrl,
+      },
+    ]);
+
+    await mf
+      .loadRemote<() => string>('@snapshot/remote1/say')
+      .catch(() => undefined);
+
+    const manifestCall = emitSpy.mock.calls.find(
+      (call) => typeof call[0] === 'string' && call[0] === manifestUrl,
+    );
+
+    expect(manifestCall).toBeTruthy();
+    // 3rd argument is remoteInfo for the remote being loaded — the hook keys
+    // its header/auth decisions off this.
+    expect((manifestCall?.[2] as any)?.name).toBe('@snapshot/remote1');
+    expect((manifestCall?.[2] as any)?.entry).toBe(manifestUrl);
+  });
+});
diff --git a/packages/runtime-core/__tests__/manifest-fetch-options.spec.ts b/packages/runtime-core/__tests__/manifest-fetch-options.spec.ts
deleted file mode 100644
index 5f98d681148..00000000000
--- a/packages/runtime-core/__tests__/manifest-fetch-options.spec.ts
+++ /dev/null
@@ -1,49 +0,0 @@
-import { describe, it, expect, vi, afterEach } from 'vitest';
-import { ModuleFederation } from '../src';
-import { resetFederationGlobalInfo } from '../src/global';
-
-describe('manifest fetch carries fetchOptions', () => {
-  afterEach(() => {
-    resetFederationGlobalInfo();
-    vi.restoreAllMocks();
-  });
-
-  it('passes the remote fetchOptions to the manifest fetch hook', async () => {
-    const fetchOptions: RequestInit = {
-      headers: { Authorization: 'Bearer token-123' },
-    };
-    const manifestUrl =
-      'http://localhost:1111/resources/snapshot/remote1/federation-manifest.json';
-
-    const mf = new ModuleFederation({
-      name: '@manifest-fetch-options/host',
-      remotes: [],
-    });
-
-    const emitSpy = vi.spyOn(mf.loaderHook.lifecycle.fetch, 'emit');
-
-    mf.registerRemotes(
-      [
-        {
-          name: '@snapshot/remote1',
-          entry: manifestUrl,
-        },
-      ],
-      { fetchOptions },
-    );
-
-    await mf
-      .loadRemote<() => string>('@snapshot/remote1/say')
-      .catch(() => undefined);
-
-    const manifestCall = emitSpy.mock.calls.find(
-      (call) => typeof call[0] === 'string' && call[0] === manifestUrl,
-    );
-
-    expect(manifestCall).toBeTruthy();
-    // 2nd argument is the request options threaded from the remote.
-    expect(manifestCall?.[1]).toEqual(fetchOptions);
-    // 3rd argument is remoteInfo, and should carry the fetchOptions too.
-    expect((manifestCall?.[2] as any)?.fetchOptions).toEqual(fetchOptions);
-  });
-});
diff --git a/packages/runtime-core/__tests__/preload-css-fetch-options.spec.ts b/packages/runtime-core/__tests__/preload-css-fetch-hook.spec.ts
similarity index 51%
rename from packages/runtime-core/__tests__/preload-css-fetch-options.spec.ts
rename to packages/runtime-core/__tests__/preload-css-fetch-hook.spec.ts
index 00a508bd610..8de3c6870eb 100644
--- a/packages/runtime-core/__tests__/preload-css-fetch-options.spec.ts
+++ b/packages/runtime-core/__tests__/preload-css-fetch-hook.spec.ts
@@ -2,7 +2,34 @@ import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import * as sdk from '@module-federation/sdk';
 import { preloadAssets } from '../src/utils/preload';
 
-describe('preloadAssets CSS with fetchOptions', () => {
+// Build a host whose fetch lifecycle exposes a real `listeners` Set so
+// preload.ts can gate the blob loader on `listeners.size`.
+function createHost(hasFetchListener: boolean): any {
+  const fetchListeners = new Set<any>();
+  if (hasFetchListener) {
+    fetchListeners.add(() => undefined);
+  }
+  return {
+    options: { inBrowser: true },
+    loaderHook: {
+      lifecycle: {
+        fetch: { emit: vi.fn(), listeners: fetchListeners },
+        createLink: { emit: vi.fn() },
+        createScript: { emit: vi.fn() },
+      },
+    },
+  };
+}
+
+const remoteInfo = (name: string): any => ({
+  name,
+  entry: 'http://x/e.js',
+  type: 'module',
+  entryGlobalName: name,
+  shareScope: 'default',
+});
+
+describe('preloadAssets CSS with a fetch hook', () => {
   let spy: any;
   beforeEach(() => {
     spy = vi.spyOn(sdk, 'loadCssWithFetch').mockResolvedValue(undefined as any);
@@ -12,46 +39,24 @@ describe('preloadAssets CSS with fetchOptions', () => {
     vi.clearAllMocks();
   });
 
-  it('routes manifest CSS through the blob loader when fetchOptions is set', async () => {
-    const remoteInfo: any = {
-      name: 'a',
-      entry: 'http://x/e.js',
-      type: 'module',
-      entryGlobalName: 'a',
-      shareScope: 'default',
-      fetchOptions: { headers: { Authorization: 'Bearer t' } },
-    };
-    const host: any = {
-      options: { inBrowser: true },
-      loaderHook: { lifecycle: { fetch: { emit: vi.fn() } } },
-    };
+  it('routes manifest CSS through the blob loader when a fetch hook is registered', async () => {
+    const host = createHost(true);
     const assets: any = {
       cssAssets: ['http://x/a.css'],
       jsAssetsWithoutEntry: [],
       entryAssets: [],
     };
-    await preloadAssets(remoteInfo, host, assets, false);
+    await preloadAssets(remoteInfo('a'), host, assets, false);
     expect(spy).toHaveBeenCalledWith(
       expect.objectContaining({
         href: 'http://x/a.css',
-        fetchOptions: remoteInfo.fetchOptions,
+        customFetch: expect.any(Function),
       }),
     );
   });
 
-  it('does NOT apply authenticated CSS during a preload hint (useLinkPreload)', async () => {
-    const remoteInfo: any = {
-      name: 'a',
-      entry: 'http://x/e.js',
-      type: 'module',
-      entryGlobalName: 'a',
-      shareScope: 'default',
-      fetchOptions: { headers: { Authorization: 'Bearer t' } },
-    };
-    const host: any = {
-      options: { inBrowser: true },
-      loaderHook: { lifecycle: { fetch: { emit: vi.fn() } } },
-    };
+  it('does NOT apply CSS through the blob loader during a preload hint (useLinkPreload)', async () => {
+    const host = createHost(true);
     const assets: any = {
       cssAssets: ['http://x/a.css'],
       jsAssetsWithoutEntry: [],
@@ -60,28 +65,12 @@ describe('preloadAssets CSS with fetchOptions', () => {
     // useLinkPreload defaults to true (preloadRemote). The blob loader injects a
     // rel=stylesheet that would apply the remote's CSS before it is loaded, so it
     // must be skipped here rather than overriding host styles.
-    await preloadAssets(remoteInfo, host, assets);
+    await preloadAssets(remoteInfo('a'), host, assets);
     expect(spy).not.toHaveBeenCalled();
   });
 
-  it('does NOT use the blob loader when fetchOptions is absent', async () => {
-    const remoteInfo: any = {
-      name: 'b',
-      entry: 'http://x/e.js',
-      type: 'module',
-      entryGlobalName: 'b',
-      shareScope: 'default',
-    };
-    const host: any = {
-      options: { inBrowser: true },
-      loaderHook: {
-        lifecycle: {
-          fetch: { emit: vi.fn() },
-          createLink: { emit: vi.fn() },
-          createScript: { emit: vi.fn() },
-        },
-      },
-    };
+  it('does NOT use the blob loader when no fetch hook is registered', async () => {
+    const host = createHost(false);
     const assets: any = {
       cssAssets: ['http://x/b.css'],
       jsAssetsWithoutEntry: [],
@@ -100,7 +89,7 @@ describe('preloadAssets CSS with fetchOptions', () => {
     });
     observer.observe(document.head, { childList: true });
     try {
-      await preloadAssets(remoteInfo, host, assets, false);
+      await preloadAssets(remoteInfo('b'), host, assets, false);
     } finally {
       observer.disconnect();
     }
diff --git a/packages/runtime-core/__tests__/register-remotes.spec.ts b/packages/runtime-core/__tests__/register-remotes.spec.ts
index 5316fbbe222..c7789536191 100644
--- a/packages/runtime-core/__tests__/register-remotes.spec.ts
+++ b/packages/runtime-core/__tests__/register-remotes.spec.ts
@@ -209,44 +209,4 @@ describe('ModuleFederation', () => {
     expect(await nextAppModule()).toBe('hello world "@snapshot/remote2"');
     expect(manifestFetch).toHaveBeenCalledTimes(2);
   });
-  it('merges call-level fetchOptions with each remote (remote wins on conflict)', () => {
-    const FM = new ModuleFederation({
-      name: '@federation/instance',
-      version: '1.0.1',
-      remotes: [],
-    });
-    const fetchOptions: RequestInit = {
-      headers: { Authorization: 'Bearer t' },
-    };
-    // No own fetchOptions: gets the call-level defaults.
-    const r1 = {
-      name: '@register-remotes/fetch-a',
-      entry: 'http://localhost:1111/resources/register-remotes/app1/a.js',
-    };
-    // Own header added: merged on top of the call-level Authorization.
-    const r2 = {
-      name: '@register-remotes/fetch-b',
-      entry: 'http://localhost:1111/resources/register-remotes/app1/b.js',
-      fetchOptions: { headers: { 'X-B': '1' } } as RequestInit,
-    };
-    // Own header conflicts with the call-level one: remote wins.
-    const r3 = {
-      name: '@register-remotes/fetch-c',
-      entry: 'http://localhost:1111/resources/register-remotes/app1/c.js',
-      fetchOptions: {
-        headers: { Authorization: 'Bearer override' },
-      } as RequestInit,
-    };
-    FM.registerRemotes([r1, r2, r3], { fetchOptions });
-    const stored = FM.options.remotes;
-    expect(
-      stored.find((r) => r.name === '@register-remotes/fetch-a')!.fetchOptions,
-    ).toEqual({ headers: { Authorization: 'Bearer t' } });
-    expect(
-      stored.find((r) => r.name === '@register-remotes/fetch-b')!.fetchOptions,
-    ).toEqual({ headers: { Authorization: 'Bearer t', 'X-B': '1' } });
-    expect(
-      stored.find((r) => r.name === '@register-remotes/fetch-c')!.fetchOptions,
-    ).toEqual({ headers: { Authorization: 'Bearer override' } });
-  });
 });
diff --git a/packages/runtime-core/src/core.ts b/packages/runtime-core/src/core.ts
index c8e45bc13f2..df09129a9a0 100644
--- a/packages/runtime-core/src/core.ts
+++ b/packages/runtime-core/src/core.ts
@@ -455,10 +455,7 @@ export class ModuleFederation {
       return res;
     }, pluginRes || []);
   }
-  registerRemotes(
-    remotes: Remote[],
-    options?: { force?: boolean; fetchOptions?: RequestInit },
-  ): void {
+  registerRemotes(remotes: Remote[], options?: { force?: boolean }): void {
     return this.remoteHandler.registerRemotes(remotes, options);
   }
 
diff --git a/packages/runtime-core/src/plugins/snapshot/SnapshotHandler.ts b/packages/runtime-core/src/plugins/snapshot/SnapshotHandler.ts
index 24fad89c3c8..e3661cfdbf7 100644
--- a/packages/runtime-core/src/plugins/snapshot/SnapshotHandler.ts
+++ b/packages/runtime-core/src/plugins/snapshot/SnapshotHandler.ts
@@ -306,7 +306,7 @@ export class SnapshotHandler {
       try {
         let res = await this.loaderHook.lifecycle.fetch.emit(
           manifestUrl,
-          remoteInfo.fetchOptions ?? {},
+          {},
           remoteInfo,
           resourceOptions
             ? {
@@ -317,7 +317,7 @@ export class SnapshotHandler {
             : undefined,
         );
         if (!res || !(res instanceof Response)) {
-          res = await fetch(manifestUrl, remoteInfo.fetchOptions ?? {});
+          res = await fetch(manifestUrl, {});
         }
         manifestJson = (await res.json()) as Manifest;
       } catch (err) {
diff --git a/packages/runtime-core/src/remote/index.ts b/packages/runtime-core/src/remote/index.ts
index 9fb4145ab96..1704e41d5f7 100644
--- a/packages/runtime-core/src/remote/index.ts
+++ b/packages/runtime-core/src/remote/index.ts
@@ -4,7 +4,6 @@ import {
   composeKeyWithSeparator,
   ModuleInfo,
   GlobalModuleInfo,
-  toHeaderObject,
 } from '@module-federation/sdk';
 import { RUNTIME_004, runtimeDescMap } from '@module-federation/error-codes';
 import {
@@ -50,23 +49,6 @@ import { formatPreloadArgs, preloadAssets } from '../utils/preload';
 import { getGlobalShareScope } from '../utils/share';
 import { getGlobalRemoteInfo } from '../plugins/snapshot/SnapshotHandler';
 
-// Merge call-level fetchOptions (defaults) with a remote's own (overrides).
-// Non-header fields shallow-merge with the remote winning; headers merge
-// per-key so a remote adding one header doesn't drop the call-level ones.
-function mergeFetchOptions(
-  base: RequestInit,
-  override: RequestInit | undefined,
-): RequestInit {
-  return {
-    ...base,
-    ...(override ?? {}),
-    headers: {
-      ...toHeaderObject(base.headers),
-      ...toHeaderObject(override?.headers),
-    },
-  };
-}
-
 export interface LoadRemoteMatch {
   id: string;
   pkgNameOrAlias: string;
@@ -518,21 +500,9 @@ export class RemoteHandler {
     }
   }
 
-  registerRemotes(
-    remotes: Remote[],
-    options?: { force?: boolean; fetchOptions?: RequestInit },
-  ): void {
+  registerRemotes(remotes: Remote[], options?: { force?: boolean }): void {
     const { host } = this;
     remotes.forEach((remote) => {
-      // Call-level fetchOptions act as defaults for every remote in this call;
-      // a remote's own fetchOptions are merged on top and win on conflict
-      // (headers are merged per-key, not replaced wholesale).
-      if (options?.fetchOptions) {
-        remote.fetchOptions = mergeFetchOptions(
-          options.fetchOptions,
-          remote.fetchOptions,
-        );
-      }
       this.registerRemote(remote, host.options.remotes, {
         force: options?.force,
       });
diff --git a/packages/runtime-core/src/type/config.ts b/packages/runtime-core/src/type/config.ts
index 1dcb3ac1d3a..98c6c357bbf 100644
--- a/packages/runtime-core/src/type/config.ts
+++ b/packages/runtime-core/src/type/config.ts
@@ -17,7 +17,6 @@ export interface RemoteInfoCommon {
   shareScope?: string | string[];
   type?: RemoteEntryType;
   entryGlobalName?: string;
-  fetchOptions?: RequestInit;
 }
 
 export type RemoteInfoOptionalVersion = {
@@ -41,7 +40,6 @@ export interface RemoteInfo {
   type: RemoteEntryType;
   entryGlobalName: string;
   shareScope: string | string[];
-  fetchOptions?: RequestInit;
 }
 
 export type HostInfo = Pick<
diff --git a/packages/runtime-core/src/utils/load.ts b/packages/runtime-core/src/utils/load.ts
index 96ce92607bd..b12e6ed9bd0 100644
--- a/packages/runtime-core/src/utils/load.ts
+++ b/packages/runtime-core/src/utils/load.ts
@@ -204,17 +204,16 @@ async function loadEntryDom({
   switch (type) {
     case 'esm':
     case 'module':
-      return remoteInfo.fetchOptions
+      return loaderHook.lifecycle.fetch.listeners.size > 0
         ? (loadEsmEntryWithFetch({
             entry,
-            fetchOptions: remoteInfo.fetchOptions,
-            // Route the loader's fetches through the runtime fetch hook so
-            // existing fetch-hook plugins still compose; merged headers are
-            // applied inside the sdk loader, native fetch is the fallback.
-            // The async arrow flattens the hook's nested-promise return to the
-            // Response | void | false shape the sdk loader expects.
             customFetch: async (url, init) =>
-              loaderHook.lifecycle.fetch.emit(url, init, remoteInfo),
+              loaderHook.lifecycle.fetch.emit(
+                url,
+                init,
+                remoteInfo,
+                resourceContext,
+              ),
           }).catch((loadError: unknown) => {
             // Mirror loadEntryScript: surface blob-loader fetch/exec failures
             // (e.g. BlobLoaderNetworkError on a 401) as RUNTIME_008 so
diff --git a/packages/runtime-core/src/utils/preload.ts b/packages/runtime-core/src/utils/preload.ts
index f9001b39d04..10f7962e64b 100644
--- a/packages/runtime-core/src/utils/preload.ts
+++ b/packages/runtime-core/src/utils/preload.ts
@@ -186,9 +186,9 @@ function waitForLinkPreload({
   });
 }
 
-// When the remote carries fetchOptions, CSS must be fetched WITH headers and
-// injected as a blob <link> — a native <link href> cannot carry headers, and a
-// rel=preload hint would 401.
+// When a fetch hook is present it may modify request headers, so CSS must be
+// fetched through it and injected as a blob. A native <link href> cannot carry
+// headers, and a rel=preload hint would 401 on an authenticated origin.
 function waitForCssFetch({
   host,
   remoteInfo,
@@ -202,9 +202,8 @@ function waitForCssFetch({
 }): Promise<PreloadAssetResult> {
   return loadCssWithFetch({
     href: url,
-    fetchOptions: remoteInfo.fetchOptions,
     customFetch: async (u, init) =>
-      host.loaderHook.lifecycle.fetch.emit(u, init, remoteInfo),
+      host.loaderHook.lifecycle.fetch.emit(u, init, remoteInfo, context),
   })
     .then(() => createAssetResult(context, url, 'success'))
     .catch((error) =>
@@ -298,16 +297,11 @@ export function preloadAssets(
   if (host.options.inBrowser) {
     entryAssets.forEach((asset) => {
       const { moduleInfo: entryRemoteInfo } = asset;
-      const entryRemoteInfoWithAuth =
-        // Respect fetchOptions added to entryRemoteInfo via generatePreloadAssetsPlugin.
-        !entryRemoteInfo.fetchOptions && remoteInfo.fetchOptions
-          ? { ...entryRemoteInfo, fetchOptions: remoteInfo.fetchOptions }
-          : entryRemoteInfo;
       results.push(
         waitForRemoteEntryPreload(
           host,
           remoteInfo,
-          entryRemoteInfoWithAuth,
+          entryRemoteInfo,
           createResourceContext(baseContext, 'remoteEntry'),
         ),
       );
@@ -317,11 +311,12 @@ export function preloadAssets(
     const pushCssAsset = (cssUrl: string) => {
       const context = createResourceContext(baseContext, 'css');
 
-      // Authenticated CSS: fetch WITH headers and inject as a blob stylesheet
+      // Authenticated CSS: when a fetch hook is present it can add headers per
+      // remoteInfo, so fetch through it and inject as a blob stylesheet.
       // We should only do that on an actual load because
       // 1. native rel=preload can't carry headers so we must skip it
       // 2. applying the remote's CSS in preload might override host styles before remote module is loaded
-      if (remoteInfo.fetchOptions) {
+      if (host.loaderHook.lifecycle.fetch.listeners.size > 0) {
         if (!useLinkPreload) {
           results.push(
             waitForCssFetch({ host, remoteInfo, url: cssUrl, context }),

From 090f1531c866d2df0444d4e22bdb65432dbd3f20 Mon Sep 17 00:00:00 2001
From: Shaoyu Meng <shaoyumeng@shaoyus-mbp-5.lan>
Date: Mon, 22 Jun 2026 18:39:38 -0700
Subject: [PATCH 27/34] test(runtime-core): drop manifest-fetch-hook spec
 covering pre-existing behavior
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The test only asserted that the manifest request is emitted through the fetch
hook with remoteInfo as the 3rd arg — behavior that predates this branch (it
was already in place at v2.5.0) and that the test never inspected the init arg
this branch actually touched. It guarded no code introduced here, so remove it.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../__tests__/manifest-fetch-hook.spec.ts     | 47 -------------------
 1 file changed, 47 deletions(-)
 delete mode 100644 packages/runtime-core/__tests__/manifest-fetch-hook.spec.ts

diff --git a/packages/runtime-core/__tests__/manifest-fetch-hook.spec.ts b/packages/runtime-core/__tests__/manifest-fetch-hook.spec.ts
deleted file mode 100644
index b1a76c4b879..00000000000
--- a/packages/runtime-core/__tests__/manifest-fetch-hook.spec.ts
+++ /dev/null
@@ -1,47 +0,0 @@
-import { describe, it, expect, vi, afterEach } from 'vitest';
-import { ModuleFederation } from '../src';
-import { resetFederationGlobalInfo } from '../src/global';
-
-describe('manifest fetch goes through the fetch hook with remoteInfo', () => {
-  afterEach(() => {
-    resetFederationGlobalInfo();
-    vi.restoreAllMocks();
-  });
-
-  // Header/auth customization is request behavior handled by the existing fetch
-  // hook: the manifest request is emitted through it with the remote's
-  // `remoteInfo`, so a plugin can attach headers (e.g. Authorization) per
-  // remote without any extra remote-registration config.
-  it('emits the manifest request with remoteInfo so a plugin can authenticate it', async () => {
-    const manifestUrl =
-      'http://localhost:1111/resources/snapshot/remote1/federation-manifest.json';
-
-    const mf = new ModuleFederation({
-      name: '@manifest-fetch-hook/host',
-      remotes: [],
-    });
-
-    const emitSpy = vi.spyOn(mf.loaderHook.lifecycle.fetch, 'emit');
-
-    mf.registerRemotes([
-      {
-        name: '@snapshot/remote1',
-        entry: manifestUrl,
-      },
-    ]);
-
-    await mf
-      .loadRemote<() => string>('@snapshot/remote1/say')
-      .catch(() => undefined);
-
-    const manifestCall = emitSpy.mock.calls.find(
-      (call) => typeof call[0] === 'string' && call[0] === manifestUrl,
-    );
-
-    expect(manifestCall).toBeTruthy();
-    // 3rd argument is remoteInfo for the remote being loaded — the hook keys
-    // its header/auth decisions off this.
-    expect((manifestCall?.[2] as any)?.name).toBe('@snapshot/remote1');
-    expect((manifestCall?.[2] as any)?.entry).toBe(manifestUrl);
-  });
-});

From 72d432c00588a6991443a48f29d71597cc4dfc16 Mon Sep 17 00:00:00 2001
From: Shaoyu Meng <shaoyumeng@shaoyus-mbp-5.lan>
Date: Mon, 22 Jun 2026 19:56:13 -0700
Subject: [PATCH 28/34] test(runtime-core): tidy fetch-hook spec naming and
 helpers

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../__tests__/load-entry-fetch-hook.spec.ts   | 36 ++++++-------
 .../__tests__/preload-css-fetch-hook.spec.ts  | 52 ++++++++++---------
 2 files changed, 46 insertions(+), 42 deletions(-)

diff --git a/packages/runtime-core/__tests__/load-entry-fetch-hook.spec.ts b/packages/runtime-core/__tests__/load-entry-fetch-hook.spec.ts
index 12704f74120..9a3503cdff2 100644
--- a/packages/runtime-core/__tests__/load-entry-fetch-hook.spec.ts
+++ b/packages/runtime-core/__tests__/load-entry-fetch-hook.spec.ts
@@ -2,8 +2,7 @@ import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import * as sdk from '@module-federation/sdk';
 import { __loadEntryDomForTest } from '../src/utils/load';
 
-// A loaderHook whose fetch lifecycle exposes a real `listeners` Set, matching
-// the runtime's SyncHook so load.ts can gate on `listeners.size`.
+// Create a mocked fetch lifecycle loader hook
 function createLoaderHook(hasFetchListener: boolean) {
   const listeners = new Set<any>();
   if (hasFetchListener) {
@@ -16,13 +15,22 @@ function createLoaderHook(hasFetchListener: boolean) {
   } as any;
 }
 
-describe('loadEntryDom ESM fetch-hook gate', () => {
+// Create a mocked remote info
+function createRemoteInfo(name: string, entry: string) {
+  return {
+    name,
+    entry,
+    type: 'module',
+    entryGlobalName: name,
+    shareScope: 'default',
+  };
+}
+
+describe('loadEntryDom ESM with fetch lifecycle loader hook', () => {
   let loadEsmEntryWithFetch: ReturnType<typeof vi.spyOn>;
 
   beforeEach(() => {
     vi.clearAllMocks();
-    // Spy on the sdk's blob loader. load.ts imports from the same module
-    // namespace, so spying here intercepts the call it makes.
     loadEsmEntryWithFetch = vi
       .spyOn(sdk, 'loadEsmEntryWithFetch')
       .mockResolvedValue({ ok: 1 });
@@ -32,14 +40,6 @@ describe('loadEntryDom ESM fetch-hook gate', () => {
     loadEsmEntryWithFetch.mockRestore();
   });
 
-  const remoteInfo = (name: string, entry: string): any => ({
-    name,
-    entry,
-    type: 'module',
-    entryGlobalName: name,
-    shareScope: 'default',
-  });
-
   it('uses the blob loader for module remotes when a fetch hook is registered', async () => {
     const loaderHook = createLoaderHook(true);
     const resourceContext: any = {
@@ -48,7 +48,7 @@ describe('loadEntryDom ESM fetch-hook gate', () => {
       resourceType: 'remoteEntry',
     };
     await __loadEntryDomForTest({
-      remoteInfo: remoteInfo('a', 'http://x/e.js'),
+      remoteInfo: createRemoteInfo('a', 'http://x/e.js'),
       loaderHook,
       resourceContext,
     });
@@ -58,8 +58,8 @@ describe('loadEntryDom ESM fetch-hook gate', () => {
         customFetch: expect.any(Function),
       }),
     );
-    // The loader's customFetch routes through the fetch hook with remoteInfo and
-    // the resourceContext so the plugin can decide headers per remote/resource.
+    // The loader's customFetch accepts remoteInfo and resourceContext as
+    // additional arguments so the plugin can add different headers per remote/resource.
     const { customFetch } = loadEsmEntryWithFetch.mock.calls[0][0] as any;
     await customFetch('http://x/e.js', { headers: {} });
     expect(loaderHook.lifecycle.fetch.emit).toHaveBeenCalledWith(
@@ -75,7 +75,7 @@ describe('loadEntryDom ESM fetch-hook gate', () => {
       new Error('BlobLoaderNetworkError: 401 Unauthorized for http://x/e.js'),
     );
     const err = await __loadEntryDomForTest({
-      remoteInfo: remoteInfo('a', 'http://x/e.js'),
+      remoteInfo: createRemoteInfo('a', 'http://x/e.js'),
       loaderHook: createLoaderHook(true),
     }).then(
       () => undefined,
@@ -90,7 +90,7 @@ describe('loadEntryDom ESM fetch-hook gate', () => {
 
   it('does NOT use the blob loader for module remotes when no fetch hook is registered', async () => {
     await __loadEntryDomForTest({
-      remoteInfo: remoteInfo('b', 'http://x/e2.js'),
+      remoteInfo: createRemoteInfo('b', 'http://x/e2.js'),
       loaderHook: createLoaderHook(false),
     }).catch(() => undefined);
     expect(loadEsmEntryWithFetch).not.toHaveBeenCalled();
diff --git a/packages/runtime-core/__tests__/preload-css-fetch-hook.spec.ts b/packages/runtime-core/__tests__/preload-css-fetch-hook.spec.ts
index 8de3c6870eb..9ccae00fec4 100644
--- a/packages/runtime-core/__tests__/preload-css-fetch-hook.spec.ts
+++ b/packages/runtime-core/__tests__/preload-css-fetch-hook.spec.ts
@@ -2,26 +2,26 @@ import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
 import * as sdk from '@module-federation/sdk';
 import { preloadAssets } from '../src/utils/preload';
 
-// Build a host whose fetch lifecycle exposes a real `listeners` Set so
-// preload.ts can gate the blob loader on `listeners.size`.
-function createHost(hasFetchListener: boolean): any {
-  const fetchListeners = new Set<any>();
+// Create a mocked fetch lifecycle loader hook
+function createLoaderHook(hasFetchListener: boolean) {
+  const listeners = new Set<any>();
   if (hasFetchListener) {
-    fetchListeners.add(() => undefined);
+    listeners.add(() => undefined);
   }
   return {
     options: { inBrowser: true },
     loaderHook: {
       lifecycle: {
-        fetch: { emit: vi.fn(), listeners: fetchListeners },
+        fetch: { emit: vi.fn(), listeners },
         createLink: { emit: vi.fn() },
         createScript: { emit: vi.fn() },
       },
     },
-  };
+  } as any;
 }
 
-const remoteInfo = (name: string): any => ({
+// Create a mocked remote info
+const createRemoteInfo = (name: string): any => ({
   name,
   entry: 'http://x/e.js',
   type: 'module',
@@ -29,25 +29,29 @@ const remoteInfo = (name: string): any => ({
   shareScope: 'default',
 });
 
-describe('preloadAssets CSS with a fetch hook', () => {
-  let spy: any;
+describe('preloadAssets CSS with fetch lifecycle loader hook', () => {
+  let loadCssWithFetch: ReturnType<typeof vi.spyOn>;
+
   beforeEach(() => {
-    spy = vi.spyOn(sdk, 'loadCssWithFetch').mockResolvedValue(undefined as any);
+    vi.clearAllMocks();
+    loadCssWithFetch = vi
+      .spyOn(sdk, 'loadCssWithFetch')
+      .mockResolvedValue(undefined as any);
   });
+
   afterEach(() => {
-    spy.mockRestore();
-    vi.clearAllMocks();
+    loadCssWithFetch.mockRestore();
   });
 
-  it('routes manifest CSS through the blob loader when a fetch hook is registered', async () => {
-    const host = createHost(true);
+  it('uses the blob loader for manifest CSS when a fetch hook is registered', async () => {
+    const host = createLoaderHook(true);
     const assets: any = {
       cssAssets: ['http://x/a.css'],
       jsAssetsWithoutEntry: [],
       entryAssets: [],
     };
-    await preloadAssets(remoteInfo('a'), host, assets, false);
-    expect(spy).toHaveBeenCalledWith(
+    await preloadAssets(createRemoteInfo('a'), host, assets, false);
+    expect(loadCssWithFetch).toHaveBeenCalledWith(
       expect.objectContaining({
         href: 'http://x/a.css',
         customFetch: expect.any(Function),
@@ -56,7 +60,7 @@ describe('preloadAssets CSS with a fetch hook', () => {
   });
 
   it('does NOT apply CSS through the blob loader during a preload hint (useLinkPreload)', async () => {
-    const host = createHost(true);
+    const host = createLoaderHook(true);
     const assets: any = {
       cssAssets: ['http://x/a.css'],
       jsAssetsWithoutEntry: [],
@@ -65,12 +69,12 @@ describe('preloadAssets CSS with a fetch hook', () => {
     // useLinkPreload defaults to true (preloadRemote). The blob loader injects a
     // rel=stylesheet that would apply the remote's CSS before it is loaded, so it
     // must be skipped here rather than overriding host styles.
-    await preloadAssets(remoteInfo('a'), host, assets);
-    expect(spy).not.toHaveBeenCalled();
+    await preloadAssets(createRemoteInfo('a'), host, assets);
+    expect(loadCssWithFetch).not.toHaveBeenCalled();
   });
 
-  it('does NOT use the blob loader when no fetch hook is registered', async () => {
-    const host = createHost(false);
+  it('does NOT use the blob loader for manifest CSS when no fetch hook is registered', async () => {
+    const host = createLoaderHook(false);
     const assets: any = {
       cssAssets: ['http://x/b.css'],
       jsAssetsWithoutEntry: [],
@@ -89,10 +93,10 @@ describe('preloadAssets CSS with a fetch hook', () => {
     });
     observer.observe(document.head, { childList: true });
     try {
-      await preloadAssets(remoteInfo('b'), host, assets, false);
+      await preloadAssets(createRemoteInfo('b'), host, assets, false);
     } finally {
       observer.disconnect();
     }
-    expect(spy).not.toHaveBeenCalled();
+    expect(loadCssWithFetch).not.toHaveBeenCalled();
   });
 });

From d06e3bf40f5ae565a0c08bc5fa12ffed53a07ea8 Mon Sep 17 00:00:00 2001
From: Shaoyu Meng <shaoyumeng@Shaoyus-MacBook-Pro-5.local>
Date: Mon, 22 Jun 2026 21:22:12 -0700
Subject: [PATCH 29/34] docs(runtime): simplify fetch-hook header docs in en
 and zh

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 apps/website-new/docs/en/guide/runtime/runtime-api.mdx | 10 +++++-----
 .../docs/en/guide/runtime/runtime-hooks.mdx            |  3 ++-
 apps/website-new/docs/zh/guide/runtime/runtime-api.mdx | 10 +++++-----
 .../docs/zh/guide/runtime/runtime-hooks.mdx            |  3 ++-
 4 files changed, 14 insertions(+), 12 deletions(-)

diff --git a/apps/website-new/docs/en/guide/runtime/runtime-api.mdx b/apps/website-new/docs/en/guide/runtime/runtime-api.mdx
index ba9a6e986f2..e48b74dce80 100644
--- a/apps/website-new/docs/en/guide/runtime/runtime-api.mdx
+++ b/apps/website-new/docs/en/guide/runtime/runtime-api.mdx
@@ -305,11 +305,11 @@ When `force: true` is set, the newly registered modules will overwrite already-r
 
 :::
 
-### Loading remotes with custom headers (the `fetch` hook)
+### Loading remotes with custom headers via the `fetch` hook
 
-Custom HTTP options — most commonly `headers` such as `Authorization` — are request behavior, so they are configured through the runtime [`fetch` hook](./runtime-hooks#fetch) rather than on remote registration. The hook receives the request URL, its `RequestInit`, and the target `remoteInfo`, so you can decide headers per remote and handle dynamic cases such as token refresh or per-request auth logic.
+Some remotes require specific headers to be accessed. In that case you can configure the headers through the runtime [`fetch` hook](./runtime-hooks#fetch). You can handle dynamic cases such as token refresh or per-request auth logic inside this hook.
 
-For **`module` / `esm`** remotes, when a `fetch` hook is registered the remote entry and its manifest-declared CSS are loaded through a `fetch` + blob loader so the headers you add reach every asset request. The manifest request already flows through this hook. With no `fetch` hook registered, remotes load as before via native `import()` / `<link>` (which cannot carry custom headers).
+For **`module` / `esm`** remotes, when a `fetch` hook is registered the remote entry and its manifest-declared CSS are loaded through a `fetch` + blob loader so the headers you add reach every asset request. With no `fetch` hook registered, remotes load as before via native `import()` / `<link>` (which cannot carry custom headers).
 
 ```ts
 import { createInstance } from '@module-federation/enhanced/runtime';
@@ -326,7 +326,7 @@ const mf = createInstance({
   plugins: [
     {
       name: 'auth-fetch',
-      // `remoteInfo` lets you scope headers to specific remotes
+      // `remoteInfo` lets you use different request options for specific remotes
       fetch(url, init, remoteInfo) {
         return fetch(url, {
           ...init,
@@ -340,7 +340,7 @@ const mf = createInstance({
 
 :::info
 
-Native preload hints (`<link rel="modulepreload">` / `<link rel="preload">`) cannot carry headers, so they may fail on an authenticated origin; the actual module loads still go through the `fetch` hook. Authenticated CSS is injected directly and does not emit the `createLink` hook, so plugin-added `nonce`/SRI attributes are not applied to it.
+Native preload hints (`<link rel="modulepreload">` / `<link rel="preload">`) cannot carry headers, so they may fail on an authenticated origin; the actual loads still go through the `fetch` hook when the asset is used. Authenticated CSS is injected directly and does not emit the `createLink` hook, so plugin-added `nonce`/SRI attributes are not applied to it.
 
 :::
 
diff --git a/apps/website-new/docs/en/guide/runtime/runtime-hooks.mdx b/apps/website-new/docs/en/guide/runtime/runtime-hooks.mdx
index 8242b379fcc..165463a8497 100644
--- a/apps/website-new/docs/en/guide/runtime/runtime-hooks.mdx
+++ b/apps/website-new/docs/en/guide/runtime/runtime-hooks.mdx
@@ -726,7 +726,8 @@ const changeScriptAttributePlugin: () => ModuleFederationRuntimePlugin =
 
 `AsyncHook`
 
-The `fetch` function allows customizing the requests used to load a remote. It is always applied to the manifest JSON request (a successful `Response` must yield a valid JSON). If a `fetch` hook is registered, it is additionally applied to the remote entry and manifest-declared CSS of **`module` / `esm`** remotes, which are then loaded through a `fetch` + blob loader so custom `headers` (e.g. `Authorization`) can be applied those requests too.
+The `fetch` function allows customizing the request used to fetch the manifest JSON; a successfully loaded manifest `Response` must yield a valid JSON.
+You can also use the `fetch` function to apply custom `headers` (e.g. `Authorization`) to the remote entry and manifest-declared CSS resources of **`module` / `esm`** remotes.
 
 ```typescript
 function fetch(
diff --git a/apps/website-new/docs/zh/guide/runtime/runtime-api.mdx b/apps/website-new/docs/zh/guide/runtime/runtime-api.mdx
index 3755b6833e6..3be611634e8 100644
--- a/apps/website-new/docs/zh/guide/runtime/runtime-api.mdx
+++ b/apps/website-new/docs/zh/guide/runtime/runtime-api.mdx
@@ -305,11 +305,11 @@ interface RemoteWithVersion {
 
 :::
 
-### 使用自定义请求头加载 remote（`fetch` 钩子）
+### 通过 fetch 钩子使用自定义请求头加载 remote
 
-自定义 HTTP 配置——最常见的是 `Authorization` 等 `headers`——属于请求行为，因此通过运行时的 [`fetch` 钩子](./runtime-hooks#fetch) 配置，而不是在 remote 注册时配置。该钩子会接收请求 URL、对应的 `RequestInit` 以及目标 `remoteInfo`，因此你可以按 remote 决定请求头，并处理诸如 token 刷新、按请求鉴权等动态场景。
+某些 remote 需要特定的请求头才能访问，此时可以通过运行时的 [`fetch` 钩子](./runtime-hooks#fetch) 配置请求头。你可以在该钩子中处理诸如 token 刷新、按请求鉴权等动态场景。
 
-对于 **`module` / `esm`** 类型的 remote：当注册了 `fetch` 钩子时，其 remote entry 以及 manifest 中声明的 CSS 会通过 `fetch` + blob 加载器加载，从而让你添加的请求头能够作用到每一个资源请求上。manifest 请求本身已经会走该钩子。未注册 `fetch` 钩子时，remote 仍按原有方式通过原生 `import()` / `<link>` 加载（这些方式无法携带自定义请求头）。
+对于 **`module` / `esm`** 类型的 remote：当注册了 `fetch` 钩子时，其 remote entry 以及 manifest 中声明的 CSS 都会通过 `fetch` + blob 加载器加载，从而让你添加的请求头能够应用到每一个资源请求上。未注册 `fetch` 钩子时，remote 仍按原有方式通过原生 `import()` / `<link>` 加载（这些方式无法携带自定义请求头）。
 
 ```ts
 import { createInstance } from '@module-federation/enhanced/runtime';
@@ -326,7 +326,7 @@ const mf = createInstance({
   plugins: [
     {
       name: 'auth-fetch',
-      // 通过 `remoteInfo` 可将请求头限定到特定 remote
+      // 可通过 `remoteInfo` 对特定 remote 使用不同的请求配置
       fetch(url, init, remoteInfo) {
         return fetch(url, {
           ...init,
@@ -340,7 +340,7 @@ const mf = createInstance({
 
 :::info
 
-原生的预加载提示（`<link rel="modulepreload">` / `<link rel="preload">`）无法携带请求头，因此在需要鉴权的源上可能会失败；但真正的模块加载仍会走 `fetch` 钩子。带鉴权的 CSS 是直接注入的，不会触发 `createLink` 钩子，因此插件添加的 `nonce`/SRI 属性不会作用于这类 CSS。
+原生的预加载提示（`<link rel="modulepreload">` / `<link rel="preload">`）无法携带请求头，因此在需要鉴权的源上可能会失败；但最终使用时仍会通过 `fetch` 钩子加载。带鉴权的 CSS 是直接注入的，不会触发 `createLink` 钩子，因此插件添加的 `nonce`/SRI 属性不会作用于这类 CSS。
 
 :::
 
diff --git a/apps/website-new/docs/zh/guide/runtime/runtime-hooks.mdx b/apps/website-new/docs/zh/guide/runtime/runtime-hooks.mdx
index 8efb156254c..03254642854 100644
--- a/apps/website-new/docs/zh/guide/runtime/runtime-hooks.mdx
+++ b/apps/website-new/docs/zh/guide/runtime/runtime-hooks.mdx
@@ -687,7 +687,8 @@ const changeScriptAttributePlugin: () => ModuleFederationRuntimePlugin =
 
 `AsyncHook`
 
-`fetch` 函数允许自定义加载 remote 时使用的请求。它始终会作用于清单（manifest）JSON 请求（成功的 `Response` 必须返回一个有效的 JSON）。当注册了 `fetch` 钩子时，它还会额外作用于 **`module` / `esm`** 类型 remote 的 remote entry 及 manifest 中声明的 CSS——这些资源会通过 `fetch` + blob 加载器加载，从而让自定义的 `headers`（如 `Authorization`）也能应用到这些请求上。
+`fetch` 函数允许自定义获取清单（manifest）JSON 的请求，成功加载的清单 `Response` 必须返回一个有效的 JSON。
+你还可通过 `fetch` 函数将自定义的 `headers`（如 `Authorization`）应用到 **`module` / `esm`** 类型 remote 的 remote entry 及 manifest 中声明的 CSS 资源上。
 
 ```typescript
 function fetch(

From fb0b299951f539066c4093dafeff77238f3ba5a2 Mon Sep 17 00:00:00 2001
From: Shaoyu Meng <shaoyumeng@Shaoyus-MacBook-Pro-5.local>
Date: Mon, 22 Jun 2026 21:43:13 -0700
Subject: [PATCH 30/34] docs(changeset): clarify and reorganize
 remote-fetch-options entry

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .changeset/remote-fetch-options.md | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/.changeset/remote-fetch-options.md b/.changeset/remote-fetch-options.md
index 824a93a9c78..cee9b210a27 100644
--- a/.changeset/remote-fetch-options.md
+++ b/.changeset/remote-fetch-options.md
@@ -3,4 +3,8 @@
 '@module-federation/sdk': minor
 ---
 
-Enable header-authenticated ESM remote loading through the existing runtime `fetch` hook. When a `fetch` hook plugin is registered, `module`/`esm` remotes load their remote entry and manifest-declared CSS via a fetch + blob import-rewriting loader (instead of native `import()` / `<link>`), so custom HTTP headers (e.g. `Authorization`) be applied on every asset request. The hook receives `remoteInfo`, so headers can be decided per remote and support dynamic cases such as token refresh. Remote registration is unchanged and no new remote config is introduced; remotes load as before when no `fetch` hook is present.
+Support loading remote assets in the manifest with custom headers through the existing runtime `fetch` hook.
+
+- When a `fetch` hook plugin is registered, `module`/`esm` remotes load their remote entry and manifest-declared CSS through a fetch + blob loader, instead of native `import()` / `<link>`.
+- The hook receives `remoteInfo`, so headers can be set per remote and support dynamic cases such as token refresh.
+- When no `fetch` hook is present, remotes load exactly as before.

From 59af18ff1a7cd60e43809dbe3d5121631f967e89 Mon Sep 17 00:00:00 2001
From: Shaoyu Meng <shaoyumeng@Shaoyus-MacBook-Pro-5.local>
Date: Mon, 6 Jul 2026 23:41:36 -0700
Subject: [PATCH 31/34] rebase test to use rstest

---
 packages/runtime-core/__tests__/load-entry-fetch-hook.spec.ts  | 2 +-
 packages/runtime-core/__tests__/preload-css-fetch-hook.spec.ts | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/runtime-core/__tests__/load-entry-fetch-hook.spec.ts b/packages/runtime-core/__tests__/load-entry-fetch-hook.spec.ts
index 9a3503cdff2..48f6ff63331 100644
--- a/packages/runtime-core/__tests__/load-entry-fetch-hook.spec.ts
+++ b/packages/runtime-core/__tests__/load-entry-fetch-hook.spec.ts
@@ -1,4 +1,4 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, vi, beforeEach, afterEach } from '@rstest/core';
 import * as sdk from '@module-federation/sdk';
 import { __loadEntryDomForTest } from '../src/utils/load';
 
diff --git a/packages/runtime-core/__tests__/preload-css-fetch-hook.spec.ts b/packages/runtime-core/__tests__/preload-css-fetch-hook.spec.ts
index 9ccae00fec4..3d35c7112c3 100644
--- a/packages/runtime-core/__tests__/preload-css-fetch-hook.spec.ts
+++ b/packages/runtime-core/__tests__/preload-css-fetch-hook.spec.ts
@@ -1,4 +1,4 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { describe, it, expect, vi, beforeEach, afterEach } from '@rstest/core';
 import * as sdk from '@module-federation/sdk';
 import { preloadAssets } from '../src/utils/preload';
 

From 9783266a26a87d48043aaca5ddd4f70534c50815 Mon Sep 17 00:00:00 2001
From: Shaoyu Meng <shaoyumeng@Shaoyus-MacBook-Pro-5.local>
Date: Mon, 6 Jul 2026 23:46:25 -0700
Subject: [PATCH 32/34] fix occurance of vi

---
 .../__tests__/load-entry-fetch-hook.spec.ts        | 10 +++++-----
 .../__tests__/preload-css-fetch-hook.spec.ts       | 14 +++++++-------
 2 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/packages/runtime-core/__tests__/load-entry-fetch-hook.spec.ts b/packages/runtime-core/__tests__/load-entry-fetch-hook.spec.ts
index 48f6ff63331..78ec4b172db 100644
--- a/packages/runtime-core/__tests__/load-entry-fetch-hook.spec.ts
+++ b/packages/runtime-core/__tests__/load-entry-fetch-hook.spec.ts
@@ -1,4 +1,4 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from '@rstest/core';
+import { describe, it, expect, rs, beforeEach, afterEach } from '@rstest/core';
 import * as sdk from '@module-federation/sdk';
 import { __loadEntryDomForTest } from '../src/utils/load';
 
@@ -10,7 +10,7 @@ function createLoaderHook(hasFetchListener: boolean) {
   }
   return {
     lifecycle: {
-      fetch: { emit: vi.fn(), listeners },
+      fetch: { emit: rs.fn(), listeners },
     },
   } as any;
 }
@@ -27,11 +27,11 @@ function createRemoteInfo(name: string, entry: string) {
 }
 
 describe('loadEntryDom ESM with fetch lifecycle loader hook', () => {
-  let loadEsmEntryWithFetch: ReturnType<typeof vi.spyOn>;
+  let loadEsmEntryWithFetch: ReturnType<typeof rs.spyOn>;
 
   beforeEach(() => {
-    vi.clearAllMocks();
-    loadEsmEntryWithFetch = vi
+    rs.clearAllMocks();
+    loadEsmEntryWithFetch = rs
       .spyOn(sdk, 'loadEsmEntryWithFetch')
       .mockResolvedValue({ ok: 1 });
   });
diff --git a/packages/runtime-core/__tests__/preload-css-fetch-hook.spec.ts b/packages/runtime-core/__tests__/preload-css-fetch-hook.spec.ts
index 3d35c7112c3..ff0e7fc27fb 100644
--- a/packages/runtime-core/__tests__/preload-css-fetch-hook.spec.ts
+++ b/packages/runtime-core/__tests__/preload-css-fetch-hook.spec.ts
@@ -1,4 +1,4 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from '@rstest/core';
+import { describe, it, expect, rs, beforeEach, afterEach } from '@rstest/core';
 import * as sdk from '@module-federation/sdk';
 import { preloadAssets } from '../src/utils/preload';
 
@@ -12,9 +12,9 @@ function createLoaderHook(hasFetchListener: boolean) {
     options: { inBrowser: true },
     loaderHook: {
       lifecycle: {
-        fetch: { emit: vi.fn(), listeners },
-        createLink: { emit: vi.fn() },
-        createScript: { emit: vi.fn() },
+        fetch: { emit: rs.fn(), listeners },
+        createLink: { emit: rs.fn() },
+        createScript: { emit: rs.fn() },
       },
     },
   } as any;
@@ -30,11 +30,11 @@ const createRemoteInfo = (name: string): any => ({
 });
 
 describe('preloadAssets CSS with fetch lifecycle loader hook', () => {
-  let loadCssWithFetch: ReturnType<typeof vi.spyOn>;
+  let loadCssWithFetch: ReturnType<typeof rs.spyOn>;
 
   beforeEach(() => {
-    vi.clearAllMocks();
-    loadCssWithFetch = vi
+    rs.clearAllMocks();
+    loadCssWithFetch = rs
       .spyOn(sdk, 'loadCssWithFetch')
       .mockResolvedValue(undefined as any);
   });

From d5d9ab2914e8192d5a8092718ad14e5467cd2628 Mon Sep 17 00:00:00 2001
From: Shaoyu Meng <shaoyumeng@Shaoyus-MacBook-Pro-5.local>
Date: Tue, 7 Jul 2026 00:40:39 -0700
Subject: [PATCH 33/34] test: stub fetch and blob primitives instead of spying
 on sdk exports
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

rs.spyOn/rs.mock on @module-federation/sdk never intercepts calls from
src/utils/load.ts and preload.ts: their named imports bind directly to
the sdk's inner dist modules, bypassing the mocked package entry. Follow
the sdk blobLoad.spec.ts idiom instead — run the real blob loader, stub
globalThis.fetch and URL.createObjectURL, and assert the observable
fetch/hook-emit behavior.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
---
 .../__tests__/load-entry-fetch-hook.spec.ts   | 54 +++++++++++--------
 .../__tests__/preload-css-fetch-hook.spec.ts  | 42 ++++++++++-----
 2 files changed, 62 insertions(+), 34 deletions(-)

diff --git a/packages/runtime-core/__tests__/load-entry-fetch-hook.spec.ts b/packages/runtime-core/__tests__/load-entry-fetch-hook.spec.ts
index 78ec4b172db..07bb2e634ab 100644
--- a/packages/runtime-core/__tests__/load-entry-fetch-hook.spec.ts
+++ b/packages/runtime-core/__tests__/load-entry-fetch-hook.spec.ts
@@ -1,5 +1,5 @@
 import { describe, it, expect, rs, beforeEach, afterEach } from '@rstest/core';
-import * as sdk from '@module-federation/sdk';
+import { loadModule } from '@module-federation/sdk';
 import { __loadEntryDomForTest } from '../src/utils/load';
 
 // Create a mocked fetch lifecycle loader hook
@@ -27,17 +27,30 @@ function createRemoteInfo(name: string, entry: string) {
 }
 
 describe('loadEntryDom ESM with fetch lifecycle loader hook', () => {
-  let loadEsmEntryWithFetch: ReturnType<typeof rs.spyOn>;
+  let originalFetch: typeof globalThis.fetch;
+  let originalCreateObjectURL: typeof URL.createObjectURL;
+  let fetchMock: ReturnType<typeof rs.fn>;
 
   beforeEach(() => {
     rs.clearAllMocks();
-    loadEsmEntryWithFetch = rs
-      .spyOn(sdk, 'loadEsmEntryWithFetch')
-      .mockResolvedValue({ ok: 1 });
+    loadModule.clearCache();
+    originalFetch = globalThis.fetch;
+    originalCreateObjectURL = URL.createObjectURL;
+    fetchMock = rs.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      statusText: 'OK',
+      text: () => Promise.resolve('export const ok = 1;'),
+    });
+    globalThis.fetch = fetchMock as any;
+    URL.createObjectURL = rs.fn(
+      () => 'data:text/javascript,export const ok = 1;',
+    );
   });
 
   afterEach(() => {
-    loadEsmEntryWithFetch.mockRestore();
+    globalThis.fetch = originalFetch;
+    URL.createObjectURL = originalCreateObjectURL;
   });
 
   it('uses the blob loader for module remotes when a fetch hook is registered', async () => {
@@ -47,33 +60,30 @@ describe('loadEntryDom ESM with fetch lifecycle loader hook', () => {
       id: 'a/say',
       resourceType: 'remoteEntry',
     };
-    await __loadEntryDomForTest({
+    const result = await __loadEntryDomForTest({
       remoteInfo: createRemoteInfo('a', 'http://x/e.js'),
       loaderHook,
       resourceContext,
     });
-    expect(loadEsmEntryWithFetch).toHaveBeenCalledWith(
-      expect.objectContaining({
-        entry: 'http://x/e.js',
-        customFetch: expect.any(Function),
-      }),
-    );
-    // The loader's customFetch accepts remoteInfo and resourceContext as
+    expect(fetchMock).toHaveBeenCalledWith('http://x/e.js', expect.anything());
+    // The loader's customFetch forwards remoteInfo and resourceContext as
     // additional arguments so the plugin can add different headers per remote/resource.
-    const { customFetch } = loadEsmEntryWithFetch.mock.calls[0][0] as any;
-    await customFetch('http://x/e.js', { headers: {} });
     expect(loaderHook.lifecycle.fetch.emit).toHaveBeenCalledWith(
       'http://x/e.js',
       { headers: {} },
       expect.objectContaining({ name: 'a' }),
       resourceContext,
     );
+    expect(result).toEqual(expect.objectContaining({ ok: 1 }));
   });
 
   it('wraps blob loader failures as RUNTIME_008 so loadEntryError recovery can fire', async () => {
-    loadEsmEntryWithFetch.mockRejectedValueOnce(
-      new Error('BlobLoaderNetworkError: 401 Unauthorized for http://x/e.js'),
-    );
+    fetchMock.mockResolvedValue({
+      ok: false,
+      status: 401,
+      statusText: 'Unauthorized',
+      text: () => Promise.resolve(''),
+    });
     const err = await __loadEntryDomForTest({
       remoteInfo: createRemoteInfo('a', 'http://x/e.js'),
       loaderHook: createLoaderHook(true),
@@ -89,10 +99,12 @@ describe('loadEntryDom ESM with fetch lifecycle loader hook', () => {
   });
 
   it('does NOT use the blob loader for module remotes when no fetch hook is registered', async () => {
+    const loaderHook = createLoaderHook(false);
     await __loadEntryDomForTest({
       remoteInfo: createRemoteInfo('b', 'http://x/e2.js'),
-      loaderHook: createLoaderHook(false),
+      loaderHook,
     }).catch(() => undefined);
-    expect(loadEsmEntryWithFetch).not.toHaveBeenCalled();
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(loaderHook.lifecycle.fetch.emit).not.toHaveBeenCalled();
   });
 });
diff --git a/packages/runtime-core/__tests__/preload-css-fetch-hook.spec.ts b/packages/runtime-core/__tests__/preload-css-fetch-hook.spec.ts
index ff0e7fc27fb..ccfd749def5 100644
--- a/packages/runtime-core/__tests__/preload-css-fetch-hook.spec.ts
+++ b/packages/runtime-core/__tests__/preload-css-fetch-hook.spec.ts
@@ -1,5 +1,5 @@
 import { describe, it, expect, rs, beforeEach, afterEach } from '@rstest/core';
-import * as sdk from '@module-federation/sdk';
+import { loadModule } from '@module-federation/sdk';
 import { preloadAssets } from '../src/utils/preload';
 
 // Create a mocked fetch lifecycle loader hook
@@ -30,17 +30,28 @@ const createRemoteInfo = (name: string): any => ({
 });
 
 describe('preloadAssets CSS with fetch lifecycle loader hook', () => {
-  let loadCssWithFetch: ReturnType<typeof rs.spyOn>;
+  let originalFetch: typeof globalThis.fetch;
+  let originalCreateObjectURL: typeof URL.createObjectURL;
+  let fetchMock: ReturnType<typeof rs.fn>;
 
   beforeEach(() => {
     rs.clearAllMocks();
-    loadCssWithFetch = rs
-      .spyOn(sdk, 'loadCssWithFetch')
-      .mockResolvedValue(undefined as any);
+    loadModule.clearCache();
+    originalFetch = globalThis.fetch;
+    originalCreateObjectURL = URL.createObjectURL;
+    fetchMock = rs.fn().mockResolvedValue({
+      ok: true,
+      status: 200,
+      statusText: 'OK',
+      text: () => Promise.resolve('.a{}'),
+    });
+    globalThis.fetch = fetchMock as any;
+    URL.createObjectURL = rs.fn(() => 'blob:css');
   });
 
   afterEach(() => {
-    loadCssWithFetch.mockRestore();
+    globalThis.fetch = originalFetch;
+    URL.createObjectURL = originalCreateObjectURL;
   });
 
   it('uses the blob loader for manifest CSS when a fetch hook is registered', async () => {
@@ -51,11 +62,14 @@ describe('preloadAssets CSS with fetch lifecycle loader hook', () => {
       entryAssets: [],
     };
     await preloadAssets(createRemoteInfo('a'), host, assets, false);
-    expect(loadCssWithFetch).toHaveBeenCalledWith(
-      expect.objectContaining({
-        href: 'http://x/a.css',
-        customFetch: expect.any(Function),
-      }),
+    expect(fetchMock).toHaveBeenCalledWith('http://x/a.css', expect.anything());
+    // The loader's customFetch forwards remoteInfo and the resource context so
+    // the plugin can add different headers per remote/resource.
+    expect(host.loaderHook.lifecycle.fetch.emit).toHaveBeenCalledWith(
+      'http://x/a.css',
+      { headers: {} },
+      expect.objectContaining({ name: 'a' }),
+      expect.anything(),
     );
   });
 
@@ -70,7 +84,8 @@ describe('preloadAssets CSS with fetch lifecycle loader hook', () => {
     // rel=stylesheet that would apply the remote's CSS before it is loaded, so it
     // must be skipped here rather than overriding host styles.
     await preloadAssets(createRemoteInfo('a'), host, assets);
-    expect(loadCssWithFetch).not.toHaveBeenCalled();
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(host.loaderHook.lifecycle.fetch.emit).not.toHaveBeenCalled();
   });
 
   it('does NOT use the blob loader for manifest CSS when no fetch hook is registered', async () => {
@@ -97,6 +112,7 @@ describe('preloadAssets CSS with fetch lifecycle loader hook', () => {
     } finally {
       observer.disconnect();
     }
-    expect(loadCssWithFetch).not.toHaveBeenCalled();
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(host.loaderHook.lifecycle.fetch.emit).not.toHaveBeenCalled();
   });
 });

From 6061b9b55bdc30ce856855739db527cc637e0896 Mon Sep 17 00:00:00 2001
From: Shaoyu Meng <shaoyumeng@Shaoyus-MacBook-Pro-5.local>
Date: Fri, 10 Jul 2026 11:27:00 -0700
Subject: [PATCH 34/34] docs(runtime): add pt-BR translation for fetch-hook
 header docs

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---
 .../docs/pt-BR/guide/runtime/runtime-api.mdx  | 39 +++++++++++++++++++
 .../pt-BR/guide/runtime/runtime-hooks.mdx     |  3 +-
 2 files changed, 41 insertions(+), 1 deletion(-)

diff --git a/apps/website-new/docs/pt-BR/guide/runtime/runtime-api.mdx b/apps/website-new/docs/pt-BR/guide/runtime/runtime-api.mdx
index 44b146e5089..2bf37a59a15 100644
--- a/apps/website-new/docs/pt-BR/guide/runtime/runtime-api.mdx
+++ b/apps/website-new/docs/pt-BR/guide/runtime/runtime-api.mdx
@@ -305,6 +305,45 @@ Quando `force: true` é definir, o newly registered módulos vai overwrite já-r
 
 :::
 
+### Carregando remotes com cabeçalhos personalizados via hook `fetch`
+
+Alguns remotes exigem cabeçalhos específicos para serem acessados. Nesse caso, você pode configurar os cabeçalhos através do [hook `fetch`](./runtime-hooks#fetch) do runtime. Você pode lidar com casos dinâmicos, como atualização de token ou lógica de autenticação por requisição, dentro desse hook.
+
+Para remotes do tipo **`module` / `esm`**, quando um hook `fetch` é registrado, o remote entry e o CSS declarado no manifest são carregados através de um carregador `fetch` + blob, de modo que os cabeçalhos que você adiciona alcancem todas as requisições de recursos. Sem um hook `fetch` registrado, os remotes carregam como antes, via `import()` / `<link>` nativos (que não podem carregar cabeçalhos personalizados).
+
+```ts
+import { createInstance } from '@module-federation/enhanced/runtime';
+
+const mf = createInstance({
+  name: 'mf_host',
+  remotes: [
+    {
+      name: 'sub1',
+      entry: 'https://localhost:2001/mf-manifest.json',
+      type: 'module',
+    },
+  ],
+  plugins: [
+    {
+      name: 'auth-fetch',
+      // `remoteInfo` permite usar diferentes opções de requisição para remotes específicos
+      fetch(url, init, remoteInfo) {
+        return fetch(url, {
+          ...init,
+          headers: { ...init.headers, Authorization: `Bearer ${token}` },
+        });
+      },
+    },
+  ],
+});
+```
+
+:::info
+
+As dicas de preload nativas (`<link rel="modulepreload">` / `<link rel="preload">`) não podem carregar cabeçalhos, portanto podem falhar em uma origem autenticada; os carregamentos reais ainda passam pelo hook `fetch` quando o recurso é utilizado. O CSS autenticado é injetado diretamente e não emite o hook `createLink`, então atributos `nonce`/SRI adicionados por plugins não são aplicados a ele.
+
+:::
+
 <Tabs>
   <Tab label="Build Plugin (Use build plugin)">
   ```tsx
diff --git a/apps/website-new/docs/pt-BR/guide/runtime/runtime-hooks.mdx b/apps/website-new/docs/pt-BR/guide/runtime/runtime-hooks.mdx
index b1ecc4587c8..2ca741005a7 100644
--- a/apps/website-new/docs/pt-BR/guide/runtime/runtime-hooks.mdx
+++ b/apps/website-new/docs/pt-BR/guide/runtime/runtime-hooks.mdx
@@ -726,7 +726,8 @@ const changeScriptAttributePlugin: () => ModuleFederationRuntimePlugin =
 
 `AsyncHook`
 
-O `fetch` função allows customizing o request esse fetches o manifest JSON. Uma successful `Response` deve yield uma valid JSON.
+O `fetch` função allows customizing o request esse fetches o manifest JSON; uma manifest `Response` carregada com sucesso deve retornar um JSON válido.
+Você também pode usar a função `fetch` para aplicar `headers` personalizados (por exemplo, `Authorization`) ao remote entry e aos recursos CSS declarados no manifest de remotes do tipo **`module` / `esm`**.
 
 ```typescript
 function fetch(