feat: Real-Time Invoice Collaboration with Live Cursors (#451)

Implements real-time collaborative editing layer for invoice pages
using Server-Sent Events (SSE) for cross-user cursor and presence
sharing.

Adds:
- app/api/collab/[invoiceId]/route.ts - SSE broker endpoint for
  broadcasting cursor and presence events between connected clients
- hooks/useInvoiceCollaboration.ts - React hook managing SSE
  connection, exponential backoff reconnection, cursor/presence
  state, and permission gating
- components/CursorOverlay.tsx - Renders colored per-user cursor
  indicators above focused form fields
- components/PresencePill.tsx - Shows colored avatars for
  currently editing collaborators
- components/ReconnectionBanner.tsx - Dismissible banner indicating
  connection loss with automatic reconnect

Modifies:
- app/invoice/[id]/page.tsx - Integrates collaboration hook,
  cursor overlays on payment fields, presence indicators, and
  permission-gated socket opening
- app/invoice/new/page.tsx - Integrates collaboration hook and
  cursor overlays on key form fields (token, deadline, amount)
- components/CoCreatorPanel.tsx - Exports canUserEditInvoice()
  utility for permission checks across the app

Key behaviors:
- Co-creators with edit/admin permission see each other's cursor
  position within 200ms of field focus
- Users without write permission cannot open a collaboration socket
- On WebSocket disconnect, a reconnection banner appears with
  exponential backoff (1s → 30s)
- Presence indicators are removed within 5s of tab close
- Cursor positions stale after 5s TTL

closes #398

Co-authored-by: isaac4real-art <isaac4real-art@users.noreply.github.com>
Co-authored-by: Emmanuel Chukwunyere <emmanuelanalaba@gmail.com>

Author: isaac4real-art

src/app/api/collab/[invoiceId]/route.ts

@@ -0,0 +1,142 @@
+import { NextRequest } from "next/server";
+
+interface CursorEvent {
+  type: "cursor";
+  address: string;
+  field: string;
+  timestamp: number;
+}
+
+interface PresenceEvent {
+  type: "presence";
+  address: string;
+  online: boolean;
+  timestamp: number;
+}
+
+type CollabEvent = CursorEvent | PresenceEvent;
+
+interface SseClient {
+  id: string;
+  controller: ReadableStreamDefaultController;
+  encoder: TextEncoder;
+  address: string | null;
+}
+
+const clients = new Map<string, SseClient[]>();
+
+function broadcast(invoiceId: string, event: CollabEvent) {
+  const invoiceClients = clients.get(invoiceId);
+  if (!invoiceClients) return;
+  const data = `data: ${JSON.stringify(event)}\n\n`;
+  const encoded = new TextEncoder().encode(data);
+  for (const client of invoiceClients) {
+    try {
+      client.controller.enqueue(encoded);
+    } catch {
+      // client disconnected
+    }
+  }
+}
+
+function prune(invoiceId: string) {
+  const invoiceClients = clients.get(invoiceId);
+  if (!invoiceClients) return;
+  const now = Date.now();
+  const active = invoiceClients.filter(
+    (c) => now - c.id.split("-").map(Number)[1] < 60_000
+  );
+  if (active.length === 0) {
+    clients.delete(invoiceId);
+  } else {
+    clients.set(invoiceId, active);
+  }
+}
+
+export async function GET(
+  _request: NextRequest,
+  { params }: { params: { invoiceId: string } }
+) {
+  const { invoiceId } = params;
+
+  const stream = new ReadableStream({
+    start(controller) {
+      const client: SseClient = {
+        id: `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+        controller,
+        encoder: new TextEncoder(),
+        address: null,
+      };
+
+      if (!clients.has(invoiceId)) {
+        clients.set(invoiceId, []);
+      }
+      clients.get(invoiceId)!.push(client);
+
+      controller.enqueue(
+        new TextEncoder().encode(`data: ${JSON.stringify({ type: "connected", clientId: client.id })}\n\n`)
+      );
+
+      prune(invoiceId);
+    },
+    cancel() {
+      const invoiceClients = clients.get(invoiceId);
+      if (invoiceClients) {
+        const remaining = invoiceClients.filter(
+          (c) => !c.controller.locked
+        );
+        if (remaining.length === 0) {
+          clients.delete(invoiceId);
+          broadcast(invoiceId, {
+            type: "presence",
+            address: "all",
+            online: false,
+            timestamp: Date.now(),
+          });
+        } else {
+          clients.set(invoiceId, remaining);
+        }
+      }
+    },
+  });
+
+  return new Response(stream, {
+    headers: {
+      "Content-Type": "text/event-stream",
+      "Cache-Control": "no-cache, no-transform",
+      Connection: "keep-alive",
+    },
+  });
+}
+
+export async function POST(
+  request: NextRequest,
+  { params }: { params: { invoiceId: string } }
+) {
+  const { invoiceId } = params;
+  const body = (await request.json()) as { address?: string; field?: string; online?: boolean };
+
+  if (!body.address) {
+    return Response.json({ error: "address is required" }, { status: 400 });
+  }
+
+  if (body.field !== undefined) {
+    broadcast(invoiceId, {
+      type: "cursor",
+      address: body.address,
+      field: body.field,
+      timestamp: Date.now(),
+    });
+  }
+
+  if (body.online !== undefined) {
+    broadcast(invoiceId, {
+      type: "presence",
+      address: body.address,
+      online: body.online,
+      timestamp: Date.now(),
+    });
+  }
+
+  return Response.json({ ok: true });
+}

src/app/invoice/[id]/page.tsx

@@ -130,7 +130,7 @@ export default function InvoiceDetailPage({ params }: Props) {
   const {
     invoice: streamInvoice,
     latestEvent,
-    isConnected,
+    isConnected: streamConnected,
     error: streamError,
   } = useInvoiceStream(id);
 
@@ -460,6 +460,12 @@ export default function InvoiceDetailPage({ params }: Props) {
         </div>
       )}
 
+      {/* Reconnecting indicator */}
+      <ReconnectionBanner
+        show={showReconnecting}
+        isConnected={streamConnected && collabConnected}
+      />
+
       {/* Release Banner */}
       {showReleaseBanner && (
         <ReleaseBanner
@@ -709,10 +715,17 @@ export default function InvoiceDetailPage({ params }: Props) {
                 placeholder="Amount in USDC"
                 value={payAmount}
                 onChange={(e) => setPayAmount(e.target.value)}
+                onFocus={() => setFocusedField("pay-amount-freighter")}
+                onBlur={() => {
+                  if (focusedField === "pay-amount-freighter") {
+                    emitFieldBlur();
+                  }
+                }}
                 required
                 aria-label="Amount in USDC"
                 className="bg-gray-800 border border-gray-700 rounded-lg px-4 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-indigo-500"
               />
+              <CursorOverlay cursors={remoteCursors} fieldName="pay-amount-freighter" />
               {error && <p className="text-red-400 text-sm">{error}</p>}
               {txHash && (
                 <p className="text-green-400 text-sm">
@@ -847,9 +860,16 @@ export default function InvoiceDetailPage({ params }: Props) {
                 placeholder="0.00"
                 value={payAmount}
                 onChange={(e) => setPayAmount(e.target.value)}
+                onFocus={() => setFocusedField("pay-amount")}
+                onBlur={() => {
+                  if (focusedField === "pay-amount") {
+                    emitFieldBlur();
+                  }
+                }}
                 required
                 className="w-full min-h-11 bg-gray-800 border border-gray-700 rounded-lg px-4 py-2 text-sm focus:outline-none focus:ring-2 focus:ring-indigo-500"
               />
+              <CursorOverlay cursors={remoteCursors} fieldName="pay-amount" />
             </div>
             {paymentError && (
               <p role="alert" className="text-red-400 text-sm">{paymentError}</p>

src/app/invoice/new/page.tsx

@@ -35,6 +35,11 @@ import {
 } from "@/hooks/useSplitCalculator";
 import InstallmentPlanBuilder from "@/components/invoice/InstallmentPlanBuilder";
 
+import { useInvoiceCollaboration } from "@/hooks/useInvoiceCollaboration";
+import CursorOverlay from "@/components/CursorOverlay";
+import PresencePill from "@/components/PresencePill";
+import ReconnectionBanner from "@/components/ReconnectionBanner";
+
 const RecipientForm = dynamic(() => import("@/components/RecipientForm"), { ssr: false });
 const TemplateManager = dynamic(() => import("@/components/TemplateManager"), { ssr: false });
 const TxImportPanel = dynamic(() => import("@/components/invoice/TxImportPanel"), { ssr: false });
@@ -291,6 +296,7 @@ function NewInvoiceForm() {
     }
   }, [searchParams, addToast]);
 
+  const [publicKey, setPublicKey] = useState<string | null>(null);
   const [error, setError] = useState<string | null>(null);
   const [txModal, setTxModal] = useState<{ txHash: string; invoiceId: string } | null>(null);
   const [equalSplit, setEqualSplit] = useState(false);
@@ -299,6 +305,10 @@ function NewInvoiceForm() {
   const [autofilled, setAutofilled] = useState(false);
   const [stepErrors, setStepErrors] = useState<Record<number, string | null>>({});
 
+  useEffect(() => {
+    getFreighterPublicKey().then(setPublicKey).catch(() => null);
+  }, []);
+
   useEffect(() => {
     if (fromId || sessionStorage.getItem("invoiceTemplate") || searchParams.get("address")) return;
 
@@ -582,10 +592,15 @@ function NewInvoiceForm() {
             type="text"
             value={token}
             onChange={(e) => setToken(e.target.value)}
+            onFocus={() => setFocusedField("token-address")}
+            onBlur={() => {
+              if (focusedField === "token-address") emitFieldBlur();
+            }}
             required
             placeholder="C..."
             className="w-full min-h-11 bg-gray-800 border border-gray-700 rounded-lg px-4 py-2 text-sm text-gray-100 focus:outline-none focus:ring-2 focus:ring-indigo-500"
           />
+          <CursorOverlay cursors={remoteCursors} fieldName="token-address" />
         </ChangedField>
       </div>
 
@@ -629,9 +644,14 @@ function NewInvoiceForm() {
             max={365}
             value={deadlineDays}
             onChange={(e) => setDeadlineDays(Number(e.target.value))}
+            onFocus={() => setFocusedField("deadline-days")}
+            onBlur={() => {
+              if (focusedField === "deadline-days") emitFieldBlur();
+            }}
             required
             className="w-full min-h-11 bg-gray-800 border border-gray-700 rounded-lg px-4 py-2 text-sm text-gray-100 focus:outline-none focus:ring-2 focus:ring-indigo-500"
           />
+          <CursorOverlay cursors={remoteCursors} fieldName="deadline-days" />
           <DeadlineSuggester
             totalAmount={
               equalSplit
@@ -731,9 +751,14 @@ function NewInvoiceForm() {
             min="0.0000001"
             value={totalAmount}
             onChange={(e) => setTotalAmount(e.target.value)}
+            onFocus={() => setFocusedField("total-amount")}
+            onBlur={() => {
+              if (focusedField === "total-amount") emitFieldBlur();
+            }}
             required
             className="w-full min-h-11 bg-gray-800 border border-gray-700 rounded-lg px-4 py-2 text-sm text-gray-100 focus:outline-none focus:ring-2 focus:ring-indigo-500"
           />
+          <CursorOverlay cursors={remoteCursors} fieldName="total-amount" />
           {perRecipientAmount && (
             <p className="mt-1 text-xs text-gray-600 dark:text-gray-400">
               {perRecipientAmount} {t("invoiceNew.perRecipient")}
@@ -887,6 +912,14 @@ function NewInvoiceForm() {
 
   return (
     <main className="max-w-xl mx-auto w-full px-4 sm:px-6 py-16 overflow-x-hidden">
+      {/* Collaboration presence */}
+      {publicKey && <PresencePill presences={remotePresence} currentAddress={publicKey} />}
+
+      <ReconnectionBanner
+        show={!collabConnected && !!publicKey}
+        isConnected={collabConnected}
+      />
+
       <div
         aria-live="polite"
         className="fixed bottom-4 right-4 z-50 flex flex-col gap-2 pointer-events-none"

src/components/CoCreatorPanel.tsx

@@ -28,6 +28,16 @@ export function loadPermissions(invoiceId: string): CoCreatorEntry[] {
   }
 }
 
+export function canUserEditInvoice(
+  invoice: { creator: string; id: string; coCreators?: string[] },
+  address: string,
+): boolean {
+  if (address === invoice.creator) return true;
+  const permissions = loadPermissions(invoice.id);
+  const entry = permissions.find((e) => e.address === address);
+  return entry?.permissionLevel === "edit" || entry?.permissionLevel === "admin";
+}
+
 function savePermissions(invoiceId: string, entries: CoCreatorEntry[]): void {
   if (typeof window === "undefined") return;
   localStorage.setItem(storageKey(invoiceId), JSON.stringify(entries));

src/components/CursorOverlay.tsx

@@ -0,0 +1,43 @@
+"use client";
+
+import { truncateAddress } from "@stellar-split/sdk";
+
+interface RemoteCursor {
+  address: string;
+  field: string;
+  color: string;
+  timestamp: number;
+}
+
+interface Props {
+  cursors: RemoteCursor[];
+  fieldName: string;
+}
+
+export default function CursorOverlay({ cursors, fieldName }: Props) {
+  const active = cursors.filter((c) => c.field === fieldName);
+  if (active.length === 0) return null;
+
+  return (
+    <div className="flex items-center gap-1.5 mt-1" aria-live="polite">
+      {active.map((cursor) => (
+        <div
+          key={cursor.address}
+          className="inline-flex items-center gap-1 px-2 py-0.5 rounded-full text-[10px] font-medium"
+          style={{
+            backgroundColor: `${cursor.color}20`,
+            color: cursor.color,
+            border: `1px solid ${cursor.color}40`,
+          }}
+          title={cursor.address}
+        >
+          <span
+            className="w-1.5 h-1.5 rounded-full inline-block"
+            style={{ backgroundColor: cursor.color }}
+          />
+          {truncateAddress(cursor.address)}
+        </div>
+      ))}
+    </div>
+  );
+}

src/components/PresencePill.tsx

@@ -0,0 +1,45 @@
+"use client";
+
+import { truncateAddress } from "@stellar-split/sdk";
+
+interface RemotePresence {
+  address: string;
+  online: boolean;
+  color: string;
+}
+
+interface Props {
+  presences: RemotePresence[];
+  currentAddress: string | null;
+}
+
+export default function PresencePill({ presences, currentAddress }: Props) {
+  const online = presences.filter((p) => p.online && p.address !== currentAddress);
+  if (online.length === 0) return null;
+
+  return (
+    <div className="flex items-center gap-2 mb-4">
+      <span className="text-xs text-gray-400">Editing:</span>
+      <div className="flex items-center gap-1">
+        {online.slice(0, 5).map((p) => (
+          <div
+            key={p.address}
+            className="w-7 h-7 rounded-full flex items-center justify-center text-[10px] font-bold text-white ring-2"
+            style={{
+              backgroundColor: p.color,
+              ringColor: p.color,
+            }}
+            title={p.address}
+          >
+            {truncateAddress(p.address).slice(0, 2).toUpperCase()}
+          </div>
+        ))}
+        {online.length > 5 && (
+          <div className="w-7 h-7 rounded-full flex items-center justify-center text-[10px] font-bold bg-gray-700 text-gray-300">
+            +{online.length - 5}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}