Overview & Architecture
System Design
A lightweight document navigation minimap designed to replace heavy table-of-contents blocks with intuitive spatial awareness.
Architectural Boundaries
Engineered without DOM wrappers, borders, or nested cards to integrate seamlessly into any article or documentation canvas.
Core Primitives
Constructed using hardware-accelerated scaleX transforms anchored to the document edge to preserve zero-cost layout calculations.
Runtime Efficiency
Zero layout shifts and sub-millisecond execution time make it well-suited for long-form documentation and interactive code references.
Telemetry Integration
Real-time scroll position feedback provides precise tracking of reader engagement without extraneous polling loops.
State Topology
Supports both controlled and uncontrolled active state bindings with optional external callbacks for seamless router synchronization.
Harmonic Motion Engine
Spring Dynamics
Harmonic oscillator configuration (stiffness 350, damping 32, mass 0.6) yields physical elasticity without unwanted overshoot.
Cosine Proximity
Cosine mathematical mapping ensures tangent boundaries at the perimeter of the proximity radius with zero sharp creases.
Damped Decay
When the cursor departs the sidebar boundary, dashes return to their baseline rests through smooth exponential decay.
GPU scaleX Pipeline
Dash dimensions mutate strictly along the X axis via composited transform matrices, avoiding expensive style recalculations.
Zero Layout Thrashing
Bounding client geometry is evaluated and cached on pointer entry and resize rather than executed per continuous pointermove event.
Transform Anchors
Supports left-center or right-center orientation anchors so lines extend naturally away from the document perimeter.
Scroll Synchronization
Viewport Anchors
Tracks reading position against a configurable vertical anchor offset (default 40% from the container top).
Intersection Geometry
Distance calculations determine the closest section boundary to prevent flickering between neighboring paragraphs.
RequestAnimationFrame Sync
Scroll event listeners are debounced through animation frames to guarantee 60-120 FPS synchronization during continuous momentum scrolling.
Container Hierarchy
Intelligently climbs the DOM hierarchy to detect overflow scroll parents or the window viewport dynamically.
Bidirectional Glide
Clicking any dash triggers smooth scrollIntoView behavior that places the corresponding heading directly at the top of the viewport.
URL Hash Synchronization
Updates browser location history without disrupting scrolling or polluting the navigation history stack.
Dynamic Thresholds
Responsive height adjustments adapt the active detection anchor across compact tablet views and large widescreen monitors.
Interactive Ergonomics
Hit Target Sizing
Generous interactive hit heights ensure effortless targeting on touchscreens and mice while preserving hairline visual aesthetics.
Proximity Radius
Configurable influence radius smoothly expands nearby dashes before the cursor even makes contact with the dash stroke.
Keyboard Stepping
Full ArrowUp and ArrowDown support allows keyboard users to step through document sections sequentially with auto-scrolling.
Focus Rings
Accessible focus-visible rings highlight the currently focused dash during keyboard tab traversal.
ARIA Landmarks
Proper role='navigation', aria-label='Page sections', and aria-current='location' tags provide complete screen reader compatibility.
Performance & Reliability
120 FPS High Refresh
Tested on ProMotion and 144Hz gaming displays to ensure fluid cursor tracking without frame skipping.
Cached Rects
Eliminating synchronous getBoundingClientRect calls during motion transforms keeps CPU utilization below 1%.
Sub-pixel Compositing
Hairline line widths maintain crisp sub-pixel clarity across Retina, OLED, and standard DPI displays.
Memory Footprint
Minimal closure allocations and proper unmount teardown prevent memory leaks during long reading sessions.
Passive Event Handlers
Scroll and resize listeners use passive flags to avoid blocking browser scrolling and input threads.
Bundle Optimization
Zero dependencies beyond Motion and Tailwind keeps production bundle overhead under 3KB gzipped.