vue-page-store 0.5.0 → 0.5.1

package/README.md

@@ -641,6 +641,103 @@ __VUE_PAGE_STORE__.registry.forEach(...)
 - `__VUE_PAGE_STORE__` 是 dev-only 调试接口，shape 和键名可能在后续版本变化，**不要在生产代码里依赖**
 - 微前端场景下，多个子应用都加载 vue-page-store 时，最后挂载的会覆盖前面的。如需共存，请退回手动挂载并用自己的命名
 
+### `window.PAGE_STORE_DEVTOOLS` —— debug 注册表 *(v0.5.1 新增)*
+
+v0.5.1 新增了 dev-only 的 debug 模块，在 `window.PAGE_STORE_DEVTOOLS` 上暴露结构化调试数据：
+
+```js
+window.PAGE_STORE_DEVTOOLS
+// {
+//   stores: Map,     ← store 元信息（id、active、destroyed、storeRef…）
+//   events: [],      ← 事件时间线（最近 500 条）
+//   seq: number      ← 全局递增计数
+// }
+```
+
+#### 自动采集的事件
+
+| 事件 | 说明 |
+|---|---|
+| `store:create` | store 实例创建 |
+| `store:destroy` | store 实例销毁 |
+| `action:start` | action 调用开始（含参数快照） |
+| `action:end` | action 调用结束（含 duration） |
+| `action:error` | action 抛错或 reject（含错误信息和 duration） |
+
+每条事件包含 `seq`（全局序号）、`ts`（时间戳）、`storeId`、`type`、`payload`。
+
+#### 控制台用法
+
+```js
+// 查看当前存活的 store
+PAGE_STORE_DEVTOOLS.stores
+
+// 查看最近的事件
+PAGE_STORE_DEVTOOLS.events.slice(-5)
+
+// 筛选某个 store 的 action 事件
+PAGE_STORE_DEVTOOLS.events
+  .filter(e => e.storeId === 'orderList' && e.type.startsWith('action:'))
+
+// 查看 action 耗时
+PAGE_STORE_DEVTOOLS.events
+  .filter(e => e.type === 'action:end')
+  .map(e => e.payload.action + ': ' + e.payload.duration + 'ms')
+```
+
+生产环境下 `PAGE_STORE_DEVTOOLS` 不会被挂载，所有 debug 逻辑为 no-op。
+
+### DevPanel —— 页面内悬浮面板 *(v0.5.1 新增)*
+
+v0.5.1 提供了一个最小的页面内调试面板，在右下角悬浮显示：
+
+- **左侧**：store 列表（显示 active / idle / destroyed 状态）
+- **右侧四个 tab**：
+  - `$state` — 当前选中 store 的业务状态
+  - `$source` — 页面输入 / 原始返回
+  - `getters` — 派生计算值
+  - `events` — 该 store 最近 50 条事件
+
+面板每 500ms 刷新一次，实时反映 store 变化。
+
+#### 接入方式
+
+```js
+// main.js — 仅开发环境加载
+if (process.env.NODE_ENV !== 'production') {
+  import('vue-page-store/debug/installPanel').then(m => m.installDevPanel())
+}
+```
+
+面板会自动挂载到 `document.body`，不侵入业务组件树。生产环境下 `installDevPanel()` 是 no-op。
+
+#### 注意事项
+
+- DevPanel 是独立 Vue 实例，不影响业务组件树
+- 需要构建链能处理 `.vue` SFC（webpack + vue-loader 或 Vite 默认支持）
+- 微前端场景下，多个子应用各自挂面板，互不干扰
+- 这是 dev-only 工具，不要在生产代码里依赖
+
+#### 强制开启
+
+Vite / webpack 5 等不 polyfill `process` 的环境下，如果 `isDev` 检测失败，可以在**页面加载前**手动设置：
+
+```js
+window.__VUE_PAGE_STORE_DEV__ = true
+```
+
+### debug 模块文件结构
+
+```
+src/debug/
+  ├── registry.js      ← window.PAGE_STORE_DEVTOOLS 数据层
+  ├── emit.js          ← emitDebugEvent 埋点入口
+  ├── DevPanel.vue     ← 悬浮面板组件
+  └── installPanel.js  ← 面板挂载器
+```
+
+所有 debug 文件仅在 dev 环境生效。生产构建中：`registry.js` 和 `emit.js` 中的所有函数早 return / 返回空值，不执行任何逻辑，不挂 `window`，不占内存。如果你的打包器支持 tree-shaking 且 `import('...installPanel')` 走动态导入，面板代码不会进入生产包。
+
 ## 从 v0.3.x 升级
 
 ### Breaking Changes
@@ -708,11 +805,23 @@ v0.5 **完全向后兼容** v0.4.x：
 
 升级只需要改版本号，无需改代码。
 
+## 从 v0.5.0 升级到 v0.5.1
+
+v0.5.1 **完全向后兼容** v0.5.0：
+
+- **修复**：`isDev` 检测改用 `try/catch` 兜底，修复 Vite / webpack 5 不 polyfill `process` 时模块加载报错的问题
+- **新增**：dev-only debug 模块（`debug/registry.js`、`debug/emit.js`、`debug/DevPanel.vue`、`debug/installPanel.js`）
+- **新增**：`window.PAGE_STORE_DEVTOOLS` 调试注册表，自动采集 store 创建/销毁和 action 调用事件
+- **新增**：DevPanel 悬浮面板，可视化查看 store 列表、state/source/getters、事件时间线
+
+升级只需要改版本号。debug 模块为可选接入，不接入等同于 v0.5.0 行为。
+
 ## Roadmap
 
 - **Keyed instance** — `useStore(vm, scopeKey)` 支持同定义多实例
 - **Official plugins** — 随着 `vue-page-runtime` 等生态库成熟，补充第一方 plugin 文档
 - **More page runtime helpers** — 在不增加心智负担的前提下继续补页面层能力
+- **Vue Devtools 集成** — 在 debug 模块基础上对接 Vue Devtools inspector / timeline API
 
 ## License
 

package/dist/index.cjs.js

@@ -1,5 +1,5 @@
 /*!
- * vue-page-store v0.5.0
+ * vue-page-store v0.5.1
  * (c) 2026 weijianjun
  * @license MIT
  */
@@ -9,13 +9,221 @@ Object.defineProperty(exports, '__esModule', { value: true });
 
 var Vue = require('vue');
 
+/**
+ * vue-page-store debug / registry
+ *
+ * 纯 JS 数据层：不依赖 Vue，不涉及 UI。
+ *
+ * 对外：
+ *   window.PAGE_STORE_DEVTOOLS = { stores: Map, events: [], seq: number }
+ *
+ * API：
+ *   nextId()                 — 递增并返回 seq
+ *   addStore(meta)           — stores.set(meta.id, meta)
+ *   updateStore(id, patch)   — 浅合并进已有 meta
+ *   removeStore(id)          — stores.delete(id)
+ *   addEvent(event)          — events.push + 环形裁剪
+ *   getStores()              — 返回 Map（生产返回空 Map）
+ *   getEvents()              — 返回数组（生产返回空数组）
+ *
+ * 仅开发环境生效。生产环境下 ensure() 返回 null，
+ * 所有写 API 静默 no-op，不挂 window，不占内存。
+ */
+
+var MAX_EVENTS = 500;
+
+// ---- isDev：稳健检测 ----
+// webpack 4 / 旧 CRA 有 process；Vite / webpack 5 不 polyfill process 的情况用 try/catch 兜住。
+// 额外允许 window.__VUE_PAGE_STORE_DEV__ = true 强制开启（staging 临开调试面板用）。
+var _isDev = false;
+try {
+  if (typeof process !== 'undefined'
+      && process.env
+      && process.env.NODE_ENV !== 'production') {
+    _isDev = true;
+  }
+} catch (e) { /* no process polyfill */ }
+try {
+  if (typeof window !== 'undefined' && window.__VUE_PAGE_STORE_DEV__ === true) {
+    _isDev = true;
+  }
+} catch (e) { /* SSR */ }
+
+var isDev$1 = _isDev;
+
+// ---- 单例 ----
+var _devtools = null;
+
+function ensure() {
+  if (!isDev$1) return null;
+  if (_devtools) return _devtools;
+
+  _devtools = {
+    stores: new Map(),
+    events: [],
+    seq: 0,
+  };
+
+  if (typeof window !== 'undefined') {
+    try { window.PAGE_STORE_DEVTOOLS = _devtools; } catch (e) { /* locked window */ }
+  }
+
+  return _devtools;
+}
+
+// ---- API ----
+
+function nextId() {
+  var dt = ensure();
+  if (!dt) return 0;
+  dt.seq++;
+  return dt.seq;
+}
+
+function addStore(meta) {
+  var dt = ensure();
+  if (!dt) return;
+  if (!meta || !meta.id) return;
+  dt.stores.set(meta.id, meta);
+}
+
+function updateStore(id, patch) {
+  var dt = ensure();
+  if (!dt) return;
+  if (!id || !patch) return;
+  var m = dt.stores.get(id);
+  if (!m) return;
+  for (var k in patch) {
+    if (Object.prototype.hasOwnProperty.call(patch, k)) {
+      m[k] = patch[k];
+    }
+  }
+}
+
+function addEvent(event) {
+  var dt = ensure();
+  if (!dt) return;
+  if (!event) return;
+  dt.events.push(event);
+  // 环形裁剪，防止长时间开发内存无限增长
+  var overflow = dt.events.length - MAX_EVENTS;
+  if (overflow > 0) dt.events.splice(0, overflow);
+}
+
+/**
+ * vue-page-store debug / emit
+ *
+ * 唯一对外高层入口：
+ *   emitDebugEvent(store, type, payload)
+ *
+ * 职责：
+ *   1. 把一次领域调用写入 events 时间线（带 seq + ts）
+ *   2. 对特定 type 顺带同步 stores meta（create / destroy / lifecycle）
+ *   3. payload 做序列化快照，避免后续持有活引用
+ *   4. 仅 dev 生效；任何异常一律吞掉，绝不拖累业务
+ *
+ * 支持的 type：
+ *   store:create       payload = { name? }        → addStore(meta)
+ *   store:destroy      payload = undefined        → updateStore(id, { destroyed: true, active: false })
+ *   lifecycle:init     payload = undefined        → updateStore(id, { route })
+ *   lifecycle:enter    payload = undefined        → updateStore(id, { active: true, route })
+ *   lifecycle:leave    payload = undefined        → updateStore(id, { active: false })
+ *   action:start       payload = { action, args } → 仅写事件
+ *   action:end         payload = { action, duration } → 仅写事件
+ *   action:error       payload = { action, duration, error } → 仅写事件
+ *   state:set          payload = { key, value }   → 仅写事件
+ *   state:patch        payload = { patch }        → 仅写事件
+ */
+
+
+// ---- helpers ----
+
+function readRoute(store) {
+  try {
+    var vm = store && store.$vm;
+    if (vm && vm.$route) {
+      return {
+        path: vm.$route.path,
+        fullPath: vm.$route.fullPath,
+        name: vm.$route.name,
+      };
+    }
+  } catch (e) { /* ignore */ }
+  return null;
+}
+
+function snapshot(v) {
+  if (v === undefined) return undefined;
+  if (v === null) return null;
+  var t = typeof v;
+  if (t === 'function') return '[Function]';
+  if (t !== 'object') return v;
+  try {
+    return JSON.parse(JSON.stringify(v));
+  } catch (e) {
+    return '[Unserializable]';
+  }
+}
+
+// ---- 主入口 ----
+
+function emitDebugEvent(store, type, payload) {
+  if (!isDev$1) return null;
+
+  try {
+    var id = store && store.$id;
+
+    // 必要的 meta 同步
+    switch (type) {
+      case 'store:create':
+        addStore({
+          id: id,
+          name: (payload && payload.name) || id,
+          route: readRoute(store),
+          createdAt: Date.now(),
+          active: false,
+          destroyed: false,
+          keepAlive: false,
+          storeRef: store,
+        });
+        break;
+      case 'store:destroy':
+        updateStore(id, { destroyed: true, active: false });
+        break;
+      case 'lifecycle:init':
+        updateStore(id, { route: readRoute(store) });
+        break;
+      case 'lifecycle:enter':
+        updateStore(id, { active: true, route: readRoute(store) });
+        break;
+      case 'lifecycle:leave':
+        updateStore(id, { active: false });
+        break;
+      default:
+        break;
+    }
+
+    var event = {
+      seq: nextId(),
+      ts: Date.now(),
+      storeId: id,
+      type: type,
+      payload: snapshot(payload),
+    };
+    addEvent(event);
+    return event;
+  } catch (e) {
+    return null;
+  }
+}
+
 /*!
- * vue-page-store v0.5.0
+ * vue-page-store v0.5.1
  * (c) 2026 weijianjun
  * @license MIT
  */
 /**
- * vue-page-store 0.5.0 — Vue 2.6 Page Scope Runtime
+ * vue-page-store 0.5.1 — Vue 2.6 Page Scope Runtime
  *
  * 页面级作用域运行时容器：
  * source · state · getters · actions · watch · init/enter/leave · $setInterval · event bus · plugin
@@ -32,15 +240,25 @@ var Vue = require('vue');
  * v0.5 新增：
  *   plugin     → registerPlugin 注册外部扩展，声明字段 + 生命周期钩子
  *
+ * v0.5.1 修复/新增：
+ *   isDev      → try/catch 兜底，修复 Vite / webpack 5 不 polyfill process 时报错
+ *   debug      → dev-only 调试工具：store 创建/销毁追踪、action 埋点、DevPanel
+ *
  * @author weijianjun
  * @license MIT
  */
 
 
 // ====== dev-only warning ======
-var isDev = typeof process !== 'undefined'
-  && process.env
-  && process.env.NODE_ENV !== 'production';
+// v0.5.1 修复：try/catch 兜底，Vite / webpack 5 不 polyfill process 时不再报错
+var isDev = false;
+try {
+  isDev = typeof process !== 'undefined'
+    && process.env
+    && process.env.NODE_ENV !== 'production';
+} catch (e) {
+  // Vite / webpack 5 等环境下 process 未定义或 process.env 被 getter 拦截
+}
 
 function warn(msg) {
   if (isDev) {
@@ -48,6 +266,54 @@ function warn(msg) {
   }
 }
 
+// ====== debug: wrapAction helper ======
+function _now() {
+  return typeof performance !== 'undefined' && performance.now
+    ? performance.now()
+    : Date.now();
+}
+function wrapAction(store, name, boundFn) {
+  return function () {
+    var args = Array.prototype.slice.call(arguments);
+    var t0 = _now();
+    emitDebugEvent(store, 'action:start', { action: name, args: args });
+    var result;
+    try {
+      result = boundFn.apply(null, args);
+    } catch (syncErr) {
+      emitDebugEvent(store, 'action:error', {
+        action: name,
+        duration: +(_now() - t0).toFixed(2),
+        error: (syncErr && syncErr.message) || String(syncErr),
+      });
+      throw syncErr;
+    }
+    if (result && typeof result.then === 'function') {
+      Promise.resolve(result).then(
+        function () {
+          emitDebugEvent(store, 'action:end', {
+            action: name,
+            duration: +(_now() - t0).toFixed(2),
+          });
+        },
+        function (err) {
+          emitDebugEvent(store, 'action:error', {
+            action: name,
+            duration: +(_now() - t0).toFixed(2),
+            error: (err && err.message) || String(err),
+          });
+        },
+      );
+    } else {
+      emitDebugEvent(store, 'action:end', {
+        action: name,
+        duration: +(_now() - t0).toFixed(2),
+      });
+    }
+    return result;
+  };
+}
+
 // Store 注册表（导出供调试 / devtools 使用）
 var storeRegistry = new Map();
 
@@ -57,7 +323,9 @@ if (isDev && typeof window !== 'undefined') {
     registry: storeRegistry,
     get stores() {
       var result = {};
-      storeRegistry.forEach(function (s, id) { result[id] = s; });
+      storeRegistry.forEach(function (s, id) {
+        result[id] = s;
+      });
       return result;
     },
   };
@@ -80,9 +348,15 @@ function registerPlugin(plugin) {
     throw new Error('[vue-page-store] plugin 需要一个 name 属性');
   }
   if (typeof plugin.install !== 'function') {
-    throw new Error('[vue-page-store] plugin "' + plugin.name + '" 需要一个 install 方法');
+    throw new Error(
+      '[vue-page-store] plugin "' + plugin.name + '" 需要一个 install 方法',
+    );
   }
-  if (_plugins.some(function (p) { return p.name === plugin.name; })) {
+  if (
+    _plugins.some(function (p) {
+      return p.name === plugin.name;
+    })
+  ) {
     warn('plugin "' + plugin.name + '" 已注册，跳过重复注册');
     return;
   }
@@ -93,7 +367,8 @@ function createStoreInstance(Vue, id, options) {
   var initialState = options.state();
 
   // ====== v0.4 新增：source ======
-  var initialSource = (typeof options.source === 'function') ? options.source() : {};
+  var initialSource =
+    typeof options.source === 'function' ? options.source() : {};
 
   var getters = options.getters || {};
   var actions = options.actions || {};
@@ -119,19 +394,19 @@ function createStoreInstance(Vue, id, options) {
     data: function () {
       return {
         $$state: initialState,
-        $$source: initialSource,     // v0.4 新增
-        $$loading: {},               // v0.4 新增
+        $$source: initialSource, // v0.4 新增
+        $$loading: {}, // v0.4 新增
         $$status: {
           mounted: false,
-          active: false
-        }
+          active: false,
+        },
       };
     },
     computed: computedDefs,
   });
 
   var rawState = vm.$data.$$state;
-  var rawSource = vm.$data.$$source;   // v0.4 新增
+  var rawSource = vm.$data.$$source; // v0.4 新增
   var rawLoading = vm.$data.$$loading; // v0.4 新增
   var rawStatus = vm.$data.$$status;
 
@@ -140,7 +415,9 @@ function createStoreInstance(Vue, id, options) {
     Object.defineProperty(store, key, {
       enumerable: true,
       configurable: true,
-      get: function () { return rawState[key]; },
+      get: function () {
+        return rawState[key];
+      },
       set: function (val) {
         if (store.$disposed) {
           warn('store "' + id + '" 已销毁，忽略对 "' + key + '" 的写入');
@@ -161,12 +438,14 @@ function createStoreInstance(Vue, id, options) {
   Object.keys(getters).forEach(function (key) {
     Object.defineProperty(store, key, {
       enumerable: true,
-      get: function () { return vm[key]; },
+      get: function () {
+        return vm[key];
+      },
     });
   });
 
   // ====== actions —— v0.4 变更：自动增强 async action ======
-  var _loadingCounts = {};  // 并发计数器，防止先返回的 finally 提前关 loading
+  var _loadingCounts = {}; // 并发计数器，防止先返回的 finally 提前关 loading
 
   function finishLoading(key) {
     _loadingCounts[key]--;
@@ -180,7 +459,7 @@ function createStoreInstance(Vue, id, options) {
     var originalFn = actions[key];
     var boundFn = originalFn.bind(store);
 
-    store[key] = function () {
+    var withLoading = function () {
       var result = boundFn.apply(null, arguments);
 
       // 检测是否返回 Promise，如果是则自动追踪 loading
@@ -191,13 +470,20 @@ function createStoreInstance(Vue, id, options) {
 
         var tracked = Promise.resolve(result);
         tracked.then(
-          function () { finishLoading(key); },
-          function () { finishLoading(key); }
+          function () {
+            finishLoading(key);
+          },
+          function () {
+            finishLoading(key);
+          },
         );
       }
 
       return result;
     };
+
+    // v0.5.1：debug 包装套在 $loading 追踪外层
+    store[key] = wrapAction(store, key, withLoading);
   });
 
   // ====== watch —— 声明式副作用，生命周期自动回收 ======
@@ -219,14 +505,20 @@ function createStoreInstance(Vue, id, options) {
 
       if (!handler) {
         warn(
-          'watch "' + path + '" in store "' + id + '" 缺少 handler，该 watcher 将被跳过'
+          'watch "' +
+            path +
+            '" in store "' +
+            id +
+            '" 缺少 handler，该 watcher 将被跳过',
         );
         return;
       }
     }
 
     var expr = function () {
-      return path.split('.').reduce(function (obj, k) { return obj && obj[k]; }, store);
+      return path.split('.').reduce(function (obj, k) {
+        return obj && obj[k];
+      }, store);
     };
     vm.$watch(expr, handler.bind(store), watchOpts);
   });
@@ -241,7 +533,9 @@ function createStoreInstance(Vue, id, options) {
   Object.defineProperty(store, '$vm', {
     enumerable: true,
     configurable: false,
-    get: function () { return _vm_ref; },
+    get: function () {
+      return _vm_ref;
+    },
     set: function () {
       warn('$vm 是只读属性，不允许业务侧重写');
     },
@@ -281,7 +575,8 @@ function createStoreInstance(Vue, id, options) {
     });
 
     // v0.4 新增：重置 source
-    var freshSource = (typeof options.source === 'function') ? options.source() : {};
+    var freshSource =
+      typeof options.source === 'function' ? options.source() : {};
     Object.keys(freshSource).forEach(function (key) {
       Vue.set(rawSource, key, freshSource[key]);
     });
@@ -297,7 +592,10 @@ function createStoreInstance(Vue, id, options) {
 
   store.$emit = function (event, payload) {
     var fns = _listeners[event];
-    if (fns) fns.slice().forEach(function (fn) { fn(payload); });
+    if (fns)
+      fns.slice().forEach(function (fn) {
+        fn(payload);
+      });
   };
 
   store.$on = function (event, handler) {
@@ -373,7 +671,9 @@ function createStoreInstance(Vue, id, options) {
     }
     store.$emit('page:enter');
     // v0.5: plugin enter hooks
-    _pluginHooks.forEach(function (h) { if (h.enter) h.enter(); });
+    _pluginHooks.forEach(function (h) {
+      if (h.enter) h.enter();
+    });
   }
 
   function runLeave() {
@@ -387,7 +687,9 @@ function createStoreInstance(Vue, id, options) {
     }
     store.$emit('page:leave');
     // v0.5: plugin leave hooks
-    _pluginHooks.forEach(function (h) { if (h.leave) h.leave(); });
+    _pluginHooks.forEach(function (h) {
+      if (h.leave) h.leave();
+    });
   }
 
   // ====== bindTo 去重标记 ======
@@ -401,7 +703,10 @@ function createStoreInstance(Vue, id, options) {
   }
 
   function addBoundVm(vm) {
-    if (_boundVms) { _boundVms.add(vm); return; }
+    if (_boundVms) {
+      _boundVms.add(vm);
+      return;
+    }
     _boundVmsFallback.push(vm);
   }
 
@@ -466,12 +771,19 @@ function createStoreInstance(Vue, id, options) {
     clearAllIntervals();
 
     // v0.5: plugin destroy hooks
-    _pluginHooks.forEach(function (h) { if (h.destroy) h.destroy(); });
+    _pluginHooks.forEach(function (h) {
+      if (h.destroy) h.destroy();
+    });
 
     store.$disposed = true;
-    Object.keys(_listeners).forEach(function (key) { delete _listeners[key]; });
+    Object.keys(_listeners).forEach(function (key) {
+      delete _listeners[key];
+    });
     vm.$destroy();
     storeRegistry.delete(id);
+
+    // v0.5.1 debug: 放在所有清理之后
+    emitDebugEvent(store, 'store:destroy');
   };
 
   store._vm = vm;
@@ -485,6 +797,16 @@ function createStoreInstance(Vue, id, options) {
     if (hooks) _pluginHooks.push(hooks);
   });
 
+  // ====== v0.5.1 debug: 注册到 devtools registry ======
+  var _debugId = nextId();
+  Object.defineProperty(store, '_debugId', {
+    value: _debugId,
+    writable: false,
+    enumerable: false,
+    configurable: false,
+  });
+  emitDebugEvent(store, 'store:create', { debugId: _debugId });
+
   return store;
 }
 
@@ -503,10 +825,14 @@ function createStoreInstance(Vue, id, options) {
 function definePageStore(id, options) {
   // 入参校验
   if (!id || typeof id !== 'string') {
-    throw new Error('[vue-page-store] definePageStore 需要一个非空字符串作为 id');
+    throw new Error(
+      '[vue-page-store] definePageStore 需要一个非空字符串作为 id',
+    );
   }
   if (!options || typeof options.state !== 'function') {
-    throw new Error('[vue-page-store] definePageStore("' + id + '") 需要 state 为函数');
+    throw new Error(
+      '[vue-page-store] definePageStore("' + id + '") 需要 state 为函数',
+    );
   }
 
   var _Vue = Vue;
@@ -534,7 +860,7 @@ function definePageStore(id, options) {
 var index = {
   definePageStore: definePageStore,
   registerPlugin: registerPlugin,
-  storeRegistry: storeRegistry
+  storeRegistry: storeRegistry,
 };
 
 exports.default = index;