[FEATURE] Add Interactive Reading Progress Indicator and Persistent Scroll Memory for Chapter Pages

[pushpit21jain]

Feature Description

When users read dense, long-form core subject notes (such as Data Structures, Operating Systems, or Compiler Design), it can be difficult to track how far they have progressed down the page.

This feature introduces two key UX enhancements to the chapter documentation layout (/sem* routes):

1. Visual Reading Progress Bar: A minimalist, high-performance horizontal progress bar fixed at the very top of the viewport (or nested just beneath the sticky navbar) that fills up dynamically as the user scrolls down a chapter.
2. Persistent Scroll Memory: An auto-save mechanism using localStorage that remembers exactly where a student stopped reading. When they return to that specific chapter later, the page smoothly auto-scrolls back to their last saved position.

Problem It Solves

• Cognitive Load: Long walls of technical academic text can feel overwhelming. A visual indicator gives students a sub-conscious sense of achievement and a clear indicator of remaining content length.
• Interrupted Learning Sessions: Students frequently study in short bursts. If a user accidentally closes their tab or returns to a complex chapter the next day, they lose their spot and must waste time scrolling to find where they left off.

Proposed Solution

• Scroll Tracking: Implement a lightweight scroll event listener using a React useEffect hook (or an IntersectionObserver approach for efficiency) inside the main chapter layout component to calculate:
  $$\text{Progress %} = \left( \frac{\text{window.scrollY}}{\text{document.documentElement.scrollHeight} - \text{window.innerHeight}} \right) \times 100$$
• Framer Motion / Tailwind CSS Animation: Bind this percentage to a stylized div bar matching the brand's aesthetic.
• Debounced LocalStorage: Save the unique route path and current window.scrollY position to local storage, debounced by 500ms to avoid performance lag. Upon mounting the component, check for an existing coordinate match and trigger a smooth window scroll adjustment.

Additional Context

• This builds perfectly upon openCSE's goal of creating a clean, modern, and distraction-free documentation experience for college students.
• It scales elegantly across both desktop viewports and mobile devices.

[Samikshagit-07]

Hi maintainer, I am interested in solving this issue as part of GSSoC '26. Could you please assign this to me?

[rajesh-puripanda]

Hi @pushkarscripts!

This is an exceptional feature request. Long-form academic notes inherently require robust tracking to lower cognitive load, and adding persistence transforms how students interact with the /sem* routes.

While the general formula is solid, implementing this directly in a naive React hook will trigger two major UX flaws that I have already planned safe engineering workarounds for:

Critical Edge Cases & My Technical Solutions:

1. The Async Layout Shift (Fixing Dead Scroll Memory):
   Because academic subject notes load dynamically (with code syntax highlights, math blocks, or markdown components), triggering a native window scroll immediately on component mount will fire before the DOM fully paints its complete height. This causes the scroll to landing in a completely wrong position.

   • My Fix: I will wrap the restoration logic inside a structured layout effect combined with a ResizeObserver on the core article container. This guarantees the page only auto-adjusts its scroll position once the document height is 100% stable.

2. Scroll Jank Elimination (Passive Event Performance):
   Tracking a raw scroll listener to update state variables on every single pixel movement causes heavy main-thread layout recalculations.

   • My Fix: I will utilize a CSS Custom Property approach synced via a passive event listener ({ passive: true }). Instead of forcing a React re-render for every pixel scrolled, the scroll event will directly update a single localized CSS variable (--scroll-percentage), allowing the browser's GPU compositor to handle the progress bar fill flawlessly at 60fps.

3. Smart LocalStorage Lifecycle:
   I will write a custom hook (useScrollMemory) that tracks the route's specific semester/chapter ID as the unique storage key, utilizing a 500ms debounce window to prevent continuous read/writes while a student is actively skimming.

I have my local build environment ready to go and can push a pristine, production-ready implementation that fully solves these edge cases. Please assign this to me!

[rajesh-puripanda]

/assign gssoc