@maiyunnet/kebab 9.18.2 → 9.19.1

package/index.d.ts

@@ -5,7 +5,7 @@
  * --- 本文件用来定义每个目录实体地址的常量 ---
  */
 /** --- 当前系统版本号 --- */
-export declare const VER = "9.18.2";
+export declare const VER = "9.19.1";
 /** --- 框架根目录，以 / 结尾  --- */
 export declare const ROOT_PATH: string;
 /** --- 框架的 LIB，以 / 结尾 --- */

package/index.js

@@ -6,7 +6,7 @@
  * --- 本文件用来定义每个目录实体地址的常量 ---
  */
 /** --- 当前系统版本号 --- */
-export const VER = '9.18.2';
+export const VER = '9.19.1';
 // --- 服务端用的路径 ---
 const imu = decodeURIComponent(import.meta.url).replace('file://', '').replace(/^\/(\w:)/, '$1');
 /** --- /xxx/xxx --- */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maiyunnet/kebab",
-  "version": "9.18.2",
+  "version": "9.19.1",
   "description": "Simple, easy-to-use, and fully-featured Node.js framework that is ready-to-use out of the box.",
   "type": "module",
   "keywords": [

package/sys/ctr.d.ts

@@ -19,6 +19,8 @@ export declare function clearLocaleData(): void;
 export type TValibotResponse<TIssue extends v.BaseIssue<unknown>> = kebab.Json[] | ((issues: [TIssue, ...TIssue[]]) => kebab.Json[]);
 /** --- 在 issue 路径完整后，根据 Kebab 生成的语言键翻译消息 --- */
 export type TValibotTranslate = (key: string, issue: v.BaseIssue<unknown>) => string;
+/** --- HTTP 重定向状态码 --- */
+export type TRedirectHttpCode = 301 | 302 | 303 | 307 | 308;
 /** --- Valibot 同步校验选项 --- */
 export interface IValibotOptions<TIssue extends v.BaseIssue<unknown>> {
     /** --- 传给 Valibot 的校验配置 --- */
@@ -58,6 +60,21 @@ export type TValibotResult<TSchema extends v.GenericSchema, TIssue extends v.Bas
     readonly issues: [TIssue, ...TIssue[]];
     readonly response: kebab.Json[];
 };
+/** --- React SSR 页面选项 --- */
+export interface IReactPageOptions {
+    /** --- 是否注入客户端水合 bundle，默认 true；设为 false 时仅输出服务端渲染的 HTML --- */
+    'hydrate'?: boolean;
+    /**
+     * --- 路由模式，不传则不注入任何 Router，组件自行管理路由（如 MemoryRouter）或无路由 ---
+     * --- 'browser'：服务端用 StaticRouter，客户端用 BrowserRouter，地址栏与路由联动 ---
+     * --- 组件本身只需使用 Routes/Route/Link 等，不要包含任何 Router 包裹层 ---
+     */
+    'router'?: 'browser';
+    /** --- BrowserRouter 的 basename，相对于 urlBase，默认空字符串 --- */
+    'routerBase'?: string;
+    /** --- 静态资源基础路径，覆盖 config.set.staticPath（支持 CDN） --- */
+    'staticPath'?: string;
+}
 /**
  * --- 判断当前 HTTP 请求是否仍可响应 ---
  * @param req 请求对象
@@ -213,42 +230,20 @@ export declare class Ctr {
     /**
      * --- 加载 React 全页面进行 SSR 渲染，组件需渲染完整 HTML 文档（含 html/head/body），无需 EJS ---
      * --- 框架自动注入 props：_urlBase/_urlFull/_urlStc/_staticVer/_staticPath/_staticPathFull ---
-     * --- 多语言：自动注入 _locale（当前语言名）和 _localeData（已载语言包的合并键值对） ---
+     * --- 多语言：自动注入 _locale（当前语言名）和 _localeData（当前语种已载语言包的合并键值对） ---
      * --- 组件内创建：const l = (key: string, ...args: string[]): string => { let i = 0; return (_localeData[key] ?? key).replace(/\?/g, () => args[i++] ?? ''); }; ---
      * @param path 页面组件路径（相对于 stc/ 目录，不含扩展名，tsx 编译后的 .js）
      * @param props 传入组件的 props，框架常量自动合并，整体序列化为内联 JSON 供客户端水合复用
      * @param opt 可选配置
      */
-    protected _loadReactPage(path: string, props?: Record<string, kebab.Json>, opt?: {
-        /** --- 是否注入客户端水合脚本（import map + hydrateRoot），默认 true --- */
-        'hydrate'?: boolean;
-        /** --- react/react-dom/react-router-dom 版本号，用于 esm.sh CDN，默认 19 --- */
-        'reactVer'?: string;
-        /**
-         * --- 路由模式，不传则不注入任何 Router，组件自行管理路由（如 MemoryRouter）或无路由 ---
-         * --- 'browser'：服务端用 StaticRouter，客户端用 BrowserRouter，地址栏与路由联动 ---
-         * --- 组件本身只需使用 Routes/Route/Link 等，不要包含任何 Router 包裹层 ---
-         */
-        'router'?: 'browser';
-        /**
-         * --- BrowserRouter 的 basename，相对于 urlBase，默认空字符串 ---
-         * --- 例如组件挂载在 /test/react-router-page，则填 'test/react-router-page' ---
-         */
-        'routerBase'?: string;
-        /**
-         * --- 静态资源基础路径，覆盖 config.set.staticPath，用于指定 CDN 或自定义路径 ---
-         * --- 影响 _staticPath prop 以及水合脚本中 JS 文件的 URL 前缀 ---
-         */
-        'staticPath'?: string;
-    }): Promise<string>;
-    /**
-     * --- 递归扫描 JS 文件中的 import 语句，收集第三方 bare specifier ---
-     * @param filePath 当前要扫描的文件绝对路径
-     * @param scannedFiles 已扫描文件集（去重用）
-     * @param extraImports 收集到的第三方包名集合
-     * @param builtinImports 内置 import map，已有条目不重复添加
-     */
-    private _scanImports;
+    protected _loadReactPage(path: string, props?: Record<string, kebab.Json>, opt?: IReactPageOptions): Promise<string>;
+    /**
+     * --- 记录 React 页面错误并返回脱敏响应 ---
+     * @param message 调试信息
+     * @param detail 日志详情
+     * @returns 脱敏后的 500 页面
+     */
+    private _reactPageError;
     /**
      * --- 设置校验错误返回值 ---
      * @param rtn 返回值数组
@@ -343,10 +338,11 @@ export declare class Ctr {
      */
     protected _loadData<T>(path: string): Promise<T | false | null>;
     /**
-     * --- 跳转（302临时跳转），支持相对本项目根路径的路径或绝对路径 ---
+     * --- 跳转，支持相对本项目根路径的路径或绝对路径 ---
      * @param location 相对或绝对网址
+     * @param httpCode HTTP 重定向状态码，默认 302
      */
-    protected _location(location: string): false;
+    protected _location(location: string, httpCode?: TRedirectHttpCode): false;
     /**
      * --- 开启 Session ---
      * @param link Kv 或 Db 实例

package/sys/ctr.js

@@ -264,35 +264,35 @@ export class Ctr {
     /**
      * --- 加载 React 全页面进行 SSR 渲染，组件需渲染完整 HTML 文档（含 html/head/body），无需 EJS ---
      * --- 框架自动注入 props：_urlBase/_urlFull/_urlStc/_staticVer/_staticPath/_staticPathFull ---
-     * --- 多语言：自动注入 _locale（当前语言名）和 _localeData（已载语言包的合并键值对） ---
+     * --- 多语言：自动注入 _locale（当前语言名）和 _localeData（当前语种已载语言包的合并键值对） ---
      * --- 组件内创建：const l = (key: string, ...args: string[]): string => { let i = 0; return (_localeData[key] ?? key).replace(/\?/g, () => args[i++] ?? ''); }; ---
      * @param path 页面组件路径（相对于 stc/ 目录，不含扩展名，tsx 编译后的 .js）
      * @param props 传入组件的 props，框架常量自动合并，整体序列化为内联 JSON 供客户端水合复用
      * @param opt 可选配置
      */
     async _loadReactPage(path, props = {}, opt = {}) {
-        // --- 约定：传入路径不含 .page 后缀，框架自动补全（对应 build 命令的 *.page.tsx 约定）---
-        // --- 组件 JS 从 stc 目录读取，浏览器同样通过 staticPath（支持 CDN）下载 ---
-        const componentPath = this._config.const.rootPath + 'stc/' + path + '.page.js';
+        // --- 校验服务端组件与客户端水合产物 ---
+        const hydrate = opt.hydrate !== false;
+        const pagePath = `${this._config.const.rootPath}stc/${path}.page`;
+        const componentPath = `${pagePath}.js`;
         if (!await lFs.isFile(componentPath)) {
-            lCore.debug(`[CTR][_loadReactPage] componentPath ${componentPath} is not a file`);
-            lCore.log(this, `[CTR][_loadReactPage] componentPath ${componentPath} is not a file`, '-error');
-            return '';
+            return this._reactPageError(`componentPath ${componentPath} is not a file`);
+        }
+        const bundlePath = `${pagePath}.bundle.js`;
+        if (hydrate && !await lFs.isFile(bundlePath)) {
+            return this._reactPageError(`bundlePath ${bundlePath} is not a file; run "npx kebab build -d ${this._config.const.rootPath}stc"`);
         }
         try {
-            const reactDomServer = await import('react-dom/server');
+            // --- 并行加载 SSR 依赖与页面组件 ---
             const importPath = componentPath.startsWith('/')
                 ? componentPath
                 : `file:///${componentPath.replace(/\\/g, '/')}`;
-            const mod = await import(importPath);
-            const component = mod.default;
-            const react = await import('react');
-            // --- 语言包数据：合并所有已加载包的键值，供组件使用 _localeData 实现多语言 ---
-            const localeData = {};
-            for (const pkg in this._localeData) {
-                Object.assign(localeData, this._localeData[pkg]);
-            }
-            // --- 把框架常量合并进 props，与 _loadView 行为一致 ---
+            const [react, reactDomServer, page] = await Promise.all([
+                import('react'),
+                import('react-dom/server'),
+                import(importPath),
+            ]);
+            // --- 合并框架 Props 与路由配置 ---
             const staticPath = opt.staticPath ?? this._config.set.staticPath;
             const fullProps = {
                 ...props,
@@ -303,127 +303,49 @@ export class Ctr {
                 '_staticPath': staticPath,
                 '_staticPathFull': this._config.set.staticPathFull,
                 '_locale': this._locale,
-                '_localeData': localeData,
+                '_localeData': { ...(this._localeData[this._locale] ?? {}) },
             };
-            // --- 框架自动注入的 HTML 片段，用户组件无需手动渲染 ---
-            let headInject = '';
-            let bodyInject = '';
-            if (opt.hydrate !== false) {
-                const reactVer = opt.reactVer ?? '19';
-                const esm = 'https://esm.sh/';
-                // --- 检查是否有 npx kebab build 生成的自包含预构建包 ---
-                const bundlePath = this._config.const.rootPath + 'stc/' + path + '.page.bundle.js';
-                const hasBundle = await lFs.isFile(bundlePath);
-                if (opt.router === 'browser') {
-                    // --- BrowserRouter 模式：_routerBase 注入 props，供水合脚本读取 ---
-                    const base = opt.routerBase ?? '';
-                    const routerBase = this._config.const.urlBase + base.replace(/^\//, '');
-                    fullProps['_routerBase'] = routerBase.replace(/\/$/, '');
-                }
-                // --- propsJson 在渲染前序列化，框架直接注入 HTML，组件无需手动渲染 ---
-                const propsJson = lText.stringifyJson(fullProps).replace(/<\/script>/gi, '<\\/script>');
-                let hydrateScript;
-                if (hasBundle) {
-                    // --- bundle 模式：bundle 自包含 React + 水合逻辑，无需 import map ---
-                    const clientUrl = `${staticPath}${path}.page.bundle.js?v=${this._config.set.staticVer}`;
-                    hydrateScript = `import'${clientUrl}';`;
-                }
-                else {
-                    // --- 开发模式（tsc 编译 .js）：通过 esm.sh import map 解析 bare import ---
-                    const clientUrl = `${staticPath}${path}.page.js?v=${this._config.set.staticVer}`;
-                    // --- 内置 import map 条目（React 生态核心包）---
-                    const builtinImports = {
-                        'react': `${esm}react@${reactVer}`,
-                        'react-dom': `${esm}react-dom@${reactVer}`,
-                        'react-dom/client': `${esm}react-dom@${reactVer}/client`,
-                        'react/jsx-runtime': `${esm}react@${reactVer}/jsx-runtime`,
-                        'react-router-dom': `${esm}react-router-dom@7?external=react,react-dom`,
-                    };
-                    // --- 自动扫描入口 JS 及其相对引用，收集所有第三方 bare specifier ---
-                    const scannedFiles = new Set();
-                    const extraImports = new Set();
-                    await this._scanImports(componentPath, scannedFiles, extraImports, builtinImports);
-                    // --- 第三方包统一通过 esm.sh 解析，external react/react-dom 避免重复加载 ---
-                    for (const pkg of extraImports) {
-                        builtinImports[pkg] = `${esm}${pkg}?external=react,react-dom`;
-                    }
-                    // --- import map 注入到 </head> 前 ---
-                    headInject = `<script type="importmap">${lText.stringifyJson({ 'imports': builtinImports })}</script>`;
-                    // --- BrowserRouter 模式多一段 Router 导入与包裹层 ---
-                    const routerImport = opt.router === 'browser' ? `import{BrowserRouter}from'react-router-dom';` : '';
-                    const routerCreate = opt.router === 'browser'
-                        ? `createElement(BrowserRouter,{basename:p._routerBase},createElement(App,p))`
-                        : `createElement(App,p)`;
-                    hydrateScript =
-                        `import{hydrateRoot}from'react-dom/client';` +
-                            `import{createElement}from'react';` +
-                            routerImport +
-                            `import App from'${clientUrl}';` +
-                            `const p=JSON.parse(document.getElementById('__kebab_props__').textContent);` +
-                            `hydrateRoot(document,${routerCreate});`;
-                }
-                // --- props JSON + 水合脚本注入到 </body> 前 ---
-                bodyInject =
-                    `<script id="__kebab_props__" type="application/json">${propsJson}</script>` +
-                        `<script type="module">${hydrateScript}</script>`;
+            if (opt.router === 'browser') {
+                const routerBase = `${this._config.const.urlBase}${(opt.routerBase ?? '').replace(/^\//, '')}`;
+                fullProps['_routerBase'] = routerBase.replace(/\/$/, '');
             }
-            // --- BrowserRouter 模式：服务端用 StaticRouter 渲染，与客户端的 BrowserRouter 等价 ---
-            // --- component 来自动态 import，TypeScript 无法精确推断，需要明确限定 element 类型 ---
-            let element = react.createElement(component, fullProps);
+            // --- 创建页面元素，BrowserRouter 模式下由 StaticRouter 包裹 ---
+            const component = page.default;
+            const pageElement = react.createElement(component, fullProps);
+            let element = pageElement;
             if (opt.router === 'browser') {
-                // --- StaticRouter 在 react-router-dom v7 中从主包直接导出，无需 /server 子路径 ---
-                const lReactRouter = await import('react-router-dom');
-                const reqUrl = this._req.url ?? '/';
-                element = react.createElement(lReactRouter.StaticRouter, {
-                    'location': reqUrl,
+                const reactRouter = await import('react-router-dom');
+                element = react.createElement(reactRouter.StaticRouter, {
+                    'location': this._req.url ?? '/',
                     'basename': fullProps['_routerBase'],
-                }, react.createElement(component, fullProps));
+                }, pageElement);
             }
-            // --- 框架将 import map 注入 </head> 前，props JSON + 水合脚本注入 </body> 前 ---
-            let html = '<!DOCTYPE html>' + reactDomServer.renderToString(element);
-            if (opt.hydrate !== false) {
-                html = html.replace('</head>', headInject + '</head>');
-                html = html.replace('</body>', bodyInject + '</body>');
+            // --- 渲染完整 HTML，并按需注入客户端水合数据与 bundle ---
+            const html = `<!DOCTYPE html>${reactDomServer.renderToString(element)}`;
+            if (!hydrate) {
+                return html;
             }
-            return html;
+            const propsJson = lText.stringifyJson(fullProps).replace(/<\/script>/gi, '<\\/script>');
+            const clientUrl = `${staticPath}${path}.page.bundle.js?v=${this._config.set.staticVer}`;
+            const propsScript = `<script id="__kebab_props__" type="application/json">${propsJson}</script>`;
+            const hydrateScript = `<script type="module">import'${clientUrl}';</script>`;
+            return html.replace('</body>', `${propsScript}${hydrateScript}</body>`);
         }
         catch (e) {
-            lCore.debug(`[CTR][_loadReactPage] ${e.message ?? ''}`);
-            lCore.log(this, '[CTR][_loadReactPage] ' + lText.stringifyError(e), '-error');
-            return '';
+            return this._reactPageError(e.message ?? '', lText.stringifyError(e));
         }
     }
     /**
-     * --- 递归扫描 JS 文件中的 import 语句，收集第三方 bare specifier ---
-     * @param filePath 当前要扫描的文件绝对路径
-     * @param scannedFiles 已扫描文件集（去重用）
-     * @param extraImports 收集到的第三方包名集合
-     * @param builtinImports 内置 import map，已有条目不重复添加
+     * --- 记录 React 页面错误并返回脱敏响应 ---
+     * @param message 调试信息
+     * @param detail 日志详情
+     * @returns 脱敏后的 500 页面
      */
-    async _scanImports(filePath, scannedFiles, extraImports, builtinImports) {
-        if (scannedFiles.has(filePath)) {
-            return;
-        }
-        scannedFiles.add(filePath);
-        const src = await lFs.getContent(filePath, 'utf8');
-        if (!src) {
-            return;
-        }
-        const re = /\bfrom\s*['"]([^'"]+)['"]/g;
-        let m;
-        while ((m = re.exec(src)) !== null) {
-            const spec = m[1];
-            if (spec.startsWith('./') || spec.startsWith('../')) {
-                // --- 相对引用：解析为绝对路径后递归扫描 ---
-                const dir = filePath.substring(0, filePath.lastIndexOf('/') + 1);
-                const resolved = new URL(spec, 'file://' + dir).pathname;
-                await this._scanImports(resolved, scannedFiles, extraImports, builtinImports);
-            }
-            else if (!spec.startsWith('/') && !spec.startsWith('http') && !(spec in builtinImports)) {
-                // --- 第三方 bare specifier：加入 import map ---
-                extraImports.add(spec);
-            }
-        }
+    _reactPageError(message, detail = message) {
+        lCore.debug(`[CTR][_loadReactPage] ${message}`);
+        lCore.log(this, `[CTR][_loadReactPage] ${detail}`, '-error');
+        this._httpCode = 500;
+        return '<h1>500 Server Error</h1><hr>Kebab';
     }
     /**
      * --- 设置校验错误返回值 ---
@@ -854,13 +776,15 @@ export class Ctr {
         return json;
     }
     /**
-     * --- 跳转（302临时跳转），支持相对本项目根路径的路径或绝对路径 ---
+     * --- 跳转，支持相对本项目根路径的路径或绝对路径 ---
      * @param location 相对或绝对网址
+     * @param httpCode HTTP 重定向状态码，默认 302
      */
-    _location(location) {
+    _location(location, httpCode = 302) {
+        this._httpCode = httpCode;
         if (this._res) {
             this._res.setHeader('location', lText.urlResolve(this._config.const.urlBase, location));
-            // this._res.writeHead(302); Kebab 中要在最后设置，否则会报错：ERR_HTTP_HEADERS_SENT
+            // this._res.writeHead(httpCode); Kebab 中要在最后设置，否则会报错：ERR_HTTP_HEADERS_SENT
         }
         return false;
     }

package/sys/route.js

@@ -581,6 +581,8 @@ export async function run(data) {
         data.res.setHeader('expires', new Date(Date.now() + cacheTTL * 1_000).toUTCString());
         data.res.setHeader('cache-control', 'max-age=' + cacheTTL.toString());
     }
+    // --- 记录控制器是否显式设置状态码；未设置时，带 Location 的空响应仍兼容为 302 ---
+    const hasCustomHttpCode = httpCode !== 0;
     // --- 设置自定义 hcode ---
     if (httpCode === 0) {
         httpCode = 200;
@@ -591,7 +593,7 @@ export async function run(data) {
             // --- 已经自行输出过 writeHead，可能自行处理了内容，如 pipe，则不再 writeHead ---
         }
         else {
-            lCore.writeHead(data.res, data.res.getHeader('location') ? 302 : httpCode);
+            lCore.writeHead(data.res, data.res.getHeader('location') && !hasCustomHttpCode ? 302 : httpCode);
         }
         if (!data.res.writableEnded) {
             // --- 如果当前还没结束，则强制关闭连接，一切 pipe 请自行在方法中 await，否则会被中断 ---

package/www/example/ctr/test.js

@@ -2021,8 +2021,8 @@ error: ${JSON.stringify(res.error)}
     }
     async undiciPost() {
         const echo = [];
-        const res = await lUndici.post(this._internalUrl + 'test/netPost1', { 'a': '1', 'b': '2', 'c': ['1', '2', '3'] });
-        echo.push(`<pre>lUndici.post('${this._internalUrl}test/netPost1', { 'a': '1', 'b': '2', 'c': ['1', '2', '3'] });</pre>
+        const res = await lUndici.post(this._internalUrl + 'test/undiciPost1', { 'a': '1', 'b': '2', 'c': ['1', '2', '3'] });
+        echo.push(`<pre>lUndici.post('${this._internalUrl}test/undiciPost1', { 'a': '1', 'b': '2', 'c': ['1', '2', '3'] });</pre>
 headers: <pre>${JSON.stringify(res.headers, null, 4)}</pre>
 content: <pre>${(await res.getContent())?.toString() ?? 'null'}</pre>
 error: ${JSON.stringify(res.error)}`);
@@ -2033,8 +2033,8 @@ error: ${JSON.stringify(res.error)}`);
     }
     async undiciPostString() {
         const echo = [];
-        const res = await lUndici.post(this._internalUrl + 'test/netPostString1', 'HeiHei');
-        echo.push(`<pre>lUndici.post('${this._internalUrl}test/netPostString1', 'HeiHei');</pre>
+        const res = await lUndici.post(this._internalUrl + 'test/undiciPostString1', 'HeiHei');
+        echo.push(`<pre>lUndici.post('${this._internalUrl}test/undiciPostString1', 'HeiHei');</pre>
 headers: <pre>${JSON.stringify(res.headers, null, 4)}</pre>
 content: <pre>${(await res.getContent())?.toString() ?? 'null'}</pre>
 error: ${JSON.stringify(res.error)}`);
@@ -2045,8 +2045,8 @@ error: ${JSON.stringify(res.error)}`);
     }
     async undiciOpen() {
         const echo = [];
-        const res = await lUndici.open(this._internalUrl + 'test/netPost1').post().data({ 'a': '2', 'b': '0', 'c': ['0', '1', '3'] }).request();
-        echo.push(`<pre>lUndici.open('${this._internalUrl}test/netPost1').post().data({ 'a': '2', 'b': '0', 'c': ['0', '1', '3'] }).request();</pre>
+        const res = await lUndici.open(this._internalUrl + 'test/undiciPost1').post().data({ 'a': '2', 'b': '0', 'c': ['0', '1', '3'] }).request();
+        echo.push(`<pre>lUndici.open('${this._internalUrl}test/undiciPost1').post().data({ 'a': '2', 'b': '0', 'c': ['0', '1', '3'] }).request();</pre>
 headers: <pre>${JSON.stringify(res.headers, null, 4)}</pre>
 content: <pre>${(await res.getContent())?.toString() ?? 'null'}</pre>
 error: ${JSON.stringify(res.error)}`);

package/www/example/stc/view/hello.page.d.ts

@@ -5,7 +5,8 @@
  * 1. 这个 .page.tsx 文件（组件 + IProps）
  * 2. 一个 <link> 标签引入 CSS（如果不需要样式可省略）
  * 3. 在 Ctr 方法里调用 _loadReactPage('view/hello', props)
- * 其他一切由框架自动处理：SSR 渲染、import map、props 注入、客户端水合。
+ * 4. 执行 node ./source/main build -d source/www/example/stc 生成客户端水合 bundle
+ * 其他一切由框架自动处理：SSR 渲染、props 注入、客户端水合。
  */
 import { type ReactElement } from 'react';
 interface IProps {

package/www/example/stc/view/hello.page.js

@@ -6,7 +6,8 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * 1. 这个 .page.tsx 文件（组件 + IProps）
  * 2. 一个 <link> 标签引入 CSS（如果不需要样式可省略）
  * 3. 在 Ctr 方法里调用 _loadReactPage('view/hello', props)
- * 其他一切由框架自动处理：SSR 渲染、import map、props 注入、客户端水合。
+ * 4. 执行 node ./source/main build -d source/www/example/stc 生成客户端水合 bundle
+ * 其他一切由框架自动处理：SSR 渲染、props 注入、客户端水合。
  */
 import { useState } from 'react';
 export default function HelloPage({ _urlStc, _staticVer, greeting }) {

package/www/example/stc/view/hello.page.tsx

@@ -5,7 +5,8 @@
  * 1. 这个 .page.tsx 文件（组件 + IProps）
  * 2. 一个 <link> 标签引入 CSS（如果不需要样式可省略）
  * 3. 在 Ctr 方法里调用 _loadReactPage('view/hello', props)
- * 其他一切由框架自动处理：SSR 渲染、import map、props 注入、客户端水合。
+ * 4. 执行 node ./source/main build -d source/www/example/stc 生成客户端水合 bundle
+ * 其他一切由框架自动处理：SSR 渲染、props 注入、客户端水合。
  */
 import { useState, type ReactElement } from 'react';
 

package/www/example/stc/view/react-router.page.d.ts

@@ -15,13 +15,13 @@
  * 3. 嵌套路由通过 Outlet 渲染子路由内容
  *
  * 【编译方式】
- * tsc watch 会自动编译本文件为同路径的 .js，无需额外命令。
- * 如需打包为 .bundle.js，执行：node ./source/main build
+ * tsc watch 会自动编译本文件为同路径的 .js，供服务端 SSR 使用。
+ * 客户端水合必须执行：node ./source/main build -d source/www/example/stc
  *
  * 【Tailwind CSS 构建】
  * 需提前执行 node ./source/main build -d source/www/example/stc 生成 CSS 产物。
  * 框架通过 _staticPath 和 _staticVer 自动拼接带版本号 URL；
- * import map、props JSON、水合脚本均由框架自动注入 HTML，组件无需手动处理。
+ * props JSON、水合脚本均由框架自动注入 HTML，组件无需手动处理。
  */
 interface IUser {
     'id': string;

package/www/example/stc/view/react-router.page.js

@@ -16,13 +16,13 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * 3. 嵌套路由通过 Outlet 渲染子路由内容
  *
  * 【编译方式】
- * tsc watch 会自动编译本文件为同路径的 .js，无需额外命令。
- * 如需打包为 .bundle.js，执行：node ./source/main build
+ * tsc watch 会自动编译本文件为同路径的 .js，供服务端 SSR 使用。
+ * 客户端水合必须执行：node ./source/main build -d source/www/example/stc
  *
  * 【Tailwind CSS 构建】
  * 需提前执行 node ./source/main build -d source/www/example/stc 生成 CSS 产物。
  * 框架通过 _staticPath 和 _staticVer 自动拼接带版本号 URL；
- * import map、props JSON、水合脚本均由框架自动注入 HTML，组件无需手动处理。
+ * props JSON、水合脚本均由框架自动注入 HTML，组件无需手动处理。
  */
 import { useState, useEffect } from 'react';
 import { Routes, Route, Link, NavLink, useParams, useNavigate, useLocation, Outlet } from 'react-router-dom';

package/www/example/stc/view/react-router.page.tsx

@@ -15,13 +15,13 @@
  * 3. 嵌套路由通过 Outlet 渲染子路由内容
  *
  * 【编译方式】
- * tsc watch 会自动编译本文件为同路径的 .js，无需额外命令。
- * 如需打包为 .bundle.js，执行：node ./source/main build
+ * tsc watch 会自动编译本文件为同路径的 .js，供服务端 SSR 使用。
+ * 客户端水合必须执行：node ./source/main build -d source/www/example/stc
  *
  * 【Tailwind CSS 构建】
  * 需提前执行 node ./source/main build -d source/www/example/stc 生成 CSS 产物。
  * 框架通过 _staticPath 和 _staticVer 自动拼接带版本号 URL；
- * import map、props JSON、水合脚本均由框架自动注入 HTML，组件无需手动处理。
+ * props JSON、水合脚本均由框架自动注入 HTML，组件无需手动处理。
  */
 
 import { useState, useEffect } from 'react';
@@ -336,7 +336,6 @@ export default function ReactRouterPage({
                 <meta charSet="UTF-8" />
                 <meta name="viewport" content="width=device-width, initial-scale=1" />
                 <title suppressHydrationWarning>{title}</title>
-                {/* --- import map 由框架自动注入在此标签前，无需手动添加 --- */}
                 {/* --- dev: 需先执行 node ./source/main build -d source/www/example/stc 生成 CSS --- */}
                 <link rel="stylesheet" href={`${_urlStc}view/react-router.page.css?v=${_staticVer}`} />
             </head>

package/www/example/stc/view/react.page.d.ts

@@ -9,26 +9,22 @@
  *
  * 【使用方式】
  * 在 Ctr 方法中调用 _loadReactPage('view/react', { ...props })，
- * 框架自动将 import map、props JSON、水合脚本注入 HTML，组件只写业务逻辑，无需任何框架样板代码。
+ * 框架自动将 props JSON、水合脚本注入 HTML，组件只写业务逻辑，无需任何框架样板代码。
  *
  * 【多页面 / 共用组件】
  * 将公共 UI（如 Label/Input/Checkbox）放在 stc/lib/ui/ 目录，各页面 import 进来。
  * 这和 shadcn/ui 推荐的 components/ui/ 目录结构完全一致。
- * tsc watch 会自动将所有 .tsx 编译为同路径的 .js，无需打包工具。
+ * tsc watch 会自动将所有 .tsx 编译为同路径的 .js，供服务端 SSR 使用。
  *
  * 【编译方式】
  * 本文件 (.tsx) 已集成到 source/tsconfig.json 的 include 中，
- * 开启 `tsc: watch - source/tsconfig.json` 即可自动编译，无需额外命令。
+ * 开启 `tsc: watch - source/tsconfig.json` 即可自动编译服务端文件。
  * 编译输出：stc/view/react.page.js（由 tsc 覆盖写入，勿手动编辑 .js 文件）
+ * 客户端水合需执行：node ./source/main build -d source/www/example/stc
  *
  * 【运行时机】
  * - 服务端（Node.js）：_loadReactPage() 调用 renderToString()，产出完整 HTML 字符串。
- * - 客户端（浏览器）：import map 将 bare import 解析到 esm.sh，hydrateRoot 接管 document。
- * - 两端使用同一份 JS 文件：服务端从磁盘读，浏览器从静态 URL 下载。
- *
- * 【第三方包 import map 自动解析】
- * 开发模式下，框架会自动扫描入口 JS 及其相对引用中的所有 bare specifier，
- * 并通过 esm.sh CDN 自动生成 import map 条目，无需手动配置。
+ * - 客户端（浏览器）：加载 kebab build 生成的 bundle，由 hydrateRoot 接管 document。
  *
  * 【限制】
  * - 不能包含 Node.js 专属代码（fs/path/lDb 等），数据必须通过 props 传入。