dsh-file-activity 0.5.3 → 0.5.5

package/CHANGELOG.md

@@ -2,6 +2,27 @@
 
 本文件记录 dsh-file-activity 的所有版本变更。格式遵循 [Keep a Changelog](https://keepachangelog.com/zh-CN/1.1.0/)，版本号遵循 [语义化版本](https://semver.org/lang/zh-CN/)。
 
+## [0.5.5] - 2026-09-02
+
+### 变更
+
+- fix(scripts): #72 插件依赖未随安装自动安装（dsh-shared 未发布 npm） (#96)
+- fix(file-activity): 浮窗预览失焦自动关闭（issue #76） (#95)
+- fix(file-activity): #72 补充 dsh-better-sidebar 级联安装——dependencies 声明 + 缺失提示
+- style: prettier 全量格式修复（CI 格式门禁）
+
+## [Unreleased]
+
+### 变更
+
+- fix(ui): 浮窗预览失焦自动关闭——点击外部任意处/切换页签即关，预览失败 2.5s 自动关闭或点击任意处关闭，头部「点击外部关闭」提示（issue #76）
+
+## [0.5.4] - 2026-09-01
+
+### 变更
+
+- fix(file-activity): 浮窗预览优雅降级与工作区外文本读取（issue #68）
+
 ## [0.5.3] - 2026-09-01
 
 ### 变更

package/README.md

@@ -36,9 +36,7 @@
 
 ## 安装
 
-> 💡 **npm 安装（普通用户推荐）**：`dsh plugin --profile web add dsh-file-activity`——无需克隆本仓库；以下 link 方式供本仓库开发者使用。
-
-前置：已安装 `dsh-better-sidebar`（v0.12+，推荐 v0.14）。
+> 💡 **npm 安装（普通用户推荐）**：`dsh plugin --profile web add dsh-file-activity`——无需克隆本仓库；依赖自动级联安装：`dsh-better-sidebar`（宿主，提供侧边栏扩展点）与 `dsh-shared`（server 端共享工具包）均声明为 dependencies，安装时自动安装并加入 profile bundles，无需手动单独处理。
 
 ```sh
 # 方式一：dsh plugin（推荐）

package/lib/client.js

@@ -86,7 +86,12 @@ const strings = {
   loading: () => (isZh() ? '加载中…' : 'Loading…'),
   previewUnsupported: () => (isZh() ? '该文件类型暂不支持预览' : 'This file type cannot be previewed yet'),
   previewFailed: () => (isZh() ? '预览加载失败' : 'Preview failed to load'),
+  fileMissing: () => (isZh() ? '文件不存在或已被删除' : 'This file no longer exists'),
+  fileOutside: () =>
+    isZh() ? '文件位于工作区外，暂无法读取内容' : 'The file is outside the workspace and cannot be read',
   downloadToView: () => (isZh() ? '下载查看' : 'download to view'),
+  clickOutsideToClose: () => (isZh() ? '点击外部关闭' : 'Click outside to close'),
+  autoCloseHint: () => (isZh() ? '预览失败，即将自动关闭' : 'Preview failed — closing automatically'),
 }
 
     // ── path / time formatting helpers ────────────────────────────────────
@@ -266,6 +271,11 @@ function mediaUrlOf(sessionId, path) {
   return `/file-activity/file?${new URLSearchParams({ sessionId, path })}`
 }
 
+/** Plugin text route URL (`as=text`): fs.read-shaped JSON for recorded text. */
+function textUrlOf(sessionId, path) {
+  return `/file-activity/file?${new URLSearchParams({ sessionId, path, as: 'text' })}`
+}
+
     // ── fetch interception: sidebar file operations ───────────────────────
 function methodOf(init) {
   return (init?.method ?? 'GET').toUpperCase()
@@ -768,6 +778,7 @@ const STYLES = `
   display:flex; flex-direction:column; overflow:hidden; }
 .dfa-fp-head { display:flex; align-items:center; gap:6px; padding:6px 8px; border-bottom:1px solid var(--dsw-alias-border-l1); flex:none; }
 .dfa-fp-title { flex:1; min-width:0; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; font:var(--dsw-font-s-strong-14); color:var(--dsw-alias-label-primary); }
+.dfa-fp-hint { flex:none; font:var(--dsw-font-xxs-12); color:var(--dsw-alias-label-tertiary); opacity:0.8; }
 .dfa-fp-actions { display:flex; align-items:center; gap:2px; flex:none; }
 .dfa-fp-body { flex:1; overflow:auto; padding:10px 12px; min-height:0; }
 .dfa-fp-note { color:var(--dsw-alias-label-tertiary); font:var(--dsw-font-xxs-12); }
@@ -1116,6 +1127,11 @@ function FileActivityView({ ctx, store, scope, visible, dataStore }) {
   useEffect(() => {
     dataStore.set({ preview: null })
   }, [sessionId, dataStore])
+  // Switching tabs hides this view: close any floating preview so it never
+  // lingers over the main UI (issue #76).
+  useEffect(() => {
+    closePreviewOnHidden(visible, dataStore)
+  }, [visible, dataStore])
   const toggleDir = (path) => setCollapsedDirs((prev) => toggleInSet(prev, path))
   const openPreview = (path) => dataStore.set({ preview: { abs: path, name: basenameOf(path) } })
   const closePreview = () => dataStore.set({ preview: null })
@@ -1154,14 +1170,54 @@ function isFsReadOk(json) {
   return json !== null && typeof json === 'object' && json.ok === true && typeof json.value?.content === 'string'
 }
 
-/** Error load state from an fs.read API response (or a generic message). */
+/** Error load state from an fs.read API response (or a generic message).
+ *  Raw system errors are translated to friendly, locale-aware messages
+ *  (issue #68): deleted files and workspace-fenced paths must never surface
+ *  ENOENT / "is outside workspace" verbatim. */
 function fsReadError(json, viewer) {
-  return { status: 'error', viewer, message: json?.error?.message ?? strings.previewFailed() }
+  const raw = json?.error?.message ?? ''
+  let message
+  if (raw === '') message = strings.previewFailed()
+  else if (/ENOENT|no such file|does not exist|cannot resolve/i.test(raw)) message = strings.fileMissing()
+  else if (/outside workspace/i.test(raw)) message = strings.fileOutside()
+  else message = raw
+  return { status: 'error', viewer, message }
+}
+
+/** Milliseconds after which an error-state preview closes itself (issue #76):
+ *  a shell that failed to load any content is useless, so it must not linger
+ *  over the main UI until the user finds the × button. */
+const AUTO_CLOSE_MS = 2500
+
+/** Whether a pointerdown target lies inside the floating window. The window
+ *  surface carries the `.dfa-fp` class; anything else counts as "outside"
+ *  and dismisses the preview (issue #76 — click anywhere outside closes). */
+function isInsideFloating(target) {
+  if (!target || typeof target.closest !== 'function') return false
+  return target.closest('.dfa-fp') !== null
+}
+
+/** Click behavior for the window surface: in the error state ANY click
+ *  closes the shell (there is no content to interact with), otherwise the
+ *  click is swallowed so the viewer's own interactions keep working. */
+function previewClickAction(load, event) {
+  if (load.status === 'error') return 'close'
+  if (event && event.stopPropagation) event.stopPropagation()
+  return 'stop'
+}
+
+/** Close the floating preview when the tab goes hidden (switching tabs /
+ *  operating the main UI), so it never lingers over the interface. */
+function closePreviewOnHidden(visible, dataStore) {
+  if (!visible) dataStore.set({ preview: null })
 }
 
 /**
  * Load fsRead content through the sidebar API and resolve the viewer's
- * load state (ready with text, or error with the API message).
+ * load state (ready with text, or error with the API message). When the
+ * sidebar refuses a recorded path (its workspace fence, e.g. agent-read
+ * files under ~/.dsh), fall back to the plugin's own text route, which
+ * authorizes exactly the paths this session recorded (issue #68).
  */
 async function loadFsReadContent(viewer, path, scope, sessionId) {
   const target = resolvePath(path, scope?.cwd ?? '')
@@ -1172,9 +1228,22 @@ async function loadFsReadContent(viewer, path, scope, sessionId) {
   })
   const json = await response.json()
   if (isFsReadOk(json)) return { status: 'ready', viewer, content: json.value.content }
+  // The sidebar refused — try OUR recorded-path text route before giving up.
+  const textJson = await fetchTextContent(sessionId, path)
+  if (isFsReadOk(textJson)) return { status: 'ready', viewer, content: textJson.value.content }
   return fsReadError(json, viewer)
 }
 
+/** Plugin text route (fs.read-shaped JSON), or null on any failure. */
+async function fetchTextContent(sessionId, path) {
+  try {
+    const response = await fetch(textUrlOf(sessionId, path))
+    return await response.json()
+  } catch {
+    return null
+  }
+}
+
 /**
  * Fetch the bytes the viewer's fetchStrategy needs (fsRead text /
  * mediaUrl / customData) and resolve its load state.
@@ -1242,6 +1311,7 @@ function renderPreviewBody(load, ctx, store, scope, path, title, sessionId) {
       load.message
         ? createElement('div', { style: { marginTop: '6px', fontSize: '11px', opacity: 0.85 } }, load.message)
         : null,
+      createElement('div', { style: { marginTop: '6px', fontSize: '11px', opacity: 0.7 } }, strings.autoCloseHint()),
     )
   }
   if (load.viewer.id === 'pdf') {
@@ -1277,15 +1347,25 @@ function renderPreviewBody(load, ctx, store, scope, path, title, sessionId) {
  * built-in viewer that fetches its own URL internally (it ignores the
  * `mediaUrl` prop), so it gets a small iframe preview instead.
  */
-function FloatingPreview({ ctx, store, scope, preview, onClose }) {
-  const sessionId = scope?.sessionId ?? ''
-  const path = preview.abs
-  const title = preview.name
-  const service = ctx.betterSidebar
-  const load = usePreviewLoader(service, path, sessionId, scope)
+/**
+ * Dismissal affordances (issue #76 — the preview must never linger):
+ * 1. pointerdown anywhere OUTSIDE the window closes it (capture phase, so
+ *    it fires even if another element sits above the scrim);
+ * 2. the scrim's own onClick (kept as a fallback);
+ * 3. Escape;
+ * 4. the × button;
+ * 5. an error state closes itself after AUTO_CLOSE_MS (no content to show).
+ */
+function usePreviewDismiss(load, onClose) {
+  useEffect(() => {
+    if (typeof document === 'undefined' || typeof document.addEventListener !== 'function') return () => {}
+    const handler = (event) => {
+      if (!isInsideFloating(event?.target)) onClose()
+    }
+    document.addEventListener('pointerdown', handler, true)
+    return () => document.removeEventListener('pointerdown', handler, true)
+  }, [onClose])
 
-  // Clicking outside is the primary dismiss (the overlay's onClick);
-  // Escape is a keyboard affordance. Both call onClose.
   useEffect(() => {
     if (typeof document === 'undefined' || typeof document.addEventListener !== 'function') return () => {}
     const handler = (event) => {
@@ -1295,6 +1375,16 @@ function FloatingPreview({ ctx, store, scope, preview, onClose }) {
     return () => document.removeEventListener('keydown', handler)
   }, [onClose])
 
+  useEffect(() => {
+    if (load.status !== 'error') return undefined
+    if (typeof window === 'undefined' || typeof window.setTimeout !== 'function') return undefined
+    const timer = window.setTimeout(onClose, AUTO_CLOSE_MS)
+    return () => window.clearTimeout(timer)
+  }, [load.status, onClose])
+}
+
+/** The floating window element: head (title + hint + close) and body. */
+function renderFloatingWindow(load, ctx, store, scope, path, title, sessionId, onClose) {
   return createElement(
     'div',
     { className: 'dfa-fp-overlay', onClick: onClose },
@@ -1303,13 +1393,14 @@ function FloatingPreview({ ctx, store, scope, preview, onClose }) {
       {
         className: 'dfa-fp',
         onClick: (event) => {
-          if (event && event.stopPropagation) event.stopPropagation()
+          if (previewClickAction(load, event) === 'close') onClose()
         },
       },
       createElement(
         'div',
         { className: 'dfa-fp-head' },
         createElement('span', { className: 'dfa-fp-title' }, title),
+        createElement('span', { className: 'dfa-fp-hint' }, strings.clickOutsideToClose()),
         createElement(
           'span',
           { className: 'dfa-fp-actions' },
@@ -1334,6 +1425,16 @@ function FloatingPreview({ ctx, store, scope, preview, onClose }) {
   )
 }
 
+function FloatingPreview({ ctx, store, scope, preview, onClose }) {
+  const sessionId = scope?.sessionId ?? ''
+  const path = preview.abs
+  const title = preview.name
+  const service = ctx.betterSidebar
+  const load = usePreviewLoader(service, path, sessionId, scope)
+  usePreviewDismiss(load, onClose)
+  return renderFloatingWindow(load, ctx, store, scope, path, title, sessionId, onClose)
+}
+
 /**
  * Lightweight PDF preview. better-sidebar's built-in PdfView fetches
  * `/sidebar/file` internally (it ignores any injected `mediaUrl` prop),
@@ -1434,7 +1535,17 @@ exports.apply = function apply(ctx) {
   // Stylesheet first, unconditionally (HMR pitfall — see injectStyles).
   injectStyles(ctx)
   const service = ctx.betterSidebar
-  if (service === undefined) return
+  if (service === undefined) {
+    // 依赖缺失提示（issue #72 同类问题）：dsh-file-activity 的 client 端
+    // 依赖 dsh-better-sidebar 提供侧边栏扩展点，未安装时静默返回会让用户
+    // 以为插件坏了——明确提示安装方式。
+    if (typeof console !== 'undefined' && typeof console.warn === 'function') {
+      console.warn(
+        '[dsh-file-activity] dsh-better-sidebar 未安装：文件活动页签无法挂载。请安装宿主插件：dsh plugin --profile web add dsh-better-sidebar dsh-file-activity',
+      )
+    }
+    return
+  }
 
   // Per-session data store: { bySession: { [sessionId]: { recent, counts, loading } }, preview }
   // Each conversation reads/writes only its own bucket, so switching
@@ -1450,6 +1561,21 @@ exports.apply = function apply(ctx) {
   ctx.effect(() => installAutoOpen(ctx, TAB_ID), 'dsh-file-activity: auto-open')
 }
 
+// Internal functions exposed for the render-path test suite only; inert in
+// the browser bundle (plain properties on the exports object).
+exports.__test = {
+  loadFsReadContent,
+  fsReadError,
+  fetchTextContent,
+  textUrlOf,
+  strings,
+  renderPreviewBody,
+  previewClickAction,
+  isInsideFloating,
+  closePreviewOnHidden,
+  AUTO_CLOSE_MS,
+}
+
 
     return module.exports
   },

package/lib/media-route.js

@@ -1,12 +1,17 @@
 /**
- * /file-activity/file media route: serves recorded file bytes (images / PDFs)
- * for the floating preview. The sidebar's own /sidebar/file route refuses
- * every path outside the session working directory (isWithin(cwd, …)), but
- * file activity records files the agent touched ANYWHERE — /tmp scratch files,
- * sibling repos, … — so images/PDFs outside the workspace resolve to a broken
- * <img>. This route serves the bytes with the same trust fence, swapping the
- * "inside the session cwd" boundary for "paths this session actually
- * recorded".
+ * /file-activity/file media route: serves recorded file bytes (images / PDFs
+ * AND, with `as=text`, text content) for the floating preview. The sidebar's
+ * own /sidebar/file route refuses every path outside the session working
+ * directory (isWithin(cwd, …)), but file activity records files the agent
+ * touched ANYWHERE — /tmp scratch files, sibling repos, … — so images/PDFs
+ * outside the workspace resolve to a broken <img>. This route serves the
+ * bytes with the same trust fence, swapping the "inside the session cwd"
+ * boundary for "paths this session actually recorded".
+ *
+ * `as=text` (issue #68): the floating preview's text path first asks the
+ * sidebar fs.read API; when the sidebar refuses a recorded file (workspace
+ * fence), the client falls back to this route and receives an fs.read-shaped
+ * JSON payload ({ ok, value: { content } }) so the viewer mounts unchanged.
  */
 import { readFile, stat } from 'node:fs/promises'
 import { basename, isAbsolute, join } from 'node:path'
@@ -17,6 +22,9 @@ import { isRecordedPath } from './state.js'
 /** Cap for the plugin's own media route (bytes): images / PDFs only. */
 const MEDIA_LIMIT = 64 * 1024 * 1024
 
+/** Cap for `as=text` payloads (characters): text previews, not archives. */
+const TEXT_LIMIT = 2 * 1024 * 1024
+
 /** Content types served by /file-activity/file (mirrors the sidebar's set). */
 const MEDIA_TYPES = {
   '.png': 'image/png',
@@ -55,14 +63,7 @@ export function createMediaHandler({ ctx, store, fence }) {
       return
     }
     try {
-      const url = new URL(request.url ?? '/', 'http://dsh.internal')
-      const sessionId = url.searchParams.get('sessionId')
-      const raw = url.searchParams.get('path')
-      assertMediaParams(sessionId, raw)
-      if (!isRecordedPath(store.state, sessionId, raw))
-        throw mediaError(403, "path is not in this session's file activity")
-      const abs = isAbsolute(raw) ? raw : join(sessionCwdOf(ctx, sessionId), raw)
-      await serveMedia(response, abs, url)
+      await serveRecordedFile(request, response, ctx, store)
     } catch (error) {
       const status = typeof error?.status === 'number' ? error.status : 400
       writeJson(response, status, {
@@ -73,6 +74,25 @@ export function createMediaHandler({ ctx, store, fence }) {
   }
 }
 
+/**
+ * Resolve a recorded path (authorized per session) and serve it: bytes
+ * (images / PDFs, `download=1` supported) or, with `as=text`, an
+ * fs.read-shaped JSON payload for the floating preview's text fallback.
+ */
+async function serveRecordedFile(request, response, ctx, store) {
+  const url = new URL(request.url ?? '/', 'http://dsh.internal')
+  const sessionId = url.searchParams.get('sessionId')
+  const raw = url.searchParams.get('path')
+  assertMediaParams(sessionId, raw)
+  if (!isRecordedPath(store.state, sessionId, raw)) throw mediaError(403, "path is not in this session's file activity")
+  const abs = isAbsolute(raw) ? raw : join(sessionCwdOf(ctx, sessionId), raw)
+  if (url.searchParams.get('as') === 'text') {
+    await serveText(response, abs)
+    return
+  }
+  await serveMedia(response, abs, url)
+}
+
 /** Both query parameters are required for a media request. */
 function assertMediaParams(sessionId, raw) {
   if (sessionId === null || raw === null || raw === '') throw mediaError(400, 'sessionId and path are required')
@@ -96,3 +116,23 @@ async function serveMedia(response, abs, url) {
   response.writeHead(200, headers)
   response.end(body)
 }
+
+/**
+ * `as=text` mode: serve a recorded file's text content as an fs.read-shaped
+ * JSON payload ({ ok, value: { content } }) so the floating preview's text
+ * viewers mount unchanged even when the sidebar fs.read refuses the path
+ * (workspace fence — issue #68). Same authorization as bytes serving:
+ * recorded paths only.
+ */
+async function serveText(response, abs) {
+  let info
+  try {
+    info = await stat(abs)
+  } catch {
+    throw mediaError(404, 'file not found')
+  }
+  if (!info.isFile()) throw mediaError(400, 'not a file')
+  if (info.size > TEXT_LIMIT) throw mediaError(413, 'file too large')
+  const content = await readFile(abs, 'utf8')
+  writeJson(response, 200, { ok: true, value: { content } })
+}

package/lib/parts/api.part.js

@@ -43,3 +43,8 @@ function postClear(sessionId) {
 function mediaUrlOf(sessionId, path) {
   return `/file-activity/file?${new URLSearchParams({ sessionId, path })}`
 }
+
+/** Plugin text route URL (`as=text`): fs.read-shaped JSON for recorded text. */
+function textUrlOf(sessionId, path) {
+  return `/file-activity/file?${new URLSearchParams({ sessionId, path, as: 'text' })}`
+}

package/lib/parts/apply.part.js

@@ -68,7 +68,17 @@ exports.apply = function apply(ctx) {
   // Stylesheet first, unconditionally (HMR pitfall — see injectStyles).
   injectStyles(ctx)
   const service = ctx.betterSidebar
-  if (service === undefined) return
+  if (service === undefined) {
+    // 依赖缺失提示（issue #72 同类问题）：dsh-file-activity 的 client 端
+    // 依赖 dsh-better-sidebar 提供侧边栏扩展点，未安装时静默返回会让用户
+    // 以为插件坏了——明确提示安装方式。
+    if (typeof console !== 'undefined' && typeof console.warn === 'function') {
+      console.warn(
+        '[dsh-file-activity] dsh-better-sidebar 未安装：文件活动页签无法挂载。请安装宿主插件：dsh plugin --profile web add dsh-better-sidebar dsh-file-activity',
+      )
+    }
+    return
+  }
 
   // Per-session data store: { bySession: { [sessionId]: { recent, counts, loading } }, preview }
   // Each conversation reads/writes only its own bucket, so switching
@@ -83,3 +93,18 @@ exports.apply = function apply(ctx) {
   // auto-open once per session (default on)
   ctx.effect(() => installAutoOpen(ctx, TAB_ID), 'dsh-file-activity: auto-open')
 }
+
+// Internal functions exposed for the render-path test suite only; inert in
+// the browser bundle (plain properties on the exports object).
+exports.__test = {
+  loadFsReadContent,
+  fsReadError,
+  fetchTextContent,
+  textUrlOf,
+  strings,
+  renderPreviewBody,
+  previewClickAction,
+  isInsideFloating,
+  closePreviewOnHidden,
+  AUTO_CLOSE_MS,
+}

package/lib/parts/i18n.part.js

@@ -38,5 +38,10 @@ const strings = {
   loading: () => (isZh() ? '加载中…' : 'Loading…'),
   previewUnsupported: () => (isZh() ? '该文件类型暂不支持预览' : 'This file type cannot be previewed yet'),
   previewFailed: () => (isZh() ? '预览加载失败' : 'Preview failed to load'),
+  fileMissing: () => (isZh() ? '文件不存在或已被删除' : 'This file no longer exists'),
+  fileOutside: () =>
+    isZh() ? '文件位于工作区外，暂无法读取内容' : 'The file is outside the workspace and cannot be read',
   downloadToView: () => (isZh() ? '下载查看' : 'download to view'),
+  clickOutsideToClose: () => (isZh() ? '点击外部关闭' : 'Click outside to close'),
+  autoCloseHint: () => (isZh() ? '预览失败，即将自动关闭' : 'Preview failed — closing automatically'),
 }

package/lib/parts/preview.part.js

@@ -12,14 +12,54 @@ function isFsReadOk(json) {
   return json !== null && typeof json === 'object' && json.ok === true && typeof json.value?.content === 'string'
 }
 
-/** Error load state from an fs.read API response (or a generic message). */
+/** Error load state from an fs.read API response (or a generic message).
+ *  Raw system errors are translated to friendly, locale-aware messages
+ *  (issue #68): deleted files and workspace-fenced paths must never surface
+ *  ENOENT / "is outside workspace" verbatim. */
 function fsReadError(json, viewer) {
-  return { status: 'error', viewer, message: json?.error?.message ?? strings.previewFailed() }
+  const raw = json?.error?.message ?? ''
+  let message
+  if (raw === '') message = strings.previewFailed()
+  else if (/ENOENT|no such file|does not exist|cannot resolve/i.test(raw)) message = strings.fileMissing()
+  else if (/outside workspace/i.test(raw)) message = strings.fileOutside()
+  else message = raw
+  return { status: 'error', viewer, message }
+}
+
+/** Milliseconds after which an error-state preview closes itself (issue #76):
+ *  a shell that failed to load any content is useless, so it must not linger
+ *  over the main UI until the user finds the × button. */
+const AUTO_CLOSE_MS = 2500
+
+/** Whether a pointerdown target lies inside the floating window. The window
+ *  surface carries the `.dfa-fp` class; anything else counts as "outside"
+ *  and dismisses the preview (issue #76 — click anywhere outside closes). */
+function isInsideFloating(target) {
+  if (!target || typeof target.closest !== 'function') return false
+  return target.closest('.dfa-fp') !== null
+}
+
+/** Click behavior for the window surface: in the error state ANY click
+ *  closes the shell (there is no content to interact with), otherwise the
+ *  click is swallowed so the viewer's own interactions keep working. */
+function previewClickAction(load, event) {
+  if (load.status === 'error') return 'close'
+  if (event && event.stopPropagation) event.stopPropagation()
+  return 'stop'
+}
+
+/** Close the floating preview when the tab goes hidden (switching tabs /
+ *  operating the main UI), so it never lingers over the interface. */
+function closePreviewOnHidden(visible, dataStore) {
+  if (!visible) dataStore.set({ preview: null })
 }
 
 /**
  * Load fsRead content through the sidebar API and resolve the viewer's
- * load state (ready with text, or error with the API message).
+ * load state (ready with text, or error with the API message). When the
+ * sidebar refuses a recorded path (its workspace fence, e.g. agent-read
+ * files under ~/.dsh), fall back to the plugin's own text route, which
+ * authorizes exactly the paths this session recorded (issue #68).
  */
 async function loadFsReadContent(viewer, path, scope, sessionId) {
   const target = resolvePath(path, scope?.cwd ?? '')
@@ -30,9 +70,22 @@ async function loadFsReadContent(viewer, path, scope, sessionId) {
   })
   const json = await response.json()
   if (isFsReadOk(json)) return { status: 'ready', viewer, content: json.value.content }
+  // The sidebar refused — try OUR recorded-path text route before giving up.
+  const textJson = await fetchTextContent(sessionId, path)
+  if (isFsReadOk(textJson)) return { status: 'ready', viewer, content: textJson.value.content }
   return fsReadError(json, viewer)
 }
 
+/** Plugin text route (fs.read-shaped JSON), or null on any failure. */
+async function fetchTextContent(sessionId, path) {
+  try {
+    const response = await fetch(textUrlOf(sessionId, path))
+    return await response.json()
+  } catch {
+    return null
+  }
+}
+
 /**
  * Fetch the bytes the viewer's fetchStrategy needs (fsRead text /
  * mediaUrl / customData) and resolve its load state.
@@ -100,6 +153,7 @@ function renderPreviewBody(load, ctx, store, scope, path, title, sessionId) {
       load.message
         ? createElement('div', { style: { marginTop: '6px', fontSize: '11px', opacity: 0.85 } }, load.message)
         : null,
+      createElement('div', { style: { marginTop: '6px', fontSize: '11px', opacity: 0.7 } }, strings.autoCloseHint()),
     )
   }
   if (load.viewer.id === 'pdf') {
@@ -135,15 +189,25 @@ function renderPreviewBody(load, ctx, store, scope, path, title, sessionId) {
  * built-in viewer that fetches its own URL internally (it ignores the
  * `mediaUrl` prop), so it gets a small iframe preview instead.
  */
-function FloatingPreview({ ctx, store, scope, preview, onClose }) {
-  const sessionId = scope?.sessionId ?? ''
-  const path = preview.abs
-  const title = preview.name
-  const service = ctx.betterSidebar
-  const load = usePreviewLoader(service, path, sessionId, scope)
+/**
+ * Dismissal affordances (issue #76 — the preview must never linger):
+ * 1. pointerdown anywhere OUTSIDE the window closes it (capture phase, so
+ *    it fires even if another element sits above the scrim);
+ * 2. the scrim's own onClick (kept as a fallback);
+ * 3. Escape;
+ * 4. the × button;
+ * 5. an error state closes itself after AUTO_CLOSE_MS (no content to show).
+ */
+function usePreviewDismiss(load, onClose) {
+  useEffect(() => {
+    if (typeof document === 'undefined' || typeof document.addEventListener !== 'function') return () => {}
+    const handler = (event) => {
+      if (!isInsideFloating(event?.target)) onClose()
+    }
+    document.addEventListener('pointerdown', handler, true)
+    return () => document.removeEventListener('pointerdown', handler, true)
+  }, [onClose])
 
-  // Clicking outside is the primary dismiss (the overlay's onClick);
-  // Escape is a keyboard affordance. Both call onClose.
   useEffect(() => {
     if (typeof document === 'undefined' || typeof document.addEventListener !== 'function') return () => {}
     const handler = (event) => {
@@ -153,6 +217,16 @@ function FloatingPreview({ ctx, store, scope, preview, onClose }) {
     return () => document.removeEventListener('keydown', handler)
   }, [onClose])
 
+  useEffect(() => {
+    if (load.status !== 'error') return undefined
+    if (typeof window === 'undefined' || typeof window.setTimeout !== 'function') return undefined
+    const timer = window.setTimeout(onClose, AUTO_CLOSE_MS)
+    return () => window.clearTimeout(timer)
+  }, [load.status, onClose])
+}
+
+/** The floating window element: head (title + hint + close) and body. */
+function renderFloatingWindow(load, ctx, store, scope, path, title, sessionId, onClose) {
   return createElement(
     'div',
     { className: 'dfa-fp-overlay', onClick: onClose },
@@ -161,13 +235,14 @@ function FloatingPreview({ ctx, store, scope, preview, onClose }) {
       {
         className: 'dfa-fp',
         onClick: (event) => {
-          if (event && event.stopPropagation) event.stopPropagation()
+          if (previewClickAction(load, event) === 'close') onClose()
         },
       },
       createElement(
         'div',
         { className: 'dfa-fp-head' },
         createElement('span', { className: 'dfa-fp-title' }, title),
+        createElement('span', { className: 'dfa-fp-hint' }, strings.clickOutsideToClose()),
         createElement(
           'span',
           { className: 'dfa-fp-actions' },
@@ -192,6 +267,16 @@ function FloatingPreview({ ctx, store, scope, preview, onClose }) {
   )
 }
 
+function FloatingPreview({ ctx, store, scope, preview, onClose }) {
+  const sessionId = scope?.sessionId ?? ''
+  const path = preview.abs
+  const title = preview.name
+  const service = ctx.betterSidebar
+  const load = usePreviewLoader(service, path, sessionId, scope)
+  usePreviewDismiss(load, onClose)
+  return renderFloatingWindow(load, ctx, store, scope, path, title, sessionId, onClose)
+}
+
 /**
  * Lightweight PDF preview. better-sidebar's built-in PdfView fetches
  * `/sidebar/file` internally (it ignores any injected `mediaUrl` prop),

package/lib/parts/styles.part.js

@@ -62,6 +62,7 @@ const STYLES = `
   display:flex; flex-direction:column; overflow:hidden; }
 .dfa-fp-head { display:flex; align-items:center; gap:6px; padding:6px 8px; border-bottom:1px solid var(--dsw-alias-border-l1); flex:none; }
 .dfa-fp-title { flex:1; min-width:0; overflow:hidden; text-overflow:ellipsis; white-space:nowrap; font:var(--dsw-font-s-strong-14); color:var(--dsw-alias-label-primary); }
+.dfa-fp-hint { flex:none; font:var(--dsw-font-xxs-12); color:var(--dsw-alias-label-tertiary); opacity:0.8; }
 .dfa-fp-actions { display:flex; align-items:center; gap:2px; flex:none; }
 .dfa-fp-body { flex:1; overflow:auto; padding:10px 12px; min-height:0; }
 .dfa-fp-note { color:var(--dsw-alias-label-tertiary); font:var(--dsw-font-xxs-12); }

package/lib/parts/view.part.js

@@ -158,6 +158,11 @@ function FileActivityView({ ctx, store, scope, visible, dataStore }) {
   useEffect(() => {
     dataStore.set({ preview: null })
   }, [sessionId, dataStore])
+  // Switching tabs hides this view: close any floating preview so it never
+  // lingers over the main UI (issue #76).
+  useEffect(() => {
+    closePreviewOnHidden(visible, dataStore)
+  }, [visible, dataStore])
   const toggleDir = (path) => setCollapsedDirs((prev) => toggleInSet(prev, path))
   const openPreview = (path) => dataStore.set({ preview: { abs: path, name: basenameOf(path) } })
   const closePreview = () => dataStore.set({ preview: null })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-file-activity",
-  "version": "0.5.3",
+  "version": "0.5.5",
   "description": "DSH 侧边栏文件活动插件：按 LRU 记录文件读取/新增/修改事件（最近访问），按绝对路径树形统计（文件统计），点击文件浮窗预览（代码高亮/Markdown/图片/PDF）。DSH web plugin: file activity tracker — LRU recent-access list plus per-file read/create/modify counts in a folder tree, with floating preview.",
   "type": "module",
   "main": "lib/index.js",
@@ -43,16 +43,15 @@
       ]
     }
   },
+  "dependencies": {
+    "dsh-better-sidebar": ">=0.14.0 <0.18.0",
+    "dsh-shared": "^0.1.0"
+  },
   "peerDependencies": {
     "cordis": "^4.0.0-rc.8",
-    "dsh-better-sidebar": "^0.14.0",
-    "react": "^18.2.0 || ^19.2.0",
-    "dsh-shared": "^0.1.0"
+    "react": "^18.2.0 || ^19.2.0"
   },
   "peerDependenciesMeta": {
-    "dsh-better-sidebar": {
-      "optional": true
-    },
     "cordis": {
       "optional": true
     }