@bycrux/editor 0.9.0 → 0.11.0

package/src/state/use-project-state.ts

@@ -1,28 +1,25 @@
 /**
- * editor-core / state / use-project-state — optimistic, host-agnostic project
- * state with undo/redo and SSE reconciliation.
+ * editor-core / state / use-project-state — the carousel editor's typed,
+ * slide/element-addressed project state.
  *
- * Ported from mission-control's
- * `src/app/admin/projects/hooks/use-project-state.ts`. The MC version hardcoded
- * `/api/hub/projects/:id/montaj` fetch + EventSource. Here, ALL transport goes
- * through the injected `EditorAdapter`:
- *   - persistence → `adapter.saveProject(id, project)`
- *   - live frames → `adapter.subscribe(id, onFrame)`
- *   - refetch     → `adapter.loadProject(id)`
+ * A thin typed layer over the shape-agnostic `useProjectSync` core. This module
+ * owns everything carousel-specific: the typed `Action` vocabulary (via
+ * `projectReducer`), edit-gating by project status, and the target-exists guards
+ * on overlay/image prop edits. All save/undo/SSE machinery lives in
+ * `useProjectSync`; each typed mutation is expressed as
+ * `sync.mutate(p => projectReducer(p, action))` behind its existing gates.
  *
- * Everything else is preserved: optimistic mutations, the transient-vs-committed
- * distinction, mutation-queue serialisation, SSE deferral while a save is in
- * flight, rollback on save failure, and the MAX_HISTORY=50 undo/redo stacks.
+ * The public surface (the `UseProjectState` interface and behavior) is
+ * unchanged from when the machinery lived here inline.
  */
-import { useEffect, useReducer, useRef, useState, useCallback } from 'react'
+import { useCallback } from 'react'
 import { projectReducer, type Action, type ProjectStatus } from './project-reducer'
-import { createMutationQueue } from './mutation-queue'
+import { useProjectSync } from './use-project-sync'
 import type { Project, Slide, CarouselElement, EditorAdapter } from '../types'
 
-// Connection lifecycle: 'connecting' from mount until the first SSE frame
-// arrives, then 'live'. The adapter's subscribe auto-reconnects on drop —
-// the editor stays 'live' and simply receives the next frame when it comes.
-export type Connection = 'connecting' | 'live'
+// Re-export so existing consumers (index.ts barrel) keep importing `Connection`
+// from here; the type is now owned by the sync core.
+export type { Connection } from './use-project-sync'
 
 function isEditable(status: ProjectStatus): boolean {
   return status === 'draft' || status === 'final'
@@ -40,7 +37,7 @@ function findElementType(
 
 export interface UseProjectState<P extends Project = Project> {
   project: P
-  connection: Connection
+  connection: 'connecting' | 'live'
   isEditingAllowed: boolean
   lastError: string | null
   clearError: () => void
@@ -74,100 +71,23 @@ export function useProjectState<P extends Project = Project>(
   projectId: string,
   initial: P,
 ): UseProjectState<P> {
-  const [project, dispatch] = useReducer(
-    projectReducer as (state: P, action: Action<P>) => P,
-    initial,
+  // Reference-preserving structural merge for external frames (SSE / refetch),
+  // expressed through the reducer's `sse` case so echoes don't churn the canvas.
+  const reconcile = useCallback(
+    (prev: P, next: P): P =>
+      (projectReducer as (state: P, action: Action<P>) => P)(prev, { type: 'sse', project: next }),
+    [],
   )
-  const [connection, setConnection] = useState<Connection>('connecting')
-  const [lastError, setLastError] = useState<string | null>(null)
-  const queue = useRef(createMutationQueue())
-  // Snapshot taken before the first transient mutation in the current gesture.
-  // Reset to null after a successful commit or rollback.
-  const transientBaseline = useRef<P | null>(null)
-  // Synchronously-updated mirror of the reducer state. Written in three places:
-  //   1. Render phase, from `project` (covers SSE, rollback, refetch — paths
-  //      that go through dispatch directly without computing `next` here).
-  //   2. Inside `mutate`, after computing `next` synchronously from the reducer.
-  //   3. Inside `mutateTransient`, after computing `next` synchronously.
-  // (2) and (3) are critical: a same-tick caller (e.g. `commit()` invoked
-  // immediately after `moveElement` from the gesture's onCommit handler) reads
-  // this ref to get the post-dispatch state without waiting for a re-render.
-  // Without (2)/(3), the ref lags by one render and save bodies are stale.
-  const projectRef = useRef<P>(project)
-  projectRef.current = project
-
-  // Latest deferred SSE payload. Held while there are in-flight saves because
-  // SSE echoes for an earlier save can arrive while a later save is still
-  // mid-flight — applying them would regress the optimistic state to the older
-  // value (visible as jitter on the canvas while the operator is typing).
-  // Last-write-wins: only the most recent SSE is kept.
-  const deferredSseRef = useRef<P | null>(null)
-
-  // Undo/redo: snapshot-based stacks of full project state. Each committed
-  // local action pushes the pre-action snapshot to undoStack and clears the
-  // redoStack. undo() pops undo→redo; redo() pops redo→undo. SSE updates do
-  // NOT touch the stacks — external changes stay opaque to local history.
-  const MAX_HISTORY = 50
-  const undoStackRef = useRef<P[]>([])
-  const redoStackRef = useRef<P[]>([])
-  const [historyVersion, setHistoryVersion] = useState(0)
-  const bumpHistory = useCallback(() => setHistoryVersion((v) => v + 1), [])
-  const pushUndo = useCallback((snapshot: P) => {
-    undoStackRef.current.push(snapshot)
-    if (undoStackRef.current.length > MAX_HISTORY) undoStackRef.current.shift()
-    redoStackRef.current = []
-    bumpHistory()
-  }, [bumpHistory])
 
-  // Subscription lifecycle. The adapter owns the transport (SSE, websocket,
-  // poll); we just receive fresh frames and reconcile them.
-  useEffect(() => {
-    setConnection('connecting')
-    let active = true
-    const unsubscribe = adapter.subscribe(projectId, (next) => {
-      if (!active) return
-      setConnection('live')
-      if (queue.current.isPending()) {
-        // Hold the frame; dispatch it once the queue drains.
-        deferredSseRef.current = next
-        queue.current.onceDrained(() => {
-          const held = deferredSseRef.current
-          deferredSseRef.current = null
-          if (held) dispatch({ type: 'sse', project: held })
-        })
-        return
-      }
-      dispatch({ type: 'sse', project: next })
-    })
-    return () => {
-      active = false
-      unsubscribe()
-    }
-  }, [adapter, projectId])
-
-  // Internal: persist the full project via the adapter; rollback on failure.
-  const save = useCallback(
-    async (next: P, snapshot: P) => {
-      try {
-        await adapter.saveProject(projectId, next)
-      } catch (err) {
-        dispatch({ type: 'rollback', snapshot })
-        throw err instanceof Error ? err : new Error(String(err))
-      }
-    },
-    [adapter, projectId],
-  )
+  const sync = useProjectSync<P>(adapter, projectId, initial, { reconcile })
+  const { mutate: syncMutate, mutateTransient: syncMutateTransient, projectRef } = sync
 
-  // Internal: snapshot, optimistically reduce, dispatch, and enqueue the save.
-  // Gates on edit-allowed status and target-exists; silent no-ops are visible
-  // via console.warn so the regen→slide-deleted race surfaces in the dev
-  // console. `next` is computed synchronously via the same reducer so the save
-  // gets the correct shape without waiting for a re-render.
+  // Typed, gated mutation. Gates on edit-allowed status and target-exists; silent
+  // no-ops surface via console.warn so the regen→slide-deleted race shows up in
+  // the dev console. Non-gated actions flow straight to the core, which handles
+  // the optimistic apply + queued save.
   const mutate = useCallback(
-    (action: Action<P>) => {
-      // Read base state from the live ref, not the `project` closure, so a
-      // sequence of mutate calls in the same event tick chain correctly
-      // (call N's `next` becomes call N+1's base).
+    (action: Action<P>): Promise<void> => {
       const base = projectRef.current
       const editGated = new Set(['updateOverlayProp', 'updateImageCrop', 'setStatus', 'setName', 'moveElement', 'resizeElement', 'rotateElement', 'addElement', 'removeElement', 'addSlide', 'removeSlide', 'duplicateSlide', 'reorderSlides', 'updateSlide', 'duplicateElement', 'reorderElement', 'setOverlayFrame'])
       if (editGated.has(action.type) && !isEditable(base.status)) {
@@ -184,109 +104,26 @@ export function useProjectState<P extends Project = Project>(
           return Promise.resolve()
         }
       }
-      const snapshot = base
-      pushUndo(snapshot)
-      const next = projectReducer(base, action)
-      projectRef.current = next
-      dispatch(action)
-      // Non-transient mutations reset the baseline so any subsequent gesture
-      // starts from the freshly committed state.
-      transientBaseline.current = null
-      return queue.current.enqueue(() =>
-        save(next, snapshot).catch((err) => {
-          setLastError(err instanceof Error ? err.message : String(err))
-          throw err
-        }),
-      )
+      return syncMutate((p) => projectReducer(p, action))
     },
-    [save, pushUndo],
+    [syncMutate, projectRef],
   )
 
-  // Internal: dispatch a transient (local-only) action — no save, no queue.
-  // Records the pre-gesture baseline on the first call so commit() can roll
-  // back to it on failure.
+  // Typed transient dispatch (gesture previews) — local only, gated to the
+  // transform actions and edit-allowed status.
   const mutateTransient = useCallback(
-    (action: Action<P>) => {
+    (action: Action<P>): void => {
       const base = projectRef.current
       const editGated = new Set(['moveElement', 'resizeElement', 'rotateElement'])
       if (!editGated.has(action.type) || !isEditable(base.status)) {
         console.warn(`[useProjectState] dropped transient ${action.type}: status="${base.status}" not editable`)
         return
       }
-      // Capture baseline before the first transient change in this gesture.
-      if (transientBaseline.current === null) {
-        transientBaseline.current = base
-      }
-      const next = projectReducer(base, action)
-      projectRef.current = next
-      dispatch(action)
+      syncMutateTransient((p) => projectReducer(p, action))
     },
-    [],
+    [syncMutateTransient, projectRef],
   )
 
-  // commit() — enqueues ONE save with the current (post-drag) state.
-  // On failure, rolls back to the pre-gesture baseline.
-  const commit = useCallback((): Promise<void> => {
-    const current = projectRef.current
-    const baseline = transientBaseline.current
-    transientBaseline.current = null
-    // One undo step per gesture: only push the baseline if the gesture
-    // actually produced transient changes (baseline was captured).
-    if (baseline !== null) pushUndo(baseline)
-    const rollbackTo = baseline ?? current
-    return queue.current.enqueue(() =>
-      save(current, rollbackTo).catch((err) => {
-        setLastError(err instanceof Error ? err.message : String(err))
-        throw err
-      }),
-    )
-  }, [save, pushUndo])
-
-  // undo()/redo() — snapshot swap. Pops the target stack, pushes current
-  // state to the opposite stack, dispatches `rollback` (which replaces the
-  // entire state), and enqueues a save so the host persists the swap.
-  const undo = useCallback((): void => {
-    const prev = undoStackRef.current.pop()
-    if (!prev) return
-    const current = projectRef.current
-    redoStackRef.current.push(current)
-    if (redoStackRef.current.length > MAX_HISTORY) redoStackRef.current.shift()
-    bumpHistory()
-    projectRef.current = prev
-    dispatch({ type: 'rollback', snapshot: prev })
-    void queue.current.enqueue(() =>
-      save(prev, current).catch((err) => {
-        setLastError(err instanceof Error ? err.message : String(err))
-        throw err
-      }),
-    )
-  }, [save, bumpHistory])
-
-  const redo = useCallback((): void => {
-    const next = redoStackRef.current.pop()
-    if (!next) return
-    const current = projectRef.current
-    undoStackRef.current.push(current)
-    if (undoStackRef.current.length > MAX_HISTORY) undoStackRef.current.shift()
-    bumpHistory()
-    projectRef.current = next
-    dispatch({ type: 'rollback', snapshot: next })
-    void queue.current.enqueue(() =>
-      save(next, current).catch((err) => {
-        setLastError(err instanceof Error ? err.message : String(err))
-        throw err
-      }),
-    )
-  }, [save, bumpHistory])
-
-  const canUndo = undoStackRef.current.length > 0
-  const canRedo = redoStackRef.current.length > 0
-  // Touch historyVersion so dependent components re-render when the stacks
-  // change. Without this, canUndo/canRedo would be evaluated on stale renders.
-  void historyVersion
-
-  const clearError = useCallback(() => setLastError(null), [])
-
   const updateOverlayProp = useCallback(
     (slideId: string, elementId: string, key: string, value: string) =>
       mutate({ type: 'updateOverlayProp', slideId, elementId, key, value }),
@@ -395,26 +232,14 @@ export function useProjectState<P extends Project = Project>(
     [mutate],
   )
 
-  // Force a fresh load of the project via the adapter and replace local state.
-  // Useful when local state has drifted from the server (e.g. after a network gap).
-  const refetch = useCallback(async () => {
-    try {
-      const next = await adapter.loadProject(projectId)
-      dispatch({ type: 'sse', project: next })
-    } catch (err) {
-      setLastError(err instanceof Error ? err.message : String(err))
-      throw err
-    }
-  }, [adapter, projectId])
-
-  const isEditingAllowed = isEditable(project.status)
+  const isEditingAllowed = isEditable(sync.project.status)
 
   return {
-    project,
-    connection,
+    project: sync.project,
+    connection: sync.connection,
     isEditingAllowed,
-    lastError,
-    clearError,
+    lastError: sync.lastError,
+    clearError: sync.clearError,
     updateOverlayProp,
     updateImageCrop,
     setStatus,
@@ -432,11 +257,11 @@ export function useProjectState<P extends Project = Project>(
     reorderSlides,
     updateSlide,
     setOverlayFrame,
-    commit,
-    refetch,
-    undo,
-    redo,
-    canUndo,
-    canRedo,
+    commit: sync.commit,
+    refetch: sync.refetch,
+    undo: sync.undo,
+    redo: sync.redo,
+    canUndo: sync.canUndo,
+    canRedo: sync.canRedo,
   }
 }

package/src/state/use-project-sync.ts

@@ -0,0 +1,310 @@
+/**
+ * editor-core / state / use-project-sync — the shape-agnostic save/undo core.
+ *
+ * Extracted from `use-project-state.ts` so both editors (carousel + video) can
+ * share one save model. This hook knows NOTHING about slides, elements, or the
+ * typed action vocabulary — it operates over opaque project values `P` and
+ * function-shaped mutations `(p: P) => P`. Everything shape-specific (the typed
+ * `Action` union, `projectReducer`, edit-gating) stays in the layer above.
+ *
+ * Mechanics carried over verbatim from `use-project-state.ts`:
+ *   - mutation-queue serialisation (`createMutationQueue`)
+ *   - SSE subscribe + deferral: hold echoes while a save is in flight, then
+ *     apply only the most recent one on drain (last-write-wins)
+ *   - optimistic apply with rollback-on-save-failure
+ *   - undo/redo snapshot stacks capped at MAX_HISTORY=50
+ *   - `projectRef` same-tick mirror so a caller reading it immediately after a
+ *     mutation sees post-mutation state without waiting for a re-render
+ *
+ * The only shape-aware seam is the optional `reconcile` option: how an external
+ * frame (SSE / refetch / `applyExternal`) is folded into current state. It
+ * defaults to a plain replace; the carousel layer passes its reference-
+ * preserving structural merge so echoes don't churn the canvas. The core never
+ * looks inside `P` to do this — it just calls the supplied function.
+ */
+import { useCallback, useEffect, useReducer, useRef, useState } from 'react'
+import type { RefObject } from 'react'
+import { createMutationQueue } from './mutation-queue'
+import type { Project, EditorAdapter } from '../types'
+
+// Connection lifecycle: 'connecting' from mount until the first frame arrives,
+// then 'live'. The adapter's subscribe auto-reconnects on drop — the editor
+// stays 'live' and simply receives the next frame when it comes.
+export type Connection = 'connecting' | 'live'
+
+export interface UseProjectSyncOptions<P extends Project> {
+  /**
+   * Fold an external (server-authored) frame into current state. Receives the
+   * current project and the incoming frame; returns the state to apply. Used by
+   * the SSE path, `refetch`, and `applyExternal`. Defaults to a plain replace
+   * (`(_prev, next) => next`). Hosts that want reference-preserving merges pass
+   * one here — it must be a pure function of its two arguments.
+   */
+  reconcile?: (prev: P, next: P) => P
+}
+
+export interface UseProjectSync<P extends Project = Project> {
+  project: P
+  connection: Connection
+  /** pushUndo + optimistic apply + queued save + rollback-on-failure. */
+  mutate: (fn: (p: P) => P) => Promise<void>
+  /** Local-only apply (gesture previews) — no save, no undo push. */
+  mutateTransient: (fn: (p: P) => P) => void
+  /** One queued save for the accumulated transient state; one undo step. */
+  commit: () => Promise<void>
+  /** Apply server-authored state — no save, no undo push (e.g. caption regen). */
+  applyExternal: (p: P) => void
+  undo: () => void
+  redo: () => void
+  canUndo: boolean
+  canRedo: boolean
+  refetch: () => Promise<void>
+  lastError: string | null
+  clearError: () => void
+  projectRef: RefObject<P>
+}
+
+export function useProjectSync<P extends Project = Project>(
+  adapter: EditorAdapter<P>,
+  projectId: string,
+  initial: P,
+  options?: UseProjectSyncOptions<P>,
+): UseProjectSync<P> {
+  // Replace-only reducer: every transition computes the next project value
+  // externally and dispatches it. Keeps the core shape-agnostic (no typed
+  // action vocabulary) while dodging useState's function-arg ambiguity.
+  const [project, setProject] = useReducer((_prev: P, next: P) => next, initial)
+  const [connection, setConnection] = useState<Connection>('connecting')
+  const [lastError, setLastError] = useState<string | null>(null)
+  const queue = useRef(createMutationQueue())
+
+  // Snapshot taken before the first transient mutation in the current gesture.
+  // Reset to null after a successful commit or a non-transient mutation.
+  const transientBaseline = useRef<P | null>(null)
+
+  // Synchronously-updated mirror of reducer state. Written in the render phase
+  // (below) AND inside every mutation path after computing `next`. The same-tick
+  // writes are critical: a caller (e.g. `commit()` invoked immediately after a
+  // transient move from a gesture's onCommit handler) reads this ref to get
+  // post-dispatch state without waiting for a re-render.
+  const projectRef = useRef<P>(project)
+  projectRef.current = project
+
+  // `reconcile` stashed in a ref so the subscribe effect and apply path stay
+  // referentially stable regardless of whether the host memoises the option.
+  const reconcileRef = useRef(options?.reconcile)
+  reconcileRef.current = options?.reconcile
+
+  // Latest deferred external frame. Held while saves are in flight because an
+  // echo for an earlier save can arrive while a later save is still mid-flight —
+  // applying it would regress the optimistic state to the older value (visible
+  // as jitter on the canvas while the operator is typing). Last-write-wins:
+  // only the most recent frame is kept.
+  const deferredSseRef = useRef<P | null>(null)
+
+  // Fold an external frame into current state (reconcile, or plain replace) and
+  // apply it. No save, no undo push. Stable — reads reconcile via ref.
+  //
+  // Clears transientBaseline: an external frame invalidates any in-progress
+  // gesture's pre-gesture snapshot (it predates this frame), so a subsequent
+  // commit() must not roll back to it and undo() must not resurrect it. Without
+  // this, a stale baseline can silently swallow an external change on undo —
+  // see the regression test for the full sequence.
+  const applyExternal = useCallback((incoming: P) => {
+    const base = projectRef.current
+    const reconcile = reconcileRef.current
+    const next = reconcile ? reconcile(base, incoming) : incoming
+    projectRef.current = next
+    transientBaseline.current = null
+    setProject(next)
+  }, [])
+
+  // Undo/redo: snapshot-based stacks of full project state. Each committed local
+  // mutation pushes the pre-mutation snapshot to undoStack and clears redoStack.
+  // undo() pops undo→redo; redo() pops redo→undo. External frames do NOT touch
+  // the stacks — server changes stay opaque to local history.
+  const MAX_HISTORY = 50
+  const undoStackRef = useRef<P[]>([])
+  const redoStackRef = useRef<P[]>([])
+  const [historyVersion, setHistoryVersion] = useState(0)
+  const bumpHistory = useCallback(() => setHistoryVersion((v) => v + 1), [])
+  const pushUndo = useCallback((snapshot: P) => {
+    undoStackRef.current.push(snapshot)
+    if (undoStackRef.current.length > MAX_HISTORY) undoStackRef.current.shift()
+    redoStackRef.current = []
+    bumpHistory()
+  }, [bumpHistory])
+
+  // Subscription lifecycle. The adapter owns the transport (SSE, websocket,
+  // poll); we just receive fresh frames and reconcile them. `applyExternal` is
+  // stable so this only re-subscribes on adapter/projectId change.
+  useEffect(() => {
+    setConnection('connecting')
+    let active = true
+    const unsubscribe = adapter.subscribe(projectId, (next) => {
+      if (!active) return
+      setConnection('live')
+      if (queue.current.isPending()) {
+        // Hold the frame; apply it once the queue drains.
+        deferredSseRef.current = next
+        queue.current.onceDrained(() => {
+          const held = deferredSseRef.current
+          deferredSseRef.current = null
+          if (held) applyExternal(held)
+        })
+        return
+      }
+      applyExternal(next)
+    })
+    return () => {
+      active = false
+      unsubscribe()
+    }
+  }, [adapter, projectId, applyExternal])
+
+  // Internal: persist the full project via the adapter; rollback on failure.
+  const save = useCallback(
+    async (next: P, snapshot: P) => {
+      try {
+        await adapter.saveProject(projectId, next)
+      } catch (err) {
+        projectRef.current = snapshot
+        setProject(snapshot)
+        throw err instanceof Error ? err : new Error(String(err))
+      }
+    },
+    [adapter, projectId],
+  )
+
+  // Snapshot, optimistically apply, and enqueue the save. `next` is computed
+  // synchronously from the live ref (not the `project` closure) so a sequence of
+  // mutate calls in the same tick chains correctly (call N's next becomes call
+  // N+1's base) and the save body carries the correct shape without a re-render.
+  const mutate = useCallback(
+    (fn: (p: P) => P): Promise<void> => {
+      const base = projectRef.current
+      const snapshot = base
+      pushUndo(snapshot)
+      const next = fn(base)
+      projectRef.current = next
+      setProject(next)
+      // Non-transient mutations reset the baseline so any subsequent gesture
+      // starts from the freshly committed state.
+      transientBaseline.current = null
+      return queue.current.enqueue(() =>
+        save(next, snapshot).catch((err) => {
+          setLastError(err instanceof Error ? err.message : String(err))
+          throw err
+        }),
+      )
+    },
+    [save, pushUndo],
+  )
+
+  // Local-only apply — no save, no queue. Records the pre-gesture baseline on the
+  // first call so commit() can roll back to it on failure.
+  const mutateTransient = useCallback((fn: (p: P) => P): void => {
+    const base = projectRef.current
+    if (transientBaseline.current === null) {
+      transientBaseline.current = base
+    }
+    const next = fn(base)
+    projectRef.current = next
+    setProject(next)
+  }, [])
+
+  // commit() — enqueues ONE save with the current (post-gesture) state. On
+  // failure, rolls back to the pre-gesture baseline. One undo step per gesture:
+  // only push the baseline if the gesture actually produced transient changes.
+  const commit = useCallback((): Promise<void> => {
+    const current = projectRef.current
+    const baseline = transientBaseline.current
+    transientBaseline.current = null
+    if (baseline !== null) pushUndo(baseline)
+    const rollbackTo = baseline ?? current
+    return queue.current.enqueue(() =>
+      save(current, rollbackTo).catch((err) => {
+        setLastError(err instanceof Error ? err.message : String(err))
+        throw err
+      }),
+    )
+  }, [save, pushUndo])
+
+  // undo()/redo() — snapshot swap. Pops the target stack, pushes current state
+  // to the opposite stack, replaces the entire state, and enqueues a save so the
+  // host persists the swap. Also clears transientBaseline: it replaces state
+  // wholesale, so any in-progress gesture's pre-gesture snapshot is stale after
+  // this and must not be resurrected by a later commit()/undo() (see applyExternal).
+  const undo = useCallback((): void => {
+    const prev = undoStackRef.current.pop()
+    if (!prev) return
+    const current = projectRef.current
+    redoStackRef.current.push(current)
+    if (redoStackRef.current.length > MAX_HISTORY) redoStackRef.current.shift()
+    bumpHistory()
+    projectRef.current = prev
+    transientBaseline.current = null
+    setProject(prev)
+    void queue.current.enqueue(() =>
+      save(prev, current).catch((err) => {
+        setLastError(err instanceof Error ? err.message : String(err))
+        throw err
+      }),
+    )
+  }, [save, bumpHistory])
+
+  const redo = useCallback((): void => {
+    const next = redoStackRef.current.pop()
+    if (!next) return
+    const current = projectRef.current
+    undoStackRef.current.push(current)
+    if (undoStackRef.current.length > MAX_HISTORY) undoStackRef.current.shift()
+    bumpHistory()
+    projectRef.current = next
+    transientBaseline.current = null
+    setProject(next)
+    void queue.current.enqueue(() =>
+      save(next, current).catch((err) => {
+        setLastError(err instanceof Error ? err.message : String(err))
+        throw err
+      }),
+    )
+  }, [save, bumpHistory])
+
+  const canUndo = undoStackRef.current.length > 0
+  const canRedo = redoStackRef.current.length > 0
+  // Touch historyVersion so dependent components re-render when the stacks
+  // change. Without this, canUndo/canRedo would be evaluated on stale renders.
+  void historyVersion
+
+  const clearError = useCallback(() => setLastError(null), [])
+
+  // Force a fresh load of the project via the adapter and reconcile it in.
+  // Useful when local state has drifted from the server (e.g. after a gap).
+  const refetch = useCallback(async () => {
+    try {
+      const next = await adapter.loadProject(projectId)
+      applyExternal(next)
+    } catch (err) {
+      setLastError(err instanceof Error ? err.message : String(err))
+      throw err
+    }
+  }, [adapter, projectId, applyExternal])
+
+  return {
+    project,
+    connection,
+    mutate,
+    mutateTransient,
+    commit,
+    applyExternal,
+    undo,
+    redo,
+    canUndo,
+    canRedo,
+    refetch,
+    lastError,
+    clearError,
+    projectRef,
+  }
+}