apptify 0.2.0 → 0.5.0

package/docs/COMPONENTS.md

@@ -1,6 +1,6 @@
 # 组件 API 参考
 
-本页按 `src/index.ts` 合并的组件注册表列出当前 **68 个导出组件**，不是未来功能清单。组件名均可换成 kebab-case 模板标签，例如 `AppleOtpInput` 对应 `<apple-otp-input>`。
+本页按 `src/index.ts` 合并的组件注册表列出当前 **66 个导出组件**，不是未来功能清单。组件名均可换成 kebab-case 模板标签，例如 `AppleOtpInput` 对应 `<apple-otp-input>`。
 
 ## 公共约定
 
@@ -34,7 +34,7 @@ Tabs、TabBar、SegmentedControl、DatePicker 日期/时间页签均不使用 Ri
 | `AppleButton` | M；`variant=primary`（primary/secondary/outline/ghost/danger）、`size=medium`（small/medium/large）、`icon: Component`、`iconOnly`、`label`、`disabled`、`loading`、`ripple=true`、`href`、`type=button` | `click(event)`；default slot。纯图标按钮须提供 label。只有允许完整动效时启用 Ripple。 |
 | `AppleLink` | `href`、`external`、`disabled` | default slot；external 使用新窗口并设置 `noopener noreferrer`。 |
 | `AppleCard` | M；`title`、`subtitle`、`text`、`eyebrow`、`icon: Component 或图片 URL`、`iconColor`、`image`、`imageAlt`、`href`、`zoom=small`（big/small/none）、`shadow=normal`（normal/static/focused/none） | default、media、icon、title、actions slots；href 为标题链接，不会把所有嵌套控件变成一个大按钮。 |
-| `AppleImage` | M；必填 `src`、`alt`；`preview=true`、`gallery: string[]`、`index=0`、`squared`、`aspectRatio='4/3'`、`fit=cover`（cover/contain） | caption slot；默认点击预览；图片错误状态；squared 覆盖 aspectRatio。 |
+| `AppleImage` | M；`gallery: AppleImageItem | (string/AppleImageItem)[]`（唯一来源，默认空数组，单图可传对象）；`preview=true`、`carousel=false`、`disabled=false`、`label`、`galleryLayout=compact`（compact/tiled/tiled-wrap，所有设备）、`galleryShape=natural`（natural/square）、`index=0`、`squared`、`aspectRatio='4/3'`、`fit=cover`（cover/contain） | caption 与 item({item,index,active}) slots；carousel 强制 compact、常显控件且保留自由滚动；默认点击预览；统一入口，按触屏能力选择预览交互；完整渲染图片组，compact 在固定框内横滑，桌面触控板支持自由连续横滑、一次手势可跨越多张，快速点击翻页延续当前位置和速度；hover 不缩放，多图显示左右翻页按钮（单图小窗与全屏均无翻页箭头），跨多张点击小点时直接衔接当前画面与目标图并支持连续改选，tiled 等高横向平铺，溢出时底部常显自定义滚动条，支持拖动、点击轨道与键盘，滑块比例随内容和容器尺寸同步，tiled-wrap 等宽保留图片比例，按列从上往下紧密堆叠，避免按行对齐产生空白；平铺 hover 只缩放当前图片；galleryShape=square 强制 1:1 并居中裁剪（覆盖 fit），squared 同样作用于图片组；`update:index`、`change(index)`；图片错误状态；squared 覆盖 aspectRatio。 |
 | `AppleSearch` | `v-model: string`、`placeholder='搜索'`、`label='搜索'`、`disabled` | `search(value)` 在 Enter 时发出；清空更新 model。 |
 | `AppleContainer` | `width=1200`（number/string） | default slot；数字宽度按 px，宽度不会超过可用空间。 |
 | `AppleStack` | `direction=column`、`gap=16`、`align=stretch`、`wrap=true` | default slot；Flex 布局；数字 gap 按 px。 |
@@ -77,13 +77,16 @@ validator 返回 `true` 才通过；字符串作为错误信息，`false` 显示
 
 日期格式示例：`YYYY/MM`、`YYYY/MM/DD`、`YYYY/MM/DD HH:mm`、`YYYY/MM/DD HH:mm:ss`、`HH:mm`、`HH:mm:ss`。显示格式与模型格式分离：模型依次返回 `YYYY-MM`、`YYYY-MM-DD`、`YYYY-MM-DDTHH:mm[:ss]` 或 `HH:mm[:ss]`。独立 `AppleTimePicker` 已移除，纯时间使用 `<apple-date-picker format="HH:mm" />`；不支持原生 ISO week 模式及日期范围选择。
 
-## 内容与移动交互 · 29
+## 内容与移动交互 · 30
 
 以下组件均接受 M。
 
+导航组件默认协调同一文档中的图片预览；对话框内预览只协调该对话框内的导航。独立页面区域可用 `data-apple-navigation-scope` 容器隔离；多个预览都开始退出后恢复导航。关闭、取消和卸载均释放状态。
+
 | 组件 | 主要 Props | Events / Slots / 说明 |
 | --- | --- | --- |
-| `AppleNavibar` | `v-model: string/number`、`items: AppleItem[]`、`brand`、`brandHref='/'`、`label='主导航'`、`fixed=true`、`breakpoint=640` | `change(value,item)`、`toggle(open)`；brand、item `{item,active}`、actions `{close}` slots。固定模式自带占位；栏宽不超过 breakpoint 时折叠为三横杠菜单；选择、Escape、外部点击或焦点移出后收起。`fixed=false` 可嵌入容器。 |
+| `AppleNavibar` | `v-model: string/number`、`items: AppleItem[]`、`brand`、`brandHref='/'`、`label='主导航'`、`fixed=true`、`breakpoint=640`、`hideOnPreview`（默认跟随 fixed） | `change(value,item)`、`toggle(open)`；brand、item `{item,active}`、actions `{close}` slots。固定模式自带占位；栏宽不超过 breakpoint 时折叠为三横杠菜单；选择、Escape、外部点击或焦点移出后收起。`fixed=false` 可嵌入容器。参与预览时保留占位并隐藏，退出开始时与黑色背景淡出同步淡入。 |
+| `AppleAside` | M；`hideOnPreview=true` | 原生 aside 容器，布局由调用方提供；图片预览期间保留尺寸、隐藏并禁用交互，退出开始时 140ms 淡入。正常文档流侧栏可设 `hideOnPreview=false`。 |
 | `AppleTabs` | `v-model: string/number`、`items`、`label`、`disabled` | `change(value)`；`panel-${value}` slot `{item}` 或 default `{item,value}`；可非受控；方向键/Home/End。 |
 | `AppleTabBar` | 与 AppleTabs 相同 | 顶角圆角页签，移动选中背景与内容滑动。 |
 | `AppleBreadcrumbs` | `items`、`label='当前位置'` | `click(item,event)`；非最后项使用 item.href 或按钮；最后项为当前页文本；无下划线。 |
@@ -104,10 +107,8 @@ validator 返回 `true` 才通过；字符串作为错误信息，`false` 显示
 | `AppleDivider` | `label`、`vertical` | default slot；水平或垂直分隔语义。 |
 | `AppleSteps` | `v-model: number=0`、`items`、`clickable`、`disabled`、`label` | `change(index)`；模型是从 0 开始的步骤位置，不是 item.value。 |
 | `AppleTimeline` | `items: AppleTimelineItem[]`、`orientation=vertical`（horizontal/vertical）、`label` | item slot `{item}`；选项增加 `time?` 和 `tone?: default/success/danger`。 |
-| `AppleCarousel` | `items: AppleSlide[]`、`v-model: number`、`label`、`disabled` | `change(index)`；item slot `{item,index,active}`；选项增加 src/alt；滚动吸附与按钮/键盘，不自动播放。 |
 | `ApplePullRefresh` | `v-model: boolean`、`disabled`、`threshold=72`、`label` | `refresh(done)`；default slot `{refresh,refreshing}`；在滚动顶部下拉，也提供刷新按钮；完成必须调用 done 或将 model 设为 false。 |
 | `AppleInfiniteScroll` | `loading`、`error: boolean/string`、`finished`、`disabled`、`distance=120`、`finishedText` | `load(done)`、`retry(done)`；default slot；IntersectionObserver 及手动加载按钮；完成后调用 done，或令 loading 从 true 回到 false。 |
-| `AppleSwipeCell` | `v-model: boolean`、`disabled`、`label` | default、actions slot `{close}`；横向手势或操作按钮展开，Escape 关闭。 |
 | `AppleBackTop` | `target: CSS selector=''`、`threshold=300`、`label`、`disabled` | `click(event)`；default slot；空 target 使用 window，达到滚动阈值才显示。 |
 | `AppleFloatingGroup` | `backTop=true`、`threshold=300`、`target`、`label` | default slot 放附加操作，回顶按钮始终排最下；默认固定右下并考虑安全区。 |
 | `AppleMarquee` | `text`、`duration=24`、`paused`、`label` | default slot；duration 单位为秒；带暂停按钮；减少动态效果时停止连续滚动。 |
@@ -133,7 +134,7 @@ Table 另支持 `virtual=false`、`height=360`、`rowHeight=48`、`overscan=5`
 </apple-table>
 ```
 
-## 弹层组件 · 10
+## 弹层组件 · 9
 
 以下组件除 Host 外均接受 M。
 
@@ -143,12 +144,11 @@ Table 另支持 `virtual=false`、`height=360`、`rowHeight=48`、`overscan=5`
 | `AppleDrawer` | 同 Modal；`placement=right`（left/right）；`width=440` | 默认无 footer；全高侧边抽屉。 |
 | `AppleSheet` | 同 Modal；`width=440` | 默认无 footer；底部面板，移动端全宽；桌面样式最小设计宽度 540px，仍受可用宽度约束。 |
 | `AppleSnackbar` | `v-model: boolean=true`、`message`、`title`、`tone=default`（default/info/success/warning/danger/error）、`duration=4000`、`action`、`closable=true` | `close(value,reason)`、`action()`；default slot；duration 单位毫秒，0 常驻；直接使用时位置由业务布局决定。 |
-| `AppleOverlayHost` | 无公开配置 | 自动渲染当前上下文 overlays.entries；Provider 已包含，不要重复挂载。 |
+| `AppleOverlayHost` | 无公开配置 | 自动渲染当前上下文 overlays.entries.value；Provider 已包含，不要重复挂载。 |
 | `ApplePopover` | `v-model?: boolean`、`label='更多'`、`disabled`、`placement=bottom`（top/bottom/left/right）、`align=start`（start/center/end）、`width=280`、`role=dialog`、`openOnHover`、`trapFocus=true`、`panelClass` | `open()`、`close()`；activator `{props,open,close,isOpen}`、default `{close}`；支持非受控模式与屏幕边缘避让。 |
 | `AppleTooltip` | 必填 `text`；`placement=top`、`disabled` | default slot 为触发元素；悬停/焦点显示，Escape 关闭；短文本提示。 |
 | `AppleMenu` | `v-model?: boolean`、`label='操作'`、`items: AppleMenuItem[]`、`selected`、`disabled` | `select(value,item)`；activator slot 同 Popover、item slot `{item}`；选择后关闭，方向键/Home/End。 |
-| `AppleActionSheet` | `v-model: boolean`、`title`、`message`、`items: AppleMenuItem[]`、`cancelText='取消'` | `select(value,item)`、`close(value,reason)`；选择返回条目 value。 |
-| `AppleImageViewer` | `v-model: boolean`、`images: (string/AppleViewerImage)[]`、`v-model:index=0`、`loop` | `change(index)`、`close()`、`error(event)`；缩放与手势来自 @panzoom/panzoom，滚轮按实际滚动量连续缩放并保持鼠标焦点。 |
+| `AppleActionSheet` | `v-model: boolean`、`title`、`message`、`items: AppleMenuItem[]`、`cancelText='取消'` | `select(value,item)`、`close(value,reason)`；默认插槽支持自定义模板，提供 `select(item)`、`close(value)`，覆盖 items 内容；取消按钮保留。无拖拽指示条。 |
 
 Modal 公共属性：`title`、`message`、`ariaLabel='对话框'`、`persistent`、`loading`、`closeOnConfirm=true`、`confirmText='确定'`、`cancelText='取消'`、`showFooter`、`closable=true`、`width`、`tone=default`。Dialog 默认 width 为 480px。空按钮文本会隐藏对应按钮。
 
@@ -176,7 +176,7 @@ Modal slots：`title`、default `{close}`、footer `{close,confirm,cancel}`。
 
 `AppleMenuItem = { label; value: string|number; disabled?; danger?; description?; icon?: Component }`。
 
-`AppleViewerImage = { src: string; alt?: string; title?: string }`。数组字符串是 URL；需要可访问描述或标题时传对象。index 从 0 开始。
+`AppleViewerImage = { src: string; alt?: string; title?: string; width?: number; height?: number }` 仍是 `AppleImage` 可用的公共图片类型。图片数组字符串是 URL；需要可访问描述或标题时传对象。`AppleImageItem` 扩展该类型，`src` 可选以支持 carousel 的自定义内容，另有 `label`、`value`、`description`。顶层不接受 src/alt；index 从 0 开始、默认 0，支持 `v-model:index`，非有限值归零、越界值截取到有效范围。普通图片忽略无效空项；空列表显示占位且不打开预览。点击放大由 `AppleImage` 内部管理，不另行注册独立查看器。
 
 ## 上下文与服务
 
@@ -184,10 +184,12 @@ Modal slots：`title`、default `{close}`、footer `{close,confirm,cancel}`。
 
 | API | 作用 |
 | --- | --- |
-| `theme.set(name)` | 切换注册主题或 system。未知名称抛出错误。 |
-| `theme.register(name,tokens,scheme='light')` | 注册自定义主题并补齐基础 token。 |
-| `theme.name / resolved / current / themes` | 当前配置名、解析后名称、主题内容、主题注册表。 |
-| `motion.set(mode)` | 即时修改全局动效策略。 |
+| `theme.value.set(name)` | 切换注册主题或 system。未知名称抛出错误。 |
+| `theme.value.register(name,tokens,scheme='light')` | 注册自定义主题并补齐基础 token。 |
+| `theme.value.name / resolved / current / themes` | 当前配置名、解析后名称、主题内容、主题注册表。 |
+| `overlays.entries.value` | 当前弹层列表，`Ref<OverlayEntry[]>`。 |
+| `portalTarget.value` | 弹层挂载 DOM 元素。 |
+| `motion.value.set(mode)` | 即时修改全局动效策略。 |
 | `onMessage(channel,listener)` | 注册监听器，返回取消订阅函数。 |
 | `sendMessage(channel,payload?)` | 返回该 channel 全部监听器的返回值数组。 |
 | `dialog(options)` | 打开 dialog 并返回独立句柄。 |

package/docs/PLAYGROUND-TEMPLATE.md

@@ -0,0 +1,74 @@
+# 完整 playground 应用模板
+
+apptify 包既提供组件库，也携带完整的可编辑应用模板。模板源码在包内 templates/playground/，包括导航与页面布局、账号菜单与登录/注册表单、主题/动效/玻璃设置、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
+npm install
+npm run typecheck
+npm run build
+npm run dev
+~~~
+
+复制命令要求目标目录不存在或为空，拒绝覆盖已有项目。复制过程不会自动安装项目依赖。
+
+my-app/vendor/ 会携带组件库 tgz，应用依赖使用相对 file: 依赖。可以把整个 my-app 移动到另一目录或发给其他使用者；后续安装无需原仓库或用于调用命令的安装目录。运行与构建所需依赖全部声明在应用的 package.json。更新库时可把新 tgz 放入 vendor/ 并调整该相对依赖。
+
+也可手工复制包内 templates/playground/，把 gitignore 重命名为 .gitignore，再将模板 package.json 中的 apptify 版本依赖改为本地 tgz；复制命令会自动完成这些步骤。仓库内 templates/playground 是打包时生成的目录，开发者应编辑 playground 源文件；使用者复制出的项目可以直接编辑。
+
+## 开始业务开发
+
+可以只删除以下两页，然后编写自己的页面：
+
+~~~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。
+
+删除组件总览后，ComponentDemo.vue、catalog.ts 和 components/ComponentIndex.vue 可以留着，也可按需删除；设置、账号、404 与布局不依赖它们。不需要清理库组件依赖或维护手写路由列表。
+
+| 可编辑位置 | 用途 |
+| --- | --- |
+| 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/ | 示例图片与来源说明 |
+
+账户操作仍是 UI 演示，需要接入使用者自己的后端。图片来源说明随模板保留在 public/images/SOURCES.md。
+
+## 本地交付验证
+
+在库仓库执行：
+
+~~~sh
+npm run test:package
+~~~
+
+此检查会构建原库消费者、生成真实 npm tarball、检查每份 playground 源码和静态资源都在包内，并在临时空目录安装包后调用复制命令。随后删除最初的安装目录，独立安装、类型检查、构建和启动复制项目，实测导航、图片、设置、登录及 404；再删除首页、组件总览及其可选演示文件，重复类型检查、构建和浏览器验证。原库消费测试仍单独执行。
+
+source-snapshot.json 记录本次复制前各源码与资源的 SHA-256。构建前后与验收末尾都会比对库、模板、资源及配置；若用户在打包中途编辑，检查要求重新取最新快照，不会回写或恢复旧源码。命令打印临时目录与验收 JSON 路径，失败时也保留该目录用于检查。
+
+已生成的具体 tgz 也可直接复验：运行 node tooling/test-playground-package.mjs /absolute/path/apptify-0.4.0.tgz。验收结果记录该文件 SHA-256，避免并行构建替换了被验证对象。

package/docs/VALIDATION.md

@@ -34,3 +34,27 @@
 - 可变行高、服务端数据协议和所有大规模数据场景；Table 当前的虚拟滚动为固定行高，已验证 5000 行示例及原地追加数据。
 
 测试执行环境为 macOS、Node.js 23.11.0。构建与测试实际通过，但 Vitest 将奇数版本 Node 标记为非支持版本；日常开发和 CI 建议使用 Node.js 22 或 24 LTS。
+
+## 2026-10-01 手机图片预览
+
+- `npm test`：9 个文件、123 项单元测试通过。
+- 本轮相关浏览器回归：`gallery.spec.ts`、`overlays-redesign.spec.ts`、`mobile-images.spec.ts` 共 57 项通过，包含 Chrome 实际双指触摸输入和 WebKit 手机模拟；另增 1 项可控时钟检查通过，精确验证 199ms 第二击可放大、200ms 单击退出。
+- 新增检查覆盖双指同时缩放与平移、松手边界约束、上划不退出、下滑背景渐隐、单点退出、动画中途关闭、缩略图黑色占位切换、compact 两端定位、tiled/contain 比例、画布外图片回位、320px、横竖屏、减少动态效果与卸载清理。
+- 切图额外验证慢拖、快速轻扫、快速拖动的松手速度连续性；动画中途接住、取消下滑、从当前位置关闭；2/5 张循环首尾衔接。双端按钮检查模糊、200% 饱和度、半透明背景和按下态；手机控件淡入期间保留图片的 backdrop 采样范围。
+- 双击额外验证浏览器鼠标与实际触摸输入、点击焦点缩放和恢复、减少/关闭动效、缩放中途接住、第二次触摸长按或拖动、双指取消单击，以及叠层弹窗和立即关闭重开时的等待清理。回位动画在延迟关闭开始时捕获实际帧、黑色占位和滚动锁。
+- `npm run build` 与独立消费示例构建通过，包含 TypeScript 检查、ESM 包和类型声明生成。
+- 手机交互采用独立渲染分支；桌面图片缩放、旋转、方向按钮与键盘回归通过。未进行实体 iPhone 验证。
+
+## 2026-10-02 AppleImage 统一设备判断
+
+- AppleImage 使用统一入口，缩略图和预览共用触屏检测：`navigator.maxTouchPoints > 0` 或 `(any-pointer: coarse)`，不再根据窗口宽度选择交互。布局选项在所有设备上可用。
+- `foundation.test.ts`、`overlays.test.ts`、`image-device.test.ts`：40 项单元测试通过，包含混合输入设备、粗指针回退、无 matchMedia 和服务端环境。
+- 图片设备、手势和覆盖层回归 46 项通过；各尺寸总览及 WebKit 手机冒烟另 5 项通过。设备组合覆盖 390px/1440px、触屏/非触屏，并检查打开期间调整窗口及关闭重开。
+- `npm run build` 通过，包含类型检查、演示构建、组件库构建和类型声明。
+
+## 2026-10-02 共享状态统一使用 ref
+
+- 主题、主题注册表、动效、系统深色状态、弹层列表、挂载点和 Provider 上下文统一使用 `ref`；组件、演示与文档同步使用 `.value`。
+- 全量既有 127 项单元测试通过，另增 1 项共享 ref 身份与解构后响应更新检查通过。
+- 主题切换、系统动效、通知、嵌套弹窗及主题菜单共 5 项浏览器回归通过。
+- 生产构建及类型声明生成通过。

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "apptify",
-  "version": "0.2.0",
-  "description": "An Apple-inspired, responsive Vue 3 component library with Vuetify ripple.",
+  "version": "0.5.0",
+  "description": "An Apple-inspired, responsive Vue 3 component library.",
   "type": "module",
   "license": "MIT",
   "files": [
     "dist",
-    "docs"
+    "docs",
+    "tooling",
+    "templates/playground"
   ],
   "main": "./dist/apptify.js",
   "module": "./dist/apptify.js",
@@ -16,21 +18,28 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/apptify.js"
     },
-    "./style.css": "./dist/apptify.css"
+    "./style.css": "./dist/apptify.css",
+    "./vite": {
+      "types": "./tooling/vite.d.ts",
+      "import": "./tooling/vite.js"
+    }
   },
   "sideEffects": [
     "**/*.css"
   ],
   "scripts": {
-    "dev": "vite --host 127.0.0.1",
+    "dev": "vite",
     "build": "vue-tsc --noEmit && vite build && vite build --config vite.lib.config.ts && vue-tsc -p tsconfig.lib.json",
     "typecheck": "vue-tsc --noEmit",
     "test": "vitest run",
     "test:e2e": "playwright test",
-    "test:package": "npm run build && vite build --config vite.consumer.config.ts",
-    "preview": "vite preview --host 127.0.0.1"
+    "test:package": "npm run prepack && vite build --config vite.consumer.config.ts && node tooling/test-playground-package.mjs",
+    "preview": "vite preview --host 127.0.0.1",
+    "prepare:playground": "node tooling/prepare-playground.mjs",
+    "prepack": "node tooling/prepare-package.mjs"
   },
   "peerDependencies": {
+    "vite-plugin-pages": "^0.32.4",
     "vue": "^3.5.0",
     "vuetify": "^3.9.0"
   },
@@ -47,9 +56,19 @@
     "jsdom": "^26.0.0",
     "typescript": "^5.8.2",
     "vite": "^6.3.4",
+    "vite-plugin-pages": "^0.32.5",
     "vitest": "^4.1.11",
     "vue": "^3.5.13",
+    "vue-router": "^4.6.4",
     "vue-tsc": "^2.2.8",
     "vuetify": "^3.9.0"
+  },
+  "peerDependenciesMeta": {
+    "vite-plugin-pages": {
+      "optional": true
+    }
+  },
+  "bin": {
+    "apptify-playground": "./tooling/create-playground.mjs"
   }
 }

package/templates/playground/README.md

@@ -0,0 +1,17 @@
+# 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。

package/templates/playground/gitignore

@@ -0,0 +1,3 @@
+node_modules/
+dist/
+.env.local

package/templates/playground/index.html

@@ -0,0 +1,26 @@
+<!doctype html>
+<html lang="zh-CN">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <meta name="theme-color" content="#f5f5f7" />
+    <style>html, body { background-color: var(--app-page-bg, #f5f5f7); }</style>
+    <script>
+      // Apply the saved page canvas before the application bundle can paint.
+      try {
+        const preference = JSON.parse(localStorage.getItem('apptify:preferences') || '{}');
+        const dark = preference.theme === 'dark' || (preference.theme === 'system' && matchMedia('(prefers-color-scheme: dark)').matches);
+        const background = preference.theme === 'graphite' ? '#f3f4f4' : preference.theme === 'rose' ? '#faf7f8' : dark ? '#161617' : '#f5f5f7';
+        document.documentElement.style.setProperty('--app-page-bg', background);
+        document.documentElement.style.colorScheme = dark ? 'dark' : 'light';
+        document.querySelector('meta[name="theme-color"]').setAttribute('content', background);
+      } catch { /* Storage can be unavailable; the default canvas remains valid. */ }
+    </script>
+    <meta name="description" content="Apptify: Apple-inspired Vue 3 components. Built for every screen." />
+    <title>Apptify · 组件实验室</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/playground/main.ts"></script>
+  </body>
+</html>

package/templates/playground/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "apptify-app",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "typecheck": "vue-tsc --noEmit",
+    "build": "vue-tsc --noEmit && vite build",
+    "preview": "vite preview --host 127.0.0.1"
+  },
+  "dependencies": {
+    "apptify": "^0.5.0",
+    "vue": "^3.5.0",
+    "vue-router": "^4.6.4",
+    "vuetify": "^3.9.0",
+    "lucide-vue-next": "^0.468.0"
+  },
+  "devDependencies": {
+    "@vitejs/plugin-vue": "^5.2.3",
+    "typescript": "^5.8.2",
+    "vite": "^6.3.4",
+    "vite-plugin-pages": "^0.32.5",
+    "vue-tsc": "^2.2.8"
+  }
+}

package/templates/playground/playground/App.vue

@@ -0,0 +1,73 @@
+<template>
+  <apple-provider>
+    <apple-navibar class="site-nav" :model-value="$route.path" :items="navigation" @click.capture="navigate">
+      <template #brand>
+        <router-link class="brand" :to="homePath" aria-label="Apptify 首页"><span class="brand-symbol">a</span><span>Apptify</span></router-link>
+      </template>
+      <template #actions><UserMenu /></template>
+    </apple-navibar>
+    <router-view v-slot="{ Component, route }">
+      <div ref="routePage" class="route-page">
+        <component :is="Component" :key="route.path" />
+      </div>
+    </router-view>
+  </apple-provider>
+</template>
+
+<script setup lang="ts">
+import { onBeforeUnmount, onMounted, ref, watch } from 'vue'
+import { useRoute, useRouter } from 'vue-router'
+import { useApple } from 'apptify'
+import { animateEntrance } from 'apptify'
+import UserMenu from './components/UserMenu.vue'
+
+const router = useRouter()
+const route = useRoute()
+const apple = useApple()
+watch(() => [apple.theme.value.current.tokens.bg, apple.theme.value.current.scheme], ([background, scheme]) => {
+  document.documentElement.style.setProperty('--app-page-bg', background)
+  document.documentElement.style.colorScheme = scheme
+  document.querySelector('meta[name="theme-color"]')?.setAttribute('content', background)
+}, { immediate: true, flush: 'sync' })
+const routePage = ref<HTMLElement>()
+let entrances: Animation[] = []
+let entranceFrame = 0
+
+function cancelEntrance() {
+  cancelAnimationFrame(entranceFrame)
+  entrances.forEach(animation => animation.cancel())
+  entrances = []
+}
+function queueEntrance() {
+  cancelEntrance()
+  // Let the router restore the scroll position before animating the page.
+  // Animate the fixed sidebar itself so it shares the entrance without changing its containing block.
+  entranceFrame = requestAnimationFrame(() => {
+    const targets = [routePage.value?.querySelector<HTMLElement>('main'), routePage.value?.querySelector<HTMLElement>('.sidebar')]
+    targets.forEach((element, index) => {
+      if (!element) return
+      const animation = animateEntrance(element, index === 1 ? 'x' : 'y')
+      if (animation) entrances.push(animation)
+    })
+  })
+}
+watch(() => route.path, queueEntrance, { flush: 'post' })
+watch(() => [apple.motion.value.mode, apple.motion.value.reduced], () => {
+  if (apple.motion.value.reduced || ['none', 'reduced'].includes(apple.motion.value.mode)) cancelEntrance()
+})
+onMounted(queueEntrance)
+onBeforeUnmount(cancelEntrance)
+const navigation = [
+  { label: '首页', value: '/', href: '/' },
+  { label: '组件', value: '/components', href: '/components' },
+  { label: '设置', value: '/settings', href: '/settings' },
+].filter(item => router.getRoutes().some(page => page.path === item.href))
+const homePath = navigation[0]?.href ?? '/'
+
+function navigate(event: MouseEvent) {
+  const link = (event.target as HTMLElement).closest<HTMLAnchorElement>('a.apple-navibar__item')
+  if (!link || event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return
+  event.preventDefault()
+  void router.push(link.getAttribute('href')!)
+}
+</script>