@bycrux/editor 0.10.0 → 0.11.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bycrux/editor",
-  "version": "0.10.0",
+  "version": "0.11.0",
   "private": false,
   "type": "module",
   "exports": {

package/src/schema.ts

@@ -40,6 +40,12 @@ export interface CaptionSegment {
   start: number
   end: number
   words?: Word[]
+  offsetX?: number   // percent of frame width,  0/absent = default anchor
+  offsetY?: number   // percent of frame height, 0/absent = default anchor
+  // Visual scale of the whole caption block about its own centre — a CSS
+  // transform, not a font-size change, so it scales the background box and
+  // text stroke too and does NOT re-wrap the text. Default 1.
+  scale?: number
 }
 
 export interface Captions {

package/src/state/__tests__/use-project-sync.test.tsx

@@ -0,0 +1,315 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { act, renderHook, waitFor } from '@testing-library/react'
+import { useProjectSync } from '../use-project-sync'
+import type { EditorAdapter, Project, ImageElement, RenderEvent } from '../../types'
+
+// ---------------------------------------------------------------------------
+// Fixtures — mirrors the use-project-state test's FakeAdapter, but drives the
+// shape-agnostic core directly with `(p) => p` mutations instead of the typed
+// action vocabulary.
+// ---------------------------------------------------------------------------
+
+function makeProject(overrides: Partial<Project> = {}): Project {
+  return {
+    version: '1',
+    id: 'proj-1',
+    name: 'Test Project',
+    workflow: 'carousel',
+    status: 'draft',
+    editingPrompt: '',
+    settings: { resolution: [1080, 1080] },
+    assets: [],
+    slides: [
+      {
+        id: 'slide-0',
+        base_color: '#ffffff',
+        elements: [
+          { id: 'el-0', type: 'image', src: 'a.png', x: 0, y: 0, w: 100, h: 100, rotation: 0 },
+        ],
+      },
+    ],
+    ...overrides,
+  }
+}
+
+interface FakeAdapter extends EditorAdapter {
+  emit: (p: Project) => void
+  saveCalls: Array<{ id: string; project: Project }>
+  unsub: ReturnType<typeof vi.fn>
+}
+
+function makeFakeAdapter(opts: {
+  failSave?: boolean
+  /** When set, saveProject blocks on this until `release` is called. */
+  blockSave?: boolean
+} = {}): FakeAdapter & { release: () => void } {
+  let onFrame: ((p: Project) => void) | null = null
+  const saveCalls: Array<{ id: string; project: Project }> = []
+  const unsub = vi.fn(() => { onFrame = null })
+  let releaseSave: (() => void) | null = null
+  const adapter: FakeAdapter & { release: () => void } = {
+    loadProject: vi.fn(async () => makeProject()),
+    saveProject: vi.fn(async (id: string, project: Project) => {
+      saveCalls.push({ id, project })
+      if (opts.blockSave) await new Promise<void>((res) => { releaseSave = res })
+      if (opts.failSave) throw new Error('save boom')
+    }),
+    subscribe: (_id: string, cb: (p: Project) => void) => {
+      onFrame = cb
+      return unsub
+    },
+    render: async function* (): AsyncIterable<RenderEvent> {
+      yield { type: 'done', outputPath: '/out.png' }
+    },
+    resolveImageSrc: (el: ImageElement) => el.src,
+    compileOverlay: vi.fn(async () => () => null),
+    listGlobalOverlays: vi.fn(async () => []),
+    listSystemOverlays: vi.fn(async () => []),
+    uploadFile: vi.fn(async () => '/path'),
+    fileUrl: (path: string) => path,
+    emit: (p: Project) => onFrame?.(p),
+    saveCalls,
+    unsub,
+    release: () => releaseSave?.(),
+  }
+  return adapter
+}
+
+beforeEach(() => { vi.spyOn(console, 'warn').mockImplementation(() => {}) })
+afterEach(() => { vi.restoreAllMocks() })
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('useProjectSync — optimistic save', () => {
+  it('optimistically applies a mutation and persists via adapter.saveProject', async () => {
+    const adapter = makeFakeAdapter()
+    const initial = makeProject()
+    const { result } = renderHook(() => useProjectSync(adapter, initial.id, initial))
+
+    await act(async () => {
+      await result.current.mutate((p) => ({ ...p, name: 'Renamed' }))
+    })
+
+    expect(result.current.project.name).toBe('Renamed')
+    expect(adapter.saveProject).toHaveBeenCalledTimes(1)
+    expect(adapter.saveCalls[0].id).toBe('proj-1')
+    expect(adapter.saveCalls[0].project.name).toBe('Renamed')
+    expect(result.current.canUndo).toBe(true)
+  })
+
+  it('rolls back optimistic state and surfaces lastError when saveProject fails', async () => {
+    const adapter = makeFakeAdapter({ failSave: true })
+    const initial = makeProject()
+    const { result } = renderHook(() => useProjectSync(adapter, initial.id, initial))
+
+    await act(async () => {
+      await result.current.mutate((p) => ({ ...p, name: 'Renamed' })).catch(() => {})
+    })
+
+    // Rolled back to the pre-mutation snapshot.
+    expect(result.current.project.name).toBe('Test Project')
+    expect(result.current.lastError).toMatch(/save boom/)
+  })
+
+  it('clearError resets lastError', async () => {
+    const adapter = makeFakeAdapter({ failSave: true })
+    const initial = makeProject()
+    const { result } = renderHook(() => useProjectSync(adapter, initial.id, initial))
+
+    await act(async () => {
+      await result.current.mutate((p) => ({ ...p, name: 'X' })).catch(() => {})
+    })
+    expect(result.current.lastError).toMatch(/save boom/)
+
+    act(() => { result.current.clearError() })
+    expect(result.current.lastError).toBeNull()
+  })
+})
+
+describe('useProjectSync — external frames', () => {
+  it('applies SSE frames pushed through adapter.subscribe and goes live', async () => {
+    const adapter = makeFakeAdapter()
+    const initial = makeProject()
+    const { result } = renderHook(() => useProjectSync(adapter, initial.id, initial))
+
+    expect(result.current.connection).toBe('connecting')
+
+    act(() => { adapter.emit(makeProject({ name: 'From Server' })) })
+
+    await waitFor(() => {
+      expect(result.current.project.name).toBe('From Server')
+      expect(result.current.connection).toBe('live')
+    })
+    // External frames do not save or push undo history.
+    expect(adapter.saveProject).not.toHaveBeenCalled()
+    expect(result.current.canUndo).toBe(false)
+  })
+
+  it('applyExternal replaces state without saving or pushing undo', async () => {
+    const adapter = makeFakeAdapter()
+    const initial = makeProject()
+    const { result } = renderHook(() => useProjectSync(adapter, initial.id, initial))
+
+    act(() => { result.current.applyExternal(makeProject({ name: 'Server Authored' })) })
+
+    expect(result.current.project.name).toBe('Server Authored')
+    expect(adapter.saveProject).not.toHaveBeenCalled()
+    expect(result.current.canUndo).toBe(false)
+  })
+
+  it('routes external frames through a supplied reconcile function', async () => {
+    const adapter = makeFakeAdapter()
+    const initial = makeProject({ name: 'Local' })
+    // reconcile that ignores the incoming frame (keeps prev).
+    const reconcile = vi.fn((prev: Project, _next: Project) => prev)
+    const { result } = renderHook(() =>
+      useProjectSync(adapter, initial.id, initial, { reconcile }),
+    )
+
+    act(() => { result.current.applyExternal(makeProject({ name: 'Incoming' })) })
+
+    expect(reconcile).toHaveBeenCalledTimes(1)
+    expect(result.current.project.name).toBe('Local')
+  })
+
+  it('defers an SSE frame while a save is in flight, then applies it on drain', async () => {
+    const adapter = makeFakeAdapter({ blockSave: true })
+    const initial = makeProject()
+    const { result } = renderHook(() => useProjectSync(adapter, initial.id, initial))
+
+    // Kick a mutation whose save blocks — the queue is now pending.
+    let mutatePromise: Promise<void> = Promise.resolve()
+    act(() => {
+      mutatePromise = result.current.mutate((p) => ({ ...p, name: 'Optimistic' }))
+    })
+    expect(result.current.project.name).toBe('Optimistic')
+    await waitFor(() => expect(adapter.saveProject).toHaveBeenCalledTimes(1))
+
+    // An echo arrives mid-save — it must be HELD, not applied (no clobber).
+    act(() => { adapter.emit(makeProject({ name: 'Echo While Saving' })) })
+    expect(result.current.project.name).toBe('Optimistic')
+
+    // Release the save; the queue drains and the deferred frame is applied.
+    await act(async () => {
+      adapter.release()
+      await mutatePromise
+    })
+    await waitFor(() => expect(result.current.project.name).toBe('Echo While Saving'))
+  })
+})
+
+describe('useProjectSync — undo/redo', () => {
+  it('undo/redo swap state and re-persist via adapter', async () => {
+    const adapter = makeFakeAdapter()
+    const initial = makeProject()
+    const { result } = renderHook(() => useProjectSync(adapter, initial.id, initial))
+
+    await act(async () => {
+      await result.current.mutate((p) => ({ ...p, name: 'Renamed' }))
+    })
+    expect(result.current.project.name).toBe('Renamed')
+    expect(result.current.canUndo).toBe(true)
+    expect(result.current.canRedo).toBe(false)
+
+    await act(async () => { result.current.undo() })
+    expect(result.current.project.name).toBe('Test Project')
+    expect(result.current.canRedo).toBe(true)
+
+    await act(async () => { result.current.redo() })
+    expect(result.current.project.name).toBe('Renamed')
+
+    // mutate save + undo save + redo save
+    await waitFor(() => expect(adapter.saveProject).toHaveBeenCalledTimes(3))
+  })
+
+  it('undo is a no-op with an empty history', async () => {
+    const adapter = makeFakeAdapter()
+    const initial = makeProject()
+    const { result } = renderHook(() => useProjectSync(adapter, initial.id, initial))
+
+    act(() => { result.current.undo() })
+    expect(result.current.project.name).toBe('Test Project')
+    expect(adapter.saveProject).not.toHaveBeenCalled()
+  })
+})
+
+describe('useProjectSync — transient gestures', () => {
+  it('commit persists one save after transient mutations, with one undo step', async () => {
+    const adapter = makeFakeAdapter()
+    const initial = makeProject()
+    const { result } = renderHook(() => useProjectSync(adapter, initial.id, initial))
+
+    await act(async () => {
+      result.current.mutateTransient((p) => ({ ...p, name: 'Drag 1' }))
+      result.current.mutateTransient((p) => ({ ...p, name: 'Drag 2' }))
+    })
+    // Transient mutations do not save.
+    expect(adapter.saveProject).not.toHaveBeenCalled()
+    expect(result.current.project.name).toBe('Drag 2')
+
+    await act(async () => { await result.current.commit() })
+    expect(adapter.saveProject).toHaveBeenCalledTimes(1)
+    expect(adapter.saveCalls[0].project.name).toBe('Drag 2')
+    // One undo step for the whole gesture.
+    expect(result.current.canUndo).toBe(true)
+
+    await act(async () => { result.current.undo() })
+    expect(result.current.project.name).toBe('Test Project')
+  })
+})
+
+describe('useProjectSync — stale baseline regression', () => {
+  // Regression for a data-loss bug: applyExternal (and undo/redo) replaced
+  // state but left `transientBaseline` pointing at a now-stale pre-gesture
+  // snapshot. A second gesture would then see a non-null baseline and skip
+  // re-baselining, so commit() pushed the STALE snapshot as the undo/rollback
+  // target — a later undo silently discarded the external change in between.
+  // Sequence: gesture 1 (baseline = initial) → external frame arrives →
+  // gesture 2 (must re-baseline to the external frame, not reuse the stale
+  // one) → commit → undo. Asserts undo lands on the EXTERNAL state, not the
+  // pre-gesture-1 state.
+  it('undo after a gesture that follows an external frame restores the external state, not the stale pre-gesture baseline', async () => {
+    const adapter = makeFakeAdapter()
+    const initial = makeProject({ name: 'Test Project' })
+    const { result } = renderHook(() => useProjectSync(adapter, initial.id, initial))
+
+    // Gesture 1 — baselines against the initial state.
+    act(() => {
+      result.current.mutateTransient((p) => ({ ...p, name: 'Gesture 1' }))
+    })
+
+    // External frame arrives mid-gesture (e.g. cancelOverlayEdit routing through
+    // applyExternal, or an SSE echo / caption regen / restoreVersion).
+    act(() => {
+      result.current.applyExternal(makeProject({ name: 'External' }))
+    })
+    expect(result.current.project.name).toBe('External')
+
+    // Gesture 2 — must baseline against 'External' (the current state), not the
+    // stale 'Test Project' baseline from gesture 1.
+    act(() => {
+      result.current.mutateTransient((p) => ({ ...p, name: 'Gesture 2' }))
+    })
+
+    await act(async () => { await result.current.commit() })
+
+    await act(async () => { result.current.undo() })
+
+    // Undo should remove only gesture 2, landing back on the external state —
+    // NOT the stale pre-gesture-1 snapshot ('Test Project'), which would
+    // silently discard the external change.
+    expect(result.current.project.name).toBe('External')
+  })
+})
+
+describe('useProjectSync — subscription lifecycle', () => {
+  it('unsubscribes on unmount', () => {
+    const adapter = makeFakeAdapter()
+    const initial = makeProject()
+    const { unmount } = renderHook(() => useProjectSync(adapter, initial.id, initial))
+    unmount()
+    expect(adapter.unsub).toHaveBeenCalledTimes(1)
+  })
+})

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,
   }
 }