mellos-mapping 0.20.0 → 0.20.2

package/lib/render/options.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Layer 4a — what a caller asks the renderer for.
+ *
+ * Every stage below (canvas, skins, layout, drawing) reads these, so they
+ * live in a module of their own rather than in whichever stage happens to
+ * touch them first: a picture's inputs are not the property of one stage.
+ *
+ * Pure types; no behavior.
+ */
+import type { ZoomStep } from '../semantics/semantics.js';
+export interface RenderOptions {
+    /** Emit ANSI color codes. */
+    readonly color: boolean;
+    /** Use box-drawing characters; false falls back to pure ASCII. */
+    readonly unicode: boolean;
+    /** Spinner frame index for in-progress nodes; caller advances it over time. */
+    readonly spinnerFrame: number;
+    /**
+     * Id of the BOX to spotlight: its border and every wire touching it render
+     * bright instead of faint. Color mode only — monochrome output ignores it.
+     *
+     * VIOLATION: no-primitive-obsession - a raw string where NodeId exists,
+     * because at the far zoom the boxes are aggregated GROUPS, so this is a
+     * NodeId or a GroupId and the caller (a hit test) cannot know which. See
+     * focusInfo in ../semantics/semantics.ts, which resolves the same value and
+     * carries the full reasoning; typing it here as a union would only move the
+     * cast to whichever side of the hit test names it first.
+     */
+    readonly focus?: string | undefined;
+    /** Position on the zoom ladder; omitted means ZOOM_DEFAULT (100%). */
+    readonly zoom?: ZoomStep | undefined;
+}
+/** A window over the rendered picture, in cell coordinates (0-based). */
+export interface Viewport {
+    readonly x: number;
+    readonly y: number;
+    readonly width: number;
+    readonly height: number;
+}

package/lib/render/options.js

@@ -0,0 +1,10 @@
+/**
+ * Layer 4a — what a caller asks the renderer for.
+ *
+ * Every stage below (canvas, skins, layout, drawing) reads these, so they
+ * live in a module of their own rather than in whichever stage happens to
+ * touch them first: a picture's inputs are not the property of one stage.
+ *
+ * Pure types; no behavior.
+ */
+export {};

package/lib/render/render.d.ts

@@ -5,6 +5,22 @@
  * (colored, animated). Pure function of (map, options): no I/O, no clock —
  * animation is driven by the caller passing a spinner frame index.
  *
+ * This file is the COMPOSITION ROOT of the picture and holds the public
+ * surface; each stage lives beside it and knows nothing of the next:
+ *
+ *   width.ts          how many columns a string takes (the grid's foundation)
+ *   options.ts        what a caller asks for
+ *   canvas.ts         the drawing surface: cells, mask algebra, ANSI emission
+ *   skins.ts          status vocabulary -> this medium's borders and colors
+ *   zoom-geometry.ts  what one rung of the zoom ladder buys, in cells
+ *   layout.ts         where every box goes (columns, then rows)
+ *   routing.ts        how each edge gets there (columns and track rows)
+ *   draw.ts           transcription of all of the above onto the canvas
+ *
+ * The pipeline reads in that order and only forward: sizes and columns fix
+ * the width, routing needs the columns, the row layout needs routing's track
+ * counts, and drawing needs everything. Nothing drawn is ever decided.
+ *
  * Visual language — a dark circuit board:
  *   rank 0 renders at the BOTTOM of the picture ("primitives are the
  *   ground"). Wiring and band bars are FAINT; the glowing things are the
@@ -14,21 +30,10 @@
  *   planned      dashed dim rounded box, '·'  — a ghost: designed, not built
  *   in-progress  amber rounded box, spinner   — where attention currently is
  *   done         heavy green box, '■'         — built and verified
+ *   done, no evidence   the same box, hollow '□' in a dimmer green — the
+ *                ledger's fourth rule, made visible
  *   regressed    heavy red box, '✗'           — was done, foundation cracked
  *
- * Routing preference, in order:
- *   1. STRAIGHT — an adjacent-band edge whose box borders share a free
- *      column is one vertical line, no corners.
- *   2. DOGLEG — descend, run horizontally on a track row in the gap above
- *      the target band, descend. Tracks are PACKED: segments that do not
- *      overlap share a row, keeping bands close together.
- *   3. THREAD — a skip-level edge descends through the nearest column that
- *      is free of boxes in every intermediate band (threading the needle
- *      between boxes); only if no such column exists does it fall back to a
- *      private column on the right margin.
- * Crossings merge into proper junction characters via a direction-bitmask
- * union instead of any routing cleverness.
- *
  * Zoom — terminals cannot scale glyphs, so zooming out first COMPRESSES the
  * geometry (gaps, breathing rows, padding shrink; labels truncate toward a
  * scale-proportional budget) while boxes stay boxes. Only when a further
@@ -48,42 +53,23 @@
  * box spec (size, border, content) and the whitespace geometry change.
  */
 import type { MellosMap } from '../domain/types.js';
-import { type ZoomStep } from '../semantics/semantics.js';
-export { type ZoomStep, ZOOM_DEFAULT, ZOOM_MAX, ZOOM_MIN, clampZoom, isNeutralKind, zoomLabel } from '../semantics/semantics.js';
-export interface RenderOptions {
-    /** Emit ANSI color codes. */
-    readonly color: boolean;
-    /** Use box-drawing characters; false falls back to pure ASCII. */
-    readonly unicode: boolean;
-    /** Spinner frame index for in-progress nodes; caller advances it over time. */
-    readonly spinnerFrame: number;
-    /**
-     * Node id to spotlight: its box border and every wire touching it render
-     * bright instead of faint. Color mode only — monochrome output ignores it.
-     */
-    readonly focus?: string | undefined;
-    /** Position on the zoom ladder; omitted means ZOOM_DEFAULT (100%). */
-    readonly zoom?: ZoomStep | undefined;
-}
-/** A window over the rendered picture, in cell coordinates (0-based). */
-export interface Viewport {
-    readonly x: number;
-    readonly y: number;
-    readonly width: number;
-    readonly height: number;
-}
-/** Terminal column width of a string (CJK chars occupy two columns). */
-export declare function displayWidth(text: string): number;
-/** Truncate to a display width, ANSI-free input, appending … when cut. */
-export declare function fitWidth(s: string, width: number): string;
-/** Hard word-wrap by display width (CJK-aware, splits anywhere). */
-export declare function wrapWidth(s: string, width: number): string[];
-/** Glyph for a node kind, or undefined for unknown kinds. Shared with the watcher's panel. */
-export declare function kindGlyph(kind: string, unicode: boolean): string | undefined;
+import type { RenderOptions, Viewport } from './options.js';
+export type { RenderOptions, Viewport } from './options.js';
+export { displayWidth, fitWidth, wrapWidth } from './width.js';
+export { statusSgr } from './skins.js';
+export { type ZoomStep, 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 declare function renderMap(map: MellosMap, opts: RenderOptions): string[];
-/** Where a node's box sits on the full (unwindowed) picture, for hit testing. */
+/** Where a box sits on the full (unwindowed) picture, for hit testing. */
 export interface BoxHit {
+    /**
+     * The box's id — a node id, or a GROUP id on the aggregated far zoom.
+     *
+     * VIOLATION: no-primitive-obsession - raw string where NodeId exists, for
+     * the reason spelled out at focusInfo (../semantics/semantics.ts): which of
+     * the two an id names is what the consumer of a hit calls that function to
+     * find out, so this type cannot promise either.
+     */
     readonly id: string;
     readonly x: number;
     readonly y: number;