nook: add minimapview, the overview render layer over the geometry model

Author: truffle-dev

cmd/nook/ROADMAP.md

@@ -81,14 +81,19 @@ Roughly in priority order.
    the first slice proves that keeps the binary lean before any host
    wiring lands.
 4. **Minimap.** Optional document overview gutter. Lowest priority;
-   useful but not load-bearing for the editing experience. The geometry
-   foundation is in place: `internal/minimap` is a pure, constant-time
-   `Model` that maps between source lines and minimap rows (`LineRange`,
-   `RowForLine`, `ViewportWindow` for the highlight band, `LineForRow`
-   for click-to-scroll), fully unit-tested, no I/O, inside the
-   first-paint rule. What remains is host wiring: rendering the column
-   from per-row buffer density, drawing the viewport band, and routing
-   click-to-scroll.
+   useful but not load-bearing for the editing experience. Two of the
+   three pure layers are in place, both fully unit-tested and inside the
+   first-paint rule. `internal/minimap` is the geometry `Model` that maps
+   between source lines and minimap rows (`LineRange`, `RowForLine`,
+   `ViewportWindow` for the highlight band, `LineForRow` for
+   click-to-scroll). `internal/minimapview` is the render layer the
+   geometry deliberately left to the host: `LineFill` scores a line's
+   code density, `Density` collapses per-line fills onto rows, and
+   `Column` turns a `Model` plus densities into `Cell`s carrying a shade
+   glyph, the viewport band, and blank-past-document flags. What remains
+   is the host mount: computing line fills from the buffer each frame,
+   painting the `Cell`s with theme styles beside the editor, and routing
+   a click at a y offset through `LineForRow` to a scroll.
 
 ## How to pick the next slice
 

cmd/nook/internal/minimapview/minimapview.go

@@ -0,0 +1,163 @@
+// Package minimapview renders nook's minimap column: it owns the "what a row
+// looks like" half of the overview gutter that the minimap package deliberately
+// leaves to the host. Given a minimap.Model (where each row sits) and the code
+// density of the document's lines (how full each line is), it produces the
+// per-row cells the host paints — the shade ramp that stands in for content and
+// the viewport highlight band. Like minimap itself it is pure geometry over
+// numbers: no I/O, no buffer access, no lipgloss, constant-time per frame, so it
+// stays inside nook's first-paint rule. The host computes a fill per line once
+// from the buffer, maps it onto rows with Density, turns the rows into Cells
+// with Column, and applies its own theme styles to Glyph and InViewport.
+package minimapview
+
+import "github.com/truffle-dev/glyph/cmd/nook/internal/minimap"
+
+// Shade ramp, from empty to full. A row's code density picks one glyph: a blank
+// region reads as space, a dense region as a full block, with three shades in
+// between so the overview has depth instead of an on/off silhouette.
+const (
+	shadeEmpty  = ' '
+	shadeLight  = '░' // U+2591
+	shadeMedium = '▒' // U+2592
+	shadeDark   = '▓' // U+2593
+	shadeFull   = '█' // U+2588
+)
+
+// Cell is the drawable state of one minimap row, ready for the host to style.
+// Glyph is the density shade; InViewport marks the rows under the highlight
+// band; Blank marks rows past the end of a short document, which paint empty
+// regardless of density.
+type Cell struct {
+	Glyph      rune
+	InViewport bool
+	Blank      bool
+}
+
+// Shade maps a code-density fraction to the overview ramp glyph. Values are
+// clamped to [0,1]; exactly zero is the empty glyph, and the four filled bands
+// split the remainder into quarters so a barely-filled row still shows.
+func Shade(density float64) rune {
+	switch {
+	case density <= 0:
+		return shadeEmpty
+	case density <= 0.25:
+		return shadeLight
+	case density <= 0.5:
+		return shadeMedium
+	case density <= 0.75:
+		return shadeDark
+	default:
+		return shadeFull
+	}
+}
+
+// LineFill returns the code density of a single source line in [0,1]: the
+// fraction of its runes that are not whitespace. A blank or whitespace-only
+// line reads as empty (0), a line with no whitespace as full (1), and typical
+// code somewhere between so indentation and sparse lines read lighter than
+// dense ones. Rune-counted, not byte-counted, so multi-byte source measures
+// the same as ASCII.
+func LineFill(line string) float64 {
+	total := 0
+	code := 0
+	for _, r := range line {
+		total++
+		if !isSpace(r) {
+			code++
+		}
+	}
+	if total == 0 {
+		return 0
+	}
+	return float64(code) / float64(total)
+}
+
+func isSpace(r rune) bool {
+	return r == ' ' || r == '\t' || r == '\n' || r == '\r' || r == '\v' || r == '\f'
+}
+
+// Density collapses per-line fills onto minimap rows for a Model. fills[i] is
+// the code density of logical line i (see LineFill); the host computes it once
+// from the buffer. Each returned entry is the mean fill of the lines its row
+// covers (minimap.LineRange), so a downsampled row reads as the average density
+// of the block it stands for. The result is always m.MapHeight long (empty when
+// the map is inactive); rows past a short document average to 0. A line index
+// beyond len(fills) counts as 0 so a stale-but-shorter fills slice degrades to
+// a lighter overview rather than panicking.
+func Density(m minimap.Model, fills []float64) []float64 {
+	if m.MapHeight <= 0 {
+		return nil
+	}
+	out := make([]float64, m.MapHeight)
+	if !m.Active() {
+		return out
+	}
+	for row := 0; row < m.MapHeight; row++ {
+		start, end := m.LineRange(row)
+		if end <= start {
+			continue // past the document: leave 0
+		}
+		sum := 0.0
+		for line := start; line < end; line++ {
+			if line >= 0 && line < len(fills) {
+				sum += fills[line]
+			}
+		}
+		out[row] = sum / float64(end-start)
+	}
+	return out
+}
+
+// Column builds the per-row cells for the whole minimap. density should be
+// m.MapHeight long (as Density returns); a shorter slice treats the missing
+// rows as empty and a longer one ignores the tail, so the caller never has to
+// size-match exactly. Rows whose LineRange is empty (past a short document) are
+// Blank; rows inside m.ViewportWindow() are InViewport. The result is always
+// m.MapHeight long, or empty when the column has no rows.
+func Column(m minimap.Model, density []float64) []Cell {
+	if m.MapHeight <= 0 {
+		return nil
+	}
+	cells := make([]Cell, m.MapHeight)
+	vStart, vEnd := m.ViewportWindow()
+	for row := 0; row < m.MapHeight; row++ {
+		c := Cell{Glyph: shadeEmpty}
+		if !m.Active() {
+			c.Blank = true
+			cells[row] = c
+			continue
+		}
+		start, end := m.LineRange(row)
+		if end <= start {
+			c.Blank = true
+		} else {
+			d := 0.0
+			if row < len(density) {
+				d = density[row]
+			}
+			c.Glyph = Shade(d)
+		}
+		if row >= vStart && row < vEnd {
+			c.InViewport = true
+		}
+		cells[row] = c
+	}
+	return cells
+}
+
+// Runes returns just the glyph column, one row per line, newline-joined and
+// with no viewport styling. It is the plain-text view of a Column — handy for
+// tests and for a host that paints the overview without color.
+func Runes(cells []Cell) string {
+	if len(cells) == 0 {
+		return ""
+	}
+	out := make([]rune, 0, len(cells)*2)
+	for i, c := range cells {
+		if i > 0 {
+			out = append(out, '\n')
+		}
+		out = append(out, c.Glyph)
+	}
+	return string(out)
+}