mellos-mapping 0.20.3 → 0.23.0

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";

package/lib/render/canvas.js

@@ -12,6 +12,7 @@
  * (the ink palette below) and coordinates, and it is the only place ANSI is
  * produced.
  */
+import { terminalText } from '../domain/text.js';
 import { charWidth } from './width.js';
 /** SGR parameter per style; combined with bold ("1") at emit time. */
 export const SGR = {
@@ -22,6 +23,7 @@ export const SGR = {
     greenDim: '32;2', // done, but nothing behind the claim: green, not fully lit
     red: '31',
     faint: '90',
+    focus: '97', // bright foreground without changing font weight
 };
 export const ANSI_RESET = '\x1b[0m';
 // ---------------------------------------------------------------------------
@@ -91,7 +93,7 @@ export class Canvas {
     /** Write literal text starting at (x, y). Returns the column just past it. */
     text(x, y, s, style, bold = false) {
         let cx = x;
-        for (const ch of s) {
+        for (const ch of terminalText(s)) {
             const w = charWidth(ch.codePointAt(0));
             if (w === 0) {
                 // A combining mark, a variation selector or a skin tone takes no
@@ -162,7 +164,7 @@ export class Canvas {
                     ? ''
                     : isWire
                         ? c.bright
-                            ? '1' // spotlighted wire: bold default color against the faint board
+                            ? SGR.focus // change color only; bold fallback glyphs can visually shift
                             : SGR.faint
                         : [SGR[c.style], c.bold ? '1' : ''].filter(Boolean).join(';');
                 if (opts.color && params !== open) {

package/lib/render/draw.js

@@ -46,6 +46,9 @@ export function drawBands(canvas, columns, rows, wiredWidth, totalWidth) {
 export function drawBox(canvas, box, opts, neutral, face, focused = false) {
     const { node, x, y, w } = box;
     const skin = neutral ? neutralSkin(opts.unicode) : skinFor(face, opts.unicode);
+    // Hover must not switch font faces: some terminal fonts draw their bold
+    // box/line glyphs at a different offset, making a stationary box jump.
+    const borderStyle = focused ? 'focus' : skin.style;
     // Neutral pages give the glyph slot to the node kind (a bullet when kindless).
     const slotGlyph = neutral ? neutralGlyph(node, opts.unicode) : glyphFor(face, opts);
     if (box.borderless) {
@@ -56,18 +59,18 @@ export function drawBox(canvas, box, opts, neutral, face, focused = false) {
     }
     const inner = w - 2;
     const pad = box.pad === 1 ? ' ' : '';
-    canvas.text(x, y, skin.corners[0] + skin.h.repeat(inner) + skin.corners[1], skin.style, focused);
-    canvas.text(x, y + 1, skin.v, skin.style, focused);
+    canvas.text(x, y, skin.corners[0] + skin.h.repeat(inner) + skin.corners[1], borderStyle);
+    canvas.text(x, y + 1, skin.v, borderStyle);
     canvas.text(x + 1, y + 1, `${pad}${slotGlyph} ${box.label}${pad}`, skin.style, true);
-    canvas.text(x + w - 1, y + 1, skin.v, skin.style, focused);
+    canvas.text(x + w - 1, y + 1, skin.v, borderStyle);
     for (let i = 0; i < box.extra.length; i++) {
         const row = box.extra[i];
         const yy = y + 2 + i;
-        canvas.text(x, yy, skin.v, skin.style, focused);
+        canvas.text(x, yy, skin.v, borderStyle);
         canvas.text(x + 1, yy, row.text, row.style);
-        canvas.text(x + w - 1, yy, skin.v, skin.style, focused);
+        canvas.text(x + w - 1, yy, skin.v, borderStyle);
     }
-    canvas.text(x, y + box.h - 1, skin.corners[2] + skin.h.repeat(inner) + skin.corners[3], skin.style, focused);
+    canvas.text(x, y + box.h - 1, skin.corners[2] + skin.h.repeat(inner) + skin.corners[3], borderStyle);
 }
 /** Every wire. Those touching the focused node render bright. */
 export function drawEdges(canvas, edges, rows, opts) {

package/lib/render/render.d.ts

@@ -86,3 +86,9 @@ export interface WindowedRender {
 }
 /** Render only the given viewport of the map, plus the full content extent. */
 export declare function renderMapWindow(map: MellosMap, opts: RenderOptions, viewport: Viewport): WindowedRender;
+/**
+ * A pane-owned renderer for immutable map snapshots. Retains only the last
+ * scene: map/zoom/glyph changes rebuild geometry; animation, focus and pan
+ * only repaint it. There is no global cache or filesystem dependency.
+ */
+export declare function createWindowRenderer(): typeof renderMapWindow;

package/lib/render/render.js

@@ -68,12 +68,38 @@ export { statusSgr } from './skins.js';
 export { ZOOM_DEFAULT, ZOOM_MAX, ZOOM_MIN, clampZoom, isNeutralKind, kindGlyph, spinnerGlyph, statusGlyph, unverifiedDoneGlyph, zoomLabel, } from '../semantics/semantics.js';
 /** Render the whole map as terminal lines. */
 export function renderMap(map, opts) {
-    const built = buildCanvas(map, opts);
+    const built = paint(prepareScene(map, opts), opts);
     return built.canvas.emit(opts);
 }
 /** Render only the given viewport of the map, plus the full content extent. */
 export function renderMapWindow(map, opts, viewport) {
-    const built = buildCanvas(map, opts);
+    return renderSceneWindow(prepareScene(map, opts), opts, viewport);
+}
+/**
+ * A pane-owned renderer for immutable map snapshots. Retains only the last
+ * scene: map/zoom/glyph changes rebuild geometry; animation, focus and pan
+ * only repaint it. There is no global cache or filesystem dependency.
+ */
+export function createWindowRenderer() {
+    let previous;
+    let frame;
+    return (map, opts, viewport) => {
+        const zoom = opts.zoom ?? ZOOM_DEFAULT;
+        if (previous?.map !== map || previous.unicode !== opts.unicode || previous.zoom !== zoom) {
+            // Commit the cache only after preparation succeeds, so failures retry.
+            previous = { map, unicode: opts.unicode, zoom, scene: prepareScene(map, opts) };
+        }
+        const scene = previous.scene;
+        if (frame?.scene !== scene || frame.spinner !== opts.spinnerFrame || frame.focus !== opts.focus || frame.color !== opts.color) {
+            frame = { scene, spinner: opts.spinnerFrame, focus: opts.focus, color: opts.color, built: paint(scene, opts) };
+        }
+        return emitWindow(frame.built, opts, viewport);
+    };
+}
+function renderSceneWindow(scene, opts, viewport) {
+    return emitWindow(paint(scene, opts), opts, viewport);
+}
+function emitWindow(built, opts, viewport) {
     return {
         lines: built.canvas.emit(opts, viewport),
         contentWidth: built.canvas.width,
@@ -81,22 +107,20 @@ export function renderMapWindow(map, opts, viewport) {
         hits: built.hits,
     };
 }
-function buildCanvas(map, opts) {
+/** Static decisions, independent of spinner frame, focus, color and viewport. */
+function prepareScene(map, opts) {
     const oriented = flipForSequence(map);
     const plainGeo = zoomGeometry(opts.zoom ?? ZOOM_DEFAULT);
     // The far zoom does not shrink the map, it AGGREGATES it: groups become one
     // box each. Which map is drawn is decided here, once.
     const aggregated = plainGeo.mode === 'constellation' ? aggregateMap(oriented) : undefined;
     const drawn = aggregated ?? oriented;
-    return paint(drawn, opts, aggregated !== undefined ? AGGREGATE_GEO : plainGeo, unverifiedDoneIds(oriented, drawn));
+    const unverified = unverifiedDoneIds(oriented, drawn);
+    if (drawn.layers.length === 0)
+        return { map: drawn, unverified };
+    return { map: drawn, unverified, geometry: prepareGeometry(drawn, opts, aggregated !== undefined ? AGGREGATE_GEO : plainGeo) };
 }
-function paint(map, opts, geo, unverified) {
-    const canvas = new Canvas();
-    if (map.layers.length === 0) {
-        canvas.text(0, 0, map.title ?? 'mellos mapping', 'none', true);
-        canvas.text(0, 2, '(empty map — declare layers and nodes to begin)', 'dim');
-        return { canvas, hits: [] };
-    }
+function prepareGeometry(map, opts, geo) {
     const neutral = isNeutralKind(map);
     const columns = layoutColumns(map, geo, opts.unicode, neutral);
     const routing = routeEdges(map, columns);
@@ -105,6 +129,21 @@ function paint(map, opts, geo, unverified) {
     const wiredWidth = routing.fallbackCount > 0 ? columns.contentWidth + 2 + routing.fallbackCount * 2 : columns.contentWidth;
     /** Plus the band labels' own right margin, which nothing else may enter. */
     const totalWidth = wiredWidth + Math.max(...columns.bandLabel.map(displayWidth));
+    const hits = [...rows.boxOf.values()].map((b) => ({
+        id: b.node.id, x: b.x, y: b.y, w: b.w, h: b.h,
+    }));
+    return { neutral, columns, routing, rows, wiredWidth, totalWidth, hits };
+}
+/** Dynamic drawing always gets a fresh canvas; frames cannot contaminate each other. */
+function paint(scene, opts) {
+    const { map, unverified, geometry } = scene;
+    const canvas = new Canvas();
+    if (geometry === undefined) {
+        canvas.text(0, 0, map.title ?? 'mellos mapping', 'none', true);
+        canvas.text(0, 2, '(empty map — declare layers and nodes to begin)', 'dim');
+        return { canvas, hits: [] };
+    }
+    const { neutral, columns, routing, rows, wiredWidth, totalWidth, hits } = geometry;
     if (map.title !== undefined)
         drawTitle(canvas, map.title);
     drawLaneHeaders(canvas, map, columns, rows);
@@ -117,12 +156,5 @@ function paint(map, opts, geo, unverified) {
     }
     drawEdges(canvas, routing.edges, rows, opts);
     drawLegend(canvas, map, opts, rows.legendY, neutral, unverified.size > 0);
-    const hits = [...rows.boxOf.values()].map((b) => ({
-        id: b.node.id,
-        x: b.x,
-        y: b.y,
-        w: b.w,
-        h: b.h,
-    }));
     return { canvas, hits };
 }

package/lib/render/width.js

@@ -14,6 +14,7 @@
  *
  * Pure functions of a string; no canvas, no options, no I/O.
  */
+import { terminalText } from '../domain/text.js';
 const WIDE_RANGES = [
     [0x1100, 0x115f], // Hangul Jamo
     // Wide symbols scattered through the BMP — mostly emoji that predate the
@@ -99,6 +100,7 @@ export function displayWidth(text) {
 }
 /** Truncate to a display width, ANSI-free input, appending … when cut. */
 export function fitWidth(s, width) {
+    s = terminalText(s);
     if (displayWidth(s) <= width)
         return s;
     let out = '';
@@ -117,7 +119,7 @@ export function wrapWidth(s, width) {
     const lines = [];
     let line = '';
     let w = 0;
-    for (const ch of s.replace(/\r/g, '')) {
+    for (const ch of terminalText(s.replace(/\r/g, '').replace(/\t/g, '  '), true)) {
         if (ch === '\n') {
             lines.push(line);
             line = '';

package/lib/store/atomic.d.ts

@@ -0,0 +1,18 @@
+import { type Result } from '../domain/types.js';
+import { type StoreError } from './format.js';
+export declare function errnoOf(e: unknown): string;
+/**
+ * Write `contents` to `path` atomically (P2).
+ *
+ * Preconditions: none — the parent directory is created if missing.
+ * Postcondition on ok: `path` holds exactly `contents` and no temp file
+ * remains. Postcondition on error: `path` is untouched (it keeps its
+ * previous content, or stays absent) and no temp file remains.
+ *
+ * The temp name is private to this call — `<path>.<pid>.<random>.tmp` — so
+ * two writers racing on one page cannot install each other's partial content
+ * or make each other's rename miss its file.
+ */
+export declare function writeFileAtomic(path: string, contents: string): Result<void, StoreError>;
+/** A heartbeat may yield to the next tick; an authoritative save must retry. */
+export declare function writeAtomic(path: string, contents: string, maxAttempts: number): Result<void, StoreError>;

package/lib/store/atomic.js

@@ -0,0 +1,86 @@
+import { mkdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { err, ok } from '../domain/types.js';
+// ---------------------------------------------------------------------------
+// atomic writes — the one primitive every save in this module is built on
+// ---------------------------------------------------------------------------
+/**
+ * How many times a rename is attempted before the save is reported failed.
+ * A reader's open handle blocks a rename on Windows for as long as it holds
+ * the file; the watcher reads a page in well under a tick, so a handful of
+ * attempts spans far more than any legitimate reader needs.
+ */
+const RENAME_MAX_ATTEMPTS = 10;
+/** Backoff granularity: attempt N waits N * this, so ten attempts span ~450ms. */
+const RENAME_BACKOFF_STEP_MS = 10;
+/**
+ * errno codes a rename can raise while the target is momentarily unavailable
+ * — a reader holding it open (EPERM/EBUSY/EACCES on Windows) or an
+ * antivirus/indexer briefly owning it (ENOENT between its own operations).
+ * Anything else (ENOSPC, EROFS, ENOTDIR) is a real fault: retrying it only
+ * delays the report.
+ */
+const TRANSIENT_RENAME_CODES = new Set(['EPERM', 'EBUSY', 'EACCES', 'ENOENT']);
+/**
+ * Block this thread for `ms`. The save path is synchronous by contract (the
+ * MCP tool answers after the file is on disk), so the backoff must be too.
+ */
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/** The failed write's leftover temp, removed on a best-effort basis. */
+function discardTemp(tmp) {
+    try {
+        rmSync(tmp, { force: true });
+    }
+    catch {
+        // The temp is unreachable for the same reason the write failed; leaving
+        // a stray *.tmp is strictly better than masking the original refusal.
+    }
+}
+export function errnoOf(e) {
+    return e.code ?? e.message;
+}
+/**
+ * Write `contents` to `path` atomically (P2).
+ *
+ * Preconditions: none — the parent directory is created if missing.
+ * Postcondition on ok: `path` holds exactly `contents` and no temp file
+ * remains. Postcondition on error: `path` is untouched (it keeps its
+ * previous content, or stays absent) and no temp file remains.
+ *
+ * The temp name is private to this call — `<path>.<pid>.<random>.tmp` — so
+ * two writers racing on one page cannot install each other's partial content
+ * or make each other's rename miss its file.
+ */
+export function writeFileAtomic(path, contents) {
+    return writeAtomic(path, contents, RENAME_MAX_ATTEMPTS);
+}
+/** A heartbeat may yield to the next tick; an authoritative save must retry. */
+export function writeAtomic(path, contents, maxAttempts) {
+    const tmp = `${path}.${process.pid}.${Math.random().toString(36).slice(2, 10)}.tmp`;
+    try {
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(tmp, contents, 'utf8');
+    }
+    catch (e) {
+        discardTemp(tmp);
+        return err({ kind: 'save-failed', path, detail: `writing the temp file failed: ${errnoOf(e)}` });
+    }
+    let attempt = 1;
+    for (;;) {
+        try {
+            renameSync(tmp, path);
+            return ok(undefined);
+        }
+        catch (e) {
+            const code = errnoOf(e);
+            if (!TRANSIENT_RENAME_CODES.has(code) || attempt >= maxAttempts) {
+                discardTemp(tmp);
+                return err({ kind: 'save-failed', path, detail: `${code} after ${attempt} attempt(s)` });
+            }
+            sleepSync(attempt * RENAME_BACKOFF_STEP_MS);
+            attempt += 1;
+        }
+    }
+}

package/lib/store/channels.d.ts

@@ -0,0 +1,40 @@
+import { type PageId } from './format.js';
+/** Sibling of the default file carrying a one-shot "show this page" request. */
+export declare const FOCUS_FILE_NAME = "focus";
+export declare function focusFilePath(defaultFile: string, pid?: number): string;
+/** A consumed focus request: the page to show (undefined = the default page). */
+export interface FocusRequest {
+    readonly page: PageId | undefined;
+}
+/**
+ * Consume a pending focus request: read it, delete the file, return it.
+ * Absent file — the overwhelmingly common case — or junk content means no
+ * request; the channel is best-effort and junk is swept by the same delete.
+ */
+export declare function takeFocusRequest(defaultFile: string, pid?: number): FocusRequest | undefined;
+/** Sibling of the default file carrying a one-shot "close the pane" request. */
+export declare const QUIT_FILE_NAME = "quit";
+export declare function quitFilePath(defaultFile: string, pid?: number): string;
+/**
+ * Consume a pending quit request: read it, delete the file, say whether there
+ * was one. Absent file — the overwhelmingly common case — or content that is
+ * not a JSON object means NO request; the channel is best-effort and junk is
+ * swept by the same delete.
+ *
+ * The empty JSON object is the whole grammar. It exists so that a stray file
+ * of this name — an editor backup, a half-written write from a foreign tool —
+ * cannot take a live pane down by accident; a pane closing is the one thing
+ * in this channel a user cannot undo by waiting.
+ */
+export declare function takeQuitRequest(defaultFile: string, pid?: number): boolean;
+/**
+ * Delete a quit request WITHOUT acting on it — the same file, read as a
+ * leftover rather than as a message.
+ *
+ * A toggle that wrote the request and then lost its watcher (a crash, a
+ * closed window, a `taskkill`) leaves the file behind, and the next pane to
+ * open would consume it on its first tick and close instantly. The watcher
+ * sweeps at STARTUP for exactly that: a request that predates the pane cannot
+ * have been addressed to it. Best-effort, like every delete in this channel.
+ */
+export declare function sweepQuitRequest(defaultFile: string, pid?: number): void;