Chore/production build optimization (#5532)

* chore: production build optimization strategy (groundwork)

Investigate current asset structure and document strategy for future performance and offline improvements.

- Added Docs/PRODUCTION_BUILD_STRATEGY.md for architectural roadmap.
- Added scripts/analyze-production-assets.js for data-driven asset auditing.
- Recovered Docs/GLOBAL_STATE_AUDIT.md for completeness.

* docs: add baseline metrics and SW analysis to production strategy

Author: vanshika2720

Docs/PRODUCTION_BUILD_STRATEGY.md

@@ -0,0 +1,76 @@
+# Production Build Optimization Strategy: Architecture & Performance
+
+## Why
+Music Blocks currently serves mostly unbundled, raw JavaScript and asset files. 
+While this works in development, it introduces limitations for:
+- Production performance (high HTTP request count)
+- Predictable offline caching
+- Service worker reliability
+- Long-term maintainability alongside AMD-based loading
+
+This document explores a **lightweight investigation** of production build optimizations without introducing a full migration or breaking existing architecture.
+
+## Current Behavior
+- JavaScript and assets are largely served as individual files.
+- No formal production bundling or minification strategy exists.
+- Service worker caching must account for many independent assets (hundreds of individual JS files).
+- RequireJS / AMD loading is the primary module system, which constrains conventional bundling approaches that expect ES modules or CommonJS.
+
+## Analysis: Current State & Offline Impact
+
+### Baseline Metrics (as of Feb 2026)
+To provide a comparison reference for future optimizations:
+- **Total JavaScript Request Count:** ~248 files (209 Application, 39 Libraries).
+- **Total JavaScript Size (Uncompressed):** ~12.94 MB.
+- **Application Logic (`js/`):** 209 files, 6.42 MB.
+- **Libraries (`lib/`):** 39 files, 6.52 MB.
+- **Loading Model:** Sequential AMD loading, resulting in a deep waterfall of requests.
+
+### Service Worker & Offline Caching
+The current `sw.js` implementation follows a **stale-while-revalidate** pattern with significant constraints for offline reliability:
+1. **Limited Pre-caching:** Only `index.html` is explicitly pre-cached. All other assets are cached dynamically upon first request.
+2. **Fragmentation:** Caching 200+ individual JS files increases the risk of partial cache states (where some files are cached and others are not), leading to runtime errors in offline mode.
+3. **Implicit Dependencies:** If the service worker fails to intercept a single AMD dependency (e.g., due to a network blip), the entire module fails to load.
+4. **Cache Invalidation:** Without content hashing, ensuring users receive the latest version of a file depends on the browser's fetch behavior and the SW's revalidation logic, which can be inconsistent.
+
+### Proposed Strategy (Groundwork)
+This strategy focuses on low-risk, future-oriented thinking:
+
+### 1. Selective Minification
+Before full bundling, we can investigate minifying individual files during a "build" step.
+- Reduces payload size without changing the loading model.
+- Keep source maps for easier production debugging.
+
+### 2. Asset Grouping (Low-Risk Experiment)
+Instead of bundling everything into one file (which breaks RequireJS's dynamic loading), we can group "core" modules that are always loaded together.
+- Example: `js/utils/utils.js`, `js/turtles.js`, and basic library wrappers.
+
+### 3. Hashing/Versioning
+Introduce a simple hashing mechanism for production assets to ensure service workers can reliably identify when an asset has changed.
+
+### Running the Asset Analysis Script
+
+From the repository root:
+
+```bash
+node scripts/analyze-production-assets.js
+```
+
+This script recursively scans the `js/` and `lib/` directories to report:
+- Total JavaScript file count
+- Aggregate size
+- Estimated minification savings
+
+No build step or configuration is required.
+
+## Scope & Constraints
+- **Documentation first:** This document serves as the primary outcome of this phase.
+- **No replacement of RequireJS / AMD:** The current module system is deeply integrated and stable.
+- **No build system overhaul:** Use existing Node.js scripts or lightweight tools if any implementation is attempted.
+- **No runtime behavior changes:** The priority is stability.
+
+## Next Steps / Roadmap
+- [x] Audit total request count and asset sizes.
+- [ ] Implement a lightweight minification pass for `js/` files in the `dist/` task.
+- [ ] Research RequireJS `r.js` optimizer or modern alternatives (like Vite or esbuild) that can target AMD.
+- [ ] Create a manifest for the Service Worker to enable reliable pre-caching of core assets.

scripts/analyze-production-assets.js

@@ -0,0 +1,64 @@
+/**
+ * SPDX-License-Identifier: MIT
+ * Copyright (c) 2026 Sugar Labs
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { execSync } = require("child_process");
+
+/**
+ * Proof of Concept: Asset Analysis & Minification Groundwork
+ * This script investigates the current asset structure and estimates
+ * potential gains from a formal production build process.
+ */
+
+const JS_DIR = path.join(__dirname, "../js");
+const LIB_DIR = path.join(__dirname, "../lib");
+
+function getFiles(dir, extension) {
+    let results = [];
+    const list = fs.readdirSync(dir);
+    list.forEach(file => {
+        file = path.join(dir, file);
+        const stat = fs.statSync(file);
+        if (stat && stat.isDirectory()) {
+            results = results.concat(getFiles(file, extension));
+        } else if (file.endsWith(extension)) {
+            results.push(file);
+        }
+    });
+    return results;
+}
+
+function analyzeDir(name, dir) {
+    console.log(`--- Analyzing ${name} ---`);
+    const files = getFiles(dir, ".js");
+    let totalSize = 0;
+
+    files.forEach(file => {
+        const stats = fs.statSync(file);
+        totalSize += stats.size;
+    });
+
+    console.log(`Count: ${files.length} files`);
+    console.log(`Total Size: ${(totalSize / 1024 / 1024).toFixed(2)} MB`);
+
+    // Estimate minification (conservative 30% reduction)
+    console.log(
+        `Estimated Minified Size: ${((totalSize * 0.7) / 1024 / 1024).toFixed(2)} MB (-30%)`
+    );
+}
+
+console.log("Music Blocks Production Build Optimization Strategy - Investigation Phase\n");
+analyzeDir("Application Logic (js/)", JS_DIR);
+console.log("");
+analyzeDir("Third-party Libraries (lib/)", LIB_DIR);
+
+console.log("\n--- Strategic Recommendations ---");
+console.log("1. Selective Bundling: Grouping the 200+ JS files into 3-5 logical chunks.");
+console.log("2. Content Hashing: Using hashes (e.g., style.[hash].css) for better SW caching.");
+console.log("3. AMD Optimization: Using r.js or a modern equivalent to trace dependencies.");
+console.log(
+    "4. Pre-minification: Shipping minified versions of large files like artwork.js and activity.js."
+);