From e175f77f8d45534944c571f48d991dac7cdbb219 Mon Sep 17 00:00:00 2001
From: hasak21 <jiashuais.hi666@gmail.com>
Date: Thu, 3 Sep 2026 17:39:32 +0800
Subject: [PATCH] fix(components): preserve download dialog for HTML
 attachments (#321)

Clicking an HTML file attachment uploaded via lody_upload_files with a
workspace sourcePath previously short-circuited handlePreview into the live
file viewer or browser connection, completely skipping
SessionFilePreviewDialog. Because SessionFileCard has no separate download
button, users had no way to download the attached HTML file bytes.

Retain the in-app preview dialog for HTML attachments so that Download
and Copy actions remain accessible. Add onOpenLivePreview to
SessionFilePreviewDialog to provide a dedicated action to open the live
preview when live provenance is present, and wire canOpenHtmlFile so the
action is only shown when available.

Model: gemini-3.8-flash
---
 locales/en.json                               |   1 +
 locales/zh_CN.json                            |   1 +
 .../src/components/ai-gui/index.tsx           |   4 +
 .../ai-gui/session-file-preview-dialog.tsx    |  34 +++-
 .../ai-gui/session-files-rendering.md         |   8 +-
 .../components/src/components/ai-gui/view.tsx |  23 ++-
 .../sessions/session-chat-interface.tsx       |  20 +++
 .../session-file-preview-dialog.test.tsx      | 156 ++++++++++++++++++
 8 files changed, 234 insertions(+), 13 deletions(-)
 create mode 100644 packages/components/tests/session-file-preview-dialog.test.tsx

diff --git a/locales/en.json b/locales/en.json
index 73bc12f40..7dba4f568 100644
--- a/locales/en.json
+++ b/locales/en.json
@@ -1961,6 +1961,7 @@
   "sessions.imageStoredAsLocalFile": "Image upload is offline; added as a pending file attachment.",
   "sessions.fileDownload": "Download",
   "sessions.fileDownloadFull": "Download full file",
+  "sessions.openLivePreview": "Open live preview",
   "sessions.filePreviewRendered": "Rendered",
   "sessions.filePreviewRaw": "Raw",
   "sessions.filePreviewTruncated": "Preview shows only the start of this file. Download the full file to see everything.",
diff --git a/locales/zh_CN.json b/locales/zh_CN.json
index 8eb5cc241..c1b215ad1 100644
--- a/locales/zh_CN.json
+++ b/locales/zh_CN.json
@@ -1961,6 +1961,7 @@
   "sessions.imageStoredAsLocalFile": "图片上传处于离线状态，已作为待同步文件附件添加。",
   "sessions.fileDownload": "下载",
   "sessions.fileDownloadFull": "下载完整文件",
+  "sessions.openLivePreview": "打开实时预览",
   "sessions.filePreviewRendered": "渲染",
   "sessions.filePreviewRaw": "原文",
   "sessions.filePreviewTruncated": "预览仅显示文件开头部分。下载完整文件以查看全部内容。",
diff --git a/packages/components/src/components/ai-gui/index.tsx b/packages/components/src/components/ai-gui/index.tsx
index 1cdf37e9c..2bf512c52 100644
--- a/packages/components/src/components/ai-gui/index.tsx
+++ b/packages/components/src/components/ai-gui/index.tsx
@@ -89,6 +89,8 @@ export interface SessionChatStreamProps {
   onFilePathClick?: (filePath: string) => void;
   /** Routes HTML attachment clicks to a live file or Browser surface. */
   onOpenHtmlFile?: (file: SessionFilePayload) => boolean;
+  /** Whether an HTML attachment can be routed to a live file or Browser surface. */
+  canOpenHtmlFile?: (file: SessionFilePayload) => boolean;
   messageFileDiffEntriesByTurn?: MessageFileDiffEntriesByTurn;
   assistantActions?: AssistantMessageAction[];
   assistantActionsMessageId?: string | null;
@@ -171,6 +173,7 @@ const SessionChatStreamImpl = forwardRef<SessionChatStreamHandle, SessionChatStr
       onFileDiffClick,
       onFilePathClick,
       onOpenHtmlFile,
+      canOpenHtmlFile,
       messageFileDiffEntriesByTurn,
       assistantActions,
       assistantActionsMessageId,
@@ -279,6 +282,7 @@ const SessionChatStreamImpl = forwardRef<SessionChatStreamHandle, SessionChatStr
         onFileDiffClick={hasFileDiffClick ? stableOnFileDiffClick : undefined}
         onFilePathClick={hasFilePathClick ? stableOnFilePathClick : undefined}
         onOpenHtmlFile={onOpenHtmlFile}
+        canOpenHtmlFile={canOpenHtmlFile}
         lastAssistantMessageId={lastAssistantMessageId}
         lastCompletedAssistantMessageId={lastCompletedAssistantMessageId}
         messageFileDiffEntriesByTurn={messageFileDiffEntriesByTurn}
diff --git a/packages/components/src/components/ai-gui/session-file-preview-dialog.tsx b/packages/components/src/components/ai-gui/session-file-preview-dialog.tsx
index 945649250..3b4c0c287 100644
--- a/packages/components/src/components/ai-gui/session-file-preview-dialog.tsx
+++ b/packages/components/src/components/ai-gui/session-file-preview-dialog.tsx
@@ -1,7 +1,7 @@
 import { useEffect, useMemo, useState } from 'react';
 import { useTranslation } from 'react-i18next';
 import { toast } from 'sonner';
-import { Check, Copy, Download, FileWarning, Loader2, X } from 'lucide-react';
+import { Check, Copy, Download, ExternalLink, FileWarning, Loader2, X } from 'lucide-react';
 import type { SessionFilePayload } from '@lody/shared';
 import { Dialog, DialogClose, DialogContentWithoutClose, DialogTitle } from '@/ui/dialog';
 import { Button } from '@/ui/button';
@@ -24,6 +24,7 @@ export type SessionFilePreviewPanelProps = {
   status: SessionFilePreviewStatus;
   onDownload: (file: SessionFilePayload) => void;
   isDownloading?: boolean;
+  onOpenLivePreview?: (file: SessionFilePayload) => void;
 };
 
 /**
@@ -38,6 +39,7 @@ export function SessionFilePreviewPanel({
   status,
   onDownload,
   isDownloading = false,
+  onOpenLivePreview,
 }: SessionFilePreviewPanelProps) {
   const { t } = useTranslation();
   const markdown = isMarkdownFile(file.fileName);
@@ -123,7 +125,20 @@ export function SessionFilePreviewPanel({
               <Download className="size-4" />
             )}
           </Button>
-          {/* Divider separates content actions (copy/download) from the window
+          {onOpenLivePreview ? (
+            <Button
+              type="button"
+              variant="ghost"
+              size="icon"
+              className="size-7 text-muted-foreground hover:text-foreground"
+              onClick={() => onOpenLivePreview(file)}
+              aria-label={t('sessions.openLivePreview', 'Open live preview')}
+              title={t('sessions.openLivePreview', 'Open live preview')}
+            >
+              <ExternalLink className="size-4" />
+            </Button>
+          ) : null}
+          {/* Divider separates content actions (copy/download/live-preview) from the window
               action (close), and the close sits inline in the same row instead
               of floating in the corner over the buttons. */}
           <span className="mx-0.5 h-4 w-px bg-border" aria-hidden="true" />
@@ -204,14 +219,27 @@ export type SessionFilePreviewDialogProps = SessionFilePreviewPanelProps & {
 export function SessionFilePreviewDialog({
   open,
   onOpenChange,
+  onOpenLivePreview,
   ...panelProps
 }: SessionFilePreviewDialogProps) {
   // Re-key the panel per file so the rendered/raw toggle resets between files.
   const panelKey = useMemo(() => panelProps.file.fileId, [panelProps.file.fileId]);
+  const handleOpenLivePreview = useMemo(() => {
+    if (!onOpenLivePreview) return undefined;
+    return (file: SessionFilePayload) => {
+      onOpenChange(false);
+      onOpenLivePreview(file);
+    };
+  }, [onOpenChange, onOpenLivePreview]);
+
   return (
     <Dialog open={open} onOpenChange={onOpenChange}>
       <DialogContentWithoutClose className="w-[calc(100vw-2rem)] max-w-3xl">
-        <SessionFilePreviewPanel key={panelKey} {...panelProps} />
+        <SessionFilePreviewPanel
+          key={panelKey}
+          {...panelProps}
+          onOpenLivePreview={handleOpenLivePreview}
+        />
       </DialogContentWithoutClose>
     </Dialog>
   );
diff --git a/packages/components/src/components/ai-gui/session-files-rendering.md b/packages/components/src/components/ai-gui/session-files-rendering.md
index 9e2f7e0bd..45cffcea4 100644
--- a/packages/components/src/components/ai-gui/session-files-rendering.md
+++ b/packages/components/src/components/ai-gui/session-files-rendering.md
@@ -14,10 +14,10 @@ File attachments use `file` blocks; the product contract is in
   Upload/download/preview helpers: `@/lib/session-file-{upload,download,presentation}.ts`.
 - Agent-uploaded blocks may carry a workspace-relative `sourcePath` proven by the CLI's
   containment check. It is provenance for reopening the live file, never a download path.
-  HTML clicks use it only for same-machine Sessions and enter the existing rendered file
-  preview. Remote HTML clicks reuse an active Browser connection; an available reported
-  candidate requires an explicit confirmation before creating its tunnel. Missing provenance
-  or preview state falls back to the ordinary attachment preview instead of guessing.
+  HTML clicks open the in-app preview dialog (retaining Download and Copy); when live provenance
+  is present, the dialog additionally offers an action to open the rendered file preview (local)
+  or Browser connection (remote). Missing provenance or preview state falls back to the ordinary
+  attachment preview without the live action.
 - `@/lib/session-file-download.ts` `downloadSessionFile` branches by platform
   (`isNativeAppShell()`): web/electron uses blob + `<a download>`; native mobile routes to
   `@/lib/session-file-native-save.ts` (Capacitor Filesystem chunked base64 write to the
diff --git a/packages/components/src/components/ai-gui/view.tsx b/packages/components/src/components/ai-gui/view.tsx
index f1e8a4763..83ecd670a 100644
--- a/packages/components/src/components/ai-gui/view.tsx
+++ b/packages/components/src/components/ai-gui/view.tsx
@@ -429,6 +429,8 @@ export interface SessionChatStreamViewProps {
   onFilePathClick?: (filePath: string) => void;
   /** Returns true when an HTML attachment click was routed to a richer surface. */
   onOpenHtmlFile?: (file: SessionFilePayload) => boolean;
+  /** Returns true when an HTML attachment can be routed to a richer surface. */
+  canOpenHtmlFile?: (file: SessionFilePayload) => boolean;
   lastAssistantMessageId?: string | null;
   lastCompletedAssistantMessageId?: string | null;
   messageFileDiffEntriesByTurn?: MessageFileDiffEntriesByTurn;
@@ -455,6 +457,7 @@ export interface SessionChatStreamViewProps {
 const SessionChatActionContext = createContext<{
   sendMessage?: (message: ClientToServer) => void;
   openHtmlFile?: (file: SessionFilePayload) => boolean;
+  canOpenHtmlFile?: (file: SessionFilePayload) => boolean;
 }>({});
 const SessionImagePreviewContext = createContext<{
   openImagePreview: (imageKey: string) => void;
@@ -1178,6 +1181,7 @@ export const SessionChatStreamView = forwardRef<
       onFileDiffClick,
       onFilePathClick,
       onOpenHtmlFile,
+      canOpenHtmlFile,
       lastAssistantMessageId = null,
       lastCompletedAssistantMessageId = null,
       messageFileDiffEntriesByTurn,
@@ -1626,8 +1630,9 @@ export const SessionChatStreamView = forwardRef<
       () => ({
         ...(sendMessage ? { sendMessage } : {}),
         ...(onOpenHtmlFile ? { openHtmlFile: onOpenHtmlFile } : {}),
+        ...(canOpenHtmlFile ? { canOpenHtmlFile } : {}),
       }),
-      [onOpenHtmlFile, sendMessage]
+      [canOpenHtmlFile, onOpenHtmlFile, sendMessage]
     );
     const hasOnlyEmptyItem = items.length === 1 && items[0]?.type === 'empty';
 
@@ -4789,7 +4794,7 @@ export const SessionFileGroup = ({
   const { t } = useTranslation();
   const workspaceId = useAtomValue(currentWorkspaceIdAtom) as WorkspaceId | null;
   const authToken = useAtomValue(authTokenAtom);
-  const { openHtmlFile } = useContext(SessionChatActionContext);
+  const { openHtmlFile, canOpenHtmlFile } = useContext(SessionChatActionContext);
   const [previewFile, setPreviewFile] = useState<SessionFilePayload | null>(null);
   const [previewStatus, setPreviewStatus] = useState<SessionFilePreviewStatus>({ kind: 'loading' });
   const [downloadingId, setDownloadingId] = useState<string | null>(null);
@@ -4817,9 +4822,6 @@ export const SessionFileGroup = ({
 
   const handlePreview = useCallback(
     (file: SessionFilePayload) => {
-      if (isHtmlSessionFile(file) && openHtmlFile?.(file)) {
-        return;
-      }
       setPreviewFile(file);
       setPreviewStatus({ kind: 'loading' });
       if (!workspaceId || !authToken) {
@@ -4856,7 +4858,7 @@ export const SessionFileGroup = ({
           });
         });
     },
-    [authToken, openHtmlFile, sessionId, t, workspaceId]
+    [authToken, sessionId, t, workspaceId]
   );
 
   // The send path caps at 8 files/message, but a block list synced from another
@@ -4896,6 +4898,15 @@ export const SessionFileGroup = ({
           status={previewStatus}
           onDownload={handleDownload}
           isDownloading={downloadingId === previewFile.fileId}
+          onOpenLivePreview={
+            isHtmlSessionFile(previewFile) &&
+            openHtmlFile &&
+            (canOpenHtmlFile ? canOpenHtmlFile(previewFile) : true)
+              ? (file) => {
+                  openHtmlFile(file);
+                }
+              : undefined
+          }
         />
       ) : null}
     </>
diff --git a/packages/components/src/components/sessions/session-chat-interface.tsx b/packages/components/src/components/sessions/session-chat-interface.tsx
index 7029fcbb4..1b9635a26 100644
--- a/packages/components/src/components/sessions/session-chat-interface.tsx
+++ b/packages/components/src/components/sessions/session-chat-interface.tsx
@@ -5337,6 +5337,25 @@ export const SessionChatInterface = memo(
       }
       return false;
     });
+    const canOpenHtmlAttachment = useStableCallback((file: SessionFilePayload): boolean => {
+      const action = resolveSessionHtmlAttachmentAction({
+        isLocalSession,
+        sourcePath: file.sourcePath,
+        connectionStatus: session.previewConnection?.status,
+        candidateStatus: session.previewCandidate?.status,
+      });
+      switch (action.kind) {
+        case 'open-local-file':
+          return !!onOpenHtmlFile;
+        case 'open-existing-browser':
+          return !!onOpenExistingBrowser;
+        case 'confirm-reported-port':
+          return !!onOpenBrowser;
+        case 'fallback':
+          return false;
+      }
+      return false;
+    });
     const openInIdeTarget = useMemo(
       () =>
         resolveSessionOpenInIdePathTarget({
@@ -5846,6 +5865,7 @@ export const SessionChatInterface = memo(
                           onFileDiffClick={onFileDiffClick}
                           onFilePathClick={onFilePathClick ? handleFilePathClick : undefined}
                           onOpenHtmlFile={handleOpenHtmlAttachment}
+                          canOpenHtmlFile={canOpenHtmlAttachment}
                           messageFileDiffEntriesByTurn={messageFileDiffEntriesByTurn}
                           assistantActions={assistantQuickActions}
                           assistantActionsMessageId={latestCompletedProposedPlan?.entryId}
diff --git a/packages/components/tests/session-file-preview-dialog.test.tsx b/packages/components/tests/session-file-preview-dialog.test.tsx
new file mode 100644
index 000000000..a23815f7e
--- /dev/null
+++ b/packages/components/tests/session-file-preview-dialog.test.tsx
@@ -0,0 +1,156 @@
+// @vitest-environment jsdom
+
+import { act, createElement } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { SessionFilePayload } from '@lody/shared';
+import { Dialog, DialogContentWithoutClose } from '../src/ui/dialog';
+import {
+  SessionFilePreviewPanel,
+  SessionFilePreviewDialog,
+} from '../src/components/ai-gui/session-file-preview-dialog';
+
+vi.mock('react-i18next', () => ({
+  useTranslation: () => ({
+    t: (_key: string, fallback?: string) => fallback ?? _key,
+  }),
+}));
+
+(
+  globalThis as typeof globalThis & { IS_REACT_ACT_ENVIRONMENT?: boolean }
+).IS_REACT_ACT_ENVIRONMENT = true;
+
+const createTestFile = (overrides: Partial<SessionFilePayload> = {}): SessionFilePayload => ({
+  type: 'file',
+  fileId: 'file-html-1',
+  fileName: 'report.html',
+  mimeType: 'text/html',
+  sizeBytes: 1024,
+  sha256: 'a'.repeat(64),
+  textPreview: true,
+  transport: 'r2',
+  uploadedAt: 1700000000000,
+  ...overrides,
+});
+
+describe('SessionFilePreviewPanel & SessionFilePreviewDialog', () => {
+  let root: Root | undefined;
+  let container: HTMLDivElement | undefined;
+
+  beforeEach(() => {
+    container = document.createElement('div');
+    document.body.appendChild(container);
+    root = createRoot(container);
+  });
+
+  afterEach(async () => {
+    if (root) await act(async () => void root?.unmount());
+    root = undefined;
+    container?.remove();
+    container = undefined;
+    vi.restoreAllMocks();
+  });
+
+  it('renders download and copy buttons, and clicking download calls onDownload', async () => {
+    const onDownload = vi.fn();
+    const testFile = createTestFile();
+
+    await act(async () => {
+      root?.render(
+        createElement(
+          Dialog,
+          { open: true },
+          createElement(
+            DialogContentWithoutClose,
+            null,
+            createElement(SessionFilePreviewPanel, {
+              file: testFile,
+              status: { kind: 'loaded', text: '<h1>Hello</h1>', truncated: false },
+              onDownload,
+            })
+          )
+        )
+      );
+    });
+
+    const downloadButton = document.body.querySelector('button[aria-label="Download"]');
+    expect(downloadButton).toBeTruthy();
+
+    const copyButton = document.body.querySelector('button[aria-label="Copy"]');
+    expect(copyButton).toBeTruthy();
+
+    // Live preview button should not be present when onOpenLivePreview is omitted
+    const livePreviewButton = document.body.querySelector('button[aria-label="Open live preview"]');
+    expect(livePreviewButton).toBeNull();
+
+    await act(async () => {
+      downloadButton?.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    });
+
+    expect(onDownload).toHaveBeenCalledWith(testFile);
+  });
+
+  it('renders live preview button when onOpenLivePreview is provided and calls it on click', async () => {
+    const onDownload = vi.fn();
+    const onOpenLivePreview = vi.fn();
+    const testFile = createTestFile({ sourcePath: 'demo.html' });
+
+    await act(async () => {
+      root?.render(
+        createElement(
+          Dialog,
+          { open: true },
+          createElement(
+            DialogContentWithoutClose,
+            null,
+            createElement(SessionFilePreviewPanel, {
+              file: testFile,
+              status: { kind: 'loaded', text: '<h1>Hello</h1>', truncated: false },
+              onDownload,
+              onOpenLivePreview,
+            })
+          )
+        )
+      );
+    });
+
+    const livePreviewButton = document.body.querySelector('button[aria-label="Open live preview"]');
+    expect(livePreviewButton).toBeTruthy();
+
+    await act(async () => {
+      livePreviewButton?.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    });
+
+    expect(onOpenLivePreview).toHaveBeenCalledWith(testFile);
+  });
+
+  it('closes dialog and calls onOpenLivePreview when live preview is triggered in SessionFilePreviewDialog', async () => {
+    const onDownload = vi.fn();
+    const onOpenLivePreview = vi.fn();
+    const onOpenChange = vi.fn();
+    const testFile = createTestFile({ sourcePath: 'demo.html' });
+
+    await act(async () => {
+      root?.render(
+        createElement(SessionFilePreviewDialog, {
+          open: true,
+          onOpenChange,
+          file: testFile,
+          status: { kind: 'loaded', text: '<h1>Hello</h1>', truncated: false },
+          onDownload,
+          onOpenLivePreview,
+        })
+      );
+    });
+
+    const livePreviewButton = document.body.querySelector('button[aria-label="Open live preview"]');
+    expect(livePreviewButton).toBeTruthy();
+
+    await act(async () => {
+      livePreviewButton?.dispatchEvent(new MouseEvent('click', { bubbles: true }));
+    });
+
+    expect(onOpenChange).toHaveBeenCalledWith(false);
+    expect(onOpenLivePreview).toHaveBeenCalledWith(testFile);
+  });
+});