mellos-mapping 0.20.3 → 0.22.1

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;

package/lib/store/channels.js

@@ -0,0 +1,135 @@
+import { existsSync, readFileSync, rmSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { makePageId } from './format.js';
+import { isRecord, stripBom } from './json-text.js';
+import { viewersDirPath } from './viewers.js';
+// ---------------------------------------------------------------------------
+// focus requests — "show this page" messages from pane openers to the watcher
+// ---------------------------------------------------------------------------
+//
+// State files flow one way, MCP server → watcher; a launcher that wants an
+// ALREADY-RUNNING pane to show a particular page has no channel to it. The
+// focus file is that channel, one-shot on purpose: the watcher consumes the
+// request AND DELETES the file, so a request lives about one poll tick —
+// nothing stale survives to misdirect tomorrow's pane, and the project's git
+// status barely ever sees the file exist.
+/** Sibling of the default file carrying a one-shot "show this page" request. */
+export const FOCUS_FILE_NAME = 'focus';
+export function focusFilePath(defaultFile, pid) {
+    return paneChannelPath(defaultFile, FOCUS_FILE_NAME, pid);
+}
+/** A targeted message cannot be consumed by another pane of the same project. */
+function paneChannelPath(defaultFile, channel, pid) {
+    if (pid === undefined)
+        return join(dirname(defaultFile), channel);
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        throw new Error('Invalid pane process id');
+    return join(viewersDirPath(defaultFile), `${pid}.${channel}`);
+}
+/**
+ * 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 function takeFocusRequest(defaultFile, pid) {
+    const targeted = pid === undefined ? undefined : focusFilePath(defaultFile, pid);
+    const path = targeted !== undefined && existsSync(targeted) ? targeted : focusFilePath(defaultFile);
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        rmSync(path, { force: true });
+    }
+    catch {
+        // deletion is a courtesy: re-consuming next tick is harmless because
+        // switching to the already-shown page is a no-op
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof parsed !== 'object' || parsed === null)
+        return undefined;
+    const page = parsed.page;
+    if (page === undefined || page === null)
+        return { page: undefined };
+    if (typeof page !== 'string')
+        return undefined;
+    const id = makePageId(page);
+    return id.ok ? { page: id.value } : undefined;
+}
+// ---------------------------------------------------------------------------
+// quit requests — "close yourself" messages from the toggle to the watcher
+// ---------------------------------------------------------------------------
+//
+// The mirror of the focus file, and there for the same reason: a human who
+// types `mmap` in some OTHER terminal has no channel to the pane that is
+// already running. The quit file is that channel, one-shot on purpose — the
+// watcher consumes the request AND DELETES the file, so a request lives about
+// one poll tick and nothing stale survives to close tomorrow's pane.
+//
+// The request carries no payload. A pane belongs to one store, so "close the
+// pane watching this store" has nothing to say beyond being asked.
+/** Sibling of the default file carrying a one-shot "close the pane" request. */
+export const QUIT_FILE_NAME = 'quit';
+export function quitFilePath(defaultFile, pid) {
+    return paneChannelPath(defaultFile, QUIT_FILE_NAME, pid);
+}
+/**
+ * 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 function takeQuitRequest(defaultFile, pid) {
+    const targeted = pid === undefined ? undefined : quitFilePath(defaultFile, pid);
+    const path = targeted !== undefined && existsSync(targeted) ? targeted : quitFilePath(defaultFile);
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch {
+        return false;
+    }
+    sweepQuitRequest(defaultFile, path === targeted ? pid : undefined);
+    let parsed;
+    try {
+        parsed = JSON.parse(stripBom(raw));
+    }
+    catch {
+        return false;
+    }
+    return isRecord(parsed);
+}
+/**
+ * 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 function sweepQuitRequest(defaultFile, pid) {
+    try {
+        rmSync(quitFilePath(defaultFile, pid), { force: true });
+    }
+    catch {
+        // The file is unreachable for some reason the next tick will meet again;
+        // re-consuming a request we cannot delete only closes a pane the user
+        // asked to close.
+    }
+}

package/lib/store/format.js

@@ -21,6 +21,7 @@
  * ./store.ts, the Node-side half.
  */
 import { declareGroup, declareLane, declareLayer, declareNode, linkNodes, setKind, setTitle, updateNode } from '../domain/ops.js';
+import { mapTextError } from '../domain/text.js';
 import { EMPTY_MAP, ID_RULE, ID_RULE_TEXT, describeMapError, err, makeGroupId, makeLaneId, makeLayerId, makeMapKind, makeNodeId, makeNodeKind, makeNodeStatus, makeRank, makeSubmapRef, ok, } from '../domain/types.js';
 /** On-disk format version. Bump only with a documented migration. */
 export const STATE_FILE_VERSION = 1;
@@ -316,7 +317,8 @@ export function parseMap(raw, path) {
             return err({ kind: 'invariant-violation', path, violation: linked.error });
         map = linked.value;
     }
-    return ok(map);
+    const textError = mapTextError(map);
+    return textError ? err({ kind: 'bad-shape', path, detail: textError }) : ok(map);
 }
 /** Serialize a map into the on-disk shape. Inverse of parseMap for valid maps (F1). */
 export function serializeMap(map) {

package/lib/store/json-text.d.ts

@@ -0,0 +1,9 @@
+export declare function isRecord(v: unknown): v is Record<string, unknown>;
+/**
+ * Drop a leading UTF-8 byte-order mark. Windows editors (Notepad, some
+ * PowerShell redirections) add one when a human edits a state file by hand,
+ * and JSON.parse refuses the result — an invisible character would otherwise
+ * read as "your map is corrupt". The BOM carries no meaning for us: the
+ * files are UTF-8 by contract.
+ */
+export declare function stripBom(text: string): string;

package/lib/store/json-text.js

@@ -0,0 +1,16 @@
+// ---------------------------------------------------------------------------
+// reading text that a human may have touched — shared by every load below
+// ---------------------------------------------------------------------------
+export function isRecord(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/**
+ * Drop a leading UTF-8 byte-order mark. Windows editors (Notepad, some
+ * PowerShell redirections) add one when a human edits a state file by hand,
+ * and JSON.parse refuses the result — an invisible character would otherwise
+ * read as "your map is corrupt". The BOM carries no meaning for us: the
+ * files are UTF-8 by contract.
+ */
+export function stripBom(text) {
+    return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}

package/lib/store/maps.d.ts

@@ -0,0 +1,12 @@
+import { type MellosMap, type Result } from '../domain/types.js';
+import { type StoreError } from './format.js';
+/** Load and validate the map file at `path`. */
+export declare function loadMapFile(path: string): Result<MellosMap, StoreError>;
+/**
+ * Write the map to `path` atomically (P2): serialize to a private sibling
+ * temp file, then rename it over the target, retrying a rename the OS
+ * refuses transiently. Creates the parent directory if missing.
+ * @returns ok when the file holds the new map; save-failed when it does not,
+ *   in which case the previous content is intact and the call may be retried.
+ */
+export declare function saveMapFile(path: string, map: MellosMap): Result<void, StoreError>;

package/lib/store/maps.js

@@ -0,0 +1,42 @@
+import { readFileSync } from 'node:fs';
+import { err } from '../domain/types.js';
+import { mapTextError } from '../domain/text.js';
+import { parseMap, serializeMap } from './format.js';
+import { writeFileAtomic } from './atomic.js';
+import { stripBom } from './json-text.js';
+/** Load and validate the map file at `path`. */
+export function loadMapFile(path) {
+    let text;
+    try {
+        text = readFileSync(path, 'utf8');
+    }
+    catch (e) {
+        const code = e.code;
+        if (code === 'ENOENT')
+            return err({ kind: 'not-found', path });
+        throw e; // unexpected I/O fault: fail fast, nothing meaningful to recover here
+    }
+    let raw;
+    try {
+        raw = JSON.parse(stripBom(text));
+    }
+    catch (e) {
+        // Expected at this boundary: hand-edited files, or a reader racing a
+        // non-atomic writer from a foreign tool.
+        return err({ kind: 'malformed-json', path, detail: e.message });
+    }
+    return parseMap(raw, path);
+}
+/**
+ * Write the map to `path` atomically (P2): serialize to a private sibling
+ * temp file, then rename it over the target, retrying a rename the OS
+ * refuses transiently. Creates the parent directory if missing.
+ * @returns ok when the file holds the new map; save-failed when it does not,
+ *   in which case the previous content is intact and the call may be retried.
+ */
+export function saveMapFile(path, map) {
+    const textError = mapTextError(map);
+    if (textError)
+        return err({ kind: 'save-failed', path, detail: textError });
+    return writeFileAtomic(path, serializeMap(map));
+}

package/lib/store/migration.d.ts

@@ -0,0 +1,12 @@
+/** Project-relative location of the pre-0.20 default page file. */
+export declare const LEGACY_STATE_FILE_RELATIVE_PATH: string;
+/**
+ * Move a legacy `.claude` store — map, pages, and mapping-policy config —
+ * into the tool-owned `.mellos` location. Never merges: a project whose new
+ * store already holds anything keeps it untouched, whatever the legacy
+ * directory still contains.
+ * @param defaultFile - the NEW default page path (`<root>/.mellos/map.json`);
+ *   the legacy store is looked up relative to `<root>`.
+ * @returns whether a legacy store was moved.
+ */
+export declare function migrateLegacyStore(defaultFile: string): boolean;

package/lib/store/migration.js

@@ -0,0 +1,46 @@
+import { existsSync, mkdirSync, renameSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { PAGES_DIR_NAME } from './pages.js';
+import { configFilePath } from './policy.js';
+// ---------------------------------------------------------------------------
+// legacy migration — stores written under the old host-coupled location
+// ---------------------------------------------------------------------------
+//
+// Up to 0.19 the store lived in `.claude/mellos-mapping.*`: the map's home
+// was coupled to one host brand, which turned absurd the moment another host
+// (a harness, Codex) drove the same server. The move is one-time and
+// explicit — entry points call it before touching the store; nothing here
+// runs as a hidden side effect of ordinary loads.
+/** Project-relative location of the pre-0.20 default page file. */
+export const LEGACY_STATE_FILE_RELATIVE_PATH = join('.claude', 'mellos-mapping.json');
+const LEGACY_PAGES_DIR_NAME = 'mellos-mapping.pages';
+const LEGACY_CONFIG_FILE_NAME = 'mellos-mapping.config.json';
+/**
+ * Move a legacy `.claude` store — map, pages, and mapping-policy config —
+ * into the tool-owned `.mellos` location. Never merges: a project whose new
+ * store already holds anything keeps it untouched, whatever the legacy
+ * directory still contains.
+ * @param defaultFile - the NEW default page path (`<root>/.mellos/map.json`);
+ *   the legacy store is looked up relative to `<root>`.
+ * @returns whether a legacy store was moved.
+ */
+export function migrateLegacyStore(defaultFile) {
+    const projectRoot = dirname(dirname(defaultFile));
+    const legacyDefault = join(projectRoot, LEGACY_STATE_FILE_RELATIVE_PATH);
+    const legacyPages = join(dirname(legacyDefault), LEGACY_PAGES_DIR_NAME);
+    const legacyConfig = join(dirname(legacyDefault), LEGACY_CONFIG_FILE_NAME);
+    const hasLegacy = existsSync(legacyDefault) || existsSync(legacyPages) || existsSync(legacyConfig);
+    const hasCurrent = existsSync(defaultFile)
+        || existsSync(join(dirname(defaultFile), PAGES_DIR_NAME))
+        || existsSync(configFilePath(defaultFile));
+    if (!hasLegacy || hasCurrent)
+        return false;
+    mkdirSync(dirname(defaultFile), { recursive: true });
+    if (existsSync(legacyDefault))
+        renameSync(legacyDefault, defaultFile);
+    if (existsSync(legacyPages))
+        renameSync(legacyPages, join(dirname(defaultFile), PAGES_DIR_NAME));
+    if (existsSync(legacyConfig))
+        renameSync(legacyConfig, configFilePath(defaultFile));
+    return true;
+}