apptify 0.5.0 → 0.5.1

package/README.md

@@ -1,49 +1,18 @@
 # Apptify
 
-面向桌面与移动端的个人 Vue 3 组件库。统一使用 `<apple-*>` 前缀，保留 Vuetify 的 Ripple 指令，而不继承它的整套 Material 组件外观。
+面向桌面与移动端的 Vue 3 组件库，采用 Apple 风格设计，统一使用 `<apple-*>` 标签。支持主题切换、减少动效、表单、图片预览与多层弹窗；支持 JavaScript、TypeScript 和 Options API。
 
-设计借鉴 Apple 网站的排版、留白、层次与交互节奏；不是 Apple 官方产品，也不声称全部控件都与 Apple 网站逐像素一致。表格、级联选择、验证码、下拉刷新等能力是在同一套视觉语言下的扩展。
+[npm](https://www.npmjs.com/package/apptify) · [组件 API](docs/COMPONENTS.md) · [应用模板](docs/PLAYGROUND-TEMPLATE.md)
 
-当前导出并注册 **66 个组件**：基础 9 个、表单 18 个、内容与移动交互 28 个、弹层 9 个、动效 2 个。其中 `AppleOverlayHost` 是由 Provider 自动挂载的基础设施，通常直接使用其余 65 个即可。完整实际 API 见 [组件参考](docs/COMPONENTS.md)。
-
-## 本地运行与安装
-
-项目尚未发布到 npm。不要把 `npm install apptify` 当成已发布包的安装方式。
-
-建议使用 Node.js 22 LTS 或 24 LTS；测试工具不支持奇数版本的 Node.js。
-
-在本仓库执行：
+## 安装
 
 ```sh
-npm ci
-npm run dev
+npm install apptify vue@^3.5 vuetify@^3.9
 ```
 
-开发服务器地址以终端输出为准。随包提供完整可编辑 playground 应用模板，导航、布局、登录、设置和404均可复用；删掉首页和组件总览即可开始自己的业务页面。见[模板交付说明](docs/PLAYGROUND-TEMPLATE.md)。
-
-在另一个项目中使用本地包：
-
-```sh
-# 在本仓库构建并生成 apptify-0.4.0.tgz
-npm run build
-npm pack
-
-# 在消费项目执行，将路径替换为实际包路径
-npm install /absolute/path/apptify/apptify-0.4.0.tgz
-npm install vue@^3.5 vuetify@^3.9
-```
-
-Vue 与 Vuetify 是 peer dependencies。图标使用 `lucide-vue-next`，桌面图片预览的缩放与手势使用 `@panzoom/panzoom`，手机端使用图片边界约束的 Pointer Events 手势。本库没有要求安装 Vuetify 插件或导入其完整样式，也不需要 `<v-app>`。
-
-## 复制完整应用模板
-
-安装本地 tgz 后执行 `npx --no-install apptify-playground ../my-app`，再在新目录执行 `npm install`、`npm run dev`。复制项目携带本地库归档与完整源码/资源，能独立安装、类型检查与构建。目标目录必须为空。
-
-完整步骤、删除示例页面后的导航与路由行为，以及本地打包验收见[模板交付说明](docs/PLAYGROUND-TEMPLATE.md)。组件库的常规接入方式保持可用。
+Vue 与 Vuetify 是 peer dependencies。Vuetify 仅用于 Ripple，无需安装其插件、导入完整样式或使用 `<v-app>`。
 
-## 接入应用
-
-JavaScript 和 TypeScript 项目都可直接使用。消费项目不需要 TypeScript、`tsconfig.json` 或 `<script setup>`；普通 `<script>` 与 Options API 是完整支持的用法。随包提供的类型声明也可以为 JavaScript 编辑器提供补全。
+## 快速接入
 
 ```js
 // src/main.js
@@ -52,30 +21,23 @@ import { createAppleUI } from 'apptify'
 import 'apptify/style.css'
 import App from './App.vue'
 
-const apple = createAppleUI({
-  theme: 'system',
-  motion: 'auto',
-  persist: true,
-  storageKey: 'my-app:appearance',
-})
-
-createApp(App).use(apple).mount('#app')
+createApp(App)
+  .use(createAppleUI({ theme: 'system', motion: 'auto', persist: true }))
+  .mount('#app')
 ```
 
 ```vue
 <!-- App.vue -->
 <template>
   <apple-provider>
-    <main>
-      <apple-container>
-        <apple-card title="个人资料" subtitle="保持联系。">
-          <apple-input v-model="name" label="姓名" autocomplete="name" />
-          <template #actions>
-            <apple-button @click="save">保存</apple-button>
-          </template>
-        </apple-card>
-      </apple-container>
-    </main>
+    <apple-container>
+      <apple-card title="个人资料">
+        <apple-input v-model="name" label="姓名" />
+        <template #actions>
+          <apple-button @click="save">保存</apple-button>
+        </template>
+      </apple-card>
+    </apple-container>
   </apple-provider>
 </template>
 
@@ -91,277 +53,43 @@ export default {
 </script>
 ```
 
-这是 Options API 用法。插件注册 PascalCase 名称，Vue 模板同时支持 `<AppleCard>` 和 `<apple-card>`。所有组件也可命名导入并局部注册。
-
-`AppleProvider` 应包住业务 UI。它应用主题变量、监听系统偏好、提供同主题的 Teleport 目标，并自动渲染 `AppleOverlayHost`。**不要在同一上下文再额外渲染一份 Host。** 根 Provider 不传属性时复用插件上下文；嵌套 Provider 或显式指定 `theme` / `motion` 的 Provider 会建立局部上下文。嵌套 Provider 未指定的主题与动效属性跟随父级更新。
-
-`this.$apple` 始终指向插件级上下文。局部 Provider 内的组件如需使用局部主题、通知或弹层，使用 Options API 注入：
-
-```js
-import { appleKey } from 'apptify'
-
-export default {
-  inject: { apple: { from: appleKey } },
-  methods: {
-    showMessage() {
-      this.apple.notify('使用当前 Provider 的通知')
-    },
-  },
-}
-```
-
-也导出 `useApple()` 供 Composition API 的 `setup()` 使用，但不需要为接入组件库重写现有 Options API 页面。
-
-## 自动路由（与 Vuetify 项目相同）
-
-采用 `vite-plugin-pages` + Vue Router 4，默认扫描 `src/views`。新页面自动生成路由，不需要维护 routes 数组；普通 JavaScript 和 Options API 页面同样适用。
-
-```sh
-npm install vue-router@^4.5
-npm install -D vite-plugin-pages@^0.32.4
-```
-
-```js
-// vite.config.js
-import { defineConfig } from 'vite'
-import vue from '@vitejs/plugin-vue'
-import apptifyRoutes from 'apptify/vite'
-
-export default defineConfig({
-  plugins: [apptifyRoutes(), vue()],
-})
-```
-
-```js
-// src/router/index.js
-import { createRouter, createWebHistory } from 'vue-router'
-import routes from 'virtual:generated-pages'
-
-export default createRouter({
-  history: createWebHistory(import.meta.env.BASE_URL),
-  routes,
-})
-```
-
-```js
-// src/main.js
-import { createApp } from 'vue'
-import { createAppleUI } from 'apptify'
-import 'apptify/style.css'
-import App from './App.vue'
-import router from './router'
-
-createApp(App).use(createAppleUI()).use(router).mount('#app')
-```
-
-```vue
-<!-- src/App.vue：全局主题和弹层跨页面保留 -->
-<template>
-  <apple-provider>
-    <router-view />
-  </apple-provider>
-</template>
-```
-
-| 页面文件 | 路由 |
-| --- | --- |
-| `src/views/index.vue` | `/` |
-| `src/views/about.vue` | `/about` |
-| `src/views/users/[id].vue` | `/users/:id` |
-| `src/views/[...all].vue` | 未匹配地址（404 页面） |
+`AppleProvider` 提供主题与弹层宿主，无需额外添加 `AppleOverlayHost`。插件全局注册组件，也支持命名导入并局部注册。嵌套 Provider 内可用 `appleKey` 注入局部上下文，或在 `setup()` 中使用 `useApple()`。
 
-页面内使用 `<router-link to="/about">关于</router-link>`，Options API 可通过 `this.$router.push('/about')` 跳转、通过 `this.$route.params.id` 读取参数。页面无需再包根 `apple-provider`。
-
-TypeScript 项目在 `src/vite-env.d.ts` 增加 `/// <reference types="vite-plugin-pages/client" />`。需要改扫描目录时传入 `apptifyRoutes({ dirs: [{ dir: 'src/pages', baseRoute: '' }] })`；支持其余 Pages 选项，包括排除文件和扩展路由。
-
-已经接入 `Pages()` 的项目继续使用现有配置即可，避免重复添加生成插件。`apptify/vite` 只负责构建时生成路由，浏览器组件入口不加载此插件。
-
-本仓库演示也使用同一套机制：`playground/App.vue` 放 Provider 与 RouterView，`playground/router/index.ts` 创建 Router，工作台页面位于 `playground/views/index.vue`。演示扫描目录设为 `playground/views`。
-
-使用 history 模式部署时，服务器需要将页面 URL 回退到 `index.html`，并保留 `/api` 和静态资源自己的处理规则；你的 Spring Boot 项目同样需要配置该回退。无法配置回退时，可改用 `createWebHashHistory(import.meta.env.BASE_URL)`。
-
-## 主题与动效
-
-共享响应式状态统一使用 `ref`：`theme`、`motion`、`overlays.entries` 和 `portalTarget`。在 JavaScript 中通过 `.value` 访问；嵌套访问（如 `$apple.theme.value.name`）也需显式使用 `.value`。
-
-内置主题为 `light`、`dark`、`graphite`、`rose`；`system` 表示跟随系统浅深色。主题即时生效，不需要刷新页面。设置 `persist: true` 才会保存主题名称、动效等级并同步其他标签页的同名存储设置；自定义主题定义应通过初始化 `themes` 配置或启动时的 `register()` 再次提供。
+## 常用 API
 
 ```js
 this.$apple.theme.value.set('dark')
-this.$apple.theme.value.register('forest', {
-  accent: '#237047',
-  'accent-text': '#ffffff',
-  bg: '#f4f7f5',
-  surface: '#ffffff',
-}, 'light')
-this.$apple.theme.value.set('forest')
 this.$apple.motion.value.set('reduced')
-```
-
-`register(name, tokens, scheme)` 自动补齐对应浅色或深色主题的默认 token。可覆盖 `bg`、`surface`、`surface-alt`、`text`、`secondary`、`border`、`accent`、`accent-text`、`danger`、`success`、`warning`、`shadow`、`radius`，对应 `--apple-*` CSS 变量。注册后先调用 `set()` 才会切换；`system` 是保留名称。
-
-| 动效值 | 行为 |
-| --- | --- |
-| `auto` | 自动遵循系统减少动态效果偏好。 |
-| `full` | 在全局策略与系统偏好允许时使用完整动效。 |
-| `reduced` | 减少位移、缩放和持续动态，保留必要状态反馈。 |
-| `none` | 关闭动效，包括按钮 Ripple。 |
-| `inherit` | 组件默认值，继承当前 Provider 的策略；不是全局配置值。 |
-
-全局 `none` / `reduced` 是动效上限，安全优先。组件可以再降低动效，但 `motion="full"` 不能越过全局限制或系统的减少动态效果偏好。支持 `motion` 的组件以 [API 表](docs/COMPONENTS.md) 为准；静态布局组件不需要动效属性。
-
-```vue
-<apple-card motion="none" zoom="none" title="静态内容" />
-<apple-button :ripple="false">仅关闭这个按钮的波纹</apple-button>
-```
-
-## Dialog 与反向通道
+this.$apple.notify('保存成功', { tone: 'success' })
 
-```js
-const dialog = this.$apple.dialog({
-  title: '删除文件？',
-  message: '此操作不能撤销。',
-  confirmText: '删除',
-  cancelText: '取消',
-  tone: 'danger',
-})
-
-const confirmed = await dialog.result
-// 默认确认返回 true，取消返回 false，关闭按钮 / Escape 返回 undefined。
-if (confirmed === true) this.$apple.notify('文件已删除', { tone: 'success' })
+const dialog = this.$apple.dialog({ title: '保存修改？', cancelText: '取消' })
+const confirmed = await dialog.result // 确认 true，取消 false，关闭 undefined
 ```
 
-每次调用创建独立层。`dialog` 句柄含 `id`、`close(value?)`、`update(patch)` 与 `result` Promise。`this.$apple.overlays.closeTop()` 只关闭最上面的非通知弹层；已有层不会被新层覆盖。声明式 `<apple-dialog v-model="opened">` 与命令式弹层共享焦点栈和滚动锁。
+内置主题：`light`、`dark`、`graphite`、`rose`；`system` 跟随系统。全局动效：`auto`、`full`、`reduced`、`none`。共享状态使用 ref，在 JavaScript 中通过 `.value` 访问。
 
-自定义弹层组件接收 `close`、`sendMessage` 两个 prop。下面的编辑组件通过反向通道请求父调用方保存，父调用方再打开第二层确认。
-
-```vue
-<!-- ProfileEditor.vue -->
-<template>
-  <apple-input v-model="name" label="姓名" />
-  <apple-button :loading="saving" @click="save">保存资料</apple-button>
-</template>
+Props、事件、插槽、自定义主题与弹层消息回传见[组件 API](docs/COMPONENTS.md)。
 
-<script>
-export default {
-  props: {
-    initialName: { type: String, default: '' },
-    close: { type: Function, required: true },
-    sendMessage: { type: Function, required: true },
-  },
-  data() { return { name: this.initialName, saving: false } },
-  methods: {
-    async save() {
-      this.saving = true
-      try {
-        const result = await this.sendMessage('profile:save', { name: this.name })
-        if (result?.saved) this.close(result)
-      } finally {
-        this.saving = false
-      }
-    },
-  },
-}
-</script>
-```
-
-```js
-import ProfileEditor from './ProfileEditor.vue'
-
-export default {
-  methods: {
-    async editProfile() {
-      const editor = this.$apple.dialog({
-        title: '编辑资料',
-        component: ProfileEditor,
-        props: { initialName: '小明' },
-        confirmText: '',
-        cancelText: '取消',
-        onMessage: async (channel, payload) => {
-          if (channel !== 'profile:save') return
-          const confirmation = this.$apple.dialog({
-            title: '保存修改？',
-            message: `将姓名更新为 ${payload.name}。`,
-          })
-          if (await confirmation.result !== true) return { saved: false }
-          // 在这里执行实际业务请求；该示例只返回结果。
-          return { saved: true, name: payload.name }
-        },
-      })
-      const result = await editor.result
-      if (result?.saved) this.$apple.notify('资料已保存', { tone: 'success' })
-    },
-  },
-}
-```
-
-通用消息总线也有真实的返回值通道，而不只是单向通知：
-
-```js
-const unsubscribe = this.$apple.onMessage('profile:read', () => ({ name: '小明' }))
-const responses = this.$apple.sendMessage('profile:read')
-console.log(responses[0].name)
-unsubscribe()
-```
-
-`sendMessage()` 同步调用监听器，返回所有监听器返回值组成的数组；异步监听器返回 Promise，可用 `Promise.all()` 等待。动态弹层的 `sendMessage()` 若有专属 `onMessage`，直接返回该回调结果；未设置时才回退到当前上下文消息总线。长期监听请在 `beforeUnmount` 中调用取消订阅函数。
-
-## 通知与图片
-
-```js
-const notice = this.$apple.notify('正在同步', { duration: 0 })
-notice.update({ message: '同步完成', tone: 'success', duration: 2500 })
-// 或 notice.close()
-```
-
-通知独立堆叠，默认 4 秒，`duration: 0` 常驻，悬停或键盘焦点进入时暂停倒计时。需要动作按钮时直接使用 `<apple-snackbar action="撤销" @action="undo" />`；命令式 `notify()` 当前没有 action 配置。
-
-```vue
-<apple-image
-  :gallery="[{ src: '/images/workspace.webp', alt: '桌面工作区' }, { src: '/images/detail.webp', alt: '工作区细节' }]"
-  v-model:index="imageIndex"
-  gallery-layout="compact"
-/>
+## 创建完整应用
 
+```sh
+npm create apptify@latest ./my-app
+cd my-app
+npm install
+npm run dev
 ```
 
-示例图片路径需要替换为业务资源。图片来源仅使用 `gallery`：单图可传 `{ src, alt }` 或单元素数组，多图传数组；不再接受顶层 `src`、`alt`。`index` 从 0 开始，默认 0，可用 `v-model:index` 控制；非有限值归零，越界值限制在有效范围，空项忽略，空列表显示占位且不打开预览。单图的小窗与全屏均不显示翻页箭头。`AppleImage` 默认支持点击预览，可用 `:preview="false"` 关闭。手机端的图片组支持 `gallery-layout="compact"`（固定框内横滑，默认）和 `gallery-layout="tiled"`（横向平铺，溢出时显示随主题变化的圆角滚动条，支持拖动、轨道点击及键盘操作），组内每张预览图都会渲染。省空间（compact）模式桌面触控板支持自由连续横滑，一次手势可跨越多张图片，垂直滚动仍交给页面；快速连续点击翻页会沿当前画面的位置和速度继续。点击小点跨多张时，直接在当前画面和目标图之间滑动一屏，不快速扫过中间图片；小点保持选中目标，连续改选从当前动画画面衔接。预览支持双指缩放与同时平移、双击放大或恢复、松手边界回弹、左右滑动切图、单击或下滑退出，顶部显示序号。手机单击等待 200ms 区分双击；双击围绕点击位置放大至 2 倍，再次双击恢复；拖动、双指操作、切图及关闭会取消等待中的单击。按钮、键盘和静止松手后的切图使用接近小窗横滑的先加速、后减速曲线，时长随移动距离调整；滑动松手仍以带初速度的阻尼曲线延续手势，快速轻扫也能翻页，翻页、缩放和边界回弹均可由下一次触摸接住；打开和关闭通过固定尺寸图片的 transform 与裁剪连接原图位置，避免逐帧修改布局尺寸；退出前同步横滑预览的位置，当前缩略图保持黑色占位直到落回。`AppleImage` 统一使用同一组件入口，根据 `navigator.maxTouchPoints` 或 `(any-pointer: coarse)` 判断触屏能力，不按屏幕宽度区分；触屏设备使用手势预览，非触屏设备保留缩放、拖动、旋转、左右按钮与键盘控制。双端共用图片专用的阻尼节奏：打开 360ms、关闭 300ms、双击缩放 300ms，翻页根据剩余距离与松手速度调整；这些时长独立于通用 UI 过渡。桌面端按钮缩放、双击缩放与旋转平滑过渡，拖动可接住缩放中的实际位置，滚轮仍直接跟随输入。减少动态效果时不执行大幅位移或缩放，关闭动效时立即更新。双端预览按钮均使用半透明背景、backdrop blur 和 200% 饱和度。
-
-## 移动端与边界
-
-- 弹层、抽屉、底部面板和通知考虑安全区；布局基于可用宽度，而不是把屏幕横竖方向等同于设备类型。
-- 提供下拉刷新、无限加载、侧滑操作、验证码、级联选择、ActionSheet 等组件，保留桌面按钮或键盘入口。
-- 日期、时间、颜色和基础 Select 使用浏览器原生选择能力；弹出界面随操作系统变化，不宣称它们在所有平台都长得完全一样。
-- Upload 负责本地文件选择、拖放与限制校验，不自动上传文件；Table 支持客户端排序、分页、固定行高虚拟滚动与列宽拖拽，不含服务端分页协议。
-- 导入阶段避免直接访问浏览器全局；这不等于已完成 SSR 全部组件的服务端渲染、hydration、跨请求隔离和主题首屏验证。SSR 接入时每个请求创建独立实例，并自行验证水合行为。
-- 本项目不是浏览器、屏幕阅读器和实体设备兼容矩阵认证。即使桌面/移动视口检查通过，也不代表已覆盖 iOS Safari、Android WebView、触控笔、软键盘与所有真机组合。
-
-## 从旧项目迁移
+也可运行 `npx --package=apptify apptify-playground ./my-app`。
 
-| 旧方式 | 新方式与差异 |
-| --- | --- |
-| `<apple-card title subtitle text icon icon-color>` | 保留这些属性与默认 slot，并增加 `media`、`title`、`icon`、`actions` slots。 |
-| `zoom="big/small/none"`、`shadow="normal/static/focused/none"` | 继续支持；新默认 `zoom="small"`，不保证旧尺寸和缩放数值完全一致。 |
-| `icon="mdi-home"` | 不再识别 MDI 字符串。导入 Lucide 组件并通过 `:icon="Home"` 传入；Card 的字符串 icon 被当作图片 URL。 |
-| `globalTheme` / `fancyAnimation` 模块常量 | 改用响应式 `theme.value.set()` / `motion.value.set()`；不需要刷新，也不要再直接读写旧 localStorage 键。 |
-| `sendMessage('showSnackbar', { type, text })` | 在 `this.$apple.sendMessage()` 或当前注入上下文上兼容；`showSnackBar`、`showMessage` 别名也保留。 |
-| `sendMessage('showDiag', { title, message })` | 仍可通过当前上下文发送；推荐使用返回独立句柄与 Promise 的 `dialog()`。 |
-| `btn: [{ bgColor, text, clickEvent }]` | **不直接兼容**。简单对话框用 `confirmText` / `cancelText`，复杂交互用声明式 `#footer` 或动态组件。 |
-| `sendMessage('closeDiag')` | 关闭当前上下文最上面的非通知弹层；不会一次关闭全部层。 |
-| `<e-img src squared gallery index>` | 改为 `<apple-image :gallery="{ src, alt }">`，描述放在图片对象内；不注册旧 `e-img` 名称。 |
+目标目录需为空。模板含导航、设置、账号表单、404 和组件示例，可直接编辑；账号功能需接入自己的后端。复制项目携带库归档，可独立安装。页面开发与部署见[应用模板](docs/PLAYGROUND-TEMPLATE.md)。
 
-## 验证命令
+## 本地开发
 
 ```sh
-npm run typecheck
-npm test
-npm run build
-npm run test:e2e
-npm run test:package
+npm ci
+npm run dev
 ```
 
-命令是否通过以当前执行结果为准。`build` 生成组件库 `dist/`、类型声明与工作台 `site/`。源码中的行为测试不代替消费项目的业务测试与真机验证。
-
-### 图片轮播
+建议 Node.js 22 或 24 LTS。检查使用 `npm run typecheck`、`npm test`、`npm run build`、`npm run test:e2e` 和 `npm run test:package`；`npm pack` 自动构建并准备模板。生成器位于 [`packages/create-apptify`](packages/create-apptify/README.md)，使用 `npm run test:create` 验证。历史验证记录见[验证文档](docs/VALIDATION.md)。
 
-轮播统一使用 `AppleImage` 的 `carousel` 属性、`gallery` 与 `v-model:index`，支持 `item` 插槽；独立 `AppleCarousel` 与 `AppleSwipeCell` 已移除。
+MIT 许可。Apptify 不是 Apple 官方产品。

package/docs/COMPONENTS.md

@@ -199,7 +199,7 @@ Modal slots：`title`、default `{close}`、footer `{close,confirm,cancel}`。
 
 `OverlayOptions` 实际字段为 `kind?`、`title?`、`message?`、`component?`、`props?`、`onMessage?`、`persistent?`、`confirmText?`、`cancelText?`、`tone?`、`duration?`。不要把声明式组件的 width、loading、action 等属性假定成当前服务参数；需要这些控制时使用声明式组件或自定义内容。
 
-返回的 `OverlayHandle<T>` 为 `{ id, close(value?), update(patch), result: Promise<T | undefined> }`。`props` 传给动态内容组件；宿主额外注入 `close` 和 `sendMessage`。`onMessage(channel,payload)` 可返回普通值或 Promise，实现双向请求与响应，示例见 [README](../README.md#dialog-与反向通道)。
+返回的 `OverlayHandle<T>` 为 `{ id, close(value?), update(patch), result: Promise<T | undefined> }`。`props` 传给动态内容组件；宿主额外注入 `close` 和 `sendMessage`。`onMessage(channel,payload)` 可返回普通值或 Promise，实现双向请求与响应。
 
 ## 验证边界
 

package/docs/PLAYGROUND-TEMPLATE.md

@@ -1,74 +1,51 @@
-# 完整 playground 应用模板
+# 应用模板
 
-apptify 包既提供组件库，也携带完整的可编辑应用模板。模板源码在包内 templates/playground/，包括导航与页面布局、账号菜单与登录/注册表单、主题/动效/玻璃设置、404 纸片故事、全部示例页面及图片资源。
+npm 包包含完整可编辑的 Vue 应用：导航、账号表单、主题/动效/玻璃设置、404、组件示例与图片资源。
 
-这些应用文件不增加组件库的公开 exports。复制出的项目通过 apptify 和 apptify/vite 使用已打包组件库，不能导入原仓库的 src。
+## 创建与运行
 
-## 从本地包创建应用
-
-当前尚未发布 npm。使用 Node.js 22 或 24 LTS，先在库仓库生成包：
-
-~~~sh
-npm ci
-npm pack --pack-destination /tmp
-~~~
-
-npm pack 会先执行构建与模板准备。将输出的实际 tgz 路径代入以下命令；在一个用于安装组件库的空目录执行：
-
-~~~sh
-npm init -y
-npm install /tmp/apptify-0.4.0.tgz
-npx --no-install apptify-playground ../my-app
-cd ../my-app
+```sh
+npm create apptify@latest ./my-app
+cd my-app
 npm install
-npm run typecheck
-npm run build
 npm run dev
-~~~
-
-复制命令要求目标目录不存在或为空，拒绝覆盖已有项目。复制过程不会自动安装项目依赖。
+```
 
-my-app/vendor/ 会携带组件库 tgz，应用依赖使用相对 file: 依赖。可以把整个 my-app 移动到另一目录或发给其他使用者；后续安装无需原仓库或用于调用命令的安装目录。运行与构建所需依赖全部声明在应用的 package.json。更新库时可把新 tgz 放入 vendor/ 并调整该相对依赖。
+也可运行 `npx --package=apptify apptify-playground ./my-app`。
 
-也可手工复制包内 templates/playground/，把 gitignore 重命名为 .gitignore，再将模板 package.json 中的 apptify 版本依赖改为本地 tgz；复制命令会自动完成这些步骤。仓库内 templates/playground 是打包时生成的目录，开发者应编辑 playground 源文件；使用者复制出的项目可以直接编辑。
+使用 Node.js 22 或 24 LTS。目标目录必须不存在或为空；复制命令不会安装依赖。
 
-## 开始业务开发
+项目的 `vendor/` 保存组件库 tgz，`package.json` 使用相对 `file:` 依赖，移动整个项目后仍可独立安装。改用 npm 更新库时，在新项目执行 `npm install apptify@latest`。
 
-可以只删除以下两页，然后编写自己的页面：
+## 开始开发
 
-~~~text
-playground/views/index.vue
-playground/views/components.vue
-~~~
-
-文件路由从 playground/views/ 自动生成，不存在对这两页的硬导入。删除后重启开发服务即可；模板导航自动隐藏不存在的页面，品牌链接回到第一个保留的导航项，404 的“返回首页”在没有首页时回到设置。
-
-新页面例如 playground/views/orders.vue 会得到 /orders 路由。将入口加入 playground/App.vue 的 navigation 数组即可出现在顶部导航。自己的 index.vue 仍对应首页。生产服务器需把 history 路由请求回退到 index.html。
+| 位置 | 用途 |
+| --- | --- |
+| `playground/App.vue` | 布局、导航项与账号入口 |
+| `playground/views/` | 页面与自动生成的路由 |
+| `playground/router/index.ts` | 滚动恢复、hash 定位与页面标题 |
+| `playground/components/UserMenu.vue` | 账号菜单与登录/注册表单 |
+| `playground/views/settings.vue` | 主题、动效与玻璃设置 |
+| `playground/views/[...all].vue` | 404 页面 |
+| `playground/style.css` | 应用样式 |
+| `public/images/` | 示例图片与来源说明 |
 
-删除组件总览后，ComponentDemo.vue、catalog.ts 和 components/ComponentIndex.vue 可以留着，也可按需删除；设置、账号、404 与布局不依赖它们。不需要清理库组件依赖或维护手写路由列表。
+可删除 `views/index.vue` 和 `views/components.vue`，再创建业务页面。删除后重启开发服务；导航会隐藏不存在的页面。删除组件总览后，可一并删除 `ComponentDemo.vue`、`catalog.ts` 和 `components/ComponentIndex.vue`。
 
-| 可编辑位置 | 用途 |
-| --- | --- |
-| playground/App.vue | 公共导航、品牌、账号入口和页面进入动效 |
-| playground/router/index.ts | 滚动恢复、hash 定位和页面标题 |
-| playground/components/UserMenu.vue | 账号菜单、登录/注册、邮箱验证码和忘记密码入口 |
-| playground/views/settings.vue | 外观、动效和玻璃偏好 |
-| playground/views/[...all].vue 与 components/not-found-paper-* | 404 页面与故事 |
-| playground/style.css | 应用布局与页面样式 |
-| public/images/ | 示例图片与来源说明 |
+例如 `playground/views/orders.vue` 自动对应 `/orders`；在 `App.vue` 的 `navigation` 数组添加入口即可显示导航。`index.vue` 对应首页。
 
-账户操作仍是 UI 演示，需要接入使用者自己的后端。图片来源说明随模板保留在 public/images/SOURCES.md。
+组件通过 `apptify` 导入，样式通过 `apptify/style.css` 导入；`apptify/vite` 提供文件路由插件。已有项目接入时需安装 `vue-router` 和 `vite-plugin-pages`，模板已配置这些依赖。
 
-## 本地交付验证
+账号表单需要接入自己的后端。部署使用 history 路由，服务器需将页面请求回退到 `index.html`，保留 API 与静态资源路由。图片来源说明位于 `public/images/SOURCES.md`。
 
-在库仓库执行：
+## 检查与本地打包
 
-~~~sh
-npm run test:package
-~~~
+复制出的应用使用 `npm run typecheck` 和 `npm run build` 检查。
 
-此检查会构建原库消费者、生成真实 npm tarball、检查每份 playground 源码和静态资源都在包内，并在临时空目录安装包后调用复制命令。随后删除最初的安装目录，独立安装、类型检查、构建和启动复制项目，实测导航、图片、设置、登录及 404；再删除首页、组件总览及其可选演示文件，重复类型检查、构建和浏览器验证。原库消费测试仍单独执行。
+库开发者编辑原仓库的 `playground/`，模板目录在打包时生成。`npm pack` 自动构建组件库并准备模板；本地安装生成的 tgz 后，也可运行 `npx --no-install apptify-playground ../my-app`。
 
-source-snapshot.json 记录本次复制前各源码与资源的 SHA-256。构建前后与验收末尾都会比对库、模板、资源及配置；若用户在打包中途编辑，检查要求重新取最新快照，不会回写或恢复旧源码。命令打印临时目录与验收 JSON 路径，失败时也保留该目录用于检查。
+`npm run test:package` 验证包内容、独立安装、模板复制、类型检查、构建与浏览器交互，并检查删除示例页面后的行为。命令输出临时目录与验收结果路径。验证指定归档：
 
-已生成的具体 tgz 也可直接复验：运行 node tooling/test-playground-package.mjs /absolute/path/apptify-0.4.0.tgz。验收结果记录该文件 SHA-256，避免并行构建替换了被验证对象。
+```sh
+node tooling/test-playground-package.mjs /absolute/path/apptify-<version>.tgz
+```

package/docs/VALIDATION.md

@@ -10,7 +10,7 @@
 - WebKit 390px、触屏/移动视口模拟验证了输入、叠层弹窗、滚动锁、图片加载与翻页以及系统减少动态效果。
 - `npm run test:package`：TypeScript 检查、展示站构建、ESM 库构建、声明生成，以及通过包名 `apptify` 和 `apptify/style.css` 导入的独立消费示例均通过。消费者使用纯 JavaScript Options API，不要求 TypeScript。
 - `npm audit`：本次锁文件检查为 0 项已知漏洞。此结果仅代表当时的软件漏洞数据库。
-- 未发布到 npm；旧 tgz 是整改前版本，当前源码需重新 `npm pack`。演示图片不进入组件库安装包。
+- 此节为 2026-09-26 的历史记录。当前包已发布；模板与示例图片随包分发，最新源码需重新 `npm pack`。
 
 ## 回归修复
 

package/package.json

@@ -1,7 +1,15 @@
 {
   "name": "apptify",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "description": "An Apple-inspired, responsive Vue 3 component library.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GARBAGELINUXGRAPHIC/apptify.git"
+  },
+  "homepage": "https://github.com/GARBAGELINUXGRAPHIC/apptify#readme",
+  "bugs": {
+    "url": "https://github.com/GARBAGELINUXGRAPHIC/apptify/issues"
+  },
   "type": "module",
   "license": "MIT",
   "files": [
@@ -34,6 +42,7 @@
     "test": "vitest run",
     "test:e2e": "playwright test",
     "test:package": "npm run prepack && vite build --config vite.consumer.config.ts && node tooling/test-playground-package.mjs",
+    "test:create": "node tooling/test-create-apptify.mjs",
     "preview": "vite preview --host 127.0.0.1",
     "prepare:playground": "node tooling/prepare-playground.mjs",
     "prepack": "node tooling/prepare-package.mjs"

package/templates/playground/README.md

@@ -1,17 +1,21 @@
-# Apptify 可编辑应用模板
+# Apptify 应用模板
 
-完整源码位于 playground/，静态图片与来源说明位于 public/images/。导航、账号/登录、设置、404 和页面动效均可直接编辑复用。
+可编辑的 Vue 应用，包含导航、账号表单、外观设置、404 与组件示例。建议 Node.js 22 或 24 LTS。
 
-通过 apptify-playground 复制命令创建时，vendor/ 包含本地组件库 tgz，package.json 使用相对 file: 依赖；移动整个项目后仍可独立安装。
+```sh
+npm install
+npm run dev
+```
 
-运行 npm install、npm run typecheck、npm run build；开发使用 npm run dev。请使用 Node.js 22 或 24 LTS。
+检查：`npm run typecheck`、`npm run build`。
 
-开始业务开发可直接删除 playground/views/index.vue 和 playground/views/components.vue，再添加自己的页面；文件路由自动生成，导航自动隐藏已删除页面，品牌链接回到第一个保留的导航页面。删除页面后重启开发服务。
+- 页面：`playground/views/`，文件路由自动生成。
+- 布局与导航：`playground/App.vue` 的 `navigation` 数组。
+- 账号表单：`playground/components/UserMenu.vue`，需要接入自己的后端。
+- 样式：`playground/style.css`；图片与来源：`public/images/`。
 
-导航项在 playground/App.vue 的 navigation 数组；页面文件在 playground/views/；布局和账号入口在 App.vue 与 playground/components/UserMenu.vue。
+可删除 `views/index.vue` 和 `views/components.vue`，再添加业务页面；删除后重启开发服务。删除组件总览后，可一并删除 `ComponentDemo.vue`、`catalog.ts` 和 `components/ComponentIndex.vue`。
 
-设置保留主题、动效与玻璃偏好。404 在 playground/views/[...all].vue；首页和组件总览没有被其他页面硬导入。ComponentDemo.vue、catalog.ts 和 ComponentIndex.vue 可以保留，也可在删除总览页后按需删除。
+复制命令在 `vendor/` 保存库归档，移动整个项目后仍可独立安装。使用 npm 更新库：`npm install apptify@latest`。手工复制模板时，将 `gitignore` 重命名为 `.gitignore`。
 
-登录、注册、忘记密码、邮箱验证码仍为 UI 演示入口，需要接入自己的后端。部署采用 history 路由，服务器应把未知页面路径回退到 index.html。
-
-若手工复制包内 templates/playground，先将 package.json 的 apptify 依赖替换为实际本地 tgz 路径，或安装自己的正式发布版本；当前项目尚未发布 npm。
+部署时将页面请求回退到 `index.html`，保留 API 与静态资源路由。

package/templates/playground/package.json

@@ -10,7 +10,7 @@
     "preview": "vite preview --host 127.0.0.1"
   },
   "dependencies": {
-    "apptify": "^0.5.0",
+    "apptify": "^0.5.1",
     "vue": "^3.5.0",
     "vue-router": "^4.6.4",
     "vuetify": "^3.9.0",

package/templates/playground/source-snapshot.json

@@ -1,6 +1,6 @@
 {
-  "createdAt": "2026-10-03T06:52:26.901Z",
-  "libraryVersion": "0.5.0",
+  "createdAt": "2026-10-03T07:22:12.858Z",
+  "libraryVersion": "0.5.1",
   "files": {
     "index.html": "75f6d93e3962ddca97a13b666a04d98ba9b263b6c288171383db764215034fea",
     "playground/App.vue": "ef3f06f80758a3d4198ee90eb05f766a89b6156b4899fd566f8dca9b42e0ffc9",
@@ -94,18 +94,18 @@
     "public/images/snow.jpg": "59fec6d2bbf9df11b7c697c57a253b7bd4b5a097489ce1017fb5209b9ee54b8e",
     "public/images/sunset.jpg": "4ee91e88f1e341143a807ef48fdfc24d63aa045d99351b4ea8ad7efcfef6ef9b",
     "public/images/waterfall.jpg": "cfd55ff5f41d3a58e91793d0e26a9ca90c86760aa401da033fbfa77d3364f238",
-    "docs/COMPONENTS.md": "ca4a01cefaddd3e45a1cfdaef3bc0474fa6a831de9802fcd4c27e0926da00a70",
-    "docs/PLAYGROUND-TEMPLATE.md": "b8a418d940cb99c53dd7f95c4f44da2682dbaf03201ec7eccfe7234b198f1408",
-    "docs/VALIDATION.md": "fb73cf9a3ae78c87093c89627ad6fdd9edc516b87aefd7244849d731283a1d0f",
-    "README.md": "0a4838e51c0d6bd2269411176ad4dbb89293ec77c332e9ed95b0f7f66f07ca9f",
-    "package.json": "856dd5ba89db5b5ebe685f711f1c1851eb4869ffea94f860b5918325428c0f7f",
+    "docs/COMPONENTS.md": "975f33ddb8584c0cb2a12066316018a02a7bfd73014a0a79d89d8990ca06f496",
+    "docs/PLAYGROUND-TEMPLATE.md": "26b15d5d9ca939d765aa93ce1389018f1aa4ce32de11c368556344b81c6b8b09",
+    "docs/VALIDATION.md": "3c1755f4699d6b7d8febb44b2b0b00eb416b86559c26d8b69e46a1c98271af5f",
+    "README.md": "7923e6dd7f06996af0ac8fcafafc9c338f5700969fd080a8af31a08df9514e58",
+    "package.json": "ceb8c42a9140d21fa2d4dd20528a85922be94d99ad739aeec83519b471092a86",
     "index.html": "75f6d93e3962ddca97a13b666a04d98ba9b263b6c288171383db764215034fea",
     "vite.config.ts": "df2eae92f81c9b9007549de5721a2311dd9b918dea45a4c7b8b4979f247e49ae",
     "vite.lib.config.ts": "f877c1772da70c9fed5174118ca36a0fc25fd46cce49b71280a5f91c4f8003a3",
     "tsconfig.json": "09590870bfbf6e90614d8a34af38b9a72902e8747ecd1a76be47ab24c842f9ea",
     "tsconfig.lib.json": "c885806b003cee01192cddcaf32df3e7c6d369e645360398aa088c14b1c4792f",
     "tooling/create-playground.mjs": "c45480c5982a64efd06f69dfb4620c65fd8ea35d01877b8574e7e2b30c095606",
-    "tooling/prepare-playground.mjs": "67e62e7e8bfd9a97f567474fe14e3776ce68166c97150c8d72509ba18efe4126",
+    "tooling/prepare-playground.mjs": "2e431ee93803d640f9b81fd8228a6b2edf0538e0eef8a8749f0622abf9f1a23e",
     "tooling/prepare-package.mjs": "cf57a112eec798412e2a68089d1b2d25b984600d6ffef99397ec253abf2fca57"
   }
 }

package/tooling/prepare-playground.mjs

@@ -77,14 +77,27 @@ await writeFile(join(output, 'vite.config.ts'), [
 // npm excludes .gitignore from tarballs; the copy command restores its dot.
 await writeFile(join(output, 'gitignore'), 'node_modules/\ndist/\n.env.local\n')
 await writeFile(join(output, 'README.md'), [
-  '# Apptify 可编辑应用模板', '',
-  '完整源码位于 playground/，静态图片与来源说明位于 public/images/。导航、账号/登录、设置、404 和页面动效均可直接编辑复用。', '',
-  '通过 apptify-playground 复制命令创建时，vendor/ 包含本地组件库 tgz，package.json 使用相对 file: 依赖；移动整个项目后仍可独立安装。', '',
-  '运行 npm install、npm run typecheck、npm run build；开发使用 npm run dev。请使用 Node.js 22 或 24 LTS。', '',
-  '开始业务开发可直接删除 playground/views/index.vue 和 playground/views/components.vue，再添加自己的页面；文件路由自动生成，导航自动隐藏已删除页面，品牌链接回到第一个保留的导航页面。删除页面后重启开发服务。', '',
-  '导航项在 playground/App.vue 的 navigation 数组；页面文件在 playground/views/；布局和账号入口在 App.vue 与 playground/components/UserMenu.vue。', '',
-  '设置保留主题、动效与玻璃偏好。404 在 playground/views/[...all].vue；首页和组件总览没有被其他页面硬导入。ComponentDemo.vue、catalog.ts 和 ComponentIndex.vue 可以保留，也可在删除总览页后按需删除。', '',
-  '登录、注册、忘记密码、邮箱验证码仍为 UI 演示入口，需要接入自己的后端。部署采用 history 路由，服务器应把未知页面路径回退到 index.html。', '',
-  '若手工复制包内 templates/playground，先将 package.json 的 apptify 依赖替换为实际本地 tgz 路径，或安装自己的正式发布版本；当前项目尚未发布 npm。', '',
+  "# Apptify 应用模板",
+  "",
+  "可编辑的 Vue 应用，包含导航、账号表单、外观设置、404 与组件示例。建议 Node.js 22 或 24 LTS。",
+  "",
+  "```sh",
+  "npm install",
+  "npm run dev",
+  "```",
+  "",
+  "检查：`npm run typecheck`、`npm run build`。",
+  "",
+  "- 页面：`playground/views/`，文件路由自动生成。",
+  "- 布局与导航：`playground/App.vue` 的 `navigation` 数组。",
+  "- 账号表单：`playground/components/UserMenu.vue`，需要接入自己的后端。",
+  "- 样式：`playground/style.css`；图片与来源：`public/images/`。",
+  "",
+  "可删除 `views/index.vue` 和 `views/components.vue`，再添加业务页面；删除后重启开发服务。删除组件总览后，可一并删除 `ComponentDemo.vue`、`catalog.ts` 和 `components/ComponentIndex.vue`。",
+  "",
+  "复制命令在 `vendor/` 保存库归档，移动整个项目后仍可独立安装。使用 npm 更新库：`npm install apptify@latest`。手工复制模板时，将 `gitignore` 重命名为 `.gitignore`。",
+  "",
+  "部署时将页面请求回退到 `index.html`，保留 API 与静态资源路由。",
+  "",
 ].join('\n'))
 console.log('Prepared editable playground template: ' + output)

package/tooling/test-create-apptify.mjs

@@ -0,0 +1,76 @@
+import assert from 'node:assert/strict'
+import { mkdir, mkdtemp, readFile, rm, symlink, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
+import { fileURLToPath } from 'node:url'
+import { execFileSync, spawnSync } from 'node:child_process'
+
+const root = fileURLToPath(new URL('../', import.meta.url))
+const scratch = await mkdtemp(join(tmpdir(), 'create-apptify-test-'))
+const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm'
+const env = { ...process.env, npm_config_cache: join(scratch, 'cache'), npm_config_offline: 'true' }
+const installer = join(scratch, 'installer')
+const creator = join(installer, 'node_modules/create-apptify')
+const library = join(installer, 'node_modules/apptify')
+const cli = join(creator, 'bin/create-apptify.mjs')
+
+async function unpack(cwd, destination) {
+  const packed = JSON.parse(execFileSync(npm, ['pack', '--ignore-scripts', '--json', '--pack-destination', scratch], { cwd, env, encoding: 'utf8' }))[0]
+  await mkdir(destination, { recursive: true })
+  execFileSync('tar', ['-xzf', join(scratch, packed.filename), '--strip-components=1', '-C', destination])
+  return packed
+}
+
+try {
+  // Use real tarballs in an installed layout, without fetching dependencies.
+  // The generator only reads/copies the library; it never imports its Vue code.
+  const packed = await unpack(join(root, 'packages/create-apptify'), creator)
+  const files = new Set(packed.files.map(file => file.path))
+  for (const path of ['package.json', 'bin/create-apptify.mjs', 'README.md', 'LICENSE']) assert(files.has(path), 'Missing creator file: ' + path)
+  await unpack(root, library)
+  await mkdir(join(installer, 'node_modules/.bin'))
+  await symlink('../create-apptify/bin/create-apptify.mjs', join(installer, 'node_modules/.bin/create-apptify'))
+  await writeFile(join(installer, 'package.json'), '{"private":true,"dependencies":{"create-apptify":"0.1.0"}}\n')
+
+  const run = args => spawnSync(process.execPath, [cli, ...args], { cwd: installer, env, encoding: 'utf8' })
+  const help = run(['--help'])
+  assert.equal(help.status, 0, help.stderr)
+  assert.match(help.stdout, /npm create apptify@latest/)
+  assert.equal(run([]).status, 1)
+  assert.equal(run(['--unknown']).status, 1)
+  assert.equal(run(['one', 'two']).status, 1)
+
+  const app = join(scratch, 'my app')
+  const result = spawnSync(npm, ['create', 'apptify', '--offline', '--', app], { cwd: installer, env, encoding: 'utf8', timeout: 60_000 })
+  assert.equal(result.status, 0, result.stdout + result.stderr)
+  const manifest = JSON.parse(await readFile(join(app, 'package.json'), 'utf8'))
+  assert.match(manifest.dependencies.apptify, /^file:\.\/vendor\/apptify-/)
+  assert.match(await readFile(join(app, '.gitignore'), 'utf8'), /node_modules/)
+  await readFile(join(app, 'playground/App.vue'))
+  const archive = join(app, manifest.dependencies.apptify.slice('file:./'.length))
+  const portableManifest = JSON.parse(execFileSync('tar', ['-xOf', archive, 'package/package.json'], { encoding: 'utf8' }))
+  assert.equal(portableManifest.name, 'apptify')
+
+  const before = await readFile(join(app, 'package.json'), 'utf8')
+  const refused = run([app])
+  assert.equal(refused.status, 1)
+  assert.match(refused.stderr, /Destination must be empty/)
+  assert.equal(await readFile(join(app, 'package.json'), 'utf8'), before)
+  assert.equal(run([join(library, 'unsafe')]).status, 1)
+  const alias = join(scratch, 'library-alias')
+  await symlink(library, alias, 'dir')
+  assert.equal(run([join(alias, 'unsafe')]).status, 1)
+
+  const empty = join(scratch, 'existing-empty')
+  await mkdir(empty)
+  const copied = run([empty])
+  assert.equal(copied.status, 0, copied.stderr)
+  await readFile(join(empty, 'playground/App.vue'))
+  await rm(installer, { recursive: true, force: true })
+  execFileSync('tar', ['-t', '-f', archive])
+  console.log('create-apptify: packed CLI, npm create, portable archive, help, argument validation and overwrite protection passed.')
+  await rm(scratch, { recursive: true, force: true })
+} catch (error) {
+  console.error('Acceptance workspace retained: ' + scratch)
+  throw error
+}