@runfusion/fusion 0.22.0 → 0.24.0

package/dist/plugins/fusion-plugin-roadmap/src/dashboard/useRoadmaps.ts

@@ -0,0 +1,1188 @@
+import { useState, useEffect, useCallback, useRef } from "react";
+import type {
+  Roadmap,
+  RoadmapMilestone,
+  RoadmapFeature,
+  RoadmapCreateInput,
+  RoadmapUpdateInput,
+  RoadmapMilestoneCreateInput,
+  RoadmapMilestoneUpdateInput,
+  RoadmapFeatureCreateInput,
+  RoadmapFeatureUpdateInput,
+  RoadmapWithHierarchy,
+  RoadmapMissionPlanningHandoff,
+  RoadmapFeatureTaskPlanningHandoff,
+} from "../roadmap-types.js";
+import * as api from "./api.js";
+
+/**
+ * A suggested milestone from AI generation with a stable local draft ID.
+ * Draft IDs enable stable identity when drafts are reordered or edited.
+ * Drafts are ephemeral and NOT persisted until explicit acceptance.
+ */
+export interface MilestoneSuggestion {
+  /** Stable local draft ID for UI binding and identity */
+  id: string;
+  title: string;
+  description?: string;
+}
+
+/**
+ * A suggested feature from AI generation with a stable local draft ID.
+ * Draft IDs enable stable identity when drafts are reordered or edited.
+ * Drafts are ephemeral and NOT persisted until explicit acceptance.
+ */
+export interface FeatureSuggestion {
+  /** Stable local draft ID for UI binding and identity */
+  id: string;
+  title: string;
+  description?: string;
+}
+
+/** Patch type for updating a suggestion draft */
+export type SuggestionDraftPatch = {
+  title?: string;
+  description?: string;
+};
+
+export interface UseRoadmapsOptions {
+  /** When provided, fetches roadmaps for this project */
+  projectId?: string;
+}
+
+export interface UseRoadmapsResult {
+  /** All roadmaps for the current project */
+  roadmaps: Roadmap[];
+  /** Currently selected roadmap ID */
+  selectedRoadmapId: string | null;
+  /** Selected roadmap with full hierarchy (milestones and features) */
+  selectedRoadmap: RoadmapWithHierarchy | null;
+  /** Milestones for the selected roadmap */
+  milestones: RoadmapMilestone[];
+  /** Features by milestone ID */
+  featuresByMilestoneId: Record<string, RoadmapFeature[]>;
+  /** Loading state */
+  loading: boolean;
+  /** Error state */
+  error: Error | null;
+
+  // Roadmap CRUD callbacks
+  /** Create a new roadmap */
+  createRoadmap: (input: RoadmapCreateInput, opts?: { onSuccess?: () => void; onError?: (err: Error) => void }) => Promise<void>;
+  /** Update a roadmap */
+  updateRoadmap: (roadmapId: string, updates: RoadmapUpdateInput, opts?: { onSuccess?: () => void; onError?: (err: Error) => void }) => Promise<void>;
+  /** Delete a roadmap */
+  deleteRoadmap: (roadmapId: string, opts?: { onSuccess?: () => void; onError?: (err: Error) => void }) => Promise<void>;
+  /** Select a roadmap to view its details */
+  selectRoadmap: (roadmapId: string | null) => void;
+
+  // Milestone CRUD callbacks
+  /** Create a milestone in the selected roadmap */
+  createMilestone: (input: RoadmapMilestoneCreateInput, opts?: { onSuccess?: () => void; onError?: (err: Error) => void }) => Promise<void>;
+  /** Update a milestone */
+  updateMilestone: (milestoneId: string, updates: RoadmapMilestoneUpdateInput, opts?: { onSuccess?: () => void; onError?: (err: Error) => void }) => Promise<void>;
+  /** Delete a milestone */
+  deleteMilestone: (milestoneId: string, opts?: { onSuccess?: () => void; onError?: (err: Error) => void }) => Promise<void>;
+
+  // Milestone ordering callbacks
+  /** Reorder milestones within a roadmap */
+  reorderMilestones: (roadmapId: string, orderedMilestoneIds: string[], opts?: { onSuccess?: () => void; onError?: (err: Error) => void }) => Promise<void>;
+
+  // Feature CRUD callbacks
+  /** Create a feature in a milestone */
+  createFeature: (milestoneId: string, input: RoadmapFeatureCreateInput, opts?: { onSuccess?: () => void; onError?: (err: Error) => void }) => Promise<void>;
+  /** Update a feature */
+  updateFeature: (featureId: string, updates: RoadmapFeatureUpdateInput, opts?: { onSuccess?: () => void; onError?: (err: Error) => void }) => Promise<void>;
+  /** Delete a feature */
+  deleteFeature: (featureId: string, opts?: { onSuccess?: () => void; onError?: (err: Error) => void }) => Promise<void>;
+
+  // Feature ordering callbacks
+  /** Reorder features within a milestone */
+  reorderFeatures: (milestoneId: string, orderedFeatureIds: string[], opts?: { onSuccess?: () => void; onError?: (err: Error) => void }) => Promise<void>;
+  /** Move a feature to a different milestone or position */
+  moveFeature: (featureId: string, targetMilestoneId: string, targetIndex: number, opts?: { onSuccess?: () => void; onError?: (err: Error) => void }) => Promise<void>;
+
+  // Milestone suggestion callbacks
+  /** Current pending milestone suggestions (ephemeral, in-memory only) */
+  milestoneSuggestions: MilestoneSuggestion[];
+  /** Whether suggestions are currently being generated */
+  isGeneratingSuggestions: boolean;
+  /** Generate milestone suggestions from a goal prompt */
+  generateMilestoneSuggestions: (goalPrompt: string, count?: number, opts?: { onSuccess?: () => void; onError?: (err: Error) => void }) => Promise<void>;
+  /** Update a milestone suggestion draft before acceptance */
+  updateMilestoneSuggestionDraft: (draftId: string, patch: SuggestionDraftPatch) => void;
+  /** Accept a single milestone suggestion and create it as a milestone */
+  acceptMilestoneSuggestion: (draftId: string, opts?: { onSuccess?: () => void; onError?: (err: Error) => void }) => Promise<void>;
+  /** Accept all milestone suggestions and create them as milestones (sequentially, in draft order) */
+  acceptAllMilestoneSuggestions: (opts?: { onSuccess?: () => void; onError?: (err: Error) => void }) => Promise<void>;
+  /** Clear all pending milestone suggestions */
+  clearMilestoneSuggestions: () => void;
+
+  // Feature suggestion callbacks (ephemeral, scoped by milestone)
+  /** Pending feature suggestions by milestone ID (ephemeral, in-memory only) */
+  featureSuggestionsByMilestoneId: Record<string, FeatureSuggestion[]>;
+  /** Whether feature suggestions are being generated for a specific milestone */
+  isGeneratingFeatureSuggestions: (milestoneId: string) => boolean;
+  /** Generate feature suggestions for a specific milestone */
+  generateFeatureSuggestions: (milestoneId: string, input?: { prompt?: string; count?: number }, opts?: { onSuccess?: () => void; onError?: (err: Error) => void }) => Promise<void>;
+  /** Update a feature suggestion draft before acceptance */
+  updateFeatureSuggestionDraft: (milestoneId: string, draftId: string, patch: SuggestionDraftPatch) => void;
+  /** Accept a single feature suggestion and create it as a feature */
+  acceptFeatureSuggestion: (milestoneId: string, draftId: string, opts?: { onSuccess?: () => void; onError?: (err: Error) => void }) => Promise<void>;
+  /** Accept all feature suggestions for a milestone (sequentially, in draft order) */
+  acceptAllFeatureSuggestions: (milestoneId: string, opts?: { onSuccess?: () => void; onError?: (err: Error) => void }) => Promise<void>;
+  /** Clear pending feature suggestions for a specific milestone */
+  clearFeatureSuggestions: (milestoneId: string) => void;
+
+  // Handoff / Export callbacks
+  /** Current handoff payload (mission + feature handoffs) */
+  handoffPayload: { mission: RoadmapMissionPlanningHandoff; features: RoadmapFeatureTaskPlanningHandoff[] } | null;
+  /** Whether handoff is currently being fetched */
+  isFetchingHandoff: boolean;
+  /** Error from the last handoff fetch attempt */
+  handoffError: Error | null;
+  /** Fetch handoff payload for a roadmap */
+  fetchHandoff: (roadmapId: string, opts?: { onSuccess?: () => void; onError?: (err: Error) => void }) => Promise<void>;
+  /** Clear the current handoff payload */
+  clearHandoff: () => void;
+
+  /** Refresh all roadmaps */
+  refresh: () => Promise<void>;
+}
+
+export function useRoadmaps(options?: UseRoadmapsOptions): UseRoadmapsResult {
+  const projectId = options?.projectId;
+  const [roadmaps, setRoadmaps] = useState<Roadmap[]>([]);
+  const [selectedRoadmapId, setSelectedRoadmapId] = useState<string | null>(null);
+  const [selectedRoadmap, setSelectedRoadmap] = useState<RoadmapWithHierarchy | null>(null);
+  const [milestones, setMilestones] = useState<RoadmapMilestone[]>([]);
+  const [featuresByMilestoneId, setFeaturesByMilestoneId] = useState<Record<string, RoadmapFeature[]>>({});
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  // Handoff state
+  const [handoffPayload, setHandoffPayload] = useState<{ mission: RoadmapMissionPlanningHandoff; features: RoadmapFeatureTaskPlanningHandoff[] } | null>(null);
+  const [isFetchingHandoff, setIsFetchingHandoff] = useState(false);
+  const [handoffError, setHandoffError] = useState<Error | null>(null);
+
+  // Ephemeral milestone suggestion state (in-memory only, not persisted)
+  const [milestoneSuggestions, setMilestoneSuggestions] = useState<MilestoneSuggestion[]>([]);
+  const [isGeneratingSuggestions, setIsGeneratingSuggestions] = useState(false);
+
+  // Ephemeral feature suggestion state keyed by milestone ID (in-memory only, not persisted)
+  const [featureSuggestionsByMilestoneId, setFeatureSuggestionsByMilestoneId] = useState<Record<string, FeatureSuggestion[]>>({});
+  const [generatingFeatureSuggestions, setGeneratingFeatureSuggestions] = useState<Record<string, boolean>>({});
+
+  // Refs for feature suggestion state
+  const featureSuggestionsByMilestoneIdRef = useRef(featureSuggestionsByMilestoneId);
+  const generatingFeatureSuggestionsRef = useRef(generatingFeatureSuggestions);
+  const milestoneSuggestionsRef = useRef(milestoneSuggestions);
+
+  featureSuggestionsByMilestoneIdRef.current = featureSuggestionsByMilestoneId;
+  generatingFeatureSuggestionsRef.current = generatingFeatureSuggestions;
+  milestoneSuggestionsRef.current = milestoneSuggestions;
+
+  // Track previous projectId to detect changes
+  const previousProjectIdRef = useRef<string | undefined>(projectId);
+  // Project context version for stale-response protection
+  const projectContextVersionRef = useRef(0);
+  // Handoff fetch version for stale-response discard
+  const handoffFetchVersionRef = useRef(0);
+  // Refs to access latest state in callbacks
+  const roadmapsRef = useRef(roadmaps);
+  const selectedRoadmapIdRef = useRef(selectedRoadmapId);
+  const milestonesRef = useRef(milestones);
+  const featuresByMilestoneIdRef = useRef(featuresByMilestoneId);
+  const projectIdRef = useRef(projectId);
+  const handoffPayloadRef = useRef(handoffPayload);
+
+  roadmapsRef.current = roadmaps;
+  selectedRoadmapIdRef.current = selectedRoadmapId;
+  milestonesRef.current = milestones;
+  featuresByMilestoneIdRef.current = featuresByMilestoneId;
+  projectIdRef.current = projectId;
+  handoffPayloadRef.current = handoffPayload;
+
+  // Clear selection and suggestions when project changes
+  useEffect(() => {
+    if (previousProjectIdRef.current !== projectId) {
+      previousProjectIdRef.current = projectId;
+      projectContextVersionRef.current++;
+      setSelectedRoadmapId(null);
+      setSelectedRoadmap(null);
+      setMilestones([]);
+      setFeaturesByMilestoneId({});
+      // Clear handoff state
+      setHandoffPayload(null);
+      setHandoffError(null);
+      // Clear ephemeral suggestion state
+      setMilestoneSuggestions([]);
+      setIsGeneratingSuggestions(false);
+      setFeatureSuggestionsByMilestoneId({});
+      setGeneratingFeatureSuggestions({});
+    }
+  }, [projectId]);
+
+  // Fetch roadmaps on mount and when projectId changes
+  const fetchRoadmaps = useCallback(async () => {
+    setLoading(true);
+    setError(null);
+    try {
+      const fetchedRoadmaps = await api.fetchRoadmaps(projectId);
+      setRoadmaps(fetchedRoadmaps);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error("Failed to fetch roadmaps"));
+    } finally {
+      setLoading(false);
+    }
+  }, [projectId]);
+
+  // Fetch selected roadmap with full hierarchy
+  const fetchSelectedRoadmap = useCallback(async (roadmapId: string) => {
+    try {
+      const roadmap = await api.fetchRoadmap(roadmapId, projectId);
+      setSelectedRoadmap(roadmap);
+      setMilestones(roadmap.milestones || []);
+
+      // Build features by milestone ID
+      const featuresMap: Record<string, RoadmapFeature[]> = {};
+      for (const milestone of roadmap.milestones || []) {
+        featuresMap[milestone.id] = milestone.features || [];
+      }
+      setFeaturesByMilestoneId(featuresMap);
+    } catch (err) {
+      setError(err instanceof Error ? err : new Error("Failed to fetch roadmap"));
+    }
+  }, [projectId]);
+
+  // Initial fetch
+  useEffect(() => {
+    void fetchRoadmaps();
+  }, [fetchRoadmaps]);
+
+  // Fetch selected roadmap when selection changes
+  useEffect(() => {
+    if (selectedRoadmapId) {
+      void fetchSelectedRoadmap(selectedRoadmapId);
+    } else {
+      setSelectedRoadmap(null);
+      setMilestones([]);
+      setFeaturesByMilestoneId({});
+    }
+  }, [selectedRoadmapId, fetchSelectedRoadmap]);
+
+  // Roadmap CRUD
+  const createRoadmap = useCallback(async (
+    input: RoadmapCreateInput,
+    opts?: { onSuccess?: () => void; onError?: (err: Error) => void }
+  ) => {
+    try {
+      const newRoadmap = await api.createRoadmap(input, projectIdRef.current);
+      setRoadmaps((prev) => [...prev, newRoadmap]);
+      opts?.onSuccess?.();
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error("Failed to create roadmap");
+      opts?.onError?.(error);
+      throw error;
+    }
+  }, []); // No dependencies needed - uses refs
+
+  const updateRoadmap = useCallback(async (
+    roadmapId: string,
+    updates: RoadmapUpdateInput,
+    opts?: { onSuccess?: () => void; onError?: (err: Error) => void }
+  ) => {
+    try {
+      const updated = await api.updateRoadmap(roadmapId, updates, projectIdRef.current);
+      setRoadmaps((prev) => prev.map((r) => (r.id === roadmapId ? updated : r)));
+      if (selectedRoadmapIdRef.current === roadmapId) {
+        setSelectedRoadmap((prev) => prev ? { ...prev, ...updated } : null);
+      }
+      opts?.onSuccess?.();
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error("Failed to update roadmap");
+      opts?.onError?.(error);
+      throw error;
+    }
+  }, []); // No dependencies needed - uses refs
+
+  const deleteRoadmap = useCallback(async (
+    roadmapId: string,
+    opts?: { onSuccess?: () => void; onError?: (err: Error) => void }
+  ) => {
+    try {
+      await api.deleteRoadmap(roadmapId, projectIdRef.current);
+      setRoadmaps((prev) => prev.filter((r) => r.id !== roadmapId));
+      if (selectedRoadmapIdRef.current === roadmapId) {
+        setSelectedRoadmapId(null);
+        setSelectedRoadmap(null);
+        setMilestones([]);
+        setFeaturesByMilestoneId({});
+      }
+      opts?.onSuccess?.();
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error("Failed to delete roadmap");
+      opts?.onError?.(error);
+      throw error;
+    }
+  }, []); // No dependencies needed - uses refs
+
+  const selectRoadmap = useCallback((roadmapId: string | null) => {
+    setSelectedRoadmapId(roadmapId);
+  }, []);
+
+  // Milestone CRUD
+  const createMilestone = useCallback(async (
+    input: RoadmapMilestoneCreateInput,
+    opts?: { onSuccess?: () => void; onError?: (err: Error) => void }
+  ) => {
+    const currentRoadmapId = selectedRoadmapIdRef.current;
+    if (!currentRoadmapId) {
+      const error = new Error("No roadmap selected");
+      opts?.onError?.(error);
+      throw error;
+    }
+    try {
+      const newMilestone = await api.createRoadmapMilestone(currentRoadmapId, input, projectIdRef.current);
+      setMilestones((prev) => [...prev, newMilestone]);
+      setFeaturesByMilestoneId((prev) => ({ ...prev, [newMilestone.id]: [] }));
+      // Refresh the full roadmap to get updated hierarchy
+      if (selectedRoadmapIdRef.current) {
+        void fetchSelectedRoadmap(selectedRoadmapIdRef.current);
+      }
+      opts?.onSuccess?.();
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error("Failed to create milestone");
+      opts?.onError?.(error);
+      throw error;
+    }
+  }, [fetchSelectedRoadmap]);
+
+  const updateMilestone = useCallback(async (
+    milestoneId: string,
+    updates: RoadmapMilestoneUpdateInput,
+    opts?: { onSuccess?: () => void; onError?: (err: Error) => void }
+  ) => {
+    try {
+      const updated = await api.updateRoadmapMilestone(milestoneId, updates, projectIdRef.current);
+      setMilestones((prev) => prev.map((m) => (m.id === milestoneId ? updated : m)));
+      if (selectedRoadmapIdRef.current) {
+        void fetchSelectedRoadmap(selectedRoadmapIdRef.current);
+      }
+      opts?.onSuccess?.();
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error("Failed to update milestone");
+      opts?.onError?.(error);
+      throw error;
+    }
+  }, [fetchSelectedRoadmap]); // Uses refs internally
+
+  const deleteMilestone = useCallback(async (
+    milestoneId: string,
+    opts?: { onSuccess?: () => void; onError?: (err: Error) => void }
+  ) => {
+    try {
+      await api.deleteRoadmapMilestone(milestoneId, projectIdRef.current);
+      setMilestones((prev) => prev.filter((m) => m.id !== milestoneId));
+      setFeaturesByMilestoneId((prev) => {
+        const updated = { ...prev };
+        delete updated[milestoneId];
+        return updated;
+      });
+      if (selectedRoadmapIdRef.current) {
+        void fetchSelectedRoadmap(selectedRoadmapIdRef.current);
+      }
+      opts?.onSuccess?.();
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error("Failed to delete milestone");
+      opts?.onError?.(error);
+      throw error;
+    }
+  }, [fetchSelectedRoadmap]); // Uses refs internally
+
+  // Feature CRUD
+  const createFeature = useCallback(async (
+    milestoneId: string,
+    input: RoadmapFeatureCreateInput,
+    opts?: { onSuccess?: () => void; onError?: (err: Error) => void }
+  ) => {
+    try {
+      const newFeature = await api.createRoadmapFeature(milestoneId, input, projectIdRef.current);
+      setFeaturesByMilestoneId((prev) => ({
+        ...prev,
+        [milestoneId]: [...(prev[milestoneId] || []), newFeature],
+      }));
+      if (selectedRoadmapIdRef.current) {
+        void fetchSelectedRoadmap(selectedRoadmapIdRef.current);
+      }
+      opts?.onSuccess?.();
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error("Failed to create feature");
+      opts?.onError?.(error);
+      throw error;
+    }
+  }, [fetchSelectedRoadmap]); // Uses refs internally
+
+  const updateFeature = useCallback(async (
+    featureId: string,
+    updates: RoadmapFeatureUpdateInput,
+    opts?: { onSuccess?: () => void; onError?: (err: Error) => void }
+  ) => {
+    try {
+      const updated = await api.updateRoadmapFeature(featureId, updates, projectIdRef.current);
+      setFeaturesByMilestoneId((prev) => {
+        const updatedMap: Record<string, RoadmapFeature[]> = {};
+        for (const [milestoneId, features] of Object.entries(prev)) {
+          updatedMap[milestoneId] = features.map((f) => (f.id === featureId ? updated : f));
+        }
+        return updatedMap;
+      });
+      if (selectedRoadmapIdRef.current) {
+        void fetchSelectedRoadmap(selectedRoadmapIdRef.current);
+      }
+      opts?.onSuccess?.();
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error("Failed to update feature");
+      opts?.onError?.(error);
+      throw error;
+    }
+  }, [fetchSelectedRoadmap]); // Uses refs internally
+
+  const deleteFeature = useCallback(async (
+    featureId: string,
+    opts?: { onSuccess?: () => void; onError?: (err: Error) => void }
+  ) => {
+    try {
+      await api.deleteRoadmapFeature(featureId, projectIdRef.current);
+      setFeaturesByMilestoneId((prev) => {
+        const updatedMap: Record<string, RoadmapFeature[]> = {};
+        for (const [milestoneId, features] of Object.entries(prev)) {
+          updatedMap[milestoneId] = features.filter((f) => f.id !== featureId);
+        }
+        return updatedMap;
+      });
+      if (selectedRoadmapIdRef.current) {
+        void fetchSelectedRoadmap(selectedRoadmapIdRef.current);
+      }
+      opts?.onSuccess?.();
+    } catch (err) {
+      const error = err instanceof Error ? err : new Error("Failed to delete feature");
+      opts?.onError?.(error);
+      throw error;
+    }
+  }, [fetchSelectedRoadmap]); // Uses refs internally
+
+  // Milestone ordering
+  const reorderMilestones = useCallback(async (
+    roadmapId: string,
+    orderedMilestoneIds: string[],
+    opts?: { onSuccess?: () => void; onError?: (err: Error) => void }
+  ) => {
+    // Save snapshot for rollback
+    const snapshot = milestonesRef.current;
+
+    // Optimistic update
+    const reordered = orderedMilestoneIds
+      .map((id) => snapshot.find((m) => m.id === id))
+      .filter((m): m is RoadmapMilestone => m !== undefined)
+      .map((m, index) => ({ ...m, orderIndex: index }));
+
+    setMilestones(reordered);
+
+    try {
+      await api.reorderRoadmapMilestones(roadmapId, orderedMilestoneIds, projectIdRef.current);
+      // Refresh to get server state
+      if (selectedRoadmapIdRef.current) {
+        void fetchSelectedRoadmap(selectedRoadmapIdRef.current);
+      }
+      opts?.onSuccess?.();
+    } catch (err) {
+      // Rollback to snapshot
+      setMilestones(snapshot);
+      const error = err instanceof Error ? err : new Error("Failed to reorder milestones");
+      opts?.onError?.(error);
+      throw error;
+    }
+  }, [fetchSelectedRoadmap]); // Uses refs internally
+
+  // Feature ordering
+  const reorderFeatures = useCallback(async (
+    milestoneId: string,
+    orderedFeatureIds: string[],
+    opts?: { onSuccess?: () => void; onError?: (err: Error) => void }
+  ) => {
+    // No-op suppression: if IDs are already in the same order, skip API call
+    const currentFeatures = featuresByMilestoneIdRef.current[milestoneId] || [];
+    const currentIds = currentFeatures.map((f) => f.id);
+    if (JSON.stringify(currentIds) === JSON.stringify(orderedFeatureIds)) {
+      opts?.onSuccess?.();
+      return;
+    }
+
+    // Save snapshot for rollback
+    const snapshot = featuresByMilestoneIdRef.current;
+
+    // Optimistic update
+    const reordered = orderedFeatureIds
+      .map((id) => currentFeatures.find((f) => f.id === id))
+      .filter((f): f is RoadmapFeature => f !== undefined)
+      .map((f, index) => ({ ...f, orderIndex: index }));
+
+    setFeaturesByMilestoneId((prev) => ({
+      ...prev,
+      [milestoneId]: reordered,
+    }));
+
+    try {
+      await api.reorderRoadmapFeatures(milestoneId, orderedFeatureIds, projectIdRef.current);
+      // Refresh to get server state
+      if (selectedRoadmapIdRef.current) {
+        void fetchSelectedRoadmap(selectedRoadmapIdRef.current);
+      }
+      opts?.onSuccess?.();
+    } catch (err) {
+      // Rollback to snapshot
+      setFeaturesByMilestoneId(snapshot);
+      const error = err instanceof Error ? err : new Error("Failed to reorder features");
+      opts?.onError?.(error);
+      throw error;
+    }
+  }, [fetchSelectedRoadmap]); // Uses refs internally
+
+  const moveFeature = useCallback(async (
+    featureId: string,
+    targetMilestoneId: string,
+    targetIndex: number,
+    opts?: { onSuccess?: () => void; onError?: (err: Error) => void }
+  ) => {
+    // Save snapshot for rollback
+    const snapshot = featuresByMilestoneIdRef.current;
+
+    // Find which milestone the feature is currently in
+    let sourceMilestoneId: string | null = null;
+    for (const [milestoneId, features] of Object.entries(snapshot)) {
+      if (features.some((f) => f.id === featureId)) {
+        sourceMilestoneId = milestoneId;
+        break;
+      }
+    }
+
+    if (!sourceMilestoneId) {
+      const error = new Error("Feature not found");
+      opts?.onError?.(error);
+      throw error;
+    }
+
+    // No-op suppression: if already at target position in same milestone, skip
+    if (sourceMilestoneId === targetMilestoneId) {
+      const currentFeatures = snapshot[sourceMilestoneId] || [];
+      const clampedIndex = Math.max(0, Math.min(targetIndex, currentFeatures.length - 1));
+      const currentIndex = currentFeatures.findIndex((f) => f.id === featureId);
+      if (currentIndex === clampedIndex) {
+        opts?.onSuccess?.();
+        return;
+      }
+    }
+
+    // Optimistic update
+    const sourceFeatures = snapshot[sourceMilestoneId] || [];
+    const targetFeatures = snapshot[targetMilestoneId] || [];
+    const feature = sourceFeatures.find((f) => f.id === featureId);
+
+    if (!feature) {
+      const error = new Error("Feature not found");
+      opts?.onError?.(error);
+      throw error;
+    }
+
+    // Remove from source
+    const newSourceFeatures = sourceFeatures
+      .filter((f) => f.id !== featureId)
+      .map((f, index) => ({ ...f, orderIndex: index }));
+
+    // Add to target at correct position
+    const updatedFeature = { ...feature, milestoneId: targetMilestoneId, orderIndex: targetIndex };
+    const newTargetFeatures = [...targetFeatures];
+    newTargetFeatures.splice(targetIndex, 0, updatedFeature);
+    // Renormalize target
+    const normalizedTargetFeatures = newTargetFeatures.map((f, index) => ({ ...f, orderIndex: index }));
+
+    // If moving within same milestone, update source with the new order
+    if (sourceMilestoneId === targetMilestoneId) {
+      setFeaturesByMilestoneId((prev) => ({
+        ...prev,
+        [sourceMilestoneId]: normalizedTargetFeatures,
+      }));
+    } else {
+      // Renormalize source after removal
+      setFeaturesByMilestoneId((prev) => ({
+        ...prev,
+        [sourceMilestoneId]: newSourceFeatures,
+        [targetMilestoneId]: normalizedTargetFeatures,
+      }));
+    }
+
+    try {
+      await api.moveRoadmapFeature(featureId, targetMilestoneId, targetIndex, projectId);
+      // Refresh to get server state
+      if (selectedRoadmapIdRef.current) {
+        void fetchSelectedRoadmap(selectedRoadmapIdRef.current);
+      }
+      opts?.onSuccess?.();
+    } catch (err) {
+      // Rollback to snapshot
+      setFeaturesByMilestoneId(snapshot);
+      const error = err instanceof Error ? err : new Error("Failed to move feature");
+      opts?.onError?.(error);
+      throw error;
+    }
+  }, [fetchSelectedRoadmap, projectId]);
+
+  // ── Milestone Suggestion Actions (Ephemeral) ───────────────────────────────────
+
+  /**
+   * Generate a stable draft ID for suggestions.
+   * Uses crypto.randomUUID() for browser environments with a counter fallback.
+   */
+  function generateDraftId(): string {
+    if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+      return crypto.randomUUID();
+    }
+    // Fallback for environments without crypto.randomUUID
+    return `draft-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
+  }
+
+  const generateMilestoneSuggestions = useCallback(async (
+    goalPrompt: string,
+    count: number = 5,
+    opts?: { onSuccess?: () => void; onError?: (err: Error) => void }
+  ) => {
+    const currentRoadmapId = selectedRoadmapIdRef.current;
+    if (!currentRoadmapId) {
+      const error = new Error("No roadmap selected");
+      opts?.onError?.(error);
+      throw error;
+    }
+
+    // Capture project context version for stale-response protection
+    const contextVersionAtStart = projectContextVersionRef.current;
+    const requestProjectId = projectIdRef.current;
+
+    setIsGeneratingSuggestions(true);
+
+    try {
+      const response = await api.generateMilestoneSuggestions(
+        currentRoadmapId,
+        goalPrompt,
+        count,
+        requestProjectId
+      );
+
+      // Check for stale response
+      if (projectContextVersionRef.current !== contextVersionAtStart) {
+        // Project context changed during fetch - discard response
+        return;
+      }
+
+      // Assign stable draft IDs to suggestions for UI binding and identity
+      const suggestionsWithIds: MilestoneSuggestion[] = response.suggestions.map((s) => ({
+        id: generateDraftId(),
+        title: s.title,
+        description: s.description,
+      }));
+      setMilestoneSuggestions(suggestionsWithIds);
+      opts?.onSuccess?.();
+    } catch (err) {
+      // Check for stale response
+      if (projectContextVersionRef.current !== contextVersionAtStart) {
+        // Project context changed during fetch - discard error
+        return;
+      }
+
+      const error = err instanceof Error ? err : new Error("Failed to generate suggestions");
+      opts?.onError?.(error);
+      throw error;
+    } finally {
+      // Only clear loading state if context hasn't changed
+      if (projectContextVersionRef.current === contextVersionAtStart) {
+        setIsGeneratingSuggestions(false);
+      }
+    }
+  }, []);
+
+  const updateMilestoneSuggestionDraft = useCallback((draftId: string, patch: SuggestionDraftPatch) => {
+    // Update ref first for immediate visibility to acceptAll
+    const currentSuggestions = milestoneSuggestionsRef.current;
+    const updatedSuggestions = currentSuggestions.map((s) => (s.id === draftId ? { ...s, ...patch } : s));
+    milestoneSuggestionsRef.current = updatedSuggestions;
+    // Then update state for re-render
+    setMilestoneSuggestions((prev) =>
+      prev.map((s) => (s.id === draftId ? { ...s, ...patch } : s))
+    );
+  }, []);
+
+  const acceptMilestoneSuggestion = useCallback(async (
+    draftId: string,
+    opts?: { onSuccess?: () => void; onError?: (err: Error) => void }
+  ) => {
+    const currentRoadmapId = selectedRoadmapIdRef.current;
+    if (!currentRoadmapId) {
+      const error = new Error("No roadmap selected");
+      opts?.onError?.(error);
+      throw error;
+    }
+
+    // Capture state for stale-response protection
+    const contextVersionAtStart = projectContextVersionRef.current;
+    const currentSuggestions = milestoneSuggestionsRef.current;
+
+    // Find the suggestion by draft ID
+    const index = currentSuggestions.findIndex((s) => s.id === draftId);
+    if (index === -1) {
+      const error = new Error("Suggestion draft not found");
+      opts?.onError?.(error);
+      throw error;
+    }
+
+    const suggestion = currentSuggestions[index];
+
+    // Validate: title must not be empty/whitespace-only
+    if (!suggestion.title.trim()) {
+      const error = new Error("Title cannot be empty");
+      opts?.onError?.(error);
+      throw error;
+    }
+
+    // Optimistic update: remove from suggestions immediately
+    setMilestoneSuggestions((prev) => prev.filter((s) => s.id !== draftId));
+
+    try {
+      await api.createRoadmapMilestone(
+        currentRoadmapId,
+        { title: suggestion.title, description: suggestion.description },
+        projectIdRef.current
+      );
+
+      // Check for stale response
+      if (projectContextVersionRef.current !== contextVersionAtStart) {
+        // Project context changed - re-add to suggestions (optimistic rollback)
+        setMilestoneSuggestions((prev) => {
+          const updated = [...prev];
+          updated.splice(index, 0, suggestion);
+          return updated;
+        });
+        return;
+      }
+
+      // Refresh the roadmap to get the new milestone
+      if (selectedRoadmapIdRef.current) {
+        void fetchSelectedRoadmap(selectedRoadmapIdRef.current);
+      }
+
+      opts?.onSuccess?.();
+    } catch (err) {
+      // Rollback: re-add to suggestions
+      setMilestoneSuggestions((prev) => {
+        const updated = [...prev];
+        updated.splice(index, 0, suggestion);
+        return updated;
+      });
+
+      const error = err instanceof Error ? err : new Error("Failed to accept suggestion");
+      opts?.onError?.(error);
+      throw error;
+    }
+  }, [fetchSelectedRoadmap]);
+
+  const acceptAllMilestoneSuggestions = useCallback(async (
+    opts?: { onSuccess?: () => void; onError?: (err: Error) => void }
+  ) => {
+    const currentRoadmapId = selectedRoadmapIdRef.current;
+    if (!currentRoadmapId) {
+      const error = new Error("No roadmap selected");
+      opts?.onError?.(error);
+      throw error;
+    }
+
+    // Read from ref - it's updated synchronously by updateMilestoneSuggestionDraft
+    const suggestionsToAccept = [...milestoneSuggestionsRef.current];
+    if (suggestionsToAccept.length === 0) {
+      return;
+    }
+
+    // Validate all titles before accepting any
+    const emptyTitleIndex = suggestionsToAccept.findIndex((s) => !s.title.trim());
+    if (emptyTitleIndex !== -1) {
+      const error = new Error(`Title cannot be empty at position ${emptyTitleIndex + 1}`);
+      opts?.onError?.(error);
+      throw error;
+    }
+
+    // Clear suggestions immediately (optimistic)
+    setMilestoneSuggestions([]);
+
+    // Capture state for stale-response protection
+    const contextVersionAtStart = projectContextVersionRef.current;
+
+    // Accept sequentially to preserve order
+    for (let i = 0; i < suggestionsToAccept.length; i++) {
+      // Check for stale response
+      if (projectContextVersionRef.current !== contextVersionAtStart) {
+        // Project context changed - stop accepting
+        break;
+      }
+
+      const suggestion = suggestionsToAccept[i];
+
+      try {
+        await api.createRoadmapMilestone(
+          currentRoadmapId,
+          { title: suggestion.title, description: suggestion.description },
+          projectIdRef.current
+        );
+      } catch (err) {
+        // On error, stop accepting and report
+        const error = err instanceof Error ? err : new Error("Failed to accept all suggestions");
+        opts?.onError?.(error);
+        throw error;
+      }
+    }
+
+    // Check for stale response
+    if (projectContextVersionRef.current !== contextVersionAtStart) {
+      return;
+    }
+
+    // Refresh the roadmap to get all new milestones
+    if (selectedRoadmapIdRef.current) {
+      void fetchSelectedRoadmap(selectedRoadmapIdRef.current);
+    }
+
+    opts?.onSuccess?.();
+  }, [fetchSelectedRoadmap]);
+
+  // ── Feature Suggestion Actions (Ephemeral, Milestone-Scoped) ───────────────────────────────────
+
+  const isGeneratingFeatureSuggestions = useCallback((milestoneId: string): boolean => {
+    return generatingFeatureSuggestionsRef.current[milestoneId] ?? false;
+  }, []);
+
+  const generateFeatureSuggestions = useCallback(async (
+    milestoneId: string,
+    input?: { prompt?: string; count?: number },
+    opts?: { onSuccess?: () => void; onError?: (err: Error) => void }
+  ) => {
+    // Capture project context version for stale-response protection
+    const contextVersionAtStart = projectContextVersionRef.current;
+    const requestProjectId = projectIdRef.current;
+
+    // Set loading state for this milestone
+    setGeneratingFeatureSuggestions((prev) => ({ ...prev, [milestoneId]: true }));
+
+    try {
+      const response = await api.generateFeatureSuggestions(
+        milestoneId,
+        input,
+        requestProjectId
+      );
+
+      // Check for stale response
+      if (projectContextVersionRef.current !== contextVersionAtStart) {
+        // Project context changed during fetch - discard response
+        return;
+      }
+
+      // Assign stable draft IDs to suggestions for UI binding and identity
+      const suggestionsWithIds: FeatureSuggestion[] = response.suggestions.map((s) => ({
+        id: generateDraftId(),
+        title: s.title,
+        description: s.description,
+      }));
+      setFeatureSuggestionsByMilestoneId((prev) => ({
+        ...prev,
+        [milestoneId]: suggestionsWithIds,
+      }));
+      opts?.onSuccess?.();
+    } catch (err) {
+      // Check for stale response
+      if (projectContextVersionRef.current !== contextVersionAtStart) {
+        // Project context changed during fetch - discard error
+        return;
+      }
+
+      const error = err instanceof Error ? err : new Error("Failed to generate feature suggestions");
+      opts?.onError?.(error);
+      throw error;
+    } finally {
+      // Only clear loading state if context hasn't changed
+      if (projectContextVersionRef.current === contextVersionAtStart) {
+        setGeneratingFeatureSuggestions((prev) => ({ ...prev, [milestoneId]: false }));
+      }
+    }
+  }, []);
+
+  const updateFeatureSuggestionDraft = useCallback((milestoneId: string, draftId: string, patch: SuggestionDraftPatch) => {
+    // Update ref first for immediate visibility to acceptAll
+    const currentSuggestions = featureSuggestionsByMilestoneIdRef.current[milestoneId] || [];
+    const updatedSuggestions = currentSuggestions.map((s) => (s.id === draftId ? { ...s, ...patch } : s));
+    featureSuggestionsByMilestoneIdRef.current = {
+      ...featureSuggestionsByMilestoneIdRef.current,
+      [milestoneId]: updatedSuggestions,
+    };
+    // Then update state for re-render
+    setFeatureSuggestionsByMilestoneId((prev) => ({
+      ...prev,
+      [milestoneId]: prev[milestoneId]?.map((s) => (s.id === draftId ? { ...s, ...patch } : s)) || [],
+    }));
+  }, []);
+
+  const acceptFeatureSuggestion = useCallback(async (
+    milestoneId: string,
+    draftId: string,
+    opts?: { onSuccess?: () => void; onError?: (err: Error) => void }
+  ) => {
+    // Capture state for stale-response protection
+    const contextVersionAtStart = projectContextVersionRef.current;
+    const currentSuggestions = featureSuggestionsByMilestoneIdRef.current[milestoneId] || [];
+
+    // Find the suggestion by draft ID
+    const index = currentSuggestions.findIndex((s) => s.id === draftId);
+    if (index === -1) {
+      const error = new Error("Suggestion draft not found");
+      opts?.onError?.(error);
+      throw error;
+    }
+
+    const suggestion = currentSuggestions[index];
+
+    // Validate: title must not be empty/whitespace-only
+    if (!suggestion.title.trim()) {
+      const error = new Error("Title cannot be empty");
+      opts?.onError?.(error);
+      throw error;
+    }
+
+    // Optimistic update: remove from suggestions immediately
+    setFeatureSuggestionsByMilestoneId((prev) => ({
+      ...prev,
+      [milestoneId]: prev[milestoneId]?.filter((s) => s.id !== draftId) || [],
+    }));
+
+    try {
+      await api.createRoadmapFeature(
+        milestoneId,
+        { title: suggestion.title, description: suggestion.description },
+        projectIdRef.current
+      );
+
+      // Check for stale response
+      if (projectContextVersionRef.current !== contextVersionAtStart) {
+        // Project context changed - re-add to suggestions (optimistic rollback)
+        setFeatureSuggestionsByMilestoneId((prev) => {
+          const milestoneSuggestions = prev[milestoneId] || [];
+          const updated = [...milestoneSuggestions];
+          updated.splice(index, 0, suggestion);
+          return { ...prev, [milestoneId]: updated };
+        });
+        return;
+      }
+
+      // Refresh the roadmap to get the new feature
+      if (selectedRoadmapIdRef.current) {
+        void fetchSelectedRoadmap(selectedRoadmapIdRef.current);
+      }
+
+      opts?.onSuccess?.();
+    } catch (err) {
+      // Rollback: re-add to suggestions
+      setFeatureSuggestionsByMilestoneId((prev) => {
+        const milestoneSuggestions = prev[milestoneId] || [];
+        const updated = [...milestoneSuggestions];
+        updated.splice(index, 0, suggestion);
+        return { ...prev, [milestoneId]: updated };
+      });
+
+      const error = err instanceof Error ? err : new Error("Failed to accept suggestion");
+      opts?.onError?.(error);
+      throw error;
+    }
+  }, [fetchSelectedRoadmap]);
+
+  const acceptAllFeatureSuggestions = useCallback(async (
+    milestoneId: string,
+    opts?: { onSuccess?: () => void; onError?: (err: Error) => void }
+  ) => {
+    // Read from ref - it's updated synchronously by updateFeatureSuggestionDraft
+    const suggestionsToAccept = [...(featureSuggestionsByMilestoneIdRef.current[milestoneId] || [])];
+    if (suggestionsToAccept.length === 0) {
+      return;
+    }
+
+    // Validate all titles before accepting any
+    const emptyTitleIndex = suggestionsToAccept.findIndex((s) => !s.title.trim());
+    if (emptyTitleIndex !== -1) {
+      const error = new Error(`Title cannot be empty at position ${emptyTitleIndex + 1}`);
+      opts?.onError?.(error);
+      throw error;
+    }
+
+    // Clear suggestions for this milestone immediately (optimistic)
+    setFeatureSuggestionsByMilestoneId((prev) => ({
+      ...prev,
+      [milestoneId]: [],
+    }));
+
+    // Capture state for stale-response protection
+    const contextVersionAtStart = projectContextVersionRef.current;
+
+    // Accept sequentially to preserve order
+    for (let i = 0; i < suggestionsToAccept.length; i++) {
+      // Check for stale response
+      if (projectContextVersionRef.current !== contextVersionAtStart) {
+        // Project context changed - stop accepting
+        break;
+      }
+
+      const suggestion = suggestionsToAccept[i];
+
+      try {
+        await api.createRoadmapFeature(
+          milestoneId,
+          { title: suggestion.title, description: suggestion.description },
+          projectIdRef.current
+        );
+      } catch (err) {
+        // On error, stop accepting and report
+        const error = err instanceof Error ? err : new Error("Failed to accept all suggestions");
+        opts?.onError?.(error);
+        throw error;
+      }
+    }
+
+    // Check for stale response
+    if (projectContextVersionRef.current !== contextVersionAtStart) {
+      return;
+    }
+
+    // Refresh the roadmap to get all new features
+    if (selectedRoadmapIdRef.current) {
+      void fetchSelectedRoadmap(selectedRoadmapIdRef.current);
+    }
+
+    opts?.onSuccess?.();
+  }, [fetchSelectedRoadmap]);
+
+  const clearMilestoneSuggestions = useCallback(() => {
+    setMilestoneSuggestions([]);
+    setIsGeneratingSuggestions(false);
+  }, []);
+
+  const clearFeatureSuggestions = useCallback((milestoneId: string) => {
+    setFeatureSuggestionsByMilestoneId((prev) => {
+      const updated = { ...prev };
+      delete updated[milestoneId];
+      return updated;
+    });
+    setGeneratingFeatureSuggestions((prev) => {
+      const updated = { ...prev };
+      delete updated[milestoneId];
+      return updated;
+    });
+  }, []);
+
+  // ── Handoff / Export Functions ────────────────────────────────────────
+
+  const fetchHandoff = useCallback(async (
+    roadmapId: string,
+    opts?: { onSuccess?: () => void; onError?: (err: Error) => void }
+  ) => {
+    const requestVersion = ++handoffFetchVersionRef.current;
+    const requestProjectId = projectId; // Capture projectId at request time
+
+    setIsFetchingHandoff(true);
+    setHandoffError(null);
+
+    try {
+      const data = await api.fetchRoadmapHandoff(roadmapId, requestProjectId);
+
+      // Reject stale responses: check if project changed or version is stale
+      if (handoffFetchVersionRef.current !== requestVersion || projectId !== requestProjectId) {
+        return; // Stale response, discard
+      }
+
+      setHandoffPayload(data);
+      opts?.onSuccess?.();
+    } catch (err) {
+      // Reject stale errors: check if project changed or version is stale
+      if (handoffFetchVersionRef.current !== requestVersion || projectId !== requestProjectId) {
+        return; // Stale error, discard
+      }
+
+      const error = err instanceof Error ? err : new Error(String(err));
+      setHandoffError(error);
+      setHandoffPayload(null);
+      opts?.onError?.(error);
+    } finally {
+      // Only clear loading if this is still the current request
+      if (handoffFetchVersionRef.current === requestVersion) {
+        setIsFetchingHandoff(false);
+      }
+    }
+  }, [projectId]);
+
+  const clearHandoff = useCallback(() => {
+    setHandoffPayload(null);
+    setHandoffError(null);
+    setIsFetchingHandoff(false);
+  }, []);
+
+  const refresh = useCallback(async () => {
+    await fetchRoadmaps();
+    if (selectedRoadmapIdRef.current) {
+      await fetchSelectedRoadmap(selectedRoadmapIdRef.current);
+    }
+  }, [fetchRoadmaps, fetchSelectedRoadmap]);
+
+  return {
+    roadmaps,
+    selectedRoadmapId,
+    selectedRoadmap,
+    milestones,
+    featuresByMilestoneId,
+    loading,
+    error,
+    createRoadmap,
+    updateRoadmap,
+    deleteRoadmap,
+    selectRoadmap,
+    createMilestone,
+    updateMilestone,
+    deleteMilestone,
+    reorderMilestones,
+    createFeature,
+    updateFeature,
+    deleteFeature,
+    reorderFeatures,
+    moveFeature,
+    milestoneSuggestions,
+    isGeneratingSuggestions,
+    generateMilestoneSuggestions,
+    updateMilestoneSuggestionDraft,
+    acceptMilestoneSuggestion,
+    acceptAllMilestoneSuggestions,
+    clearMilestoneSuggestions,
+    featureSuggestionsByMilestoneId,
+    isGeneratingFeatureSuggestions,
+    generateFeatureSuggestions,
+    updateFeatureSuggestionDraft,
+    acceptFeatureSuggestion,
+    acceptAllFeatureSuggestions,
+    clearFeatureSuggestions,
+    handoffPayload,
+    isFetchingHandoff,
+    handoffError,
+    fetchHandoff,
+    clearHandoff,
+    refresh,
+  };
+}