Fix/cursor position tracker

[Kripu77]

Summary by CodeRabbit

Release Notes

• New Features

  • Added viewport state synchronization hook for real-time board tracking
  • Enhanced cursor representation with color and avatar data

• Improvements

  • Optimized cursor visibility computation and rendering performance
  • Improved cursor update throttling with configurable timing and trailing-edge flush behavior
  • Simplified cursor overlay component with flexible container reference support

• Tests

  • Updated cursor manager tests to reflect improved trailing-edge timer behavior

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
thinkix	Ready	Preview, Comment	Mar 13, 2026 4:30am

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

The PR refactors the cursor overlay rendering system by introducing a new useViewport hook for tracking board viewport state, updating the CursorManager data model to include document coordinates and user metadata, replacing its constructor with an options-based signature, and modifying the CursorOverlay component to accept an optional container reference and rely on the new viewport hook instead of debounced state logic.

Changes

Cohort / File(s)	Summary
Viewport Hook packages/collaboration/src/hooks/use-viewport.ts	New React hook that subscribes to PlaitBoard viewport changes, tracks viewport state with zoom and offset, and detects viewport operations via board.onChange patching.
Hook Exports packages/collaboration/src/hooks/index.ts	Added useViewport to public exports from the hooks module.
Cursor Overlay Refactor packages/collaboration/src/components/cursor-overlay.tsx	Added optional containerRef prop to CursorOverlayProps; replaced debounced viewport state logic with useViewport hook and containerRect state; simplified rendering pipeline with useMemo-computed cursor list.
Cursor Manager Enhancement packages/collaboration/src/cursor-manager.ts	Expanded CursorState data model with documentX, documentY, userColor, and optional userAvatar; changed createCursorManager constructor to accept options object (throttleIntervalMs, idleTimeoutMs, cleanupIntervalMs); broadened handlePointerMove signature to accept containerRect and viewport; added trailing timer mechanism for flushing pending updates; updated getVisibleCursors, paginateCursors, and getActiveCursors signatures; added PRESENCE_PAGE_SIZE constant.
Test Updates tests/unit/cursor-manager.test.ts	Updated test expectations to reflect new trailing-edge timer behavior; adjusted expected coordinate values in throttle-related tests; refined test descriptions.

Sequence Diagram(s)

sequenceDiagram
    participant PlaitBoard
    participant useViewport
    participant CursorManager
    participant CursorOverlay

    PlaitBoard->>useViewport: onChange detected (set_viewport operation)
    useViewport->>PlaitBoard: getViewport()
    PlaitBoard-->>useViewport: {zoom, offsetX, offsetY}
    useViewport->>useViewport: Update viewport state
    useViewport-->>CursorOverlay: New viewport

    CursorOverlay->>CursorManager: handlePointerMove(clientCoords, containerRect, viewport)
    CursorManager->>CursorManager: Calculate documentX/documentY from viewport
    CursorManager->>CursorManager: Start throttle + trailing timer
    CursorManager->>CursorManager: Accumulate cursor updates
    CursorManager->>CursorManager: Trailing timer fires: flush accumulated updates
    CursorManager->>CursorManager: Expand CursorState with new fields
    CursorManager-->>CursorOverlay: onCursorsChange(new cursors Map)

    CursorOverlay->>CursorOverlay: useMemo: compute visible cursors with viewport + containerRect
    CursorOverlay-->>CursorOverlay: Render cursor list

Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Poem

🐰 A viewport hook hops into view,
Cursors dance with coordinates new,
Document space, container refined,
Trailing timers flush on time—
The overlay leaps with grace so true! ✨

🚥 Pre-merge checks | ✅ 1 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Title check	❓ Inconclusive	The title 'Fix/cursor position tracker' is vague and uses the slash convention suggesting it's a branch name rather than a descriptive title. It does not clearly convey what specific issue was fixed or what change was made to the cursor position tracking system.	Consider using a more descriptive title that explains the specific fix, such as 'Refactor cursor overlay to support containerRef and improve viewport tracking' or 'Update cursor manager with trailing timer and document coordinate tracking'.

✅ Passed checks (1 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch fix/cursor-position-tracker

📝 Coding Plan

• Generate coding plan for human review comments

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Tip

CodeRabbit can generate a title for your PR based on the changes with custom instructions.

Set the reviews.auto_title_instructions setting to generate a title for your PR based on the changes in the PR with custom instructions.

[github-actions]

❌ Test Results

Metric	Coverage
Lines	0%
Functions	64.96%
Branches	41.68%
Statements	54.22%
Average	40.2%

📦 Download Coverage Report

How to view coverage report

1. Download the coverage artifact from the link above
2. Extract the ZIP file
3. Open index.html in your browser

---

Commit: fe5aca12f1a2251001d5ae6253f262666b63ec51