orbital-command 0.1.0

package/src/components/workflow/useWorkflowEditor.ts

@@ -0,0 +1,262 @@
+import { useState, useCallback, useMemo } from 'react';
+import type { WorkflowConfig, WorkflowList, WorkflowEdge } from '../../../shared/workflow-config';
+import { useEditHistory } from './useEditHistory';
+import { validateConfig } from './validateConfig';
+import type { ConfigValidationResult } from './validateConfig';
+
+// ─── Types ──────────────────────────────────────────────
+
+interface MigrationPlan {
+  valid: boolean;
+  validationErrors: string[];
+  removedLists: string[];
+  addedLists: string[];
+  dirsToCreate: string[];
+  dirsToRemove: string[];
+  orphanedScopes: Array<{ listId: string; scopeFiles: string[] }>;
+  lostEdges: Array<{ from: string; to: string }>;
+  suggestedMappings: Record<string, string>;
+  impactSummary: string;
+}
+
+interface WorkflowEditorState {
+  editMode: boolean;
+  editConfig: WorkflowConfig;
+  canUndo: boolean;
+  canRedo: boolean;
+  changeCount: number;
+  validation: ConfigValidationResult;
+  saving: boolean;
+  previewPlan: MigrationPlan | null;
+  previewLoading: boolean;
+  previewError: string | null;
+  showPreview: boolean;
+  showAddList: boolean;
+  showAddEdge: boolean;
+  showConfigSettings: boolean;
+}
+
+interface WorkflowEditorActions {
+  enterEditMode: () => void;
+  exitEditMode: () => void;
+  undo: () => void;
+  redo: () => void;
+  updateList: (original: WorkflowList, updated: WorkflowList) => void;
+  deleteList: (listId: string) => void;
+  addList: (list: WorkflowList) => void;
+  updateEdge: (original: WorkflowEdge, updated: WorkflowEdge) => void;
+  deleteEdge: (from: string, to: string) => void;
+  addEdge: (edge: WorkflowEdge) => void;
+  updateConfig: (config: WorkflowConfig) => void;
+  save: () => Promise<void>;
+  discard: () => void;
+  preview: () => Promise<void>;
+  applyMigration: (orphanMappings: Record<string, string>) => Promise<void>;
+  setShowPreview: (show: boolean) => void;
+  setShowAddList: (show: boolean) => void;
+  setShowAddEdge: (show: boolean) => void;
+  setShowConfigSettings: (show: boolean) => void;
+}
+
+export type WorkflowEditor = WorkflowEditorState & WorkflowEditorActions;
+
+// ─── Hook ───────────────────────────────────────────────
+
+export function useWorkflowEditor(activeConfig: WorkflowConfig): WorkflowEditor {
+  const [editMode, setEditMode] = useState(false);
+  const [saving, setSaving] = useState(false);
+  const [previewPlan, setPreviewPlan] = useState<MigrationPlan | null>(null);
+  const [previewLoading, setPreviewLoading] = useState(false);
+  const [previewError, setPreviewError] = useState<string | null>(null);
+  const [showPreview, setShowPreview] = useState(false);
+  const [showAddList, setShowAddList] = useState(false);
+  const [showAddEdge, setShowAddEdge] = useState(false);
+  const [showConfigSettings, setShowConfigSettings] = useState(false);
+
+  const history = useEditHistory(activeConfig);
+
+  const validation = useMemo(
+    () => validateConfig(history.present),
+    [history.present],
+  );
+
+  // ─── Mode Toggle ────────────────────────────────────
+
+  const enterEditMode = useCallback(() => {
+    history.reset(activeConfig);
+    setEditMode(true);
+  }, [activeConfig, history]);
+
+  const exitEditMode = useCallback(() => {
+    setEditMode(false);
+    setShowPreview(false);
+    setShowAddList(false);
+    setShowAddEdge(false);
+    setShowConfigSettings(false);
+  }, []);
+
+  const discard = useCallback(() => {
+    history.reset(activeConfig);
+    exitEditMode();
+  }, [activeConfig, history, exitEditMode]);
+
+  // ─── List Operations ────────────────────────────────
+
+  const addList = useCallback((list: WorkflowList) => {
+    const config = structuredClone(history.present);
+    config.lists.push(list);
+    history.pushState(config);
+  }, [history]);
+
+  const updateList = useCallback((original: WorkflowList, updated: WorkflowList) => {
+    const config = structuredClone(history.present);
+    const idx = config.lists.findIndex((l) => l.id === original.id);
+    if (idx === -1) return;
+    // If ID changed, update all edge references
+    if (original.id !== updated.id) {
+      for (const edge of config.edges) {
+        if (edge.from === original.id) edge.from = updated.id;
+        if (edge.to === original.id) edge.to = updated.id;
+      }
+    }
+    config.lists[idx] = updated;
+    history.pushState(config);
+  }, [history]);
+
+  const deleteList = useCallback((listId: string) => {
+    const config = structuredClone(history.present);
+    config.lists = config.lists.filter((l) => l.id !== listId);
+    config.edges = config.edges.filter((e) => e.from !== listId && e.to !== listId);
+    history.pushState(config);
+  }, [history]);
+
+  // ─── Edge Operations ────────────────────────────────
+
+  const addEdge = useCallback((edge: WorkflowEdge) => {
+    const config = structuredClone(history.present);
+    config.edges.push(edge);
+    history.pushState(config);
+  }, [history]);
+
+  const updateConfig = useCallback((updated: WorkflowConfig) => {
+    history.pushState(structuredClone(updated));
+  }, [history]);
+
+  const updateEdge = useCallback((original: WorkflowEdge, updated: WorkflowEdge) => {
+    const config = structuredClone(history.present);
+    const key = `${original.from}:${original.to}`;
+    const idx = config.edges.findIndex((e) => `${e.from}:${e.to}` === key);
+    if (idx === -1) return;
+    config.edges[idx] = updated;
+    history.pushState(config);
+  }, [history]);
+
+  const deleteEdge = useCallback((from: string, to: string) => {
+    const config = structuredClone(history.present);
+    config.edges = config.edges.filter((e) => !(e.from === from && e.to === to));
+    history.pushState(config);
+  }, [history]);
+
+  // ─── Save ───────────────────────────────────────────
+
+  const save = useCallback(async () => {
+    if (!validation.valid || saving) return;
+    setSaving(true);
+    try {
+      const res = await fetch('/api/orbital/workflow', {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(history.present),
+      });
+      const json: { success: boolean; error?: string } = await res.json();
+      if (!json.success) throw new Error(json.error ?? 'Save failed');
+      exitEditMode();
+    } catch (err) {
+      setPreviewError(err instanceof Error ? err.message : 'Save failed');
+    } finally {
+      setSaving(false);
+    }
+  }, [validation.valid, saving, history.present, exitEditMode]);
+
+  // ─── Preview ────────────────────────────────────────
+
+  const preview = useCallback(async () => {
+    setPreviewLoading(true);
+    setPreviewError(null);
+    setPreviewPlan(null);
+    setShowPreview(true);
+    try {
+      const res = await fetch('/api/orbital/workflow/preview', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(history.present),
+      });
+      const json: { success: boolean; data?: MigrationPlan; error?: string } = await res.json();
+      if (!json.success) throw new Error(json.error ?? 'Preview failed');
+      setPreviewPlan(json.data ?? null);
+    } catch (err) {
+      setPreviewError(err instanceof Error ? err.message : 'Preview failed');
+    } finally {
+      setPreviewLoading(false);
+    }
+  }, [history.present]);
+
+  // ─── Apply Migration ────────────────────────────────
+
+  const applyMigration = useCallback(async (orphanMappings: Record<string, string>) => {
+    setSaving(true);
+    try {
+      const res = await fetch('/api/orbital/workflow/apply', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ config: history.present, orphanMappings }),
+      });
+      const json: { success: boolean; error?: string } = await res.json();
+      if (!json.success) throw new Error(json.error ?? 'Migration failed');
+      setShowPreview(false);
+      exitEditMode();
+    } catch (err) {
+      setPreviewError(err instanceof Error ? err.message : 'Migration failed');
+    } finally {
+      setSaving(false);
+    }
+  }, [history.present, exitEditMode]);
+
+  return {
+    // State
+    editMode,
+    editConfig: history.present,
+    canUndo: history.canUndo,
+    canRedo: history.canRedo,
+    changeCount: history.changeCount,
+    validation,
+    saving,
+    previewPlan,
+    previewLoading,
+    previewError,
+    showPreview,
+    showAddList,
+    showAddEdge,
+    showConfigSettings,
+    // Actions
+    enterEditMode,
+    exitEditMode,
+    undo: history.undo,
+    redo: history.redo,
+    updateList,
+    deleteList,
+    addList,
+    updateEdge,
+    deleteEdge,
+    addEdge,
+    updateConfig,
+    save,
+    discard,
+    preview,
+    applyMigration,
+    setShowPreview,
+    setShowAddList,
+    setShowAddEdge,
+    setShowConfigSettings,
+  };
+}

package/src/components/workflow/validateConfig.ts

@@ -0,0 +1,70 @@
+import type { WorkflowConfig } from '../../../shared/workflow-config';
+import { isWorkflowConfig } from '../../../shared/workflow-config';
+
+// ─── Types ──────────────────────────────────────────────
+
+export interface ConfigValidationResult {
+  valid: boolean;
+  errors: string[];
+}
+
+// ─── Validation ─────────────────────────────────────────
+// Mirrors server-side validation in workflow-service.ts
+
+export function validateConfig(config: WorkflowConfig): ConfigValidationResult {
+  const errors: string[] = [];
+
+  if (!isWorkflowConfig(config)) {
+    errors.push('Invalid config shape: must have version=1, name, lists[], edges[]');
+    return { valid: false, errors };
+  }
+
+  if (config.branchingMode !== undefined && config.branchingMode !== 'trunk' && config.branchingMode !== 'worktree') {
+    errors.push(`Invalid branchingMode: "${config.branchingMode}" (must be "trunk" or "worktree")`);
+  }
+
+  // Unique list IDs
+  const listIds = new Set<string>();
+  for (const list of config.lists) {
+    if (listIds.has(list.id)) errors.push(`Duplicate list ID: "${list.id}"`);
+    listIds.add(list.id);
+  }
+
+  // Valid edge references + no duplicates
+  const edgeKeys = new Set<string>();
+  for (const edge of config.edges) {
+    if (!listIds.has(edge.from)) errors.push(`Edge references unknown list: from="${edge.from}"`);
+    if (!listIds.has(edge.to)) errors.push(`Edge references unknown list: to="${edge.to}"`);
+    if (edge.from === edge.to) errors.push(`Self-referencing edge: "${edge.from}" → "${edge.to}"`);
+    const key = `${edge.from}:${edge.to}`;
+    if (edgeKeys.has(key)) errors.push(`Duplicate edge: ${key}`);
+    edgeKeys.add(key);
+  }
+
+  // Exactly 1 entry point
+  const entryPoints = config.lists.filter((l) => l.isEntryPoint);
+  if (entryPoints.length === 0) errors.push('No entry point defined (isEntryPoint=true)');
+  if (entryPoints.length > 1) errors.push(`Multiple entry points: ${entryPoints.map((l) => l.id).join(', ')}`);
+
+  // Graph connectivity — all non-terminal lists reachable from entry point
+  if (entryPoints.length === 1 && errors.length === 0) {
+    const terminal = new Set(config.terminalStatuses ?? []);
+    const reachable = new Set<string>();
+    const queue = [entryPoints[0].id];
+    while (queue.length > 0) {
+      const current = queue.shift()!;
+      if (reachable.has(current)) continue;
+      reachable.add(current);
+      for (const edge of config.edges) {
+        if (edge.from === current && !reachable.has(edge.to)) queue.push(edge.to);
+      }
+    }
+    for (const list of config.lists) {
+      if (!terminal.has(list.id) && !reachable.has(list.id)) {
+        errors.push(`List "${list.id}" is not reachable from entry point`);
+      }
+    }
+  }
+
+  return { valid: errors.length === 0, errors };
+}

package/src/hooks/useActiveDispatches.ts

@@ -0,0 +1,198 @@
+import { createContext, useContext, useState, useEffect, useCallback, useRef, useMemo } from 'react';
+import { socket } from '../socket';
+import type { OrbitalEvent, Scope, DispatchResolvedPayload } from '@/types';
+import { useWorkflow } from './useWorkflow';
+
+export interface AbandonedInfo {
+  from_status: string | null;
+  abandoned_at: string;
+}
+
+interface ActiveDispatchContextValue {
+  activeScopes: Set<number>;
+  abandonedScopes: Map<number, AbandonedInfo>;
+  recoverScope: (scopeId: number, fromStatus: string) => Promise<void>;
+  dismissAbandoned: (scopeId: number) => Promise<void>;
+}
+
+const DEFAULT_VALUE: ActiveDispatchContextValue = {
+  activeScopes: new Set(),
+  abandonedScopes: new Map(),
+  recoverScope: async () => {},
+  dismissAbandoned: async () => {},
+};
+
+export const ActiveDispatchContext = createContext<ActiveDispatchContextValue>(DEFAULT_VALUE);
+
+/** Provider hook — call once at ScopeBoard level.
+ *  Fetches initial set from REST, then maintains via socket events. */
+export function useActiveDispatchProvider(): ActiveDispatchContextValue {
+  const { engine } = useWorkflow();
+  const terminalStatuses = useMemo(
+    () => new Set(engine.getConfig().terminalStatuses ?? []),
+    [engine],
+  );
+  const [activeScopes, setActiveScopes] = useState<Set<number>>(new Set());
+  const [abandonedScopes, setAbandonedScopes] = useState<Map<number, AbandonedInfo>>(new Map());
+  const mountedRef = useRef(true);
+
+  const removeFromAbandoned = useCallback((scopeId: number) => {
+    setAbandonedScopes((prev) => {
+      if (!prev.has(scopeId)) return prev;
+      const next = new Map(prev);
+      next.delete(scopeId);
+      return next;
+    });
+  }, []);
+
+  const fetchActiveScopes = useCallback(async () => {
+    try {
+      const res = await fetch('/api/orbital/dispatch/active-scopes');
+      if (!res.ok) {
+        console.warn('[Orbital] Failed to fetch active scopes:', res.status, res.statusText);
+        return;
+      }
+      const data = await res.json() as {
+        scope_ids: number[];
+        abandoned_scopes?: Array<{ scope_id: number; from_status: string | null; abandoned_at: string }>;
+      };
+      if (!mountedRef.current) return;
+      setActiveScopes(new Set(data.scope_ids));
+
+      if (data.abandoned_scopes) {
+        const map = new Map<number, AbandonedInfo>();
+        for (const item of data.abandoned_scopes) {
+          map.set(item.scope_id, { from_status: item.from_status, abandoned_at: item.abandoned_at });
+        }
+        setAbandonedScopes(map);
+      }
+    } catch {
+      // Silently ignore — will retry on next reconnect
+    }
+  }, []);
+
+  const recoverScope = useCallback(async (scopeId: number, fromStatus: string) => {
+    try {
+      const res = await fetch(`/api/orbital/dispatch/recover/${scopeId}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ from_status: fromStatus }),
+      });
+      if (!res.ok) {
+        const body = await res.json().catch(() => ({ error: res.statusText }));
+        console.error('[Orbital] Failed to recover scope:', body.error);
+        return;
+      }
+      removeFromAbandoned(scopeId);
+    } catch (err) {
+      console.error('[Orbital] Failed to recover scope:', err);
+    }
+  }, [removeFromAbandoned]);
+
+  const dismissAbandoned = useCallback(async (scopeId: number) => {
+    try {
+      const res = await fetch(`/api/orbital/dispatch/dismiss-abandoned/${scopeId}`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+      });
+      if (!res.ok) {
+        const body = await res.json().catch(() => ({ error: res.statusText }));
+        console.error('[Orbital] Failed to dismiss abandoned scope:', body.error);
+        return;
+      }
+      removeFromAbandoned(scopeId);
+    } catch (err) {
+      console.error('[Orbital] Failed to dismiss abandoned scope:', err);
+    }
+  }, [removeFromAbandoned]);
+
+  useEffect(() => {
+    mountedRef.current = true;
+    fetchActiveScopes();
+    return () => { mountedRef.current = false; };
+  }, [fetchActiveScopes]);
+
+  useEffect(() => {
+    function onNewEvent(event: OrbitalEvent) {
+      if (event.type !== 'DISPATCH' || event.data.resolved != null) return;
+
+      // Collect scope IDs: single dispatch uses event.scope_id, batch uses data.scope_ids
+      const ids: number[] = [];
+      if (event.scope_id != null) ids.push(event.scope_id);
+      if (Array.isArray(event.data.scope_ids)) {
+        for (const id of event.data.scope_ids as number[]) {
+          if (!ids.includes(id)) ids.push(id);
+        }
+      }
+      if (ids.length === 0) return;
+
+      setActiveScopes((prev) => {
+        const toAdd = ids.filter(id => !prev.has(id));
+        if (toAdd.length === 0) return prev;
+        const next = new Set(prev);
+        for (const id of toAdd) next.add(id);
+        return next;
+      });
+      for (const id of ids) removeFromAbandoned(id);
+    }
+
+    function onDispatchResolved(payload: DispatchResolvedPayload) {
+      // Collect all scope IDs: single dispatch + batch scope_ids
+      const ids: number[] = [];
+      if (payload.scope_id != null) ids.push(payload.scope_id);
+      if (Array.isArray(payload.scope_ids)) ids.push(...payload.scope_ids);
+      if (ids.length === 0) return;
+
+      setActiveScopes((prev) => {
+        const toRemove = ids.filter(id => prev.has(id));
+        if (toRemove.length === 0) return prev;
+        const next = new Set(prev);
+        for (const id of toRemove) next.delete(id);
+        return next;
+      });
+
+      if (payload.outcome === 'abandoned') {
+        fetchActiveScopes();
+      } else {
+        for (const id of ids) removeFromAbandoned(id);
+      }
+    }
+
+    function onScopeUpdated(scope: Scope) {
+      if (terminalStatuses.has(scope.status)) {
+        const scopeId = scope.id;
+        setActiveScopes((prev) => {
+          if (!prev.has(scopeId)) return prev;
+          const next = new Set(prev);
+          next.delete(scopeId);
+          return next;
+        });
+        // Terminal state clears abandoned
+        removeFromAbandoned(scopeId);
+      }
+    }
+
+    function onReconnect() {
+      fetchActiveScopes();
+    }
+
+    socket.on('event:new', onNewEvent);
+    socket.on('dispatch:resolved', onDispatchResolved);
+    socket.on('scope:updated', onScopeUpdated);
+    socket.on('connect', onReconnect);
+
+    return () => {
+      socket.off('event:new', onNewEvent);
+      socket.off('dispatch:resolved', onDispatchResolved);
+      socket.off('scope:updated', onScopeUpdated);
+      socket.off('connect', onReconnect);
+    };
+  }, [fetchActiveScopes, removeFromAbandoned, terminalStatuses]);
+
+  return { activeScopes, abandonedScopes, recoverScope, dismissAbandoned };
+}
+
+/** Consumer hook — use in ScopeCard to check dispatch state */
+export function useActiveDispatches(): ActiveDispatchContextValue {
+  return useContext(ActiveDispatchContext);
+}

package/src/hooks/useBoardSettings.ts

@@ -0,0 +1,170 @@
+import { useState, useCallback, useEffect } from 'react';
+import type { Scope } from '@/types';
+import { EFFORT_BUCKETS } from '@/types';
+
+// ─── Types ─────────────────────────────────────────────────
+export type SortField = 'id' | 'priority' | 'effort' | 'updated_at' | 'created_at' | 'title';
+export type SortDirection = 'asc' | 'desc';
+
+export interface BoardSettings {
+  sortField: SortField;
+  sortDirection: SortDirection;
+  collapsed: Set<string>;
+}
+
+// ─── Constants ─────────────────────────────────────────────
+const SORT_KEY = 'cc-board-sort';
+const COLLAPSE_KEY = 'cc-board-collapsed';
+
+const DEFAULT_SORT_DIRECTIONS: Record<SortField, SortDirection> = {
+  id: 'asc',
+  priority: 'asc',
+  effort: 'asc',
+  updated_at: 'desc',
+  created_at: 'desc',
+  title: 'asc',
+};
+
+const PRIORITY_ORDER: Record<string, number> = {
+  critical: 0,
+  high: 1,
+  medium: 2,
+  low: 3,
+};
+
+function effortRank(raw: string | null): number {
+  if (!raw) return Infinity;
+  const idx = EFFORT_BUCKETS.indexOf(raw as typeof EFFORT_BUCKETS[number]);
+  return idx >= 0 ? idx : Infinity;
+}
+
+// ─── localStorage helpers ──────────────────────────────────
+function readSort(): { field: SortField; direction: SortDirection } {
+  try {
+    const raw = localStorage.getItem(SORT_KEY);
+    if (raw) {
+      const parsed = JSON.parse(raw) as { field: string; direction: string };
+      if (parsed.field in DEFAULT_SORT_DIRECTIONS) {
+        return {
+          field: parsed.field as SortField,
+          direction: parsed.direction === 'desc' ? 'desc' : 'asc',
+        };
+      }
+    }
+  } catch { /* use defaults */ }
+  return { field: 'id', direction: 'asc' };
+}
+
+function readCollapsed(): Set<string> {
+  try {
+    const raw = localStorage.getItem(COLLAPSE_KEY);
+    if (raw) {
+      const arr = JSON.parse(raw) as string[];
+      if (Array.isArray(arr)) return new Set(arr);
+    }
+  } catch { /* use defaults */ }
+  return new Set();
+}
+
+function persistSort(field: SortField, direction: SortDirection) {
+  try { localStorage.setItem(SORT_KEY, JSON.stringify({ field, direction })); } catch { /* noop */ }
+}
+
+function persistCollapsed(collapsed: Set<string>) {
+  try { localStorage.setItem(COLLAPSE_KEY, JSON.stringify([...collapsed])); } catch { /* noop */ }
+}
+
+// ─── Sort comparator ───────────────────────────────────────
+export function sortScopes(scopes: Scope[], field: SortField, direction: SortDirection): Scope[] {
+  const sorted = [...scopes].sort((a, b) => {
+    const cmp = compareByField(a, b, field);
+    return direction === 'desc' ? -cmp : cmp;
+  });
+  return sorted;
+}
+
+function compareByField(a: Scope, b: Scope, field: SortField): number {
+  switch (field) {
+    case 'id':
+      return a.id - b.id;
+
+    case 'priority': {
+      const pa = a.priority ? (PRIORITY_ORDER[a.priority] ?? Infinity) : Infinity;
+      const pb = b.priority ? (PRIORITY_ORDER[b.priority] ?? Infinity) : Infinity;
+      return pa - pb;
+    }
+
+    case 'effort':
+      return effortRank(a.effort_estimate) - effortRank(b.effort_estimate);
+
+    case 'updated_at': {
+      const ua = a.updated_at ? new Date(a.updated_at).getTime() : 0;
+      const ub = b.updated_at ? new Date(b.updated_at).getTime() : 0;
+      return ua - ub;
+    }
+
+    case 'created_at': {
+      const ca = a.created_at ? new Date(a.created_at).getTime() : 0;
+      const cb = b.created_at ? new Date(b.created_at).getTime() : 0;
+      return ca - cb;
+    }
+
+    case 'title':
+      return a.title.localeCompare(b.title);
+
+    default:
+      return 0;
+  }
+}
+
+// ─── Hook ──────────────────────────────────────────────────
+export function useBoardSettings() {
+  const [sortField, setSortField] = useState<SortField>(() => readSort().field);
+  const [sortDirection, setSortDirection] = useState<SortDirection>(() => readSort().direction);
+  const [collapsed, setCollapsed] = useState<Set<string>>(readCollapsed);
+
+  // Cross-tab sync
+  useEffect(() => {
+    function onStorage(e: StorageEvent) {
+      if (e.key === SORT_KEY) {
+        const s = readSort();
+        setSortField(s.field);
+        setSortDirection(s.direction);
+      }
+      if (e.key === COLLAPSE_KEY) {
+        setCollapsed(readCollapsed());
+      }
+    }
+    window.addEventListener('storage', onStorage);
+    return () => window.removeEventListener('storage', onStorage);
+  }, []);
+
+  const setSort = useCallback((field: SortField) => {
+    setSortField((prevField) => {
+      setSortDirection((prevDir) => {
+        // Same field → toggle direction; different field → default direction
+        const nextDir = prevField === field
+          ? (prevDir === 'asc' ? 'desc' : 'asc')
+          : DEFAULT_SORT_DIRECTIONS[field];
+        persistSort(field, nextDir);
+        return nextDir;
+      });
+      return field;
+    });
+  }, []);
+
+  const toggleCollapse = useCallback((columnId: string) => {
+    setCollapsed((prev) => {
+      const next = new Set(prev);
+      if (next.has(columnId)) {
+        next.delete(columnId);
+      } else {
+        next.add(columnId);
+      }
+      persistCollapsed(next);
+      return next;
+    });
+  }, []);
+
+  return { sortField, sortDirection, setSort, collapsed, toggleCollapse } as const;
+}