mellos-mapping 0.12.1 → 0.15.0

package/README.md

@@ -125,7 +125,10 @@ session's working directory instead: the state file lands in your project,
 same as under Claude Code. The registered path is version-specific — re-run
 the script after updating the plugin.
 
-To watch the live pane beside a Codex session, run
+To watch the live pane beside a Codex session on Windows, run
+`node <plugin root>/scripts/open-pane.mjs <project dir>` — it splits the
+terminal window hosting the session (or falls back to a dedicated
+"mellos-mapping" window; `--window` picks that on purpose). Elsewhere run
 `node <plugin root>/dist/watch.mjs` from the project directory in a second
 terminal (or any terminal split).
 
@@ -154,7 +157,10 @@ get the four `mmap_*` tools and the pane, and bring their own prompting.
    declare the ghost design and keep the map current as it works.
 2. Run `/mellos-mapping:mmap` to open the live pane (Windows Terminal split
    on Windows, tmux split inside tmux, or a printed command to run in any
-   second terminal). Prefer `--ascii` if your font lacks box-drawing glyphs.
+   second terminal). On Windows the pane opens in the terminal window
+   hosting YOUR session, even with several windows open; pass `--window` to
+   put the map in its own dedicated window instead. Prefer `--ascii` if
+   your font lacks box-drawing glyphs.
 3. Watch nodes light up from the bottom. Interrupt when the picture worries
    you — that is what it is for.
 

package/README.zh-CN.md

@@ -115,8 +115,11 @@ node ~/.codex/plugins/cache/mellos-mapping/mellos-mapping/<版本>/scripts/codex
 项目里，与 Claude Code 下行为一致。注册的是版本相关的绝对路径——插件
 更新后重跑一次脚本即可。
 
-要在 Codex 会话旁边看实况面板，在项目目录下的第二个终端（或任意分屏）
-运行 `node <插件根>/dist/watch.mjs`。
+要在 Codex 会话旁边看实况面板，Windows 上运行
+`node <插件根>/scripts/open-pane.mjs <项目目录>`——它会在承载本会话的
+终端窗口里分屏（识别不到就确定性地开到专属的 "mellos-mapping" 窗口；
+`--window` 则是主动选择专属窗口）。其他环境在项目目录下的第二个终端
+（或任意分屏）运行 `node <插件根>/dist/watch.mjs`。
 
 ## 任意 MCP 客户端
 
@@ -143,7 +146,9 @@ npx -y -p mellos-mapping mellos-mapping-watch
    设计，并在工作过程中保持地图与现实一致。
 2. 运行 `/mellos-mapping:mmap` 打开实况分屏（Windows 上是 Windows
    Terminal 分屏，tmux 里是 tmux 分屏，其他环境会打印一条命令让你在
-   第二个终端里运行）。字体缺少制表符字形时用 `--ascii`。
+   第二个终端里运行）。Windows 上即使开着多个终端窗口，分屏也会落在
+   **你的会话所在的窗口**；想让地图独占一个窗口就加 `--window`。字体
+   缺少制表符字形时用 `--ascii`。
 3. 看着节点从底部一路亮起。图让你不安的时候就打断它——这正是它存在的
    意义。
 

package/dist/server.mjs

@@ -21390,7 +21390,7 @@ function removeLayer(map, id) {
 
 // src/render/render.ts
 var ZOOM_MIN = -4;
-var ZOOM_MAX = 1;
+var ZOOM_MAX = 2;
 var ZOOM_DEFAULT = 0;
 function clampZoom(n) {
   return Math.max(ZOOM_MIN, Math.min(ZOOM_MAX, Math.round(n)));
@@ -21668,10 +21668,14 @@ function neutralSkin(unicode) {
 var BOX_H = 3;
 var BOX_GAP = 2;
 var LEFT_MARGIN = 2;
+var DETAIL_BUDGET = { innerMin: 22, innerMax: 32, noteRows: 3 };
+var DETAIL_PLUS_BUDGET = { innerMin: 30, innerMax: 48, noteRows: 12 };
 function zoomGeometry(zoom) {
   switch (zoom) {
+    case 2:
+      return { mode: "detail", scale: 1, pad: 1, boxGap: BOX_GAP, breathe: 1, titleGap: 1, barGap: 1, bandCounts: false, detail: DETAIL_PLUS_BUDGET };
     case 1:
-      return { mode: "detail", scale: 1, pad: 1, boxGap: BOX_GAP, breathe: 1, titleGap: 1, barGap: 1, bandCounts: false };
+      return { mode: "detail", scale: 1, pad: 1, boxGap: BOX_GAP, breathe: 1, titleGap: 1, barGap: 1, bandCounts: false, detail: DETAIL_BUDGET };
     case 0:
       return { mode: "boxes", scale: 1, pad: 1, boxGap: BOX_GAP, breathe: 1, titleGap: 1, barGap: 1, bandCounts: false };
     case -1:
@@ -21684,9 +21688,6 @@ function zoomGeometry(zoom) {
       return { mode: "constellation", scale: 0, pad: 0, boxGap: BOX_GAP, breathe: 0, titleGap: 0, barGap: 1, bandCounts: true };
   }
 }
-var DETAIL_INNER_MIN = 22;
-var DETAIL_INNER_MAX = 32;
-var DETAIL_NOTE_ROWS = 3;
 var LABEL_BUDGET_MIN = 4;
 function boxSpec(node, geo, unicode, neutral) {
   const glyph = node.kind !== void 0 ? kindGlyph(node.kind, unicode) : void 0;
@@ -21696,14 +21697,15 @@ function boxSpec(node, geo, unicode, neutral) {
   if (geo.mode === "constellation") {
     return { w: 3, h: 1, label: "", pad: 0, borderless: true, extra: [] };
   }
-  if (geo.mode === "detail") {
-    const innerW = Math.min(Math.max(displayWidth(text2) + badgeW + 4, DETAIL_INNER_MIN), DETAIL_INNER_MAX);
+  if (geo.mode === "detail" && geo.detail !== void 0) {
+    const budget2 = geo.detail;
+    const innerW = Math.min(Math.max(displayWidth(text2) + badgeW + 4, budget2.innerMin), budget2.innerMax);
     const extra = [];
     if (node.evidence !== void 0) extra.push({ text: fitWidth(` ${node.evidence}`, innerW), style: "faint" });
     if (node.detail !== void 0) {
       const wrapped = wrapWidth(node.detail, innerW - 2);
-      for (let i = 0; i < Math.min(wrapped.length, DETAIL_NOTE_ROWS); i++) {
-        const cut = i === DETAIL_NOTE_ROWS - 1 && wrapped.length > DETAIL_NOTE_ROWS;
+      for (let i = 0; i < Math.min(wrapped.length, budget2.noteRows); i++) {
+        const cut = i === budget2.noteRows - 1 && wrapped.length > budget2.noteRows;
         extra.push({ text: ` ${cut ? fitWidth(wrapped[i] + "\u2026", innerW - 2) : wrapped[i]}`, style: "none" });
       }
     }
@@ -22513,7 +22515,7 @@ function summarize(map) {
 
 // src/server/server.ts
 var SERVER_NAME = "mellos-mapping";
-var SERVER_VERSION = "0.12.1";
+var SERVER_VERSION = "0.15.0";
 var ID = external_exports.string().regex(/^[a-z0-9][a-z0-9-]{0,63}$/, "lowercase letters, digits and dashes, 1-64 chars").describe("stable kebab-case identifier");
 var PAGE = ID.optional().describe(
   "page (parallel map) this call targets; omit for the default page. One effort = one page: start a NEW effort on its own page named after the effort, so concurrent sessions never write over each other and the pane can switch between pages."

package/dist/watch.mjs

@@ -201,13 +201,15 @@ function updateNode(map, input) {
 
 // src/render/render.ts
 var ZOOM_MIN = -4;
-var ZOOM_MAX = 1;
+var ZOOM_MAX = 2;
 var ZOOM_DEFAULT = 0;
 function clampZoom(n) {
   return Math.max(ZOOM_MIN, Math.min(ZOOM_MAX, Math.round(n)));
 }
 function zoomLabel(zoom) {
   switch (zoom) {
+    case 2:
+      return "detail+";
     case 1:
       return "detail";
     case 0:
@@ -495,10 +497,14 @@ function neutralSkin(unicode) {
 var BOX_H = 3;
 var BOX_GAP = 2;
 var LEFT_MARGIN = 2;
+var DETAIL_BUDGET = { innerMin: 22, innerMax: 32, noteRows: 3 };
+var DETAIL_PLUS_BUDGET = { innerMin: 30, innerMax: 48, noteRows: 12 };
 function zoomGeometry(zoom) {
   switch (zoom) {
+    case 2:
+      return { mode: "detail", scale: 1, pad: 1, boxGap: BOX_GAP, breathe: 1, titleGap: 1, barGap: 1, bandCounts: false, detail: DETAIL_PLUS_BUDGET };
     case 1:
-      return { mode: "detail", scale: 1, pad: 1, boxGap: BOX_GAP, breathe: 1, titleGap: 1, barGap: 1, bandCounts: false };
+      return { mode: "detail", scale: 1, pad: 1, boxGap: BOX_GAP, breathe: 1, titleGap: 1, barGap: 1, bandCounts: false, detail: DETAIL_BUDGET };
     case 0:
       return { mode: "boxes", scale: 1, pad: 1, boxGap: BOX_GAP, breathe: 1, titleGap: 1, barGap: 1, bandCounts: false };
     case -1:
@@ -511,9 +517,6 @@ function zoomGeometry(zoom) {
       return { mode: "constellation", scale: 0, pad: 0, boxGap: BOX_GAP, breathe: 0, titleGap: 0, barGap: 1, bandCounts: true };
   }
 }
-var DETAIL_INNER_MIN = 22;
-var DETAIL_INNER_MAX = 32;
-var DETAIL_NOTE_ROWS = 3;
 var LABEL_BUDGET_MIN = 4;
 function boxSpec(node, geo, unicode, neutral) {
   const glyph = node.kind !== void 0 ? kindGlyph(node.kind, unicode) : void 0;
@@ -523,14 +526,15 @@ function boxSpec(node, geo, unicode, neutral) {
   if (geo.mode === "constellation") {
     return { w: 3, h: 1, label: "", pad: 0, borderless: true, extra: [] };
   }
-  if (geo.mode === "detail") {
-    const innerW = Math.min(Math.max(displayWidth(text) + badgeW + 4, DETAIL_INNER_MIN), DETAIL_INNER_MAX);
+  if (geo.mode === "detail" && geo.detail !== void 0) {
+    const budget2 = geo.detail;
+    const innerW = Math.min(Math.max(displayWidth(text) + badgeW + 4, budget2.innerMin), budget2.innerMax);
     const extra = [];
     if (node.evidence !== void 0) extra.push({ text: fitWidth(` ${node.evidence}`, innerW), style: "faint" });
     if (node.detail !== void 0) {
       const wrapped = wrapWidth(node.detail, innerW - 2);
-      for (let i = 0; i < Math.min(wrapped.length, DETAIL_NOTE_ROWS); i++) {
-        const cut = i === DETAIL_NOTE_ROWS - 1 && wrapped.length > DETAIL_NOTE_ROWS;
+      for (let i = 0; i < Math.min(wrapped.length, budget2.noteRows); i++) {
+        const cut = i === budget2.noteRows - 1 && wrapped.length > budget2.noteRows;
         extra.push({ text: ` ${cut ? fitWidth(wrapped[i] + "\u2026", innerW - 2) : wrapped[i]}`, style: "none" });
       }
     }
@@ -1175,7 +1179,7 @@ var KEY_PAN = {
 function mouseEvent(code, x, y, final) {
   if (code & WHEEL) {
     const down = (code & 1) !== 0;
-    return code & SHIFT ? { kind: "pan", dx: 0, dy: (down ? 1 : -1) * WHEEL_V_STEP } : { kind: "zoom", delta: down ? -1 : 1 };
+    return code & SHIFT ? { kind: "pan", dx: 0, dy: (down ? 1 : -1) * WHEEL_V_STEP } : { kind: "zoom", delta: down ? -1 : 1, at: { x, y } };
   }
   const buttons = code & BUTTON_BITS;
   if (final === "m") return buttons === 0 ? { kind: "mouse-up", x, y } : void 0;
@@ -1271,6 +1275,9 @@ var RESET = "\x1B[0m";
 var PANEL_CONTENT_ROWS = 6;
 var PANEL_ROWS_MIN = 2;
 var MAP_ROWS_MIN = 4;
+function usableColumns(cols) {
+  return Math.max(1, cols - 1);
+}
 function clampPanelRows(wanted, totalRows, tabRows) {
   const largest = totalRows - tabRows - MAP_ROWS_MIN - 2;
   return Math.max(PANEL_ROWS_MIN, Math.min(wanted, largest));
@@ -1302,27 +1309,46 @@ function anchorOffsets(anchor, offset, before, after) {
     y: before.h > 0 ? Math.round(offset.y * after.h / before.h) : 0
   };
 }
-function pageTabRow(tabs, width, unicode) {
-  const segments = [];
-  let col = 1;
-  for (const [index, tab] of tabs.entries()) {
-    const room = width - (col - 1);
-    if (room <= 3) break;
+var TAB_INDICATOR_W = 3;
+function pageTabRow(tabs, width, unicode, scroll = 0) {
+  const texts = tabs.map((tab) => {
     const marker = tab.active ? unicode ? "\u25CF" : "*" : unicode ? "\u25CB" : "o";
     const glyph = STATUS_GLYPH[tab.status][unicode ? 0 : 1];
-    const text = fitWidth(tab.neutral === true ? ` ${marker} ${tab.title} ` : ` ${marker} ${glyph} ${tab.title} `, room);
+    return tab.neutral === true ? ` ${marker} ${tab.title} ` : ` ${marker} ${glyph} ${tab.title} `;
+  });
+  const sgrOf = (tab) => tab.neutral === true ? tab.active ? "1" : tab.fresh ? "36" : "90" : tab.active ? `${STATUS_SGR[tab.status]};1` : tab.fresh ? STATUS_SGR[tab.status] : "90";
+  const widths = texts.map(displayWidth);
+  const count = tabs.length;
+  let lo = 0;
+  let hi = count - 1;
+  if (widths.reduce((a, b) => a + b, 0) > width) {
+    lo = Math.max(0, Math.min(scroll, count - 1));
+    hi = lo;
+    const cost = (l, h) => widths.slice(l, h + 1).reduce((a, b) => a + b, 0) + (l > 0 ? TAB_INDICATOR_W : 0) + (h < count - 1 ? TAB_INDICATOR_W : 0);
+    while (hi + 1 < count && cost(lo, hi + 1) <= width) hi++;
+  }
+  const segments = [];
+  let col = 1;
+  const push = (text, sgr, action) => {
     const w = displayWidth(text);
-    segments.push({
-      text,
-      sgr: tab.neutral === true ? tab.active ? "1" : tab.fresh ? "36" : "90" : tab.active ? `${STATUS_SGR[tab.status]};1` : tab.fresh ? STATUS_SGR[tab.status] : "90",
-      lo: col,
-      hi: col + w - 1,
-      index
-    });
+    segments.push({ text, sgr, lo: col, hi: col + w - 1, action });
     col += w;
+  };
+  if (lo > 0) push(unicode ? " \u2039 " : " < ", "90", { kind: "scroll", delta: -1 });
+  const tail = hi < count - 1 ? TAB_INDICATOR_W : 0;
+  for (let i = lo; i <= hi; i++) {
+    push(fitWidth(texts[i], Math.max(1, width - (col - 1) - tail)), sgrOf(tabs[i]), { kind: "switch", index: i });
   }
+  if (hi < count - 1) push(unicode ? " \u203A " : " > ", "90", { kind: "scroll", delta: 1 });
   return segments;
 }
+function tabScrollFor(tabs, width, unicode, scroll, index) {
+  if (index <= scroll) return Math.max(0, index);
+  const visibleAt = (s2) => pageTabRow(tabs, width, unicode, s2).some((seg) => seg.action.kind === "switch" && seg.action.index === index);
+  let s = Math.max(0, Math.min(scroll, tabs.length - 1));
+  while (s < index && !visibleAt(s)) s++;
+  return s;
+}
 function topLevelFiles(defaultFile, files, mapOf) {
   const refs = /* @__PURE__ */ new Set();
   for (const m of mapOf.values()) {
@@ -1442,6 +1468,131 @@ function nodePanel(map, focusId, unicode, width, pinned, rows = PANEL_CONTENT_RO
   }
   return lines.slice(0, rows);
 }
+var SPLASH_FONT = {
+  M: ["#   #", "## ##", "# # #", "#   #", "#   #"],
+  E: ["####", "#", "###", "#", "####"],
+  L: ["#", "#", "#", "#", "####"],
+  O: [" ###", "#   #", "#   #", "#   #", " ###"],
+  S: [" ####", "#", " ###", "    #", "####"],
+  A: [" ###", "#   #", "#####", "#   #", "#   #"],
+  P: ["####", "#   #", "####", "#", "#"],
+  I: ["###", " #", " #", " #", "###"],
+  N: ["#   #", "##  #", "# # #", "#  ##", "#   #"],
+  G: [" ####", "#", "#  ##", "#   #", " ###"]
+};
+var SPLASH_ROWS = 5;
+var SPLASH_SHADES = {
+  unicode: ["\u2591", "\u2591", "\u2592", "\u2592", "\u2593", "\u2593", "\u2588", "\u2588"],
+  ascii: [".", ".", ":", ":", "=", "=", "#", "#"]
+};
+var WAVE_RAMP = [17, 18, 19, 61, 24, 25, 31, 37, 44, 45, 51, 87, 123, 159, 195];
+var SPINNER_FRAMES = {
+  unicode: ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"],
+  ascii: ["|", "/", "-", "\\"]
+};
+function wordArt(word) {
+  const glyphs = [...word.toUpperCase()].map((ch) => SPLASH_FONT[ch]).filter((g) => g !== void 0);
+  const widths = glyphs.map((g) => Math.max(...g.map((r) => r.length)));
+  const rows = [];
+  for (let r = 0; r < SPLASH_ROWS; r++) {
+    rows.push(glyphs.map((g, i) => (g[r] ?? "").padEnd(widths[i], " ")).join(" "));
+  }
+  return rows;
+}
+function splashArt() {
+  const words = [wordArt("MELLOS"), wordArt("MAPPING")];
+  const width = Math.max(...words.flat().map((r) => r.length));
+  const centered = words.map((rows) => {
+    const own = Math.max(...rows.map((r) => r.length));
+    return rows.map((r) => " ".repeat(Math.floor((width - own) / 2)) + r);
+  });
+  return [...centered[0], "", ...centered[1]];
+}
+var WAVE_INTERVAL = 18;
+var WAVE_LIFETIME = 64;
+var WAVE_SPEED = 0.9;
+var WAVE_ENVELOPE = 10;
+var WAVE_NUMBER = 0.42;
+var WAVE_LEVELS = 7;
+var WAVE_GAIN = 4.5;
+function waveHash(n) {
+  let h = Math.imul(n + 1, 2654435761) >>> 0;
+  h ^= h >>> 15;
+  h = Math.imul(h, 2246822519) >>> 0;
+  h ^= h >>> 13;
+  return h >>> 0;
+}
+var WAVE_CORNERS = [
+  [0, 0],
+  [1, 0],
+  [0, 1],
+  [1, 1]
+];
+function liveRipples(frame, width, height) {
+  const out = [];
+  const first = Math.floor((frame - WAVE_LIFETIME - WAVE_INTERVAL) / WAVE_INTERVAL);
+  const last = Math.floor(frame / WAVE_INTERVAL);
+  for (let n = Math.max(0, first); n <= last; n++) {
+    const h = waveHash(n);
+    const age = frame - (n * WAVE_INTERVAL + h % WAVE_INTERVAL);
+    if (age < 0 || age > WAVE_LIFETIME) continue;
+    const [fx, fy] = WAVE_CORNERS[h % WAVE_CORNERS.length];
+    out.push({
+      ox: fx * (width - 1),
+      oy: fy * (height - 1),
+      r: age * WAVE_SPEED,
+      fade: 1 - age / WAVE_LIFETIME
+    });
+  }
+  return out;
+}
+function waveAt(ripples, x, y) {
+  let value = 0;
+  for (const w of ripples) {
+    const front = Math.hypot(x - w.ox, (y - w.oy) * 2) - w.r;
+    value += Math.cos(front * WAVE_NUMBER) * Math.exp(-(front * front) / (2 * WAVE_ENVELOPE ** 2)) * w.fade;
+  }
+  return value;
+}
+function waveLevel(value) {
+  return Math.max(-WAVE_LEVELS, Math.min(WAVE_LEVELS, Math.round(value * WAVE_GAIN)));
+}
+function splashFrame(notice, frame, width, height, unicode, color) {
+  const art = splashArt();
+  const artWidth = Math.max(...art.map((r) => r.length));
+  if (width < artWidth + 2 || height < art.length + 2) return void 0;
+  const mode = unicode ? "unicode" : "ascii";
+  const shades = SPLASH_SHADES[mode];
+  const solid = shades[shades.length - 1];
+  const indent = " ".repeat(Math.floor((width - artWidth) / 2));
+  const ripples = liveRipples(frame, artWidth, art.length);
+  const inkOf = (x, y) => {
+    const level = waveLevel(waveAt(ripples, x, y));
+    return color ? `38;5;${WAVE_RAMP[WAVE_LEVELS + level]}` : shades[Math.abs(level)];
+  };
+  const paintRow = (row, y) => {
+    const cells = [...row].map((ch, x) => ch === "#" ? inkOf(x, y) : void 0);
+    let out = "";
+    for (let i = 0; i < cells.length; ) {
+      const cell = cells[i];
+      let j = i;
+      while (j < cells.length && cells[j] === cell) j++;
+      if (cell === void 0) out += " ".repeat(j - i);
+      else out += color ? `\x1B[${cell}m${solid.repeat(j - i)}${RESET}` : cell.repeat(j - i);
+      i = j;
+    }
+    return out;
+  };
+  const spinner = SPINNER_FRAMES[mode];
+  const status = fitWidth(`${spinner[frame % spinner.length]} ${notice}`, Math.max(1, width - 2));
+  const statusIndent = " ".repeat(Math.max(0, Math.floor((width - displayWidth(status)) / 2)));
+  const block = [
+    ...art.map((row, y) => row.trim() === "" ? "" : indent + paintRow(row, y)),
+    "",
+    statusIndent + (color ? `\x1B[90m${status}${RESET}` : status)
+  ];
+  return [...Array.from({ length: Math.max(0, Math.floor((height - block.length) / 2)) }, () => ""), ...block];
+}
 function mapPanel(map, unicode, width, rows = PANEL_CONTENT_ROWS) {
   const g = (s) => STATUS_GLYPH[s][unicode ? 0 : 1];
   const count = (s) => map.nodes.filter((n) => n.status === s).length;
@@ -1466,6 +1617,7 @@ function main() {
   const mouseActive = interactive && cfg.mouse;
   let lastFrame = "";
   let spinnerFrame = 0;
+  let splashTick = 0;
   let map;
   let notice = `waiting for ${cfg.file} ...`;
   let lastCols = process.stdout.columns ?? 0;
@@ -1476,6 +1628,7 @@ function main() {
   let activeFile;
   let firstScan = true;
   let lastTabSegments = [];
+  let tabScroll = 0;
   let offsetX = 0;
   let offsetY = 0;
   let zoom = ZOOM_DEFAULT;
@@ -1508,8 +1661,19 @@ function main() {
     }
     return false;
   };
+  const viewWidth = () => usableColumns(process.stdout.columns ?? 100);
   const viewHeight = () => Math.max(1, (process.stdout.rows ?? 30) - (1 + panelContentRows) - 1 - tabRows());
   const dividerY = () => tabRows() + viewHeight() + 1;
+  const pageTabsOf = (files) => files.map((f) => {
+    const m = pageData.get(f)?.map;
+    return {
+      title: m?.title ?? (pageIdOfFile(cfg.file, f) ?? "main"),
+      status: m !== void 0 ? mapStatus(m) : "planned",
+      active: f === activeFile,
+      fresh: pageData.get(f)?.fresh ?? false,
+      neutral: m !== void 0 && isNeutralKind(m)
+    };
+  });
   const switchPage = (file) => {
     if (activeFile !== void 0) pageViews.set(activeFile, { offsetX, offsetY, zoom, selectedId });
     activeFile = file;
@@ -1523,10 +1687,14 @@ function main() {
     if (entry !== void 0 && entry.fresh) pageData.set(file, { ...entry, fresh: false });
     map = entry?.map;
     notice = map === void 0 ? `waiting for ${file} ...` : "";
+    const top = topFiles();
+    const tabIndex = top.indexOf(file);
+    if (tabIndex >= 0) tabScroll = tabScrollFor(pageTabsOf(top), viewWidth(), cfg.unicode, tabScroll, tabIndex);
   };
   const hitTest = (termX, termY) => {
     const sx = termX - 1;
     const sy = termY - 1 - tabRows();
+    if (sx < 0 || sx >= viewWidth()) return void 0;
     if (sy < 0 || sy >= viewHeight()) return void 0;
     const cx = sx + offsetX;
     const cy = sy + offsetY;
@@ -1541,6 +1709,7 @@ function main() {
   process.on("SIGTERM", restore);
   const paint = () => {
     const cols = process.stdout.columns ?? 100;
+    const viewW = viewWidth();
     panelContentRows = clampPanelRows(panelContentRows, process.stdout.rows ?? 30, tabRows());
     const viewH = viewHeight();
     const focus = hoverId ?? selectedId;
@@ -1551,9 +1720,9 @@ function main() {
       const windowed = renderMapWindow(
         map,
         { color: cfg.color, unicode: cfg.unicode, spinnerFrame, focus, zoom },
-        { x: offsetX, y: offsetY, width: cols, height: viewH }
+        { x: offsetX, y: offsetY, width: viewW, height: viewH }
       );
-      const maxX = Math.max(0, windowed.contentWidth - cols);
+      const maxX = Math.max(0, windowed.contentWidth - viewW);
       const maxY = Math.max(0, windowed.contentHeight - viewH);
       if (offsetX > maxX || offsetY > maxY || offsetX < 0 || offsetY < 0) {
         offsetX = Math.min(Math.max(0, offsetX), maxX);
@@ -1567,10 +1736,10 @@ function main() {
       lastContent = { w: windowed.contentWidth, h: windowed.contentHeight };
       if (offsetX !== 0 || offsetY !== 0) panned = `  (+${offsetX},+${offsetY})`;
     } else {
-      body = [fitWidth(notice, Math.max(1, cols - 1))];
+      body = (interactive ? splashFrame(notice, splashTick, viewW, viewH, cfg.unicode, cfg.color) : void 0) ?? [fitWidth(notice, viewW)];
     }
     if (notice !== "" && map !== void 0) {
-      body[body.length - 1] = fitWidth(`  ${notice}`, Math.max(1, cols - 1));
+      body[body.length - 1] = fitWidth(`  ${notice}`, viewW);
     }
     const panelWidth = Math.max(10, cols - 2);
     let panel;
@@ -1582,9 +1751,9 @@ function main() {
       panel = mapPanel(map, cfg.unicode, panelWidth, panelContentRows);
     }
     const grip = cfg.unicode ? " \u22EF " : " ~ ";
-    const bar = (cfg.unicode ? "\u2500" : "-").repeat(cols);
-    const gripAt = Math.max(0, Math.floor((cols - grip.length) / 2));
-    const separator = cols > grip.length + 2 ? bar.slice(0, gripAt) + grip + bar.slice(gripAt + grip.length) : bar;
+    const bar = (cfg.unicode ? "\u2500" : "-").repeat(viewW);
+    const gripAt = Math.max(0, Math.floor((viewW - grip.length) / 2));
+    const separator = viewW > grip.length + 2 ? bar.slice(0, gripAt) + grip + bar.slice(gripAt + grip.length) : bar;
     const panelRows = [
       cfg.color ? `\x1B[90m${separator}${RESET}` : separator,
       ...panel.map(
@@ -1600,29 +1769,19 @@ function main() {
       const parentTitle = parentFile !== void 0 ? pageData.get(parentFile)?.map?.title ?? (pageIdOfFile(cfg.file, parentFile) ?? "main") : "main";
       const nodeLabel = scanned?.label ?? map?.title ?? "";
       const crumbHead = ` ${cfg.unicode ? "\u232B" : "<"} ${parentTitle} ${cfg.unicode ? "\u25B8" : ">"} `;
-      const head = { text: crumbHead, sgr: "90", lo: 1, hi: displayWidth(crumbHead), index: -1 };
-      const tailText = fitWidth(`${nodeLabel} `, Math.max(1, cols - displayWidth(crumbHead)));
+      const head = { text: crumbHead, sgr: "90", lo: 1, hi: displayWidth(crumbHead), action: { kind: "back" } };
+      const tailText = fitWidth(`${nodeLabel} `, Math.max(1, viewW - displayWidth(crumbHead)));
       const tail = {
         text: tailText,
         sgr: "1",
         lo: head.hi + 1,
         hi: head.hi + displayWidth(tailText),
-        index: -1
+        action: { kind: "back" }
       };
       lastTabSegments = [head, tail];
       tabLine = lastTabSegments.map((s) => cfg.color && s.sgr !== "" ? `\x1B[${s.sgr}m${s.text}${RESET}` : s.text).join("");
     } else if (tabRows() > 0) {
-      const tabs = lastTabFiles.map((f) => {
-        const m = pageData.get(f)?.map;
-        return {
-          title: m?.title ?? (pageIdOfFile(cfg.file, f) ?? "main"),
-          status: m !== void 0 ? mapStatus(m) : "planned",
-          active: f === activeFile,
-          fresh: pageData.get(f)?.fresh ?? false,
-          neutral: m !== void 0 && isNeutralKind(m)
-        };
-      });
-      const segments = pageTabRow(tabs, cols, cfg.unicode);
+      const segments = pageTabRow(pageTabsOf(lastTabFiles), viewW, cfg.unicode, tabScroll);
       lastTabSegments = segments;
       tabLine = segments.map((s) => cfg.color && s.sgr !== "" ? `\x1B[${s.sgr}m${s.text}${RESET}` : s.text).join("");
     } else {
@@ -1630,7 +1789,7 @@ function main() {
     }
     const zoomTag = `${cfg.unicode ? "\u2295" : "zoom"} ${zoomLabel(zoom)}`;
     const hint = !interactive ? cfg.file : (flash !== void 0 ? `${flash.text} \xB7 ` : "") + `${zoomTag} \xB7 wheel zoom \xB7 ` + (pannable ? "drag pan \xB7 " : "") + "hover/click \xB7 0 reset \xB7 q quit";
-    const footerText = fitWidth(` ${hint}${panned}`, Math.max(1, cols - 1));
+    const footerText = fitWidth(` ${hint}${panned}`, viewW);
     const footer = cfg.color ? `\x1B[90m${footerText}${RESET}` : footerText;
     let frame = HOME;
     if (tabLine !== void 0) frame += tabLine + ERASE_LINE_END + "\n";
@@ -1723,10 +1882,14 @@ function main() {
             dirty = true;
             break;
           case "zoom": {
+            if (event.at !== void 0 && event.at.y === 1 && tabRows() > 0 && !inSubmap()) {
+              tabScroll = Math.max(0, Math.min(tabScroll + (event.delta === 1 ? -1 : 1), topFiles().length - 1));
+              dirty = true;
+              break;
+            }
             const next = clampZoom(zoom + event.delta);
             if (next === zoom || map === void 0) break;
-            const cols = process.stdout.columns ?? 100;
-            const anchorId = hoverId ?? selectedId ?? nearestHit(lastHits, offsetX + cols / 2, offsetY + viewHeight() / 2)?.id;
+            const anchorId = hoverId ?? selectedId ?? nearestHit(lastHits, offsetX + viewWidth() / 2, offsetY + viewHeight() / 2)?.id;
             const before = lastHits.find((h) => h.id === anchorId);
             zoom = next;
             const sized = renderMapWindow(
@@ -1790,10 +1953,12 @@ function main() {
             if (press && !press.moved) {
               const tabHit = tabRows() > 0 && event.y === 1 ? lastTabSegments.find((s) => event.x >= s.lo && event.x <= s.hi) : void 0;
               if (tabHit !== void 0) {
-                if (tabHit.index === -1) {
+                if (tabHit.action.kind === "back") {
                   climbBack();
+                } else if (tabHit.action.kind === "scroll") {
+                  tabScroll = Math.max(0, Math.min(tabScroll + tabHit.action.delta, lastTabFiles.length - 1));
                 } else {
-                  const target = lastTabFiles[tabHit.index];
+                  const target = lastTabFiles[tabHit.action.index];
                   if (target !== void 0 && target !== activeFile) switchPage(target);
                 }
               } else {
@@ -1854,6 +2019,13 @@ function main() {
   }
   tick();
   setInterval(tick, cfg.intervalMs);
+  if (interactive) {
+    setInterval(() => {
+      if (map !== void 0) return;
+      splashTick++;
+      paint();
+    }, 80);
+  }
 }
 function launchedAsEntry(argv1, moduleUrl) {
   if (argv1 === void 0) return false;
@@ -1868,17 +2040,28 @@ if (launchedAsEntry(process.argv[1], import.meta.url)) {
 }
 export {
   PANEL_ROWS_MIN,
+  WAVE_LEVELS,
+  WAVE_NUMBER,
   anchorOffsets,
   clampPanelRows,
   diveOrigin,
   fitWidth,
   launchedAsEntry,
+  liveRipples,
   mapPanel,
   nearestHit,
   nodePanel,
   pageTabRow,
   panelRowsFromDividerY,
   parseArgs,
+  splashArt,
+  splashFrame,
+  tabScrollFor,
   topLevelFiles,
+  usableColumns,
+  waveAt,
+  waveHash,
+  waveLevel,
+  wordArt,
   wrapWidth
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mellos-mapping",
-  "version": "0.12.1",
+  "version": "0.15.0",
   "mcpName": "io.github.GuangminJu/mellos-mapping",
   "description": "A live layered dependency map for bottom-up development — MCP server + terminal pane. Ghost the design first, then light nodes up from the bottom as they are built and verified.",
   "type": "module",
@@ -33,7 +33,8 @@
   "files": [
     "dist",
     "README.zh-CN.md",
-    "scripts/codex-register.mjs"
+    "scripts/codex-register.mjs",
+    "scripts/open-pane.mjs"
   ],
   "engines": {
     "node": ">=18"

package/scripts/open-pane.mjs

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+/**
+ * Open the live map pane in the RIGHT Windows Terminal window.
+ *
+ *   node scripts/open-pane.mjs <project-dir> [--window] [--ascii] [--force]
+ *
+ * Why this exists: the agent's shell runs on a hidden console (no WT_SESSION),
+ * so a bare `wt -w 0 sp` targets the MOST RECENTLY USED terminal window — with
+ * several windows open the map lands wherever the user last clicked, not
+ * beside the conversation. Verified on Windows 11 / WT single-process mode:
+ * all windows share one WindowsTerminal.exe pid, and the console UI is
+ * attached by default-terminal delegation, so neither pid-matching nor the
+ * process tree can name the hosting window.
+ *
+ * What does work — and what this script does, verifying every step:
+ *
+ *   1. Walk this process's ancestors and AttachConsole to each in turn; write
+ *      a nonce into that console's title. The WT window whose title lights up
+ *      is the one hosting this session. The nonce only shows when the session
+ *      tab is the window's ACTIVE tab — exactly the precondition under which
+ *      `sp` would split beside the conversation, so identification doubles as
+ *      the go/no-go check.
+ *   2. Bring that window to the foreground (plain SetForegroundWindow, then
+ *      the Alt-key unlock, then AttachThreadInput — Windows' foreground lock
+ *      denies the plain call from background processes), verifying with
+ *      GetForegroundWindow after each attempt.
+ *   3. Only then `wt -w 0 sp` — "most recently used" is now provably ours.
+ *
+ * Any step failing falls back to a dedicated window named "mellos-mapping":
+ * deterministic, never a random window. `--window` picks that mode outright
+ * (explicit choice for users who want the map separate from the chat).
+ *
+ * Known race, accepted: if the user focuses a DIFFERENT terminal window in
+ * the ~1s between our focus-verify and wt reading its MRU state, the split
+ * can still land there. The window is at least one the user is actively in.
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const argv = process.argv.slice(2);
+const flags = new Set(argv.filter((a) => a.startsWith('--')));
+const positional = argv.filter((a) => !a.startsWith('--'));
+
+if (positional.length !== 1) {
+  console.error('usage: node scripts/open-pane.mjs <project-dir> [--window] [--ascii] [--force]');
+  process.exit(1);
+}
+if (process.platform !== 'win32') {
+  console.error('open-pane.mjs is Windows Terminal-only — use the tmux/manual route from the command doc.');
+  process.exit(1);
+}
+
+const projectDir = resolve(positional[0]);
+if (!existsSync(projectDir)) {
+  console.error(`project directory does not exist: ${projectDir}`);
+  process.exit(1);
+}
+
+const pluginRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+const watchPath = join(pluginRoot, 'dist', 'watch.mjs');
+if (!existsSync(watchPath)) {
+  console.error(`watcher not found (is the plugin built?): ${watchPath}`);
+  process.exit(1);
+}
+const mapFile = join(projectDir, '.claude', 'mellos-mapping.json');
+
+function runPowerShell(script) {
+  const encoded = Buffer.from(script, 'utf16le').toString('base64');
+  const r = spawnSync(
+    'powershell.exe',
+    ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-EncodedCommand', encoded],
+    { encoding: 'utf8', timeout: 30_000, windowsHide: true },
+  );
+  return r.stdout ?? '';
+}
+
+// One watcher per map file is enough — watch.mjs redraws on change for every
+// viewer of the same file, and piling up panes on repeated /mmap is noise.
+// Matches only watchers this script started (they carry --file <mapFile> on
+// their command line); --force bypasses.
+function watcherAlreadyRunning() {
+  const token = mapFile.replace(/'/g, "''");
+  const out = runPowerShell(
+    `$ErrorActionPreference = 'SilentlyContinue'\n` +
+    `$w = @(Get-CimInstance Win32_Process -Filter "Name='node.exe'" | Where-Object { $_.CommandLine -like '*watch.mjs*' -and $_.CommandLine -like '*${token}*' })\n` +
+    `Write-Output "WATCHERS=$($w.Count)"`,
+  );
+  const m = out.match(/WATCHERS=(\d+)/);
+  return m !== null && Number(m[1]) > 0;
+}
+
+// Prints IDENT=<hwnd|0> and, when identified, FOCUS=<1|0>.
+const IDENTIFY_AND_FOCUS = String.raw`
+$ErrorActionPreference = 'SilentlyContinue'
+Add-Type @"
+using System;
+using System.Text;
+using System.Runtime.InteropServices;
+public class MmapWin {
+  [DllImport("user32.dll")] public static extern bool EnumWindows(EnumWindowsProc cb, IntPtr lp);
+  public delegate bool EnumWindowsProc(IntPtr hWnd, IntPtr lp);
+  [DllImport("user32.dll")] public static extern bool IsWindowVisible(IntPtr hWnd);
+  [DllImport("user32.dll", CharSet=CharSet.Unicode)] public static extern int GetClassName(IntPtr hWnd, StringBuilder sb, int max);
+  [DllImport("user32.dll", CharSet=CharSet.Unicode)] public static extern int GetWindowText(IntPtr hWnd, StringBuilder sb, int max);
+  [DllImport("user32.dll")] public static extern bool SetForegroundWindow(IntPtr hWnd);
+  [DllImport("user32.dll")] public static extern IntPtr GetForegroundWindow();
+  [DllImport("user32.dll")] public static extern bool BringWindowToTop(IntPtr hWnd);
+  [DllImport("user32.dll")] public static extern bool AttachThreadInput(uint a, uint b, bool f);
+  [DllImport("kernel32.dll")] public static extern uint GetCurrentThreadId();
+  [DllImport("user32.dll")] public static extern uint GetWindowThreadProcessId(IntPtr hWnd, out uint pid);
+  [DllImport("user32.dll")] public static extern void keybd_event(byte bVk, byte bScan, uint dwFlags, IntPtr dwExtraInfo);
+  [DllImport("user32.dll")] public static extern bool ShowWindow(IntPtr hWnd, int nCmdShow);
+  [DllImport("user32.dll")] public static extern bool IsIconic(IntPtr hWnd);
+  [DllImport("kernel32.dll")] public static extern bool FreeConsole();
+  [DllImport("kernel32.dll")] public static extern bool AttachConsole(uint pid);
+  [DllImport("kernel32.dll", CharSet=CharSet.Unicode)] public static extern bool SetConsoleTitle(string title);
+  [DllImport("kernel32.dll", CharSet=CharSet.Unicode)] public static extern uint GetConsoleTitle(StringBuilder sb, uint size);
+}
+"@
+function Get-WtWindows {
+  $wins = New-Object System.Collections.ArrayList
+  $cb = {
+    param($h, $lp)
+    if ([MmapWin]::IsWindowVisible($h)) {
+      $cls = New-Object System.Text.StringBuilder 256
+      [void][MmapWin]::GetClassName($h, $cls, 256)
+      if ($cls.ToString() -eq 'CASCADIA_HOSTING_WINDOW_CLASS') {
+        $t = New-Object System.Text.StringBuilder 512
+        [void][MmapWin]::GetWindowText($h, $t, 512)
+        [void]$wins.Add(@{ hwnd = $h.ToInt64(); title = $t.ToString() })
+      }
+    }
+    return $true
+  }
+  [void][MmapWin]::EnumWindows($cb, [IntPtr]::Zero)
+  return ,$wins
+}
+
+$ancestors = @()
+$p = $PID
+for ($i = 0; $i -lt 12 -and $p; $i++) {
+  $proc = Get-CimInstance Win32_Process -Filter "ProcessId=$p"
+  if (-not $proc) { break }
+  if ($i -gt 0) { $ancestors += [uint32]$proc.ProcessId }
+  $p = $proc.ParentProcessId
+}
+
+# The agent CLI (claude/codex/...) is some ancestor holding the console that a
+# WT window renders; hidden-console ancestors just never light a window up.
+$nonce = "__NONCE__"
+$hwnd = [IntPtr]::Zero
+foreach ($apid in $ancestors) {
+  [void][MmapWin]::FreeConsole()
+  if (-not [MmapWin]::AttachConsole($apid)) { continue }
+  $sb = New-Object System.Text.StringBuilder 1024
+  [void][MmapWin]::GetConsoleTitle($sb, 1024)
+  $orig = $sb.ToString()
+  for ($i = 0; $i -lt 6 -and $hwnd -eq [IntPtr]::Zero; $i++) {
+    [void][MmapWin]::SetConsoleTitle($nonce)
+    Start-Sleep -Milliseconds 60
+    foreach ($w in (Get-WtWindows)) {
+      if ($w.title -like "*$nonce*") { $hwnd = [IntPtr]$w.hwnd; break }
+    }
+  }
+  Start-Sleep -Milliseconds 100
+  [void][MmapWin]::SetConsoleTitle($orig)
+  Start-Sleep -Milliseconds 200
+  [void][MmapWin]::FreeConsole()
+  if ($hwnd -ne [IntPtr]::Zero) { break }
+}
+
+if ($hwnd -eq [IntPtr]::Zero) { Write-Output 'IDENT=0'; exit 0 }
+Write-Output "IDENT=$($hwnd.ToInt64())"
+
+if ([MmapWin]::IsIconic($hwnd)) { [void][MmapWin]::ShowWindow($hwnd, 9) }
+$focused = $false
+[void][MmapWin]::SetForegroundWindow($hwnd)
+Start-Sleep -Milliseconds 150
+if ([MmapWin]::GetForegroundWindow() -eq $hwnd) { $focused = $true }
+if (-not $focused) {
+  [MmapWin]::keybd_event(0x12, 0, 0, [IntPtr]::Zero)
+  [void][MmapWin]::SetForegroundWindow($hwnd)
+  [MmapWin]::keybd_event(0x12, 0, 2, [IntPtr]::Zero)
+  Start-Sleep -Milliseconds 150
+  if ([MmapWin]::GetForegroundWindow() -eq $hwnd) { $focused = $true }
+}
+if (-not $focused) {
+  $fgpid = 0
+  $fgThread = [MmapWin]::GetWindowThreadProcessId([MmapWin]::GetForegroundWindow(), [ref]$fgpid)
+  $myThread = [MmapWin]::GetCurrentThreadId()
+  [void][MmapWin]::AttachThreadInput($myThread, $fgThread, $true)
+  [void][MmapWin]::BringWindowToTop($hwnd)
+  [void][MmapWin]::SetForegroundWindow($hwnd)
+  [void][MmapWin]::AttachThreadInput($myThread, $fgThread, $false)
+  Start-Sleep -Milliseconds 150
+  if ([MmapWin]::GetForegroundWindow() -eq $hwnd) { $focused = $true }
+}
+Write-Output "FOCUS=$(if ($focused) { 1 } else { 0 })"
+`;
+
+function paneCommand() {
+  const cmd = ['--title', 'mellos map', '-d', projectDir, 'node', watchPath, '--file', mapFile];
+  if (flags.has('--ascii')) cmd.push('--ascii');
+  return cmd;
+}
+
+function openWt(args, what) {
+  const r = spawnSync('wt', args, { stdio: 'ignore', timeout: 15_000, windowsHide: true });
+  if (r.status !== 0) {
+    console.error(`wt failed to ${what} (exit ${r.status ?? 'timeout'}) — is Windows Terminal installed?`);
+    process.exit(1);
+  }
+}
+
+function openDedicatedWindow(reason) {
+  openWt(['-w', 'mellos-mapping', 'nt', ...paneCommand()], 'open the dedicated window');
+  console.log(`MMAP_PANE mode=window name=mellos-mapping reason=${reason}`);
+  console.log('Map opened in the dedicated "mellos-mapping" window.');
+}
+
+if (!flags.has('--force') && watcherAlreadyRunning()) {
+  console.log('MMAP_PANE already-open');
+  console.log(`A watcher for ${mapFile} is already running — not opening another pane (use --force to override).`);
+  process.exit(0);
+}
+
+if (flags.has('--window')) {
+  openDedicatedWindow('requested');
+  process.exit(0);
+}
+
+const nonce = `MMAP-NONCE-${process.pid}`;
+const out = runPowerShell(IDENTIFY_AND_FOCUS.replaceAll('__NONCE__', nonce));
+const ident = out.match(/IDENT=(\d+)/)?.[1] ?? '0';
+const focused = /FOCUS=1/.test(out);
+
+if (ident === '0') {
+  openDedicatedWindow('session-window-not-identified');
+} else if (!focused) {
+  openDedicatedWindow('session-window-focus-denied');
+} else {
+  // The identified window is foreground right now, so "most recently used"
+  // is deterministically it (see the race note in the header).
+  openWt(['-w', '0', 'sp', '-V', '--size', '0.42', ...paneCommand()], 'split the session window');
+  console.log(`MMAP_PANE mode=split hwnd=${ident}`);
+  console.log('Map opened beside this conversation (vertical split).');
+}