dsh-documents 1.0.0 → 1.0.2

package/README.md

@@ -31,7 +31,9 @@ DSH Desktop 插件：把**会话生成、编辑或交付过的文档**集中起
 - 侧边栏「文档」图标打开文档库。
 - **左侧始终保留文档列表**，右侧是查看器；点击列表中的另一个文档即可直接切换查看。
 - 列表按最近活动排序，显示创建会话、更新时间；可按类型 / 工作区筛选，按名称、文件夹、会话标题搜索。
-- **缓存与刷新**：列表和文档预览都会缓存在页面内，打开 / 切换文档不会重新请求；列表每 **60 秒**自动后台刷新一次（仅页面可见时），窗口重新聚焦时只有在缓存过期后才刷新。右上角「刷新」按钮可立即强制刷新并清空预览缓存。
+- **渐进加载**：列表按会话日志分块返回（NDJSON 流），先扫完的文档先显示，其余在后台继续扫描，底部提示「正在继续扫描会话…已显示 N 个」，不必等全部会话日志读完。
+- **增量刷新**：列表每 **60 秒**后台刷新一次（仅页面可见时），只回传新增 / 变化 / 删除的文档，没有变化时完全不重绘；窗口重新聚焦时只有在缓存过期后才刷新。右上角「刷新」按钮强制刷新并清空预览缓存。
+- **缓存**：文档预览缓存在页面内，打开 / 切换文档不会重新请求。
 - 重命名后的文件会记录映射并在列表中保留（映射存放在 `~/.dsh/documents-renames.json`），不会因为会话日志里还是旧路径而消失。
 - 查看器：
   - Markdown 默认**阅读模式**（渲染标题、列表、表格、代码块、链接），可切换源码。
@@ -67,35 +69,39 @@ DSH Desktop 插件：把**会话生成、编辑或交付过的文档**集中起
 
 ### 一次性准备
 
-1. 在 npmjs.com 建账号，生成 **Automation** token。
-2. 在 GitHub 创建仓库 `dsh-documents`（公开），然后：
+使用 **npm trusted publishing（OIDC）**：GitHub 里不存任何 npm token，凭据由 Actions 的 `id-token` 现换现用，provenance 自动生成。
 
-```bash
-git init
-git add .
-git commit -m "feat: session-linked document library"
-git branch -M main
-git remote add origin https://github.com/aerfaman/dsh-documents.git
-git push -u origin main
-```
-
-3. 仓库 **Settings → Secrets and variables → Actions → New repository secret**，添加 `NPM_TOKEN`（npm Automation token）。
+1. 包已存在于 npm（trusted publishing 不能创建新包，首次发布需手动；`dsh-documents@1.0.0` 已发布）。
+2. npmjs.com → 该包 → **Settings → Trusted publishing** → 添加 **GitHub Actions**：
+   - Organization or user：`aerfaman`
+   - Repository：`dsh-documents`
+   - Workflow filename：`release.yml`（必须与 `.github/workflows/release.yml` 同名）
+   - Environment：`release`（**必须**与 workflow 里的 `environment: release` 完全一致；两边不一致时 registry 的 OIDC 交换会返回 404，npm 随后静默退回传统认证并报 `ENEEDAUTH / npm login`）
+3. **不要**再配置 `NPM_TOKEN` / `NODE_AUTH_TOKEN`：npm 一旦发现 token 就会放弃 OIDC，退回 token 认证。
+4. 仓库 **Settings → Actions → General → Workflow permissions** 勾选 `Read and write`（创建 Release 需要 `contents: write`，workflow 内已声明 `permissions`）。
+5. workflow 里 `actions/setup-node` **不要**加 `registry-url`（它会写入 `${NODE_AUTH_TOKEN}` 的 `.npmrc`），registry 由 `package.json` 的 `publishConfig.registry` 决定。
 
 ### 发布新版本
 
+推 main 即自动发布，`release.yml` 做这些事：
+
 ```bash
-npm version patch   # 或 minor / major：改 package.json 并打 tag
-git push --follow-tags
+npm version patch     # 或 minor / major：只改 package.json 版本号
+git push origin main  # 或者 git push --follow-tags，同时推 v* tag
 ```
 
-`Release` workflow 会在 `v*` tag 上：
+1. `npm run check` 校验包结构；
+2. 查 npm 上是否已有该版本：**已有 → 跳过发布**（所以只推代码、没改版本号不会失败）；
+3. preflight：用 GitHub OIDC token 走一遍 npm 的 token 交换，失败时打出 registry 的真实状态码和原因，而不是 npm 那句含糊的 `ENEEDAUTH`；
+4. 版本是新的 → `npm publish --provenance --access public`（OIDC 换短期凭证，provenance 自动生成）；
+5. 该 tag 还没有 GitHub Release → `npm pack` 并把 `.tgz` 附到 Release，同时创建 `v<version>` tag。
 
-1. 校验 tag 与 `package.json` 版本一致；
-2. `npm run check`；
-3. `npm publish --provenance --access public`（发布到 registry.npmjs.org）；
-4. `npm pack` 并把 `.tgz` 附到 GitHub Release。
+补充：
 
-也可以在本机手动发布（注意本机 npm 默认 registry 是 npmmirror，必须显式指定官方源）：
+- 打 `v*` tag 触发时会额外校验 tag 与 `package.json` 版本一致。
+- 手动重跑：Actions → Release → **Run workflow**（`workflow_dispatch`）。
+- 运行环境需要 npm ≥ 11.5.1，workflow 里已 `npm install -g npm@latest` 并校验。
+- 也可以在本机手动发布（npm ≥ 11.5.1，注意本机 npm 默认 registry 可能是 npmmirror，必须显式指定官方源）：
 
 ```bash
 npm login --registry https://registry.npmjs.org
@@ -126,11 +132,13 @@ npm run pack:dry    # 查看 npm 包内容
 | `icon.svg` | 插件图标 |
 | `scripts/verify.mjs` | 包名 / 客户端 id / patch 行名一致性校验 |
 | `.github/workflows/ci.yml` | 推送与 PR 时校验包结构 |
-| `.github/workflows/release.yml` | tag 发布到 npm 并创建 GitHub Release |
+| `.github/workflows/release.yml` | 推 main / `v*` tag 时发布到 npm 并创建 GitHub Release |
 
 ## 本地接口
 
-- `GET /dsh-documents/api/list` — `{ documents, sessionCount, truncated }`
+- `GET /dsh-documents/api/list` — `{ documents, sessionCount, truncated, rev }`
+- `GET /dsh-documents/api/list?stream=1` — NDJSON：每扫完一块会话输出一行 `{ t: "docs", documents, scanned, sessions, sessionCount }`，结束为 `{ t: "done", rev, total, limit, truncated }`
+- `GET /dsh-documents/api/list?since=<rev>` — 增量：`{ rev, added, updated, removed }`；无变化返回 `{ unchanged: true }`；`rev` 不在保留的历史里（宿主重启或落后太多）返回 `{ full: true, documents }`
 - `GET /dsh-documents/api/preview?path=...` — 文本预览
 - `GET /dsh-documents/api/raw?path=...` — 图片 / PDF 内嵌流（支持 Range）
 - `POST /dsh-documents/api/action` — `{ action: "open" | "reveal" | "rename" | "trash", path, name? }`
@@ -142,3 +150,4 @@ POST 需要 `x-dsh-documents: 1`；所有路径先做 realpath 校验，必须
 - 包名切换为 `dsh-documents` 后重新安装成功，插件行 active，`/list` 返回 31 个会话文档 / 32 个会话。
 - 客户端 bundle 以 `dsh-documents` 模块 id 正常下发。
 - `npm run check` 与 `npm pack --dry-run` 通过，tarball 包含全部运行文件（9 个）。
+- 列表改为「分块流式 + 增量」：用桩 ctx 验证 8 个会话分 2 批、40 个文档（首批 20 个先上屏）；增量接口正确返回 `added` / `updated` / `removed`，无变化返回 `unchanged`，过期 revision 回退 `full`；同一套逻辑经真实 HTTP 流式读回一致。

package/client.js

@@ -13,7 +13,7 @@ window.__ModuleLoader__.load({
       'count': 'documents',
       'sessionCount': 'sessions',
       'refresh': 'Refresh',
-      'refresh.auto': 'Auto-refresh every 60s',
+      'refresh.auto': 'Auto-refresh every 60s · changes only',
       'search': 'Search document, folder, or session',
       'filter.all': 'All',
       'sort.recent': 'Recently active',
@@ -21,6 +21,7 @@ window.__ModuleLoader__.load({
       'sort.size': 'Largest first',
       'workspace.all': 'All workspaces',
       'loading': 'Loading documents…',
+      'loading.partial': 'Still scanning sessions… {count} shown',
       'empty.title': 'No session documents yet',
       'empty.body': 'When a DSH session writes, edits, or presents a document in a workspace, it appears here with its originating session.',
       'empty.filtered': 'No documents match this filter.',
@@ -91,7 +92,7 @@ window.__ModuleLoader__.load({
       'count': '个文档',
       'sessionCount': '个会话',
       'refresh': '刷新',
-      'refresh.auto': '每 60 秒自动刷新',
+      'refresh.auto': '每 60 秒增量刷新',
       'search': '搜索文档、文件夹或会话',
       'filter.all': '全部',
       'sort.recent': '最近活动',
@@ -99,6 +100,7 @@ window.__ModuleLoader__.load({
       'sort.size': '从大到小',
       'workspace.all': '全部工作区',
       'loading': '正在加载文档…',
+      'loading.partial': '正在继续扫描会话…已显示 {count} 个',
       'empty.title': '还没有会话文档',
       'empty.body': 'DSH 会话在工作区写入、编辑或交付文档后，会连同来源会话一起显示在这里。',
       'empty.filtered': '没有符合当前筛选的文档。',
@@ -172,6 +174,9 @@ window.__ModuleLoader__.load({
       text: '#5b6472',
     }
     const REFRESH_MS = 60 * 1000
+    // Survives a remount (switching panels and coming back): the list paints from
+    // the last known state and a delta refresh runs behind it.
+    const panelState = { documents: [], sessionCount: 0, revision: '' }
 
     const CSS = `
       .dshdoc-page {
@@ -595,9 +600,9 @@ window.__ModuleLoader__.load({
       const t = typeof props.t === 'function' ? props.t : translateWith(EN)
       const jumpToSession = props.jumpToSession
 
-      const [documents, setDocuments] = React.useState([])
-      const [sessionCount, setSessionCount] = React.useState(0)
-      const [loading, setLoading] = React.useState(true)
+      const [documents, setDocuments] = React.useState(() => panelState.documents)
+      const [sessionCount, setSessionCount] = React.useState(() => panelState.sessionCount)
+      const [loading, setLoading] = React.useState(() => panelState.documents.length === 0)
       const [error, setError] = React.useState(null)
       const [truncated, setTruncated] = React.useState(false)
       const [query, setQuery] = React.useState('')
@@ -612,6 +617,7 @@ window.__ModuleLoader__.load({
       const [preview, setPreview] = React.useState(null)
       const [previewEpoch, setPreviewEpoch] = React.useState(0)
       const [refreshing, setRefreshing] = React.useState(false)
+      const [streaming, setStreaming] = React.useState(false)
       const [busy, setBusy] = React.useState(false)
       const [toast, setToast] = React.useState(null)
       const [dialog, setDialog] = React.useState(null)
@@ -624,6 +630,8 @@ window.__ModuleLoader__.load({
       const inFlight = React.useRef(false)
       const previewCache = React.useRef(new Map())
       const reloadTimer = React.useRef(null)
+      /** Server revision of the list currently on screen; '' forces a full reload. */
+      const revision = React.useRef(panelState.revision)
 
       React.useEffect(() => {
         alive.current = true
@@ -634,6 +642,12 @@ window.__ModuleLoader__.load({
         }
       }, [])
 
+      React.useEffect(() => {
+        panelState.documents = documents
+        panelState.sessionCount = sessionCount
+        panelState.revision = revision.current
+      }, [documents, sessionCount])
+
       const showToast = React.useCallback((text, isError) => {
         setToast({ text, isError: isError === true })
         if (toastTimer.current !== null) window.clearTimeout(toastTimer.current)
@@ -642,6 +656,103 @@ window.__ModuleLoader__.load({
         }, 4200)
       }, [])
 
+      /**
+       * Read the whole library as a stream of NDJSON batches.
+       *
+       * The host scans session logs in chunks and pushes one `docs` event per
+       * chunk, so rows land on screen while the remaining logs are still being
+       * read. Returning early (unmount, newer load) cancels the reader.
+       */
+      const loadStream = React.useCallback(async (ticket) => {
+        const response = await fetch(API + '/list?stream=1', {
+          cache: 'no-store',
+          headers: { 'x-dsh-documents': '1' },
+        })
+        if (!response.ok || response.body === null) throw new Error(`HTTP ${response.status}`)
+        const reader = response.body.getReader()
+        const decoder = new TextDecoder()
+        const collected = new Map()
+        let buffer = ''
+        let painted = false
+        let final = null
+        const paint = () => {
+          if (!alive.current || ticket !== loadId.current) return false
+          setDocuments([...collected.values()])
+          if (!painted) {
+            painted = true
+            setLoading(false)
+          }
+          return true
+        }
+        try {
+          for (;;) {
+            const step = await reader.read()
+            if (step.done) break
+            buffer += decoder.decode(step.value, { stream: true })
+            let newline = buffer.indexOf('\n')
+            while (newline !== -1) {
+              const line = buffer.slice(0, newline).trim()
+              buffer = buffer.slice(newline + 1)
+              newline = buffer.indexOf('\n')
+              if (line === '') continue
+              let event
+              try {
+                event = JSON.parse(line)
+              } catch {
+                continue
+              }
+              if (event.t === 'docs') {
+                if (!Array.isArray(event.documents)) continue
+                for (const doc of event.documents) collected.set(doc.path.toLowerCase(), doc)
+                // Paint only once there is something to show: an empty first chunk
+                // must not flash the "no documents" state.
+                if (event.documents.length > 0 && !paint()) return
+                if (typeof event.sessionCount === 'number') setSessionCount(event.sessionCount)
+              } else if (event.t === 'done') {
+                final = event
+              } else if (event.t === 'error') {
+                throw new Error(String(event.error || 'list failed'))
+              } else if (event.ok === true && Array.isArray(event.documents)) {
+                // Host without streaming support answered with the plain JSON shape.
+                for (const doc of event.documents) collected.set(doc.path.toLowerCase(), doc)
+                if (!paint()) return
+              }
+            }
+          }
+        } finally {
+          reader.cancel().catch(() => {})
+        }
+        if (!alive.current || ticket !== loadId.current) return
+        if (final !== null) {
+          revision.current = typeof final.rev === 'string' ? final.rev : ''
+          panelState.revision = revision.current
+          setSessionCount(typeof final.sessionCount === 'number' ? final.sessionCount : collected.size)
+          setTruncated(final.truncated === true)
+          const limit = typeof final.limit === 'number' ? final.limit : 0
+          if (limit > 0 && collected.size > limit) {
+            setDocuments([...collected.values()].slice(0, limit))
+          }
+        }
+        if (!painted) setDocuments([...collected.values()])
+        setLoading(false)
+      }, [])
+
+      /** Apply an incremental refresh: only rows that appeared, changed, or vanished. */
+      const mergeDelta = React.useCallback((data) => {
+        const added = Array.isArray(data.added) ? data.added : []
+        const updated = Array.isArray(data.updated) ? data.updated : []
+        const removed = Array.isArray(data.removed) ? data.removed : []
+        if (added.length === 0 && updated.length === 0 && removed.length === 0) return false
+        setDocuments((current) => {
+          const map = new Map(current.map((doc) => [doc.path.toLowerCase(), doc]))
+          for (const doc of added) map.set(doc.path.toLowerCase(), doc)
+          for (const doc of updated) map.set(doc.path.toLowerCase(), doc)
+          for (const key of removed) map.delete(String(key).toLowerCase())
+          return [...map.values()]
+        })
+        return true
+      }, [])
+
       const load = React.useCallback(async (options) => {
         const force = options === true || (options !== undefined && options.force === true)
         const silent = options !== undefined && options.silent === true
@@ -653,27 +764,48 @@ window.__ModuleLoader__.load({
         if (!force && lastLoaded.current !== 0 && now - lastLoaded.current < REFRESH_MS) return
         const ticket = ++loadId.current
         inFlight.current = true
+        const full = revision.current === ''
+        if (full) setStreaming(true)
         if (!silent) setLoading(true)
         setError(null)
         try {
-          const data = await requestJson('/list')
-          if (!alive.current || ticket !== loadId.current) return
-          const next = Array.isArray(data.documents) ? data.documents : []
-          setDocuments(next)
-          setSessionCount(typeof data.sessionCount === 'number' ? data.sessionCount : 0)
-          setTruncated(data.truncated === true)
+          if (full) {
+            await loadStream(ticket)
+          } else {
+            const data = await requestJson('/list?since=' + encodeURIComponent(revision.current))
+            if (!alive.current || ticket !== loadId.current) return
+            if (data.full === true) {
+              revision.current = typeof data.rev === 'string' ? data.rev : ''
+              panelState.revision = revision.current
+              setDocuments(Array.isArray(data.documents) ? data.documents : [])
+            } else {
+              if (typeof data.rev === 'string' && data.rev !== '') {
+                revision.current = data.rev
+                panelState.revision = data.rev
+              }
+              if (data.unchanged !== true) mergeDelta(data)
+            }
+            if (typeof data.sessionCount === 'number') setSessionCount(data.sessionCount)
+            setTruncated(data.truncated === true)
+            setLoading(false)
+          }
           lastLoaded.current = Date.now()
-          setLoading(false)
-          setViewerPath((current) => (current !== null && next.some((doc) => doc.path === current) ? current : null))
         } catch (loadError) {
           if (!alive.current || ticket !== loadId.current) return
           setError(String((loadError && loadError.message) || loadError))
           setLoading(false)
+          if (full) {
+            revision.current = ''
+            panelState.revision = ''
+          }
         } finally {
           inFlight.current = false
-          if (alive.current) setRefreshing(false)
+          if (alive.current) {
+            setRefreshing(false)
+            setStreaming(false)
+          }
         }
-      }, [])
+      }, [loadStream, mergeDelta])
 
       const refreshNow = React.useCallback(() => {
         previewCache.current.clear()
@@ -709,6 +841,13 @@ window.__ModuleLoader__.load({
         return () => window.clearInterval(timer)
       }, [load])
 
+      // A delta refresh can drop the document that was open (rename, trash, delete).
+      React.useEffect(() => {
+        if (loading || streaming) return
+        if (viewerPath === null) return
+        if (!documents.some((doc) => doc.path === viewerPath)) setViewerPath(null)
+      }, [documents, viewerPath, loading, streaming])
+
       const selected = React.useMemo(
         () => documents.find((doc) => doc.path === viewerPath) || null,
         [documents, viewerPath],
@@ -1177,6 +1316,13 @@ window.__ModuleLoader__.load({
         }
       }
 
+      if (streaming && documents.length > 0) {
+        listContent = h(React.Fragment, null, listContent,
+          h('div', { className: 'dshdoc-empty-body', style: { padding: '12px 12px 0' } },
+            String(t('loading.partial') || '').replace('{count}', String(documents.length))),
+        )
+      }
+
       const sidePanel = h('div', { className: 'dshdoc-side', 'data-open': String(listOpen) },
         h('div', { className: 'dshdoc-side-head' },
           h('label', { className: 'dshdoc-search' },

package/index.js

@@ -19,6 +19,10 @@ const RENAME_FILE = path.join(os.homedir(), '.dsh', 'documents-renames.json')
 const PREVIEW_LIMIT = 400 * 1024
 const MAX_DOCUMENTS = 800
 const DOCS_CACHE_MS = 15000
+/** Session logs read in parallel per chunk; the scan streams one batch per chunk. */
+const SESSION_CHUNK = 4
+/** How many list revisions stay addressable, so a client can still ask for a delta. */
+const SNAPSHOT_HISTORY = 4
 
 const KINDS = [
   { id: 'word', color: '#2b579a', exts: ['doc', 'docx', 'docm', 'rtf', 'odt', 'pages'] },
@@ -53,9 +57,11 @@ const WRITE_TOOLS = new Set([
 const PATH_ARG_KEYS = ['path', 'file_path', 'filePath', 'target_file', 'file']
 
 
-let docsCache = { at: 0, key: '', value: null }
+let docsCache = { at: 0, key: '', value: null, snapshot: null, rev: '' }
 let renameMap = null
 const sessionCache = new Map()
+/** Recent list snapshots, keyed by revision, so a polling client can receive a delta. */
+const snapshotHistory = new Map()
 
 /**
  * Renames performed through this plugin are remembered because session events
@@ -302,75 +308,143 @@ function extractSessionFiles(events, sessionCwd) {
   return out
 }
 
-async function sessionRecords(ctx, signal) {
+/**
+ * Read one session log, reusing the extraction cache while its revision is stable.
+ * Returns null for a session whose log cannot be read.
+ */
+async function readSessionRecord(query, persistence, record, titles, signal) {
+  const header = record?.header
+  if (!header || typeof header.cwd !== 'string') return null
+  const id = String(header.id)
+  let revision = ''
+  if (persistence && typeof persistence.stat === 'function') {
+    try {
+      const stat = await persistence.stat(header.id, { signal })
+      revision = String(stat?.revision ?? '')
+    } catch {
+      revision = ''
+    }
+  }
+  let cached = sessionCache.get(id)
+  if (cached === undefined || cached.revision !== revision) {
+    let snapshot
+    try {
+      snapshot = await query.readSession(header.id)
+    } catch {
+      return null
+    }
+    const events = Array.isArray(snapshot?.events) ? snapshot.events : []
+    cached = {
+      revision,
+      header,
+      files: extractSessionFiles(events, header.cwd),
+    }
+    sessionCache.set(id, cached)
+  }
+  return {
+    id,
+    header,
+    title: titles.get(id) || '',
+    files: cached.files,
+  }
+}
+
+/**
+ * Walk every session log in small parallel chunks.
+ *
+ * Reading a log is by far the expensive step (36 logs / ~24 MB here), so callers
+ * that paint progressively can yield a batch after each chunk instead of waiting
+ * for the whole scan. Cached sessions skip `readSession` entirely, which makes a
+ * refresh cheap once the library has been loaded once.
+ */
+async function* iterateSessionRecords(ctx, signal) {
   const query = ctx.get('sessionQuery')
   const persistence = ctx.get('sessionPersistence')
   if (!query || typeof query.listSessions !== 'function' || typeof query.readSession !== 'function') {
     throw new Error('会话查询服务不可用')
   }
   const records = await query.listSessions(signal)
-  let titles = new Map()
+  const titles = new Map()
   try {
-    const observed = await query.readTitleSnapshots(records.map((record) => record.header.id), signal)
+    const ids = records.map((record) => record?.header?.id).filter((id) => id !== undefined && id !== null)
+    const observed = await query.readTitleSnapshots(ids, signal)
     for (const item of observed) {
       if (item && item.status === 'fulfilled' && item.value && item.value.title) {
         titles.set(String(item.sessionId), String(item.value.title.title ?? ''))
       }
     }
   } catch {
-    titles = new Map()
+    // Titles are decoration; a scan without them is still useful.
   }
-  const out = []
-  for (const record of records) {
-    const header = record.header
-    if (!header || typeof header.cwd !== 'string') continue
-    const id = String(header.id)
-    let revision = ''
-    if (persistence && typeof persistence.stat === 'function') {
-      try {
-        const stat = await persistence.stat(header.id, { signal })
-        revision = String(stat?.revision ?? '')
-      } catch {
-        revision = ''
-      }
-    }
-    let cached = sessionCache.get(id)
-    if (cached === undefined || cached.revision !== revision) {
-      let snapshot
-      try {
-        snapshot = await query.readSession(header.id)
-      } catch {
-        continue
-      }
-      const events = Array.isArray(snapshot?.events) ? snapshot.events : []
-      cached = {
-        revision,
-        header,
-        files: extractSessionFiles(events, header.cwd),
-      }
-      sessionCache.set(id, cached)
+  for (let index = 0; index < records.length; index += SESSION_CHUNK) {
+    const slice = records.slice(index, index + SESSION_CHUNK)
+    const settled = await Promise.all(
+      slice.map((record) => readSessionRecord(query, persistence, record, titles, signal)),
+    )
+    yield {
+      sessions: settled.filter((entry) => entry !== null),
+      scanned: Math.min(index + slice.length, records.length),
+      total: records.length,
     }
-    out.push({
-      id,
-      header,
-      title: titles.get(id) || '',
-      files: cached.files,
-    })
   }
-  return out
 }
 
 function kindOf(ext) {
   return KIND_BY_EXT.get(ext)
 }
 
-async function collectDocuments(ctx, config, signal) {
-  const roots = rootsFor(ctx, config)
-  const renames = await loadRenames()
-  const sessions = await sessionRecords(ctx, signal)
-  const relevant = sessions.filter((session) => insideRoots(path.resolve(session.header.cwd), roots))
+/**
+ * Identity of one document row. Any change here means the client must be told
+ * about the document again on the next incremental refresh.
+ */
+function fingerprintOf(doc) {
+  return `${doc.mtime}|${doc.bytes}|${doc.sessionCount}|${doc.editCount}|${doc.lastTime}`
+}
+
+function snapshotOf(documents) {
+  const snapshot = new Map()
+  for (const doc of documents) snapshot.set(doc.path.toLowerCase(), fingerprintOf(doc))
+  return snapshot
+}
+
+/**
+ * Stable hash of a document set, used as the delta cursor. Kept deterministic so
+ * a client revision stays meaningful after the host restarts.
+ */
+function revisionOf(snapshot) {
+  let hash = 0x811c9dc5
+  for (const key of [...snapshot.keys()].sort()) {
+    const line = `${key}=${snapshot.get(key)}\n`
+    for (let index = 0; index < line.length; index += 1) {
+      hash ^= line.charCodeAt(index)
+      hash = Math.imul(hash, 0x01000193) >>> 0
+    }
+  }
+  return hash.toString(16).padStart(8, '0')
+}
+
+async function statDocument(filePath, cache) {
+  if (cache.has(filePath)) return cache.get(filePath)
+  let info = null
+  try {
+    const stat = await fs.stat(filePath)
+    if (stat.isFile()) info = { size: stat.size, mtime: stat.mtimeMs }
+  } catch {
+    info = null
+  }
+  cache.set(filePath, info)
+  return info
+}
+
+/**
+ * Turn session file events into the public document shape.
+ *
+ * `statCache` keeps the stat cost flat while a streaming caller re-runs this for
+ * every chunk, and an unreadable file simply drops out of the library.
+ */
+async function buildDocuments(sessions, roots, renames, statCache) {
   const byPath = new Map()
-  for (const session of relevant) {
+  for (const session of sessions) {
     const rootInfo = rootForPath(path.resolve(session.header.cwd), roots)
     for (const file of session.files) {
       const sourcePath = path.resolve(file.path)
@@ -426,13 +500,8 @@ async function collectDocuments(ctx, config, signal) {
 
   const documents = []
   for (const doc of byPath.values()) {
-    let info
-    try {
-      info = await fs.stat(doc.path)
-    } catch {
-      continue
-    }
-    if (!info.isFile()) continue
+    const info = await statDocument(doc.path, statCache)
+    if (info === null) continue
     const entries = [...doc.sessions.values()]
     for (const entry of entries) entry.events.sort((a, b) => a.seq - b.seq)
     entries.sort((a, b) => {
@@ -451,7 +520,7 @@ async function collectDocuments(ctx, config, signal) {
       rootTitle: doc.rootTitle,
       rel: doc.rel,
       bytes: info.size,
-      mtime: info.mtimeMs,
+      mtime: info.mtime,
       firstTime: doc.firstTime,
       lastTime: doc.lastTime,
       sessionCount: entries.length,
@@ -470,6 +539,20 @@ async function collectDocuments(ctx, config, signal) {
     })
   }
   documents.sort((a, b) => b.lastTime - a.lastTime)
+  return documents
+}
+
+/** Collect the whole library in one pass (agent tool, JSON endpoint). */
+async function collectDocuments(ctx, config, signal) {
+  const roots = rootsFor(ctx, config)
+  const renames = await loadRenames()
+  const relevant = []
+  for await (const chunk of iterateSessionRecords(ctx, signal)) {
+    for (const session of chunk.sessions) {
+      if (insideRoots(path.resolve(session.header.cwd), roots)) relevant.push(session)
+    }
+  }
+  const documents = await buildDocuments(relevant, roots, renames, new Map())
   return {
     roots,
     documents: documents.slice(0, MAX_DOCUMENTS),
@@ -486,12 +569,55 @@ async function listDocuments(ctx, config) {
     return docsCache.value
   }
   const value = await collectDocuments(ctx, config)
-  docsCache = { key, at: now, value }
+  const snapshot = snapshotOf(value.documents)
+  const rev = revisionOf(snapshot)
+  docsCache = { key, at: now, value, snapshot, rev }
+  rememberSnapshot(rev, snapshot)
   return value
 }
 
+function rememberSnapshot(rev, snapshot) {
+  snapshotHistory.delete(rev)
+  snapshotHistory.set(rev, snapshot)
+  while (snapshotHistory.size > SNAPSHOT_HISTORY) {
+    const oldest = snapshotHistory.keys().next().value
+    if (oldest === undefined) break
+    snapshotHistory.delete(oldest)
+  }
+}
+
+/**
+ * Answer an incremental refresh: only the documents that appeared, changed, or
+ * vanished since the caller's revision. When that revision has fallen out of the
+ * retained history (or the host restarted), the full list is resent once.
+ */
+async function listDelta(ctx, config, since) {
+  const value = await listDocuments(ctx, config)
+  const snapshot = docsCache.snapshot ?? snapshotOf(value.documents)
+  const rev = docsCache.rev || revisionOf(snapshot)
+  const base = { sessionCount: value.sessionCount, truncated: value.truncated }
+  if (since === rev) return { ok: true, unchanged: true, rev, ...base }
+  const previous = snapshotHistory.get(since)
+  if (previous === undefined) {
+    return { ok: true, full: true, rev, documents: value.documents, ...base }
+  }
+  const added = []
+  const updated = []
+  for (const doc of value.documents) {
+    const key = doc.path.toLowerCase()
+    const before = previous.get(key)
+    if (before === undefined) added.push(doc)
+    else if (before !== snapshot.get(key)) updated.push(doc)
+  }
+  const removed = []
+  for (const key of previous.keys()) {
+    if (!snapshot.has(key)) removed.push(key)
+  }
+  return { ok: true, rev, added, updated, removed, ...base }
+}
+
 function invalidateCache() {
-  docsCache = { at: 0, key: '', value: null }
+  docsCache = { at: 0, key: '', value: null, snapshot: null, rev: '' }
 }
 
 async function readPreview(target, roots) {
@@ -725,6 +851,70 @@ async function serveRaw(req, res, url, ctx, config) {
   createReadStream(resolved, { start, end }).pipe(res)
 }
 
+/**
+ * Stream the library as NDJSON.
+ *
+ * One `docs` event per scanned chunk means the panel can paint the documents it
+ * already knows about while the remaining session logs are still being read,
+ * instead of staring at a skeleton for the whole scan.
+ */
+async function serveListStream(req, res, ctx, config) {
+  res.writeHead(200, {
+    'content-type': 'application/x-ndjson; charset=utf-8',
+    'cache-control': 'no-store',
+    'x-accel-buffering': 'no',
+  })
+  const controller = new AbortController()
+  const abort = () => controller.abort()
+  res.on('close', abort)
+  const write = (event) => {
+    if (res.writableEnded === true) return
+    res.write(JSON.stringify(event) + '\n')
+  }
+  try {
+    const roots = rootsFor(ctx, config)
+    const renames = await loadRenames()
+    const statCache = new Map()
+    const relevant = []
+    const emitted = new Map()
+    let documents = []
+    let sessionCount = 0
+    for await (const chunk of iterateSessionRecords(ctx, controller.signal)) {
+      for (const session of chunk.sessions) {
+        if (insideRoots(path.resolve(session.header.cwd), roots)) relevant.push(session)
+      }
+      sessionCount = relevant.length
+      documents = await buildDocuments(relevant, roots, renames, statCache)
+      const changed = []
+      for (const doc of documents) {
+        const key = doc.path.toLowerCase()
+        const fingerprint = fingerprintOf(doc)
+        if (emitted.get(key) === fingerprint) continue
+        if (!emitted.has(key) && emitted.size >= MAX_DOCUMENTS) continue
+        emitted.set(key, fingerprint)
+        changed.push(doc)
+      }
+      write({ t: 'docs', documents: changed, scanned: chunk.scanned, sessions: chunk.total, sessionCount })
+    }
+    const rev = revisionOf(emitted)
+    const truncated = documents.length > MAX_DOCUMENTS
+    docsCache = {
+      key: roots.map((root) => root.path).join('|'),
+      at: Date.now(),
+      value: { roots, documents: documents.slice(0, MAX_DOCUMENTS), truncated, sessionCount },
+      snapshot: emitted,
+      rev,
+    }
+    rememberSnapshot(rev, emitted)
+    write({ t: 'done', rev, sessionCount, total: documents.length, limit: MAX_DOCUMENTS, truncated })
+  } catch (error) {
+    write({ t: 'error', error: messageOf(error) })
+  } finally {
+    res.off('close', abort)
+    if (res.writableEnded !== true) res.end()
+  }
+}
+
 function createHandler(ctx, config) {
   return async function handleDocumentsRequest(req, res) {
     try {
@@ -738,8 +928,17 @@ function createHandler(ctx, config) {
 
       if (req.method === 'GET' || req.method === 'HEAD') {
         if (route === '/list') {
+          const since = url.searchParams.get('since')
+          if (since !== null && since !== '') {
+            sendJson(res, 200, await listDelta(ctx, config, since))
+            return
+          }
+          if (url.searchParams.get('stream') === '1' && req.method !== 'HEAD') {
+            await serveListStream(req, res, ctx, config)
+            return
+          }
           const result = await listDocuments(ctx, config)
-          sendJson(res, 200, { ok: true, ...result })
+          sendJson(res, 200, { ok: true, rev: docsCache.rev, ...result })
           return
         }
         if (route === '/preview') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-documents",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Session-linked document library for DSH Desktop: in-app Markdown viewer, zoom, provenance and edit history.",
   "type": "module",
   "license": "MIT",