From 02f28b6e09ffb5112411c590124e9dc54f74e2cf Mon Sep 17 00:00:00 2001
From: seasonyuu <seasonyuu@gmail.com>
Date: Wed, 21 Oct 2026 15:14:30 +0800
Subject: [PATCH 1/6] feat: add direct Canvas WebRTC rendering mode

Introduce renderer adapters, accessible mode selection and preference migration. Add no-Video rendering, JPEG fallback diagnostics, session isolation and regression coverage with localized documentation.
---
 README.md                                     |   8 +-
 README.zh-CN.md                               |   8 +-
 common/src/main/assets/web/app.js             | 329 +++++++++++++-----
 common/src/main/assets/web/index.html         |   7 +-
 common/src/main/assets/web/style.css          |   2 +
 .../shilapi/xcertplay/web/BrowserStrings.kt   |  13 +
 docs/ARCHITECTURE.md                          |  12 +
 docs/WEBRTC_RECOVERY.md                       |  10 +-
 .../src/main/res/values-zh-rCN/ui_strings.xml |  12 +
 .../src/main/res/values-zh-rTW/ui_strings.xml |  12 +
 shared/src/main/res/values/ui_strings.xml     |  12 +
 test/localization.test.js                     |  13 +
 test/pairing.test.js                          |   4 +-
 test/stream-client.test.js                    | 207 ++++++++++-
 test/track-canvas.test.js                     |  91 +++++
 test/webrtc.test.js                           |  82 ++++-
 16 files changed, 704 insertions(+), 118 deletions(-)
 create mode 100644 test/track-canvas.test.js

diff --git a/README.md b/README.md
index e87ffb8..61ab379 100644
--- a/README.md
+++ b/README.md
@@ -37,7 +37,13 @@ For 60 fps, select WebRTC video passthrough under Settings → Display & streami
 
 The WebRTC interruption tolerance setting offers 4, 10 (default), or 30 seconds and applies on the next browser connection. Recoverable interruptions keep the last video frame visible while waiting for recovery; persistent problems fall back to JPEG after the grace period. Unsupported codecs and terminal connection failures still fall back immediately. This does not enlarge the video buffer or change control and audio connection rules. Refresh the webpage after updating the App. See the [stability and troubleshooting notes](docs/WEBRTC_RECOVERY.md) (Chinese).
 
-If the video element renders incorrectly in your car's browser, enable “Use Canvas to display video (experimental)” on the webpage's connection screen before connecting. This is disabled by default. The selection is saved in the current browser and persists across automatic reconnects and page reloads; if browser storage is disabled, it applies only to the current page. WebRTC video is still decoded by an offscreen `<video>` element and drawn directly onto a visible Canvas with `drawImage()`. Video frame callbacks are preferred, with animation frames used for older browsers or when offscreen callbacks stall. Touch coordinates are mapped to the video's aspect ratio, and drawing failures trigger a fallback to JPEG. This mode may increase GPU / CPU usage. The video frame rate in the status bar still reflects the browser's video presentation statistics, not the actual Canvas drawing rate.
+The connection page offers three **Video display mode** radio cards. **Native Video** remains the default; both Canvas options are experimental:
+
+- **Native Video** displays the WebRTC stream in a video element.
+- **Compatibility Canvas** decodes with an offscreen `<video>` and copies frames with `drawImage()`. Video frame callbacks are preferred, with animation frames recovering older browsers or stalled offscreen callbacks.
+- **Direct Canvas** reads WebRTC `VideoFrame` objects through the main-thread `MediaStreamTrackProcessor` and draws them directly. It never creates a `<video>` or uses `VideoDecoder`. Worker-only Processor implementations are outside this first version. Missing support or runtime failure falls back directly to JPEG without switching to a video-element mode.
+
+The browser remembers the choice across reloads and automatic reconnects; unavailable storage retains it only in the current page. Existing Canvas preferences migrate to Compatibility Canvas. Disconnect before choosing another mode; automatic retries retain the launch choice. Both Canvas modes wait for a successfully drawn frame before stopping JPEG, and touch mapping follows actual frame dimensions. Canvas can increase GPU / CPU usage and does not guarantee 60 fps. Direct Canvas reports successful draw submissions in the status bar; the other modes retain video presentation / decoding statistics. Neither measures physical display refresh. `window.wheelplayStats.presentation` exposes selected / active modes, drawing statistics and fallback reasons.
 
 Canvas mode requires testing on car browsers such as NIO's. Changing the rendering path may help if an overlay covers only the native video element; it cannot guarantee success if the system stops decoding or overlays the entire page. Test while the vehicle is parked. Drivers should use only essential navigation interfaces while driving.
 
diff --git a/README.zh-CN.md b/README.zh-CN.md
index db3578f..4e660e1 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -39,7 +39,13 @@ WheelPlay 是一款 Android 局域网 CarPlay 服务端应用，可将 iPhone 
 
 「WebRTC 卡顿容忍时间」可选 4 秒、10 秒（默认）或 30 秒，下次浏览器连接生效。短暂断流时保留最后一帧并等待恢复，持续异常超过阈值才回退 JPEG；不支持的编码或彻底失败的连接仍立即回退。该设置不会扩大视频缓冲，控制与音频保持各自的连接规则。更新 App 后请刷新网页。详见 [稳定性分析与排查](docs/WEBRTC_RECOVERY.md)。
 
-车机浏览器的视频元素显示异常时，可在网页连接界面勾选「使用 Canvas 显示视频（实验性）」，再连接设备。默认关闭；选择保存在当前浏览器，自动重连及刷新后保留（浏览器禁用存储时仅当前页面有效）。WebRTC 视频仍由 `<video>` 解码，元素放在屏幕外，使用 `drawImage()` 直接绘制到可见 Canvas；优先使用视频帧回调，旧浏览器或离屏回调停顿时使用动画帧刷新。触控区域按画面比例映射，绘制失败自动回退 JPEG。该模式可能增加 GPU / CPU 消耗；状态栏中的视频帧率仍为浏览器的视频呈现统计，不能代表 Canvas 的实际绘制帧率。
+网页连接界面的「视频显示方式」提供三张单选卡片，默认「原生 Video」。两个 Canvas 模式均为实验性：
+
+- **原生 Video**：由视频元素直接显示 WebRTC 画面。
+- **兼容 Canvas**：保留离屏 `<video>` 解码并使用 `drawImage()` 绘制，优先视频帧回调，旧浏览器或离屏回调停顿时使用动画帧补偿。
+- **直接 Canvas**：使用主线程 `MediaStreamTrackProcessor` 读取 WebRTC `VideoFrame` 并绘制，全程不创建 `<video>`，也不使用 `VideoDecoder`。仅在 Worker 中提供 Processor 的浏览器不在首版支持范围；不支持或运行失败时直接使用 JPEG，不切换到旧的视频元素模式。
+
+浏览器保存所选方式，刷新和自动重连后保留；禁用存储时仅当前页面有效。原有 Canvas 偏好自动迁移为「兼容 Canvas」。需要断开后重新选择，自动重连不会改变本次启动的方式。两种 Canvas 都在首帧绘制成功后才停止 JPEG；尺寸与触控按实际画面映射。Canvas 可能增加 GPU / CPU 消耗，不保证达到 60 fps。直接 Canvas 状态栏的 fps 是成功绘制次数，其他模式保留原有视频呈现 / 解码统计，均不等于屏幕实际刷新率。`window.wheelplayStats.presentation` 可查看所选 / 实际方式、绘制统计和回退原因。
 
 Canvas 模式需要蔚来等车机实测：若遮罩只覆盖原生视频元素，改变显示路径可能有效；若系统停止解码或在整个页面上叠加遮罩，则无法保证有效。请在车辆停稳后验证，驾驶员行驶中只应使用必要的导航界面。
 
diff --git a/common/src/main/assets/web/app.js b/common/src/main/assets/web/app.js
index 7bb93e9..0c5079e 100644
--- a/common/src/main/assets/web/app.js
+++ b/common/src/main/assets/web/app.js
@@ -96,7 +96,7 @@ export function createPresentationController({
     status(meta) {
       if (!accept(meta)) return false;
       // Compatibility with servers predating versioned media packets.
-      if (videoEpoch === null && frame && (meta.width !== frame.width || meta.height !== frame.height)) {
+      if (videoEpoch === null && frame && frame.transport !== 'rtc' && (meta.width !== frame.width || meta.height !== frame.height)) {
         revision++; invalid = false;
       }
       source = meta.sourceState || (meta.streaming ? 'ready' : 'recovering');
@@ -285,7 +285,7 @@ export function createControlOutbox(socket, {
 // suppress video frame callbacks on embedded browsers. drawImage copies decoded
 // frames directly; it does not read pixels back through getImageData.
 export function createVideoCanvasRenderer(video, canvas, {
-  onFrame = () => {}, onError = () => {},
+  onFrame = () => {}, onDraw = () => {}, onError = () => {},
   requestFrame = callback => requestAnimationFrame(callback), cancelFrame = id => cancelAnimationFrame(id),
   now = () => performance.now(),
 } = {}) {
@@ -317,6 +317,7 @@ export function createVideoCanvasRenderer(video, canvas, {
       if (!resized && key !== null && key === lastFrameKey) return;
       if (resized) { canvas.width = width; canvas.height = height; }
       context.drawImage(video, 0, 0, width, height);
+      onDraw();
       lastFrameKey = key;
       const first = canvas.hidden;
       canvas.hidden = false;
@@ -356,10 +357,133 @@ function isRtcErrorRetryable(error) {
   return !['NotAllowedError', 'NotSupportedError'].includes(error?.name);
 }
 
+export function videoRendererPreference(value, legacy) {
+  return ['native', 'video-canvas', 'track-canvas'].includes(value) ? value : legacy === 'true' ? 'video-canvas' : 'native';
+}
+
+// A reader owns each VideoFrame until it is drawn or discarded, including after stop.
+export function createTrackCanvasRenderer(canvas, {
+  onReady = () => {}, onResize = () => {}, onError = () => {},
+  createProcessor = init => new MediaStreamTrackProcessor(init),
+} = {}) {
+  let generation = 0, reader = null, running = false, width = 0, height = 0, renderedFrames = 0;
+  function stop() {
+    generation++; running = false;
+    const old = reader; reader = null;
+    if (old) { try { Promise.resolve(old.cancel()).catch(() => {}); } catch (_) {} }
+    canvas.hidden = true; canvas.width = canvas.height = 0;
+  }
+  async function consume(activeReader, context, token) {
+    const current = () => running && generation === token;
+    try {
+      while (current()) {
+        const { value: frame, done } = await activeReader.read();
+        try {
+          if (!current()) break;
+          if (done) throw new Error('track-ended');
+          if (!frame || !(frame.displayWidth > 0) || !(frame.displayHeight > 0)) continue;
+          const resized = width !== frame.displayWidth || height !== frame.displayHeight;
+          if (resized) { canvas.width = frame.displayWidth; canvas.height = frame.displayHeight; }
+          context.drawImage(frame, 0, 0, frame.displayWidth, frame.displayHeight);
+          width = frame.displayWidth; height = frame.displayHeight; renderedFrames++;
+          canvas.hidden = false;
+          if (renderedFrames === 1) onReady({ width, height });
+          else if (resized) onResize({ width, height });
+        } finally { frame?.close(); }
+      }
+    } catch (error) {
+      if (current()) { stop(); onError(error.message === 'track-ended' ? 'track-ended' : 'renderer-error', isRtcErrorRetryable(error)); }
+    } finally {
+      try { activeReader.releaseLock(); } catch (_) {}
+      if (reader === activeReader) reader = null;
+    }
+  }
+  return {
+    start(track) {
+      stop(); width = height = renderedFrames = 0;
+      try {
+        const context = canvas.getContext('2d', { alpha: false });
+        if (!context) throw Object.assign(new Error('Canvas 2D unavailable'), { name: 'NotSupportedError' });
+        reader = createProcessor({ track, maxBufferSize: 1 }).readable.getReader();
+        running = true;
+        void consume(reader, context, generation);
+      } catch (error) { stop(); onError('renderer-error', isRtcErrorRetryable(error)); }
+    },
+    stop,
+    snapshot: () => ({ width, height, renderedFrames, presentedFrames: null }),
+  };
+}
+
+// Video elements exist only for the two legacy renderers, and belong to one offer.
+export function createVideoRenderer(mode, canvas, {
+  createVideo, onReady = () => {}, onResize = () => {}, onError = () => {},
+} = {}) {
+  let video = null, copy = null, frameCallback = null, generation = 0, ready = false, started = false;
+  let width = 0, height = 0, presentedFrames = null, renderedFrames = mode === 'video-canvas' ? 0 : null;
+  function report(w, h) {
+    if (!video || !w || !h) return;
+    const resized = width !== w || height !== h;
+    width = w; height = h;
+    if (!ready) { ready = true; if (!copy) video.hidden = false; onReady({ width, height }); }
+    else if (resized) onResize({ width, height });
+  }
+  function stop() {
+    generation++;
+    if (copy) copy.stop(); copy = null;
+    if (video) {
+      if (frameCallback !== null) video.cancelVideoFrameCallback?.(frameCallback);
+      video.onloadeddata = video.onerror = video.onresize = null;
+      video.srcObject = null; video.remove(); video = null;
+    }
+    frameCallback = null;
+  }
+  return {
+    start(track, streams = []) {
+      stop(); ready = started = false; width = height = 0; presentedFrames = null;
+      renderedFrames = mode === 'video-canvas' ? 0 : null;
+      try {
+        video = createVideo();
+        const token = generation, current = () => video !== null && token === generation;
+        if (mode === 'video-canvas') {
+          copy = createVideoCanvasRenderer(video, canvas, {
+            onDraw: () => { renderedFrames++; }, onFrame: report,
+            onError: error => { if (current()) onError('renderer-error', isRtcErrorRetryable(error)); },
+          });
+          copy.prepare();
+        }
+        const displayed = () => {
+          if (!current() || video.readyState < 2 || !video.videoWidth || !video.videoHeight) return;
+          if (copy) { if (!started) { started = true; copy.start(); } }
+          else report(video.videoWidth, video.videoHeight);
+        };
+        video.onloadeddata = displayed;
+        video.onresize = () => { if (current() && !copy) displayed(); };
+        video.onerror = () => { if (current()) onError('renderer-error'); };
+        if (video.requestVideoFrameCallback) {
+          let firstPresented = null;
+          presentedFrames = 0;
+          const observe = (_, metadata) => {
+            if (!current()) return;
+            if (firstPresented === null) firstPresented = metadata.presentedFrames;
+            presentedFrames = metadata.presentedFrames - firstPresented;
+            if (!copy) displayed();
+            if (current()) frameCallback = video.requestVideoFrameCallback(observe);
+          };
+          frameCallback = video.requestVideoFrameCallback(observe);
+        }
+        video.srcObject = streams[0] || new MediaStream([track]);
+        Promise.resolve(video.play()).then(displayed).catch(error => { if (current()) onError('renderer-error', isRtcErrorRetryable(error)); });
+      } catch (error) { onError('renderer-error', isRtcErrorRetryable(error)); }
+    },
+    stop,
+    snapshot: () => ({ width, height, presentedFrames, renderedFrames }),
+  };
+}
+
 // Video WebRTC remains receive-only. Browser audio uses the paired WebSocket.
-export function createRtcReceiver(video, {
+export function createRtcReceiver(createRenderer, {
   send, onReady = () => {}, onStop = () => {}, onStats = () => {},
-  onTrack = () => {}, onReset = () => {},
+  onResize = () => {}, onReset = () => {},
   createPeer = () => new RTCPeerConnection({ iceServers: [] }),
   supportsCodec = codec => {
     if (typeof RTCRtpReceiver === 'undefined' || !RTCRtpReceiver.getCapabilities) return true;
@@ -368,7 +492,7 @@ export function createRtcReceiver(video, {
   },
   schedule = setTimeout, cancel = clearTimeout, now = () => Date.now(),
 } = {}) {
-  let frameCallback = null, presented = 0, previousStats = null;
+  let renderer = null, track = null, previousStats = null, renderStalledSince = null, lastRendered = 0;
   let codec = 'H264';
   let peer = null, id = null, generation = 0, timeout = null, statsTimer = null, ready = false;
   let lastDecoded = 0, sent = 0, lastSentAt = 0, sentAtLastProgress = 0;
@@ -377,37 +501,39 @@ export function createRtcReceiver(video, {
     generation++; cancel(timeout); cancel(statsTimer); cancel(disconnectTimer);
     timeout = null; statsTimer = null; disconnectTimer = null;
     stalledSince = null; statsFailedSince = null;
+    renderStalledSince = null;
     const old = peer; peer = null; ready = false; id = null;
-    if (frameCallback !== null && video.cancelVideoFrameCallback) video.cancelVideoFrameCallback(frameCallback);
-    frameCallback = null; presented = 0; previousStats = null;
-    video.onloadeddata = null; video.onerror = null;
-    if (old) { old.ontrack = null; old.onconnectionstatechange = null; old.close(); }
     onReset();
-    video.srcObject = null; video.hidden = true;
+    if (renderer) renderer.stop(); renderer = null;
+    if (track) { track.onended = null; track.stop(); track = null; }
+    previousStats = null; lastRendered = 0;
+    if (old) { old.ontrack = old.onconnectionstatechange = old.onicegatheringstatechange = null; old.close(); }
   }
-  function fallback(retryable = true) {
+  function fallback(reason = 'connection-failed', retryable = true) {
     const current = id;
-    close(); onStop();
-    if (current !== null) send({ type: 'rtc-fallback', id: current, ...(retryable ? {} : { retryable: false }) });
+    if (current === null) return;
+    close(); onStop(reason);
+    send({ type: 'rtc-fallback', id: current, ...(retryable ? {} : { retryable: false }) });
   }
   async function receive(message) {
     if (message.type === 'rtc-stop') {
-      if (message.id === id) { close(); onStop(); }
+      if (message.id === id) { close(); onStop('server-stop'); }
       return;
     }
     if (message.type !== 'rtc-offer') return;
     close(); id = message.id; codec = message.codec === 'H265' ? 'H265' : 'H264';
     recoveryGraceMs = [4000, 10000, 30000].includes(message.recoveryGraceMs) ? message.recoveryGraceMs : 10000;
     const token = generation, current = () => generation === token && peer !== null;
-    timeout = schedule(() => { if (generation === token) fallback(); }, Math.max(10000, recoveryGraceMs));
+    timeout = schedule(() => { if (generation === token) fallback('first-frame-timeout'); }, Math.max(10000, recoveryGraceMs));
     try {
-      if (!supportsCodec(codec)) { fallback(false); return; }
+      if (!supportsCodec(codec)) { fallback('codec-unsupported', false); return; }
       const pc = createPeer(); peer = pc;
-      const displayed = () => {
-        if (!current() || ready || !video.videoWidth || video.readyState < 2) return;
+      const displayed = size => {
+        if (!current() || ready || !size.width || !size.height) return;
         ready = true; cancel(timeout); timeout = null;
         lastDecoded = 0; sent = 0; sentAtLastProgress = 0; lastSentAt = now();
-        send({ type: 'rtc-ready', id }); onReady();
+        lastRendered = renderer?.snapshot().renderedFrames ?? 0;
+        send({ type: 'rtc-ready', id }); onReady(size);
         if (current()) statsTimer = schedule(sample, 1000);
       };
       const sample = async () => {
@@ -417,8 +543,16 @@ export function createRtcReceiver(video, {
           if (!current()) return;
           statsFailedSince = null;
           report.forEach(stat => {
+            if (!current()) return;
             if (stat.type !== 'inbound-rtp' || (stat.kind || stat.mediaType) !== 'video') return;
             const decoded = stat.framesDecoded || 0, at = now();
+            const output = renderer.snapshot();
+            const presented = output.presentedFrames;
+            const rendered = output.renderedFrames;
+            if (rendered === null || rendered !== lastRendered || sent <= sentAtLastProgress || at - lastSentAt >= 2000) {
+              renderStalledSince = null;
+            } else if (renderStalledSince === null) renderStalledSince = at;
+            lastRendered = rendered;
             if (decoded !== lastDecoded || sent <= sentAtLastProgress || at - lastSentAt >= 2000) {
               stalledSince = null; sentAtLastProgress = sent;
             } else if (stalledSince === null) stalledSince = at;
@@ -434,7 +568,9 @@ export function createRtcReceiver(video, {
             });
             const metrics = {
               receivedFps: rate('framesReceived'), decodedFps: rate('framesDecoded'),
-              presentedFps: video.requestVideoFrameCallback && elapsed ? Math.max(0, presented - previous.presented) * 1000 / elapsed : null,
+              presentedFps: presented !== null && previous?.presented !== null && elapsed ? Math.max(0, presented - previous.presented) * 1000 / elapsed : null,
+              renderedFps: rendered !== null && previous?.rendered !== null && elapsed ? Math.max(0, rendered - previous.rendered) * 1000 / elapsed : null,
+              renderedFrames: rendered,
               decodeMs: averageMs('totalDecodeTime', 'framesDecoded'),
               jitterBufferMs: averageMs('jitterBufferDelay', 'jitterBufferEmittedCount'),
               processingMs: averageMs('totalProcessingDelay', 'framesDecoded'),
@@ -443,21 +579,28 @@ export function createRtcReceiver(video, {
               rttMs,
             };
             onStats(metrics.presentedFps ?? metrics.decodedFps, metrics);
+            if (!current()) return;
             send({ type: 'rtc-feedback', id, packets: Math.max(0, stat.packetsReceived || 0),
               lost: Math.max(0, stat.packetsLost || 0), decoded, nack: Math.max(0, stat.nackCount || 0), rttMs });
-            previousStats = { at, stat, presented };
+            previousStats = { at, stat, presented, rendered };
             lastDecoded = decoded;
             // Static CarPlay screens legitimately stop producing frames.
-            if (stalledSince !== null && at - stalledSince >= recoveryGraceMs) fallback();
+            if (stalledSince !== null && at - stalledSince >= recoveryGraceMs) fallback('decode-stalled');
+            else if (renderStalledSince !== null && at - renderStalledSince >= recoveryGraceMs) fallback('render-stalled');
           });
         } catch (_) {
           if (current()) {
             if (statsFailedSince === null) statsFailedSince = now();
-            if (now() - statsFailedSince >= recoveryGraceMs) fallback();
+            if (now() - statsFailedSince >= recoveryGraceMs) fallback('stats-unavailable');
           }
         }
         if (current()) statsTimer = schedule(sample, 1000);
       };
+      renderer = createRenderer({
+        onReady: displayed,
+        onResize: size => { if (current()) onResize(size); },
+        onError: (reason, retryable) => { if (current()) fallback(reason, retryable); },
+      });
       pc.onconnectionstatechange = () => {
         if (!current()) return;
         if (['failed', 'closed'].includes(pc.connectionState)) { fallback(); return; }
@@ -474,30 +617,16 @@ export function createRtcReceiver(video, {
       };
       pc.ontrack = event => {
         if (!current()) return;
-        video.onloadeddata = displayed;
-        video.onerror = () => { if (current()) fallback(); };
-        if (video.requestVideoFrameCallback && frameCallback === null) {
-          let firstPresented = null;
-          const observe = (_, metadata) => {
-            if (!current()) return;
-            if (firstPresented === null) firstPresented = metadata.presentedFrames;
-            presented = metadata.presentedFrames - firstPresented;
-            frameCallback = video.requestVideoFrameCallback(observe);
-          };
-          frameCallback = video.requestVideoFrameCallback(observe);
-        }
-        video.srcObject = event.streams[0] || new MediaStream([event.track]);
-        onTrack();
-        if (!current()) return;
-        video.play().then(displayed).catch(error => {
-          if (current()) fallback(isRtcErrorRetryable(error));
-        });
+        if (track) { fallback('track-replaced'); return; }
+        track = event.track;
+        track.onended = () => { if (current()) fallback('track-ended'); };
+        renderer.start(track, event.streams);
       };
       await pc.setRemoteDescription({ type: 'offer', sdp: message.sdp });
       if (!current()) return;
       const answer = await pc.createAnswer();
       if (!current()) return;
-      if (/^m=video 0(?: |\r?$)/m.test(answer.sdp)) { fallback(false); return; }
+      if (/^m=video 0(?: |\r?$)/m.test(answer.sdp)) { fallback('codec-unsupported', false); return; }
       // Use the browser as DTLS server: Mbed TLS 3.6 cannot reassemble a fragmented
       // ClientHello from newer Chrome versions. Passive is a standard answer role.
       await pc.setLocalDescription({ type: answer.type, sdp: answer.sdp.replace(/a=setup:active/g, 'a=setup:passive') });
@@ -510,14 +639,15 @@ export function createRtcReceiver(video, {
       if (pc.iceGatheringState === 'complete') answerReady();
       else pc.onicegatheringstatechange = answerReady;
     } catch (error) {
-      if (generation === token) fallback(isRtcErrorRetryable(error));
+      if (generation === token) fallback(error.message === 'processor-unsupported' ? error.message : 'connection-failed',
+        error.message !== 'processor-unsupported' && isRtcErrorRetryable(error));
     }
   }
   return { receive, close, fallback, get active() { return ready; }, get codec() { return codec; },
-    get recovering() { return ready && (disconnectTimer !== null || stalledSince !== null || statsFailedSince !== null); },
+    get recovering() { return ready && (disconnectTimer !== null || stalledSince !== null || renderStalledSince !== null || statsFailedSince !== null); },
     progress(count) {
       if (count > sent) {
-        if (now() - lastSentAt >= 2000) stalledSince = null;
+        if (now() - lastSentAt >= 2000) { stalledSince = null; renderStalledSince = null; }
         lastSentAt = now();
       }
       sent = count;
@@ -532,12 +662,13 @@ if (typeof document !== 'undefined') {
   const screen = $('screen');
   const screens = [screen, $('screen-next'), $('screen-third')];
   const heldFrame = $('held-frame');
-  const video = $('video');
+  let video = null;
   const canvas = $('video-canvas');
   const display = $('display');
   const touchSurface = $('touch-surface');
   // Read-only diagnostic snapshots; counters never include pairing credentials or video payloads.
-  const performanceStats = { source: null, transport: null, receiver: null, image: null };
+  const rendererStats = { selectedMode: 'native', activeMode: 'waiting', renderedFps: null, renderedFrames: null, fallbackReason: null };
+  const performanceStats = { source: null, transport: null, receiver: null, image: null, presentation: rendererStats };
   const webpSupport = probeWebp();
   Object.defineProperty(window, 'wheelplayStats', { configurable: true, get: () => JSON.parse(JSON.stringify(performanceStats)) });
   let rtc = null, rtcRequested = false, rtcFps = null;
@@ -584,19 +715,41 @@ if (typeof document !== 'undefined') {
       if (!jpeg.current) presentation.invalidate('jpeg');
     },
   });
-  const canvasOption = $('canvas-video');
-  const canvasPreference = 'wheelplay.canvasVideo';
-  try { canvasOption.checked = window.localStorage.getItem(canvasPreference) === 'true'; } catch (_) {}
-  canvasOption.addEventListener('change', () => {
-    try { window.localStorage.setItem(canvasPreference, String(canvasOption.checked)); } catch (_) {}
-  });
-  const canvasRenderer = createVideoCanvasRenderer(video, canvas, {
-    onFrame: (frameWidth, frameHeight) => {
-      if (!presentation.present(rtcMedia, frameWidth, frameHeight, 'rtc', rtcMedia.revision)) return;
-      width = frameWidth; height = frameHeight; jpeg.cancelPending(); jpeg.hide(); clearHeldFrame();
-    },
-    onError: error => { if (rtc) rtc.fallback(isRtcErrorRetryable(error)); },
-  });
+  const rendererPreference = 'wheelplay.videoRenderer';
+  let selectedMode = 'native';
+  try {
+    selectedMode = videoRendererPreference(window.localStorage.getItem(rendererPreference), window.localStorage.getItem('wheelplay.canvasVideo'));
+    window.localStorage.setItem(rendererPreference, selectedMode);
+  } catch (_) {}
+  let launchMode = selectedMode;
+  const processorSupported = () => typeof MediaStreamTrackProcessor === 'function';
+  function updateRendererOptions() {
+    for (const mode of ['native', 'video-canvas', 'track-canvas']) {
+      $(`renderer-${mode}`).checked = selectedMode === mode;
+      $(`renderer-${mode}-card`).classList.toggle('selected', selectedMode === mode);
+    }
+    $('renderer-hint').hidden = selectedMode !== 'track-canvas' || processorSupported();
+  }
+  for (const mode of ['native', 'video-canvas', 'track-canvas']) {
+    $(`renderer-${mode}`).addEventListener('change', () => {
+      if (!$(`renderer-${mode}`).checked) return;
+      selectedMode = mode; updateRendererOptions();
+      try { window.localStorage.setItem(rendererPreference, mode); } catch (_) {}
+    });
+  }
+  updateRendererOptions();
+  function createLegacyVideo() {
+    video = document.createElement('video');
+    video.id = 'video'; video.autoplay = true; video.muted = true; video.playsInline = true; video.hidden = true;
+    video.setAttribute('disablepictureinpicture', '');
+    video.setAttribute('aria-label', t('web_live_carplay_video'));
+    display.insertBefore(video, canvas); bindSurface(video);
+    return video;
+  }
+  function showRtcSize(size) {
+    if (!presentation.present(rtcMedia, size.width, size.height, 'rtc', rtcMedia.revision)) return;
+    width = size.width; height = size.height; jpeg.cancelPending(); jpeg.hide(); clearHeldFrame();
+  }
   const pairApi = async (path, request = null) => {
     const headers = request?.token ? { 'X-Pair-Token': request.token } :
       request?.code ? { 'X-Pair-Code': request.code } :
@@ -813,11 +966,15 @@ if (typeof document !== 'undefined') {
   function release() { cancelMove(); pointers.clear(); send({ type: 'touch', contacts: [] }); }
   function renderPresentation(value) {
     live = value.interactive;
-    for (const surface of [...screens, video, canvas, heldFrame]) surface.classList.toggle('stale', !value.visible);
+    for (const surface of [...screens, video, canvas, heldFrame].filter(Boolean)) surface.classList.toggle('stale', !value.visible);
     touchSurface.classList.toggle('stale', !live);
     $('waiting').hidden = value.visible;
     if (!live && pointers.size) release();
-    const transport = rtc && (rtc.active || value.frame?.transport === 'rtc') ? `${rtc.codec === 'H265' ? 'HEVC' : 'H.264'} / WebRTC${canvasOption.checked ? ' / Canvas' : ''}${rtcFps === null ? '' : ` · ${rtcFps} fps`}` : value.frame?.mime === 'image/webp' ? 'WebP' : 'JPEG';
+    const rtcVisible = rtc && value.visible && value.frame?.transport === 'rtc';
+    rendererStats.activeMode = rtcVisible ? launchMode : value.visible ? 'jpeg' : 'waiting';
+    const rendererLabel = launchMode === 'native' ? 'Video' : t(launchMode === 'video-canvas' ? 'web_video_renderer_compat' : 'web_video_renderer_direct');
+    const fallbackLabel = rendererStats.fallbackReason ? t(rendererStats.fallbackReason === 'processor-unsupported' ? 'web_video_renderer_unavailable' : 'web_video_renderer_failed') : '';
+    const transport = rtcVisible ? `${rtc.codec === 'H265' ? 'HEVC' : 'H.264'} / WebRTC / ${rendererLabel}${rtcFps === null ? '' : ` · ${rtcFps} fps`}` : `${value.frame?.mime === 'image/webp' ? 'WebP' : 'JPEG'}${fallbackLabel}`;
     $('status').textContent = value.state === 'recovering' ? t('web_video_recovering', transport) :
       value.visible ? value.interactive ? t('web_transport_touch_connected', transport, rtc?.recovering ? t('web_waiting_for_recovery') : '') :
         t('web_video_input_unavailable', transport) : t('web_connected_waiting_for_iphone_video');
@@ -842,9 +999,9 @@ if (typeof document !== 'undefined') {
   }
   function cleanupRtc() {
     if (rtc) rtc.close(); rtc = null; rtcRequested = false; rtcFps = null;
-    canvasRenderer.stop();
+    video = null;
     performanceStats.source = performanceStats.transport = performanceStats.receiver = performanceStats.image = null;
-    video.hidden = true;
+    rendererStats.activeMode = 'waiting';
   }
   function exitLaunchFullscreen() {
     try { Promise.resolve(document.exitFullscreen()).catch(() => {}); } catch (_) {}
@@ -890,7 +1047,7 @@ if (typeof document !== 'undefined') {
     const auth = pairingToken ? `token=${encodeURIComponent(pairingToken)}` : `code=${encodeURIComponent($('code').value)}`;
     const ws = new WebSocket(`${location.protocol === 'https:' ? 'wss' : 'ws'}://${location.host}/stream?${auth}&media=2&images=3`);
     ws.binaryType = 'arraybuffer';
-    const useCanvas = canvasOption.checked;
+    const mode = launchMode;
     socket = ws;
     const connectTimer = setTimeout(() => ws.close(), 8000);
     ws.onopen = () => {
@@ -908,21 +1065,34 @@ if (typeof document !== 'undefined') {
       webpSupport.then(supported => {
         if (supported && socket === ws && ws.readyState === WebSocket.OPEN) send({ type: 'image-format', format: 'webp' });
       });
-      rtc = createRtcReceiver(video, { send,
-        onTrack: () => { if (useCanvas) canvasRenderer.prepare(); },
-        onReset: () => { holdRtcFrame(); canvasRenderer.stop(); presentation.invalidate('rtc'); },
-        onReady: () => {
+      Object.assign(rendererStats, { selectedMode: mode, activeMode: 'waiting', renderedFps: null, renderedFrames: null,
+        fallbackReason: mode === 'track-canvas' && !processorSupported() ? 'processor-unsupported' : null });
+      rtc = createRtcReceiver(callbacks => {
+        if (mode === 'track-canvas') {
+          if (!processorSupported()) throw new Error('processor-unsupported');
+          return createTrackCanvasRenderer(canvas, callbacks);
+        }
+        return createVideoRenderer(mode, canvas, { ...callbacks, createVideo: createLegacyVideo });
+      }, { send,
+        onReset: () => { holdRtcFrame(); presentation.invalidate('rtc'); },
+        onResize: size => { if (socket === ws) showRtcSize(size); },
+        onReady: size => {
           if (socket !== ws) return;
-          if (useCanvas) { canvasRenderer.start(); return; }
-          if (!presentation.present(rtcMedia, video.videoWidth, video.videoHeight, 'rtc', rtcMedia.revision)) return;
-          jpeg.cancelPending(); jpeg.hide(); clearHeldFrame(); video.hidden = false;
-          width = video.videoWidth; height = video.videoHeight;
+          rendererStats.activeMode = mode; rendererStats.fallbackReason = null;
+          rendererStats.renderedFrames = mode === 'native' ? null : 1;
+          showRtcSize(size);
         },
-        onStop: () => {
+        onStop: reason => {
           if (socket !== ws) return;
-          video.hidden = true; rtcFps = null; presentation.invalidate('rtc');
+          video = null; rtcFps = null; rendererStats.fallbackReason = reason; rendererStats.renderedFps = null;
+          presentation.invalidate('rtc');
+        },
+        onStats: (fps, metrics) => {
+          const outputFps = mode === 'track-canvas' ? metrics.renderedFps : fps;
+          rtcFps = outputFps === null ? null : Math.round(outputFps); performanceStats.receiver = metrics;
+          rendererStats.renderedFps = metrics.renderedFps; rendererStats.renderedFrames = metrics.renderedFrames;
+          presentation.refresh();
         },
-        onStats: (fps, metrics) => { rtcFps = fps === null ? null : Math.round(fps); performanceStats.receiver = metrics; },
       });
       $('message').textContent = '';
       $('phone-connect').disabled = false;
@@ -977,7 +1147,8 @@ if (typeof document !== 'undefined') {
           }
           $('stage').textContent = data.stage || t("web_waiting_for_iphone_video");
           rtc.progress(data.rtcFrames || 0);
-          if (data.rtcAvailable && !rtcRequested && !rtc.active && typeof RTCPeerConnection !== 'undefined') {
+          if (data.rtcAvailable && !rtcRequested && !rtc.active && typeof RTCPeerConnection !== 'undefined' &&
+              (mode !== 'track-canvas' || processorSupported())) {
             rtcRequested = true; send({ type: 'rtc-start' });
           }
           // The server resets availability when the iPhone starts a new video configuration.
@@ -1040,6 +1211,7 @@ if (typeof document !== 'undefined') {
   }
   $('connect-form').addEventListener('submit', event => {
     event.preventDefault();
+    launchMode = selectedMode;
     const generation = ++authGeneration;
     prepareLaunchPresentation();
     stopQr(); $('connect').disabled = true; $('message').textContent = '';
@@ -1097,7 +1269,7 @@ if (typeof document !== 'undefined') {
     scheduleViewportReport();
   });
   // A separate layer prevents Android Chrome's native video gestures cancelling drags.
-  for (const surface of [...screens, video, canvas, touchSurface]) {
+  function bindSurface(surface) {
   surface.addEventListener('contextmenu', event => event.preventDefault());
   surface.addEventListener('pointerdown', event => {
     if (!live || pointers.size >= 2 || (event.pointerType === 'mouse' && event.button !== 0)) return;
@@ -1135,6 +1307,7 @@ if (typeof document !== 'undefined') {
   surface.addEventListener('pointercancel', up);
   surface.addEventListener('lostpointercapture', up);
   }
+  for (const surface of [...screens, canvas, touchSurface]) bindSurface(surface);
   window.addEventListener('blur', release);
   document.addEventListener('visibilitychange', () => { if (document.hidden) release(); presentation.refresh(); });
   window.addEventListener('pagehide', () => disconnect(false));
diff --git a/common/src/main/assets/web/index.html b/common/src/main/assets/web/index.html
index 6236972..edf5687 100644
--- a/common/src/main/assets/web/index.html
+++ b/common/src/main/assets/web/index.html
@@ -18,7 +18,11 @@ <h1 id="title">{{web_connect_your_carplay_display}}</h1>
 <p id="pair-instructions">{{web_for_the_first_connection_tap_scan_qr_code_to}}<br class="wide">{{web_then_scan_the_qr_code_below_and_allow_the}}</p>
 <label class="launch-option" for="hide-toolbar"><input id="hide-toolbar" type="checkbox"><span><strong>{{web_hide_top_bar_after_connecting}}</strong><small>{{web_let_carplay_fill_the_page_refresh_to_return_to}}</small></span></label>
 <label class="launch-option" for="fullscreen-on-start"><input id="fullscreen-on-start" type="checkbox"><span><strong>{{web_hide_top_bar_enter_full_screen_on_start}}</strong><small>{{web_enter_full_screen_when_starting_and_hide_the_top}}</small></span></label>
-<label class="launch-option" for="canvas-video"><input id="canvas-video" type="checkbox"><span><strong>{{web_display_video_with_canvas_experimental}}</strong><small>{{web_decode_video_offscreen_then_draw_it_on_a_canvas}}</small></span></label>
+<fieldset class="renderer-options"><legend>{{web_video_renderer_title}}</legend><div class="renderer-cards">
+<label id="renderer-native-card" class="renderer-card" for="renderer-native"><input id="renderer-native" type="radio" name="video-renderer" value="native" checked><span><strong>{{web_video_renderer_native}}</strong><small>{{web_video_renderer_native_description}}</small></span></label>
+<label id="renderer-video-canvas-card" class="renderer-card" for="renderer-video-canvas"><input id="renderer-video-canvas" type="radio" name="video-renderer" value="video-canvas"><span><strong>{{web_video_renderer_compat}}</strong><em>{{web_video_renderer_experimental}}</em><small>{{web_video_renderer_compat_description}}</small></span></label>
+<label id="renderer-track-canvas-card" class="renderer-card" for="renderer-track-canvas"><input id="renderer-track-canvas" type="radio" name="video-renderer" value="track-canvas"><span><strong>{{web_video_renderer_direct}}</strong><em>{{web_video_renderer_experimental}}</em><small>{{web_video_renderer_direct_description}}</small></span></label>
+</div><p id="renderer-hint" class="renderer-hint" role="status" hidden>{{web_video_renderer_hint}}</p></fieldset>
 <label class="launch-option" for="ignore-browser-zoom"><input id="ignore-browser-zoom" type="checkbox"><span><strong>{{web_ignore_browser_zoom}}</strong><small>{{web_ignore_browser_zoom_help}}</small></span></label>
 <details class="secure-setup" id="secure-setup"><summary>{{web_browser_microphone_requires_https}}</summary><p>{{web_local_http_pages_cannot_request_microphone_permission_in_the}}</p><code id="tls-fingerprint">{{web_loading}}</code><div class="secure-links"><a href="/certificate.crt" download="wheelplay-certificate.crt">{{web_download_local_certificate}}</a><a id="https-entry" href="#">{{web_open_https_page}}</a></div><p id="tls-error" role="status"></p></details>
 <div id="remembered-device" role="status" hidden><strong id="device-name"></strong><p id="device-status">{{web_pairing_restored_choose_the_options_above_then_tap_start}}</p></div>
@@ -33,7 +37,6 @@ <h1 id="title">{{web_connect_your_carplay_display}}</h1>
 <img id="screen-third" alt="{{web_live_carplay_display}}" draggable="false" hidden>
 <canvas id="held-frame" width="0" height="0" aria-label="{{web_live_carplay_display}}" hidden></canvas>
 <div id="media-message" role="status" aria-live="polite" hidden></div>
-<video id="video" aria-label="{{web_live_carplay_video}}" autoplay muted playsinline disablepictureinpicture hidden></video>
 <canvas id="video-canvas" width="0" height="0" aria-label="{{web_live_carplay_video_canvas}}" hidden></canvas>
 <div id="touch-surface" aria-hidden="true"></div>
 <div id="audio-message" hidden role="status" aria-live="polite"></div>
diff --git a/common/src/main/assets/web/style.css b/common/src/main/assets/web/style.css
index fd28da6..3541707 100644
--- a/common/src/main/assets/web/style.css
+++ b/common/src/main/assets/web/style.css
@@ -16,3 +16,5 @@
 #screen-next,#screen-third,#held-frame{width:100%;height:100%;object-fit:contain;touch-action:none;user-select:none;-webkit-user-select:none}#screen-next.stale,#screen-third.stale,#held-frame.stale{opacity:.2;pointer-events:none}
 
 #media-message{position:absolute;left:16px;top:16px;z-index:2;max-width:85%;padding:10px 14px;background:#1c2428e8;border-radius:12px;font-size:13px;color:#efbe90;pointer-events:none}
+
+.renderer-options{border:0;margin:28px 0 0;padding:0;min-width:0}.renderer-options legend{padding:0;margin-bottom:12px;font-size:15px;font-weight:600}.renderer-cards{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:12px}.renderer-card{display:flex;align-items:flex-start;gap:12px;margin:0;padding:18px 16px;min-height:130px;border:1px solid #46514e;border-radius:12px;background:#1c2428;cursor:pointer}.renderer-card.selected{border-color:#b4d9b1;background:#24352c;box-shadow:inset 0 0 0 1px #b4d9b1}.renderer-card input{appearance:auto;accent-color:#b4d9b1;flex:0 0 auto;width:20px;height:20px;margin:2px 0 0;padding:0;letter-spacing:0}.renderer-card span{display:flex;flex-wrap:wrap;align-items:center;gap:6px}.renderer-card strong{font-size:15px;line-height:1.5}.renderer-card em{font-style:normal;font-size:11px;color:#b4d9b1;border:1px solid #465e4b;border-radius:4px;padding:1px 5px}.renderer-card small{flex-basis:100%;margin-top:3px;font-size:13px;line-height:1.6;color:#b5beb9}.renderer-hint{font-size:13px;line-height:1.6;color:#efbe90;margin:12px 0 0}@media(max-width:759px){.renderer-cards{grid-template-columns:1fr}.renderer-card{min-height:0;padding:16px}}
diff --git a/common/src/main/java/com/shilapi/xcertplay/web/BrowserStrings.kt b/common/src/main/java/com/shilapi/xcertplay/web/BrowserStrings.kt
index 37c96db..eea2119 100644
--- a/common/src/main/java/com/shilapi/xcertplay/web/BrowserStrings.kt
+++ b/common/src/main/java/com/shilapi/xcertplay/web/BrowserStrings.kt
@@ -9,6 +9,8 @@ import org.json.JSONObject
 internal object BrowserStrings {
     private val resources =
         mapOf(
+            "web_video_recovering" to UiR.string.web_video_recovering,
+            "web_video_input_unavailable" to UiR.string.web_video_input_unavailable,
             "web_ignore_browser_zoom" to UiR.string.web_ignore_browser_zoom,
             "web_ignore_browser_zoom_help" to UiR.string.web_ignore_browser_zoom_help,
             "web_browser_paired" to UiR.string.web_browser_paired,
@@ -118,6 +120,17 @@ internal object BrowserStrings {
                 UiR.string.web_display_video_with_canvas_experimental,
             "web_decode_video_offscreen_then_draw_it_on_a_canvas" to
                 UiR.string.web_decode_video_offscreen_then_draw_it_on_a_canvas,
+            "web_video_renderer_title" to UiR.string.web_video_renderer_title,
+            "web_video_renderer_native" to UiR.string.web_video_renderer_native,
+            "web_video_renderer_native_description" to UiR.string.web_video_renderer_native_description,
+            "web_video_renderer_compat" to UiR.string.web_video_renderer_compat,
+            "web_video_renderer_compat_description" to UiR.string.web_video_renderer_compat_description,
+            "web_video_renderer_direct" to UiR.string.web_video_renderer_direct,
+            "web_video_renderer_direct_description" to UiR.string.web_video_renderer_direct_description,
+            "web_video_renderer_experimental" to UiR.string.web_video_renderer_experimental,
+            "web_video_renderer_hint" to UiR.string.web_video_renderer_hint,
+            "web_video_renderer_unavailable" to UiR.string.web_video_renderer_unavailable,
+            "web_video_renderer_failed" to UiR.string.web_video_renderer_failed,
             "web_browser_microphone_requires_https" to
                 UiR.string.web_browser_microphone_requires_https,
             "web_local_http_pages_cannot_request_microphone_permission_in_the" to
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index 8017d3d..d76874f 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -37,6 +37,18 @@ Web 服务由 DiPlaySessionService 创建/销毁；离屏 Surface 生命周期
 新网页另外协商 [v2 媒体版本](MEDIA_PRESENTATION.md)及 [v3 图片格式与流水线](IMAGE_STREAM.md)：
 v3 可使用 WebP，最多两帧在途，并以媒体版本和帧序号精确 ACK；上述原始 JPEG 协议仍供旧客户端使用。
 
+## 浏览器三种渲染方式
+
+`native` 为默认原生 Video；`video-canvas` 使用离屏 Video 与可见 Canvas；实验性 `track-canvas` 使用主线程 `MediaStreamTrackProcessor({ track, maxBufferSize: 1 })` → `VideoFrame` → Canvas 2D。不新增网络消息、解码器或依赖。两个旧模式按需创建自己的 Video 元素，停止时移除；直接 Canvas 及其 JPEG 回退期间不创建 Video。
+
+接收器通过渲染器工厂创建适配器，调用 `start(track, streams)`、`stop()` 和 `snapshot()`，由适配器报告首次就绪、尺寸变化及错误。接收器持有 PeerConnection、远端轨道及恢复计时器；适配器持有 reader、绘制上下文、元素及绘制回调。关闭先使代次失效，再停止适配器、移除监听、停止远端轨道并关闭 PeerConnection；取消读取不阻塞重连，读取结束后释放锁。每个读出的 VideoFrame 均在 finally 中 close，包含错误和过期帧。
+
+两种 Canvas 仅在首次绘制成功后发送 `rtc-ready`。画面尺寸来自实际显示帧或 JPEG，心跳中的默认宽高不能覆盖它，以避免竖屏触控失准。直接 Canvas 不要求 `VideoDecoder` 或安全上下文检测；按主线程 Processor 的实际可用性判断，Worker-only 实现使用 JPEG。
+
+偏好键 `wheelplay.videoRenderer` 保存三种模式；有效新值优先，否则旧 `wheelplay.canvasVideo=true` 迁移为 `video-canvas`，其余默认 native。只写新键并保留旧键；连接时固定模式，自动重连沿用。缺少 Processor 时跳过 rtc-start 并记录本地原因，运行失败使用现有 rtc-fallback，不改变用户选择。
+
+`wheelplayStats.presentation` 包含 selectedMode、activeMode（含 waiting / jpeg）、renderedFps、renderedFrames、fallbackReason。绘制指标为 Canvas 的成功提交次数，不代表屏幕刷新率；兼容 Canvas 的补偿重绘可能重复同一解码帧。receiver 保留现有统计字段并新增 renderedFps / renderedFrames，rtc-feedback 仍报告 WebRTC framesDecoded。
+
 ## 生命周期与资源约束
 
 - 每个媒体 sink 有独立的离屏输出和代次编号；旧会话结束不会覆盖/清空新会话画面。
diff --git a/docs/WEBRTC_RECOVERY.md b/docs/WEBRTC_RECOVERY.md
index e879d3f..ca07a64 100644
--- a/docs/WEBRTC_RECOVERY.md
+++ b/docs/WEBRTC_RECOVERY.md
@@ -58,6 +58,14 @@ WebSocket 控制连接的心跳与重连规则独立于视频策略；整个网
 - `expiredFrames` / `overflowFrames` 持续上升：优先检查 Android CPU 调度、发送耗时和帧大小。容忍时间能等待关键帧恢复，但不会消除持续过载。
 - 发送速率正常，接收速率下降，`lost` / `nack` / RTT 升高：优先检查 Wi-Fi 信号、热点负载、UDP 限制。HTTP 能访问不代表 WebRTC 的 UDP 路径正常；项目没有外部 STUN / TURN。
 - 接收正常，解码速率停顿：检查浏览器编码兼容性，先禁用 iPhone HEVC，使用 H.264 对比。
-- 解码正常，呈现停顿：检查车机浏览器视频渲染，可对比网页的 Canvas 实验选项。
+- 解码正常，呈现停顿：检查车机浏览器视频渲染，可对比网页的「兼容 Canvas」与「直接 Canvas」实验选项。
 
 真机需分别验证 4 / 10 / 30 秒策略：播放动态画面，制造短于阈值的 UDP 丢包或短暂断开，确认保留 WebRTC 并恢复新画面；持续阻断超过阈值，确认回退 JPEG，并按退避间隔尝试新连接；解除阻断后确认 JPEG 持续显示和可操作，视频首帧到来后切回；静态画面停留一分钟后操作，确认没有立即回退；再检查触控、音频和浏览器自动重连。自动化测试覆盖策略、超时边界、重试与会话隔离，但不能证明某款 Tesla 浏览器或热点的实际兼容性。
+
+## 直接 Canvas 的恢复与回退
+
+直接 Canvas 缺少主线程 Processor 时不请求 WebRTC，保留 JPEG；前端仍记录 `processor-unsupported` 并显示提示，不依赖服务端 fallback 字段。已收到 offer 后发现不可用时发送匹配 ID 的 rtc-fallback。Processor 构造、读取、绘制错误或轨道意外结束立即回退；回退保留控制和音频通道，释放触点、reader 及 Canvas 缓冲，不转用旧 Video 模式。
+
+首次成功绘制之前保持 JPEG，首帧等待 `max(10000ms, recoveryGraceMs)`。持续发送时分别检查解码和绘制进展，即使 framesDecoded 增长而画布不再更新，也会在所选容忍时间后回退。没有新输入的静态画面不触发渲染停滞；恢复输入时重新计时。连接短暂断开时仍保留最后一帧。
+
+`presentation.fallbackReason` 区分 processor-unsupported、renderer-error、track-ended、first-frame-timeout、decode-stalled、render-stalled、stats-unavailable、connection-failed、codec-unsupported 等原因；server-stop 表示服务端停止本次媒体。选择保留，重新连接或视频配置变化后允许重试。直接 Canvas 状态栏使用 renderedFps，原生 Video 与兼容 Canvas 继续使用 presentedFps / decodedFps。
diff --git a/shared/src/main/res/values-zh-rCN/ui_strings.xml b/shared/src/main/res/values-zh-rCN/ui_strings.xml
index 5f563a1..e406317 100644
--- a/shared/src/main/res/values-zh-rCN/ui_strings.xml
+++ b/shared/src/main/res/values-zh-rCN/ui_strings.xml
@@ -545,4 +545,16 @@
     <string name="web_ignore_browser_zoom_help">浏览器缩放变化时，让 CarPlay 画面保持适配可见区域。此浏览器会记住选择。</string>
     <string name="web_video_recovering">%1$s · 等待恢复 · 触控已暂停</string>
     <string name="web_video_input_unavailable">%1$s · 等待触控输入</string>
+
+    <string name="web_video_renderer_title">视频显示方式</string>
+    <string name="web_video_renderer_native">原生 Video</string>
+    <string name="web_video_renderer_native_description">默认方式，直接显示视频。</string>
+    <string name="web_video_renderer_compat">兼容 Canvas</string>
+    <string name="web_video_renderer_compat_description">使用离屏视频解码，再绘制到画布。</string>
+    <string name="web_video_renderer_direct">直接 Canvas</string>
+    <string name="web_video_renderer_direct_description">不使用视频元素；不支持时使用 JPEG。</string>
+    <string name="web_video_renderer_experimental">实验性</string>
+    <string name="web_video_renderer_hint">此浏览器不支持直接 Canvas，连接后将使用 JPEG。</string>
+    <string name="web_video_renderer_unavailable">（直接 Canvas 不可用，已使用 JPEG）</string>
+    <string name="web_video_renderer_failed">（视频中断，已回退 JPEG）</string>
 </resources>
diff --git a/shared/src/main/res/values-zh-rTW/ui_strings.xml b/shared/src/main/res/values-zh-rTW/ui_strings.xml
index 17855f4..95ba350 100644
--- a/shared/src/main/res/values-zh-rTW/ui_strings.xml
+++ b/shared/src/main/res/values-zh-rTW/ui_strings.xml
@@ -545,4 +545,16 @@
     <string name="web_ignore_browser_zoom_help">瀏覽器縮放變化時，讓 CarPlay 畫面保持適配可見區域。此瀏覽器會記住選擇。</string>
     <string name="web_video_recovering">%1$s · 等待恢復 · 觸控已暫停</string>
     <string name="web_video_input_unavailable">%1$s · 等待觸控輸入</string>
+
+    <string name="web_video_renderer_title">影片顯示方式</string>
+    <string name="web_video_renderer_native">原生 Video</string>
+    <string name="web_video_renderer_native_description">預設方式，直接顯示影片。</string>
+    <string name="web_video_renderer_compat">相容 Canvas</string>
+    <string name="web_video_renderer_compat_description">使用離螢幕影片解碼，再繪製到畫布。</string>
+    <string name="web_video_renderer_direct">直接 Canvas</string>
+    <string name="web_video_renderer_direct_description">不使用影片元素；不支援時使用 JPEG。</string>
+    <string name="web_video_renderer_experimental">實驗性</string>
+    <string name="web_video_renderer_hint">此瀏覽器不支援直接 Canvas，連線後將使用 JPEG。</string>
+    <string name="web_video_renderer_unavailable">（直接 Canvas 無法使用，已使用 JPEG）</string>
+    <string name="web_video_renderer_failed">（影片中斷，已改用 JPEG）</string>
 </resources>
diff --git a/shared/src/main/res/values/ui_strings.xml b/shared/src/main/res/values/ui_strings.xml
index 574b9be..e874cd5 100644
--- a/shared/src/main/res/values/ui_strings.xml
+++ b/shared/src/main/res/values/ui_strings.xml
@@ -545,4 +545,16 @@
     <string name="web_ignore_browser_zoom_help">Keep the CarPlay display fitted to the visible area when the browser zoom changes. Saved for this browser.</string>
     <string name="web_video_recovering">%1$s · Waiting for recovery · Touch paused</string>
     <string name="web_video_input_unavailable">%1$s · Waiting for touch input</string>
+
+    <string name="web_video_renderer_title">Video display mode</string>
+    <string name="web_video_renderer_native">Native Video</string>
+    <string name="web_video_renderer_native_description">Default mode. Display video directly.</string>
+    <string name="web_video_renderer_compat">Compatibility Canvas</string>
+    <string name="web_video_renderer_compat_description">Decode with an offscreen video element, then draw to the canvas.</string>
+    <string name="web_video_renderer_direct">Direct Canvas</string>
+    <string name="web_video_renderer_direct_description">No video element. Use JPEG if unsupported.</string>
+    <string name="web_video_renderer_experimental">Experimental</string>
+    <string name="web_video_renderer_hint">This browser does not support Direct Canvas. JPEG will be used after connecting.</string>
+    <string name="web_video_renderer_unavailable"> (Direct Canvas unavailable; using JPEG)</string>
+    <string name="web_video_renderer_failed"> (video interrupted; using JPEG)</string>
 </resources>
diff --git a/test/localization.test.js b/test/localization.test.js
index fe1559f..880f846 100644
--- a/test/localization.test.js
+++ b/test/localization.test.js
@@ -29,3 +29,16 @@ test('localized messages preserve positional arguments without interpreting thei
 test('browser template interpolation escapes markup', () => {
   assert.equal(renderBrowserTemplate('<p>{{text}}</p>', { text: '"<&' }), '<p>&quot;&lt;&amp;</p>');
 });
+
+test('Android exports every browser template and literal message key, not just the desktop fixture', () => {
+  const android = readFileSync(new URL('../common/src/main/java/com/shilapi/xcertplay/web/BrowserStrings.kt', import.meta.url), 'utf8');
+  const keys = new Set([...android.matchAll(/"([a-z0-9_]+)"\s+to\s+UiR\.string\.([a-z0-9_]+)/g)].map(match => {
+    assert.equal(match[1], match[2]); return match[1];
+  }));
+  const required = [...template.matchAll(/\{\{([a-z0-9_]+)\}\}/g)].map(match => match[1]);
+  for (const name of ['app.js', 'browser-audio.js']) {
+    const js = readFileSync(new URL(`../common/src/main/assets/web/${name}`, import.meta.url), 'utf8');
+    required.push(...[...js.matchAll(/\bt\(['"]([a-z0-9_]+)['"]/g)].map(match => match[1]));
+  }
+  for (const key of required) if (key !== 'locale') assert.ok(keys.has(key), `Android BrowserStrings is missing ${key}`);
+});
diff --git a/test/pairing.test.js b/test/pairing.test.js
index 27a5cf4..5f7649f 100644
--- a/test/pairing.test.js
+++ b/test/pairing.test.js
@@ -64,12 +64,12 @@ test('QR approval remembers the browser and waits for the explicit launch button
   assert.equal(f.element('code').required, false);
   assert.equal(f.element('connect-label').textContent, '启动显示');
   assert.deepEqual(JSON.parse(f.preferences.get('wheelplay.browserDevice')), savedDevice);
-  f.element('hide-toolbar').checked = true; f.element('canvas-video').checked = true;
+  f.element('hide-toolbar').checked = true; f.element('renderer-video-canvas').checked = true;
   f.submit(); await flush();
   assert.equal(f.sockets.length, 1);
   assert.equal(f.sockets[0].url, 'ws://server:8080/stream?token=resumed-token&media=2&images=3');
   assert.equal(f.element('hide-toolbar').checked, true);
-  assert.equal(f.element('canvas-video').checked, true);
+  assert.equal(f.element('renderer-video-canvas').checked, true);
   assert.equal(f.requests.some(r => r.url.endsWith('/cancel')), false);
 });
 
diff --git a/test/stream-client.test.js b/test/stream-client.test.js
index d640b1c..6af244f 100644
--- a/test/stream-client.test.js
+++ b/test/stream-client.test.js
@@ -9,13 +9,14 @@ const source = readFileSync(new URL('../common/src/main/assets/web/text.js', imp
   .replace(/^import .*text\.js';$/m, '').replaceAll('export function', 'function') + '\n' +
   readFileSync(new URL('../common/src/main/assets/web/app.js', import.meta.url), 'utf8')
     .replace(/^import .*browser-audio\.js';$/m, '').replace(/^import .*text\.js';$/m, '').replaceAll('export function', 'function');
-function fixture({ storedCanvas = null, storedIgnoreZoom = null, storageDisabled = false, canvasAvailable = true, supportsWebp = false,
+function fixture({ storedCanvas = null, storedMode = null, processorAvailable = true, storedIgnoreZoom = null, storageDisabled = false, canvasAvailable = true, supportsWebp = false,
   geometry = null, visual = null,
   fullscreen = 'supported', codeDenied = false, resume = () => ({ token: 'session-token', name: 'Chrome' }) } = {}) {
   const elements = new Map(), timers = new Map(), raf = new Map(), sockets = [], peers = [], draws = [];
   const preferences = new Map(storedCanvas === null ? [] : [['wheelplay.canvasVideo', storedCanvas]]);
   if (storedIgnoreZoom !== null) preferences.set('wheelplay.ignoreBrowserZoom', storedIgnoreZoom);
-  const videoCallbacks = new Map();
+  const videoCallbacks = new Map(), createdVideos = [], processors = [];
+  if (storedMode !== null) preferences.set('wheelplay.videoRenderer', storedMode);
   const documentEvents = {}, fullscreenCalls = [];
   const visualEvents = {};
   const visualViewport = visual ? { ...visual, addEventListener(type, fn) { visualEvents[type] = fn; } } : undefined;
@@ -24,7 +25,7 @@ function fixture({ storedCanvas = null, storedIgnoreZoom = null, storageDisabled
   let nextTimer = 0, nextFrame = 0, clockNow = 1000;
   const element = id => {
     const classes = new Set();
-    if (!elements.has(id)) elements.set(id, { hidden: false, value: '123456', handlers: {}, naturalWidth: 1280, naturalHeight: 720,
+    if (!elements.has(id)) elements.set(id, { hidden: id === 'video-canvas', complete: true, value: '123456', handlers: {}, naturalWidth: 1280, naturalHeight: 720,
       checked: false, videoWidth: 1280, videoHeight: 720, readyState: 2, currentTime: 0,
       style: { removeProperty(name) { delete this[name]; } },
       parentElement: { getBoundingClientRect: () => mainRect },
@@ -33,6 +34,8 @@ function fixture({ storedCanvas = null, storedIgnoreZoom = null, storageDisabled
       requestVideoFrameCallback(fn) { const frame = ++nextFrame; videoCallbacks.set(frame, fn); return frame; },
       cancelVideoFrameCallback(frame) { videoCallbacks.delete(frame); },
       classList: { toggle(name, enabled) { if (enabled) classes.add(name); else classes.delete(name); }, contains: name => classes.has(name) },
+      remove() { this.hidden = true; this.removed = true; },
+      insertBefore(child) { child.removed = false; },
       removeAttribute() {}, setAttribute() {}, setPointerCapture() {},
       getBoundingClientRect() {
         if (id !== 'display' || !classes.has('ignore-browser-zoom')) return mainRect;
@@ -56,7 +59,7 @@ function fixture({ storedCanvas = null, storedIgnoreZoom = null, storageDisabled
     async setLocalDescription() {}
     close() { this.closed = true; }
   }
-  const document = { getElementById: element, fullscreenElement: null, documentElement: {},
+  const document = { createElement(tag) { assert.equal(tag, 'video'); const video = element('video'); createdVideos.push(video); return video; }, getElementById: element, fullscreenElement: null, documentElement: {},
     addEventListener(name, fn) { documentEvents[name] = fn; },
     exitFullscreen() {
       fullscreenCalls.push('exit'); this.fullscreenElement = null;
@@ -78,6 +81,17 @@ function fixture({ storedCanvas = null, storedIgnoreZoom = null, storageDisabled
     },
   },
     location: { host: 'server:8080' }, URL: { createObjectURL: () => 'blob:frame', revokeObjectURL() {} }, Date, WebSocket: Socket,
+    MediaStreamTrackProcessor: processorAvailable ? class {
+      constructor(init) {
+        this.init = init; this.pending = [];
+        this.reader = {
+          read: () => new Promise(resolve => this.pending.push(resolve)),
+          cancel: () => { this.canceled = true; this.pending.splice(0).forEach(resolve => resolve({ done: true })); },
+          releaseLock: () => { this.released = true; },
+        };
+        this.readable = { getReader: () => this.reader }; processors.push(this);
+      }
+    } : undefined,
     ArrayBuffer, DataView, Blob,
     RTCPeerConnection: Peer, performance: { now: () => clockNow },
     setTimeout(fn, delay) { const id = ++nextTimer; timers.set(id, { fn, delay, at: clockNow + delay }); return id; },
@@ -98,7 +112,7 @@ function fixture({ storedCanvas = null, storedIgnoreZoom = null, storageDisabled
   };
   context.wheelplayMessages = messages;
   vm.runInNewContext(source, context);
-  return { element, sockets, timers, peers, draws, preferences, raf, videoCallbacks, document, fullscreenCalls, visualViewport, visualEvents,
+  return { element, sockets, timers, peers, draws, preferences, raf, videoCallbacks, document, fullscreenCalls, createdVideos, processors, visualViewport, visualEvents,
     reportViewport() {
       const [id, timer] = [...timers].find(([, t]) => t.delay === 180);
       timers.delete(id); timer.fn();
@@ -111,6 +125,13 @@ function fixture({ storedCanvas = null, storedIgnoreZoom = null, storageDisabled
         timers.delete(entry[0]); entry[1].fn();
       }
     },
+    stats: () => context.window.wheelplayStats,
+    select(mode) { element(`renderer-${mode}`).checked = true; element(`renderer-${mode}`).handlers.change(); },
+    async decoded(width = 1280, height = 720) {
+      const frame = { displayWidth: width, displayHeight: height, closes: 0, close() { this.closes++; } };
+      processors.at(-1).pending.shift()({ value: frame, done: false });
+      await new Promise(resolve => setImmediate(resolve)); return frame;
+    },
     async connect() {
       element('connect-form').handlers.submit({ preventDefault() {} });
       await new Promise(resolve => setImmediate(resolve));
@@ -120,7 +141,7 @@ function fixture({ storedCanvas = null, storedIgnoreZoom = null, storageDisabled
     async offer(ws, id = 1, meta = {}) {
       ws.onmessage({ data: JSON.stringify({ type: 'rtc-offer', id, sdp: 'offer', ...meta }) });
       await new Promise(resolve => setImmediate(resolve));
-      peers.at(-1).ontrack({ streams: [{}] });
+      peers.at(-1).ontrack({ track: { stop() {} }, streams: [{}] });
       await new Promise(resolve => setImmediate(resolve));
     },
     pointer(type, x = 100, surface = 'screen') { element(surface).handlers[type]({ pointerId: 1, pointerType: 'touch', clientX: x, clientY: 100, preventDefault() {} }); },
@@ -256,14 +277,19 @@ test('pending movement is cancelled at up before another down', async () => {
   assert.deepEqual(ws.sent.filter(m => m.type === 'touch').map(m => m.contacts[0].down), [true, false, true]);
 });
 
-test('Canvas preference defaults off, persists per browser, and tolerates unavailable storage', async () => {
-  const defaults = fixture(); assert.equal(defaults.element('canvas-video').checked, false);
-  const f = fixture({ storedCanvas: 'true' }); assert.equal(f.element('canvas-video').checked, true);
-  f.element('canvas-video').checked = false; f.element('canvas-video').handlers.change();
-  assert.equal(f.preferences.get('wheelplay.canvasVideo'), 'false');
-  const denied = fixture({ storageDisabled: true });
-  denied.element('canvas-video').checked = true; denied.element('canvas-video').handlers.change();
+test('renderer defaults, legacy migration, new preference precedence and storage errors', async () => {
+  const defaults = fixture(); assert.equal(defaults.element('renderer-native').checked, true);
+  const f = fixture({ storedCanvas: 'true' }); assert.equal(f.element('renderer-video-canvas').checked, true);
+  f.select('track-canvas');
+  assert.equal(f.preferences.get('wheelplay.videoRenderer'), 'track-canvas');
+  assert.equal(f.preferences.get('wheelplay.canvasVideo'), 'true');
+  assert.equal(f.element('renderer-video-canvas').checked, false);
+  const preferred = fixture({ storedCanvas: 'true', storedMode: 'native' });
+  assert.equal(preferred.element('renderer-native').checked, true);
+  assert.equal(fixture({ storedCanvas: 'true', storedMode: 'invalid' }).element('renderer-video-canvas').checked, true);
+  const denied = fixture({ storageDisabled: true }); denied.select('track-canvas');
   assert.equal((await denied.connect()).readyState, 1);
+  assert.equal(denied.stats().presentation.selectedMode, 'track-canvas');
 });
 
 test('default WebRTC presents native video without allocating a Canvas', async () => {
@@ -301,7 +327,7 @@ test('Canvas WebRTC handles touch, late JPEG loads, and reconnection without lea
   f.pointer('pointerdown', 100, 'touch-surface'); f.pointer('pointerup', 100, 'touch-surface');
   assert.deepEqual(ws.sent.filter(m => m.type === 'touch').map(m => m.contacts[0].down), [true, false]);
   ws.onmessage({ data: JSON.stringify({ type: 'status', width: 1280, height: 720, streaming: true, rtcAvailable: true }) });
-  assert.match(f.element('status').textContent, /WebRTC \/ Canvas/);
+  assert.match(f.element('status').textContent, /WebRTC \/ 兼容 Canvas/);
   const lateFrames = [...f.videoCallbacks.values()], lateRefresh = [...f.raf.values()];
   ws.close(); assert.equal(f.element('video-canvas').hidden, true);
   assert.equal(f.videoCallbacks.size, 0); assert.equal(f.raf.size, 0);
@@ -320,10 +346,10 @@ test('Canvas failure falls back to JPEG while control and the selected preferenc
   assert.equal(f.timers.size > 0 && [...f.timers.values()].some(t => t.delay === 1000), false);
   assert.equal(ws.sent.at(-1).type, 'rtc-fallback');
   assert.equal(ws.sent.at(-1).retryable, false);
-  f.frame(ws); assert.equal(f.element('screen').hidden, false);
+  f.frame(ws); assert.equal(['screen', 'screen-next', 'screen-third'].some(id => !f.element(id).hidden), true);
   f.pointer('pointerdown', 100, 'touch-surface'); f.pointer('pointerup', 100, 'touch-surface');
   assert.equal(ws.sent.filter(m => m.type === 'touch').length, 2);
-  assert.equal(f.element('canvas-video').checked, true);
+  assert.equal(f.element('renderer-video-canvas').checked, true);
 });
 
 
@@ -507,7 +533,7 @@ test('automatic RTC retry preserves JPEG and touch until the new video frame is
     assert.equal(ws.sent.filter(message => message.type === 'touch').at(-1).contacts[0].down, false);
     ws.onmessage({ data: videoPacket(1) }); finishJpeg(f);
     const second = f.peers.at(-1);
-    second.ontrack({ streams: [{}] }); await new Promise(resolve => setImmediate(resolve));
+    second.ontrack({ track: { stop() {} }, streams: [{}] }); await new Promise(resolve => setImmediate(resolve));
     assert.equal([f.element('screen'), f.element('screen-next')].every(image => image.hidden), true);
     assert.equal(f.element(storedCanvas ? 'video-canvas' : 'video').hidden, false);
     assert.equal(f.element('waiting').hidden, true);
@@ -631,7 +657,7 @@ test('an RTC rebuild keeps a frozen picture and rejects the previous offer and f
     const f = fixture({ storedCanvas }), ws = await f.connect(); mediaStatus(ws);
     ws.onmessage({ data: JSON.stringify({ type: 'rtc-offer', id: 1, sdp: 'offer', sessionId: 7, videoEpoch: 1 }) });
     await new Promise(resolve => setImmediate(resolve));
-    f.peers.at(-1).ontrack({ streams: [{}] }); await new Promise(resolve => setImmediate(resolve));
+    f.peers.at(-1).ontrack({ track: { stop() {} }, streams: [{}] }); await new Promise(resolve => setImmediate(resolve));
     const oldCallbacks = [...f.videoCallbacks.values()];
     mediaStatus(ws, { videoEpoch: 2 });
     assert.equal(f.element('held-frame').hidden, false);
@@ -658,3 +684,148 @@ test('stopped media immediately covers an old image and a reconnected session ne
   current.onmessage({ data: videoPacket(3) }); finishJpeg(f);
   assert.equal(f.element('waiting').hidden, true);
 });
+
+
+test('Direct Canvas waits for drawing and never creates Video through recovery, fallback and reconnection', async () => {
+  const f = fixture({ storedMode: 'track-canvas' }), ws = await f.connect();
+  f.frame(ws);
+  ws.onmessage({ data: {} }); const lateJpeg = f.element('screen-next').onload;
+  await f.offer(ws);
+  assert.equal(ws.sent.some(m => m.type === 'rtc-ready'), false);
+  assert.equal(f.element('screen').hidden, false);
+  const frame = await f.decoded(); assert.equal(frame.closes, 1);
+  assert.equal(ws.sent.filter(m => m.type === 'rtc-ready').length, 1);
+  lateJpeg(); assert.equal(f.element('screen').hidden, true);
+  assert.equal(f.element('video-canvas').hidden, false);
+  assert.equal(f.processors[0].init.maxBufferSize, 1);
+  const peer = f.peers.at(-1);
+  peer.connectionState = 'disconnected'; peer.onconnectionstatechange();
+  assert.equal(f.element('video-canvas').hidden, false);
+  peer.connectionState = 'connected'; peer.onconnectionstatechange();
+  f.pointer('pointerdown', 100, 'touch-surface');
+  f.processors.at(-1).pending.shift()({ done: true });
+  await new Promise(resolve => setImmediate(resolve));
+  assert.equal(ws.readyState, 1);
+  assert.equal(f.stats().presentation.fallbackReason, 'track-ended');
+  assert.equal(f.element('video-canvas').width, 0);
+  assert.equal(ws.sent.filter(m => m.type === 'touch').at(-1).contacts.length, 0);
+  f.frame(ws); assert.equal(['screen', 'screen-next', 'screen-third'].some(id => !f.element(id).hidden), true);
+  ws.close();
+  const next = await f.connect(); await f.offer(next, 2); await f.decoded();
+  assert.equal(f.createdVideos.length, 0);
+  assert.equal(f.stats().presentation.activeMode, 'track-canvas');
+  assert.equal(f.processors[0].released, true);
+});
+
+test('unsupported Direct Canvas skips rtc-start and handles an unexpected offer without Video', async () => {
+  const f = fixture({ storedMode: 'track-canvas', processorAvailable: false }), ws = await f.connect();
+  assert.equal(f.element('renderer-hint').hidden, false);
+  for (let i = 0; i < 3; i++) ws.onmessage({ data: JSON.stringify({ type: 'status', streaming: true, rtcAvailable: true }) });
+  assert.equal(ws.sent.some(m => m.type === 'rtc-start'), false);
+  f.frame(ws);
+  assert.match(f.element('status').textContent, /直接 Canvas 不可用/);
+  ws.onmessage({ data: JSON.stringify({ type: 'rtc-offer', id: 9, sdp: 'offer' }) });
+  await new Promise(resolve => setImmediate(resolve));
+  assert.equal(ws.sent.filter(m => m.type === 'rtc-fallback').length, 1);
+  assert.equal(f.createdVideos.length, 0);
+  assert.equal(f.preferences.get('wheelplay.videoRenderer'), 'track-canvas');
+});
+
+test('Direct Canvas resize controls touch mapping even after server status reports landscape', async () => {
+  const f = fixture({ storedMode: 'track-canvas' }), ws = await f.connect(); await f.offer(ws);
+  await f.decoded(720, 1280);
+  ws.onmessage({ data: JSON.stringify({ type: 'status', width: 1280, height: 720, streaming: true }) });
+  f.pointer('pointerdown', 100, 'touch-surface');
+  assert.equal(ws.sent.some(m => m.type === 'touch'), false, 'Pillarbox is not touchable');
+  f.pointer('pointerdown', 640, 'touch-surface');
+  assert.equal(ws.sent.filter(m => m.type === 'touch').at(-1).contacts[0].x, .5);
+  assert.equal(f.element('video-canvas').width, 720);
+  assert.equal(f.element('video-canvas').height, 1280);
+  f.pointer('pointerup', 640, 'touch-surface');
+  await f.decoded(1280, 720); f.pointer('pointerdown', 100, 'touch-surface');
+  assert.ok(ws.sent.filter(m => m.type === 'touch').at(-1).contacts[0].x < .1);
+});
+
+test('Direct Canvas drawing errors use JPEG and do not change browser audio or the connection', async () => {
+  const f = fixture({ storedMode: 'track-canvas', canvasAvailable: false }), ws = await f.connect(); await f.offer(ws);
+  assert.equal(ws.readyState, 1); assert.equal(f.createdVideos.length, 0);
+  assert.equal(f.stats().presentation.fallbackReason, 'renderer-error');
+  assert.equal(f.stats().presentation.activeMode, 'waiting');
+  assert.equal(f.element('renderer-track-canvas').checked, true);
+  f.pointer('pointerdown'); assert.equal(ws.sent.some(m => m.type === 'touch'), false);
+  f.frame(ws); f.pointer('pointerdown'); f.pointer('pointerup');
+  assert.equal(ws.sent.filter(m => m.type === 'touch').length, 2);
+});
+
+test('an automatic retry keeps the launch mode until the user starts a new display session', async () => {
+  const f = fixture({ storedMode: 'track-canvas' }), ws = await f.connect();
+  f.select('native'); ws.close();
+  const retry = [...f.timers.values()].find(t => t.delay === 1000);
+  await retry.fn();
+  const replacement = f.sockets.at(-1); replacement.readyState = 1; replacement.onopen();
+  assert.equal(f.stats().presentation.selectedMode, 'track-canvas');
+  await f.offer(replacement); await f.decoded();
+  assert.equal(f.createdVideos.length, 0);
+  f.element('disconnect').handlers.click();
+  const next = await f.connect(); await f.offer(next);
+  assert.equal(f.stats().presentation.selectedMode, 'native');
+  assert.equal(f.createdVideos.length, 1);
+});
+
+test('late JPEG errors cannot close a live Canvas stream or a replacement connection', async () => {
+  const f = fixture({ storedMode: 'track-canvas' }), ws = await f.connect();
+  ws.onmessage({ data: {} }); const oldError = f.element('screen').onerror;
+  await f.offer(ws); await f.decoded();
+  oldError(); assert.equal(ws.readyState, 1);
+  ws.close(); const replacement = await f.connect();
+  oldError(); assert.equal(replacement.readyState, 1);
+  assert.equal(f.createdVideos.length, 0);
+});
+
+test('a replaced JPEG load cannot ACK or display an obsolete image in the same session', async () => {
+  const f = fixture(), ws = await f.connect();
+  ws.onmessage({ data: {} }); const oldLoad = f.element('screen').onload;
+  ws.onmessage({ data: {} });
+  f.element('screen-next').onload();
+  const before = ws.sent.length; oldLoad(); assert.equal(ws.sent.length, before);
+  assert.equal(f.element('screen-next').hidden, false);
+  assert.equal(f.element('screen').hidden, true);
+});
+
+test('Direct Canvas preserves versioned media isolation and input readiness across an RTC rebuild', async () => {
+  const f = fixture({ storedMode: 'track-canvas' }), ws = await f.connect(); mediaStatus(ws);
+  await f.offer(ws, 1, { sessionId: 7, videoEpoch: 1 }); await f.decoded();
+  f.pointer('pointerdown', 100, 'touch-surface');
+  mediaStatus(ws, { videoEpoch: 2, sourceState: 'recovering', inputReady: false });
+  assert.deepEqual(ws.sent.filter(m => m.type === 'touch').at(-1).contacts, []);
+  assert.equal(f.element('held-frame').hidden, false);
+  assert.equal(f.element('touch-surface').classList.contains('stale'), true);
+  const count = f.peers.length;
+  ws.onmessage({ data: JSON.stringify({ type: 'rtc-offer', id: 2, sdp: 'offer', sessionId: 7, videoEpoch: 1 }) });
+  assert.equal(f.peers.length, count);
+  mediaStatus(ws, { videoEpoch: 2 });
+  await f.offer(ws, 3, { sessionId: 7, videoEpoch: 2 }); await f.decoded(720, 1280);
+  assert.equal(f.element('held-frame').hidden, true);
+  assert.equal(f.element('touch-surface').classList.contains('stale'), false);
+  f.pointer('pointerdown', 640, 'touch-surface');
+  assert.equal(ws.sent.filter(m => m.type === 'touch').at(-1).videoEpoch, 2);
+  assert.equal(f.createdVideos.length, 0);
+});
+
+test('Direct Canvas retries over v3 WebP without Video and only switches after the first new draw', async () => {
+  const f = fixture({ storedMode: 'track-canvas' }), ws = await f.connect(); mediaStatus(ws);
+  await f.offer(ws, 1, { sessionId: 7, videoEpoch: 1 }); await f.decoded();
+  f.peers.at(-1).connectionState = 'failed'; f.peers.at(-1).onconnectionstatechange();
+  ws.onmessage({ data: videoPacket(1, { protocol: 3, sequence: 17, format: 2 }) }); const image = finishJpeg(f);
+  assert.match(f.element('status').textContent, /WebP/);
+  assert.deepEqual(ws.sent.filter(m => m.type === 'ack').at(-1), { type: 'ack', sessionId: 7, videoEpoch: 1, sequence: 17 });
+  mediaStatus(ws, { rtcAvailable: false }); mediaStatus(ws, { rtcAvailable: true });
+  await f.offer(ws, 2, { sessionId: 7, videoEpoch: 1 });
+  assert.equal(image.hidden, false);
+  f.pointer('pointerdown', 100, 'touch-surface'); f.pointer('pointerup', 100, 'touch-surface');
+  await f.decoded();
+  assert.equal(image.hidden, true);
+  assert.equal(f.stats().presentation.activeMode, 'track-canvas');
+  assert.equal(f.stats().presentation.fallbackReason, null);
+  assert.equal(f.createdVideos.length, 0);
+});
diff --git a/test/track-canvas.test.js b/test/track-canvas.test.js
new file mode 100644
index 0000000..a6a338b
--- /dev/null
+++ b/test/track-canvas.test.js
@@ -0,0 +1,91 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { createTrackCanvasRenderer } from '../common/src/main/assets/web/app.js';
+const flush = () => new Promise(resolve => setImmediate(resolve));
+
+function fixture({ contextAvailable = true, constructError = false } = {}) {
+  const draws = [], ready = [], sizes = [], errors = [], readers = [], configurations = [];
+  const context = { drawImage: (...args) => draws.push(args) };
+  const canvas = { hidden: true, width: 0, height: 0, getContext: () => contextAvailable ? context : null };
+  const renderer = createTrackCanvasRenderer(canvas, {
+    onReady: size => ready.push(size), onResize: size => sizes.push(size), onError: reason => errors.push(reason),
+    createProcessor(init) {
+      if (constructError) throw new Error('not supported');
+      configurations.push(init);
+      const pending = [];
+      const reader = {
+        pending, read: () => new Promise((resolve, reject) => pending.push({ resolve, reject })),
+        cancel() { this.cancels = (this.cancels || 0) + 1; },
+        releaseLock() { this.releases = (this.releases || 0) + 1; },
+      };
+      readers.push(reader); return { readable: { getReader: () => reader } };
+    },
+  });
+  return { renderer, canvas, context, draws, ready, sizes, errors, readers, configurations,
+    async frame(width = 1280, height = 720, reader = readers.at(-1)) {
+      const frame = { displayWidth: width, displayHeight: height, closes: 0, close() { this.closes++; } };
+      reader.pending.shift().resolve({ value: frame, done: false }); await flush(); return frame;
+    },
+  };
+}
+
+test('processor bounds its queue, waits for valid output, and reports first draw and actual dimensions', async () => {
+  const f = fixture(), track = {};
+  f.renderer.start(track);
+  assert.deepEqual(f.configurations, [{ track, maxBufferSize: 1 }]);
+  assert.equal(f.ready.length, 0); assert.equal(f.canvas.hidden, true);
+  assert.equal((await f.frame(0, 720)).closes, 1);
+  assert.equal(f.draws.length, 0);
+  const frame = await f.frame(); assert.equal(frame.closes, 1);
+  assert.equal(f.ready.length, 1); assert.equal(f.canvas.hidden, false);
+  await f.frame(720, 1280);
+  assert.deepEqual(f.sizes, [{ width: 720, height: 1280 }]);
+  assert.deepEqual(f.renderer.snapshot(), { width: 720, height: 1280, renderedFrames: 2, presentedFrames: null });
+});
+
+test('stop cancels without waiting; a late frame is released without drawing into a new session', async () => {
+  const f = fixture(); f.renderer.start({});
+  const old = f.readers[0]; f.renderer.stop(); f.renderer.stop();
+  assert.equal(old.cancels, 1); assert.equal(f.canvas.width, 0);
+  f.renderer.start({}); await f.frame(720, 1280);
+  const frame = await f.frame(1920, 1080, old);
+  assert.equal(frame.closes, 1); assert.equal(old.releases, 1);
+  assert.equal(f.draws.length, 1); assert.equal(f.canvas.width, 720);
+  assert.equal(f.errors.length, 0);
+});
+
+test('a drawing exception releases the current frame and clears the canvas exactly once', async () => {
+  const f = fixture(); f.renderer.start({});
+  f.context.drawImage = () => { throw new Error('draw failed'); };
+  const frame = await f.frame();
+  assert.equal(frame.closes, 1); assert.deepEqual(f.errors, ['renderer-error']);
+  assert.equal(f.readers[0].cancels, 1); assert.equal(f.readers[0].releases, 1);
+  assert.equal(f.canvas.hidden, true); assert.equal(f.canvas.width, 0);
+});
+
+test('reader rejection and unexpected end report an error and release the lock', async () => {
+  for (const end of [false, true]) {
+    const f = fixture(); f.renderer.start({});
+    const reader = f.readers[0], pending = reader.pending.shift();
+    if (end) pending.resolve({ done: true }); else pending.reject(new Error('read failed'));
+    await flush();
+    assert.deepEqual(f.errors, [end ? 'track-ended' : 'renderer-error']);
+    assert.equal(reader.releases, 1); assert.equal(f.canvas.hidden, true);
+  }
+});
+
+test('missing context and processor construction failures do not leave a read loop', () => {
+  for (const options of [{ contextAvailable: false }, { constructError: true }]) {
+    const f = fixture(options); f.renderer.start({});
+    assert.deepEqual(f.errors, ['renderer-error']); assert.equal(f.readers.length, 0);
+    assert.equal(f.canvas.width, 0); assert.equal(f.canvas.hidden, true);
+  }
+});
+
+test('a canceled read rejection cannot report an error into a replacement session', async () => {
+  const f = fixture(); f.renderer.start({}); const old = f.readers[0];
+  f.renderer.stop(); f.renderer.start({});
+  old.pending.shift().reject(new Error('late cancellation')); await flush();
+  assert.equal(f.errors.length, 0); assert.equal(old.releases, 1);
+  await f.frame(); assert.equal(f.ready.length, 1);
+});
diff --git a/test/webrtc.test.js b/test/webrtc.test.js
index 325bf6b..53f4fbc 100644
--- a/test/webrtc.test.js
+++ b/test/webrtc.test.js
@@ -1,17 +1,17 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { createRtcReceiver, createControlOutbox } from '../common/src/main/assets/web/app.js';
+import { createRtcReceiver, createControlOutbox, createVideoRenderer } from '../common/src/main/assets/web/app.js';
 
-function fixture(createPeer, supportsCodec = () => true) {
+function fixture(createPeer, supportsCodec = () => true, rendererFactory = null) {
   const sent = [], measurements = [], timers = new Map();
   let sequence = 0, clock = 0, ready = 0, stopped = 0;
-  const video = { videoWidth: 1280, videoHeight: 720, readyState: 2, play: async () => {} };
+  const video = { videoWidth: 1280, videoHeight: 720, readyState: 2, play: async () => {}, remove() {} };
   const pc = { connectionState: 'new', iceGatheringState: 'complete', localDescription: { sdp: 'answer' },
     setRemoteDescription: async () => {}, createAnswer: async () => ({ type: 'answer', sdp: 'a=setup:active\r\n' }),
     setLocalDescription: async d => { pc.appliedAnswer = d; },
     close() { this.closed = true; }, getStats: async () => new Map([['video', { type: 'inbound-rtp', kind: 'video', framesDecoded: 10 }]]),
   };
-  const receiver = createRtcReceiver(video, { send: m => sent.push(m), supportsCodec, createPeer: createPeer || (() => pc),
+  const receiver = createRtcReceiver(rendererFactory || (callbacks => createVideoRenderer('native', null, { ...callbacks, createVideo: () => video })), { send: m => sent.push(m), supportsCodec, createPeer: createPeer || (() => pc),
     onStats: (fps, metrics) => measurements.push({ fps, metrics }),
     onReady: () => ready++, onStop: () => stopped++, now: () => clock,
     schedule(fn, delay) { const id = ++sequence; timers.set(id, { fn, delay }); return id; },
@@ -29,7 +29,7 @@ test('JPEG remains active until the browser actually decodes a video frame', asy
   assert.deepEqual(f.sent, [{ type: 'rtc-answer', id: 1, sdp: 'answer' }]);
   assert.equal(f.pc.appliedAnswer.sdp, 'a=setup:passive\r\n');
   assert.equal(f.receiver.active, false);
-  f.pc.ontrack({ streams: [{}] }); await Promise.resolve();
+  f.pc.ontrack({ track: { stop() {} }, streams: [{}] }); await Promise.resolve();
   assert.equal(f.receiver.active, true); assert.equal(f.ready, 1);
   f.video.onloadeddata(); assert.equal(f.ready, 1);
   assert.equal(f.sent.at(-1).type, 'rtc-ready');
@@ -60,7 +60,7 @@ test('autoplay and unsupported platform errors block retries, while transient se
   const f = fixture();
   f.video.play = async () => { throw Object.assign(new Error('autoplay'), { name: 'NotAllowedError' }); };
   await f.receiver.receive({ type: 'rtc-offer', id: 22, sdp: 'offer' });
-  f.pc.ontrack({ streams: [{}] }); await new Promise(resolve => setImmediate(resolve));
+  f.pc.ontrack({ track: { stop() {} }, streams: [{}] }); await new Promise(resolve => setImmediate(resolve));
   assert.deepEqual(f.sent.at(-1), { type: 'rtc-fallback', id: 22, retryable: false });
 });
 
@@ -78,7 +78,7 @@ test('late SDP and stale stop cannot affect a replacement connection', async ()
 
 test('a static scene resuming updates gets a fresh recovery window', async () => {
   const f = fixture(); await f.receiver.receive({ type: 'rtc-offer', id: 6, sdp: 'offer' });
-  f.pc.ontrack({ streams: [{}] }); await Promise.resolve();
+  f.pc.ontrack({ track: { stop() {} }, streams: [{}] }); await Promise.resolve();
   await f.tick(1000, 1000);
   await f.tick(1000, 10000); assert.equal(f.receiver.active, true);
   f.receiver.progress(100);
@@ -95,7 +95,7 @@ test('each configured grace period applies to transient disconnections and first
     const f = fixture();
     await f.receiver.receive({ type: 'rtc-offer', id: grace, sdp: 'offer', recoveryGraceMs: grace });
     assert.ok([...f.timers.values()].some(t => t.delay === Math.max(10000, grace)));
-    f.pc.ontrack({ streams: [{}] }); await Promise.resolve();
+    f.pc.ontrack({ track: { stop() {} }, streams: [{}] }); await Promise.resolve();
     f.pc.connectionState = 'disconnected'; f.pc.onconnectionstatechange();
     assert.equal(f.receiver.active, true);
     await f.tick(grace, grace);
@@ -108,7 +108,7 @@ test('decode progress resets a stall deadline while continuous stalled input eve
   const f = fixture(); let decoded = 10;
   f.pc.getStats = async () => new Map([['video', { type: 'inbound-rtp', kind: 'video', framesDecoded: decoded }]]);
   await f.receiver.receive({ type: 'rtc-offer', id: 7, sdp: 'offer', recoveryGraceMs: 4000 });
-  f.pc.ontrack({ streams: [{}] }); await Promise.resolve();
+  f.pc.ontrack({ track: { stop() {} }, streams: [{}] }); await Promise.resolve();
   for (let at = 1000; at <= 5000; at += 1000) {
     f.setTime(at); f.receiver.progress(at);
     if (at === 5000) decoded++;
@@ -123,7 +123,7 @@ test('decode progress resets a stall deadline while continuous stalled input eve
 test('a temporary getStats failure recovers, but persistent sampling failures exhaust the grace period', async () => {
   const f = fixture(); const goodStats = f.pc.getStats;
   await f.receiver.receive({ type: 'rtc-offer', id: 8, sdp: 'offer', recoveryGraceMs: 4000 });
-  f.pc.ontrack({ streams: [{}] }); await Promise.resolve();
+  f.pc.ontrack({ track: { stop() {} }, streams: [{}] }); await Promise.resolve();
   f.pc.getStats = async () => { throw new Error('temporary stats error'); };
   await f.tick(1000, 1000); assert.equal(f.receiver.active, true);
   f.pc.getStats = goodStats;
@@ -138,7 +138,7 @@ test('a temporary getStats failure recovers, but persistent sampling failures ex
 test('terminal failures stay immediate and stale disconnect timers cannot stop a new session', async () => {
   const f = fixture();
   await f.receiver.receive({ type: 'rtc-offer', id: 9, sdp: 'offer', recoveryGraceMs: 30000 });
-  f.pc.ontrack({ streams: [{}] }); await Promise.resolve();
+  f.pc.ontrack({ track: { stop() {} }, streams: [{}] }); await Promise.resolve();
   f.pc.connectionState = 'disconnected'; f.pc.onconnectionstatechange();
   const stale = [...f.timers.values()].find(t => t.delay === 30000).fn;
   await f.receiver.receive({ type: 'rtc-offer', id: 10, sdp: 'offer' });
@@ -151,7 +151,7 @@ test('terminal failures stay immediate and stale disconnect timers cannot stop a
 test('a cancelled disconnect timer cannot expire a later interruption on the same peer', async () => {
   const f = fixture();
   await f.receiver.receive({ type: 'rtc-offer', id: 21, sdp: 'offer' });
-  f.pc.ontrack({ streams: [{}] }); await Promise.resolve();
+  f.pc.ontrack({ track: { stop() {} }, streams: [{}] }); await Promise.resolve();
   f.pc.connectionState = 'disconnected'; f.pc.onconnectionstatechange();
   const stale = [...f.timers.values()].find(t => t.delay === 10000).fn;
   f.pc.connectionState = 'connected'; f.pc.onconnectionstatechange();
@@ -163,7 +163,7 @@ test('a cancelled disconnect timer cannot expire a later interruption on the sam
 test('checking a disconnected connection does not cancel its recovery deadline', async () => {
   const f = fixture();
   await f.receiver.receive({ type: 'rtc-offer', id: 22, sdp: 'offer', recoveryGraceMs: 4000 });
-  f.pc.ontrack({ streams: [{}] }); await Promise.resolve();
+  f.pc.ontrack({ track: { stop() {} }, streams: [{}] }); await Promise.resolve();
   f.pc.connectionState = 'disconnected'; f.pc.onconnectionstatechange();
   f.pc.connectionState = 'connecting'; f.pc.onconnectionstatechange();
   assert.equal(f.receiver.recovering, true);
@@ -193,7 +193,7 @@ test('HEVC negotiates its own codec and waits for decoded output; rejected media
   await f.receiver.receive({ type: 'rtc-offer', id: 11, codec: 'H265', sdp: 'offer' });
   assert.equal(f.receiver.codec, 'H265');
   assert.equal(f.receiver.active, false);
-  f.pc.ontrack({ streams: [{}] }); await Promise.resolve();
+  f.pc.ontrack({ track: { stop() {} }, streams: [{}] }); await Promise.resolve();
   assert.equal(f.receiver.active, true);
   f.pc.createAnswer = async () => ({ type: 'answer', sdp: 'm=video 0 UDP/TLS/RTP/SAVPF 96\r\n' });
   await f.receiver.receive({ type: 'rtc-offer', id: 12, codec: 'H265', sdp: 'offer' });
@@ -211,7 +211,7 @@ test('receiver reports interval rates and separate presentation, decode and jitt
     totalDecodeTime: .1, jitterBufferDelay: .2, jitterBufferEmittedCount: 10, totalProcessingDelay: .3 };
   f.pc.getStats = async () => new Map([['video', stat], ['pair', { type: 'candidate-pair', nominated: true, state: 'succeeded', currentRoundTripTime: .015 }]]);
   await f.receiver.receive({ type: 'rtc-offer', id: 20, sdp: 'offer' });
-  f.pc.ontrack({ streams: [{}] }); await Promise.resolve();
+  f.pc.ontrack({ track: { stop() {} }, streams: [{}] }); await Promise.resolve();
   callback(0, { presentedFrames: 2 });
   await f.tick(1000, 1000);
   assert.equal(f.measurements.at(-1).fps, null); // First cumulative snapshot is a baseline.
@@ -244,3 +244,55 @@ test('feedback is coalesced behind essential controls and cleared on close', ()
   outbox.close(); socket.bufferedAmount = 0; tasks.shift()();
   assert.equal(sent.length, 3);
 });
+
+
+test('render stalls expire each grace period even while WebRTC continues decoding', async () => {
+  for (const grace of [4000, 10000, 30000]) {
+    let rendered = 1, callbacks, decoded = 1, stopped = 0;
+    const f = fixture(null, () => true, hooks => {
+      callbacks = hooks;
+      return { start() { hooks.onReady({ width: 720, height: 1280 }); }, stop() { stopped++; },
+        snapshot: () => ({ width: 720, height: 1280, renderedFrames: rendered, presentedFrames: null }) };
+    });
+    f.pc.getStats = async () => new Map([['video', { type: 'inbound-rtp', kind: 'video', framesDecoded: ++decoded }]]);
+    await f.receiver.receive({ type: 'rtc-offer', id: grace, sdp: 'offer', recoveryGraceMs: grace });
+    const track = { stop() { this.stopped = true; } };
+    f.pc.ontrack({ track, streams: [] });
+    for (let at = 1000; at <= grace; at += 1000) {
+      f.setTime(at); f.receiver.progress(at); await f.tick(1000, at);
+      assert.equal(f.receiver.active, true);
+    }
+    f.setTime(grace + 1000); f.receiver.progress(grace + 1000); await f.tick(1000, grace + 1000);
+    assert.equal(f.receiver.active, false); assert.equal(stopped, 1); assert.equal(track.stopped, true);
+    assert.equal(f.sent.filter(m => m.type === 'rtc-fallback').length, 1);
+    callbacks.onReady({ width: 1, height: 1 }); callbacks.onError('late');
+    assert.equal(f.sent.filter(m => m.type === 'rtc-ready').length, 1);
+  }
+});
+
+test('static rendered output survives idle time and drawing progress resets its own recovery deadline', async () => {
+  let rendered = 1, decoded = 0;
+  const f = fixture(null, () => true, hooks => ({
+    start() { hooks.onReady({ width: 1280, height: 720 }); }, stop() {},
+    snapshot: () => ({ renderedFrames: rendered, presentedFrames: null }),
+  }));
+  f.pc.getStats = async () => new Map([['video', { type: 'inbound-rtp', kind: 'video', framesDecoded: ++decoded }]]);
+  await f.receiver.receive({ type: 'rtc-offer', id: 30, sdp: 'offer', recoveryGraceMs: 4000 });
+  f.pc.ontrack({ track: { stop() {} }, streams: [] });
+  await f.tick(1000, 60000); assert.equal(f.receiver.active, true);
+  for (let at = 61000; at <= 68000; at += 1000) {
+    f.setTime(at); f.receiver.progress(at);
+    if (at === 64000 || at === 68000) rendered++;
+    await f.tick(1000, at); assert.equal(f.receiver.active, true);
+  }
+  assert.equal(f.measurements.at(-1).metrics.renderedFps, 1);
+});
+
+test('a remote track ending falls back immediately and detaches its end handler before stopping', async () => {
+  const f = fixture(); await f.receiver.receive({ type: 'rtc-offer', id: 31, sdp: 'offer' });
+  const track = { stop() { assert.equal(this.onended, null); this.stopped = true; } };
+  f.pc.ontrack({ track, streams: [{}] }); await Promise.resolve();
+  track.onended();
+  assert.equal(track.stopped, true); assert.equal(f.receiver.active, false);
+  assert.deepEqual(f.sent.at(-1), { type: 'rtc-fallback', id: 31 });
+});

From 8336242d01a2430440317f32c6515e04c5b0c6c0 Mon Sep 17 00:00:00 2001
From: seasonyuu <seasonyuu@gmail.com>
Date: Wed, 21 Oct 2026 15:14:39 +0800
Subject: [PATCH 2/6] fix: disambiguate length-prefixed video before RTP
 packetization

Declare the input framing at AirPlay decode entry points instead of guessing from start-code bytes. Cover AVC and HEVC length boundaries, keyframe detection, malformed records and byte-exact RTP roundtrips.
---
 common/src/main/cpp/video_buffer.hpp | 11 +++-
 common/src/main/cpp/video_crypto.cpp |  4 +-
 test/native/CMakeLists.txt           |  2 +-
 test/native/video-buffer.cpp         | 89 ++++++++++++++++++++++++++++
 4 files changed, 100 insertions(+), 6 deletions(-)
 create mode 100644 test/native/video-buffer.cpp

diff --git a/common/src/main/cpp/video_buffer.hpp b/common/src/main/cpp/video_buffer.hpp
index 7509c65..6b2a0bb 100644
--- a/common/src/main/cpp/video_buffer.hpp
+++ b/common/src/main/cpp/video_buffer.hpp
@@ -34,16 +34,21 @@ struct VideoBuffer {
     bool avcKeyframe = false, hevcKeyframe = false;
     ~VideoBuffer() { pool->recycle(std::move(bytes)); }
 };
-// Validates the entire record before rewriting it, matching the JVM fallback's behavior.
-inline void annexB(VideoBuffer& frame) {
+enum class VideoInputFormat { LengthPrefixed, AnnexB };
+
+// The caller knows the framing. A length of 256..511 starts with 00 00 01 too,
+// so an Annex B prefix probe cannot distinguish these inputs.
+// Validate the entire length-prefixed record before rewriting any bytes.
+inline void annexB(VideoBuffer& frame, VideoInputFormat format) {
     auto& b = frame.bytes;
+    frame.avcKeyframe = frame.hevcKeyframe = false;
     auto prefix = [&](size_t i) -> size_t {
         if (i + 3 > b.size() || b[i] || b[i+1]) return 0;
         if (b[i+2] == 1) return 3;
         return i + 4 <= b.size() && !b[i+2] && b[i+3] == 1 ? 4 : 0;
     };
     auto length = [&](size_t i) { return (uint32_t(b[i]) << 24) | (uint32_t(b[i+1]) << 16) | (uint32_t(b[i+2]) << 8) | b[i+3]; };
-    if (!prefix(0)) {
+    if (format == VideoInputFormat::LengthPrefixed) {
         size_t i = 0;
         while (i + 4 <= b.size()) {
             auto n = length(i); i += 4;
diff --git a/common/src/main/cpp/video_crypto.cpp b/common/src/main/cpp/video_crypto.cpp
index 26b0fe0..21afe76 100644
--- a/common/src/main/cpp/video_crypto.cpp
+++ b/common/src/main/cpp/video_crypto.cpp
@@ -46,7 +46,7 @@ Java_com_shilapi_xcertplay_web_NativeVideoDecoder_decrypt(JNIEnv* env, jobject,
             mbedtls_platform_zeroize(frame->bytes.data(),frame->bytes.size());
             error(env,"javax/crypto/AEADBadTagException","Video authentication failed"); return 0;
         }
-        wheelplay::annexB(*frame);
+        wheelplay::annexB(*frame, wheelplay::VideoInputFormat::LengthPrefixed);
         return reinterpret_cast<jlong>(frame.release());
     } catch (const std::exception& e) { error(env,"java/lang/IllegalStateException",e.what()); return 0; }
 }
@@ -76,7 +76,7 @@ Java_com_shilapi_xcertplay_web_NativeVideoDecoder_importFrame(JNIEnv* env,jobjec
         auto frame = std::make_unique<wheelplay::VideoBuffer>();
         frame->pool = decoder->pool; frame->bytes = decoder->pool->acquire(size);
         env->GetByteArrayRegion(bytes,0,size,reinterpret_cast<jbyte*>(frame->bytes.data()));
-        wheelplay::annexB(*frame);
+        wheelplay::annexB(*frame, wheelplay::VideoInputFormat::LengthPrefixed);
         return reinterpret_cast<jlong>(frame.release());
     } catch (const std::exception& e) { error(env,"java/lang/IllegalStateException",e.what()); return 0; }
 }
diff --git a/test/native/CMakeLists.txt b/test/native/CMakeLists.txt
index 0cd0a8d..7275b00 100644
--- a/test/native/CMakeLists.txt
+++ b/test/native/CMakeLists.txt
@@ -14,7 +14,7 @@ add_subdirectory("${LIBDATACHANNEL_SOURCE_DIR}" rtc)
 include(../../common/src/main/cpp/media_send_feedback.cmake)
 include(../../common/src/main/cpp/srtp_optimization.cmake)
 enable_testing()
-foreach(name media-send video-packetizer video-rtp-handler srtp-packet)
+foreach(name media-send video-buffer video-packetizer video-rtp-handler srtp-packet)
     add_executable(${name} ${name}.cpp)
     target_include_directories(${name} PRIVATE ../../common/src/main/cpp)
     target_compile_options(${name} PRIVATE -UNDEBUG)
diff --git a/test/native/video-buffer.cpp b/test/native/video-buffer.cpp
new file mode 100644
index 0000000..cdf4c7d
--- /dev/null
+++ b/test/native/video-buffer.cpp
@@ -0,0 +1,89 @@
+#include "video_buffer.hpp"
+#include "video_packetizer.hpp"
+#include <cassert>
+#include <iostream>
+
+using Bytes = std::vector<uint8_t>;
+static Bytes lengths(const std::vector<Bytes>& nals) {
+    Bytes result;
+    for (const auto& nal : nals) {
+        const uint32_t size = nal.size();
+        for (int shift : {24,16,8,0}) result.push_back(size >> shift);
+        result.insert(result.end(),nal.begin(),nal.end());
+    }
+    return result;
+}
+static Bytes annex(const std::vector<Bytes>& nals, bool mixed = false) {
+    Bytes result;
+    for (size_t i=0;i<nals.size();++i) {
+        if (!mixed || i%2 == 0) result.push_back(0);
+        result.insert(result.end(),{0,0,1});
+        result.insert(result.end(),nals[i].begin(),nals[i].end());
+    }
+    return result;
+}
+static void verify(const std::vector<Bytes>& nals, bool hevc, bool keyframe) {
+    wheelplay::VideoBuffer frame;
+    frame.pool = std::make_shared<wheelplay::VideoPool>();
+    frame.bytes = lengths(nals);
+    wheelplay::annexB(frame,wheelplay::VideoInputFormat::LengthPrefixed);
+    assert(frame.bytes == annex(nals));
+    assert((hevc ? frame.hevcKeyframe : frame.avcKeyframe) == keyframe);
+    // Check the consumer sees the original NAL bytes after conversion and RTP FU assembly.
+    std::vector<Bytes> reconstructed;
+    size_t markers = 0;
+    wheelplay::packetizeVideo({frame.bytes.data(),frame.bytes.size()},{nullptr,0},hevc,1100,
+        [&](wheelplay::VideoView header, wheelplay::VideoView payload, bool marker) {
+            if (!header.size) reconstructed.emplace_back(payload.data,payload.data+payload.size);
+            else {
+                const uint8_t flags = header.data[header.size-1];
+                if (flags & 0x80) {
+                    if (hevc) reconstructed.push_back({uint8_t((header.data[0]&0x81)|((flags&63)<<1)),header.data[1]});
+                    else reconstructed.push_back({uint8_t((header.data[0]&0xe0)|(flags&31))});
+                }
+                reconstructed.back().insert(reconstructed.back().end(),payload.data,payload.data+payload.size);
+            }
+            if (marker) markers++;
+        });
+    assert(reconstructed == nals);
+    assert(markers == 1);
+}
+int main() {
+    for (bool hevc : {false,true}) {
+        for (size_t size=2;size<=1101;++size) {
+            Bytes nal(size,0x55); nal[0] = hevc ? 0x02 : 0x41;
+            if (hevc) nal[1] = 1;
+            verify({nal},hevc,false);
+            // A small first NAL must not hide the next NAL or invent a keyframe.
+            verify({nal,nal},hevc,false);
+            nal[0] = hevc ? 0x28 : 0x65;
+            verify({nal},hevc,true);
+        }
+        Bytes large(65536,0x55);large[0] = hevc ? 0x02 : 0x41;large[1] = 1;
+        verify({large},hevc,false);
+    }
+    // Genuine Annex B remains explicit; scanning accepts both start-code lengths.
+    for (Bytes bytes : {Bytes{0,0,1,0x28,1,7},Bytes{0,0,0,1,0x28,1,7},
+                       annex({{0x40,1,9},{0x42,1,8},{0x44,1,7},{0x28,1,6}},true)}) {
+        wheelplay::VideoBuffer frame;frame.pool = std::make_shared<wheelplay::VideoPool>();
+        frame.bytes = bytes;
+        wheelplay::annexB(frame,wheelplay::VideoInputFormat::AnnexB);
+        assert(frame.bytes == bytes && frame.hevcKeyframe);
+    }
+    for (Bytes bytes : {Bytes{},Bytes{0,0,0},Bytes{0,0,0,0},Bytes{0,0,1,0x20,0x28,1},
+                       Bytes{0,0,0,2,0x28,1,0},Bytes{0,0,0,2,0x28,1,0,0,0,9,2,1}}) {
+        wheelplay::VideoBuffer frame;frame.pool = std::make_shared<wheelplay::VideoPool>();
+        frame.bytes = bytes;frame.avcKeyframe = frame.hevcKeyframe = true;
+        wheelplay::annexB(frame,wheelplay::VideoInputFormat::LengthPrefixed);
+        assert(frame.bytes == bytes && !frame.avcKeyframe && !frame.hevcKeyframe);
+    }
+    // Even a valid three-byte Annex B access unit can also form a valid length record.
+    // Its format must come from the caller, not from a heuristic over these bytes.
+    auto ambiguous = lengths({Bytes(380,0x55)});
+    ambiguous[4] = 2;ambiguous[5] = 1;
+    wheelplay::VideoBuffer frame;frame.pool = std::make_shared<wheelplay::VideoPool>();
+    frame.bytes = ambiguous;
+    wheelplay::annexB(frame,wheelplay::VideoInputFormat::AnnexB);
+    assert(frame.bytes == ambiguous);
+    std::cout << "Native conversion: length boundaries, framing contracts, keyframe flags, malformed records and RTP roundtrip passed\n";
+}

From b50ae8e07949298c43ce37519a2bb4235ec1a79a Mon Sep 17 00:00:00 2001
From: seasonyuu <seasonyuu@gmail.com>
Date: Wed, 21 Oct 2026 15:14:40 +0800
Subject: [PATCH 3/6] docs: record device rendering and HEVC regression
 validation

Document frame-rate measurements, bottleneck investigation, the NAL framing diagnosis and fixed-APK verification across all three renderers. Record restored device settings and remaining validation limits.
---
 docs/VALIDATION.md | 150 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 150 insertions(+)

diff --git a/docs/VALIDATION.md b/docs/VALIDATION.md
index 9e56089..92f9c4f 100644
--- a/docs/VALIDATION.md
+++ b/docs/VALIDATION.md
@@ -356,3 +356,153 @@ SHA-256：
 ```
 
 包名 `moe.feng.wheelplay`，发行签名，此本地产物包含上述 CarPlay 认证资产。
+
+## WebRTC 三种渲染方式（2026-10-21）
+
+连接页改为原生 Video（默认）、兼容 Canvas、直接 Canvas 三张单选卡片。直接 Canvas 使用主线程 MediaStreamTrackProcessor 与 Canvas 2D，不创建 Video 元素；不支持或运行失败直接使用 JPEG。旧 Canvas 偏好迁移，用户选择、自动重连及失败后的选择均保留。
+
+- Node 自动化：94 项通过，覆盖三个适配器、旧模式回归、单选与迁移、存储错误、逐帧释放、reader 取消及迟到任务、首帧等待、三档恢复时间、解码继续而绘制停滞、静态画面、JPEG 回退、横竖触控、迟到 JPEG 加载 / 错误和重连隔离。新增检查确保网页模板及 JS 消息在 Android BrowserStrings 中导出，避免桌面夹具正常而 APK 缺少文案映射。
+- `npm run check`、`git diff --check` 通过。Android `:mobile:assembleDebug --no-configuration-cache` 构建成功；BrowserStringsTest 的 1 项和 LocalizationTest 的 7 项 Robolectric 测试通过，后者使用 APK 网页模板检查英文、简体、繁体资源。构建需显式设置本机 ANDROID_HOME；首次未配置 SDK 的尝试失败后已按现有 SDK 路径完成构建。
+- 真实 Chromium + 合成 WebRTC/H.264：三个模式均收到解码画面，首帧 ready 每次仅一次；两种 Canvas 的绿色测试区域像素正确。直接 Canvas 在非安全 HTTP origin（isSecureContext=false）及 HTTPS origin 均绘制成功，1280×720 改为 720×1280 后尺寸正确，Video 元素数量始终为 0。两个旧模式播放时各有一个 Video，断开后均移除，无页面 JS 错误。
+- HTTPS / 非安全 HTTP origin 由浏览器 QA 路由代理提供资源与合成信令，用于验证页面环境下的 API 和真实浏览器解码，不验证 Android HTTPS 证书、服务端媒体发送或真实热点网络。另以真实本地 demo WebSocket 验证禁用 Processor 后接收 1280×720 JPEG、显示回退提示且 Video 数量为 0。
+- 已检查 1280px / 390px 页面截图、卡片选中状态、键盘方向键切换和窄屏无横向溢出。前台动态夹具观察到约 30 次 / 秒绘制；后台 QA 页会受调度限制，以上结果不作为性能保证。截图及浏览器夹具保存在 Git 忽略的 `.local/renderer-qa/`。
+- 待实机验收：Android / iPhone / 目标车机端到端、真实 HTTP / HTTPS 入口与证书、静态一分钟后恢复、UDP 短暂断流及超时回退、HEVC、功耗和 60 fps。未安装 APK 到设备，未宣称绕过车机系统遮罩或后台解码限制。
+
+## 真机链路验证：三种渲染方式（2026-10-21）
+
+设备为 Pixel 3（Android 15）和无线连接的 iPhone XS Max，显示端为 macOS Chromium / Chrome，经真实局域网 HTTP 访问 Android Web 服务；没有代理配对、信令或视频数据。设备 APK 与本地 Debug APK 的 SHA-256 一致。浏览器固定 1280×800，对应 1280×720 CarPlay 画面。以下是该组合的观测结果，不代表其他车机或设备的性能。
+
+| 检查 | 结果 |
+| --- | --- |
+| 原生 Video / 兼容 Canvas / 直接 Canvas | 均通过真实 H.264 出画；三次连接首帧分别约 549 / 406 / 599 ms；采样未见丢包 |
+| 直接 Canvas 的元素与绘制 | Video 数量始终为 0；动态画面曾观测到约 29 fps，源端静态降帧时同步下降 |
+| 静置一分钟 | 60 次采样均保持 track-canvas，无回退、无 Video；包含源端 0 fps 和绘制 0 fps 的时段，未误判停滞 |
+| 真实触控 | 浏览器点击 CarPlay 主屏按钮后，iPhone 输出切换动画；JPEG 回退后仍可触控并收到更新图像 |
+| 短暂渲染停顿 | 包装原生 Processor reader，仅阻塞应用读取约 3 秒；实际 WebRTC 仍解码约 26–30 fps。恢复读取后继续直接 Canvas，无回退 |
+| 持续渲染停顿 | 在持续触控动画输入下阻塞读取，默认 10 秒容忍策略约 12.1 秒后触发 render-stalled；真实 JPEG 恢复为 1280×720，Video 仍为 0 |
+| 控制连接重连 | 主动关闭真实客户端 WebSocket，约 1.76 秒自动恢复直接 Canvas，模式选择保留、Video 为 0 |
+| HEVC | 临时开启 iPhone HEVC 并重新连接；真实 HEVC → WebRTC → 直接 Canvas 出画，1280×720，动态采样约 24–30 fps，Video 为 0、未见丢包 |
+
+故障注入只阻塞应用层对原生 Processor 的读取，未替换发送端或浏览器解码器；该项不等同于 UDP 丢包测试。记录与脚本保存在 Git 忽略的 `.local/device-renderer-qa/`，截图可能包含真实 CarPlay 内容，不纳入版本库。
+
+额外观察：兼容 Canvas 在静态低帧率时可能触发动画帧补偿，同一解码帧重复绘制约 120 次 / 秒；这不是源视频帧率，也未测量功耗。直接 Canvas 在没有新帧时不提交绘制。开启「自适应浏览器尺寸」时，窗口变化会触发整个无线 CarPlay 重协商；本次曾等待约 40–50 秒才恢复源画面，因此固定窗口完成模式对比。
+
+测试后关闭临时 HEVC 设置，保持原有 30 fps、10 秒恢复策略及尺寸自适应设置，并恢复用户原 Chrome 的直接 Canvas 会话。尚未覆盖目标车机浏览器、真实 UDP 阻断、设备 HTTPS 证书、60 fps 与功耗。
+
+## 真机补测：直接 Canvas 的 60 fps 协商与稳定性（2026-10-21）
+
+沿用 Pixel 3 / Android 15、无线 iPhone XS Max 和 macOS Chromium，真实 LAN HTTP / H.264 链路；临时将协商帧率设为 60 fps，设备日志确认请求生效。固定浏览器视口，等待尺寸重协商完成后，持续交替滑动 CarPlay 应用主屏，制造真实动态输入。1280×720 对应 1280×800 浏览器视口；2544×1576 对应 2544×1656、DPR 1 的测试视口，与用户原 Chrome 的源画面像素尺寸一致，但 CSS 尺寸及 DPR 不同。
+
+| 指标 | 1280×720 | 2544×1576 |
+| --- | ---: | ---: |
+| 连续动态采样时长 | 45.39 秒 | 45.28 秒 |
+| 源端输入平均帧率 | 54.81 fps | 40.75 fps |
+| 浏览器解码平均帧率 | 55.03 fps | 41.12 fps |
+| 成功绘制平均帧率 | 54.43 fps | 41.06 fps |
+| 约 1 秒采样窗口的最高绘制帧率 | 59.01 fps | 55.98 fps |
+| 成功绘制帧数 / 不同帧时间戳数 | 2471 / 2471 | 1859 / 1859 |
+| 绘制间隔中位数 / P95 / 最大值 | 15.7 / 37.2 / 126.5 ms | 18.3 / 50.4 / 161.0 ms |
+| WebRTC 报告丢包数 / framesDropped 增量 | 0 / 0 | 0 / 0 |
+
+额外一次 1280×720 的 25.46 秒连续滑动采样，成功绘制平均 53.49 fps、约 1 秒窗口峰值 56.98 fps。上述三个动态采样块均保持 track-canvas 和连接状态，未回退 JPEG，Video 元素数始终为 0；720p 两块动态观察合计约 71 秒，高分辨率观察约 45 秒。没有小时级稳定性、功耗或温升结论。
+
+绘制计数在调用原生 `CanvasRenderingContext2D.drawImage` 成功返回后递增，并按 `VideoFrame.timestamp` 核对不同帧；原生 PeerConnection `getStats` 提供解码与网络计数。仅增加观测包装，未替换源视频、传输、Processor 或解码器。这些数值是应用提交 Canvas 绘制的速率，不是屏幕实际呈现或刷新率。WebRTC 的 framesDropped 为 0 不代表 Processor 消费端绝对不丢帧；例如 720p 主采样中，解码增量比实际绘制多 27 帧。
+
+本轮未观察到持续满 60 fps。绘制基本跟上解码，但源端平均输入本身低于 60 fps，且主屏滑动不是恒定 60 fps 测试片，因此不能单独据此判定 Canvas 的吞吐上限或瓶颈位置。源端静态降帧、窗口 / 设置变化引起的无线 CarPlay 重协商均与稳定采样分开；一次截图重置测试视口导致的重协商数据，以及最初混入静置时段的试采样，未纳入表格。
+
+测完已恢复原有 30 fps / H.264，保留 10 秒恢复策略与尺寸自适应设置，并关闭测试浏览器。设备日志确认恢复后的 2544×1576 / 30 fps 协商及首帧；用户原 Chrome 恢复「H.264 / WebRTC / 直接 Canvas · 触控已连接」，Android 显示「CarPlay 画面正在串流」。
+
+原始采样及设备日志保存在 Git 忽略的 `.local/device-60fps-qa/`。目标车机浏览器的 60 fps、恒定帧率输入、设备 HTTPS、真实 UDP 阻断及功耗仍待验证。
+
+## 真机分段排查：高分辨率不足 60 fps（2026-10-21）
+
+继续使用 Pixel 3 / Android 15、无线 iPhone XS Max 和 macOS Chromium，协商上限 60 fps。高分辨率固定为 2544×1576，半尺寸对照为 1272×788。主屏重复左右滑动，每组约 30 秒；额外使用一次不松手的连续往返拖动。都是实际 CarPlay 输入，未生成或替换媒体数据。窗口和编码重协商期间不计入稳定帧率。
+
+本轮首先核对计数位置：`wheelplayStats.source.counts.input` 在 `WebVideoSource.frame` 内递增，是 Android 收齐 AirPlay 视频包并解密后的输入数，**不是 iPhone 内部生成帧数**。`ScreenStream` 以 TCP 顺序读取完整包；源 PTS 来自 AirPlay 包头，`ptsInterval` 在 Android 交给转发器前计算。`transport.sender.counts.accepted` 是原生发送调用成功次数；浏览器 `framesReceived` 才是接收端证据。设备心跳与浏览器 getStats 不完全同步，表中小幅速率差异包含采样边界偏差，不能当作某一级多生成或丢弃了帧。
+
+| 对照组 | Android 输入 fps | Android 成功发送 fps | 浏览器接收 / 解码 fps | Canvas 成功绘制 fps |
+| --- | ---: | ---: | ---: | ---: |
+| 高分辨率 H.264，直接 Canvas A | 48.33 | 48.33 | 48.43 / 48.43 | 48.40 |
+| 同尺寸 H.264，跳过 drawImage B | 48.79 | 48.79 | 49.32 / 49.22 | —（消费 49.22） |
+| 同尺寸 H.264，原生 Video C | 45.84 | 45.84 | 46.04 / 45.91 | — |
+| 同尺寸 H.264，不松手往返拖动 D | 38.85 | 38.85 | 39.25 / 39.25 | 39.15 |
+| 半尺寸 H.264，直接 Canvas E | 52.36 | 52.36 | 52.59 / 52.55 | 52.32 |
+| 高分辨率 HEVC，重连接收器后 I | 50.56 | 50.56 | 50.62 / 50.62 | 50.56 |
+| 高分辨率 H.264，恢复编码后的复测 J | 48.89 | 48.86 | 49.26 / 49.19 | 49.19 |
+
+B 组只在页面内临时跳过 `drawImage`，持续读取并释放原生 VideoFrame；它是排除绘制负载的诊断，消费速率不能称为实际绘制帧率。C 组额外观察到约 44.41 次 / 秒的原生视频帧回调及 VideoPlaybackQuality dropped 增量 14，回调可能合并，不能与 Canvas 提交次数等同。不同组不是恒定内容的逐帧回放；尤其连续拖动会受页面边界和内容更新策略影响，D 不能单独作为设备吞吐上限。半尺寸改变了 CarPlay 布局及物理尺寸通告，也不是严格的单变量编码性能基准。
+
+分段证据及结论：
+
+- **源端 / 无线输入边界：** 高分辨率 H.264 的源 PTS 已包含 33.3 / 50 ms 等间隔，A 组稳定后最近 240 帧窗口的平均 PTS 间隔约 20.22 ms；浏览器消费到的 PTS 间隔平均 20.48 ms、P95 50 ms，绘制间隔平均 20.48 ms、P95 50.70 ms。缺口在 Canvas 之前已存在。项目通过 AirPlay `/info` 的 `maxFPS` 通告 60，是上限能力，不会强迫 iPhone 每秒生成 60 个不同画面。本轮把主要缺口限定在 Android 完整收帧之前，仍不能进一步区分 iPhone 内容更新 / 合成 / 编码和无线 TCP 回压；未取得 iPhone 内部计数，也未做 USB 对照。
+- **Android 转发：** A、B、C、D、E、I、J 稳定采样均无转发队列过期、溢出或发送失败；A / J 的 1 Hz 队列快照为 0，B / C 最大为 1。A 组排除前 7 秒旧窗口后，窗口 meanMs 的平均值为解密 1.36 ms、收包后至交接 1.40 ms、排队 0.69 ms、发送调用 4.54 ms；交接已包含解密，不能重复相加。完整动态接收日志的处理最大耗时约 3–6 ms，读取等待可达约 50–80 ms；未见持续队列积压。没有证据表明本次帧率主要被 Android 转发器截断，仍不代表其无限吞吐或无线输入链路没有压力。
+- **浏览器解码与绘制：** A / J 解码平均约 5.67 / 5.62 ms，Canvas drawImage 调用平均约 0.186 / 0.192 ms、P95 均约 0.3 ms，无观测到的主线程长任务。跳过绘制后没有升到 60，原生 Video 也没有升到 60；H.264 各组实际输出基本跟上解码，直接 Canvas 的 Video 元素数始终为 0。drawImage 调用耗时不包含全部异步 GPU / 屏幕呈现工作，本轮没有测量物理显示帧率，也没有用恒定 60 fps 输入确认浏览器极限。
+
+HEVC 单独发现间歇性解码失败：第一次直接 Canvas 接收器出画后停止解码，动态采样前 9 秒 Android 输入与成功发送各增加 392 帧，浏览器接收增加 410、解码增加 0、framesDropped 增加 409、packetsLost 增加 0，约第 10 秒回退 `decode-stalled`。第一次改用原生 Video 也观察到同一回退原因；该次未及时捕获回退前完整时序，不能据其计算动态性能。随后重新建立原生 Video 接收器的 18.56 秒采样恢复约 51.18 fps 解码；再重新建立直接 Canvas 的 I 组 30.06 秒采样正常，约 50.56 fps 绘制，无回退。故该问题不依赖 Canvas，尚不能区分 HEVC 码流 / 打包参考链和浏览器解码器状态；不把它解释为固定 40–50 fps 性能上限，也不以重连成功宣称已修复。
+
+HEVC 正常组码率约 14.59 Mbps，H.264 A / J 约 29.85 / 28.18 Mbps，但输入只从约 49 提升到约 51 fps；本次顺序采样不能证明无线带宽是唯一瓶颈。Android 热状态从测试前 0 变为后期 1；没有频率及 iPhone 温度证据，未排除热与调度影响。一次辅助 top 采样未可靠对齐动态窗口，不用于 CPU 饱和结论。
+
+下一步若要继续收敛源端原因，应使用同分辨率、同场景的 USB / 无线对照并取得 iPhone 侧帧时间或稳定帧率内容；若要定位 HEVC 间歇失败，应在失败前保存压缩访问单元及 PTS、关键帧 / 参数集信息，与浏览器解码错误对齐，区分码流及打包问题和解码器状态。当前证据不支持优先重写 Canvas 绘制器或增加转发缓冲。
+
+采样、观测脚本及设备日志保存在忽略的 `.local/device-bottleneck-qa/`，未修改产品代码、未安装新 APK。首次 HEVC 回退使汇总脚本遇到空 transport，已保留原始采样并单独分析；该错误不计为产品异常。截图和原始内容不进入版本库。
+
+测试后 UI 确认恢复 30 fps、HEVC 关闭，原始分辨率、自适应和 10 秒恢复时间保留；日志确认 2544×1576 / 30 fps / H.264 重新协商及首帧，直接 Canvas 恢复并可触控。随后撤销页面观测包装、断开并关闭专用测试浏览器，偏好恢复直接 Canvas。用户原 Chrome 在本轮开始时即为「已配对 · 等待启动」，本轮没有修改它的地址、选项或连接状态。
+
+## HEVC 间歇性 decode-stalled：长度前缀被误识别（2026-10-21）
+
+本轮在同一真机链路、2544×1576 / HEVC / 60 fps 下，分别用原生 Video 和直接 Canvas 复现停滞，确认了 Android Native 码流转换的确定性缺陷。产品代码及设备 APK 均未修改；已安装 APK 与本地 Debug APK SHA-256 一致（`fd24d487512022b9b9100ea9aa7cbd6b96fbb2e65d50abff6e91a69172de4ed2`）。浏览器为 Chromium 156.0.8078.47，revision `1d17a2e2ee147bb7d6ae2ab6abdb3a2510c17775`。
+
+**观测方法与证据。** 临时为测试 PeerConnection 启用 encoded insertable streams，在接收器解包后、解码前复制真实 RTCEncodedVideoFrame 数据与元信息，并立即原样送入 writable；没有改变帧内容或插入媒体。保存 Annex B 数据、每帧边界 / RTP 时间戳 / NAL 类型及 1 Hz getStats，另用本机 FFmpeg 软件解码。新增观测路径会影响时序，因此性能数值不作基准；本轮目的是捕获已损坏的字节，而两种渲染器都确实发生了同类回退。
+
+| 样本 | 解包后捕获帧数 | 末次有效 getStats：收到 / 解码 / 丢弃 | 结果 |
+| --- | ---: | ---: | --- |
+| run-0，直接 Canvas 正常基线 | 导出码流离线解出 2790 帧 | 持续随输入解码，未回退 | 约 100 秒静置后动态恢复正常；FFmpeg 无警告 |
+| run-1，原生 Video 重连 | 248 | 231 / 11 / 210 | 首帧后停止解码，decode-stalled；末次有效 stats 丢包 0 |
+| run-2，直接 Canvas 重连 | 193 | 125 / 7 / 108 | 同类异常及回退；末次有效 stats 丢包 0 |
+
+表中捕获总数包含末次有效 stats 之后、关闭前到达的帧，不能用三项计数直接相减核算全部丢弃。失败样本的元信息长度总和与二进制文件长度完全一致。run-1 / run-2 的 FFprobe 分别只能离线解出 88 / 84 帧，报告 `Failed to parse header of NALU`、`Could not find ref with POC` 和 `Error constructing the frame RPS`；FFmpeg 可能跳过错误后继续解码，不能把进程退出成功误称为码流有效。浏览器 Media 域未提供有用的 decoder-specific 错误，本轮未取得硬件解码器的私有日志。
+
+**确定性原因。** `common/src/main/cpp/video_buffer.hpp:38` 的 `annexB()` 同时用 `prefix()` 判断是否已经为 Annex B；`prefix()` 将 `00 00 01` 识别为三字节起始码。AirPlay 的四字节大端 NAL 长度在 256–511 范围内恰为 `00 00 01 xx`，因此 `if (!prefix(0))` 跳过整个长度前缀转换，后续扫描把 `xx` 当成 NAL 头。`video_packetizer.hpp` 按已声明的 Annex B 输入扫描，于是把这个多余字节连同原 NAL 一起封进 RTP。问题位于打包前的格式转换，不是已确认的 FU 位布局或浏览器绘制问题。
+
+run-1 捕获的第 12 个访问单元（索引 11）为：
+
+```text
+推导出的长度前缀输入：00 00 01 7c 02 01 d0 0b ...
+                     长度 380 └─真实 HEVC NAL 头
+应得到的 Annex B：   00 00 00 01 02 01 d0 0b ...
+浏览器实际收到：     00 00 00 01 7c 02 01 d0 0b ...
+```
+
+抓包不是 Android 转换前的直接采样，第一行明确是根据接收数据推导：长度字段为 380，剩余 payload 恰好 380 字节。将此输入送入**未修改的生产转换器与打包器**，得到 385 字节，与浏览器捕获结果逐字节相同。字节 `7c` 令该 NAL 被识别为 type 62 / tid_plus1 2；原本的 `02 01` 则是 type 1 / tid_plus1 1。run-2 也在同一字节位置出现相同偏移模式。
+
+另外用隔离的 C++ 诊断程序扫描首个 NAL 长度 2–1100，恰有 256 个长度失败，范围精确为 256–511；255 和 512 正常。生产的 `test/native/video-packetizer.cpp` 原有 MTU / FU / marker / 参数集 roundtrip 测试仍通过，它只给 packetizer 输入正确 Annex B，没有覆盖 Native 长度前缀转换。Native 随后的关键帧扫描还可能把长度末字节误认成 IRAP，导致错误插入参数集和虚假的关键帧分类。静态或低变化画面更容易产生小 NAL，符合间歇性触发特征，但并非所有静态画面都必然触发。
+
+**与浏览器的区分。** 浏览器解码前数据已损坏，独立软件解码也出现语法与参考链错误；两种渲染器都复现，且页内捕获没有修改帧。因此本轮复现的首要原因是 Android Native 格式误判，不能再把该现象仅归为浏览器 HEVC 性能或随机解码器状态。正常样本包含 VPS / SPS / PPS / IDR，RTP FU、时间戳及末包 marker 的实现和已有测试未暴露同类问题；协议核对依据 [RFC 7798](https://www.rfc-editor.org/rfc/rfc7798.html)。这不代表已排除所有 HEVC 或浏览器兼容问题，也未声称修复后验证完成。
+
+**建议修复与验证。** 将“输入格式判定”和“Annex B NAL 扫描”分开；AirPlay 长度前缀入口按已知格式验证完整访问单元后转换，不能用前三个字节推断格式。若需保留 Annex B 输入支持，应明确输入契约并与 JVM 路径对齐，避免破坏合法三 / 四字节起始码。补充 Native / JVM 一致性及 255、256、380、511、512 边界、多 NAL、畸形长度、不误判关键帧的测试；使用本次推导输入及不含私人画面的等价夹具验证转换和 RTP 往返字节一致。修复后再做同 APK 真机 HEVC 两种渲染器重连、静置 / 动态恢复、H.264 回归，核对 encoded 数据及 decode-stalled，而非只确认首次出画。风险主要是既有 Annex B 兼容分支；问题代码为 AVC / HEVC 共用，H.264 也应补测。
+
+原始媒体、元信息、离线解码日志及隔离复现程序保存在 Git 忽略的 `.local/hevc-diagnosis/`，包含真实 CarPlay 内容，不提交版本库。诊断阶段未修改产品实现、未安装 APK；尚未实施上述修复。
+
+测试后已关闭临时 HEVC、恢复 30 fps，保留原始分辨率、自适应与 10 秒恢复策略。设备日志确认恢复后的 2544×1576 / 30 fps / H.264 协商及首帧，网页恢复直接 Canvas 绘制、触控及 Video 数量 0；撤销观测包装后断开并关闭专用测试浏览器，原 Chrome 未操作。`git diff --check` 通过。
+
+## HEVC 长度前缀修复及真机复验（2026-10-21）
+
+已实施上一节定位的修复：Native 转换器通过 `VideoInputFormat` 显式区分长度前缀与 Annex B；两个 AirPlay 解密入口均指定 LengthPrefixed，完整验证访问单元后再改写长度。Annex B 的三 / 四字节起始码扫描独立保留，不再通过前三个字节推断输入格式。每次扫描先清除关键帧标记，畸形长度不产生虚假的关键帧。没有改变 RTP 分片、浏览器解码策略或恢复时间。
+
+**回归检查。** 新增 `test/native/video-buffer.cpp`，覆盖 AVC / HEVC 的 2–1101 字节 NAL（含完整 256–511 缺陷区间）、单 / 多 NAL、关键帧分类、65536 字节分片、显式三 / 四字节 Annex B、歧义输入与畸形长度，并经过生产 packetizer / FU 重组逐字节校验。该测试在旧转换器上先失败，修复后以 ASan / UBSan 编译运行通过；已有 packetizer 测试也通过。上一节推导的真实 380 字节输入经修复后得到正确 384 字节访问单元，移除多余长度尾字节。`npm test` 94 项通过，`npm run check`、`git diff --check` 及 `:mobile:assembleDebug --no-configuration-cache` 通过。Native 新测试已注册至 CMake；本轮运行的是上述两个独立 Native 可执行文件，未重跑完整 CMake 套件。
+
+**同设备实测。** 安装修复版 Debug APK，并核对设备上 APK 的 SHA-256 与本地产物一致：`4fb3f33a988ee417897fe644b7a513ffc7357d81a1aa1fb46876b6d9a696c3a3`。沿用 Pixel 3 / Android 15、无线 iPhone XS Max、Chromium 156 的真实链路；设置 HEVC、协商上限 60 fps、自适应 2544×1576，恢复容忍时间仍为 10 秒。五轮通过网页断开后重新连接，使用真实触控滑动应用页产生动态画面；没有合成输入或替换压缩帧。
+
+| 轮次 / 模式 | 观测时长 | 末次收到 / 解码 / 丢弃 | 结果 |
+| --- | ---: | ---: | --- |
+| 0，直接 Canvas，捕获开启 | 142 秒 | 3026 / 3023 / 0 | 静止超过一分钟后恢复滑动，持续出画 |
+| 1，原生 Video，捕获开启 | 50 秒 | 1278 / 1278 / 0 | 重连后正常解码与显示 |
+| 2，直接 Canvas，捕获开启 | 35 秒 | 1044 / 1044 / 0 | 再次重连后正常绘制 |
+| 3，直接 Canvas，捕获关闭 | 38 秒 | 1138 / 1138 / 0 | 排除 encoded insertable streams 观测路径的影响 |
+| 4，兼容 Canvas，捕获关闭 | 31 秒 | 1160 / 1160 / 0 | 旧 Canvas 路径回归通过 |
+
+所有轮次都未记录 `decode-stalled`、其他 JPEG 回退或丢包；轮次 0 终止采样时有 3 帧尚未解码，当时 framesDropped 为 0，不能将该瞬间差额算作解码丢弃。直接 Canvas 的各轮 Video 元素数均为 0。动态窗口排除开始 2 秒后，轮次 0 / 2 / 3 成功绘制约 50.46 / 51.00 / 52.20 fps，原生轮次 1 解码约 51.60 fps；这些顺序触控样本用于稳定性回归，不是恒定内容的性能基准，也未证明已达到持续 60 fps。兼容 Canvas 保留动画帧补偿，绘制次数不能作为不同视频帧的数量。
+
+前三轮共捕获 5348 个完整访问单元，元信息与导出二进制边界一致，没有超过保存容量。包含 **32 个 256–511 字节 NAL**，其头部均为正确的 HEVC type 1 / layer 0 / tid_plus1 1；所有捕获 NAL 均未再出现上一节多余长度字节形成的异常头部。三份码流经 FFmpeg `-xerror` 解码及 FFprobe 逐帧计数，分别完整解出 3026 / 1278 / 1044 帧，警告和错误日志均为空。结合旧版本的确定性失败用例、同长度区间实测和独立解码结果，本轮确认已修复此前定位的格式误判；短时复验不代表穷尽所有 HEVC 设备兼容性或长时间运行问题。
+
+**恢复与清理。** UI 再次确认恢复 30 fps、HEVC 关闭、原始分辨率、自适应开启及 10 秒容忍时间。重新连接后的网页实际协商 H.264，直接 Canvas 首轮恢复约 30 fps，继续滑动可见画面更新，累计绘制 629 帧，未回退，Video 数量 0。随后释放触点、撤销页面观测包装、恢复直接 Canvas 偏好并断开关闭专用测试浏览器；用户原 Chrome 的地址、选项和连接状态未操作。保留修复版 APK，未恢复旧缺陷版本。原始码流、元信息、构建与设备日志保存在忽略的 `.local/hevc-fix-qa/`，真实内容不提交版本库。

From a710ab91bbaea6cc1f1ef978d28d6a6aad53d8c9 Mon Sep 17 00:00:00 2001
From: seasonyuu <seasonyuu@gmail.com>
Date: Wed, 21 Oct 2026 15:56:32 +0800
Subject: [PATCH 4/6] fix(web): probe WebP within Android content security
 policy

Use a temporary Blob URL for the WebP capability image and revoke it on completion. Run the real browser media regression against the Android CSP so blocked data URLs cannot silently disable WebP negotiation.
---
 common/src/main/assets/web/app.js   | 17 ++++++++++++++---
 scripts/test-media-presentation.mjs |  3 +++
 test/image-pipeline.test.js         |  7 ++++++-
 3 files changed, 23 insertions(+), 4 deletions(-)

diff --git a/common/src/main/assets/web/app.js b/common/src/main/assets/web/app.js
index 0c5079e..57e75e4 100644
--- a/common/src/main/assets/web/app.js
+++ b/common/src/main/assets/web/app.js
@@ -139,19 +139,30 @@ export function decodeVideoPacket(buffer) {
   return { ...packet, protocol, mime: format === 2 ? 'image/webp' : 'image/jpeg', jpeg: buffer.slice(headerBytes) };
 }
 
-export function probeWebp({ createImage = () => new Image(), schedule = setTimeout, cancel = clearTimeout } = {}) {
+export function probeWebp({ createImage = () => new Image(), schedule = setTimeout, cancel = clearTimeout,
+  createUrl = data => URL.createObjectURL(data), revokeUrl = url => URL.revokeObjectURL(url),
+} = {}) {
   return new Promise(resolve => {
-    let image, timer = null, finished = false;
+    let image, url = null, timer = null, finished = false;
     const finish = supported => {
       if (finished) return; finished = true; cancel(timer);
       if (image) { image.onload = image.onerror = null; image.removeAttribute('src'); }
+      if (url !== null) revokeUrl(url);
       resolve(supported);
     };
     try {
       image = createImage(); timer = schedule(() => finish(false), 1500);
       image.onload = () => finish(image.naturalWidth === 2 && image.naturalHeight === 2);
       image.onerror = () => finish(false);
-      image.src = 'data:image/webp;base64,UklGRjwAAABXRUJQVlA4IDAAAADQAQCdASoCAAIAAgA0JaACdLoB+AADsAD+8MQL/yC5YXXI1/8gP+QH/ID/+PIAAAA=';
+      // The Android page allows blob: images but deliberately blocks data: URLs.
+      // This is the same 2x2 WebP fixture used by the capability probe.
+      url = createUrl(new Blob([new Uint8Array([
+        82, 73, 70, 70, 60, 0, 0, 0, 87, 69, 66, 80, 86, 80, 56, 32, 48, 0, 0, 0,
+        208, 1, 0, 157, 1, 42, 2, 0, 2, 0, 2, 0, 52, 37, 160, 2, 116, 186, 1, 248,
+        0, 3, 176, 0, 254, 240, 196, 11, 255, 32, 185, 97, 117, 200, 215, 255, 32,
+        63, 228, 7, 252, 128, 255, 248, 242, 0, 0, 0,
+      ])], { type: 'image/webp' }));
+      image.src = url;
     } catch (_) { finish(false); }
   });
 }
diff --git a/scripts/test-media-presentation.mjs b/scripts/test-media-presentation.mjs
index c3e50ff..c3502d7 100644
--- a/scripts/test-media-presentation.mjs
+++ b/scripts/test-media-presentation.mjs
@@ -12,6 +12,8 @@ import { resourceStrings, renderBrowserTemplate } from './resource-strings.mjs';
 const pause = ms => new Promise(resolve => setTimeout(resolve, ms));
 const messages = resourceStrings('values-zh-rCN');
 const root = new URL('../common/src/main/assets/web/', import.meta.url);
+const androidServer = await readFile(new URL('../common/src/main/java/com/shilapi/xcertplay/web/LanWebServer.kt', import.meta.url), 'utf8');
+const csp = androidServer.match(/"(default-src 'self';[^"\n]+)"/)[1];
 const profile = await mkdtemp(join(tmpdir(), 'wheelplay-media-'));
 function image(width, height, codec = 'mjpeg') {
   const result = spawnSync(ffmpeg, ['-v', 'error', '-f', 'lavfi', '-i', `testsrc=size=${width}x${height}:rate=1`,
@@ -25,6 +27,7 @@ const touches = [], errors = [];
 let media = { type: 'status', mediaProtocol: 3, sessionId: 7, videoEpoch: 1, width: 320, height: 180,
   sourceState: 'ready', inputReady: true, streaming: true, stage: 'Synthetic browser test' };
 const server = http.createServer(async (req, res) => {
+  res.setHeader('Content-Security-Policy', csp);
   if (req.url.startsWith('/pair/')) {
     const result = req.url === '/pair/remember' ? { id: 'd'.repeat(32), secret: 's'.repeat(32), name: 'Test' } :
       req.url === '/pair/request' ? { id: 'qr', secret: 'poll', expiresIn: 120 } :
diff --git a/test/image-pipeline.test.js b/test/image-pipeline.test.js
index 5abf61d..e7ac7b1 100644
--- a/test/image-pipeline.test.js
+++ b/test/image-pipeline.test.js
@@ -5,13 +5,18 @@ import { createJpegPresenter, createControlOutbox, decodeVideoPacket, probeWebp
 test('WebP probe checks decoded dimensions and cleans up on success, failure and timeout', async () => {
   for (const result of ['supported', 'wrong-size', 'error', 'timeout']) {
     const image = { naturalWidth: result === 'wrong-size' ? 0 : 2, naturalHeight: 2, removeAttribute() { delete this.src; } };
-    let deadline, cancelled;
+    let deadline, cancelled, fixture;
+    const revoked = [];
     const promise = probeWebp({ createImage: () => image,
+      createUrl: data => { fixture = data; return 'blob:webp-probe'; }, revokeUrl: url => revoked.push(url),
       schedule: fn => { deadline = fn; return 7; }, cancel: id => { cancelled = id; } });
+    assert.equal(image.src, 'blob:webp-probe'); assert.equal(fixture.type, 'image/webp');
+    assert.equal(fixture.size, 68);
     const late = image.onload;
     if (result === 'timeout') deadline(); else if (result === 'error') image.onerror(); else image.onload();
     assert.equal(await promise, result === 'supported');
     late(); assert.equal(cancelled, 7); assert.equal(image.onload, null); assert.equal(image.src, undefined);
+    assert.deepEqual(revoked, ['blob:webp-probe']);
   }
   assert.equal(await probeWebp({ createImage: () => { throw new Error('unavailable'); } }), false);
 });

From 3f5c4624d9999e63fec273a77a0421b023e3d170 Mon Sep 17 00:00:00 2001
From: seasonyuu <seasonyuu@gmail.com>
Date: Wed, 21 Oct 2026 15:56:32 +0800
Subject: [PATCH 5/6] docs: align renderer fallback guidance and record rebased
 device validation

Describe JPEG and WebP image fallback with upstream retry and presentation state. Record merged checks, real HEVC playback and recovery, the CSP probe regression, final APK verification and restored device settings.
---
 README.md                                     |  4 +--
 README.zh-CN.md                               |  4 +--
 docs/ARCHITECTURE.md                          |  4 +--
 docs/VALIDATION.md                            | 26 +++++++++++++++++++
 docs/WEBRTC_RECOVERY.md                       |  4 +--
 .../src/main/res/values-zh-rCN/ui_strings.xml |  8 +++---
 .../src/main/res/values-zh-rTW/ui_strings.xml |  8 +++---
 shared/src/main/res/values/ui_strings.xml     |  8 +++---
 8 files changed, 46 insertions(+), 20 deletions(-)

diff --git a/README.md b/README.md
index 61ab379..db366cc 100644
--- a/README.md
+++ b/README.md
@@ -41,9 +41,9 @@ The connection page offers three **Video display mode** radio cards. **Native Vi
 
 - **Native Video** displays the WebRTC stream in a video element.
 - **Compatibility Canvas** decodes with an offscreen `<video>` and copies frames with `drawImage()`. Video frame callbacks are preferred, with animation frames recovering older browsers or stalled offscreen callbacks.
-- **Direct Canvas** reads WebRTC `VideoFrame` objects through the main-thread `MediaStreamTrackProcessor` and draws them directly. It never creates a `<video>` or uses `VideoDecoder`. Worker-only Processor implementations are outside this first version. Missing support or runtime failure falls back directly to JPEG without switching to a video-element mode.
+- **Direct Canvas** reads WebRTC `VideoFrame` objects through the main-thread `MediaStreamTrackProcessor` and draws them directly. It never creates a `<video>` or uses `VideoDecoder`. Worker-only Processor implementations are outside this first version. Missing support or runtime failure falls back directly to JPEG / WebP without switching to a video-element mode.
 
-The browser remembers the choice across reloads and automatic reconnects; unavailable storage retains it only in the current page. Existing Canvas preferences migrate to Compatibility Canvas. Disconnect before choosing another mode; automatic retries retain the launch choice. Both Canvas modes wait for a successfully drawn frame before stopping JPEG, and touch mapping follows actual frame dimensions. Canvas can increase GPU / CPU usage and does not guarantee 60 fps. Direct Canvas reports successful draw submissions in the status bar; the other modes retain video presentation / decoding statistics. Neither measures physical display refresh. `window.wheelplayStats.presentation` exposes selected / active modes, drawing statistics and fallback reasons.
+The browser remembers the choice across reloads and automatic reconnects; unavailable storage retains it only in the current page. Existing Canvas preferences migrate to Compatibility Canvas. Disconnect before choosing another mode; automatic retries retain the launch choice. Both Canvas modes wait for a successfully drawn frame before stopping the image stream, and touch mapping follows actual frame dimensions. Canvas can increase GPU / CPU usage and does not guarantee 60 fps. Direct Canvas reports successful draw submissions in the status bar; the other modes retain video presentation / decoding statistics. Neither measures physical display refresh. `window.wheelplayStats.presentation` exposes selected / active modes, drawing statistics and fallback reasons.
 
 Canvas mode requires testing on car browsers such as NIO's. Changing the rendering path may help if an overlay covers only the native video element; it cannot guarantee success if the system stops decoding or overlays the entire page. Test while the vehicle is parked. Drivers should use only essential navigation interfaces while driving.
 
diff --git a/README.zh-CN.md b/README.zh-CN.md
index 4e660e1..f155774 100644
--- a/README.zh-CN.md
+++ b/README.zh-CN.md
@@ -43,9 +43,9 @@ WheelPlay 是一款 Android 局域网 CarPlay 服务端应用，可将 iPhone 
 
 - **原生 Video**：由视频元素直接显示 WebRTC 画面。
 - **兼容 Canvas**：保留离屏 `<video>` 解码并使用 `drawImage()` 绘制，优先视频帧回调，旧浏览器或离屏回调停顿时使用动画帧补偿。
-- **直接 Canvas**：使用主线程 `MediaStreamTrackProcessor` 读取 WebRTC `VideoFrame` 并绘制，全程不创建 `<video>`，也不使用 `VideoDecoder`。仅在 Worker 中提供 Processor 的浏览器不在首版支持范围；不支持或运行失败时直接使用 JPEG，不切换到旧的视频元素模式。
+- **直接 Canvas**：使用主线程 `MediaStreamTrackProcessor` 读取 WebRTC `VideoFrame` 并绘制，全程不创建 `<video>`，也不使用 `VideoDecoder`。仅在 Worker 中提供 Processor 的浏览器不在首版支持范围；不支持或运行失败时直接使用 JPEG / WebP，不切换到旧的视频元素模式。
 
-浏览器保存所选方式，刷新和自动重连后保留；禁用存储时仅当前页面有效。原有 Canvas 偏好自动迁移为「兼容 Canvas」。需要断开后重新选择，自动重连不会改变本次启动的方式。两种 Canvas 都在首帧绘制成功后才停止 JPEG；尺寸与触控按实际画面映射。Canvas 可能增加 GPU / CPU 消耗，不保证达到 60 fps。直接 Canvas 状态栏的 fps 是成功绘制次数，其他模式保留原有视频呈现 / 解码统计，均不等于屏幕实际刷新率。`window.wheelplayStats.presentation` 可查看所选 / 实际方式、绘制统计和回退原因。
+浏览器保存所选方式，刷新和自动重连后保留；禁用存储时仅当前页面有效。原有 Canvas 偏好自动迁移为「兼容 Canvas」。需要断开后重新选择，自动重连不会改变本次启动的方式。两种 Canvas 都在首帧绘制成功后才停止图像串流；尺寸与触控按实际画面映射。Canvas 可能增加 GPU / CPU 消耗，不保证达到 60 fps。直接 Canvas 状态栏的 fps 是成功绘制次数，其他模式保留原有视频呈现 / 解码统计，均不等于屏幕实际刷新率。`window.wheelplayStats.presentation` 可查看所选 / 实际方式、绘制统计和回退原因。
 
 Canvas 模式需要蔚来等车机实测：若遮罩只覆盖原生视频元素，改变显示路径可能有效；若系统停止解码或在整个页面上叠加遮罩，则无法保证有效。请在车辆停稳后验证，驾驶员行驶中只应使用必要的导航界面。
 
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
index d76874f..ee01d0c 100644
--- a/docs/ARCHITECTURE.md
+++ b/docs/ARCHITECTURE.md
@@ -39,9 +39,9 @@ v3 可使用 WebP，最多两帧在途，并以媒体版本和帧序号精确 AC
 
 ## 浏览器三种渲染方式
 
-`native` 为默认原生 Video；`video-canvas` 使用离屏 Video 与可见 Canvas；实验性 `track-canvas` 使用主线程 `MediaStreamTrackProcessor({ track, maxBufferSize: 1 })` → `VideoFrame` → Canvas 2D。不新增网络消息、解码器或依赖。两个旧模式按需创建自己的 Video 元素，停止时移除；直接 Canvas 及其 JPEG 回退期间不创建 Video。
+`native` 为默认原生 Video；`video-canvas` 使用离屏 Video 与可见 Canvas；实验性 `track-canvas` 使用主线程 `MediaStreamTrackProcessor({ track, maxBufferSize: 1 })` → `VideoFrame` → Canvas 2D。不新增网络消息、解码器或依赖。两个旧模式按需创建自己的 Video 元素，停止时移除；直接 Canvas 及其 JPEG / WebP 回退期间不创建 Video。
 
-接收器通过渲染器工厂创建适配器，调用 `start(track, streams)`、`stop()` 和 `snapshot()`，由适配器报告首次就绪、尺寸变化及错误。接收器持有 PeerConnection、远端轨道及恢复计时器；适配器持有 reader、绘制上下文、元素及绘制回调。关闭先使代次失效，再停止适配器、移除监听、停止远端轨道并关闭 PeerConnection；取消读取不阻塞重连，读取结束后释放锁。每个读出的 VideoFrame 均在 finally 中 close，包含错误和过期帧。
+接收器通过渲染器工厂创建适配器，调用 `start(track, streams)`、`stop()` 和 `snapshot()`，由适配器报告首次就绪、尺寸变化及错误。接收器持有 PeerConnection、远端轨道及恢复计时器；适配器持有 reader、绘制上下文、元素及绘制回调。关闭先使代次失效，再停止适配器、移除监听、停止远端轨道并关闭 PeerConnection；关闭前先复制当前画面至上游 held-frame，按媒体版本与恢复期限管理显示和触控；取消读取不阻塞重连，读取结束后释放锁。每个读出的 VideoFrame 均在 finally 中 close，包含错误和过期帧。
 
 两种 Canvas 仅在首次绘制成功后发送 `rtc-ready`。画面尺寸来自实际显示帧或 JPEG，心跳中的默认宽高不能覆盖它，以避免竖屏触控失准。直接 Canvas 不要求 `VideoDecoder` 或安全上下文检测；按主线程 Processor 的实际可用性判断，Worker-only 实现使用 JPEG。
 
diff --git a/docs/VALIDATION.md b/docs/VALIDATION.md
index 92f9c4f..93052b4 100644
--- a/docs/VALIDATION.md
+++ b/docs/VALIDATION.md
@@ -506,3 +506,29 @@ run-1 捕获的第 12 个访问单元（索引 11）为：
 前三轮共捕获 5348 个完整访问单元，元信息与导出二进制边界一致，没有超过保存容量。包含 **32 个 256–511 字节 NAL**，其头部均为正确的 HEVC type 1 / layer 0 / tid_plus1 1；所有捕获 NAL 均未再出现上一节多余长度字节形成的异常头部。三份码流经 FFmpeg `-xerror` 解码及 FFprobe 逐帧计数，分别完整解出 3026 / 1278 / 1044 帧，警告和错误日志均为空。结合旧版本的确定性失败用例、同长度区间实测和独立解码结果，本轮确认已修复此前定位的格式误判；短时复验不代表穷尽所有 HEVC 设备兼容性或长时间运行问题。
 
 **恢复与清理。** UI 再次确认恢复 30 fps、HEVC 关闭、原始分辨率、自适应开启及 10 秒容忍时间。重新连接后的网页实际协商 H.264，直接 Canvas 首轮恢复约 30 fps，继续滑动可见画面更新，累计绘制 629 帧，未回退，Video 数量 0。随后释放触点、撤销页面观测包装、恢复直接 Canvas 偏好并断开关闭专用测试浏览器；用户原 Chrome 的地址、选项和连接状态未操作。保留修复版 APK，未恢复旧缺陷版本。原始码流、元信息、构建与设备日志保存在忽略的 `.local/hevc-fix-qa/`，真实内容不提交版本库。
+
+## Rebase 上游后的集成与真机复验（2026-10-21）
+
+分支已 rebase 至 `upstream/main` 的 `03a5934`。保留上游媒体 sessionId / videoEpoch、画面与输入就绪状态、两秒保留画面、浏览器缩放补偿、v3 JPEG / WebP 流水线和有界退避重试，三种渲染器接入同一呈现控制器。关闭渲染器前通过 held-frame 保存当前画面，旧轨道回调仍由代次隔离；直接 Canvas 在重建、图像回退与自动重试期间不创建 Video。明确不支持的编码、Processor / Canvas 或播放权限错误使用 `retryable: false`，临时绘制错误保留上游重试行为。补齐上游新增的两条 Android 浏览器状态文案导出。
+
+**工程检查。** 前端 136 项测试通过，包含新增的直接 Canvas 媒体版本重建及 v3 WebP 回退后重试；Android `:common:testDebugUnitTest` 57 个套件、324 项通过，无失败或跳过。Native 长度前缀测试通过 ASan / UBSan，已有 packetizer 测试通过。`npm run check`、`git diff --check` 和 Android Debug 构建通过。真实 Chromium 媒体测试验证 WebP 探测、缩放下触控、损坏 WebP 后 JPEG 回退、两帧流水线精确 ACK、旧帧拒绝、恢复期限、旋转及 WebSocket 重连；这些合成图像测试与下述真实 CarPlay 验证分别记录。
+
+**真机链路与 HEVC。** 沿用 Pixel 3 / Android 15、无线 iPhone XS Max → Android 转发 → Mac Chromium 的链路，实际 WebRTC 尺寸为 2544×1576。临时协商上限 60 fps / HEVC，容忍时间 10 秒，真实应用页滑动驱动画面。首个 rebase APK SHA-256 为 `b945cf72f401b1d990554afdd0a178e547d11265c160c4c79ff8b2e65f848afe`，核对设备安装包一致。
+
+| 轮次 | 收到 / 解码 / 丢弃 | 观测结果 |
+| --- | ---: | --- |
+| H.264 / 30 fps / 直接 Canvas | 402 / 402 / 0 | 动态触控正常，动态窗口约 26.67 fps 绘制 |
+| HEVC / 直接 Canvas，捕获开启 | 2496 / 2496 / 0 | 约 135 秒，静置约 80 秒后动态恢复；动态窗口约 51.12 fps 绘制 |
+| HEVC / 原生 Video，捕获开启 | 999 / 999 / 0 | 重连后正常，动态窗口约 52.73 fps 解码 |
+| HEVC / 兼容 Canvas，捕获关闭 | 843 / 843 / 0 | 重连与滑动正常，动态窗口约 51.99 fps 解码 |
+| HEVC / 直接 Canvas，捕获关闭 | 1089 / 1089 / 0 | 正常运行后注入一次临时绘制异常，JPEG 回退后自动重试恢复 |
+
+上表正常运行期间没有 decode-stalled 或非预期回退，末次统计丢包均为 0。两份真实 HEVC 捕获共 3495 帧，含 15 个 256–511 字节 NAL，头部均正确；FFmpeg / FFprobe 分别完整解出 2496 / 999 帧，无警告与错误。Native NAL 修复在 rebase 后继续有效。静态画面的零 fps、Chrome freeze / PLI 计数以及兼容 Canvas 的重复补绘不作为独立故障或显示刷新率证据；顺序触控样本未证明持续达到 60 fps。
+
+**真机额外发现并修复 WebP 探测问题。** 上游探测图片使用 `data:` URL，但 Android 实际 CSP 为 `img-src 'self' blob:`，因此真实页面探测失败并一直协商 JPEG；原浏览器测试服务没有同一 CSP，未暴露问题。改用相同 68 字节、2×2 WebP 的 Blob URL，在成功、失败和超时后均释放 URL，不放宽 CSP。浏览器测试改为读取 Android 服务端实际 CSP：旧探测先因等待 WebP 超时失败，修复后全部通过；单元测试补充 Blob 类型、尺寸及幂等释放断言。
+
+最终 APK SHA-256 为 `b3adefe53f82aa1b2268ba4ad02d270bbaf8534d6d7b8bce54283a443b852bfb`，再次安装并核对设备哈希。真机页面实际 WebP 探测成功，状态统计为 protocol 3 / image/webp。最终 APK 的直接 Canvas 动态窗口约 50.67 fps；注入一次只影响 drawImage 的异常后，真实 WebP 画面成功加载，2544×1576 图像可见且输入就绪；约 5.8 秒自动恢复 HEVC / 直接 Canvas，恢复后动态窗口约 50.99 fps，末次收到 / 解码均为 964 帧，丢弃和丢包为 0。故障观测全过程 Video DOM 数、Video 创建次数和视频 play 调用次数均为 0。该故障注入未改写压缩码流或协议，仅用于验证回退与恢复。
+
+1280px 连接页三列、390px 单列，均无横向溢出且 Video 数为 0。测试后 UI 确认恢复 30 fps、HEVC 关闭、原始分辨率、自适应开启和 10 秒容忍时间；新增加的图片格式 WebP / 质量 75 沿用安装后的设置，测试未修改。实际重新协商 H.264 后，触控与直接 Canvas 正常，末次收到 / 解码均为 1038 帧，丢弃为 0，未回退；Video 创建和 play 调用均为 0。随后释放触点，撤销页面观测包装，恢复直接 Canvas 偏好，断开并关闭专用测试浏览器。设备保留最终修复版 APK。
+
+记录、真实码流、设备与构建日志保存至忽略的 `.local/rebase-qa/`；不提交私人画面。目标车机型号及长时间运行仍需单独验证，本轮未操作用户原 Chrome。
diff --git a/docs/WEBRTC_RECOVERY.md b/docs/WEBRTC_RECOVERY.md
index ca07a64..3030ccb 100644
--- a/docs/WEBRTC_RECOVERY.md
+++ b/docs/WEBRTC_RECOVERY.md
@@ -64,8 +64,8 @@ WebSocket 控制连接的心跳与重连规则独立于视频策略；整个网
 
 ## 直接 Canvas 的恢复与回退
 
-直接 Canvas 缺少主线程 Processor 时不请求 WebRTC，保留 JPEG；前端仍记录 `processor-unsupported` 并显示提示，不依赖服务端 fallback 字段。已收到 offer 后发现不可用时发送匹配 ID 的 rtc-fallback。Processor 构造、读取、绘制错误或轨道意外结束立即回退；回退保留控制和音频通道，释放触点、reader 及 Canvas 缓冲，不转用旧 Video 模式。
+直接 Canvas 缺少主线程 Processor 时不请求 WebRTC，保留图像串流（JPEG / WebP）；前端仍记录 `processor-unsupported` 并显示提示，不依赖服务端 fallback 字段。已收到 offer 后发现不可用时发送匹配 ID 的 rtc-fallback。Processor 构造、读取、绘制错误或轨道意外结束立即回退；回退保留控制和音频通道，释放触点、reader 及 Canvas 缓冲，不转用旧 Video 模式。
 
 首次成功绘制之前保持 JPEG，首帧等待 `max(10000ms, recoveryGraceMs)`。持续发送时分别检查解码和绘制进展，即使 framesDecoded 增长而画布不再更新，也会在所选容忍时间后回退。没有新输入的静态画面不触发渲染停滞；恢复输入时重新计时。连接短暂断开时仍保留最后一帧。
 
-`presentation.fallbackReason` 区分 processor-unsupported、renderer-error、track-ended、first-frame-timeout、decode-stalled、render-stalled、stats-unavailable、connection-failed、codec-unsupported 等原因；server-stop 表示服务端停止本次媒体。选择保留，重新连接或视频配置变化后允许重试。直接 Canvas 状态栏使用 renderedFps，原生 Video 与兼容 Canvas 继续使用 presentedFps / decodedFps。
+`presentation.fallbackReason` 区分 processor-unsupported、renderer-error、track-ended、first-frame-timeout、decode-stalled、render-stalled、stats-unavailable、connection-failed、codec-unsupported 等原因；server-stop 表示服务端停止本次媒体。选择保留；可恢复错误沿用上游有界退避重试，缺少 Processor、Canvas 2D 或明确的平台不支持错误停止当前配置的重试，重新连接或配置变化后再尝试。直接 Canvas 状态栏使用 renderedFps，原生 Video 与兼容 Canvas 继续使用 presentedFps / decodedFps。
diff --git a/shared/src/main/res/values-zh-rCN/ui_strings.xml b/shared/src/main/res/values-zh-rCN/ui_strings.xml
index e406317..fc2c8ab 100644
--- a/shared/src/main/res/values-zh-rCN/ui_strings.xml
+++ b/shared/src/main/res/values-zh-rCN/ui_strings.xml
@@ -552,9 +552,9 @@
     <string name="web_video_renderer_compat">兼容 Canvas</string>
     <string name="web_video_renderer_compat_description">使用离屏视频解码，再绘制到画布。</string>
     <string name="web_video_renderer_direct">直接 Canvas</string>
-    <string name="web_video_renderer_direct_description">不使用视频元素；不支持时使用 JPEG。</string>
+    <string name="web_video_renderer_direct_description">不使用视频元素；不支持时使用 JPEG / WebP。</string>
     <string name="web_video_renderer_experimental">实验性</string>
-    <string name="web_video_renderer_hint">此浏览器不支持直接 Canvas，连接后将使用 JPEG。</string>
-    <string name="web_video_renderer_unavailable">（直接 Canvas 不可用，已使用 JPEG）</string>
-    <string name="web_video_renderer_failed">（视频中断，已回退 JPEG）</string>
+    <string name="web_video_renderer_hint">此浏览器不支持直接 Canvas，连接后将使用 JPEG / WebP。</string>
+    <string name="web_video_renderer_unavailable">（直接 Canvas 不可用，已使用 JPEG / WebP）</string>
+    <string name="web_video_renderer_failed">（视频中断，已回退 JPEG / WebP）</string>
 </resources>
diff --git a/shared/src/main/res/values-zh-rTW/ui_strings.xml b/shared/src/main/res/values-zh-rTW/ui_strings.xml
index 95ba350..1b6f529 100644
--- a/shared/src/main/res/values-zh-rTW/ui_strings.xml
+++ b/shared/src/main/res/values-zh-rTW/ui_strings.xml
@@ -552,9 +552,9 @@
     <string name="web_video_renderer_compat">相容 Canvas</string>
     <string name="web_video_renderer_compat_description">使用離螢幕影片解碼，再繪製到畫布。</string>
     <string name="web_video_renderer_direct">直接 Canvas</string>
-    <string name="web_video_renderer_direct_description">不使用影片元素；不支援時使用 JPEG。</string>
+    <string name="web_video_renderer_direct_description">不使用影片元素；不支援時使用 JPEG / WebP。</string>
     <string name="web_video_renderer_experimental">實驗性</string>
-    <string name="web_video_renderer_hint">此瀏覽器不支援直接 Canvas，連線後將使用 JPEG。</string>
-    <string name="web_video_renderer_unavailable">（直接 Canvas 無法使用，已使用 JPEG）</string>
-    <string name="web_video_renderer_failed">（影片中斷，已改用 JPEG）</string>
+    <string name="web_video_renderer_hint">此瀏覽器不支援直接 Canvas，連線後將使用 JPEG / WebP。</string>
+    <string name="web_video_renderer_unavailable">（直接 Canvas 無法使用，已使用 JPEG / WebP）</string>
+    <string name="web_video_renderer_failed">（影片中斷，已改用 JPEG / WebP）</string>
 </resources>
diff --git a/shared/src/main/res/values/ui_strings.xml b/shared/src/main/res/values/ui_strings.xml
index e874cd5..6fc8a2d 100644
--- a/shared/src/main/res/values/ui_strings.xml
+++ b/shared/src/main/res/values/ui_strings.xml
@@ -552,9 +552,9 @@
     <string name="web_video_renderer_compat">Compatibility Canvas</string>
     <string name="web_video_renderer_compat_description">Decode with an offscreen video element, then draw to the canvas.</string>
     <string name="web_video_renderer_direct">Direct Canvas</string>
-    <string name="web_video_renderer_direct_description">No video element. Use JPEG if unsupported.</string>
+    <string name="web_video_renderer_direct_description">No video element. Use JPEG / WebP if unsupported.</string>
     <string name="web_video_renderer_experimental">Experimental</string>
-    <string name="web_video_renderer_hint">This browser does not support Direct Canvas. JPEG will be used after connecting.</string>
-    <string name="web_video_renderer_unavailable"> (Direct Canvas unavailable; using JPEG)</string>
-    <string name="web_video_renderer_failed"> (video interrupted; using JPEG)</string>
+    <string name="web_video_renderer_hint">This browser does not support Direct Canvas. JPEG / WebP will be used after connecting.</string>
+    <string name="web_video_renderer_unavailable"> (Direct Canvas unavailable; using JPEG / WebP)</string>
+    <string name="web_video_renderer_failed"> (video interrupted; using JPEG / WebP)</string>
 </resources>

From 9a073a7017cb7a657bc1886021edde272d2e15d5 Mon Sep 17 00:00:00 2001
From: Siubeng <fythonx@gmail.com>
Date: Wed, 21 Oct 2026 16:43:36 +0800
Subject: [PATCH 6/6] fix(web): preserve direct Canvas frame before fallback
 cleanup

---
 common/src/main/assets/web/app.js |  6 +++++-
 test/stream-client.test.js        | 31 +++++++++++++++++++++++++++++++
 test/track-canvas.test.js         | 28 ++++++++++++++++++++++++++--
 3 files changed, 62 insertions(+), 3 deletions(-)

diff --git a/common/src/main/assets/web/app.js b/common/src/main/assets/web/app.js
index 57e75e4..f393ee2 100644
--- a/common/src/main/assets/web/app.js
+++ b/common/src/main/assets/web/app.js
@@ -403,7 +403,11 @@ export function createTrackCanvasRenderer(canvas, {
         } finally { frame?.close(); }
       }
     } catch (error) {
-      if (current()) { stop(); onError(error.message === 'track-ended' ? 'track-ended' : 'renderer-error', isRtcErrorRetryable(error)); }
+      if (current()) {
+        // Let the receiver freeze the last picture before stop clears the canvas.
+        try { onError(error.message === 'track-ended' ? 'track-ended' : 'renderer-error', isRtcErrorRetryable(error)); }
+        finally { if (generation === token) stop(); }
+      }
     } finally {
       try { activeReader.releaseLock(); } catch (_) {}
       if (reader === activeReader) reader = null;
diff --git a/test/stream-client.test.js b/test/stream-client.test.js
index 6af244f..258179f 100644
--- a/test/stream-client.test.js
+++ b/test/stream-client.test.js
@@ -757,6 +757,37 @@ test('Direct Canvas drawing errors use JPEG and do not change browser audio or t
   assert.equal(ws.sent.filter(m => m.type === 'touch').length, 2);
 });
 
+test('Direct Canvas failures freeze the last frame until the fallback image is decoded', async () => {
+  for (const failure of ['draw', 'end']) {
+    const f = fixture({ storedMode: 'track-canvas' }), ws = await f.connect();
+    const canvas = f.element('video-canvas'), held = f.element('held-frame');
+    let failDraw = false, copied = false;
+    canvas.getContext = () => ({ drawImage() { if (failDraw) throw new Error('draw failed'); } });
+    held.getContext = () => ({ drawImage(source) {
+      assert.equal(source, canvas); assert.equal(source.hidden, false);
+      assert.equal(source.width, 1280); assert.equal(source.height, 720);
+      copied = true;
+    } });
+    await f.offer(ws); await f.decoded();
+    f.pointer('pointerdown', 100, 'touch-surface');
+    if (failure === 'draw') { failDraw = true; await f.decoded(); }
+    else {
+      f.processors.at(-1).pending.shift()({ done: true });
+      await new Promise(resolve => setImmediate(resolve));
+    }
+    assert.equal(copied, true); assert.equal(held.hidden, false);
+    assert.equal(canvas.width, 0); assert.equal(f.element('waiting').hidden, true);
+    assert.deepEqual(ws.sent.filter(m => m.type === 'touch').at(-1).contacts, []);
+    assert.equal(f.processors[0].canceled, true); assert.equal(f.processors[0].released, true);
+    assert.equal(ws.sent.filter(m => m.type === 'rtc-fallback').length, 1);
+    ws.onmessage({ data: {} });
+    assert.equal(held.hidden, false, 'Keep the snapshot while the fallback image is loading');
+    [f.element('screen'), f.element('screen-next'), f.element('screen-third')].find(image => image.onload).onload();
+    assert.equal(held.hidden, true); assert.equal(held.width, 0);
+    assert.equal(f.createdVideos.length, 0);
+  }
+});
+
 test('an automatic retry keeps the launch mode until the user starts a new display session', async () => {
   const f = fixture({ storedMode: 'track-canvas' }), ws = await f.connect();
   f.select('native'); ws.close();
diff --git a/test/track-canvas.test.js b/test/track-canvas.test.js
index a6a338b..ce114d5 100644
--- a/test/track-canvas.test.js
+++ b/test/track-canvas.test.js
@@ -3,12 +3,13 @@ import assert from 'node:assert/strict';
 import { createTrackCanvasRenderer } from '../common/src/main/assets/web/app.js';
 const flush = () => new Promise(resolve => setImmediate(resolve));
 
-function fixture({ contextAvailable = true, constructError = false } = {}) {
+function fixture({ contextAvailable = true, constructError = false, onError = () => {} } = {}) {
   const draws = [], ready = [], sizes = [], errors = [], readers = [], configurations = [];
   const context = { drawImage: (...args) => draws.push(args) };
   const canvas = { hidden: true, width: 0, height: 0, getContext: () => contextAvailable ? context : null };
   const renderer = createTrackCanvasRenderer(canvas, {
-    onReady: size => ready.push(size), onResize: size => sizes.push(size), onError: reason => errors.push(reason),
+    onReady: size => ready.push(size), onResize: size => sizes.push(size),
+    onError: reason => { errors.push(reason); onError(reason); },
     createProcessor(init) {
       if (constructError) throw new Error('not supported');
       configurations.push(init);
@@ -89,3 +90,26 @@ test('a canceled read rejection cannot report an error into a replacement sessio
   assert.equal(f.errors.length, 0); assert.equal(old.releases, 1);
   await f.frame(); assert.equal(f.ready.length, 1);
 });
+
+test('a read failure preserves the displayed frame for the error callback before releasing it', async () => {
+  let captured;
+  const f = fixture({ onError() {
+    captured = { hidden: f.canvas.hidden, width: f.canvas.width, height: f.canvas.height };
+  } });
+  f.renderer.start({}); await f.frame();
+  f.readers[0].pending.shift().reject(new Error('read failed')); await flush();
+  assert.deepEqual(captured, { hidden: false, width: 1280, height: 720 });
+  assert.equal(f.canvas.width, 0); assert.equal(f.canvas.hidden, true);
+  assert.equal(f.readers[0].cancels, 1); assert.equal(f.readers[0].releases, 1);
+});
+
+test('error cleanup does not stop a renderer restarted by its error callback', async () => {
+  const f = fixture({ onError() { f.renderer.start({}); } });
+  f.renderer.start({}); await f.frame();
+  const old = f.readers[0]; old.pending.shift().reject(new Error('read failed')); await flush();
+  await f.frame(720, 1280);
+  assert.equal(old.cancels, 1); assert.equal(old.releases, 1);
+  assert.equal(f.readers[1].cancels, undefined);
+  assert.equal(f.canvas.hidden, false); assert.equal(f.canvas.width, 720);
+  f.renderer.stop();
+});