Refactor build pipeline for performance and config

Adopt esbuild minification, enable thread-loader by default,
and support parallel production builds while keeping cache
compression configurable.
Consolidate boolean env parsing, cache the Sass
implementation per process, and tune worker defaults for
more predictable build behavior.

Author: PeterDaveHello

.github/workflows/pre-release-build.yml

@@ -24,7 +24,20 @@ jobs:
       - uses: actions/setup-node@v6
         with:
           node-version: 20
+          cache: 'npm'
+          cache-dependency-path: '**/package-lock.json'
+      - name: Detect Node major version
+        run: echo "NODE_MAJOR=$(node -p 'process.versions.node.split(".")[0]')" >> $GITHUB_ENV
       - run: npm ci
+      - name: Cache Webpack filesystem cache
+        uses: actions/cache@v4
+        with:
+          path: |
+            .cache/webpack
+            node_modules/.cache/webpack
+          key: ${{ runner.os }}-node${{ env.NODE_MAJOR }}-webpack-${{ hashFiles('**/package-lock.json', 'build.mjs') }}
+          restore-keys: |
+            ${{ runner.os }}-node${{ env.NODE_MAJOR }}-webpack-
       - run: npm run build
 
       - uses: josStorer/get-current-time@v2

AGENTS.md

@@ -17,6 +17,25 @@ Always reference these instructions first and fall back to search or bash comman
 - Lint code: `npm run lint` -- uses ESLint.
 - Safari build: `npm run build:safari` (see Platform-Specific Instructions for details)
 
+### Build Performance Options
+
+- BUILD_PARALLEL: Toggle parallel build of production variants
+  - Default: on (parallel). Set to `0` to run sequentially (lower CPU/IO spikes on low-core machines)
+- BUILD_THREAD / BUILD_THREAD_WORKERS: Control Babel parallelism via thread-loader
+  - Default: threads enabled in dev/prod; workers = CPU cores
+  - Set `BUILD_THREAD=0` to disable; set `BUILD_THREAD_WORKERS=<n>` to override worker count
+- BUILD_CACHE_COMPRESSION: Webpack filesystem cache compression
+  - Default: `0` (no compression) for faster warm builds on CPU-bound SSD machines
+  - 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
+- 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
+
+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
 
 Production build creates multiple variants in `build/` directory: