@taskforcehq/taskforce 0.3.168

package/dist/hooks/useDraggable.js

@@ -0,0 +1,65 @@
+import { useState, useCallback, useEffect, useRef } from 'react';
+export function useDraggable(initialPosition = { x: 0, y: 0 }) {
+    const [position, setPosition] = useState(initialPosition);
+    const [isDragging, setIsDragging] = useState(false);
+    const [dragStart, setDragStart] = useState({ x: 0, y: 0 });
+    const [initialTop, setInitialTop] = useState(0);
+    const modalRef = useRef(null);
+    const handleMouseDown = useCallback((e) => {
+        // Prevent drag if clicking buttons, inputs, selects, or textareas
+        const target = e.target;
+        if (target.closest('button') ||
+            target.closest('input') ||
+            target.closest('select') ||
+            target.closest('textarea') ||
+            target.closest('[role="button"]') ||
+            target.closest('.no-drag')) {
+            return;
+        }
+        if (modalRef.current) {
+            const rect = modalRef.current.getBoundingClientRect();
+            // We need to account for the current transform position
+            setInitialTop(rect.top - position.y);
+        }
+        setIsDragging(true);
+        setDragStart({
+            x: e.clientX - position.x,
+            y: e.clientY - position.y
+        });
+    }, [position]);
+    const handleMouseMove = useCallback((e) => {
+        if (isDragging) {
+            let newX = e.clientX - dragStart.x;
+            let newY = e.clientY - dragStart.y;
+            // Optional: Constrain Y so it doesn't go off top
+            if (newY < -initialTop) {
+                newY = -initialTop;
+            }
+            setPosition({ x: newX, y: newY });
+        }
+    }, [isDragging, dragStart, initialTop]);
+    const handleMouseUp = useCallback(() => {
+        setIsDragging(false);
+    }, []);
+    useEffect(() => {
+        if (isDragging) {
+            window.addEventListener('mousemove', handleMouseMove);
+            window.addEventListener('mouseup', handleMouseUp);
+        }
+        else {
+            window.removeEventListener('mousemove', handleMouseMove);
+            window.removeEventListener('mouseup', handleMouseUp);
+        }
+        return () => {
+            window.removeEventListener('mousemove', handleMouseMove);
+            window.removeEventListener('mouseup', handleMouseUp);
+        };
+    }, [isDragging, handleMouseMove, handleMouseUp]);
+    return {
+        position,
+        isDragging,
+        handleMouseDown,
+        modalRef,
+        setPosition
+    };
+}

package/dist/hooks/useRealtimeSync.d.ts

@@ -0,0 +1,24 @@
+import { type RealtimeReconcileTelemetry } from '../sync/realtimeReconcile';
+export type RealtimeConnectionState = 'connected' | 'reconnecting' | 'degraded-fallback';
+type RealtimeSignalType = 'taskforce:update' | 'taskforce:mutation' | 'taskforce:replay' | 'taskforce:replay-gap' | 'taskforce:replay-reset';
+export interface RealtimeSyncSignal {
+    type: RealtimeSignalType;
+    workspaceId: string;
+    eventId?: string;
+}
+export interface UseRealtimeSyncInput {
+    enabled: boolean;
+    workspaceId: string;
+    websocketUrl: string;
+    reconnectBaseMs?: number;
+    reconnectMaxMs?: number;
+    degradeAfterAttempts?: number;
+    replayLimit?: number;
+    onSignal?: (signal: RealtimeSyncSignal) => void;
+    onTelemetry?: (telemetry: RealtimeReconcileTelemetry) => void;
+}
+export declare function useRealtimeSync(input: UseRealtimeSyncInput): {
+    connectionState: RealtimeConnectionState;
+    telemetry: RealtimeReconcileTelemetry;
+};
+export {};

package/dist/hooks/useRealtimeSync.js

@@ -0,0 +1,275 @@
+import { useEffect, useMemo, useRef, useState } from 'react';
+import { RealtimeReconcileTracker } from '../sync/realtimeReconcile';
+export function useRealtimeSync(input) {
+    const { enabled, workspaceId, websocketUrl, reconnectBaseMs = 400, reconnectMaxMs = 10_000, degradeAfterAttempts = 5, replayLimit = 200, onSignal, onTelemetry } = input;
+    const [connectionState, setConnectionState] = useState('degraded-fallback');
+    const wsRef = useRef(null);
+    const reconnectTimerRef = useRef(null);
+    const reconnectAttemptRef = useRef(0);
+    const replayCursorRef = useRef('');
+    const recoveryInProgressRef = useRef(false);
+    const signalDebounceTimerRef = useRef(null);
+    const signalQueueRef = useRef(null);
+    const reconcileRef = useRef(new RealtimeReconcileTracker());
+    const [telemetry, setTelemetry] = useState({
+        accepted: 0,
+        duplicateDiscarded: 0,
+        outOfOrderDiscarded: 0,
+        invalidDiscarded: 0,
+        recoveryTriggered: 0
+    });
+    const normalizedWorkspaceId = useMemo(() => String(workspaceId || '').trim(), [workspaceId]);
+    const normalizedUrl = useMemo(() => String(websocketUrl || '').trim(), [websocketUrl]);
+    useEffect(() => {
+        let disposed = false;
+        const clearReconnectTimer = () => {
+            if (reconnectTimerRef.current !== null) {
+                window.clearTimeout(reconnectTimerRef.current);
+                reconnectTimerRef.current = null;
+            }
+        };
+        const closeSocket = () => {
+            const existing = wsRef.current;
+            wsRef.current = null;
+            if (existing) {
+                try {
+                    existing.close();
+                }
+                catch {
+                    // best-effort only
+                }
+            }
+        };
+        const signalPriority = (type) => {
+            if (type === 'taskforce:replay-gap' || type === 'taskforce:replay-reset')
+                return 4;
+            if (type === 'taskforce:mutation' || type === 'taskforce:replay')
+                return 3;
+            return 1;
+        };
+        const queueSignal = (next) => {
+            const current = signalQueueRef.current;
+            if (current) {
+                const currentPriority = signalPriority(current.type);
+                const nextPriority = signalPriority(next.type);
+                if (nextPriority < currentPriority)
+                    return;
+                if (nextPriority === currentPriority && current.eventId && !next.eventId)
+                    return;
+            }
+            signalQueueRef.current = next;
+            if (signalDebounceTimerRef.current !== null) {
+                window.clearTimeout(signalDebounceTimerRef.current);
+            }
+            signalDebounceTimerRef.current = window.setTimeout(() => {
+                signalDebounceTimerRef.current = null;
+                if (!signalQueueRef.current || typeof onSignal !== 'function')
+                    return;
+                const queued = signalQueueRef.current;
+                signalQueueRef.current = null;
+                onSignal(queued);
+            }, 80);
+        };
+        const parseEvent = (raw) => {
+            try {
+                const parsed = JSON.parse(String(raw.data || ''));
+                if (!parsed || typeof parsed !== 'object')
+                    return null;
+                return parsed;
+            }
+            catch {
+                return null;
+            }
+        };
+        const saveReplayCursor = (event) => {
+            const serverEpoch = typeof event.serverEpoch === 'string' ? event.serverEpoch.trim() : '';
+            const seq = Number(event.seq);
+            if (!serverEpoch || !Number.isFinite(seq) || seq < 0)
+                return;
+            replayCursorRef.current = `${serverEpoch}:${Math.floor(seq)}`;
+            recoveryInProgressRef.current = false;
+        };
+        const syncTelemetry = () => {
+            const next = reconcileRef.current.getTelemetry();
+            setTelemetry(next);
+            if (typeof onTelemetry === 'function')
+                onTelemetry(next);
+        };
+        const sendReplayRequest = (socket) => {
+            const payload = {
+                type: 'taskforce:replay',
+                workspaceId: normalizedWorkspaceId,
+                limit: replayLimit
+            };
+            const cursor = replayCursorRef.current;
+            if (cursor)
+                payload.cursor = cursor;
+            socket.send(JSON.stringify(payload));
+        };
+        const scheduleReconnect = () => {
+            if (!enabled || disposed)
+                return;
+            clearReconnectTimer();
+            reconnectAttemptRef.current += 1;
+            const attempt = reconnectAttemptRef.current;
+            const baseDelay = Math.max(50, Math.floor(reconnectBaseMs));
+            const maxDelay = Math.max(baseDelay, Math.floor(reconnectMaxMs));
+            const delay = Math.min(maxDelay, baseDelay * Math.pow(2, Math.max(0, attempt - 1)));
+            setConnectionState(attempt >= degradeAfterAttempts ? 'degraded-fallback' : 'reconnecting');
+            reconnectTimerRef.current = window.setTimeout(() => {
+                if (disposed)
+                    return;
+                reconnectTimerRef.current = null;
+                connect();
+            }, delay);
+        };
+        const connect = () => {
+            if (!enabled || disposed || !normalizedWorkspaceId || !normalizedUrl)
+                return;
+            closeSocket();
+            let socket;
+            try {
+                socket = new WebSocket(normalizedUrl);
+            }
+            catch {
+                scheduleReconnect();
+                return;
+            }
+            wsRef.current = socket;
+            socket.addEventListener('open', () => {
+                reconnectAttemptRef.current = 0;
+                setConnectionState('connected');
+                socket.send(JSON.stringify({
+                    type: 'taskforce:subscribe',
+                    workspaceId: normalizedWorkspaceId
+                }));
+                sendReplayRequest(socket);
+            });
+            socket.addEventListener('message', (raw) => {
+                const event = parseEvent(raw);
+                if (!event || typeof event.type !== 'string')
+                    return;
+                const eventWorkspaceId = typeof event.workspaceId === 'string'
+                    ? event.workspaceId.trim()
+                    : normalizedWorkspaceId;
+                if (!eventWorkspaceId || eventWorkspaceId !== normalizedWorkspaceId)
+                    return;
+                if (event.type === 'taskforce:update') {
+                    queueSignal({
+                        type: 'taskforce:update',
+                        workspaceId: normalizedWorkspaceId
+                    });
+                    return;
+                }
+                if (event.type === 'taskforce:mutation') {
+                    const reconcile = reconcileRef.current.process({
+                        eventId: event.eventId,
+                        serverEpoch: event.serverEpoch,
+                        seq: event.seq
+                    });
+                    if (!reconcile.accepted) {
+                        syncTelemetry();
+                        if (reconcile.shouldRecover) {
+                            replayCursorRef.current = '';
+                            if (!recoveryInProgressRef.current) {
+                                recoveryInProgressRef.current = true;
+                                queueSignal({
+                                    type: 'taskforce:replay-gap',
+                                    workspaceId: normalizedWorkspaceId
+                                });
+                            }
+                        }
+                        return;
+                    }
+                    saveReplayCursor(event);
+                    syncTelemetry();
+                    queueSignal({
+                        type: event.type,
+                        workspaceId: normalizedWorkspaceId,
+                        eventId: typeof event.eventId === 'string' ? event.eventId.trim() : undefined
+                    });
+                    return;
+                }
+                if (event.type === 'taskforce:replay') {
+                    const replayEvents = Array.isArray(event.events) ? event.events : [];
+                    let acceptedReplayEvents = 0;
+                    for (const replayEvent of replayEvents) {
+                        const reconcile = reconcileRef.current.process({
+                            eventId: replayEvent.eventId,
+                            serverEpoch: replayEvent.serverEpoch,
+                            seq: replayEvent.seq
+                        });
+                        if (!reconcile.accepted)
+                            continue;
+                        acceptedReplayEvents += 1;
+                        saveReplayCursor(replayEvent);
+                    }
+                    recoveryInProgressRef.current = false;
+                    syncTelemetry();
+                    if (acceptedReplayEvents > 0 || event.truncated === true) {
+                        queueSignal({ type: 'taskforce:replay', workspaceId: normalizedWorkspaceId });
+                    }
+                    if (event.truncated === true) {
+                        sendReplayRequest(socket);
+                    }
+                    return;
+                }
+                if (event.type === 'taskforce:replay-gap' || event.type === 'taskforce:replay-reset') {
+                    replayCursorRef.current = '';
+                    if (recoveryInProgressRef.current)
+                        return;
+                    recoveryInProgressRef.current = true;
+                    queueSignal({
+                        type: event.type,
+                        workspaceId: normalizedWorkspaceId
+                    });
+                }
+            });
+            socket.addEventListener('close', () => {
+                if (wsRef.current === socket)
+                    wsRef.current = null;
+                scheduleReconnect();
+            });
+            socket.addEventListener('error', () => {
+                try {
+                    socket.close();
+                }
+                catch {
+                    // best-effort only
+                }
+            });
+        };
+        if (!enabled || !normalizedWorkspaceId || !normalizedUrl) {
+            setConnectionState('degraded-fallback');
+            clearReconnectTimer();
+            closeSocket();
+            return () => {
+                clearReconnectTimer();
+                closeSocket();
+            };
+        }
+        setConnectionState('reconnecting');
+        connect();
+        return () => {
+            disposed = true;
+            clearReconnectTimer();
+            if (signalDebounceTimerRef.current !== null) {
+                window.clearTimeout(signalDebounceTimerRef.current);
+                signalDebounceTimerRef.current = null;
+            }
+            signalQueueRef.current = null;
+            closeSocket();
+        };
+    }, [
+        enabled,
+        normalizedWorkspaceId,
+        normalizedUrl,
+        reconnectBaseMs,
+        reconnectMaxMs,
+        degradeAfterAttempts,
+        replayLimit,
+        onSignal,
+        onTelemetry
+    ]);
+    return { connectionState, telemetry };
+}

package/dist/hooks/useRealtimeSync.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/hooks/useRealtimeSync.test.js

@@ -0,0 +1,284 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { act, renderHook, waitFor } from '@testing-library/react';
+import { useRealtimeSync } from './useRealtimeSync';
+class MockWebSocket {
+    static instances = [];
+    static OPEN = 1;
+    static CLOSED = 3;
+    url;
+    readyState = 0;
+    sent = [];
+    listeners = {
+        open: [],
+        message: [],
+        close: [],
+        error: []
+    };
+    constructor(url) {
+        this.url = url;
+        MockWebSocket.instances.push(this);
+    }
+    addEventListener(type, listener) {
+        this.listeners[type] = this.listeners[type] || [];
+        this.listeners[type].push(listener);
+    }
+    close() {
+        this.readyState = MockWebSocket.CLOSED;
+        this.emit('close', {});
+    }
+    send(payload) {
+        this.sent.push(payload);
+    }
+    emit(type, event) {
+        const handlers = this.listeners[type] || [];
+        handlers.forEach((handler) => handler(event));
+    }
+    open() {
+        this.readyState = MockWebSocket.OPEN;
+        this.emit('open', {});
+    }
+    message(payload) {
+        this.emit('message', { data: JSON.stringify(payload) });
+    }
+}
+describe('useRealtimeSync', () => {
+    afterEach(() => {
+        vi.useRealTimers();
+        vi.unstubAllGlobals();
+        MockWebSocket.instances = [];
+    });
+    it('connects, subscribes, and emits coalesced signal on update', async () => {
+        vi.stubGlobal('WebSocket', MockWebSocket);
+        const onSignal = vi.fn();
+        const { result } = renderHook(() => useRealtimeSync({
+            enabled: true,
+            workspaceId: 'ws-1',
+            websocketUrl: 'wss://example.com/taskforce-ws',
+            onSignal
+        }));
+        expect(MockWebSocket.instances).toHaveLength(1);
+        const socket = MockWebSocket.instances[0];
+        act(() => {
+            socket.open();
+            socket.message({ type: 'taskforce:update', workspaceId: 'ws-1' });
+            socket.message({ type: 'taskforce:update', workspaceId: 'ws-1' });
+        });
+        await waitFor(() => {
+            expect(result.current.connectionState).toBe('connected');
+        });
+        await waitFor(() => {
+            expect(onSignal).toHaveBeenCalledTimes(1);
+        });
+        const outboundTypes = socket.sent.map((entry) => JSON.parse(entry).type);
+        expect(outboundTypes).toContain('taskforce:subscribe');
+        expect(outboundTypes).toContain('taskforce:replay');
+    });
+    it('reconnects with backoff and degrades after threshold', async () => {
+        vi.useFakeTimers();
+        vi.stubGlobal('WebSocket', MockWebSocket);
+        const { result } = renderHook(() => useRealtimeSync({
+            enabled: true,
+            workspaceId: 'ws-1',
+            websocketUrl: 'wss://example.com/taskforce-ws',
+            reconnectBaseMs: 100,
+            reconnectMaxMs: 100,
+            degradeAfterAttempts: 2
+        }));
+        const first = MockWebSocket.instances[0];
+        act(() => {
+            first.open();
+            first.close();
+        });
+        expect(result.current.connectionState).toBe('reconnecting');
+        act(() => {
+            vi.advanceTimersByTime(100);
+        });
+        expect(MockWebSocket.instances).toHaveLength(2);
+        const second = MockWebSocket.instances[1];
+        act(() => {
+            second.close();
+        });
+        expect(result.current.connectionState).toBe('degraded-fallback');
+    });
+    it('does not connect when disabled', () => {
+        vi.stubGlobal('WebSocket', MockWebSocket);
+        const { result } = renderHook(() => useRealtimeSync({
+            enabled: false,
+            workspaceId: 'ws-1',
+            websocketUrl: 'wss://example.com/taskforce-ws'
+        }));
+        expect(MockWebSocket.instances).toHaveLength(0);
+        expect(result.current.connectionState).toBe('degraded-fallback');
+    });
+    it('resumes replay from last acknowledged cursor after reconnect', async () => {
+        vi.stubGlobal('WebSocket', MockWebSocket);
+        renderHook(() => useRealtimeSync({
+            enabled: true,
+            workspaceId: 'ws-1',
+            websocketUrl: 'wss://example.com/taskforce-ws'
+        }));
+        const first = MockWebSocket.instances[0];
+        act(() => {
+            first.open();
+            first.message({
+                type: 'taskforce:mutation',
+                workspaceId: 'ws-1',
+                serverEpoch: 'epoch-1',
+                seq: 5
+            });
+            first.close();
+        });
+        await waitFor(() => {
+            expect(MockWebSocket.instances.length).toBeGreaterThanOrEqual(2);
+        });
+        const second = MockWebSocket.instances[1];
+        act(() => {
+            second.open();
+        });
+        const replayPayloads = second.sent
+            .map((entry) => JSON.parse(entry))
+            .filter((entry) => entry.type === 'taskforce:replay');
+        expect(replayPayloads.length).toBeGreaterThanOrEqual(1);
+        expect(replayPayloads[0].cursor).toBe('epoch-1:5');
+    });
+    it('triggers full-resync signal once on replay-gap/reset until cursor recovers', async () => {
+        vi.stubGlobal('WebSocket', MockWebSocket);
+        const onSignal = vi.fn();
+        renderHook(() => useRealtimeSync({
+            enabled: true,
+            workspaceId: 'ws-1',
+            websocketUrl: 'wss://example.com/taskforce-ws',
+            onSignal
+        }));
+        const socket = MockWebSocket.instances[0];
+        act(() => {
+            socket.open();
+            socket.message({ type: 'taskforce:replay-gap', workspaceId: 'ws-1' });
+            socket.message({ type: 'taskforce:replay-reset', workspaceId: 'ws-1' });
+        });
+        await waitFor(() => {
+            expect(onSignal).toHaveBeenCalledTimes(1);
+        });
+        expect(onSignal.mock.calls[0][0]?.type).toBe('taskforce:replay-gap');
+        act(() => {
+            socket.message({
+                type: 'taskforce:mutation',
+                workspaceId: 'ws-1',
+                serverEpoch: 'epoch-2',
+                seq: 1
+            });
+            socket.message({ type: 'taskforce:replay-reset', workspaceId: 'ws-1' });
+        });
+        await waitFor(() => {
+            expect(onSignal.mock.calls.length).toBeGreaterThanOrEqual(2);
+        });
+        expect(onSignal.mock.calls[1][0]?.type).toBe('taskforce:replay-reset');
+    });
+    it('converts out-of-order mutation delivery into replay-gap recovery signal and telemetry', async () => {
+        vi.stubGlobal('WebSocket', MockWebSocket);
+        const onSignal = vi.fn();
+        const onTelemetry = vi.fn();
+        renderHook(() => useRealtimeSync({
+            enabled: true,
+            workspaceId: 'ws-1',
+            websocketUrl: 'wss://example.com/taskforce-ws',
+            onSignal,
+            onTelemetry
+        }));
+        const socket = MockWebSocket.instances[0];
+        act(() => {
+            socket.open();
+            socket.message({
+                type: 'taskforce:mutation',
+                workspaceId: 'ws-1',
+                eventId: 'epoch-1:1',
+                serverEpoch: 'epoch-1',
+                seq: 1
+            });
+            socket.message({
+                type: 'taskforce:mutation',
+                workspaceId: 'ws-1',
+                eventId: 'epoch-1:3',
+                serverEpoch: 'epoch-1',
+                seq: 3
+            });
+        });
+        await waitFor(() => {
+            expect(onSignal.mock.calls.some((call) => call?.[0]?.type === 'taskforce:replay-gap')).toBe(true);
+        });
+        await waitFor(() => {
+            expect(onTelemetry).toHaveBeenCalled();
+        });
+        const lastTelemetry = onTelemetry.mock.calls.at(-1)?.[0];
+        expect(lastTelemetry?.outOfOrderDiscarded).toBeGreaterThanOrEqual(1);
+        expect(lastTelemetry?.recoveryTriggered).toBeGreaterThanOrEqual(1);
+    });
+    it('prioritizes mutation over trailing update and keeps mutation eventId', async () => {
+        vi.stubGlobal('WebSocket', MockWebSocket);
+        const onSignal = vi.fn();
+        renderHook(() => useRealtimeSync({
+            enabled: true,
+            workspaceId: 'ws-1',
+            websocketUrl: 'wss://example.com/taskforce-ws',
+            onSignal
+        }));
+        const socket = MockWebSocket.instances[0];
+        act(() => {
+            socket.open();
+            socket.message({
+                type: 'taskforce:mutation',
+                workspaceId: 'ws-1',
+                eventId: 'epoch-1:10',
+                serverEpoch: 'epoch-1',
+                seq: 10
+            });
+            socket.message({
+                type: 'taskforce:update',
+                workspaceId: 'ws-1'
+            });
+        });
+        await waitFor(() => {
+            expect(onSignal).toHaveBeenCalledTimes(1);
+        });
+        expect(onSignal.mock.calls[0][0]).toMatchObject({
+            type: 'taskforce:mutation',
+            workspaceId: 'ws-1',
+            eventId: 'epoch-1:10'
+        });
+    });
+    it('does not emit replay signal for duplicate-only replay batch', async () => {
+        vi.stubGlobal('WebSocket', MockWebSocket);
+        const onSignal = vi.fn();
+        renderHook(() => useRealtimeSync({
+            enabled: true,
+            workspaceId: 'ws-1',
+            websocketUrl: 'wss://example.com/taskforce-ws',
+            onSignal
+        }));
+        const socket = MockWebSocket.instances[0];
+        act(() => {
+            socket.open();
+            socket.message({
+                type: 'taskforce:replay',
+                workspaceId: 'ws-1',
+                events: [
+                    { eventId: 'epoch-1:1', serverEpoch: 'epoch-1', seq: 1 }
+                ]
+            });
+            socket.message({
+                type: 'taskforce:replay',
+                workspaceId: 'ws-1',
+                events: [
+                    { eventId: 'epoch-1:1', serverEpoch: 'epoch-1', seq: 1 }
+                ]
+            });
+        });
+        await waitFor(() => {
+            expect(onSignal).toHaveBeenCalledTimes(1);
+        });
+        expect(onSignal.mock.calls[0][0]).toMatchObject({
+            type: 'taskforce:replay',
+            workspaceId: 'ws-1'
+        });
+    });
+});