Skip to content

feat(trail): cursor trail with policy-based visibility filtering #7

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
josstei wants to merge 22 commits into
base: main
Choose a base branch
from
Open

feat(trail): cursor trail with policy-based visibility filtering #7

josstei wants to merge 22 commits into from

Conversation

@josstei
Copy link
Member

@josstei josstei commented Feb 8, 2026

Summary

  • Cursor trail system: Renders a fading trail of highlight segments behind cursor movement using extmarks and a ring buffer renderer
  • Policy abstraction layer: Three built-in policies (always, never, distance) filter trail visibility based on movement type and distance, reducing visual noise on trivial motions (hjkl single-line moves)
  • Resolution chain: User config overrides > motion-level policy > category default > always fallback, giving full control over trail behavior per-motion

What Changed

Trail Core (renderer, highlights)

  • Ring buffer position tracking with configurable segment count (2-12)
  • Color blending from trail color to background with linear fade
  • Auto-resolves trail color from Cursor highlight group
  • Extmark-based rendering with boundary clamping

Policy System

  • always - unconditionally shows trail
  • never - unconditionally hides trail
  • distance - shows trail only when movement exceeds configurable line/column thresholds
  • Policy registry with resolve() implementing the full resolution chain
  • Config validation for policy, distance thresholds, and per-motion overrides

Motion Integration

  • All motions assigned trail_policy: distance for hjkl/gj/gk, always for everything else
  • invoke_start now passes result to traits for policy evaluation
  • motion_id attached to context for policy resolution

Config Defaults

  • Cursor trail: enabled, distance policy, min_lines=2, min_cols=5
  • Scroll trail: disabled, always policy

Test Plan

  • 583 tests passing (100% pass rate)
  • 64 new tests covering all policy files, registry, config, and integration
  • Backwards compatibility: existing trail integration tests unchanged and passing
  • Edge cases: zero movement, backward movement, missing cursor, unknown policies

josstei added 22 commits February 7, 2026 23:45
@josstei
test: add extmark, namespace, and highlight mocks
b762220
@josstei
feat(config): add trail defaults for cursor and scroll
70a7917
@josstei
feat(config): add trail config validation
59d3c04
@josstei
feat(trail): add highlights module with color blending
b47c94c
@josstei
feat(trail): add renderer module with ring buffer and extmarks
0335a0f
@josstei
feat(traits): wire on_start/on_complete lifecycle hooks
6e462cd
@josstei
feat(trail): register trail trait and wire into builtin motions
1d866ea
@josstei
feat(init): setup trail highlights during plugin initialization
dfabbe5
@josstei
feat(orchestrator): attach motion category to context
1545066
@josstei
test: add trail integration tests
c08acd3
@josstei
docs: add trail modules to architecture documentation
a8999e2
@josstei
fix(trail): clean up empty if/else and fix intensity curve for all se…
32bfe7a 
…gment counts
@josstei
fix(renderer): clamp extmark end_col to line length to prevent out-of…
dca1563 
…-range errors
@josstei
test(renderer): add edge case coverage for extmark boundary clamping
b46b561
@josstei
fix(trail): use cursor color by default and improve vibrancy
5bc7645 
- Default trail color is now "auto" (reads from Cursor highlight group)
- Intensity curve starts at 1.0 with gentler (1-t)^1.2 decay
- Add resolve_color() to highlights module for runtime color resolution
- Update validation to accept "auto" as valid trail color
@josstei
fix(trail): smooth linear fade with more segments
2668216 
- Linear intensity curve (1-t) for uniform color steps between segments
- Increase default segments from 6 to 8 for smoother gradient
@josstei
fix(trail): increase default segments to 10 for smoother fade
9de1de5
@josstei
docs(trail): add trail policy system design
8f11a29 
Introduces a policy abstraction layer between motion execution and trail
rendering to filter trail visibility based on movement distance and
motion type.
@josstei
docs(trail): add trail policy implementation plan
4297b65
@josstei
feat(trail): add always, never, and distance trail policies
d826c09 
Three built-in policies for filtering trail visibility:
- always: unconditionally enables trail
- never: unconditionally disables trail
- distance: enables trail only when movement exceeds configurable thresholds
@josstei
feat(trail): add policy registry, config, motion assignments, and tra…
15e94aa 
…its signature

- Policy registry with resolution chain: user override > motion > category > always
- Config defaults: cursor uses distance policy, scroll uses always
- Validation for policy, distance thresholds, and overrides
- All builtin motions assigned trail_policy (distance for hjkl/gj/gk, always for rest)
- invoke_start now passes result to traits, motion_id attached to context
@josstei
feat(trail): integrate policy system into trail trait
d1a44d4 
Trail trait now evaluates policies at animation start via on_start.
Policies are registered during setup (always, never, distance).
Trail rendering is gated by context.trail_active flag.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@josstei