Merge branch 'master' into perf/stabilize-infinite-playback-engine

Author: 7se7en72025

CONTRIBUTING.md

@@ -6,7 +6,7 @@ is a community-driven project, and every meaningful contribution helps
 improve the platform for learners and educators around the world.
 
 If you’re new to the project, start by setting up the local
-development environment using the guide linked above, then explore
+development environment using the guide linked below, then explore
 open issues or discussions to find a place to contribute.
 
 - [How to set up a local server](README.md#how-to-set-up-a-local-server)
@@ -49,9 +49,13 @@ following resources:
 - [JavaScript tutorial - w3schools.com](https://www.w3schools.com/js/default.asp)
 - [JavaScript reference - MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript)
 
-Programmers, please follow these general [guidelines for
+For code contributions, please follow these general [guidelines for
 contributions](https://github.com/sugarlabs/sugar-docs/blob/master/src/contributing.md).
 
+### AI guidelines
+
+Follow [AI guidelines for Sugar Labs](https://github.com/sugarlabs/sugar-docs/blob/master/src/contributing.md#ai-guidelines-for-sugar-labs)
+
 ### Before You Push
 
 Run these commands locally before submitting a PR:

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.

css/activities.css

@@ -14,10 +14,15 @@
 
 @import url("play-only-mode.css");
 
-*:focus {
+*:focus:not(:focus-visible) {
   outline: none;
 }
 
+*:focus-visible {
+  outline: 2px solid #0066FF !important;
+  outline-offset: 2px;
+}
+
 body:not(.dark) #helpfulSearch,
 body:not(.dark) .ui-autocomplete {
   background-color: #fff !important;
@@ -509,6 +514,8 @@ div.back:active {
   position: absolute;
   top: 0;
   left: 0;
+
+  height: calc(var(--vh, 1vh) * 100);
 }
 
 .canvasHolder.hide {
@@ -623,7 +630,7 @@ nav ul li {
 
 #planet-iframe {
   width: 100vw;
-  height: 100vh;
+  height: calc(var(--vh, 1vh) * 100);
   background-color: #fff;
   position: absolute;
   top: 0;
@@ -633,6 +640,8 @@ nav ul li {
 iframe,
 canvas {
   overflow: clip !important;
+  width: 100%;
+  height: 100%;
 }
 
 .projectname {
@@ -1199,7 +1208,7 @@ table {
   left: 0 !important;
   border: 0 !important;
   overflow-x: hidden;
-  overflow-y: auto;
+  overflow: visible;
   width: calc(100% - 130px) !important;
   max-width: 350px;
   padding: 1rem 1rem 0 1rem;
@@ -1209,6 +1218,10 @@ table {
   align-items: center;
 }
 
+#helpScrollWrapper {
+  overflow-y: auto;
+}
+
 #helpBodyDiv .heading,
 #helpBodyDiv .description,
 #helpBodyDiv .message {