@arshdelight/practi 0.9.5 → 0.10.0

package/web-default/detail.js

@@ -10,6 +10,12 @@ var navStack = []; // 走过的路径栈，Prev 回退用（避开只读全局 w
 var nodeIndex = null; // 哈希→树内路径登记簿（数据窗 nodeIndex），inputs.from 反解用
 var view = 'wizard';  // 内容区视图：wizard | sv | doc（侧栏顶部三 tab）
 var svJson = null;    // StandardView JSON 缓存（首次切到该 tab 才拉取）
+var notesByHash = {}; // 本地学习笔记（/api/notes），按节点哈希分组；写入口=CLI（practi note）+ 右栏（POST /api/notes）
+var hashByPath = {};  // nodeIndex 的逆映射（树内路径 → 哈希）；根（空路径）= HASH 本身
+var notesOpen = false;  // 右栏开合：默认折叠；首载若本文档有笔记则自动展开（不持久化，每页按规则重判）
+var notesTouched = false; // 用户本页手动开合过——之后自动规则不再介入
+var draftByHash = {};   // 未落库的新建草稿（文档哈希 → 文本）：跨重渲染/导航存活，失焦有内容才落库
+var noteErrorMsg = null; // 右栏写操作失败的一次性报错（下次动作或重渲染即清）
 
 // op 旁注：用自然语言说清组合语义（seq 不需要说明）；loop 的旁注由 loopNote 按数据推导
 var OP_NOTES = {
@@ -55,6 +61,21 @@ function shortHash(h) {
   return String(h).length > 16 ? String(h).slice(0, 16) + '…' : String(h);
 }
 
+function notesFor(hash) {
+  return notesByHash[hash] || [];
+}
+
+/** 当前节点哈希：根=HASH（URL 里那份），树内=逆登记簿 */
+function hashAt(p) {
+  return p.length ? hashByPath[p.join(',')] : HASH;
+}
+
+/** 大纲里的笔记数徽标：0 条不出现；点击=跳到该节点并展开笔记栏（点击委托 data-note-badge） */
+function noteBadge(pathKey, count) {
+  if (!count) return '';
+  return '<span class="note-badge" data-note-badge data-path="' + pathKey + '">' + count + '</span>';
+}
+
 // ── 渲染 ──────────────────────────────────────────────
 
 function render() {
@@ -65,15 +86,16 @@ function render() {
   app.innerHTML = (view === 'wizard' ? nodeHtml(node) : jsonSectionHtml()) + navHtml();
   updateTabs();
   markSide();
+  renderNoteSide(); // 右栏跟人走：每次导航换节点都重渲染（草稿保真在 renderNoteSide 内部处理）
   // 向导视图回顶（瞬移，既有行为）；JSON 视图平滑滚到当前高亮块首行。
-  // 原生 smooth 滚动天然可中断：快速连点不同节点时，新目标的滚动指令
-  // 会取消进行中的动画，从当前位置转向新目标（CSSOM View 语义）
+  // 滚动容器是中间内容列自身（应用壳布局：整页不滚），原生 smooth 滚动天然可中断：
+  // 快速连点不同节点时，新目标的滚动指令会取消进行中的动画，从当前位置转向新目标
   if (view === 'wizard') {
-    window.scrollTo(0, 0);
+    app.scrollTop = 0;
   } else {
     var hl = document.querySelector('.json-pre .ln.hl');
     if (hl) hl.scrollIntoView({ behavior: 'smooth', block: 'start' });
-    else window.scrollTo({ top: 0, behavior: 'smooth' });
+    else app.scrollTo({ top: 0, behavior: 'smooth' });
   }
 }
 
@@ -172,9 +194,10 @@ function jsonHtml(value, markChild) {
 // ── 左侧大纲（学 hub /pop 详情侧栏）：根的直接孩子成节（1、2…）递归（1.1），
 // 与 fromRef 的 #编号同一坐标系；点击 goTo 跳转，当前节点高亮 ──
 
-function countActions(n) {
-  if (n.type === 'action') return 1;
-  return (n.children || []).reduce(function (s, c) { return s + countActions(c); }, 0);
+/** 全树节点数（含根本身）——侧栏大纲列的就是节点（1、1.1…），统计行与之同口径；
+ *  不叫 steps：steps 只对 op:seq 成立 */
+function countNodes(n) {
+  return 1 + (n.children || []).reduce(function (s, c) { return s + countNodes(c); }, 0);
 }
 
 /** 图标 tab（lucide list-todo/list-ordered/list-tree）：图标即按钮，名字进 tooltip 与 aria-label */
@@ -185,21 +208,21 @@ function tabIconBtn(view, tipKey, inner) {
 }
 
 function sideHtml() {
-  var total = countActions(doc);
+  var total = countNodes(doc);
   // 视图三 tab 钉在侧栏最顶：向导正文 / StandardView JSON / document JSON（内容区随之换形态）
   var html = '<div class="side-tabs">' +
     tabIconBtn('wizard', 'tabWizard', '<path d="M13 5h8"/><path d="M13 12h8"/><path d="M13 19h8"/><path d="m3 17 2 2 4-4"/><rect x="3" y="4" width="6" height="6" rx="1"/>') +
     tabIconBtn('sv', 'tabSv', '<path d="M11 5h10"/><path d="M11 12h10"/><path d="M11 19h10"/><path d="M4 4h1v5"/><path d="M4 9h2"/><path d="M6.5 20H3.4c0-1 2.6-1.925 2.6-3.5a1.5 1.5 0 0 0-2.6-1.02"/>') +
     tabIconBtn('doc', 'tabDoc', '<path d="M8 5h13"/><path d="M13 12h8"/><path d="M13 19h8"/><path d="M3 10a2 2 0 0 0 2 2h3"/><path d="M3 5v12a2 2 0 0 0 2 2h3"/>') +
     '</div>' +
-    '<p class="side-count">' + POP_I18N.t('stepCount', total) + '</p>' +
-    '<a href="#" class="side-item side-root" data-path="">' + escapeHtml(doc.name) + '</a>';
+    '<p class="side-count">' + POP_I18N.t('nodeCount', total) + '</p>' +
+    '<a href="#" class="side-item side-root" data-path="">' + escapeHtml(doc.name) + noteBadge('', notesFor(HASH).length) + '</a>';
   (function walkSide(n, prefix, depth, p) {
     (n.children || []).forEach(function (c, i) {
       var num = prefix + (i + 1);
       var cp = p.concat([i]);
       html += '<a href="#" class="side-item" data-path="' + cp.join(',') + '" style="padding-left:' + (14 + depth * 14) + 'px">' +
-        '<span class="side-num">' + num + '</span>' + escapeHtml(c.name) + '</a>';
+        '<span class="side-num">' + num + '</span>' + escapeHtml(c.name) + noteBadge(cp.join(','), notesFor(hashAt(cp)).length) + '</a>';
       if (c.children && c.children.length) walkSide(c, num + '.', depth + 1, cp);
     });
   })(doc, '', 0, []);
@@ -270,10 +293,173 @@ function nodeHtml(node) {
   html += proseHtml(node);
   if (node.type === 'action') html += outputsHtml(node) + attHtml(node);
   html += childrenHtml(node) + choiceHtml(node) + setHtml(node);
-  // revisions 已挪到左侧大纲底部（全文档汇总）；refines 同处
+  // 笔记只住右侧栏（不进内容区）：revisions 已挪到左侧大纲底部（全文档汇总）；refines 同处
   return html;
 }
 
+// ── 学习笔记（/api/notes，本地 sidecar notes.json）──
+// 呈现只住右侧笔记栏；内容区与 JSON 两视图不出现
+
+/** ISO → 浏览器本地时区的 YYYY-MM-DD HH:mm（个人日记口径：时间属于看的人，不属于服务器） */
+function fmtNoteTime(iso) {
+  var d = new Date(iso);
+  if (isNaN(d.getTime())) return String(iso || '');
+  function p(x) { return (x < 10 ? '0' : '') + x; }
+  return d.getFullYear() + '-' + p(d.getMonth() + 1) + '-' + p(d.getDate()) + ' ' + p(d.getHours()) + ':' + p(d.getMinutes());
+}
+
+// ── 右侧笔记栏（#note-side）：当前节点的笔记工作台，常驻可增改删 ──
+// 交互：点文本进入行内编辑、失焦即存（Esc 取消、清空=还原原文）；新建=头部按钮弹出
+// 草稿（失焦有内容才落库，空=静默放弃——存储层不允许空笔记）。写入门之二
+// （其一=CLI practi note）：POST /api/notes，CSRF 闸与 /api/run 同规格
+
+var TRASH_ICON = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M3 6h18"/><path d="M19 6v14a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2V6"/><path d="M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2"/></svg>';
+var PLUS_ICON = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M5 12h14"/><path d="M12 5v14"/></svg>';
+
+/** 开合同步：面板宽度与内容列让位由 CSS transition 承担，这里只切类
+ *  （body.note-open 让底部操作区同步让位，与内容列一起平滑重排） */
+function applyNotesOpen() {
+  var panel = document.getElementById('note-side');
+  if (panel) panel.classList.toggle('open', notesOpen);
+  document.body.classList.toggle('note-open', notesOpen);
+}
+
+/** 展开收起舌片：钉在面板左缘垂直居中（shell 内面板的相邻兄弟，right 与面板宽度
+ *  同步过渡即贴合面板边）；收起后停在屏幕右缘仍可点 */
+function wireNoteToggle() {
+  var btn = document.getElementById('note-toggle');
+  if (!btn) return;
+  btn.innerHTML = '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="m9 18 6-6-6-6"/></svg>';
+  btn.setAttribute('aria-label', POP_I18N.t('notePanel'));
+  btn.addEventListener('click', function () {
+    notesOpen = !notesOpen;
+    notesTouched = true;
+    noteErrorMsg = null;
+    renderNoteSide();
+  });
+}
+
+function renderNoteSide() {
+  var panel = document.getElementById('note-side');
+  if (!panel) return;
+  applyNotesOpen();
+  reconcileNoteSide();
+}
+
+/** 面板渲染=把 DOM 对齐到服务端笔记。笔记本体是常驻可编辑的 textarea（无边框、
+ *  自动长高，观感与正文一致）——没有「进入编辑态」这个动作，点了就有光标，失焦即存。
+ *  重建时保留未落库的改动与聚焦位（SSE 重拉/语言切换/导航不打断打字） */
+function reconcileNoteSide() {
+  var panel = document.getElementById('note-side');
+  if (!panel) return;
+  applyNotesOpen();
+  var list = document.getElementById('note-list');
+  if (!list) return;
+  var keep = {};      // 未落库改动的值（key=data-id）
+  var activeKey = null, caret = null;
+  list.querySelectorAll('[data-note-input]').forEach(function (ta) {
+    var id = ta.getAttribute('data-id');
+    if (!id) return; // 草稿的存活走 draftByHash，不进 keep
+    var n = noteById(id);
+    if (n && ta.value !== n.content) keep[id] = ta.value;
+    if (document.activeElement === ta) { activeKey = id; caret = ta.selectionStart; }
+  });
+  var hash = hashAt(path);
+  var notes = notesFor(hash);
+  var draftValue = draftByHash.hasOwnProperty(hash) ? draftByHash[hash] : null;
+  var count = notes.length + (draftValue !== null ? 1 : 0);
+  var html = '<div class="nside-head"><p class="nside-title">' + POP_I18N.t('secNotes', count) + '</p>' +
+    '<button type="button" class="nside-new" data-act="note-new" data-tip="' + escapeHtml(POP_I18N.t('noteNew')) + '" aria-label="' + escapeHtml(POP_I18N.t('noteNew')) + '">' + PLUS_ICON + '</button></div>';
+  if (noteErrorMsg) html += '<p class="nside-err">' + escapeHtml(noteErrorMsg) + '</p>';
+  if (!notes.length && draftValue === null) html += '<p class="nside-empty">' + escapeHtml(POP_I18N.t('noteEmpty')) + '</p>';
+  html += notes.map(function (n) {
+    var v = keep.hasOwnProperty(n.id) ? keep[n.id] : n.content;
+    return '<div class="nside-item">' +
+      '<div class="nside-meta"><span class="note-time">' + escapeHtml(fmtNoteTime(n.createdAt)) + '</span>' +
+      '<span class="nside-acts">' +
+      '<button type="button" class="nside-act" data-act="note-del" data-id="' + n.id + '" data-tip="' + escapeHtml(POP_I18N.t('noteDelete')) + '" aria-label="' + escapeHtml(POP_I18N.t('noteDelete')) + '">' + TRASH_ICON + '</button>' +
+      '</span></div>' +
+      '<textarea class="nside-input" data-note-input data-id="' + n.id + '">' + escapeHtml(v) + '</textarea></div>';
+  }).join('');
+  if (draftValue !== null) html += '<div class="nside-item"><textarea class="nside-input" data-note-input data-hash="' + escapeHtml(hash) + '">' + escapeHtml(draftValue) + '</textarea></div>';
+  list.innerHTML = html;
+  list.querySelectorAll('[data-note-input]').forEach(function (ta) {
+    autoGrow(ta);
+    var k = ta.getAttribute('data-id');
+    if (activeKey === k) {
+      ta.focus();
+      try { ta.setSelectionRange(caret, caret); } catch (e) { /* 类型输入框无 selection */ }
+    }
+  });
+}
+
+/** textarea 高度自适应内容（无边框伪装成正文的代价：得自己长个） */
+function autoGrow(ta) {
+  if (window.CSS && CSS.supports && CSS.supports('field-sizing', 'content')) return; // 原生自适应，JS 别插手
+  ta.style.height = 'auto';
+  ta.style.height = ta.scrollHeight + 'px';
+}
+
+function updateNoteCount() {
+  var list = document.getElementById('note-list');
+  if (!list) return;
+  var n = notesFor(hashAt(path)).length + list.querySelectorAll('[data-note-input]:not([data-id])').length;
+  var el = list.querySelector('.nside-title');
+  if (el) el.textContent = POP_I18N.t('secNotes', n);
+}
+
+function postNote(body) {
+  return fetch('/api/notes', {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+  }).then(function (r) {
+    return r.json().catch(function () { return null; }).then(function (j) {
+      if (!r.ok) {
+        var msg = j && j.error ? j.error : 'HTTP ' + r.status;
+        // 裸 404（非 JSON 响应体）= 服务器没有这条路由：进程还在跑旧构建
+        // （前端静态文件即时读盘是新的，web.ts 服务器代码是冷的——重启 practi web 即愈）
+        if (!j && r.status === 404) msg += ' — ' + POP_I18N.t('noteServerStale');
+        throw new Error(msg);
+      }
+      return j;
+    });
+  });
+}
+
+/** 所有笔记 POST 串行过同一队列：失焦保存与删除并发时不会互相覆盖 */
+var noteQueue = Promise.resolve();
+function queueNoteOp(fn) {
+  var p = noteQueue.then(fn, fn);
+  noteQueue = p.catch(function () {});
+  return p;
+}
+
+function noteById(id) {
+  var arr = notesFor(hashAt(path));
+  for (var i = 0; i < arr.length; i++) if (arr[i].id === id) return arr[i];
+  return null;
+}
+
+function noteFail(e) {
+  noteErrorMsg = String(e && e.message ? e.message : e);
+  renderNoteSide();
+}
+
+function deleteNoteById(id, itemNode) {
+  queueNoteOp(function () {
+    return postNote({ op: 'delete', id: id }).then(function () {
+      Object.keys(notesByHash).forEach(function (k) {
+        notesByHash[k] = notesByHash[k].filter(function (x) { return x.id !== id; });
+      });
+      if (itemNode && itemNode.parentNode) itemNode.parentNode.removeChild(itemNode);
+      document.getElementById('side').innerHTML = sideHtml(); // 徽标计数更新
+      updateNoteCount();
+    }).catch(function (e) { noteFail(e); });
+  });
+}
+
+
 function loopNote(node) {
   if (node.loop && node.loop.mode === 'count') return POP_I18N.t('repeatX', node.loop.count);
   if (node.loop && node.loop.mode === 'until') return POP_I18N.t('repeatUntil', node.loop.until);
@@ -480,6 +666,15 @@ document.addEventListener('click', function (e) {
     goTo(path.concat([Number(jump.getAttribute('data-idx'))]));
     return;
   }
+  var nbadge = e.target.closest('[data-note-badge]');
+  if (nbadge) {
+    // 徽标语义=看这条节点的笔记：跳转交给下面的 data-path，这里负责展开右栏
+    if (!notesOpen) {
+      notesOpen = true;
+      notesTouched = true;
+      renderNoteSide();
+    }
+  }
   var jump = e.target.closest('[data-path]');
   if (jump) {
     e.preventDefault();
@@ -490,6 +685,37 @@ document.addEventListener('click', function (e) {
   var act = e.target.closest('[data-act]');
   if (!act) return;
   var a = act.getAttribute('data-act');
+  if (a === 'note-new') {
+    // 新建=在列表末尾补一个草稿框（已有草稿就聚焦它）；失焦有内容才落库
+    var list = document.getElementById('note-list');
+    if (!list) return;
+    var existing = list.querySelector('[data-note-input]:not([data-id])');
+    if (existing) { existing.focus(); return; }
+    var item = document.createElement('div');
+    item.className = 'nside-item';
+    item.innerHTML = '<textarea class="nside-input" data-note-input></textarea>';
+    list.appendChild(item);
+    var ta = item.querySelector('textarea');
+    ta.focus();
+    updateNoteCount();
+    return;
+  }
+  if (a === 'note-del') {
+    // 写写相碰：进串行队列等当前失焦保存落库后再删，防并发读改写互相覆盖
+    var id = act.getAttribute('data-id');
+    var item = act.closest('.nside-item');
+    queueNoteOp(function () {
+      return postNote({ op: 'delete', id: id }).then(function () {
+        Object.keys(notesByHash).forEach(function (k) {
+          notesByHash[k] = notesByHash[k].filter(function (x) { return x.id !== id; });
+        });
+        if (item && item.parentNode) item.parentNode.removeChild(item);
+        document.getElementById('side').innerHTML = sideHtml(); // 徽标计数更新
+        updateNoteCount();
+      }).catch(function (e) { noteFail(e); });
+    });
+    return;
+  }
   if (a === 'next') {
     var n = nextOf(path);
     if (n) goTo(n);
@@ -503,6 +729,79 @@ document.addEventListener('click', function (e) {
 
 // ── 启动 ──
 
+// 右栏键盘（textarea 常驻可编辑）：Ctrl/Cmd+Enter 立即失焦保存，Esc 还原原文/放弃草稿
+document.addEventListener('DOMContentLoaded', function () {
+  var list = document.getElementById('note-list');
+  if (!list) return;
+  list.addEventListener('keydown', function (e) {
+    var ta = e.target;
+    if (!ta.matches || !ta.matches('[data-note-input]')) return;
+    if (e.key === 'Escape') {
+      var id = ta.getAttribute('data-id');
+      if (id) {
+        var n = noteById(id);
+        if (n) ta.value = n.content; // 还原原文
+      } else {
+        ta.value = '';               // 草稿：清空
+      }
+      autoGrow(ta);
+      ta.blur(); // focusout 委托统一收口（未改动/空草稿都不会落库）
+    } else if ((e.ctrlKey || e.metaKey) && e.key === 'Enter') {
+      ta.blur();
+    }
+  });
+  // 输入即长高
+  list.addEventListener('input', function (e) {
+    if (e.target.matches && e.target.matches('[data-note-input]')) autoGrow(e.target);
+  });
+  // 失焦即存：blur 不冒泡、focusout 冒泡，委托在列表上（innerHTML 重建不丢监听）
+  list.addEventListener('focusout', function (e) {
+    var ta = e.target;
+    if (!ta.matches || !ta.matches('[data-note-input]')) return;
+    var id = ta.getAttribute('data-id');
+    if (id) {
+      var n = noteById(id);
+      if (!n) return;
+      if (ta.value === n.content) return;                                // 未改动
+      if (!ta.value.trim()) { ta.value = n.content; autoGrow(ta); return; } // 清空=还原原文
+      var content = ta.value;
+      queueNoteOp(function () {
+        return postNote({ op: 'edit', id: id, content: content }).then(function (j) {
+          n.content = content;
+          if (j.note && j.note.updatedAt) n.updatedAt = j.note.updatedAt;
+        }).catch(function (err) { noteFail(err); });
+      });
+    } else {
+      var hash = ta.getAttribute('data-hash') || hashAt(path);
+      if (!ta.value.trim()) {                                            // 空草稿=放弃
+        var item = ta.closest('.nside-item');
+        if (item) item.remove();
+        delete draftByHash[hash];
+        updateNoteCount();
+        return;
+      }
+      draftByHash[hash] = ta.value;                                      // 先记着：POST 在途时重渲染不丢
+      var content2 = ta.value;
+      queueNoteOp(function () {
+        return postNote({ op: 'add', hash: hash, content: content2 }).then(function (j) {
+          var note = j.note;
+          if (note) (notesByHash[hash] = notesByHash[hash] || []).push(note);
+          delete draftByHash[hash];
+          ta.setAttribute('data-id', note.id);
+          document.getElementById('side').innerHTML = sideHtml();        // 徽标 0→N
+          updateNoteCount();
+        }).catch(function (err) { noteFail(err); });
+      });
+    }
+  });
+});
+
+// 右栏舌片事件接线（元素静态在 HTML；提示文案等 lang.js 就绪，故挂 DOMContentLoaded）
+document.addEventListener('DOMContentLoaded', function () {
+  wireNoteToggle();
+  applyNotesOpen();
+});
+
 // 语言切换：侧栏大纲与内容区一并重绘
 POP_I18N.onChange(function () {
   if (doc) document.getElementById('side').innerHTML = sideHtml();
@@ -511,6 +810,45 @@ POP_I18N.onChange(function () {
 
 var HASH = decodeURIComponent((location.pathname.split('/pop/')[1] || '').replace(/\.json$/, ''));
 
+// nodeIndex（哈希→路径）逆成 hashByPath（路径→哈希）：笔记按哈希钉，侧栏/节点卡按路径定位
+function buildHashByPath() {
+  hashByPath = {};
+  if (!nodeIndex) return;
+  for (var h in nodeIndex) hashByPath[nodeIndex[h].join(',')] = h;
+}
+
+/** 笔记到货后的重绘：只动左右两栏（侧栏徽标 + 右栏），内容区不碰——
+ *  笔记不进内容区，动它只会带来无谓的重绘与闪烁。
+ *  侧栏是整段 innerHTML 重建，重建后必须补回 tab 选中态与当前节点高亮 */
+function onNotesArrived() {
+  if (!doc) return;
+  document.getElementById('side').innerHTML = sideHtml();
+  updateTabs();
+  markSide();
+  renderNoteSide();
+}
+
+function loadNotesData() {
+  fetch('/api/notes?ref=' + encodeURIComponent(HASH))
+    .then(function (r) { return r.ok ? r.json() : { notes: [] }; })
+    .then(function (j) {
+      notesByHash = {};
+      (j.notes || []).forEach(function (n) {
+        (notesByHash[n.hash] = notesByHash[n.hash] || []).push(n);
+      });
+      // 默认折叠；首载本文档有笔记则自动展开（用户手动开合过就不再自动介入）
+      if (!notesTouched && (j.notes || []).length) notesOpen = true;
+      onNotesArrived();
+    })
+    .catch(function () { /* 笔记是锦上添花：拉取失败静默，文档照常显示 */ });
+}
+
+// 另一终端写笔记（CLI/别的页面）→ 服务器发 notes 轻事件 → 只重拉笔记，绝不整刷。
+// reconcile 会保留未落库改动与聚焦位，编辑中收到推送也不丢字
+document.addEventListener('practi:notes', function () {
+  loadNotesData();
+});
+
 fetch('/doc/' + encodeURIComponent(HASH) + '.json')
   .then(function (r) {
     if (!r.ok) throw new Error('HTTP ' + r.status);
@@ -520,9 +858,11 @@ fetch('/doc/' + encodeURIComponent(HASH) + '.json')
     // 数据窗=加法演进：树字段在顶层，nodeIndex 是后加的兄弟键（老响应没有它 → 哈希兜底）
     doc = d;
     nodeIndex = d.nodeIndex || null;
+    buildHashByPath();
     document.title = doc.name + ' — practi';
     document.getElementById('side').innerHTML = sideHtml();
     render();
+    loadNotesData();
   })
   .catch(function (err) {
     document.getElementById('app').innerHTML =

package/web-default/lang.js

@@ -15,7 +15,7 @@ var POP_I18N = (function () {
       labelDocJson: '文档 JSON', labelSvJson: 'StandardView JSON',
       // 目录页
       pageTitle: '我的实践',
-      thDocument: '文档', thSteps: '步骤', thAdded: '添加时间',
+      thDocument: '文档', thNodes: '节点', thAdded: '添加时间',
       emptyLead: '还没有记录。写下第一手实践经验，成为一份 POP 文档——哈希可验证，永久保存。',
       emptyHint: '用 <code>practi new</code> 创建',
       countDocs: function (n) { return n + ' 篇文档'; },
@@ -23,7 +23,7 @@ var POP_I18N = (function () {
       pagerPrev: '上一页', pagerNext: '下一页',
       loadFail: '加载失败（/api/directs）',
       // 详情页
-      stepCount: function (n) { return n + ' 个步骤'; },
+      nodeCount: function (n) { return n + ' 个节点'; },
       loading: '加载中…',
       opPar: '以下任务并行执行——顺序无关',
       opChoice: '选择一个分支继续',
@@ -41,6 +41,12 @@ var POP_I18N = (function () {
       endPractice: '实践完结',
       revisions: function (n) { return '修订 (' + n + ')'; },
       refines: function (n) { return '改进 (' + n + ')'; },
+      secNotes: function (n) { return '笔记 (' + n + ')'; },
+      notePanel: '笔记',
+      noteNew: '新建',
+      noteDelete: '删除',
+      noteEmpty: '这条节点还没有笔记，点上方「新建」写一条。',
+      noteServerStale: '服务器像是旧构建（前端新、服务器旧）——重启 practi web 再试',
       docFail: function (s) { return '文档加载失败（' + s + '）'; },
       backMine: '← 我的实践'
     },
@@ -49,14 +55,14 @@ var POP_I18N = (function () {
       tabWizard: 'Todo', tabSv: 'StandardView', tabDoc: 'Document',
       labelDocJson: 'Document JSON', labelSvJson: 'StandardView JSON',
       pageTitle: 'My practices',
-      thDocument: 'Document', thSteps: 'Steps', thAdded: 'Added',
+      thDocument: 'Document', thNodes: 'Nodes', thAdded: 'Added',
       emptyLead: 'Nothing recorded yet. Write first-hand experience as a POP document — verifiable by hash, forever.',
       emptyHint: 'create one with <code>practi new</code>',
       countDocs: function (n) { return n + (n === 1 ? ' document' : ' documents'); },
       pageOf: function (a, b) { return 'page ' + a + ' of ' + b; },
       pagerPrev: 'Previous', pagerNext: 'Next',
       loadFail: 'failed to load /api/directs',
-      stepCount: function (n) { return n + (n === 1 ? ' step' : ' steps'); },
+      nodeCount: function (n) { return n + (n === 1 ? ' node' : ' nodes'); },
       loading: 'loading…',
       opPar: 'the tasks below run in parallel — order does not matter',
       opChoice: 'pick one branch to continue',
@@ -74,6 +80,12 @@ var POP_I18N = (function () {
       endPractice: 'end of practice',
       revisions: function (n) { return 'revisions (' + n + ')'; },
       refines: function (n) { return 'refines (' + n + ')'; },
+      secNotes: function (n) { return 'notes (' + n + ')'; },
+      notePanel: 'Notes',
+      noteNew: 'New',
+      noteDelete: 'Delete',
+      noteEmpty: 'No notes on this node yet — click New above to write one.',
+      noteServerStale: 'the server looks like an older build — restart practi web and retry',
       docFail: function (s) { return 'failed to load document (' + s + ')'; },
       backMine: '← My practices'
     }

package/web-default/style.css

@@ -47,13 +47,13 @@ a:hover { text-decoration: underline; }
    fixed 布局是必须的：hash 是无空格长串，auto 布局下 max-width 失效会把表撑出横向滚动 */
 .doc-table { width: 100%; border-collapse: collapse; font-size: 14px; table-layout: fixed; }
 .doc-table th { padding: 8px 16px; font-size: 12px; font-weight: 500; color: var(--brand-50); text-align: left; white-space: nowrap; border-bottom: 1px solid var(--border); }
-.doc-table th.col-steps { width: 8ch; }
+.doc-table th.col-nodes { width: 8ch; }
 .doc-table th.col-added { width: 22ch; }
 .doc-table td { padding: 12px 16px; vertical-align: middle; border-bottom: 1px solid var(--border-light); overflow: hidden; text-overflow: ellipsis; }
 .doc-table tr:last-child td { border-bottom: none; }
 .doc-name { font-weight: 500; color: var(--brand); }
 .doc-desc { font-size: 12px; color: var(--brand-40); margin: 2px 0 0; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
-.doc-steps { font-size: 12px; color: var(--brand-40); font-variant-numeric: tabular-nums; }
+.doc-nodes { font-size: 12px; color: var(--brand-40); font-variant-numeric: tabular-nums; }
 .doc-date { font-size: 12px; color: var(--brand-40); white-space: nowrap; font-variant-numeric: tabular-nums; }
 .doc-date.derived { opacity: .6; }
 .count-row { display: flex; justify-content: space-between; align-items: center; margin-top: 24px; font-size: 14px; color: var(--brand-60); }
@@ -67,7 +67,8 @@ a:hover { text-decoration: underline; }
 .empty code { font-family: ui-monospace, "Cascadia Code", Consolas, monospace; }
 
 /* ── 详情页（向导模式）：一次一节点，op 决定呈现 ── */
-.detail { max-width: 48rem; padding-bottom: 110px; }
+/* 内容列=详情页唯一的滚动容器（应用壳布局）；gutter 常驻防长文档切换时内容左右微移 */
+.detail { max-width: 48rem; overflow-y: auto; scrollbar-gutter: stable; padding-bottom: 110px; }
 .node-title { font-size: 22px; font-weight: 700; color: var(--brand); margin: 8px 0 4px; }
 .node-desc { color: var(--brand-60); margin: 0 0 12px; }
 .op-note { font-size: 13px; color: var(--brand-40); font-style: italic; margin: 0 0 8px; }
@@ -130,7 +131,9 @@ button.child-card:hover { border-color: var(--brand); color: var(--brand); }
 .choice-card:hover { border-color: var(--brand); background: rgba(0, 51, 102, .04); }
 /* 底部导航固定在视口底部：位置恒定，不随内容高度漂移；内行与正文列同宽对齐 */
 /* 底部操作区：固定视口底悬浮于内容列上方，无分界线（仅极轻投影托起），行与正文列同宽 */
-.nav { position: fixed; left: 0; right: 0; bottom: 0; z-index: 10; background: #fff; padding: 10px 24px; box-shadow: 0 -1px 8px rgba(0, 51, 102, .03); }
+.nav { position: fixed; left: 0; right: 0; bottom: 0; z-index: 10; background: #fff; padding: 10px 24px; box-shadow: 0 -1px 8px rgba(0, 51, 102, .03); transition: right .25s ease; }
+/* 笔记栏展开时操作区同步让位（与内容列居中一起平滑重排） */
+body.note-open .nav { right: 18rem; }
 .nav-row { max-width: 48rem; margin: 0 auto; display: flex; justify-content: space-between; align-items: center; gap: 12px; }
 .btn { padding: 8px 16px; border: 1px solid #d1d5db; border-radius: 8px; background: #fff; color: var(--brand-60); font-size: 14px; cursor: pointer; text-decoration: none; display: inline-block; }
 .btn:hover { background: var(--hover-bg); text-decoration: none; }
@@ -138,8 +141,10 @@ button.child-card:hover { border-color: var(--brand); color: var(--brand); }
 .btn-primary:hover { background: #1f2937; }
 .nav-hint { font-size: 13px; color: var(--brand-40); }
 .finish { font-size: 13px; color: var(--brand-40); }
-/* ── 详情页外壳：左侧大纲栏（sticky 侧栏）+ 内容列；窄屏侧栏隐藏回单列 ── */
-.shell { display: flex; align-items: flex-start; }
+/* ── 详情页外壳：应用壳布局——整页不滚（滚动只属于中间内容列），header 常驻、左右栏满高 ── */
+body.detail-page { height: 100dvh; overflow: hidden; display: flex; flex-direction: column; }
+body.detail-page > header { flex: none; }
+.shell { display: flex; align-items: stretch; flex: 1; min-height: 0; position: relative; }
 .shell main { flex: 1; min-width: 0; }
 .side { display: none; }
 .side-count { font-size: 12px; font-weight: 500; color: var(--brand-40); margin: 0 0 8px; }
@@ -159,7 +164,7 @@ a.side-note:hover { color: var(--brand); text-decoration: none; background: rgba
 /* 档案底仓：钉在侧栏最底（flex 末位），大纲长过侧栏时随滚动自然跟在内容后 */
 .side-foot { margin-top: auto; padding-top: 4px; }
 @media (min-width: 1024px) {
-  .side { display: flex; flex-direction: column; position: sticky; top: 49px; height: calc(100dvh - 49px); overflow-y: auto; width: 16rem; flex: none; border-right: 1px solid var(--border); background: #f8fafc; padding: 12px 14px 24px; }
+  .side { display: flex; flex-direction: column; overflow-y: auto; width: 16rem; flex: none; border-right: 1px solid var(--border); background: #f8fafc; padding: 12px 14px 24px; }
   /* 操作区只覆盖内容列：left 让出侧栏，侧栏档案区完整可见 */
   .nav { left: 16rem; }
 }
@@ -179,4 +184,51 @@ a.side-note:hover { color: var(--brand); text-decoration: none; background: rgba
 /* revisions 折叠：节点自己的变更史，默认收起，好奇点开 */
 /* revisions 折叠已删：revisions/refines 汇总挪到左侧大纲底部（.side-sec） */
 
+/* 学习笔记：只住右侧笔记栏（内容区不出现）；note-time 由右栏条目复用 */
+.note-time { display: block; font-size: 12px; color: var(--brand-40); font-variant-numeric: tabular-nums; margin-bottom: 2px; }
+/* 侧栏大纲的笔记数徽标：实心、可点（跳到该节点并展开笔记栏），
+   边框/文字继承所在条目的颜色（currentColor）——普通态/选中态/根标题自动同色 */
+.note-badge { display: inline-block; min-width: 14px; height: 13px; line-height: 13px; padding: 0 4px; border-radius: 999px; background: var(--primary); color: #f8fafc; font-size: 9px; font-weight: 600; text-align: center; margin-left: 5px; vertical-align: middle; cursor: pointer; }
+.note-badge:hover { background: #374151; }
+
+/* ── 右侧笔记栏：布局列（非悬浮）——宽度 0↔18rem 平滑过渡，内容列随之在两栏之间保持居中 ── */
+#note-side { flex: none; width: 0; overflow: hidden; align-self: stretch; transition: width .25s ease; }
+#note-side.open { width: 18rem; }
+/* 内层定宽：动画期间内容不被挤压，从右缘逐步露出（抽屉观感）；边框/投影挂内层，
+   收起宽度 0 时被 overflow 裁掉，不留残线 */
+#note-list { width: 18rem; height: 100%; overflow-y: auto; overflow-x: hidden; display: flex; flex-direction: column; background: #f8fafc; border-left: 1px solid var(--border); box-shadow: 0 0 24px rgba(0, 51, 102, .08); padding: 14px 14px 16px; }
+/* 展开收起舌片：钉在面板左缘垂直居中（面板的相邻兄弟，right 与面板宽度同参数过渡即贴合）；
+   收起后停在屏幕右缘仍可点 */
+#note-toggle { position: absolute; right: 0; top: 50%; transform: translateY(-50%); width: 26px; height: 56px; display: flex; align-items: center; justify-content: center; border: 1px solid var(--border); border-right: none; border-radius: 8px 0 0 8px; background: #f8fafc; color: var(--brand-40); cursor: pointer; z-index: 5; transition: right .25s ease; }
+#note-side.open + #note-toggle { right: 18rem; }
+#note-toggle:hover { color: var(--brand); }
+/* 箭头语义=面板去向：收起态朝左（展开=面板从右缘向左滑出），展开态朝右（收起=向右滑走） */
+#note-toggle svg { width: 14px; height: 14px; transition: transform .25s ease; transform: rotate(180deg); }
+#note-side.open + #note-toggle svg { transform: rotate(0deg); }
+.nside-head { display: flex; align-items: center; justify-content: space-between; gap: 8px; margin-bottom: 10px; }
+.nside-title { margin: 0; font-size: 12px; font-weight: 600; color: var(--brand-50); }
+/* 新建按钮：面板头部的小胶囊 */
+.nside-new { flex: none; display: inline-flex; align-items: center; justify-content: center; border: none; background: transparent; color: var(--brand-40); cursor: pointer; padding: 2px; }
+.nside-new svg { width: 12px; height: 12px; }
+.nside-new:hover { color: var(--brand); }
+/* 头部贴面板顶+右缘：气泡朝下开、右缘对齐，避免被 #note-list 的 overflow 裁掉 */
+.nside-new[data-tip]::after { left: auto; right: 0; bottom: auto; top: calc(100% + 6px); transform: none; }
+.nside-empty { font-size: 12px; line-height: 1.6; color: var(--brand-40); margin: 0 0 10px; }
+.nside-err { font-size: 12px; line-height: 1.5; color: #b91c1c; background: #fef2f2; border: 1px solid #fecaca; border-radius: 8px; padding: 6px 10px; margin: 0 0 10px; overflow-wrap: break-word; }
+.nside-item { background: #fff; border: 1px solid var(--border); border-radius: 10px; padding: 8px 10px; margin-bottom: 8px; }
+.nside-meta { display: flex; align-items: center; justify-content: space-between; gap: 6px; margin-bottom: 3px; }
+.nside-acts { display: inline-flex; gap: 2px; }
+.nside-act { display: inline-flex; align-items: center; justify-content: center; width: 24px; height: 24px; border: none; border-radius: 6px; background: transparent; color: var(--brand-30); cursor: pointer; }
+.nside-act svg { width: 13px; height: 13px; }
+.nside-act:hover { background: var(--hover-bg); color: var(--brand); }
+.nside-item .note-time { font-size: 11px; }
+/* 行内编辑态与底部新增框共用输入框形态 */
+.nside-input { display: block; width: 100%; border: none; background: transparent; resize: none; overflow: hidden; padding: 0; margin: 0; color: var(--brand-60); font-family: inherit; font-size: 13px; line-height: 1.6; cursor: default; caret-color: transparent; transition: color .15s ease; }
+/* 支持 field-sizing 的浏览器：输入框只占文字本身宽度——点卡片空白处不会出现光标，
+   点文字才进编辑且光标落在点击处；autoGrow 在 JS 侧对支持的浏览器跳过 */
+@supports (field-sizing: content) {
+  .nside-input { field-sizing: content; width: auto; min-width: 24px; max-width: 100%; min-height: 0; }
+}
+.nside-input:focus { outline: none; cursor: text; caret-color: auto; color: var(--primary); }
+
 /* LR kick */