feat(grid): allow bounded coarse selection labels (#1537)

Author: D00mch

configs/default-config.toml

@@ -182,6 +182,7 @@ generic_clickable_min_confidence = 0.5       # Minimum confidence for generic cl
 enabled = true
 characters = "abcdefghijklmnpqrstuvwxyz"    # Primary grid labels
 sublayer_keys = "abcdefghijklmnpqrstuvwxyz" # Subgrid labels, first 9 used (empty = infer from characters)
+max_label_length = 4                        # Maximum coarse label length (2–4); 4 keeps the legacy automatic layout
 row_labels = ""                             # Custom row labels (empty = infer from characters)
 col_labels = ""                             # Custom column labels (empty = infer from characters)
 live_match_update = true                    # Highlight cells as you type

configs/grid-only-config.toml

@@ -10,6 +10,7 @@ enabled = false
 [grid]
 enabled = true
 characters = "abcdefghijklmnpqrstuvwxyz"
+max_label_length = 4
 prewarm_enabled = true
 enable_gc = false
 

docs/CONFIGURATION.md

@@ -1055,6 +1055,7 @@ Cursor behavior is chosen per invocation: `neru grid --cursor-selection-mode fol
 | `enabled`           | bool   | `true`                        | Enable/disable grid mode    |
 | `characters`        | string | `"abcdefghijklmnpqrstuvwxyz"` | Primary grid labels         |
 | `sublayer_keys`     | string | `"abcdefghijklmnpqrstuvwxyz"` | Subgrid labels; empty is resolved at load time to the characters the grid is labelled with, the same ones `row_labels` is inferred from. Only the first 9 are used — the subgrid is 3×3 |
+| `max_label_length`  | int    | `4`                           | Maximum coarse-grid label length (2–4). The default preserves the legacy automatic 2–4-key layout. When a limit of 2 shortens an automatically longer label, the coarse grid is enlarged and spatially rebalanced while still covering the screen; the following subgrid refinement remains one keypress |
 | `row_labels`        | string | `""`                          | Custom row labels; empty is resolved at load time to the labels inferred from `characters` |
 | `col_labels`        | string | `""`                          | Custom column labels; empty is resolved the same way as `row_labels`                       |
 | `live_match_update` | bool   | `true`                        | Highlight cells as you type |

internal/adapter/overlay/render/grid/overlay_darwin.go

@@ -138,6 +138,24 @@ func getCommonGridSizes() []image.Rectangle {
 	}
 }
 
+func prewarm(config config.GridConfig) {
+	if !config.PrewarmEnabled {
+		return
+	}
+
+	options := domainGrid.Options{
+		Characters:     config.Characters,
+		RowLabels:      config.RowLabels,
+		ColLabels:      config.ColLabels,
+		MaxLabelLength: config.MaxLabelLength,
+	}
+	go func() {
+		for _, rect := range getCommonGridSizes() {
+			_ = domainGrid.NewGridWithOptions(options, rect, zap.NewNop())
+		}
+	}()
+}
+
 // NewOverlay creates a new grid overlay instance with its own window and prewarms common grid sizes.
 func NewOverlay(config config.GridConfig, logger *zap.Logger) (*Overlay, error) {
 	base, err := overlayutil.NewBaseOverlay(logger)
@@ -146,11 +164,7 @@ func NewOverlay(config config.GridConfig, logger *zap.Logger) (*Overlay, error)
 	}
 	base.CallbackManager.SetComponent("grid")
 	initGridPools()
-	chars := config.Characters
-
-	if config.PrewarmEnabled {
-		go domainGrid.Prewarm(chars, getCommonGridSizes())
-	}
+	prewarm(config)
 
 	return &Overlay{
 		window:          C.OverlayWindow(base.Window),
@@ -169,11 +183,7 @@ func NewOverlayWithWindow(
 	windowPtr unsafe.Pointer,
 ) *Overlay {
 	initGridPools()
-	chars := config.Characters
-
-	if config.PrewarmEnabled {
-		go domainGrid.Prewarm(chars, getCommonGridSizes())
-	}
+	prewarm(config)
 	base := overlayutil.NewBaseOverlayWithWindow(logger, windowPtr)
 	base.CallbackManager.SetComponent("grid")
 

internal/app/components/types.go

@@ -60,16 +60,17 @@ func (g *GridComponent) UpdateConfig(cfg *config.Config, logger *zap.Logger) {
 				charactersChanged := newCharacters != oldGrid.Characters()
 				rowLabelsChanged := newRowLabels != oldGrid.RowLabels()
 				colLabelsChanged := newColLabels != oldGrid.ColLabels()
+				maxLabelLengthChanged := cfg.Grid.MaxLabelLength != oldGrid.MaxLabelLength()
 
-				if charactersChanged || rowLabelsChanged || colLabelsChanged {
+				if charactersChanged || rowLabelsChanged || colLabelsChanged ||
+					maxLabelLengthChanged {
 					logger.Debug("Recreating grid due to config changes",
 						zap.Bool("charactersChanged", charactersChanged),
 						zap.Bool("rowLabelsChanged", rowLabelsChanged),
-						zap.Bool("colLabelsChanged", colLabelsChanged))
-					newGrid := domainGrid.NewGridWithLabels(
-						characters,
-						cfg.Grid.RowLabels,
-						cfg.Grid.ColLabels,
+						zap.Bool("colLabelsChanged", colLabelsChanged),
+						zap.Bool("maxLabelLengthChanged", maxLabelLengthChanged))
+					newGrid := domainGrid.NewGridWithOptions(
+						cfg.GridOptions(),
 						oldGrid.Bounds(),
 						logger,
 					)

internal/app/components/types_test.go

@@ -217,6 +217,33 @@ func TestGridComponent_UpdateConfig_RecreatedGridKeepsBounds(t *testing.T) {
 	}
 }
 
+// TestGridComponent_UpdateConfig_RecreatesGridOnMaxLabelLengthChange pins hot
+// reload for the geometry option: the manager must start using the new coarse
+// label bound immediately, and an unchanged follow-up reload must keep it.
+func TestGridComponent_UpdateConfig_RecreatesGridOnMaxLabelLengthChange(t *testing.T) {
+	component := newGridComponent(t, testCharacters, "", "")
+	before := component.Manager.Grid()
+
+	cfg := gridConfig(testCharacters, "", "")
+	cfg.Grid.MaxLabelLength = 2
+	component.UpdateConfig(cfg, zap.NewNop())
+
+	after := component.Manager.Grid()
+	if after == before {
+		t.Fatal("changing max_label_length did not recreate the grid")
+	}
+
+	if got := after.MaxLabelLength(); got != 2 {
+		t.Errorf("MaxLabelLength() = %d, want 2", got)
+	}
+
+	component.UpdateConfig(cfg, zap.NewNop())
+
+	if component.Manager.Grid() != after {
+		t.Error("reloading an unchanged max_label_length rebuilt the grid")
+	}
+}
+
 // TestGridComponent_UpdateConfig_DisabledGridIsLeftAlone makes sure a disabled
 // grid is not silently rebuilt behind the user's back.
 func TestGridComponent_UpdateConfig_DisabledGridIsLeftAlone(t *testing.T) {

internal/app/modes/grid.go

@@ -119,10 +119,8 @@ func (h *handlerState) createGridInstance() *domainGrid.Grid {
 	// Normalize normalizedBounds to window-local coordinates using helper function
 	normalizedBounds := geometry.NormalizeToLocalCoordinates(screenBounds)
 
-	gridInstance := domainGrid.NewGridWithLabels(
-		h.config.GridCharacters(),
-		h.config.Grid.RowLabels,
-		h.config.Grid.ColLabels,
+	gridInstance := domainGrid.NewGridWithOptions(
+		h.config.GridOptions(),
 		normalizedBounds,
 		h.logger,
 	)
@@ -151,10 +149,8 @@ func (h *handlerState) initializeGridManager(gridInstance *domainGrid.Grid) {
 		}
 
 		bounds := image.Rect(0, 0, screenBounds.Dx(), screenBounds.Dy())
-		gridInstance = domainGrid.NewGridWithLabels(
-			h.config.GridCharacters(),
-			h.config.Grid.RowLabels,
-			h.config.Grid.ColLabels,
+		gridInstance = domainGrid.NewGridWithOptions(
+			h.config.GridOptions(),
 			bounds,
 			h.logger,
 		)

internal/app/modes/grid_labels_test.go

@@ -95,6 +95,27 @@ func TestCreateGridInstance_UsesTheResolvedLabels(t *testing.T) {
 	}
 }
 
+// TestCreateGridInstance_UsesMaxLabelLength pins the mode-to-domain wiring for
+// the two-key coarse selection option.
+func TestCreateGridInstance_UsesMaxLabelLength(t *testing.T) {
+	cfg := config.DefaultConfig()
+	cfg.Grid.Enabled = true
+	cfg.Grid.Characters = "abcd"
+	cfg.Grid.MaxLabelLength = 2
+	cfg.ResolveGridLabels()
+
+	gridInstance := newGridLabelHandler(cfg).createGridInstance()
+	if got := gridInstance.MaxLabelLength(); got != 2 {
+		t.Fatalf("grid MaxLabelLength() = %d, want 2", got)
+	}
+
+	for _, cell := range gridInstance.Cells() {
+		if got := len(cell.Coordinate()); got > 2 {
+			t.Fatalf("coordinate %q has length %d, want at most 2", cell.Coordinate(), got)
+		}
+	}
+}
+
 // TestInitializeGridManager_FallbackGridUsesTheResolvedLabels covers the
 // defensive branch that builds its own grid when handed none. It reached for
 // grid.characters directly while the path above reached for the hint

internal/app/modes/monitor.go

@@ -320,12 +320,8 @@ func (h *handlerState) refreshGridForMonitorMove(targetBounds image.Rectangle) {
 	h.setScreenBounds(targetBounds)
 	normalizedBounds := geometry.NormalizeToLocalCoordinates(targetBounds)
 
-	gridInstance := domainGrid.NewGridWithLabels(
-		h.config.GridCharacters(),
-		h.config.Grid.RowLabels,
-		h.config.Grid.ColLabels,
-		normalizedBounds,
-		h.logger,
+	gridInstance := domainGrid.NewGridWithOptions(
+		h.config.GridOptions(), normalizedBounds, h.logger,
 	)
 	h.grid.Context.SetGridInstanceValue(gridInstance)
 

internal/app/simulation_journey_test.go

@@ -1839,6 +1839,7 @@ const moveMonitorHotkey = "Primary+Shift+N"
 // the calls in between.
 func TestSimulation_MonitorMoveRedrawsTheModeOnTheNewDisplay(t *testing.T) {
 	cfg := simConfig()
+	cfg.Grid.MaxLabelLength = 2
 	cfg.Hotkeys.Bindings[moveMonitorHotkey] = []string{
 		"action move_monitor --name " + secondDisplayName,
 	}
@@ -1873,6 +1874,10 @@ func TestSimulation_MonitorMoveRedrawsTheModeOnTheNewDisplay(t *testing.T) {
 	if sim.app.CurrentMode() != domain.ModeGrid {
 		t.Fatalf("mode after monitor move = %v, want grid", sim.app.CurrentMode())
 	}
+
+	if got := sim.overlay.lastGrid().MaxLabelLength(); got != cfg.Grid.MaxLabelLength {
+		t.Errorf("grid label limit after monitor move = %d, want %d", got, cfg.Grid.MaxLabelLength)
+	}
 }
 
 // TestSimulation_ScreenChangeWhileIdleLeavesTheOverlayHidden pins the quietest