@proteus-vue/create-proteus 0.2.0

package/README.md

@@ -0,0 +1,40 @@
+# @proteus-vue/create-proteus —— Proteus 脚手架
+
+> `npm create @proteus-vue/proteus my-app` —— 一键生成 Web + 微信小程序（Skyline）双端工程。
+
+## 使用
+
+```bash
+npm create @proteus-vue/proteus my-app
+cd my-app
+npm install
+npm run dev:web        # Web 端（浏览器打开 Vite 提示地址）
+npm run build:mp       # 小程序端（微信开发者工具导入 dist/mp-weixin，替换 proteus.config.ts 的 appid）
+```
+
+## 生成内容（32 个文件）
+
+- **编译管线**：`vite.config.ts` + `vite-plugin-mp-transform.ts`（薄适配层，依赖 npm 包 `@proteus-vue/compiler`）+ `scripts/gen-routes.ts`（路由/app.json/page.json 生成器）+ `scripts/mp-entry-stub.ts`
+- **框架本体**（src/ 快照）：`router`（Router/RouterView/guards/skyline/presets）+ `platform`（adapter 双端）+ `runtime`（setData 桥接/生命周期/app 骨架）+ `shims`（wx 类型）
+- **应用骨架**：`src/main.ts`（Web 入口）/ `src/main.mp.ts`（★极简入口：不写 App()，骨架自动生成）/ `src/App.vue` / `src/pages/index.vue`（首页，含 `<route>` 块）
+- **配置**：`proteus.config.ts`（platform/skyline/appid/rules 规则覆盖…）
+
+## 模板维护（★与主仓库同步）
+
+模板 = 主仓库快照 + 手写模板，`scripts/snapshot-template.ts` 负责同步：
+
+```bash
+tsx scripts/snapshot-template.ts
+```
+
+- **自动快照**：`src/platform/` `src/runtime/` `src/shims/` `src/router/`（除 auto-routes.ts）`scripts/`（除 snapshot 自身）`vite-plugin-mp-transform.ts`（import 替换为 `@proteus-vue/compiler`）`tsconfig.json` `index.html`（入口替换为 src/main.ts）
+- **手写模板**（改主仓时手动同步）：`package.json`（含 `{{name}}` 占位）/ `proteus.config.ts` / `vite.config.ts` / `src/main.ts` / `src/main.mp.ts` / `src/App.vue` / `src/pages/index.vue` / `src/router/auto-routes.ts`（仅首页占位，首次 build 时 gen-routes 重新生成）
+
+> ⚠ `@proteus-vue/compiler` 未发布 npm 前，生成工程安装会 404；临时用 `npm install <仓库>/packages/compiler` 或 npm link。
+
+## 发布
+
+```bash
+npm run build -w @proteus-vue/create-proteus   # esbuild 单文件（dist/index.js + shebang）
+npm publish                       # files: dist + templates
+```

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+/** 复制模板工程到目标目录（纯函数：返回生成的文件列表；templatesDir 可注入便于测试） */
+export declare function copyTemplate(targetDir: string, opts: {
+    name: string;
+}, templatesDir?: string): string[];

package/dist/index.js

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import fs from "node:fs";
+import path from "node:path";
+var TEMPLATES_DIR = process.env.CREATE_PROTEUS_TEMPLATES ?? new URL("../templates/", import.meta.url).pathname;
+var NEXT_STEPS = (name) => `\u2705 \u5DF2\u751F\u6210\u5DE5\u7A0B\uFF1A${name}
+
+\u4E0B\u4E00\u6B65\uFF1A
+  cd ${name}
+  npm install            # \u5B89\u88C5\u4F9D\u8D56\uFF08@proteus-vue/compiler \u53D1\u5E03\u540E\u53EF\u6B63\u5E38\u5B89\u88C5\uFF1B\u672A\u53D1\u5E03\u65F6\u7528\u4ED3\u5E93 workspace \u6216 npm link\uFF09
+  npm run dev:web        # Web \u7AEF\uFF08\u6D4F\u89C8\u5668\u6253\u5F00 Vite \u63D0\u793A\u5730\u5740\uFF09
+  npm run build:mp       # \u5C0F\u7A0B\u5E8F\u7AEF\uFF08\u5FAE\u4FE1\u5F00\u53D1\u8005\u5DE5\u5177\u5BFC\u5165 dist/mp-weixin\uFF0C\u9700\u66FF\u6362 proteus.config.ts \u7684 appid\uFF09
+
+\u63D0\u793A\uFF1A
+  - npx proteus explain src/pages/index.vue   # \u51B3\u7B56 trace\uFF08\u8BE5\u6587\u4EF6\u89E6\u53D1\u7684\u5168\u90E8\u8F6C\u6362\u89C4\u5219\uFF09
+  - npx proteus rules                         # \u7F16\u8BD1\u5668\u80FD\u529B\u6E05\u5355\uFF0849 \u6761 AI \u8BF4\u660E\u4E66\uFF09
+  - \u7F16\u8F91 proteus.config.ts \u7684 rules \u6BB5        # \u5E95\u7EBF\u5FAA\u73AF \u2462\uFF1A\u6539\u914D\u7F6E\u5373\u6539\u53D8\u7F16\u8BD1\u884C\u4E3A`;
+function copyTemplate(targetDir, opts, templatesDir = TEMPLATES_DIR) {
+  const generated = [];
+  walk(templatesDir, (from, rel) => {
+    const to = path.join(targetDir, rel);
+    fs.mkdirSync(path.dirname(to), { recursive: true });
+    const content = fs.readFileSync(from, "utf-8").replace(/\{\{name\}\}/g, opts.name);
+    fs.writeFileSync(to, content);
+    generated.push(rel);
+  });
+  return generated;
+}
+function walk(dir, visit, base = "") {
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    if (entry.name === ".git") continue;
+    const full = path.join(dir, entry.name);
+    const rel = base ? `${base}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) walk(full, visit, rel);
+    else visit(full, rel);
+  }
+}
+function main() {
+  const [nameArg, ...rest] = process.argv.slice(2);
+  if (!nameArg) {
+    console.error("\u7528\u6CD5\uFF1Anpm create @proteus-vue/proteus <\u9879\u76EE\u540D>\uFF08\u5982 npm create @proteus-vue/proteus my-app\uFF09");
+    process.exitCode = 1;
+    return;
+  }
+  if (rest.length) {
+    console.error(`\u591A\u4F59\u53C2\u6570\uFF1A${rest.join(" ")}`);
+    process.exitCode = 1;
+    return;
+  }
+  const name = nameArg.toLowerCase().replace(/[^a-z0-9-]/g, "-").replace(/^-+|-+$/g, "");
+  if (!name) {
+    console.error("\u9879\u76EE\u540D\u4E0D\u5408\u6CD5\uFF08\u4EC5\u5141\u8BB8\u5B57\u6BCD/\u6570\u5B57/\u8FDE\u5B57\u7B26\uFF09");
+    process.exitCode = 1;
+    return;
+  }
+  if (fs.existsSync(nameArg) && fs.readdirSync(nameArg).length > 0) {
+    console.error(`\u76EE\u5F55\u5DF2\u5B58\u5728\u4E14\u975E\u7A7A\uFF1A${nameArg}`);
+    process.exitCode = 1;
+    return;
+  }
+  const targetDir = nameArg;
+  const files = copyTemplate(targetDir, { name });
+  console.log(`\u5DF2\u590D\u5236 ${files.length} \u4E2A\u6587\u4EF6\uFF08\u542B\u6A21\u677F\u5FEB\u7167\uFF1A\u6846\u67B6\u672C\u4F53 + \u7F16\u8BD1\u7BA1\u7EBF + \u9996\u9875\uFF09`);
+  console.log(NEXT_STEPS(nameArg));
+}
+main();
+export {
+  copyTemplate
+};

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@proteus-vue/create-proteus",
+  "version": "0.2.0",
+  "description": "Proteus 脚手架：npm create @proteus-vue/proteus my-app —— 一键生成 Web + 微信小程序（Skyline）双端工程",
+  "type": "module",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "access": "public"
+  },
+  "bin": {
+    "create-proteus": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json --emitDeclarationOnly && esbuild src/index.ts --bundle --format=esm --platform=node --outfile=dist/index.js --banner:js=\"#!/usr/bin/env node\""
+  }
+}

package/templates/.github/workflows/proteus.yml

@@ -0,0 +1,53 @@
+# AUTO-GENERATED by @proteus-vue/create-proteus 模板（cli-plus G-33 M4）。可自由编辑。
+# 流水线：proteus check（CSS/Style/Router/CLI 四域门禁）→ 双端构建 → 测试（L1-L3 + Web E2E；automator 仅 Mac runner）
+name: Proteus CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: npm
+      - run: npm ci
+      - name: proteus check（四域门禁）
+        run: npx proteus check
+  build:
+    needs: check
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: npm
+      - run: npm ci
+      - run: npx proteus build --target web
+      - run: npx proteus build --target skyline
+      - uses: actions/upload-artifact@v4
+        with:
+          name: proteus-dist
+          path: |
+            dist/
+            dist/mp-weixin/
+  test:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: npm
+      - run: npm ci
+      - name: 单测 + 编译快照（L1-L3）
+        run: npx proteus test
+      - name: Web E2E（Playwright headless）
+        run: npx proteus build --target web && npx proteus test e2e:web

package/templates/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Proteus</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/templates/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "{{name}}",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "description": "Proteus 应用：一份标准 Vue 源码 → Web + 微信小程序（Skyline）",
+  "scripts": {
+    "dev:web": "vite --mode web",
+    "build:web": "vue-tsc --noEmit && vite build --mode web",
+    "dev:mp": "tsx scripts/gen-routes.ts && vite --mode mp-weixin",
+    "build:mp": "tsx scripts/gen-routes.ts && vue-tsc --noEmit && vite build --mode mp-weixin",
+    "debug:mp": "PROTEUS_DEBUG=1 npm run build:mp",
+    "proteus": "npx proteus"
+  },
+  "dependencies": {
+    "@proteus-vue/router": "^0.2.0-beta.0",
+    "@proteus-vue/runtime": "^0.2.0-beta.0",
+    "@proteus-vue/shared": "^0.2.0-beta.0",
+    "vue": "^3.4.0"
+  },
+  "devDependencies": {
+    "@proteus-vue/compiler": "^0.3.0-beta.0",
+    "@proteus-vue/plugin-vite": "^0.2.0-beta.0",
+    "@types/node": "^20.0.0",
+    "@vitejs/plugin-vue": "^5.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.4.0",
+    "vite": "^5.0.0",
+    "vue-tsc": "^2.0.0"
+  }
+}

package/templates/proteus.config.ts

@@ -0,0 +1,35 @@
+// proteus.config.ts —— Proteus 框架统一配置（拆包步骤 7：类型契约来自 @proteus-vue/plugin-vite npm 包）
+import type { ProteusConfig } from '@proteus-vue/plugin-vite'
+
+const config: ProteusConfig = {
+  platform: 'mp-weixin',
+  skyline: true,
+  appid: 'wx0000000000', // 替换为真实 AppID
+  pagesDir: 'src/pages',
+  routesOutput: 'src/router/auto-routes.ts',
+  customRoute: {
+    registerPresets: true,
+    // 内置预设 builders（随 @proteus-vue/router 包发布源码，插件读取后内联进 app.js 注册）
+    builders: {
+      halfScreen: 'node_modules/@proteus-vue/router/src/presets/halfScreen.ts',
+      slideUp: 'node_modules/@proteus-vue/router/src/presets/slideUp.ts',
+      scaleDown: 'node_modules/@proteus-vue/router/src/presets/scaleDown.ts',
+    },
+  },
+  // ★底线循环 ①③：规则覆盖（改这里立即改变编译行为）
+  rules: {
+    disabled: [],
+    mapping: {},
+    customTags: {}, // 例：{ 'my-widget': 'view' } —— 新增标签映射
+  },
+  setDataBridge: {
+    batchWindow: 16, // ~1 帧
+    perComponent: true,
+  },
+  style: {
+    px2rpx: true,
+    rpxRatio: 2,
+  },
+}
+
+export default config

package/templates/scripts/gen-routes.ts

@@ -0,0 +1,7 @@
+// scripts/gen-routes.ts —— 编译期路由表生成器 CLI（拆包步骤 7：逻辑来自 @proteus-vue/plugin-vite npm 包）
+// 运行：tsx scripts/gen-routes.ts（dev:mp / build:mp 前置步骤）
+// 输出：src/router/auto-routes.ts + dist/mp-weixin/{app.json,page.json,component.json}
+import config from '../proteus.config'
+import { runGenRoutes } from '@proteus-vue/plugin-vite'
+
+runGenRoutes({ config })

package/templates/scripts/mp-entry-stub.ts

@@ -0,0 +1,5 @@
+// scripts/mp-entry-stub.ts
+// mp 构建的 rollup 占位入口：真实 app.js 由 vite-plugin-mp-transform 在 buildStart 直出为纯文本资产
+// （绕开 rollup 打包——微信 worklet 响应式重执行对打包代码不友好，见 examples/main.mp.ts 注释）
+// 构建后此 chunk 会被插件在 generateBundle 中删除
+export {}

package/templates/src/App.vue

@@ -0,0 +1,18 @@
+<!-- src/App.vue —— Web 端根组件（SPA 壳：RouterView 按当前路由渲染页面） -->
+<script setup lang="ts">
+// RouterView 为应用壳（随应用存放），不再从框架包引子路径（拆包步骤 7）
+import RouterView from './router/RouterView.vue'
+</script>
+
+<template>
+  <div class="app">
+    <RouterView />
+  </div>
+</template>
+
+<style>
+.app {
+  font-family: system-ui, -apple-system, sans-serif;
+  color: #1f2328;
+}
+</style>

package/templates/src/main.mp.ts

@@ -0,0 +1,18 @@
+// src/main.mp.ts —— 小程序端入口（★极简模式）
+// 不需要写 App()/onLaunch/调试日志/错误捕获——app 骨架由编译插件自动生成（appSkeleton），
+// 本文件只需写"自定义"：自定义路由 builder（覆盖/新增预设，见 proteus.config customRoute）。
+// 若要完全自定义 app 生命周期，写一个含 App() 的完整入口即可（插件尊重原样）。
+
+// 示例：自定义路由 builder（halfScreen 半屏转场，微信 RouteBuilder 契约）
+// function myBuilder(customRouteContext: RouteContext): RouteBuilderResult {
+//   const primaryAnimation = customRouteContext.primaryAnimation
+//   const handlePrimaryAnimation = () => {
+//     'worklet'
+//     const t = primaryAnimation.value
+//     return { transform: `translateY(${(1 - t) * 100}%)` }
+//   }
+//   return { opaque: false, barrierDismissible: true, barrierColor: 'rgba(0,0,0,0.6)', handlePrimaryAnimation }
+// }
+// if (typeof wx !== 'undefined' && wx.router) {
+//   wx.router.addRouteBuilder('halfScreen', myBuilder)
+// }

package/templates/src/main.ts

@@ -0,0 +1,5 @@
+// src/main.ts —— Web 端入口（Web 原生、零转换：标准 Vue SPA）
+import { createApp } from 'vue'
+import App from './App.vue'
+
+createApp(App).mount('#app')

package/templates/src/pages/index.vue

@@ -0,0 +1,33 @@
+<!-- src/pages/index.vue —— 首页（路由页面：编译期由 gen-routes 扫描注册） -->
+<route>
+{
+  "meta": {
+    "title": "首页",
+    "isTab": true
+  }
+}
+</route>
+<script setup lang="ts">
+import { ref } from 'vue'
+
+const count = ref(0)
+
+function handleTap() {
+  count.value++
+}
+</script>
+
+<template>
+  <div class="home">
+    <h1>Hello Proteus</h1>
+    <p class="tapped-count">tapped {{ count }} times</p>
+    <button @click="handleTap">tap</button>
+  </div>
+</template>
+
+<style>
+.home {
+  text-align: center;
+  padding: 48px 0;
+}
+</style>

package/templates/src/router/RouterView.vue

@@ -0,0 +1,378 @@
+<!-- examples/router/RouterView.vue —— Web 端渲染容器（应用壳，仅 Web 构建使用）
+     ★ Web 原生转场：routeType 驱动 Vue <Transition>（CSS 动画），与 MP 的 Skyline worklet 转场对应——
+       同一套 routeType API（halfScreen/slideUp → 上滑、scaleDown → 缩放、默认 fade） -->
+<script setup lang="ts">
+import { computed, ref, defineAsyncComponent } from 'vue'
+import type { Component } from 'vue'
+import { routeMap } from './auto-routes'
+import { adapter } from '@proteus-vue/shared'
+import { webTransitionName } from '@proteus-vue/router'
+
+// 懒加载全部页面（含分包页）：Web 端按页面自动 code-split
+// glob 相对本文件（examples/router/）→ examples/pages 与 examples/subpackages/*/pages
+const modules = import.meta.glob('../**/pages/**/*.vue')
+
+// 页面组件缓存 + 预热：异步组件首次挂载会跳过 Transition 动画（真机/浏览器验证"第一次无下沉转场"），
+// 预热使首次导航也同步挂载（chunk 已加载则 defineAsyncComponent 不再是异步 wrapper）
+const pageCache = new Map<string, Component>()
+for (const [key, load] of Object.entries(modules)) {
+  ;(load() as Promise<{ default: Component }>).then((mod) => {
+    pageCache.set(key, mod.default)
+  })
+}
+const current = ref(adapter.getCurrentPages()[0]?.route || 'pages/index')
+
+// 路由变化 → 转场名（★透明化：routeType → Vue Transition 映射由框架共享表 webTransitionName 提供，
+//   不再 RouterView 私有硬编码；三端共用同一枚举见 packages/router/src/transforms/transform-transition.ts）
+const transitionName = ref('fade')
+let lastForwardName = 'fade' // 当前页进入时的转场名（后退时取其反向）
+adapter.onPageLoad?.((route, _query, routeType, nav) => {
+  current.value = route || 'pages/index'
+  if (nav === 'back') {
+    // 反向转场：用当前退出页进入时的转场名 + '-back'
+    transitionName.value =
+      lastForwardName && lastForwardName !== 'fade' ? `${lastForwardName}-back` : 'fade'
+  } else if (nav === 'replace' || nav === 'reLaunch' || nav === 'switchTab') {
+    lastForwardName = 'fade' // 无堆叠语义，后退按 fade
+    transitionName.value = nav === 'replace' ? 'replace' : nav === 'reLaunch' ? 'reset' : 'tab'
+  } else {
+    lastForwardName = webTransitionName(routeType)
+    transitionName.value = lastForwardName
+  }
+})
+
+const currentRoute = computed(() => current.value || 'pages/index')
+
+// 层叠转场（routeType 前进/后退）：新旧同屏重叠 → 绝对定位 + default 模式；
+// fade / replace / reset / tab 用 out-in（先退后进）
+const layeredNames = ['halfscreen', 'slide-up', 'scale', 'halfscreen-back', 'slide-up-back', 'scale-back']
+const isLayered = computed(() => layeredNames.includes(transitionName.value))
+
+// 遮罩对齐 MP barrierColor：halfScreen 0.4 / scaleDown 0.8（forward + back 都显示）；slideUp opaque 无遮罩
+// 遮罩常驻但被停留页(z:2)盖住：forward 时旧页(z:0)暴露在遮罩下淡入，back 时前页(z:0)暴露在遮罩下淡出
+const showBarrier = computed(() => {
+  const n = transitionName.value
+  return n === 'halfscreen' || n === 'scale' || n === 'halfscreen-back' || n === 'scale-back'
+})
+const isBack = computed(() => transitionName.value.endsWith('-back'))
+const barrierOpacity = computed(() => (transitionName.value.startsWith('halfscreen') ? 0.4 : 0.8))
+
+const view = computed<Component | null>(() => {
+  // routeMap 以 name 为键，这里收到的是 path，需按 path 回退查找（同 guards.getCurrentFrom）
+  const rec =
+    routeMap[currentRoute.value] || Object.values(routeMap).find((r) => r.path === currentRoute.value)
+  if (!rec) return null
+  // rec.component 为相对 examples/router/ 的路径，与 glob 键一致；优先用缓存（同步挂载保证转场）
+  const cached = pageCache.get(rec.component)
+  if (cached) return cached
+  const load = (modules as Record<string, () => Promise<unknown>>)[rec.component]
+  return load ? defineAsyncComponent(load as () => Promise<Component>) : null
+})
+</script>
+
+<template>
+  <!-- routeType 转场全部层叠（default 模式 + 绝对定位重叠 → 新旧同屏）：
+       halfScreen/slideUp/scaleDown 各自层叠语义；默认 fade 用 out-in 先退后进
+       :key 按路由强制重挂载触发过渡 -->
+  <div class="router-view" :class="{ layered: isLayered }">
+    <!-- 遮罩层（对齐 MP barrierColor）：旧页/前页(z:0)之上、停留页(z:2)之下；forward 淡入压暗，back 淡出抬起 -->
+    <div
+      v-if="showBarrier"
+      class="route-barrier"
+      :class="{ 'barrier-out': isBack }"
+      :style="{ '--barrier-opacity': barrierOpacity }"
+    />
+    <Transition :name="transitionName" :mode="isLayered ? undefined : 'out-in'">
+      <component :is="view" v-if="view" :key="currentRoute" class="page" />
+      <div v-else :key="'404'" class="page">404 Not Found</div>
+    </Transition>
+  </div>
+</template>
+
+<style>
+/* 层叠容器：所有 routeType 转场时新旧页同屏绝对定位重叠 */
+.router-view {
+  position: relative;
+  min-height: 100vh;
+}
+.router-view.layered .page {
+  position: absolute;
+  inset: 0;
+  overflow-y: auto;
+}
+
+/* 遮罩层（对齐 MP barrierColor）：前/旧页(z:0)之上、停留页(z:2)之下；forward 淡入压暗、back 淡出抬起 */
+.route-barrier {
+  position: absolute;
+  inset: 0;
+  z-index: 1;
+  background: #000;
+  opacity: 0;
+  animation: barrier-in 0.3s ease forwards;
+  pointer-events: none;
+}
+@keyframes barrier-in {
+  from {
+    opacity: 0;
+  }
+  to {
+    opacity: var(--barrier-opacity);
+  }
+}
+.route-barrier.barrier-out {
+  animation: barrier-out 0.4s ease forwards;
+}
+@keyframes barrier-out {
+  from {
+    opacity: var(--barrier-opacity);
+  }
+  to {
+    opacity: 0;
+  }
+}
+
+/* 页面"纸片"基础样式：白色背景 + 撑满视口 + 恒在遮罩(z:1)之上(z:2)
+   层叠转场时旧页被 leave 规则降为 z:0 暴露在遮罩下；停留页始终盖住遮罩 */
+.page {
+  background: #fff;
+  min-height: 100vh;
+  z-index: 2;
+}
+
+/* 默认：淡入淡出 */
+.fade-enter-active,
+.fade-leave-active {
+  transition: opacity 0.25s ease;
+}
+.fade-enter-from,
+.fade-leave-to {
+  opacity: 0;
+}
+
+/* halfScreen / slideUp：底部上滑（缓出曲线，与 MP 预设一致） */
+.slide-up-enter-active {
+  transition: transform 0.32s cubic-bezier(0.35, 0.91, 0.33, 0.97);
+}
+.slide-up-enter-from {
+  transform: translateY(20%);
+}
+.slide-up-leave-active {
+  transition: opacity 0.25s ease;
+}
+.slide-up-leave-to {
+  opacity: 0;
+}
+
+/* scaleDown：层叠缩放——新页从底部滑入覆盖（z 上层），旧页同时下沉缩放（z 下层） */
+.scale-enter-active {
+  transition: transform 0.4s cubic-bezier(0.35, 0.91, 0.33, 0.97);
+  z-index: 2;
+}
+.scale-enter-from {
+  transform: translateY(100%);
+}
+.scale-leave-active {
+  transition:
+    transform 0.4s cubic-bezier(0.35, 0.91, 0.33, 0.97),
+    opacity 0.4s ease,
+    border-radius 0.4s ease;
+  z-index: 0;
+}
+.scale-leave-to {
+  transform: scale(0.92) translateY(4%);
+  opacity: 0.8;
+  border-radius: 12px;
+}
+
+/* slideUp：层叠推入——新页底部推入覆盖（z:2），旧页被推出视口上方（z:1，对应 MP slideUp） */
+.slide-up-enter-active {
+  transition: transform 0.32s cubic-bezier(0.35, 0.91, 0.33, 0.97);
+  z-index: 2;
+}
+.slide-up-enter-from {
+  transform: translateY(100%);
+}
+.slide-up-leave-active {
+  transition:
+    transform 0.32s cubic-bezier(0.35, 0.91, 0.33, 0.97),
+    opacity 0.32s ease;
+  z-index: 0;
+}
+.slide-up-leave-to {
+  transform: translateY(-20%);
+  opacity: 0;
+}
+
+/* halfScreen：层叠半屏——新页底部滑入覆盖（z:2），旧页保持原位淡出（对应 MP 半屏前页保持） */
+.halfscreen-enter-active {
+  transition: transform 0.3s cubic-bezier(0.35, 0.91, 0.33, 0.97);
+  z-index: 2;
+}
+.halfscreen-enter-from {
+  transform: translateY(100%);
+}
+.halfscreen-leave-active {
+  transition: opacity 0.3s ease;
+  z-index: 0;
+}
+.halfscreen-leave-to {
+  opacity: 0;
+}
+
+/* ===== 反向转场（返回/后退：当前页 B 反向退出滑出底部，前页 A 恢复原态）===== */
+/* scale 返回：B 滑出底部（z:2），A 从下沉态恢复 scale(0.92)→1 */
+.scale-back-enter-active {
+  transition:
+    transform 0.4s cubic-bezier(0.35, 0.91, 0.33, 0.97),
+    opacity 0.4s ease,
+    border-radius 0.4s ease;
+  z-index: 0; /* 低于遮罩(z:1)，恢复过程中被遮罩压暗 */
+}
+.scale-back-enter-from {
+  transform: scale(0.92) translateY(4%);
+  opacity: 0.8;
+  border-radius: 12px;
+}
+.scale-back-leave-active {
+  transition: transform 0.4s cubic-bezier(0.35, 0.91, 0.33, 0.97);
+  z-index: 2;
+}
+.scale-back-leave-to {
+  transform: translateY(100%);
+}
+
+/* slideUp 返回：B 滑出底部（z:2），A 从被推出上方恢复 */
+.slide-up-back-enter-active {
+  transition:
+    transform 0.32s cubic-bezier(0.35, 0.91, 0.33, 0.97),
+    opacity 0.32s ease;
+  z-index: 1;
+}
+.slide-up-back-enter-from {
+  transform: translateY(-20%);
+  opacity: 0;
+}
+.slide-up-back-leave-active {
+  transition: transform 0.32s cubic-bezier(0.35, 0.91, 0.33, 0.97);
+  z-index: 2;
+}
+.slide-up-back-leave-to {
+  transform: translateY(100%);
+}
+
+/* halfScreen 返回：B 滑出底部（z:2），A 轻微下沉后恢复 */
+.halfscreen-back-enter-active {
+  transition: transform 0.3s cubic-bezier(0.35, 0.91, 0.33, 0.97);
+  z-index: 0; /* 低于遮罩(z:1) */
+}
+.halfscreen-back-enter-from {
+  transform: translateY(8%);
+}
+.halfscreen-back-leave-active {
+  transition: transform 0.3s cubic-bezier(0.35, 0.91, 0.33, 0.97);
+  z-index: 2;
+}
+.halfscreen-back-leave-to {
+  transform: translateY(100%);
+}
+
+/* replace（redirectTo）：替换当前页——旧页轻微缩小淡出、新页淡入（out-in） */
+.replace-enter-active,
+.replace-leave-active {
+  transition:
+    opacity 0.2s ease,
+    transform 0.2s ease;
+}
+.replace-enter-from {
+  opacity: 0;
+  transform: scale(0.98);
+}
+.replace-leave-to {
+  opacity: 0;
+  transform: scale(0.98);
+}
+
+/* reLaunch：重置——淡入 */
+.reset-enter-active {
+  transition: opacity 0.25s ease;
+}
+.reset-enter-from {
+  opacity: 0;
+}
+.reset-leave-active {
+  transition: opacity 0.2s ease;
+}
+.reset-leave-to {
+  opacity: 0;
+}
+
+/* switchTab：tab 切换——淡入淡出 */
+.tab-enter-active {
+  transition: opacity 0.2s ease;
+}
+.tab-enter-from {
+  opacity: 0;
+}
+.tab-leave-active {
+  transition: opacity 0.15s ease;
+}
+.tab-leave-to {
+  opacity: 0;
+}
+
+/* 无障碍：减少动态偏好时关闭全部转场 */
+@media (prefers-reduced-motion: reduce) {
+  .fade-enter-active,
+  .fade-leave-active,
+  .slide-up-enter-active,
+  .slide-up-leave-active,
+  .halfscreen-enter-active,
+  .halfscreen-leave-active,
+  .scale-enter-active,
+  .scale-leave-active,
+  .slide-up-back-enter-active,
+  .slide-up-back-leave-active,
+  .halfscreen-back-enter-active,
+  .halfscreen-back-leave-active,
+  .scale-back-enter-active,
+  .scale-back-leave-active,
+  .replace-enter-active,
+  .replace-leave-active,
+  .reset-enter-active,
+  .reset-leave-active,
+  .tab-enter-active,
+  .tab-leave-active {
+    transition: none !important;
+  }
+  .fade-enter-from,
+  .fade-leave-to,
+  .slide-up-enter-from,
+  .slide-up-leave-to,
+  .halfscreen-enter-from,
+  .halfscreen-leave-to,
+  .scale-enter-from,
+  .scale-leave-to,
+  .slide-up-back-enter-from,
+  .slide-up-back-leave-to,
+  .halfscreen-back-enter-from,
+  .halfscreen-back-leave-to,
+  .scale-back-enter-from,
+  .scale-back-leave-to,
+  .replace-enter-from,
+  .replace-leave-to,
+  .reset-enter-from,
+  .reset-leave-to,
+  .tab-enter-from,
+  .tab-leave-to {
+    transform: none;
+    opacity: 1;
+  }
+  .route-barrier {
+    animation: none;
+    opacity: var(--barrier-opacity);
+  }
+  .route-barrier.barrier-out {
+    opacity: 0;
+  }
+}
+</style>

package/templates/src/router/auto-routes.ts

@@ -0,0 +1,17 @@
+// src/router/auto-routes.ts —— 应用侧路由表（AUTO-GENERATED by scripts/gen-routes.ts，勿手动编辑）
+// ★拆包步骤 4：auto-routes 随应用存放（工厂化后路由表由应用注入 createRouter），不再属于 @proteus-vue/router 包
+import type { RouteRecord } from '@proteus-vue/router/types'
+
+export const routes: RouteRecord[] = [
+  { name: "index", path: "pages/index", component: "../pages/index.vue", meta: {"title":"首页","isTab":true} },
+]
+
+export const tabRoutes: RouteRecord[] = routes.filter(r => r.meta?.isTab)
+export const routeMap: Record<string, RouteRecord> = routes.reduce((m, r) => { m[r.name] = r; return m }, {} as Record<string, RouteRecord>)
+
+// ★ 类型提示：按路由名索引的参数类型表（来源：<route> 块 params 声明）
+declare module '@proteus-vue/router/types' {
+  interface RouteParamsByName {
+    'index': {  },
+  }
+}

package/templates/src/router/index.ts

@@ -0,0 +1,18 @@
+// examples/router/index.ts —— 应用侧路由单例（拆包步骤 4 工厂化）
+// ★工厂化：路由表不再藏在框架里，由本文件从 gen-routes 生成的 ./auto-routes 注入 createRouter
+// 应用开发者视角：只需这一行单例；换应用换路由表，框架零改动
+import { createRouter } from '@proteus-vue/router'
+import { routes } from './auto-routes'
+
+export const router = createRouter(routes)
+
+// 类型契约透传（应用页面可直接 import type { PageOnLoad } from './router'，无需深路径）
+export type {
+  RouteRecord,
+  RouteMeta,
+  RouteParams,
+  RouteParamsByName,
+  PageOnLoad,
+  NavigateOptions,
+  RouterInstance,
+} from '@proteus-vue/router'

package/templates/src/shims/events.d.ts

@@ -0,0 +1,20 @@
+// src/shims/events.d.ts
+// 事件处理器类型（类型提示全链路步骤 4）—— 全局声明（无 export，页面/组件无需 import）
+// 微信事件对象：detail（自定义数据）/ currentTarget.dataset（元素自定义数据）
+// 用法：function onChange(e: MpInputEvent) { e.detail.value } / function onTap(e: TapEvent) { e.currentTarget.dataset.url }
+// 命名避开 DOM 内置类型（InputEvent/UIEvent 已存在）
+
+/** 通用微信事件（TDetail = 事件携带数据，如 input 的 { value: string }） */
+interface MpEvent<TDetail = unknown> {
+  type: string
+  detail: TDetail
+  target: { dataset: Record<string, string>; id?: string }
+  currentTarget: { dataset: Record<string, string>; id?: string }
+  timeStamp: number
+}
+
+/** input/textarea 输入事件（v-model handler 等）：e.detail.value: string */
+type MpInputEvent = MpEvent<{ value: string }>
+
+/** 点击事件（tap）：e.currentTarget.dataset 可读元素自定义数据 */
+type TapEvent = MpEvent<Record<string, never>>

package/templates/src/shims/mp.d.ts

@@ -0,0 +1,112 @@
+// src/shims/mp.d.ts
+// ============================================================
+// 微信小程序 API 类型声明垫片（minimal）
+//
+// 职责：
+// - 让 wx.* / Page() / App() / Component() 在小程序端代码中通过编译
+// - 提供 RouteBuilder / PageOptions 等类型，是 P3（router）、
+//   P4（编译产物）、P5（pageLifecycle）的类型依据，务必完整
+//
+// 注意：本文件无 import/export，保持全局声明（ambient）形态
+// ============================================================
+
+/** wx 全局对象（minimal：任何属性可用，仅供编译通过） */
+declare const wx: any
+
+/** Skyline wx.router 自定义路由上下文（官方 CustomRouteContext） */
+interface RouteContext {
+  /** 主转场动画进度 0→1（控制推入页面的进入/退出过渡） */
+  primaryAnimation: { value: number }
+  /** 主动画控制器状态：0=dismissed 1=forward 2=reverse 3=completed */
+  primaryAnimationStatus: { value: number }
+  /** 次转场动画进度 0→1（控制栈顶页面的压入/压出过渡） */
+  secondaryAnimation: { value: number }
+  /** 次动画控制器状态 */
+  secondaryAnimationStatus: { value: number }
+  /** 当前路由进度是否由手势控制 */
+  userGestureInProgress: { value: number }
+  /** 手势开始控制路由 */
+  startUserGesture: () => void
+  /** 手势不再控制路由 */
+  stopUserGesture: () => void
+  /** 返回上一级（效果同 wx.navigateBack） */
+  didPop: () => void
+}
+
+/** worklet 返回值（'worklet' 指令注释由编译器保留） */
+interface WorkletValue {
+  transform?: string
+  opacity?: number
+}
+
+/** routeBuilder 返回结构（wx.router.addRouteBuilder 的 builder 返回值，字段见官方 CustomRouteConfig） */
+interface RouteBuilderResult {
+  /** 是否不透明（false 时前一页可见，如半屏弹窗） */
+  opaque?: boolean
+  /** 是否保持前一个页面状态 */
+  maintainState?: boolean
+  /** 页面推入动画时长（ms） */
+  transitionDuration?: number
+  /** 页面推出动画时长（ms） */
+  reverseTransitionDuration?: number
+  /** 遮罩层背景色 rgba() / #RRGGBBAA */
+  barrierColor?: string
+  /** 点击遮罩层返回上一页 */
+  barrierDismissible?: boolean
+  /** 无障碍语义 */
+  barrierLabel?: string
+  /** 是否与下一个页面联动（决定当前页 secondaryAnimation 是否生效） */
+  canTransitionTo?: boolean
+  /** 是否与前一个页面联动（决定前一个页 secondaryAnimation 是否生效；false = 前页保持不动） */
+  canTransitionFrom?: boolean
+  handlePrimaryAnimation?: () => WorkletValue
+  handleSecondaryAnimation?: () => WorkletValue
+  /** 控制上一级页面的压入/压出动画（基础库 ≥3.0.0） */
+  handlePreviousPageAnimation?: () => WorkletValue
+  /** 页面进入时是否采用 snapshot 模式优化动画性能（基础库 ≥3.2.0） */
+  allowEnterRouteSnapshotting?: boolean
+  /** 页面退出时是否采用 snapshot 模式（基础库 ≥3.2.0） */
+  allowExitRouteSnapshotting?: boolean
+  /** 右滑返回可拖动范围是否撑满屏幕（基础库 ≥3.2.0，常用于半屏弹窗） */
+  fullscreenDrag?: boolean
+  /** 返回手势方向（基础库 ≥3.4.0） */
+  popGestureDirection?: 'horizontal' | 'vertical' | 'multi'
+}
+
+/** 自定义路由 builder（skyline.ts 注册到 wx.router） */
+type RouteBuilder = (ctx: RouteContext) => RouteBuilderResult
+
+/** 小程序 Page 构造器配置（pageLifecycle.createPage 的返回类型） */
+interface PageOptions {
+  data?: Record<string, unknown> | (() => Record<string, unknown>)
+  onLoad?: (options: Record<string, string>) => void
+  onReady?: () => void
+  onUnload?: () => void
+  [key: string]: unknown
+}
+
+/** 小程序 Component 构造器配置（pageLifecycle.createComponent 的返回类型） */
+interface ComponentOptions {
+  properties?: Record<string, unknown>
+  data?: Record<string, unknown> | (() => Record<string, unknown>)
+  methods?: Record<string, Function>
+  lifetimes?: {
+    attached?: () => void
+    detached?: () => void
+  }
+  [key: string]: unknown
+}
+
+declare function App(options: Record<string, unknown>): void
+declare function Page(options: PageOptions): void
+declare function Component(options: ComponentOptions): void
+
+/** Skyline worklet 渲染线程全局（仅 worklet 函数内可用） */
+declare const screenHeight: number
+declare const windowWidth: number
+
+/** 调试开关（PROTEUS_DEBUG=1 构建时由 vite define 注入为 true） */
+declare const __PROTEUS_DEBUG__: boolean
+
+/** Skyline 渲染开关（mp 构建时由 vite define 注入 proteus.config.skyline） */
+declare const __PROTEUS_SKYLINE__: boolean

package/templates/src/shims/vue.d.ts

@@ -0,0 +1,8 @@
+// src/shims/vue.d.ts
+// .vue 模块声明 —— 供 .ts 文件 import 组件（如 src/components/index.ts 聚合导出）
+// vue-tsc 对 .vue 文件内部 import .vue 原生支持；.ts 文件需要此声明
+declare module '*.vue' {
+  import type { DefineComponent } from 'vue'
+  const component: DefineComponent<Record<string, unknown>, Record<string, unknown>, unknown>
+  export default component
+}

package/templates/tsconfig.json

@@ -0,0 +1,31 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "jsx": "preserve",
+    "noEmit": true,
+    "isolatedModules": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "sourceMap": true,
+    "skipLibCheck": true,
+    "allowImportingTsExtensions": true,
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "types": ["vite/client", "./src/shims/mp.d.ts", "./src/shims/events.d.ts"],
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["src/*"]
+    }
+  },
+  "include": [
+    "src/**/*.ts",
+    "src/**/*.d.ts",
+    "src/**/*.vue",
+    "vite.config.ts",
+    "proteus.config.ts",
+    "scripts/**/*.ts"
+  ],
+  "exclude": ["node_modules", "dist"]
+}

package/templates/vite.config.ts

@@ -0,0 +1,55 @@
+// vite.config.ts —— Proteus 工程骨架（拆包步骤 7：插件来自 @proteus-vue/plugin-vite npm 包）
+import { defineConfig } from 'vite'
+import type { Plugin } from 'vite'
+import vue from '@vitejs/plugin-vue'
+import { fileURLToPath, URL } from 'node:url'
+import config from './proteus.config'
+import { mpTransform } from '@proteus-vue/plugin-vite'
+
+/** 处理 <route> 自定义块虚拟模块（?vue&type=route），保证 Web 构建不报错 */
+function routeBlocksPlugin(): Plugin {
+  return {
+    name: 'proteus-route-blocks',
+    enforce: 'pre',
+    transform(code, id) {
+      if (id.includes('?vue&type=route')) {
+        return { code: `export default ${code}`, map: null }
+      }
+      return null
+    },
+  }
+}
+
+export default defineConfig(({ mode }) => {
+  const platform = mode === 'mp-weixin' || mode === 'web' ? mode : config.platform
+  const isMp = platform === 'mp-weixin'
+
+  return {
+    define: {
+      __PROTEUS_DEBUG__: process.env.PROTEUS_DEBUG === '1',
+      // Skyline 开关注入：mp 构建时 __PROTEUS_SKYLINE__ = config.skyline（router/skyline 解耦 config）
+      __PROTEUS_SKYLINE__: isMp && config.skyline,
+    },
+    plugins: isMp
+      ? [
+          // 小程序端：独占编译管线（不用 plugin-vue），标准 Vue SFC → wxml/wxss/js
+          mpTransform({ config }),
+        ]
+      : [vue(), routeBlocksPlugin()],
+    resolve: {
+      alias: [
+        { find: '@', replacement: fileURLToPath(new URL('./src', import.meta.url)) },
+      ],
+    },
+    build: {
+      target: 'es2018',
+      cssCodeSplit: false,
+      minify: isMp ? false : undefined,
+      outDir: `dist/${platform}`,
+      emptyOutDir: !isMp,
+      rollupOptions: isMp
+        ? { input: 'scripts/mp-entry-stub.ts', output: { entryFileNames: 'mp-entry.js' } }
+        : undefined,
+    },
+  }
+})