@composy/store-vue 0.0.1

package/README.md

@@ -0,0 +1,154 @@
+# @composy/store-vue
+
+`@composy/store-vue` 是 `packages/store` 的 Vue 3 适配层。
+
+它保留现有定位不变：
+
+- 基于 Pinia 提供 Vue 侧接入能力
+- 提供一组围绕 Store 的 composables
+- 提供持久化、注册表和调试相关插件能力
+- 同时支持原生 Vue Plugin 用法和 `@composy/engine-core` plugin 用法
+
+## 目录结构
+
+```text
+src/
+├─ composables/   # Vue 侧组合式 API
+├─ context/       # 注入 key
+├─ plugins/       # 对外公开的插件入口与兼容导出
+├─ runtime/       # 运行时、注册表、安装链
+├─ index.ts       # 包入口
+└─ types.ts       # Vue 侧公开类型
+```
+
+当前实现中，真正的安装与生命周期逻辑已经收敛到 `runtime/`：
+
+- `runtime/store-plugin-options.ts`
+  - 统一运行时配置和默认值
+- `runtime/store-registry.ts`
+  - 统一 Store 注册、查询、批量重置和运行时 API
+- `runtime/store-runtime.ts`
+  - 统一创建 Pinia、注册 registry、挂接 persist plugin
+- `runtime/install-store-app.ts`
+  - 统一把 runtime 安装到 Vue app，并处理 `provide`、`globalProperties` 和卸载清理
+
+`plugins/` 只保留明确职责的公开入口：
+
+- `vue-plugin.ts`
+  - 原生 Vue Plugin 入口
+- `engine-plugin.ts`
+  - `@composy/engine-core` plugin 入口，内部委托 `@composy/store-core/engine` 的 `createStoreEngineBridge()`
+- `pinia-plugin.ts`
+  - 持久化插件与控制器
+- `registry-plugin.ts`
+  - registry 能力导出
+- `enhanced-persist-plugin.ts`
+  - 旧子路径兼容导出
+
+## 推荐用法
+
+### 原生 Vue Plugin
+
+```ts
+import {
+  createStoreVuePlugin,
+  defineStore,
+} from '@composy/store-vue'
+import { createApp } from 'vue'
+import App from './App.vue'
+
+const app = createApp(App)
+
+app.use(createStoreVuePlugin({
+  persist: true,
+  persistOptions: {
+    keyPrefix: 'demo:',
+    syncTabs: true,
+  },
+}))
+
+app.mount('#app')
+
+export const useCounterStore = defineStore('counter', {
+  state: () => ({
+    count: 0,
+  }),
+})
+```
+
+### `@composy/engine-core` Plugin
+
+```ts
+import { createStoreEnginePlugin } from '@composy/store-vue'
+
+export const storePlugin = createStoreEnginePlugin({
+  name: 'store',
+  version: '1.0.0',
+  persist: true,
+  provide: true,
+  globalProperties: true,
+})
+```
+
+设计要点：
+
+- 如果 engine 已拿到 Vue app，插件会直接复用同一条 runtime 安装链。
+- 如果 app 还没创建，插件会先准备 runtime，再在 `app:created` 时接入。
+- 如果外部 app 已安装过 store runtime，engine plugin 会复用已有 runtime，而不是重复创建第二套 Pinia/registry。
+- engine state/API/container/events 的同步逻辑由 core bridge 统一处理，Vue 包只传入 `createStoreRuntime()`、`installStoreRuntime()` 和 Vue App 识别函数。
+
+## 持久化能力
+
+`createPersistPlugin()` 和 `createEnhancedPersistPlugin()` 现在共享同一套实现，统一支持：
+
+- `paths`
+- `excludePaths`
+- `debounce`
+- `syncTabs`
+- `ttl`
+- `serializer.serialize`
+- `serializer.deserialize`
+
+示例：
+
+```ts
+import { defineStore } from 'pinia'
+
+export const useUserStore = defineStore('user', {
+  state: () => ({
+    profile: null,
+    token: '',
+    session: {
+      lastSeenAt: 0,
+    },
+  }),
+  persist: {
+    paths: ['profile', 'token'],
+    excludePaths: ['session.lastSeenAt'],
+    syncTabs: true,
+    ttl: 1000 * 60 * 60 * 24,
+  },
+})
+```
+
+## 本轮整理结果
+
+- 原生 Vue Plugin 和 engine plugin 已统一复用同一条 runtime/install 链
+- engine plugin 已收口为 core bridge 的 Vue 薄封装，不再复制 engine state/API 生命周期逻辑
+- registry、persist、Pinia 安装和 app 卸载清理都集中在 `runtime/`
+- `plugins/` 目录不再承载重复 runtime 逻辑，只保留公开入口和兼容层
+- `useFormStore`、`useStoreDevtools`、`usePersistedState` 等 composable 的实现更清晰，避免继续堆叠历史写法
+- 持久化、Store registry 的 `$dispose` 补丁逻辑已支持重复挂载/运行时重建场景，避免残留旧清理回调
+
+## 开发校验
+
+当前包建议优先使用：
+
+```bash
+pnpm -C packages/store/packages/vue run lint:check
+pnpm -C packages/store/packages/vue run type-check
+pnpm -C packages/store/packages/vue run test:run
+pnpm -C packages/store/packages/vue run build
+```
+
+完整构建后必须同时存在 `dist`、`es`、`esm`、`lib` 四类产物目录。