mellos-mapping 0.20.3 → 0.23.0

package/docs/codex.md

@@ -0,0 +1,189 @@
+# 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 eight 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
+
+For saved-map discovery, structured CRUD, checkpoints and concurrent updates,
+see [the persistent-map API guide](map-api.md). Start by reading existing pages;
+a new conversation does not require a new map. Restart older MCP/native watchers
+before writing maps with format-2 context or source references. Reopening a Web
+surface replaces services without format-2 support and returns a new URL.
+
+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/docs/map-api.md

@@ -0,0 +1,148 @@
+# Persistent maps and the MCP API
+
+Maps survive process restarts and new conversations. Begin with `mmap_read
+{resource: "pages"}`, match the effort to a saved page, then read only relevant
+records. A conversation is not a page identity. `mmap_view` remains the visual
+representation; `mmap_read` is the editable data contract.
+
+## Read
+
+`mmap_read` returns JSON text and the same object in `structuredContent`:
+`resource`, `project`, `page`, `revision`, `total`, `items`, `nextCursor`.
+The default page is represented by a null `page` and the record ID `_default`.
+Named page slugs and resource IDs remain stable; change display titles/labels
+instead of renaming identity. Edge IDs are `from->to`.
+
+| resource | Records |
+| --- | --- |
+| pages (default) | Page IDs, titles, kind, counts, context and each page's revision; a broken page is listed with its error |
+| map | One page's metadata/context/counts; it does not embed the entire graph |
+| nodes | Node IDs, labels, status and membership; request detail, evidence and sources through fields |
+| edges | ID, from, to and optional label |
+| layers / groups / lanes | The stored editable records |
+| neighborhood | Related nodes selected by id/ids, direction (dependencies/consumers/both) and depth (0–4) |
+| changes | Source-file verification state for selected nodes and up to 100 affected consumer IDs |
+
+Use `id` for exact lookup (missing is `NOT_FOUND`), `ids` for a selection,
+`query` for text matching, and status/layer/group/lane for node filtering.
+`fields` projects records while always retaining identity and edge endpoints.
+The default limit is 30, maximum 100. Repeat the same query with nextCursor;
+if the graph changes, the cursor returns `CONFLICT` instead of skipping records.
+An absent page is `NOT_FOUND`; an empty list is successful. The legacy view's
+empty-map behavior is retained for compatibility.
+
+Use a page or record response's revision for that page's next write. The top-level
+revision of a pages listing describes the listing, not any individual page.
+`ifRevision` can avoid resending unchanged graph data. It does not suppress
+source checks: files may change without a graph edit. Pagination checks graph
+revisions, not a filesystem snapshot of source files changing during the query.
+
+```json
+{"resource":"nodes","page":"payments","status":"in-progress","fields":["label","detail","evidence"],"limit":20}
+```
+
+## Create, update and delete
+
+The existing tools and fields remain supported. New writes return a revision
+and structured outcome in addition to the existing summary.
+
+- `mmap_declare`: create pages, layers, groups, lanes, nodes and edges. Existing
+  IDs are refused. Pass expectedRevision: "absent" to require a new page.
+- `mmap_update`: existing node fields, layer names/ranks, group labels/layers,
+  lane labels, complete laneOrder, map title/kind/context and edge patches.
+  An edge patch identifies from/to, with optional label, newFrom and newTo.
+  A null label clears it. A laneOrder contains every lane exactly once.
+- `mmap_remove`: existing per-resource deletion and cascades. Use deletePage:
+  true to delete the targeted page, including the default page. Inbound submap
+  references are refused unless references: "keep" is explicit. Unlink nodes
+  first when the references should disappear. This form cannot include edits
+  or legacy pages batches.
+
+Optional fields are unchanged when omitted and removed when set to null where
+the schema permits. context and sources are replaced as whole values. Moving
+a group does not silently move members: include their intended node moves in
+the same update or transaction. Normal single-field changes keep the old graph
+constraints; use a batch for changes that require a coordinated final graph.
+
+Every graph writer in the current MCP, HTTP viewer and watcher uses a cooperative
+cross-process project lock. MCP expectedRevision is compared inside that lock
+before loading the proposed changes into the saved map. `CONFLICT` requires a
+fresh read and reconsideration of the edit. `BUSY` means another transaction is
+active; retry after it completes. There is no background lock polling. Locks are
+released on normal completion/error; a confirmed dead PID can be recovered.
+An incomplete owner file after an abrupt crash is refused for manual inspection,
+not guessed stale from its age.
+
+Low-level library saveMapFile, hand edits, and older running processes do not
+participate in this contract. Restart MCP processes and native watchers after
+upgrading. Opening a Web surface upgrades services that lack format-2 support;
+existing tabs must reconnect with the newly returned URL. Atomic file
+replacement alone does not make a caller's stale read/modify/write safe.
+
+Legacy `mmap_remove {pages:[...]}` remains a separately documented batch of file
+deletions, with explicit partial success and historical reference behavior. It
+does not accept expectedRevision; use per-page deletePage for checked deletion.
+It is not a multi-page transaction.
+
+## One-page mixed transactions
+
+`mmap_batch` accepts page, expectedRevision and 1–100 ordered operations. Each
+operation is `{op: "declare" | "update" | "remove", data: {...}}`, with the
+same per-page fields as that tool. Per-operation page, expectedRevision and
+page deletion are excluded. Changes are drafted, the final graph is validated,
+and the page is saved once; a refusal preserves the original file bytes.
+
+```json
+{
+  "page":"payments",
+  "expectedRevision":"<revision returned by mmap_read>",
+  "operations":[
+    {"op":"remove","data":{"edges":[{"from":"api","to":"old-store"}]}},
+    {"op":"declare","data":{"nodes":[{"id":"new-store","label":"Store","layer":"base"}]}},
+    {"op":"declare","data":{"edges":[{"from":"api","to":"new-store"}]}},
+    {"op":"update","data":{"context":{"summary":"Payment services","next":"Verify the new store contract"}}}
+  ]
+}
+```
+
+Machine-readable error codes include NOT_FOUND, INVALID_STORE, REFUSED,
+CONFLICT, BUSY, INVALID_CURSOR, INVALID_ARGUMENT, REFERENCED and SAVE_FAILED.
+Malformed schema inputs remain MCP invalid-argument errors. Read calls do not
+open panels or create page files.
+
+## Checkpoints and source changes
+
+Map context has optional summary and next fields (up to 2,000 characters each).
+Save concise decisions and next actions, rather than copying the conversation.
+Nodes can hold up to 100 sources: `{path: "src/store.ts", sha256: "..."}`.
+Paths are project-relative, forward-slash paths with no traversal. SHA256 is
+optional so sources can be linked before verification.
+
+`mmap_read {resource:"changes", page, id}` hashes only the selected node's
+listed files, reports currentSha256 and unchanged/changed/unknown node state,
+and identifies affected consumers. Missing files count as changed. Missing
+baselines, inaccessible files, files over 8 MiB and paths resolving outside
+the project remain unverified. There is no whole-repository source scan and
+no automatic status change. After verification, copy the current hashes into
+sources[].sha256 with a revision-checked update.
+
+Classic maps continue to serialize as format 1. Maps containing context or
+source references serialize as format 2; this runtime reads both. Older runtimes
+must refuse format 2 instead of silently dropping its new fields. Removing all
+extension fields allows serialization as format 1 again. Both formats preserve
+the same graph, statuses and existing evidence.
+
+## Project identity
+
+Without an explicit MELLOS_MAPPING_CWD or CLAUDE_PROJECT_DIR, the server walks
+up from cwd to the nearest existing map store or Git root. An explicit override
+stays explicit. The mmap command and watcher use the same resolver. Nested
+repositories and worktrees are boundaries; separate branches are not silently
+redirected to a shared writable graph. Carry maps through Git or deliberate
+workspace setup when a new worktree needs them, and recheck source baselines.
+
+Codex CLI and App skills both start by reading existing pages. MCP initialization
+also advertises the restore workflow, including for MCP-only installations.
+Viewer selection follows host capabilities; the CLI does not try to use a
+desktop panel tool. After context compaction, repeat the lightweight page/context
+read, then load only the affected resources.

package/lib/domain/context.d.ts

@@ -0,0 +1,11 @@
+/** Optional portable provenance; no host paths or I/O in the map format. */
+export interface SourceRef {
+    readonly path: string;
+    readonly sha256?: string | undefined;
+}
+export interface MapContext {
+    readonly summary?: string | undefined;
+    readonly next?: string | undefined;
+}
+export declare function sourceError(raw: unknown): string | undefined;
+export declare function contextError(raw: unknown): string | undefined;

package/lib/domain/context.js

@@ -0,0 +1,27 @@
+export function sourceError(raw) {
+    if (!Array.isArray(raw) || raw.length > 100)
+        return 'sources must be an array of at most 100 file references';
+    for (const item of raw) {
+        if (!item || typeof item !== 'object' || Array.isArray(item))
+            return 'source must be an object';
+        const s = item;
+        if (Object.keys(s).some(k => k !== 'path' && k !== 'sha256'))
+            return 'unknown source field';
+        if (typeof s.path !== 'string' || s.path.length > 1024 || !s.path || /[\u0000-\u001f\u007f-\u009f\\:]/.test(s.path) || s.path.startsWith('/') || s.path.split('/').some(p => !p || p === '.' || p === '..'))
+            return 'source path must be relative to the project, with forward slashes and no traversal';
+        if (s.sha256 !== undefined && (typeof s.sha256 !== 'string' || !/^[a-f0-9]{64}$/.test(s.sha256)))
+            return 'source sha256 must be a lowercase SHA256 hash';
+    }
+    return undefined;
+}
+export function contextError(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return 'context must be an object';
+    for (const [key, value] of Object.entries(raw)) {
+        if (key !== 'summary' && key !== 'next')
+            return 'unknown context field';
+        if (typeof value !== 'string' || value.length > 2000 || /[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/.test(value))
+            return 'context fields must be text of at most 2000 characters';
+    }
+    return undefined;
+}

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,54 @@
+import { contextError, sourceError } from './context.js';
+// 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) {
+    if (map.context !== undefined) {
+        const error = contextError(map.context);
+        if (error)
+            return error;
+    }
+    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()) {
+        if (node.sources !== undefined) {
+            const error = sourceError(node.sources);
+            if (error)
+                return `nodes[${i}]: ${error}`;
+        }
+        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.d.ts

@@ -171,7 +171,9 @@ export interface MapLane {
     readonly label: string;
 }
 /** A unit of work living in exactly one band. */
+export type { SourceRef, MapContext } from './context.js';
 export interface MapNode {
+    readonly sources?: readonly import('./context.js').SourceRef[];
     readonly id: NodeId;
     readonly label: string;
     readonly layer: LayerId;
@@ -198,6 +200,7 @@ export interface DepEdge {
 }
 /** The whole map. A plain immutable value — operations return new maps. */
 export interface MellosMap {
+    readonly context?: import('./context.js').MapContext;
     readonly title?: string;
     /** Presentation intent; absent means 'dev' (the progress ledger). */
     readonly kind?: MapKind;

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>;
+};