@fulgurjs/federation 5.0.4 → 5.1.1

package/dist/react-adapter.cjs

@@ -0,0 +1,521 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/react-adapter.ts
+var react_adapter_exports = {};
+__export(react_adapter_exports, {
+  RemoteErrorBoundary: () => RemoteErrorBoundary,
+  createReactHostPages: () => createReactHostPages,
+  createRemoteComponent: () => createRemoteComponent,
+  createUseLoadRemote: () => createUseLoadRemote
+});
+module.exports = __toCommonJS(react_adapter_exports);
+var import_react = require("react");
+
+// src/pages.ts
+var normSpec = (s) => s.replace(/^[./]+/, "").replace(/\/+$/, "");
+var hasParam = (route) => /(^|\/):[\w]+/.test(route);
+var segs = (route) => route.split("/").filter(Boolean);
+function defaultDeriveSpec(route) {
+  return segs(route).slice(1).filter((seg) => !seg.startsWith(":")).join("/");
+}
+function shadows(earlier, later) {
+  const a = segs(earlier);
+  const b = segs(later);
+  if (a.length !== b.length) return null;
+  if (earlier === later) return "full";
+  let hasParam2 = false;
+  for (let i = 0; i < a.length; i++) {
+    if (a[i] === b[i]) continue;
+    if (a[i].startsWith(":")) {
+      hasParam2 = true;
+      continue;
+    }
+    return null;
+  }
+  return hasParam2 ? "param" : null;
+}
+function remoteOfRoute(route, remotes) {
+  if (!remotes) return null;
+  for (const [prefix, name] of Object.entries(remotes)) {
+    if (route === prefix.replace(/\/+$/, "") || route.startsWith(prefix)) return name;
+  }
+  return null;
+}
+function validatePages(pages, options = {}) {
+  const deriveSpec = options.deriveSpec ?? defaultDeriveSpec;
+  const violations = [];
+  const effective = pages.map((p) => normSpec(p.spec ?? deriveSpec(p.route)));
+  pages.forEach((p, i) => {
+    if (p.spec || !hasParam(p.route)) return;
+    pages.forEach((q, j) => {
+      if (i === j) return;
+      if (effective[j] !== effective[i]) return;
+      violations.push({
+        rule: "R1",
+        level: "error",
+        message: `[R1] \u8DEF\u7531 "${p.route}" \u5265\u53C2\u63A8\u5BFC spec "${effective[i]}" \u4E0E\u8DEF\u7531 "${q.route}"${q.spec ? "\uFF08\u663E\u5F0F spec\uFF09" : ""}\u6536\u655B\u76F8\u540C\u3002
+   \u6839\u56E0\uFF1A\u53C2\u6570\u6BB5\u5265\u79BB\u540E expose \u952E\u4E0E\u5176\u5B83\u6761\u76EE\u76F8\u540C\uFF0C\u8BE5\u8DEF\u7531\u4F1A\u9759\u9ED8\u52A0\u8F7D\u9519\u8BEF\u7EC4\u4EF6
+   \uFF08\u771F\u5B9E\u4E8B\u6545\uFF1A\u5E26\u53C2\u52A8\u4F5C\u9875\u8BEF\u8D70\u5217\u8868/\u66F4\u65B0\u8BED\u4E49\uFF0C\u6570\u636E\u98CE\u9669\uFF09\u3002
+   \u4FEE\u6CD5\uFF1A\u4E3A\u8BE5\u6761\u76EE\u663E\u5F0F\u58F0\u660E spec: '...'\uFF08\u6307\u5411\u5E26\u53C2\u9875\u9762\u81EA\u5DF1\u7684 expose\uFF09\uFF0C\u6216\u8C03\u6574\u8DEF\u7531\u62C6\u5206\u3002`
+      });
+    });
+  });
+  const seenSpec = /* @__PURE__ */ new Map();
+  pages.forEach((p, i) => {
+    const key = effective[i];
+    if (seenSpec.has(key)) {
+      const first = pages[seenSpec.get(key)];
+      const bothExplicit = !!p.spec && !!first.spec;
+      violations.push({
+        rule: "R2",
+        level: "warn",
+        message: `[R2] \u8DEF\u7531 "${p.route}" \u4E0E "${first.route}" \u6709\u6548 spec \u76F8\u540C\uFF08"${key}"\uFF09\u3002${bothExplicit ? "\u4E24\u6761\u5747\u4E3A\u663E\u5F0F spec" : "\u5176\u4E2D\u542B\u63A8\u5BFC spec"}\u2014\u2014\u82E5\u4E3A\u523B\u610F\u7684\u83DC\u5355\u522B\u540D\u53EF\u5FFD\u7565\u672C\u8B66\u544A\uFF0C\u5426\u5219\u8BF7\u6838\u5BF9\u3002`
+      });
+    } else {
+      seenSpec.set(key, i);
+    }
+  });
+  if (options.schema && options.remotes) {
+    pages.forEach((p, i) => {
+      const remote = remoteOfRoute(p.route, options.remotes);
+      if (!remote) return;
+      const entry = options.schema[remote];
+      if (!entry || entry.exists === false) return;
+      const exposes = new Set((entry.exposes ?? []).map(normSpec));
+      if (!exposes.has(effective[i])) {
+        violations.push({
+          rule: "R3",
+          level: "error",
+          message: `[R3] \u8DEF\u7531 "${p.route}" \u7684 spec "${effective[i]}" \u4E0D\u5728\u8FDC\u7A0B "${remote}" \u7684 exposes \u6E05\u5355\u4E2D\u3002
+   \u6839\u56E0\uFF1Aspec \u62FC\u5199\u4E0E\u8FDC\u7A0B exposes \u952E\u4E0D\u4E00\u81F4\uFF08\u8FD0\u884C\u65F6\u5C06 MFU-006 \u52A0\u8F7D\u5931\u8D25\uFF09\u3002
+   \u4FEE\u6CD5\uFF1A\u6838\u5BF9\u8FDC\u7A0B vite.config exposes \u952E\u540D\uFF0C\u6216\u4FEE\u6B63\u672C\u8868 spec\u3002
+   \u8FDC\u7A0B\u5B9E\u9645 exposes\uFF08\u524D 10\uFF09\uFF1A${[...exposes].slice(0, 10).join("\u3001") || "\uFF08\u7A7A\uFF09"}`
+        });
+      }
+    });
+  }
+  pages.forEach((p, i) => {
+    pages.forEach((q, j) => {
+      if (j <= i) return;
+      const kind = shadows(p.route, q.route);
+      if (!kind) return;
+      violations.push({
+        rule: "R4",
+        level: "error",
+        message: kind === "full" ? `[R4] \u8DEF\u7531\u5B8C\u5168\u91CD\u590D\uFF1A"${p.route}"\uFF08\u7B2C ${i + 1} \u6761\uFF09\u4E0E "${q.route}"\uFF08\u7B2C ${j + 1} \u6761\uFF09\u3002` : `[R4] \u8DEF\u7531 "${q.route}"\uFF08\u7B2C ${j + 1} \u6761\uFF09\u4F1A\u88AB\u66F4\u9760\u524D\u7684 "${p.route}" \u906E\u853D\uFF08\u5339\u914D\u5148\u5230\u5148\u5F97\uFF0C\u540E\u8005\u6210\u6B7B\u8DEF\u7531\uFF09\u3002
+   \u4FEE\u6CD5\uFF1A\u8C03\u6574\u6570\u7EC4\u987A\u5E8F\uFF08\u66F4\u5177\u4F53\u7684\u9759\u6001\u8DEF\u7531\u653E\u524D\u9762\uFF09\u6216\u5408\u5E76\u6761\u76EE\u3002`
+      });
+    });
+  });
+  const seenName = /* @__PURE__ */ new Map();
+  pages.forEach((p, i) => {
+    const name = typeof p.name === "string" ? p.name : "";
+    if (!name) return;
+    if (seenName.has(name)) {
+      violations.push({
+        rule: "R5",
+        level: "warn",
+        message: `[R5] name "${name}" \u91CD\u590D\uFF08"${pages[seenName.get(name)].route}" \u4E0E "${p.route}"\uFF09\u2014\u2014vue-router \u547D\u540D\u8DF3\u8F6C push({name}) \u5C06\u547D\u4E2D\u524D\u8005\uFF0C\u8BF7\u6838\u5BF9\u3002`
+      });
+    } else {
+      seenName.set(name, i);
+    }
+  });
+  return violations;
+}
+function formatViolations(violations) {
+  const errors = violations.filter((v) => v.level === "error");
+  const warns = violations.filter((v) => v.level === "warn");
+  let out = "";
+  if (errors.length) {
+    out += `[fulgurjs] \u8DEF\u7531\u8868\u6821\u9A8C\u5931\u8D25\uFF08${errors.length} \u9879\uFF0CERROR\uFF09\uFF1A
+` + errors.map((v) => v.message).join("\n") + "\n";
+  }
+  if (warns.length) {
+    out += `[fulgurjs] \u8DEF\u7531\u8868\u6821\u9A8C\u8B66\u544A\uFF08${warns.length} \u9879\uFF0CWARN\uFF09\uFF1A
+` + warns.map((v) => v.message).join("\n");
+  }
+  return out.trim();
+}
+function definePages(pages, options = {}) {
+  const violations = validatePages(pages, options);
+  const errors = violations.filter((v) => v.level === "error");
+  const warns = violations.filter((v) => v.level === "warn");
+  const text = formatViolations(violations);
+  if (text) {
+    if (errors.length && options.strict !== false) {
+      throw new Error(text);
+    }
+    console[errors.length ? "error" : "warn"](text);
+  }
+  return pages;
+}
+
+// src/host-pages-core.ts
+var cleanCompName = (spec) => "Fulgurjs_" + spec.replace(/[^A-Za-z0-9_-]/g, "_");
+function defaultDeriveSpec2(route) {
+  return route.split("/").filter(Boolean).slice(1).filter((seg) => !seg.startsWith(":")).join("/");
+}
+function readSessionKey() {
+  const sk = (globalThis.__FULGURJS_APP_CONFIG__ ?? {}).sessionKey;
+  return typeof sk === "string" && sk !== "" ? sk : void 0;
+}
+function shouldResetSessionCache(sessionKey, cached) {
+  return sessionKey !== void 0 && sessionKey !== cached;
+}
+function noRenderableExportError(spec, inner) {
+  return new Error(
+    `[fulgurjs] \u8FDC\u7A0B\u6A21\u5757 "${spec}" \u6CA1\u6709\u5BFC\u51FA\u53EF\u6E32\u67D3\u7EC4\u4EF6\uFF1B\u5F53\u524D\u503C\u7C7B\u578B\u4E3A ${inner === null ? "null" : typeof inner}\u3002
+  \u4FEE\u6CD5: \u6838\u5BF9\u8FDC\u7A0B exposes \u952E\u540D\u4E0E\u9875\u9762\u8868 spec \u662F\u5426\u4E00\u81F4\uFF08MFU-006 \u8BED\u4E49\uFF09`
+  );
+}
+function createHostPagesCore(options) {
+  const { pages, remotePrefixes, deriveSpec, schema, strict, base } = options;
+  definePages(pages, { deriveSpec, remotes: remotePrefixes, schema, strict });
+  const prefixes = Object.entries(remotePrefixes).map(([p, name]) => [p.endsWith("/") ? p : `${p}/`, name]).sort((a, b) => b[0].length - a[0].length);
+  const remoteOf = (route) => {
+    for (const [prefix, name] of prefixes) {
+      if (route.startsWith(prefix) || `${route}/` === prefix) return name;
+    }
+    throw new Error(
+      `[fulgurjs] \u9875\u9762\u8DEF\u7531 "${route}" \u672A\u5339\u914D\u4EFB\u4F55 remotePrefixes\uFF1A{ ${Object.entries(remotePrefixes).map(([k, v]) => `'${k}': '${v}'`).join(", ")} }
+  \u6839\u56E0: \u9875\u9762\u8868\u6761\u76EE\u7684\u8DEF\u7531\u4E0D\u5728\u4EFB\u4F55\u5DF2\u58F0\u660E\u7684\u8FDC\u7A0B\u524D\u7F00\u4E0B\u3002
+  \u4FEE\u6CD5: \u5728 remotePrefixes \u8865\u5145\u8BE5\u8DEF\u7531\u524D\u7F00 \u2192 \u8FDC\u7A0B\u540D\u7684\u6620\u5C04\uFF0C\u6216\u4FEE\u6B63\u9875\u9762\u8868 route\u3002`
+    );
+  };
+  for (const page of pages) remoteOf(page.route);
+  const specOf = (page) => {
+    const s = page.spec ?? (deriveSpec ? deriveSpec(page.route) : defaultDeriveSpec2(page.route));
+    return `${remoteOf(page.route)}/${String(s).replace(/^[./]+/, "")}`;
+  };
+  const baseNorm = base && base !== "/" ? base.endsWith("/") ? base : `${base}/` : "";
+  const matchSegments = (pattern, path) => {
+    const patSegs = pattern.split("/").filter(Boolean);
+    const pathSegs = path.split("/").filter(Boolean);
+    if (patSegs.length !== pathSegs.length) return null;
+    const params = {};
+    for (let i = 0; i < patSegs.length; i++) {
+      const seg = patSegs[i];
+      if (seg.startsWith(":")) {
+        try {
+          params[seg.slice(1)] = decodeURIComponent(pathSegs[i]);
+        } catch {
+          return null;
+        }
+      } else if (seg !== pathSegs[i]) {
+        return null;
+      }
+    }
+    return params;
+  };
+  const resolve = (rawPath) => {
+    let clean = String(rawPath ?? "");
+    if (baseNorm) {
+      if (clean === baseNorm.replace(/\/$/, "")) clean = "/";
+      else if (clean.startsWith(baseNorm)) clean = `/${clean.slice(baseNorm.length)}`;
+    }
+    clean = (clean.replace(/\/+$/, "") || "/").split("?")[0].split("#")[0];
+    for (const page of pages) {
+      const params = matchSegments(page.route, clean);
+      if (params) return { page, remote: remoteOf(page.route), spec: specOf(page), params };
+    }
+    return null;
+  };
+  return { pages, resolve, remoteOf, specOf };
+}
+
+// src/react-adapter.ts
+var ERROR_STYLE = {
+  padding: "16px",
+  border: "1px solid #fde2e2",
+  borderRadius: "4px",
+  background: "#fef0f0",
+  color: "#c45656",
+  fontSize: "13px",
+  lineHeight: "1.6",
+  boxSizing: "border-box"
+};
+var TITLE_STYLE = { margin: "0 0 4px", fontWeight: 600 };
+var MESSAGE_STYLE = { margin: "0 0 8px", wordBreak: "break-all" };
+var FIX_STYLE = { margin: "0 0 8px" };
+var DefaultErrorView = function FulgurjsRemoteError({ error, retry, phase }) {
+  const err = error;
+  const code = err?.code ?? "UNKNOWN";
+  const message = err?.message ?? String(error ?? "unknown error");
+  return (0, import_react.createElement)("div", { style: ERROR_STYLE, "data-fulgurjs-error": code }, [
+    (0, import_react.createElement)(
+      "p",
+      { key: "t", style: TITLE_STYLE },
+      phase === "load" ? `\u8FDC\u7A0B\u7EC4\u4EF6\u52A0\u8F7D\u5931\u8D25\uFF08\u9519\u8BEF\u7801 ${code}\uFF09` : `\u8FDC\u7A0B\u7EC4\u4EF6\u6E32\u67D3\u51FA\u9519\uFF08\u9519\u8BEF\u7801 ${code}\uFF09`
+    ),
+    (0, import_react.createElement)("p", { key: "m", style: MESSAGE_STYLE }, message),
+    (0, import_react.createElement)("p", { key: "f", style: FIX_STYLE }, phase === "render" ? "\u4FEE\u6CD5\uFF1A\u67E5\u770B\u6D4F\u89C8\u5668 console \u4E2D\u7684\u7EC4\u4EF6\u8C03\u7528\u6808\u5B9A\u4F4D\u8FDC\u7A0B\u7EC4\u4EF6\u5185\u90E8\u7684\u6E32\u67D3\u5F02\u5E38\uFF08\u9519\u8BEF\u629B\u81EA\u8FDC\u7A0B\u4EE3\u7801\u672C\u8EAB\uFF0C\u4E0E\u7F51\u7EDC\u52A0\u8F7D\u65E0\u5173\uFF09\u3002" : "\u4FEE\u6CD5\uFF1A\u2460 \u6838\u5BF9 spec \u7684\u300C\u8FDC\u7A0B\u540D/expose \u540D\u300D\u4E0E\u8FDC\u7A0B\u5E94\u7528 exposes \u662F\u5426\u4E00\u81F4\uFF08MFU-006/008\uFF09\uFF1B\u2461 \u6838\u5BF9 remotes \u5730\u5740\u7AEF\u53E3\u4E0E\u8FDC\u7A0B\u670D\u52A1\u53EF\u8FBE\u6027\uFF08MFU-001\uFF09\uFF1B\u2462 \u67E5\u770B window \u7684 fulgurjs:error \u4E8B\u4EF6\u4E0E console \u540C\u6E90\u9519\u8BEF\u5B9A\u4F4D\u6839\u56E0\u3002"),
+    (0, import_react.createElement)("button", { key: "r", onClick: retry, type: "button" }, "\u91CD\u8BD5")
+  ]);
+};
+function isValidComponentType(v) {
+  if (typeof v === "function") return true;
+  if (v !== null && typeof v === "object" && typeof v.$$typeof === "symbol") return true;
+  return false;
+}
+function assertAdapterOptions(source, opts) {
+  if (opts.retries !== void 0 && (typeof opts.retries !== "number" || !Number.isInteger(opts.retries) || opts.retries < 0 || opts.retries > 10)) {
+    throw new Error(
+      `[fulgurjs] ${source} \u7684 retries \u914D\u7F6E\u65E0\u6548\uFF1A\u5F53\u524D\u4E3A ${String(opts.retries)}\uFF0C\u5E94\u4E3A 0 \u5230 10 \u7684\u6574\u6570\u3002\u8BF7\u4FEE\u6B63\u9009\u9879\u3002`
+    );
+  }
+  if (opts.timeout !== void 0 && (typeof opts.timeout !== "number" || !Number.isFinite(opts.timeout) || opts.timeout <= 0)) {
+    throw new Error(
+      `[fulgurjs] ${source} \u7684 timeout \u914D\u7F6E\u65E0\u6548\uFF1A\u5F53\u524D\u4E3A ${String(opts.timeout)}\uFF0C\u5E94\u4E3A\u5927\u4E8E 0 \u7684\u6709\u9650\u6BEB\u79D2\u6570\u3002\u8BF7\u4FEE\u6B63\u9009\u9879\u3002`
+    );
+  }
+}
+function renderErrorNode(errorOpt, error, retry, phase) {
+  if (typeof errorOpt === "function") return errorOpt(error, retry);
+  if (errorOpt !== void 0) return errorOpt;
+  return (0, import_react.createElement)(DefaultErrorView, { error, retry, phase });
+}
+var RemoteErrorBoundary = class extends import_react.Component {
+  state = { error: null };
+  static getDerivedStateFromError(error) {
+    return { error };
+  }
+  componentDidCatch(error, info) {
+    console.error("[fulgurjs] \u8FDC\u7A0B\u7EC4\u4EF6\u6E32\u67D3\u5F02\u5E38\uFF08RemoteErrorBoundary \u6355\u83B7\uFF09\uFF1A", error, info?.componentStack ?? "");
+    this.props.onError?.(error, info);
+  }
+  componentDidUpdate(prev) {
+    if (this.state.error !== null && !shallowArrayEq(prev.resetKeys, this.props.resetKeys)) {
+      this.reset();
+    }
+  }
+  reset = () => {
+    this.setState({ error: null });
+  };
+  render() {
+    if (this.state.error !== null) {
+      const f = this.props.fallback;
+      if (typeof f === "function") return f({ error: this.state.error, reset: this.reset });
+      if (f !== void 0) return f;
+      return renderErrorNode(void 0, this.state.error, this.reset, "render");
+    }
+    return this.props.children;
+  }
+};
+function shallowArrayEq(a, b) {
+  if (a === b) return true;
+  if (!a || !b || a.length !== b.length) return false;
+  return a.every((v, i) => v === b[i]);
+}
+function RemoteLoader({ spec, opts, loadRemote, beforeLoad, attempt, sessionKey, retry, passthrough, fwdRef }) {
+  const [state, setState] = (0, import_react.useState)({ phase: "pending" });
+  const latest = (0, import_react.useRef)({ passthrough, fwdRef });
+  latest.current = { passthrough, fwdRef };
+  (0, import_react.useEffect)(() => {
+    let cancelled = false;
+    let settled = false;
+    let timer;
+    const gen = `${attempt}@${sessionKey ?? ""}`;
+    const commit = (next) => {
+      if (cancelled || settled || gen !== `${attempt}@${sessionKey ?? ""}`) return;
+      settled = true;
+      setState(next);
+    };
+    setState({ phase: "pending" });
+    const run = (async () => {
+      await beforeLoad?.();
+      return loadRemote(spec, { retries: opts.retries });
+    })();
+    run.catch(() => {
+    });
+    const race = opts.timeout === void 0 ? run : Promise.race([
+      run,
+      new Promise((_, reject) => {
+        timer = setTimeout(() => {
+          reject(new Error(
+            `[fulgurjs] \u8FDC\u7A0B\u7EC4\u4EF6 "${spec}" \u52A0\u8F7D\u7B49\u5F85\u8D85\u8FC7 ${opts.timeout} \u6BEB\u79D2\uFF08\u9002\u914D\u5C42 timeout\uFF09\u3002\u8BE5\u8D85\u65F6\u53EA\u7ED3\u675F\u672C\u6B21\u7B49\u5F85\uFF0C\u4E0D\u53D6\u6D88\u5DF2\u53D1\u51FA\u7684\u5171\u4EAB\u8BF7\u6C42\uFF1B\u53EF\u70B9\u51FB\u91CD\u8BD5\u5EFA\u7ACB\u65B0\u7684\u52A0\u8F7D\u5C1D\u8BD5\u3002`
+          ));
+        }, opts.timeout);
+      })
+    ]);
+    race.then(
+      (ns) => {
+        if (timer !== void 0) clearTimeout(timer);
+        const inner = ns?.default ?? ns;
+        if (!isValidComponentType(inner)) {
+          commit({ phase: "error", error: noRenderableExportError(spec, inner) });
+          return;
+        }
+        commit({ phase: "ready", Comp: inner });
+      },
+      (err) => {
+        if (timer !== void 0) clearTimeout(timer);
+        commit({ phase: "error", error: err });
+      }
+    );
+    return () => {
+      cancelled = true;
+      if (timer !== void 0) clearTimeout(timer);
+    };
+  }, [attempt, sessionKey]);
+  if (state.phase === "pending") return opts.fallback ?? null;
+  if (state.phase === "error") return renderErrorNode(opts.error, state.error, retry, "load");
+  const Comp = state.Comp;
+  const merged = fwdRef === void 0 ? latest.current.passthrough : { ...latest.current.passthrough, ref: latest.current.fwdRef };
+  return (0, import_react.createElement)(Comp, merged);
+}
+var RemoteRenderBoundary = class extends import_react.Component {
+  state = { error: null };
+  static getDerivedStateFromError(error) {
+    return { error };
+  }
+  componentDidCatch(error, info) {
+    console.error("[fulgurjs] \u8FDC\u7A0B\u7EC4\u4EF6\u6E32\u67D3\u5F02\u5E38\uFF08remoteComponent \u5185\u7F6E\u8FB9\u754C\uFF09\uFF1A", error, info?.componentStack ?? "");
+  }
+  retry = () => {
+    this.props.onRetry();
+  };
+  render() {
+    return this.props.render(this.state.error, this.retry);
+  }
+};
+function buildRemoteComponent(spec, opts, loadRemote, beforeLoad) {
+  const displayName = cleanCompName(spec);
+  function RemoteRoot(props) {
+    const [attempt, setAttempt] = (0, import_react.useState)(0);
+    const retry = (0, import_react.useCallback)(() => setAttempt((a) => a + 1), []);
+    const { __fulgurjsRef, ...rest } = props;
+    const passthrough = rest;
+    const sessionKey = readSessionKey();
+    return (0, import_react.createElement)(
+      RemoteRenderBoundary,
+      {
+        key: attempt,
+        onRetry: retry,
+        render: (boundaryError) => boundaryError !== null ? renderErrorNode(opts.error, boundaryError, retry, "render") : (0, import_react.createElement)(RemoteLoader, {
+          spec,
+          opts,
+          loadRemote,
+          beforeLoad,
+          attempt,
+          sessionKey,
+          retry,
+          passthrough,
+          fwdRef: __fulgurjsRef
+        })
+      }
+    );
+  }
+  RemoteRoot.displayName = displayName;
+  const Wrapped = (0, import_react.forwardRef)(
+    (props, ref) => (0, import_react.createElement)(RemoteRoot, { ...props, __fulgurjsRef: ref })
+  );
+  Wrapped.displayName = displayName;
+  return Wrapped;
+}
+function createRemoteComponent(loadRemote) {
+  return function remoteComponent(spec, opts = {}) {
+    assertAdapterOptions(`remoteComponent("${spec}")`, opts);
+    return buildRemoteComponent(spec, opts, loadRemote);
+  };
+}
+function createUseLoadRemote(loadRemote) {
+  return function useLoadRemote(spec, opts = {}) {
+    assertAdapterOptions(`useLoadRemote("${spec}")`, opts);
+    const { shareScope, retries, fallbackModule } = opts;
+    const [data, setData] = (0, import_react.useState)(void 0);
+    const [error, setError] = (0, import_react.useState)(void 0);
+    const [loading, setLoading] = (0, import_react.useState)(true);
+    const reqGen = (0, import_react.useRef)(0);
+    const optsRef = (0, import_react.useRef)(opts);
+    optsRef.current = opts;
+    const sessionKey = readSessionKey();
+    (0, import_react.useEffect)(() => {
+      const gen = ++reqGen.current;
+      let cancelled = false;
+      const isCurrent = () => gen === reqGen.current && !cancelled;
+      setData(void 0);
+      setError(void 0);
+      setLoading(true);
+      loadRemote(spec, { shareScope, retries, fallbackModule }).then(
+        (ns) => {
+          if (!isCurrent()) return;
+          setData(ns);
+          setLoading(false);
+        },
+        (err) => {
+          if (!isCurrent()) return;
+          setError(err);
+          setLoading(false);
+        }
+      );
+      return () => {
+        cancelled = true;
+      };
+    }, [spec, shareScope, retries, fallbackModule, loadRemote, sessionKey]);
+    const reload = (0, import_react.useCallback)(async () => {
+      const gen = ++reqGen.current;
+      setLoading(true);
+      setError(void 0);
+      const o = optsRef.current;
+      try {
+        const ns = await loadRemote(spec, { shareScope: o.shareScope, retries: o.retries, fallbackModule: o.fallbackModule });
+        if (gen === reqGen.current) {
+          setData(ns);
+          setLoading(false);
+        }
+      } catch (err) {
+        if (gen === reqGen.current) {
+          setError(err);
+          setLoading(false);
+        }
+      }
+    }, [spec, loadRemote]);
+    return { data, error, loading, reload };
+  };
+}
+function createReactHostPages(options, loadRemote) {
+  const { beforeLoad, fallback, error, retries, timeout } = options;
+  assertAdapterOptions("createReactHostPages()", { retries, timeout });
+  const core = createHostPagesCore(options);
+  let cacheSession;
+  const compCache = /* @__PURE__ */ new Map();
+  const component = (spec) => {
+    const sessionKey = readSessionKey();
+    if (shouldResetSessionCache(sessionKey, cacheSession)) {
+      compCache.clear();
+      cacheSession = sessionKey;
+    }
+    let comp = compCache.get(spec);
+    if (!comp) {
+      comp = buildRemoteComponent(spec, { fallback, error, retries, timeout }, loadRemote, beforeLoad);
+      compCache.set(spec, comp);
+    }
+    return comp;
+  };
+  return { pages: core.pages, resolve: core.resolve, component };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  RemoteErrorBoundary,
+  createReactHostPages,
+  createRemoteComponent,
+  createUseLoadRemote
+});

package/dist/react-adapter.d.cts

@@ -0,0 +1,117 @@
+import { ComponentType, ReactNode, Component, ErrorInfo, Ref } from 'react';
+import { PageRouteLike } from './pages.cjs';
+import { R as ResolvedHostPage, H as HostPagesCoreOptions } from './host-pages-core-BFxp-IOj.cjs';
+
+interface LoadRemoteOptions {
+    shareScope?: string;
+    retries?: number;
+    fallbackModule?: () => any;
+}
+
+/**
+ * React 适配层：remoteComponent() / useLoadRemote() / RemoteErrorBoundary /
+ * createReactHostPages()。只接收加载函数，不静态引用运行时内核（同 vue-adapter 形态，
+ * dist/react.js 由构建脚本绑定 loadRemote 后再导出）。
+ *
+ * 语义要点（README React 章节的实现依据）：
+ * - remoteComponent：工厂与页面表声明零加载副作用；首次渲染才 loadRemote；
+ *   加载状态机自带 pending/error/ready 三态，不用 React.lazy——lazy 的失败 Promise
+ *   会缓存在实例上，仅重置错误边界无法恢复，必须重建加载尝试。retry 以受控 attempt
+ *   计数触发（不在普通 render 中重建加载器，组件本地状态不因重渲染反复重置）。
+ * - timeout 是本次组件加载等待上限（适配层实现），不取消 loadRemote 的共享请求，
+ *   不修改远程入口配置超时；迟到的成功/失败一律丢弃，不产生未处理 rejection。
+ *   retry 对已成功缓存的模块不重新下载（运行时缓存），只重走生命周期（onSession 按代次去重）。
+ * - 渲染期异常由内置 RemoteRenderBoundary 捕获，与网络/导出错误分开记录与展示；
+ *   ErrorBoundary 不捕获事件处理器与任意异步回调（React 边界语义，README 已声明）。
+ * - 代码全部 createElement（无 JSX）：适配器自身不依赖 jsx-runtime，减少共享子路径面。
+ */
+
+type LoadRemoteFn = (spec: string, opts?: LoadRemoteOptions) => Promise<any>;
+/** 渲染函数形态的错误占位：(error, retry) => ReactNode；与 remoteComponent.error 一致 */
+type RemoteErrorFallback = (error: unknown, retry: () => void) => ReactNode;
+interface ReactRemoteComponentOptions {
+    /** 本次加载 pending 时的占位（区别于失败占位）；默认 null */
+    fallback?: ReactNode;
+    /** 加载失败或子树渲染错误的展示；默认内置中文占位（错误码+根因+修法+重试） */
+    error?: ReactNode | RemoteErrorFallback;
+    /** 透传现行 loadRemote 的重试选项（0-10 整数），不另叠自动重试 */
+    retries?: number;
+    /** 本次组件加载等待上限 ms；不提供则沿用 loadRemote 自身超时。不取消已发出的共享请求 */
+    timeout?: number;
+}
+interface RemoteErrorBoundaryProps {
+    children?: ReactNode;
+    /** 错误占位：节点或 ({ error, reset }) 渲染函数；默认内置中文占位 */
+    fallback?: ReactNode | ((args: {
+        error: unknown;
+        reset: () => void;
+    }) => ReactNode);
+    /** 渲染异常回调（error + React componentStack 信息） */
+    onError?: (error: unknown, info: ErrorInfo) => void;
+    /** 任一项变化时重置边界状态（受控重试的常用形态：传 [retryEpoch]） */
+    resetKeys?: readonly unknown[];
+}
+interface BoundaryState {
+    error: unknown | null;
+}
+/**
+ * 页面级错误边界：只捕获传到它的子树渲染错误。remoteComponent 内置边界已处理自身错误，
+ * 外层边界看不到内层已消费的异常。reset 只重置边界状态；子组件若持有失败缓存
+ * （如 React.lazy），还需要由调用方重建加载尝试（remoteComponent 的 retry 已含两者）。
+ */
+declare class RemoteErrorBoundary extends Component<RemoteErrorBoundaryProps, BoundaryState> {
+    state: BoundaryState;
+    static getDerivedStateFromError(error: unknown): BoundaryState;
+    componentDidCatch(error: unknown, info: ErrorInfo): void;
+    componentDidUpdate(prev: RemoteErrorBoundaryProps): void;
+    readonly reset: () => void;
+    render(): ReactNode;
+}
+declare function createRemoteComponent(loadRemote: LoadRemoteFn): <P = Record<string, unknown>>(spec: string, opts?: ReactRemoteComponentOptions) => ComponentType<P & {
+    ref?: Ref<unknown>;
+}>;
+interface UseLoadRemoteOptions {
+    /** 透传 loadRemote 的 shareScope */
+    shareScope?: string;
+    /** 透传 loadRemote 的重试次数（0-10 整数） */
+    retries?: number;
+    /**
+     * 用户显式配置的失败兜底模块（透传 loadRemote.fallbackModule）：配置后加载失败返回
+     * 兜底值而不写 error。这是显式声明的行为，不是静默成功——README 已说明。
+     */
+    fallbackModule?: () => any;
+}
+interface UseLoadRemoteResult<Module = any> {
+    /** 加载成功后的模块命名空间；未成功时 undefined */
+    data: Module | undefined;
+    /** 失败原因；无错误时恒为 undefined（统一空值） */
+    error: unknown;
+    /** 是否有请求在途 */
+    loading: boolean;
+    /** 重新走一次加载生命周期；已成功的模块经运行时缓存不会重新下载。Promise<void> 正常结束（不抛） */
+    reload: () => Promise<void>;
+}
+declare function createUseLoadRemote(loadRemote: LoadRemoteFn): <Module = any>(spec: string, opts?: UseLoadRemoteOptions) => UseLoadRemoteResult<Module>;
+interface ReactHostPagesOptions extends HostPagesCoreOptions {
+    /** 每次页面模块实际加载尝试前执行（同步或异步）；宿主在此提供最新 context */
+    beforeLoad?: () => void | Promise<void>;
+    /** 页面加载 pending 占位（同 remoteComponent.fallback） */
+    fallback?: ReactNode;
+    /** 页面加载/渲染错误占位（同 remoteComponent.error） */
+    error?: ReactNode | RemoteErrorFallback;
+    /** 透传 loadRemote 重试（0-10 整数） */
+    retries?: number;
+    /** 单次页面组件加载等待上限 ms（同 remoteComponent.timeout） */
+    timeout?: number;
+}
+interface ReactHostPages {
+    /** 原页面记录 */
+    pages: PageRouteLike[];
+    /** 路径 → 页面解析（base 前缀、最长前缀、参数解码、R1–R5 语义与 Vue 完全一致） */
+    resolve(path: string): ResolvedHostPage | null;
+    /** 按 spec 取页面组件（同 spec 同登录代次复用；新非空 sessionKey 到来时重建以触发 onSession） */
+    component<P = Record<string, unknown>>(spec: string): ComponentType<P>;
+}
+declare function createReactHostPages(options: ReactHostPagesOptions, loadRemote: LoadRemoteFn): ReactHostPages;
+
+export { type ReactHostPages, type ReactHostPagesOptions, type ReactRemoteComponentOptions, RemoteErrorBoundary, type RemoteErrorBoundaryProps, type RemoteErrorFallback, ResolvedHostPage, type UseLoadRemoteOptions, type UseLoadRemoteResult, createReactHostPages, createRemoteComponent, createUseLoadRemote };