Build: polish dev DX and cache correctness; Docs tweaks

- Watch-once: await async callback before closing watcher/exiting
- Copy external source maps in development for CSP-safe debugging
- copyFiles: avoid TOCTOU by relying on fs.copy and handling ENOENT (dev CSS only)
- Use fs.ensureDir for idempotent targetDir creation
- Webpack filesystem cache: add lockfiles/package.json to buildDependencies
- Docs: fix list indentation and clarify performance defaults wording

Author: PeterDaveHello

.github/copilot-instructions.md

@@ -29,11 +29,11 @@ Always reference these instructions first and fall back to search or bash comman
   - Options: `0|false|none`, `gzip` (or `brotli` if explicitly desired)
   - Affects only `.cache/webpack` size/speed; does not change final artifacts
 - BUILD_WATCH_ONCE (dev): When set, `npm run dev` runs a single build and exits (useful for timing)
- - BUILD_POOL_TIMEOUT: Override thread-loader production pool timeout (ms)
-   - Default: `2000`. Increase if workers recycle too aggressively on slow machines/CI
+- BUILD_POOL_TIMEOUT: Override thread-loader production pool timeout (ms)
+  - Default: `2000`. Increase if workers recycle too aggressively on slow machines/CI
 
-Performance defaults: esbuild handles JS/CSS minification; in development CSS is injected via style-loader;
-in production CSS is extracted via MiniCssExtractPlugin; thread-loader is enabled by default in both dev and prod.
+Performance defaults: esbuild handles JS/CSS minification. In development, CSS is injected via style-loader;
+in production, CSS is extracted via MiniCssExtractPlugin. Thread-loader is enabled by default in both dev and prod.
 
 ### Build Output Structure
 

build.mjs

@@ -146,7 +146,11 @@ async function runWebpack(isWithoutKatex, isWithoutTiktoken, minimal, sourceBuil
       // default none; override via BUILD_CACHE_COMPRESSION=gzip|brotli
       compression: cacheCompressionOption ?? false,
       buildDependencies: {
-        config: [path.resolve('build.mjs')],
+        config: [
+          path.resolve('build.mjs'),
+          path.resolve('package.json'),
+          path.resolve('package-lock.json'),
+        ],
       },
     },
     optimization: {
@@ -391,14 +395,17 @@ async function runWebpack(isWithoutKatex, isWithoutTiktoken, minimal, sourceBuil
         err ||
         (stats && typeof stats.hasErrors === 'function' && stats.hasErrors())
       )
-      callback(err, stats)
+      const ret = callback(err, stats)
       if (process.env.BUILD_WATCH_ONCE) {
-        watching.close((closeErr) => {
-          if (closeErr) console.error('Error closing watcher:', closeErr)
-          // Exit explicitly to prevent hanging processes in CI
-          // Use non-zero exit code when errors occurred
-          process.exit(hasErrors || closeErr ? 1 : 0)
-        })
+        const finalize = () =>
+          watching.close((closeErr) => {
+            if (closeErr) console.error('Error closing watcher:', closeErr)
+            // Exit explicitly to prevent hanging processes in CI
+            // Use non-zero exit code when errors occurred
+            process.exit(hasErrors || closeErr ? 1 : 0)
+          })
+        if (ret && typeof ret.then === 'function') ret.then(finalize, finalize)
+        else finalize()
       }
     })
   }
@@ -421,27 +428,24 @@ async function zipFolder(dir) {
 }
 
 async function copyFiles(entryPoints, targetDir) {
-  if (!fs.existsSync(targetDir)) await fs.mkdir(targetDir, { recursive: true })
+  await fs.ensureDir(targetDir)
   await Promise.all(
     entryPoints.map(async (entryPoint) => {
       try {
-        if (await fs.pathExists(entryPoint.src)) {
-          await fs.copy(entryPoint.src, `${targetDir}/${entryPoint.dst}`)
-        } else {
-          // Skip missing CSS in development (placeholders will be created later)
-          const isCss = String(entryPoint.dst).endsWith('.css')
-          if (!isProduction || isCss) {
-            if (!isProduction && isCss) {
-              console.log(
-                `[build] Skipping missing CSS file: ${entryPoint.src} -> ${entryPoint.dst} (placeholder will be created)`,
-              )
-              return
-            }
+        await fs.copy(entryPoint.src, `${targetDir}/${entryPoint.dst}`)
+      } catch (e) {
+        const isCss = String(entryPoint.dst).endsWith('.css')
+        if (e && e.code === 'ENOENT') {
+          if (!isProduction && isCss) {
+            console.log(
+              `[build] Skipping missing CSS file: ${entryPoint.src} -> ${entryPoint.dst} (placeholder will be created)`,
+            )
+            return
           }
-          throw new Error(`Missing build artifact: ${entryPoint.src}`)
+          console.error('Missing build artifact:', entryPoint.src)
+        } else {
+          console.error('Copy failed:', entryPoint, e)
         }
-      } catch (e) {
-        console.error('Copy failed:', entryPoint, e)
         throw e
       }
     }),
@@ -466,6 +470,15 @@ async function finishOutput(outputDirSuffix, sourceBuildDir = outdir) {
 
     { src: `${sourceBuildDir}/IndependentPanel.js`, dst: 'IndependentPanel.js' },
     { src: 'src/pages/IndependentPanel/index.html', dst: 'IndependentPanel.html' },
+    // Dev-only: copy external source maps for CSP-safe debugging
+    ...(isProduction
+      ? []
+      : [
+          { src: `${sourceBuildDir}/content-script.js.map`, dst: 'content-script.js.map' },
+          { src: `${sourceBuildDir}/background.js.map`, dst: 'background.js.map' },
+          { src: `${sourceBuildDir}/popup.js.map`, dst: 'popup.js.map' },
+          { src: `${sourceBuildDir}/IndependentPanel.js.map`, dst: 'IndependentPanel.js.map' },
+        ]),
   ]
 
   // chromium