task.md

task.md — Thread Anchor Implementation Tasks

Phase 1: Project Setup & Foundation

Task 1.1: Create project structure

• Create extension/ directory
• Create extension/src/content/ directory
• Create extension/src/popup/ directory
• Create extension/assets/ directory

Task 1.2: Create manifest.json (MV3)

• Create extension/manifest.json
• Set manifest_version to 3
• Configure content_scripts to match https://old.reddit.com/r/*/comments/*
• Add storage permission
• Configure popup action
• Reference icon assets (16, 48, 128)

Task 1.3: Create placeholder icons

• Create extension/assets/icon16.png
• Create extension/assets/icon48.png
• Create extension/assets/icon128.png

---

Phase 2: Popup & Settings

Task 2.1: Create popup HTML

• Create extension/src/popup/popup.html
• Add toggle for "Sticky ancestors"
• Add slider/number input for "Pinned rows (N)"
• Add optional checkbox for "Compact sticky rows"

Task 2.2: Create popup CSS

• Create extension/src/popup/popup.css
• Style toggles and controls
• Keep UI clean and minimal

Task 2.3: Create popup JS with storage wiring

• Create extension/src/popup/popup.js
• Implement chrome.storage.sync read/write
• Set defaults:
  • stickyAncestorsEnabled: true
  • stickyDepth: 3
  • stickyCompact: true
• Wire UI controls to storage updates

---

Phase 3: Content Script Foundation

Task 3.1: Create selectors.js

• Create extension/src/content/selectors.js
• Implement getAllCommentThings() — returns all comment elements
• Implement isCommentThing(el) — checks if element is a comment
• Implement getCommentId(el) — returns unique ID for comment
• Implement getExpandControl(el) — returns clickable expand element
• Implement isCollapsed(el) — checks if comment is collapsed
• Implement getIndentDepth(el) — returns nesting depth
• Implement getParentThing(el) — returns parent comment element

Task 3.2: Create util.js

• Create extension/src/content/util.js
• Implement debounce function
• Implement throttle function (if needed)
• Add any shared utility functions

Task 3.3: Create main.js entry point

• Create extension/src/content/main.js
• Read settings from chrome.storage.sync on load
• Listen for chrome.storage.onChanged events
• Initialize/deinitialize feature modules based on settings

---

Phase 4: Feature — Sticky Ancestors Header

Task 4.1: Create activeComment.js module

• Create extension/src/content/activeComment.js
• Implement IntersectionObserver to track visible comments
• Maintain set of currently visible comments
• Compute "active" comment (smallest positive top distance to viewport top)
• Debounce active comment updates (50-100ms)
• Export onActiveChange(callback) for notifying changes

Task 4.2: Create ancestors.js module

• Create extension/src/content/ancestors.js
• Implement computeAncestors(commentEl) function
• Walk backwards in DOM to find parent (depth - 1)
• Repeat until reaching top-level (depth 0)
• Return chain array [topLevel, ..., currentComment]
• Cache depth values in WeakMap for performance

Task 4.3: Create stickyUI.js module

• Create extension/src/content/stickyUI.js
• Create container div#ta-sticky-container
• Style as fixed position at top, full width, high z-index
• Position below Reddit's #header to avoid overlap

Task 4.4: Implement sticky row rendering

• Implement render(chain, N) function
• For each comment in chain.slice(0, N):
  • Extract and display: author, score, timestamp (optional), short excerpt
  • Add "jump" link that scrolls to original comment on click
  • Truncate long excerpts with ellipsis
• Keep rendering lightweight (don't clone full comment HTML)

Task 4.5: Handle body padding for sticky header

• Measure sticky container height
• Set document.body.style.paddingTop accordingly
• Update padding when container height changes

Task 4.6: Wire active comment to sticky UI

• In main.js, register onActiveChange callback
• On change: compute ancestors, call stickyUI.render(chain, N)
• Handle edge cases:
  • Active comment is null → hide container or show post title
  • Chain length < N → render only available rows
  • Comment is collapsed → still show in sticky using available DOM data

---

Phase 5: Polish & Edge Cases

Task 5.1: Implement compact mode for sticky rows

• Add compact rendering option (single-line rows)
• Toggle based on stickyCompact setting

Task 5.2: Implement jump-to-comment functionality

• Clicking sticky row scrolls viewport to original comment
• Smooth scroll or instant scroll (user preference)
• Optionally highlight the target comment briefly

Task 5.3: Handle Reddit header offset

• Detect old Reddit header height (#header)
• Set sticky container top below Reddit header

Task 5.4: Add MutationObserver for dynamic comments

• Watch for newly inserted comments (rare but possible)
• Register new comments with IO observers

---

Phase 6: Performance Optimization

Task 6.1: Implement caching with WeakMaps

• Cache comment depth values (selectors.js: depthCache)
• Cache comment IDs (selectors.js: idCache)
• Cache comment metadata (selectors.js: metaCache)
• Cache parent lookups (ancestors.js: parentCache)
• Cache ancestor chains (ancestors.js: chainCache)

Task 6.2: Optimize rendering

• Only re-render sticky UI when active comment or settings change (currentChainIds comparison)
• Avoid querySelectorAll in scroll handlers (use visibleComments Set)
• Use IO rootMargin instead of manual buffer calculations

Task 6.3: Performance testing

• Added performance measurement utilities (Util.perfStart, perfMeasure, perfStats, perfLog)
• Test on large threads (1000+ comments) — manual testing required
• Verify no scroll jank during fast scrolling — manual testing required
• Profile and optimize any bottlenecks — manual testing required

---

Phase 7: Testing & Validation

Task 7.1: Manual testing — Sticky ancestors feature

• Enable sticky ancestors with N=3
• Scroll into nested replies → verify pinned chain updates correctly
• Move between sibling threads → verify replacement behavior
• Test with different N values (1, 2, 3, 5)

Task 7.2: Manual testing — Edge cases

• Test collapsed parent chains
• Test very shallow threads (< N depth)
• Verify sticky rows don't overlap Reddit header

Task 7.3: Manual testing — Click interactions

• Click sticky rows → verify scroll to correct comment

Task 7.4: Cross-browser testing

• Test in Chrome
• Test in other Chromium browsers (Edge, Brave, etc.)

---

Done Criteria

• Works on Reddit comment threads (old.reddit.com and www.reddit.com)
• Sticky ancestor header shows correct chain, updates smoothly, supports configurable N
• Toggle state persists across reloads via chrome.storage
• No significant scroll jank on large threads
• UI is clean and doesn't break Reddit's native behavior