🚀 Zustand Migration Analysis

📊 Executive Summary

The migration from React Context to Zustand has fundamentally improved the application's rendering performance by addressing the core architectural flaw: cascading re-renders from context value changes.

🔍 The Dock Flicker Case Study

The Symptom

When refreshing the root page with the dock in a collapsed state (saved to localStorage), users observed:

1. Page loads with dock briefly appearing in expanded/default state
2. Quick flicker (100-200ms)
3. Dock collapses to the correct saved state

The Technical Chain of Events (Pre-Zustand)

Why Zustand Fixed It

// Board.tsx - Synchronous hydration (the key fix)
const hydratedRef = useRef(false);

// Hydrate store synchronously on first render
if (!hydratedRef.current) {
    useBoardStore.setState(board);
    hydratedRef.current = true;
}

⚠️ Exhaustive Pre-Zustand Re-render Issues

The Context-based architecture had multiple re-render issues across the application. Here is a comprehensive analysis:

// Old BoardContext.tsx pattern
const value = useMemo(() => ({
    board,        // New object every dispatch
    patchTask,
    createTask,
    deleteTask,
    // ... more actions
}), [board, /* all action deps */]);

/**
 * TODO optimize the number of times it is rendered
 */
export default function Column({ column, onOpenTask }) { ... }

// OLD pattern (pre-migration)
const [paneTask, setPaneTask] = useState<TaskView | null>(task);

// This caused:
// 1. Stale data when board updated
// 2. Extra useState + useEffect re-renders
// 3. Manual sync required for every mutation

const paneTask = useActiveTask(taskId);

// OLD pattern
const [items, setItems] = useState<TaskView[]>(initial || []);

// External updates = stale display
// Direct taskAdapter calls = bypassed context

// OLD pattern (hypothetical)
const { board } = useBoard();
const runningTasks = Object.values(board.tasks).filter(t => t.state === 'IN_PROGRESS');
const onHoldTasks = Object.values(board.tasks).filter(t => t.state === 'ON_HOLD');
// ... 4 more filters

// ANY task change = 6 filter recalculations + re-render

const runningTasks = useTasksByState("IN_PROGRESS");
const onHoldTasks = useTasksByState("ON_HOLD");
// Each uses useShallow for array comparison

// Actions are stable function refs in Zustand
export function useBoardActions() {
    const hydrate = useBoardStore((s) => s.hydrate);
    const patchTask = useBoardStore((s) => s.patchTask);
    // ... returns memoized object
}

✅ How Zustand Mitigated These Issues

1. Selector-Based Subscriptions

The core architectural shift: components now subscribe to specific slices of state rather than the entire context.

// useBoardStore.ts - Fine-grained selectors
export const useBoardId = () => useBoardStore((s) => s.id);
export const useBoardName = () => useBoardStore((s) => s.name);
export const useBoardTasks = () => useBoardStore((s) => s.tasks);
export const useBoardColumns = () => useBoardStore((s) => s.columns);

export function useTaskById(id) {
    return useBoardStore((s) => s.tasks[id]);
}

export function useTasksByState(state) {
    return useBoardStore(
        useShallow((s) => Object.values(s.tasks).filter((t) => t.state === state))
    );
}

2. Synchronous Store Initialization

The crucial fix for the dock flicker:

// Board.tsx - Before first render
if (!hydratedRef.current) {
    useBoardStore.setState(board);  // Synchronous!
    hydratedRef.current = true;
}

// vs old Context pattern
useEffect(() => {
    dispatch({ type: "HYDRATE", data: board });  // Async!
}, []);

3. useShallow for Collection Comparisons

Zustand's useShallow hook performs shallow equality checks on arrays and objects:

export function useTasksInColumn(id) {
    return useBoardStore(
        useShallow((s) => {
            const col = s.columns[id];
            return col?.taskIds.map((tid) => s.tasks[tid]).filter(Boolean) ?? [];
        })
    );
}

4. Stable Action References

Unlike Context where the actions object could change identity, Zustand actions are stable:

// Actions are defined once in create() and never change
const useBoardStore = create((set, get) => ({
    hydrate: (data) => set(data),
    patchTask: async (id, patch) => { ... },
    // These function references never change
}));

5. DevTools Integration

The migration included Zustand DevTools middleware for debugging:

export const useBoardStore = create(
    devtools(
        (set, get) => ({ ... }),
        { name: "board-store" }
    )
);

📋 Current State Analysis

Remaining Optimization Opportunities

Current Architecture Strengths

🔮 Future Implications & Challenges

Benefits Gained

Future Challenges

💡 Recommendations

Short-term

1. Add React.memo to TaskCard: Since it receives a task prop from Column, memoization would prevent re-renders when unrelated tasks change.
2. Address Column TODO: Profile the Column component and apply targeted optimizations.
3. Consider breaking up TaskPane: 1500 lines is large; extract logical sections into smaller components with their own selector hooks.

Medium-term

1. Virtualization for large boards: If task counts grow significantly, virtualize column content.
2. Persist more UI state in Zustand: Currently dock collapsed state is in localStorage + useState. Consider a dedicated UI store.
3. Establish selector naming conventions: Document patterns like use[Entity]By[Filter] for consistency.

Long-term

1. Consider middleware for logging: Add a custom middleware to track state changes in production for debugging.
2. Evaluate React Query integration: For server state synchronization, React Query could complement Zustand.
3. Performance budgets: Set metrics for maximum re-renders per action type.