fix: serialize theme preview uploads to avoid out-of-order reloads

Chokidar does not await async listeners, so rapid saves were kicking
off concurrent PUT /local_preview uploads. The reload broadcast
fired whenever each request resolved, which could leave the browser
reloading on a stale state. Gate uploads on a single in-flight flag
and coalesce events received during a run via a rerun flag that
retriggers once the current upload finishes.

Author: luis-almeida

packages/zcli-themes/src/commands/themes/preview.ts

@@ -99,8 +99,12 @@ export default class Preview extends Command {
       `${themePath}/style.css`
     ]
 
-    const handleThemeChange = async (path: string) => {
-      this.log(chalk.bold('Change'), path)
+    let previewing = false
+    let rerun = false
+
+    const runPreview = async () => {
+      previewing = true
+      rerun = false
       try {
         await preview(themePath, flags)
         wss.clients.forEach((client) => {
@@ -110,9 +114,18 @@ export default class Preview extends Command {
         })
       } catch (e) {
         this.error(e as Error, { exit: false })
+      } finally {
+        previewing = false
+        if (rerun) runPreview()
       }
     }
 
+    const handleThemeChange = (path: string) => {
+      this.log(chalk.bold('Change'), path)
+      if (previewing) rerun = true
+      else runPreview()
+    }
+
     const watcher = chokidar.watch(monitoredPaths, { ignoreInitial: true })
       .on('add', handleThemeChange)
       .on('change', handleThemeChange)

packages/zcli-themes/tests/functional/preview.test.ts

@@ -86,15 +86,23 @@ describe('themes:preview', function () {
       call.args[0]?.method === 'PUT'
     ).length
 
-    const waitForUploadCount = async (expected: number, timeoutMs = 2000) => {
+    const waitForUploadCount = async (expected: number, timeoutMs = 5000) => {
       const start = Date.now()
       while (previewUploadCalls() < expected && Date.now() - start < timeoutMs) {
         await new Promise(resolve => setTimeout(resolve, 50))
       }
     }
 
+    // chokidar may not have finished its initial scan when the test body
+    // runs. Wait until its events become observable before triggering the
+    // fs operations under test.
+    const waitForWatcherReady = async () => {
+      await new Promise(resolve => setTimeout(resolve, 200))
+    }
+
     preview
       .it('should revalidate when a new template partial is added', async () => {
+        await waitForWatcherReady()
         const initialCalls = previewUploadCalls()
         const partialsDir = path.join(baseThemePath, 'templates/partials')
         const partialPath = path.join(partialsDir, 'foo.hbs')
@@ -110,6 +118,7 @@ describe('themes:preview', function () {
 
     preview
       .it('should revalidate when an asset is deleted', async () => {
+        await waitForWatcherReady()
         const assetPath = path.join(baseThemePath, 'assets/bike.png')
         const assetContent = fs.readFileSync(assetPath)
         const initialCalls = previewUploadCalls()
@@ -121,6 +130,27 @@ describe('themes:preview', function () {
           fs.writeFileSync(assetPath, assetContent)
         }
       })
+
+    preview
+      .it('should serialize rapid successive changes instead of uploading concurrently', async () => {
+        await waitForWatcherReady()
+        const initialCalls = previewUploadCalls()
+        const partialsDir = path.join(baseThemePath, 'templates/partials')
+        fs.mkdirSync(partialsDir, { recursive: true })
+        const paths = ['a.hbs', 'b.hbs', 'c.hbs'].map(name => path.join(partialsDir, name))
+        try {
+          for (const p of paths) fs.writeFileSync(p, '<div/>')
+          await waitForUploadCount(initialCalls + 1)
+          // Let any queued rerun finish; a working serializer produces at
+          // most one in-flight upload plus one queued rerun.
+          await new Promise(resolve => setTimeout(resolve, 500))
+          const calls = previewUploadCalls() - initialCalls
+          expect(calls).to.be.greaterThan(0)
+          expect(calls).to.be.at.most(2)
+        } finally {
+          fs.rmSync(partialsDir, { recursive: true, force: true })
+        }
+      })
   })
 
   describe('validation errors', () => {