feat(files): an HTML file opens as the page — Files panel, Chat preview, File Explorer

Clicking an .html/.htm file now renders it instead of showing its source or downloading it: - Changes/Files panel: a whole HTML file opens on Preview (Raw = the editor). - Chat file preview: a workspace page brings its relative files along. - File Explorer: double-click / Enter opens a viewer; Download stays on its header and right-click menu. The page runs in the chat artifact's sandbox (iframe srcdoc, scripts, never allow-same-origin). Its relative stylesheets (and their url()s), scripts, images, media and icons are read by the dashboard through the existing download routes and inlined as <style>/data: URLs (lib/htmlInline.ts: never above the folder's root, ≤ 60 files / 30 MB) — the login cookie is SameSite=Strict, so a frame could not fetch them itself, and no new route serves files without it.
2026-10-28 16:45:57 +07:00
parent ca55ff8ec5
commit 7b5abc6ad9
11 changed files with 633 additions and 25 deletions
@@ -0,0 +1,98 @@
+/**
+ * @file HtmlFrame.tsx
+ * @description An HTML file rendered as a page, the one way every file view
+ * shows one (a Chat file preview, the Changes panel's Preview, the File
+ * Explorer's viewer): its relative CSS, scripts and images pulled in through
+ * the caller's guarded read (`lib/htmlInline.ts`), then run in the chat
+ * artifact's sandbox — `<iframe srcdoc>` with scripts but never the
+ * dashboard's origin (no `allow-same-origin`). Given no `html`, it reads the
+ * file itself through the same `fetchFile`.
+ * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
+ */
+
+import { useEffect, useState } from "react";
+import { FileText, Loader2 } from "lucide-react";
+import { artifactDocument, frameSandbox } from "../lib/artifactView";
+import { blobText, inlineHtml, type FetchFile } from "../lib/htmlInline";
+
+/** A page read by `fetchFile` is shown up to this size. */
+const HTML_MAX = 10 * 1024 * 1024;
+
+export function HtmlFrame({
+  path,
+  html,
+  fetchFile,
+  title,
+  className = "",
+  testId = "html-frame",
+}: {
+  /** The file's path relative to the place `fetchFile` reads from. */
+  path: string;
+  /** The page's text; read through `fetchFile` when absent. */
+  html?: string;
+  /** Reads the page's relative files; none = the page as it is. */
+  fetchFile?: FetchFile | null;
+  title: string;
+  className?: string;
+  testId?: string;
+}) {
+  const [doc, setDoc] = useState<string | null>(null);
+  const [failed, setFailed] = useState(false);
+  useEffect(() => {
+    let live = true;
+    // The page shown stays until its successor is ready (a version step, a
+    // re-read): no flash of the spinner between two renders of one file.
+    setFailed(false);
+    (async () => {
+      let text = html;
+      if (text === undefined) {
+        if (!fetchFile) throw new Error("nothing to read the page with");
+        const b = await fetchFile(path);
+        if (b.size > HTML_MAX) throw new Error("too big");
+        text = await blobText(b);
+      }
+      const page = text;
+      return fetchFile ? inlineHtml(page, path, fetchFile).catch(() => page) : page;
+    })().then(
+      (d) => live && setDoc(d),
+      () => live && setFailed(true)
+    );
+    return () => {
+      live = false;
+    };
+  }, [html, path, fetchFile]);
+  if (failed) {
+    return (
+      <div className="flex flex-1 flex-col items-center justify-center gap-2 p-6 text-center text-sm text-fg-muted">
+        <FileText className="h-8 w-8" />
+        <p className="break-all font-mono text-xs">{path}</p>
+      </div>
+    );
+  }
+  if (doc === null) {
+    return (
+      <div className="flex flex-1 items-center justify-center">
+        <Loader2 className="h-5 w-5 animate-spin text-fg-muted" />
+      </div>
+    );
+  }
+  return (
+    <iframe
+      data-testid={testId}
+      title={title}
+      srcDoc={artifactDocument("html", doc, false) ?? ""}
+      sandbox={frameSandbox("html")}
+      referrerPolicy="no-referrer"
+      className={`min-h-0 w-full flex-1 border-0 bg-white ${className}`}
+    />
+  );
+}
+
+/** A `FetchFile` over a download URL builder (a workspace's or a home's). */
+export function fetchVia(url: (relPath: string) => string): FetchFile {
+  return async (rel) => {
+    const r = await fetch(url(rel), { credentials: "same-origin" });
+    if (!r.ok) throw new Error(String(r.status));
+    return r.blob();
+  };
+}
@@ -17,7 +17,8 @@
 * (the clipboard outlives the dialog); upload files or whole folders (picker
 * or dropped from the desktop), streamed with progress, ≤ 500 MB a batch;
 * drag items onto a folder to move them (Ctrl: copy); download a file as
- * itself, anything else as one zip; a taken name asks Replace / Keep both /
+ * itself, anything else as one zip — except an HTML file, which opens as the
+ * page (`HtmlViewer`, Download on its header and right-click menu); a taken name asks Replace / Keep both /
 * Skip. Deleting forever asks first when it empties the Trash or touches
 * another user's. An admin's Trash opens on one folder per user (with its
 * item count); each folder is THAT user's Trash, to restore from or purge
@@ -90,6 +91,7 @@ import {
 } from "../../lib/api";
 import type { Lane } from "../../lib/types";
 import { useDialog } from "../../hooks/useDialog";
+import { HtmlFrame, fetchVia } from "../HtmlFrame";
 import { toast } from "../../lib/toast";
 import { confirmDialog } from "../../lib/confirm";
 import { formatBytes } from "../../lib/format";
@@ -166,6 +168,7 @@ const join = (dir: string, name: string) => (dir ? `${dir}/${name}` : name);
 const errText = (e: unknown) => (e instanceof Error ? e.message : String(e));
 const errCode = (e: unknown) => (e as { code?: string })?.code;
 const isFolder = (e: FsEntry) => e.type === "dir" || e.type === "linkdir";
+const isHtml = (e: FsEntry) => !isFolder(e) && /\.html?$/i.test(e.name);
 const ext = (name: string) => name.slice(name.lastIndexOf(".") + 1).toLowerCase();
 const IMAGE = new Set(["png", "jpg", "jpeg", "gif", "webp", "bmp", "ico"]);
 const CODE = new Set([
@@ -498,8 +501,11 @@ export function FileBrowser({
  };

  // ── Actions ─────────────────────────────────────────────────────────────
+  // An HTML page opens as itself (`HtmlViewer`); any other file downloads.
+  const [viewing, setViewing] = useState<FsEntry | null>(null);
  const openEntry = (e: FsEntry) => {
    if (isFolder(e)) go(e.path);
+    else if (isHtml(e)) setViewing(e);
    else download([e]);
  };
  const goUp = () => {
@@ -970,6 +976,14 @@ export function FileBrowser({
      onClick={() => setMenu(null)}
      data-testid="file-explorer"
    >
+      {viewing && (
+        <HtmlViewer
+          entry={viewing}
+          place={target}
+          onDownload={() => download([viewing])}
+          onClose={() => setViewing(null)}
+        />
+      )}
      {cloneParent && (
        <CloneHereDialog
          open={cloning}
@@ -1656,13 +1670,18 @@ export function FileBrowser({
          {menuItem ? (
            <>
              <MenuItem onSelect={close(() => openEntry(menuItem))}>
-                {isFolder(menuItem) ? t("fx.open") : t("fx.download")}
+                {isFolder(menuItem) || isHtml(menuItem) ? t("fx.open") : t("fx.download")}
              </MenuItem>
              {(isFolder(menuItem) || menuTargets.length > 1) && (
                <MenuItem onSelect={close(() => download(menuTargets))}>
                  {t("fx.downloadZip")}
                </MenuItem>
              )}
+              {isHtml(menuItem) && menuTargets.length === 1 && (
+                <MenuItem onSelect={close(() => download([menuItem]))}>
+                  {t("fx.download")}
+                </MenuItem>
+              )}
              <MenuSeparator />
              {!ro && (
                <MenuItem onSelect={close(() => putClip(menuTargets, true))}>
@@ -1916,6 +1935,67 @@ export function FileExplorer({
  );
 }

+/** An HTML file shown as the page, over the explorer: its relative CSS,
+ *  scripts and images read through the same download route (`HtmlFrame`).
+ *  Keys and clicks stop here — through the portal they would otherwise reach
+ *  the explorer's own shortcuts (Delete would trash the selection). */
+function HtmlViewer({
+  entry,
+  place,
+  onDownload,
+  onClose,
+}: {
+  entry: FsEntry;
+  place: FsPlace;
+  onDownload: () => void;
+  onClose: () => void;
+}) {
+  const { t } = useTranslation(["lanes"]);
+  const panelRef = useRef<HTMLDivElement>(null);
+  useDialog(true, panelRef, onClose);
+  const placeKey = JSON.stringify(place);
+  const fetchFile = useMemo(
+    () => fetchVia((p) => api.files.downloadUrl(place, p)),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [placeKey]
+  );
+  return createPortal(
+    <div
+      className="fixed inset-0 z-[70] flex items-center justify-center bg-black/60 p-3"
+      onClick={(e) => {
+        e.stopPropagation();
+        onClose();
+      }}
+      onKeyDown={(e) => e.stopPropagation()}
+      role="presentation"
+    >
+      <div
+        ref={panelRef}
+        role="dialog"
+        aria-modal="true"
+        aria-label={entry.name}
+        data-testid="fx-html-viewer"
+        className="flex h-[92vh] w-[96vw] max-w-7xl flex-col overflow-hidden rounded-xl border border-border bg-surface-1 shadow-2xl shadow-black/50"
+        onClick={(e) => e.stopPropagation()}
+      >
+        <div className="flex items-center gap-2 border-b border-border px-3 py-2">
+          <span className="min-w-0 flex-1 truncate font-mono text-[13px] text-fg-primary">
+            {entry.path}
+          </span>
+          <HeadButton label={t("fx.download")} onClick={onDownload}>
+            <Download className="h-4 w-4" />
+          </HeadButton>
+          <HeadButton label={t("fx.close")} onClick={onClose}>
+            <X className="h-4 w-4" />
+          </HeadButton>
+        </div>
+        <HtmlFrame path={entry.path} fetchFile={fetchFile} title={entry.name} />
+      </div>
+    </div>,
+    document.body
+  );
+}
+
 function HeadButton({
  label,
  onClick,
@@ -13,7 +13,9 @@
 *              side, each block with the diff's Undo / Keep while nothing
 *              is unsaved): Changes folds the unchanged lines away, Whole file
 *              shows them; any other file opens on its read-only diff; a
- *              whole markdown file can also be read rendered (Preview), and an
+ *              whole markdown file can also be read rendered (Preview), an HTML
+ *              file opens as the page itself (`HtmlFrame`, its relative CSS,
+ *              scripts and images read like downloads), and an
 *              image file is shown as the picture (`GET …/git/raw`)
 *   history  — recent commits; opening one shows that commit's diff
 *   browse   — quick-open by path, or the repo's tracked file tree (the
@@ -77,7 +79,16 @@
 * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
 */

-import { Suspense, lazy, useCallback, useEffect, useLayoutEffect, useRef, useState } from "react";
+import {
+  Suspense,
+  lazy,
+  useCallback,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
 import { useTranslation } from "react-i18next";
 import {
  ChevronDown,
@@ -127,6 +138,7 @@ import { LaneConflictView } from "./LaneConflictView";
 import { FileExplorer } from "./FileExplorer";
 import { ContextMenu, MenuItem, MenuSeparator, useContextMenu } from "../ContextMenu";
 import { MarkdownPreview, isMarkdown } from "../MarkdownPreview";
+import { HtmlFrame, fetchVia } from "../HtmlFrame";
 import { LaneGitHeader, useLaneGitFacts } from "./LaneGitHeader";
 import { changeTree, treeFiles, type ChangeTreeDir } from "../../lib/changeTree";
 import { dragProjectPath } from "../../lib/promptAttach";
@@ -185,6 +197,9 @@ function Delta({
  );
 }

+/** An HTML page, which the viewer can show rendered (`HtmlFrame`). */
+const isHtml = (p: string | null | undefined) => !!p && /\.html?$/i.test(p);
+
 /** What the viewer shows as a picture (`readImageAt`'s list on the server). */
 const IMAGE_FILE = /\.(png|jpe?g|gif|webp|avif|bmp|ico|svg)$/i;
 // CodeMirror is loaded only once a file is edited.
@@ -874,10 +889,11 @@ export function LaneChangesPanel({
  const [layout, setLayout] = useState<DiffLayout>(wide ? "split" : "unified");
  useEffect(() => setLayout(wide ? "split" : "unified"), [wide]);
  const [whole, setWhole] = useState(false);
-  // A whole markdown file shown rendered instead of as source; per file, each
-  // one opening as Settings → Appearance says (`lib/markdownView.ts`).
+  // A whole markdown or HTML file shown rendered instead of as source; per
+  // file, markdown opening as Settings → Appearance says
+  // (`lib/markdownView.ts`), an HTML page always as the page.
  const [mdPreview, setMdPreview] = useState(readMarkdownPreview);
-  useEffect(() => setMdPreview(readMarkdownPreview()), [openFile]);
+  useEffect(() => setMdPreview(isHtml(openFile) || readMarkdownPreview()), [openFile]);
  const [data, setData] = useState<LaneChanges | null>(null);
  // A folder that is not a repo (an empty new workspace, a parent of clones)
  // has no changes, review or history — only its files, which Files reads
@@ -2042,8 +2058,16 @@ export function LaneChangesPanel({
    });

  const dirty = draft !== null && draft !== text?.lines.join("\n");
-  // Rendered only where the toggle is offered: a whole markdown file.
-  const mdShown = mdPreview && whole && isMarkdown(openFile);
+  // Rendered only where the toggle is offered: a whole markdown or HTML file.
+  const mdShown = mdPreview && whole && (isMarkdown(openFile) || isHtml(openFile));
+  // An HTML page's relative CSS/scripts/images, read like a download — only
+  // from the working tree: a commit's page would get today's files.
+  const htmlFetch = useMemo(
+    () =>
+      range === "commit" ? null : fetchVia((p) => api.lanes.gitDownloadUrl(target, p)),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [range, JSON.stringify(target)]
+  );
  dirtyRef.current = dirty;
  useUnsavedGuard(dirty);
  const dirtyChangeRef = useRef(onDirtyChange);
@@ -2969,7 +2993,7 @@ export function LaneChangesPanel({
                      {t("changes.annotate")}
                    </button>
                  )}
-                  {whole && text && !dirty && isMarkdown(openFile) && (
+                  {whole && text && !dirty && (isMarkdown(openFile) || isHtml(openFile)) && (
                    <button
                      type="button"
                      data-testid="lane-file-preview"
@@ -3113,7 +3137,17 @@ export function LaneChangesPanel({
                    </Suspense>
                  )
                ) : whole ? (
-                  text && mdShown ? (
+                  text && mdShown && isHtml(openFile) ? (
+                    <HtmlFrame
+                      key={openFile}
+                      path={text.path}
+                      // A cut-off page is read whole through the download.
+                      html={text.truncated && htmlFetch ? undefined : text.lines.join("\n")}
+                      fetchFile={htmlFetch}
+                      title={text.path}
+                      className="rounded border border-border-light"
+                    />
+                  ) : text && mdShown ? (
                    <div className="min-h-0 flex-1 overflow-auto rounded border border-border-light bg-surface-0 p-4">
                      <MarkdownPreview text={text.lines.join("\n")} />
                    </div>
@@ -9,7 +9,8 @@
 * purge there, sending the item's store) and
 * shows a Trash that could not be read as an error, never as empty; nests a
 * user's workspaces under their home in the sidebar (under a fold-only row
- * when the viewer may not open that home).
+ * when the viewer may not open that home); opens an HTML file as the page
+ * instead of downloading it.
 * @author Nguyễn Ngọc Trí Vĩ <vinnt@smartgift.vn>
 */
 import { describe, it, expect, vi, beforeEach } from "vitest";
@@ -136,6 +137,38 @@ describe("FileExplorer", () => {
    expect(api.files.list).toHaveBeenLastCalledWith(1, "src");
  });

+  it("opens an HTML file as the page, its stylesheet read through the download", async () => {
+    vi.mocked(api.files.list).mockResolvedValue({
+      ...root,
+      entries: [
+        ...root.entries,
+        { name: "deck.html", path: "deck.html", type: "file", size: 9, mtime: 0 },
+      ],
+    });
+    const body: Record<string, string> = {
+      "/dl/1/deck.html": '<link rel="stylesheet" href="s.css"><p>deck</p>',
+      "/dl/1/s.css": "p{color:red}",
+    };
+    const fetchSpy = vi
+      .spyOn(globalThis, "fetch")
+      .mockImplementation(async (u) => new Response(body[String(u)] ?? "", { status: 200 }));
+    const click = vi.spyOn(HTMLAnchorElement.prototype, "click").mockImplementation(() => {});
+    open();
+    await screen.findByText("deck.html");
+    fireEvent.doubleClick(row("deck.html"));
+    const viewer = await screen.findByTestId("fx-html-viewer");
+    await waitFor(() =>
+      expect(within(viewer).getByTestId("html-frame").getAttribute("srcdoc")).toContain(
+        "<style>p{color:red}</style>"
+      )
+    );
+    expect(click).not.toHaveBeenCalled();
+    fireEvent.click(within(viewer).getByRole("button", { name: "Close" }));
+    expect(screen.queryByTestId("fx-html-viewer")).toBeNull();
+    fetchSpy.mockRestore();
+    click.mockRestore();
+  });
+
  it("makes a folder inline", async () => {
    vi.mocked(api.files.mkdir).mockResolvedValue({ path: "docs" });
    const user = userEvent.setup();
@@ -544,6 +544,34 @@ describe("LaneChangesPanel", () => {
    expect(screen.queryByTestId("lane-file-editor")).toBeNull();
  });

+  it("opens a whole HTML file as the page, its source after Raw", async () => {
+    vi.mocked(api.lanes.gitTree).mockResolvedValue({
+      available: true,
+      path: "",
+      entries: [{ name: "deck.html", path: "deck.html", dir: false, status: "??" }],
+      truncated: false,
+    });
+    vi.mocked(api.lanes.gitFile).mockResolvedValue({
+      available: true,
+      path: "deck.html",
+      rev: "work",
+      binary: false,
+      truncated: false,
+      lines: ["<p>deck</p>"],
+      sha: "c".repeat(40),
+    });
+    const user = userEvent.setup();
+    render(<LaneChangesPanel laneId={7} full />);
+    const sidebar = await screen.findByTestId("lane-changes-sidebar");
+    await user.click(await within(sidebar).findByText("deck.html"));
+    const frame = await screen.findByTestId("html-frame");
+    expect(frame.getAttribute("srcdoc")).toContain("<p>deck</p>");
+    expect(frame.getAttribute("sandbox")).not.toContain("allow-same-origin");
+    await user.click(screen.getByTestId("lane-file-preview"));
+    expect(await screen.findByTestId("lane-file-editor")).toHaveValue("<p>deck</p>");
+    expect(screen.queryByTestId("html-frame")).toBeNull();
+  });
+
  it("shows an image file as the picture, with no edit control", async () => {
    vi.mocked(api.lanes.gitTree).mockResolvedValue({
      available: true,
@@ -39,6 +39,7 @@ import { useDialog } from "../../hooks/useDialog";
 import { dragSkill } from "../../lib/promptAttach";
 import { readMarkdownPreview } from "../../lib/markdownView";
 import { MarkdownPreview } from "../MarkdownPreview";
+import { HtmlFrame, fetchVia } from "../HtmlFrame";
 import { CodeBlock } from "../conversation/CodeBlock";
 import { useTheme } from "../../hooks/useTheme";
 import { toast } from "../../lib/toast";
@@ -85,6 +86,18 @@ export const extOf = (p: string) => {
 export const displayName = (p: string) =>
  DROP_RE.test(p) ? baseName(p).replace(/^[0-9a-f]{16}-?/, "") || baseName(p) : baseName(p);

+/** A file inside the pane's folder: the git target that reads it and its path there. */
+function workspaceFile(path: string, scope: PreviewScope) {
+  const file = slashed(path);
+  const base = slashed(scope.cwd).replace(/\/+$/, "");
+  if (scope.laneId === null || !base || !file.startsWith(`${base}/`)) return null;
+  const target =
+    base === slashed(scope.laneCwd).replace(/\/+$/, "")
+      ? scope.laneId
+      : gitTarget(scope.laneId, scope.sessionId);
+  return { target, rel: file.slice(base.length + 1) };
+}
+
 type Content =
  | { kind: "loading" }
  | { kind: "image"; src: string }
@@ -121,8 +134,8 @@ function useContent(path: string, scope: PreviewScope): Content {
      };
    }
    const file = slashed(path);
-    const base = slashed(scope.cwd).replace(/\/+$/, "");
-    if (scope.laneId === null || !base || !file.startsWith(`${base}/`)) {
+    const inside = workspaceFile(path, scope);
+    if (!inside) {
      // Claude Code's own files (memory, a skill): the config pages' guarded read.
      if (/\/\.claude\//.test(file) && !IMAGE_RE.test(file)) {
        show(
@@ -147,11 +160,7 @@ function useContent(path: string, scope: PreviewScope): Content {
        live = false;
      };
    }
-    const rel = file.slice(base.length + 1);
-    const target =
-      base === slashed(scope.laneCwd).replace(/\/+$/, "")
-        ? scope.laneId
-        : gitTarget(scope.laneId, scope.sessionId);
+    const { target, rel } = inside;
    if (IMAGE_RE.test(path)) {
      setContent({ kind: "image", src: api.lanes.gitRawUrl(target, rel) });
      return;
@@ -235,9 +244,28 @@ function defaultView(path: string): View {
  return kind === "markdown" && !readMarkdownPreview() ? "code" : "preview";
 }

-function Body({ path, content, view }: { path: string; content: Content; view: View }) {
+function Body({
+  path,
+  content,
+  view,
+  scope,
+}: {
+  path: string;
+  content: Content;
+  view: View;
+  scope: PreviewScope;
+}) {
  const { t } = useTranslation("run");
  const kind = artifactKind(path);
+  // A page in the workspace brings its relative CSS, scripts and images along.
+  const inside = kind === "html" ? workspaceFile(path, scope) : null;
+  const insideTarget = inside ? JSON.stringify(inside.target) : null;
+  const page = useMemo(() => {
+    if (!inside) return null;
+    const { target, rel } = inside;
+    return { rel, fetchFile: fetchVia((p) => api.lanes.gitDownloadUrl(target, p)) };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [insideTarget, inside?.rel]);
  // An image the route refused (gone, server mode) shows like no preview.
  const [broken, setBroken] = useState<string | null>(null);
  const shown: Content =
@@ -290,6 +318,18 @@ function Body({ path, content, view }: { path: string; content: Content; view: V
    );
  }
  if (kind === "csv") return <CsvTable text={shown.text} tab={/\.tsv$/i.test(path)} />;
+  if (page && !shown.truncated) {
+    return (
+      <HtmlFrame
+        key={path}
+        path={page.rel}
+        html={shown.text}
+        fetchFile={page.fetchFile}
+        title={baseName(path)}
+        testId="artifact-frame"
+      />
+    );
+  }
  return <ArtifactFrame kind={kind} text={shown.text} title={baseName(path)} />;
 }

@@ -503,7 +543,7 @@ export function FilePreview({
          </button>
        </div>
      </header>
-      <Body path={path} content={content} view={view} />
+      <Body path={path} content={content} view={view} scope={scope} />
    </section>
  );
  // Full screen: over the whole page, where a pane's edges cannot clip it.
@@ -242,7 +242,9 @@ describe("the artifact view", () => {
      ((await screen.findByTestId("artifact-frame")) as HTMLIFrameElement).getAttribute("srcdoc")
    ).toContain("two");
    fireEvent.click(versions.querySelector("button")!);
-    expect(screen.getByTestId("artifact-frame").getAttribute("srcdoc")).toContain("<p>one</p>");
+    await vi.waitFor(() =>
+      expect(screen.getByTestId("artifact-frame").getAttribute("srcdoc")).toContain("<p>one</p>")
+    );
    cleanup();
  });