mellos-mapping 0.19.0 → 0.20.0

package/lib/render/render.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Layer 4 (presentation) — pure rendering of a MellosMap to terminal lines.
+ *
+ * Shared by the MCP `mmap_view` tool (monochrome) and the split-pane watcher
+ * (colored, animated). Pure function of (map, options): no I/O, no clock —
+ * animation is driven by the caller passing a spinner frame index.
+ *
+ * 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
+ *   nodes. Junctions where a wire enters a box inherit the box's color,
+ *   like lit pins. Dependency lines only ever travel downward.
+ *
+ *   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
+ *   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
+ * step would leave labels too short to mean anything does the picture switch
+ * mode — to a borderless glyph constellation whose band bars carry
+ * done/total counts. Zooming in past 100% unfolds evidence and design notes
+ * inside the boxes; a second step widens the boxes and unfolds the notes
+ * further. The ladder, one wheel tick per step:
+ *   +2   detail+       wider boxes, design notes unfold almost fully
+ *   +1   detail        evidence + design notes unfold inside boxes
+ *    0   100%          the standard working view (default, unchanged)
+ *   -1   85%           labels truncated to 85%, geometry still roomy
+ *   -2   70%           padding and breathing rows collapse
+ *   -3   55%           tightest meaningful boxes; band bars gain done/total
+ *   -4   overview      MODE SWITCH: borderless status glyphs, pure topology
+ * The same layout/routing machinery runs at every step; only the per-node
+ * 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;
+/** 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. */
+export interface BoxHit {
+    readonly id: string;
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+}
+export interface WindowedRender {
+    readonly lines: string[];
+    /** Full extent of the picture, for viewport clamping. */
+    readonly contentWidth: number;
+    readonly contentHeight: number;
+    /** Node hit regions in full-picture coordinates, for mouse interaction. */
+    readonly hits: readonly BoxHit[];
+}
+/** Render only the given viewport of the map, plus the full content extent. */
+export declare function renderMapWindow(map: MellosMap, opts: RenderOptions, viewport: Viewport): WindowedRender;