mellos-mapping 0.14.0 → 0.16.0

package/README.md

@@ -128,9 +128,11 @@ the script after updating the plugin.
 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).
+"mellos-mapping" window; `--window` picks that on purpose). Add
+`--page <slug>` to open on a particular page — and with a pane already open,
+rerunning with `--page` retargets it instead of opening another. Elsewhere
+run `node <plugin root>/dist/watch.mjs` (same `--page` flag) from the
+project directory in a second terminal (or any terminal split).
 
 ## Any MCP client
 

package/README.zh-CN.md

@@ -118,8 +118,10 @@ node ~/.codex/plugins/cache/mellos-mapping/mellos-mapping/<版本>/scripts/codex
 要在 Codex 会话旁边看实况面板，Windows 上运行
 `node <插件根>/scripts/open-pane.mjs <项目目录>`——它会在承载本会话的
 终端窗口里分屏（识别不到就确定性地开到专属的 "mellos-mapping" 窗口；
-`--window` 则是主动选择专属窗口）。其他环境在项目目录下的第二个终端
-（或任意分屏）运行 `node <插件根>/dist/watch.mjs`。
+`--window` 则是主动选择专属窗口）。加 `--page <slug>` 指定打开哪一页；
+面板已经开着时，带 `--page` 重跑一次不会再开新面板，而是让现有面板
+切到那一页。其他环境在项目目录下的第二个终端（或任意分屏）运行
+`node <插件根>/dist/watch.mjs`（同样支持 `--page`）。
 
 ## 任意 MCP 客户端
 

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" });
       }
     }
@@ -22131,7 +22133,7 @@ function drawBox(canvas, box, opts, neutral, focused = false) {
 }
 
 // src/store/store.ts
-import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 var STATE_FILE_VERSION = 1;
 var STATE_FILE_RELATIVE_PATH = join(".claude", "mellos-mapping.json");
@@ -22513,7 +22515,7 @@ function summarize(map) {
 
 // src/server/server.ts
 var SERVER_NAME = "mellos-mapping";
-var SERVER_VERSION = "0.14.0";
+var SERVER_VERSION = "0.16.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" });
       }
     }
@@ -963,11 +967,14 @@ function drawBox(canvas, box, opts, neutral, focused = false) {
 }
 
 // src/store/store.ts
-import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 var STATE_FILE_VERSION = 1;
 var STATE_FILE_RELATIVE_PATH = join(".claude", "mellos-mapping.json");
 var PAGES_DIR_NAME = "mellos-mapping.pages";
+function makePageId(raw) {
+  return ID_RULE.test(raw) ? ok(raw) : err({ kind: "invalid-id", raw, rule: ID_RULE_TEXT });
+}
 function pageFilePath(defaultFile, page) {
   return page === void 0 ? defaultFile : join(dirname(defaultFile), PAGES_DIR_NAME, `${page}.json`);
 }
@@ -989,6 +996,35 @@ function listPageFiles(defaultFile) {
   }
   return out;
 }
+var FOCUS_FILE_NAME = "mellos-mapping.focus";
+function focusFilePath(defaultFile) {
+  return join(dirname(defaultFile), FOCUS_FILE_NAME);
+}
+function takeFocusRequest(defaultFile) {
+  const path = focusFilePath(defaultFile);
+  let raw;
+  try {
+    raw = readFileSync(path, "utf8");
+  } catch {
+    return void 0;
+  }
+  try {
+    rmSync(path, { force: true });
+  } catch {
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return void 0;
+  }
+  if (typeof parsed !== "object" || parsed === null) return void 0;
+  const page = parsed.page;
+  if (page === void 0 || page === null) return { page: void 0 };
+  if (typeof page !== "string") return void 0;
+  const id = makePageId(page);
+  return id.ok ? { page: id.value } : void 0;
+}
 function describeStoreError(e) {
   switch (e.kind) {
     case "not-found":
@@ -1175,7 +1211,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;
@@ -1237,11 +1273,17 @@ function parseArgs(argv, cwd) {
   let unicode = true;
   let color = true;
   let mouse = true;
+  let page;
   for (let i = 0; i < argv.length; i++) {
     switch (argv[i]) {
       case "--file":
         file = argv[++i] ?? file;
         break;
+      case "--page": {
+        const parsed = makePageId(argv[++i] ?? "");
+        if (parsed.ok) page = parsed.value;
+        break;
+      }
       case "--interval":
         intervalMs = Math.max(50, Number(argv[++i]) || intervalMs);
         break;
@@ -1258,7 +1300,19 @@ function parseArgs(argv, cwd) {
         break;
     }
   }
-  return { file, intervalMs, unicode, color, mouse };
+  return { file, intervalMs, unicode, color, mouse, page };
+}
+function mostRecentPageFile(files, mtimeOf) {
+  let best;
+  let bestMtime = -Infinity;
+  for (const file of files) {
+    const mtime = mtimeOf(file);
+    if (mtime !== void 0 && mtime > bestMtime) {
+      best = file;
+      bestMtime = mtime;
+    }
+  }
+  return best ?? files[0];
 }
 var HIDE_CURSOR = "\x1B[?25l";
 var SHOW_CURSOR = "\x1B[?25h";
@@ -1271,6 +1325,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 +1359,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()) {
@@ -1601,7 +1677,9 @@ function main() {
   const pageViews = /* @__PURE__ */ new Map();
   let activeFile;
   let firstScan = true;
+  let pendingFocusFile = cfg.page === void 0 ? void 0 : pageFilePath(cfg.file, cfg.page);
   let lastTabSegments = [];
+  let tabScroll = 0;
   let offsetX = 0;
   let offsetY = 0;
   let zoom = ZOOM_DEFAULT;
@@ -1629,13 +1707,24 @@ function main() {
       parent = diveOrigin(cfg.file, activeFile, pageFiles, maps())?.parent;
     }
     if (parent !== void 0 && parent !== activeFile) {
-      switchPage(parent);
+      handSwitch(parent);
       return true;
     }
     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;
@@ -1649,10 +1738,18 @@ 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 handSwitch = (file) => {
+    pendingFocusFile = void 0;
+    switchPage(file);
   };
   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;
@@ -1667,6 +1764,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;
@@ -1677,9 +1775,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);
@@ -1693,10 +1791,10 @@ function main() {
       lastContent = { w: windowed.contentWidth, h: windowed.contentHeight };
       if (offsetX !== 0 || offsetY !== 0) panned = `  (+${offsetX},+${offsetY})`;
     } else {
-      body = (interactive ? splashFrame(notice, splashTick, cols, viewH, cfg.unicode, cfg.color) : void 0) ?? [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;
@@ -1708,9 +1806,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(
@@ -1726,29 +1824,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 {
@@ -1756,7 +1844,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";
@@ -1813,8 +1901,18 @@ function main() {
         if (file === activeFile) notice = describeStoreError(loaded.error);
       }
     }
+    const request = takeFocusRequest(cfg.file);
+    if (request !== void 0 && !(firstScan && pendingFocusFile !== void 0)) {
+      pendingFocusFile = pageFilePath(cfg.file, request.page);
+    }
+    if (pendingFocusFile !== void 0 && pageFiles.includes(pendingFocusFile)) {
+      if (pendingFocusFile !== activeFile) switchPage(pendingFocusFile);
+      pendingFocusFile = void 0;
+    }
     firstScan = false;
-    if (activeFile === void 0 || !pageFiles.includes(activeFile)) switchPage(pageFiles[0]);
+    if (activeFile === void 0 || !pageFiles.includes(activeFile)) {
+      switchPage(mostRecentPageFile(pageFiles, (f) => pageData.get(f)?.mtimeMs));
+    }
     if ([...pageData.values()].some((p) => p.map?.nodes.some((n) => n.status === "in-progress"))) spinnerFrame++;
     if (flash !== void 0 && Date.now() > flash.until) flash = void 0;
     paint();
@@ -1849,10 +1947,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(
@@ -1916,11 +2018,13 @@ 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];
-                  if (target !== void 0 && target !== activeFile) switchPage(target);
+                  const target = lastTabFiles[tabHit.action.index];
+                  if (target !== void 0 && target !== activeFile) handSwitch(target);
                 }
               } else {
                 const id = hitTest(event.x, event.y);
@@ -1931,7 +2035,7 @@ function main() {
                     const target = pageFilePath(cfg.file, submap);
                     if (pageFiles.includes(target) && target !== activeFile) {
                       diveStack.push(activeFile);
-                      switchPage(target);
+                      handSwitch(target);
                     } else if (!pageFiles.includes(target)) {
                       flash = { text: `submap "${submap}" has no page yet`, until: now + 2500 };
                     }
@@ -1955,7 +2059,7 @@ function main() {
               const step = event.kind === "next-page" ? 1 : -1;
               const target = top[(current + step + top.length) % top.length];
               if (target !== activeFile) {
-                switchPage(target);
+                handSwitch(target);
                 dirty = true;
               }
             }
@@ -1964,7 +2068,7 @@ function main() {
           case "page": {
             const target = topFiles()[event.index];
             if (target !== void 0 && target !== activeFile) {
-              switchPage(target);
+              handSwitch(target);
               dirty = true;
             }
             break;
@@ -2010,6 +2114,7 @@ export {
   launchedAsEntry,
   liveRipples,
   mapPanel,
+  mostRecentPageFile,
   nearestHit,
   nodePanel,
   pageTabRow,
@@ -2017,7 +2122,9 @@ export {
   parseArgs,
   splashArt,
   splashFrame,
+  tabScrollFor,
   topLevelFiles,
+  usableColumns,
   waveAt,
   waveHash,
   waveLevel,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mellos-mapping",
-  "version": "0.14.0",
+  "version": "0.16.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",

package/scripts/open-pane.mjs

@@ -2,7 +2,7 @@
 /**
  * Open the live map pane in the RIGHT Windows Terminal window.
  *
- *   node scripts/open-pane.mjs <project-dir> [--window] [--ascii] [--force]
+ *   node scripts/open-pane.mjs <project-dir> [--page <slug>] [--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
@@ -33,18 +33,38 @@
  * 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.
+ *
+ * --page <slug> opens the map ON that page (the effort under discussion, not
+ * whatever page the store lists first). With a watcher already running it
+ * writes the one-shot focus file instead — the existing pane retargets within
+ * a poll tick — so re-running with --page is also how you steer an open pane.
  */
 import { spawnSync } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { existsSync, mkdirSync, renameSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+const USAGE = 'usage: node scripts/open-pane.mjs <project-dir> [--page <slug>] [--window] [--ascii] [--force]';
+
 const argv = process.argv.slice(2);
-const flags = new Set(argv.filter((a) => a.startsWith('--')));
-const positional = argv.filter((a) => !a.startsWith('--'));
+const flags = new Set();
+const positional = [];
+let pageSlug;
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a === '--page') pageSlug = argv[++i];
+  else if (a.startsWith('--')) flags.add(a);
+  else positional.push(a);
+}
 
 if (positional.length !== 1) {
-  console.error('usage: node scripts/open-pane.mjs <project-dir> [--window] [--ascii] [--force]');
+  console.error(USAGE);
+  process.exit(1);
+}
+// Mirrors ID_RULE in src/domain/types.ts — this script runs standalone and
+// cannot import the TypeScript sources.
+if (pageSlug !== undefined && !/^[a-z0-9][a-z0-9-]{0,63}$/.test(pageSlug)) {
+  console.error(`--page needs a kebab-case slug (got "${pageSlug}")\n${USAGE}`);
   process.exit(1);
 }
 if (process.platform !== 'win32') {
@@ -203,6 +223,7 @@ 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');
+  if (pageSlug !== undefined) cmd.push('--page', pageSlug);
   return cmd;
 }
 
@@ -221,8 +242,21 @@ function openDedicatedWindow(reason) {
 }
 
 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).`);
+  if (pageSlug !== undefined) {
+    // One-shot focus request (see takeFocusRequest in src/store/store.ts):
+    // the running watcher consumes and deletes it within a poll tick. Temp +
+    // rename because the watcher polls: a torn read would be swept as junk,
+    // silently losing the request.
+    mkdirSync(dirname(mapFile), { recursive: true });
+    const focusFile = join(dirname(mapFile), 'mellos-mapping.focus');
+    writeFileSync(`${focusFile}.tmp`, JSON.stringify({ page: pageSlug }));
+    renameSync(`${focusFile}.tmp`, focusFile);
+    console.log(`MMAP_PANE already-open refocused=${pageSlug}`);
+    console.log(`A watcher for ${mapFile} is already running — asked it to show page "${pageSlug}".`);
+  } else {
+    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);
 }