beauticode-dsh 1.0.16 → 1.0.18

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 beautiCode contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/client.js

@@ -8,9 +8,16 @@
     globalThis.crypto?.randomUUID?.() ||
     `bc-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
   const desiredModes = { fish: false, muted: true, tone: "auto" };
-  const IMAGE_LOAD_TIMEOUT_MS = 12_000;
-  const VIDEO_STARTUP_TIMEOUT_MS = 20_000;
-  const DSH_STRUCTURE_TIMEOUT_MS = 10_000;
+  // The DSH host owns a hard 10-second verification boundary. Keep the browser
+  // transaction inside it so failures remain phase-specific instead of turning
+  // into a generic host timeout.
+  const CLIENT_APPLY_DEADLINE_MS = 8_000;
+  const IMAGE_LOAD_TIMEOUT_MS = CLIENT_APPLY_DEADLINE_MS;
+  const IMAGE_ATTEMPT_TIMEOUT_MS = 3_000;
+  const IMAGE_MAX_ATTEMPTS = 2;
+  const VIDEO_STARTUP_TIMEOUT_MS = CLIENT_APPLY_DEADLINE_MS;
+  const DSH_STRUCTURE_TIMEOUT_MS = CLIENT_APPLY_DEADLINE_MS;
+  const FRAME_FALLBACK_MS = 120;
   const VIDEO_STABLE_FRAMES = 3;
   const VIDEO_STABLE_PROGRESS_SEC = 0.18;
   const CROSSFADE_MS = 180;
@@ -67,10 +74,10 @@ html[data-bc-active="true"]:has(#root [data-phase="settling"]) #beauticode-bg-st
 html[data-bc-resolved-tone="light"][data-bc-active="true"]:has(#root [data-phase="active"]) #beauticode-bg-stage::after,
 html[data-bc-resolved-tone="light"][data-bc-active="true"]:has(#root [data-phase="settling"]) #beauticode-bg-stage::after{background:rgba(255,255,255,.22)}
 html[data-bc-fish="true"] #beauticode-bg-stage::after{background:transparent!important}
-#beauticode-bg-stage .beauticode-media-slot{position:absolute;inset:0;z-index:0;opacity:0;overflow:hidden;pointer-events:none;transition:opacity ${CROSSFADE_MS}ms ease;will-change:opacity}
-#beauticode-bg-stage .beauticode-media-slot[data-bc-role="current"]{z-index:0;opacity:1}
-#beauticode-bg-stage .beauticode-media-slot[data-bc-role="candidate"]{z-index:1;opacity:0}
-#beauticode-bg-stage[data-bc-empty="true"] .beauticode-media-slot[data-bc-role="candidate"]{opacity:1}
+#beauticode-bg-stage .beauticode-media-slot{position:absolute;inset:0;z-index:0;opacity:1;overflow:hidden;pointer-events:none;transition:opacity ${CROSSFADE_MS}ms ease;will-change:opacity}
+#beauticode-bg-stage .beauticode-media-slot[data-bc-role="current"]{z-index:1;opacity:1}
+#beauticode-bg-stage .beauticode-media-slot[data-bc-role="candidate"]{z-index:2;opacity:1}
+#beauticode-bg-stage[data-bc-empty="true"] .beauticode-media-slot[data-bc-role="candidate"]{z-index:1}
 #beauticode-bg-stage[data-bc-transitioning="true"] .beauticode-media-slot[data-bc-role="current"]{opacity:0}
 #beauticode-bg-stage[data-bc-transitioning="true"] .beauticode-media-slot[data-bc-role="candidate"]{opacity:1}
 #beauticode-bg-stage .beauticode-media-slot img,#beauticode-bg-stage .beauticode-media-slot video{position:absolute;inset:0;width:100%;height:100%;object-fit:cover;display:block;pointer-events:none;transition:opacity 120ms ease}
@@ -127,12 +134,12 @@ html[data-bc-fish="true"] #root{opacity:0!important;visibility:hidden!important;
       attributeFilter: ["data-ds-dark-theme"],
     });
   }
-  systemDarkMedia?.addEventListener("change", () => {
-    if (desiredModes.tone === "auto") {
-      syncDshTheme();
-      void acknowledgeMode();
-    }
-  });
+  systemDarkMedia?.addEventListener("change", () => {
+    if (desiredModes.tone === "auto") {
+      syncDshTheme();
+      void acknowledgeMode().catch(() => {});
+    }
+  });
   syncDshTheme();
 
   function stage() {
@@ -184,8 +191,23 @@ html[data-bc-fish="true"] #root{opacity:0!important;visibility:hidden!important;
     });
   }
 
+  function mountedCurrentSlot() {
+    const node = document.getElementById("beauticode-bg-stage");
+    if (
+      !currentSlot ||
+      currentSlot.isConnected !== true ||
+      currentSlot.parentElement !== node ||
+      currentSlot.dataset.bcRole !== "current"
+    ) {
+      currentSlot = null;
+      committedPayload = null;
+      return null;
+    }
+    return currentSlot;
+  }
+
   function activeVideo() {
-    const video = currentSlot?.querySelector?.("video") ?? null;
+    const video = mountedCurrentSlot()?.querySelector?.("video") ?? null;
     return video instanceof HTMLVideoElement ? video : null;
   }
 
@@ -195,7 +217,7 @@ html[data-bc-fish="true"] #root{opacity:0!important;visibility:hidden!important;
       '.beauticode-media-slot[data-bc-role="candidate"] video',
     );
     return video instanceof HTMLVideoElement ? video : null;
-  }
+  }
 
   async function postAck(body) {
     await fetch("/__beauticode/ack", {
@@ -267,45 +289,212 @@ html[data-bc-fish="true"] #root{opacity:0!important;visibility:hidden!important;
     if (signal?.aborted) throw abortError();
   }
 
-  function loadImage(url, signal, timeoutMs = IMAGE_LOAD_TIMEOUT_MS) {
-    const image = new Image();
-    image.alt = "";
-    image.decoding = "async";
+  function releaseImage(image, { remove = false } = {}) {
+    if (!image) return;
+    image.onload = null;
+    image.onerror = null;
+    try {
+      image.removeAttribute?.("src");
+    } catch {
+      image.src = "";
+    }
+    if (remove) image.remove?.();
+  }
+
+  function imageAttemptUrl(url, attempt) {
+    if (attempt === 0) return url;
+    try {
+      const retryUrl = new URL(url, globalThis.location?.href);
+      retryUrl.searchParams.set(
+        "bcImageRetry",
+        `${clientId}-${attempt}-${Date.now().toString(36)}`,
+      );
+      return retryUrl.href;
+    } catch {
+      return url;
+    }
+  }
+
+  function waitForImageAttempt(image, url, signal, timeoutMs) {
     return new Promise((resolve, reject) => {
       let settled = false;
-      let timer = null;
+      let decodeStarted = false;
+      let decodeFallback = null;
       const cleanup = () => {
-        if (timer) clearTimeout(timer);
+        clearTimeout(timer);
+        if (decodeFallback) clearTimeout(decodeFallback);
         signal?.removeEventListener?.("abort", aborted);
         image.onload = null;
         image.onerror = null;
       };
-      const finish = (error) => {
+      const finish = (error = null) => {
         if (settled) return;
         settled = true;
         cleanup();
         if (error) reject(error);
-        else resolve(image);
+        else resolve();
       };
-      const aborted = () => {
-        try {
-          image.removeAttribute?.("src");
-        } catch {
-          image.src = "";
+      const acceptLoaded = () => {
+        if (!(image.complete && image.naturalWidth > 0 && image.naturalHeight > 0)) {
+          if (image.complete) finish(new Error("图片尺寸无效"));
+          return;
         }
-        finish(abortError());
+        if (!decodeStarted && typeof image.decode === "function") {
+          decodeStarted = true;
+          // decode() is a second readiness signal, but the per-attempt timer
+          // remains authoritative. A loaded image is still accepted after a
+          // short decode grace period if Chromium leaves decode() pending.
+          decodeFallback = setTimeout(() => {
+            if (
+              image.isConnected === true &&
+              image.complete &&
+              image.naturalWidth > 0 &&
+              image.naturalHeight > 0
+            ) {
+              finish();
+            } else {
+              finish(new Error("图片解码未完成"));
+            }
+          }, 750);
+          let decodePromise;
+          try {
+            decodePromise = image.decode();
+          } catch {
+            finish(new Error("图片解码失败"));
+            return;
+          }
+          Promise.resolve(decodePromise).then(
+            () => finish(),
+            () => finish(new Error("图片解码失败")),
+          );
+          return;
+        }
+        finish();
       };
-      image.onload = () => finish();
-      image.onerror = () => finish(new Error("图片加载失败"));
-      timer = setTimeout(() => finish(new Error("等待图片加载超时")), timeoutMs);
+      const failed = () => finish(new Error("图片请求失败"));
+      const aborted = () => finish(abortError());
+      const timer = setTimeout(
+        () => finish(new Error("等待图片请求或解码超时")),
+        timeoutMs,
+      );
+      image.onload = acceptLoaded;
+      image.onerror = failed;
       signal?.addEventListener?.("abort", aborted, { once: true });
       if (signal?.aborted) {
         aborted();
         return;
       }
       image.src = url;
+      if (image.complete) queueMicrotask(acceptLoaded);
     });
   }
+
+  function waitForRetryWindow(signal, timeoutMs) {
+    return new Promise((resolve, reject) => {
+      let settled = false;
+      const finish = (error = null) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        signal?.removeEventListener?.("abort", aborted);
+        if (error) reject(error);
+        else resolve();
+      };
+      const aborted = () => finish(abortError());
+      const timer = setTimeout(() => finish(), timeoutMs);
+      signal?.addEventListener?.("abort", aborted, { once: true });
+      if (signal?.aborted) aborted();
+    });
+  }
+
+  async function loadImage(slot, url, signal, timeoutMs = IMAGE_LOAD_TIMEOUT_MS) {
+    const deadline = performance.now() + timeoutMs;
+    const attempts = [];
+    let lastError = null;
+
+    const startAttempt = (attempt) => {
+      throwIfAborted(signal);
+      const remainingMs = deadline - performance.now();
+      if (remainingMs <= 0) throw new Error("等待图片请求或解码超时");
+      const controller = new AbortController();
+      const parentAborted = () => controller.abort();
+      signal?.addEventListener?.("abort", parentAborted, { once: true });
+      const image = new Image();
+      image.alt = "";
+      image.decoding = "async";
+      image.className = "beauticode-media-poster";
+      slot.prepend(image);
+      const promise = waitForImageAttempt(
+        image,
+        imageAttemptUrl(url, attempt),
+        controller.signal,
+        Math.max(1, remainingMs),
+      )
+        .then(() => image)
+        .finally(() => signal?.removeEventListener?.("abort", parentAborted));
+      const record = { controller, image, promise };
+      attempts.push(record);
+      return record;
+    };
+
+    const cleanupAttempts = (winner = null) => {
+      for (const attempt of attempts) {
+        if (attempt.image === winner) continue;
+        attempt.controller.abort();
+        releaseImage(attempt.image, { remove: true });
+      }
+    };
+
+    try {
+      const first = startAttempt(0);
+      const firstWindow = await Promise.race([
+        first.promise.then(
+          (image) => ({ image }),
+          (error) => ({ error }),
+        ),
+        waitForRetryWindow(
+          signal,
+          Math.max(1, Math.min(IMAGE_ATTEMPT_TIMEOUT_MS, deadline - performance.now())),
+        ).then(() => ({ retry: true })),
+      ]);
+      if (firstWindow.image) {
+        cleanupAttempts(firstWindow.image);
+        return firstWindow.image;
+      }
+      if (isAbortError(firstWindow.error) || signal?.aborted) throw abortError();
+      lastError = firstWindow.error ?? lastError;
+
+      // Keep the original request alive. The cache-busted retry runs beside it
+      // so a merely slow cold decode is never destroyed to recover a hung one.
+      if (IMAGE_MAX_ATTEMPTS > 1) startAttempt(1);
+      let winner;
+      try {
+        winner = await Promise.any(attempts.map((attempt) => attempt.promise));
+      } catch (error) {
+        const errors = Array.isArray(error?.errors) ? error.errors : [];
+        lastError = errors.at(-1) ?? lastError ?? error;
+        throw lastError;
+      }
+      cleanupAttempts(winner);
+      return winner;
+    } catch (error) {
+      cleanupAttempts();
+      if (isAbortError(error) || signal?.aborted) throw abortError();
+      lastError = error ?? lastError;
+      const visibility = document.visibilityState || "unknown";
+      const online = globalThis.navigator?.onLine === false ? "offline" : "online";
+      const phase = lastError?.message || "unknown";
+      const summary =
+        phase === "图片请求失败"
+          ? "图片加载失败"
+          : phase.includes("超时")
+            ? "等待图片加载超时"
+            : "图片校验失败";
+      throw new Error(
+        `${summary}（已尝试 ${attempts.length} 次；页面=${visibility}；网络=${online}；最后阶段=${phase}）`,
+      );
+    }
+  }
 
   function describeVideoState(video, phase) {
     const mediaErrorNames = {
@@ -320,13 +509,13 @@ html[data-bc-fish="true"] #root{opacity:0!important;visibility:hidden!important;
   }
 
   function waitForVideo(video, signal, timeoutMs = VIDEO_STARTUP_TIMEOUT_MS) {
-    const canPlayState = HTMLMediaElement.HAVE_FUTURE_DATA ?? 3;
-    if (video.readyState >= canPlayState) return Promise.resolve();
+    const frameReadyState = HTMLMediaElement.HAVE_CURRENT_DATA ?? 2;
+    if (video.readyState >= frameReadyState) return Promise.resolve();
     return new Promise((resolve, reject) => {
       let settled = false;
       const done = () => finish();
       const check = () => {
-        if (video.readyState >= canPlayState) done();
+        if (video.readyState >= frameReadyState) done();
       };
       const failed = () => {
         finish(new Error(describeVideoState(video, "MP4 加载或解码失败")));
@@ -335,7 +524,7 @@ html[data-bc-fish="true"] #root{opacity:0!important;visibility:hidden!important;
         finish(signal?.aborted ? abortError() : new Error(describeVideoState(video, "视频加载已中止")));
       };
       const timer = setTimeout(() => {
-        finish(new Error(describeVideoState(video, "等待视频可播放状态超时")));
+        finish(new Error(describeVideoState(video, "等待视频首帧超时")));
       }, timeoutMs);
       const cleanup = () => {
         clearTimeout(timer);
@@ -402,7 +591,7 @@ html[data-bc-fish="true"] #root{opacity:0!important;visibility:hidden!important;
       let lastFrameTime = null;
       let playingSeen =
         !video.paused &&
-        video.readyState >= (HTMLMediaElement.HAVE_FUTURE_DATA ?? 3);
+        video.readyState >= HTMLMediaElement.HAVE_CURRENT_DATA;
       let settled = false;
       let frameRequest = null;
       const hasFrameCallback = typeof video.requestVideoFrameCallback === "function";
@@ -413,6 +602,8 @@ html[data-bc-fish="true"] #root{opacity:0!important;visibility:hidden!important;
         video.removeEventListener("timeupdate", check);
         video.removeEventListener("waiting", resetStableWindow);
         video.removeEventListener("stalled", resetStableWindow);
+        video.removeEventListener("pause", resetStableWindow);
+        video.removeEventListener("seeking", resetStableWindow);
         video.removeEventListener("error", failed);
         video.removeEventListener("abort", aborted);
         signal?.removeEventListener?.("abort", aborted);
@@ -465,7 +656,7 @@ html[data-bc-fish="true"] #root{opacity:0!important;visibility:hidden!important;
           return;
         }
         observeProgress();
-        if (!video.paused && video.readyState >= (HTMLMediaElement.HAVE_FUTURE_DATA ?? 3)) {
+        if (!video.paused && video.readyState >= HTMLMediaElement.HAVE_CURRENT_DATA) {
           playingSeen = true;
         }
         const framesReady = hasFrameCallback
@@ -508,6 +699,8 @@ html[data-bc-fish="true"] #root{opacity:0!important;visibility:hidden!important;
       video.addEventListener("timeupdate", check);
       video.addEventListener("waiting", resetStableWindow);
       video.addEventListener("stalled", resetStableWindow);
+      video.addEventListener("pause", resetStableWindow);
+      video.addEventListener("seeking", resetStableWindow);
       video.addEventListener("error", failed, { once: true });
       video.addEventListener("abort", aborted, { once: true });
       signal?.addEventListener?.("abort", aborted, { once: true });
@@ -536,62 +729,57 @@ html[data-bc-fish="true"] #root{opacity:0!important;visibility:hidden!important;
 
   async function playWithPreference(video, signal = null) {
     throwIfAborted(signal);
-    playbackBlocked = false;
-    video.muted = desiredModes.muted;
-    try {
-      await video.play();
-    } catch (error) {
-      if (desiredModes.muted) throw error;
-      playbackBlocked = true;
+    const requestedMuted = desiredModes.muted;
+    let blocked = false;
+    video.muted = requestedMuted;
+    try {
+      await video.play();
+    } catch (error) {
+      throwIfAborted(signal);
+      if (requestedMuted) throw error;
+      blocked = true;
       video.muted = true;
       await video.play();
     }
     throwIfAborted(signal);
-    video.dataset.bcPlaybackBlocked = playbackBlocked ? "true" : "false";
-  }
-
-  function createPlayingWaiter(video, signal, timeoutMs) {
-    let cancel = () => {};
-    const promise = new Promise((resolve, reject) => {
-      let settled = false;
-      const cleanup = () => {
-        clearTimeout(timer);
-        video.removeEventListener("playing", played);
-        video.removeEventListener("error", failed);
-        video.removeEventListener("abort", aborted);
-        signal?.removeEventListener?.("abort", aborted);
-      };
-      const finish = (error) => {
-        if (settled) return;
-        settled = true;
-        cleanup();
-        if (error) reject(error);
-        else resolve();
-      };
-      const played = () => finish();
-      const failed = () => finish(new Error(describeVideoState(video, "视频开始播放失败")));
-      const aborted = () => finish(abortError());
-      const timer = setTimeout(
-        () => finish(new Error(describeVideoState(video, "等待 playing 事件超时"))),
-        timeoutMs,
-      );
-      cancel = (error = abortError()) => finish(error);
-      video.addEventListener("playing", played, { once: true });
-      video.addEventListener("error", failed, { once: true });
-      video.addEventListener("abort", aborted, { once: true });
-      signal?.addEventListener?.("abort", aborted, { once: true });
-      if (signal?.aborted) aborted();
-    });
-    return { promise, cancel };
+    video.dataset.bcPlaybackBlocked = blocked ? "true" : "false";
+    return blocked;
   }
 
   async function startCandidatePlayback(video, signal, timeoutMs) {
-    const playing = createPlayingWaiter(video, signal, timeoutMs);
+    const playbackController = new AbortController();
+    const parentAborted = () => playbackController.abort();
+    signal?.addEventListener?.("abort", parentAborted, { once: true });
+    let timer = null;
+    let abortListener = null;
+    const playback = playWithPreference(video, playbackController.signal);
+    const deadline = new Promise((_, reject) => {
+      timer = setTimeout(() => {
+        reject(new Error(describeVideoState(video, "等待视频开始播放超时")));
+        playbackController.abort();
+      }, timeoutMs);
+      abortListener = () => reject(abortError());
+      playbackController.signal.addEventListener("abort", abortListener, { once: true });
+    });
+    if (signal?.aborted) parentAborted();
     try {
-      await Promise.all([playWithPreference(video, signal), playing.promise]);
+      // The play() promise itself resolves only after playback has started, so
+      // a second playing-event waiter would create an orphaned promise race.
+      return await Promise.race([playback, deadline]);
     } catch (error) {
-      playing.cancel(error);
+      playbackController.abort();
+      try {
+        video.pause();
+      } catch {
+        /* best effort: disposeSlot will release src as the final guard */
+      }
       throw error;
+    } finally {
+      if (timer) clearTimeout(timer);
+      signal?.removeEventListener?.("abort", parentAborted);
+      if (abortListener) {
+        playbackController.signal.removeEventListener("abort", abortListener);
+      }
     }
   }
 
@@ -623,14 +811,12 @@ html[data-bc-fish="true"] #root{opacity:0!important;visibility:hidden!important;
     if (!slot) return;
     for (const video of slot.querySelectorAll?.("video") ?? []) disposeVideo(video);
     for (const image of slot.querySelectorAll?.("img") ?? []) {
-      image.onload = null;
-      image.onerror = null;
-      image.removeAttribute?.("src");
+      releaseImage(image);
     }
     slot.remove?.();
   }
 
-  function createSlot(payload, image, video = null) {
+  function createSlot(payload, video = null) {
     const slot = document.createElement("div");
     slot.className = "beauticode-media-slot";
     slot.dataset.bcRole = "candidate";
@@ -638,8 +824,10 @@ html[data-bc-fish="true"] #root{opacity:0!important;visibility:hidden!important;
     slot.dataset.bcGeneration = String(payload.generation);
     slot.dataset.bcImageUrl = payload.imageUrl;
     if (payload.videoUrl) slot.dataset.bcVideoUrl = payload.videoUrl;
-    image.className = "beauticode-media-poster";
-    slot.append(image);
+    if (payload.media === "video") {
+      const startAt = Number(payload.startAt);
+      slot.dataset.bcStartAt = String(Number.isFinite(startAt) && startAt >= 0 ? startAt : 0);
+    }
     if (video) {
       video.className = "beauticode-media-video";
       slot.append(video);
@@ -648,9 +836,36 @@ html[data-bc-fish="true"] #root{opacity:0!important;visibility:hidden!important;
   }
 
   function slotMatchesPayload(slot, payload) {
-    if (!slot || slot.dataset.bcMedia !== payload.media) return false;
+    if (!slot || slot !== mountedCurrentSlot() || slot.dataset.bcMedia !== payload.media) {
+      return false;
+    }
     if (slot.dataset.bcImageUrl !== payload.imageUrl) return false;
-    return payload.media !== "video" || slot.dataset.bcVideoUrl === payload.videoUrl;
+    if (payload.media !== "video") {
+      const image = slot.querySelector?.("img");
+      return Boolean(
+        image?.isConnected === true &&
+          image.complete &&
+          image.naturalWidth > 0 &&
+          image.naturalHeight > 0,
+      );
+    }
+    if (slot.dataset.bcVideoUrl !== payload.videoUrl) return false;
+    const video = slot.querySelector?.("video");
+    if (
+      !(video instanceof HTMLVideoElement) ||
+      video.error ||
+      video.ended ||
+      video.paused ||
+      video.seeking ||
+      video.readyState < HTMLMediaElement.HAVE_CURRENT_DATA
+    ) {
+      return false;
+    }
+    const requestedStartAt = Number(payload.startAt);
+    const normalizedStartAt =
+      Number.isFinite(requestedStartAt) && requestedStartAt >= 0 ? requestedStartAt : 0;
+    const appliedStartAt = Number(slot.dataset.bcStartAt);
+    return Number.isFinite(appliedStartAt) && Math.abs(appliedStartAt - normalizedStartAt) < 0.25;
   }
 
   function updateCommittedDom(payload) {
@@ -682,9 +897,10 @@ html[data-bc-fish="true"] #root{opacity:0!important;visibility:hidden!important;
   function attachCandidate(slot, payload) {
     const node = stage();
     discardCandidates();
+    const previous = mountedCurrentSlot();
     slot.dataset.bcRole = "candidate";
     node.append(slot);
-    if (!currentSlot) {
+    if (!previous) {
       node.dataset.bcEmpty = "true";
       document.documentElement.dataset.bcActive = "true";
       document.documentElement.dataset.bcMedia =
@@ -696,17 +912,34 @@ html[data-bc-fish="true"] #root{opacity:0!important;visibility:hidden!important;
   function nextFrame(signal) {
     if (typeof requestAnimationFrame !== "function") return Promise.resolve();
     return new Promise((resolve, reject) => {
+      let settled = false;
       let request = null;
-      const aborted = () => {
-        if (request != null && typeof cancelAnimationFrame === "function") cancelAnimationFrame(request);
+      let timer = null;
+      const cleanup = () => {
+        if (timer) clearTimeout(timer);
+        if (request != null && typeof cancelAnimationFrame === "function") {
+          cancelAnimationFrame(request);
+        }
         signal?.removeEventListener?.("abort", aborted);
-        reject(abortError());
       };
-      request = requestAnimationFrame(() => {
-        signal?.removeEventListener?.("abort", aborted);
-        if (signal?.aborted) reject(abortError());
+      const finish = (error = null) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        if (error) reject(error);
         else resolve();
+      };
+      const aborted = () => {
+        finish(abortError());
+      };
+      request = requestAnimationFrame(() => {
+        request = null;
+        if (signal?.aborted) finish(abortError());
+        else finish();
       });
+      // Background or power-saved Chromium pages may suspend rAF entirely.
+      // A short timer keeps the transaction bounded without skipping aborts.
+      timer = setTimeout(() => finish(), FRAME_FALLBACK_MS);
       signal?.addEventListener?.("abort", aborted, { once: true });
       if (signal?.aborted) aborted();
     });
@@ -739,16 +972,21 @@ html[data-bc-fish="true"] #root{opacity:0!important;visibility:hidden!important;
     });
   }
 
-  async function commitCandidate(payload, slot, signal) {
+  async function commitCandidate(payload, slot, signal, remainingMs = () => Infinity) {
     throwIfAborted(signal);
     const node = stage();
-    const previous = currentSlot;
-    if (previous) {
+    const previous = mountedCurrentSlot();
+    const canAnimate =
+      previous &&
+      reducedMotionMedia?.matches !== true &&
+      document.visibilityState === "visible" &&
+      remainingMs() > CROSSFADE_MS + FRAME_FALLBACK_MS * 2 + 250;
+    if (canAnimate) {
       await nextFrame(signal);
       await nextFrame(signal);
       throwIfAborted(signal);
       node.dataset.bcTransitioning = "true";
-      await waitForCrossfade(slot, signal);
+      await waitForCrossfade(previous, signal);
     }
     throwIfAborted(signal);
     if (previous && previous !== slot) disposeSlot(previous);
@@ -767,7 +1005,7 @@ html[data-bc-fish="true"] #root{opacity:0!important;visibility:hidden!important;
     const node = document.getElementById("beauticode-bg-stage");
     node?.removeAttribute("data-bc-transitioning");
     node?.removeAttribute("data-bc-empty");
-    if (committedPayload && currentSlot) {
+    if (committedPayload && mountedCurrentSlot()) {
       updateCommittedDom(committedPayload);
       playbackBlocked = activeVideo()?.dataset?.bcPlaybackBlocked === "true";
       return;
@@ -779,12 +1017,19 @@ html[data-bc-fish="true"] #root{opacity:0!important;visibility:hidden!important;
   }
 
   function syncGallery(payload) {
-    const on = payload?.atmosphere?.preset === "gallery";
-    globalThis.BeauticodeAtmosphere?.setWindowMode?.(on ? "on" : "closed");
-  }
+    const on = payload?.atmosphere?.preset === "gallery";
+    try {
+      const sync = globalThis.BeauticodeAtmosphere?.setWindowMode?.(on ? "on" : "closed");
+      if (sync && typeof sync.then === "function") void sync.catch(() => {});
+    } catch {
+      /* Atmosphere is optional and must never invalidate a rendered background. */
+    }
+  }
 
   async function applyBackground(payload, signal) {
     throwIfAborted(signal);
+    const applyDeadline = performance.now() + CLIENT_APPLY_DEADLINE_MS;
+    const remaining = () => Math.max(1, applyDeadline - performance.now());
     if (payload.media === "clear") {
       desiredModes.fish = false;
       playbackBlocked = false;
@@ -803,13 +1048,20 @@ html[data-bc-fish="true"] #root{opacity:0!important;visibility:hidden!important;
       await acknowledgeMode();
       return;
     }
-    if (typeof payload.imageUrl !== "string") return;
-    const structureIssue = dshStructureIssue();
-    if (structureIssue) {
-      await acknowledgeRender(payload, false, false, structureIssue);
+    if (typeof payload.imageUrl !== "string" || payload.imageUrl.length === 0) {
+      await acknowledgeRender(payload, false, Boolean(mountedCurrentSlot()), "图片载荷无效");
       return;
     }
-    if (slotMatchesPayload(currentSlot, payload)) {
+    let reusable = slotMatchesPayload(currentSlot, payload);
+    if (reusable && payload.media === "video") {
+      try {
+        await waitForStablePlayback(activeVideo(), signal, Math.min(750, remaining()));
+      } catch (error) {
+        if (isAbortError(error) || signal?.aborted) throw error;
+        reusable = false;
+      }
+    }
+    if (reusable) {
       committedPayload = payload;
       currentSlot.dataset.bcGeneration = String(payload.generation);
       updateCommittedDom(payload);
@@ -819,17 +1071,17 @@ html[data-bc-fish="true"] #root{opacity:0!important;visibility:hidden!important;
       return;
     }
     let candidate = null;
+    let candidateVideo = null;
     let committed = false;
     try {
-      await waitForDshStructure(signal);
-      const image = await loadImage(payload.imageUrl, signal);
-      throwIfAborted(signal);
+      await waitForDshStructure(signal, remaining());
       if (payload.media === "image") {
-        if (!(image.naturalWidth > 0 && image.naturalHeight > 0)) throw new Error("图片尺寸无效");
-        playbackBlocked = false;
-        candidate = createSlot(payload, image);
+        candidate = createSlot(payload);
         attachCandidate(candidate, payload);
-        await commitCandidate(payload, candidate, signal);
+        const image = await loadImage(candidate, payload.imageUrl, signal, remaining());
+        throwIfAborted(signal);
+        if (!(image.naturalWidth > 0 && image.naturalHeight > 0)) throw new Error("图片尺寸无效");
+        await commitCandidate(payload, candidate, signal, remaining);
         committed = true;
         await acknowledgeRender(payload, true, true);
         await acknowledgeMode();
@@ -839,32 +1091,48 @@ html[data-bc-fish="true"] #root{opacity:0!important;visibility:hidden!important;
         throw new Error("视频载荷无效");
       }
       const video = document.createElement("video");
-      video.autoplay = false;
+      video.autoplay = true;
       video.loop = true;
       video.playsInline = true;
       video.preload = "auto";
-      video.poster = payload.imageUrl;
-      video.src = payload.videoUrl;
-      candidate = createSlot(payload, image, video);
+      video.crossOrigin = "anonymous";
+      // Set mute before src so Chromium may start the request immediately
+      // without waiting for an audible autoplay decision.
+      video.defaultMuted = true;
+      video.muted = desiredModes.muted;
+      video.setAttribute("muted", "");
+      candidate = createSlot(payload, video);
       attachCandidate(candidate, payload);
+      candidateVideo = video;
+      video.src = payload.videoUrl;
       video.load();
-      const deadline = performance.now() + VIDEO_STARTUP_TIMEOUT_MS;
-      const remaining = () => Math.max(1, deadline - performance.now());
-      await waitForVideo(video, signal, remaining());
+      const imageReady = loadImage(candidate, payload.imageUrl, signal, remaining());
+      // play() is deliberately started alongside media readiness. Chromium is
+      // allowed to ignore preload=auto for hidden/background media; waiting for
+      // canplay before play() creates a circular stall at readyState=0.
+      await Promise.all([
+        imageReady,
+        waitForVideo(video, signal, remaining()),
+        startCandidatePlayback(video, signal, remaining()),
+      ]);
       throwIfAborted(signal);
-      seekVideo(video, payload.startAt);
+      const appliedStartAt = seekVideo(video, payload.startAt);
+      candidate.dataset.bcStartAt = String(appliedStartAt);
       await waitForSeek(video, signal, remaining());
       await waitForVideo(video, signal, remaining());
-      await startCandidatePlayback(video, signal, remaining());
       await waitForStablePlayback(video, signal, remaining());
       throwIfAborted(signal);
       candidate.dataset.bcVideoReady = "true";
-      await commitCandidate(payload, candidate, signal);
+      await commitCandidate(payload, candidate, signal, remaining);
       committed = true;
       const visible = video.readyState >= HTMLMediaElement.HAVE_CURRENT_DATA && !video.paused;
       await acknowledgeRender(payload, visible, visible, visible ? null : "视频未开始播放");
       await acknowledgeMode();
     } catch (error) {
+      if (candidateVideo && candidateVideo.parentElement !== candidate) {
+        disposeVideo(candidateVideo);
+        candidateVideo.remove?.();
+      }
       if (candidate && !committed) disposeSlot(candidate);
       if (isAbortError(error) || signal?.aborted || activePayload !== payload) return;
       restoreCommittedDom();
@@ -879,6 +1147,22 @@ html[data-bc-fish="true"] #root{opacity:0!important;visibility:hidden!important;
 
   function scheduleBackground(payload) {
     if (!Number.isSafeInteger(payload?.generation)) return;
+    // EventSource reconnects can replay the current frame while its first
+    // render is still in flight. Restarting the same generation would discard
+    // a healthy cold media request and move its deadline indefinitely.
+    if (
+      applyController &&
+      activePayload?.generation === payload.generation &&
+      activePayload?.media === payload.media
+    ) {
+      return;
+    }
+    if (
+      Number.isSafeInteger(activePayload?.generation) &&
+      payload.generation < activePayload.generation
+    ) {
+      return;
+    }
     applyController?.abort();
     discardCandidates();
     const controller = new AbortController();
@@ -886,11 +1170,23 @@ html[data-bc-fish="true"] #root{opacity:0!important;visibility:hidden!important;
     activePayload = payload;
     renderPhase = "pending";
     document.documentElement.dataset.bcPendingGeneration = String(payload.generation);
-    void applyBackground(payload, controller.signal).finally(() => {
-      if (applyController !== controller) return;
-      applyController = null;
-      document.documentElement.removeAttribute("data-bc-pending-generation");
-    });
+    void applyBackground(payload, controller.signal)
+      .catch(async (error) => {
+        if (isAbortError(error) || controller.signal.aborted || activePayload !== payload) return;
+        restoreCommittedDom();
+        await acknowledgeRender(
+          payload,
+          false,
+          Boolean(mountedCurrentSlot()),
+          error instanceof Error ? error.message : String(error),
+        );
+      })
+      .finally(() => {
+        if (applyController !== controller) return;
+        applyController = null;
+        document.documentElement.removeAttribute("data-bc-pending-generation");
+      })
+      .catch(() => {});
   }
 
   async function applyModes(payload) {
@@ -908,8 +1204,8 @@ html[data-bc-fish="true"] #root{opacity:0!important;visibility:hidden!important;
     const candidate = pendingVideo();
     if (candidate instanceof HTMLVideoElement) candidate.muted = desiredModes.muted;
     if (video instanceof HTMLVideoElement) {
-      try {
-        await playWithPreference(video);
+      try {
+        playbackBlocked = await playWithPreference(video);
       } catch {
         playbackBlocked = desiredModes.muted === false;
       }
@@ -932,25 +1228,48 @@ html[data-bc-fish="true"] #root{opacity:0!important;visibility:hidden!important;
   events.onmessage = (event) => {
     try {
       const payload = JSON.parse(event.data);
-      if (payload?.type === "mode") void applyModes(payload);
+      if (payload?.type === "mode") void applyModes(payload).catch(() => {});
       else if (payload?.type === "apply") scheduleBackground(payload);
     } catch {
       /* EventSource will continue with the next valid frame. */
     }
   };
 
-  setInterval(() => {
-    const video = activeVideo();
-    if (
-      committedPayload?.media === "video" &&
-      activePayload === committedPayload &&
-      renderPhase === "ready" &&
-      video instanceof HTMLVideoElement
-    ) {
+  setInterval(() => {
+    if (
+      !committedPayload ||
+      activePayload !== committedPayload ||
+      renderPhase !== "ready"
+    ) {
+      return;
+    }
+    if (committedPayload.media === "clear") {
+      void acknowledgeRender(committedPayload, true, false).catch(() => {});
+      return;
+    }
+    const slot = mountedCurrentSlot();
+    if (!slot) return;
+    if (committedPayload.media === "image") {
+      const image = slot.querySelector?.("img");
+      if (
+        image?.isConnected === true &&
+        image.complete &&
+        image.naturalWidth > 0 &&
+        image.naturalHeight > 0
+      ) {
+        void acknowledgeRender(committedPayload, true, true).catch(() => {});
+      }
+      return;
+    }
+    const video = activeVideo();
+    if (
+      committedPayload.media === "video" &&
+      video instanceof HTMLVideoElement
+    ) {
       // A heartbeat is observational, not a second render verdict. Playback can
       // briefly pause while Chromium changes modes or refills an 8K buffer; do
       // not downgrade an already-rendered generation or fail a pending one.
-      void acknowledgeRender(committedPayload, true, true);
+      void acknowledgeRender(committedPayload, true, true).catch(() => {});
     }
   }, 1_000);
 })();

package/host-apply.mjs

@@ -7,7 +7,8 @@ import {
 } from "./control-client.mjs";
 import { canvasImagePath } from "./presets.mjs";
 
-const sessions = new Map();
+const sessions = new Map();
+const DSH_VERIFY_DEADLINE_MS = 10_000;
 
 export const ENGINE_MISSING_MESSAGE =
   "beautiCode 插件未能加载本机导入引擎。请执行 npx beauticode-dsh，或从完整安装目录加载桥接。";
@@ -92,7 +93,7 @@ export async function ensureInProcessSession(options) {
     const session = new adapter.DshSession({
       dataRoot,
       baseUrl,
-      verifyDeadlineMs: 30_000,
+      verifyDeadlineMs: DSH_VERIFY_DEADLINE_MS,
       bundledGalleryImagePath: canvasImagePath() || undefined,
     });
     try {

package/index.mjs

@@ -1,8 +1,8 @@
 import crypto from "node:crypto";
-import fs from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-import { fileURLToPath } from "node:url";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { registerAgentSurfaces } from "./agent.mjs";
 import { resolvePluginBaseUrl } from "./host-apply.mjs";
 import { createBeauticodeUi } from "./ui-host.mjs";
@@ -12,10 +12,10 @@ export const name = "beauticode-bridge";
 export const inject = ["webServer"];
 export const bridgeProtocol = 4;
 
-const here = path.dirname(fileURLToPath(import.meta.url));
-const TOKEN_PATTERN = /^[a-f0-9]{64}$/;
-const REVISION_PATTERN = /^[a-f0-9]{64}$/;
-const MAX_BODY_BYTES = 64 * 1024;
+const here = path.dirname(fileURLToPath(import.meta.url));
+const TOKEN_PATTERN = /^[a-f0-9]{64}$/;
+const REVISION_PATTERN = /^[a-f0-9]{64}$/;
+const MAX_BODY_BYTES = 64 * 1024;
 
 async function readBridgeIdentity() {
   try {
@@ -111,7 +111,7 @@ function isSameOrigin(req) {
   return req.headers["sec-fetch-site"] === "same-origin";
 }
 
-function validLoopbackMediaUrl(value) {
+function validLoopbackMediaUrl(value) {
   if (typeof value !== "string") return false;
   try {
     const url = new URL(value);
@@ -123,9 +123,9 @@ function validLoopbackMediaUrl(value) {
   } catch {
     return false;
   }
-}
-
-function validApplyPayload(body) {
+}
+
+function validApplyPayload(body) {
   if (!Number.isSafeInteger(body.generation) || body.generation < 0) return false;
   if (!["image", "video", "clear"].includes(body.media)) return false;
   if (body.atmosphere != null && !normalizeAtmosphere(body.atmosphere)) return false;
@@ -192,10 +192,10 @@ function publicStatus(current, modes, clients, clientStates) {
 }
 
 export function apply(ctx, config = {}) {
-  const tokenFile = path.resolve(config.tokenFile || defaultTokenFile());
-  const clients = new Map();
-  const clientStates = new Map();
-  let current = null;
+  const tokenFile = path.resolve(config.tokenFile || defaultTokenFile());
+  const clients = new Map();
+  const clientStates = new Map();
+  let current = null;
   const modes = { fish: false, muted: true, tone: "auto" };
   const dataRoot = path.dirname(tokenFile);
   const baseUrl = resolvePluginBaseUrl(ctx);
@@ -308,9 +308,9 @@ export function apply(ctx, config = {}) {
           res.end(req.method === "HEAD" ? undefined : source);
         },
       }),
-      ctx.webServer.register({
-        kind: "exact",
-        path: "/__beauticode/client.js",
+      ctx.webServer.register({
+        kind: "exact",
+        path: "/__beauticode/client.js",
         handler: async (req, res) => {
           if (req.method !== "GET" && req.method !== "HEAD") {
             res.writeHead(405).end();
@@ -322,10 +322,10 @@ export function apply(ctx, config = {}) {
             "cache-control": "no-store",
             "content-length": source.length,
           });
-          res.end(req.method === "HEAD" ? undefined : source);
-        },
-      }),
-      ctx.webServer.register({
+          res.end(req.method === "HEAD" ? undefined : source);
+        },
+      }),
+      ctx.webServer.register({
         kind: "exact",
         path: "/__beauticode/gallery.js",
         handler: async (req, res) => {
@@ -442,8 +442,8 @@ export function apply(ctx, config = {}) {
           clients.get(clientId)?.destroy();
           clients.set(clientId, res);
           clientStates.set(clientId, { render: null, mode: null });
-          if (current) {
-            res.write(`data: ${JSON.stringify({ type: "apply", ...current })}\n\n`);
+          if (current) {
+            res.write(`data: ${JSON.stringify({ type: "apply", ...current })}\n\n`);
           }
           res.write(`data: ${JSON.stringify({ type: "mode", ...modes })}\n\n`);
           ui.scheduleRestore();
@@ -472,18 +472,18 @@ export function apply(ctx, config = {}) {
             sendJson(res, 400, { ok: false, error: "背景载荷无效。" });
             return;
           }
-          current = {
-            generation: body.generation,
-            media: body.media,
-            imageUrl: body.media === "clear" ? null : body.imageUrl,
-            videoUrl: body.media === "video" ? body.videoUrl : null,
-            startAt: body.media === "video" ? body.startAt ?? null : null,
-          };
-          const atmosphere = normalizeAtmosphere(body.atmosphere);
-          if (atmosphere) current.atmosphere = atmosphere;
-          if (body.media === "clear") modes.fish = false;
-          for (const state of clientStates.values()) state.render = null;
-          broadcast({ type: "apply", ...current });
+          current = {
+            generation: body.generation,
+            media: body.media,
+            imageUrl: body.media === "clear" ? null : body.imageUrl,
+            videoUrl: body.media === "video" ? body.videoUrl : null,
+            startAt: body.media === "video" ? body.startAt ?? null : null,
+          };
+          const atmosphere = normalizeAtmosphere(body.atmosphere);
+          if (atmosphere) current.atmosphere = atmosphere;
+          if (body.media === "clear") modes.fish = false;
+          for (const state of clientStates.values()) state.render = null;
+          broadcast({ type: "apply", ...current });
           if (body.media === "clear") broadcast({ type: "mode", ...modes });
           sendJson(res, 200, { ok: true });
         },
@@ -621,10 +621,10 @@ export function apply(ctx, config = {}) {
     return () => {
       disposeTap();
       for (const dispose of disposers) dispose();
-      for (const response of clients.values()) response.destroy();
-      clients.clear();
-      clientStates.clear();
-      void ui.dispose();
+      for (const response of clients.values()) response.destroy();
+      clients.clear();
+      clientStates.clear();
+      void ui.dispose();
     };
   }, "beauticode-bridge: routes and browser injection");
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "beauticode-dsh",
-  "version": "1.0.16",
+  "version": "1.0.18",
   "description": "Cordis plugin: image/video backgrounds for DeepSeek Harness web.",
   "type": "module",
   "main": "./index.mjs",