mellos-mapping 0.20.2 → 0.22.1

package/docs/codex.md

@@ -0,0 +1,183 @@
+# Mellos Mapping · ChatGPT App (Codex mode)
+
+This package targets Codex mode in the ChatGPT desktop app, also called Codex App.
+The two editions share the map model, store and renderers. The desktop edition
+has its own skill and includes no Claude SessionStart hook or MCP configuration.
+
+## Install and update
+
+Requires Node.js 18+ and a Codex CLI with plugin commands (tested with 0.153.4).
+From the `chatgpt-app` branch run `node install.mjs`; from `main` run
+`node install.mjs chatgpt-app`. Committed bundles need no build or npm dependencies.
+
+The installer checks file hashes and a real MCP handshake, copies the runtime to
+`~/.mellos/installations/chatgpt-app/`, registers the `mellos-mapping-codex`
+marketplace, installs the skill, and registers the six MCP tools at user scope.
+The runtime uses an absolute Node executable and leaves its working directory
+unset so each conversation writes to its own project. The clone can be deleted
+or moved after installation. Other plugins, maps and mapping policies are preserved.
+
+Start a new conversation after installing or updating. Ask:
+“用梅勒斯地图制定计划，并在当前对话右侧终端展示，持续更新验证进度。”
+Run the installer again from a newer release to update. In an edition clone,
+`node install.mjs --check` checks prerequisites, file integrity and MCP without
+changing host configuration. Existing watchers retain old code until restarted.
+
+If migrating from the earlier personal-marketplace version, remove its plugin
+with Codex first to avoid two copies of the skill. The registration helper
+`scripts/codex-register.mjs` remains available to maintain those existing installs.
+It replaces only the named MCP entry; custom transport options may need reapplying.
+
+To uninstall the release edition:
+
+```sh
+codex plugin remove mellos-mapping@mellos-mapping-codex
+codex mcp remove mellos-mapping
+codex plugin marketplace remove mellos-mapping-codex
+```
+
+Project maps and mapping preferences remain. GitHub distribution does not itself
+publish the package into OpenAI's public plugin directory.
+
+## Automatic web terminal
+
+Call `mmap_open {surface: "web-terminal", page: "<slug>"}` and pass the returned
+`hostOpen` object to `open_in_codex`. It uses `placement: "right"` and a browser
+target in the current conversation. The local service starts mmap when the
+browser connects; the user does not paste a startup command. No Computer Use
+or desktop keyboard automation is involved. With an older MCP schema:
+
+```sh
+node "<plugin root>/dist/web.mjs" "<project>" --terminal --page <slug>
+```
+
+Open the printed JSON `url`. The page provides its own font-size selector,
+help, reconnection and a link to the same map in graphical SVG mode. Font
+changes remeasure terminal cells rather than stretching an image, and do not
+change the host's global terminal font. The terminal uses xterm.js cell rendering;
+the graphical mode remains native SVG and supports SVG export.
+
+Both modes use the same project maps. Terminal input/output goes over a local
+WebSocket to a dedicated mmap worker. Each connected browser owns its own
+page/zoom/selection state and renderer; there is no shared shell. Closing the
+tab or stopping the service ends its worker. `q` closes the map until Reconnect.
+Network interruptions get three retry attempts; reopen via MCP if the service
+has exited. A reconnect starts a fresh view on the current page.
+
+All assets and the worker ship prebuilt. No node-pty, native compiler, npm install,
+external terminal, remote hosting or account is required. The service accepts
+only bounded map input/resize messages from its own origin and secret URL,
+limits sessions to eight, and keeps one output chunk in flight until the browser
+renders it. Slow clients cannot accumulate unlimited rendered map frames.
+
+An already-running service from before this feature is stopped and restarted
+on a web-terminal request. That restart disconnects its existing graphical tabs;
+reopen them with the new URL. For later runtime updates, use `--stop` first.
+
+## Optional native desktop terminal
+
+Call `mmap_open {surface: "codex-terminal", page: "<slug>"}`. This prepares the
+actual Node executable and absolute watcher/map paths, with PowerShell and POSIX
+commands. It starts no program or window. Use the host's `open_in_codex` tool with
+`placement: "right"` and `target: {type: "terminal"}` in the current conversation.
+
+If a supported host tool executes commands in this user terminal, use it.
+If only opening/reading tools are exposed, paste the returned command once.
+That interface cannot provide fully automatic first startup. Agent command PTYs
+are separate; stringifying their numeric session IDs cannot attach them to the
+user terminal. No shell profile modification or external-window workaround is used.
+
+Check the map title and controls with `read_thread_terminal` after startup.
+`queued` means a pending panel request; a shell prompt means the map has not
+started. A viewer heartbeat could come from another window. Reuse an existing
+viewer and preserve a manually pinned page. Map writes refresh the watcher.
+
+The equivalent manual command, with paths appropriate to the current install:
+
+```sh
+node "<plugin root>/dist/watch.mjs" --file "<project>/.mellos/map.json" --page <slug>
+```
+
+Wheel / `+` / `-` changes semantic zoom; drag pans; click pins details;
+double-click enters a submap; `0` resets and `q` exits. `--no-mouse` leaves
+mouse events to the host. Font size follows the app's code/terminal settings.
+After an update, press `q` and rerun the command to load the new watcher.
+
+The native watcher uses an alternate screen and reasserts mouse reporting every
+second to recover panel remounts. It outputs changed rows, coalesces mouse-motion
+paints within 16 ms and keeps only the latest pending frame under backpressure.
+A full snapshot every second repairs truncated terminal replay. Viewer-presence
+writes yield on locked files; authoritative map saves retain atomic retries.
+Hover changes border and dependency colors without toggling font weight.
+
+Plain `mmap_open {surface: "terminal"}` is the external Windows Terminal launcher
+for Claude Code and Codex CLI. It does not open the desktop integrated terminal.
+
+## Desktop right-side map
+
+The existing document surface remains available. Call
+`mmap_open {surface: "markdown", page: "<slug>"}`, then open the returned absolute
+Markdown path with the host's file target and `placement: "right"`.
+
+The runtime generates `.mellos/previews/page-<slug>.md` (or `map.md` for the
+default page), `index.md`, and content-hashed SVG images. JSON is authoritative.
+The document includes dependencies, status, details, evidence and child-page links.
+Vectors stay sharp when enlarged. Image nodes do not support dragging, hovering,
+animated spinners or double-clicking. Use the document links to visit child maps.
+
+Opening this surface enables automatic exports after successful MCP map writes,
+including after server restart. Direct JSON edits or older clients need regeneration:
+
+```sh
+node "<plugin root>/dist/preview.mjs" "<project>" --page <slug>
+```
+
+File generation does not prove visibility or automatic host refresh. Regenerate
+and reopen if stale. `preview: STALE` means the map was saved but exporting failed;
+fix the export without repeating the mutation. Previous SVG images remain for
+already-open documents. `.mellos/previews/` is disposable; removing it disables
+auto-export until the next open. Remove a stale `.publish-lock` only after its
+old exporter has stopped, then regenerate.
+
+## Optional interactive web viewer
+
+Call `mmap_open {surface: "web", page: "<slug>"}` and open the returned local URL
+with the host's browser target on the right. Or run:
+
+```sh
+node "<plugin root>/dist/web.mjs" "<project>" --page <slug>
+```
+
+The viewer supports vector pan/zoom, hover and pinned details, dependency
+highlighting, search, status filters, page switching, submaps, breadcrumbs,
+semantic group aggregation below 55%, lanes/sequences, SVG export, themes and
+confirmed page deletion. Dragging pans the canvas; nodes retain automatic layout.
+Narrow panels place details beneath a draggable divider. Map edits use MCP tools.
+
+Cards, labels and connections are native SVG. Zoom changes the SVG `viewBox`.
+The local service binds to `127.0.0.1`, uses an unpredictable per-launch URL,
+checks Host/Origin and serves bundled assets and project maps only. It polls every
+800 ms. Broken pages show errors without hiding other pages; connection failures
+label the last available data. Manual page choice pins that page. Existing
+Markdown exports and terminal preferences remain available.
+
+The detached service survives its MCP parent and stops after five minutes without
+requests. Stop it before reopening after a runtime update:
+
+```sh
+node "<plugin root>/dist/web.mjs" "<project>" --stop
+```
+
+A queued browser-open result does not prove that the viewer is visible.
+
+## Developer verification
+
+Use Node.js 22.12+ for source development. Run `npm ci` then `npm run verify`.
+`npm run package:codex`
+produces the flat plugin; `npm run package:release` produces both installable host
+editions. Runtime tests use actual stdio in separate temporary projects; installation
+checks must use isolated host configuration. No developer path belongs in a release.
+
+The [official plugin documentation](https://developers.openai.com/plugins/build/plugins)
+describes local marketplaces and Git distribution. See the
+[plugin usage guide](https://learn.chatgpt.com/docs/plugins) for host installation behavior.

package/lib/domain/text.d.ts

@@ -0,0 +1,9 @@
+/** Text remains data at every input and display boundary. No host dependencies. */
+import type { MellosMap } from './types.js';
+export declare const NO_CONTROLS: RegExp;
+export declare const NO_CONTROLS_TEXT = "one line of text; control characters (ESC, newline, tab) are not allowed";
+export declare const NO_CONTROLS_BUT_BREAKS: RegExp;
+export declare const NO_CONTROLS_BUT_BREAKS_TEXT = "text with optional newlines (\\n) and tabs; other control characters (ESC, BEL, CR) are not allowed";
+export declare function mapTextError(map: MellosMap): string | undefined;
+/** Defensive rendering for maps constructed directly by library consumers. */
+export declare function terminalText(text: string, multiline?: boolean): string;

package/lib/domain/text.js

@@ -0,0 +1,43 @@
+// Explicit ranges also work in the JSON Schema published by the MCP adapter.
+export const NO_CONTROLS = /^[^\u0000-\u001f\u007f-\u009f]*$/;
+export const NO_CONTROLS_TEXT = 'one line of text; control characters (ESC, newline, tab) are not allowed';
+export const NO_CONTROLS_BUT_BREAKS = /^[^\u0000-\u0008\u000b-\u001f\u007f-\u009f]*$/;
+export const NO_CONTROLS_BUT_BREAKS_TEXT = 'text with optional newlines (\\n) and tabs; other control characters (ESC, BEL, CR) are not allowed';
+export function mapTextError(map) {
+    const check = (field, value, multiline = false) => value === undefined || (multiline ? NO_CONTROLS_BUT_BREAKS : NO_CONTROLS).test(value)
+        ? undefined : `${field}: ${multiline ? NO_CONTROLS_BUT_BREAKS_TEXT : NO_CONTROLS_TEXT}`;
+    let error = check('title', map.title);
+    if (error)
+        return error;
+    for (const [i, layer] of map.layers.entries()) {
+        error = check(`layers[${i}].name`, layer.name);
+        if (error)
+            return error;
+    }
+    for (const name of ['lanes', 'groups']) {
+        for (const [i, item] of map[name].entries()) {
+            error = check(`${name}[${i}].label`, item.label);
+            if (error)
+                return error;
+        }
+    }
+    for (const [i, node] of map.nodes.entries()) {
+        for (const name of ['label', 'evidence', 'detail']) {
+            // Version-1 files and document exports also support multiline evidence.
+            // MCP keeps its narrower one-line evidence input for concise updates.
+            error = check(`nodes[${i}].${name}`, node[name], name !== 'label');
+            if (error)
+                return error;
+        }
+    }
+    for (const [i, edge] of map.edges.entries()) {
+        error = check(`edges[${i}].label`, edge.label);
+        if (error)
+            return error;
+    }
+    return undefined;
+}
+/** Defensive rendering for maps constructed directly by library consumers. */
+export function terminalText(text, multiline = false) {
+    return text.replace(multiline ? /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g : /[\u0000-\u001f\u007f-\u009f]/g, '?');
+}

package/lib/domain/types.js

@@ -147,7 +147,16 @@ export function describeMapError(e) {
         case 'layer-holds-group':
             return `layer "${e.id}" still holds group "${e.occupant}"; remove its groups (removeGroup) first`;
         case 'edge-not-downward':
+            // The fault is one invariant (I4) but the remedy is not: a same-band
+            // edge is a modeling error the caller fixes by restructuring, an
+            // upward edge is usually a reversed arrow. The refusal is the moment
+            // the caller needs the remedy, so it is spelled out here, not only in
+            // the skill text they read before the batch was composed.
             return (`edge ${e.from} (rank ${e.fromRank}) -> ${e.to} (rank ${e.toRank}) is not strictly downward; ` +
-                `dependencies may only point to a lower layer`);
+                (e.fromRank === e.toRank
+                    ? `same-band siblings may not depend on each other — either "${e.to}" is really a lower concept ` +
+                        `(declare it on a lower band) or "${e.from}" and "${e.to}" are one node (merge them)`
+                    : `"${e.from}" would USE "${e.to}" from a lower band — reverse the edge if "${e.to}" is the user, ` +
+                        `otherwise move or re-rank so "${e.from}" sits above "${e.to}"`));
     }
 }

package/lib/preview/index.d.ts

@@ -0,0 +1,3 @@
+/** Pure presentation API; persistence and host integration are separate adapters. */
+export { renderMapSvg } from './svg.js';
+export { renderMapMarkdown, renderPreviewIndex, type PreviewPage } from './markdown.js';

package/lib/preview/index.js

@@ -0,0 +1,3 @@
+/** Pure presentation API; persistence and host integration are separate adapters. */
+export { renderMapSvg } from './svg.js';
+export { renderMapMarkdown, renderPreviewIndex } from './markdown.js';

package/lib/preview/markdown.d.ts

@@ -0,0 +1,8 @@
+/** Pure document projection. JSON remains the sole editable map source. */
+import type { MellosMap } from '../domain/types.js';
+export interface PreviewPage {
+    readonly page: string | undefined;
+    readonly map: MellosMap;
+}
+export declare function renderMapMarkdown(map: MellosMap, image: string, pages: readonly PreviewPage[]): string;
+export declare function renderPreviewIndex(pages: readonly PreviewPage[]): string;

package/lib/preview/markdown.js

@@ -0,0 +1,54 @@
+import { isNeutralKind } from '../semantics/semantics.js';
+import { documentName, isVerified, statusText } from './presentation.js';
+import { cell, markdown as md } from './text.js';
+export function renderMapMarkdown(map, image, pages) {
+    const neutral = isNeutralKind(map);
+    const rows = [`# ${md(map.title ?? '梅勒斯地图')}`, '', '[所有地图](index.md)', '',
+        '> 自动生成的地图预览；修改地图数据后重新生成。', ''];
+    if (!neutral) {
+        const active = map.nodes.filter(n => n.status === 'in-progress');
+        rows.push(`**当前：** ${active.length ? active.map(n => md(n.label)).join('、') : '暂无进行中的模块'}`, '', `已验证 **${map.nodes.filter(isVerified).length} / ${map.nodes.length}**　｜　回归 **${map.nodes.filter(n => n.status === 'regressed').length}**`, '');
+    }
+    rows.push('## 分层依赖', '', `![分层依赖地图](${image})`, '');
+    if (!neutral)
+        rows.push('· 待开发　⠿ 开发中　■ 已验证　✗ 出现回归　□ 完成但缺少证据', '');
+    rows.push(map.kind === 'sequence' ? '时间从上向下推进；箭头保留地图中的依赖方向。' : '箭头由使用方指向它依赖的模块；基础层位于下方。', '', '## 模块详情', '');
+    const nodes = new Map(map.nodes.map(n => [n.id, n]));
+    const layers = [...map.layers].sort((a, b) => map.kind === 'sequence' ? a.rank - b.rank : b.rank - a.rank);
+    for (const layer of layers) {
+        rows.push(`### ${md(layer.name)}`, '');
+        const members = map.nodes.filter(n => n.layer === layer.id);
+        if (!members.length)
+            rows.push('尚未声明模块。', '');
+        for (const node of members) {
+            rows.push(`#### ${md(node.label)}${neutral ? '' : `　${statusText(node)}`}`, '');
+            if (node.detail !== undefined)
+                rows.push(md(node.detail), '');
+            const used = map.edges.filter(e => e.from === node.id);
+            rows.push(`**依赖：** ${used.length ? used.map(e => `${md(nodes.get(e.to).label)}${e.label !== undefined ? `（${md(e.label)}）` : ''}`).join('、') : '无'}`, '');
+            const meta = [node.group === undefined ? undefined : map.groups.find(g => g.id === node.group)?.label,
+                node.lane === undefined ? undefined : map.lanes.find(l => l.id === node.lane)?.label,
+                node.kind].filter((v) => v !== undefined);
+            if (meta.length)
+                rows.push(`**归属 / 类型：** ${meta.map(md).join(' · ')}`, '');
+            if (node.evidence !== undefined)
+                rows.push(`**验证记录：** ${md(node.evidence)}`, '');
+            if (node.submap !== undefined)
+                rows.push(pages.some(p => p.page === node.submap)
+                    ? `[打开子图：${md(node.submap)}](${documentName(node.submap)})`
+                    : `子图尚未创建：${md(node.submap)}`, '');
+        }
+    }
+    if (!neutral) {
+        rows.push('## 验证记录', '', '| 模块 | 状态 | 最近证据 |', '| --- | --- | --- |');
+        for (const node of map.nodes)
+            rows.push(`| ${cell(node.label)} | ${statusText(node)} | ${node.evidence === undefined ? '尚未记录' : cell(node.evidence)} |`);
+        rows.push('');
+    }
+    rows.push('---', '', '静态文档：更新时重新生成地图图片与文字。图中节点不支持拖拽、悬停展开或动画。', '');
+    return rows.join('\n');
+}
+export function renderPreviewIndex(pages) {
+    return ['# 梅勒斯地图 · 页面目录', '', ...pages.map(p => `- [${md(p.map.title ?? p.page ?? '默认地图')}](${documentName(p.page)})`), '',
+        '地图预览由项目内的地图数据生成。', ''].join('\n');
+}

package/lib/preview/presentation.d.ts

@@ -0,0 +1,6 @@
+/** Preview vocabulary; shares status glyphs with every existing map surface. */
+import type { MapNode } from '../domain/types.js';
+export declare function isVerified(node: MapNode): boolean;
+export declare function statusText(node: MapNode): string;
+/** Default and named pages never collide, including a named page called map. */
+export declare function documentName(page: string | undefined): string;

package/lib/preview/presentation.js

@@ -0,0 +1,14 @@
+import { statusGlyph, unverifiedDoneGlyph } from '../semantics/semantics.js';
+const LABELS = { planned: '待开发', 'in-progress': '开发中', done: '已验证', regressed: '出现回归' };
+export function isVerified(node) {
+    return node.status === 'done' && node.evidence !== undefined;
+}
+export function statusText(node) {
+    return node.status === 'done' && !isVerified(node)
+        ? `${unverifiedDoneGlyph(true)} 完成但缺少证据`
+        : `${statusGlyph(node.status, true)} ${LABELS[node.status]}`;
+}
+/** Default and named pages never collide, including a named page called map. */
+export function documentName(page) {
+    return page === undefined ? 'map.md' : `page-${page}.md`;
+}

package/lib/preview/publisher.d.ts

@@ -0,0 +1,23 @@
+import { type Result } from '../domain/types.js';
+import { type PageId } from '../store/store.js';
+export declare const PREVIEW_DIR_NAME = "previews";
+export interface PublishedPreview {
+    readonly path: string;
+    readonly index: string;
+    readonly pages: number;
+}
+export declare function previewDirectory(defaultFile: string): string;
+export declare function previewFile(defaultFile: string, page?: PageId): string;
+/**
+ * Activation is project-local and survives MCP restarts. Each publisher reads
+ * it again, so concurrent clients cooperate without a shared server process.
+ * SVG names are content-addressed: a document always points at a complete
+ * image and file-preview caches cannot reuse the previous state's picture.
+ * Old images stay available to open documents; the preview directory is a
+ * disposable cache, never source history.
+ */
+export declare function createPreviewPublisher(defaultFile: string): {
+    enabled: () => boolean;
+    refresh: (page?: PageId) => Result<PublishedPreview, string>;
+    activate: (page?: PageId) => Result<PublishedPreview, string>;
+};

package/lib/preview/publisher.js

@@ -0,0 +1,143 @@
+/** Filesystem adapter for derived previews. Never writes back into map JSON. */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, rmdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { EMPTY_MAP, ID_RULE, err, ok } from '../domain/types.js';
+import { describeStoreError, listPageFiles, loadMapFile, pageIdOfFile, writeFileAtomic } from '../store/store.js';
+import { renderMapMarkdown, renderPreviewIndex } from './markdown.js';
+import { documentName } from './presentation.js';
+import { renderMapSvg } from './svg.js';
+export const PREVIEW_DIR_NAME = 'previews';
+const ENABLED = '.enabled';
+const PUBLISH_LOCK = '.publish-lock';
+export function previewDirectory(defaultFile) {
+    return join(dirname(defaultFile), PREVIEW_DIR_NAME);
+}
+export function previewFile(defaultFile, page) {
+    if (page !== undefined && !ID_RULE.test(page))
+        throw new Error('Invalid preview page id.');
+    return join(previewDirectory(defaultFile), documentName(page));
+}
+function save(path, contents) {
+    try {
+        if (readFileSync(path, 'utf8') === contents)
+            return;
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    const result = writeFileAtomic(path, contents);
+    if (!result.ok)
+        throw new Error(describeStoreError(result.error));
+}
+/** Output directories cannot redirect generated writes through a junction. */
+function ownedDirectory(path) {
+    mkdirSync(path, { recursive: true });
+    const expected = join(realpathSync(dirname(path)), path.slice(dirname(path).length + 1));
+    const actual = realpathSync(path);
+    if ((process.platform === 'win32' ? actual.toLowerCase() !== expected.toLowerCase() : actual !== expected)) {
+        throw new Error(`Preview directory redirects outside its parent: ${path}`);
+    }
+}
+/**
+ * Serialize project-wide projections across processes. Source saves stay
+ * independent; the next waiting publisher reads them AFTER taking this lock,
+ * so an older project snapshot cannot overwrite a later page's preview.
+ * A killed exporter leaves a visible failure, never a silently stale success.
+ */
+function acquireLock(directory) {
+    const path = join(directory, PUBLISH_LOCK);
+    const deadline = Date.now() + 2_000;
+    while (true) {
+        try {
+            mkdirSync(path);
+            return () => rmdirSync(path);
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            if (Date.now() >= deadline)
+                throw new Error(`Preview export is busy or was interrupted. Retry; if no exporter is running, remove the stale lock directory: ${path}`);
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
+        }
+    }
+}
+/**
+ * Activation is project-local and survives MCP restarts. Each publisher reads
+ * it again, so concurrent clients cooperate without a shared server process.
+ * SVG names are content-addressed: a document always points at a complete
+ * image and file-preview caches cannot reuse the previous state's picture.
+ * Old images stay available to open documents; the preview directory is a
+ * disposable cache, never source history.
+ */
+export function createPreviewPublisher(defaultFile) {
+    const directory = previewDirectory(defaultFile);
+    const enabledFile = join(directory, ENABLED);
+    const enabled = () => existsSync(enabledFile);
+    const refresh = (page) => {
+        try {
+            const path = previewFile(defaultFile, page);
+            ownedDirectory(directory);
+            const release = acquireLock(directory);
+            try {
+                const pages = [];
+                for (const source of listPageFiles(defaultFile)) {
+                    const slug = pageIdOfFile(defaultFile, source);
+                    if (slug !== undefined && !ID_RULE.test(slug))
+                        throw new Error(`Invalid map page filename: ${source}`);
+                    const loaded = loadMapFile(source);
+                    if (!loaded.ok)
+                        throw new Error(describeStoreError(loaded.error));
+                    pages.push({ page: slug, map: loaded.value });
+                }
+                // An unopened project can show a standby default map. A misspelled named
+                // page must not manufacture a plausible empty diagram.
+                if (page !== undefined && !pages.some(p => p.page === page))
+                    return err(`No map page named "${page}".`);
+                if (page === undefined && !pages.some(p => p.page === undefined))
+                    pages.unshift({ page: undefined, map: EMPTY_MAP });
+                const images = join(directory, 'images');
+                ownedDirectory(images);
+                const present = new Set();
+                for (const item of pages) {
+                    const svg = renderMapSvg(item.map);
+                    const digest = createHash('sha256').update(svg).digest('hex');
+                    const image = `images/${digest}.svg`;
+                    save(join(images, `${digest}.svg`), svg);
+                    const filename = documentName(item.page);
+                    save(join(directory, filename), renderMapMarkdown(item.map, image, pages));
+                    present.add(filename);
+                }
+                // An already-open deleted page must stop presenting its old state.
+                for (const filename of readdirSync(directory)) {
+                    if (/^(map|page-[a-z0-9][a-z0-9-]{0,63})\.md$/.test(filename) && !present.has(filename)) {
+                        save(join(directory, filename), '# 地图已删除\n\n此页面已不在项目地图中。\n\n[返回地图目录](index.md)\n');
+                    }
+                }
+                const index = join(directory, 'index.md');
+                save(index, renderPreviewIndex(pages));
+                return ok({ path: resolve(path), index: resolve(index), pages: pages.length });
+            }
+            finally {
+                release();
+            }
+        }
+        catch (error) {
+            return err(error instanceof Error ? error.message : String(error));
+        }
+    };
+    const activate = (page) => {
+        const published = refresh(page);
+        if (!published.ok)
+            return published;
+        try {
+            save(enabledFile, 'Markdown preview updates are enabled for this project.\n');
+        }
+        catch (error) {
+            return err(error instanceof Error ? error.message : String(error));
+        }
+        return published;
+    };
+    return { enabled, refresh, activate };
+}

package/lib/preview/svg.d.ts

@@ -0,0 +1,3 @@
+/** Pure vector view. Reuses terminal layout/routing, without ANSI or browser I/O. */
+import type { MellosMap } from '../domain/types.js';
+export declare function renderMapSvg(map: MellosMap): string;

package/lib/preview/svg.js

@@ -0,0 +1,74 @@
+import { flipForSequence, isNeutralKind } from '../semantics/semantics.js';
+import { layoutColumns, layoutRows } from '../render/layout.js';
+import { edgePolyline, routeEdges } from '../render/routing.js';
+import { displayWidth, fitWidth } from '../render/width.js';
+import { zoomGeometry } from '../render/zoom-geometry.js';
+import { isVerified, statusText } from './presentation.js';
+import { xml } from './text.js';
+const X = 8;
+const Y = 26;
+const TOP = 20;
+const PALETTES = {
+    planned: ['#f5f7fa', '#98a3b2', '#566477'],
+    'in-progress': ['#fff4d9', '#c48c24', '#805910'],
+    done: ['#e9f5ee', '#67a883', '#286247'],
+    regressed: ['#fdecec', '#cc7575', '#923d3d'],
+    unverified: ['#fff6e8', '#b49a77', '#785e3e'],
+    neutral: ['#f2f5f9', '#a1adbc', '#364558'],
+};
+export function renderMapSvg(map) {
+    const neutral = isNeutralKind(map);
+    const originals = new Map(map.nodes.map(n => [n.id, n]));
+    const oriented = flipForSequence(map);
+    // Reserve enough room for the second status line, cap long labels; full text
+    // remains in the document and each SVG node's accessible title.
+    const shaped = { ...oriented, nodes: oriented.nodes.map(n => {
+            const label = fitWidth(n.label, 32);
+            return { ...n, label: label + ' '.repeat(Math.max(0, 20 - displayWidth(label))) };
+        }) };
+    const geo = { ...zoomGeometry(0), boxGap: 6 };
+    const columns = layoutColumns(shaped, geo, true, neutral);
+    const routing = routeEdges(shaped, columns);
+    const rows = layoutRows(columns, geo, routing.gapRowCount, false, map.lanes.length > 0);
+    const width = Math.max(440, (columns.contentWidth + 4 + routing.fallbackCount * 2) * X);
+    const height = Math.max(100, TOP + rows.legendY * Y);
+    const parts = [
+        `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}" role="img" aria-labelledby="map-title map-desc">`,
+        `<title id="map-title">${xml(map.title ?? '梅勒斯地图')}</title>`,
+        `<desc id="map-desc">${map.nodes.length} 个节点，${map.edges.length} 条依赖。完整说明与验证记录在地图文档中。</desc>`,
+        '<defs><marker id="arrow" viewBox="0 0 8 8" refX="7" refY="4" markerWidth="6" markerHeight="6" orient="auto-start-reverse"><path d="M0 0 L8 4 L0 8 Z" fill="#8995a5"/></marker></defs>',
+        `<rect width="${width}" height="${height}" fill="#ffffff"/>`,
+        '<g font-family="Segoe UI, Microsoft YaHei, Noto Sans CJK SC, sans-serif">',
+    ];
+    if (map.nodes.length === 0)
+        parts.push('<text x="20" y="52" font-size="14" fill="#657286">尚未声明模块，等待地图更新。</text>');
+    columns.bands.forEach((band, i) => {
+        const top = TOP + rows.barY[i] * Y;
+        const boxes = rows.bandBoxes[i];
+        const bottom = boxes.reduce((max, b) => Math.max(max, TOP + (b.y + b.h - 1) * Y), top + 60);
+        parts.push(`<rect x="8" y="${top - 10}" width="${width - 16}" height="${bottom - top + 26}" rx="5" fill="#fafbfc"/>`);
+        parts.push(`<text x="16" y="${top + 5}" font-size="12" fill="#6a7687">${xml(fitWidth(band.name, Math.floor((width - 40) / X)))}</text>`);
+    });
+    if (rows.laneHeaderY !== undefined)
+        map.lanes.forEach((lane, i) => {
+            const region = columns.lanes[i];
+            parts.push(`<text x="${(region.x + region.w / 2) * X}" y="${TOP + rows.laneHeaderY * Y + 5}" text-anchor="middle" font-size="12" fill="#566477">${xml(fitWidth(lane.label, region.w))}</text>`);
+        });
+    for (const edge of routing.edges) {
+        const points = edgePolyline(edge, rows).map(([x, y]) => `${x * X},${TOP + y * Y}`).join(' ');
+        parts.push(`<polyline points="${points}" fill="none" stroke="#8995a5" stroke-width="1.4" marker-end="url(#arrow)"/>`);
+    }
+    for (const box of rows.boxOf.values()) {
+        const node = originals.get(box.node.id);
+        const palette = neutral ? PALETTES.neutral : node.status === 'done' && !isVerified(node) ? PALETTES.unverified : PALETTES[node.status];
+        const x = box.x * X, y = TOP + box.y * Y, w = (box.w - 1) * X, h = (box.h - 1) * Y;
+        const dash = !neutral && node.status === 'planned' ? ' stroke-dasharray="5 4"' : '';
+        parts.push(`<g data-node="${xml(node.id)}"><title>${xml(node.label)}${neutral ? '' : ` · ${xml(statusText(node))}`}</title>`);
+        parts.push(`<rect x="${x}" y="${y}" width="${w}" height="${h}" rx="5" fill="${palette[0]}" stroke="${palette[1]}" stroke-width="1.5"${dash}/>`);
+        parts.push(`<text x="${x + w / 2}" y="${y + 21}" text-anchor="middle" font-size="14" fill="${palette[2]}">${xml(box.label.trim())}</text>`);
+        const secondary = neutral ? node.kind ?? node.id : statusText(node);
+        parts.push(`<text x="${x + w / 2}" y="${y + 40}" text-anchor="middle" font-size="11" fill="${palette[2]}">${xml(fitWidth(secondary, box.w - 4))}</text></g>`);
+    }
+    parts.push('</g></svg>');
+    return parts.join('\n');
+}

package/lib/preview/text.d.ts

@@ -0,0 +1,4 @@
+/** Literal user content stays data in both XML and Markdown output. */
+export declare function xml(text: string): string;
+export declare function markdown(text: string): string;
+export declare function cell(text: string): string;

package/lib/preview/text.js

@@ -0,0 +1,13 @@
+/** Literal user content stays data in both XML and Markdown output. */
+export function xml(text) {
+    return text.replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\ufffe\uffff]/g, '')
+        .replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;').replace(/'/g, '&apos;');
+}
+export function markdown(text) {
+    return text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+        .replace(/([\\`*_[\]{}()#+.!|~-])/g, '\\$1').replace(/\r?\n/g, '  \n');
+}
+export function cell(text) {
+    return markdown(text).replace(/  \n/g, '<br>');
+}

package/lib/render/canvas.d.ts

@@ -13,7 +13,7 @@
  * produced.
  */
 import type { RenderOptions, Viewport } from './options.js';
-export type Style = 'none' | 'dim' | 'amber' | 'green' | 'greenDim' | 'red' | 'faint';
+export type Style = 'none' | 'dim' | 'amber' | 'green' | 'greenDim' | 'red' | 'faint' | 'focus';
 /** SGR parameter per style; combined with bold ("1") at emit time. */
 export declare const SGR: Readonly<Record<Style, string>>;
 export declare const ANSI_RESET = "\u001B[0m";