You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
NOTE: Only run ```prettier``` on the files you have modified.
70
+
67
71
If formatting fails, run `npx prettier --write .` to fix it.
68
72
73
+
### After your PR is merged
74
+
75
+
Please note that production deployments of Music Blocks are **manual**.
76
+
77
+
This means that even after your pull request is merged, your changes may not immediately appear. Your update will become visible after the next official release is deployed.
78
+
79
+
If your changes are not visible right away, it does **not** indicate a problem with your PR or implementation.
80
+
81
+
This note is included to prevent contributors from spending time debugging caching or deployment issues unnecessarily.
82
+
69
83
### License Header
70
84
71
85
Music Blocks is licensed under the [AGPL](https://www.gnu.org/licenses/agpl-3.0.en.html).
This document explores a **lightweight investigation** of production build optimizations without introducing a full migration or breaking existing architecture.
12
+
13
+
## Current Behavior
14
+
- JavaScript and assets are largely served as individual files.
15
+
- No formal production bundling or minification strategy exists.
16
+
- Service worker caching must account for many independent assets (hundreds of individual JS files).
17
+
- RequireJS / AMD loading is the primary module system, which constrains conventional bundling approaches that expect ES modules or CommonJS.
18
+
19
+
## Analysis: Current State & Offline Impact
20
+
21
+
### Baseline Metrics (as of Feb 2026)
22
+
To provide a comparison reference for future optimizations:
-**Loading Model:** Sequential AMD loading, resulting in a deep waterfall of requests.
28
+
29
+
### Service Worker & Offline Caching
30
+
The current `sw.js` implementation follows a **stale-while-revalidate** pattern with significant constraints for offline reliability:
31
+
1.**Limited Pre-caching:** Only `index.html` is explicitly pre-cached. All other assets are cached dynamically upon first request.
32
+
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.
33
+
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.
34
+
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.
35
+
36
+
### Proposed Strategy (Groundwork)
37
+
This strategy focuses on low-risk, future-oriented thinking:
38
+
39
+
### 1. Selective Minification
40
+
Before full bundling, we can investigate minifying individual files during a "build" step.
41
+
- Reduces payload size without changing the loading model.
42
+
- Keep source maps for easier production debugging.
43
+
44
+
### 2. Asset Grouping (Low-Risk Experiment)
45
+
Instead of bundling everything into one file (which breaks RequireJS's dynamic loading), we can group "core" modules that are always loaded together.
46
+
- Example: `js/utils/utils.js`, `js/turtles.js`, and basic library wrappers.
47
+
48
+
### 3. Hashing/Versioning
49
+
Introduce a simple hashing mechanism for production assets to ensure service workers can reliably identify when an asset has changed.
50
+
51
+
### Running the Asset Analysis Script
52
+
53
+
From the repository root:
54
+
55
+
```bash
56
+
node scripts/analyze-production-assets.js
57
+
```
58
+
59
+
This script recursively scans the `js/` and `lib/` directories to report:
60
+
- Total JavaScript file count
61
+
- Aggregate size
62
+
- Estimated minification savings
63
+
64
+
No build step or configuration is required.
65
+
66
+
## Scope & Constraints
67
+
-**Documentation first:** This document serves as the primary outcome of this phase.
68
+
-**No replacement of RequireJS / AMD:** The current module system is deeply integrated and stable.
69
+
-**No build system overhaul:** Use existing Node.js scripts or lightweight tools if any implementation is attempted.
70
+
-**No runtime behavior changes:** The priority is stability.
71
+
72
+
## Next Steps / Roadmap
73
+
-[x] Audit total request count and asset sizes.
74
+
-[ ] Implement a lightweight minification pass for `js/` files in the `dist/` task.
75
+
-[ ] Research RequireJS `r.js` optimizer or modern alternatives (like Vite or esbuild) that can target AMD.
76
+
-[ ] Create a manifest for the Service Worker to enable reliable pre-caching of core assets.
0 commit comments