@pascal-app/editor 1.0.3 → 1.0.5

package/src/hooks/use-auto-save.integration.test.tsx

@@ -1,8 +1,11 @@
 import { afterEach, expect, test } from 'bun:test'
 import {
   BuildingNode,
+  beginScenePreview,
   ColumnNode,
   clearSceneHistory,
+  endScenePreview,
+  isScenePreviewing,
   LevelNode,
   SiteNode,
   useScene,
@@ -11,13 +14,16 @@ import { create } from '@react-three/test-renderer'
 import { type SaveStatus, useAutoSave } from './use-auto-save'
 
 const originalWindow = globalThis.window
+const originalRequestAnimationFrame = globalThis.requestAnimationFrame
 const previousScene = useScene.getState()
 let renderer: Awaited<ReturnType<typeof create>> | undefined
 
 afterEach(async () => {
+  endScenePreview()
   await renderer?.unmount()
   renderer = undefined
   globalThis.window = originalWindow
+  globalThis.requestAnimationFrame = originalRequestAnimationFrame
   useScene.setState(previousScene, true)
   clearSceneHistory()
 })
@@ -42,11 +48,8 @@ function graph(count: number) {
   return { nodes: Object.fromEntries(nodes.map((node) => [node.id, node])), rootNodeIds: [site.id] }
 }
 
-async function mount(
-  loadedCount: number,
-  guardAgainstSceneWipe?: boolean,
-  save?: () => Promise<void>,
-) {
+/** Mounts the hook in its initial state: a scene load not yet completed. */
+async function mountBeforeLoad(guardAgainstSceneWipe?: boolean, save?: () => Promise<void>) {
   globalThis.window = new EventTarget() as unknown as Window & typeof globalThis
   useScene.setState({ ...graph(0), readOnly: false })
   clearSceneHistory()
@@ -65,10 +68,6 @@ async function mount(
     return null
   }
   renderer = await create(<Host guardAgainstSceneWipe={guardAgainstSceneWipe} />)
-  useScene.setState(graph(loadedCount))
-  clearSceneHistory()
-  controls!.isLoadingSceneRef.current = false
-  statuses.length = 0
   return {
     writes,
     statuses,
@@ -78,31 +77,149 @@ async function mount(
   }
 }
 
-test.each([
-  'undo',
-  'redo',
-  'delete',
-] as const)('autosave permits a 5 to 4 single-node %s', async (action) => {
-  const { writes, statuses } = await mount(5)
-  if (action === 'undo') {
-    useScene.setState(graph(4))
-    clearSceneHistory()
-    useScene.setState(graph(5))
-    useScene.temporal.getState().undo()
-  } else if (action === 'redo') {
-    useScene.getState().deleteNode('column_autosave_1')
-    useScene.temporal.getState().undo()
-    useScene.temporal.getState().redo()
-  } else {
-    useScene.getState().deleteNode('column_autosave_1')
-  }
-  expect(Object.keys(useScene.getState().nodes)).toHaveLength(4)
+async function mount(
+  loadedCount: number,
+  guardAgainstSceneWipe?: boolean,
+  save?: () => Promise<void>,
+) {
+  const mounted = await mountBeforeLoad(guardAgainstSceneWipe, save)
+  useScene.setState(graph(loadedCount))
+  clearSceneHistory()
+  mounted.controls.completeSceneLoad()
+  mounted.statuses.length = 0
+  return mounted
+}
+
+/** The Editor's load sequence: begin, unload, hydrate the store, complete. */
+function loadScene(controls: ReturnType<typeof useAutoSave>, count: number) {
+  controls.beginSceneLoad()
+  useScene.getState().unloadScene()
+  hydrate(count)
+  controls.completeSceneLoad()
+}
+
+function hydrate(count: number) {
+  const { nodes, rootNodeIds } = graph(count)
+  useScene.getState().setScene(nodes as never, rootNodeIds as never)
+  clearSceneHistory()
+}
+
+function agentAddsColumn() {
+  useScene
+    .getState()
+    .createNode(
+      ColumnNode.parse({ id: 'column_agent', parentId: 'level_autosave' }),
+      'level_autosave' as never,
+    )
+}
+
+/** A hidden tab: requestAnimationFrame callbacks never run. */
+function hideDocument() {
+  const frames: FrameRequestCallback[] = []
+  globalThis.requestAnimationFrame = ((callback: FrameRequestCallback) => {
+    frames.push(callback)
+    return frames.length
+  }) as typeof requestAnimationFrame
+  return frames
+}
+
+test('a scene loaded in a hidden tab autosaves agent edits without waiting for a frame', async () => {
+  hideDocument()
+  const { writes, statuses, controls } = await mountBeforeLoad()
+  statuses.length = 0
+  // Pre-hydration document writes (the host-panel installedPlugins sync on
+  // mount) still must not arm a save of the empty store.
+  useScene.getState().setInstalledPlugins(['pre-hydration-default'], { explicit: false })
+  loadScene(controls, 12)
+  expect(statuses).toEqual([])
+
+  agentAddsColumn()
+  await Bun.sleep(1100)
+  expect(writes).toEqual([13])
+  expect(statuses.at(-1)).toBe('saved')
+})
+
+test('opening a scene and leaving it unchanged saves nothing', async () => {
+  const { writes, statuses, controls } = await mountBeforeLoad()
+  loadScene(controls, 12)
+  statuses.length = 0
+  // Mount-time writes after the load: systems re-marking nodes, and a plugin
+  // that registers late syncing the default plugin set.
+  useScene.getState().markDirty('level_autosave' as never)
+  useScene.getState().setInstalledPlugins(['late-default'], { explicit: false })
   await Bun.sleep(1100)
+  window.dispatchEvent(new Event('pagehide'))
+  expect(writes).toEqual([])
+  expect(statuses).toEqual([])
+})
+
+test('installing a plugin by hand after the load is saved', async () => {
+  const { writes, controls } = await mountBeforeLoad()
+  loadScene(controls, 12)
+  useScene.getState().setInstalledPlugins(['chosen'], { explicit: true })
+  await Bun.sleep(1100)
+  expect(writes).toEqual([12])
+})
+
+test('the exit flush writes an agent edit made right after a hidden load', async () => {
+  hideDocument()
+  const { writes, statuses, controls } = await mountBeforeLoad()
+  loadScene(controls, 12)
+  agentAddsColumn()
+  window.dispatchEvent(new Event('pagehide'))
+  expect(writes).toEqual([13])
   expect(statuses).not.toContain('error')
-  expect(writes).toEqual([4])
+})
+
+test('the exit flush still skips while a load is in flight', async () => {
+  const { writes, controls } = await mount(12)
+  agentAddsColumn()
+  controls.beginSceneLoad()
+  useScene.getState().unloadScene()
+  window.dispatchEvent(new Event('pagehide'))
+  expect(writes).toEqual([])
+})
+
+test('a save that came due mid-load is written once the load completes', async () => {
+  const { writes, statuses, controls } = await mount(12)
+  agentAddsColumn()
+  controls.beginSceneLoad()
+  useScene.getState().unloadScene()
+  await Bun.sleep(1100)
+  expect(writes).toEqual([])
+  expect(statuses.at(-1)).toBe('paused')
+
+  hydrate(12)
+  controls.completeSceneLoad()
+  await Bun.sleep(0)
+  expect(writes).toEqual([12])
   expect(statuses.at(-1)).toBe('saved')
 })
 
+test.each(['undo', 'redo', 'delete'] as const)(
+  'autosave permits a 5 to 4 single-node %s',
+  async (action) => {
+    const { writes, statuses } = await mount(5)
+    if (action === 'undo') {
+      useScene.setState(graph(4))
+      clearSceneHistory()
+      useScene.setState(graph(5))
+      useScene.temporal.getState().undo()
+    } else if (action === 'redo') {
+      useScene.getState().deleteNode('column_autosave_1')
+      useScene.temporal.getState().undo()
+      useScene.temporal.getState().redo()
+    } else {
+      useScene.getState().deleteNode('column_autosave_1')
+    }
+    expect(Object.keys(useScene.getState().nodes)).toHaveLength(4)
+    await Bun.sleep(1100)
+    expect(statuses).not.toContain('error')
+    expect(writes).toEqual([4])
+    expect(statuses.at(-1)).toBe('saved')
+  },
+)
+
 test('autosave permits a single-node deletion on exit', async () => {
   const { writes, statuses } = await mount(5)
   useScene.getState().deleteNode('column_autosave_1')
@@ -138,20 +255,20 @@ test('collaboration scaffold deletion waits for persistence and reports saved',
   expect(statuses).toEqual(['pending', 'saving', 'saved'])
 })
 
-test.each([
-  'pagehide',
-  'unmount',
-])('collaboration scaffold deletion still flushes on %s', async (event) => {
-  const { writes, statuses } = await mount(78, false)
-  useScene.setState(graph(4))
-  if (event === 'pagehide') window.dispatchEvent(new Event(event))
-  else {
-    await renderer!.unmount()
-    renderer = undefined
-  }
-  expect(statuses).not.toContain('error')
-  expect(writes).toEqual([4])
-})
+test.each(['pagehide', 'unmount'])(
+  'collaboration scaffold deletion still flushes on %s',
+  async (event) => {
+    const { writes, statuses } = await mount(78, false)
+    useScene.setState(graph(4))
+    if (event === 'pagehide') window.dispatchEvent(new Event(event))
+    else {
+      await renderer!.unmount()
+      renderer = undefined
+    }
+    expect(statuses).not.toContain('error')
+    expect(writes).toEqual([4])
+  },
+)
 
 test('collaboration guard exemption preserves preview pause and resume', async () => {
   const { writes, statuses, update } = await mount(78, false)
@@ -195,3 +312,58 @@ test('collaboration callback failures still report error', async () => {
   expect(writes).toEqual([4])
   expect(statuses).toEqual(['pending', 'saving', 'error'])
 })
+
+// A scene preview (the scene as it was before an agent's turn, shown while a control is held) is not
+// an edit: it must reach neither the server nor the exit flush, and must not leave a save armed.
+const beforeLastEdit = () => useScene.temporal.getState().pastStates.at(-1) as never
+
+test('a held preview saves nothing and leaves nothing to save', async () => {
+  const { writes } = await mount(12)
+  agentAddsColumn()
+  await Bun.sleep(1100)
+  expect(writes).toEqual([13])
+
+  const preview = beginScenePreview(beforeLastEdit())
+  expect(Object.keys(useScene.getState().nodes)).toHaveLength(12)
+  await Bun.sleep(1100)
+  preview?.end()
+  await Bun.sleep(1100)
+
+  expect(writes).toEqual([13])
+})
+
+test('an edit that came due under a held preview is written after it, from the live scene', async () => {
+  const { writes } = await mount(12)
+  agentAddsColumn()
+  const preview = beginScenePreview(beforeLastEdit())
+  await Bun.sleep(1100)
+  expect(writes).toEqual([])
+
+  preview?.end()
+  await Bun.sleep(10)
+
+  expect(writes).toEqual([13])
+})
+
+test('leaving the page under a held preview writes the live scene, not the preview', async () => {
+  const { writes } = await mount(12)
+  agentAddsColumn()
+  beginScenePreview(beforeLastEdit())
+
+  window.dispatchEvent(new Event('pagehide'))
+
+  expect(isScenePreviewing()).toBe(false)
+  expect(writes).toEqual([13])
+})
+
+test('the save shortcut under a held preview writes the live scene', async () => {
+  const { writes, controls } = await mount(12)
+  agentAddsColumn()
+  beginScenePreview(beforeLastEdit())
+
+  controls.saveNow()
+  await Bun.sleep(0)
+
+  expect(isScenePreviewing()).toBe(false)
+  expect(writes).toEqual([13])
+})

package/src/hooks/use-auto-save.ts

@@ -1,8 +1,13 @@
 'use client'
 
-import { useScene } from '@pascal-app/core'
-import { type MutableRefObject, useCallback, useEffect, useRef } from 'react'
-import { type SceneGraph, saveSceneToLocalStorage } from '../lib/scene'
+import {
+  endScenePreview,
+  isScenePreviewing,
+  subscribeScenePreview,
+  useScene,
+} from '@pascal-app/core'
+import { useCallback, useEffect, useRef } from 'react'
+import { getSavedSceneDocument, type SceneGraph, saveSceneToLocalStorage } from '../lib/scene'
 
 const AUTOSAVE_DEBOUNCE_MS = 1000
 const STRUCTURAL_NODE_COUNT = 4
@@ -105,7 +110,8 @@ export function useAutoSave({
   onSaveStatusChange,
   isVersionPreviewMode = false,
 }: UseAutoSaveOptions): {
-  isLoadingSceneRef: MutableRefObject<boolean>
+  beginSceneLoad: () => void
+  completeSceneLoad: () => void
   saveNow: () => void
 } {
   const saveTimeoutRef = useRef<NodeJS.Timeout | undefined>(undefined)
@@ -163,13 +169,19 @@ export function useAutoSave({
     let lastInstalledPluginsRef = useScene.getState().installedPlugins
 
     async function executeSave() {
+      // A held scene preview is on screen, not in the document: wait for it to end.
+      if (isScenePreviewing()) {
+        pendingSaveRef.current = true
+        return
+      }
       if (isLoadingSceneRef.current || isVersionPreviewModeRef.current) {
         pendingSaveRef.current = true
         setSaveStatus('paused')
         return
       }
 
-      const { nodes, rootNodeIds, collections, materials, installedPlugins } = useScene.getState()
+      const { nodes, rootNodeIds, collections, materials, installedPlugins } =
+        getSavedSceneDocument()
       const sceneGraph = {
         nodes,
         rootNodeIds,
@@ -228,6 +240,10 @@ export function useAutoSave({
         return
       }
 
+      // The store shows another state for a moment: it is not a change, and the live scene it
+      // gives back is what the last snapshot already holds.
+      if (isScenePreviewing()) return
+
       if (isVersionPreviewModeRef.current) {
         setSaveStatus('paused')
         lastNodesSnapshot = JSON.stringify(state.nodes)
@@ -237,18 +253,23 @@ export function useAutoSave({
         return
       }
 
+      // A plugin set the user never chose is the host's defaults, re-derived on
+      // every load: a plugin registering after the load (hosted plugins arrive
+      // late) syncs it without anyone editing the scene.
+      const pluginsEdited =
+        state.installedPlugins !== lastInstalledPluginsRef && state.hasExplicitPluginInstallState
+      lastInstalledPluginsRef = state.installedPlugins
       const currentNodesSnapshot = JSON.stringify(state.nodes)
       const changed =
         currentNodesSnapshot !== lastNodesSnapshot ||
         state.collections !== lastCollectionsRef ||
         state.materials !== lastMaterialsRef ||
-        state.installedPlugins !== lastInstalledPluginsRef
+        pluginsEdited
       if (!changed) return
 
       lastNodesSnapshot = currentNodesSnapshot
       lastCollectionsRef = state.collections
       lastMaterialsRef = state.materials
-      lastInstalledPluginsRef = state.installedPlugins
       hasDirtyChangesRef.current = true
       onDirtyRef.current?.()
       setSaveStatus('pending')
@@ -272,7 +293,10 @@ export function useAutoSave({
     // would otherwise drop the change entirely. `pagehide` fires in cases
     // (mobile Safari, bfcache) where `beforeunload` does not.
     function flushOnExit() {
-      const { nodes, rootNodeIds, collections, materials, installedPlugins } = useScene.getState()
+      // What is on screen may be a preview: write the live scene, never that.
+      endScenePreview()
+      const { nodes, rootNodeIds, collections, materials, installedPlugins } =
+        getSavedSceneDocument()
       const currentNodeCount = Object.keys(nodes).length
       const previousNodeCount = storedNodeCount.count
       const decision = decideExitFlush({
@@ -317,7 +341,15 @@ export function useAutoSave({
     window.addEventListener('beforeunload', flushOnExit)
     window.addEventListener('pagehide', flushOnExit)
 
+    // A save that came due under a held preview was deferred; the live scene is back.
+    const stopWatchingPreview = subscribeScenePreview((previewing) => {
+      if (previewing || !pendingSaveRef.current || isSavingRef.current) return
+      if (isLoadingSceneRef.current || saveTimeoutRef.current) return
+      executeSaveRef.current?.()
+    })
+
     return () => {
+      stopWatchingPreview()
       executeSaveRef.current = null
       window.removeEventListener('beforeunload', flushOnExit)
       window.removeEventListener('pagehide', flushOnExit)
@@ -362,6 +394,7 @@ export function useAutoSave({
   // in the loop. A write already in flight only arms the follow-up.
   const saveNow = useCallback(() => {
     if (isLoadingSceneRef.current) return
+    endScenePreview()
 
     if (saveTimeoutRef.current) {
       clearTimeout(saveTimeoutRef.current)
@@ -376,5 +409,23 @@ export function useAutoSave({
     executeSaveRef.current?.()
   }, [])
 
-  return { isLoadingSceneRef, saveNow }
+  const beginSceneLoad = useCallback(() => {
+    isLoadingSceneRef.current = true
+  }, [])
+
+  // Call as soon as the store holds the loaded graph — hydration is data, not
+  // a frame. Gating this on requestAnimationFrame kept a tab loaded while
+  // hidden (no frames ever run) "loading" indefinitely: every later edit was
+  // adopted as the loaded baseline, so nothing autosaved and the exit flush
+  // had nothing dirty to write.
+  const completeSceneLoad = useCallback(() => {
+    isLoadingSceneRef.current = false
+    // A save that came due mid-load was deferred; the store now holds real
+    // data, so write it rather than leave the status parked on 'paused'.
+    if (pendingSaveRef.current && !isSavingRef.current && !saveTimeoutRef.current) {
+      executeSaveRef.current?.()
+    }
+  }, [])
+
+  return { beginSceneLoad, completeSceneLoad, saveNow }
 }