@tbox.cn/app-template-h5 0.1.16 → 0.1.17

package/AGENTS.md

@@ -1,12 +1,12 @@
 # AGENTS.md
 
-template-h5 是面向 AI 生成 H5 应用的单 workspace 模板：`apps/client`（React/Vite）+ `apps/server`（Express）。
+template-h5 是面向 AI 生成 Web 应用的单 workspace 模板：`apps/client`（React/Vite）+ `apps/server`（Express）。
 
 ## 工程结构
 
 | 包 | 职责 |
 |---|---|
-| `apps/client` | React/Vite H5 页面与业务入口（@app/client） |
+| `apps/client` | React/Vite Web 页面与业务入口（@app/client） |
 | `apps/server` | Express API：健康检查、静态托管、inspector（@app/server） |
 | `scripts/` | 平台生命周期脚本（prepare/dev/start/stop/build 固定名契约）与工程守卫 |
 
@@ -52,16 +52,20 @@ apps/server/src/dev.ts                   # vite dev 入口（仅 tsx 运行；
 - `apps/server/tests` 契约测试随模板分发勿删（health/JSON 404 断言）；client 业务面测试由应用自建——模板出厂零 client 测试文件（`passWithNoTests` 保绿，新增测试后本约定不变）
 - 服务端凭证/环境变量不进 client bundle（客户端环境值仅 `import.meta.env.VITE_*` 且经 `configureRuntime` 注入）
 
-## web-view 样式约定（嵌入支付宝小程序 web-view 壳时遵守）
+## 端形态决策（先于样式开发）
 
-1. **长度单位 PX 大写**——小写 `px` 被壳内字体缩放改写，大写跳过改写保持视觉尺寸。
-2. **flex 子项设 `flex-shrink: 0`**——防壳内宽度不定导致元素被压缩。
-3. **滚动容器隐藏滚动条**（`::-webkit-scrollbar { display: none }`）。
-4. **颜色用 `rgba()` 传统语法**——避免 `color-mix`/`oklch` 在低版本内核不渲染。
+模板不预设端形态——适配策略由应用自定。开发前先从用户需求确认目标端（PC / 移动 / 自适应 / 嵌入壳）；未明确声明移动端或小程序壳时按通用 Web 处理：默认满幅流式布局，**勿给内容套限宽居中壳**（限宽列、居中窄条、大触区属移动形态决策，仅在用户明确要求时采用）。
+
+## web-view 嵌入约定（仅用户明确要求嵌入支付宝小程序 web-view 壳时适用）
+
+1. **滚动容器隐藏滚动条**（`::-webkit-scrollbar { display: none }`）——移动端无常驻滚动条，内层滚动容器冒出的滚动条与设计不符。
+2. **避免 CSS Color 4+ 新颜色语法**——`color-mix()` / `oklch()` / 空格分隔 `rgb(r g b / a)` 在低版本 web-view 内核整条声明失效（不降级、直接消失）；用 `rgba()`、`#hex` 等传统语法。
+
+未声明嵌入 = 以上两条不适用，勿为兼容壳预写任何样式。另注：大写 `PX` 不是 web-view 约定——它只是 postcss-pxtorem 类构建管线的转义写法（本模板无此管线，应用自建时才相关）。
 
 ## 边界
 
 - 保持单 workspace 的 `apps/client` + `apps/server` 两成员；不新增 `apps/client/` 之外的 Vite 配置或嵌套 lockfile（`pnpm check:workspace` 校验）。
 - 无模块/Provider/主题装配面：缺双端 `apps/*/src/modules.ts`——`npx --yes @tbox.cn/app-cli module add`、`npx --yes @tbox.cn/app-cli new module`、`npx --yes @tbox.cn/app-cli new provider` 会被 CLI 直接拒绝；`npx --yes @tbox.cn/app-cli theme use` 因无主题接线点也不适用。
-- 模板不预设端形态（移动/桌面/自适应）——适配策略由应用自定；全局样式挂点 = `apps/client/src/styles/base.css`（仅设备无关卫生规则）。
+- 全局样式挂点 = `apps/client/src/styles/base.css`（仅设备无关卫生规则）；端形态决策见上节。
 - 结构、路由、命令、依赖或环境变量变化时同步 README 与本文件。

package/README.md

@@ -1,6 +1,6 @@
 # template-h5
 
-tbox H5 全栈模板（包名 `@tbox.cn/app-template-h5`），单 workspace：`apps/client`（React/Vite）+ `apps/server`（Express）。运行时与页面微调经 `@tbox.cn/app-sdk-client` / `@tbox.cn/app-sdk-server`。
+tbox Web 全栈模板（包名 `@tbox.cn/app-template-h5`，h5 为家族历史名——不预设端形态），单 workspace：`apps/client`（React/Vite）+ `apps/server`（Express）。运行时与页面微调经 `@tbox.cn/app-sdk-client` / `@tbox.cn/app-sdk-server`。
 
 ## 快速开始
 
@@ -9,12 +9,12 @@ pnpm install
 pnpm dev
 ```
 
-开发期浏览器访问 `http://localhost:8000`（单端口：API + 页面 + HMR）。`server` 负责 API、健康检查与生产静态托管，`client` 负责 H5 页面与业务入口。
+开发期浏览器访问 `http://localhost:8000`（单端口：API + 页面 + HMR）。`server` 负责 API、健康检查与生产静态托管，`client` 负责 Web 页面与业务入口。
 
 ## 生成新应用
 
 ```sh
-npx --yes @tbox.cn/app-cli create . --name my-h5-app --source @tbox.cn/app-template-h5
+npx --yes @tbox.cn/app-cli create . --name my-web-app --source @tbox.cn/app-template-h5
 pnpm install
 ```
 

package/apps/client/index.html

@@ -4,7 +4,7 @@
     <meta charset="UTF-8" />
     <!-- 基础视口；全屏 safe-area（viewport-fit=cover + env() 补偿）由应用成对启用 -->
     <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <title>H5 应用</title>
+    <title>Web 应用</title>
     <!-- 平台微调(inspector) runtime：由 server 提供 GET /__vs_inspector__.js；dev 下经 Vite 代理到 server。 -->
     <script src="/__vs_inspector__.js" defer></script>
   </head>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@tbox.cn/app-template-h5",
-  "version": "0.1.16",
-  "description": "tbox H5 全栈模板（单 workspace：apps/client + apps/server），运行时与页面微调经 @tbox.cn/app-sdk。",
+  "version": "0.1.17",
+  "description": "tbox Web 全栈模板（单 workspace：apps/client + apps/server；h5 为家族历史名，不预设端形态），运行时与页面微调经 @tbox.cn/app-sdk。",
   "type": "module",
   "engines": {
     "node": ">=24.0.0 <25.0.0"

package/pnpm-lock.template.yaml

@@ -7,8 +7,8 @@ settings:
 catalogs:
   default:
     '@tbox.cn/app-sdk-client':
-      specifier: 0.21.3
-      version: 0.21.3
+      specifier: 0.21.4
+      version: 0.21.4
     '@tbox.cn/app-sdk-server':
       specifier: 0.26.2
       version: 0.26.2
@@ -97,7 +97,7 @@ importers:
     dependencies:
       '@tbox.cn/app-sdk-client':
         specifier: 'catalog:'
-        version: 0.21.3
+        version: 0.21.4
       react:
         specifier: 'catalog:'
         version: 18.3.1
@@ -955,10 +955,6 @@ packages:
   '@standard-schema/spec@1.1.0':
     resolution: {integrity: sha512-l2aFy5jALhniG5HgqrD6jXLi/rUWrKvqN/qJx6yoJsgKhblVd+iqqU4RCXavm/jPityDo5TCvKMnpjKnOriy0w==}
 
-  '@tbox.cn/app-contracts@0.13.0':
-    resolution: {integrity: sha512-8sqP/23MoUlbTX9enFNotP5bu7XKFfigDUJ6sEn1Ff2a0rRlSTWzLWmDv9lP70cfZMPjh4MHoLKFoukr8QPvMA==}
-    engines: {node: '>=20.0.0'}
-
   '@tbox.cn/app-contracts@0.13.2':
     resolution: {integrity: sha512-0lY9g29ice7xYbmV5XDnEiMmM70jvSzeK2cciUZVpzHgGykWqZiPRlqXIGkIRY7uObDQ1cICHC4mS67HuNQ8Jg==}
     engines: {node: '>=20.0.0'}
@@ -967,12 +963,8 @@ packages:
     resolution: {integrity: sha512-P16LFd+ZzIASrujs6fyaOEwRnsLg7Lh5k1qOVDNblmohrvUbVIOK5ntn+7mupJxnjK7SY43RUT4mtWtfM85/rQ==}
     engines: {node: '>=20.0.0'}
 
-  '@tbox.cn/app-sdk-client@0.21.3':
-    resolution: {integrity: sha512-64y22k5gzCc9eEQ0IJA1izxPaosNEmoCJ4YrsfHOoHYq2UPJCCmP7RIu3Rn4stPZ4tcmRdMdAi2y5499KObYHw==}
-    engines: {node: '>=20.0.0'}
-
-  '@tbox.cn/app-sdk-core@0.20.4':
-    resolution: {integrity: sha512-4kcoxnZnPgsO0RwAsjsodOXRhZNQcr9r3INN3Z03/JR2e3E+izkW2YHsgGcdbVSVX81s8gZrkaBbE+xco3wSqg==}
+  '@tbox.cn/app-sdk-client@0.21.4':
+    resolution: {integrity: sha512-Vbk0593RGWGIVgGiR1xNOF8x62z+2/Ix6NRTHURhdrLLB1pOIFlixm4AHn9d/noyaItiXTND55OeOTAaTEJQcQ==}
     engines: {node: '>=20.0.0'}
 
   '@tbox.cn/app-sdk-core@0.20.5':
@@ -2825,12 +2817,6 @@ snapshots:
 
   '@standard-schema/spec@1.1.0': {}
 
-  '@tbox.cn/app-contracts@0.13.0':
-    dependencies:
-      '@ag-ui/core': 0.0.47
-      react: 18.3.1
-      zod: 3.25.76
-
   '@tbox.cn/app-contracts@0.13.2':
     dependencies:
       '@ag-ui/core': 0.0.47
@@ -2843,17 +2829,13 @@ snapshots:
       react: 18.3.1
       zod: 3.25.76
 
-  '@tbox.cn/app-sdk-client@0.21.3':
+  '@tbox.cn/app-sdk-client@0.21.4':
     dependencies:
-      '@tbox.cn/app-contracts': 0.13.0
-      '@tbox.cn/app-sdk-core': 0.20.4
+      '@tbox.cn/app-contracts': 0.13.3
+      '@tbox.cn/app-sdk-core': 0.20.5
       react: 18.3.1
       react-dom: 18.3.1(react@18.3.1)
 
-  '@tbox.cn/app-sdk-core@0.20.4':
-    dependencies:
-      '@tbox.cn/app-contracts': 0.13.0
-
   '@tbox.cn/app-sdk-core@0.20.5':
     dependencies:
       '@tbox.cn/app-contracts': 0.13.2

package/pnpm-workspace.template.yaml

@@ -34,12 +34,12 @@ catalog:
   express: 4.22.2
   "@types/express": 4.17.25
   "@tbox.cn/app-sdk-core": 0.20.5
-  "@tbox.cn/app-sdk-client": 0.21.3
+  "@tbox.cn/app-sdk-client": 0.21.4
   "@tbox.cn/app-sdk-server": 0.26.2
   "@tbox.cn/app-agent-sdk-server": 0.3.3
-  "@tbox.cn/app-agent-sdk-client": 0.2.0
+  "@tbox.cn/app-agent-sdk-client": 0.2.1
   "@tbox.cn/app-contracts": 0.13.3
-  "@tbox.cn/app-contracts-mall": 0.13.2
+  "@tbox.cn/app-contracts-mall": 0.14.0
   eslint: 9.39.5
   typescript-eslint: 8.67.0
   eslint-plugin-react-hooks: 5.2.0

package/scripts/dev.sh

@@ -6,7 +6,10 @@ PROJECT_DIR="$(dirname "$SCRIPT_DIR")"
 cd "$PROJECT_DIR"
 echo "Project directory: $PROJECT_DIR"
 
+echo "Installing dependencies..."
+pnpm install
+
 echo "Starting development server..."
 echo "  - http://localhost:8000 (API + 页面 + HMR)"
-# 相对 filter：本脚本在仓内被 pnpm dev h5（native preset）调用，名称 filter 会三模板同名命中
+# 相对 filter：仓内直跑时名称 filter 会三模板同名命中（@app/server ×3）
 pnpm --filter ./apps/server dev