mellos-mapping 0.19.0 → 0.20.2

package/lib/semantics/semantics.js

@@ -0,0 +1,380 @@
+/**
+ * Layer 1c — medium-neutral VIEW SEMANTICS of a MellosMap.
+ *
+ * Every renderer (the terminal pane, a web panel, a future editor view) must
+ * agree on what a zoom step MEANS, when a map aggregates into its groups,
+ * how sequence time is oriented, and which map kinds render neutrally.
+ * Those rules live here, pure of any medium: no cells, no colors, no DOM,
+ * no I/O. Geometry — how a mode maps onto character cells or pixels — stays
+ * private to each renderer.
+ *
+ * The shared ALPHABET (status glyphs, spinner frames, node-kind glyphs) is
+ * medium-neutral for the same reason and lives beside this file in
+ * ./vocabulary.js, re-exported here so consumers keep one import site.
+ */
+import { groupStatus } from '../domain/ops.js';
+export { NODE_KIND_GLYPHS, SPINNER_FRAMES, STATUS_GLYPHS, UNVERIFIED_DONE_GLYPHS, kindGlyph, spinnerGlyph, statusGlyph, unverifiedDoneGlyph, } from './vocabulary.js';
+export const ZOOM_MIN = -4;
+export const ZOOM_MAX = 2;
+export const ZOOM_DEFAULT = 0;
+export function clampZoom(n) {
+    return Math.max(ZOOM_MIN, Math.min(ZOOM_MAX, Math.round(n)));
+}
+/**
+ * What a zoom step MEANS, before any renderer decides what it looks like:
+ * scaling only compresses, the ends of the ladder switch mode. 'detail'
+ * unfolds evidence and design notes; 'overview' switches to the aggregated
+ * far view (groups become the nodes — see aggregateMap); 'boxes' is every
+ * step in between, where boxes stay boxes and only whitespace and label
+ * budgets change.
+ */
+export function zoomMode(zoom) {
+    if (zoom >= 1)
+        return 'detail';
+    if (zoom <= -4)
+        return 'overview';
+    return 'boxes';
+}
+/** What a footer shows: a percentage while scaling, a mode name at the ends. */
+export function zoomLabel(zoom) {
+    switch (zoom) {
+        case 2:
+            return 'detail+';
+        case 1:
+            return 'detail';
+        case 0:
+            return '100%';
+        case -1:
+            return '85%';
+        case -2:
+            return '70%';
+        case -3:
+            return '55%';
+        case -4:
+            return 'overview';
+    }
+}
+// ---------------------------------------------------------------------------
+// kind semantics
+// ---------------------------------------------------------------------------
+/** Documentation kinds render neutrally: no status skins, no progress counts. */
+export function isNeutralKind(map) {
+    return map.kind !== undefined && map.kind !== 'dev';
+}
+// ---------------------------------------------------------------------------
+// derived views (never persisted)
+// ---------------------------------------------------------------------------
+/**
+ * The derived coarse picture the far zoom renders when the map declares
+ * groups: each group becomes ONE labeled node (status derived from members,
+ * label carrying done/total), ungrouped nodes stay themselves, and edges
+ * collapse onto representatives (intra-group wiring disappears into the
+ * box). Derived for rendering only — never persisted. A map without groups
+ * returns undefined and falls back to whatever anonymous overview the
+ * renderer draws.
+ */
+export function aggregateMap(map) {
+    if (map.groups.length === 0)
+        return undefined;
+    // VIOLATION: no-primitive-obsession - a GroupId is written into a NodeId
+    // slot below (`g.id as unknown as NodeId`), and the representative table is
+    // keyed by raw strings because it holds both kinds at once. The honest type
+    // would be a `BoxId = NodeId | GroupId` running through MellosMap, every op
+    // and the file format — a domain-wide change for a value that exists only
+    // between this function and a renderer. It is safe for one reason the
+    // domain guarantees rather than this cast: nodes and groups share ONE id
+    // namespace (I10), so no group id can collide with a node id here. The
+    // brands guard PERSISTED maps; this map is never persisted (see the doc
+    // comment above). Follow-up: introduce BoxId with the next format version,
+    // when the file format has to move anyway.
+    const representative = new Map();
+    for (const n of map.nodes)
+        representative.set(n.id, (n.group ?? n.id));
+    const nodes = map.groups.map((g) => {
+        const members = map.nodes.filter((n) => n.group === g.id);
+        const done = members.filter((n) => n.status === 'done').length;
+        return {
+            id: g.id,
+            // neutral kinds document structure, not progress — no member counts
+            label: isNeutralKind(map) ? g.label : `${g.label} ${done}/${members.length}`,
+            layer: g.layer,
+            status: groupStatus(map, g.id),
+        };
+    });
+    for (const n of map.nodes)
+        if (n.group === undefined)
+            nodes.push(n);
+    const seen = new Set();
+    const edges = [];
+    for (const e of map.edges) {
+        const from = representative.get(e.from);
+        const to = representative.get(e.to);
+        if (from === to || seen.has(`${from}->${to}`))
+            continue;
+        seen.add(`${from}->${to}`);
+        edges.push({ from: from, to: to });
+    }
+    return {
+        ...(map.title !== undefined ? { title: map.title } : {}),
+        ...(map.kind !== undefined ? { kind: map.kind } : {}),
+        layers: map.layers,
+        groups: [],
+        lanes: map.lanes,
+        nodes,
+        edges,
+    };
+}
+/**
+ * Derive what a detail panel says about one focused id — a node, or a group
+ * when the far zoom's aggregated boxes are what the pointer is over. Pure
+ * data: every renderer picks its own glyphs, colors, and words (a sequence
+ * page reads uses/usedBy as after/before; that is the caller's vocabulary).
+ * Groups are resolved first, which is unambiguous: one id names one box on
+ * the map (I10), so no node can be shadowed by a group of the same name.
+ * @param map - the map the focus lives in.
+ * @param focusId - node or group id.
+ * @returns the focus view, or undefined when the id names neither.
+ *
+ * VIOLATION: no-primitive-obsession - `focusId` is a raw string, not a brand.
+ * It has to be: the caller is a hit test over the picture, and at the far
+ * zoom that picture is the AGGREGATED map, whose boxes are groups. So the id
+ * arriving here is a NodeId or a GroupId and the caller cannot know which —
+ * deciding that is this function's whole job. `NodeId | GroupId` would type
+ * it, but every hit-test path (BoxHit.id, RenderOptions.focus, the pane's
+ * hover/selection state) would then have to carry that union and cast into it
+ * at the same boundary, moving the cast rather than removing it. The value is
+ * validated the only way it can be: an id that names neither answers
+ * undefined.
+ */
+export function focusInfo(map, focusId) {
+    const layerNameOf = (layerId) => map.layers.find((l) => l.id === layerId)?.name ?? layerId;
+    const group = map.groups.find((g) => g.id === focusId);
+    if (group) {
+        const members = map.nodes.filter((n) => n.group === group.id);
+        const memberIds = new Set(members.map((n) => n.id));
+        // A neighbour is shown as its own group when it has one, else as itself.
+        const rep = (id) => {
+            const n = map.nodes.find((x) => x.id === id);
+            const owner = n.group !== undefined ? map.groups.find((g) => g.id === n.group) : undefined;
+            return owner !== undefined
+                ? { id: owner.id, label: owner.label, status: groupStatus(map, owner.id) }
+                : { id: n.id, label: n.label, status: n.status };
+        };
+        const dedupe = (refs) => {
+            const seen = new Set();
+            const out = [];
+            for (const r of refs) {
+                if (seen.has(r.id))
+                    continue;
+                seen.add(r.id);
+                out.push(r);
+            }
+            return out;
+        };
+        return {
+            kind: 'group',
+            group,
+            status: groupStatus(map, group.id),
+            layerName: layerNameOf(group.layer),
+            members,
+            uses: dedupe(map.edges
+                .filter((e) => memberIds.has(e.from) && !memberIds.has(e.to))
+                .map((e) => rep(e.to))),
+            usedBy: dedupe(map.edges
+                .filter((e) => memberIds.has(e.to) && !memberIds.has(e.from))
+                .map((e) => rep(e.from))),
+        };
+    }
+    const node = map.nodes.find((n) => n.id === focusId);
+    if (!node)
+        return undefined;
+    const ref = (id, edgeLabel) => {
+        const n = map.nodes.find((x) => x.id === id);
+        return {
+            id,
+            label: n?.label ?? id,
+            status: n?.status ?? 'planned',
+            ...(edgeLabel !== undefined ? { edgeLabel } : {}),
+        };
+    };
+    const laneLabel = node.lane !== undefined ? map.lanes.find((l) => l.id === node.lane)?.label : undefined;
+    return {
+        kind: 'node',
+        node,
+        layerName: layerNameOf(node.layer),
+        ...(laneLabel !== undefined ? { laneLabel } : {}),
+        uses: map.edges.filter((e) => e.from === node.id).map((e) => ref(e.to, e.label)),
+        usedBy: map.edges.filter((e) => e.to === node.id).map((e) => ref(e.from, e.label)),
+    };
+}
+// ---------------------------------------------------------------------------
+// page-set semantics — which pages are siblings, and where a dive came from
+// ---------------------------------------------------------------------------
+//
+// VIOLATION: no-primitive-obsession - page slugs cross this section as raw
+// strings (submapRefs, interiorPages, diveParent), never as a brand. This is
+// exactly where the system's TWO brands over one grammar have to meet: a
+// node's `submap` is a SubmapRef (Layer 0, a reference a map declares) and a
+// page identity is a PageId (Layer 1a, what the store calls a file). Typing
+// these parameters as either brand would force every caller on the other side
+// to cast into it — moving the cast, not removing it — and unifying the two
+// would make Layer 0 name a persistence concept. What these functions do with
+// a slug is compare it; none parses or resolves one, and both brands are
+// validated against the same rule where they enter the system (the tool
+// schema and the file format).
+/**
+ * Page slugs some node of any map dives into — the raw fact only, WITHOUT
+ * the rule a sibling strip needs on top of it (that is interiorPages).
+ * @param maps - every known page's map (undefined entries are skipped).
+ * @returns the referenced submap slugs.
+ */
+export function submapRefs(maps) {
+    const refs = new Set();
+    for (const m of maps) {
+        for (const n of m?.nodes ?? [])
+            if (n.submap !== undefined)
+                refs.add(n.submap);
+    }
+    return refs;
+}
+/**
+ * Which pages are INTERIOR: reached by diving through a node, never by
+ * sitting beside their parent as a sibling tab.
+ *
+ * "Referenced by anyone" is NOT the rule, because a strip computed that way
+ * can erase itself. Two refinements make it total:
+ *   - a page never hides itself. A node whose submap names its own page is a
+ *     loop with no bottom, not a parent link — read as one, it deleted the
+ *     tab of the very page it was drawn on.
+ *   - a page referenced only from pages it can itself reach keeps its tab. A
+ *     link cycle has no outside, so hiding every page in it leaves a strip
+ *     with nothing in it and a client with nowhere left to go.
+ * Everything else is interior: some page OUTSIDE its own loop dives into it,
+ * and that page's node is the way in.
+ *
+ * @param pages - every known page as (slug, map) pairs; the default page has
+ *   no slug a node could name, so it is passed as undefined and is never
+ *   interior. Entries with no map (unreadable, not yet loaded) contribute no
+ *   links.
+ * @returns the slugs to keep out of a sibling strip.
+ */
+export function interiorPages(pages) {
+    /** slug -> the pages it dives into. */
+    const dives = new Map();
+    /** slug -> the pages that dive into it (undefined = the default page). */
+    const divedIntoBy = new Map();
+    for (const [slug, map] of pages) {
+        const targets = new Set();
+        for (const n of map?.nodes ?? []) {
+            const target = n.submap;
+            if (target === undefined || target === slug)
+                continue;
+            targets.add(target);
+            const sources = divedIntoBy.get(target) ?? new Set();
+            sources.add(slug);
+            divedIntoBy.set(target, sources);
+        }
+        if (slug !== undefined)
+            dives.set(slug, targets);
+    }
+    /** Every page reachable from `start` by following submap links onward. */
+    const reachableFrom = (start) => {
+        const seen = new Set();
+        const pending = [start];
+        while (pending.length > 0) {
+            for (const target of dives.get(pending.pop()) ?? []) {
+                if (seen.has(target))
+                    continue;
+                seen.add(target);
+                pending.push(target);
+            }
+        }
+        return seen;
+    };
+    const interior = new Set();
+    for (const [target, sources] of divedIntoBy) {
+        const outward = reachableFrom(target);
+        for (const source of sources) {
+            // the default page (undefined) is never reachable: it has no slug
+            if (source === undefined || !outward.has(source)) {
+                interior.add(target);
+                break;
+            }
+        }
+    }
+    return interior;
+}
+/**
+ * Where a sub-map page was dived into from: the entry whose map links the
+ * page, plus the linking node's label. Derived by scan, so a breadcrumb
+ * survives any client restart with an empty dive stack.
+ * @param entries - known pages as (key, map) pairs; keys are caller-owned.
+ * @param pageId - the sub-map page's slug.
+ * @returns the linking entry's key and node label, or undefined for a top-level page.
+ */
+export function diveParent(entries, pageId) {
+    for (const [key, m] of entries) {
+        const node = m?.nodes.find((n) => n.submap === pageId);
+        if (node !== undefined)
+            return { parent: key, label: node.label };
+    }
+    return undefined;
+}
+/**
+ * The page a client shows when nobody asked for one: the most recently
+ * WRITTEN page — the ledger last touched is almost always the effort under
+ * way. Keys without a readable timestamp lose; an empty set answers the
+ * first key (caller-ordered: default page first, then slug order).
+ * @param keys - candidate page keys in the caller's fallback order.
+ * @param mtimeOf - last-written timestamp of a key, undefined when unknown.
+ * @returns the winning key, or undefined for an empty candidate set.
+ *
+ * VIOLATION: prefer-objects - `mtimeOf` is a function parameter, which this
+ * layer otherwise avoids. It is what keeps the rule medium-neutral: the two
+ * callers ask different worlds for the same fact — the pane stats a file, the
+ * browser panel reads an mtime the host already sent over the wire — and
+ * neither timestamp source can be named here without dragging a filesystem or
+ * a transport into a module that must stay free of both. The alternative,
+ * taking `readonly [K, number | undefined][]`, only moves the same lookup to
+ * the caller and makes it allocate a pair per page per tick. The parameter is
+ * a pure query, called once per key, never stored.
+ */
+export function mostRecentKey(keys, mtimeOf) {
+    let best;
+    let bestMtime = -Infinity;
+    for (const key of keys) {
+        const mtime = mtimeOf(key);
+        if (mtime !== undefined && mtime > bestMtime) {
+            best = key;
+            bestMtime = mtime;
+        }
+    }
+    return best ?? keys[0];
+}
+/**
+ * Sequence pages read like the classic diagram: time flows DOWNWARD, the
+ * earliest step right under the participant headers. The stored map keeps
+ * rank 0 = earliest with edges pointing later -> earlier ("later stands on
+ * earlier"); this derived value inverts the ranks and reverses the edges so
+ * unchanged top-down machinery draws top-down time — each wire now runs
+ * from the sender's moment down into the receiver's. Derived for rendering
+ * only, never persisted (same contract as aggregateMap).
+ */
+export function flipForSequence(map) {
+    if (map.kind !== 'sequence')
+        return map;
+    return {
+        ...map,
+        // VIOLATION: state-explicit-in-types - `-l.rank as Rank` produces a value
+        // the Rank brand promises cannot exist: mirroring 0..99 gives -99..0, and
+        // makeRank would refuse every one of them. The alternative is a second
+        // ordered-position type (an unbranded `order` field) threaded through the
+        // renderer's whole layout stage purely so this one derived map can be
+        // typed — a large change to express "these ranks are an order, not a
+        // stored value". What makes it safe is the same thing that makes it
+        // wrong: this map only ever reaches a renderer, which compares ranks and
+        // never writes them (same contract as aggregateMap).
+        layers: map.layers.map((l) => ({ ...l, rank: -l.rank })),
+        edges: map.edges.map((e) => ({ from: e.to, to: e.from, ...(e.label !== undefined ? { label: e.label } : {}) })),
+    };
+}

package/lib/semantics/vocabulary.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Layer 1c — the medium-neutral VISUAL VOCABULARY of a map.
+ *
+ * A status and a node kind each have ONE agreed glyph. Not because glyphs are
+ * semantics — they are not — but because they are the map's shared alphabet:
+ * the terminal picture, the pane's tab strip and detail panel, and a browser
+ * view all show the same map to the same person, and a status that reads ⠿ in
+ * one place and ◐ in another is a lie about the map being one thing. The
+ * table lived in three files and had already drifted; it lives here now, and
+ * every medium reads it.
+ *
+ * What stays with each renderer is what its medium OWNS: SGR parameters and
+ * cell geometry in the terminal, CSS and SVG in a browser. This module has no
+ * colors, no cells, no DOM, no I/O — and no node:* imports, so it loads in a
+ * browser as-is (see ../browser-safe.test.ts).
+ *
+ * Exported through ./semantics.js so consumers keep one import site.
+ */
+import type { NodeStatus } from '../domain/types.js';
+/**
+ * Status -> [unicode, ascii] glyph, both display width 1.
+ *
+ * The in-progress glyph is the braille spinner AT REST: a surface that cannot
+ * animate (a tab, a panel line, a static page) shows the settled form of the
+ * same shape the animated boxes cycle through, so one status still reads as
+ * one thing across media.
+ */
+export declare const STATUS_GLYPHS: Readonly<Record<NodeStatus, readonly [unicode: string, ascii: string]>>;
+/**
+ * The glyph a status shows where nothing animates.
+ * @param unicode - false selects the ASCII fallback for terminals that cannot
+ *   draw the box-drawing/braille repertoire.
+ */
+export declare function statusGlyph(status: NodeStatus, unicode: boolean): string;
+/**
+ * The glyph a DONE node wears when nothing was recorded to back the claim.
+ *
+ * "No evidence, no done" is the fourth rule of the ledger, and until now the
+ * picture could not say when it was broken: a done node with a test run
+ * behind it and a done node with nothing behind it were the same solid
+ * square. The hollow square is deliberately the SAME SHAPE — this is still
+ * done, just not filled in — so it reads as a degree of done, not as a fifth
+ * status. There is no fifth status: evidence is a property of a node, and
+ * whether it exists is presentation, not structure.
+ */
+export declare const UNVERIFIED_DONE_GLYPHS: readonly [unicode: string, ascii: string];
+/** The glyph for a done node with no evidence; see {@link UNVERIFIED_DONE_GLYPHS}. */
+export declare function unverifiedDoneGlyph(unicode: boolean): string;
+/**
+ * Animation frames for in-progress work, per repertoire. The caller owns the
+ * clock: it advances a frame index and this module maps it to a glyph, so
+ * every animated surface spins at whatever rate its medium can paint while
+ * showing the same shapes.
+ */
+export declare const SPINNER_FRAMES: Readonly<Record<'unicode' | 'ascii', readonly string[]>>;
+/**
+ * One spinner frame.
+ * @param frame - any integer; it wraps, negatives included, so a caller's
+ *   clock never has to be normalized before it is used.
+ */
+export declare function spinnerGlyph(frame: number, unicode: boolean): string;
+/**
+ * Known node kinds -> [unicode, ascii] glyphs (all display width 1).
+ * Behavior trees, dataflow and architecture vocabularies; an unknown kind
+ * renders without a glyph and stays readable in a detail panel.
+ */
+export declare const NODE_KIND_GLYPHS: Readonly<Record<string, readonly [string, string]>>;
+/**
+ * Glyph for a node kind, or undefined for the open vocabulary's unknown kinds.
+ *
+ * VIOLATION: no-primitive-obsession - `kind` is a raw string where NodeKind
+ * exists. NodeKind is an OPEN vocabulary by design (the domain accepts any
+ * slug; this table knows thirteen of them), so the brand carries no
+ * information this function could use — it answers undefined for anything it
+ * does not know, branded or not. Requiring NodeKind would only force every
+ * caller reading `node.kind` to unwrap and re-wrap it, and would not let a
+ * single wrong call through any less.
+ */
+export declare function kindGlyph(kind: string, unicode: boolean): string | undefined;

package/lib/semantics/vocabulary.js

@@ -0,0 +1,112 @@
+/**
+ * Layer 1c — the medium-neutral VISUAL VOCABULARY of a map.
+ *
+ * A status and a node kind each have ONE agreed glyph. Not because glyphs are
+ * semantics — they are not — but because they are the map's shared alphabet:
+ * the terminal picture, the pane's tab strip and detail panel, and a browser
+ * view all show the same map to the same person, and a status that reads ⠿ in
+ * one place and ◐ in another is a lie about the map being one thing. The
+ * table lived in three files and had already drifted; it lives here now, and
+ * every medium reads it.
+ *
+ * What stays with each renderer is what its medium OWNS: SGR parameters and
+ * cell geometry in the terminal, CSS and SVG in a browser. This module has no
+ * colors, no cells, no DOM, no I/O — and no node:* imports, so it loads in a
+ * browser as-is (see ../browser-safe.test.ts).
+ *
+ * Exported through ./semantics.js so consumers keep one import site.
+ */
+/**
+ * Status -> [unicode, ascii] glyph, both display width 1.
+ *
+ * The in-progress glyph is the braille spinner AT REST: a surface that cannot
+ * animate (a tab, a panel line, a static page) shows the settled form of the
+ * same shape the animated boxes cycle through, so one status still reads as
+ * one thing across media.
+ */
+export const STATUS_GLYPHS = {
+    planned: ['·', '.'],
+    'in-progress': ['⠿', '*'],
+    done: ['■', '#'],
+    regressed: ['✗', 'X'],
+};
+/**
+ * The glyph a status shows where nothing animates.
+ * @param unicode - false selects the ASCII fallback for terminals that cannot
+ *   draw the box-drawing/braille repertoire.
+ */
+export function statusGlyph(status, unicode) {
+    const [uni, ascii] = STATUS_GLYPHS[status];
+    return unicode ? uni : ascii;
+}
+/**
+ * The glyph a DONE node wears when nothing was recorded to back the claim.
+ *
+ * "No evidence, no done" is the fourth rule of the ledger, and until now the
+ * picture could not say when it was broken: a done node with a test run
+ * behind it and a done node with nothing behind it were the same solid
+ * square. The hollow square is deliberately the SAME SHAPE — this is still
+ * done, just not filled in — so it reads as a degree of done, not as a fifth
+ * status. There is no fifth status: evidence is a property of a node, and
+ * whether it exists is presentation, not structure.
+ */
+export const UNVERIFIED_DONE_GLYPHS = ['□', 'o'];
+/** The glyph for a done node with no evidence; see {@link UNVERIFIED_DONE_GLYPHS}. */
+export function unverifiedDoneGlyph(unicode) {
+    const [uni, ascii] = UNVERIFIED_DONE_GLYPHS;
+    return unicode ? uni : ascii;
+}
+/**
+ * Animation frames for in-progress work, per repertoire. The caller owns the
+ * clock: it advances a frame index and this module maps it to a glyph, so
+ * every animated surface spins at whatever rate its medium can paint while
+ * showing the same shapes.
+ */
+export const SPINNER_FRAMES = {
+    unicode: ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'],
+    ascii: ['|', '/', '-', '\\'],
+};
+/**
+ * One spinner frame.
+ * @param frame - any integer; it wraps, negatives included, so a caller's
+ *   clock never has to be normalized before it is used.
+ */
+export function spinnerGlyph(frame, unicode) {
+    const frames = SPINNER_FRAMES[unicode ? 'unicode' : 'ascii'];
+    return frames[((frame % frames.length) + frames.length) % frames.length];
+}
+/**
+ * Known node kinds -> [unicode, ascii] glyphs (all display width 1).
+ * Behavior trees, dataflow and architecture vocabularies; an unknown kind
+ * renders without a glyph and stays readable in a detail panel.
+ */
+export const NODE_KIND_GLYPHS = {
+    selector: ['?', '?'],
+    sequence: ['»', '>'],
+    parallel: ['‖', '='],
+    decorator: ['◌', 'o'],
+    condition: ['◇', 'c'],
+    action: ['·', '.'],
+    source: ['○', 'o'],
+    transform: ['◐', '%'],
+    sink: ['●', '*'],
+    service: ['◆', 'S'],
+    db: ['▤', 'D'],
+    queue: ['≣', 'Q'],
+    ui: ['▣', 'U'],
+};
+/**
+ * Glyph for a node kind, or undefined for the open vocabulary's unknown kinds.
+ *
+ * VIOLATION: no-primitive-obsession - `kind` is a raw string where NodeKind
+ * exists. NodeKind is an OPEN vocabulary by design (the domain accepts any
+ * slug; this table knows thirteen of them), so the brand carries no
+ * information this function could use — it answers undefined for anything it
+ * does not know, branded or not. Requiring NodeKind would only force every
+ * caller reading `node.kind` to unwrap and re-wrap it, and would not let a
+ * single wrong call through any less.
+ */
+export function kindGlyph(kind, unicode) {
+    const pair = NODE_KIND_GLYPHS[kind];
+    return pair === undefined ? undefined : unicode ? pair[0] : pair[1];
+}

package/lib/store/format.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Layer 1a — the state-file FORMAT of a MellosMap, pure of any I/O.
+ *
+ * This module owns the on-disk vocabulary (version, page-id grammar) and the
+ * two format promises every consumer relies on:
+ *
+ *   P1. Whatever parseMap accepts satisfies the structural invariants of
+ *       Layer 0. Parsing is done by REPLAYING the raw data through the domain
+ *       operations, so a hand-edited or corrupted file can never smuggle an
+ *       invariant violation into the process (validate at the boundary,
+ *       trust internal code afterwards).
+ *       The shape is read STRICTLY: a wrong type is refused, never coerced
+ *       and never quietly dropped. The reason is that the store round-trips —
+ *       a lenient read of `{"nodes": {...}}` as "no nodes" would be written
+ *       back by the next save, so leniency here does not tolerate a damaged
+ *       file, it destroys one.
+ *   F1. serializeMap is the inverse of parseMap for valid maps.
+ *
+ * No node:* imports — this module must load in a browser as-is. Filesystem
+ * concerns (atomic writes, page file listing, focus requests) live in
+ * ./store.ts, the Node-side half.
+ */
+import { type InvalidId, type MapError, type MellosMap, type Result } from '../domain/types.js';
+/** On-disk format version. Bump only with a documented migration. */
+export declare const STATE_FILE_VERSION = 1;
+export type PageId = string & {
+    readonly __brand: 'PageId';
+};
+export declare function makePageId(raw: string): Result<PageId, InvalidId>;
+export type StoreError = {
+    readonly kind: 'not-found';
+    readonly path: string;
+} | {
+    readonly kind: 'malformed-json';
+    readonly path: string;
+    readonly detail: string;
+} | {
+    readonly kind: 'bad-shape';
+    readonly path: string;
+    readonly detail: string;
+} | {
+    readonly kind: 'invariant-violation';
+    readonly path: string;
+    readonly violation: MapError;
+}
+/** A write that did not land. The file still holds its previous content. */
+ | {
+    readonly kind: 'save-failed';
+    readonly path: string;
+    readonly detail: string;
+}
+/** A deletion the filesystem refused. The file is still there. */
+ | {
+    readonly kind: 'delete-failed';
+    readonly path: string;
+    readonly detail: string;
+};
+export declare function describeStoreError(e: StoreError): string;
+/**
+ * Rebuild a MellosMap from untrusted raw data by replaying it through the
+ * Layer 0 operations (P1). Field order in the file does not matter; replay
+ * order (layers -> lanes -> groups -> nodes -> edges) supplies the required
+ * declaration order.
+ */
+export declare function parseMap(raw: unknown, path: string): Result<MellosMap, StoreError>;
+/** Serialize a map into the on-disk shape. Inverse of parseMap for valid maps (F1). */
+export declare function serializeMap(map: MellosMap): string;