dsh-file-activity 0.5.7 → 0.5.9

package/lib/client.js

@@ -1,29 +1,30 @@
 /**
  * dsh-file-activity — client half (browser).
  *
- * Extends dsh-better-sidebar with a "文件活动 / File Activity" tab:
- *  - recent file access history (agent + sidebar operations),
- *  - per-file create/modify/read counts flattened by folder, with multi-level
- *    folders shown as dotted paths (a.b.c.d) and their files indented below,
- *  - clicking any file opens a FLOATING preview that reuses the sidebar's
- *    NATIVE viewer via `ctx.betterSidebar.matchFileViewer(path)` — its own
- *    `component` is mounted (built-in markdown / code / image / pdf / html
- *    renderers), so code gets syntax highlighting and markdown gets rendered
- *    with no hand-rolled preview; clicking outside / Esc / × closes it,
- *  - auto-opens once per session by default (toggleable in the sidebar
- *    settings, enabled by default).
+ * A native right-Sidebar tab ("文件活动 / File Activity") built on the HOST's
+ * own extension points (issue #187 batch 2 — no third-party sidebar service):
+ *  - the tab type registers into `ctx.sidebarRightTabs` (stage one) and its
+ *    body / chip title into the keyed `sidebar.right.pane.tab` and
+ *    `sidebar.right.pane.tab.title` seats (stage two);
+ *  - clicking a file opens a FLOATING preview implemented by this plugin inside
+ *    the `shell.overlay` list seat: recent access history (agent + plugin
+ *    routes), per-file create/modify/read counts flattened by folder, and the
+ *    preview window itself — clicking outside / Esc / × closes it;
+ *  - a document-preview descriptor registers with `ctx.documentPreviews`
+ *    (metadata only: the native document owner reads the bytes);
+ *  - auto-opens once per session by default, with its toggle in the Web
+ *    Settings → Plugins tab (`settings.plugins.tab`).
  *
  * Data source: the plugin host half (fs/observed for agent tools) + this
- * half's fetch interception for sidebar file operations (fs.read / fs.write /
- * /sidebar/file media opens), both persisted host-side; the tab polls
- * /file-activity/api/stats.
+ * half's fetch interception for the plugin's own file routes, both persisted
+ * host-side; the tab polls /file-activity/api/stats.
  *
- * Styling follows the dsh-better-sidebar design language: all colors ride the
- * DSH semantic tokens (--dsw-alias-*), typography rides the font roles
- * (--dsw-font-*), motion rides --ds-*. Flat surfaces (no box-shadow), hairline
- * borders, 28px circular icon controls with hover fills, and 8px-radius rows
- * with hover fills. The stylesheet is injected once per activation and torn
- * down with the fiber, so HMR/disable leaves no residue.
+ * Styling follows the DSH design language: all colors ride the DSH semantic
+ * tokens (--dsw-alias-*), typography rides the font roles (--dsw-font-*),
+ * motion rides --ds-*. Flat surfaces (no box-shadow), hairline borders, 28px
+ * circular icon controls with hover fills, and 8px-radius rows with hover
+ * fills. The stylesheet is injected once per activation and torn down with the
+ * fiber, so HMR/disable leaves no residue.
  *
  * BUILD NOTE: this file is the SOURCE TEMPLATE. scripts/build.mjs splices the
  * `lib/parts/*.part.js` pieces into the PART placeholder markers below (each
@@ -40,13 +41,17 @@ window.__ModuleLoader__.load({
     Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' })
     const { createElement, useEffect, useMemo, useState, useSyncExternalStore } = require('react')
 
-    const TAB_ID = 'file-activity:recent'
+    const TAB_ID = 'dsh-file-activity'
+    const TAB_KIND = 'file-activity'
+    const PREVIEW_ID = 'dsh-file-activity-preview'
     const AUTO_OPEN_KEY = 'dsh-file-activity:auto-opened:'
+    const AUTO_OPEN_PREF_KEY = 'dsh-file-activity:autoOpen'
     const POLL_MS = 6000
 
     // ── parts (injected by scripts/build.mjs; keep this exact order — the
     //    const initializers below run in splice order) ─────────────────────
-    // ── i18n ──────────────────────────────────────────────────────────────
+    'use strict'
+// ── i18n ──────────────────────────────────────────────────────────────
 function isZh() {
   try {
     const lang = (navigator.language || 'en').toLowerCase()
@@ -55,7 +60,6 @@ function isZh() {
     return false
   }
 }
-
 const strings = {
   title: () => (isZh() ? '文件活动' : 'File Activity'),
   recent: () => (isZh() ? '最近访问' : 'Recent'),
@@ -91,16 +95,30 @@ const strings = {
     isZh() ? '文件位于工作区外，暂无法读取内容' : 'The file is outside the workspace and cannot be read',
   downloadToView: () => (isZh() ? '下载查看' : 'download to view'),
   clickOutsideToClose: () => (isZh() ? '点击外部关闭' : 'Click outside to close'),
+  guideDescription: () =>
+    isZh()
+      ? '查看 agent 与侧边栏读写过的文件（最近访问 + 目录统计）'
+      : 'Files the agent and the sidebar touched (recent + tree)',
+  autoOpenLabel: () => (isZh() ? '会话开始时自动打开' : 'Auto-open on session start'),
+  autoOpenHint: () =>
+    isZh()
+      ? '每个会话首次打开时自动显示本页；关闭后仍可从侧边栏右上角的「新标签页」手动打开。'
+      : 'Shows this page once per session. When off, open it from the sidebar new-tab control.',
+  tabUnavailable: () => (isZh() ? '侧边栏扩展点不可用' : 'Sidebar extension point unavailable'),
+  tabUnavailableHint: () =>
+    isZh()
+      ? '本插件未能注册页签（宿主原生 API 可能已变更）。原因见浏览器控制台。'
+      : 'This plugin could not register its tab (the host native API may have changed). See the browser console.',
   autoCloseHint: () => (isZh() ? '预览失败，即将自动关闭' : 'Preview failed — closing automatically'),
 }
 
-    // ── path / time formatting helpers ────────────────────────────────────
+    'use strict'
+// ── path / time formatting helpers ────────────────────────────────────
 function basenameOf(path) {
   const norm = path.split('\\').join('/')
   const idx = norm.lastIndexOf('/')
   return idx === -1 ? norm : norm.slice(idx + 1)
 }
-
 /** Compact relative time: 刚刚 / N 分钟前 / N 小时前 / N 天前 / MM/DD. */
 function formatRelative(time) {
   if (typeof time !== 'number' || !Number.isFinite(time)) return ''
@@ -115,7 +133,6 @@ function formatRelative(time) {
   const date = new Date(time)
   return `${date.getMonth() + 1}/${date.getDate()}`
 }
-
 /** Local wall-clock HH:MM:SS (used in tooltips; full precision). */
 function formatTime(time) {
   const date = new Date(time)
@@ -123,7 +140,8 @@ function formatTime(time) {
   return `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}`
 }
 
-    // ── directory tree construction ───────────────────────────────────────
+    'use strict'
+// ── directory tree construction ───────────────────────────────────────
 /**
  * Collapse chain directories: a directory whose only child is another
  * directory merges into it (a → a.b → a.b.c …). Deep single-child paths
@@ -143,7 +161,6 @@ function compressChains(node, isRoot) {
     node.compressed = true
   }
 }
-
 /**
  * Sort a directory node: directories first (alphabetically), then files
  * (by total activity, then name); recurse into directories.
@@ -160,7 +177,6 @@ function sortNode(node) {
     if (child.type === 'dir') sortNode(child)
   }
 }
-
 /**
  * Build a nested directory tree from per-file counts, keyed by the file's
  * absolute path. Every directory node aggregates its subtree counters and
@@ -208,7 +224,8 @@ function buildTree(counts) {
   return root
 }
 
-    // ── tiny external store ───────────────────────────────────────────────
+    'use strict'
+// ── tiny external store ───────────────────────────────────────────────
 function createStore(initial) {
   let state = initial
   const listeners = new Set()
@@ -224,15 +241,33 @@ function createStore(initial) {
     },
   }
 }
-
-    // ── data access (host routes) ─────────────────────────────────────────
+// ── shared store slot ─────────────────────────────────────────────────
+//
+// The tab body renders inside a session-scoped seat while the floating preview
+// renders inside the root-scoped 'shell.overlay' seat, so the store the two
+// halves share cannot travel as a prop from one to the other. One module-level
+// reference is enough: the overlay seat is mounted for the plugin's whole
+// lifetime and only ever reads the CURRENT store, and a rebuild replaces the
+// reference before the new overlay renders.
+/** The store the overlay seat reads; set once per activation. */
+let sharedDataStore = null
+/** Publish the activation's store for the root-scoped overlay seat. */
+function registerSharedStore(store) {
+  sharedDataStore = store
+}
+/** The activation's store, or null before apply() ran. */
+function sharedStore() {
+  return sharedDataStore
+}
+
+    'use strict'
+// ── data access (host routes) ─────────────────────────────────────────
 async function fetchStats(sessionId) {
   const response = await fetch(`/file-activity/api/stats?sessionId=${encodeURIComponent(sessionId)}`)
   const json = await response.json()
   if (json === null || typeof json !== 'object' || json.ok !== true) return null
   return json.value
 }
-
 /** Resolve the session working directory through the sidebar's native API. */
 async function fetchSessionCwd(sessionId) {
   try {
@@ -248,7 +283,6 @@ async function fetchSessionCwd(sessionId) {
     return ''
   }
 }
-
 function postRecord(sessionId, path, op) {
   if (typeof sessionId !== 'string' || sessionId === '' || typeof path !== 'string' || path === '') return
   void fetch('/file-activity/api/record', {
@@ -257,7 +291,6 @@ function postRecord(sessionId, path, op) {
     body: JSON.stringify({ sessionId, path, op }),
   }).catch(() => {})
 }
-
 function postClear(sessionId) {
   void fetch('/file-activity/api/clear', {
     method: 'POST',
@@ -265,54 +298,41 @@ function postClear(sessionId) {
     body: JSON.stringify({ sessionId }),
   }).catch(() => {})
 }
-
 /** Plugin media route URL for a recorded path (authorized per session). */
 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()
-}
-
-/** POST body as a plain object (non-string bodies are ignored). */
-function parseBody(init) {
-  return typeof init?.body === 'string' ? JSON.parse(init.body) : {}
-}
-
-/** Record fs.read / fs.write POSTs observed on the sidebar API. */
-function recordSidebarFs(url, init) {
-  if (url.pathname !== '/sidebar/api/fs.read' && url.pathname !== '/sidebar/api/fs.write') return
-  if (methodOf(init) !== 'POST') return
-  const body = parseBody(init)
-  if (typeof body.sessionId !== 'string' || typeof body.path !== 'string') return
-  postRecord(body.sessionId, body.path, url.pathname === '/sidebar/api/fs.write' ? 'write' : 'read')
-}
-
-/** Record sidebar media opens (/sidebar/file?sessionId=...&path=...). */
-function recordMediaOpen(url, init) {
-  if (url.pathname !== '/sidebar/file' || methodOf(init) !== 'GET') return
+    'use strict'
+// ── fetch interception: the plugin's own file routes ───────────────────
+//
+// Before the native migration this module also watched the THIRD-PARTY
+// sidebar's routes (/sidebar/api/fs.read|fs.write, /sidebar/file). Those are
+// the host's internal surface now, fed by the host's own file provider and
+// document owner — the plugin neither opens nor owns them, so observing them
+// would record host traffic that is already recorded through the plugin's
+// fs/observed host half. What remains is the plugin's own media/text route,
+// whose reads ARE the user's previews.
+/** Record requests for the plugin's own file route (media + text previews). */
+function recordOwnMediaOpen(url, init) {
+  if (url.pathname !== '/file-activity/file') return
+  if ((init?.method ?? 'GET').toUpperCase() !== 'GET') return
   const sessionId = url.searchParams.get('sessionId')
   const path = url.searchParams.get('path')
   if (sessionId !== null && path !== null) postRecord(sessionId, path, 'read')
 }
-
-/** Observe a resolved fetch URL and record sidebar file operations. */
+/** Observe a resolved fetch URL and record plugin file operations. */
 function observeSidebarFetch(url, init) {
   try {
-    recordSidebarFs(url, init)
-    recordMediaOpen(url, init)
+    recordOwnMediaOpen(url, init)
   } catch {
     // observation must never break the underlying call
   }
 }
-
 function installFetchInterceptor() {
   const original = window.fetch.bind(window)
   window.fetch = (input, init) => {
@@ -333,81 +353,167 @@ function installFetchInterceptor() {
   }
 }
 
-    // ── auto-open (enabled by default) ────────────────────────────────────
-function findTabIn(state, tabId) {
-  const leaves = (node) => (node.kind === 'leaf' ? [node] : (node.children ?? []).flatMap(leaves))
-  for (const node of [state?.splits, state?.bottomSplits]) {
-    if (node === undefined || node === null) continue
-    for (const leaf of leaves(node)) {
-      if ((leaf.tabs ?? []).some((tab) => tab.type === tabId)) return true
-    }
-  }
-  return false
-}
-
-/** Current sidebar snapshot, or null when the service is not ready. */
-function sidebarSnapshot(service) {
+    'use strict'
+// ── auto-open (enabled by default) ────────────────────────────────────
+//
+// Native flow: the tab is a PAGE type, so opening it means
+// `ctx.sidebarRight.openTab(kind)` — there is no layout snapshot to inspect
+// and no session id to read from a third-party sidebar service anymore.
+//
+// Timing is the whole problem. The navigation controller throws
+// "sidebarRight: no session surface is mounted" when the right column has not
+// mounted its session surface yet — which is exactly the state during the
+// first paint of a fresh page. The previous third-party sidebar used to answer with a snapshot
+// and the old code simply gave up when it was missing, which is how the tab
+// could silently never auto-open. Here the attempt is RETRIED with the timers
+// until the surface is up, and a permanent failure is recorded through
+// markDegraded() instead of disappearing.
+/** Retry cadence while the right column has not mounted its session surface. */
+const AUTO_OPEN_RETRY_MS = 1000
+/** Give up after this many attempts (~30s) and degrade observably. */
+const AUTO_OPEN_MAX_TRIES = 30
+/**
+ * Pending retry timer id (0 = none).
+ *
+ * There is deliberately NO "already attempted" flag guarding this module: a
+ * rejected registration or an HMR rebuild re-runs apply(), and the second run
+ * must still be able to bring the tab back. `openTab` is idempotent — it
+ * focuses the existing page instead of duplicating it.
+ */
+let autoOpenTimer = 0
+/**
+ * Whether this BROWSER TAB already had its auto-open attempt.
+ *
+ * The native API exposes no "current session id" to a plugin (`openTab`
+ * targets the mounted session, and the layout store is the host's own), so a
+ * per-session marker cannot be written from here. The marker is therefore
+ * per-browser-tab: one attempt per page load, which is exactly the visible
+ * behaviour — the session's tab record itself is persisted host-side, so
+ * revisiting a session that already shows the tab merely focuses it.
+ */
+function isAutoOpenAttempted() {
+  const key = AUTO_OPEN_KEY + 'loaded'
   try {
-    return service.getSnapshot?.()
+    return window.sessionStorage.getItem(key) === '1'
   } catch {
-    return null
+    return false
   }
 }
-
-/** The user disabled auto-open for this tab in the sidebar settings. */
-function isAutoOpenDisabled(snapshot, tabId) {
-  const settings = snapshot.prefs?.pluginSettings?.[tabId]
-  return settings !== undefined && settings.autoOpen === false
-}
-
-/** Whether this session was already auto-opened (localStorage marker). */
-function isAutoOpenMarked(sessionId) {
+/** Mark this browser tab as already attempted. */
+function markAutoOpenAttempted() {
   try {
-    return Boolean(window.localStorage.getItem(AUTO_OPEN_KEY + sessionId))
+    window.sessionStorage.setItem(AUTO_OPEN_KEY + 'loaded', '1')
   } catch {
-    return true
+    // ignore
   }
 }
-
-/** Persist the auto-opened marker for this session. */
-function markAutoOpened(sessionId) {
+/** The most recent controller refusal, surfaced when retries run out. */
+let lastAutoOpenError = null
+/** One open attempt: true when the controller accepted it. */
+function tryOpenTab(ctx, tries) {
   try {
-    window.localStorage.setItem(AUTO_OPEN_KEY + sessionId, '1')
-  } catch {
-    // ignore
+    ctx.sidebarRight.openTab(TAB_KIND, { revealIfOpened: false })
+    return true
+  } catch (error) {
+    if (tries === 0) lastAutoOpenError = error
+    return false
   }
 }
-
-/** Open the tab once per session unless disabled in the plugin settings. */
-function tryAutoOpen(service, tabId) {
-  const snapshot = sidebarSnapshot(service)
-  if (snapshot === undefined || snapshot === null || snapshot.sessionId === undefined || snapshot.state === undefined)
-    return
-  const sessionId = snapshot.sessionId
-  if (isAutoOpenDisabled(snapshot, tabId)) return
-  if (isAutoOpenMarked(sessionId)) return
-  if (findTabIn(snapshot.state, tabId)) {
-    markAutoOpened(sessionId)
-    return
+/**
+ * Open the tab once the session surface exists, then stop. The tab record
+ * itself is persisted host-side, so a session that already shows it is not
+ * reopened: `openTab` focuses the existing page instead of duplicating it.
+ * @param ctx - client context carrying the navigation controller.
+ * @returns disposer cancelling a pending retry.
+ */
+function installAutoOpen(ctx) {
+  if (!autoOpenEnabled()) return () => {}
+  if (isAutoOpenAttempted()) return () => {}
+  let tries = 0
+  const attempt = () => {
+    tries += 1
+    if (tryOpenTab(ctx, tries - 1)) {
+      autoOpenTimer = 0
+      markAutoOpenAttempted()
+      return
+    }
+    if (tries >= AUTO_OPEN_MAX_TRIES) {
+      autoOpenTimer = 0
+      markDegraded('auto-open', lastAutoOpenError ?? 'sidebarRight: session surface never mounted')
+      return
+    }
+    autoOpenTimer = window.setTimeout(attempt, AUTO_OPEN_RETRY_MS)
   }
-  try {
-    service.openTab({ type: tabId, title: strings.title(), path: '' })
-    markAutoOpened(sessionId)
-  } catch (error) {
-    console.error('[dsh-file-activity] auto-open failed:', error)
+  attempt()
+  return () => {
+    if (autoOpenTimer !== 0) {
+      window.clearTimeout(autoOpenTimer)
+      autoOpenTimer = 0
+    }
   }
 }
 
-function installAutoOpen(ctx, tabId) {
-  const service = ctx.betterSidebar
-  tryAutoOpen(service, tabId)
-  let off = () => {}
+    'use strict'
+// ── native document previews (metadata + plain-text renderer) ──────────
+//
+// The HOST owns file content on the native side: a registered preview only
+// declares WHICH suffixes this implementation recognizes and HOW the document
+// owner should deliver the bytes ('text-pages' = paged text window,
+// 'bytes-complete' = whole file). The owner then injects the prepared
+// DocumentContent into the 'sidebar.right.tab.document' seat, keyed by this
+// implementation's id — so the renderer never fetches anything itself
+// (the responsibility split that made 第三方查看器注册表的 matchFileViewer
+// obsolete; its fetchStrategy belonged to the third-party viewer).
+//
+// Scope of the registration: filenames whose suffixes no shipped renderer
+// claims. Anything the host already renders (code / markdown / image / pdf /
+// html) keeps winning: those implementations outrank this one by longest
+// suffix, and a 'fallback' band type (the shipped text preview) still beats
+// nothing-else-matches. This descriptor exists so a recorded log/diff/ndjson
+// file opens with a real renderer instead of the "nothing can view this"
+// notice.
+//
+// Degradation is explicit and observable (issue #187 batch 2): a rejected
+// registration is logged with its cause and marked on <html> so it can never
+// fail silently.
+/** Suffixes this implementation claims (no leading dot; compound is allowed). */
+const PREVIEW_EXTENSIONS = ['log', 'jsonl', 'ndjson', 'diff', 'patch']
+/**
+ * Record an extension-point failure so it is visible to users, tests and e2e.
+ * The <html> markers are `data-dfa-degraded` (which stage failed) plus
+ * `data-dfa-degraded-cause` (why), which makes a missing tab diagnosable from
+ * the page itself instead of only from the browser console.
+ */
+function markDegraded(kind, error) {
+  const message = error instanceof Error ? error.message : String(error)
+  if (typeof console !== 'undefined' && typeof console.error === 'function') {
+    console.error('[dsh-file-activity] ' + kind + ' 注册失败: ' + message)
+  }
   try {
-    off = service.subscribeState?.(() => tryAutoOpen(service, tabId)) ?? off
+    const root = typeof document === 'undefined' ? undefined : document.documentElement
+    if (root !== undefined && root !== null && root.dataset !== undefined) {
+      root.dataset.dfaDegraded = kind
+      root.dataset.dfaDegradedCause = message.slice(0, 200)
+    }
   } catch {
-    // service may lack subscribeState on older versions
+    // observation only: a missing document must not break activation
   }
-  return off
+}
+/** Register the native document-preview descriptor (metadata only). */
+function registerDocumentPreviews(ctx) {
+  ctx.effect(
+    () =>
+      ctx.documentPreviews.register({
+        id: TAB_ID,
+        extensions: PREVIEW_EXTENSIONS,
+        // 'extension' lets this implementation win over a shipped one on the
+        // same suffix; distinct suffixes keep the shipped renderers in charge.
+        priority: 'extension',
+        title: () => strings.title(),
+        loading: 'text-pages',
+      }),
+    'dsh-file-activity: document previews',
+  )
 }
 
     // ── shared icons (inline, stroke=currentColor, matching better-sidebar) ──
@@ -558,6 +664,27 @@ const icon = {
       ],
       size,
     ),
+  // 下载（issue #85 新增）：箭头入托盘，图表导出按钮（dsh-mermaid-render
+  // 卡片下载 PNG/SVG），stroke=currentColor 风格与其余图标一致。
+  download: (size = 16) =>
+    iconSvg(
+      [
+        createElement('path', { d: 'M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4' }),
+        createElement('polyline', { points: '7 10 12 15 17 10' }),
+        createElement('line', { x1: 12, y1: 15, x2: 12, y2: 3 }),
+      ],
+      size,
+    ),
+  // 复制（issue #85 新增）：双层矩形，复制源码按钮（dsh-mermaid-render
+  // 卡片复制代码），stroke=currentColor 风格与其余图标一致。
+  copy: (size = 16) =>
+    iconSvg(
+      [
+        createElement('rect', { x: 9, y: 9, width: 13, height: 13, rx: 2 }),
+        createElement('path', { d: 'M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1' }),
+      ],
+      size,
+    ),
 }
 
 // Common-language / file-type badges (issue #24): brand fill + contrast
@@ -714,10 +841,30 @@ const fileIconByExt = (ext, size = 14) => {
   return spec === undefined ? icon.file(size) : badgeIcon(spec, size)
 }
 
-    // ── themed stylesheet (injected once per activation) ──────────────────
-// Mirrors the better-sidebar explorer surface: tight 2px 6px 8px body,
+    'use strict'
+// ── themed stylesheet (injected once per activation) ──────────────────
+// Mirrors the host explorer surface: tight 2px 6px 8px body,
 // 30px rows, box-sizing border-box indentation, folder rows use the
 // strong type face to read as directories, files stay regular.
+/**
+ * Inject this activation's stylesheet into the document head exactly once per
+ * fiber. Static CSS only: it must not sit behind any service check, or an HMR
+ * rebuild / service reload can leave an already-rendered tab unstyled. The
+ * disposer removes only this fiber's own <style> element, so a rebuild always
+ * keeps at least one copy.
+ */
+function injectStyles(ctx) {
+  ctx.effect(() => {
+    if (typeof document === 'undefined' || document === null || typeof document.head === 'undefined') return () => {}
+    const style = document.createElement('style')
+    style.setAttribute('data-dsh-file-activity', 'styles')
+    style.textContent = STYLES
+    document.head.appendChild(style)
+    return () => {
+      if (style.parentNode) style.parentNode.removeChild(style)
+    }
+  }, 'dsh-file-activity: styles')
+}
 const STYLES = `
 .dfa { display:flex; flex-direction:column; height:100%; overflow-y:auto; overflow-x:hidden;
   padding:2px 6px 8px; gap:2px; font:var(--dsw-font-s-14); color:var(--dsw-alias-label-primary); }
@@ -781,7 +928,7 @@ const STYLES = `
 .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; }
 /* issue #111: the preview body is a FLEX COLUMN so the mounted viewer
-   component (better-sidebar's TextEditor for html/code/markdown, the image
+   component (the host's TextEditor for html/code/markdown, the image
    wrap, and the pdf frame) actually fills the window. Their roots size via
    flex:1 (html iframe .editorHtml, .editorCm, .editorMd, .editorImageWrap,
    .dfa-pdf), which is IGNORED in a block context — so the HTML iframe, which
@@ -802,10 +949,37 @@ const STYLES = `
 @keyframes dfa-row-in { from { opacity:0; transform:translateY(1px); } to { opacity:1; transform:none; } }
 /* issue #60: 移除 #25 的侧边栏页签选中态品牌蓝覆盖（[class*="tab"][class*=
    "tabActive"] 全局子串选择器误伤宿主对话/工作区 tab 选中态，出现用户不
-   想要的蓝色高亮）。页签选中态回归宿主（dsh-better-sidebar）默认样式。 */
+   想要的蓝色高亮）。页签选中态回归宿主原生样式（issue #187 批 2：原生
+   dockkit 页签自己负责选中态，本插件不再覆盖）。 */
+/* issue #187 批 2：页签 chip 由本插件的 title 席位渲染（原生 chip 无图标
+   API），因此标题连同图标一起画在这里。 */
+.dfa-chip { display:inline-flex; align-items:center; gap:4px; min-width:0; }
+/* 扩展点注册失败的显式提示（绝不静默失效）。 */
+.dfa-degraded { margin:6px 2px; padding:6px 8px; border-radius:6px;
+  border:1px solid var(--dsw-alias-state-error-primary); background:color-mix(in srgb, var(--dsw-alias-state-error-primary) 8%, transparent); }
+.dfa-degraded-title { font:var(--dsw-font-xs-13); color:var(--dsw-alias-state-error-primary); }
+.dfa-degraded-hint { margin-top:2px; font:var(--dsw-font-xxs-12); opacity:.8; }
+/* 设置页（settings.plugins.tab）：开关行。 */
+.dfa-set { display:flex; flex-direction:column; gap:10px; padding:10px 2px; }
+.dfa-set-title { font:var(--dsw-font-sm-14); }
+.dfa-set-row { display:flex; align-items:center; justify-content:space-between; gap:12px; cursor:pointer; }
+.dfa-set-text { display:flex; flex-direction:column; gap:2px; min-width:0; }
+.dfa-set-label { font:var(--dsw-font-xs-13); }
+.dfa-set-hint { font:var(--dsw-font-xxs-12); opacity:.75; }
+.dfa-set-switch { flex:none; width:16px; height:16px; accent-color:var(--dsw-alias-accent); cursor:pointer; }
+/* 浮窗正文：Markdown / 代码 / 纯文本 / 图片四种渲染体。 */
+.dfa-fp-md { height:100%; overflow:auto; padding:2px 4px; }
+.dfa-fp-code { height:100%; overflow:auto; }
+.dfa-fp-pre { margin:0; padding:8px 10px; overflow:auto; height:100%; font:var(--dsw-font-xxs-12);
+  white-space:pre-wrap; word-break:break-word; }
+.dfa-fp-img { display:block; margin:auto; max-width:100%; max-height:100%; object-fit:contain; }
+/* HTML 预览（issue #266 C）：沙箱 iframe 撑满浮窗主体并内部滚动（与 PDF 一致）。 */
+.dfa-fp-html { display:flex; flex-direction:column; width:100%; height:100%; }
+.dfa-fp-html-frame { flex:1; min-height:0; width:100%; border:none; border-radius:6px; background:#fff; }
 `
 
-    // ── row rendering helpers (recent list & stats tree) ──────────────────
+    'use strict'
+// ── row rendering helpers (recent list & stats tree) ──────────────────
 const opClass = (op) =>
   op === 'create'
     ? 'dfa-op-create'
@@ -822,7 +996,6 @@ const opLabel = (op) =>
       : op === 'delete'
         ? strings.delete()
         : strings.read()
-
 /** Tooltip for a stats file row: absolute path + created / last-seen times. */
 const fileTitle = (abs, firstSeen, lastSeen) => {
   const times = []
@@ -830,7 +1003,6 @@ const fileTitle = (abs, firstSeen, lastSeen) => {
   if (typeof lastSeen === 'number') times.push(`${strings.lastSeen()} ${formatTime(lastSeen)}`)
   return times.length > 0 ? `${abs}\n${times.join(' · ')}` : abs
 }
-
 /** Count pills for a file/dir node — only actions that actually happened are
  *  shown (a zero count renders no pill; all-zero nodes render no pill group,
  *  keeping untouched files visually quiet). */
@@ -849,7 +1021,6 @@ const countPills = (node) => {
   if (pills.length === 0) return null
   return createElement('span', { className: 'dfa-counts', style: { paddingLeft: '6px' } }, ...pills)
 }
-
 /** Extension of a file name (lowercase, no leading dot); '' when none.
  *  Dotfiles map to their whole name ('.gitignore' → 'gitignore') so the
  *  badge table can cover them; 'notes.' still yields ''. */
@@ -859,14 +1030,12 @@ const extOf = (name) => {
   if (dot === 0) return name.slice(1).toLowerCase()
   return ''
 }
-
 /** Extension-less but common build files → their badge key. */
 const NAME_BADGES = {
   makefile: 'makefile',
   dockerfile: 'dockerfile',
   'cmakelists.txt': 'cmake',
 }
-
 /** Badge key for a file name: basename match first, then extension. */
 const badgeKeyOf = (name) => {
   const base = name.toLowerCase()
@@ -874,7 +1043,6 @@ const badgeKeyOf = (name) => {
   if (named !== undefined) return named
   return extOf(name)
 }
-
 /** A stats-tree file row: icon + name + count pills + relative time. */
 const fileRow = (file, depth, onOpen) =>
   createElement(
@@ -891,7 +1059,6 @@ const fileRow = (file, depth, onOpen) =>
     countPills(file),
     file.lastSeen ? createElement('span', { className: 'dfa-time' }, formatRelative(file.lastSeen)) : null,
   )
-
 /** One stats-tree node: file rows render inline, dirs toggle collapse. */
 function renderTreeNode(node, depth, collapsedDirs, onToggleDir, onOpen) {
   if (node.type === 'file') return fileRow(node, depth, onOpen)
@@ -917,7 +1084,6 @@ function renderTreeNode(node, depth, collapsedDirs, onToggleDir, onOpen) {
       : node.children.map((child) => renderTreeNode(child, depth + 1, collapsedDirs, onToggleDir, onOpen)),
   )
 }
-
 /** A recent-list row: op badge + basename + relative time. */
 const recentEntry = (entry, onOpen) =>
   createElement(
@@ -932,7 +1098,6 @@ const recentEntry = (entry, onOpen) =>
     createElement('span', { className: 'dfa-row-name' }, basenameOf(entry.path)),
     createElement('span', { className: 'dfa-time' }, formatRelative(entry.time)),
   )
-
 /** Toggle a key in a Set (directory collapse state). */
 function toggleInSet(set, key) {
   const next = new Set(set)
@@ -940,7 +1105,6 @@ function toggleInSet(set, key) {
   else next.add(key)
   return next
 }
-
 /** Clear the current session's records host-side and reset its bucket. */
 function clearSessionData(dataStore, sessionId) {
   if (!window.confirm(strings.clearConfirm())) return
@@ -953,7 +1117,6 @@ function clearSessionData(dataStore, sessionId) {
     },
   })
 }
-
 /** Manual refresh: fetch stats + the authoritative cwd for this session. */
 function refreshSessionData(dataStore, sessionId, setCwd, setError) {
   if (sessionId === '') return
@@ -976,10 +1139,41 @@ function refreshSessionData(dataStore, sessionId, setCwd, setError) {
   })
 }
 
-    // ── view component ────────────────────────────────────────────────────
+    'use strict'
+// ── view component ────────────────────────────────────────────────────
 /** Shared empty bucket for sessions that have never loaded data (stable ref). */
 const EMPTY_SESSION = { recent: [], counts: {}, loading: true }
-
+/** tab.visible out of the host's SidebarRightTabInfo; undefined when the
+ *  information (or its shape) is unavailable. */
+function readSeatVisible(info) {
+  if (info === null || typeof info !== 'object') return undefined
+  const tab = info.tab
+  if (tab === null || typeof tab !== 'object') return undefined
+  const visible = tab.visible
+  return typeof visible === 'boolean' ? visible : undefined
+}
+/**
+ * Resolve whether this seat is on screen.
+ *
+ * The native seat hands the component **no** `visible` prop: the host dispatches
+ * it as `renderSlot('sidebar.right.pane.tab', {}, { hookContext })`, so the owner
+ * props share is empty and everything live arrives through the injected
+ * `useTabInfo()` hook (SidebarRightTabInfo.tab.visible). Reading `props.visible`
+ * alone is therefore always `undefined` — the pre-#266 (`if (!visible) return`)
+ * guard was constant-true, so an opened panel never loaded and never polled
+ * (it only showed data after a manual Refresh).
+ *
+ * Order: the host hook first, then the legacy prop, then visible by default.
+ * Defaulting to visible is the deliberate failure direction (issue #266): if the
+ * hook is unavailable or the host shape changes again, the panel must still
+ * load — the cost is one polling panel, the alternative is a blank one.
+ */
+function useSeatVisible(useTabInfo, legacyVisible) {
+  const info = typeof useTabInfo === 'function' ? useTabInfo() : undefined
+  const seatVisible = readSeatVisible(info)
+  if (seatVisible !== undefined) return seatVisible
+  return legacyVisible !== false
+}
 /**
  * Polling loader for one session: fetches stats on mount and on a fixed
  * interval while visible, prefers the sidebar's authoritative session.cwd
@@ -1022,7 +1216,6 @@ function useSessionLoader(visible, sessionId, scope, dataStore, setCwd, setError
     }
   }, [visible, sessionId, dataStore])
 }
-
 /** Error banner element, or null when the last load succeeded. */
 function renderError(error) {
   if (!error) return null
@@ -1038,7 +1231,6 @@ function renderError(error) {
     strings.loadError(),
   )
 }
-
 /** "最近访问" section: collapsible head with refresh/clear actions. */
 function renderRecentSection(recent, recentOpen, onToggle, onRefresh, onClear, onOpen) {
   return createElement(
@@ -1094,7 +1286,6 @@ function renderRecentSection(recent, recentOpen, onToggle, onRefresh, onClear, o
           ),
   )
 }
-
 /** "文件统计" section: the directory tree, or an empty hint. */
 function renderStatsSection(tree, collapsedDirs, onToggleDir, onOpen) {
   return createElement(
@@ -1110,20 +1301,31 @@ function renderStatsSection(tree, collapsedDirs, onToggleDir, onOpen) {
         ),
   )
 }
-
 /**
  * The file-activity tab. Each session renders only its own store bucket:
  * a fresh conversation shows an empty list immediately, with no residue
  * from the previous session. Clicking any file opens a FLOATING preview
  * that reuses the sidebar's NATIVE viewer via matchFileViewer.
  */
-function FileActivityView({ ctx, store, scope, visible, dataStore }) {
+function FileActivityView({
+  ctx,
+  store,
+  scope,
+  sessionId: seatSessionId,
+  visible: legacyVisible,
+  useTabInfo,
+  dataStore,
+}) {
   const data = useSyncExternalStore(dataStore.subscribe, dataStore.getSnapshot)
   const [cwd, setCwd] = useState(scope?.cwd || '')
   const [error, setError] = useState(false)
   const [recentOpen, setRecentOpen] = useState(true)
   const [collapsedDirs, setCollapsedDirs] = useState(() => new Set())
-  const sessionId = scope?.sessionId ?? ''
+  // Native seats pass sessionId directly; the legacy scope object still works.
+  const sessionId = seatSessionId ?? scope?.sessionId ?? ''
+  // issue #266 A: the native seat passes NO visible prop — visibility comes
+  // from the injected useTabInfo() (see useSeatVisible).
+  const visible = useSeatVisible(useTabInfo, legacyVisible)
   const sessionData = (data.bySession ?? {})[sessionId] ?? EMPTY_SESSION
   const tree = useMemo(() => buildTree(sessionData.counts ?? {}), [sessionData.counts])
   useEffect(() => {
@@ -1142,8 +1344,10 @@ function FileActivityView({ ctx, store, scope, visible, dataStore }) {
     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 })
+  // The floating preview itself lives in the root-scoped 'shell.overlay' seat
+  // (registered by registerPreviewOverlay), so this view only publishes the
+  // target — together with the owning session, which authorizes the routes.
+  const openPreview = (path) => dataStore.set({ preview: { abs: path, name: basenameOf(path), sessionId } })
   const onClear = () => clearSessionData(dataStore, sessionId)
   const onRefresh = () => refreshSessionData(dataStore, sessionId, setCwd, setError)
   const recent = sessionData.recent ?? []
@@ -1151,21 +1355,67 @@ function FileActivityView({ ctx, store, scope, visible, dataStore }) {
     'div',
     { className: 'dfa' },
     renderError(error),
+    renderDegraded(),
     renderRecentSection(recent, recentOpen, () => setRecentOpen((v) => !v), onRefresh, onClear, openPreview),
     renderStatsSection(tree, collapsedDirs, toggleDir, openPreview),
-    data.preview
-      ? createElement(FloatingPreview, {
-          ctx,
-          store,
-          scope,
-          preview: data.preview,
-          onClose: closePreview,
-        })
-      : null,
+  )
+}
+/**
+ * Degradation notice: shown when this activation failed to register one of the
+ * host extension points (registerTabType / documentPreviews / auto-open). The
+ * panel is also marked with data-dfa-degraded so the e2e suite can assert the
+ * failure instead of hunting a missing tab.
+ * @returns the notice element, or null when nothing degraded.
+ */
+function renderDegraded() {
+  try {
+    const markers = typeof document === 'undefined' ? undefined : document.documentElement?.dataset
+    if (markers === undefined || markers === null || markers.dfaDegraded === undefined) return null
+  } catch {
+    return null
+  }
+  return createElement(
+    'div',
+    { className: 'dfa-degraded', 'data-dfa-degraded': '1' },
+    createElement('div', { className: 'dfa-degraded-title' }, strings.tabUnavailable()),
+    createElement('div', { className: 'dfa-degraded-hint' }, strings.tabUnavailableHint()),
   )
 }
 
-    // ── floating preview window (reuses the sidebar's native viewer) ──────
+    'use strict'
+// ── preview data access (routes, viewer choice, loading) ────────────────
+//
+// The floating window used to mount the third-party sidebar's built-in viewer,
+// picked by the third-party sidebar matchFileViewer(path), and fed it the bytes its
+// fetchStrategy asked for. That service is gone (issue #187 batch 2), so this
+// module does the reading itself through the plugin's own routes:
+//
+//   /file-activity/file?sessionId&path        → raw bytes (image / pdf)
+//   /file-activity/file?sessionId&path&as=text → fs.read-shaped JSON text
+//
+// The route matters: file activity records files the agent touched ANYWHERE
+// (scratch files in /tmp, sibling repos, ~/.dsh), while the host's file
+// provider is fenced to the session workspace. The plugin route authorizes
+// exactly the paths this session recorded.
+/** Image suffixes the browser renders natively. */
+const IMAGE_EXT = /^(svg|png|jpe?g|gif|webp|avif|bmp|ico)$/i
+/** Suffixes rendered as Markdown. */
+const MARKDOWN_EXT = /^(md|markdown|mdx)$/i
+/** Suffixes rendered as a sandboxed HTML document (issue #266 C). */
+const HTML_EXT = /^(html?|xhtml)$/i
+/** Lower-case suffix of a path ('' when it has none). extOf (rows.ts) works on
+ *  a file NAME, so the basename is sliced off first. */
+function extOfPath(path) {
+  return extOf(path.slice(path.lastIndexOf('/') + 1))
+}
+/** Official UI atoms come from the host's staticModules (zero install). */
+function uiAtoms() {
+  try {
+    return require('@deepseek-ai/dsh-client-ui-primitives')
+  } catch {
+    return {}
+  }
+}
 /** Resolve a possibly-relative path against the session cwd. */
 function resolvePath(path, cwd) {
   if (typeof path !== 'string' || path === '') return path
@@ -1173,12 +1423,10 @@ function resolvePath(path, cwd) {
   if (typeof cwd === 'string' && cwd !== '') return `${cwd.replace(/\/+$/, '')}/${path}`
   return path
 }
-
 /** Whether the fs.read API response carries a text content payload. */
 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).
  *  Raw system errors are translated to friendly, locale-aware messages
  *  (issue #68): deleted files and workspace-fenced paths must never surface
@@ -1192,20 +1440,87 @@ function fsReadError(json, viewer) {
   else message = raw
   return { status: 'error', viewer, message }
 }
-
+/** 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
+  }
+}
+/**
+ * Load the recorded file's text through the plugin's own route, falling back
+ * to the host sidebar route when the plugin refuses the path. Whatever the
+ * host viewer used to do with its own fetchStrategy, this window does the
+ * reading itself now — the routes are the same ones the previous
+ * implementation used for its fsRead strategy.
+ */
+async function loadFsReadContent(viewer, path, scope, sessionId) {
+  const cwd = scope === null || scope === undefined ? '' : scope.cwd
+  const target = resolvePath(path, cwd ?? '')
+  const own = await fetchTextContent(sessionId, target)
+  if (isFsReadOk(own)) return { status: 'ready', viewer, content: own.value.content }
+  try {
+    const response = await fetch('/sidebar/api/fs.read', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ sessionId, path: target }),
+    })
+    const json = await response.json()
+    if (isFsReadOk(json)) return { status: 'ready', viewer, content: json.value.content }
+    return fsReadError(json, viewer)
+  } catch {
+    return fsReadError(own, viewer)
+  }
+}
+/** Which renderer a recorded path gets. */
+function viewerOf(path) {
+  const ext = extOfPath(path)
+  if (IMAGE_EXT.test(ext)) return 'image'
+  if (ext === 'pdf') return 'pdf'
+  if (HTML_EXT.test(ext)) return 'html'
+  if (MARKDOWN_EXT.test(ext)) return 'markdown'
+  return 'text'
+}
+/** Fetch the bytes the chosen renderer needs (media URL, or text content). */
+async function fetchPreviewLoad(target) {
+  const viewer = { id: viewerOf(target.abs) }
+  // image / pdf / html are served as BYTES by the plugin's own media route;
+  // html goes through an iframe (see HtmlBody), not through the text path.
+  if (viewer.id === 'image' || viewer.id === 'pdf' || viewer.id === 'html') {
+    return { status: 'ready', viewer, mediaUrl: mediaUrlOf(target.sessionId, target.abs) }
+  }
+  return loadFsReadContent(viewer, target.abs, null, target.sessionId)
+}
+
+    'use strict'
+// ── floating preview window (own renderer, shell.overlay seat) ─────────
+//
+// History: this window used to mount the third-party sidebar's built-in
+// viewer and let it fetch its own bytes. That service is gone (issue #187
+// batch 2), so the window renders the recorded file itself:
+//
+//   image (svg/png/jpeg/gif/webp/avif/bmp/ico) → <img src> on the plugin media route
+//   pdf                                        → <iframe src> on the same route
+//   markdown                                   → host MarkdownText atom
+//   anything else                              → host CodeBlock atom, else <pre>
+//
+// The overlay lives in the root-scoped 'shell.overlay' list seat (the host's
+// own floating layer: above every column, click-through unless the entry opts
+// into pointer events) and renders nothing at all while no preview is open.
+// Data access (routes, viewer choice, loading) lives in preview-data.ts.
 /** 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"
+ *  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. */
@@ -1214,81 +1529,17 @@ function previewClickAction(load, event) {
   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
- * 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 ?? '')
-  const response = await fetch('/sidebar/api/fs.read', {
-    method: 'POST',
-    headers: { 'content-type': 'application/json' },
-    body: JSON.stringify({ sessionId, path: target }),
-  })
-  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.
- */
-async function fetchPreviewLoad(viewer, path, scope, sessionId) {
-  const strategy = viewer.fetchStrategy
-  if (strategy === 'fsRead') return loadFsReadContent(viewer, path, scope, sessionId)
-  if (strategy === 'mediaUrl') {
-    return { status: 'ready', viewer, mediaUrl: mediaUrlOf(sessionId, path) }
-  }
-  if (strategy === 'custom') {
-    const data = await (viewer.load?.(path, scope) ?? Promise.resolve(undefined))
-    return { status: 'ready', viewer, customData: data }
-  }
-  // 'binary-download' and anything else: mount the viewer's own
-  // component (it handles the download / media itself).
-  return { status: 'ready', viewer }
-}
-
-/**
- * Resolve the file's viewer through the sidebar registry and load the
- * bytes it needs; failures become an error state shown in the window.
- */
-function usePreviewLoader(service, path, sessionId, scope) {
+function usePreviewLoader(target) {
   const [load, setLoad] = useState({ status: 'loading', viewer: null })
   useEffect(() => {
     let cancelled = false
-    const viewer = service?.matchFileViewer?.(path)
-    if (!viewer) {
-      setLoad({ status: 'error', viewer: null, message: strings.previewUnsupported() })
-      return () => {
-        cancelled = true
-      }
-    }
-    setLoad({ status: 'loading', viewer })
-    fetchPreviewLoad(viewer, path, scope, sessionId)
+    setLoad({ status: 'loading', viewer: { id: viewerOf(target.abs) } })
+    fetchPreviewLoad(target)
       .then((next) => {
         if (!cancelled) setLoad(next)
       })
@@ -1296,18 +1547,64 @@ function usePreviewLoader(service, path, sessionId, scope) {
         if (!cancelled)
           setLoad({
             status: 'error',
-            viewer,
+            viewer: null,
             message: error instanceof Error ? error.message : String(error),
           })
       })
     return () => {
       cancelled = true
     }
-  }, [path, sessionId, scope])
+  }, [target.abs, target.sessionId])
   return load
 }
-
-/** Preview window body: loading note / error panel / viewer mount. */
+/** Text body: the host's own Markdown / code atoms, with a plain <pre> fallback. */
+function TextBody({ load, path }) {
+  const text = load.content ?? ''
+  const ui = uiAtoms()
+  if (load.viewer?.id === 'markdown' && typeof ui.MarkdownText === 'function') {
+    return createElement('div', { className: 'dfa-fp-md' }, createElement(ui.MarkdownText, { text }))
+  }
+  if (typeof ui.CodeBlock === 'function') {
+    return createElement(
+      'div',
+      { className: 'dfa-fp-code' },
+      createElement(ui.CodeBlock, { code: text, language: extOfPath(path) }),
+    )
+  }
+  return createElement('pre', { className: 'dfa-fp-pre' }, text)
+}
+/** Image body: the plugin's media route renders the recorded bytes. */
+function ImageBody({ load, title }) {
+  return createElement('img', { className: 'dfa-fp-img', src: load.mediaUrl, alt: title })
+}
+/**
+ * HTML body: a SANDBOXED iframe over the plugin's media route (issue #266 C —
+ * the README promised a sandboxed iframe while the code rendered the markup as
+ * a code block).
+ *
+ * Two independent sandbox layers, deliberately without `allow-same-origin`:
+ *  - the iframe's `sandbox` attribute gives the document an opaque origin, so
+ *    a previewed page cannot read the host's storage, cookies or same-origin
+ *    APIs, and cannot reach the parent document;
+ *  - the route answers text/html with a response-level
+ *    `Content-Security-Policy: sandbox …` header, so the SAME protection holds
+ *    when the URL is opened directly instead of inside this iframe.
+ * Scripts/forms stay enabled so interactive documents (charts, demos) work;
+ * navigation of the top window is not granted.
+ */
+function HtmlBody({ load, title }) {
+  return createElement(
+    'div',
+    { className: 'dfa-fp-html' },
+    createElement('iframe', {
+      className: 'dfa-fp-html-frame',
+      src: load.mediaUrl,
+      sandbox: 'allow-scripts allow-forms',
+      title,
+    }),
+  )
+}
+/** Preview window body: loading note / error panel / renderer mount. */
 function renderPreviewBody(load, ctx, store, scope, path, title, sessionId) {
   if (load.status === 'loading') {
     return createElement('div', { className: 'dfa-fp-note' }, strings.loading())
@@ -1323,39 +1620,15 @@ function renderPreviewBody(load, ctx, store, scope, path, title, sessionId) {
       createElement('div', { style: { marginTop: '6px', fontSize: '11px', opacity: 0.7 } }, strings.autoCloseHint()),
     )
   }
-  if (load.viewer.id === 'pdf') {
+  const props = { load, path, title, sessionId }
+  if (load.viewer?.id === 'image') return ImageBody(props)
+  if (load.viewer?.id === 'html') return HtmlBody(props)
+  if (load.viewer?.id === 'pdf') {
     const url = mediaUrlOf(sessionId, path)
     return createElement(PdfPreview, { src: url, download: `${url}&download=1`, title })
   }
-  return createElement(load.viewer.component, {
-    ctx,
-    store,
-    scope,
-    path,
-    title,
-    viewerId: load.viewer.id,
-    content: load.content,
-    mediaUrl: load.mediaUrl,
-    customData: load.customData,
-  })
+  return TextBody(props)
 }
-
-/**
- * A floating preview window. Instead of re-implementing rendering, it
- * asks the sidebar registry for the file's viewer (`matchFileViewer`),
- * fetches the bytes the viewer's fetchStrategy needs (fsRead text /
- * mediaUrl / customData), then mounts that viewer's own component — so
- * code gets syntax highlighting and markdown gets rendered by the SAME
- * built-in renderers the sidebar's editor tab uses.
- *
- * Media caveat: the sidebar's own media route (/sidebar/file) only serves
- * files inside the session working directory, while file activity records
- * files the agent touched anywhere (/tmp scratch files, sibling repos…).
- * Media bytes therefore come from OUR route (/file-activity/file), which
- * authorizes exactly the paths this session recorded; PDF is the one
- * built-in viewer that fetches its own URL internally (it ignores the
- * `mediaUrl` prop), so it gets a small iframe preview instead.
- */
 /**
  * Dismissal affordances (issue #76 — the preview must never linger):
  * 1. pointerdown anywhere OUTSIDE the window closes it (capture phase, so
@@ -1369,12 +1642,11 @@ function usePreviewDismiss(load, onClose) {
   useEffect(() => {
     if (typeof document === 'undefined' || typeof document.addEventListener !== 'function') return () => {}
     const handler = (event) => {
-      if (!isInsideFloating(event?.target)) onClose()
+      if (!isInsideFloating(event && event.target)) onClose()
     }
     document.addEventListener('pointerdown', handler, true)
     return () => document.removeEventListener('pointerdown', handler, true)
   }, [onClose])
-
   useEffect(() => {
     if (typeof document === 'undefined' || typeof document.addEventListener !== 'function') return () => {}
     const handler = (event) => {
@@ -1383,7 +1655,6 @@ function usePreviewDismiss(load, onClose) {
     document.addEventListener('keydown', handler)
     return () => document.removeEventListener('keydown', handler)
   }, [onClose])
-
   useEffect(() => {
     if (load.status !== 'error') return undefined
     if (typeof window === 'undefined' || typeof window.setTimeout !== 'function') return undefined
@@ -1391,7 +1662,6 @@ function usePreviewDismiss(load, onClose) {
     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(
@@ -1401,6 +1671,7 @@ function renderFloatingWindow(load, ctx, store, scope, path, title, sessionId, o
       'div',
       {
         className: 'dfa-fp',
+        'data-dfa-preview': '1',
         onClick: (event) => {
           if (previewClickAction(load, event) === 'close') onClose()
         },
@@ -1433,24 +1704,50 @@ function renderFloatingWindow(load, ctx, store, scope, path, title, sessionId, o
     ),
   )
 }
-
-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)
+/**
+ * The floating preview, mounted by the root-scoped 'shell.overlay' list seat
+ * (the host's own floating layer: above every column, click-through unless the
+ * entry opts into pointer events). It renders nothing at all while no preview
+ * is open, so the layer stays invisible.
+ */
+function FloatingPreviewOverlay() {
+  const store = sharedStore()
+  const state = useSyncExternalStore(
+    store === null ? () => () => {} : store.subscribe,
+    store === null ? () => null : store.getSnapshot,
+  )
+  const preview = state === null || state === undefined ? null : state.preview
+  const sessionId = preview === null ? '' : preview.sessionId
+  // Hooks must run unconditionally: the loader is fed an empty target while
+  // the window is closed (it then never resolves a load, and nothing renders).
+  const target = preview ?? { abs: '', name: '', sessionId: '' }
+  const load = usePreviewLoader(target)
+  const onClose = () => {
+    if (store !== null) store.set({ preview: null })
+  }
   usePreviewDismiss(load, onClose)
-  return renderFloatingWindow(load, ctx, store, scope, path, title, sessionId, onClose)
+  if (preview === null) return null
+  return renderFloatingWindow(load, undefined, null, null, preview.abs, preview.name, sessionId, onClose)
+}
+/** Register the overlay seat (list slot: additive, never replaces host UI). */
+function registerPreviewOverlay(ctx, dataStore) {
+  void dataStore
+  ctx.effect(
+    () =>
+      ctx.slots.inject('shell.overlay', () =>
+        ctx.slots.register(
+          { name: 'shell.overlay', id: PREVIEW_ID, order: 100, label: () => strings.title() },
+          FloatingPreviewOverlay,
+        ),
+      ),
+    'dsh-file-activity: preview overlay',
+  )
 }
-
 /**
- * Lightweight PDF preview. better-sidebar's built-in PdfView fetches
- * `/sidebar/file` internally (it ignores any injected `mediaUrl` prop),
- * and that route refuses files outside the session working directory — so
- * a recorded /tmp PDF would never load. This tiny view embeds the bytes
- * from OUR media route in a native browser PDF frame, with a download
- * fallback in its toolbar.
+ * Lightweight PDF preview. The recorded file often lives outside the session
+ * workspace, and the host's own PDF route is fenced to it — so the bytes come
+ * from the plugin's media route inside a native browser PDF frame, with a
+ * download fallback in its toolbar.
  */
 function PdfPreview({ src, download, title }) {
   return createElement(
@@ -1474,102 +1771,180 @@ function PdfPreview({ src, download, title }) {
   )
 }
 
-    // ── plugin body ───────────────────────────────────────────────────────
-/**
- * The stylesheet is pure static CSS and must NOT depend on the
- * betterSidebar service: inject it first, unconditionally. If it lived
- * behind the `service === undefined` early return, an HMR rebuild or
- * service reload could leave the already-rendered tab WITHOUT its
- * stylesheet — the raw white-text list you see when the CSS is gone.
- * Each fiber owns its own <style> element and the disposer removes
- * only that element, so a rebuild always keeps at least one copy.
- */
-function injectStyles(ctx) {
-  ctx.effect(() => {
-    if (typeof document === 'undefined' || document === null || typeof document.head === 'undefined') return () => {}
-    const style = document.createElement('style')
-    style.setAttribute('data-dsh-file-activity', 'styles')
-    style.textContent = STYLES
-    document.head.appendChild(style)
-    return () => {
-      if (style.parentNode) style.parentNode.removeChild(style)
-    }
-  }, 'dsh-file-activity: styles')
+    'use strict'
+// ── settings tab (replaces 迁移前的 settings.pluginToggles) ────
+//
+// The host renders no per-plugin toggle UI for third-party tabs, so this
+// plugin contributes its own tab to the Web Settings → Plugins section
+// ('settings.plugins.tab': a list seat declared by the settings section). The
+// section only exists while it is mounted, so the seat is declared with
+// ctx.slots.inject — the declarative form that survives HMR and late mounts
+// (a plain register on a not-yet-mounted seat would silently contribute
+// nothing).
+/** Auto-open preference (plugin-owned; 迁移前的插件偏好已不存在). */
+function autoOpenEnabled() {
+  try {
+    return window.localStorage.getItem(AUTO_OPEN_PREF_KEY) !== '0'
+  } catch {
+    return true
+  }
 }
-
-/** Mount probe: report client activation to the host state (synthetic
- *  session id, invisible in the UI — confirms the client half actually
- *  loaded after a page refresh). */
-function mountProbe() {
-  void fetch('/file-activity/api/record', {
-    method: 'POST',
-    headers: { 'content-type': 'application/json' },
-    body: JSON.stringify({ sessionId: '__probe__', path: 'mounted', op: 'read' }),
-  }).catch(() => {})
+/** Persist the auto-open preference. */
+function setAutoOpenEnabled(enabled) {
+  try {
+    window.localStorage.setItem(AUTO_OPEN_PREF_KEY, enabled ? '1' : '0')
+  } catch {
+    // storage unavailable (private mode): the in-memory toggle still applies
+  }
+}
+/** One labeled switch row. */
+function settingsRow(label, hint, checked, onChange) {
+  return createElement(
+    'label',
+    { className: 'dfa-set-row' },
+    createElement(
+      'span',
+      { className: 'dfa-set-text' },
+      createElement('span', { className: 'dfa-set-label' }, label),
+      createElement('span', { className: 'dfa-set-hint' }, hint),
+    ),
+    createElement('input', {
+      type: 'checkbox',
+      className: 'dfa-set-switch',
+      checked,
+      onChange: (event) => onChange(event?.target?.checked === true),
+    }),
+  )
+}
+/** Settings panel body: the auto-open switch plus its explanatory hint. */
+function FileActivitySettings() {
+  const [enabled, setEnabled] = useState(autoOpenEnabled)
+  return createElement(
+    'div',
+    { className: 'dfa-set', 'data-dfa-settings': '1' },
+    createElement('div', { className: 'dfa-set-title' }, strings.title()),
+    settingsRow(strings.autoOpenLabel(), strings.autoOpenHint(), enabled, (next) => {
+      setAutoOpenEnabled(next)
+      setEnabled(next)
+    }),
+  )
+}
+/** Register the settings tab into the settings section's list seat. */
+function registerSettingsTab(ctx) {
+  ctx.effect(
+    () =>
+      ctx.slots.inject('settings.plugins.tab', () =>
+        ctx.slots.register(
+          { name: 'settings.plugins.tab', id: TAB_ID, order: 60, label: () => strings.title() },
+          FileActivitySettings,
+        ),
+      ),
+    'dsh-file-activity: settings tab',
+  )
 }
 
-/** Register the tab (enabled by default in the Side card settings). */
-function registerTab(ctx, dataStore) {
-  const service = ctx.betterSidebar
+    'use strict'
+// ── plugin body (native sidebar extension points) ─────────────────────
+//
+// Everything this half needs comes from Cordis services the HOST provides
+// (issue #187 batch 2): the tab registry, the slot registry, the document
+// preview registry and the right-Sidebar navigation controller. There is no
+// third-party sidebar package in the picture anymore, so the page keeps
+// working on any host that ships those four services.
+//
+// The stylesheet is pure static CSS and must NOT depend on any of them:
+// inject it first, unconditionally. If it lived behind an early return, an HMR
+// rebuild or service reload could leave the already-rendered tab WITHOUT its
+// stylesheet — the raw white-text list you see when the CSS is gone. Each
+// fiber owns its own <style> element and the disposer removes only that
+// element, so a rebuild always keeps at least one copy.
+/** registerTab step one: the tab TYPE (what a file-activity page is). */
+function registerTabType(ctx) {
   ctx.effect(
     () =>
-      service.registerTab({
+      ctx.sidebarRightTabs.register({
         id: TAB_ID,
+        kind: TAB_KIND,
+        // No patterns: this is a page type, opened by kind (ctx.sidebarRight.openTab).
         title: () => strings.title(),
-        icon: (size) => icon.clock(size),
-        order: 15,
-        single: true,
-        settings: {
-          pluginToggles: [
-            {
-              key: 'autoOpen',
-              title: () => (isZh() ? '会话开始时自动打开' : 'Auto-open on session start'),
-              desc: () =>
-                isZh()
-                  ? '每个会话首次打开时自动显示本页（可在侧边栏设置中关闭）'
-                  : 'Opens this tab once per session by default (turn off here)',
-              type: 'switch',
-            },
-          ],
-        },
-        component: (props) => createElement(FileActivityView, { ...props, dataStore }),
+        // Guide entry (issue #266 B): the sidebar's "new tab" page is the guide
+        // tab, and its doors come from `sidebarRightTabs.guide()` — the entries
+        // every registered type contributes. Without one the page was reachable
+        // ONLY through auto-open, so closing its chip made it impossible to
+        // reopen from the UI. Picking the capsule opens this kind in the guide's
+        // place (host GuideBody → actions.openTab(kind, { replaceTab: true })).
+        guide: [
+          {
+            order: 20,
+            title: () => strings.title(),
+            description: () => strings.guideDescription(),
+          },
+        ],
       }),
-    'dsh-file-activity: tab registration',
+    'dsh-file-activity: tab type',
   )
 }
-
-exports.inject = ['betterSidebar']
-
+/** registerTab step two: the body seat (keyed by the definition id). */
+function registerTabBody(ctx, dataStore) {
+  ctx.effect(
+    () =>
+      ctx.slots.inject('sidebar.right.pane.tab', () =>
+        ctx.slots.register({ name: 'sidebar.right.pane.tab', key: TAB_ID }, function (props) {
+          const injected = Object.assign({}, props, { dataStore })
+          return createElement(FileActivityView, injected)
+        }),
+      ),
+    'dsh-file-activity: tab body',
+  )
+}
+/** registerTab step three: the chip title seat (a live, localized label). */
+function registerTabTitle(ctx) {
+  ctx.effect(
+    () =>
+      ctx.slots.inject('sidebar.right.pane.tab.title', () =>
+        ctx.slots.register({ name: 'sidebar.right.pane.tab.title', key: TAB_ID }, () =>
+          createElement('span', { className: 'dfa-chip' }, strings.title()),
+        ),
+      ),
+    'dsh-file-activity: tab title',
+  )
+}
+/**
+ * Run one registration, converting a throw into an observable failure.
+ *
+ * Swallowing is deliberate: the host throws for a taken id or a taken kind, and
+ * letting it escape would fail the WHOLE activation (the stylesheet, the
+ * floating preview and the settings tab would go with it). What must never
+ * happen is a SILENT failure, so the cause is logged, marked on <html> and
+ * rendered as a notice inside the tab body.
+ */
+function guarded(kind, register) {
+  try {
+    register()
+  } catch (error) {
+    markDegraded(kind, error)
+  }
+}
+exports.inject = ['slots', 'sidebarRightTabs', 'documentPreviews', 'sidebarRight']
 exports.apply = function apply(ctx) {
-  // Stylesheet first, unconditionally (HMR pitfall — see injectStyles).
+  // Stylesheet first, unconditionally (HMR pitfall — see the header note).
   injectStyles(ctx)
-  const service = ctx.betterSidebar
-  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
-  // sessions never leaks another session's file activity into the view.
+  // Failing loudly beats failing silently: a rejected registration (id taken,
+  // kind taken, seat missing) is recorded so the user and the e2e suite can
+  // see WHY the tab never appeared.
+  guarded('tab', () => registerTabType(ctx))
   const dataStore = createStore({ bySession: {}, preview: null })
-  mountProbe()
-
+  registerSharedStore(dataStore)
+  registerTabBody(ctx, dataStore)
+  registerTabTitle(ctx)
+  registerPreviewOverlay(ctx, dataStore)
+  registerSettingsTab(ctx)
+  guarded('previews', () => registerDocumentPreviews(ctx))
   // sidebar operations → host record route
   ctx.effect(() => installFetchInterceptor(), 'dsh-file-activity: sidebar fetch observation')
-  registerTab(ctx, dataStore)
-
   // auto-open once per session (default on)
-  ctx.effect(() => installAutoOpen(ctx, TAB_ID), 'dsh-file-activity: auto-open')
+  ctx.effect(() => installAutoOpen(ctx), '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 = {
@@ -1578,10 +1953,13 @@ exports.__test = {
   fetchTextContent,
   textUrlOf,
   strings,
+  viewerOf,
   renderPreviewBody,
   previewClickAction,
   isInsideFloating,
   closePreviewOnHidden,
+  autoOpenEnabled,
+  PREVIEW_EXTENSIONS,
   AUTO_CLOSE_MS,
   // Static stylesheet text, so the render-path suite can assert the floating
   // preview body keeps its flex-fill container (issue #111).