@cfp-studio/plugin-react 17.3.1 → 17.3.2

package/README.md

@@ -9,6 +9,7 @@ React 框架的 CFP Studio 插件，支持 React 组件/Story 静态分析、属
 - 兼容 CSF/Storybook 规范，支持 args/参数提取
 - 支持 preview 目录下自定义 Wrapper、ErrorBoundary、不同 React 版本渲染器
 - 内置丰富的 E2E/单元测试用例，覆盖多种工程模板
+- **兼容 UmiJS 4 工程**（`umi` / `@umijs/max`），见下文
 
 ## 架构与工作原理
 
@@ -33,6 +34,95 @@ import { reactFrameworkPlugin } from "@cfp-studio/plugin-react";
 // 传入 core/Previewer 或 createChromelessWorkspace 等集成
 ```
 
+## UmiJS 支持
+
+支持 **Umi 4**（`umi` 或 `@umijs/max`，已用 `4.7.30` 验证）。Umi 5 不存在，npm 最新即 4.x。
+
+**Umi 3 明确不支持**（不再维护，且用的是 react-router 5，与 Umi 4 是两套语义）。
+Umi 3 工程会走普通 React 路径：不 alias `umi`，也不加 `@/` 别名。
+纯 React 组件能渲染；用了 `import … from "umi"` 的组件会明确报错（不会给出误导性的假实现）。
+
+完整设计与决策记录见 [`docs/spec-umijs-support.md`](docs/spec-umijs-support.md)。
+
+自动生效的三件事（无需配置）：
+
+| 能力 | 说明 |
+| --- | --- |
+| `@/` → `src/` 别名 | **不依赖工程的 `tsconfig.paths`**；`@@/` → `src/.umi/` 仅在生成目录存在时添加 |
+| 传递依赖的 React | 真实 Umi 4 工程不声明 `react`，由框架包带入；插件会解析实际安装位置 |
+| 生成目录排除 | `src/.umi*` 不进组件列表 |
+
+### Umi 运行时的降级行为
+
+`umi` 是服务端 + 客户端混合包，直接在浏览器里跑会用到 `process.platform` 等 Node API 而崩。
+预览用 [`preview/shims/umi.tsx`](preview/shims/umi.tsx) 顶替它，**只改模块解析，不碰业务代码**。
+
+| API | 预览里的行为 |
+| --- | --- |
+| `useModel` | **恒返回 `{}`**（不猜初值）。要真实初值请在 `__previewjs__/Wrapper.tsx` 里包 Provider |
+| `useRequest` / `useFetcher` | **返回空态**：`{ data: undefined, loading: false, … }` / `state: "idle"`，`useRequest` 会打一条 `console.debug` |
+| `history` / `useNavigate` / `useLocation` | 内存版位置栈，`push` 后可被 `useLocation` 观察到 |
+| `useParams` / `useSearchParams` | 空值（`{}` / 空 `URLSearchParams`） |
+| `useAppData` | 结构完整的空上下文（`routes: {}`、`clientRoutes: []` 等）。`clientRoutes.length` 为 `0`，不是 `undefined` |
+| `useSelectedRoutes` / `useMatch` / `useRoutes` / `useOutlet` | 空值（`[]` / `null`） |
+| `useRouteProps` / `useRouteData` / `useOutletContext` | 空对象（`{}` / `{ route: {} }`） |
+| `useServerLoaderData` / `useClientLoaderData` / `useLoaderData` | 空态（`{ data: undefined }` / `undefined`） |
+| `Link` / `NavLink` / `LinkWithPrefetch` | 渲染成 `<a>`，点击被拦截 |
+| `Outlet` / `Navigate` | 渲染 `null`；`Navigate` 会把目标路径记进内存 location |
+| `Helmet` / `HelmetProvider` | 渲染子节点，不改文档头 |
+| `connect` / `withRouter` | 直通 HOC |
+| `createSearchParams` / `generatePath` / `matchPath` / `resolvePath` | **真实语义**（不需要路由上下文，没必要降级） |
+| `matchRoutes` | 恒 `null`（预览没有路由表） |
+| `createMemoryHistory` / `createBrowserHistory` / `createHashHistory` | 同内存版 `history`（接口较真实 `history` 包小很多） |
+| `request` / `renderClient` / `__getRoot` | **显式抛错**，并说明「请用 DevBrowser（应用预览）」 |
+
+判据：**渲染路径上的高频 API 给降级值**（抛错会让整棵树挂掉），**不在渲染路径的显式失败**。
+`useRequest` 返回空态意味着组件会显示「无数据」—— 那是预期行为，不是 bug。
+
+### 为什么导出面必须完整
+
+ESM 是**静态**导出校验：shim 少导出任何一个 Umi 名字，整个模块就
+`SyntaxError: does not provide an export named '…'`，组件连挂载机会都没有 ——
+**预览直接白屏**，而报错里只有 `__previewjs_internal__/renderer/shims/umi.tsx`
+这个内部路径，用户看不出发生了什么。
+
+所以即使是用不上的应用级 API（`renderClient` / `__getRoot`）也**显式导出并抛错**，
+而不是省略。`tests/umi.spec.ts` 的用例 3d 把这条约束固化成了回归测试
+（故意把一个导出去掉，它就会红）。
+
+### 用真实的 `react-router`（accessory lib）
+
+组件里直接 `import { useHref } from "react-router"` 是支持的 —— 插件会把
+`react-router` / `react-router-dom` 解析到 `umi` 依赖树里的实际安装位置（它们是 **`umi` 的传递依赖**）。
+
+但这些 hook 必须活在 `<Router>` 里。**预览不替你决定路由形态**（memory / hash / browser、
+初始路径、basename），请在 `__previewjs__/Wrapper.tsx` 里自己包一层：
+
+```tsx
+import { ReactNode } from "react";
+import { MemoryRouter } from "react-router-dom";
+
+export const Wrapper = ({ children }: { children: ReactNode }) => {
+	return <MemoryRouter initialEntries={["/"]}>{children}</MemoryRouter>;
+};
+```
+
+（导出必须是**具名** `Wrapper`。）不包的话会报
+`useHref() may be used only in the context of a <Router> component`。
+
+> 版本以 Umi 为准（当前 `react-router` **6.3.0**）。用了 6.4+ 的 API（如 `createBrowserRouter`）会报
+> `does not provide an export named`。
+
+更一般的 Wrapper 用法（主题、状态、布局、能做什么 / 做不到什么）见
+[用户文档 · 组件预览](../../../../docs/user/04-component-preview.md#用-wrapper-包住组件)。
+
+### 不覆盖的范围
+
+- **路由 / 页面级约定**（`pages/*` 的 route props、layout、约定式路由）—— 预览把页面当普通组件渲染。
+  整站/带数据场景走应用预览（dev server），见 `docs/specs/0001-runtime-bridge`。
+- **`.umirc.ts` 的 `alias` / `proxy` 配置** —— 预览不读 Umi 的工程配置（`alias` 的原因见 spec §23.1）。
+- **`@umijs/max` 插件生态的语义**（`access` / `initialState` / `micro`）—— 只有上面表里的降级值。
+
 ## 依赖
 
 - `react`、`@cfp-studio/*`、`typescript`、`vite`、`esbuild-plugin-polyfill-node`

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 /// <reference types="node" />
+import * as fs$1 from "node:fs";
 import * as url$1 from "node:url";
 import { URL as URL$1 } from "node:url";
-import * as fs$1 from "node:fs";
 import { Reader } from "@cfp-studio/vfs";
 import { Analyzer } from "@cfp-studio/analyzer-api";
 import * as http from "node:http";
@@ -5721,10 +5721,16 @@ interface FrameworkPluginFactory {
   /**
    * 检查当前项目的依赖是否与该框架插件兼容。
    *
-   * @param dependencies - 项目的依赖包信息。
+   * @param dependencies - 项目的依赖包信息。**只含工程 `package.json` 里显式声明的包**
+   *   （`dependencies` / `devDependencies` / `peerDependencies` 的并集），
+   *   不含传递依赖。
+   * @param rootDir - 工程根目录（可选，向后兼容）。
+   *   有些框架（如 Umi 4）**不显式声明 `react`**，而由框架包作为传递依赖带入 ——
+   *   那种情况下 `dependencies.react` 是 `undefined`，插件需要靠 `rootDir` 自行解析。
+   *   见 `docs/spec-umijs-support.md` §15。
    * @returns 一个 Promise，解析为布尔值，表示是否兼容。
    */
-  isCompatible(dependencies: PackageDependencies): Promise<boolean>;
+  isCompatible(dependencies: PackageDependencies, rootDir?: string): Promise<boolean>;
   /**
    * 创建框架插件实例。
    *
@@ -5762,6 +5768,17 @@ interface FrameworkPlugin extends Analyzer {
    * @returns Vite 用户配置对象。
    */
   viteConfig: (configuredPlugins: Plugin[]) => UserConfig;
+  /**
+   * 该框架的**生成目录** glob，供文件爬取排除（可选）。
+   *
+   * 用于框架把代码生成到工程内的场景 —— 例如 Umi 4 的 `src/.umi`，
+   * dev server 一跑就是几万行。不排除的话它们会进组件树，
+   * 既慢又干扰（`docs/spec-umijs-support.md` G2）。
+   *
+   * 语义边界：**只是"不扫这些路径"**，不是 gitignore，也不影响文件读取
+   * （`@cfp-studio/reader` 仍能读到）。不实现该字段即保持现状。
+   */
+  ignoredPaths?: string[];
   /**
    * 清理插件资源的方法。
    * 当插件不再使用时，调用此方法释放资源。
@@ -5777,9 +5794,24 @@ interface FrameworkPlugin extends Analyzer {
  */
 //#endregion
 //#region src/index.d.ts
+/**
+ * Umi 4 工程里需要从依赖预构建中排除的 native 模块。
+ *
+ * **为什么需要**：`@umijs/bundler-vite` 自带一份 `vite@7`，其依赖 `fsevents`
+ * 含 `.node` 二进制；esbuild 的依赖预构建没有 `.node` 的 loader，会导致
+ * `error while updating dependencies` 而整个预览起不来。
+ *
+ * 实测（`docs/spec-umijs-support.md` §11.2）：不加这两项，任何
+ * `import ... from "umi"` 的组件都无法预览。
+ *
+ * 只排除**已知的 native 模块**，不做 `platform: "node"` 之类的全局放宽 ——
+ * 那会改变所有依赖的构建目标。
+ */
+declare const UMI_NATIVE_MODULES_TO_EXCLUDE: string[];
+declare const UMI_GENERATED_DIR_GLOBS: string[];
 declare const reactFrameworkPlugin: FrameworkPluginFactory;
 /**
  * 导出默认的 reactFrameworkPlugin 对象
  */
 //#endregion
-export { reactFrameworkPlugin as default };
+export { UMI_GENERATED_DIR_GLOBS, UMI_NATIVE_MODULES_TO_EXCLUDE, reactFrameworkPlugin as default };

package/dist/index.mjs

@@ -1 +1 @@
-import e from"node:path";import t from"node:url";import n from"@vitejs/plugin-react";import{polyfillNode as r}from"esbuild-plugin-polyfill-node";import i from"node:fs";import{createAnalyzer as a}from"@cfp-studio/analyzer-api/analyzer";import{createFileSystemReader as o,createStackedReader as s}from"@cfp-studio/vfs";import c from"typescript";import{decodePreviewableId as l,defineSpecialTypes as u,generatePreviewableId as d}from"@cfp-studio/analyzer-api";import{parseSerializableValue as f}from"@cfp-studio/serializable-values";import{extractArgs as p,extractCsf3Stories as m,extractStoriesInfo as h,resolvePreviewableId as g}from"@cfp-studio/storybook-helpers";import{EMPTY_OBJECT_TYPE as _,NODE_TYPE as v,UNKNOWN_TYPE as y,arrayType as b,dereferenceType as x,functionType as S,helpers as C,maybeOptionalType as w,objectType as T,stripUnusedTypes as E}from"@cfp-studio/type-analyzer";function D(e,t){for(let n of e.statements)if(c.isExpressionStatement(n)&&c.isBinaryExpression(n.expression)&&n.expression.operatorToken.kind===c.SyntaxKind.EqualsToken&&c.isPropertyAccessExpression(n.expression.left)&&c.isIdentifier(n.expression.left.expression)){if(n.expression.left.expression.text!==t)continue;if(n.expression.left.name.text===`propTypes`)return n.expression.right}else if(c.isClassDeclaration(n)&&n.name){if(n.name.text!==t)continue;for(let e of n.members)if(c.isPropertyDeclaration(e)&&e.initializer&&e.name.getText()===`propTypes`)return e.initializer}return null}function O(e,t,n,r,i){let a=t.sourceFile(n),o=null;a&&(o=D(a,r));let s=null;return s=o?A(t,o):k(e,t,i),{props:s.type,types:{...s.collected}}}function k(e,t,n){let r=n.getParameters()[0];if(!r)return{type:_,collected:{}};if(!r.valueDeclaration)return{type:y,collected:{}};let i=t.checker.getTypeOfSymbolAtLocation(r,r.valueDeclaration);try{let{type:e,collected:n}=t.resolveType(i);if([e]=x(e,n,[]),e.kind===`object`&&c.isParameter(r.valueDeclaration)&&c.isObjectBindingPattern(r.valueDeclaration.name)){let t=r.valueDeclaration.name,n=new Set,i=new Set,a=!1;for(let e of t.elements){if(e.dotDotDotToken){a=!0;break}let t=e.propertyName||e.name;if(!c.isIdentifier(t)){a=!0;break}n.add(t.text),e.initializer&&i.add(t.text)}a||(e=T(Object.fromEntries(Object.entries(e.fields).filter(([e])=>n.has(e)).map(([e,t])=>[e,w(t,i.has(e))]))))}return{type:e,collected:n}}catch(n){e.warn(`Unable to resolve props type for ${t.checker.typeToString(i)}`),e.error(n.toString())}return{type:y,collected:{}}}function A(e,t){let n=e.checker.getTypeAtLocation(t),r={},i={};for(let t of n.getProperties())r[t.name]=(()=>{if(!t.valueDeclaration)return y;let n=e.checker.getTypeAtLocation(t.valueDeclaration),r=e.resolveTypeArguments(n),a=r.types[0];return a?(i={...i,...r.collected},w(a,n.symbol.name===`Requireable`)):y})();let a=T(r);return{type:a,collected:E(i,[a])}}async function j(t,n,r,i){let a=n.sourceFile(i);if(!a)return[];let o=[];for(let e of a.statements)if(c.isExportAssignment(e)){if(c.isIdentifier(e.expression))continue;o.push([`default`,e,e.expression])}else if(c.isVariableStatement(e))for(let t of e.declarationList.declarations)!c.isIdentifier(t.name)||!t.initializer||o.push([t.name.text,e,t.initializer]);else if(c.isFunctionDeclaration(e)){let t=!!e.modifiers?.find(e=>e.kind===c.SyntaxKind.ExportKeyword)&&!!e.modifiers?.find(e=>e.kind===c.SyntaxKind.DefaultKeyword),n=e.name?.text;(t||n)&&o.push([n||`default`,e,e])}else c.isClassDeclaration(e)&&e.name&&o.push([e.name.text,e,e]);let s=h(a);t.debug(`**storiresInfo: ${s}`);let u=[],g=p(a),_=C.extractExportedNames(a);async function v(e,a,o){if(o===`default`&&s)return null;let c=g[o],l=o===`default`||!!_[o],u=N(n.checker,a);if(s&&l&&(c||u?.parameters.length===0)){let i=M(t,n,r,s.component);return{...e,analyze:async()=>({args:c?{sourcePosition:{start:c.getStart(),end:c.getEnd()},value:await f(c)}:null}),associatedComponent:i}}return u?{...e,exported:l,analyze:async()=>O(t,n,i,o,u)}:null}for(let[t,n,a]of o){let o=await v({id:d({filePath:e.relative(r,i),name:t}),sourcePosition:{start:n.getStart(),end:n.getEnd()}},a,t);o&&u.push(o)}return[...u,...await m(r,n,a,async i=>{let{filePath:a}=l(i),o=(await j(t,n,r,e.join(r,a))).find(e=>e.id===i);return!o||!(`exported`in o)?{props:y,types:{}}:o.analyze()})]}function M(t,n,r,i){let a=g(r,n.checker,i);return i&&a?{id:a,analyze:async()=>{let o=N(n.checker,i);if(!o)return{props:y,types:{}};let{filePath:s,name:c}=l(a);return O(t,n,e.join(r,s),c,o)}}:null}function N(e,t){let n=e.getTypeAtLocation(t);if(n.flags===c.TypeFlags.Any&&c.isCallExpression(t)&&c.isPropertyAccessExpression(t.expression)&&c.isIdentifier(t.expression.name)&&t.expression.name.text===`bind`){let r=e.getSymbolAtLocation(t.expression.expression);r?.valueDeclaration&&c.isVariableDeclaration(r.valueDeclaration)&&r.valueDeclaration.initializer&&(n=e.getTypeAtLocation(r.valueDeclaration.initializer))}for(let e of n.getCallSignatures())if(P(e.getReturnType()))return e;if(n.symbol){let r=e.getTypeOfSymbolAtLocation(n.symbol,t);for(let e of r.getConstructSignatures())if(e.getReturnType().getProperty(`render`))return e}return null}function P(e){return!!I(e)}const F=new Set([`Element`,`ReactElement`]);function I(e){if(e.isUnion()){for(let t of e.types)if(I(t))return!0}return F.has(e.symbol?.getEscapedName().toString())}const L=u({Component:v,ComponentClass:S(v),FunctionComponent:S(v),ReactElement:v,ReactNode:v,ReactNodeArray:b(v),ReactPortal:v}),R=a({typeAnalyzerOptions:({reader:n,rootDir:r})=>{let a=t.fileURLToPath(new URL(`.`,import.meta.url)),l=e.join(a,`..`,`types`),u=e.join(a,`..`,`node_modules`),d=i.existsSync(l)?l:u;return{reader:s([n,o({mapping:{from:d,to:e.join(r,`node_modules`)},watch:!1}),...d===l?[o({mapping:{from:l,to:e.join(r,`node_modules`,`@types`)},watch:!1})]:[]]),specialTypes:L,tsCompilerOptions:{jsx:c.JsxEmit.ReactJSX,jsxImportSource:`react`}}},crawlFile:({logger:e,resolver:t,rootDir:n,absoluteFilePath:r})=>j(e,t,n,r)}),z={line:`data-inspector-line`,column:`data-inspector-column`,relativePath:`data-inspector-relative-path`};function B(e){return e.includes(z.relativePath)}function V(e,t){if(!e.includes(`<`)||B(e))return;let n=c.createSourceFile(t.relativePath,e,c.ScriptTarget.Latest,!0,c.ScriptKind.TSX),r=[],i=e=>{if(c.isJsxElement(e)||c.isJsxSelfClosingElement(e)){let i=c.isJsxElement(e)?e.openingElement:e,a=i.tagName.getStart(n),{line:o,character:s}=n.getLineAndCharacterOfPosition(a),l=i.tagName.getEnd(),u=` ${z.line}="${o+1}" ${z.column}="${s+1}" ${z.relativePath}="${H(t.relativePath)}"`;r.push({at:l,text:u})}c.forEachChild(e,i)};if(i(n),r.length===0)return;r.sort((e,t)=>t.at-e.at);let a=e;for(let{at:e,text:t}of r)a=a.slice(0,e)+t+a.slice(e);return a}function H(e){return e.replace(/&/g,`&amp;`).replace(/"/g,`&quot;`)}const U=/import (\* as )?React[ ,]/;function W(){return{name:`previewjs:react-js-imports`,async transform(t,n){return n.includes(`node_modules`)||e.extname(n)!==`.js`||U.test(t)?t:`import React from 'react';${t}`}}}function G(){let t=``;return{name:`previewjs:inspector-attrs`,enforce:`pre`,configResolved(e){t=e.root},transform(n,r){let i=r.split(`?`)[0]??r;if(!/\.[jt]sx$/.test(i)||i.includes(`node_modules`)||i.includes(`__previewjs__`))return;let a=V(n,{relativePath:e.relative(t,i).split(e.sep).join(`/`)});if(a!==void 0)return{code:a,map:null}}}}const K={info:{apiVersion:5,name:`@cfp-studio/plugin-react`},isCompatible:async e=>{let t=await e.react?.readInstalledVersion();if(!t)return!1;let[n,r]=t.split(`.`).map(e=>Number.parseInt(e));return Number.isNaN(n)||Number.isNaN(r)?!1:n>=17||n===16&&r>=14},async create({rootDir:i,reader:a,logger:o,dependencies:s}){let c=t.fileURLToPath(new URL(`.`,import.meta.url)),l=R({rootDir:i,reader:a,logger:o});return{defaultWrapperPath:`__previewjs__/Wrapper.tsx`,previewDirPath:e.join(c,`..`,`preview`),...l,viteConfig:e=>{let t=e.find(e=>e.name.startsWith(`vite:react-`));return{optimizeDeps:{esbuildOptions:{plugins:s.next?[r()]:[]}},resolve:{alias:{"react-native":`react-native-web`}},plugins:[G(),W(),...e,...t?[]:[n()],{name:`previewjs:update-react-import`,async transform(e,t){if(!t.endsWith(`__previewjs_internal__/renderer/index.tsx`))return;let n=Number.parseInt(await s.react?.readInstalledVersion()||`0`);return e.replace(/__PREVIEWJS_PLUGIN_REACT_IMPORT_PATH__/g,n>=18?`./render-18`:`./render-16`)}}]}}}}};export{K as default};
+import{createRequire as e}from"node:module";import t from"node:fs";import n from"node:path";import r from"node:url";import i from"@vitejs/plugin-react";import{polyfillNode as a}from"esbuild-plugin-polyfill-node";import{createAnalyzer as o}from"@cfp-studio/analyzer-api/analyzer";import{createFileSystemReader as s,createStackedReader as c}from"@cfp-studio/vfs";import l from"typescript";import{decodePreviewableId as u,defineSpecialTypes as d,generatePreviewableId as f}from"@cfp-studio/analyzer-api";import{parseSerializableValue as p}from"@cfp-studio/serializable-values";import{extractArgs as m,extractCsf3Stories as h,extractStoriesInfo as g,resolvePreviewableId as _}from"@cfp-studio/storybook-helpers";import{EMPTY_OBJECT_TYPE as v,NODE_TYPE as y,UNKNOWN_TYPE as b,arrayType as x,dereferenceType as S,functionType as C,helpers as w,maybeOptionalType as T,objectType as E,stripUnusedTypes as D}from"@cfp-studio/type-analyzer";function O(e,t){for(let n of e.statements)if(l.isExpressionStatement(n)&&l.isBinaryExpression(n.expression)&&n.expression.operatorToken.kind===l.SyntaxKind.EqualsToken&&l.isPropertyAccessExpression(n.expression.left)&&l.isIdentifier(n.expression.left.expression)){if(n.expression.left.expression.text!==t)continue;if(n.expression.left.name.text===`propTypes`)return n.expression.right}else if(l.isClassDeclaration(n)&&n.name){if(n.name.text!==t)continue;for(let e of n.members)if(l.isPropertyDeclaration(e)&&e.initializer&&e.name.getText()===`propTypes`)return e.initializer}return null}function k(e,t,n,r,i){let a=t.sourceFile(n),o=null;a&&(o=O(a,r));let s=null;return s=o?j(t,o):A(e,t,i),{props:s.type,types:{...s.collected}}}function A(e,t,n){let r=n.getParameters()[0];if(!r)return{type:v,collected:{}};if(!r.valueDeclaration)return{type:b,collected:{}};let i=t.checker.getTypeOfSymbolAtLocation(r,r.valueDeclaration);try{let{type:e,collected:n}=t.resolveType(i);if([e]=S(e,n,[]),e.kind===`object`&&l.isParameter(r.valueDeclaration)&&l.isObjectBindingPattern(r.valueDeclaration.name)){let t=r.valueDeclaration.name,n=new Set,i=new Set,a=!1;for(let e of t.elements){if(e.dotDotDotToken){a=!0;break}let t=e.propertyName||e.name;if(!l.isIdentifier(t)){a=!0;break}n.add(t.text),e.initializer&&i.add(t.text)}a||(e=E(Object.fromEntries(Object.entries(e.fields).filter(([e])=>n.has(e)).map(([e,t])=>[e,T(t,i.has(e))]))))}return{type:e,collected:n}}catch(n){e.warn(`Unable to resolve props type for ${t.checker.typeToString(i)}`),e.error(n.toString())}return{type:b,collected:{}}}function j(e,t){let n=e.checker.getTypeAtLocation(t),r={},i={};for(let t of n.getProperties())r[t.name]=(()=>{if(!t.valueDeclaration)return b;let n=e.checker.getTypeAtLocation(t.valueDeclaration),r=e.resolveTypeArguments(n),a=r.types[0];return a?(i={...i,...r.collected},T(a,n.symbol.name===`Requireable`)):b})();let a=E(r);return{type:a,collected:D(i,[a])}}async function M(e,t,r,i){let a=t.sourceFile(i);if(!a)return[];let o=[];for(let e of a.statements)if(l.isExportAssignment(e)){if(l.isIdentifier(e.expression))continue;o.push([`default`,e,e.expression])}else if(l.isVariableStatement(e))for(let t of e.declarationList.declarations)!l.isIdentifier(t.name)||!t.initializer||o.push([t.name.text,e,t.initializer]);else if(l.isFunctionDeclaration(e)){let t=!!e.modifiers?.find(e=>e.kind===l.SyntaxKind.ExportKeyword)&&!!e.modifiers?.find(e=>e.kind===l.SyntaxKind.DefaultKeyword),n=e.name?.text;(t||n)&&o.push([n||`default`,e,e])}else l.isClassDeclaration(e)&&e.name&&o.push([e.name.text,e,e]);let s=g(a);e.debug(`**storiresInfo: ${s}`);let c=[],d=m(a),_=w.extractExportedNames(a);async function v(n,a,o){if(o===`default`&&s)return null;let c=d[o],l=o===`default`||!!_[o],u=P(t.checker,a);if(s&&l&&(c||u?.parameters.length===0)){let i=N(e,t,r,s.component);return{...n,analyze:async()=>({args:c?{sourcePosition:{start:c.getStart(),end:c.getEnd()},value:await p(c)}:null}),associatedComponent:i}}return u?{...n,exported:l,analyze:async()=>k(e,t,i,o,u)}:null}for(let[e,t,a]of o){let o=await v({id:f({filePath:n.relative(r,i),name:e}),sourcePosition:{start:t.getStart(),end:t.getEnd()}},a,e);o&&c.push(o)}return[...c,...await h(r,t,a,async i=>{let{filePath:a}=u(i),o=(await M(e,t,r,n.join(r,a))).find(e=>e.id===i);return!o||!(`exported`in o)?{props:b,types:{}}:o.analyze()})]}function N(e,t,r,i){let a=_(r,t.checker,i);return i&&a?{id:a,analyze:async()=>{let o=P(t.checker,i);if(!o)return{props:b,types:{}};let{filePath:s,name:c}=u(a);return k(e,t,n.join(r,s),c,o)}}:null}function P(e,t){let n=e.getTypeAtLocation(t);if(n.flags===l.TypeFlags.Any&&l.isCallExpression(t)&&l.isPropertyAccessExpression(t.expression)&&l.isIdentifier(t.expression.name)&&t.expression.name.text===`bind`){let r=e.getSymbolAtLocation(t.expression.expression);r?.valueDeclaration&&l.isVariableDeclaration(r.valueDeclaration)&&r.valueDeclaration.initializer&&(n=e.getTypeAtLocation(r.valueDeclaration.initializer))}for(let e of n.getCallSignatures())if(F(e.getReturnType()))return e;if(n.symbol){let r=e.getTypeOfSymbolAtLocation(n.symbol,t);for(let e of r.getConstructSignatures())if(e.getReturnType().getProperty(`render`))return e}return null}function F(e){return!!L(e)}const I=new Set([`Element`,`ReactElement`]);function L(e){if(e.isUnion()){for(let t of e.types)if(L(t))return!0}return I.has(e.symbol?.getEscapedName().toString())}const R=d({Component:y,ComponentClass:C(y),FunctionComponent:C(y),ReactElement:y,ReactNode:y,ReactNodeArray:x(y),ReactPortal:y}),z=o({typeAnalyzerOptions:({reader:e,rootDir:i})=>{let a=r.fileURLToPath(new URL(`.`,import.meta.url)),o=n.join(a,`..`,`types`),u=n.join(a,`..`,`node_modules`),d=t.existsSync(o)?o:u;return{reader:c([e,s({mapping:{from:d,to:n.join(i,`node_modules`)},watch:!1}),...d===o?[s({mapping:{from:o,to:n.join(i,`node_modules`,`@types`)},watch:!1})]:[]]),specialTypes:R,tsCompilerOptions:{jsx:l.JsxEmit.ReactJSX,jsxImportSource:`react`}}},crawlFile:({logger:e,resolver:t,rootDir:n,absoluteFilePath:r})=>M(e,t,n,r)}),B={line:`data-inspector-line`,column:`data-inspector-column`,relativePath:`data-inspector-relative-path`};function V(e){return e.includes(B.relativePath)}function H(e,t){if(!e.includes(`<`)||V(e))return;let n=l.createSourceFile(t.relativePath,e,l.ScriptTarget.Latest,!0,l.ScriptKind.TSX),r=[],i=e=>{if(l.isJsxElement(e)||l.isJsxSelfClosingElement(e)){let i=l.isJsxElement(e)?e.openingElement:e,a=i.tagName.getStart(n),{line:o,character:s}=n.getLineAndCharacterOfPosition(a),c=i.tagName.getEnd(),u=` ${B.line}="${o+1}" ${B.column}="${s+1}" ${B.relativePath}="${U(t.relativePath)}"`;r.push({at:c,text:u})}l.forEachChild(e,i)};if(i(n),r.length===0)return;r.sort((e,t)=>t.at-e.at);let a=e;for(let{at:e,text:t}of r)a=a.slice(0,e)+t+a.slice(e);return a}function U(e){return e.replace(/&/g,`&amp;`).replace(/"/g,`&quot;`)}const W=/import (\* as )?React[ ,]/;function G(){return{name:`previewjs:react-js-imports`,async transform(e,t){return t.includes(`node_modules`)||n.extname(t)!==`.js`||W.test(e)?e:`import React from 'react';${e}`}}}const K=e(import.meta.url),q=[`fsevents`];function J(e,t){if(t.react)return{};let r={};for(let t of[`react`,`react-dom`])try{let i=K.resolve(`${t}/package.json`,{paths:[e]});r[t]=n.dirname(i)}catch{}return r}function Y(e,r){try{let i=K.resolve(e,{paths:[r]}),a=n.dirname(i);for(;a!==n.dirname(a);){let e=n.join(a,`package.json`);if(t.existsSync(e)){let n=JSON.parse(t.readFileSync(e,`utf8`));return typeof n.version==`string`?n.version:null}a=n.dirname(a)}return null}catch{return null}}const X=[`src/.umi/**`,`src/.umi-production/**`,`src/.umi-test/**`,`src/.umi-tmp/**`];function Z(){let e=``;return{name:`previewjs:inspector-attrs`,enforce:`pre`,configResolved(t){e=t.root},transform(t,r){let i=r.split(`?`)[0]??r;if(!/\.[jt]sx$/.test(i)||i.includes(`node_modules`)||i.includes(`__previewjs__`)||i.includes(`__previewjs_internal__`))return;let a=H(t,{relativePath:n.relative(e,i).split(n.sep).join(`/`)});if(a!==void 0)return{code:a,map:null}}}}const Q={info:{apiVersion:5,name:`@cfp-studio/plugin-react`},isCompatible:async(e,t)=>{let n=await e.react?.readInstalledVersion();if(!n&&t&&(n=Y(`react`,t)),!n)return!1;let[r,i]=n.split(`.`).map(e=>Number.parseInt(e));return Number.isNaN(r)||Number.isNaN(i)?!1:r>=17||r===16&&i>=14},async create({rootDir:e,reader:o,logger:s,dependencies:c}){let l=r.fileURLToPath(new URL(`.`,import.meta.url)),u=await c.umi?.readInstalledVersion()??await c[`@umijs/max`]?.readInstalledVersion(),d=u?Number.parseInt(u.split(`.`)[0]??`0`)>=4:!1,f=z({rootDir:e,reader:o,logger:s}),p=n.join(l,`..`,`preview`),m=J(e,c),h=`/__previewjs_internal__/renderer/shims/umi.tsx`,g=n.join(e,`src`),_={};if(d){t.existsSync(g)&&(_[`@`]=g);let r=n.join(g,`.umi`);t.existsSync(r)?_[`@@`]=r:s.debug(`umi: 跳过 @@ 别名，src/.umi 不存在（dev server 未启动）`);let i=(()=>{try{return n.dirname(K.resolve(`umi`,{paths:[e]}))}catch{try{return n.dirname(K.resolve(`@umijs/max`,{paths:[e]}))}catch{return e}}})();for(let e of[`react-router`,`react-router-dom`])try{let t=K.resolve(`${e}/package.json`,{paths:[i]});_[e]=n.dirname(t)}catch{s.debug(`umi: 跳过 ${e} 别名，解析不到实际安装位置`)}}return{defaultWrapperPath:`__previewjs__/Wrapper.tsx`,previewDirPath:p,ignoredPaths:d?X:[],...f,viteConfig:e=>{let t=e.find(e=>e.name.startsWith(`vite:react-`));return{optimizeDeps:{...d?{exclude:q}:{},esbuildOptions:{plugins:c.next?[a()]:[]}},resolve:{alias:{"react-native":`react-native-web`,...m,...d?{umi:h,"@umijs/max":h,..._}:{}}},plugins:[Z(),G(),...e,...t?[]:[i()],{name:`previewjs:update-react-import`,async transform(e,t){if(!t.endsWith(`__previewjs_internal__/renderer/index.tsx`))return;let n=Number.parseInt(await c.react?.readInstalledVersion()||`0`);return e.replace(/__PREVIEWJS_PLUGIN_REACT_IMPORT_PATH__/g,n>=18?`./render-18`:`./render-16`)}}]}}}}};export{X as UMI_GENERATED_DIR_GLOBS,q as UMI_NATIVE_MODULES_TO_EXCLUDE,Q as default};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cfp-studio/plugin-react",
-  "version": "17.3.1",
+  "version": "17.3.2",
   "license": "MIT",
   "files": [
     "dist",
@@ -16,10 +16,10 @@
     "esbuild-plugin-polyfill-node": "0.3.0",
     "typescript": "5.9.3",
     "@cfp-studio/analyzer-api": "0.1.13",
-    "@cfp-studio/serializable-values": "9.0.8",
     "@cfp-studio/storybook-helpers": "6.0.2",
+    "@cfp-studio/serializable-values": "9.0.8",
     "@cfp-studio/type-analyzer": "10.1.8",
-    "@cfp-studio/vfs": "2.1.7"
+    "@cfp-studio/vfs": "2.1.8"
   },
   "devDependencies": {
     "@playwright/test": "1.64.1",
@@ -33,9 +33,9 @@
     "react-dom": "18.3.1",
     "vite": "6.4.5",
     "vitest": "5.0.5",
-    "@cfp-studio/core": "1.0.6",
-    "@cfp-studio/iframe": "18.4.1",
-    "@cfp-studio/testing": "14.0.1"
+    "@cfp-studio/core": "1.0.8",
+    "@cfp-studio/testing": "14.0.1",
+    "@cfp-studio/iframe": "18.4.3"
   },
   "engines": {
     "node": ">=20"
@@ -51,7 +51,7 @@
     "typecheck": "tsc --noEmit && tsc -p preview/tsconfig.json",
     "test": "node scripts/prepare-types.mjs && vitest run",
     "test:watch": "vitest watch",
-    "e2e-test": "pnpm --dir tests/apps/react16 install --ignore-workspace --ignore-scripts && pnpm --dir tests/apps/react17 install --ignore-workspace --ignore-scripts && pnpm --dir tests/apps/react18 install --ignore-workspace --ignore-scripts && pnpm --dir tests/apps/react-sass install --ignore-workspace --ignore-scripts && playwright test",
+    "e2e-test": "pnpm --dir tests/apps/react16 install --ignore-workspace --ignore-scripts && pnpm --dir tests/apps/react17 install --ignore-workspace --ignore-scripts && pnpm --dir tests/apps/react18 install --ignore-workspace --ignore-scripts && pnpm --dir tests/apps/react-sass install --ignore-workspace --ignore-scripts && pnpm --dir tests/apps/umi4 install --ignore-workspace --ignore-scripts && pnpm --dir tests/apps/umi-max install --ignore-workspace --ignore-scripts && tsx scripts/link-shared-umi-fixtures.ts && playwright test",
     "lint": "oxlint",
     "format": "oxfmt --write ."
   }

package/preview/shims/router-utils.spec.ts

@@ -0,0 +1,158 @@
+import { describe, expect, it } from "vitest";
+
+import { generatePath, matchPath, resolvePath } from "./umi.js";
+
+/**
+ * 对照测试：shim 里 react-router 纯函数的转导出必须与 `react-router@6.3.0`
+ * 的**真实输出**一致。
+ *
+ * 每个期望值都是在真实包上跑出来的（不是手写的猜测）：
+ *
+ * ```sh
+ * node -e "const rr=require('<...>/react-router/main.js'); console.log(rr.matchPath('/users/:id','/users/42'))"
+ * ```
+ *
+ * ## 为什么这份测试重要
+ *
+ * 早期 shim 用的是「按 `/` 切段逐个比」的简版，错四处且都很难发现：
+ *
+ * | # | 输入 | 简版错误 | 后果 |
+ * | --- | --- | --- | --- |
+ * | 1 | 任意 | 返回 `params` 本体而非 `{ params, pathname, pathnameBase, pattern }` | 写 `match?.params.id` 的组件拿到 `undefined` |
+ * | 2 | `/files/*` + `/files/a/b/c` | 丢掉 splat 捕获 | 组件看到「匹配成功」但 `params["*"]` 为空 |
+ * | 3 | `/users/:id` + `/Users/42` | 大小写敏感 → `null` | 大小写不同的 URL 导不了 |
+ * | 4 | `/users/:id?` + `/users/42` | 产出 `"id?"` 这个脏键 | 参数名带问号 |
+ *
+ * 简版还让 e2e 用例 3e 断言的是 `match?.id`（简版的形状）—— 测试是绿的，
+ * 但语义是错的。这份单测把真实形状固定下来。
+ *
+ * ## 为什么测试放在 `src/` 而不是 `preview/`
+ *
+ * `preview/` 整体被 `vitest.config.ts` 排除（里面是浏览器端渲染入口）。
+ * 这份用例虽然测的是 `preview/shims/umi.tsx`，但它只是普通函数、不碰 DOM，
+ * 从 `src/` 引用即可。
+ */
+describe("matchPath 与 react-router 6.3 对齐", () => {
+	it("返回 `{ params, pathname, pathnameBase, pattern }` 四键（不是 params 本体）", () => {
+		const match = matchPath("/users/:id", "/users/42");
+		expect(Object.keys(match ?? {}).sort()).toEqual(["params", "pathname", "pathnameBase", "pattern"]);
+	});
+
+	it("基本参数捕获", () => {
+		expect(matchPath("/users/:id", "/users/42")).toEqual({
+			params: { id: "42" },
+			pathname: "/users/42",
+			pathnameBase: "/users/42",
+			pattern: { path: "/users/:id", caseSensitive: false, end: true },
+		});
+	});
+
+	it("默认大小写不敏感（`caseSensitive: false`）", () => {
+		expect(matchPath("/users/:id", "/Users/42")?.params.id).toBe("42");
+	});
+
+	it("`caseSensitive: true` 时大小写敏感", () => {
+		expect(matchPath({ path: "/users/:id", caseSensitive: true }, "/Users/42")).toBeNull();
+	});
+
+	it('尾部 splat 是具名捕获组，值进 `params["*"]`', () => {
+		const match = matchPath("/files/*", "/files/a/b/c");
+		expect(match?.params["*"]).toBe("a/b/c");
+		// `pathnameBase` 不含 splat 部分。
+		expect(match?.pathnameBase).toBe("/files");
+	});
+
+	it("`/files/*` 也能匹配 `/files` 本身（splat 为空字符串，不是 undefined）", () => {
+		expect(matchPath("/files/*", "/files")?.params["*"]).toBe("");
+	});
+
+	it("`/users/:id/*` 同时捕获参数与 splat", () => {
+		const match = matchPath("/users/:id/*", "/users/42/extra/deep");
+		expect(match?.params.id).toBe("42");
+		expect(match?.params["*"]).toBe("extra/deep");
+	});
+
+	it("`end: false` 允许前缀匹配", () => {
+		expect(matchPath({ path: "/users", end: false }, "/users/42/extra")?.pathnameBase).toBe("/users");
+	});
+
+	it("默认 `end: true`：多出的段不匹配", () => {
+		expect(matchPath("/users/:id", "/users/42/extra")).toBeNull();
+	});
+
+	it("忽略尾部斜杠", () => {
+		expect(matchPath("/users/:id/", "/users/42")?.params.id).toBe("42");
+	});
+
+	it("根路径", () => {
+		expect(matchPath("/", "/")).toEqual({
+			params: {},
+			pathname: "/",
+			pathnameBase: "/",
+			pattern: { path: "/", caseSensitive: false, end: true },
+		});
+	});
+
+	it("纯 `*` 匹配任意路径", () => {
+		expect(matchPath("*", "/anything/at/all")?.params["*"]).toBe("anything/at/all");
+	});
+
+	it("URL 段会被解码", () => {
+		expect(matchPath("/u/:id", "/u/%E4%B8%AD")?.params.id).toBe("中");
+	});
+
+	it("malformed 百分号编码不抛错，原样返回", () => {
+		expect(matchPath("/u/:id", "/u/%ZZ")?.params.id).toBe("%ZZ");
+	});
+
+	it("`:id?` 在 v6 不是可选段，且不产出 `id?` 这种脏键", () => {
+		// 与真实 react-router 一致：`?` 被当作字面字符，匹配不上。
+		expect(matchPath("/users/:id?", "/users/42")).toBeNull();
+		expect(matchPath("/users/:id?", "/users")).toBeNull();
+	});
+});
+
+describe("resolvePath 与 react-router 6.3 对齐", () => {
+	const cases: Array<[string, string, string]> = [
+		["child", "/parent/", "/parent/child"],
+		["child", "/parent", "/parent/child"],
+		["../sibling", "/a/b/", "/a/sibling"],
+		["../../up", "/a/b/c", "/a/up"],
+		["./same", "/a/b", "/a/b/same"],
+		["", "/a/b", "/a/b"],
+		["/abs", "/a/b", "/abs"],
+		["child", "/", "/child"],
+	];
+
+	for (const [to, from, expected] of cases) {
+		it(`resolvePath(${JSON.stringify(to)}, ${JSON.stringify(from)}) → ${expected}`, () => {
+			expect(resolvePath(to, from).pathname).toBe(expected);
+		});
+	}
+
+	it("保留 search 与 hash（并补上前缀符号）", () => {
+		expect(resolvePath("x?q=1#h", "/base/")).toEqual({ pathname: "/base/x", search: "?q=1", hash: "#h" });
+	});
+});
+
+describe("generatePath 与 react-router 6.3 对齐", () => {
+	it("替换 `:param`", () => {
+		expect(generatePath("/users/:id/posts/:postId", { id: "7", postId: "9" })).toBe("/users/7/posts/9");
+	});
+
+	it("不做 URL 编码（中文原样）", () => {
+		expect(generatePath("/u/:id", { id: "中文" })).toBe("/u/中文");
+	});
+
+	it("支持尾部 splat", () => {
+		expect(generatePath("/files/*", { "*": "a/b" })).toBe("/files/a/b");
+	});
+
+	it("splat 为空时去掉末尾星号", () => {
+		expect(generatePath("/files/*", {})).toBe("/files");
+	});
+
+	it("缺失参数抛错（与真实实现一致）", () => {
+		expect(() => generatePath("/u/:id", {})).toThrow('Missing ":id" param');
+	});
+});

package/preview/shims/umi.tsx

@@ -0,0 +1,580 @@
+/**
+ * `umi` / `@umijs/max` 的最小 shim（预览环境专用）。
+ *
+ * 见 `docs/spec-umijs-support.md` §4.2。**这个文件不进业务代码**，
+ * 只在预览服务器里通过 `resolve.alias` 顶替真实的 `umi` 包。
+ *
+ * ## 为什么要 shim
+ *
+ * `umi` 是**服务端 + 客户端混合**的包，直接 import 会用到 `process.platform`、
+ * `fs` 等 Node API，在浏览器里直接崩（实测：
+ * `TypeError: Cannot read properties of undefined (reading 'platform')`）。
+ *
+ * ## 设计原则
+ *
+ * 1. **渲染路径上的高频 API 给降级值**（`useModel` / `useRequest`）——
+ *    抛错会让整棵组件树渲染不出来，预览就失去意义。
+ * 2. **不在渲染路径的 API 显式抛错**（`request`）—— 静默 `undefined`
+ *    会让人以为"跑通了但没数据"，比报错更难排查。
+ * 3. **不伪造数据**：空态就是空态，不编造看起来合理的假值。
+ */
+import { type AnchorHTMLAttributes, type ReactNode, useCallback, useEffect, useMemo, useState } from "react";
+
+/** 内存版位置栈：`history.push` 后可被 `useLocation` 观察到。 */
+interface MemoryLocation {
+	pathname: string;
+	search: string;
+	hash: string;
+	state: unknown;
+}
+
+let currentLocation: MemoryLocation = { pathname: "/", search: "", hash: "", state: null };
+const locationListeners = new Set<(location: MemoryLocation) => void>();
+
+function parsePath(to: string): MemoryLocation {
+	const [beforeHash, hash = ""] = to.split("#");
+	const [pathname, search = ""] = (beforeHash ?? "/").split("?");
+	return { pathname: pathname || "/", search, hash, state: null };
+}
+
+function navigate(to: string): void {
+	currentLocation = parsePath(to);
+	for (const listener of locationListeners) {
+		listener(currentLocation);
+	}
+}
+
+export function useLocation() {
+	const [location, setLocation] = useState(currentLocation);
+	useEffect(() => {
+		locationListeners.add(setLocation);
+		return () => {
+			locationListeners.delete(setLocation);
+		};
+	}, []);
+	return location;
+}
+
+export function useNavigate() {
+	return useCallback((to: string) => {
+		navigate(to);
+	}, []);
+}
+
+/** 路由参数：预览里没有路由，恒为空对象。 */
+export function useParams(): Record<string, string> {
+	return useMemo(() => ({}) as Record<string, string>, []);
+}
+
+export function useSearchParams(): URLSearchParams {
+	return useMemo(() => new URLSearchParams(currentLocation.search), []);
+}
+
+export const history = {
+	get location() {
+		return currentLocation;
+	},
+	push: navigate,
+	replace: navigate,
+	goBack: () => undefined,
+	listen: (listener: (location: MemoryLocation) => void) => {
+		locationListeners.add(listener);
+		return () => {
+			locationListeners.delete(listener);
+		};
+	},
+};
+
+type LinkProps = AnchorHTMLAttributes<HTMLAnchorElement> & { to?: string; children?: ReactNode };
+
+/** `Link` 渲染成 `<a>`，点击被拦截（不真正导航，避免预览页跳走）。 */
+export function Link({ to = "#", children, onClick, ...rest }: LinkProps) {
+	return (
+		<a
+			{...rest}
+			href={to}
+			onClick={(event) => {
+				event.preventDefault();
+				onClick?.(event);
+				navigate(to);
+			}}
+		>
+			{children}
+		</a>
+	);
+}
+
+/** `NavLink` 与 `Link` 同构；预览里恒为「未激活」。 */
+export function NavLink({ children, ...rest }: LinkProps) {
+	return <Link {...rest}>{children}</Link>;
+}
+
+/**
+ * `useModel` —— **恒返回空对象**。
+ *
+ * P0 不猜初值（见 spec §9.1 的评审修正 2）：需要真实初值时，
+ * 由用户在 `__previewjs__/Wrapper.tsx` 里包 Provider。
+ *
+ * selector 形式 `useModel(ns, s => …)` 正常运行（对 `{}` 求值）。
+ */
+export function useModel<T = Record<string, unknown>>(
+	_namespace: string,
+	selector?: (model: Record<string, unknown>) => T,
+): T {
+	const model = useMemo(() => ({}), []);
+	return (selector ? selector(model) : model) as T;
+}
+
+/** `connect` 直通 HOC：注入空 props，不做状态映射。 */
+export function connect<T>(Component: T): T {
+	return Component;
+}
+
+/* ------------------------------------------------------------------ *
+ * 应用上下文（`@umijs/renderer-react` 的 appContext）
+ *
+ * 这几个都在**渲染路径上**，且 `@umijs/max` 的页面组件很常见 ——
+ * 缺任何一个，整个模块会因 ESM 静态导出校验直接 `SyntaxError`，组件连挂载的机会都没有。
+ * 所以统一给「结构完整、内容为空」的降级值，而不是抛错。
+ * ------------------------------------------------------------------ */
+
+/**
+ * `useAppData()` —— 返回空的应用上下文。
+ *
+ * 真实返回值包含 `routes` / `clientRoutes` / `clientLoaderData` / `pluginManager` 等。
+ * 这里只保证**字段存在且类型形状对**，不伪造路由表（组件若遍历 `routes` 会得到空循环，
+ * 而不是 `Cannot read properties of undefined`）。
+ */
+export function useAppData() {
+	return useMemo(
+		() => ({
+			routes: {} as Record<string, unknown>,
+			routeComponents: {} as Record<string, unknown>,
+			clientRoutes: [] as unknown[],
+			pluginManager: undefined as unknown,
+			clientLoaderData: {} as Record<string, unknown>,
+			serverLoaderData: {} as Record<string, unknown>,
+			preloadRoute: (_to: string) => undefined,
+			basename: "/",
+			history,
+		}),
+		[],
+	);
+}
+
+/** 当前选中的路由链：预览里没有路由，恒为空数组。 */
+export function useSelectedRoutes(): unknown[] {
+	return useMemo(() => [], []);
+}
+
+/**
+ * 当前路由的配置（`IRoute`）。
+ *
+ * 恒返回 `{}`：真实的 `path` / `component` / `routes` 都由约定式路由生成，
+ * 预览不重建那套映射（那是 `specs/0001` 应用预览的领域）。
+ */
+export function useRouteProps<T = Record<string, unknown>>(): T {
+	return useMemo(() => ({}) as T, []);
+}
+
+/**
+ * 路由上下文（`IRouteContextType`）。
+ *
+ * 注意它与 `useRouteProps()` 不同：后者是路由配置对象本身，前者是
+ * `{ route: IRoute }` 的包装 —— 组件常见写法是 `useRouteData().route`。
+ */
+export function useRouteData(): { route: Record<string, unknown> } {
+	return useMemo(() => ({ route: {} }), []);
+}
+
+/** loader 数据：三个 loader hook 都返回空态，形状对齐真实签名。 */
+export function useServerLoaderData(): { data: undefined } {
+	return useMemo(() => ({ data: undefined }), []);
+}
+
+export function useClientLoaderData(): { data: undefined } {
+	return useMemo(() => ({ data: undefined }), []);
+}
+
+/** `useLoaderData()` 直接返回数据本身（不是 `{ data }` 包装）。 */
+export function useLoaderData(): undefined {
+	return undefined;
+}
+
+/* ------------------------------------------------------------------ *
+ * react-router 转导出
+ *
+ * `@umijs/max` 的 `umi` 入口会把这些 react-router 的 API 再导出一遍。
+ * 预览不引入 react-router（它有自己的 Router 上下文），所以全部给静态降级值。
+ * ------------------------------------------------------------------ */
+
+/**
+ * `useFetcher()` —— 返回空态的 fetcher。
+ *
+ * 真实签名里 `state` 取 `"idle" | "loading" | "submitting"`，这里恒为 `idle`，
+ * 让组件的 `if (fetcher.state !== "idle") return <Spin/>` 分支走正常路径。
+ */
+export function useFetcher() {
+	return useMemo(
+		() => ({
+			state: "idle" as const,
+			data: undefined,
+			formData: undefined,
+			load: async () => undefined,
+			submit: async () => undefined,
+		}),
+		[],
+	);
+}
+
+/** `useMatch()` —— 没有路由，匹配不中，恒 `null`。 */
+export function useMatch(_pattern?: unknown): null {
+	return null;
+}
+
+/** `useResolvedPath()` —— 返回自身路径的解析结果（不解析相对路径）。 */
+export function useResolvedPath(to: string) {
+	return useMemo(() => parsePath(to), [to]);
+}
+
+/** `useRoutes()` —— 预览不渲染路由表，恒渲染 `null`。 */
+export function useRoutes(_routes?: unknown): null {
+	return null;
+}
+
+/** `useOutlet()` —— 没有嵌套路由，恒 `null`。 */
+export function useOutlet(_context?: unknown): null {
+	return null;
+}
+
+/** `useOutletContext()` —— 没有 Outlet 提供者，恒空对象。 */
+export function useOutletContext<T = Record<string, unknown>>(): T {
+	return useMemo(() => ({}) as T, []);
+}
+
+/**
+ * `<Outlet />` —— 渲染 `null`。
+ *
+ * 子路由的内容由 Umi 的 layout / 约定式路由注入，预览不重建。
+ */
+export function Outlet(): null {
+	return null;
+}
+
+/**
+ * `<Navigate />` —— 渲染 `null`，并同步内存 location。
+ *
+ * 真实行为会立刻跳转；预览里不真的导航（避免渲染期间改状态导致循环），
+ * 只把目标路径记进内存栈，让后续 `useLocation()` 能读到。
+ */
+export function Navigate({ to }: { to: string }): null {
+	useEffect(() => {
+		navigate(to);
+	}, [to]);
+	return null;
+}
+
+/** 真实导出名是 `__useFetcher`，`useFetcher` 是它无下划线的别名，两个都要给。 */
+export const __useFetcher = useFetcher;
+
+/* ------------------------------------------------------------------ *
+ * react-router 的纯函数转导出
+ *
+ * 都是无状态的工具函数，可以给出**真实语义**（不需要路由上下文），
+ * 所以这里不降级为 `undefined` —— 降级反而会让组件的输入变成期望外的值。
+ * ------------------------------------------------------------------ */
+
+/** `createSearchParams(init)` —— 与 react-router 一致，返回 `URLSearchParams`。 */
+export function createSearchParams(
+	init?: string | Record<string, string> | Array<[string, string]> | URLSearchParams,
+): URLSearchParams {
+	return new URLSearchParams(init as string | Array<[string, string]> | Record<string, string> | undefined);
+}
+
+/**
+ * `resolvePath(to, fromPathname)` —— 相对路径解析成绝对路径。
+ *
+ * 移植自 react-router 6.3 的 `resolvePath` + `resolvePathname`：
+ * 处理 `.` / `..`、空的 `pathname`（回退到 `fromPathname`）与尾斜杠保留。
+ * 返回 `{ pathname, search, hash }`，**不含** `state`。
+ */
+export function resolvePath(to: string, fromPathname = "/"): { pathname: string; search: string; hash: string } {
+	const parsed = parsePathForResolve(to);
+	const { search = "", hash = "" } = parsed;
+	// 空 `to`（或只有 search/hash）应该 **保留 `fromPathname`**，而不是回到根。
+	// `parsePath()` 把空串规整成了 `/`，所以这里要看原始 `to` 而不是解析结果。
+	const toPathname = to === "" || to.startsWith("?") || to.startsWith("#") ? "" : (to.split(/[?#]/)[0] ?? "");
+	const pathname = toPathname
+		? toPathname.startsWith("/")
+			? toPathname
+			: resolvePathname(toPathname, fromPathname)
+		: fromPathname;
+	return { pathname, search: normalizeSearch(search), hash: normalizeHash(hash) };
+}
+
+/** 本模块私有的 parsePath（不依赖 shim 的版本，避免互相 import）。 */
+function parsePathForResolve(to: string): { pathname: string; search?: string; hash?: string } {
+	const [beforeHash, hash = ""] = to.split("#");
+	const [pathname, search = ""] = (beforeHash ?? "/").split("?");
+	return { pathname: pathname || "/", search, hash };
+}
+
+/** 相对路径拼接（与 react-router 的 `resolvePathname` 同算法）。 */
+function resolvePathname(relativePath: string, fromPathname: string): string {
+	const segments = fromPathname.replace(/\/+$/, "").split("/");
+	for (const segment of relativePath.split("/")) {
+		if (segment === "..") {
+			// 保留根部的空段，让 pathname 仍以 / 开头
+			if (segments.length > 1) {
+				segments.pop();
+			}
+		} else if (segment !== ".") {
+			segments.push(segment);
+		}
+	}
+	return segments.length > 1 ? segments.join("/") : "/";
+}
+
+function normalizeSearch(search: string): string {
+	return !search || search === "?" ? "" : search.startsWith("?") ? search : `?${search}`;
+}
+
+function normalizeHash(hash: string): string {
+	return !hash || hash === "#" ? "" : hash.startsWith("#") ? hash : `#${hash}`;
+}
+
+/**
+ * `matchPath(pattern, pathname)` —— 与 react-router 6.3 语义一致。
+ *
+ * ## 为什么不能用「按 `/` 切段逐个比」的简版
+ *
+ * 简版会错三处，而且错得很难发现：
+ *
+ * 1. **返回形状**：真实返回 `{ params, pathname, pathnameBase, pattern }`，
+ *    不是 `params` 本体。写 `match?.params.id` 的组件拿到的是 `undefined`。
+ * 2. **splat 捕获**：`/files/*` 的 `*` 是**具名捕获组**（`params["*"]`），
+ *    简版直接丢掉，组件会以为匹配上了但没有尾部路径。
+ * 3. **大小写**：默认 `caseSensitive: false`，`/Users/42` 能匹配 `/users/:id`。
+ *
+ * 所以这里直接移植 react-router 的 `compilePath` / `matchPath`（MIT，
+ * 见 `react-router@6.3.0` 的 `react-router.development.js`）。
+ */
+export interface PathMatch {
+	params: Record<string, string>;
+	pathname: string;
+	pathnameBase: string;
+	pattern: { path: string; caseSensitive: boolean; end: boolean };
+}
+
+export function matchPath(
+	pattern: string | { path: string; caseSensitive?: boolean; end?: boolean },
+	pathname: string,
+): PathMatch | null {
+	const compiled =
+		typeof pattern === "string"
+			? { path: pattern, caseSensitive: false, end: true }
+			: { path: pattern.path, caseSensitive: pattern.caseSensitive ?? false, end: pattern.end ?? true };
+
+	const [matcher, paramNames] = compilePath(compiled.path, compiled.caseSensitive, compiled.end);
+	const match = pathname.match(matcher);
+	if (!match) {
+		return null;
+	}
+	const matchedPathname = match[0] as string;
+	let pathnameBase = matchedPathname.replace(/(.)\/+$/, "$1");
+	const captureGroups = match.slice(1);
+	const params: Record<string, string> = {};
+
+	paramNames.forEach((paramName, index) => {
+		// splat 的 `pathnameBase` 要用**未解码**的原始值算，所以先算再解码。
+		if (paramName === "*") {
+			const splatValue = captureGroups[index] || "";
+			pathnameBase = matchedPathname.slice(0, matchedPathname.length - splatValue.length).replace(/(.)\/+$/, "$1");
+		}
+		params[paramName] = safelyDecodeURIComponent(captureGroups[index] || "", paramName);
+	});
+
+	return { params, pathname: matchedPathname, pathnameBase, pattern: compiled };
+}
+
+/** 把路径模式编译成正则 + 参数名列表（与 react-router 同）：`^/users/([^\/]+)\/?$`。 */
+function compilePath(path: string, caseSensitive = false, end = true): [RegExp, string[]] {
+	const paramNames: string[] = [];
+	let regexpSource = `^${path
+		.replace(/\/*\*?$/, "") // 尾部的 / 与 /* 由下面单独处理
+		.replace(/^\/*/, "/") // 保证以 / 开头
+		.replace(/[\\.*+^$?{}|()[\]]/g, "\\$&") // 转义正则特殊字符
+		.replace(/:(\w+)/g, (_match, paramName: string) => {
+			paramNames.push(paramName);
+			return "([^\\/]+)";
+		})}`;
+
+	if (path.endsWith("*")) {
+		paramNames.push("*");
+		// `*` / `/*` 已经匹配了开头的 /，剩下的直接 capture；
+		// 否则不要把这个 / 算进 params["*"]。
+		regexpSource += path === "*" || path === "/*" ? "(.*)$" : "(?:\\/(.+)|\\/*)$";
+	} else if (end) {
+		regexpSource += "\\/*$"; // 匹配到末尾时忽略尾斜杠
+	} else {
+		regexpSource += "(?:(?=[.~-]|%[0-9A-F]{2})|\\b|\\/|$)";
+	}
+
+	return [new RegExp(regexpSource, caseSensitive ? undefined : "i"), paramNames];
+}
+
+/** 解码失败的 URL 段原样返回，不抛错（与 react-router 同：那里只打 warning）。 */
+function safelyDecodeURIComponent(value: string, _paramName: string): string {
+	try {
+		return decodeURIComponent(value);
+	} catch {
+		return value;
+	}
+}
+
+/**
+ * `generatePath(pattern, params)` —— 把 `:param` 与尾部 `*` 替换成实际值。
+ *
+ * 移植自 react-router 6.3：**不做 URL 编码**（中文等原样输出），
+ * 缺失参数抛错，`*` 允许为空。
+ */
+export function generatePath(pattern: string, params: Record<string, string> = {}): string {
+	return pattern
+		.replace(/:(\w+)/g, (_match, key: string) => {
+			const value = params[key];
+			// 真实实现用 `params[key] != null`（同时排除 null 与 undefined），
+			// 这里展开写，避免依赖宽松相等。
+			if (value === undefined || value === null) {
+				throw new Error(`Missing ":${key}" param`);
+			}
+			return value;
+		})
+		.replace(/\/*\*$/, () => {
+			const splat = params["*"];
+			return splat === undefined || splat === null ? "" : String(splat).replace(/^\/*/, "/");
+		});
+}
+
+/** `matchRoutes(routes, pathname)` —— 没有路由表时恒 `null`。 */ export function matchRoutes(
+	_routes?: unknown,
+	_pathname?: string,
+): null {
+	return null;
+}
+
+/**
+ * `withRouter()` —— 直通 HOC。
+ *
+ * 真实版本注入 `history` / `location` / `match`；预览没有路由上下文，
+ * 注入空值（与 `connect` 的策略一致）。
+ */
+export function withRouter<T>(Component: T): T {
+	return Component;
+}
+
+/* ------------------------------------------------------------------ *
+ * helmet / history 转导出
+ * ------------------------------------------------------------------ */
+
+/**
+ * `<Helmet>` / `<HelmetProvider>` —— 渲染子节点，不改文档头。
+ *
+ * 预览的 `document.title` 由面板控制，让组件随便改会与宿主抢控制权。
+ */
+export function Helmet({ children }: { children?: ReactNode }): ReactNode {
+	return children ?? null;
+}
+
+export function HelmetProvider({ children }: { children?: ReactNode }): ReactNode {
+	return children ?? null;
+}
+
+/**
+ * `createMemoryHistory()` —— 返回与 shim 的 `history` 同构的内存栈。
+ *
+ * 注意：真实 `history` 包的接口大得多（`block` / `go` / `createHref` 等）。
+ * 这里只提供**渲染路径上常见**的几个，未实现的显式抛错（与 `request` 同策略）。
+ */
+export function createMemoryHistory(_options?: unknown) {
+	return history;
+}
+
+export const createBrowserHistory = createMemoryHistory;
+export const createHashHistory = createMemoryHistory;
+
+/** `LinkWithPrefetch as Link` —— 真实导出名是无下划线的 prefetch 版，预览里与 `Link` 同构。 */
+export const LinkWithPrefetch = Link;
+
+/* ------------------------------------------------------------------ *
+ * 应用挂载入口
+ *
+ * 这两个是 **应用级** API（把整棵路由树挂到 DOM），组件预览永远不会调用。
+ * 仍然显式导出：ESM 是**静态**导出校验，少一个名字整个模块就 `SyntaxError`，
+ * 整个预览白屏 —— 而降级为抛错至少能给出可读的原因。
+ * ------------------------------------------------------------------ */
+
+/** `renderClient()` —— 应用级挂载，不在组件预览的职责内。 */
+export function renderClient(): never {
+	throw new Error("预览环境不提供 umi.renderClient —— 应用级渲染请用 DevBrowser（应用预览）");
+}
+
+/** `__getRoot()` —— 拿到应用根元素，同上。 */
+export function __getRoot(): never {
+	throw new Error("预览环境不提供 umi.__getRoot —— 应用级渲染请用 DevBrowser（应用预览）");
+}
+
+/**
+ * `useRequest` —— **返回空态而非抛错**。
+ *
+ * 理由（spec §4.2.1）：它是 `@umijs/max` 下最高频的 API，抛错会让几乎所有页面
+ * 组件在预览里直接崩。空态能让组件的 `if (!data) return null` 分支自然生效。
+ *
+ * 选择 `loading: false` 而非 `true`：`true` 会让组件永远停在骨架屏，
+ * 而预览的目的是看结构，不是看 loading。
+ *
+ * 注意：**不伪造数据**，`data` 恒为 `undefined`。
+ */
+let warnedUseRequestEmpty = false;
+
+export function useRequest<R = unknown>(_service: unknown, _options?: unknown) {
+	if (!warnedUseRequestEmpty && typeof console !== "undefined") {
+		// 只打一次：每次渲染都打会把控制台刷爆。
+		// 让"为什么没数据"可被发现，而不是让人误以为是 bug（spec §11 R6）。
+		warnedUseRequestEmpty = true;
+		console.debug("[cfp-preview] useRequest：预览环境返回空态");
+	}
+	return {
+		data: undefined as R | undefined,
+		error: undefined,
+		loading: false,
+		run: async () => undefined as R | undefined,
+		runAsync: async () => undefined as R | undefined,
+		refresh: async () => undefined as R | undefined,
+		refreshAsync: async () => undefined as R | undefined,
+		mutate: () => undefined,
+		cancel: () => undefined,
+	};
+}
+
+/** 其它未实现的 API：显式抛错，不做静默 `undefined`。 */
+export function request(): never {
+	throw new Error("预览环境未实现 umi.request —— 请求类逻辑请在 DevBrowser（应用预览）里验证");
+}
+
+export function useAccess(): Record<string, boolean> {
+	return {};
+}
+
+export function useIntl() {
+	return {
+		formatMessage: ({ id }: { id: string }) => id,
+	};
+}
+
+export function getLocale(): string {
+	return "zh-CN";
+}
+
+export function setLocale(): void {
+	// 预览里切语言不生效：Umi 的 locale 由运行时注入，shim 不做模拟。
+}