@arcaneorion/dsh-teaching-board 0.5.0 → 0.5.1

package/README.md

@@ -16,7 +16,7 @@ dsh plugin --profile web add @arcaneorion/dsh-teaching-board
 它是一个 **profile 级 bundle**：装一次，这个进程里所有会话都拿得到 `stage_*` 工具与「教学平面」页签。
 （`dsh plugin add` 会把依赖与 bundles 条目一起写进该 profile 的 manifest。）
 
-> **发布状态**：`@arcaneorion/dsh-teaching-board` 已发布（`0.4.0` 于 2026-09-15 10:17 CST 上线，当前 `0.5.0`）。
+> **发布状态**：`@arcaneorion/dsh-teaching-board` 已发布（`0.4.0` 于 2026-09-15 10:17 CST 上线，当前 `0.5.1`）。
 > 改名前的 `@arcaneorion/dsh-stage-panel@0.1.0` 仍在 registry 上，对应本仓早期版本——**别再用**，
 > 装它只会拿到残缺面板（`npm deprecate @arcaneorion/dsh-stage-panel "renamed to @arcaneorion/dsh-teaching-board"` 可让老名字自己说明去向）。
 
@@ -68,6 +68,7 @@ dsh plugin --profile web add @arcaneorion/dsh-teaching-board
 | `skills/stage-panel/` | 行为层：使用手册 `SKILL.md` + 选型/布局/视觉三份规范 + 五个素材库 |
 | `src/client.js` | client 半：「教学平面」视图（工具栏 + 注入 runtime + 截图交付 + agent 请求监听） |
 | `package.json` / `cordis.patch.yml` | bundle 声明（行 id `teaching-board`），挂载进 `web` profile |
+| `test/ink-anchor.html` + `test/serve.mjs` | 审计测试：笔迹锚定的 5 项断言（改注入 runtime 后必跑）。不进 npm 包（`files` 未含 `test`） |
 | `PROTOTYPE-*.js` | 早期动态原型（`lwst-2`）存档，仅供历史参考 |
 
 ## 分层
@@ -99,7 +100,11 @@ dsh plugin --profile web add @arcaneorion/dsh-teaching-board
 
 **保留与边界**：
 - 笔迹按 `board` id 存在客户端，板面更新后由父层重新注入（`cmd:'load'`）；滚动位置同理。
-- 笔迹是**视口坐标**：`append` 只往板尾加内容、已有内容不动，所以笔迹对得上；若演进时上半部分重排，旧笔迹会错位——规范是「接着写」时保持板上半部分稳定。
+- **笔迹锚定在板面内容上（书页感）**：画布是视口大小的浮层，但笔迹坐标存的是**文档坐标**，
+  重绘时按滚动量平移，并记下「这一笔写在哪一段（`.stg-block`）上」当锚点。
+  于是滚动、以及 AI 在它上面改写内容导致的重排，笔迹都跟着那段文字一起走 ——
+  不会像旧版那样钉在屏幕上（旧版存视口坐标，滚动一下圈就脱开，实测漂移 = 滚动距离）。
+  块被删掉时退回文档坐标。审计测试见 `test/ink-anchor.html`。
 - 笔迹存在每个客户端自己那里：同一会话开了两个浏览器，两边各画各的，不互相同步。
 - 第一块（`op:"open"`）决定整块板的样式：后续片段共享它的 CSS，所以视觉规范要写在开板那一次里。
 
@@ -120,5 +125,26 @@ dsh plugin --profile web install        # 补 link symlink（改包源后必须
 # 视图槽位 occupancy 出现 id=teaching-board；工具目录出现 stage_*
 ```
 
+### 审计测试（改注入 runtime 后必跑）
+
+```bash
+node test/serve.mjs                     # 默认 8130，打印测试页地址
+# 打开 http://127.0.0.1:8130/test/ink-anchor.html
+```
+
+`test/ink-anchor.html` 直接在浏览器里把 `src/client.js` 的注入 runtime 抽出来跑，
+构造合成板面并断言 5 件事（页面右侧实时显示每项实测数字，`window.__audit` 给出结构化结果）：
+
+| | 断言 | 说明 |
+|---|---|---|
+| A | 画下去就对准那段文字 | 笔迹与文字中心差 ≤ 3px |
+| B | 笔迹坐标 = 文档坐标 | 存下的 y ≈ 屏幕 y + 滚动量（旧版存的是视口坐标，这项必红） |
+| C | 滚动 200px 后不脱开 | 笔迹位移 = 内容位移（旧版笔迹不动 → 漂移 = 滚动距离） |
+| D | 上方段落改写后不脱开 | 走的是段落锚点（`.stg-block`）而不是绝对坐标 |
+| E | 截图里笔迹与文字对齐 | 截图按当前视口（`viewBox`）截取，图内两者仍然对齐 |
+
+> 用旧版（`git show HEAD:src/client.js > src/client.js`）跑过：B/C/D/E 四项变红，
+> 说明这组断言确实盯得住这个 bug —— 不是「跑过就算过」的测试。
+
 > 静态 bundle 改动**需要重启 dsh 进程并刷新页面**，与动态 Cordis 插件的热更新不同。
 > 其它静态化踩坑（boot 解析 / host 需 JS 源 / ModuleLoader handoff / 空配置分支）详见 `../README.md` §4。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arcaneorion/dsh-teaching-board",
-  "version": "0.5.0",
+  "version": "0.5.1",
   "type": "module",
   "main": "src/index.js",
   "exports": {

package/src/client.js

@@ -56,12 +56,22 @@ window.__ModuleLoader__.load({
   if (window.__stagePanelInk) return;
   var P = { mode: 'off', color: '#e5484d', size: 3 };
   var strokes = [], cur = null, drawing = false;
+  var anchorCache = {};   // 一次重绘内，同一块只算一次位移
+  var lastSX = -1, lastSY = -1;   // 上次重绘时的滚动位置（判断要不要重画）
   var MAX_BYTES = 1200 * 1024;
 
   function send(m) { try { parent.postMessage(m, '*'); } catch (e) {} }
 
   var cv = document.createElement('canvas');
   cv.setAttribute('data-stage-ink', '');
+  /**
+   * 画布仍是**视口大小**（内存恒定，不受板面长度影响 —— 铺满整份文档在长板子上
+   * 会变成几十 MB 的位图，移动端还有 canvas 面积上限），
+   * 但笔迹存的是**文档坐标**，重绘时按滚动量平移 —— 于是它钉在板面内容上。
+   *
+   * 原实现存 clientX/clientY 且不平移：笔迹其实钉在**屏幕**上，
+   * 一滚动（或 AI 增量写板把内容推下去）就与内容错位。
+   */
   cv.style.cssText = 'position:fixed;left:0;top:0;width:100%;height:100%;z-index:2147483000;pointer-events:none;touch-action:none;';
   (document.body || document.documentElement).appendChild(cv);
   var g = cv.getContext('2d');
@@ -69,11 +79,20 @@ window.__ModuleLoader__.load({
   function dpr() { return window.devicePixelRatio || 1; }
   function fit() {
     var d = dpr();
-    cv.width = Math.max(1, Math.round(window.innerWidth * d));
-    cv.height = Math.max(1, Math.round(window.innerHeight * d));
+    var w = Math.max(1, Math.round(window.innerWidth));
+    var h = Math.max(1, Math.round(window.innerHeight));
+    cv.style.width = w + 'px';
+    cv.style.height = h + 'px';
+    var nw = Math.max(1, Math.round(w * d));
+    var nh = Math.max(1, Math.round(h * d));
+    if (nw === cv.width && nh === cv.height) return;   // 尺寸没变就别白清一次位图
+    cv.width = nw;
+    cv.height = nh;
     redraw();
   }
-  function paintStroke(s) {
+  function paintStroke(s, dx, dy) {
+    dx = dx || 0;
+    dy = dy || 0;
     g.globalCompositeOperation = s.erase ? 'destination-out' : 'source-over';
     g.strokeStyle = s.color;
     g.lineWidth = s.erase ? s.size * 5 : s.size;
@@ -81,19 +100,45 @@ window.__ModuleLoader__.load({
     g.lineJoin = 'round';
     g.beginPath();
     for (var i = 0; i < s.pts.length; i++) {
-      if (i === 0) g.moveTo(s.pts[i][0], s.pts[i][1]); else g.lineTo(s.pts[i][0], s.pts[i][1]);
+      if (i === 0) g.moveTo(s.pts[i][0] + dx, s.pts[i][1] + dy);
+      else g.lineTo(s.pts[i][0] + dx, s.pts[i][1] + dy);
     }
-    if (s.pts.length === 1) g.lineTo(s.pts[0][0] + 0.1, s.pts[0][1]);
+    if (s.pts.length === 1) g.lineTo(s.pts[0][0] + dx + 0.1, s.pts[0][1] + dy);
     g.stroke();
     g.globalCompositeOperation = 'source-over';
   }
   function redraw() {
     var d = dpr();
+    lastSX = window.scrollX || 0;
+    lastSY = window.scrollY || 0;
+    anchorCache = {};   // 每次重绘重新解析锚点（块可能刚被 AI 改写 / 移动过）
     g.setTransform(1, 0, 0, 1, 0, 0);
     g.clearRect(0, 0, cv.width, cv.height);
     g.setTransform(d, 0, 0, d, 0, 0);
-    for (var i = 0; i < strokes.length; i++) paintStroke(strokes[i]);
-    if (cur) paintStroke(cur);
+    // ★ 视口画布 + 按滚动量平移：笔迹存的是文档坐标，平移之后正好落在板面内容上。
+    g.translate(-lastSX, -lastSY);
+    for (var i = 0; i < strokes.length; i++) {
+      var off = strokeDelta(strokes[i]);
+      paintStroke(strokes[i], off[0], off[1]);
+    }
+    if (cur) {
+      var offCur = strokeDelta(cur);
+      paintStroke(cur, offCur[0], offCur[1]);
+    }
+  }
+
+  /**
+   * 滚动 = 笔迹要跟着内容走。
+   *
+   * ⚠️ 必须**同步**重画，不能塞进 requestAnimationFrame：
+   * 后台标签页 / 被遮挡的 iframe 里 rAF 会被浏览器暂停，那样笔迹就定格在旧位置
+   * （实测：审计测试 C/D 两项就是被这个坑掉的）。浏览器本来就把 scroll 事件
+   * 节流到每帧一次，同步重画不会把主线程刷爆。
+   */
+  function syncScroll() {
+    var x = window.scrollX || 0, y = window.scrollY || 0;
+    if (x === lastSX && y === lastSY) return;   // 位置没动就别白画一遍
+    redraw();
   }
   function count() { send({ __stagePanel: true, type: 'ink', strokes: strokes.length, data: strokes }); }
 
@@ -137,17 +182,89 @@ window.__ModuleLoader__.load({
     if (n && n.parentNode) n.parentNode.removeChild(n);
   }
 
+  /** 视口坐标 → **文档坐标**（笔迹的坐标系：原点 = 文档左上角）。
+      画布是视口大小的浮层，指针事件给的是 clientX/clientY，所以必须加上
+      当前滚动量换算成文档坐标；原实现直接把 clientX/clientY 存下来，
+      笔迹其实钉在屏幕上 —— 一滚动、或 AI 增量写板把内容推下去，就与内容错位。 */
+  function toBoard(e) {
+    var r = cv.getBoundingClientRect();
+    return [
+      e.clientX - r.left + (window.scrollX || 0),
+      e.clientY - r.top + (window.scrollY || 0),
+    ];
+  }
+
+  /**
+   * 这一笔落在哪一块上（.stg-block），记下它的**文档原点**当锚点。
+   *
+   * 为什么需要锚点：文档坐标只解决「滚动」，解决不了「重排」——
+   * AI 在用户圈过的那段上面又写了一段（set/remove 也会改变高度），
+   * 那段文字整体下移，而笔迹的文档坐标没变，于是又脱开了。
+   * 锚在「它所在的那一块」上，块移动多少，笔迹就跟着移动多少 —— 这才是写在书上。
+   *
+   * ⚠️ 不能用 elementFromPoint：画布盖在最上层，内容层根本点不到。
+   */
+  function anchorAt(clientX, clientY) {
+    var blocks = document.querySelectorAll('.stg-block');
+    for (var i = 0; i < blocks.length; i++) {
+      var r = blocks[i].getBoundingClientRect();
+      if (clientY >= r.top && clientY <= r.bottom && clientX >= r.left && clientX <= r.right) {
+        return {
+          region: blocks[i].getAttribute('data-stage-region') || null,
+          index: i,
+          ox: r.left + (window.scrollX || 0),
+          oy: r.top + (window.scrollY || 0),
+        };
+      }
+    }
+    return null;   // 落在块外的空白上（比如最后一块下面那片留白）：只能靠文档坐标
+  }
+
+  /** 锚点现在跑到哪了（相对画下去时的位置）。块没了就退回绝对坐标。 */
+  function anchorDeltaByKey(key) {
+    var cached = anchorCache[key];
+    if (cached !== undefined) return cached;
+
+    var a = JSON.parse(key);   // [region, index, ox, oy]
+    var node = null;
+    if (a[0]) {
+      try { node = document.querySelector('[data-stage-region="' + String(a[0]).replace(/"/g, '') + '"]'); } catch (e) { node = null; }
+    }
+    if (!node) {
+      var all = document.querySelectorAll('.stg-block');
+      node = all[a[1]] || null;
+    }
+    var out = [0, 0];
+    if (node) {
+      var r = node.getBoundingClientRect();
+      out = [r.left + (window.scrollX || 0) - a[2], r.top + (window.scrollY || 0) - a[3]];
+    }
+    anchorCache[key] = out;
+    return out;
+  }
+
+  function strokeDelta(s) {
+    var a = s.anchor;
+    if (!a) return [0, 0];
+    return anchorDeltaByKey(JSON.stringify([a.region, a.index, Math.round(a.ox), Math.round(a.oy)]));
+  }
+
   cv.addEventListener('pointerdown', function (e) {
     if (P.mode === 'off') return;
     if (forwardClick(e.clientX, e.clientY)) return;
     drawing = true;
     try { cv.setPointerCapture(e.pointerId); } catch (err) {}
-    cur = { color: P.color, size: P.size, erase: P.mode === 'erase', pts: [[e.clientX, e.clientY]] };
+    cur = {
+      color: P.color, size: P.size, erase: P.mode === 'erase',
+      pts: [toBoard(e)],
+      // 记下「这一笔写在哪一段上」—— 那一段以后被推下去，笔迹跟着它走
+      anchor: anchorAt(e.clientX, e.clientY),
+    };
     redraw();
   });
   cv.addEventListener('pointermove', function (e) {
     if (!drawing) return;
-    cur.pts.push([e.clientX, e.clientY]);
+    cur.pts.push(toBoard(e));
     redraw();
   });
   function end() {
@@ -166,6 +283,8 @@ window.__ModuleLoader__.load({
     return new Promise(function (resolve, reject) {
       var w = Math.max(1, Math.round(window.innerWidth));
       var h = Math.max(1, Math.round(window.innerHeight));
+      var sx = Math.max(0, window.scrollX || 0);
+      var sy = Math.max(0, window.scrollY || 0);
       var clone = document.documentElement.cloneNode(true);
       var drop = clone.querySelectorAll('[data-stage-capture-ignore]');
       for (var d = 0; d < drop.length; d++) drop[d].parentNode.removeChild(drop[d]);
@@ -173,15 +292,31 @@ window.__ModuleLoader__.load({
       var dsts = clone.querySelectorAll('canvas');
       for (var i = 0; i < srcs.length && i < dsts.length; i++) {
         var st = window.getComputedStyle(srcs[i]);
+        var rect = srcs[i].getBoundingClientRect();
         var im = document.createElement('img');
         try { im.setAttribute('src', srcs[i].toDataURL('image/png')); } catch (e) { continue; }
-        im.setAttribute('style', 'position:fixed;left:' + st.left + ';top:' + st.top +
-          ';width:' + st.width + ';height:' + st.height + ';');
+        /**
+         * ★ img 要放到**文档坐标**上，不能照抄 computed left/top。
+         *
+         * 画布是 position:fixed（视口锚定）的浮层，它的 left/top 恒为 0px ——
+         * 照抄的话，位图会被贴到「文档最顶端」，而它画的却是当前这一屏的笔迹，
+         * 于是截图里的圈和内容差着整整一个滚动距离。
+         * 位图本身画的是「当前视口 + 滚动量平移」的结果，所以要换算成文档坐标再绝对定位；
+         * 再配合下面 SVG 的 viewBox（= 当前视口），拍到的才是「你正在看的那一屏」。
+         */
+        var left = Math.round(rect.left + sx);
+        var top = Math.round(rect.top + sy);
+        im.setAttribute('style', 'position:absolute;left:' + left + 'px;top:' + top + 'px;' +
+          'width:' + st.width + ';height:' + st.height + ';z-index:2147483000;');
         dsts[i].parentNode.replaceChild(im, dsts[i]);
       }
       var xml = new XMLSerializer().serializeToString(clone);
+      // 文档可能比视口长：foreignObject 装整份文档，viewBox 只框当前视口 ——
+      // 拍到的就是你正在看的区域（含笔迹），而不是文档开头。
+      var docW = Math.max(w, document.documentElement.scrollWidth || 0);
+      var docH = Math.max(h, document.documentElement.scrollHeight || 0);
       var svg = '<svg xmlns="http://www.w3.org/2000/svg" width="' + w + '" height="' + h +
-        '" viewBox="0 0 ' + w + ' ' + h + '"><foreignObject x="0" y="0" width="' + w + '" height="' + h +
+        '" viewBox="' + sx + ' ' + sy + ' ' + w + ' ' + h + '"><foreignObject x="0" y="0" width="' + docW + '" height="' + docH +
         '">' + xml + '</foreignObject></svg>';
       var img = new Image();
       img.onload = function () {
@@ -257,19 +392,42 @@ window.__ModuleLoader__.load({
         else if (po.op === 'set') setRegionBlock(po.region, po.html);
         else if (po.op === 'remove') removeRegionBlock(po.region);
       }
+      // 内容长高不影响画布（画布是视口大小、按滚动量平移），不用重新 fit
     } else if (d.cmd === 'load') {
       // 同一块板的演进：把父层保存的笔迹重新注入新板。
       strokes = Array.isArray(d.strokes) ? d.strokes : [];
-      redraw();
-      count();
       if (typeof d.scrollY === 'number' && d.scrollY > 0) {
         try { window.scrollTo(0, d.scrollY); } catch (e) {}
       }
+      redraw();   // 平移量取决于滚动位置，滚动还原之后必须重画一次
+      count();
     } else if (d.cmd === 'ping') {
       send({ __stagePanel: true, type: 'ready' });
     }
   });
 
+  /**
+   * 滚动 = 笔迹要跟着内容走（syncScroll 定义在上面，和 redraw 放一起）。
+   *
+   * ⚠️ 必须**同步**重画，不能塞进 requestAnimationFrame：
+   * 后台标签页 / 被遮挡的 iframe 里 rAF 会被浏览器暂停，那样笔迹就定格在旧位置
+   * （实测：审计测试 C/D 两项就是被这个坑掉的）。浏览器本来就把 scroll 事件
+   * 节流到每帧一次，同步重画不会把主线程刷爆。
+   */
+  window.addEventListener('scroll', syncScroll, { passive: true });
+  /**
+   * 回到前台 / 重新获得焦点时**强制**重画一次。
+   *
+   * 为什么需要：滚动事件属于「渲染帧」的生命周期 —— 标签页被遮挡、iframe 不在视口里时
+   * 浏览器会暂停出帧，scroll 事件也就不派发，位图可能停在旧位置；
+   * 用户切回来第一眼就会看到错位的笔迹。（这也正是自动化测试在后台标签页里
+   * 会看到「滚动之后笔迹不动」的原因 —— 不是坐标算错了，是事件没来。）
+   */
+  function forceRedraw() { lastSX = -1; lastSY = -1; syncScroll(); }
+  document.addEventListener('visibilitychange', function () { if (!document.hidden) forceRedraw(); });
+  window.addEventListener('focus', forceRedraw);
+  window.addEventListener('pageshow', forceRedraw);
+
   // 把滚动位置报给父层，换板后用来还原（学生正在看的那一段不该跳回顶部）。
   var scrollTimer = null;
   window.addEventListener('scroll', function () {
@@ -280,7 +438,11 @@ window.__ModuleLoader__.load({
     }, 120);
   });
 
-  window.addEventListener('resize', fit);
+  window.addEventListener('resize', function () {
+    fit();
+    lastSX = -1; lastSY = -1;   // 尺寸/方向变了，强制重画一次
+    syncScroll();
+  });
   fit();
   count();
   send({ __stagePanel: true, type: 'ready' });