Skip to content

feat: show_hints — opt out of the hint chrome - #5

Merged
teocns merged 1 commit into
mainfrom
feat/show-hints
Jul 29, 2026
Merged

feat: show_hints — opt out of the hint chrome#5
teocns merged 1 commit into
mainfrom
feat/show-hints

Conversation

@teocns

@teocns teocns commented Jul 29, 2026

Copy link
Copy Markdown
Owner

Closes #4.

@scc02 asked for a way to hide the ⟪neocursor · <Tab> jump⟫ label while keeping the suggestion itself. This adds show_hints, using the exact API shape proposed in the issue.

require("neocursor").setup({
  show_hints = false,                  -- hide both hint surfaces
  -- show_hints = { edit = false },    -- hide the label, keep the jump pill
})

Two surfaces, and they aren't equally safe to hide

Surface Renders Cost of hiding
edit ⟪neocursor · <Tab> accept⟫ none — the diff beside it already shows the change
prediction ⟪<Tab> → L42⟫ the only on-screen sign a jump is queued

false hides both, since that's the least surprising reading of the option name. The table form keeps the pill for anyone who wants the label gone but still wants to see where <Tab> will land. The README documents the tradeoff rather than hiding it.

The trap

show_prediction() does double duty — it paints the pill and returns the boolean that gates jumping at four call sites (init.lua 358, 398, 814, 956).

The obvious implementation (return false when hints are off) renders correctly and silently disables <Tab> jumping. So: the paint is conditional, the return value is not.

Verification

Two independent angles, both in CI on ubuntu/windows/macos:

  • test/hints_spec.lua (new, 16 assertions) — label present/absent, diff body byte-identical either way, prediction-pill namespace isolation, all 7 normalization cases.
  • test/flow_spec.lua now reruns its entire 20-assertion behavioral suite under NEOCURSOR_SPEC_NO_HINTS=1. Tab jumps to predicted line and prediction consumed by jump pass with zero chrome — that's the regression that would otherwise ship silently.

:NeocursorDebug prints the resolved setting.

Note

M._normalize_hints is exposed (underscore-prefixed, internal) so the spec can test the pure normalizer without spawning a sidecar.

Closes #4.

The ⟪neocursor · <Tab> accept⟫ label and the ⟪<Tab> → L42⟫ prediction pill
are discoverability aids; once you know the keys they are just noise in the
buffer. `show_hints` turns them off without touching suggestions.

  show_hints = false               -- hide both
  show_hints = { edit = false }    -- hide the label, keep the jump pill

The invariant this has to preserve: hint chrome is display-only. It is easy to
break, because show_prediction() both paints the pill and returns the boolean
that gates jumping at four call sites — suppressing the paint by returning
false would silently disable <Tab> jumps. The paint is now conditional; the
return value is not.

Covered two ways: test/hints_spec.lua asserts the render layer (label present
or absent, diff body byte-identical either way, pill namespace isolation) and
normalization; flow_spec.lua now reruns its full behavioral suite under
NEOCURSOR_SPEC_NO_HINTS=1, so jump/accept/chain are proven identical with the
chrome gone. Both wired into CI on all three platforms.
@teocns
teocns merged commit d6782f1 into main Jul 29, 2026
7 checks passed
@teocns
teocns deleted the feat/show-hints branch July 29, 2026 13:54
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add an option to hide the “《neocursor <Tab> jump》” hint

1 participant