Refine build helpers and docs for recent feedback

- add env-controlled symlink resolution and clarify thread timeout rationale\n- harden cache compression parsing, Sass loader options, and CSS detection\n- document new BUILD_RESOLVE_SYMLINKS flag and validate build/dev flows\n\nTests: npm run build; BUILD_WATCH_ONCE=1 npm run dev

Author: PeterDaveHello

AGENTS.md

@@ -31,8 +31,9 @@ Always reference these instructions first and fall back to search or bash comman
 - 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_RESOLVE_SYMLINKS: When set to `1`/`true`, re-enable Webpack symlink resolution for `npm link`/pnpm workspace development (default off to avoid duplicate module instances)
 - Source maps (dev): Dev builds emit external `.map` files next to JS bundles for CSP-safe debugging; production builds disable source maps
-- Symlinks: Webpack uses `resolve.symlinks: false` to improve performance and ensure consistent module identity; if you rely on `npm link`/pnpm workspaces, temporarily enable symlink resolution while developing linked packages
+- Symlinks: Webpack uses `resolve.symlinks: false` to improve performance and ensure consistent module identity; use `BUILD_RESOLVE_SYMLINKS=1` when you need to work with linked dependencies locally
 
 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.mjs

@@ -39,7 +39,7 @@ const parallelBuild = getBooleanEnv(process.env.BUILD_PARALLEL, true)
 const isWatchOnce = getBooleanEnv(process.env.BUILD_WATCH_ONCE, false)
 // Cache compression control: default none; allow override via env
 function parseCacheCompressionOption(envVal) {
-  if (envVal == null) return undefined
+  if (envVal == null) return false
   const v = String(envVal).trim().toLowerCase()
   if (v === '' || v === '0' || v === 'false' || v === 'none') return false
   if (v === 'gzip' || v === 'brotli') return v
@@ -73,6 +73,7 @@ function parseThreadWorkerCount(envValue, cpuCount) {
 }
 const threadWorkers = parseThreadWorkerCount(process.env.BUILD_THREAD_WORKERS, cpuCount)
 // Thread-loader pool timeout constants (allow override via env)
+// Keep worker pool warm briefly to amortize repeated builds while still exiting quickly in CI
 let PRODUCTION_POOL_TIMEOUT_MS = 2000
 if (process.env.BUILD_POOL_TIMEOUT) {
   const n = parseInt(process.env.BUILD_POOL_TIMEOUT, 10)
@@ -86,6 +87,8 @@ if (process.env.BUILD_POOL_TIMEOUT) {
 }
 // Enable threads by default; allow disabling via BUILD_THREAD=0/false/no/off
 const enableThread = getBooleanEnv(process.env.BUILD_THREAD, true)
+// Allow opt-in symlink resolution for linked/workspace development when needed
+const resolveSymlinks = getBooleanEnv(process.env.BUILD_RESOLVE_SYMLINKS, false)
 
 // Cache and resolve Sass implementation once per process
 let sassImplPromise
@@ -173,7 +176,7 @@ async function runWebpack(isWithoutKatex, isWithoutTiktoken, minimal, sourceBuil
       // unnecessary cache invalidations across machines/CI runners
       version: JSON.stringify({ PROD: isProduction }),
       // default none; override via BUILD_CACHE_COMPRESSION=gzip|brotli
-      compression: cacheCompressionOption ?? false,
+      compression: cacheCompressionOption,
       buildDependencies: {
         config: [
           path.resolve('build.mjs'),
@@ -231,9 +234,8 @@ async function runWebpack(isWithoutKatex, isWithoutTiktoken, minimal, sourceBuil
     ],
     resolve: {
       extensions: ['.jsx', '.mjs', '.js'],
-      // Disable symlink resolution for consistent behavior/perf; note this can
-      // affect `npm link`/pnpm workspaces during local development
-      symlinks: false,
+      // Disable symlink resolution for consistent behavior/perf; enable via BUILD_RESOLVE_SYMLINKS=1 when working with linked deps
+      symlinks: resolveSymlinks,
       alias: {
         parse5: path.resolve(__dirname, 'node_modules/parse5'),
         ...(minimal
@@ -303,7 +305,12 @@ async function runWebpack(isWithoutKatex, isWithoutTiktoken, minimal, sourceBuil
             },
             {
               loader: 'sass-loader',
-              options: { implementation: sassImpl },
+              options: {
+                implementation: sassImpl,
+                sassOptions: {
+                  silentDeps: true,
+                },
+              },
             },
           ],
         },
@@ -510,7 +517,7 @@ async function copyFiles(entryPoints, targetDir) {
       try {
         await fs.copy(entryPoint.src, `${targetDir}/${entryPoint.dst}`)
       } catch (e) {
-        const isCss = String(entryPoint.dst).endsWith('.css')
+        const isCss = typeof entryPoint.dst === 'string' && entryPoint.dst.endsWith('.css')
         if (e && e.code === 'ENOENT') {
           if (!isProduction && isCss) {
             console.log(