From 2c5da744eba6625d5bff6a3e6e26cdcb645365c5 Mon Sep 17 00:00:00 2001
From: joaner <1726541+joaner@users.noreply.github.com>
Date: Wed, 5 Aug 2026 17:01:31 +0800
Subject: [PATCH 1/2] refactor: redesign media debug overlay as vertical
 key-value panel

Replace the crowded single-line layout with a Stats-for-nerds style
overlay, drop redundant feature/dtype/title fields, and allow copy.
---
 .../panels/Common/MediaDebugOverlay.tsx       | 27 +++++++------------
 .../panels/ImagePanel/ImagePanel.tsx          |  1 -
 .../panels/VideoPanel/VideoPanel.tsx          |  1 -
 src/react/locales/en.json                     |  8 ------
 src/react/locales/zh.json                     |  8 ------
 tests/media-debug-overlay.spec.ts             |  9 ++++---
 6 files changed, 15 insertions(+), 39 deletions(-)

diff --git a/src/react/components/panels/Common/MediaDebugOverlay.tsx b/src/react/components/panels/Common/MediaDebugOverlay.tsx
index 0ec3801..9a87dd6 100644
--- a/src/react/components/panels/Common/MediaDebugOverlay.tsx
+++ b/src/react/components/panels/Common/MediaDebugOverlay.tsx
@@ -4,7 +4,6 @@ import { cn } from '@/ui';
 import type { MediaDebugMetadata } from '@/core';
 
 interface MediaDebugOverlayProps {
-  featureKey: string;
   metadata: MediaDebugMetadata | null;
   translationPrefix: 'panels.video.debug' | 'panels.image.debug';
   className?: string;
@@ -27,7 +26,6 @@ function formatTimeline(metadata: MediaDebugMetadata): string | null {
 }
 
 export const MediaDebugOverlay: React.FC<MediaDebugOverlayProps> = ({
-  featureKey,
   metadata,
   translationPrefix,
   className,
@@ -39,8 +37,6 @@ export const MediaDebugOverlay: React.FC<MediaDebugOverlayProps> = ({
   }
 
   const items = [
-    { label: t(`${translationPrefix}.feature`), value: featureKey, breakAll: true },
-    { label: t(`${translationPrefix}.dtype`), value: metadata.dtype },
     {
       label: t(`${translationPrefix}.fps`),
       value: metadata.fps != null ? String(metadata.fps) : null,
@@ -64,27 +60,22 @@ export const MediaDebugOverlay: React.FC<MediaDebugOverlayProps> = ({
     { label: t(`${translationPrefix}.clipRange`), value: formatTimeline(metadata) },
   ].filter((item) => item.value);
 
+  if (items.length === 0) {
+    return null;
+  }
+
   return (
     <div
-      aria-hidden="true"
       className={cn(
-        'pointer-events-none absolute left-2 top-2 z-10 flex max-w-[calc(100%-1rem)] items-center gap-2 overflow-hidden whitespace-nowrap rounded-md border border-white/10 bg-black/70 px-2 py-1 text-[10px] text-white opacity-0 shadow-lg backdrop-blur-sm transition-opacity duration-150 group-hover:opacity-100 group-focus-within:opacity-100',
+        'absolute left-2 top-2 z-10 max-h-[50%] max-w-[min(16rem,calc(100%-1rem))] overflow-y-auto rounded-md border border-white/10 bg-black/70 px-2.5 py-2 text-[11px] text-white opacity-0 shadow-lg backdrop-blur-sm transition-opacity duration-150 group-hover:opacity-100 group-focus-within:opacity-100',
         className,
       )}
     >
-      <p className="shrink-0 font-semibold uppercase tracking-[0.12em] text-white/70">
-        {t(`${translationPrefix}.title`)}
-      </p>
-      <dl className="flex min-w-0 items-center gap-2 overflow-hidden border-l border-white/15 pl-2">
+      <dl className="flex flex-col gap-1">
         {items.map((item) => (
-          <div
-            key={item.label}
-            className={cn('flex shrink-0 items-baseline gap-1', item.breakAll && 'min-w-0 shrink')}
-          >
-            <dt className="shrink-0 text-white/60">{item.label}</dt>
-            <dd
-              className={cn('font-mono tabular-nums', item.breakAll && 'min-w-0 max-w-48 truncate')}
-            >
+          <div key={item.label} className="grid grid-cols-[auto_1fr] items-baseline gap-x-3 gap-y-0">
+            <dt className="shrink-0 text-white/55">{item.label}</dt>
+            <dd className="min-w-0 break-all text-right font-mono tabular-nums text-white/95">
               {item.value}
             </dd>
           </div>
diff --git a/src/react/components/panels/ImagePanel/ImagePanel.tsx b/src/react/components/panels/ImagePanel/ImagePanel.tsx
index b0f3591..21d8a2f 100644
--- a/src/react/components/panels/ImagePanel/ImagePanel.tsx
+++ b/src/react/components/panels/ImagePanel/ImagePanel.tsx
@@ -279,7 +279,6 @@ export const ImagePanel: React.FC<ImagePanelProps> = ({ params }) => {
   return (
     <div className="group relative flex h-full w-full items-center justify-center overflow-hidden bg-black">
       <MediaDebugOverlay
-        featureKey={featureKey}
         metadata={debugMetadata}
         translationPrefix="panels.image.debug"
       />
diff --git a/src/react/components/panels/VideoPanel/VideoPanel.tsx b/src/react/components/panels/VideoPanel/VideoPanel.tsx
index 68ae8cc..4ac7020 100644
--- a/src/react/components/panels/VideoPanel/VideoPanel.tsx
+++ b/src/react/components/panels/VideoPanel/VideoPanel.tsx
@@ -314,7 +314,6 @@ const VideoPanelContent: React.FC<VideoPanelProps> = ({ params }) => {
   return (
     <div className="group relative flex h-full w-full items-center justify-center overflow-hidden bg-black">
       <MediaDebugOverlay
-        featureKey={featureKey}
         metadata={debugMetadata}
         translationPrefix="panels.video.debug"
       />
diff --git a/src/react/locales/en.json b/src/react/locales/en.json
index 650b55e..7006b2e 100644
--- a/src/react/locales/en.json
+++ b/src/react/locales/en.json
@@ -468,10 +468,6 @@
       "title": "Video Panel",
       "placeholder": "Waiting for video file...",
       "debug": {
-        "title": "Media debug",
-        "feature": "Feature",
-        "dtype": "DType",
-        "shape": "Shape",
         "fps": "FPS",
         "resolution": "Resolution",
         "codec": "Codec",
@@ -487,10 +483,6 @@
       "title": "Image Panel",
       "placeholder": "Waiting for image file...",
       "debug": {
-        "title": "Media debug",
-        "feature": "Feature",
-        "dtype": "DType",
-        "shape": "Shape",
         "fps": "FPS",
         "resolution": "Resolution",
         "codec": "Codec",
diff --git a/src/react/locales/zh.json b/src/react/locales/zh.json
index d33d776..e9fcac9 100644
--- a/src/react/locales/zh.json
+++ b/src/react/locales/zh.json
@@ -465,10 +465,6 @@
       "title": "视频面板",
       "placeholder": "等待加载视频文件...",
       "debug": {
-        "title": "媒体调试信息",
-        "feature": "Feature",
-        "dtype": "类型",
-        "shape": "Shape",
         "fps": "FPS",
         "resolution": "分辨率",
         "codec": "编码",
@@ -484,10 +480,6 @@
       "title": "图像面板",
       "placeholder": "等待加载图像文件...",
       "debug": {
-        "title": "媒体调试信息",
-        "feature": "Feature",
-        "dtype": "类型",
-        "shape": "Shape",
         "fps": "FPS",
         "resolution": "分辨率",
         "codec": "编码",
diff --git a/tests/media-debug-overlay.spec.ts b/tests/media-debug-overlay.spec.ts
index ea88e2f..b73f09b 100644
--- a/tests/media-debug-overlay.spec.ts
+++ b/tests/media-debug-overlay.spec.ts
@@ -10,13 +10,12 @@ vi.mock('react-i18next', () => ({
 }));
 
 describe('MediaDebugOverlay', () => {
-  it('renders hover-only overlay classes and metadata rows', () => {
+  it('renders vertical hover-only overlay with media metadata rows', () => {
     const markup = renderToStaticMarkup(
       React.createElement(
         'div',
         { className: 'group' },
         React.createElement(MediaDebugOverlay, {
-          featureKey: 'observation.images.cam',
           translationPrefix: 'panels.video.debug',
           metadata: {
             dtype: 'video',
@@ -38,9 +37,13 @@ describe('MediaDebugOverlay', () => {
     );
 
     expect(markup).toContain('group-hover:opacity-100');
-    expect(markup).toContain('observation.images.cam');
+    expect(markup).toContain('flex-col');
     expect(markup).toContain('1280 x 720');
     expect(markup).toContain('h264');
     expect(markup).toContain('0.00s - 1.50s');
+    expect(markup).not.toContain('observation.images.cam');
+    expect(markup).not.toContain('panels.video.debug.feature');
+    expect(markup).not.toContain('panels.video.debug.dtype');
+    expect(markup).not.toContain('panels.video.debug.title');
   });
 });

From 9fdbe9315b9ce32815a1d8f65d2cf7dee3775dd0 Mon Sep 17 00:00:00 2001
From: joaner <1726541+joaner@users.noreply.github.com>
Date: Wed, 5 Aug 2026 17:03:47 +0800
Subject: [PATCH 2/2] style: apply prettier formatting to media debug overlay
 files

---
 src/react/components/panels/Common/MediaDebugOverlay.tsx | 5 ++++-
 src/react/components/panels/ImagePanel/ImagePanel.tsx    | 5 +----
 src/react/components/panels/VideoPanel/VideoPanel.tsx    | 5 +----
 3 files changed, 6 insertions(+), 9 deletions(-)

diff --git a/src/react/components/panels/Common/MediaDebugOverlay.tsx b/src/react/components/panels/Common/MediaDebugOverlay.tsx
index 9a87dd6..d8bea58 100644
--- a/src/react/components/panels/Common/MediaDebugOverlay.tsx
+++ b/src/react/components/panels/Common/MediaDebugOverlay.tsx
@@ -73,7 +73,10 @@ export const MediaDebugOverlay: React.FC<MediaDebugOverlayProps> = ({
     >
       <dl className="flex flex-col gap-1">
         {items.map((item) => (
-          <div key={item.label} className="grid grid-cols-[auto_1fr] items-baseline gap-x-3 gap-y-0">
+          <div
+            key={item.label}
+            className="grid grid-cols-[auto_1fr] items-baseline gap-x-3 gap-y-0"
+          >
             <dt className="shrink-0 text-white/55">{item.label}</dt>
             <dd className="min-w-0 break-all text-right font-mono tabular-nums text-white/95">
               {item.value}
diff --git a/src/react/components/panels/ImagePanel/ImagePanel.tsx b/src/react/components/panels/ImagePanel/ImagePanel.tsx
index 21d8a2f..d82aa47 100644
--- a/src/react/components/panels/ImagePanel/ImagePanel.tsx
+++ b/src/react/components/panels/ImagePanel/ImagePanel.tsx
@@ -278,10 +278,7 @@ export const ImagePanel: React.FC<ImagePanelProps> = ({ params }) => {
 
   return (
     <div className="group relative flex h-full w-full items-center justify-center overflow-hidden bg-black">
-      <MediaDebugOverlay
-        metadata={debugMetadata}
-        translationPrefix="panels.image.debug"
-      />
+      <MediaDebugOverlay metadata={debugMetadata} translationPrefix="panels.image.debug" />
 
       {/* canvas 始终保留，帧更新直接 drawImage，无 React 渲染 */}
       <canvas
diff --git a/src/react/components/panels/VideoPanel/VideoPanel.tsx b/src/react/components/panels/VideoPanel/VideoPanel.tsx
index 4ac7020..3891d5c 100644
--- a/src/react/components/panels/VideoPanel/VideoPanel.tsx
+++ b/src/react/components/panels/VideoPanel/VideoPanel.tsx
@@ -313,10 +313,7 @@ const VideoPanelContent: React.FC<VideoPanelProps> = ({ params }) => {
 
   return (
     <div className="group relative flex h-full w-full items-center justify-center overflow-hidden bg-black">
-      <MediaDebugOverlay
-        metadata={debugMetadata}
-        translationPrefix="panels.video.debug"
-      />
+      <MediaDebugOverlay metadata={debugMetadata} translationPrefix="panels.video.debug" />
 
       {/* Video - 始终可见，无过渡效果 */}
       <video