Fix export stall when StageViewer is hidden in map mode (goplus#2968)

* fix: skip stage screenshots when preview is hidden

* refactor: tighten screenshot renderable guard

Author: nighca

spx-gui/src/components/editor/preview/stage-viewer/StageViewer.vue

@@ -471,10 +471,18 @@ function handleWheel(e: KonvaEventObject<WheelEvent>) {
 
 // TODO: implement a standalone screenshot taker which does not depend on StageViewer
 // See details in https://github.com/goplus/builder/issues/1807 .
+const canTakeScreenshot = computed(() => stageConfig.value != null)
+
+function ensureCanTakeScreenshot() {
+  if (!canTakeScreenshot.value) throw new Error('stage viewer is not renderable for screenshot')
+}
+
 async function takeScreenshot(name: string, signal?: AbortSignal) {
+  ensureCanTakeScreenshot()
   const stage = await untilNotNull(stageRef, signal)
   const nodeTransformer = await untilNotNull(nodeTransformerRef, signal)
   await until(() => !loading.value, signal)
+  ensureCanTakeScreenshot()
   // Omit transform control when taking screenshot
   const blob = await nodeTransformer.withHidden(
     () =>
@@ -488,6 +496,7 @@ async function takeScreenshot(name: string, signal?: AbortSignal) {
 }
 
 watchEffect((onCleanup) => {
+  if (!canTakeScreenshot.value) return
   const unbind = editorCtx.project.bindScreenshotTaker(takeScreenshot)
   onCleanup(unbind)
 })

spx-gui/src/models/spx/project.test.ts

@@ -7,13 +7,13 @@ import { fromText, toConfig, type Files } from '../common/file'
 import * as hashHelper from '../common/hash'
 import { Backdrop } from './backdrop'
 import { Monitor } from './widget/monitor'
-import { SpxProject, projectConfigFilePath, type RawProjectConfig } from './project'
+import { SpxProject, projectConfigFilePath, type RawProjectConfig, type ScreenshotTaker } from './project'
 
 function mockFile(name = 'mocked') {
   return fromText(name, Math.random() + '')
 }
 
-function makeProject() {
+function makeProject(screenshotTaker: ScreenshotTaker | null = async () => mockFile()) {
   const project = new SpxProject()
   const sound = new Sound('sound', mockFile())
   project.addSound(sound)
@@ -35,7 +35,7 @@ function makeProject() {
   const animation = Animation.create('default', animationCostumes)
   sprite.addAnimation(animation)
   project.addSprite(sprite)
-  project.bindScreenshotTaker(async () => mockFile())
+  if (screenshotTaker != null) project.bindScreenshotTaker(screenshotTaker)
   return project
 }
 
@@ -99,6 +99,20 @@ describe('Project', () => {
     expect(hash).toBe(hash2)
   })
 
+  it('should export with existing thumbnail after screenshot taker unbound', async () => {
+    const project = makeProject(null)
+    const thumbnail = mockFile('thumbnail')
+    const unbindScreenshotTaker = project.bindScreenshotTaker(async () => thumbnail)
+
+    // Schedule the debounced update first, then flush it immediately for a deterministic assertion.
+    project['updateThumbnail']()
+    await project['updateThumbnail'].flush()
+    unbindScreenshotTaker()
+
+    const { metadata } = await project.export()
+    expect(metadata.thumbnail).toBe(thumbnail)
+  })
+
   it('should move sprites correctly', async () => {
     const project = new SpxProject()
     const sprite1 = new Sprite('sprite1')