mellos-mapping 0.20.0 → 0.20.2

package/lib/render/zoom-geometry.js

@@ -0,0 +1,56 @@
+/**
+ * Layer 4a — what one rung of the zoom ladder buys, in terminal cells.
+ *
+ * Terminals cannot scale glyphs, so zooming out COMPRESSES geometry instead:
+ * gaps, breathing rows and padding shrink, labels truncate toward a
+ * scale-proportional budget, and only when a further step would leave labels
+ * too short to mean anything does the picture switch mode. WHICH steps switch
+ * mode is semantics (zoomMode over in ../semantics); this module owns only
+ * the whitespace and label budgets each step spends.
+ */
+import { zoomMode } from '../semantics/semantics.js';
+/** Height of a box with nothing unfolded inside it: border, content, border. */
+export const BOX_H = 3;
+/** Columns between two boxes of one band at the roomy default. */
+export const BOX_GAP = 2;
+/** Columns before the leftmost box; the picture never starts at the edge. */
+export const LEFT_MARGIN = 2;
+/** Bar cells kept left of the narrowest band label, so a band still reads as a band. */
+export const BAR_MIN_RUN = 7;
+/** +1: a readable unfold. +2: the box grows into a reading card. */
+const DETAIL_BUDGET = { innerMin: 22, innerMax: 32, noteRows: 3 };
+const DETAIL_PLUS_BUDGET = { innerMin: 30, innerMax: 48, noteRows: 12 };
+export function zoomGeometry(zoom) {
+    const m = zoomMode(zoom);
+    const mode = m === 'overview' ? 'constellation' : m;
+    switch (zoom) {
+        case 2:
+            return { mode, scale: 1, pad: 1, boxGap: BOX_GAP, breathe: 1, titleGap: 1, barGap: 1, bandCounts: false, detail: DETAIL_PLUS_BUDGET };
+        case 1:
+            return { mode, scale: 1, pad: 1, boxGap: BOX_GAP, breathe: 1, titleGap: 1, barGap: 1, bandCounts: false, detail: DETAIL_BUDGET };
+        case 0:
+            return { mode, scale: 1, pad: 1, boxGap: BOX_GAP, breathe: 1, titleGap: 1, barGap: 1, bandCounts: false };
+        case -1:
+            return { mode, scale: 0.85, pad: 1, boxGap: BOX_GAP, breathe: 1, titleGap: 1, barGap: 1, bandCounts: false };
+        case -2:
+            return { mode, scale: 0.7, pad: 0, boxGap: BOX_GAP, breathe: 0, titleGap: 0, barGap: 1, bandCounts: false };
+        case -3:
+            return { mode, scale: 0.55, pad: 0, boxGap: 1, breathe: 0, titleGap: 0, barGap: 1, bandCounts: true };
+        case -4:
+            return { mode, scale: 0, pad: 0, boxGap: BOX_GAP, breathe: 0, titleGap: 0, barGap: 1, bandCounts: true };
+    }
+}
+/**
+ * Geometry for the aggregated far zoom: tight chrome, but FULL labels — the
+ * point of collapsing a map into its groups is reading their names.
+ */
+export const AGGREGATE_GEO = {
+    mode: 'boxes',
+    scale: 1,
+    pad: 0,
+    boxGap: 1,
+    breathe: 0,
+    titleGap: 0,
+    barGap: 1,
+    bandCounts: false,
+};

package/lib/semantics/semantics.d.ts

@@ -4,11 +4,16 @@
  * 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 glyphs, no DOM,
+ * 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 type { MapGroup, MapNode, MellosMap, NodeStatus } from '../domain/types.js';
+export { NODE_KIND_GLYPHS, SPINNER_FRAMES, STATUS_GLYPHS, UNVERIFIED_DONE_GLYPHS, kindGlyph, spinnerGlyph, statusGlyph, unverifiedDoneGlyph, } from './vocabulary.js';
 /** One wheel tick on the zoom ladder. */
 export type ZoomStep = -4 | -3 | -2 | -1 | 0 | 1 | 2;
 export declare const ZOOM_MIN: ZoomStep;
@@ -73,19 +78,53 @@ export interface GroupFocus {
  * 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 declare function focusInfo(map: MellosMap, focusId: string): NodeFocus | GroupFocus | undefined;
 /**
- * Page slugs some node of any map dives into. A page referenced as a submap
- * is interior detail — it is reached by diving through its linking node,
- * never by sitting beside its parent as a sibling tab.
+ * 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 declare function submapRefs(maps: Iterable<MellosMap | undefined>): Set<string>;
+/**
+ * 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 declare function interiorPages(pages: Iterable<readonly [string | undefined, MellosMap | undefined]>): Set<string>;
 /**
  * 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
@@ -106,6 +145,16 @@ export declare function diveParent<K>(entries: Iterable<readonly [K, MellosMap |
  * @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 declare function mostRecentKey<K>(keys: readonly K[], mtimeOf: (key: K) => number | undefined): K | undefined;
 /**

package/lib/semantics/semantics.js

@@ -4,11 +4,16 @@
  * 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 glyphs, no DOM,
+ * 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;
@@ -71,8 +76,17 @@ export function isNeutralKind(map) {
 export function aggregateMap(map) {
     if (map.groups.length === 0)
         return undefined;
-    // Group ids join the node-id slug space inside this derived value; the
-    // brands only guard PERSISTED maps, and this one never leaves rendering.
+    // 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));
@@ -115,9 +129,22 @@ export function aggregateMap(map) {
  * 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;
@@ -183,10 +210,21 @@ export function focusInfo(map, focusId) {
 // ---------------------------------------------------------------------------
 // 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. A page referenced as a submap
- * is interior detail — it is reached by diving through its linking node,
- * never by sitting beside its parent as a sibling tab.
+ * 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.
  */
@@ -199,6 +237,73 @@ export function submapRefs(maps) {
     }
     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
@@ -223,6 +328,16 @@ export function diveParent(entries, pageId) {
  * @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;
@@ -250,6 +365,15 @@ export function flipForSequence(map) {
         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

@@ -9,6 +9,11 @@
  *       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
@@ -37,6 +42,18 @@ export type StoreError = {
     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;
 /**