From 65e79afe5c7397dbb138d4f73111ef6c09d7fc1b Mon Sep 17 00:00:00 2001
From: Fabricio Giglio <58532944+gigliof@users.noreply.github.com>
Date: Fri, 29 May 2026 18:01:42 +0200
Subject: [PATCH] Add boot loading placeholder to cover cold-load window,
 lazy-load smplr off the critical path

---
 frontend/index.html                | 55 +++++++++++++++++++++++++++++-
 frontend/src/engine/AudioEngine.ts | 19 ++++++-----
 2 files changed, 65 insertions(+), 9 deletions(-)

diff --git a/frontend/index.html b/frontend/index.html
index 5d4823a..ebd62e0 100644
--- a/frontend/index.html
+++ b/frontend/index.html
@@ -15,9 +15,62 @@
     <link rel="preconnect" href="https://fonts.googleapis.com" />
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
     <link href="https://fonts.googleapis.com/css2?family=Space+Grotesk:wght@400;500;600;700&display=swap" rel="stylesheet" />
+    <script>
+      // Anti-flash + boot theme: apply the persisted/system theme to <html>
+      // BEFORE first paint, mirroring getInitialTheme() in the app exactly
+      // (localStorage "b2b-theme" -> prefers-color-scheme -> light fallback).
+      // React sets the same value on mount, so there's no conflict - this just
+      // makes the cold-load window (before the JS bundle parses) show the right
+      // background instead of a white flash. Wrapped in try/catch so a blocked
+      // localStorage (private mode) can never break boot.
+      (function () {
+        try {
+          var t = localStorage.getItem("b2b-theme");
+          if (t !== "dark" && t !== "light") {
+            t = window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+          }
+          document.documentElement.dataset.theme = t;
+        } catch (e) {
+          document.documentElement.dataset.theme = "light";
+        }
+      })();
+    </script>
+    <style>
+      /* Boot placeholder shown during the cold-load window (bundle download +
+         parse + service-worker install) before React mounts. Lives inside #root
+         so React's createRoot().render() replaces it automatically on first
+         render - no cleanup code needed. Inline so it works before the CSS
+         chunk loads. Colors mirror --color-bg (dark #1a1a2e / light #ffffff). */
+      html { background: #1a1a2e; }
+      html[data-theme="light"] { background: #ffffff; }
+      #b2b-boot {
+        position: fixed;
+        inset: 0;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        background: #1a1a2e;
+      }
+      html[data-theme="light"] #b2b-boot { background: #ffffff; }
+      #b2b-boot .b2b-spinner {
+        width: 38px;
+        height: 38px;
+        border-radius: 50%;
+        border: 3px solid rgba(147, 51, 234, 0.25);
+        border-top-color: #9333ea;
+        animation: b2b-spin 0.8s linear infinite;
+      }
+      @keyframes b2b-spin {
+        to {
+          transform: rotate(360deg);
+        }
+      }
+    </style>
   </head>
   <body>
-    <div id="root"></div>
+    <div id="root">
+      <div id="b2b-boot"><div class="b2b-spinner"></div></div>
+    </div>
     <!-- Error catcher: shows any unhandled JS error directly on screen -->
     <div id="error-overlay" style="display:none;position:fixed;inset:0;background:#1a0000;color:#ff6b6b;padding:24px;font:14px monospace;z-index:9999;white-space:pre-wrap;overflow:auto;"></div>
     <script>
diff --git a/frontend/src/engine/AudioEngine.ts b/frontend/src/engine/AudioEngine.ts
index e42d1af..6ea4f3c 100644
--- a/frontend/src/engine/AudioEngine.ts
+++ b/frontend/src/engine/AudioEngine.ts
@@ -1,4 +1,3 @@
-import { SplendidGrandPiano, Soundfont, ElectricPiano } from "smplr";
 import type { NoteEvent } from "@bach-to-basics/shared";
 
 // ── Instrument catalogue ──────────────────────────────────────────────────────
@@ -36,15 +35,19 @@ export type Player = {
 
 /**
  * Build a smplr player for the given instrument against any AudioContext-like.
- * Exported (not local) so the MP3 export pipeline can reuse it for an
- * OfflineAudioContext - same sample set / same instrument as live playback,
- * which is critical for the rendered audio to match what the user hears.
+ *
+ * smplr is imported DYNAMICALLY here (not at module top level) so it lands in
+ * its own lazy chunk instead of the main bundle. The piano keyboard (PixiJS),
+ * falling notes, and sheet music don't need smplr to render, so keeping it out
+ * of the critical path lets the first paint happen much sooner. smplr only
+ * loads on the first audio interaction (pre-warm on mount, or first note).
  *
  * Accepts `BaseAudioContext` (the common parent of both AudioContext and
- * OfflineAudioContext) rather than `AudioContext` alone, so callers can pass
- * an offline context for batch rendering. The smplr classes accept either.
+ * OfflineAudioContext) so callers can pass an offline context for batch
+ * rendering. The smplr classes accept either.
  */
-export function createPlayer(id: InstrumentId, ctx: BaseAudioContext): Player {
+export async function createPlayer(id: InstrumentId, ctx: BaseAudioContext): Promise<Player> {
+  const { SplendidGrandPiano, Soundfont, ElectricPiano } = await import("smplr");
   switch (id) {
     case "grand":
       return new SplendidGrandPiano(ctx as AudioContext) as unknown as Player;
@@ -79,7 +82,7 @@ export class AudioEngine {
     this._loadPromise = (async () => {
       try {
         if (!this.ctx) this.ctx = new AudioContext();
-        this.player = createPlayer(this._currentId, this.ctx);
+        this.player = await createPlayer(this._currentId, this.ctx);
         await this.player.load;
         this._loaded = true;
       } catch (err) {