dsh-file-activity 0.5.4 → 0.5.5

package/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 本文件记录 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
 
 ### 变更

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

@@ -90,6 +90,8 @@ const strings = {
   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 ────────────────────────────────────
@@ -776,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); }
@@ -1124,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 })
@@ -1176,6 +1184,34 @@ function fsReadError(json, viewer) {
   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). When the
@@ -1275,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') {
@@ -1310,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) => {
@@ -1328,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 },
@@ -1336,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' },
@@ -1367,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),
@@ -1467,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
@@ -1485,7 +1563,18 @@ exports.apply = function apply(ctx) {
 
 // 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 }
+exports.__test = {
+  loadFsReadContent,
+  fsReadError,
+  fetchTextContent,
+  textUrlOf,
+  strings,
+  renderPreviewBody,
+  previewClickAction,
+  isInsideFloating,
+  closePreviewOnHidden,
+  AUTO_CLOSE_MS,
+}
 
 
     return module.exports

package/lib/media-route.js

@@ -84,8 +84,7 @@ async function serveRecordedFile(request, response, ctx, store) {
   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")
+  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)

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
@@ -86,4 +96,15 @@ exports.apply = function apply(ctx) {
 
 // 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 }
+exports.__test = {
+  loadFsReadContent,
+  fsReadError,
+  fetchTextContent,
+  textUrlOf,
+  strings,
+  renderPreviewBody,
+  previewClickAction,
+  isInsideFloating,
+  closePreviewOnHidden,
+  AUTO_CLOSE_MS,
+}

package/lib/parts/i18n.part.js

@@ -42,4 +42,6 @@ const strings = {
   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

@@ -26,6 +26,34 @@ function fsReadError(json, viewer) {
   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). When the
@@ -125,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') {
@@ -160,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) => {
@@ -178,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 },
@@ -186,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' },
@@ -217,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.4",
+  "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
     }