sage-mem 2.1.19 → 2.1.21

package/README.md

@@ -12,7 +12,7 @@
 
 **Cross-session memory for DeepSeek Harness — plain markdown files, no database, no worker.**
 
-**Current release: `2.1.19`** — the npm badge above is the dynamic source of truth. **Contract baseline: `1.0.0`** — the first stable release, whose public commitments, the capability boundaries and the list of things it explicitly cannot do are frozen in the
+**Current release: `2.1.21`** — the npm badge above is the dynamic source of truth. **Contract baseline: `1.0.0`** — the first stable release, whose public commitments, the capability boundaries and the list of things it explicitly cannot do are frozen in the
 [frozen contract](https://github.com/gezi-wen/sage-mem/blob/main/docs/1.0.0-contract.md).
 
 If it is useful to you, a Star is the most direct feedback.

package/README.zh.md

@@ -14,7 +14,7 @@
 
 > File-based cross-session memory for DeepSeek Harness — every memory is a plain markdown file you can open, edit and delete. No database, no worker, no port.
 
-**当前发布版本：`2.1.19`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
+**当前发布版本：`2.1.21`** —— 顶部 npm 徽章是动态权威。**契约基线：`1.0.0`** —— 第一个稳定版，公开承诺、能力边界与「明确做不到」的清单冻结在
 [契约冻结](https://github.com/gezi-wen/sage-mem/blob/main/docs/1.0.0-contract.md)。
 
 如果它对你有用，给个 Star 是最直接的反馈。

package/lib/client.js

@@ -978,6 +978,22 @@ const StarmapRuntime = (function (require, _react) {
 			return makeCanvas2DRenderer(canvasEl, layout, visBox, hoverBox);
 		}
 
+		/**
+		 * 星图动画的统一时钟（Q15）。
+		 *
+		 * rAF 回调的时间戳与 `performance.now()` 是**同一个原点**（单调、从页面加载起算），
+		 * 而 `Date.now()` 是 epoch 毫秒 —— 两套混用会让相位变成大负数。旧版入场动画就是这个
+		 * bug：`t0 = Date.now()` 去减 rAF 的 `ts`，`ts - t0` 恒为大负数 → 永远「入场没结束」，
+		 * 但每帧画完又不接着排帧，于是入场只画了一帧、相位还是负的。
+		 *
+		 * 星图里所有「过了多少毫秒」都走这里（freshness 那种墙钟判断除外，那本来就该用 Date.now）。
+		 */
+		function starmapNow() {
+			return (typeof performance !== "undefined" && performance && typeof performance.now === "function")
+				? performance.now()
+				: Date.now();
+		}
+
 		// ── 星图主体（canvas + 图例 + 详情面板）──
 		function StarMap(props) {
 			const ctx = props.ctx || appCtx;
@@ -1108,16 +1124,18 @@ const StarmapRuntime = (function (require, _react) {
 				if (!data || !layout || !canvasEl) return undefined;
 				const renderer = createRenderer(canvasEl, layout, visBox, hoverBox);
 				drawBox.renderer = renderer;
-				drawBox.t0 = Date.now();
+				// t0 与 rAF 的 ts 必须同一时钟（见 starmapNow）。旧版用 Date.now 当 t0，
+				// 于是相位是 epoch 级的大负数，入场窗口永远关不上。
+				drawBox.t0 = starmapNow();
 				renderer.render(0);
 
 				// ── 按需重绘（重做过一版）──
 				// 旧版是一个常驻 rAF 循环：只要星图页开着就永远满帧重画，后台标签页也一样，
 				// 而画面其实早就静止了。新的规矩只有三种情况会画：
 				//   1. 入场展示动画期间（约 1.3s，星点按诞生时间依次点亮）
-				//   2. 有人调 markDirty()（hover / 数据或筛选变化 / 尺寸变化）
+				//   2. 有人调 markDirty()（hover / 数据或筛选变化 / 尺寸变化 / 回放）
 				//   3. 诞生回放进行中
-				// 其余时间一帧都不画。另外帧率封顶 30fps，页面不可见时直接跳过。
+				// 其余时间一帧都不画。另外帧率封顶 30fps，页面不可见时暂停（回来再补一帧）。
 				const FRAME_MS = 1000 / 30;
 				const ENTRANCE_MS = 1300;
 				let raf = 0;
@@ -1126,26 +1144,51 @@ const StarmapRuntime = (function (require, _react) {
 				function schedule() {
 					if (!raf) raf = window.requestAnimationFrame(tick);
 				}
+				/** 还需要连续帧的两种状态：入场动画没走完 / 诞生回放激活。 */
+				function animating(ts) {
+					return (ts - drawBox.t0 < ENTRANCE_MS) || replayBox.active === true;
+				}
 				function tick(ts) {
 					raf = 0;
 					if (!drawBox.renderer) return;
-					if (ts - drawBox.t0 < ENTRANCE_MS || replayBox.active) dirty = true;
+					if (animating(ts)) dirty = true;
+					// 页面不可见：这一帧不画，也**不**再排下一帧（旧版直接 return，结果从后台
+					// 切回来就再也不画了）。visibilitychange 回到可见时会补一帧。
+					if (typeof document !== "undefined" && document && document.hidden) {
+						dirty = true;
+						return;
+					}
 					if (!dirty) return;
-					if (typeof document !== "undefined" && document.hidden) return;
 					if (ts - lastDraw < FRAME_MS) { schedule(); return; }
 					dirty = false;
 					lastDraw = ts;
 					drawBox.renderer.render((ts - drawBox.t0) / 1000);
+					// 入场 / 回放没结束就接着排下一帧；静止之后一帧都不排（不允许常驻空转）。
+					if (animating(ts)) schedule();
 				}
 				drawBox.markDirty = function () { dirty = true; schedule(); };
+				// 从后台标签页回来：补一帧（隐藏期间不排帧，靠这个事件唤醒）。
+				const onVisibility = function () {
+					if (typeof document === "undefined" || !document) return;
+					if (document.hidden) { dirty = true; return; }
+					dirty = true;
+					schedule();
+				};
+				if (typeof document !== "undefined" && document && typeof document.addEventListener === "function") {
+					document.addEventListener("visibilitychange", onVisibility);
+				}
 				schedule();
 
 				return () => {
 					window.cancelAnimationFrame(raf);
+					if (typeof document !== "undefined" && document && typeof document.removeEventListener === "function") {
+						document.removeEventListener("visibilitychange", onVisibility);
+					}
 					drawBox.renderer = null;
 					drawBox.markDirty = null;
 					replayBox.active = false;
 					window.cancelAnimationFrame(replayBox.raf);
+					replayBox.raf = 0;
 					if (renderer.destroy) renderer.destroy();
 				};
 			}, [data, layout, canvasEl, themeKey]);
@@ -1163,7 +1206,7 @@ const StarmapRuntime = (function (require, _react) {
 					if (drawBox.renderer.setGeometry) drawBox.renderer.setGeometry();
 					// 交给按需重绘那一套：下一帧画（<33ms），不再这里直接 render
 					if (drawBox.markDirty) drawBox.markDirty();
-					else drawBox.renderer.render((Date.now() - drawBox.t0) / 1000);
+					else drawBox.renderer.render((starmapNow() - drawBox.t0) / 1000);
 				}
 			}, [data, layout, kindsOn, query, showArchive]);
 
@@ -1298,7 +1341,9 @@ const StarmapRuntime = (function (require, _react) {
 			function stopReplay() {
 				replayBox.active = false;
 				window.cancelAnimationFrame(replayBox.raf);
+				replayBox.raf = 0;
 				if (drawBox.renderer && drawBox.renderer.setReveal) drawBox.renderer.setReveal(null);
+				// 停回放要回到「全亮」：markDirty 让绘制循环补这一帧。
 				if (drawBox.markDirty) drawBox.markDirty();
 				setReplaying(false);
 				setReplayDate(null);
@@ -1316,17 +1361,22 @@ const StarmapRuntime = (function (require, _react) {
 				window.cancelAnimationFrame(replayBox.raf);
 				const span = Math.max(mx - mn, 60000) + 2400;
 				const dur = 18000;
-				const t0 = Date.now();
+				let t0 = null;
 				replayBox.active = true;
 				setReplaying(true);
+				// 关键：回放期间由「按需绘制」那套逐帧重画。setReveal 只改渲染器的变量，
+				// 不标脏 / 不唤醒绘制循环的话屏幕上什么都不动（旧版就是这样，回放是空的）。
+				if (drawBox.markDirty) drawBox.markDirty();
 				let lastLabel = 0;
-				const tick = () => {
+				const tick = (ts) => {
 					if (!replayBox.active) return;
-					const p = Math.min(1, (Date.now() - t0) / dur);
+					// 进度也用 rAF 的单调时间戳，和绘制循环同一个时钟（旧版用 Date.now 又混了一次）。
+					if (t0 === null) t0 = ts;
+					const p = Math.min(1, (ts - t0) / dur);
 					const cur = mn - 1200 + span * p;
 					if (drawBox.renderer && drawBox.renderer.setReveal) drawBox.renderer.setReveal(cur);
-					if (Date.now() - lastLabel > 250) {
-						lastLabel = Date.now();
+					if (ts - lastLabel > 250) {
+						lastLabel = ts;
 						setReplayDate(Math.min(mx, cur));
 					}
 					if (p >= 1) { stopReplay(); return; }
@@ -2758,6 +2808,20 @@ const StarmapRuntime = (function (require, _react) {
 			}, props.label);
 		}
 
+		/**
+		 * 活动卡片「展开态」的合并（Q16，2.1.21）。
+		 *
+		 * 为什么是个纯函数：连续点两张卡（或同一帧里点两次）时，事件回调手里那个
+		 * `expanded` 可能还是上一帧的快照 —— 拿快照拼新对象会把另一笔改动覆盖掉。
+		 * 所以 Section 走**函数式 setState**，把「怎么合并」收敛到这里：
+		 * 只翻转目标文件那一条，其余原样保留。测试也直接喂 prev 来验这条语义。
+		 */
+		function mergeExpanded(prev, file) {
+			const next = Object.assign({}, prev);
+			next[file] = !(prev && prev[file]);
+			return next;
+		}
+
 		function Card(props) {
 			const item = props.item;
 			const meta = TYPE_META[item.type] || TYPE_META.reference;
@@ -5590,7 +5654,7 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 		// 只负责「按状态/筛选把卡片摆出来 + 四种空态」；状态、筛选语义、动作回调全部由 Section 传。
 		// 抽出的判据：它是 Section 里最大的一块纯渲染，而卡片组件（Card / ArchivedCard）本来就在 50 共享层。
 		function FilesView(props) {
-			const { loading, totalCount, openAdd, createIndexSkeleton, statusFilter, setStatusFilter, items, archiveItems, filtered, setTypeFilter, setTagFilter, setQuery, busy, restoring, archDelete, archEdit, archLoad, archSaving, archText, setArchText, openArchEdit, saveArchEdit, cancelArchEdit, restoreFile, setArchDelete, setArchEdit, deleteArchivedFile, expanded, deleting, archiving, archiveReason, setArchiveReason, setArchiving, setDeleting, confirmArchive, toggleLock, openEdit, confirmDelete } = props;
+			const { loading, totalCount, openAdd, createIndexSkeleton, statusFilter, setStatusFilter, items, archiveItems, filtered, setTypeFilter, setTagFilter, setQuery, busy, restoring, archDelete, archEdit, archLoad, archSaving, archText, setArchText, openArchEdit, saveArchEdit, cancelArchEdit, restoreFile, setArchDelete, setArchEdit, deleteArchivedFile, expanded, onToggleExpanded, deleting, archiving, archiveReason, setArchiveReason, setArchiving, setDeleting, confirmArchive, toggleLock, openEdit, confirmDelete } = props;
 			let filesView;
 			if (loading && totalCount === 0) {
 				filesView = h("div", { className: "smem-skeleton", key: "loading", "data-loading": "1" }, [0, 1, 2].map(function (i) {
@@ -5654,11 +5718,10 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 						onCancelArchive: function () { setArchiving(null); setArchiveReason(""); },
 						onConfirmArchive: confirmArchive,
 						onToggleLock: toggleLock,
-						onToggle: function (file) {
-							const nx = {};
-							nx[file] = !expanded[file];
-							setExpanded(Object.assign({}, expanded, nx));
-						},
+						// 展开 / 收起是**业务回调**（Q16）：卡片只上报「点了哪张」，
+						// 合并逻辑归 Section。旧版这里引用旧 Section 闭包里的 `setExpanded` ——
+						// 拆件后它不在本函数作用域，点击即 ReferenceError: setExpanded is not defined。
+						onToggle: onToggleExpanded,
 						onEdit: openEdit,
 						onAskDelete: function (file) { setDeleting(file); setArchiving(null); },
 						onCancelDelete: function () { setDeleting(null); },
@@ -5778,6 +5841,12 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 			const query = sQuery[0], setQuery = sQuery[1];
 			const sExpanded = react.useState({});
 			const expanded = sExpanded[0], setExpanded = sExpanded[1];
+			// Q16：卡片「展开 / 收起」是业务回调（FilesView 只上报点了哪张卡）。
+			// 必须走**函数式** setState：事件里捕获的 expanded 可能是上一帧快照，
+			// 直接 Object.assign({}, expanded, …) 会把连续点击的上一笔改动覆盖掉。
+			function onToggleExpanded(file) {
+				setExpanded(function (prev) { return mergeExpanded(prev, file); });
+			}
 			const sDeleting = react.useState(null);
 			const deleting = sDeleting[0], setDeleting = sDeleting[1];
 			const sFormOpen = react.useState(false);
@@ -6790,7 +6859,7 @@ h("span", { key: "sep", className: "smem-actions-sep", "aria-hidden": "true" }),
 				archText: archText, setArchText: setArchText,
 				openArchEdit: openArchEdit, saveArchEdit: saveArchEdit, cancelArchEdit: cancelArchEdit,
 				restoreFile: restoreFile, setArchDelete: setArchDelete, setArchEdit: setArchEdit, deleteArchivedFile: deleteArchivedFile,
-				expanded: expanded, deleting: deleting, archiving: archiving,
+				expanded: expanded, onToggleExpanded: onToggleExpanded, deleting: deleting, archiving: archiving,
 				archiveReason: archiveReason, setArchiveReason: setArchiveReason,
 				setArchiving: setArchiving, setDeleting: setDeleting,
 				confirmArchive: confirmArchive, toggleLock: toggleLock,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sage-mem",
   "description": "Cross-session memory for DeepSeek Harness — plain markdown files, no database, no worker.",
-  "version": "2.1.19",
+  "version": "2.1.21",
   "type": "module",
   "main": "lib/index.js",
   "icon": "./icon.png",