Real-Time Invoice Collaboration with Live Cursors

[Kingsman-99]

Description

Multiple co-creators editing an invoice simultaneously have no awareness of each other's position or intent, leading to overwrite conflicts and confusion. This issue implements a real-time collaborative editing layer for /invoice/new and /invoice/[id] using WebSockets or a CRDT-backed channel, rendering each connected user's cursor position and active field as a colored presence indicator. The feature must gracefully degrade when the WebSocket connection drops, locking out concurrent edits and showing a reconnection banner.

Technical Context

Involves creating hooks/useInvoiceCollaboration.ts with a WebSocket connection manager and conflict resolver, extending app/invoice/new/page.tsx and app/invoice/[id]/page.tsx to render <CursorOverlay> and <PresencePill> components. Each form field must emit focus/blur events to the channel. The useReducer pattern should manage remote cursor state keyed by userId. Server-side, a lightweight Next.js Route Handler at app/api/collab/[invoiceId]/route.ts should broker connections or proxy to an external Partykit/Liveblocks endpoint. Existing co-creator permission logic in the permissions panel must gate write access before the socket is opened.

Acceptance Criteria

• Two browser sessions editing the same invoice simultaneously display each other's name and cursor color above the focused field within 200 ms of a field-focus event
• Conflict resolution prevents silent overwrites: the second writer receives an optimistic-lock toast and their change is rebased or discarded with a clear diff shown
• When the WebSocket drops, the UI enters read-only mode and a dismissible reconnection banner appears; full edit capability resumes automatically on reconnect
• Co-creators without write permission cannot open a collaboration socket; attempting to do so returns a 403 and shows an inline error
• Presence indicators are removed within 5 seconds of a user closing their tab or navigating away
• All CI checks (npm test, npm run build, ESLint/TypeScript) pass and the branch has no merge conflicts

---

[isaac4real-art]

@isaac4real-art has applied to work on this issue as part of the Stellar Wave Program's 7th wave.

Hello, I have carefully reviewed the issue details and am confident in my ability to deliver a clean, efficient, and maintainable solution.

ℹ️ Repo Maintainers: To accept this application, review their application or assign @isaac4real-art to this issue.

[drips-wave]

Congratulations, @isaac4real-art! 🎉 Your application was accepted by the repo's maintainers, and the issue is due on July 30, 2026.

🧑‍💻 @isaac4real-art: Please resolve the issue such that the repo's maintainers have enough time to review your contribution before the due date. You'll earn Points for completing the issue on-time, which will make you eligible for a share of the Stellar Wave Program's reward pool.

Warning

When opening a PR, please link it to this issue to ensure it gets tracked accurately. Points are awarded when this issue is marked as completed by the maintainer.

🤠 Repo maintainers: Please keep an eye on the contributor's progress and review their work before the due date. You can manage this issue, including adjusting its complexity and points, here.

🌊 Happy Wave 🌊