From f78c8a88715f06162aeff89dbc9c2ec6f4433aa0 Mon Sep 17 00:00:00 2001
From: 69520 <yan.zhu@bangdao-tech.com>
Date: Tue, 23 Jun 2026 17:44:52 +0800
Subject: [PATCH] feat(miku-web): add branded boot screen with loading progress
 and error states

Replace the blank loading canvas with a styled boot panel that shows
progress, startup steps, and clear error messaging when the wasm runtime
fails to initialize. The Rust web entrypoint now signals ready/failed
state to the DOM so the loading overlay fades out on success or surfaces
the underlying error on failure.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 crates/miku-web/index.html | 306 ++++++++++++++++++++++++++++++++++++-
 crates/miku-web/src/lib.rs |  71 ++++++++-
 2 files changed, 372 insertions(+), 5 deletions(-)

diff --git a/crates/miku-web/index.html b/crates/miku-web/index.html
index ce01b6a..4f86c34 100644
--- a/crates/miku-web/index.html
+++ b/crates/miku-web/index.html
@@ -5,6 +5,20 @@
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <title>Miku</title>
     <style>
+      :root {
+        color-scheme: dark;
+        --miku-bg: #0f1115;
+        --miku-panel-border: #2b313a;
+        --miku-text: #edf2f7;
+        --miku-muted: #9aa7b5;
+        --miku-faint: #66717f;
+        --miku-accent: #55d08a;
+        --miku-accent-strong: #90f0b8;
+        --miku-warn: #f4bd50;
+        --miku-error: #ff6b6b;
+        --miku-grid: rgba(255, 255, 255, 0.045);
+      }
+
       html,
       body,
       canvas {
@@ -15,20 +29,306 @@
 
       body {
         overflow: hidden;
-        background: #0f1115;
+        background:
+          linear-gradient(var(--miku-grid) 1px, transparent 1px),
+          linear-gradient(90deg, var(--miku-grid) 1px, transparent 1px),
+          var(--miku-bg);
+        background-size:
+          42px 42px,
+          42px 42px,
+          auto;
+        color: var(--miku-text);
+        font-family:
+          ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI",
+          sans-serif;
       }
 
       canvas {
         display: block;
+        opacity: 0;
+        transition: opacity 220ms ease;
+      }
+
+      #miku-loading {
+        position: fixed;
+        inset: 0;
+        z-index: 10;
+        display: grid;
+        place-items: center;
+        padding: 28px;
+        box-sizing: border-box;
+        background:
+          linear-gradient(180deg, rgba(15, 17, 21, 0.88), rgba(15, 17, 21, 0.98)),
+          var(--miku-bg);
+        transition:
+          opacity 260ms ease,
+          visibility 260ms ease;
+      }
+
+      .boot-panel {
+        width: min(440px, 100%);
+        box-sizing: border-box;
+        padding: 28px;
+        border: 1px solid var(--miku-panel-border);
+        border-radius: 8px;
+        background: rgba(23, 26, 32, 0.92);
+        box-shadow: 0 24px 80px rgba(0, 0, 0, 0.32);
+      }
+
+      .brand-row {
+        display: flex;
+        align-items: center;
+        gap: 14px;
+        margin-bottom: 28px;
+      }
+
+      .brand-mark {
+        position: relative;
+        width: 48px;
+        height: 48px;
+        flex: 0 0 auto;
+        border: 1px solid rgba(85, 208, 138, 0.5);
+        border-radius: 8px;
+        background: #11161a;
+      }
+
+      .brand-mark::before,
+      .brand-mark::after {
+        position: absolute;
+        content: "";
+        background: var(--miku-accent);
+      }
+
+      .brand-mark::before {
+        inset: 12px 14px;
+        border-radius: 999px;
+        box-shadow:
+          -9px 7px 0 -3px var(--miku-accent-strong),
+          9px 7px 0 -3px var(--miku-accent-strong);
+      }
+
+      .brand-mark::after {
+        left: 15px;
+        right: 15px;
+        bottom: 9px;
+        height: 3px;
+        border-radius: 999px;
+        background: var(--miku-warn);
+      }
+
+      .eyebrow {
+        margin: 0 0 3px;
+        color: var(--miku-muted);
+        font-size: 12px;
+        letter-spacing: 0;
+        text-transform: uppercase;
+      }
+
+      h1 {
+        margin: 0;
+        color: var(--miku-text);
+        font-size: 32px;
+        font-weight: 700;
+        line-height: 1.05;
+        letter-spacing: 0;
+      }
+
+      .loading-message {
+        min-height: 28px;
+        margin: 0 0 18px;
+        color: var(--miku-text);
+        font-size: 18px;
+        line-height: 1.55;
+      }
+
+      .progress {
+        height: 3px;
+        overflow: hidden;
+        border-radius: 999px;
+        background: #29303a;
+      }
+
+      .progress span {
+        display: block;
+        width: 46%;
+        height: 100%;
+        border-radius: inherit;
+        background: var(--miku-accent);
+        animation: miku-progress 1.35s cubic-bezier(0.65, 0, 0.35, 1) infinite;
+      }
+
+      .boot-steps {
+        display: grid;
+        grid-template-columns: repeat(3, minmax(0, 1fr));
+        gap: 12px;
+        margin: 22px 0 0;
+        padding: 0;
+        color: var(--miku-muted);
+        font-size: 13px;
+        list-style: none;
+      }
+
+      .boot-steps li {
+        display: flex;
+        min-width: 0;
+        align-items: center;
+        gap: 8px;
+        white-space: nowrap;
+      }
+
+      .boot-steps span {
+        width: 8px;
+        height: 8px;
+        flex: 0 0 auto;
+        border-radius: 999px;
+        background: var(--miku-accent);
+        animation: miku-pulse 1.4s ease-in-out infinite;
+      }
+
+      .boot-steps li:nth-child(2) span {
+        animation-delay: 180ms;
+      }
+
+      .boot-steps li:nth-child(3) span {
+        animation-delay: 360ms;
+      }
+
+      .loading-detail {
+        min-height: 20px;
+        margin: 18px 0 0;
+        color: var(--miku-faint);
+        font-size: 13px;
+        line-height: 1.55;
+      }
+
+      .miku-ready canvas {
+        opacity: 1;
+      }
+
+      .miku-ready #miku-loading {
+        visibility: hidden;
+        opacity: 0;
+        pointer-events: none;
+      }
+
+      .miku-boot-error #miku-loading {
+        background: var(--miku-bg);
+      }
+
+      .miku-boot-error .brand-mark,
+      .miku-boot-error .progress span,
+      .miku-boot-error .boot-steps span {
+        border-color: rgba(255, 107, 107, 0.5);
+        background: var(--miku-error);
+        animation: none;
+      }
+
+      .miku-boot-error .loading-message,
+      .miku-boot-error .loading-detail {
+        color: var(--miku-error);
+      }
+
+      @media (max-width: 520px) {
+        #miku-loading {
+          padding: 18px;
+        }
+
+        .boot-panel {
+          padding: 22px;
+        }
+
+        .boot-steps {
+          grid-template-columns: 1fr;
+        }
+      }
+
+      @media (prefers-reduced-motion: reduce) {
+        *,
+        *::before,
+        *::after {
+          animation-duration: 1ms !important;
+          animation-iteration-count: 1 !important;
+          scroll-behavior: auto !important;
+          transition-duration: 1ms !important;
+        }
+      }
+
+      @keyframes miku-progress {
+        0% {
+          transform: translateX(-105%);
+        }
+        100% {
+          transform: translateX(235%);
+        }
+      }
+
+      @keyframes miku-pulse {
+        0%,
+        100% {
+          opacity: 0.45;
+          transform: scale(0.82);
+        }
+        45% {
+          opacity: 1;
+          transform: scale(1);
+        }
       }
     </style>
     <script type="module">
-      import init from "./miku_web.js";
+      const root = document.documentElement;
+      const loadingMessage = document.getElementById("miku-loading-message");
+      const loadingDetail = document.getElementById("miku-loading-detail");
+      const formatError = (error) => {
+        if (error instanceof Error && error.message) {
+          return error.message;
+        }
+        if (typeof error === "string") {
+          return error;
+        }
+        return String(error);
+      };
 
-      await init();
+      try {
+        root.dataset.mikuBoot = "wasm-loading";
+        const { default: init } = await import("./miku_web.js");
+        await init();
+        root.dataset.mikuBoot = "app-starting";
+        if (loadingDetail) {
+          loadingDetail.textContent = "Starting Miku workspace";
+        }
+      } catch (error) {
+        console.error("failed to load Miku web runtime", error);
+        root.classList.add("miku-boot-error");
+        root.dataset.mikuBoot = "failed";
+        if (loadingMessage) {
+          loadingMessage.textContent = "Miku could not start";
+        }
+        if (loadingDetail) {
+          loadingDetail.textContent = formatError(error);
+        }
+      }
     </script>
   </head>
   <body>
+    <main id="miku-loading" aria-live="polite" aria-busy="true">
+      <section class="boot-panel" aria-labelledby="miku-loading-title">
+        <div class="brand-row">
+          <div class="brand-mark" aria-hidden="true"></div>
+          <div>
+            <p class="eyebrow">Miku Web</p>
+            <h1 id="miku-loading-title">Miku</h1>
+          </div>
+        </div>
+        <p id="miku-loading-message" class="loading-message">Preparing workspace</p>
+        <div class="progress" aria-hidden="true"><span></span></div>
+        <ul class="boot-steps" aria-label="Startup progress">
+          <li><span aria-hidden="true"></span>Web shell</li>
+          <li><span aria-hidden="true"></span>Runtime</li>
+          <li><span aria-hidden="true"></span>Services</li>
+        </ul>
+        <p id="miku-loading-detail" class="loading-detail">Loading WebAssembly runtime</p>
+      </section>
+    </main>
     <canvas id="miku-canvas"></canvas>
   </body>
 </html>
diff --git a/crates/miku-web/src/lib.rs b/crates/miku-web/src/lib.rs
index c595a84..dfcda5c 100644
--- a/crates/miku-web/src/lib.rs
+++ b/crates/miku-web/src/lib.rs
@@ -24,7 +24,8 @@ impl WebHandle {
     #[wasm_bindgen]
     pub async fn start(&self, canvas: web_sys::HtmlCanvasElement) -> Result<(), JsValue> {
         tracing::info!("starting web app");
-        self.runner
+        let result = self
+            .runner
             .start(
                 canvas,
                 eframe::WebOptions::default(),
@@ -37,7 +38,14 @@ impl WebHandle {
                     Ok(Box::new(app))
                 }),
             )
-            .await
+            .await;
+
+        match &result {
+            Ok(()) => mark_loading_ready(),
+            Err(error) => mark_loading_failed(error),
+        }
+
+        result
     }
 
     #[wasm_bindgen]
@@ -87,3 +95,62 @@ fn web_app() -> Result<miku_ui::MikuApp, String> {
         client,
     )))
 }
+
+#[cfg(target_arch = "wasm32")]
+fn mark_loading_ready() {
+    let Some(document) = browser_document() else {
+        return;
+    };
+
+    if let Some(root) = document.document_element() {
+        add_class(&root, "miku-ready");
+        let _ = root.set_attribute("data-miku-boot", "ready");
+    }
+
+    if let Some(loading) = document.get_element_by_id("miku-loading") {
+        let _ = loading.set_attribute("aria-busy", "false");
+    }
+}
+
+#[cfg(target_arch = "wasm32")]
+fn mark_loading_failed(error: &JsValue) {
+    let Some(document) = browser_document() else {
+        return;
+    };
+
+    if let Some(root) = document.document_element() {
+        add_class(&root, "miku-boot-error");
+        let _ = root.set_attribute("data-miku-boot", "failed");
+    }
+
+    if let Some(message) = document.get_element_by_id("miku-loading-message") {
+        message.set_text_content(Some("Miku could not start"));
+    }
+
+    if let Some(detail) = document.get_element_by_id("miku-loading-detail") {
+        detail.set_text_content(Some(&format!("{error:?}")));
+    }
+}
+
+#[cfg(target_arch = "wasm32")]
+fn browser_document() -> Option<web_sys::Document> {
+    web_sys::window()?.document()
+}
+
+#[cfg(target_arch = "wasm32")]
+fn add_class(element: &web_sys::Element, class_name: &str) {
+    let classes = element.class_name();
+    if classes
+        .split_ascii_whitespace()
+        .any(|current| current == class_name)
+    {
+        return;
+    }
+
+    let next_classes = if classes.is_empty() {
+        class_name.to_owned()
+    } else {
+        format!("{classes} {class_name}")
+    };
+    element.set_class_name(&next_classes);
+}